ph4ntom IDA Bridge 🌉

面向 IDA Pro 9.x 的自主 AI 与 MCP 控制层
将 IDA Pro 打造成智能体驱动的逆向工程利器。通过模型上下文协议（MCP）或高性能 REST API 连接 Claude Desktop、Cursor、Antigravity 或自定义 LLM 智能体。

---

              ┌─────────────────────────────────────────────────────────┐
              │                       IDA Pro 9.x                       │
              │         ph4ntom_ida_bridge.py (102 REST Endpoints)      │
              │         127.0.0.1:13370 (Bearer Token Protected)        │
              └────────────────────────────┬────────────────────────────┘
                                           │ REST / JSON / SSE
          ┌────────────────────────────────┼───────────────────────────────┐
          ▼                                ▼                               ▼
   ┌───────────────┐               ┌───────────────┐               ┌───────────────┐
   │  MCP Server   │               │   CLI / SDK   │               │   AI Agents   │
   │  54 Tools     │               │  `ph4ntom-ida`│               │  Multi-LLM    │
   │  Claude       │               │  Automation   │               │  Gemini       │
   │  Cursor       │               │  Headless     │               │  Ollama       │
   │  Antigravity  │               │  Testing      │               │  Claude / GPT │
   └───────────────┘               └───────────────┘               └───────────────┘

ph4ntom IDA Bridge 是 IDA Pro 9.x 的仅限 localhost 的控制层。它集成了自包含的 IDA 插件、JSON REST API、Python 客户端、CLI、54 个原生 MCP 工具以及可选的独立 AI 后端。

版本 6.2.0 带来了对 IDA 9.3 的完全兼容、原子化数据库变更、恒定时间令牌认证、SSE 游标跟踪以及完整的测试套件覆盖。

---

⚡ 快速开始：Claude Desktop 与 Cursor（一键 MCP 配置）

在 60 秒内将 Claude Desktop、Cursor 或任何 MCP 客户端连接到正在运行的 IDA Pro 实例：

1. 克隆并安装

git clone https://github.com/ph4ntom-rev/ph4ntom-ida-bridge.git
cd ph4ntom-ida-bridge
python -m pip install -e ".[mcp]"

2. 将插件安装到 IDA Pro 中

python cli.py install-plugin --ida-dir "C:\Program Files\IDA Professional 9.0"

（或将 ida_plugin/ph4ntom_ida_bridge.py 和 api_schema.json 直接复制到你的 IDA plugins/ 目录中）。

3. 添加到你的 MCP 配置

🟣 Claude Desktop

编辑 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "ida-bridge": {
      "command": "python",
      "args": [
        "C:/path/to/ph4ntom-ida-bridge/mcp_server.py"
      ]
    }
  }
}

💻 Cursor / Windsurf

添加到 .cursor/mcp.json 或 Cursor 设置 → MCP：

{
  "mcpServers": {
    "ida-bridge": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "C:/path/to/ph4ntom-ida-bridge"
    }
  }
}

启动 IDA Pro，按 Ctrl+Shift+A 切换服务器，然后向你的 AI 助手发出提示：

“检查位于 0x140001000 的函数。追踪交叉引用，分析微码，反编译为 C 伪代码，并将混淆的变量重命名为有意义的名称。”

---

⚔️ 与替代方案的比较

功能	ph4ntom IDA Bridge	Gepetto / IDAGPT	Hex-Rays Copilot
架构	双向 MCP + REST + CLI	单一提示包装器	专有 UI 插件
工具数量	54 个细粒度 MCP 工具	1（反编译提示）	固定提示操作
AST 与控制流	完整 ctree AST + 微码 IR（0-7）	仅伪代码文本	仅伪代码文本
安全变更	支持回滚的原子批量变更	仅插入注释	UI 中的建议
实时调试器	寄存器、堆栈、内存、断点	无	无
动态执行	即时 IDAPython 执行引擎	无	无
支持的 LLM	任意 MCP 客户端 / Claude / GPT / Gemini / Ollama	仅 OpenAI API	专有云
安全与认证	仅限 localhost、256 位令牌、所有者 DACL	暴露明文 API 密钥	专有
IDA Pro 9.3 支持	已验证并全面测试	在 IDA 9+ 上失效	官方

---

🛠️ MCP 工具参考（54 个工具与 2 个资源）

MCP 服务器在 7 个逆向工程领域提供 54 个专用工具：

