Skip to content

Solucao de Problemas

Jump to bottom
André Henrique edited this page Jun 30, 2026 · 2 revisions

Idioma: Português (pt-BR) | English: Troubleshooting

Solução de Problemas

Problemas comuns e soluções para o IndustrialXPL-Forge.

Problemas de Instalação

pip install industrialxpl-forge falha

Sintoma: pip reporta erro de build ou conflito de dependência.

Solução:

# Atualizar o pip primeiro
python -m pip install --upgrade pip

# Instalar com saída detalhada para ver o erro exato
pip install industrialxpl-forge -v

# Se o scapy falhar no Windows, instalar o Npcap primeiro
# https://npcap.com/

# Verificar versão do Python
python --version  # deve ser 3.9+

Comando ixf não encontrado após instalação

Sintoma: ixf: command not found ou 'ixf' is not recognized

Diagnóstico:

# Verificar se o entry point foi instalado
pip show industrialxpl-forge | grep -i location

# Localizar o diretório de scripts
python -c "import sys; print(sys.prefix + '/Scripts')"   # Windows
python -c "import sys; print(sys.prefix + '/bin')"       # Linux/macOS

Solução:

# Linux/macOS: adicionar ao PATH
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# Windows: adicionar a pasta Scripts ao PATH nas Variáveis de Ambiente do Sistema
# Ou usar o caminho completo:
python -m industrialxpl

# Ou a partir do repositório:
python ixf.py

Crash no Windows: AttributeError: 'NoneType' object has no attribute 'write_history_file'

Causa: O readline é None no Windows (módulo exclusivo do Unix) e o shell tentou chamá-lo.

Correção: Atualizar para v1.0.12+ que protege todas as chamadas ao readline:

pip install --upgrade industrialxpl-forge

Se ainda falhar, instalar o pyreadline3 manualmente:

pip install pyreadline3>=3.4

ModuleNotFoundError: No module named 'scapy'

Causa: o scapy falhou na instalação (comum no Windows sem o Npcap).

Correção:

# Instalar o Npcap primeiro (Windows): https://npcap.com/
# Depois:
pip install scapy

# No Linux, se o libpcap estiver ausente:
sudo apt install libpcap-dev  # Debian/Ubuntu
sudo dnf install libpcap-devel  # Fedora/RHEL
pip install scapy

ModuleNotFoundError: No module named 'pysnmp'

Causa: pysnmp não instalado ou versão incorreta.

Correção:

pip install "pysnmp>=6.1"
# Atenção: pysnmp v4.x é incompatível com Python 3.12+

Aviso de versão urllib3/requests na inicialização

Sintoma:

RequestsDependencyWarning: urllib3 (2.6.3) or chardet doesn't match a supported version!

Correção:

pip install "requests>=2.31.0,<3.0" "urllib3>=1.26.0,<3.0"

Problemas com Módulos

0 módulos indexados

Sintoma:

[*] Indexing modules…
[+] 0 modules indexed.

Diagnóstico:

python -c "
from industrialxpl.core.exploit.utils import index_modules, MODULES_DIR
print('MODULES_DIR:', MODULES_DIR)
print('Exists:', MODULES_DIR.exists())
mods = index_modules()
print('Count:', len(mods))
"

Correção:

# Reinstalar o pacote
pip install --force-reinstall industrialxpl-forge

# Ou instalar a partir do código-fonte
git clone https://github.com/mrhenrike/IndustrialXPL-Forge.git
cd IndustrialXPL-Forge
pip install -e .

Erro de importação de módulo

Sintoma:

ixf > use cve/siemens/cve_2021_22681_s7_1200_hardcoded_key
[-] Error loading module: ...

Diagnóstico:

python -c "
from industrialxpl.core.exploit.utils import import_exploit
obj = import_exploit('industrialxpl.modules.cve.siemens.cve_2021_22681_s7_1200_hardcoded_key')
print('OK:', obj)
"

Causas comuns:

  1. Erro de sintaxe no arquivo do módulo - verificar o arquivo em busca de problemas de sintaxe
  2. Dependência ausente - o módulo pode exigir um pacote opcional
  3. Versão incorreta do Python - alguns módulos usam f-strings ou operador walrus

check() sempre retorna False

Sintoma: check exibe NOT VULNERABLE mesmo quando o alvo deveria responder.

Diagnóstico:

# Testar conectividade bruta
python -c "
import socket
s = socket.socket()
s.settimeout(5)
try:
    s.connect(('192.168.1.100', 502))
    print('Port open')
    s.close()
except Exception as e:
    print('Failed:', e)
"

Causas comuns:

  1. Firewall bloqueando a porta
  2. Número de porta incorreto - use show options e verifique
  3. Sonda do módulo rejeitada pelo dispositivo - alguns dispositivos só respondem a unit IDs específicos
  4. Problema de roteamento de rede - você consegue fazer ping no alvo?

run em modo simulate não exibe nada

Causa: O método run() do módulo não chama DestructiveGate.print_simulation().

Pode ser um bug no módulo. Verifique o código-fonte do módulo:

cat industrialxpl/modules/cve/vendor/module_name.py | grep "print_simulation"

