Reversecore_mcp

Reversecore MCP

通过 Model Context Protocol 实现 AI 驱动的逆向工程与安全分析

一个 MCP 服务，让 Claude 和 Cursor 等 AI 助手能够通过自然语言执行逆向工程、恶意软件分析、漏洞研究、数字取证和源代码审计。

---

目录

• Reversecore MCP 是什么？
• 架构
• 工具目录（177 个工具）
• 引导式分析提示词（22 种模式）
• MCP 资源（11 个 URI）
• 快速开始
• 连接到你的 AI 客户端
• 配置
• 安全模型
• 开发
• CI/CD 流水线
• Docker 构建架构
• 系统要求
• 项目结构
• 错误处理
• 添加新工具
• 贡献
• 文档
• 许可证

Reversecore MCP 是什么？

Reversecore MCP 是一个 Model Context Protocol 服务，将 177 个分析工具封装到一个统一接口中，AI 助手可以通过自然语言调用这些工具。

无需学习十几种不同工具的命令行语法，只需描述你的需求：

"Decompile the main function of this malware sample, extract all network IOCs,
 map the behavior to MITRE ATT&CK, and generate a triage report."

AI 助手会将其拆解为多个工具调用：

r2_decompile("sample.exe", "main")
  → extract_iocs("sample.exe")
    → add_mitre_technique(technique_id="T1071.001", ...)
      → create_analysis_report(template_type="quick_triage")

每个工具都会返回结构化的 ToolResult（ToolSuccess 或 ToolError），其中包含类型化数据，AI 可以据此进行推理、串联后续查询，或将结果呈现给用户。

覆盖范围

架构

AI Client (Claude / Cursor / any MCP-compatible client)
        │  MCP Protocol (stdio or HTTP/SSE)
        ▼
┌──────────────────────────────────────────────────────┐
│                   FastMCP 3.4.4 Server               │
│          177 registered tools · Fully async          │
│                  Python 3.10–3.12                    │
├────────────────────┬─────────────────────────────────┤
│   Guided Prompts   │  Dynamic Resources              │
│  (22 analysis      │  (11 URI-based: per-binary      │
│   modes)           │   strings, IOCs, ASM, CFG, …)   │
├────────────────────┴─────────────────────────────────┤
│                  Core Infrastructure                 │
│  Config · Security · Validators · Exceptions (17)    │
│  R2 Pool · Metrics · Memory (SQLite) · Task Queue    │
│  MITRE Mapper · Evidence Engine · Resilience Layer   │
│  Arch Registry (x86/ARM/MIPS/RISC-V/PPC)            │
│  Result Cache (SHA256) · Analysis Cache (Redis+SQL)  │
│  SAST (Python AST + C/C++ Regex) · Plugin System     │
├──────────────────────────────────────────────────────┤
│                 Analysis Engines                     │
│  Radare2 6.0.4     │  YARA 4.3.1 · LIEF · Capstone  │
│  r2ghidra           │  CAPA · angr · Qiling          │
│  Volatility3 · Scapy│ DIE · Binwalk · Sleuth Kit    │
│  pwntools · ROPgadget│ Keystone (assembler)          │
└──────────────────────────────────────────────────────┘

该服务支持 Python 3.10–3.12。可选的 angr 符号执行引擎会安装在 Python 3.12 及更高版本中，因为这些版本有安全且兼容的发行版；Python 3.10 和 3.11 的安装不会包含 angr。

核心基础设施（37 个模块）

reversecore_mcp/core/ 目录包含所有工具所依赖的共享基础设施：

工具目录（177 个工具）

📖 权威工具目录与参数参考（151 个工具） 📊 工具配置文件占用与上下文基准矩阵

每个工具都会返回结构化的 ToolResult——包含类型化 data 的 ToolSuccess，或带有 RCMCP-E* 错误代码的 ToolError。工具划分为 11 个领域插件，分布在 5 种模块化执行配置中（full、static、malware、forensics、vuln-research）：

🔍 静态分析插件（24 个工具）

🔐 源代码审计插件（1 个工具）

🛠️ 常用实用工具插件（20 个工具）

