Headless RE-MCP

Windows 上的无分析器窗口逆向 MCP（v0.2.1）。把 IDA idalib 静态分析、x64dbg headless.exe 动态调试、Android 设备/APK 逆向与 Web（CDP/JS/WASM/抓包）收成 265 个受限语义工具，供 Cursor 等 MCP 客户端调用；不开放任意调试器命令、不开放任意 JS 求值、不开放 adb shell 透传，也不弹 IDA/x64dbg GUI。

变更记录见 CHANGELOG.md。

现状口径（偏保守）： 公开仓库历史很短、单维护者。连接级自愈、错误契约与安装包都有真机验证（下方「范围与风险」列了具体数字），但可选后端成熟度不一，仍建议在隔离环境使用。缺后端时集成测试会 skip，skip ≠ pass。

依赖

powershell -File .\scripts\build_deps_bundle.ps1
# -> artifacts/release/deps-bundle/headless-re-mcp-win.x64.zip

解压后执行 activate_deps.ps1，再设置 HEADLESS_RE_IDA_HOME。

版本兼容矩阵

下表是仓库实际探测并在 doctor 中逐项校验的组合；缺可选项只降级，不阻塞就绪。

python -m headless_re_mcp doctor 按「必需 / 可选」分组输出，并单独列出阻塞项与对应修复命令。

Related MCP server: PCM

快速开始

用安装包（不需要先装 Python）

到 Releases 下载 headless-re-mcp.msi（约 33 MB，per-user 安装到 %LocalAppData%\HeadlessReMcp，无需管理员）。 Python 运行时与全部依赖在包内，装完直接用：

& "$env:LOCALAPPDATA\HeadlessReMcp\start_web.cmd"                 # 监控台（系统浏览器）
& "$env:LOCALAPPDATA\HeadlessReMcp\headless-re-mcp.cmd" doctor --json

首次启动会自检环境并打印带 token 的本地地址。IDA 与 x64dbg 仍需自备，在监控台里填路径即可。

从源码

cd <repo-root>
python setup.py                    # 一条命令完成安装与配置
python -m headless_re_mcp doctor --json --strict
python -m headless_re_mcp serve

setup.py 会依次安装 ida,pe,web,native 依赖、发现本机授权的 IDA Professional 9.x、 按固定大小与 SHA-256 校验下载缺失的 x64dbg/可选 CLI 依赖包、写入用户 config.json、 激活 idalib，最后生成 MCP 配置并跑一遍 Doctor。IDA、idalib、Hex-Rays 与许可证永远不进依赖包。

无人值守用 --non-interactive；已有依赖用 --skip-release；不装 Python 包用 --skip-pip。

python -m headless_re_mcp serve-web   # 仅 loopback + 本地 token
python start_web.py                   # 监控台（系统浏览器，非内嵌）

非 MCP 客户端（OpenAI function calling 等）可导出工具定义：

python openai_bridge.py --output openai_tools.json   # tools[] + 反查名映射 + 写操作清单
python openai_bridge.py --names-only                 # 只看 OpenAI 名 -> MCP 名

OpenAI 不允许函数名带点，导出会做安全名转换并附 name_map 供回调派发；write_tools 列出会改状态的工具，便于桥接方保留审批策略。

能力概览

同一会话可同时附着 IDA 与 x64dbg；支持主模块与显式模块的 preferred VA ↔ RVA ↔ runtime VA 换算、真实插件回调事件流（原生 1024 槽环形缓冲 + 会话级持久化 drain/重放；仅当 drain 也未能赶上覆盖窗口时才 unrecovered_gap）、以及 workflow 导航/断点意图。

主要工具面（节选）：

• 会话：session.create/get/list/close

• 静态：static.open/functions/strings/decompile 等

• 动态：dynamic.open/state/events/wait/launch/attach/stop/pause/resume、单步、寄存器/内存、模块与断点

