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 (120 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 120 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

Domain	What you can do
Static analysis	Disassembly, decompilation (r2ghidra), binary parsing (LIEF), packer detection (DIE), capability detection (CAPA), string extraction, firmware scanning (binwalk)
Dynamic & symbolic	ESIL emulation, angr symbolic execution, taint analysis, fuzzing harness generation
Malware analysis	IOC extraction, YARA scanning, dormant backdoor detection, adaptive vaccine generation, autonomous vulnerability hunting
Vulnerability research	Dangerous API detection, ROP gadget discovery, heap exploit analysis, crash triage, PoC generation
Digital forensics	Memory forensics (Volatility3), PCAP analysis (Scapy), disk forensics (Sleuth Kit), artifact correlation
Source code audit	Python AST scanning, C/C++ regex pattern scanning
Reporting	Session-based reports with MITRE ATT&CK mapping, SIGMA rule generation, VEX reports, email delivery

---

Architecture

AI Client (Claude / Cursor / any MCP-compatible client)
        │  MCP Protocol (stdio or HTTP/SSE)
        ▼
┌──────────────────────────────────────────────────────┐
│                   FastMCP 3.4.4 Server               │
│          120 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)          │
└──────────────────────────────────────────────────────┘

Core Infrastructure (37 modules)

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

Module	Purpose
config.py	Pydantic BaseSettings with 34+ environment variables
security.py	Input sanitization, command argument validation
validators.py	File and binary path validation with TOCTOU mitigation, symlink resolution
r2_pool.py	Thread-safe Radare2 connection pool with configurable size
r2_helpers.py	Structured Radare2 output parsing
metrics.py	Per-tool execution times, call counts, error rates, cache statistics
memory.py	Async SQLite-backed AI memory store for persisting analysis findings across sessions
mitre_mapper.py	MITRE ATT&CK technique ID mapping engine
evidence.py	Evidence classification system: OBSERVED, INFERRED, POSSIBLE
resilience.py	Retry, circuit-breaker, and timeout decorator patterns
task_queue.py	Background task queue via Redis + arq
extension_registry.py	Plugin registration and lifecycle management
arch_registry.py	Multi-architecture mapping (x86, x86_64, ARM32, ARM64, MIPS, RISC-V, PPC → r2 arch/bits/registers)
result_cache.py	SHA256-based tool result caching decorator (@cache_tool_result)
analysis_cache.py	Multi-level decompilation cache (L1: Redis, L2: SQLite)
result.py	ToolSuccess / ToolError Pydantic models
exceptions.py	17 exception classes with RCMCP-E* error codes
decorators.py	@log_execution, @track_metrics
error_handling.py	@handle_tool_errors decorator
error_formatting.py	Structured error response formatting
execution.py	Safe subprocess execution with timeout and output limits
command_spec.py	Command specification for subprocess calls
loader.py	Dynamic tool module loader
plugin.py	Plugin base class
extension.py	Extension base class
container.py	Container/sandbox execution support
audit.py	Audit logging
binary_cache.py	Binary file caching
json_utils.py	JSON serialization via orjson (3-5x faster than stdlib json)
logging_config.py	Loguru-based structured logging
report_generator.py	Report rendering engine (Markdown, PDF via xhtml2pdf)
resource_manager.py	MCP resource lifecycle management
sast/python_ast_scanner.py	Python AST-based vulnerability scanner
sast/regex_scanner.py	C/C++ regex-based vulnerability scanner
sast/rule_manager.py	SAST rule loading and management

---

Tool Catalog (120 Tools)

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 8 plugins.

---

🔍 Static Analysis Plugin (24 tools)

