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

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:

Variable	Description	Example
IDAT_PATH	Full path to idat.exe	C:\Program Files\IDA Pro 9.3\idat.exe
DIAPHORA_DIR	Folder containing diaphora.py	C:\Program Files\IDA Pro 9.3\plugins\diaphora-3.4.1
DIAPHORA_OUTPUT_ROOT	Root directory allowed for new export files	D:\\diaphora-outputs
DIAPHORA_PYTHON	Python interpreter for diff	/usr/bin/python3 (defaults to sys.executable)

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

Tool	Description
export_idb_to_diaphora	Exports .i64/.idb database to SQLite format using IDA headless
batch_export_and_diff	Full pipeline: export primary → export secondary → diff → summary

Diff

Tool	Description
diff_diaphora_dbs	Diffs two exported Diaphora SQLite databases
get_diff_results	Reads .diaphora diff file with filtering
get_diff_summary	Returns match statistics