一、项目定位与目标

Reversecore MCP 是一个面向逆向工程领域的集成式静态与动态分析平台，通过 Model Context Protocol（MCP）将多种二进制分析工具统一暴露给 AI 客户端（如 Claude、IDE 插件等），使大语言模型能够直接调用专业的逆向工具完成自动化分析任务。资料来源：README.md:1-30

项目的核心目标是为安全研究员、恶意软件分析师和漏洞挖掘工程师提供一个"开箱即用"的 AI 协作逆向环境，覆盖从二进制加载、指令反汇编、控制流分析、漏洞模式匹配到 Yara 规则扫描、硬件级取证的全流程。资料来源：PROJECT.md:5-40

与传统逆向工具（如 IDA Pro、Ghidra、Radare2 的 CLI 模式）相比，Reversecore MCP 的独特之处在于：

• AI 原生接口：所有工具以 MCP 协议暴露，可被任意 MCP 兼容客户端调用。资料来源：README.md:32-60
• 容器化部署：完整的 Docker 镜像封装了 Radare2、Ghidra、Yara、Volatility 等依赖，避免宿主环境配置困难。资料来源：README.md:62-90
• 静态与动态融合：v3.0.0 起同时支持静态分析（SAST、Yara、模式匹配）与动态分析（内存取证、行为追踪）。资料来源：CHANGELOG.md:1-25

二、核心能力矩阵

下表汇总了 Reversecore MCP 在不同版本迭代中引入的核心分析能力：

资料来源：CHANGELOG.md:1-60，PROJECT.md:42-80

三、系统架构概览

Reversecore MCP 采用分层架构，从外到内依次为：MCP 客户端层 → MCP 协议适配层 → 工具注册与路由层 → 工具实现层（Radare2/Ghidra/Yara/Volatility/SAST 等）→ 系统依赖层（Docker 容器）。

graph TB
    A[MCP 客户端<br/>Claude/IDE] -->|MCP 协议| B[MCP 服务器<br/>reversecore_server.py]
    B --> C[工具注册中心<br/>tool registry]
    C --> D1[Radare2 适配器]
    C --> D2[Ghidra 适配器]
    C --> D3[Yara 扫描器]
    C --> D4[SAST 分析器]
    C --> D5[Volatility 动态模块]
    D1 --> E[Docker 容器<br/>分析沙箱]
    D2 --> E
    D3 --> E
    D4 --> E
    D5 --> E

资料来源：README.md:90-140，AGENTS.md:10-45

所有工具通过统一的 MCP 接口暴露，AI 客户端无需关心底层 CLI 细节，工具内部封装进程调用、输出解析、错误恢复逻辑。资料来源：AGENTS.md:20-55

四、典型使用场景

1. 恶意软件样本分析：通过 run_file 加载样本，使用 r2pipe 执行反汇编，配合 Yara 规则识别已知家族特征。资料来源：README.md:140-180
2. 漏洞 PoC 验证：结合 SAST 框架定位可疑代码段，再在动态分析模块中执行验证。资料来源：PROJECT.md:82-110
3. CTF / 竞赛解题：AI 助手调用 MCP 工具完成字符串提取、函数识别、加密算法还原。资料来源：ORIGINAL_REQUEST.md:15-45
4. 固件与硬件取证：利用硬件级分析工具处理嵌入式固件镜像，提取文件系统与配置。资料来源：CHANGELOG.md:25-55

五、版本演进与社区关注点

项目自 1.7.8 起步，在 2.0.x 系列完成了 MCP 协议标准化与 Docker 化重构，v2.1.0 引入 AI 驱动的 SAST 是社区关注的里程碑之一，v3.0.0 进一步整合动态分析能力。资料来源：CHANGELOG.md:1-70

社区中常见的问题集中在以下方面：

• Radare2 会话生命周期：v2.0.4 修复了 r2pipe 会话未在创建时打开导致的连接失败问题，是用户频繁遇到的环境类 issue。资料来源：CHANGELOG.md:30-45
• CI/CD 测试稳定性：v2.0.6 将集成测试迁移至 Docker 容器内运行，显著降低了"本地可复现、CI 失败"的问题。资料来源：CHANGELOG.md:20-35
• 大体积二进制性能：v3.0.0 包含 3 项性能/重构提交，专门优化大型样本处理路径。资料来源：CHANGELOG.md:5-15

总体而言，Reversecore MCP 是一个以"AI 协作逆向"为核心卖点、覆盖静态到动态全流程、且持续通过容器化与测试改进来提升生产可用性的逆向工程中间件平台。资料来源：README.md:1-200

