Reversecore MCP

Official

by sjkim1127 · Python

Security-first MCP server for reverse engineering, malware analysis, forensics, and SAST.

Topics

mcp-serverreverse-engineeringmcpghidraradare2securitymcp-securitysast

README.md26 KBView on GitHub

Reversecore MCP

AI-Powered Reverse Engineering & Security Analysis via Model Context Protocol

Enterprise-grade integrated static & dynamic analysis server — speak natural language, get expert-level reverse engineering, vulnerability triage, malware analysis, and forensics.

Watch the Demo

What is Reversecore MCP?
Architecture
Tool Catalog (50+ Tools)
Guided Analysis Prompts
Quick Start
Connect to Your AI Client
Configuration
Security Model
Development
Project Structure
Contributing
License

What is Reversecore MCP?

Reversecore MCP is an enterprise-grade Model Context Protocol server that transforms AI assistants like Claude and Cursor into expert-level security research workstations.

It goes far beyond binary disassembly. Reversecore MCP integrates 50+ analysis tools spanning:

🔬 Static analysis — disassembly, decompilation, binary parsing
💥 Dynamic triage — GDB crash parsing, exploitability assessment
🦠 Malware analysis — capability detection, IOC extraction, threat hunting
🧬 Vulnerability research — symbolic execution, fuzzing, ROP gadget detection
🔏 SAST — source code auditing for Python, C, and C++
🕵️ Digital forensics — memory, disk, network, and artifact analysis
📊 Reporting — MITRE ATT&CK-mapped structured reports

Instead of learning complex tools by hand, you simply describe what you want in natural language:

code

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

↓

Reversecore MCP automatically invokes r2_decompile → extract_iocs → add_session_mitre → create_analysis_report, returning structured analyst-grade output.

Architecture

code

AI Client (Claude / Cursor / any MCP-compatible client)
        │  MCP Protocol (stdio or HTTP/SSE)
        ▼
┌──────────────────────────────────────────────────────┐
│                   FastMCP Server                     │
│            50+ registered tools · Async              │
│                  Python 3.10–3.12                    │
├────────────────────┬─────────────────────────────────┤
│   Guided Prompts   │  Dynamic Resources              │
│  (5 expert modes)  │  (workspace, metrics, health)   │
├────────────────────┴─────────────────────────────────┤
│                  Core Infrastructure                 │
│  Config · Security · Validators · Exception Hierarchy│
│  R2 Pool · Metrics · Memory (SQLite) · Task Queue   │
│  MITRE Mapper · Evidence Engine · Resilience Layer  │
├──────────────────────────────────────────────────────┤
│                 Analysis Engines                     │
│  Radare2 + r2ghidra  │  YARA · LIEF · Capstone      │
│  CAPA (Mandiant)     │  angr (Symbolic Execution)   │
│  Volatility3 · Scapy │  DIE · Qiling · Binwalk      │
└──────────────────────────────────────────────────────┘

Core Infrastructure Modules

Module	Purpose
`core/config.py`	Centralized environment-aware configuration
`core/security.py`	Input sanitization & path validation
`core/validators.py`	File & binary path validators
`core/r2_pool.py`	Thread-safe Radare2 connection pool
`core/r2_helpers.py`	Structured Radare2 output utilities
`core/metrics.py`	Per-tool execution times & error rates
`core/memory.py`	Async SQLite AI memory store
`core/mitre_mapper.py`	MITRE ATT&CK technique mapping engine
`core/evidence.py`	Evidence classification (OBSERVED/INFERRED/POSSIBLE)
`core/resilience.py`	Retry, circuit-breaker, timeout patterns
`core/task_queue.py`	Background task queue (Redis + arq)
`core/extension_registry.py`	Plugin/extension registration system
`core/sast/`	Python AST scanner + C/C++ regex scanner

Tool Catalog

Reversecore MCP exposes 50+ tools across 7 categories. Every tool returns a structured ToolResult with status, content, and optional error fields.