• 地址：sync.*、modules.list/resolve；sync.resolve_runtime_address 把 static VA / 模块 RVA / runtime VA 一次解析成运行时地址，dynamic.breakpoint.set 可用 address_space=static|rva 直接下断（内部重定位，调用方不做地址运算）

• 复合工作流：dynamic.analyze_function（反编译 + 重定位下断 + 运行 + 寄存器，一次调用）、dynamic.trace_api_arguments（按符号或地址断 API 并捕获整型参数：x64 取 RCX/RDX/R8/R9，x86 从返回地址之上的栈读取；结束必清断点）

• 分析记录与报告：knowledge.record/query（按 kind+key 幂等累积函数/断点/结构体/API 等发现）、report.generate（渲染 Markdown 报告并落盘为产物）

• 可观测：meta.metrics（每工具调用数、失败数、p50/p95/max 延迟；同时以 JSON 行写入 headless_re_mcp.telemetry 日志）

• 自愈：session.health（按需检查各后端存活与连接状态，并就地重建掉线的连接）、session.recover（重开死掉的后端）

• Workflow：workflow.*

• 检测/脱壳（可选外部 CLI）：detect.*、unpack.*（非通杀承诺；claims_universal_unpack=false）

• 目标 UI（有界）：Win32 交互与截图；UIA/OCR/SendInput 为实验路径，勿默认依赖

• Android 静态：apk.open/manifest/permissions/certificates/components/classes/methods/strings/xrefs（androguard 进程内）、apk.decompile/export_sources（jadx CLI）

• Android 改包：apk.decode/repack/sign（apktool + apksigner；apk.sign 缺省用 Android debug keystore）

• Android 设备：device.list/connect/info/properties/packages/install/uninstall/launch/force_stop/current_activity/logcat/screenshot/pull/push/forward

• Android 动态：frida.devices/device.connect/server.ensure/applications/spawn/java.classes/java.methods；hook 复用 frida.hook.template（含 android_ssl_unpin / android_crypto_monitor / android_root_bypass）

• Web 静态：js.deobfuscate/beautify/unpack_bundle（webcrack）、wasm.info/wat（wabt）；WASM 反编译复用 ghidra.* + ghidra-wasm-plugin

• Web 动态：web.open/navigate/close/network.list/network.get/console/scripts/script.source/wasm.list/dom.snapshot/screenshot/har.export（Playwright 驱动 CDP）

• 抓包（Web 与 Android 共用）：proxy.start/stop/status/flows/flow.get/replay/export_har/ca.install_android（mitmproxy 进程内）

• 工作方向：workspace.mode.get/set（full|pe|android|web）

目标类型与工作方向

session.create 按扩展名与魔数自动判定目标类型（MZ→PE、含 AndroidManifest.xml 的 zip→APK、http(s)/.js/.wasm→Web），也可显式传 target。PE 专属工具对非 PE 会话返回结构化 target_mismatch，不会深入后端才失败。

未干净关闭的会话会按同一 ID 从 sessions.db 水合回来（state=created，metadata.restored=true），不自动拉起 IDA/x64dbg。监控台重启后继续用旧 id，不要再 session.create 一条新的。

工作方向（workspace_profile）把工具面裁剪到单一场景：pe 隐藏 Android 与 Web 工具，android 隐藏 Web 工具，web 隐藏 Android 工具，默认 full 不裁剪。裁剪只影响可见性，完整 catalog 仍是唯一权威；读写策略是另一条独立边界。监控台开屏会让你选择方向，选择同时作用于 MCP 客户端下次连接看到的工具集、监控台 Agent 的工具面，以及检查器布局（PE 虚拟桌面 / Web 页面监视 / Android APK；侧栏在 Web 方向改为 URL）。

动态写操作仅接受明确参数与白名单寄存器；无 dynamic.command。同样的原则贯穿新增面：没有 device.shell、没有 web.evaluate、不接受调用方自带 Frida 脚本——设备与浏览器上的每个能力都是具名且校验过参数的工具。设备序列号与包名按严格正则校验，杜绝参数注入。

故障自愈