1. 整体架构概览

系统采用典型的「中心化调度 + 池化资源 + 工具注册」模式。入口由 server.py 提供，MCP 客户端（如 Claude Desktop、Cursor 等）通过 stdio/HTTP 与之通信；所有静态分析能力最终都落在 core/ 子模块上。

flowchart TB
    Client[MCP 客户端] -->|stdio/JSON-RPC| Server[server.py<br/>工具注册与调度]
    Server --> Config[core/config.py<br/>配置加载]
    Server --> Security[core/security.py<br/>路径与命令校验]
    Server --> Pool[core/r2_pool.py<br/>Radare2 会话池]
    Server --> Memory[core/memory.py<br/>分析结果缓存]
    Server --> Mitre[core/mitre_mapper.py<br/>ATT&CK 映射]
    Pool --> R2[(radare2 / r2pipe)]
    Security -.拦截.-> Server

2. 入口与工具注册层（server.py）

server.py 是整个 MCP 服务的入口，负责：

• 初始化日志、配置加载器与全局异常拦截；
• 注册所有可被 LLM 调用的工具（如 run_file、r2_cmd、decompile_function、yara_scan 等）；
• 在请求生命周期内统一调用 core/security.py 进行输入校验。

资料来源：server.py:1-80

v3.0.0 的关键演进

v3.0.0 是一次「完整的架构重构」(complete architectural overhaul)，新增了完整的 动态分析 能力并整合了 v2.x 阶段的静态能力。这意味着 server.py 同时暴露了静态工具（反汇编、字符串提取、YARA 扫描）与动态工具（运行时插桩、行为追踪）。资料来源：release notes v3.0.0

3. 配置中心（core/config.py）

config.py 集中管理：

• 工具允许的根目录白名单（防止越权访问宿主任意文件）；
• radare2、yara、docker 等外部依赖的二进制路径；
• 会话池上限、缓存 TTL、并发数等运行时参数；
• 通过环境变量或 .env 文件注入敏感信息。

这种「单一配置源」的模式让运维人员无需修改代码即可调整策略，也使 v2.0.6 引入的 Docker 化集成测试得以在容器内复用同一份配置。资料来源：reversecore_mcp/core/config.py:1-120

4. 安全边界（core/security.py）

由于服务可直接被 LLM 触发命令执行，security.py 是最关键的防线，主要职责：

1. 路径校验：所有文件操作必须落在白名单目录内；
2. 命令注入防护：radare2 命令经参数化封装后才会下发到 r2pipe；
3. 资源隔离：限制单个会话可占用的 CPU/内存，防止恶意样本触发拒绝服务。

资料来源：reversecore_mcp/core/security.py:1-150

社区反馈显示，多个 PR 与 issue 都围绕 r2pipe 会话打开时机与命令沙箱化展开（例如 PR #77 修复了「会话创建时未打开 r2pipe session」的问题）。资料来源：release notes 2.0.4

5. Radare2 会话池（core/r2_pool.py）

为避免每次分析都重新启动 radare2（开销极高），r2_pool.py 实现了连接/会话复用机制：

• 采用 LRU 或引用计数策略回收空闲会话；
• 单二进制分析期间持有独占会话，避免命令交错；
• 支持「会话暂停/恢复」以适配长时间批处理。

v2.0.4 的关键修复正是确保会话在创建时立即打开 r2pipe 通道，避免首次命令下发时出现空指针或超时。资料来源：reversecore_mcp/core/r2_pool.py:1-200，release notes 2.0.4

6. 内存与分析缓存（core/memory.py）

memory.py 提供短期与跨调用的结果缓存：

• 短期缓存：同一函数反汇编、同一偏移字符串提取在会话内复用；
• 跨会话缓存：基于 SHA256 等指纹识别相同样本，避免重复分析；
• 与 r2_pool.py 协同，未命中缓存时才会真正调用 radare2。

资料来源：reversecore_mcp/core/memory.py:1-180

7. ATT&CK 战术映射（core/mitre_mapper.py）

mitre_mapper.py 将分析过程中识别出的行为（如 API 调用模式、shellcode 特征）与 MITRE ATT&CK 框架编号关联，输出可被下游 SIEM 消费的标准化结果。该模块是 v2.x 阶段「高级分析能力」的一部分。资料来源：reversecore_mcp/core/mitre_mapper.py:1-160

8. 集成与部署