文件操作（5 个工具）

补丁说明（1 个工具）

汇编器（1 个工具）

AI 记忆管理（11 个工具）

这些工具可让 AI 使用异步 SQLite 数据库，在不同分析会话间持久化和回忆分析结果：

服务监控（2 个工具）

⚙️ Radare2 和 r2ghidra 插件（30 个工具）

所有 Radare2 工具都使用线程安全的连接池（r2_pool.py），自动管理 r2pipe 会话。

🦠 恶意软件分析插件（9 个工具）

🕵️ 数字取证插件（22 个工具）

内存取证（6 个工具）

磁盘取证（6 个工具）

网络取证（5 个工具）

工件分析（5 个工具）

📝 报告生成插件（14 个工具）

引导式分析提示词（22 种模式）

提示词是预先构建的分析工作流，可为 AI 提供结构化角色、分步工具使用流程和证据分类规则。在 AI 客户端中引用提示词名称即可启用。

恶意软件分析（9 个提示词）

安全研究（6 个提示词）

CVE 研究与漏洞利用开发（5 个提示词）

其他（2 个提示词）

**提示词的工作方式：**每个提示词都会为 AI 设定一个结构化的分析角色。其中包含思维链推理检查点（AI 必须暂停并评估后才能继续），以及证据分类规则，防止 AI 将猜测陈述为事实。每项发现都必须标记为 OBSERVED（已直接验证）、INFERRED（通过静态分析逻辑推导得出）或 POSSIBLE（需要进一步验证）。

MCP 资源（11 个 URI）

资源是只读数据端点，AI 客户端可通过 URI 模板访问。资源通过提供结构化数据来补充工具，无需显式调用工具。

静态资源

动态资源（每个二进制文件的虚拟文件系统）

这些 URI 会针对每个二进制文件进行解析，并按需调用相应的分析工具：

快速开始

选项 1 — PyPI（最简单）

pip install reversecore-mcp
reversecore-mcp

先决条件： 系统上必须已安装 Radare2（r2 --version）。YARA 会通过 yara-python 自动安装。

选项 2 — Docker（推荐，可获得完整功能）

所有分析引擎（Radare2、r2ghidra、YARA、Binwalk、Sleuth Kit、GDB 等）均已预装：

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

选项 3 — 从源代码构建（Docker Compose）

git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
./scripts/run-docker.sh        # auto-detects Intel / Apple Silicon

或者手动操作：

docker compose --profile x86 up -d    # Intel/AMD
docker compose --profile arm64 up -d  # Apple Silicon (M1/M2/M3)

选项 4 — Python（本地开发）

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
python -m reversecore_mcp.server

本地模式的先决条件： 系统上必须已安装 Radare2（r2 --version）。各个工具后端（YARA、LIEF、Capstone 等）通过 pip 安装。要获得完整的取证支持，还需要 Volatility3、Scapy 和 Sleuth Kit。

连接到 AI 客户端

将服务配置添加到 IDE 客户端设置中（例如，~/.cursor/mcp.json 或 claude_desktop_config.json）。

⚡ 选项 1：Docker Exec 模式（推荐）

如果你通过 Docker Compose 运行了容器，此模式会将 stdio 直接传入正在运行的容器。启动延迟为零、内存持久保留，且可使用所有工具。

{
  "mcpServers": {
    "Reversecore_MCP": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "reversecore-mcp-arm64",
        "python",
        "-m",
        "reversecore_mcp.server"
      ]
    }
  }
}

如果你使用的是 Intel/AMD，请将 reversecore-mcp-arm64 替换为 reversecore-mcp。

🌐 选项 2：SSE HTTP 模式

用于基于网络的流式传输（服务器发送事件）：