#	Tool	Backend	Description
1	run_strings	strings CLI	ASCII/Unicode string extraction with configurable min-length
2	run_binwalk	Binwalk	Firmware deep-scan for embedded signatures and filesystems
3	run_binwalk_extract	Binwalk	Extract embedded files discovered by binwalk
4	parse_binary_with_lief	LIEF	Full PE/ELF/Mach-O header, section, import/export, TLS parsing
5	detect_packer	DIE	Quick packer/compiler detection
6	detect_packer_deep	DIE (diec)	Deep packer/protector analysis via Detect It Easy
7	run_capa	CAPA (Mandiant FLARE)	Capability detection — "encrypts data", "creates persistence", etc.
8	run_capa_quick	CAPA	Quick capability scan with a rule subset
9	generate_signature	Radare2	Generate binary signatures for identification
10	generate_yara_rule	Radare2 + YARA	Generate YARA detection rules from binary patterns
11	generate_advanced_yara_rule	Radare2 + YARA	Advanced YARA rules with behavioral indicators
12	scan_for_versions	LIEF + strings	Scan binary for embedded version strings
13	extract_rtti_info	Radare2	Extract C++ RTTI (Run-Time Type Information)
14	diff_binaries	Radare2	Semantic binary diff between two file versions
15	analyze_variant_changes	Radare2	Analyze changes between binary variants
16	match_libraries	Radare2	Identify statically linked libraries by function fingerprint
17	patch_diff_1day	Radare2 + heuristics	Automated patch diff analysis for 1-day vulnerability research
18	analyze_patch_diff_auto	Radare2 + inference	Automated patch vulnerability inference
19	emulate_binary	Radare2 ESIL	Register/memory-traced code emulation
20	generate_fuzzing_harness	Qiling + AFL++	Generate a fuzzing harness targeting a specific function
21	run_fuzzing_campaign	AFL++	Run a full fuzzing campaign with crash collection
22	triage_crash	GDB	Crash parsing and exploitability assessment
23	verify_path_and_get_args	angr	Symbolic execution — prove path reachability and compute concrete inputs
24	taint_trace	Radare2 + angr	Data-flow taint analysis from sources to sinks

---

🔐 Source Code Audit Plugin (1 tool)

#	Tool	Backend	Description
25	audit_source_code	AST + Regex	Python AST scanning + C/C++ regex scanning for dangerous patterns

---

🛠️ Common Utilities Plugin (20 tools)

File Operations (5 tools)

#	Tool	Description
26	run_file	File type, architecture, and compiler fingerprinting
27	copy_to_workspace	Copy a file into the analysis workspace
28	create_directory	Create a directory in the workspace
29	list_workspace	List all files in the workspace
30	scan_workspace	Full workspace scan with file metadata

Patch Explanation (1 tool)

#	Tool	Description
31	explain_patch	Explain a binary patch in natural language

Assembler (1 tool)

#	Tool	Backend	Description
32	assemble_instructions	Keystone	Assemble instructions to machine code (x86, ARM, MIPS, etc.)

AI Memory Management (11 tools)

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

#	Tool	Description
33	create_memory_session	Start a new memory session for an analysis
34	store_analysis_finding	Persist an analysis finding with tags
35	query_analysis_memories	Search past findings by query
36	get_binary_analysis_context	Retrieve all context for a specific binary
37	tag_analysis_session	Add tags to a session for organization
38	search_memories_by_tag	Find sessions/findings by tag
39	delete_analysis_session	Remove a session and its findings
40	cleanup_expired_sessions	Remove sessions older than a threshold
41	list_analysis_sessions	List all active sessions
42	export_memory_store	Export all memories to a portable format
43	import_memory_store	Import memories from an export file

Server Monitoring (2 tools)

#	Tool	Description
44	get_server_health	Uptime, memory usage, loaded tools, Python version
45	get_tool_metrics	Per-tool call counts, mean execution times, error rates, cache hit/miss

---

⚙️ Radare2 & r2ghidra Plugin (30 tools)

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

