Leggi in russo

Diaphora MCP

Diaphora MCP è un server MCP (Model Context Protocol) per il diffing automatico di binari. Collega Diaphora (il motore di diffing) e IDA Pro (il disassemblatore) tramite il protocollo MCP, consentendo ad agenti AI (come Claude Code) di eseguire confronti di file binari, trovare patch di sicurezza e analizzare le modifiche.

Caratteristiche

• Export: Converte i database .i64/.idb analizzati nel formato SQLite di Diaphora (tramite idat.exe in modalità headless)
• Diffing: Confronta due database esportati, filtra i risultati per tipo di corrispondenza e rapporto
• Analisi delle vulnerabilità: Cerca modifiche rilevanti per la sicurezza utilizzando corrispondenza di parole chiave e euristiche
• Rilevamento delle patch: Rileva automaticamente nuovi controlli di bounds, controlli di null, gestione degli errori e modifiche crittografiche
• Classificazione: Classifica le funzioni modificate per importanza in base a CFG, salti di complessità e indicatori di sicurezza
• Grafo delle chiamate: Confronta i percorsi di chiamata (BFS, fino a N livelli) e rileva le modifiche alla causa principale nelle cascate di chiamate
• Trasferimento dei metadati: Prepara nomi, commenti e prototipi per il trasferimento tra database
• Integrazione IDA Pro MCP: Tutti gli strumenti restituiscono indirizzi e percorsi di database pronti per essere passati direttamente agli strumenti IDA Pro MCP

Installazione

1. Dipendenze

• Python 3.10+
• IDA Pro 8.x / 9.x (per esportazioni headless tramite idat.exe)
• Plugin Diaphora installato in IDA
• Claude Code (o qualsiasi altro client conforme a MCP)

2. Installazione del pacchetto

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

3. Configurazione dei percorsi

Il pacchetto tenta di trovare automaticamente IDA Pro e Diaphora nelle posizioni di installazione standard. Se non vengono trovati, è possibile impostare le seguenti variabili d'ambiente:

Per Claude Code, è possibile specificarle in ~/.claude.json (o nel file di configurazione corrispondente del proprio client 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: Per binari molto grandi (>100 MB), assicurarsi che timeout sia almeno 7200 (2 ore).

3.1. Codex e headless IDA MCP

Codex utilizza tipicamente due server MCP complementari:

• diaphora-mcp — questo progetto: esportazione, diff Diaphora e analisi dei risultati;
• ida-pro-mcp — il server di ispezione IDA upstream per idb_open, decompilazione e analisi a livello di indirizzo.

idalib-mcp è il backend headless di ida-pro-mcp, non un server Diaphora separato. Dopo averlo installato, riavvia Codex:

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

Per questo progetto, una configurazione stdio è sufficiente:

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

4. Preparazione dei database per il diffing

IDA Pro deve prima analizzare i binari (creando file .i64 o .idb). Dopodiché:

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

Oppure esegui l'intero pipeline in un unico comando:

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

Non passare .i64 direttamente agli strumenti dei risultati: è un database IDA, non SQLite. Esportalo prima.

Avvio rapido

┃ # 1. Full pipeline: export two .i64 → diff → summary report
┃ batch_export_and_diff(idb1="v1.0.i64", idb2="v1.1.i64")
 
┃ # 2. If databases are already exported
┃ diff_diaphora_dbs(db1="v1.0.sqlite", db2="v1.1.sqlite")
 
┃ # 3. Security analysis of diff results
┃ analyze_diff_results(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 4. Importance ranking of changes
┃ rank_changes(results_path="v1.0_vs_v1.1.diaphora", top_n=20)
 
┃ # 5. Find root-cause changes
┃ find_patch_root(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 6. Detect probable security patches
┃ detect_security_patches(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 7. Generate full report
┃ summarize_patch(results_path="v1.0_vs_v1.1.diaphora")

Esempio (trascrizione di sessione live)

Vedi examples/basic-session.md per una trascrizione completa passo-passo di una sessione reale di Diaphora MCP — dall'esportazione di due database IDB al confronto di funzioni individuali. Disponibile anche in russo.

Ecco un'anteprima di ciò che il server restituisce:

Input — confronta due DLL SQLite3 (2015 vs 2023):

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

Output — riepilogo dopo export + diff:

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

La sessione esamina 6 chiamate a strumenti MCP, mostrando l'esatto JSON in/out per ogni passaggio, insieme al ragionamento dell'agente.

Investigazione di un singolo database

┃ # Get database export info
┃ get_export_info(db_path="app.sqlite")
 
┃ # Search for functions
┃ search_export_db(db_path="app.sqlite", name_pattern="%crypt%", min_instructions=50)
 
┃ # Retrieve pseudocode
┃ get_function_pseudocode(db_path="app.sqlite", address="401000")

Struttura del progetto

diaphora-mcp/
├── diaphora_mcp_server.py          # Main entrypoint
├── diaphora_mcp/
│   ├── diaphora_mcp_server.py      # MCP tool registration
│   ├── config.py                   # Path configuration and auto-detection
│   ├── models.py                   # Constants and models
│   ├── core/
│   │   ├── export.py               # Headless export, batch pipeline
│   │   ├── diff.py                 # Diffing and .diaphora results reader
│   │   ├── analysis.py             # Function search, compare, explain
│   │   ├── security.py             # Keyword matching, patch detection
│   │   ├── ranking.py              # Importance ranking
│   │   ├── graph.py                # Callgraph, BFS call trees, root cause
│   │   ├── metadata.py             # Metadata preparation (names, comments)
│   │   └── report.py               # Overall patch report generation
│   └── utils/
│       ├── sqlite.py               # SQLite helpers
│       ├── format.py               # Pseudocode diff, feature vector extraction
│       └── log.py                  # Export logging utilities
├── _diaphora_headless.py           # idat.exe -S thin wrapper
└── logs/                           # Automated export logs (created dynamically)

Riferimento agli strumenti MCP (21 strumenti)

Export

Diff

Analisi

Sicurezza

Classificazione

Grafo delle chiamate

Prestazioni

Metadati

Integrazione con IDA Pro GUI (XML-RPC Bridge)

Il progetto include un'integrazione integrata con le sessioni GUI di IDA Pro in esecuzione, consentendo esportazioni istantanee direttamente dalle finestre IDA attive senza conflitti di blocco del database.

1. Avvio automatico: Copia diaphora_gui_listener.py nella directory plugins/ di IDA Pro. Avvierà un server XML-RPC in background sulla porta 28652 ogni volta che IDA viene avviato.
2. Smart Export: Quando si chiama export_idb_to_diaphora, il server MCP controlla la porta 28652. Se una sessione è attiva, esegue l'esportazione direttamente nella GUI. Altrimenti, ricade automaticamente sull'esecuzione headless in background tramite idat.exe.

Per istruzioni dettagliate sulla configurazione del bridge, vedere GUI_INSTRUCTIONS.md.

Gestione di database giganteschi (100k+ funzioni)

Quando si elaborano progetti estremamente grandi, Diaphora MCP applica ottimizzazioni specifiche:

• Limite di ricorsione: Il limite di ricorsione di Python viene automaticamente aumentato a 100000 (sys.setrecursionlimit) per prevenire crash durante le traversate di grandi grafi di chiamate.
• Ottimizzazioni delle transazioni SQLite: In diaphora_config.py, impostando COMMIT_AFTER_EACH_GUI_UPDATE = False si riducono le scritture su disco, accelerando l'esportazione GUI di 2x-3x.
• Microcodice Hex-Rays: Disabilita l'esportazione del microcodice (EXPORTING_USE_MICROCODE = False nella configurazione Diaphora) per un'esportazione più rapida quando il decompilatore non è strettamente richiesto.

Integrazione con IDA Pro MCP

Strumenti come analyze_diff_results, compare_functions e find_function_match restituiscono un blocco ida_pro_mcp contenente indirizzi e percorsi. Queste informazioni possono essere passate direttamente agli strumenti ida-pro-mcp:

┃ # 1. Diaphora finds a suspicious function
┃ analyze_diff_results(results_path="diff.diaphora")
┃   → addr1="401000", db1="old.sqlite"
 
┃ # 2. IDA Pro MCP decompiles it
┃ decompile_function(address="401000")

Esempi

Per vedere Diaphora MCP in azione, consulta i seguenti esempi:

• Basic Session Transcript: Una panoramica di una sessione MCP reale con input/output JSON esatto per ogni chiamata di strumento — dall'esportazione al confronto di funzioni. Disponibile anche in russo.

Linee guida per agenti AI (Importante)

Se sei un assistente di codifica AI (come Claude Code) che utilizza questo protocollo, tieni presenti le seguenti regole di compatibilità:

1. Schemi di esportazione GUI vs. Headless:

   • L'esportazione tramite una sessione GUI attiva (plugin ida_mcp.py) produce uno schema personalizzato contenente tabelle come calls, strings, structures, ma nessuna tabella program.
   • L'esportazione headless (tramite idat.exe) produce lo schema Diaphora ufficiale che contiene la tabella program.
   • Fondamentale: Il motore di diffing (diff_diaphora_dbs) richiede lo schema ufficiale. Esporta sempre in modalità headless se intendi confrontare/differenziare database.

2. Database bloccati nella GUI:

   • Un database attualmente aperto nella GUI di IDA Pro è bloccato. Tentare di esportarlo in modalità headless fallirà.
   • Se hai bisogno di differenziare il database attualmente aperto, chiedi all'utente di chiuderlo nella GUI (o di aprire un database fittizio) per rilasciare il blocco del file, quindi attiva un'esportazione headless.

3. Evita collisioni di nomi dei database:

   • I database di esportazione Diaphora predefiniti hanno nome <basename>.diaphora.sqlite.
   • Non usare mai <basename>.sqlite per le esportazioni Diaphora, poiché entra in conflitto con il database cache interno creato dal supervisore ida-pro-mcp.

Stato di verifica e limitazioni

I fixture controllati di IDA Pro 9.3 superano la suite di regressione: 16 passed, 1 xpassed. Sono state verificate anche un'esportazione reale e un diff Diaphora di due DLL SQLite3. Gli IDB grandi o aperti in GUI richiedono ancora un lock IDA libero, un DIAPHORA_OUTPUT_ROOT valido e un timeout del client MCP sufficientemente grande.

Licenza

MIT