{
  "mcpServers": {
    "Reversecore_MCP": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

📦 选项 3：Stdio 模式（按需启动 Docker）

每个会话都会启动一个全新且隔离的容器：

{
  "mcpServers": {
    "reversecore": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USERNAME/samples:/app/workspace",
        "-e", "REVERSECORE_WORKSPACE=/app/workspace",
        "-e", "MCP_TRANSPORT=stdio",
        "ghcr.io/sjkim1127/reversecore_mcp:latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "reversecore": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/YOUR_USERNAME/samples:/app/workspace",
        "-e", "REVERSECORE_WORKSPACE=/app/workspace",
        "-e", "MCP_TRANSPORT=stdio",
        "ghcr.io/sjkim1127/reversecore_mcp:latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "reversecore": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:/samples:/app/workspace",
        "-e", "REVERSECORE_WORKSPACE=/app/workspace",
        "-e", "MCP_TRANSPORT=stdio",
        "ghcr.io/sjkim1127/reversecore_mcp:latest"
      ]
    }
  }
}

⚠️ 重要 — Docker 内的文件路径

你的本地文件夹会挂载到容器内的 /app/workspace。 请始终仅使用文件名引用文件，不要使用本地完整路径。

❌ 错误	✅ 正确
r2_decompile("/Users/john/samples/mal.exe")	r2_decompile("mal.exe")

配置

所有设置都可以通过环境变量或 .env 文件提供（参见 .env.example）。设置通过带有 REVERSECORE_ 前缀的 Pydantic BaseSettings 管理。

核心设置

HTTP 模式设置

Radare2 设置

沙箱设置

存储与队列

日志记录

插件与 SAST

安全模型

安全性通过纵深防御实现，在多个层面提供保护：

输入与路径安全

网络与身份验证

容器与运行时

CI/CD 安全关卡

结构化错误处理

全部 17 个异常类均带有 RCMCP-E* 错误代码，以便通过程序处理。完整层级请参阅错误处理。

开发

设置

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
pip install -r requirements-dev.txt
pre-commit install   # installs Ruff, Bandit, Gitleaks hooks

测试

# Full test suite with coverage report
pytest tests/ -v

# Unit tests only (fast, no external dependencies)
pytest tests/unit/ -v

# Integration tests (requires Docker)
pytest tests/integration/ -v

# Run with coverage threshold enforcement
pytest tests/unit/ --cov=reversecore_mcp --cov-fail-under=80

# Run a specific test
pytest tests/unit/test_cli_tools.py::TestRunFile::test_success -v

# Security boundary tests
pytest tests/ -m security -v

# Benchmarks
pytest tests/ -m benchmark -v

测试状态：

• ✅ 1,957 个单元测试已通过，覆盖 Python 3.10 / 3.11 / 3.12
• 📊 87% 代码覆盖率（CI 强制要求最低 80%）
• 🔒 Bandit 零发现项
• ⚡ 通过 pytest-asyncio 实现完全异步的测试套件

测试标记：

代码质量

ruff check reversecore_mcp/      # Lint (E, W, F, I, B, C4, UP rules)
ruff format reversecore_mcp/     # Format
mypy reversecore_mcp/            # Type check (0 errors across 108 files)
bandit -r reversecore_mcp/       # Security scan (all severities)
pip-audit                        # Dependency CVE scan

Pre-commit 钩子

每次提交时都会自动运行以下钩子：

1. Ruff — lint 并自动修复，同时检查格式
2. trailing-whitespace — 删除行尾空格
3. end-of-file-fixer — 确保文件以换行符结尾
4. check-yaml / check-json — 验证 YAML/JSON 语法
5. check-added-large-files — 阻止大小超过 1 MB 的文件
6. check-merge-conflict — 检测未解决的合并标记
7. detect-private-key — 防止意外提交密钥
8. Bandit — Python 安全扫描

CI/CD 流水线