Se estiver ausente, o módulo implementa apenas o modo ao vivo. Abra uma issue no GitHub.

Problemas com o Shell

Autocompletar com Tab não funciona

Windows: Requer pyreadline3. Instale se estiver ausente:

pip install pyreadline3

Linux/macOS: O readline deve ser nativo. Se não estiver:

pip install readline  # macOS
sudo apt install python3-readline  # Debian/Ubuntu

Histórico de comandos não é salvo entre sessões

Sintoma: A seta para cima não exibe comandos de sessões anteriores.

Causa: O arquivo ~/.ixf_history não está sendo gravado (problema de permissão ou readline indisponível).

Correção:

# Verificar se o arquivo existe
ls -la ~/.ixf_history

# Verificar permissões de escrita
touch ~/.ixf_history

Cores ANSI exibidas como códigos de escape literais (Windows)

Sintoma: A saída mostra \x1b[32m[+]\x1b[0m em vez de texto colorido.

Correção: Use o Windows Terminal ou PowerShell 7:

# Instalar o Windows Terminal pela Microsoft Store
# Ou usar o PowerShell 7+: https://github.com/PowerShell/PowerShell

# Alternativa: desabilitar cores (contorno temporário)
$env:NO_COLOR = "1"
ixf

Problemas com NSE

nse install falha com Erro de Permissão (Linux)

Correção:

sudo python tools/nse_install.py --install
# ou
sudo ixf
# depois: nse install

nse install falha no Windows

Correção: Execute o terminal como Administrador:

  1. Clique com o botão direito no PowerShell > Executar como Administrador
  2. Depois execute ixf e nse install

Nmap não encontrado mesmo estando instalado

Sintoma: nse status mostra "Nmap NOT installed" mas o nmap funciona no terminal.

Causa: o nmap não está no PATH do processo Python.

Diagnóstico:

import shutil
print(shutil.which("nmap"))  # Deve mostrar o caminho ou None

Correção (Linux/macOS):

which nmap  # Localizar o nmap
# Adicionar ao PATH se necessário
export PATH="/usr/bin:$PATH"

Correção (Windows):

where.exe nmap  # Localizar o nmap
# Adicionar a pasta do Nmap ao PATH nas Variáveis de Ambiente do Sistema

Script NSE não encontrado pelo Nmap após instalação

Execute nmap --script-updatedb para atualizar o banco de dados de scripts:

nmap --script-updatedb

# Ou use o IXF (ele executa isso automaticamente após a instalação)
ixf > nse install

Problemas com SAST / LLM

LLM key not configured

ixf > sast /path/to/plc/ --mode sast
[-] No LLM API key configured

Correção:

export OPENAI_API_KEY=sk-...
export GOOGLE_AI_STUDIO_API_KEY=AIzaSy...
ixf

Ou dentro do IXF:

ixf > llm-key gemini AIzaSyBGaoio...

LLM request failed: HTTP 429

Limite de requisições excedido. Aguarde alguns segundos e tente novamente:

ixf > sast /path/to/plc/ --mode sast

Ou troque de provedor:

ixf > llm-key openai sk-...

Resposta do SAST truncada

Sintoma: A análise é interrompida no meio de uma frase.

Causa: Limite padrão de max_tokens.

Contorno: Use um provedor com limites maiores de tokens (GPT-4o: 128K de contexto, Claude 3.5: 200K).

Problemas de Desempenho

O IXF inicializa lentamente (indexação de módulos leva mais de 10 segundos)

Causa: Grande quantidade de módulos (1190+) sendo indexados.

Contorno: A indexação é armazenada em cache na memória durante a sessão. As operações subsequentes são rápidas.

Melhoria: Use o modo não interativo para comandos únicos:

ixf stats  # mais rápido que iniciar interativamente + stats

Varredura muito lenta

Causas:

  1. Intervalo CIDR grande - use --rate-limit para controlar o ritmo
  2. Timeout alto - reduza com set timeout 3
  3. Muitos módulos por técnica - use ttp-check para modo somente verificação
ixf > ttp T0843 192.168.1.0/24 --rate-limit 100
ixf > set timeout 3
ixf > ttp-check T0843 192.168.1.0/24

Obtendo Ajuda

  1. Consulte este guia de solução de problemas
  2. Execute python tools/env_doctor.py para diagnóstico do ambiente
  3. Pesquise nas Issues do GitHub: https://github.com/mrhenrike/IndustrialXPL-Forge/issues
  4. Abra uma nova issue com:
    • Versão do IXF: ixf stats
    • Versão do Python: python --version
    • Sistema operacional: uname -a (Linux/macOS) ou winver (Windows)
    • Saída completa do erro

Voltar para o Índice

Aviso Legal: O uso desta ferramenta é restrito a ambientes autorizados, laboratórios isolados e atividades legítimas de pesquisa e avaliação de segurança. A utilização não autorizada contra sistemas reais constitui crime federal. Os autores e a União Geek não assumem qualquer responsabilidade por uso indevido.

Autor: André Henrique (@mrhenrike) | União Geek | https://uniaogeek.com.br/

Clone this wiki locally