#	Tool	Description
46	Radare2_open_file	Open a binary file in Radare2
47	Radare2_close_file	Close a Radare2 session
48	Radare2_list_open_files	List currently open files
49	Radare2_analyze_binary	Run full auto-analysis (aaa)
50	Radare2_list_functions	List all detected functions
51	Radare2_disassemble_function	Disassemble a specific function
52	Radare2_disassemble_address	Disassemble at a specific address
53	Radare2_decompile_function	Decompile via r2ghidra (Ghidra engine embedded in r2, no JVM needed)
54	Radare2_list_exports	List exported symbols
55	Radare2_list_imports	List imported functions
56	Radare2_list_sections	List binary sections with entropy
57	Radare2_list_strings	List strings found in the binary
58	Radare2_find_cross_references	Track function calls and data references
59	Radare2_search_bytes	Search for byte patterns in the binary
60	Radare2_get_binary_info	Get binary metadata (arch, format, endianness)
61	Radare2_execute_command	Execute a raw Radare2 command
62	Radare2_esil_emulate	ESIL emulation at a specific address
63	Radare2_get_hexdump	Hex dump at a virtual address
64	Radare2_get_cfg_data	Extract control flow graph data
65	Radare2_generate_cfg_png	Generate CFG as PNG image
66	Radare2_generate_callgraph	Generate function call graph
67	Radare2_recover_structures	Auto-recover C structs and persist to annotation database
68	Radare2_decompile_with_r2ghidra	High-quality C decompilation with caching
69	Radare2_annotate_binary	Add annotations to the binary
70	Radare2_get_annotations	Retrieve annotations
71	Radare2_export_annotations	Export annotations to file
72	Radare2_import_annotations	Import annotations from file
73	Radare2_detect_crypto_constants	Detect cryptographic constants (AES S-box, etc.)
74	Radare2_find_gadgets	Find ROP/JOP gadgets
75	Radare2_calculate_entropy	Calculate per-section entropy

---

🦠 Malware Analysis Plugin (9 tools)

#	Tool	Backend	Description
76	dormant_detector	Radare2 + heuristics	Find hidden backdoors, orphan functions, time-bombs, logic bombs
77	adaptive_vaccine	YARA + Radare2	Generate detection YARA rules + binary patches to neutralize threats
78	vulnerability_hunter	Radare2 + analysis	Detect dangerous API patterns (strcpy, sprintf) and ROP gadget chains
79	extract_iocs	Regex + LIEF	Extract IPs, URLs, domains, hashes, registry keys, crypto addresses
80	run_yara	YARA	Scan with custom rule files and built-in rulesets
81	generate_poc_exploit	pwntools	Generate proof-of-concept exploit code
82	build_rop_chain	ROPgadget + pwntools	Automated ROP chain construction
83	autonomous_vuln_hunt	Radare2 + angr	Autonomous vulnerability hunting pipeline
84	analyze_heap_exploit	Radare2 + heuristics	Heap exploitation analysis (UAF, double-free, overflow)

---

🕵️ Digital Forensics Plugin (22 tools)

Memory Forensics (6 tools)

#	Tool	Backend	Description
85	memory_analyze	Volatility3	Full memory dump analysis
86	memory_list_processes	Volatility3	List running processes from memory dump
87	memory_detect_injections	Volatility3	Detect code injection in process memory
88	memory_extract_strings	Volatility3	Extract strings from process memory
89	memory_dump_module	Volatility3	Dump a loaded module from memory
90	memory_list_symbols	Volatility3	List symbols from memory

Disk Forensics (6 tools)

#	Tool	Backend	Description
91	disk_list_partition	Sleuth Kit	List disk partitions
92	disk_list_files	Sleuth Kit	List files in a disk image
93	disk_recover_deleted	Sleuth Kit	Recover deleted files
94	disk_analyze_mft	Sleuth Kit	Analyze NTFS Master File Table
95	disk_extract_file	Sleuth Kit	Extract a file from disk image
96	disk_hash_verify	Sleuth Kit	Verify file integrity via hash

