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

Diaphora MCP

Diaphora MCP ist ein MCP-Server (Model Context Protocol) für automatisierte Binärdiff-Analysen. Er verbindet Diaphora (die Diffing-Engine) und IDA Pro (den Disassembler) über das MCP-Protokoll, sodass KI-Agenten (wie Claude Code) Binärdateien vergleichen, Sicherheitspatches finden und Änderungen analysieren können.

Funktionen

• Export: Konvertiert analysierte .i64/.idb-Datenbanken in das Diaphora-SQLite-Format (über den headless-Modus von idat.exe)
• Diffing: Vergleicht zwei exportierte Datenbanken und filtert Ergebnisse nach Übereinstimmungstyp und -verhältnis
• Sicherheitsanalyse: Sucht nach sicherheitsrelevanten Änderungen mittels Stichwortsuche und Heuristiken
• Patcherkennung: Erkennt automatisch neue Grenzwertprüfungen, Nullprüfungen, Fehlerbehandlungen und kryptografische Änderungen
• Ranking: Bewertet geänderte Funktionen nach Wichtigkeit basierend auf CFG, Komplexitätssprüngen und Sicherheitsindikatoren
• Callgraph: Vergleicht Aufrufpfade (BFS, bis zu N Ebenen) und erkennt Grundursachenänderungen in Aufrufkaskaden
• Metadaten-Transfer: Bereitet Namen, Kommentare und Prototypen für den Transfer zwischen Datenbanken vor
• IDA Pro MCP-Integration: Alle Werkzeuge geben Adressen und Datenbankpfade zurück, die direkt an IDA Pro MCP-Werkzeuge übergeben werden können

Installation

1. Abhängigkeiten

• Python 3.10+
• IDA Pro 8.x / 9.x (für headless-Exporte via idat.exe)
• Diaphora-Plugin installiert in IDA
• Claude Code (oder ein anderer MCP-konformer Client)

2. Paketinstallation

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

3. Pfadkonfiguration

Das Paket versucht, IDA Pro und Diaphora automatisch an Standardinstallationsorten zu finden. Falls nicht gefunden, können die folgenden Umgebungsvariablen gesetzt werden:

Für Claude Code können diese in ~/.claude.json (oder der entsprechenden Konfigurationsdatei Ihres MCP-Clients) angegeben werden:

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

Hinweis: Für sehr große Binärdateien (>100 MB) sollte timeout mindestens 7200 (2 Stunden) betragen.

3.1. Codex und headless IDA MCP

Codex verwendet typischerweise zwei komplementäre MCP-Server:

• diaphora-mcp – dieses Projekt: Export, Diaphora-Diff und Ergebnisanalyse;
• ida-pro-mcp – der vorgelagerte IDA-Inspectionsserver für idb_open, Dekompilierung und Adressanalyse.

idalib-mcp ist das headless-Backend von ida-pro-mcp, kein separater Diaphora-Server. Nach der Installation Codex neu starten:

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

Für dieses Projekt genügt eine stdio-Konfiguration:

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

4. Vorbereiten der Datenbanken für den Diff

IDA Pro muss die Binärdateien zuerst analysieren (Erstellung von .i64- oder .idb-Dateien). Danach:

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

Oder die gesamte Pipeline in einem Befehl ausführen:

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

.i64 nicht direkt an Ergebniswerkzeuge übergeben: Es ist eine IDA-Datenbank, kein SQLite. Zuerst exportieren.

Schnellstart

┃ # 1. Vollständige Pipeline: zwei .i64 exportieren → diff → zusammenfassender Bericht
┃ batch_export_and_diff(idb1="v1.0.i64", idb2="v1.1.i64")
 
┃ # 2. Wenn Datenbanken bereits exportiert sind
┃ diff_diaphora_dbs(db1="v1.0.sqlite", db2="v1.1.sqlite")
 