每次推送到 main 都会触发 11 个流水线任务。部署前所有任务都必须通过。

 Lint & Security Gate              Unit Tests (Python Matrix)
   ├─ Gitleaks (secret scan)         ├─ pytest 3.10 --cov-fail-under=80
   ├─ Hadolint (Dockerfile lint)     ├─ pytest 3.11 --cov-fail-under=80
   ├─ Ruff check + format            └─ pytest 3.12 --cov-fail-under=80
   ├─ Mypy type check (108 files)
   ├─ Bandit (all severities)      Wheel Smoke Test
   ├─ pip-audit (no CVEs)            └─ Build wheel → install in /tmp
   └─ Security boundary tests            → verify plugin discovery
                                          → assert __file__ under sys.prefix
 CodeQL Analysis
   └─ Python SAST                  Docker Verification
                                     ├─ Build reversecore-mcp:ci
 Exploit Safety Gate                 ├─ Trivy container scan
   ├─ Bandit on POC templates        ├─ Image size check (< 5 GB)
   ├─ Hypothesis DAST fuzzing        ├─ CLI tool verification
   ├─ Performance benchmarks         ├─ Integration tests in container
   └─ Container isolation test       └─ E2E tool invocation

 In-Container Smoke Test           Build Base Image (amd64 + arm64)
   ├─ Copy test ELF into container   ├─ Compile YARA 4.3.1
   └─ Run scripts/smoke_test.py     ├─ Compile Radare2 6.0.4
                                     ├─ Compile r2ghidra
 Deploy (amd64 + arm64)             └─ Push to GHCR
   ├─ Build app image
   ├─ Push to GHCR                 Merge Manifests
   └─ Trivy rescan on published     └─ Multi-arch manifest → :latest

**零绕过策略：**绝不会通过修改流水线配置来解决 CI/CD 失败。始终直接在源代码或依赖项中修复根本原因。

Docker 构建架构

Docker 构建采用双层方案，以控制构建耗时：

第 1 层：基础镜像（Dockerfile.base）

多阶段构建，从源代码编译所有构建缓慢且很少变更的依赖项：

compiler-toolchain (python:3.12-slim-bookworm + build tools)
    ├── compiler-yara      (YARA 4.3.1 from source)     [parallel]
    ├── compiler-r2        (Radare2 6.0.4 from source)   [parallel]
    │     └── compiler-r2ghidra  (r2ghidra plugin)       [sequential]
    └── compiler-pip       (pip install into /opt/venv)  [parallel]

base (final runtime: python:3.12-slim-bookworm)
    ├── Runtime packages: file, binutils, gdb, binwalk, graphviz, nasm, sleuthkit
    ├── /opt/yara (compiled YARA)
    ├── /opt/radare2 (compiled r2 + r2ghidra)
    ├── /opt/venv (Python packages)
    └── Non-root user: appuser (UID 1000)

仅在工具版本发生变化时才会重建此镜像。构建耗时：约 12 分钟。

第 2 层：应用镜像（Dockerfile）

基于基础镜像，并复制应用代码：

FROM base image
    ├── COPY reversecore_mcp/ (application code)
    ├── COPY scripts/ (smoke test, benchmarks)
    ├── pip install any new requirements
    ├── Security package upgrades
    └── CMD ["python", "-m", "reversecore_mcp.server"]

构建耗时：约 60 秒。

Docker Compose

包含 3 个服务，并使用特定架构的配置文件：

资源限制：每个容器使用 2.0 个 CPU 核心、4 GB 内存。

系统要求

项目结构

