xTeardx/diaphora-mcp

[阅读俄语版本](README.ru.md) # Diaphora MCP **Diaphora MCP** 是一个用于自动化 binary diffing 的 MCP (Model Context Protocol) 服务器。它通过 MCP 协议连接 [Diaphora](https://github.com/joxeankoret/diaphora)（diffing 引擎）和 IDA Pro（反汇编器），允许 AI agents（如 Claude Code）执行二进制文件比较、寻找安全补丁以及分析更改。 ## 功能 - **导出**：将分析过的 `.i64` / `.idb` 数据库转换为 Diaphora SQLite 格式（通过 `idat.exe` headless 模式） - **Diffing**：比较两个导出的数据库，按匹配类型和比率过滤结果 - **漏洞分析**：使用关键字匹配和启发式方法搜索与安全相关的更改 - **补丁检测**：自动检测新的边界检查、空检查、错误处理和加密更改 - **排名**：基于 CFG、复杂度跳变和安全指标，根据重要性对更改的函数进行排名 - **Call Graph**：比较调用路径（BFS，最多 N 层），并检测调用级联中的根本原因更改 - **元数据传输**：准备名称、注释和原型，以便在数据库之间传输 - **IDA Pro MCP 集成**：所有工具返回的地址和数据库路径均可直接传递给 IDA Pro MCP 工具 ## 安装说明 ### 1. 依赖项 - Python 3.10+ - [IDA Pro](https://hex-rays.com/IDA-pro/) 8.x / 9.x（用于通过 `idat.exe` 进行 headless 导出） - 安装在 IDA 中的 [Diaphora](https://github.com/joxeankoret/diaphora) 插件 - [Claude Code](https://claude.ai/code)（或任何其他兼容 MCP 的客户端） ### 2. 安装包 ``` git clone https://github.com/xTeardx/diaphora-mcp.git cd diaphora-mcp pip install -e . ``` ### 3. 路径配置 该包会尝试在标准安装位置**自动查找** IDA Pro 和 Diaphora。如果未找到，您可以设置以下环境变量： | 变量 | 描述 | 示例 | |-----------|-------------|---------| | `IDAT_PATH` | idat.exe 的完整路径 | `C:\Program Files\IDA Pro 9.3\idat.exe` | | `DIAPHORA_DIR` | 包含 diaphora.py 的文件夹 | `C:\Program Files\IDA Pro 9.3\plugins\diaphora-3.4.1` | | `DIAPHORA_PYTHON` | 用于 diff 的 Python 解释器 | `/usr/bin/python3`（默认为 sys.executable） | 对于 Claude Code，您可以在 `~/.claude.json`（或您的 MCP 客户端对应的配置文件）中指定它们： ``` { "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 } } } ``` ### 4. 准备进行 Diffing 的数据库 IDA Pro 必须首先分析二进制文件（创建 `.i64` 或 `.idb` 文件）。之后： ``` ┃ export_idb_to_diaphora(idb_path="old_version.i64") ┃ export_idb_to_diaphora(idb_path="new_version.i64") ``` 或者在一个命令中运行整个 pipeline： ``` ┃ batch_export_and_diff(idb1="old.i64", idb2="new.i64") ``` ## 快速开始 ``` ┃ # 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") ``` ## 示例（实时会话记录） 请参阅 **[examples/basic-session.md](examples/basic-session.md)**，获取一个完整的 Diaphora MCP 实际会话的分步记录——从导出两个 IDB 数据库到比较单个函数。还提供 [俄语](examples/basic-session.ru.md) 版本。 以下是服务器返回内容的预览： **输入——比较两个 SQLite3 DLL（2015 对 2023）：** ``` {"idb1_path": "old.i64", "idb2_path": "new.i64", "use_decompiler": false} ``` **输出——导出 + diff 后的摘要：** ``` { "best_matches": 60, "partial_matches": 993, "multimatches": 52, "unmatched_primary": 2647 } ``` 该会话演示了 6 次 MCP 工具调用，展示了每一步的确切 JSON 输入/输出，并附带了 agent 的推理过程。 ### 调查单个数据库 ``` ┃ # 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") ``` ## 项目结构 ``` 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 工具参考（20 个工具） ### 导出 | 工具 | 描述 | |------|-------------| | `export_idb_to_diaphora` | 使用 IDA headless 将 `.i64`/`.idb` 数据库导出为 SQLite 格式 | | `batch_export_and_diff` | 完整 pipeline：导出主数据库 → 导出次数据库 → diff → 摘要 | ### Diff | 工具 | 描述 | |------|-------------| | `diff_diaphora_dbs` | 对两个导出的 Diaphora SQLite 数据库进行 diff | | `get_diff_results` | 读取带有过滤功能的 `.diaphora` diff 文件 | | `get_diff_summary` | 返回匹配统计信息 | ### 分析 | 工具 | 描述 | |------|-------------| | `analyze_diff_results` | 使用安全关键字和过滤器筛选结果 | | `compare_functions` | 对两个数据库中的函数进行并排比较 | | `find_function_match` | 在第二个二进制文件中匹配函数，并提供置信度指标 | | `explain_similarity` | 分解相似度因素（助记符、CFG、常量、原型、哈希） | | `detect_behavior_change` | 提供对函数逻辑更改的自然语言摘要 | | `summarize_patch` | 生成全面的更新报告 | | `search_export_db` | 按名称/指令/复杂度查询导出的函数 | | `get_function_pseudocode` | 获取函数的伪代码和元数据 | | `get_export_info` | 检索常规数据库元数据 | ### 安全 | 工具 | 描述 | |------|-------------| | `detect_security_patches` | 检测可能的安全修复（边界检查、内存安全、反调试等） | ### 排名 | 工具 | 描述 | |------|-------------| | `rank_changes` | 按重要性对更改的函数进行排名（0-100 分） | ### Callgraph | 工具 | 描述 | |------|-------------| | `get_changed_callgraph` | 比较函数的传入和传出调用 | | `compare_call_path` | 从某个函数遍历 callgraph（BFS 调用路径比较，最多 N 层） | | `find_patch_root` | 检测导致调用级联的根本原因函数 | ### 元数据 | 工具 | 描述 | |------|-------------| | `transfer_metadata` | 准备名称、注释和原型以便批量传输 | ## IDA Pro GUI 集成（XML-RPC 桥接） 该项目内置了与正在运行的 GUI IDA Pro 会话的集成，能够直接从活动的 IDA 窗口进行即时导出，而不会产生数据库锁定冲突。 1. **自动启动**：将 [diaphora_gui_listener.py](diaphora_gui_listener.py) 复制到您的 IDA Pro `plugins/` 目录。每当 IDA 启动时，它都会在端口 `28652` 上启动一个后台 XML-RPC 服务器。 2. **智能导出**：当调用 `export_idb_to_diaphora` 时，MCP 服务器会检查端口 `28652`。如果有活动的会话，它会直接在 GUI 中运行导出。否则，它会自动回退到通过 `idat.exe` 进行 headless 后台执行。 有关配置桥接的详细说明，请参阅 [GUI_INSTRUCTIONS.md](GUI_INSTRUCTIONS.md)。 ## 处理超大型数据库（10万+ 函数） 在处理极其庞大的项目时，Diaphora MCP 会应用特定的优化： - **递归限制**：Python 递归限制会自动提升至 `100000`（`sys.setrecursionlimit`），以防止在大型 callgraph 遍历期间发生崩溃。 - **SQLite 事务优化**：在您的 `diaphora_config.py` 中，设置 `COMMIT_AFTER_EACH_GUI_UPDATE = False` 可以减少磁盘写入，从而将 GUI 导出速度提高 2 到 3 倍。 - **Hex-Rays Microcode**：当不严格要求使用反编译器时，禁用微代码导出（在 Diaphora 配置中设置 `EXPORTING_USE_MICROCODE = False`）可获得更快的导出速度。 ## IDA Pro MCP 集成 像 `analyze_diff_results`、`compare_functions` 和 `find_function_match` 这样的工具会返回一个包含地址和路径的 `ida_pro_mcp` 块。此信息可以直接传递给 `ida-pro-mcp` 工具： ``` ┃ # 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") ``` ## 示例 要查看 Diaphora MCP 的实际运行情况，请查看以下示例： - [基本会话记录](examples/basic-session.md)：一个实际的 MCP 会话演练，包含了每次工具调用确切的 JSON 输入/输出——从导出到函数比较。还提供 [俄语](examples/basic-session.ru.md) 版本。 ## AI Agent 指南（重要） 如果您是使用此协议的 AI 编码助手（如 Claude Code），请牢记以下兼容性规则： 1. **GUI 与 Headless 导出 Schema**： - 通过活动的 GUI 会话（`ida_mcp.py` 插件）导出会生成一个自定义 schema，其中包含 `calls`、`strings`、`structures` 等表，但**没有 `program` 表**。 - Headless 导出（通过 `idat.exe`）会生成包含 `program` 表的官方 Diaphora schema。 - **关键**：diff 引擎（`diff_diaphora_dbs`）需要官方 schema。**如果您打算比较/diff 数据库，请务必使用 headless 导出**。 2. **GUI 中锁定的数据库**： - 当前在 GUI IDA Pro 中打开的数据库是被锁定的。尝试对其进行 headless 导出将会失败。 - 如果您需要对当前打开的数据库进行 diff，请要求用户在 GUI 中将其关闭（或打开一个虚拟数据库）以释放文件锁定，然后再触发 headless 导出。 3. **避免数据库名称冲突**： - Diaphora 导出的数据库默认为 `.diaphora.sqlite`。 - 切勿将 `.sqlite` 用于 Diaphora 导出，因为这会与 `ida-pro-mcp` 监督程序创建的内部缓存数据库发生冲突。 ## 许可证 MIT

标签：IDA Pro, MCP, 二进制比对, 云资产清单, 漏洞分析, 网络调试, 自动化, 路径探测, 逆向工具, 逆向工程