RPC 连接掉线（例如被调试程序卡住导致一次超时）不会终结会话。worker 仍在运行、仍持有被调试进程， 后台健康检查会重建连接；即便监控关闭，下一次调用也会自行重连。失败的那次调用不会被重放， 因为重放可能让状态变更类操作执行两次——调用方仍会收到那次失败，但标记为 retryable。

worker 进程真正死亡时只上报不自动重启：重启后的调试器不再附着于任何进程，是否重新启动目标 必须由调用方决定，用 session.recover 显式处理。

health_check_interval_s 控制后台巡检间隔，设为 0 关闭（此时仍保留调用时重连）。

无人值守（加壳分析默认开；完全访问是开关）

监控台对话框右侧是两档：请求批准（写操作停下等人）和 完全访问（放开 state_change + file_write）。PUT /api/agent/autonomy 传 {"mode":"request"|"full_access"} 即可切换并持久化。

未在 config/环境里写 autonomy 键时，Settings.load() 默认放开加壳 PE 分析所需的 state_change 以及 dynamic.stealth.set / unpack / static.open 等文件写入； patches.apply / static.bytes.patch、APK/Web 改包仍要人批。显式空列表 （agent_auto_approve_effects: [] 且 agent_auto_approve_tools: []）仍是 fail-closed。

细粒度的 agent_auto_approve_effects / agent_auto_approve_tools 仍可用。 agent_never_auto_approve 优先级高于一切授权（含只读基线），写进去就是无条件停止。 自动执行的写操作会发 approval.auto 事件并写明是哪条规则批准的。 GET /api/agent/autonomy 可读回 mode、策略与它实际放开的工具清单。

加壳样本：packer.classify / unpack.recommend 给出 stealth_profile （tmd/Themida/WinLicense → themida）。dynamic.open / dynamic.launch 省略该参数时按映射自动写 ScyllaHide ini，不必再等用户说「切到 tmd」。

• 持久目标与调度：run 有界（分钟级、十来轮工具），mission 是跨 run 存活的目标。调度器按最早 优先认领、一次喂一个 run，完成判据是 run 自己输出 MISSION_COMPLETE 标记，而不是"没有再调用 工具"——后者会在模型停下来思考时误判。max_runs 是强制预算。重启时在途 mission 退回 PENDING 而不是丢弃。接口在 POST /api/agent/missions。

• 进程守护：headless-re-mcp supervise 在子进程退出或连续探测不到 /readyz 时重启它（进程 活着但卡死是两种不同故障）。退避递增，单次探测失败不算故障，启动期不做就绪判定；快速反复崩溃 会诚实地停下并报 crash_loop，而不是用重启循环伪装成正常运行。scripts/install_service.ps1 注册开机自启——用计划任务而非 Windows 服务，因为后端需要交互式会话和持有 IDA 授权的用户配置。

• 看门狗：watchdog_interval_s 控制巡检；发现死掉或反复掉线的后端会告警。 watchdog_auto_recover_backends 默认关闭——恢复后的动态后端不再附着任何进程，是否重启目标 是真实决策。告警走 telemetry 通道，外部采集器无需第二个端点。

• 样本间隔离：isolation_command 在 mission 之间（不是 run 之间，同一 mission 的 run 共享目标） 执行你提供的命令。本服务不管理虚拟机——hypervisor、快照名和凭据属于部署方。必需步骤失败会 中止该 mission，因为继续下去正是会静默交叉污染结果的那种情况。

• provider 韧性：限流和 5xx 会退避重试，但只在流还没吐出任何内容之前——过了第一个 token 重放会重复输出，还可能把工具调用再执行一遍。客户端错误不重试。

运维探针：/healthz 只回答存活（刻意不碰别的，慢后端不该引发重启循环），/readyz 单独回答就绪 并在存储或产物目录失效时返 503，/metrics 是 Prometheus 抓取点。后两者不需要控制台 token， 便于本机守护进程探测。

只读部署