reversecore_mcp/
├── core/                          # Infrastructure layer (37 modules)
│   ├── config.py                  # Pydantic BaseSettings (34+ env vars)
│   ├── exceptions.py              # Exception hierarchy (17 classes, RCMCP-E* codes)
│   ├── security.py                # Input sanitization & command arg validation
│   ├── validators.py              # Path validators (TOCTOU-hardened, symlink-safe)
│   ├── r2_pool.py                 # Thread-safe Radare2 connection pool
│   ├── r2_helpers.py              # Structured Radare2 output parsing
│   ├── metrics.py                 # Per-tool timing, counts, error rates, cache stats
│   ├── decorators.py              # @log_execution, @track_metrics
│   ├── error_handling.py          # @handle_tool_errors decorator
│   ├── error_formatting.py        # Structured error formatting
│   ├── execution.py               # Safe subprocess with timeout/output limits
│   ├── command_spec.py            # Command specifications
│   ├── memory.py                  # Async SQLite AI memory store
│   ├── mitre_mapper.py            # MITRE ATT&CK mapping engine
│   ├── evidence.py                # Evidence classification (OBSERVED/INFERRED/POSSIBLE)
│   ├── resilience.py              # Retry, circuit-breaker, timeout patterns
│   ├── task_queue.py              # Background task queue (Redis + arq)
│   ├── extension_registry.py      # Plugin registration system
│   ├── arch_registry.py           # Multi-arch mapping (x86/ARM/MIPS/RISC-V/PPC)
│   ├── result_cache.py            # SHA256-based tool result caching
│   ├── analysis_cache.py          # Multi-level decompilation cache (Redis + SQLite)
│   ├── result.py                  # ToolSuccess / ToolError Pydantic models
│   ├── loader.py                  # Dynamic tool module loader
│   ├── plugin.py                  # Plugin base class
│   ├── extension.py               # Extension base class
│   ├── container.py               # Container/sandbox execution
│   ├── audit.py                   # Audit logging
│   ├── binary_cache.py            # Binary file caching
│   ├── json_utils.py              # orjson-backed JSON (3-5x faster)
│   ├── logging_config.py          # Loguru logging configuration
│   ├── report_generator.py        # Report rendering (Markdown, PDF)
│   ├── resource_manager.py        # MCP resource lifecycle
│   └── sast/                      # Source code scanners
│       ├── python_ast_scanner.py  # Python AST vulnerability scanner
│       ├── regex_scanner.py       # C/C++ regex vulnerability scanner
│       ├── rule_manager.py        # SAST rule loader
│       └── default_rules.yaml     # Default scanning rules
│
├── tools/                         # MCP tool implementations (177 tools)
│   ├── analysis/                  # Static analysis (24 tools)
│   │   ├── static_analysis.py     # file, strings, binwalk
│   │   ├── lief_tools.py          # LIEF binary parser
│   │   ├── capa_tools.py          # CAPA capability detection
│   │   ├── die_tools.py           # Detect It Easy packer detection
│   │   ├── diff_tools.py          # Binary diffing
│   │   ├── emulation_tools.py     # ESIL emulation
│   │   ├── fuzz_tools.py          # Fuzzing harness generator
│   │   ├── fuzzing_campaign.py    # Full fuzzing campaign runner
│   │   ├── symbolic_analysis.py   # angr symbolic execution
│   │   ├── signature_tools.py     # Library signature matching
│   │   ├── source_auditor.py      # SAST (Python + C/C++)
│   │   ├── crash_triage.py        # GDB crash triage
│   │   ├── taint_analysis.py      # Source→sink taint tracing
│   │   ├── advanced_yara.py       # Advanced YARA generation
│   │   ├── patch_vuln_inference.py # Patch vulnerability inference
│   │   └── cache_tools.py         # Analysis cache management
│   │
│   ├── radare2/                   # Disassembly & decompilation (30 tools)
│   │   ├── radare2_mcp_tools.py   # Core Radare2 tool set
│   │   ├── r2ghidra_tools.py      # r2ghidra decompiler (cached)
│   │   ├── r2_analysis.py         # Deep function analysis
│   │   ├── r2_db.py               # SQLite annotation + cache DB
│   │   ├── r2_esil_simulator.py   # Multi-arch ESIL simulator
│   │   └── r2_session.py          # Stateful analysis sessions
│   │
│   ├── malware/                   # Threat detection (9 tools)
│   │   ├── dormant_detector.py    # Backdoor/logic bomb detection
│   │   ├── ioc_tools.py           # IOC extraction
│   │   ├── yara_tools.py          # YARA scanning
│   │   ├── adaptive_vaccine.py    # YARA rule + patch generation
│   │   ├── vulnerability_hunter.py # Dangerous API detection
│   │   ├── autonomous_hunter.py   # Autonomous vuln hunting pipeline
│   │   ├── heap_exploit.py        # Heap exploitation analysis
│   │   ├── poc_generator.py       # PoC exploit generation
│   │   └── rop_builder.py         # ROP chain construction
│   │
│   ├── forensics/                 # Digital forensics (22 tools)
│   │   ├── memory.py              # Volatility3 memory forensics
│   │   ├── network.py             # Scapy PCAP analysis
│   │   ├── disk.py                # Sleuth Kit disk forensics
│   │   └── artifact.py            # Browser/registry/event log analysis
│   │
│   ├── report/                    # Report generation (14 tools)
│   │   ├── report_mcp_tools.py    # MCP-registered report tools
│   │   ├── report_tools.py        # Report rendering logic
│   │   ├── session.py             # Session state management
│   │   ├── converter.py           # Format conversion (Markdown → PDF/HTML)
│   │   ├── email.py               # SMTP report delivery
│   │   ├── sigma_generator.py     # SIGMA rule generation
│   │   └── vex_generator.py       # VEX report generation
│   │
│   └── common/                    # Shared utilities (20 tools)
│       ├── file_operations.py     # File ops, workspace management
│       ├── server_tools.py        # Server health, tool metrics
│       ├── memory_tools.py        # AI memory management (11 tools)
│       ├── patch_explainer.py     # Binary patch explanation
│       └── assembler.py           # Keystone assembler
│
├── prompts/                       # AI reasoning prompts (22 modes)
│   ├── malware.py                 # 9 malware analysis prompts
│   ├── security.py                # 6 security research prompts
│   ├── cve_research.py            # 5 CVE/exploit research prompts
│   ├── game.py                    # Game client analysis prompt
│   ├── report.py                  # Report generation prompt
│   ├── server_health.py           # Server inspection prompts
│   └── common.py                  # Shared constants (DOCKER_PATH_RULE, LANGUAGE_RULE)
│
├── dashboard/                     # Web dashboard (FastAPI + HTMX)
│   ├── templates/                 # Jinja2 templates with HTMX fragments
│   └── static/                    # htmx.min.js (local, CSP-compliant)
│
├── web/                           # HTTP transport layer
│   ├── auth.py                    # API key authentication middleware
│   ├── middleware.py              # Security headers, loopback restriction
│   └── endpoints.py               # /health, file upload, dashboard routes
│
├── resources.py                   # 11 MCP resources (static + dynamic per-binary)
└── server.py                      # FastMCP server entry point