┃ # 3. Sicherheitsanalyse der Diff-Ergebnisse
┃ analyze_diff_results(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 4. Wichtigkeitsranking der Änderungen
┃ rank_changes(results_path="v1.0_vs_v1.1.diaphora", top_n=20)
 
┃ # 5. Grundursache von Änderungen finden
┃ find_patch_root(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 6. Wahrscheinliche Sicherheitspatches erkennen
┃ detect_security_patches(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 7. Vollständigen Bericht generieren
┃ summarize_patch(results_path="v1.0_vs_v1.1.diaphora")

Beispiel (Live-Sitzungstranskript)

Siehe examples/basic-session.md für ein vollständiges Schritt-für-Schritt-Transkript einer echten Diaphora-MCP-Sitzung – vom Export zweier IDB-Datenbanken bis zum Vergleich einzelner Funktionen. Auch auf Russisch verfügbar.

Hier ein Vorgeschmack auf das, was der Server zurückgibt:

Eingabe – Vergleich zweier SQLite3-DLLs (2015 vs. 2023):

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

Ausgabe – Zusammenfassung nach Export + Diff:

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

Die Sitzung durchläuft 6 MCP-Toolaufrufe, zeigt das exakte JSON-Eingabe-/Ausgabepaar für jeden Schritt und die Überlegungen des Agenten.

Untersuchen einer einzelnen Datenbank

┃ # Datenbank-Exportinfo abrufen
┃ get_export_info(db_path="app.sqlite")
 
┃ # Nach Funktionen suchen
┃ search_export_db(db_path="app.sqlite", name_pattern="%crypt%", min_instructions=50)
 
┃ # Pseudocode abrufen
┃ get_function_pseudocode(db_path="app.sqlite", address="401000")

Projektstruktur

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)

MCP-Tool-Referenz (21 Tools)

Export

Diff

Analyse

Sicherheit

Ranking

Callgraph

Leistung

Metadaten

IDA Pro GUI-Integration (XML-RPC-Bridge)

Das Projekt enthält eine integrierte Integration mit laufenden IDA Pro GUI-Sitzungen, die sofortige Exporte direkt aus aktiven IDA-Fenstern ermöglicht, ohne Datenbanksperrkonflikte.

1. Autostart: Kopieren Sie diaphora_gui_listener.py in Ihr IDA plugins/-Verzeichnis. Es startet einen Hintergrund-XML-RPC-Server auf Port 28652, sobald IDA startet.
2. Intelligenter Export: Beim Aufruf von export_idb_to_diaphora prüft der MCP-Server Port 28652. Wenn eine Sitzung aktiv ist, wird der Export direkt in der GUI ausgeführt. Andernfalls erfolgt ein automatischer Rückfall auf die headless-Hintergrundausführung via idat.exe.

Detaillierte Anweisungen zur Konfiguration der Bridge finden Sie in GUI_INSTRUCTIONS.md.

Umgang mit gigantischen Datenbanken (100k+ Funktionen)

Bei der Verarbeitung extrem großer Projekte wendet Diaphora MCP spezifische Optimierungen an:

• Rekursionsgrenze: Die Python-Rekursionsgrenze wird automatisch auf 100000 erhöht (sys.setrecursionlimit), um Abstürze während großer Callgraph-Durchläufe zu verhindern.
• SQLite-Transaktionsoptimierungen: Wenn Sie in Ihrer diaphora_config.py COMMIT_AFTER_EACH_GUI_UPDATE = False setzen, werden Datenträgerschreibvorgänge reduziert, was den GUI-Export um das 2- bis 3-fache beschleunigt.
• Hex-Rays-Microcode: Deaktivieren Sie den Microcode-Export (EXPORTING_USE_MICROCODE = False in der Diaphora-Konfiguration) für einen schnelleren Export, wenn der Dekompilierer nicht zwingend erforderlich ist.

IDA Pro MCP-Integration

Werkzeuge wie analyze_diff_results, compare_functions und find_function_match geben einen ida_pro_mcp-Block zurück, der Adressen und Pfade enthält. Diese Informationen können direkt an die ida-pro-mcp-Werkzeuge übergeben werden:

┃ # 1. Diaphora findet eine verdächtige Funktion
┃ analyze_diff_results(results_path="diff.diaphora")
┃   → addr1="401000", db1="old.sqlite"
 
┃ # 2. IDA Pro MCP dekompiliert sie
┃ decompile_function(address="401000")

Beispiele

Um Diaphora MCP in Aktion zu sehen, schauen Sie sich die folgenden Beispiele an:

• Basic Session Transcript: Ein echtes MCP-Sitzungs-Walkthrough mit exakten JSON-Eingaben/Ausgaben für jeden Tool-Aufruf – vom Export bis zum Funktionsvergleich. Auch auf Russisch verfügbar.

Richtlinien für KI-Agenten (Wichtig)

Wenn Sie ein KI-Code-Assistent (wie Claude Code) sind, der dieses Protokoll verwendet, beachten Sie die folgenden Kompatibilitätsregeln:

1. GUI vs. Headless-Export-Schemas:

   • Der Export über eine aktive GUI-Sitzung (ida_mcp.py-Plugin) erzeugt ein benutzerdefiniertes Schema mit Tabellen wie calls, strings, structures, aber keine program-Tabelle.
   • Der Headless-Export (via idat.exe) erzeugt das offizielle Diaphora-Schema mit der program-Tabelle.
   • Wichtig: Die Diff-Engine (diff_diaphora_dbs) erfordert das offizielle Schema. Exportieren Sie immer headless, wenn Sie Datenbanken vergleichen/diffen möchten.

2. Gesperrte Datenbanken in der GUI:

   • Eine aktuell in der GUI geöffnete Datenbank ist gesperrt. Der Versuch, sie headless zu exportieren, schlägt fehl.
   • Wenn Sie die aktuell geöffnete Datenbank diffen müssen, bitten Sie den Benutzer, sie in der GUI zu schließen (oder eine Dummy-Datenbank zu öffnen), um die Dateisperre freizugeben, und lösen Sie dann einen headless-Export aus.

3. Datenbank-Namenskollisionen vermeiden:

   • Diaphora-Exportdatenbanken heißen standardmäßig <basename>.diaphora.sqlite.
   • Verwenden Sie niemals <basename>.sqlite für Diaphora-Exporte, da dies mit der internen Cache-Datenbank des ida-pro-mcp-Supervisors kollidiert.

Verifikationsstatus und Einschränkungen

Die geprüften IDA Pro 9.3-Fixdurchläufe bestehen die Regressionstestsuite: 16 passed, 1 xpassed. Ein echter gestaffelter Export und Diaphora-Diff von zwei SQLite3-DLLs wurden ebenfalls verifiziert. Große oder in der GUI geöffnete IDBs erfordern weiterhin eine freie IDA-Sperre, ein gültiges DIAPHORA_OUTPUT_ROOT und ein ausreichend großes MCP-Client-Timeout.

Lizenz

MIT