🔍 Static Analysis

Tool	Backend	Description
`run_file`	`file` CLI	File type, architecture, and compiler fingerprinting
`run_strings`	`strings` CLI	ASCII/Unicode string extraction with configurable min-length and limits
`run_binwalk`	Binwalk	Firmware deep-scan: embedded signatures, filesystems, compressed blobs
`parse_binary_with_lief`	LIEF	Full PE / ELF / Mach-O header, section, import/export, and TLS parsing
`detect_compiler_and_packer`	DIE (`diec`)	Compiler, linker, packer, and protector detection via Detect It Easy
`run_capa`	CAPA (Mandiant FLARE)	High-level capability detection — "encrypts data", "creates persistence", etc.
`audit_source_code`	AST + Regex SAST	Python AST scanner + C/C++ regex scanner for dangerous patterns

⚙️ Disassembly & Decompilation

Tool	Backend	Description
`run_radare2`	r2pipe	Raw Radare2 command execution with connection pooling
`Radare2_disassemble`	Radare2	Function disassembly with full auto-analysis (`aaa`)
`r2_decompile`	r2ghidra	High-quality C decompilation (Ghidra engine embedded in r2, no JVM)
`r2_recover_structures`	r2ghidra + SQLite	Auto-recover C structs and persist to annotation database
`r2_analyze_function`	Radare2	Deep single-function analysis with type inference and variable tracking
`r2_get_call_graph`	Radare2	Call graph extraction for a given function address
`r2_simulate_patch`	Radare2	Preview binary patch effects before applying to disk
`r2_session`	Radare2	Stateful multi-command analysis sessions
`disassemble_with_capstone`	Capstone	Multi-arch disassembly: x86/x64, ARM, MIPS, PPC, SPARC

🔗 Cross-Reference & Binary Annotation

Tool	Backend	Description
`analyze_xrefs`	Radare2	Track function calls, data references, and control flow
`r2_read_memory`	Radare2	Read raw bytes from a given virtual address
`r2_list_structures`	SQLite	List all annotated C structs from the persistent annotation DB
`r2_create_structure`	SQLite	Create and persist a new struct annotation
`r2_add_bookmark`	SQLite	Annotate an address with a persistent comment
`r2_list_bookmarks`	SQLite	List all address bookmarks across the workspace
`r2_list_types`	Radare2	List all known types in the current binary analysis

🧬 Dynamic & Symbolic Analysis

Tool	Backend	Description
`emulate_machine_code`	Radare2 ESIL	Register/memory-traced code emulation without running the binary
`verify_path_and_get_args`	angr	Symbolic execution — prove path reachability and compute concrete inputs
`generate_fuzzing_harness`	Qiling + AFL++	Auto-generate a Qiling-based fuzzing harness targeting a specific function
`diff_binaries`	Radare2	Semantic binary diff to track patch changes between versions
`match_libraries`	Radare2	Identify statically linked libraries by function fingerprint matching

🦠 Malware Analysis & Threat Detection

Tool	Backend	Description
`dormant_detector`	Radare2 + heuristics	Find hidden backdoors, orphan functions, time-bombs, and logic bombs
`extract_iocs`	Regex + LIEF	Extract IPs, URLs, domains, hashes, registry keys, crypto addresses
`run_yara`	YARA	YARA rule scanning with custom rule files and built-in rulesets
`adaptive_vaccine`	YARA + Radare2	Generate detection YARA rules + binary patches to neutralize a threat
`vulnerability_hunter`	Radare2 + analysis	Detect dangerous API patterns (strcpy, sprintf) and ROP gadget chains

📝 Session Tracking & Report Generation

Tool	Description
`start_analysis_session`	Start a timed analysis session with unique session ID
`add_session_ioc`	Collect and tag IOCs during a live session
`add_session_mitre`	Document MITRE ATT&CK technique IDs during analysis
`end_analysis_session`	Finalize session: computes duration, locks IOC/ATT&CK lists
`create_analysis_report`	Render session report in 4 modes: `full` / `triage` / `ioc_summary` / `executive`
`generate_malware_submission`	One-shot standardized JSON submission report
`send_report_email`	Deliver rendered report via SMTP

