zboralski/ida-headless-mcp

# IDA Headless MCP Server 通过 Model Context Protocol 进行 Headless IDA Pro 二进制分析。Go 负责编排多会话并发，而 Python worker 负责 IDA 操作。 ## 架构 ``` ┌─────────────────┐ │ MCP Client │ Claude Desktop, Claude Code, CLI │ (HTTP/SSE) │ └────────┬────────┘ │ http://localhost:17300/ ▼ ┌─────────────────┐ │ Go Server │ Session registry, worker manager, watchdog │ (MCP Tools) │ └────────┬────────┘ │ Connect RPC over Unix socket ▼ ┌─────────────────┐ │ Python Worker │ IDA + idalib (one per session) │ (per session) │ └─────────────────┘ ``` **核心功能：** - 通过进程隔离实现多会话并发 - 52 个用于二进制分析的 MCP 工具 - 自动会话超时（默认 4 小时，可配置） - 支持配置限制的分页结果（默认 1000） - 为 Unity 游戏导入 [Il2CppDumper](https://github.com/Perfare/Il2CppDumper) 元数据 - 为 Flutter/Dart 应用导入 [unflutter](https://github.com/zboralski/unflutter) 元数据 ## 常量 这些值是由 [`wit`](https://github.com/zboralski/wit) 从 `internal/server/server.go` 中提取的；如果 README 与源代码产生偏差，`wit check README.md` 将会报错。 | 常量 | 值 | |----------|-------| | 默认端口 | 17300 | | 会话超时（分钟） | 240 | | 默认分页限制 | 1000 | ## 前置条件 1. **IDA Pro 9.0+ 或 IDA Essential 9.2+**，安装在 `/Applications` 下。构建过程会自动发现最新版本的 IDA，或者您可以将 `IDA_INSTALL_DIR` 指向其 `Contents/MacOS` 目录。 2. **Go 1.21+**。C++ worker 通过 cgo 链接 IDA headless；所需的 SDK 头文件已包含在 `third_party/ida-include` 中，因此无需单独检出 SDK。 可选：用于 Unity 游戏的 [Il2CppDumper](https://github.com/Perfare/Il2CppDumper)，以及用于 Flutter/Dart 应用的 [unflutter](https://github.com/zboralski/unflutter)。 ## 构建 构建由 [magefile](https://magefile.org) 驱动。有两种运行方式： ``` # 安装 mage 后： go install github.com/magefile/mage@latest mage all # build the server and the ida-worker # Zero-install（无需 mage binary）： go run mage.go all ``` 目标：`all`、`build`、`worker`、`run`、`restart`、`test`、`clean` （使用 `go run mage.go -l` 列出它们）。 ## 使用说明 ### 启动服务器 ``` ./bin/ida-mcp-server ``` 服务器在端口 17300 上运行（可通过 `config.json`、环境变量或 `--port` 配置），同时提供两种传输方式： - Streamable HTTP（推荐）：`http://localhost:17300/` - SSE 兼容端点：`http://localhost:17300/sse` ### 配置 Claude Desktop ``` { "mcpServers": { "ida-headless": { "url": "http://127.0.0.1:17300/", "type": "http" } } } ``` 编辑后请重启 Claude Desktop。 ### 配置 Claude Code 将 `.claude/settings.json` 复制到 `~/.claude/settings.json` 以授予对所有 IDA MCP 工具的访问权限。 ### 基本工作流 ``` 1. open_binary(path="/path/to/binary.so") → {"session_id": "abc123"} 2. run_auto_analysis(session_id="abc123") → {"completed": true} 3. get_entry_point(session_id="abc123") → {"address": 4198400} 4. get_decompiled_func(session_id="abc123", address=4198400) → {pseudocode...} 5. get_functions(session_id="abc123") → {"functions": [...], "count": 1523} 6. close_binary(session_id="abc123") → {"success": true} ``` ### Flutter/Dart 导入 ``` 1. Run unflutter on the target: unflutter meta libapp.so 2. open_binary(path="libapp.so") 3. import_flutter(session_id="...", meta_json_path="flutter_meta.json") → {"functions_created": 9926, "structs_created": 2090, "signatures_applied": 9926, "comments_set": 34172} 4. run_auto_analysis(session_id="...") ``` 通过 MCP 使用 `tools/list` 查看所有可用工具。 ## 配置 命令行参数： ``` ./bin/ida-mcp-server \ --port 17300 \ --max-sessions 10 \ --session-timeout 4h \ --worker python/worker/server.py \ --debug ``` 环境变量（会被 CLI 参数覆盖）： ``` IDA_MCP_PORT=17300 IDA_MCP_SESSION_TIMEOUT_MIN=240 IDA_MCP_MAX_SESSIONS=10 IDA_MCP_WORKER=/custom/worker.py IDA_MCP_DEBUG=1 ``` ## 开发 ### 构建与测试 ``` mage build # build the server (go run mage.go build without mage installed) mage worker # build the per-session ida-worker mage all # both mage test # go tests + wit check (README constants match the code) mage restart # kill, rebuild, restart server mage clean # remove binaries and the rpath symlink ``` `mage test` 会对本 README 运行 [`wit`](https://github.com/zboralski/wit)，因此 [常量](#constants) 中提取的值不会与 `internal/server/server.go` 产生偏差。 ### 项目结构 ``` ida-headless-mcp/ ├── cmd/ida-mcp-server/ # Go MCP server entry point ├── internal/ │ ├── server/ # MCP tool handlers │ ├── session/ # Session registry │ └── worker/ # Worker process manager ├── proto/ # Protobuf definitions ├── python/worker/ # Python worker (idalib wrapper) ├── contrib/il2cpp/ # Il2CppDumper helpers (MIT) └── tests/ # Test suites ``` ### 添加新工具 1. 将 RPC 添加到 `proto/ida/worker/v1/ida_service.proto` 2. 重新生成：`make proto` 3. 在 `python/worker/ida_wrapper.py` 中实现 4. 在 `python/worker/connect_server.py` 中添加处理程序 5. 在 `internal/server/server.go` 中注册 MCP 工具 ## 会话生命周期 1. 客户端调用 `open_binary(path)` 2. Go 在注册表中创建会话 (UUID) 3. Go 生成 Python worker 子进程 4. Worker 在 `/tmp/ida-worker-{id}.sock` 创建 Unix socket 5. Worker 使用 idalib 打开 IDA 数据库 6. Go 通过 socket 创建 Connect RPC 客户端 7. 后续工具调用通过 Connect 代理到 worker 8. Watchdog 监控空闲时间（默认：4 小时） 9. 超时或调用 `close_binary` 时：保存数据库，终止 worker，清理环境 10. 会话元数据持久化存储在 `/sessions` 下，以便在服务器重启后自动恢复 ## 故障排除 **Worker 启动失败：** ``` python3 -c "import idapro; print('OK')" ``` 如果失败，请运行 `./scripts/setup_idalib.sh` **Socket 超时：** 检查 Python worker 日志。Worker 可能在初始化期间崩溃。 **端口已被占用：** ``` lsof -ti:17300 | xargs kill # 或使用不同的 port ./bin/ida-mcp-server --port 17301 ``` **找不到会话：** 会话可能已超时。使用 `list_sessions` 检查活动会话。 ## 许可证 MIT ## 相关项目 **MCP Server：** - [LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP) - [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) - [cnitlrt/headless-ida-mcp-server](https://github.com/cnitlrt/headless-ida-mcp-server) **元数据提取器：** - [Perfare/Il2CppDumper](https://github.com/Perfare/Il2CppDumper)（由 `import_il2cpp` 使用） - [zboralski/unflutter](https://github.com/zboralski/unflutter)（由 `import_flutter` 使用） ## 参考 - [MCP 规范](https://spec.modelcontextprotocol.io/) - [Connect RPC](https://connectrpc.com/) - [IDA Pro idalib](https://hex-rays.com/products/ida/support/idapython_docs/)

标签：EVTX分析, 日志审计, 逆向工具