Network Forensics (5 tools)

#	Tool	Backend	Description
97	pcap_analyze	Scapy	PCAP analysis: protocol breakdown, anomalies
98	pcap_list_connections	Scapy	List all network connections
99	pcap_extract_dns	Scapy	Extract DNS queries and responses
100	pcap_extract_c2	Scapy	Identify potential C2 communication
101	pcap_reconstruct_stream	Scapy	Reconstruct TCP streams

Artifact Analysis (5 tools)

#	Tool	Backend	Description
102	artifact_collect	Custom parsers	Collect browser history, registry hives, event logs, prefetch
103	artifact_correlate_ioc	Custom parsers	Correlate artifacts with known IOCs
104	artifact_generate_yara	YARA	Generate YARA rules from artifact patterns
105	artifact_timeline	Custom parsers	Build timeline from multiple artifact sources
106	artifact_report	Custom parsers	Generate artifact analysis report

---

📝 Report Generation Plugin (14 tools)

#	Tool	Description
107	get_system_time	Get server timestamp (prevents AI from hallucinating dates)
108	set_timezone	Set the reporting timezone
109	get_timezone_info	Get current timezone information
110	start_report_session	Start a timed analysis session with unique ID
111	end_report_session	Finalize session: compute duration, lock IOC/ATT&CK lists
112	get_report_session_status	Check session status
113	list_report_sessions	List all active/completed sessions
114	add_ioc	Collect and tag IOCs during a live session
115	add_analysis_note	Add categorized notes (finding, warning, behavior)
116	add_mitre_technique	Document MITRE ATT&CK technique IDs
117	set_severity	Set session severity (low/medium/high/critical)
118	create_analysis_report	Render report in 4 modes: full_analysis, quick_triage, ioc_summary, executive_brief
119	generate_vex_report	Generate a VEX (Vulnerability Exploitability eXchange) report
120	generate_sigma_rule	Generate SIGMA detection rules

---

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)

Prompt	Use Case
full_analysis_mode	6-phase comprehensive analysis: triage → disassembly → behavior → network → persistence → report
malware_analysis_mode	Focused malware analysis with threat classification
basic_analysis_mode	Rapid triage for initial assessment and quick verdicts
apt_hunting_mode	APT-specific hunting: lateral movement, persistence, data exfiltration
malware_defense_mode	Defense-oriented: generate detection rules and mitigations
unpacking_mode	Analyze and bypass packing/obfuscation (Themida, VMProtect, UPX)
c2_extraction_mode	Extract and analyze C2 communication infrastructure
ransomware_triage_mode	Ransomware-specific triage: encryption analysis, key recovery assessment
code_similarity_mode	Compare binaries for code similarity and shared lineage

Security Research (6 prompts)

Prompt	Use Case
vulnerability_research_mode	Bug hunting: buffer overflows, UAF, command injection
crypto_analysis_mode	Cryptographic implementation analysis and weakness detection
firmware_analysis_mode	IoT/embedded firmware: binwalk extraction, UART strings, hardcoded credentials
patch_analysis_mode	Security patch analysis and regression testing
source_code_audit_mode	Source code security audit (Python, C, C++)
autonomous_vuln_hunt_mode	Autonomous vulnerability hunting pipeline

CVE Research & Exploit Development (5 prompts)

Prompt	Use Case
taint_analysis_mode	Data-flow taint analysis: automated source→sink path discovery
heap_exploit_mode	Heap exploitation analysis and PoC generation
fuzzing_mode	Fuzzing campaign setup and crash triage
patch_diff_auto_mode	Automated patch diff for 1-day vulnerability research
cve_discovery_pipeline_mode	Full CVE discovery pipeline: from patch diff to working exploit

Other (2 prompts)

