Reversecore MCP
AI-Powered Reverse Engineering & Security Analysis via Model Context Protocol
An MCP server that gives AI assistants like Claude and Cursor the ability to perform reverse engineering, malware analysis, vulnerability research, digital forensics, and source code auditing through natural language.
Table of Contents
- What is Reversecore MCP?
- Architecture
- Tool Catalog (177 Tools)
- Guided Analysis Prompts (22 Modes)
- MCP Resources (11 URIs)
- Quick Start
- Connect to Your AI Client
- Configuration
- Security Model
- Development
- CI/CD Pipeline
- Docker Build Architecture
- System Requirements
- Project Structure
- Error Handling
- Adding New Tools
- Contributing
- Documentation
- License
What is Reversecore MCP?
Reversecore MCP is a Model Context Protocol server that wraps 177 analysis tools into a single interface that AI assistants can call through natural language.
Instead of learning the command-line syntax for a dozen different tools, you describe what you want:
"Decompile the main function of this malware sample, extract all network IOCs,
map the behavior to MITRE ATT&CK, and generate a triage report."
The AI assistant breaks this into tool calls:
r2_decompile("sample.exe", "main")
→ extract_iocs("sample.exe")
→ add_mitre_technique(technique_id="T1071.001", ...)
→ create_analysis_report(template_type="quick_triage")
Each tool returns a structured ToolResult (either ToolSuccess or ToolError) with typed data that the AI can reason about, chain into follow-up queries, or render for the user.
What it covers
Architecture
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) │
└──────────────────────────────────────────────────────┘
The server supports Python 3.10–3.12. The optional angr symbolic execution
engine is installed on Python 3.12 and newer, where a secure compatible release
is available; Python 3.10 and 3.11 installs omit angr.
Core Infrastructure (37 modules)
The reversecore_mcp/core/ directory contains the shared infrastructure that all tools build on:
Tool Catalog (177 Tools)
📖 Authoritative Tool Catalog & Parameter Reference (151 Tools) 📊 Tool Profile Footprint & Context Benchmark Matrix
Every tool returns a structured ToolResult — either a ToolSuccess with typed data or a ToolError with an RCMCP-E* error code. Tools are organized into 11 domain plugins across 5 modular execution profiles (full, static, malware, forensics, vuln-research):
🔍 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)
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.
Malware Analysis (9 prompts)
Security Research (6 prompts)
CVE Research & Exploit Development (5 prompts)
Other (2 prompts)
How prompts work: Each prompt primes the AI with a structured analysis persona. It includes Chain-of-Thought reasoning checkpoints (where the AI must stop and evaluate before proceeding) and evidence classification rules that prevent the AI from stating speculation as fact. Every finding must be labeled as
OBSERVED(directly verified),INFERRED(logically derived from static analysis), orPOSSIBLE(requires further verification).
MCP Resources (11 URIs)
Resources are read-only data endpoints that AI clients can access through URI templates. They complement tools by providing structured data without requiring explicit tool calls.
Static Resources
Dynamic Resources (Per-Binary Virtual Filesystem)
These URIs resolve per-binary and invoke the corresponding analysis tools on demand:
Quick Start
Option 1 — PyPI (Simplest)
pip install reversecore-mcp
reversecore-mcp
Prerequisites: Radare2 must be installed on your system (
r2 --version). YARA is installed automatically viayara-python.
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 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.
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 (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-arm64withreversecore-mcpif you are on Intel/AMD.
🌐 Option 2: SSE HTTP Mode
For network-based streaming (Server-Sent Events):
{
"mcpServers": {
"Reversecore_MCP": {
"url": "http://localhost:8000/mcp/sse"
}
}
}
📦 Option 3: Stdio Mode (Docker-on-Demand)
Runs a fresh, isolated container for every session:
{
"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"
]
}
}
}
⚠️ Important — File Paths Inside Docker
Your local folder is mounted to
/app/workspaceinside the container. Always reference files by filename only, not by your local full path.
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
Storage & Queue
Logging
Plugins & SAST
Security Model
Security is implemented as defense-in-depth, with protections at multiple layers:
Input & Path Safety
Network & Authentication
Container & Runtime
CI/CD Security Gates
Structured Error Handling
All 17 exception classes carry RCMCP-E* error codes for programmatic handling. See Error Handling for the full hierarchy.
Development
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
Testing
# 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
Test status:
- ✅ 1,957 unit tests passing across Python 3.10 / 3.11 / 3.12
- 📊 87% code coverage (80% minimum enforced in CI)
- 🔒 Zero Bandit findings
- ⚡ Fully async test suite via
pytest-asyncio
Test markers:
Code Quality
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 Hooks
The following hooks run automatically on every commit:
- Ruff — lint with auto-fix + format check
- trailing-whitespace — remove trailing whitespace
- end-of-file-fixer — ensure files end with newline
- check-yaml / check-json — validate YAML/JSON syntax
- check-added-large-files — block files > 1 MB
- check-merge-conflict — detect unresolved merge markers
- detect-private-key — prevent accidental key commits
- Bandit — Python security scanning
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.
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.
System Requirements
Project Structure
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
Other directories:
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
Error Handling
All custom exceptions inherit from ReversecoreError and carry structured error codes:
AI clients can use the error_code field to programmatically handle failures and decide whether to retry, try an alternative tool, or report the error to the user.
Adding New Tools
Follow this pattern to add a new MCP tool:
# 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.",
)
Then register it in the appropriate plugin's __init__.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 (Google-style), and the pull request checklist.
Documentation
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)."
Multi-Architecture Support
The arch_registry.py module maps architecture names to Radare2 configuration parameters, enabling tools to work across different CPU architectures without manual configuration:
Alias resolution is handled automatically:
amd64→x86_64aarch64→arm64armwithbits=64→arm64armwithbits=16orbits=32→arm32
Tools like Radare2_esil_emulate, assemble_instructions, and r2_simulate_patch use this registry to configure the analysis environment correctly for any target binary.
Result Cache System
Two caching layers minimize redundant computation:
Tool Result Cache (result_cache.py)
The @cache_tool_result decorator caches any tool's output based on a SHA256 hash of the binary file and the tool's keyword arguments:
Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )
Storage backend: SQLite database via r2_db.py, accessible through get_cached_result() and set_cached_result() tools.
Metrics: Cache hits and misses are tracked via metrics_collector.record_cache_hit() and record_cache_miss(), visible through the get_tool_metrics tool.
Analysis Cache (analysis_cache.py)
A multi-level cache specifically for decompilation results (which are expensive to compute):
Import/Export: The export_analysis_cache and import_analysis_cache tools allow saving cache state to/from rcpack files for sharing between environments.
AI Memory System
The AI memory system (memory_tools.py + core/memory.py) provides persistent, queryable storage for analysis findings across sessions. This allows the AI to:
- Remember what it previously found about a binary
- Cross-reference findings between different samples
- Tag and search sessions by topic, malware family, or technique
How It Works
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
Storage: Async SQLite database at the path configured by MEMORY_DB_PATH (default: ~/.reversecore_mcp/memory.db).
Portability: Use export_memory_store and import_memory_store to transfer the entire memory database between environments.
Web Dashboard
When running in HTTP mode (MCP_TRANSPORT=http), a web dashboard is available at http://localhost:8000/dashboard. It provides:
- Binary upload with drag-and-drop
- Real-time analysis status
- Interactive function list and disassembly view
- IOC extraction results
- Server health monitoring
Tech stack: FastAPI + Jinja2 templates + HTMX (loaded locally from dashboard/static/, no CDN dependency for CSP compliance).
Security features:
- CSRF tokens on all state-changing forms
- Jinja2 auto-escaping enabled
- All user input sanitized via
html.escape()before display - Path traversal protection via
validate_file_path()
Deployment
Production Checklist
Before deploying to production:
Health Checks
The server provides HTTP health check endpoints for orchestration:
# 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
These endpoints are exempted from API key authentication so load balancers and container orchestrators can probe them.
Container Healthcheck
The Docker image includes a built-in HEALTHCHECK instruction that verifies TCP connectivity to port 8000 every 30 seconds. Docker and Kubernetes will automatically restart unhealthy containers.
Troubleshooting
Common Issues
The required CLI tool is not installed in the environment.
Solution: If using Docker, verify the tool is in the base image:
docker exec reversecore-mcp-arm64 which r2 yara binwalk tsk_recover gdb
If using local Python installation, install the missing tool:
# macOS
brew install radare2 yara binwalk sleuthkit
# Ubuntu/Debian
apt install radare2 yara binwalk sleuthkit
Analysis exceeded the configured timeout.
Solution: Increase the timeout:
export REVERSECORE_DEFAULT_TOOL_TIMEOUT=300 # 5 minutes
For large binaries (>100 MB), consider using quick-scan variants:
run_capa_quickinstead ofrun_capadetect_packerinstead ofdetect_packer_deep
You referenced a file outside the workspace directory.
Solution: Copy the file into the workspace first:
copy_to_workspace("/path/to/file.exe")
Or mount additional directories as read-only:
export REVERSECORE_READ_DIRS=/opt/samples,/mnt/evidence
Make sure you're using the ARM64 profile:
docker compose --profile arm64 up -d
Or use the auto-detection script:
./scripts/run-docker.sh
The task queue requires a running Redis instance.
Solution: Start Redis alongside the main service:
docker compose --profile arm64 up -d # Starts both reversecore and redis
Or disable Redis-dependent features by not setting REDIS_URL.
This usually means the function wasn't analyzed first.
Solution: Run analysis before decompilation:
Radare2_analyze_binary("sample.exe")
Radare2_decompile_function("sample.exe", "main")
FAQ
No. This project is a complement, not a replacement. It uses r2ghidra (the Ghidra decompiler engine embedded in Radare2) for decompilation. It does not provide a GUI, and it does not have the interactive analysis workflow of a full disassembler. Its purpose is to let AI assistants perform analysis tasks programmatically.
No. The r2ghidra plugin embeds the Ghidra decompiler engine directly inside Radare2. No JDK, no Ghidra installation, no Ghidra project files. Just r2 with the r2ghidra plugin compiled in.
Any client that implements the Model Context Protocol specification. Tested with: Claude Desktop, Cursor, Windsurf, and Google Antigravity. The server supports both stdio and HTTP/SSE transports.
Yes. Static analysis (disassembly, decompilation, string extraction, IOC extraction, YARA scanning) works on any file format regardless of host OS. Dynamic analysis (emulation, fuzzing) may have limitations depending on the target architecture.
The Docker container provides isolation: non-root user, no network by default in CI, resource limits. For live malware analysis, we recommend running in a dedicated VM or using the sandbox feature (REVERSECORE_SANDBOX_ENABLED=true). Static analysis tools (r2, YARA, strings) never execute the target binary.
Default limits:
- Upload: 100 MB (
MAX_UPLOAD_SIZE) - LIEF parsing: 1 GB (
REVERSECORE_LIEF_MAX_FILE_SIZE) - Tool output: 10 MB (
REVERSECORE_MAX_OUTPUT_SIZE)
All limits are configurable via environment variables.
Acknowledgments
This project is built on the work of many open-source projects:
License
MIT — see LICENSE for details.