• Docker/CI：v2.1.0 重构了 Docker 构建以加快 CI 速度，所有集成测试在容器内运行以匹配生产环境。资料来源：release notes 2.0.6
• MCP 工具发现：v2.0.6 引入了「自动发现并调用所有注册工具」的测试用例，覆盖 run_file、r2_cmd 等核心 API。

小结

server.py + core/* 构成了 Reversecore_MCP 的「心脏」：配置决定行为边界、安全决定信任边界、池化决定性能边界、缓存决定成本边界、MITRE 映射决定语义边界。这五层共同支撑起 v3.0.0 「集成静态与动态分析」的目标。

概览与设计目标

Reversecore MCP 是一个基于 Model Context Protocol（MCP）的逆向工程与二进制安全分析平台，其核心能力通过 reversecore_mcp/tools/ 目录下的多个子模块对外暴露。每个工具以 MCP 兼容函数的形式注册到服务器，使大语言模型（LLM）客户端可以通过统一协议调用 radare2 反汇编、capability 检测、源码审计、恶意模式识别等多种分析能力。

工具目录遵循"按分析维度分目录"的原则组织：analysis/ 负责静态分析，radare2/ 负责反汇编与反编译引擎封装，malware/ 负责威胁模式识别。这种结构使得新增分析能力（如 v3.0.0 引入的动态分析）可以在保持核心接口稳定的前提下进行扩展 资料来源：reversecore_mcp/tools/analysis/static_analysis.py。

静态分析工具集

analysis/ 子模块集中了所有不依赖运行时执行的纯静态分析工具。static_analysis.py 提供基础的二进制特征采集接口（如哈希、节区信息、导入导出表），是上层所有分析流程的入口；capa_tools.py 封装了 FireEye CAPA 的能力检测能力，将可执行文件中的代码段映射为"创建进程"、"读写注册表"、"网络通信"等高层行为 资料来源：reversecore_mcp/tools/analysis/capa_tools.py。

source_auditor.py 是 v2.1.0 引入的 AI 驱动 SAST（Static Application Security Testing）框架。它通过对源码进行静态扫描，结合 AI 推理识别缓冲区溢出、命令注入、不安全反序列化等常见漏洞模式，从而把"二进制分析平台"扩展为同时覆盖源码安全的工具链 资料来源：reversecore_mcp/tools/analysis/source_auditor.py。

反汇编与反编译工具集

radare2/ 子模块是平台反汇编能力的核心。radare2_mcp_tools.py 通过 r2pipe 与 radare2 进行交互，封装了常见的反汇编命令（如 pdf、afl、iz 等），并提供函数级会话管理；v2.0.4 修复了 r2pipe 在会话创建时未及时打开的问题，避免了首次调用失败 资料来源：reversecore_mcp/tools/radare2/radare2_mcp_tools.py。

r2ghidra_tools.py 在 radare2 之上集成了 Ghidra 的反编译能力，将汇编指令还原为类 C 伪代码，便于人工审计复杂函数逻辑。两者组合形成了"汇编视图 + 伪代码视图"的双重视角，使得 AI 客户端既能获得底层控制流信息，也能获得高层语义摘要 资料来源：reversecore_mcp/tools/radare2/r2ghidra_tools.py。

恶意软件与模式检测工具集

malware/ 子模块专注于威胁识别。dormant_detector.py 用于检测二进制中"休眠"或"延迟触发"的代码片段，例如长时间睡眠、WaitForSingleObject 大参数、自修改解密循环等典型规避技术。在 v2.0.5 中，平台还引入了 YARA 模式匹配能力，包含 25 条覆盖 Windows API、shellcode、进程注入等场景的规则，并支持多二进制批量扫描与 JSON 报告输出 资料来源：reversecore_mcp/tools/malware/dormant_detector.py。

工具注册与调用机制

所有工具通过统一的 MCP 注册机制对外暴露。v2.0.6 的"Comprehensive MCP Tool Invocation"测试套件验证了 run_file、r2_*、yara_*、capa_* 等所有已注册工具均可被自动发现并调用，确保 LLM 客户端在不修改配置的前提下即可使用新增能力。这种"工具即函数"的模型，使得分析能力可以像插件一样持续扩展，而无需改动 MCP 协议本身 资料来源：reversecore_mcp/tools/analysis/static_analysis.py。

演进与扩展性

从 1.x 到 v3.0.0，工具目录经历了"基础反汇编 → 高级分析 → 源码审计 → 动态分析"的演进。v3.0.0 的 102 个提交中新增了完整的动态分析模块，与现有静态工具形成互补，标志着平台从"纯静态"转向"动静结合"的综合分析平台 资料来源：reversecore_mcp/tools/radare2/radare2_mcp_tools.py。

部署架构

Reversecore MCP 采用"基础镜像 + 应用镜像"的分层 Docker 模式构建。Dockerfile.base 负责预装逆向分析依赖链（Python 运行时、radare2、r2pipe、Yara 规则编译环境等），Dockerfile 在其之上安装 Python 包与 MCP 服务入口，二者通过 docker-compose.yml 编排。v2.0.6 起，集成测试改为在容器内运行以贴合生产环境 资料来源：docker-compose.yml:1-40。

flowchart LR
  A[开发者机器] --> B[docker-compose up]
  B --> C[Dockerfile.base<br/>逆向分析工具栈]
  C --> D[Dockerfile<br/>Python + MCP 服务器]
  D --> E[MCP 客户端<br/>Claude / IDE 插件]
  D --> F[挂载卷<br/>样本目录 / Yara 规则]
  D --> G[网络出口<br/>EGRESS 白名单]

关键环境变量

完整变量清单见 资料来源：.env.example:1-30。

安全模型

Reversecore MCP 的核心假设是"输入样本不可信"，因此安全边界围绕沙箱化、最小特权与可审计性展开。

静态侧：SAST 框架

v2.1.0 引入的 AI 辅助 SAST（Static Application Security Testing）模块在不执行样本的前提下对二进制与反汇编产物进行扫描，并保留规则命中证据。框架输出结构化 JSON 报告，便于在 CI 中作为门禁 资料来源：README.md:1-80。

动态侧：沙箱与权限

动态分析在容器内受限于 seccomp 与 capabilities 默认拒绝策略；网络访问通过 ALLOW_NETWORK 显式开关，避免样本回连。Yara 规则集覆盖 Windows API、shellcode、进程注入等 25 类模式，可在分析前对样本进行预筛 资料来源：Dockerfile.base:1-60。

工具调用边界

所有 MCP 工具（run_file、r2_* 命令族、Yara 扫描等）必须经过注册表校验，v2.0.6 引入的"综合工具调用"测试会枚举并调用每个注册项以保证清单一致 资料来源：README.md:81-160。

开发与 CI/CD

本地开发循环

git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pre-commit install

提交前由 .pre-commit-config.yaml 触发钩子，覆盖代码格式化、敏感信息扫描与基础 Lint 资料来源：.pre-commit-config.yaml:1-25。

CI 流水线

CI 在每次推送和 PR 时构建 Dockerfile.base 与 Dockerfile，随后在容器内执行 pytest 集成套件，确保 MCP 工具调用、Yara 匹配、radare2 会话开启等行为在生产等价环境中通过 资料来源：docker-compose.yml:40-80。

依赖治理

requirements.txt 锁定运行时版本，CI 中通过 pip check 与已知漏洞扫描双重校验；新增依赖需在 PR 中注明安全评估结论。

贡献指引要点

• 任何新增 MCP 工具必须在测试套件中注册其调用样例
• 涉及 shell/system 调用的代码须走 SAST 扫描并附报告
• Yara 规则新增需附带误报样本说明
• 容器相关变更需同步更新 .env.example 与文档

遵循以上约束可保证动静态分析能力在持续迭代中保持可复现与可审计，支撑 v3.0.0 引入的完整动态分析栈 资料来源：README.md:160-240。

Pitfall Log / 踩坑日志

项目：sjkim1127/Reversecore_MCP

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

1. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -i --rm -v /path/to/your/samples:/app/workspace -e REVERSECORE_WORKSPACE=/app/workspace -e MCP_TRANSPORT=stdio ghcr.io/sjkim1127/reversecore_mcp:latest
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -i --rm -v /path/to/your/samples:/app/workspace -e REVERSECORE_WORKSPACE=/app/workspace -e MCP_TRANSPORT=stdio ghcr.io/sjkim1127/reversecore_mcp:latest
• 证据：identity.distribution | https://github.com/sjkim1127/Reversecore_MCP | docker run -i --rm -v /path/to/your/samples:/app/workspace -e REVERSECORE_WORKSPACE=/app/workspace -e MCP_TRANSPORT=stdio ghcr.io/sjkim1127/reversecore_mcp:latest

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/sjkim1127/Reversecore_MCP | host_targets=mcp_host, claude, cursor

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/sjkim1127/Reversecore_MCP | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/sjkim1127/Reversecore_MCP | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/sjkim1127/Reversecore_MCP | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/sjkim1127/Reversecore_MCP | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/sjkim1127/Reversecore_MCP | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/sjkim1127/Reversecore_MCP | release_recency=unknown