Читать на русском языке

Diaphora MCP

Diaphora MCP é um servidor MCP (Model Context Protocol) para diffing binário automatizado. Ele conecta o Diaphora (o motor de diffing) e o IDA Pro (o descompilador) através do protocolo MCP, permitindo que agentes de IA (como o Claude Code) realizem comparação de arquivos binários, encontrem patches de segurança e analisem alterações.

Funcionalidades

• Exportação: Converte bases de dados .i64 / .idb analisadas para o formato SQLite do Diaphora (via modo headless idat.exe)
• Diffing: Compara duas bases de dados exportadas, filtra resultados por tipo de correspondência e proporção
• Análise de Vulnerabilidades: Pesquisa alterações relevantes de segurança usando correspondência de palavras-chave e heurísticas
• Detecção de Patches: Detecta automaticamente novas verificações de limites, verificações nulas, tratamento de erros e alterações criptográficas
• Classificação: Classifica funções alteradas por importância com base no CFG, saltos de complexidade e indicadores de segurança
• Grafo de Chamadas: Compara caminhos de chamada (BFS, até N níveis) e detecta alterações de causa raiz em cascatas de chamadas
• Transferência de Metadados: Prepara nomes, comentários e protótipos para transferência entre bases de dados
• Integração com IDA Pro MCP: Todas as ferramentas retornam endereços e caminhos de bases de dados prontos para serem passados diretamente para as ferramentas do IDA Pro MCP

Instalação

1. Dependências

• Python 3.10+
• IDA Pro 8.x / 9.x (para exportações headless via idat.exe)
• Plugin Diaphora instalado no IDA
• Claude Code (ou qualquer outro cliente compatível com MCP)

2. Instalação do Pacote

git clone https://github.com/xTeardx/diaphora-mcp.git
cd diaphora-mcp
pip install -e .

3. Configuração de Caminhos

O pacote tenta encontrar automaticamente o IDA Pro e o Diaphora nos locais de instalação padrão. Se não forem encontrados, pode definir as seguintes variáveis de ambiente:

No Claude Code, pode especificá-los em ~/.claude.json (ou no ficheiro de configuração correspondente do seu cliente MCP):

{
  "mcpServers": {
    "diaphora": {
      "command": "python",
      "args": ["path/to/repo/diaphora_mcp_server.py"],
      "env": {
        "IDAT_PATH": "C:\\Program Files\\IDA Pro 9.3\\idat.exe",
        "DIAPHORA_DIR": "C:\\Program Files\\IDA Pro 9.3\\plugins\\diaphora-3.4.1"
      },
      "timeout": 7200
    }
  }
}

Nota: Para binários muito grandes (>100 MB), certifique-se de que o timeout é pelo menos 7200 (2 horas).

3.1. Codex e IDA MCP headless

O Codex normalmente utiliza dois servidores MCP complementares:

• diaphora-mcp — este projeto: exportação, diff Diaphora e análise de resultados;
• ida-pro-mcp — o servidor de inspeção IDA upstream para idb_open, descompilação e análise ao nível do endereço.

idalib-mcp é o backend headless do ida-pro-mcp, não um servidor Diaphora separado. Após instalá-lo, reinicie o Codex:

uv run ida-pro-mcp --install codex --transport streamable-http --scope global --ida-rpc http://127.0.0.1:8745/mcp

Para este projeto, uma configuração stdio é suficiente:

[mcp_servers.diaphora-mcp]
command = "python"
args = ["D:\\path\\to\\diaphora-mcp\\diaphora_mcp_server.py"]
startup_timeout_sec = 120

4. Preparação de Bases de Dados para o Diffing

O IDA Pro deve analisar primeiro os binários (criando ficheiros .i64 ou .idb). Depois disso:

┃ export_idb_to_diaphora(idb_path="old_version.i64")
┃ export_idb_to_diaphora(idb_path="new_version.i64")

Ou execute todo o pipeline num único comando:

┃ batch_export_and_diff(idb1="old.i64", idb2="new.i64")