Prompt	Use Case
game_analysis_mode	Game client analysis: anti-cheat detection, protocol RE, memory inspection
report_generation_mode	Structured session workflow with MITRE ATT&CK technique mapping

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), or POSSIBLE (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

URI	Description
reversecore://guide	Tool usage guide with file path rules and best practices
reversecore://guide/structures	Structure recovery and cross-reference analysis technical guide
reversecore://tools	Complete documentation for all 120 registered tools
reversecore://logs	Application logs (last 100 lines)

Dynamic Resources (Per-Binary Virtual Filesystem)

These URIs resolve per-binary and invoke the corresponding analysis tools on demand:

URI Template	Description
reversecore://{filename}/strings	Extract all strings from a binary
reversecore://{filename}/iocs	Extract IOCs (IPs, URLs, emails, hashes)
reversecore://{filename}/func/{address}/code	Decompiled pseudo-C code for a function
reversecore://{filename}/func/{address}/asm	Disassembly for a function
reversecore://{filename}/func/{address}/cfg	Control flow graph in Mermaid format
reversecore://{filename}/functions	List of all functions in the binary
reversecore://{filename}/dormant_detector	Dormant detector analysis results

---

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 via yara-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-arm64 with reversecore-mcp if 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/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). Settings are managed via Pydantic BaseSettings with the REVERSECORE_ prefix.

Core Settings

Variable	Default	Description
MCP_TRANSPORT	stdio	Transport mode: stdio or http
REVERSECORE_WORKSPACE	./ (cwd)	Analysis workspace directory
REVERSECORE_READ_DIRS	""	Comma-separated list of additional read-only directories
REVERSECORE_STRICT_PATHS	false	Raise errors for missing paths instead of warnings
REVERSECORE_STRUCTURED_ERRORS	false	Enable structured error responses with error codes
REVERSECORE_DEFAULT_TOOL_TIMEOUT	120	Default tool execution timeout in seconds
REVERSECORE_MAX_OUTPUT_SIZE	10000000	Maximum output size for tools (bytes)

HTTP Mode Settings

Variable	Default	Description
MCP_HOST	0.0.0.0	Host interface to bind (auto-overrides to 127.0.0.1 if no API key)
MCP_PORT	8000	Port for HTTP server
MCP_API_KEY	(unset)	API key for HTTP authentication (X-API-Key or Authorization: Bearer)
REVERSECORE_RATE_LIMIT	60	Max requests per minute (HTTP mode only, via slowapi)
MAX_UPLOAD_SIZE	100000000	Maximum upload size (100 MB default)
FILE_RETENTION_MINUTES	1440	Retention period for uploaded files (24h default)

Radare2 Settings

Variable	Default	Description
REVERSECORE_R2_POOL_SIZE	3	Number of Radare2 connections in the pool
REVERSECORE_R2_POOL_TIMEOUT	30	Timeout for acquiring a connection from the pool
REVERSECORE_R2_EXTENSIONS	""	Comma-separated list of r2 extension classes (module:ClassName)
REVERSECORE_GHIDRA_MAX_PROJECTS	3	Max cached r2ghidra decompiler projects
REVERSECORE_GHIDRA_EXTENSIONS	""	Comma-separated list of Ghidra extension classes
MAX_EMULATION_INSTRUCTIONS	1000	Maximum ESIL emulation instructions

Sandbox Settings

Variable	Default	Description
REVERSECORE_SANDBOX_ENABLED	false	Enable sandbox execution for dynamic analysis tools
REVERSECORE_SANDBOX_MODE	auto	Sandbox mode: auto, host, container, disabled
REVERSECORE_SANDBOX_DOCKER_IMAGE	reversecore-sandbox:latest	Docker image for sandbox execution
REVERSECORE_SANDBOX_CPU_LIMIT	1.0	CPU core limit for sandbox containers
REVERSECORE_SANDBOX_MEMORY_LIMIT	512m	Memory limit for sandbox containers
REVERSECORE_SANDBOX_PIDS_LIMIT	100	PID limit for sandbox containers
REVERSECORE_SANDBOX_USER	nobody	Non-root user for sandbox execution

