Evidências focadas em engenharia reversa de malware com inspeção profunda de PE/.NET, reconstrução com Ghidra, verificações cruzadas com IA, YARA e depuração de ELF
O AIDebug é uma CLI e interface de terminal focada em evidências para engenharia reversa de malware. Ele combina triagem offline determinística, inspeção hexadecimal de arquivos inteiros, análise profunda da estrutura de PE, desmontagem com Capstone, reconstrução com Ghidra, verificações cruzadas opcionais com LLM, depuração local de ELF, exercícios de aprendizado compilados e relatórios para revisão analítica.
Versão atual do código-fonte: AIDebug 3.1.0. Consulte as notas de versão 3.1.0.
A versão publicada imutável mais recente permanece AIDebug v3.0.0, disponível como
1200km-aidebug, até que a tag 3.1.0 correspondente à versão e o release no GitHub concluam o fluxo de publicação verificado.
Instale o pacote estável a partir do PyPI:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 1200km-aidebug==3.0.0
aidebug --version
Instale capacidades opcionais conforme necessário:
# Provedores de LLM remotos/locais e geração validada de YARA
python -m pip install "1200km-aidebug[ai]==3.0.0"
# Instrumentação dinâmica com Frida
python -m pip install "1200km-aidebug[dynamic]==3.0.0"
# Todas as integrações Python opcionais
python -m pip install "1200km-aidebug[all]==3.0.0"
Para desenvolvimento:
git clone https://github.com/anpa1200/AIDebug.git
cd AIDebug
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,dynamic]"
Ghidra, GDB, Bubblewrap, um compilador C e componentes de destino do Frida são ferramentas externas usadas apenas pelos fluxos de trabalho que as exigem.
Abra uma amostra PE ou ELF na interface principal do terminal:
aidebug --binary /path/to/sample.exe --offline
Execute análise determinística sem a interface de tela cheia e exporte evidências:
aidebug --binary /path/to/sample.exe \
--offline --no-tui --report --json-export --yara \
--out-dir reports/
Use a reconstrução com Ghidra:
aidebug --binary /path/to/sample.exe --offline --no-tui --decompile
aidebug --binary /path/to/sample.exe --offline --no-tui \
--decompile-all reports/sample-reconstruction.c
Analise uma unidade de tradução C por meio de um artefato ELF temporário e não executado:
aidebug --source /path/to/example.c --offline --no-tui
Identifique um arquivo arbitrário independentemente da extensão do nome:
aidebug --identify /path/to/renamed-or-unknown-file --offline
--identify relata JSON estruturado com o tipo declarado, tipo MIME, extensões
comuns, confiança, método, evidência, SHA-256 e tamanho. A cobertura
determinística inclui formatos comuns de executáveis e bytecode, arquivos e imagens de disco,
contêineres Office/OpenDocument/EPUB, documentos, imagens, áudio/vídeo,
capturas de pacotes, bancos de dados, artefatos de registro/log de eventos, scripts e texto.
Formatos baseados em ZIP são inspecionados por nomes de membros limitados e pequenas leituras
de metadados; arquivos nunca são executados ou extraídos.
Instale python-magic além do banco de dados libmagic do sistema operacional para
assinaturas adicionais conhecidas pela plataforma local:
python -m pip install python-magic
Quando nenhuma assinatura determinística, estrutura ou regra de texto corresponde, um
provedor de IA configurado pode inferir um candidato a partir de metadados limitados: a extensão, o tamanho,
SHA-256, até 96 bytes de cabeçalho, 32 bytes finais, entropia da amostra e proporção de NUL.
O corpo do arquivo, strings extraídas e o caminho do sistema de arquivos não são enviados. Resultados
somente de IA são rotulados como ai-inference, limitados a 60% de confiança e exigem
validação analítica. Use --offline para desabilitar o fallback completamente; um
tipo não resolvido é relatado como Unknown com status de saída 2.
Pressione S na interface principal do terminal, ou inicie diretamente no espaço de trabalho:
aidebug --binary /path/to/sample.exe --offline --strings
O espaço de trabalho preserva offsets de arquivo, endereços mapeados quando disponíveis, codificação, comprimentos em bytes e caracteres, informações de ocorrências duplicadas, contexto de seção, confiança, pontuação de triagem e os motivos determinísticos para cada classificação. Os filtros cobrem comprimento mínimo, codificação, categoria e busca de texto livre; ordenação de colunas e paginação mantêm inventários grandes utilizáveis. Cada codificação selecionada examina o artefato completo limitado por tamanho. O inventário retido é limitado a 25.000 registros e 4.096 caracteres exibidos por valor; contagens exatas de candidatos/omissões e cobertura completa de bytes tornam qualquer limite visível. Cada registro retém no máximo 32 anotações de DLL/API e 4.096 caracteres de descrição; estouros adversariais são relatados nos motivos do registro.
A detecção é multi-rótulo. Um único valor pode ser simultaneamente uma DLL, caminho
Windows, URL, endereço IP, chave de registro, comando, fragmento PowerShell, pipe nomeado,
hash, candidato a credencial, user agent ou outro tipo de evidência suportado.
Candidatos de domínio são normalizados por IDNA e verificados contra um snapshot offline
empacotado da zona raiz da IANA; endereços IP devem ocupar um token válido completo, e
atribuições de configuração devem corresponder a uma gramática conservadora de linha completa. Isso
impede que fragmentos binários curtos sejam promovidos apenas por conterem um ponto,
dois-pontos ou sinal de igual. Rótulos relacionados compartilham uma família de confiança, então
ip_address mais ipv6 não é tratado como duas observações independentes.
DLLs e APIs conhecidas recebem descrições curtas e neutras de capacidade; nomes
desconhecidos recebem um fallback explícito não verificado em vez de uma finalidade adivinhada.
Um nome extraído é evidência de presença, não prova de que o código o invocou ou que
a amostra é maliciosa.
Imprima o inventário determinístico localmente, filtre a visualização CLI exibida ou grave o inventário completo canônico como JSON somente do proprietário:
aidebug --binary /path/to/sample.exe --strings --no-tui
aidebug --binary /path/to/sample.exe --strings --no-tui \
--string-encoding ascii --min-string-length 6 --string-category url
aidebug --binary /path/to/sample.exe --strings --no-tui \
--strings-output reports/sample-strings.json
A revisão de strings por IA é uma ação separada de adesão opcional. Pressione A dentro do espaço
de trabalho e confirme o aviso de privacidade/custo, ou solicite-a explicitamente no modo CLI:
aidebug --binary /path/to/sample.exe --strings --no-tui \
--analyze-strings --accept-ai-cost \
--strings-output reports/sample-strings-ai.json
Cada string retida recebe um ID de evidência estável. Após confirmação
explícita, o caminho de IA planeja cada registro retido em blocos determinísticos
e limitados; falhas de provedor ou validação param com segurança e permanecem visíveis.
As respostas devem explicar cada ID fornecido e
passar por validação estrita local de esquema, enumeração, referência e fundamentação de IOC antes de
serem aceitas. Um redutor final vê achados validados em vez do
inventário bruto. Limites de extração, lotes com falha
e contagens revisadas/enviadas são sempre relatados; cobertura incompleta força uma
avaliação geral unknown. Strings podem conter senhas, tokens de API,
dados de clientes e injeção de prompt criada por atacantes, portanto revise o limite
de IA remota antes de habilitar este recurso.
Inspecione análises anteriores por arquivo ou SHA-256:
aidebug --history /path/to/sample.exe
aidebug --history 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
Carregue um arquivo PE e pressione X (ou P) na interface gráfica principal. O AIDebug apresenta os
bytes exatos que ele aplicou hash e organiza evidências estruturais em visualizações
limitadas e navegáveis.
| Área | Evidência |
|---|---|
| Cabeçalhos | DOS, NT, COFF, Cabeçalho Opcional, características, diretórios de dados e flags de mitigação |
| Seções | Campos completos de IMAGE_SECTION_HEADER, intervalos mapeados, entropia e permissões |
| Importações e exportações | Descritores de importação, entradas INT/IAT, importações atrasadas, ordinais, nomes, RVAs e forwarders |
| Recursos | Hierarquia tipo/nome/idioma, metadados, hashes, pré-visualizações e exportação segura sem sobrescrita |
| Realocações e ASLR | Blocos/entradas de realocação e avaliação estrutural de compatibilidade com ASLR |
| TLS | Diretório TLS, dados de modelo, índice, tabela de callbacks, mapeamentos e evidência de terminação |
| Exceções e unwind | Funções de runtime x64, UNWIND_INFO, operações, handlers e registros encadeados |
| Configuração de carga | Campos versionados, flags de Guard, evidência de stack-cookie e mitigação de exploração |
| CFG | Ponteiros de check/dispatch, alvos de Guard Function ID, ordenação, supressão e verificações de consistência |
| Authenticode | Registros de certificado, evidência PKCS#7/X.509, comparação de digest de imagem PE e verificação de assinante |
| Depuração e proveniência | Cabeçalho Rich, Diretório de Depuração, CodeView RSDS/NB10, GUID do PDB, idade e caminho |
| Overlays | Offset exato, tamanho, hash, entropia, pré-visualização e exportação segura |
| .NET / CLR | Cabeçalho COR20, raiz e streams de metadados, tabelas ECMA-335, assemblies, referências e recursos |
O AIDebug não executa um PE ao construir essas visualizações. A verificação estática de certificados não é confiança de raiz Windows ou validação de revogação, metadados Rich não são atribuição, metadados de nome forte não são confiança do editor, e flags estáticas de mitigação não são prova de política de runtime efetiva.
Estes artigos fornecem os fluxos de trabalho detalhados e capturas de tela que complementam a documentação do repositório:
Abra o catálogo completo ou comece com um caso específico:
aidebug --learn
aidebug --learn mov-load
aidebug --learn lea-arithmetic
aidebug --learn switch-dispatch
Cada caso incluído é um arquivo independente em learning/cases/.
O AIDebug compila o caso selecionado em um ELF x86-64 temporário, mostra o
código C exato e as instruções geradas pelo compilador, pede ao Ghidra uma
reconstrução independente, registra a proveniência da compilação e remove o artefato temporário.
O binário da lição gerado nunca é executado.
Use --no-tui para saída de texto, ou carregue uma coleção externa revisada:
aidebug --learn movsxd --no-tui
aidebug --learn --learning-collection /path/to/reviewed-cases
A análise por IA é opcional. O modo offline determinístico permanece disponível sem credenciais.
python -m pip install "1200km-aidebug[ai]==3.0.0"
cp .env.example .env
chmod 600 .env
Configure exatamente um provedor, ou defina AIDEBUG_LLM_PROVIDER explicitamente quando
existirem várias credenciais:
AIDEBUG_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=replace_with_your_key
# Alternativas:
# OPENAI_API_KEY=replace_with_your_key
# GEMINI_API_KEY=replace_with_your_key
# OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
Use AIDEBUG_ENV_FILE=/absolute/path/to/private.env para manter a configuração longe
de diretórios de análise não confiáveis. A análise remota em massa exige o reconhecimento
explícito --accept-ai-cost. Revise o limite de dados de IA remota
antes de enviar evidências de amostras a qualquer provedor.
O modo ativo com suporte a GDB executa o ELF local selecionado. Use-o apenas dentro de um laboratório isolado e autorizado:
aidebug --binary ./sample.elf --mode debug --breakpoint main
Os comandos disponíveis incluem break, continue, step, next, finish,
registers, changes, io, disassemble e quit. O modo dinâmico com Frida está
disponível separadamente para fluxos de trabalho suportados de instrumentação local ou remota.
| Saída | Uso pretendido |
|---|---|
| Relatório HTML | Revisão humana e notas de caso |
| JSON versionado | Entrada para integração personalizada; não é um esquema nativo de fornecedor ou STIX |
| JSON de Inteligência de Strings | Inventário canônico de strings retidas mais anotações opcionais de IA validadas e cobertura |
| Candidatos YARA | Sementes de engenharia de detecção compiladas localmente que exigem revisão e teste |
| Candidatos ATT&CK | Hipóteses em nível de técnica que exigem validação analítica |
| Visualização CFG | Revisão de fluxo de controle em nível de função |
| Histórico SQLite | Evidência de sessão local e restauração de achados baseada em SHA-256 |
flowchart LR
Input[PE, ELF, or C source] --> Parse[Bounded parsing and hashing]
Parse --> Structure[Hex and PE structure evidence]
Parse --> Strings[Deterministic string intelligence]
Parse --> Disasm[Capstone disassembly]
Disasm --> Patterns[Deterministic patterns]
Disasm --> Ghidra[Ghidra reconstruction]
Patterns --> Offline[Offline findings]
Patterns --> AI[Optional LLM cross-check]
Strings --> StringAI[Opt-in chunked string AI review]
Ghidra --> AI
Offline --> Reports[HTML, JSON, YARA, CFG]
AI --> Reports
StringAI --> StringJSON[Structured string JSON]
Reports --> History[SHA-256-indexed history]Use o AIDebug apenas em software e sistemas que você está autorizado a examinar, dentro de uma VM ou laboratório de análise de malware isolado.
Leia o modelo de segurança completo, a política de segurança e o plano de limitações e validação antes de analisar amostras não confiáveis.
| Documento | Finalidade |
|---|---|
| Fluxo de trabalho do analista | Processo de análise repetível |
| Modelo de segurança | Limites de confiança e operação segura |
| Plano de validação | Afirmações de capacidade testáveis |
| Evidência de amostra | Capturas de tela ilustrativas e artefatos simulados |
| Comparação | Escopo e posicionamento |
| Prontidão de release | Portões de release reproduzíveis |
| Notas de versão do AIDebug 3.1 | Mudanças da versão atual do código-fonte |
| Notas de versão do AIDebug 3.0 | Mudanças da versão publicada anterior |
| Changelog | Histórico de versões |
Execute as verificações locais rápidas:
python -m ruff check .
python -m pytest -q
Execute o portão de release isolado completo:
./scripts/release-readiness.sh
Consulte CONTRIBUTING.md para orientações de contribuição. Não anexe malware ao vivo, credenciais, dados de casos privados ou evidências não redigidas a issues ou pull requests.
O AIDebug é distribuído sob a Licença MIT.