diaphora-mcp

[Versione russa](https://github.com/xteardx/diaphora-mcp/blob/master/README.ru.md)

# Diaphora MCP

Confronta due binari analizzati con IDA dal tuo assistente AI. Diaphora MCP esporta i database IDA salvati, esegue [Diaphora](https://github.com/joxeankoret/diaphora) e consente all'AI di ispezionare le funzioni corrispondenti e i loro call graph.

L'interfaccia predefinita dispone di **10 strumenti** incentrati sul confronto. Diaphora fornisce le corrispondenze; l'AI legge il codice effettivo e spiega le modifiche.

[Avvio rapido](#quick-start) · [Esempi](#examples) · [Strumenti](#tools) · [Risoluzione dei problemi](#troubleshooting)

```text
old.i64 + new.i64 → headless export → SQLite exports + diff results
                                       ↓
                            summary → matched code → call graph
```

## Requisiti

- Python 3.10+, IDA Pro con `idat.exe`/`idat64` e un plugin Diaphora installato.
- Entrambi i binari analizzati e salvati come database `.i64`/`.idb`.
- Un client MCP locale, come Codex, Claude Code o Cursor.
- Un decompilatore Hex-Rays compatibile solo se desideri lo pseudocodice.

IDA e Diaphora vengono installati separatamente. La validazione dello schema di diff attualmente è mirata a Diaphora **3.4.1**; altri schemi potrebbero richiedere aggiornamenti di compatibilità. L'interprete Python utilizzato per il diff deve avere installate le dipendenze standalone di Diaphora.

## Avvio rapido

### 1. Installa e crea una directory di output

```powershell
git clone https://github.com/xTeardx/diaphora-mcp.git
cd diaphora-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
New-Item -ItemType Directory -Force C:\diaphora-outputs | Out-Null
```

### 2. Connetti il server MCP

Aggiungi questa voce alla configurazione MCP del tuo client. Sostituisci i percorsi del repository, di IDA e di Diaphora con i tuoi percorsi di installazione. Usa l'eseguibile Python dell'ambiente in cui hai installato questo progetto.

```json
{
  "mcpServers": {
    "diaphora": {
      "command": "C:/src/diaphora-mcp/.venv/Scripts/python.exe",
      "args": ["C:/src/diaphora-mcp/diaphora_mcp_server.py"],
      "env": {
        "IDAT_PATH": "C:/Program Files/IDA Professional 9.3/idat.exe",
        "DIAPHORA_DIR": "C:/Program Files/IDA Professional 9.3/plugins/diaphora",
        "DIAPHORA_OUTPUT_ROOT": "C:/diaphora-outputs"
      }
    }
  }
}
```

Il client avvia il server tramite stdio; non c'è alcun servizio web separato da avviare. Riavvia il server MCP dopo aver modificato il suo codice o l'ambiente. Una connessione riuscita espone i 10 strumenti elencati di seguito.

### 3. Chiedi al tuo assistente di confrontare i file

```text
Use Diaphora to compare C:/analysis/old.i64 (old) against
C:/analysis/new.i64 (new). Save output under C:/diaphora-outputs/run-001.
Export headlessly with assembly detail, keep the exports, show a summary,
then inspect partial matches and explain the code changes in the interesting
functions. Use the result mapping when comparing functions and call graphs.
```

Scegli ogni volta una **directory di esecuzione nuova**. I target generati esistenti non vengono mai sovrascritti.

## Esempi

I seguenti blocchi JSON sono **argomenti degli strumenti MCP**, non comandi shell. Il tuo assistente può chiamare direttamente gli strumenti indicati. I percorsi e `0x401000` sono esempi; usa i percorsi e gli indirizzi restituiti dalla tua esecuzione.

### 1. Esporta e confronta due database IDA

Strumento: **`batch_export_and_diff`**. Il vecchio è sempre il primo input, il nuovo il secondo.

```json
{
  "idb1_path": "C:/analysis/old.i64",
  "idb2_path": "C:/analysis/new.i64",
  "output_dir": "C:/diaphora-outputs/run-001",
  "export_mode": "headless",
  "use_decompiler": false,
  "summaries_only": false,
  "cleanup": false,
  "limit": 100,
  "unmatched_limit": 50
}
```

Questo mantiene il dettaglio dell'assembly senza richiedere Hex-Rays. Seleziona il profilo di esportazione di cui hai bisogno:

| Dettaglio | `use_decompiler` | `summaries_only` | Uso |
| --- | --- | --- | --- |
| Riepiloghi delle corrispondenze | `false` | `true` | Prima passata veloce; nessun codice dettagliato |
| Assembly | `false` | `false` | Confronta il disassembly senza un decompilatore |
| Assembly + pseudocodice | `true` | `false` | Revisione del codice con un decompilatore Hex-Rays compatibile; più lento |

Prendi sempre i percorsi di output dalla risposta:

```text
OLD_SQLITE = steps.export1.output
NEW_SQLITE = steps.export2.output
RESULTS    = steps.diff.output
```

Per questo esempio, i file generati sono `old.diaphora.sqlite`, `new.diaphora.sqlite` e `old_vs_new.diaphora` sotto `run-001`. Nomi di base degli input uguali producono nomi di esportazione distinti `old_`/`new_`. Mantieni `cleanup=false` per l'ispezione successiva delle funzioni.

### 2. Ottieni un riepilogo e ispeziona le corrispondenze modificate

Strumento: **`get_diff_summary`**.

```json
{
  "results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```

Strumento: **`get_diff_results`**. Questa pagina inizia con le corrispondenze parziali a rapporto più basso.

```json
{
  "results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora",
  "match_type": "partial",
  "min_ratio": 0.0,
  "limit": 50,
  "offset": 0,
  "unmatched_limit": 50,
  "unmatched_offset": 0,
  "sort_by": "ratio",
  "sort_order": "asc"
}
```

`partial` seleziona una categoria di corrispondenza di Diaphora, non garantisce un cambiamento comportamentale. Usa `match_type="all"` per tutte le categorie supportate. La risposta include i conteggi per categoria, il totale filtrato, le corrispondenze, le righe non corrispondenti, `next_offset` e `next_unmatched_offset`.

Per continuare, copia gli offset successivi restituiti nella chiamata successiva, mantenendo gli stessi filtri e l'ordinamento. Ad esempio, se sono `50` e `50`, usa `offset=50` e `unmatched_offset=50`. Un offset successivo `null` significa che quella lista è terminata; smetti di avanzarla. Le due liste procedono in modo indipendente. Le dimensioni di pagina devono essere positive e sono limitate a 5000. Usa `sort_order="desc"` per ispezionare prima le corrispondenze più forti.

### 3. Confronta una funzione corrispondente e il suo grafo

Strumento: **`compare_functions`**.

```json
{
  "db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
  "address": "0x401000",
  "match_results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```

La risposta contiene `function_old`, `function_new`, assembly/pseudocodice disponibili, differenze misurate e prove di identità. Puoi usare `name` invece di `address`. Se vengono forniti entrambi i selettori, l'indirizzo ha la precedenza; omettilo quando selezioni per nome.

Strumento: **`get_changed_callgraph`** accetta gli stessi argomenti di cui sopra. Traduce gli indirizzi corrispondenti di chiamanti/chiamati prima di segnalare le modifiche, e separa i vicini non risolti dalle differenze di edge confermate.

Preferisci **indirizzi con prefisso `0x`** per rendere esplicito l'input esadecimale. Fornisci `match_results_path` quando disponibile: gestisce il rebasing e le funzioni rinominate. Indirizzi uguali da soli non stabiliscono l'identità. Le corrispondenze ambigue o mancanti rimangono non risolte anziché essere chiamate eliminazioni. Se hai verificato manualmente una coppia, puoi fornire esplicitamente `address2` o `name2`.

### 4. Trova una funzione e leggi il suo codice

Strumento: **`search_export_db`**. `name_pattern` usa SQL LIKE: `%` corrisponde a qualsiasi sequenza.

```json
{
  "db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "name_pattern": "%parse%",
  "min_instructions": 20,
  "limit": 20
}
```

Strumento: **`get_function_pseudocode`** restituisce lo pseudocodice disponibile **e l'assembly**, nonostante il nome.

```json
{
  "db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "address": "0x401000"
}
```

Se lo pseudocodice è vuoto, riesegui l'esportazione in una nuova directory di esecuzione con `use_decompiler=true` e `summaries_only=false`, usando un decompilatore compatibile. Usa `get_export_info` con `db_path` per ispezionare i metadati dell'esportazione.

### 5. Confronta esportazioni che hai già

Strumento: **`diff_diaphora_dbs`**. Questo salta l'esportazione IDA e confronta le esportazioni SQLite ufficiali esistenti.

```json
{
  "db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
  "db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
  "output_path": "C:/diaphora-outputs/another-diff.diaphora"
}
```

Per una nuova esportazione, usa `export_idb_to_diaphora` con `idb_path`, un `output_path` nuovo e `export_mode="headless"`.

## Strumenti

| Strumento | Scopo |
| --- | --- |
| `export_idb_to_diaphora` | Esporta un database IDA salvato |
| `batch_export_and_diff` | Esporta entrambi i database e li confronta |
| `diff_diaphora_dbs` | Confronta esportazioni esistenti |
| `get_diff_summary` | Statistiche delle corrispondenze ed esempi limitati |
| `get_diff_results` | Risultati filtrati, ordinati e paginati |
| `get_export_info` | Metadati e conteggi dell'esportazione |
| `search_export_db` | Cerca funzioni |
| `get_function_pseudocode` | Leggi assembly/pseudocodice |
| `compare_functions` | Confronta una coppia vecchio/nuovo risolta |
| `get_changed_callgraph` | Confronta chiamanti/chiamati mappati |

Le firme esatte sono individuabili tramite MCP `tools/list`. Vedi [Riferimento degli strumenti](https://github.com/xteardx/diaphora-mcp/blob/master/docs/TOOLS.md).

## Modalità di esportazione e configurazione

| Modalità | Comportamento |
| --- | --- |
| `headless` | Avvia IDA in modalità headless e valida lo schema di diff; consigliata per i confronti |
| `auto` | Prova il bridge GUI attivo, poi il fallback headless |
| `gui` | Richiede la sessione GUI aperta corretta; nessun fallback headless |

`batch_export_and_diff` richiede `headless`.

| Variabile d'ambiente | Significato |
| --- | --- |
| `IDAT_PATH` | Percorso assoluto dell'eseguibile headless di IDA |
| `DIAPHORA_DIR` | Directory contenente gli script di Diaphora |
| `DIAPHORA_OUTPUT_ROOT` | Root consentita esistente per nuove esportazioni e risultati di diff |
| `DIAPHORA_PYTHON` | Interprete opzionale per il diff; predefinito all'interprete del server MCP |
| `DIAPHORA_ENABLE_LEGACY_TOOLS` | Esattamente `1` abilita la precedente interfaccia a 21 strumenti |

Il matching legacy, i punteggi delle feature, il triage di sicurezza, i report, i metadati e la diagnostica rimangono opt-in. Per abilitarli, aggiungi la seguente voce all'oggetto `env` della configurazione e riavvia:

```json
{
  "DIAPHORA_ENABLE_LEGACY_TOOLS": "1"
}
```

Questi strumenti usano euristiche; i loro punteggi non provano equivalenza semantica, correzioni di sicurezza o causalità. [Configurazione](https://github.com/xteardx/diaphora-mcp/blob/master/docs/CONFIGURATION.md) · [Configurazione GUI](https://github.com/xteardx/diaphora-mcp/blob/master/GUI_INSTRUCTIONS.md).

## Risoluzione dei problemi

| Sintomo | Azione |
| --- | --- |
| Il target esiste già | Usa una directory di esecuzione o un nome di file di output nuovi |
| Output fuori dalla root consentita | Scegli una destinazione sotto `DIAPHORA_OUTPUT_ROOT`; crea prima la root |
| Database IDA passato a uno strumento per i risultati | Usa le esportazioni `.diaphora.sqlite` restituite o i risultati `.diaphora`, a seconda dei casi |
| Controparte mancante/ambigua | Controlla l'ordine vecchio/nuovo e la mappatura; ispeziona manualmente il candidato |
| Assembly/pseudocodice vuoto | Controlla il profilo di esportazione; ottieni una nuova esportazione dettagliata |
| Esportazione/diff molto lenta | Aumenta il timeout del client MCP; ispeziona i `logs/` locali; considera una prima passata solo con i riepiloghi |
| IDB bloccato da una sessione IDA | Chiudi la sessione o usa la modalità di esportazione GUI corrispondente per una singola esportazione |
| Schema non supportato | Riesporta con la versione di Diaphora supportata; vedi le tabelle/colonne mancanti segnalate |

Il matching rimane euristico; un rapporto elevato è un'evidenza, non una prova. Le funzioni non corrispondenti non sono aggiunte/eliminazioni confermate. Tieni binari, IDB, esportazioni e log fuori da Git. Vedi [Flussi di lavoro](https://github.com/xteardx/diaphora-mcp/blob/master/docs/WORKFLOWS.md), [Limitazioni](https://github.com/xteardx/diaphora-mcp/blob/master/docs/LIMITATIONS.md) e [Sicurezza](https://github.com/xteardx/diaphora-mcp/blob/master/SECURITY.md).

## Sviluppo

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q .
git diff --check
```

La suite di regressione usa database sintetici e processi IDA simulati. L'esportazione IDA reale richiede una validazione di integrazione locale. [Contribuire](https://github.com/xteardx/diaphora-mcp/blob/master/CONTRIBUTING.md) · [Istruzioni per l'agente](https://github.com/xteardx/diaphora-mcp/blob/master/AGENTS.md).