其他目录：

tests/
├── unit/                          # 1,957 unit tests
├── integration/                   # Docker-based integration tests
├── fixtures/                      # Test binaries, YARA rules, sample data
└── conftest.py                    # Shared pytest fixtures

scripts/
├── smoke_test.py                  # Multi-layer in-container smoke test
├── check_release_metadata.py      # Version consistency validation
├── fetch_test_binaries.py         # Download test fixtures
├── run-docker.sh                  # Auto-detect architecture and start
└── ...                            # Benchmarks, analysis scripts

docs/
├── getting-started/               # Installation guide
├── development/                   # Architecture, contributing, testing guides
├── api/                           # Tool and module reference
└── user-guide/                    # Analysis workflows

错误处理

所有自定义异常都继承自 ReversecoreError，并携带结构化错误代码：

AI 客户端可以使用 error_code 字段以编程方式处理失败，并决定是重试、尝试其他工具，还是向用户报告错误。

添加新工具

按照以下模式添加新的 MCP 工具：

# reversecore_mcp/tools/analysis/my_tool.py

from reversecore_mcp.core.decorators import log_execution
from reversecore_mcp.core.result import ToolResult, success, failure
from reversecore_mcp.core.security import validate_file_path


@log_execution()
async def my_analysis_tool(
    file_path: str,
    option: str | None = None,
) -> ToolResult:
    """Analyze a binary for X.

    Args:
        file_path: Path to the binary file (relative to workspace).
        option: Optional analysis option.

    Returns:
        ToolResult with status='success' and structured content.
    """
    try:
        safe_path = validate_file_path(file_path)
        result = await perform_analysis(safe_path)
        return success({"result": result})
    except Exception as e:
        return failure(
            error_code="RCMCP-E100",
            message=str(e),
            hint="Check that the file exists and is a valid binary.",
        )

然后在相应插件的 __init__.py 中注册该工具，并在 tests/unit/ 中添加测试。

贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feat/my-feature
3. 随代码编写测试——覆盖率不得低于 80%
4. 确保所有检查均通过：pytest、ruff check、mypy、bandit
5. 提交清晰描述变更内容的拉取请求

请阅读贡献指南，了解代码规范、文档字符串约定（Google 风格）以及拉取请求检查清单。

文档

使用示例

示例 1：基本恶意软件初步分析

User: "Analyze this suspicious file sample.exe"

AI calls:
  1. run_file("sample.exe")           → PE32 executable, x86, MSVC
  2. detect_packer("sample.exe")      → Not packed
  3. extract_iocs("sample.exe")       → 3 IPs, 2 URLs, 1 mutex
  4. run_capa("sample.exe")           → "creates persistence", "encrypts data"
  5. dormant_detector("sample.exe")   → 2 orphan functions with network calls
  6. generate_yara_rule("sample.exe") → Detection rule generated

AI response: "This PE32 binary shows ransomware-like behavior. CAPA detected
encryption and persistence capabilities. I found 2 hidden network functions
that may serve as a backup C2 channel. Here's a YARA rule for detection..."

示例 2：使用污点分析进行漏洞研究

User: "Find exploitable bugs in this network daemon"

AI activates: taint_analysis_mode

AI calls:
  1. taint_trace("daemon", verify_with_angr=True)
     → Found 3 source→sink paths:
       recv() → strcpy()   [CWE-120, CONFIRMED by angr]
       read() → sprintf()  [CWE-134, LIKELY]
       getenv() → system() [CWE-78, POSSIBLE]

  2. vulnerability_hunter("daemon")
     → 12 dangerous API calls, 4 exploitable patterns

  3. generate_poc_exploit(target="daemon", vuln_type="bof", offset=128)
     → Python exploit script generated

AI response: "I found a confirmed stack buffer overflow where recv() data
flows directly into strcpy() at 0x40123C. angr proved the path is reachable.
Here's a working PoC..."

示例 3：数字取证调查

User: "Analyze this memory dump from a compromised server"

AI calls:
  1. memory_list_processes("memdump.raw")
     → 47 processes, 2 with suspicious names

  2. memory_detect_injections("memdump.raw")
     → Code injection detected in PID 1842 (svchost.exe)

  3. memory_extract_strings("memdump.raw", pid=1842)
     → C2 domain strings extracted

  4. artifact_correlate_ioc(artifacts={"domains": ["evil-c2.com"]})
     → Matches known APT group IOCs

  5. create_analysis_report(template_type="full_analysis")
     → PDF report with timeline and MITRE ATT&CK mapping

示例 4：用于 1-day 研究的补丁差异分析

User: "Compare the patched and unpatched versions to find what was fixed"

AI activates: patch_diff_auto_mode

AI calls:
  1. diff_binaries("libfoo-1.0.so", "libfoo-1.1.so")
     → 3 functions changed, 1 new function

  2. patch_diff_1day("libfoo-1.0.so", "libfoo-1.1.so")
     → Automated analysis: bounds check added at parse_header()

  3. r2_decompile("libfoo-1.0.so", "parse_header")
     → Decompiled vulnerable version (no bounds check)

  4. r2_decompile("libfoo-1.1.so", "parse_header")
     → Decompiled patched version (memcpy size limited)

AI response: "The patch adds a bounds check in parse_header() at 0x12340.
The old version copies user-controlled length bytes via memcpy without
validation, creating a heap buffer overflow (CWE-122)."

多架构支持

arch_registry.py 模块将架构名称映射到 Radare2 配置参数，使工具无需手动配置即可适用于不同的 CPU 架构：

别名解析会自动处理：

• amd64 → x86_64
• aarch64 → arm64
• arm 搭配 bits=64 → arm64
• arm 搭配 bits=16 或 bits=32 → arm32

Radare2_esil_emulate、assemble_instructions 和 r2_simulate_patch 等工具会使用此注册表，为任何目标二进制文件正确配置分析环境。

结果缓存系统

两层缓存可尽量减少重复计算：

工具结果缓存（result_cache.py）

@cache_tool_result 装饰器根据二进制文件的 SHA256 哈希值和工具的关键字参数缓存任意工具的输出：

Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )

**存储后端：**通过 r2_db.py 使用 SQLite 数据库，可通过 get_cached_result() 和 set_cached_result() 工具访问。

**指标：**通过 metrics_collector.record_cache_hit() 和 record_cache_miss() 记录缓存命中和未命中情况，可通过 get_tool_metrics 工具查看。

分析缓存（analysis_cache.py）

专为反编译结果（计算开销较大）设计的多级缓存：

导入/导出：export_analysis_cache 和 import_analysis_cache 工具可将缓存状态保存到 rcpack 文件或从中导入，以便在不同环境之间共享。

AI 记忆系统

AI 记忆系统（memory_tools.py + core/memory.py）可跨会话持久存储并查询分析发现。这使 AI 能够：

• 记住 先前对某个二进制文件的发现
• 交叉引用 不同样本之间的发现
• 按主题、恶意软件家族或技术标记并搜索会话

工作原理

create_memory_session("analysis of ransomware sample")
    │
    ├── store_analysis_finding("Found AES-256 encryption at 0x401000", tags=["crypto", "ransomware"])
    ├── store_analysis_finding("C2 beacon interval: 30 seconds", tags=["c2", "network"])
    └── tag_analysis_session(tags=["ransomware", "financial-sector"])

# Later, in a different session:
query_analysis_memories("ransomware encryption")
    → Returns previous findings about ransomware encryption patterns

get_binary_analysis_context("sample.exe")
    → Returns all findings ever recorded for this binary

**存储：**使用异步 SQLite 数据库，路径由 MEMORY_DB_PATH 配置（默认值：~/.reversecore_mcp/memory.db）。

**可移植性：**使用 export_memory_store 和 import_memory_store 在不同环境之间传输整个记忆数据库。

Web 仪表盘

以 HTTP 模式（MCP_TRANSPORT=http）运行时，可通过 http://localhost:8000/dashboard 访问 Web 仪表盘。它提供：

• 支持拖放的二进制文件上传
• 实时分析状态
• 交互式函数列表和反汇编视图
• IOC 提取结果
• 服务健康状态监控

**技术栈：**FastAPI + Jinja2 模板 + HTMX（从 dashboard/static/ 本地加载；为符合 CSP 要求，不依赖 CDN）。

安全功能：

• 所有更改状态的表单均使用 CSRF 令牌
• 已启用 Jinja2 自动转义
• 显示前使用 html.escape() 清理所有用户输入
• 通过 validate_file_path() 防止路径遍历

部署

生产环境检查清单

部署到生产环境之前：

健康检查

该服务提供用于编排的 HTTP 健康检查端点：

# Liveness (always 200 if process is running)
curl http://localhost:8000/health/live

# Readiness (checks tool availability)
curl http://localhost:8000/health/ready

# Full health (requires API key if configured)
curl -H "X-API-Key: <key>" http://localhost:8000/health

这些端点无需通过 API 密钥身份验证，供负载均衡器和容器编排器探测。

容器健康检查

Docker 镜像内置了 HEALTHCHECK 指令，每隔 30 秒检查一次与端口 8000 的 TCP 连接。Docker 和 Kubernetes 会自动重启状态不健康的容器。

故障排除

常见问题

docker exec reversecore-mcp-arm64 which r2 yara binwalk tsk_recover gdb

# macOS
brew install radare2 yara binwalk sleuthkit

# Ubuntu/Debian
apt install radare2 yara binwalk sleuthkit

export REVERSECORE_DEFAULT_TOOL_TIMEOUT=300  # 5 minutes

copy_to_workspace("/path/to/file.exe")

export REVERSECORE_READ_DIRS=/opt/samples,/mnt/evidence

docker compose --profile arm64 up -d

./scripts/run-docker.sh

docker compose --profile arm64 up -d   # Starts both reversecore and redis

Radare2_analyze_binary("sample.exe")
Radare2_decompile_function("sample.exe", "main")

常见问题

致谢

本项目基于众多开源项目的成果构建：

许可证

MIT — 详情请参见 LICENSE。