local_full_access: false 会让所有会改变状态或写文件的工具返回 write_disabled 错误， 只读查询不受影响。工具仍然可见——调用方拿到的是能理解的拒绝，而不是工具凭空消失。 265 个工具的读写归类（148 只读 / 117 写）在 tools/catalog.py 里逐个显式声明，策略在调用时 读取，改配置不必重启。工具面裁剪（workspace_profile）与读写策略是两条独立的边界：前者决定 「看得见什么」，后者决定「能不能改」。

守卫下沉在 CommandCatalog.bind_mcp——所有绑定路径的唯一收口，所以 MCP、Web 控制台的 agent 路由与 OpenAI 桥接拿到的是同一套策略；Web 那条直接调服务方法的写入路径单独做了检查。

并发

工具在工作线程上执行，长调用（启动被调试程序、反编译）不会阻塞 MCP 事件循环， 同一连接上的其它请求仍能得到响应。单个后端内部仍按会话串行——调试器本身是有状态的。

仓库结构

src/headless_re_mcp/   # Python 包与 MCP 服务
tests/                 # unit / integration / gate
native/                # x64dbg headless RPC
fixtures/              # 无害测试样本
scripts/               # 构建、同步、打包
packaging/             # WiX 等
external/              # 本机大型依赖占位（二进制多半 gitignore）
upstream/              # 本地上游 checkout（gitignore）
artifacts/             # 本地构建产物（gitignore）

根目录元数据：pyproject.toml、README.md、setup.py、start_web.py、upstream.lock.json、LICENSE。

上游不进 Git：复制 .cursor/mcp.json.example 或跑 python setup.py；拉取锁定上游：

powershell -File .\scripts\sync_upstream.ps1
powershell -File .\scripts\sync_upstream.ps1 -Name x64dbg

安装与构建

python -m pip install -e ".[dev,ida,pe,web]"

powershell -File .\fixtures\native\build.ps1 -Architecture all