Não passe .i64 diretamente para as ferramentas de resultados: é uma base de dados IDA, não SQLite. Exporte primeiro.

Início Rápido

┃ # 1. Pipeline completo: exportar dois .i64 → diff → relatório resumido
┃ batch_export_and_diff(idb1="v1.0.i64", idb2="v1.1.i64")
 
┃ # 2. Se as bases de dados já estiverem exportadas
┃ diff_diaphora_dbs(db1="v1.0.sqlite", db2="v1.1.sqlite")
 
┃ # 3. Análise de segurança dos resultados do diff
┃ analyze_diff_results(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 4. Classificação por importância das alterações
┃ rank_changes(results_path="v1.0_vs_v1.1.diaphora", top_n=20)
 
┃ # 5. Encontrar alterações de causa raiz
┃ find_patch_root(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 6. Detetar patches de segurança prováveis
┃ detect_security_patches(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 7. Gerar relatório completo
┃ summarize_patch(results_path="v1.0_vs_v1.1.diaphora")

Exemplo (Transcrição de Sessão ao Vivo)

Consulte examples/basic-session.md para uma transcrição passo a passo completa de uma sessão real do Diaphora MCP — desde a exportação de duas bases de dados IDB até à comparação de funções individuais. Também disponível em Russo.

Aqui está uma prévia do que o servidor retorna:

Entrada — comparar duas DLLs SQLite3 (2015 vs 2023):

{"idb1_path": "old.i64", "idb2_path": "new.i64", "use_decompiler": false}

Saída — resumo após exportação + diff:

{
  "best_matches": 60,
  "partial_matches": 993,
  "multimatches": 52,
  "unmatched_primary": 2647
}

A sessão percorre 6 chamadas de ferramentas MCP, mostrando o JSON de entrada/saída exato para cada passo, com o raciocínio do agente ao lado.

Investigar uma Única Base de Dados

┃ # Obter informação de exportação da base de dados
┃ get_export_info(db_path="app.sqlite")
 
┃ # Procurar funções
┃ search_export_db(db_path="app.sqlite", name_pattern="%crypt%", min_instructions=50)
 
┃ # Obter pseudocódigo
┃ get_function_pseudocode(db_path="app.sqlite", address="401000")

Estrutura do Projeto

diaphora-mcp/
├── diaphora_mcp_server.py          # Ponto de entrada principal
├── diaphora_mcp/
│   ├── diaphora_mcp_server.py      # Registo de ferramentas MCP
│   ├── config.py                   # Configuração de caminhos e deteção automática
│   ├── models.py                   # Constantes e modelos
│   ├── core/
│   │   ├── export.py               # Exportação headless, pipeline batch
│   │   ├── diff.py                 # Leitor de diff e resultados .diaphora
│   │   ├── analysis.py             # Pesquisa de funções, comparação, explicação
│   │   ├── security.py             # Correspondência de palavras-chave, deteção de patches
│   │   ├── ranking.py              # Classificação por importância
│   │   ├── graph.py                # Grafo de chamadas, árvores BFS, causa raiz
│   │   ├── metadata.py             # Preparação de metadados (nomes, comentários)
│   │   └── report.py               # Geração de relatório global de patches
│   └── utils/
│       ├── sqlite.py               # Utilitários SQLite
│       ├── format.py               # Diff de pseudocódigo, extração de vetores de características
│       └── log.py                  # Utilitários de registo de exportação
├── _diaphora_headless.py           # Wrapper fino do idat.exe -S
└── logs/                           # Registos de exportação automatizada (criados dinamicamente)

Referência de Ferramentas MCP (21 ferramentas)

Exportação

Diff

Análise

Segurança

Classificação

Grafo de Chamadas

Desempenho

Metadados

Integração com IDA Pro GUI (Ponte XML-RPC)

O projeto inclui integração integrada com sessões IDA Pro GUI em execução, permitindo exportações instantâneas diretamente de janelas IDA ativas sem conflitos de bloqueio de base de dados.

1. Auto-inicialização: Copie diaphora_gui_listener.py para o diretório plugins/ do seu IDA Pro. Ele iniciará um servidor XML-RPC em segundo plano na porta 28652 sempre que o IDA arrancar.
2. Exportação Inteligente: Ao chamar export_idb_to_diaphora, o servidor MCP verifica a porta 28652. Se uma sessão estiver ativa, executa a exportação diretamente na GUI. Caso contrário, recai automaticamente para execução headless em segundo plano via idat.exe.

Para instruções detalhadas sobre a configuração da ponte, consulte GUI_INSTRUCTIONS.md.

Lidar com Bases de Dados Gigantescas (100k+ funções)

Ao processar projetos extremamente grandes, o Diaphora MCP aplica otimizações específicas:

• Limite de Recursão: O limite de recursão do Python é automaticamente aumentado para 100000 (sys.setrecursionlimit) para evitar falhas durante travessias grandes do grafo de chamadas.
• Otimizações de Transação SQLite: No seu diaphora_config.py, definir COMMIT_AFTER_EACH_GUI_UPDATE = False reduz as escritas no disco, acelerando a exportação GUI 2x a 3x.
• Microcódigo Hex-Rays: Desative a exportação de microcódigo (EXPORTING_USE_MICROCODE = False na configuração do Diaphora) para uma exportação mais rápida quando o descompilador não for estritamente necessário.

Integração com IDA Pro MCP

Ferramentas como analyze_diff_results, compare_functions e find_function_match retornam um bloco ida_pro_mcp contendo endereços e caminhos. Esta informação pode ser passada diretamente para as ferramentas ida-pro-mcp:

┃ # 1. Diaphora encontra uma função suspeita
┃ analyze_diff_results(results_path="diff.diaphora")
┃   → addr1="401000", db1="old.sqlite"
 
┃ # 2. IDA Pro MCP descompila-a
┃ decompile_function(address="401000")

Exemplos

Para ver o Diaphora MCP em ação, consulte os seguintes exemplos:

• Transcrição de Sessão Básica: Uma sessão MCP real com entrada/saída JSON exata para cada chamada de ferramenta — desde a exportação até à comparação de funções. Também disponível em Russo.

Diretrizes para Agentes de IA (Importante)

Se é um assistente de IA de codificação (como o Claude Code) a usar este protocolo, tenha em mente as seguintes regras de compatibilidade:

1. Esquemas de Exportação GUI vs. Headless:

   • A exportação através de uma sessão GUI ativa (ida_mcp.py plugin) produz um esquema personalizado contendo tabelas como calls, strings, structures, mas sem tabela program.
   • A exportação headless (via idat.exe) produz o esquema oficial do Diaphora contendo a tabela program.
   • Crucial: O motor de diff (diff_diaphora_dbs) requer o esquema oficial. Exporte sempre em modo headless se pretender comparar/fazer diff de bases de dados.

2. Bases de Dados Bloqueadas na GUI:

   • Uma base de dados atualmente aberta na GUI do IDA Pro está bloqueada. Tentar exportá-la em modo headless irá falhar.
   • Se precisar de fazer diff da base de dados atualmente aberta, peça ao utilizador para a fechar na GUI (ou abrir uma base de dados fictícia) para libertar o bloqueio de ficheiro, e depois acione uma exportação headless.

3. Evitar Colisões de Nomes de Base de Dados:

   • As bases de dados de exportação do Diaphora têm como padrão <basename>.diaphora.sqlite.

Estado de Verificação e Limitações

As fixtures verificadas do IDA Pro 9.3 passam na suíte de regressão: 16 passed, 1 xpassed. Uma exportação real em cenário e diff Diaphora de duas DLLs SQLite3 também foram verificados. Bases de dados grandes ou abertas na GUI ainda requerem um bloqueio IDA livre, um DIAPHORA_OUTPUT_ROOT válido e um tempo limite do cliente MCP suficientemente grande.

Licença

MIT