feat(re): cyber-re 原生工具环境、CLI/MCP 接入与 Skills #176

目标与当前状态

cyber-re = cyber-harness 原生 Profile + 逆向工具环境 + 通用 CLI/MCP 接入 + Skills。

cyber-harness 提供共享 workspace、文件/终端、工具发现、既有 Agent loop、Session、后台任务与可选观测；AI 根据任务选择工具、打开或切换目标、编写脚本、组合结果。分析方法、evidence、报告组织与目标核对通过 prompt / Skill 引导。

2026-10-12 修订：本版替换此前“受管理目标绑定 + 只读分析子集 + 强制证据归档”方案。首版重点是工具环境、入口接线和使用说明，不新增 Binding/Investigation/EvidenceStore、统一 RE runtime 或第二套 Agent loop。关联 #148；#175 的观测能力可以独立组合。

• feat(mcp): map MCP tools to schema-derived bash commands #177 已实现通用 stdio / Streamable HTTP MCP→harness bash 命令：分页目录、完整 schema、参数转换、JSON/file 输入、原始 MCP result、错误反馈、连接关闭与失败回滚。PR 当前仍开放，尚未合并。
• 已有 Windows x64 / JBR 21 / 原版 jadx-headless-mcp 0.7.1 的真实引擎验证，以及 gpt-6.1-sol → StandardLoop → bash → JADX MCP 的 UnCrackable L1、ApiDemos LoaderCustom 任务。模型自行发现工具、恢复调用错误并卸载 APK，见验证记录。
• 独立 cyber-re 发行、工具包选择、RE Skills，以及其他引擎/平台/运行时场景的实际验收待完成。以下清单是接入路线，不能视为全部已集成或已验证。

本次检查了 harness/#177、REA 源码与相关上游工具说明，未重新运行真实引擎或模型任务。

1. 执行入口与 Skill 分开描述

CLI、MCP、脚本/API、交互式会话描述的是如何执行；Skill 描述的是如何使用。两者可以组合，同一工具可能同时具有多种执行入口和配套 Skill。

不要求给所有 CLI 再包装 MCP，也不把每个工具改成 re decompile / re xrefs / re evidence 等统一代理。优先保留原名称、原参数与原返回格式；有具体能力缺口时才增加实现。

2. 工具清单与实际入口

“目录已有”指当前 Arsenal catalog 有资产描述，不代表已选入 cyber-re 默认包、已安装或完成真实分析验收。“拟接入”指可选路线；用户现有工具也可以直接使用。

工具清单覆盖的场景可以逐步增加；默认包选择保持独立。不因列入清单就默认安装所有引擎，也不以宿主 Go 可交叉编译推导工具跨平台可用。

3. 调用方式、配置与发现

普通 CLI 与脚本

由 bash 直接调用实际安装入口，参数遵循工具自己的 help。以下展示执行方式，不是统一的 RE 命令协议：

jadx --help
apktool --help
ilspycmd --help
capa -j sample.exe > capa.json
floss -j sample.exe > strings.json
rea analyze-javascript-application /absolute/path/app --json > app.json
python analysis.py

rea CLI 的连字符子命令与 MCP 的下划线工具名可能不同。脚本/API、CLI/MCP 支持范围也不必一一相同，应分别给出真实入口与示例。

MCP → harness bash

复用 #177 的 mcpServers 配置。以已验证 JAR 为例：

{
  "mcpServers": {
    "jadx_mcp": {
      "command": "/path/to/java",
      "args": ["-Xmx512m", "-jar", "/path/to/jadx-headless-mcp-0.7.1-all.jar"]
    }
  }
}

需要既有 Java 17+；已验证环境为 JBR 21。Windows 填写实际可执行入口，例如 java.exe；Node/npm 的 .cmd shim 不能假定可被直接 exec，可改用 node.exe 加已安装包入口。服务也可以按 #177 文档配置 Streamable HTTP URL、headers、cwd/env 和 timeout。

同一个长期运行 Profile 内：

jadx_mcp --list
jadx_mcp load_apk --help
jadx_mcp load_apk --path '/absolute/path/app.apk' --threads 1 --resources lite
jadx_mcp list_classes --offset 0 --limit 10
jadx_mcp unload_apk

# 另行配置 ida / rea_mcp 后，按上游实际目录发现
ida --list
ida idb_open --help
ida idb_list
rea_mcp open_binary --help

jadx_mcp、rea_mcp、ida 是配置选择的服务别名。它们不生成 PATH 可执行文件；外部 Python subprocess、独立系统 shell 和容器不会自动获得这些命令。需要外部脚本访问时，使用工具原生 CLI/SDK/MCP client，或以后基于真实需求补通用宿主入口。

#177 的能力边界：

