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

Diaphora MCP

Diaphora MCP is an MCP (Model Context Protocol) server for automated binary diffing. It connects Diaphora (the diffing engine) and IDA Pro (the disassembler) via the MCP protocol, allowing AI agents (such as Claude Code) to perform binary file comparison, find security patches, and analyze changes.

Features

• Export: Converts analyzed .i64 / .idb databases to the Diaphora SQLite format (via idat.exe headless mode)
• Diffing: Compares two exported databases, filters results by match type and ratio
• Vulnerability Analysis: Searches for security-relevant changes using keyword matching and heuristics
• Patch Detection: Automatically detects new bounds checks, null checks, error handling, and cryptographic changes
• Ranking: Ranks changed functions by importance based on CFG, complexity jumps, and security indicators
• Call Graph: Compares call paths (BFS, up to N levels), and detects root-cause changes in call cascades
• Metadata Transfer: Prepares names, comments, and prototypes for transfer between databases
• IDA Pro MCP Integration: All tools return addresses and database paths ready to be passed directly to IDA Pro MCP tools

Installation

1. Dependencies

• Python 3.10+
• IDA Pro 8.x / 9.x (for headless exports via idat.exe)
• Diaphora plugin installed in IDA
• Claude Code (or any other MCP-compliant client)

2. Package Installation

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

3. Path Configuration

The package tries to automatically find IDA Pro and Diaphora in standard installation locations. If not found, you can set the following environment variables:

For Claude Code, you can specify them in ~/.claude.json (or the corresponding config file of your MCP client):

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

Note: For very large binaries (>100 MB), ensure timeout is at least 7200 (2 hours).

3.1. Codex and headless IDA MCP

Codex typically uses two complementary MCP servers:

• diaphora-mcp — this project: export, Diaphora diff, and result analysis;
• ida-pro-mcp — the upstream IDA inspection server for idb_open, decompilation, and address-level analysis.

idalib-mcp is the headless backend of ida-pro-mcp, not a separate Diaphora server. After installing it, restart Codex:

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

For this project, a stdio configuration is sufficient:

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

4. Preparing Databases for Diffing

IDA Pro must analyze the binaries first (creating .i64 or .idb files). After that:

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

Or run the full pipeline in one command:

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

Do not pass .i64 directly to results tools: it is an IDA database, not SQLite. Export it first.

Quick Start

┃ # 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")

Example (Live Session Transcript)

See examples/basic-session.md for a complete step-by-step transcript of a real Diaphora MCP session — from exporting two IDB databases to comparing individual functions. Also available in Russian.

Here's a sneak peek of what the server returns:

Input — compare two SQLite3 DLLs (2015 vs 2023):

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

Output — summary after export + diff:

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

The session walks through 6 MCP tool calls, showing the exact JSON in/out for each step, with the agent's reasoning alongside.

Investigating a Single 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")

Project Structure

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 Tools Reference (21 tools)

Export

Diff

Analysis

Security

Ranking

Callgraph

Performance

Metadata

IDA Pro GUI Integration (XML-RPC Bridge)

The project includes built-in integration with running GUI IDA Pro sessions, enabling instant exports directly from active IDA windows without database locking conflicts.

1. Auto-start: Copy diaphora_gui_listener.py to your IDA Pro plugins/ directory. It will start a background XML-RPC server on port 28652 whenever IDA starts.
2. Smart Export: When calling export_idb_to_diaphora, the MCP server checks port 28652. If a session is active, it runs the export directly in the GUI. Otherwise, it automatically falls back to headless background execution via idat.exe.

For detailed instructions on configuring the bridge, see GUI_INSTRUCTIONS.md.

Handling Gigantic Databases (100k+ functions)

When processing extremely large projects, Diaphora MCP applies specific optimizations:

• Recursion Limit: Python recursion limit is automatically raised to 100000 (sys.setrecursionlimit) to prevent crashes during large callgraph traversals.
• SQLite Transaction Optimizations: In your diaphora_config.py, setting COMMIT_AFTER_EACH_GUI_UPDATE = False reduces disk writes, speeding up GUI export 2x to 3x.
• Hex-Rays Microcode: Disable microcode export (EXPORTING_USE_MICROCODE = False in Diaphora config) for a faster export when decompiler is not strictly required.

IDA Pro MCP Integration

Tools like analyze_diff_results, compare_functions, and find_function_match return an ida_pro_mcp block containing addresses and paths. This information can be passed directly to the ida-pro-mcp tools:

┃ # 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")

Examples

To see Diaphora MCP in action, check out the following examples:

• Basic Session Transcript: A real MCP session walkthrough with exact JSON input/output for every tool call — from export to function comparison. Also available in Russian.

AI Agent Guidelines (Important)

If you are an AI coding assistant (like Claude Code) using this protocol, keep the following compatibility rules in mind:

1. GUI vs. Headless Export Schemas:

   • Exporting via an active GUI session (ida_mcp.py plugin) produces a custom schema containing tables like calls, strings, structures, but no program table.
   • Headless export (via idat.exe) produces the official Diaphora schema containing the program table.
   • Crucial: The diff engine (diff_diaphora_dbs) requires the official schema. Always export headlessly if you intend to compare/diff databases.

2. Locked Databases in GUI:

   • A database currently open in GUI IDA Pro is locked. Attempting to export it headlessly will fail.
   • If you need to diff the currently open database, ask the user to close it in the GUI (or open a dummy database) to release the file lock, then trigger a headless export.

3. Avoid Database Name Collisions:

   • Diaphora export databases default to <basename>.diaphora.sqlite.
   • Never use <basename>.sqlite for Diaphora exports, as this conflicts with the internal cache database created by the ida-pro-mcp supervisor.

Verification status and limitations

The checked IDA Pro 9.3 fixtures pass the regression suite: 16 passed, 1 xpassed. A real staged export and Diaphora diff of two SQLite3 DLLs were also verified. Large or GUI-open IDBs still require a free IDA lock, a valid DIAPHORA_OUTPUT_ROOT, and a sufficiently large MCP client timeout.

License

MIT