🕵️ Digital Forensics

Tool	Backend	Description
`analyze_memory_dump`	Volatility3	Full memory forensics: process list, network connections, injected code, handles
`analyze_network_capture`	Scapy	PCAP analysis: protocol breakdown, DNS queries, HTTP payloads, anomalies
`analyze_disk_image`	The Sleuth Kit	Filesystem forensics: deleted files, timeline reconstruction, metadata
`analyze_artifacts`	Custom parsers	Browser history, Windows registry hives, event logs, prefetch files

📊 Server Health & Workspace

Tool	Description
`get_server_health`	Uptime, memory usage, loaded tools, and operational status
`get_tool_metrics`	Per-tool call counts, mean execution times, and error rates
`list_workspace`	List all files available in the analysis workspace
`get_file_info`	Metadata for a specific workspace file (size, hash, type)

Guided Analysis Prompts

Activate expert analysis modes by referencing these prompts in your AI client:

Prompt	Use Case
`full_analysis_mode`	6-phase comprehensive analysis: triage → disassembly → behavior → network → persistence → report
`basic_analysis_mode`	Rapid triage for initial assessment and quick verdicts
`game_analysis_mode`	Game client analysis with anti-cheat detection and memory inspection
`firmware_analysis_mode`	IoT/embedded firmware: binwalk extraction, UART strings, hardcoded credentials
`report_generation_mode`	Structured session workflow with MITRE ATT&CK technique mapping

How prompts work: Each prompt primes the AI with an expert persona, structured Chain-of-Thought checkpoints, and evidence classification (OBSERVED / INFERRED / POSSIBLE). This produces analyst-grade output, not just raw tool output.

Quick Start

Option 1 — Docker (Recommended)

The fastest way to get started with zero dependency installation:

bash

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 2 — Build from Source

bash

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

Or manually:

bash

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

Option 3 — Python (Local Development)

bash

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 server.py

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

Connect to Your AI Client

Add the server configuration to your IDE client settings (e.g., ~/.cursor/mcp.json or claude_desktop_config.json).

⚡ Option 1: Docker Exec Mode (Highly Recommended)

If you run the server via Docker Compose (in the background), this mode uses standard stdio channeled directly inside the running container. It offers zero startup latency, persistent analysis memory, and perfect compatibility (bypasses IDE client-side HTTP/SSE connection bugs).

json

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

Note: Replace reversecore-mcp-arm64 with reversecore-mcp if you are on an Intel/AMD architecture.

🌐 Option 2: SSE HTTP Mode

If you prefer network-based streaming (Server-Sent Events) for remote clients:

json

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

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

If you prefer running a fresh, isolated container automatically on every request:

🍎 macOS

json

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

🐧 Linux

json

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

🪟 Windows

json

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

⚠️ 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")

Configuration

All settings can be provided via environment variables or a .env file (see .env.example):

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`REVERSECORE_WORKSPACE`	`/app/workspace`	Analysis workspace directory
`REVERSECORE_READ_DIRS`	`""`	Additional colon-separated read-only directories
`LOG_LEVEL`	`INFO`	Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`MCP_API_KEY`	(unset)	API key for HTTP mode authentication (optional)
`REVERSECORE_RATE_LIMIT`	`60`	Max requests per minute (HTTP mode only)
`REVERSECORE_DEFAULT_TOOL_TIMEOUT`	`120`	Default tool execution timeout in seconds
`REVERSECORE_R2_POOL_SIZE`	`3`	Radare2 connection pool size
`REDIS_URL`	`redis://localhost:6379/0`	Redis URL for background task queue
`REVERSECORE_SMTP_HOST`	(unset)	SMTP host for report email delivery
`REVERSECORE_SMTP_PORT`	`587`	SMTP port
`REVERSECORE_SMTP_USER`	(unset)	SMTP username
`REVERSECORE_SMTP_PASSWORD`	(unset)	SMTP password