powershell -File .\native\xdbg-headless-rpc\build.ps1 `
  -Architecture all -BuildParallelism 2 -RunGate

headless.exe 必须保留完整 Release 目录（同目录 DLL / Qt / TitanEngine）。

$env:HEADLESS_RE_X64DBG_HEADLESS_X86 = "$PWD\artifacts\x64dbg-x86\Release\headless.exe"
$env:HEADLESS_RE_X64DBG_HEADLESS_X64 = "$PWD\artifacts\x64dbg-x64\Release\headless.exe"
$env:HEADLESS_RE_DIEC = "C:\path\to\diec.exe"   # 可选
$env:HEADLESS_RE_UPX  = "C:\path\to\upx.exe"    # 可选

安装包

发布版提供 per-user MSI（装到 %LocalAppData%\HeadlessReMcp，不需要管理员）。Python 运行时 与全部依赖随包发布，装完即可用，不要求机器上已装 Python；装好后运行 start_web.cmd 打开 工作台，或用 headless-re-mcp.cmd 调 CLI。IDA 与 x64dbg 仍需自行准备。

内置解释器版本是锁定的（pydantic-core 只发 cp312 专用轮子，没有 abi3），所以运行时和 依赖必须成套打包。本地构建需要 WiX Toolset 3.14，会联网取一次 Python 嵌入包并缓存到 artifacts/tools：

powershell -File .\scripts\build_msi.ps1     # 产出 MSI 与 .sha256
powershell -File .\scripts\verify_msi.ps1    # 装 → 跑 → 卸，并断言零残留

验证会清空 PATH 里的所有解释器，只允许自带运行时应答——用系统 Python 去测安装副本， 只能证明目录完整，证明不了装完能用。

推 v* 标签会由 release 工作流构建、跑同一套往返验证，再连同校验和发布。

验收

先跑零窗口 Gate，再按需跑 pytest。集成 Gate 依赖本机后端；缺环境出现 skip 时不能当通过。

python -m headless_re_mcp gate-xdbg --architecture x86 --timeout 60
python -m headless_re_mcp gate-xdbg --architecture x64 --timeout 60

python -m ruff check src tests fixtures
python -m mypy
python -m compileall -q src tests
python -m pip check
python -m pytest tests/unit -q
python -m pytest tests/integration -q -rs   # 需本机后端；-rs 会列出每个 skip 的原因
#   开了 HEADLESS_RE_HIDDEN_DESKTOP 时 test_m10_ui_* 会跳过，见下方「硬约束」一节
python -m headless_re_mcp doctor --json --strict

前端（改动 webui/ 时）：

cd webui
npm install            # 国内网络可加 --registry=https://registry.npmmirror.com
npm run typecheck
npx vitest run
npm run build          # 产物直接写入 src/headless_re_mcp/web/spa

硬约束：分析器进程（IDA / x64dbg headless）顶层窗口必须为 0；目标程序 GUI 不受此限。

tests/integration/test_m10_ui_* 会驱动目标窗口，需要独占的交互桌面：跑这几个 gate 时不要在 同一会话里安装软件或打开别的窗口，否则前台焦点被抢会得到 no foreground window for SendInput 或 SendMessageTimeout，那是环境干扰而不是回归。

它们枚举的是当前桌面，所以和 HEADLESS_RE_HIDDEN_DESKTOP=1 互斥：开着隐藏桌面时被调试进程 的窗口在另一个 Win32 Desktop 对象上，这 9 个 gate 会带 visible_desktop 标记明确跳过（而不是 以「窗口没观察到」失败）。要覆盖这部分就临时取消该变量再单独跑。

隔离部署

分析未知样本时调试器会真实执行目标代码，请把执行端放进可随时丢弃的环境。

基本要求：

• 专用低权限账户，不要用管理员运行；不共享宿主目录、剪贴板与凭据

• 默认断网，确需联网走白名单代理

• Web 监控台只监听回环并带 token（serve-web / start_web.py 默认如此），不要转发到局域网

• 每次任务结束回滚快照或重装，不要在同一环境里连续分析多个未知样本

目标程序会弹窗但你不想看到时，可开隐藏桌面：设 HEADLESS_RE_HIDDEN_DESKTOP=1（或 config.json 的 hidden_desktop）。x64dbg 与被调试进程会创建在独立的 Win32 Desktop 对象上，全程不切换输入桌面；WebUI「虚拟桌面」面板可被动查看窗口清单并按需截图，GPU/DirectX 窗口返回空白帧时会标记 degraded，不会静默切桌面兜底。

隐藏桌面解决的是「不干扰你的桌面」，不是反检测：样本仍可能识别虚拟化、调试器或非默认桌面。

端到端示例：解一个 crackme

仓库自带 fixtures/native/crackme_serial.c（校验 8 位序列号，把输入逐字节异或 0x41 后与常量比对）。构建后可完整走一遍动静结合流程：

powershell -File .\fixtures\native\build.ps1 -Architecture all
# -> artifacts/fixtures-x64/crackme_serial.exe

典型工具顺序：

tests/integration/test_crackme_serial_e2e_gate.py 是这条链路的可执行版本：它从二进制还原出序列号并在调试器下验证，跑通即说明本机环境可用。

范围与风险

已有较完整的静态查询、动态调试闭环、事件流、地址同步、workflow，以及 dump / IAT / UPX 等脱壳相关路径的代码与真机 Gate。连接级自愈已实测，但公开提交仍少，可选后端成熟度不一。

Android 与 Web 两个目标域是新加的，成熟度明显低于 PE 那条链路：契约（信封、读写分级、敌意输入）与降级路径有单元测试强制，但真机 Gate 只在装了对应工具的机器上才真正执行。缺 adb/jadx/apktool/webcrack/wabt 时相关 Gate 会如实跳过，skip 不等于 pass。

当前证据（在一台配好 x64dbg headless + Chrome/Playwright + mitmproxy + androguard 的机器上实测； 该机器未配置 IDA，所以 idalib 相关路径这一轮没有被执行）：

• 单元测试 1532 passed / 4 skipped（IDA UPX 夹具 1；Windows 上 3 个 shebang 探针超时测，Linux CI 会跑）

• 集成 Gate 78 passed / 9 skipped（含 x86 与 x64 双架构、UI 自动化、r2/frida/windbg 可选后端、 隐藏桌面隔离、连接掉线自愈、crackme 端到端、浏览器 CDP、抓包起停与端口释放、浏览器生命周期、 浏览器跨线程驱动、关闭会话同时回收浏览器与抓包端口、长跑页面不按次泄漏句柄）

• 9 个 skip 均有明确原因：缺 .NET 样本（2）、未安装 Exeinfo PE（3）、未安装 webcrack（1）与 wabt（1）、以及 2 个有文档说明的故意跳过

• 262 个工具在敌意输入下全部返回结构化错误信封，无一抛出（只排除会真删数据的 artifacts.gc）， 且这条性质由 tests/unit/test_tool_fault_contract.py 每次运行强制校验，不是一次性测量。 敌意环境同样覆盖：产物库被删除、变成只读或被损坏时，工具照常返回信封（存储类故障有专门的 storage_unavailable 码并区分是否可重试），就绪探针如实报不可用，服务在目录恢复后自愈

• 长期驻留状态有专门的有界性与并发回归测试（tests/unit/test_unattended_resource_bounds.py）： 抓包双缓冲同步淘汰、浏览器脚本表有界、多线程读写不撕裂、后端单例、APK 缓存随会话回收、 会话关闭后无任何字典仍以其 id 为键、产物配额在会话开着时也生效且能扛住突发写入、失败的抓包 启动不留残留、浏览器调用线程收敛且等待有界、产物目录被删后服务照常应答并自动重建

• 抓包的有界性用真实流量复核过：2600 次经代理的请求后保留数停在 2000（环形缓冲上限）， 内存在到达上限后不再增长（2000→2500 次请求期间 98 MB 持平），句柄 +2、线程 0

• 上述结论用压缩时间的 soak 实测复核过：600 轮会话生命周期 RSS +1 MB、线程与句柄零增长； 20 轮抓包起停与 15 轮浏览器开关同样零增长；失败路径（上千次无后端调用、40 次端口被占的抓包 启动、12 次浏览器启动失败）在修复后均为零增长。其中会话流失那条已固化为常驻测试 （200 轮 create/register/close，断言线程数归位、产物根不超配额三倍），不再依赖"记得去 soak"

• 安装包：清空 PATH 里所有解释器后仍能用自带运行时启动工作台，SPA 与 /api/sessions 均返回 200， 卸载后目录完全移除

已知不稳定：test_m10_ui_* 依赖独占的交互桌面，在全量并发跑时偶发失败（前台焦点被抢）， 单独重跑稳定通过。判定回归前请先单独复跑。

Gate 会从 config.json 读取后端路径（tests/integration/conftest.py 负责桥接），所以配置好的机器不会因为"没设环境变量"而假跳过。skip 仍然不等于 pass：换一台缺后端的机器，对应 Gate 会如实跳过。

无人值守的机制已经具备（自动批准策略、持久目标与调度、进程守护、看门狗、隔离钩子、provider 退避）， 但这不等于本项目替你承担了 SLA。仍然成立的限制：真机 Gate 只在配好后端的机器上手动跑过， 自建 runner 的那条 CI 从未绿过；单维护者、公开历史短；IDA idalib 与 x64dbg headless 本身都不是 为 7×24 无人值守设计的，可用性上限被它们锁死。要对外承诺可用性数字，这三条得先自己解决。

不适合：跨平台、无 IDA 授权、把可用性责任外包给上游的场景。
适合：已有 Windows + IDA 9.x，愿意自己盯着跑，想要 MCP 驱动的逆向辅助（可长期无人值守运行）。

仅分析你拥有或获明确授权的样本。本地服务含写寄存器/内存能力，勿对不可信代理暴露，勿在未隔离环境处理未知样本。

License

GPL-3.0-only。见根目录 LICENSE。第三方工具由用户自行获取与授权；上游修订锁定见 upstream.lock.json。