diaphora-mcp

[Русская версия](https://github.com/xteardx/diaphora-mcp/blob/master/README.ru.md)

# Diaphora MCP

Vergleiche zwei von IDA analysierte Binärdateien aus deinem KI-Assistenten heraus. Diaphora MCP exportiert die gespeicherten IDA-Datenbanken, führt [Diaphora](https://github.com/joxeankoret/diaphora) aus und ermöglicht der KI, entsprechende Funktionen und ihre Aufrufgraphen zu untersuchen.

Die Standardoberfläche bietet **10 Tools**, die auf den Vergleich ausgerichtet sind. Diaphora liefert Übereinstimmungen; die KI liest den tatsächlichen Code und erklärt die Änderungen.

[Schnellstart](#quick-start) · [Beispiele](#examples) · [Tools](#tools) · [Fehlerbehebung](#troubleshooting)

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

## Anforderungen

- Python 3.10+, IDA Pro mit `idat.exe`/`idat64` und ein installiertes Diaphora-Plugin.
- Beide Binärdateien analysiert und als `.i64`/`.idb`-Datenbanken gespeichert.
- Ein lokaler MCP-Client, wie Codex, Claude Code oder Cursor.
- Ein kompatibler Hex-Rays-Decompiler nur, wenn du Pseudocode möchtest.

IDA und Diaphora werden separat installiert. Die Diff-Schema-Validierung zielt derzeit auf Diaphora **3.4.1** ab; andere Schemata benötigen möglicherweise Kompatibilitätsaktualisierungen. Der für den Diff verwendete Python-Interpreter muss über die eigenständigen Abhängigkeiten von Diaphora verfügen.

## Schnellstart

### 1. Installieren und ein Ausgabeverzeichnis erstellen

```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. Den MCP-Server verbinden

Füge diesen Eintrag zur MCP-Konfiguration deines Clients hinzu. Ersetze die Repository-, IDA- und Diaphora-Pfade durch deine Installationspfade. Verwende die Python-Executable aus der Umgebung, in der du dieses Projekt installiert hast.

```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"
      }
    }
  }
}
```

Der Client startet den Server über stdio; es gibt keinen separaten Webdienst zum Starten. Starte den MCP-Server neu, nachdem du seinen Code oder seine Umgebung geändert hast. Eine erfolgreiche Verbindung stellt die unten aufgeführten 10 Tools bereit.

### 3. Bitte deinen Assistenten, die Dateien zu vergleichen

```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.
```

Wähle jedes Mal ein **frisches Ausführungsverzeichnis**. Vorhandene generierte Ziele werden niemals überschrieben.

## Beispiele

Die folgenden JSON-Blöcke sind **MCP-Tool-Argumente**, keine Shell-Befehle. Dein Assistent kann die genannten Tools direkt aufrufen. Pfade und `0x401000` sind Beispiele; verwende die Pfade und Adressen, die von deinem eigenen Lauf zurückgegeben wurden.

### 1. Zwei IDA-Datenbanken exportieren und vergleichen

Tool: **`batch_export_and_diff`**. Alt ist immer die erste Eingabe, neu die zweite.

```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
}
```

Dies behält Assembly-Details bei, ohne Hex-Rays zu erfordern. Wähle das benötigte Exportprofil:

| Detail | `use_decompiler` | `summaries_only` | Verwendung |
| --- | --- | --- | --- |
| Übereinstimmungszusammenfassungen | `false` | `true` | Schneller erster Durchlauf; kein detaillierter Code |
| Assembly | `false` | `false` | Disassembly ohne Decompiler vergleichen |
| Assembly + Pseudocode | `true` | `false` | Code-Review mit einem kompatiblen Hex-Rays-Decompiler; langsamer |

Entnimm die Ausgabepfade immer der Antwort:

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

Für dieses Beispiel sind die generierten Dateien `old.diaphora.sqlite`, `new.diaphora.sqlite` und `old_vs_new.diaphora` unter `run-001`. Gleiche Basisnamen der Eingaben erzeugen unterschiedliche Exportnamen `old_`/`new_`. Behalte `cleanup=false` für die spätere Funktionsuntersuchung bei.

### 2. Eine Zusammenfassung abrufen und geänderte Übereinstimmungen untersuchen

Tool: **`get_diff_summary`**.

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

Tool: **`get_diff_results`**. Diese Seite beginnt mit partiellen Übereinstimmungen mit niedrigerem Verhältnis.

```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` wählt eine Diaphora-Übereinstimmungskategorie aus, keine Garantie für eine Verhaltensänderung. Verwende `match_type="all"` für alle unterstützten Kategorien. Die Antwort enthält Kategoriezählungen, die gefilterte Gesamtzahl, Übereinstimmungen, nicht zugeordnete Zeilen, `next_offset` und `next_unmatched_offset`.

Um fortzufahren, kopiere die zurückgegebenen nächsten Offsets in den nächsten Aufruf und behalte dieselben Filter und dieselbe Sortierung bei. Wenn sie beispielsweise `50` und `50` sind, verwende `offset=50` und `unmatched_offset=50`. Ein `null`-nächster-Offset bedeutet, dass diese Liste abgeschlossen ist; höre auf, sie weiterzuschieben. Die beiden Listen schreiten unabhängig voran. Seitengrößen müssen positiv sein und sind auf 5000 begrenzt. Verwende `sort_order="desc"`, um die stärksten Übereinstimmungen zuerst zu untersuchen.

### 3. Eine übereinstimmende Funktion und ihren Graphen vergleichen

Tool: **`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"
}
```

Die Antwort enthält `function_old`, `function_new`, verfügbares Assembly/Pseudocode, gemessene Unterschiede und Identitätsnachweise. Du kannst `name` anstelle von `address` verwenden. Wenn beide Selektoren angegeben werden, hat die Adresse Vorrang; lasse sie weg, wenn du nach Namen auswählst.

Tool: **`get_changed_callgraph`** akzeptiert dieselben Argumente wie oben. Es übersetzt entsprechende Aufrufer-/Aufgerufenen-Adressen, bevor Änderungen gemeldet werden, und trennt unaufgelöste Nachbarn von bestätigten Kantenunterschieden.

Bevorzuge **`0x`-präfixierte Adressen**, um hexadezimale Eingaben explizit zu machen. Gib `match_results_path` an, wenn verfügbar: Es behandelt Rebasing und umbenannte Funktionen. Gleiche Adressen allein begründen keine Identität. Mehrdeutige oder fehlende Übereinstimmungen bleiben unaufgelöst, statt als Löschungen bezeichnet zu werden. Wenn du ein Paar manuell verifiziert hast, kannst du `address2` oder `name2` explizit angeben.

### 4. Eine Funktion finden und ihren Code lesen

Tool: **`search_export_db`**. `name_pattern` verwendet SQL LIKE: `%` entspricht einer beliebigen Sequenz.

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

Tool: **`get_function_pseudocode`** gibt trotz seines Namens verfügbaren Pseudocode **und Assembly** zurück.

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

Wenn Pseudocode leer ist, führe den Export erneut in einem neuen Ausführungsverzeichnis mit `use_decompiler=true` und `summaries_only=false` unter Verwendung eines kompatiblen Decompilers aus. Verwende `get_export_info` mit `db_path`, um Exportmetadaten zu untersuchen.

### 5. Exporte vergleichen, die du bereits hast

Tool: **`diff_diaphora_dbs`**. Dies überspringt den IDA-Export und vergleicht die vorhandenen offiziellen SQLite-Exporte.

```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"
}
```

Für einen neuen Export verwende `export_idb_to_diaphora` mit `idb_path`, einem frischen `output_path` und `export_mode="headless"`.

## Tools

| Tool | Zweck |
| --- | --- |
| `export_idb_to_diaphora` | Eine gespeicherte IDA-Datenbank exportieren |
| `batch_export_and_diff` | Beide Datenbanken exportieren und vergleichen |
| `diff_diaphora_dbs` | Vorhandene Exporte vergleichen |
| `get_diff_summary` | Übereinstimmungsstatistiken und begrenzte Beispiele |
| `get_diff_results` | Gefilterte, sortierte, paginierte Ergebnisse |
| `get_export_info` | Exportmetadaten und Zählungen |
| `search_export_db` | Funktionen suchen |
| `get_function_pseudocode` | Assembly/Pseudocode lesen |
| `compare_functions` | Ein aufgelöstes Alt/Neu-Paar vergleichen |
| `get_changed_callgraph` | Zugeordnete Aufrufer/Aufgerufene vergleichen |

Exakte Signaturen sind über MCP `tools/list` auffindbar. Siehe [Tool-Referenz](https://github.com/xteardx/diaphora-mcp/blob/master/docs/TOOLS.md).

## Exportmodi und Konfiguration

| Modus | Verhalten |
| --- | --- |
| `headless` | IDA headless starten und das Diff-Schema validieren; empfohlen für Vergleiche |
| `auto` | Zuerst die aktive GUI-Bridge versuchen, dann Headless-Fallback |
| `gui` | Die korrekte offene GUI-Sitzung erfordern; kein Headless-Fallback |

`batch_export_and_diff` erfordert `headless`.

| Umgebungsvariable | Bedeutung |
| --- | --- |
| `IDAT_PATH` | Absoluter Pfad zur IDA-Headless-Executable |
| `DIAPHORA_DIR` | Verzeichnis, das die Diaphora-Skripte enthält |
| `DIAPHORA_OUTPUT_ROOT` | Vorhandenes erlaubtes Stammverzeichnis für neue Exporte und Diff-Ergebnisse |
| `DIAPHORA_PYTHON` | Optionaler Diff-Interpreter; standardmäßig der Interpreter des MCP-Servers |
| `DIAPHORA_ENABLE_LEGACY_TOOLS` | Genau `1` aktiviert die vorherige 21-Tool-Oberfläche |

Legacy-Matching, Feature-Scores, Security-Triage, Berichte, Metadaten und Diagnosen bleiben opt-in. Um sie zu aktivieren, füge den folgenden Eintrag zum `env`-Objekt der Konfiguration hinzu und starte neu:

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

Diese Tools verwenden Heuristiken; ihre Scores beweisen keine semantische Äquivalenz, Sicherheitsfixes oder Kausalität. [Konfiguration](https://github.com/xteardx/diaphora-mcp/blob/master/docs/CONFIGURATION.md) · [GUI-Einrichtung](https://github.com/xteardx/diaphora-mcp/blob/master/GUI_INSTRUCTIONS.md).

## Fehlerbehebung

| Symptom | Aktion |
| --- | --- |
| Ziel existiert bereits | Verwende ein frisches Ausführungsverzeichnis oder einen anderen Ausgabedateinamen |
| Ausgabe außerhalb des erlaubten Stammverzeichnisses | Wähle ein Ziel unter `DIAPHORA_OUTPUT_ROOT`; erstelle zuerst das Stammverzeichnis |
| IDA-Datenbank an ein Ergebnis-Tool übergeben | Verwende zurückgegebene `.diaphora.sqlite`-Exporte oder `.diaphora`-Ergebnisse, je nach Bedarf |
| Fehlendes/mehrdeutiges Gegenstück | Prüfe die Alt/Neu-Reihenfolge und das Mapping; untersuche den Kandidaten manuell |
| Leeres Assembly/Pseudocode | Prüfe das Exportprofil; erstelle einen neuen detaillierten Export |
| Export/Diff dauert lange | Erhöhe das Timeout des MCP-Clients; prüfe lokale `logs/`; erwäge einen ersten Durchlauf nur mit Zusammenfassungen |
| IDB durch eine IDA-Sitzung gesperrt | Schließe die Sitzung oder verwende den passenden GUI-Exportmodus für einen einzelnen Export |
| Nicht unterstütztes Schema | Exportiere erneut mit der unterstützten Diaphora-Version; siehe die gemeldeten fehlenden Tabellen/Spalten |

Matching bleibt heuristisch; ein hohes Verhältnis ist ein Hinweis, kein Beweis. Nicht zugeordnete Funktionen sind keine bestätigten Hinzufügungen/Löschungen. Halte Binärdateien, IDBs, Exporte und Logs aus Git heraus. Siehe [Workflows](https://github.com/xteardx/diaphora-mcp/blob/master/docs/WORKFLOWS.md), [Einschränkungen](https://github.com/xteardx/diaphora-mcp/blob/master/docs/LIMITATIONS.md) und [Sicherheit](https://github.com/xteardx/diaphora-mcp/blob/master/SECURITY.md).

## Entwicklung

```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
```

Die Regressionssuite verwendet synthetische Datenbanken und gemockte IDA-Prozesse. Der echte IDA-Export erfordert lokale Integrationsvalidierung. [Mitwirken](https://github.com/xteardx/diaphora-mcp/blob/master/CONTRIBUTING.md) · [Agent-Anweisungen](https://github.com/xteardx/diaphora-mcp/blob/master/AGENTS.md).