类别	工具	描述
🔍 二进制与段	ping、get_binary_info、list_segments、read_bytes、read_vtable	二进制元数据、位数、权限、vtable 提取
🧩 反编译与 AST	decompile、get_disassembly、get_ctree、get_microcode、get_local_variables、get_function_details	Hex-Rays C 伪代码、AST ctree JSON、微码 IR（0=PREOPT 至 7=LVARS）、原型信息
🕸️ 调用图与交叉引用	get_xrefs_to、get_xrefs_from、get_callers、get_callees、get_call_graph、get_basic_blocks、get_strings_used	交叉引用、递归调用者树、基本块控制流
🔎 搜索与探索	search_function、search_bytes、search_text、list_strings、list_names、list_imports、list_exports	通配符字节搜索（??）、导入的 DLL 函数、导出、字符串过滤
🏷️ 类型与结构体	list_structs、get_struct、list_enums、list_types、get_type、create_type、create_struct	C 声明解析、结构体定义、枚举成员检查
✏️ 数据库变更	rename_function、comment_function、set_inline_comment、rename_variable、set_variable_type、set_function_type、patch_bytes、batch_mutations、undo、redo、save_database、navigate_to	经验证的重命名、局部变量类型设置、二进制修补、原子回滚
🐞 实时调试器	dbg_start、dbg_set_breakpoint、dbg_continue、dbg_step_into、dbg_step_over、dbg_get_registers、dbg_read_memory、dbg_get_stack	进程执行控制、硬件断点、实时寄存器与内存转储
⚡ 动态 IDAPython	execute_idapython	实时执行 IDAPython 并捕获结构化 result
📦 MCP 资源	ida://info、ida://schema	实时二进制元数据与完整 OpenAPI 架构

---

🔒 安全模型

该桥接运行在 IDA Pro 内部，赋予强大的能力。版本 6 实现了纵深防御默认设置：

• 仅绑定回环地址：严格绑定到 127.0.0.1:13370。
• 加密会话令牌：256 位令牌存储在 ~/.ph4ntom_ida_bridge_token 中。
• 仅所有者 DACL：在 Windows 上，令牌文件在写入前会以仅所有者可访问的受保护权限进行保护。
• 恒定时间授权：防止令牌验证期间的时序侧信道攻击。
• POST 请求体限制：上限为 5 MiB，并严格校验 UTF-8 JSON 对象。
• CORS 限制：浏览器 CORS 仅允许来自 localhost 源。
• 默认禁用动态 IDAPython：执行需要显式设置 IDA_BRIDGE_ALLOW_EXEC=1。
• 头文件导入受限：POST /api/import-header 需要预先配置受信任的根路径。

[!CAUTION] 切勿通过公共接口、隧道或反向代理暴露端口 13370。完整加固指南请参阅 SECURITY.md。

---

📦 组件

路径	用途
ida_plugin/ph4ntom_ida_bridge.py	标准 IDA 插件和 REST 服务器（102 个端点）
api_schema.json	机器可读的 REST 参考和 OpenAPI 模式
core/client.py	共享的带令牌刷新的认证 HTTP 客户端
cli.py	CLI、插件安装器、doctor 和 IDA 启动器
mcp_server.py	暴露 54 个工具和两个资源的 FastMCP 服务器
agent.py	具有 5 个可互换 LLM 后端的交互式终端代理
swarm_worker.py	结构化批量分析工作器
agent_config.json	面向 IDE 代理的机器可读集成规范
AGENT_SKILL.md	面向 Antigravity 和基于 IDE 的代理的技能定义

---

💻 CLI 快速开始

随附的 CLI 可从任何终端即时控制你的 IDA 会话：

# Health & info
ph4ntom-ida ping
ph4ntom-ida info

# Functions & strings
python cli.py functions --limit 50
python cli.py strings --filter "socket|http|connect"

# Decompilation & Cross-references
python cli.py decompile 0x140001000
python cli.py xrefs 0x140001000
python cli.py callers 0x140001000

# Direct API queries
python cli.py api GET /api/function/0x140001000/ctree
python cli.py api POST /api/function/0x140001000/rename --body '{"name":"decrypt_payload"}'

# Launch IDA with bridge autostart
python cli.py launch malware_sample.bin --wait

⚡ 可选的动态 IDAPython 执行

动态执行默认处于关闭状态。仅在可信环境中启用：

PowerShell：

$env:IDA_BRIDGE_ALLOW_EXEC = "1"

Bash：

export IDA_BRIDGE_ALLOW_EXEC=1

以内联方式、从文件或通过 stdin 管道执行脚本：

python cli.py exec "result['ea'] = hex(idc.here())"
python cli.py exec --file custom_scan.py
cat analyze.py | python cli.py exec -

脚本可完整访问 IDAPython SDK（idc、idaapi、idautils、ida_hexrays 等），并可使用一个以 JSON 形式返回的全局 result 字典。

---