Reversecore_mcp

Reversecore MCP

Model Context Protocol による AI を活用したリバースエンジニアリングとセキュリティ分析

Claude や Cursor などの AI アシスタントが、自然言語を通じてリバースエンジニアリング、マルウェア分析、脆弱性調査、デジタルフォレンジック、ソースコード監査を実行できるようにする MCP サーバーです。

---

目次

• Reversecore MCP とは？
• アーキテクチャ
• ツール一覧（177 種類）
• ガイド付き分析プロンプト（22 モード）
• MCP リソース（11 URI）
• クイックスタート
• AI クライアントへの接続
• 設定
• セキュリティモデル
• 開発
• CI/CD パイプライン
• Docker ビルドアーキテクチャ
• システム要件
• プロジェクト構成
• エラー処理
• 新しいツールの追加
• コントリビューション
• ドキュメント
• ライセンス

Reversecore MCP とは？

Reversecore MCP は、177 個の分析ツールを単一のインターフェースにまとめ、AI アシスタントが自然言語を通じて呼び出せるようにする、Model Context Protocol サーバーです。

複数のツールのコマンドライン構文を覚える代わりに、実行したい内容を説明するだけです。

"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 ツール） 📊 ツールプロファイルのフットプリントとコンテキストのベンチマークマトリクス

すべてのツールは、型付きの data を含む ToolSuccess、または RCMCP-E* エラーコードを含む ToolError のいずれかとして、構造化された ToolResult を返します。ツールは、5 つのモジュール型実行プロファイル（full、static、malware、forensics、vuln-research）にわたる 11 のドメインプラグインに整理されています。

🔍 静的解析プラグイン（24 ツール）

🔐 ソースコード監査プラグイン（1 ツール）

🛠️ 共通ユーティリティプラグイン（20 個のツール）

ファイル操作（5 個のツール）

パッチの説明（1 個のツール）

アセンブラー（1 個のツール）

AI メモリ管理（11 個のツール）

これらのツールを使うと、非同期 SQLite データベースを使用して、AI が分析セッションをまたいで調査結果を保存し、呼び出せます。

サーバー監視（2 個のツール）

⚙️ Radare2 & r2ghidra プラグイン（30 個のツール）

Radare2 のすべてのツールは、r2pipe セッションを自動管理するスレッドセーフな接続プール（r2_pool.py）を使用します。

🦠 マルウェア解析プラグイン（9 個のツール）

🕵️ デジタルフォレンジックプラグイン（22 ツール）

メモリフォレンジック（6 ツール）

ディスクフォレンジック（6 ツール）

ネットワークフォレンジック（5 ツール）

アーティファクト分析（5 ツール）

📝 レポート生成プラグイン（14 ツール）

ガイド付き分析プロンプト（22 モード）

プロンプトは、構造化されたペルソナ、段階的なツール使用手順、証拠分類ルールを AI に設定する、事前構築済みの分析ワークフローです。AI クライアントでプロンプト名を指定すると有効になります。

マルウェア解析（9 個のプロンプト）

セキュリティ研究（6 個のプロンプト）

CVE 研究とエクスプロイト開発（5 個のプロンプト）

その他（2 個のプロンプト）

プロンプトの仕組み： 各プロンプトは、構造化された解析担当者として AI に役割を設定します。AI が次に進む前に立ち止まって評価する必要がある Chain-of-Thought 推論チェックポイントと、推測を事実として述べることを防ぐ証拠の分類ルールが含まれています。すべての調査結果には、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 モード

ネットワーク経由でストリーミングする場合（Server-Sent Events）：

{
  "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 — 自動修正付きのリンティングとフォーマットチェック
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 ビルドでは、ビルド時間を抑えるために 2 層構成を採用しています。

レイヤー 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つのサービスです。

リソース制限：コンテナあたり CPU コア 2.0、メモリ 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. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feat/my-feature
3. コードと併せてテストを作成します — カバレッジは 80% を下回ってはなりません
4. すべてのチェックに合格することを確認します：pytest、ruff check、mypy、bandit
5. 明確な説明を添えてプルリクエストを作成します

コーディング規約、docstring の規約（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
• bits=64 を指定した arm → arm64
• bits=16 または bits=32 を指定した arm → arm32

Radare2_esil_emulate、assemble_instructions、r2_simulate_patch などのツールは、このレジストリーを使用して、任意のターゲットバイナリーに適した分析環境を設定します。

結果キャッシュシステム

2 層のキャッシュにより、重複する計算を最小限に抑えます。

ツール結果キャッシュ（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() および metrics_collector.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

ストレージ： MEMORY_DB_PATH で設定したパス（デフォルト：~/.reversecore_mcp/memory.db）にある非同期 SQLite データベースです。

移植性： export_memory_store と import_memory_store を使うと、メモリーデータベース全体を環境間で転送できます。

Web ダッシュボード

HTTP モード（MCP_TRANSPORT=http）で実行すると、http://localhost:8000/dashboard から Web ダッシュボードを利用できます。以下の機能を提供します。

• ドラッグ＆ドロップによるバイナリーのアップロード
• リアルタイムの分析状況
• 関数リストと逆アセンブリ表示のインタラクティブな操作
• IOC 抽出結果
• サーバーの稼働状況の監視

技術スタック： FastAPI + Jinja2 テンプレート + HTMX（CSP への準拠のため、CDN に依存せず dashboard/static/ からローカルに読み込みます）。

セキュリティ機能：

• 状態を変更するすべてのフォームで 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 イメージには、30 秒ごとにポート 8000 への TCP 接続を確認する組み込みの HEALTHCHECK 命令が含まれています。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")

FAQ

謝辞

このプロジェクトは、多くのオープンソースプロジェクトの成果を基盤としています。

ライセンス

MIT — 詳細は LICENSE を参照してください。