• --list 展示启用工具；<tool> --help 提供完整上游声明。命名 flags 按 schema 编码，复杂输入可用 --json / --file，原工具名和参数拼写保持不变。
• stdout 返回完整原始 MCP result JSON，包括 mixed content、structuredContent、metadata；错误/partial result 保留，由既有执行反馈呈现，不统一改写成 Evidence DTO。
• 目录在 Profile Load 时获取，上游目录改变需重载。当前处理 tools，不接入 resources/prompts、sampling、elicitation 或 legacy HTTP+SSE；server instructions 不自动变成 system prompt。
• 可选 tools allowlist 属于用户配置；省略/null 表示全部，空数组表示空目录。默认不因“逆向分析”隐藏 load/open/switch/close、script、patch 或 debug 工具。
• 生命周期和 database 选择由 AI 按上游实际命令操作；同一 Profile 的多个 Agent Session 可能共享服务状态，使用显式句柄、多个服务配置或独立 Profile 取决于任务和工具能力。

Skill 加载

沿用 harness 的发行 Bundle、.cyber/skills/、.agent/skills/ 和 CLI 显式 Skill 路径。同名覆盖使用既有优先级，长工具说明与场景参考按需读取。

REA 已提供 reverse-engineer-anything Skill，安装命令 npx skills add morluto/rea --skill reverse-engineer-anything 只安装说明，不安装 REA/引擎、不注册 MCP。其上游目录名 .agents/skills 与 harness 当前自动扫描的 .agent/skills 不同；发行 Bundle 或显式路径接入即可，不假定安装后会自动发现。

4. 原生 infra 与 REA 借鉴边界

flowchart TD
    P["cyber-re 原生 Profile"] --> B["BaseExtensions: files / bash / skills / provider / events"]
    B --> A["可选 Arsenal / 工具环境"]
    A --> M["通用 MCP extension"]
    M --> L["既有 Loop / Session"]
    L --> H["CLI / Web / node 与可选 observer"]
    B --> C["PATH CLI / scripts / 交互式工具"]
    M --> E["JADX / IDA / REA / 其他 MCP"]

发行组合根负责 Profile、工具配置、Skill Bundle 和实际资产。复用 pkg/profile.Profile、harness.New、Extension Set 与既有 loop；通用 MCP/terminal/Arsenal 留在通用层。首版不需要 exts/re、tools/re 领域框架、EngineManager 或 host-private lifecycle catalog。

独立 re/ 发行模块可沿用合并后的 audit 分发约定；具体目录跟随仓库现行结构，不把旧 cmd/re 布局当作架构要求。CLI/Web/节点共用装配。既有 Subagent 接线可直接复用，也可显式装配最小 Loop/Session；不增加“先建立目标 Binding 才能委派”的前置条件。

从 REA 参考：

REA 本身具有 CLI、MCP、providers 和内部资源管理，作为可选工具保留其原契约。直接使用 IDA/JADX/CLI 不自动获得 REA 的 metadata/overload 语义、Evidence 或进程管理保证。

共享 workspace 与 Ghidra project 是不同层次。 workspace 是 AI 和工具使用的文件目录；Ghidra project 是 Ghidra 保存导入 Program/分析数据库所需的引擎容器。原生入口例如 analyzeHeadless <project-dir> <project-name> -import <target>，可以由 AI 选择已有或临时 project。REA 当前的目标快照、私有运行目录、headless bridge 与临时 Ghidra project 是其内部实现，不成为所有 cyber-re 工具的统一要求。

不要求分析前复制/hash/register target，不规定一个 Profile 只能对应一个样本，不在宿主校验每次请求的 database 是否属于某个调查。输入、解包目录、脚本、报告和分析数据库继续使用共享 workspace 或用户指定位置；文件组织由 Skill 建议。

资源关闭仍是工程职责，但依据真实归属：

• terminal 管理自己启动的工作、后台状态与实际退出；MCP extension 管理自己的连接及直接 stdio 子进程。
• load/open/unload/close 等业务工具向 AI 正常公开；REA 的内部 project/worker 由 REA 按自身契约处理。
• HTTP server、用户 GUI、持久数据库与上游 detached worker 不因 MCP client 关闭就被证明已释放；不能杀不属于自己的进程或删除用户产物。
• 保持 Extension Set 逆序关闭、ErrCloseIncomplete 与重试语义；取消等待和底层任务停止分别呈现。需 process group/Windows Job 等机制时，在实际后端补足并验收。

5. 工具交付与执行环境

每个工具补齐安装/配置文档与可运行示例即可，不先设计统一 Engine DTO 或新包管理框架。说明至少包括：