Storage & Queue

Variable	Default	Description
REDIS_URL	redis://localhost:6379/0	Redis URL for task queue and result caching
MEMORY_DB_PATH	~/.reversecore_mcp/memory.db	Path to AI memory SQLite database
REVERSECORE_LIEF_MAX_FILE_SIZE	1000000000	Maximum file size for LIEF parsing (1 GB)

Logging

Variable	Default	Description
LOG_LEVEL	INFO	Logging verbosity: DEBUG, INFO, WARNING, ERROR
LOG_FILE	<tempdir>/reversecore/app.log	Path to log file
LOG_FORMAT	human	Log format: human (readable) or json (structured)

Plugins & SAST

Variable	Default	Description
REVERSECORE_PLUGIN_DIRS	""	Comma-separated directories to scan for extension plugins
REVERSECORE_SAST_RULES_PATH	""	Path to custom YAML SAST rules file

---

Security Model

Security is implemented as defense-in-depth, with protections at multiple layers:

Input & Path Safety

Control	Implementation
No shell injection	All subprocess calls use list arguments, never shell strings (execution.py)
Path traversal prevention	validate_file_path() and validate_binary_path() resolve symlinks and confine access to the workspace (validators.py)
TOCTOU mitigation	bypass_cache=True flag re-validates paths to prevent race conditions
Input sanitization	All parameters sanitized before execution (security.py)
CSRF protection	Dashboard forms require token-based CSRF validation (dashboard/__init__.py)

Network & Authentication

Control	Implementation
Timing-attack-safe auth	secrets.compare_digest() for API key comparison (web/auth.py)
Restricted auth vectors	Only X-API-Key and Authorization: Bearer headers accepted; no query params or cookies
Loopback-only fallback	Without MCP_API_KEY, HTTP access restricted to 127.0.0.1 (web/middleware.py)
Rate limiting	Configurable per-minute limits via slowapi
Security headers	HSTS, X-Content-Type-Options, X-Frame-Options, CSP on all HTTP responses (web/middleware.py)
Minimized /health	Public endpoint returns only {"status": "alive"}; details behind authentication (web/endpoints.py)

Container & Runtime

Control	Implementation
Non-root execution	Runs as appuser (UID 1000) with minimal capabilities
Resource limits	Docker Compose enforces CPU (2.0) and memory (4 GB) limits
Sandbox isolation	Optional container-based sandboxing for dynamic analysis tools

CI/CD Security Gates

Control	Implementation
Secrets scanning	Gitleaks runs on every commit (pre-commit hook + CI)
SAST	Bandit scans all Python code on every commit
CodeQL	GitHub CodeQL static analysis on every push to main
Dependency auditing	pip-audit on every push — no unreviewed CVEs
Container scanning	Trivy scans Docker images for vulnerabilities (LOW through CRITICAL)
Exploit safety gate	POC templates scanned with Bandit; Hypothesis DAST fuzzing; container isolation verified

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:

Marker	Purpose
@pytest.mark.unit	Fast unit tests
@pytest.mark.integration	Tests requiring Docker or external tools
@pytest.mark.slow	Long-running tests
@pytest.mark.benchmark	Performance benchmarks
@pytest.mark.security	Security boundary validation tests

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:

1. Ruff — lint with auto-fix + format check
2. trailing-whitespace — remove trailing whitespace
3. end-of-file-fixer — ensure files end with newline
4. check-yaml / check-json — validate YAML/JSON syntax
5. check-added-large-files — block files > 1 MB
6. check-merge-conflict — detect unresolved merge markers
7. detect-private-key — prevent accidental key commits
8. 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:

Service	Profile	Description
reversecore-mcp	default, x86	Intel/AMD x86_64
reversecore-mcp-arm64	arm64, macos	Apple Silicon A