Reversecore MCP逆向工程服务

Unit tests only (fast, no external dependencies)

pytest tests/unit/ -v

Integration tests (requires Docker)

pytest tests/integration/ -v

System Requirements

---

Option 2 — Docker (Recommended for Full Functionality)

All analysis engines (Radare2, r2ghidra, YARA, Binwalk, Sleuth Kit, GDB, etc.) come pre-installed:

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

Option 3 — Build from Source (Docker Compose)

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

Or manually:

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

⚡ Option 1: Docker Exec Mode (Recommended)

If you have the container running via Docker Compose, this mode channels stdio directly into the running container. Zero startup latency, persistent memory, and full tool availability.

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

Replace reversecore-mcp-arm64 with reversecore-mcp if you are on Intel/AMD.

---

📦 Option 3: Stdio Mode (Docker-on-Demand)

Runs a fresh, isolated container for every session:

<details> <summary>🍎 macOS</summary>

{
  "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"
      ]
    }
  }
}

</details>

<details> <summary>🐧 Linux</summary>

{
  "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"
      ]
    }
  }
}

</details>

<details> <summary>🪟 Windows</summary>

{
  "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"
      ]
    }
  }
}

</details>

⚠️ Important — File Paths Inside Docker Your local folder is mounted to /app/workspace inside the container. Always reference files by filename only, not by your local full path. | ❌ Wrong | ✅ Correct | |---|---| | r2_decompile("/Users/john/samples/mal.exe") | r2_decompile("mal.exe") |

---

Setup

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

Docker Build Architecture

The Docker build uses a two-layer approach to keep build times manageable:

Layer 1: Base Image (`Dockerfile.base`)

A multi-stage build that compiles all slow-to-build, rarely-changing dependencies from source:

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)

This image is rebuilt only when tool versions change. Build time: ~12 minutes.

Layer 2: Application Image (`Dockerfile`)

Inherits from the base image and copies application code:

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"]

Build time: ~60 seconds.

Docker Compose

Three services with architecture-specific profiles:

Resource limits: 2.0 CPU cores, 4 GB memory per container.

---

Guided Analysis Prompts (22 Modes)

Prompts are pre-built analysis workflows that prime the AI with a structured persona, step-by-step tool usage sequences, and evidence classification rules. You activate them by referencing the prompt name in your AI client.

Quick Start

Usage Examples

Example 1: Basic Malware Triage

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..."

Example 2: Vulnerability Research with Taint Analysis

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..."

Example 3: Digital Forensics Investigation

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

Example 4: Patch Diffing for 1-day Research

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)."

---

Option 1 — PyPI (Simplest)

pip install reversecore-mcp
reversecore-mcp

Prerequisites: Radare2 must be installed on your system (r2 --version). YARA is installed automatically via yara-python.

Option 4 — Python (Local Development)

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

Prerequisites for local mode: Radare2 must be installed on your system (r2 --version). Individual tool backends (YARA, LIEF, Capstone, etc.) are installed via pip. For full forensics support, you'll also need Volatility3, Scapy, and Sleuth Kit.

---

🌐 Option 2: SSE HTTP Mode

For network-based streaming (Server-Sent Events):

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

---

Configuration

All settings can be provided via environment variables or a .env file (see .env.example). Settings are managed via Pydantic BaseSettings with the REVERSECORE_ prefix.

Core Settings

HTTP Mode Settings

Radare2 Settings

Sandbox Settings

Core Infrastructure (37 modules)

The reversecore_mcp/core/ directory contains the shared infrastructure that all tools build on:

---

🔍 Static Analysis Plugin (24 tools)

---

🔐 Source Code Audit Plugin (1 tool)

---

🛠️ Common Utilities Plugin (20 tools)

File Operations (5 tools)

Patch Explanation (1 tool)

Assembler (1 tool)

AI Memory Management (11 tools)

These tools let the AI persist and recall findings across analysis sessions using an async SQLite database:

Server Monitoring (2 tools)

---

⚙️ Radare2 & r2ghidra Plugin (30 tools)

All Radare2 tools use a thread-safe connection pool (r2_pool.py) that automatically manages r2pipe sessions.

---

🦠 Malware Analysis Plugin (9 tools)

---

🕵️ Digital Forensics Plugin (22 tools)

Memory Forensics (6 tools)

Disk Forensics (6 tools)

Network Forensics (5 tools)

Artifact Analysis (5 tools)

---

📝 Report Generation Plugin (14 tools)

---

Plugins & SAST

---

CI/CD Pipeline

Every push to main triggers 11 pipeline jobs. All must pass before deployment.

 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

Zero-bypass policy: CI/CD failures are never resolved by modifying pipeline configuration. Root causes are always fixed directly in source code or dependencies.

---