mitsuakki/reverse-mcp

# re-toolbox 用于逆向工程的一体化 Docker 容器 —— radare2 + Ghidra headless 作为 MCP server 接入，并包含 BinDiff、angr、AFL++、honggfuzz 以及 Android 工具 （apktool、jadx、frida）。可与 Claude Code、Claude Desktop、Cline、Continue， 或任何支持 StreamableHTTP 的 MCP client 配合使用。 仅限 Headless —— 无 GUI、无 VNC。一切操作均在终端中或通过 MCP 运行。 ## 环境要求 - Docker 23.0+（需要 BuildKit —— 23.0 起默认开启） - Docker Compose 2.0+（`docker compose`，而非 `docker-compose`） Docker 18.09–22.x 用户：在构建之前请导出 `DOCKER_BUILDKIT=1`。 ## 快速开始 ``` docker compose build docker compose up -d ``` 容器启动后，gateway 将监听 `localhost:3100`。将二进制文件放入 `./workspace` —— 它会被挂载到容器内的 `/workspace`。 ``` docker exec -it toolbox bash # optional — CLI access to all tools ``` ## MCP **单一 HTTP endpoint。** 将 [`.mcp.json`](.mcp.json) 中的 `toolbox` 条目复制到 你的 MCP client 配置中。gateway 在一个 URL 背后组合了所有的 toolbox MCP server —— 无需 Docker socket、无需 `docker exec`、无需逐个注册 server。 ``` { "mcpServers": { "toolbox": { "type": "http", "url": "http://localhost:3100/mcp" } } } ``` Claude Code 用户：项目的 `.mcp.json` 会自动进行配置。其他 client： | MCP client | 文件 | |---|---| | Claude Code | `.claude/mcp.json`（项目级）或 `~/.claude/mcp.json`（全局） | | Claude Desktop | `claude_desktop_config.json`（[文档](https://docs.anthropic.com/en/docs/claude-desktop)） | | Cline (VS Code) | `cline_mcp_settings.json` | | Continue | `~/.continue/config.json` | | Zed | `settings.json` → `{"context_servers": {...}}` | 编辑后请重启 client。gateway 作为后台服务在容器内运行 —— 始终保持可用，无冷启动。 ### 架构 ``` MCP client (Claude Code, Desktop, etc.) │ HTTP POST /mcp (StreamableHTTP) ▼ localhost:3100 ───────────────────────────────────────┐ │ │ │ docker compose port mapping │ ▼ │ ┌───────────────────────────────────────────────────┐ │ │ container: toolbox │ │ │ │ │ │ gateway.py --transport http :3100 │ │ │ ├─ r2pm -r r2mcp → r2__* │ │ │ ├─ bridge_mcp_ghidra.py :8089 → ghidra__* │ │ │ ├─ shell-mcp.py → shell__* │ │ │ └─ python3 -m angr.mcp → angr__* │ │ └───────────────────────────────────────────────────┘ │ ``` Gateway 在启动时启动所有子 MCP server。工具采用**命名空间隔离** （`r2__*`、`ghidra__*`、`shell__*`、`angr__*`） —— 绝不冲突。启动失败的子进程 会被记录，但不会阻塞 gateway；gateway 会基于已连接的部分继续降级运行。 ### Server 目录 | 命名空间 | Server | 提供的功能 | |---|---|---| | `r2__*` | 通过 `r2pm` 安装的 r2mcp | 反汇编、反编译（r2ghidra）、十六进制转储、交叉引用、符号、搜索、模拟 | | `ghidra__*` | bridge_mcp_ghidra.py → Ghidra headless :8089 | 项目管理、导入、自动分析、200+ 工具：反编译、patching、结构体/类型、调试器、Bindiff | | `shell__*` | shell-mcp.py | 任意 shell 命令 —— angr、AFL++、honggfuzz、apktool、jadx、gdb、gcc、python3 等 | | `angr__*` | angr.mcp（内置） | 二进制分析 —— 项目加载、CFG、符号执行、数据依赖、VFG | ### Ghidra 工具可用性 Ghidra 工具分为两大类： | 类别 | 何时可用 | 示例 | |---|---|---| | **静态** | 始终可用 —— 无需实例 | `import_file`、`list_instances`、`connect_instance`、`list_tool_groups`、`load_tool_group` | | **实例级** | 连接到已加载的程序后 | `decompile_function`、`list_functions`、`rename_function`、`xrefs_to`、`disassemble_function`、所有调试器工具 | 生命周期： ``` import_file ──→ auto-connect ──→ schema fetch ──→ all 200+ tools available │ └── or: connect_instance ──→ schema fetch ──→ all tools available ``` 使用 `check_tools` 查看当前可调用的工具： ``` ghidra__check_tools: "decompile_function,list_functions,import_file,bindiff" → import_file=callable, decompile_function=not_found (no instance yet) → import_file completes → all four = callable ``` 静态工具内置于 bridge 中。实例级工具会在连接后从头less server 的 `/mcp/schema` 动态获取。如果某个工具 显示为 `not_loaded`（存在但其所属组未加载），请使用类别名调用 `load_tool_group`。使用 `list_tool_groups` 查看所有类别及其加载状态。 ### Ghidra GUI（可选） 在宿主机上通过运行在 8080 端口的 GhidraMCP 插件运行 Ghidra GUI。在 `docker-compose.yml` 中设置 `GHIDRA_MCP_URL`，使 bridge 指向你的宿主机： ``` environment: - GHIDRA_MCP_URL=http://host.docker.internal:8080 ``` 重新构建后，gateway 的 ghidra bridge 将路由到你的 GUI 实例，而不是 headless server。 ## Agents `.claude/agents/` 内置了专用的 RE agent。任何克隆该 repo 的人都会 自动获取它们 —— Claude Code 会从项目的 `.claude/` 目录中加载 agent。 | Agent | 模型 | 功能 | |---|---|---| | `binary-triage` | haiku | 使用 radare2 + shell 对未知二进制文件进行快速初探 | | `ghidra-importer` | sonnet | 将二进制文件导入 Ghidra headless，运行自动分析 | | `ghidra-analyst` | sonnet | 静态 RE —— 反编译、交叉引用、重命名、注释 | | `ghidra-debugger` | sonnet | 动态分析 —— attach、断点、追踪、内存监控 | | `re-orchestrator` | opus | 完整 pipeline：初探 → 导入 → 静态 → 动态 → 报告 | ### 使用示例 ``` triage this binary: /workspace/suspicious.elf import /workspace/challenge.exe into Ghidra decompile the function at 0x401000 and trace its xrefs find all strings containing "http" in this binary trace every call to D2Common.ordinal:10624 with arguments full reverse engineering analysis on /workspace/malware.bin ``` ### 添加自定义 agent 将 `.md` 文件添加到 `.claude/agents/`。Frontmatter： ``` --- name: my-agent description: What it does model: haiku | sonnet | opus tools: [Read, Bash, mcp__toolbox__ghidra__*, mcp__toolbox__r2__*, mcp__toolbox__shell__exec] --- ``` `tools` 为可选项 —— 省略则从父会话继承所有工具。MCP 工具使用带有命名空间的名称：`mcp__toolbox____`。 ## CLI 工具 所有工具均可在容器内使用。通过以下命令进入 shell： ``` docker exec -it toolbox bash ``` ### radare2 ``` r2 -A /workspace/chall # open + analyze r2 -c "pdg @ main" /workspace/chall # decompile main via r2ghidra r2pm -r r2mcp -t # list MCP tools exposed by r2mcp ``` ### Ghidra headless 通过内置脚本进行**快速导入**： ``` /opt/tools/scripts/load-ghidra.sh /workspace/my-binary # auto-analyze /opt/tools/scripts/load-ghidra.sh /workspace/my-binary myproj # named project /opt/tools/scripts/load-ghidra.sh /workspace/my-binary --no-analyze ``` 检查 MCP server 健康状态，通过 `analyzeHeadless` 导入，并调用 `/load_program` 以便 bridge 识别该二进制文件。项目存放在 `/home/ctf/.config/ghidra`（通过 Docker volume `ghidra-projects` 持久化）。 使用 analyzeHeadless 进行**手动导入**： ### HTTP API (Ghidra headless) ``` curl http://localhost:8089/check_connection curl -X POST "http://localhost:8089/load_program" -d "file=/workspace/mybin" curl "http://localhost:8089/decompile_function?program=mybin&name=main" ``` ### BinDiff CLI 与 MCP。从 Ghidra 或 IDA 导出 `.BinExport`，然后进行比对： ``` bindiff old.BinExport new.BinExport ``` ghidra-headless MCP 暴露了 `bindiff` 和 `bindiff_export_from_ghidra` 工具， 用于直接从 Ghidra 项目进行比对。 ### angr + Python RE 技术栈 预装工具：angr、pwntools、ropper、ropgadget、capstone、unicorn、keystone、 z3、lief、r2pipe、frida-tools、objection。 ``` python3 -c " import angr p = angr.Project('/workspace/chall', auto_load_libs=False) cfg = p.analyses.CFGFast() print(f'{len(cfg.kb.functions)} functions, entry at {hex(p.entry)}') " ``` ### 模糊测试 AFL++ 和 honggfuzz 安装在 `/opt/tools/fuzzing/bin` 下（已加入 PATH）。 ``` # AFL++ mkdir -p fuzz-in && echo AAAA > fuzz-in/seed afl-fuzz -i fuzz-in -o fuzz-out -- /workspace/chall @@ # 黑盒 / 无源码：添加 -Q (QEMU mode) # honggfuzz mkdir -p hf-in && echo AAAA > hf-in/seed honggfuzz -i hf-in -o hf-out -- /workspace/chall ___FILE___ ``` ### Android RE ``` apktool d app.apk -o app_decoded jadx app.apk -d app_jadx_out adb devices frida -U -f com.example.app -l hook.js --no-pause objection -g com.example.app explore ``` ### 其他工具 `gdb`、`lldb`、`strace`、`ltrace`、`nasm`、`objdump`、`strings`、`patchelf`、 `gcc`、`clang` 和 `python3` 均已加入 PATH。 ## 项目结构 ``` . ├── .mcp.json MCP config — paste into your client (single HTTP entry) ├── CLAUDE.md Agent reference + quickstart for Claude Code ├── docker-compose.yml One-command start ├── docker/ │ └── Dockerfile Multi-stage build, pinned versions ├── scripts/ │ ├── entrypoint.sh Container entrypoint (starts Ghidra MCP + gateway HTTP) │ ├── load-ghidra.sh Import + load binary into Ghidra MCP from CLI │ └── mcp/ │ ├── gateway.py MCP gateway — composes all servers behind one HTTP endpoint │ └── shell-mcp.py Shell command MCP server ├── .claude/ │ ├── settings.json Auto-enables project MCP servers │ ├── settings.local.json Local overrides (git-ignored) │ └── agents/ Specialized RE agents (auto-loaded by Claude Code) │ ├── binary-triage.md Fast radare2 first-look │ ├── ghidra-importer.md Binary import + auto-analysis │ ├── ghidra-analyst.md Static RE deep-dive │ ├── ghidra-debugger.md Dynamic analysis / debugger │ └── re-orchestrator.md Full pipeline coordinator └── workspace/ Mounted at /workspace — put binaries here ``` ## 安全性 Compose 添加了 `SYS_PTRACE` 并禁用了 seccomp（`unconfined`） —— 这是 gdb、strace 和 AFL 必需的。在分析不受信任的二进制文件时，请在隔离的 VM 中运行 此容器。 MCP gateway 在容器内的 `0.0.0.0:3100` 上监听。只有你选择在 `docker-compose.yml` 中暴露的端口才能到达你的宿主机。gateway 本身 没有身份验证 —— 请将其视为本地开发工具， 而不是面向互联网的服务。 ## 构建与发布 每次 push 和 PR 都会通过 GitHub Actions （`.github/workflows/build.yml`）验证构建。推送版本 tag（`v1.0.0`、`v1.0`）即可 将镜像发布到 GHCR（`ghcr.io//re-toolbox`）。

标签：请求拦截, 逆向工具