1. 工具名称、上游来源、版本/安装渠道、实际 executable/JAR/package/URL；区分工具名、MCP alias 和 Skill 名。
2. 支持的执行入口及 help/调用示例；CLI 参数、MCP schema、API/脚本入口分别描述。
3. runtime、插件、规则、外部 extractors、宿主软件/许可证、平台与架构。
4. cwd、输入/输出路径、stdin/stdout、编码、当前目标/database/device/session，以及保存/关闭方式。
5. 对应 Skill/references、已做的真实验证和仍未覆盖的功能。

分发按实际形态处理：

• 普通 CLI 资产：复用 Arsenal catalog、bundle 与既有安装机制；默认集、可选集和用户 PATH 工具分开配置，不复制版本表。
• JAR/多文件/dotnet/Python/npm/bridge：提供对应 runtime 和真实入口说明，支持用户已有安装；不能把 Ghidra/REA/JDK 等伪装成一个单文件二进制塞进普通 CLI 安装器。
• MCP 服务配置：只声明实际 command+args 或 URL、env/cwd/timeout、可选 tools；工具安装与服务注册分开。发布示例固定可复现版本，避免用 REA main 的工具清单承诺旧 npm 包也支持。
• 可选 Linux 镜像/远端节点：复用原工具和 harness 节点能力。server 访问的是其所在机器的路径；容器需要挂载/容器内路径，设备需要实际连接。设置 cwd 不会自动重写所有 schema 路径。
• Skills：随发行或用户配置加载；可以使用 REA Skill 或 cyber-re 场景说明，遵循 harness 的发现/覆盖规则。

可提供工具配置诊断，报告缺失依赖、版本和连接错误；不要求每次分析先运行 doctor 或注册目标。安装步骤使用既有显式配置，不在普通工具调用中偷偷安装/升级引擎。

6. Skill 与观测

默认逆向 Skill 可以引导：先读 help/status；确认正在使用的文件/database/runtime；按任务组合引擎；必要时保存副本、摘要和关键输出；区分反编译、静态关系、推断与运行观察；说明未知事项；使用后关闭自己打开的临时会话。

这些要求属于 prompt。不设置 mandatory evidence manifest、统一结果 schema、Evidence commit、报告 validator 或分析调用 gate。 AI 可以根据任务调整方法，用户可以覆盖 Skill；未按某种证据格式写文件不会使工具调用被拒绝。

既有 Session/AOP/Artifact 和可选 #175 观测继续记录运行与访问产物，不承担领域证据认证。REA 返回 Evidence 时原样传递；普通 CLI 允许文本、JSON、文件或脚本结果。质量通过任务评估与 Skill 迭代改善。

7. 实施顺序与验收

P0：原生 Profile 与首条可用路线

• 合并/复用 feat(mcp): map MCP tools to schema-derived bash commands #177；独立 cyber-re Profile/发行入口，接线共享 workspace、terminal/files、既有 loop/Session、MCP 配置与 Skill。
• 确定最小 CLI bundle 与可选工具清单；补实际平台资产及安装/help 文档。
• 将已验证 JADX MCP 路线接入发行配置，使用 jadx_mcp 等独立 alias；保留原 load/unload/查询工具。
• 分别说明普通 CLI、内部命令、MCP alias 与外部脚本的执行边界，验证 Windows 启动入口和含空格路径。

P1：多工具组合

• 接已有 IDA MCP 与已发布 REA/Ghidra 路线；分别验收 native 引擎、headless/GUI 模式和资源归属。
• 补 JADX CLI、Apktool、ILSpyCmd 等互补入口与对应 references；不为它们先统一包装 MCP。
• 用 APK→JNI、native、Electron 等代表任务检验 AI 的发现、纠错、目标切换与跨工具组合。

P2：扩展执行域与场景

• 按需求补 Frida/ADB、调试器、固件 extractors、浏览器、网络及其他格式工具。
• 复用既有远端/容器/委派能力；根据真实缺口改善通用连接、后台会话或进程监督。
• 按具体工具/平台维护真实验收记录与 Skill，工具清单和默认包独立演进。

工程验收关注 catalog/schema、参数与返回保真、cwd/路径、stdout/stderr/退出码、错误反馈、后台状态、取消、失败初始化回滚与自有资源 Close/重试。测试不把“遵循分析方法”变成前置条件。

Agent/Skill 验收关注代表任务中的工具选择、操作恢复、跨工具组合与结果准确性，可使用人工或源码/oracle 核对。真实工具/模型任务与模拟协议测试分开报告；已有 Windows/JADX 基线不外推为 IDA/Ghidra/Hopper/HTTP/设备或其他平台已验证。

参考

• feat(mcp): map MCP tools to schema-derived bash commands #177 MCP 接入文档、真实 LLM 验证。
• REA 审阅基线 7296f2b：architecture、tool design、installation、Skill。