Security Model

Security is a first-class concern. Reversecore MCP was designed to safely analyze untrusted malware samples without risk to the host system.

Control	Implementation
No shell injection	All subprocess calls use list arguments, never shell strings
Path traversal prevention	All file access validated and confined to configured workspace
Input sanitization	All parameters sanitized via `core/security.py` before execution
Rate limiting	Configurable per-minute request limits in HTTP mode (via slowapi)
Container isolation	Runs as non-root `appuser` (UID 1000) with minimal Linux capabilities
Secrets scanning	Gitleaks runs on every commit — no credentials ever reach the repo
SAST in CI	Bandit (all severities) + CodeQL on every push to `main`
Dependency auditing	pip-audit on every push — no unreviewed CVEs
Container scanning	Trivy scans final Docker image — LOW through CRITICAL findings reviewed
Error codes	Structured exception hierarchy with `RCMCP-E*` codes for AI-parseable errors

Development

Setup

bash

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 Gitleaks, Ruff, Bandit hooks

Testing

bash

# 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

Test status:

✅ 1,520 unit tests passing across Python 3.10 / 3.11 / 3.12
📊 82% code coverage (80% minimum enforced in CI)
🔒 Zero Bandit findings · No unreviewed vulnerabilities (pip-audit / container scans)
⚡ Fully async test suite via pytest-asyncio

Code Quality

bash

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 87 files)
bandit -r reversecore_mcp/       # Security scan (all severities)
pip-audit                        # Dependency CVE scan

CI/CD Pipeline

Every push to main runs the following gates — all must pass before deployment:

code

Lint & Security Gate            Unit Tests (Python Matrix)
  ├─ Gitleaks (secret scan)       ├─ pytest 3.10 --cov-fail-under=80
  ├─ Hadolint (Dockerfile)        ├─ pytest 3.11 --cov-fail-under=80
  ├─ Ruff check + format          └─ pytest 3.12 --cov-fail-under=80
  ├─ Mypy type check (87 files)
  ├─ Bandit (all severities)    Docker Verification
  └─ pip-audit (no unreviewed CVEs) ├─ Build multi-arch image (amd64/arm64)
                                  ├─ Trivy container scan (LOW→CRITICAL)
CodeQL Analysis                   ├─ Integration tests (inside container)
  └─ Python SAST                  └─ E2E MCP tool invocation
  └─ Push to GHCR + Trivy rescan on published image

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

System Requirements

Component	Minimum	Recommended
CPU	4 cores	8+ cores
RAM	8 GB	16 GB
Storage	20 GB	50 GB SSD
OS	Linux / macOS	Docker environment (any OS)
Docker	20.10+	24.0+
Python (local mode)	3.10	3.11 or 3.12

Project Structure

code

reversecore_mcp/
├── core/                      # Infrastructure layer
│   ├── config.py              # Centralized configuration
│   ├── exceptions.py          # Exception hierarchy (RCMCP-E* codes)
│   ├── security.py            # Input sanitization & path validation
│   ├── validators.py          # File & binary path validators
│   ├── r2_pool.py             # Thread-safe Radare2 connection pool
│   ├── r2_helpers.py          # Structured Radare2 output utilities
│   ├── metrics.py             # Tool execution metrics
│   ├── decorators.py          # @log_execution, @track_metrics
│   ├── error_handling.py      # @handle_tool_errors decorator
│   ├── memory.py              # Async SQLite AI memory store
│   ├── mitre_mapper.py        # MITRE ATT&CK mapping engine
│   ├── evidence.py            # Evidence classification system
│   ├── resilience.py          # Retry, circuit-breaker, timeout
│   ├── task_queue.py          # Background task queue (Redis/arq)
│   ├── extension_registry.py  # Plugin registration system
│   └── sast/                  # Python AST + C/C++ scanners
│
├── tools/                     # MCP tool implementations
│   ├── analysis/              # Static analysis
│   │   ├── static_analysis.py # file, strings, binwalk
│   │   ├── lief_tools.py      # LIEF binary parser
│   │   ├── capa_tools.py      # CAPA capability detection
│   │   ├── die_tools.py       # DIE packer/compiler detection
│   │   ├── diff_tools.py      # Binary diffing
│   │   ├── emulation_tools.py # ESIL emulation
│   │   ├── fuzz_tools.py      # Fuzzing harness generator
│   │   ├── symbolic_analysis.py # angr symbolic execution
│   │   ├── signature_tools.py # Library signature matching
│   │   └── source_auditor.py  # SAST (Python + C/C++)
│   │
│   ├── radare2/               # Radare2 & decompilation
│   │   ├── radare2_mcp_tools.py # Core r2 tool set
│   │   ├── r2ghidra_tools.py  # Ghidra decompiler (r2ghidra)
│   │   ├── r2_analysis.py     # Deep function analysis
│   │   ├── r2_db.py           # SQLite annotation database
│   │   └── r2_session.py      # Stateful analysis sessions
│   │
│   ├── malware/               # Threat detection & defense
│   │   ├── 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 # Vuln pattern detection
│   │
│   ├── forensics/             # Digital forensics
│   │   ├── memory.py          # Volatility3 memory forensics
│   │   ├── network.py         # Scapy PCAP analysis
│   │   ├── disk.py            # Sleuth Kit disk forensics
│   │   └── artifact.py        # Browser/registry/event log
│   │
│   ├── report/                # Report generation
│   └── common/                # File ops, server health
│
├── prompts/                   # AI reasoning prompts (5 modes)
├── resources.py               # Dynamic MCP resources
└── server.py                  # FastMCP server entrypoint (50+ tools registered)

Adding New Tools

Follow this pattern to add a new MCP tool:

python

# 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(str(e))

Then register it in server.py and add tests in tests/unit/.

Contributing

Fork the repository
Create a feature branch: git checkout -b feat/my-feature
Write tests alongside your code — coverage must not drop below 80%
Ensure all gates pass: pytest, ruff check, mypy, bandit
Open a pull request with a clear description

Please read the Contributing Guide for code standards, docstring conventions, and the pull request checklist.

Documentation

Document	Description
Installation Guide	Detailed setup for all environments
Architecture Guide	System design & component deep-dive
Contributing Guide	Code standards, docstrings, PR workflow
Testing Guide	Test patterns, fixtures, and coverage
API Reference	Tool and module reference
User Guide	End-user analysis workflows

License

MIT — see LICENSE for details.

GitHub · FastMCP Docs · MCP Spec · Radare2 · YARA

Install

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "reversecore-mcp": {
      "command": "uvx",
      "args": [
        "reversecore-mcp"
      ]
    }
  }
}

Topics

Reversecore MCP

Table of Contents

What is Reversecore MCP?

Architecture

Core Infrastructure Modules

Tool Catalog

🔍 Static Analysis

⚙️ Disassembly & Decompilation

🔗 Cross-Reference & Binary Annotation

🧬 Dynamic & Symbolic Analysis

🦠 Malware Analysis & Threat Detection

📝 Session Tracking & Report Generation

🕵️ Digital Forensics

📊 Server Health & Workspace

Guided Analysis Prompts

Quick Start

Option 1 — Docker (Recommended)

Option 2 — Build from Source

Option 3 — Python (Local Development)

Connect to Your AI Client

⚡ Option 1: Docker Exec Mode (Highly Recommended)

🌐 Option 2: SSE HTTP Mode

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

Configuration

Security Model

Development

Setup

Testing

Code Quality

CI/CD Pipeline

System Requirements

Project Structure

Adding New Tools

Contributing

Documentation

License

Install