โก Instant One-Line Setup
Automatically detects installed AI clients (Cursor, Claude Code, Windsurf, Claude Desktop, OpenAI Codex, Antigravity, Cline/Roo Code) and registers Reversecore MCP with automatic configuration backups:
pipx run reversecore-mcp setup
curl -fsSL https://raw.githubusercontent.com/sjkim1127/Reversecore_MCP/main/install.sh | bash
npx skills add sjkim1127/Reversecore_MCP
๐ก Reduce LLM context token usage by 94.4%: Run pipx run reversecore-mcp setup --tiered to expose 15 core security tools + 8 domain sub-agents while keeping all 186 tools callable on demand.
Table of Contents
What is Reversecore MCP?
Reversecore MCP is a Model Context Protocol server that wraps 194 analysis tools into a unified interface for AI-assisted security research, malware triage, vulnerability discovery, and digital forensics.
Instead of manually switching between disassemblers, decompilers, YARA scanners, and forensics utilities, you describe your investigation goal in natural language:
"Decompile the main payload of this suspicious sample, recover its custom string decryption
routine, extract all C2 IOCs, map behaviors to MITRE ATT&CK, and generate a triage report."
Each tool runs locally (or inside an isolated Docker container) and returns a structured ToolResult (ToolSuccess or ToolError) with byte-level provenance so the AI can chain multi-step security investigations without hallucinating findings.
๐ก๏ธ Security Analysis Workflows
Workflow 1: Malware Cryptor / DGA Recovery & Safe Emulation Verification
Modern malware families encrypt C2 configurations or generate domains dynamically (DGA). Translating decompiled C into a Python decryptor by hand is error-prone due to subtle 32/64-bit integer wrap-around and bitwise shifts. Reversecore MCP reconstructs the routine and verifies 100% behavioral equivalence inside Radare2's ESIL CPU emulator without executing live malware on the host.
Prompt:
"Analyze the config decryption function at 0x401180 in sample.bin, write a safe Python
decryptor script, and verify with ESIL emulation that its output matches the binary."
Agent Tool Chain & Verified Output:
1. r2_decompile("sample.bin", "0x401180", detail="summary")
โโ Returns compact complexity/API summary + cache handle: evidence_id="ev_9a4c102f8b11"
2. inspect_analysis_view(evidence_id="ev_9a4c102f8b11", facet="lines", offset=0, limit=40)
โโ Streams exact pseudo-C lines on demand without exhausting context window
3. reconstruct_feature_code(
file_path="sample.bin",
address_or_symbol="sym.decrypt_word",
target_language="python",
test_inputs=["0x0", "0xff", "0xffff"]
)
โโ Decompilation & Synthesis: r2ghidra -> clean Python function (decrypt_word)
โโ Binary Emulation: Radare2 ESIL VM (isolated register/memory state, zero host execution)
โโ Equivalence Verdict: VERIFIED (branch_parity: true, test_vectors_evaluated: 3, emulation_successful: true)
โโ Reconstructed Code:
def decrypt_word(param_1: Any = 0, param_2: Any = 0, *args: Any, **kwargs: Any) -> Any:
uVar1 = (param_1 ^ param_2) * 0x45d9f3b
return uVar1 >> 0x10 ^ uVar1
Workflow 2: Modern Runtime Threat & Supply-Chain Auditing (Go/Rust, Electron ASAR, Unity)
Threat actors increasingly write cross-platform ransomware in stripped Go/Rust or distribute trojanized Electron (app.asar) desktop installers. Reversecore MCP provides built-in pure-Python static parsers to recover stripped symbols and audit runtime security boundaries:
Prompt:
"Audit this suspicious installer's app.asar for insecure BrowserWindow settings and
suspicious IPC handlers, and recover function symbols from its bundled stripped Go helper."
Agent Tool Chain & Verified Output:
1. inspect_electron_asar("app.asar", search_pattern="ipcMain|child_process|shell")
โโ Format: Chromium Pickle ASAR (header_size: 48,210 bytes, 642 files)
โโ Exposed IPC Handlers: 14 channels mapped across main and preload scripts
โโ Security Audit Findings:
โข [HIGH] nodeIntegration: true detected in BrowserWindow configuration
โข [MEDIUM] sandbox: false detected in renderer window options
2. inspect_go_rust_binary("helper_daemon.elf")
โโ Runtime Detected: Go (gopclntab magic 0xfffffff1, Go 1.22)
โโ Symbol Recovery: 148 stripped package/function names recovered from .gopclntab
โโ Suspicious Packages Identified:
โข main.establishBeaconLoop @ 0x48a200
โข main.encryptLocalVolume @ 0x48b940
Workflow 3: Zero-Day Crash Triage, Taint Analysis & Adaptive YARA/Vaccine Generation
From an ASan/GDB crash log or a packed binary with dormant logic bombs, Reversecore MCP chains crash classification, source-to-sink taint reachability, and automated detection rule synthesis.
Prompt:
"Triage this ASan crash log on daemon.bin, verify whether untrusted network input reaches
the vulnerable memcpy sink, scan for dormant backdoors, and generate a YARA rule."
Agent Tool Chain & Verified Output:
1. cve_triage_crash(crash_log_or_text=asan_log)
โโ Bug Class: heap-buffer-overflow (READ) | CWE-125 | Faulting Function: parse_packet+0x84
2. taint_trace("daemon.bin", function_name="parse_packet", verify_with_angr=True)
โโ SourceโSink Confirmed: recv() โ memcpy() at 0x402190 (unbounded length field)
3. dormant_detector("daemon.bin")
โโ Discovered 1 orphan function (0x404800) with time-bomb trigger (cmp eax, 0x67758ac0)
4. adaptive_vaccine(threat_report={...}, action="both")
โโ Generated YARA detection rule with wildcarded address displacement masking
โโ Synthesized binary mitigation patch neutralizing the vulnerable/malicious branch
What You Can Analyze
| Target Category | Security & Reverse Engineering Capabilities | Engine / Requirement |
|---|
| Native Binaries (PE / ELF / Mach-O) | Disassembly, r2ghidra C decompilation, CFG, C++ RTTI, struct recovery, imports/exports, section entropy, Authenticode/certificates | Radare2 + r2ghidra + LIEF (x86, x64, ARM32, ARM64, MIPS, RISC-V, PowerPC) |
| Malware & Packed Executables | Packer/compiler identification, CAPA behavioral capability mapping, dormant backdoor/time-bomb detection, IOC extraction, YARA & Sigma rules, binary vaccines | YARA + CAPA + DIE + Custom Heuristics |
| Stripped Go & Rust Malware / Binaries | Go .gopclntab (go1.2โgo1.20+) symbol recovery, Rust .dep-v0 (cargo-auditable) dependency tree & vulnerable crate auditing, _ZN...E demangling | Built-in pure Python (inspect_go_rust_binary) โ no Go/Rust SDK required |
Electron Desktop Apps (app.asar) | Supply-chain & client security audit: Chromium Pickle VFS parser, ipcMain/contextBridge surface mapping, nodeIntegration/contextIsolation checks | Built-in pure Python (inspect_electron_asar) โ zero external dependencies |
| Unity IL2CPP Binaries | Mobile/client security audit: global-metadata.dat (0xFAB11BAF, v24โv31+) header encryption/entropy detection, C# class/method/string recovery, libil2cpp.so correlation | Built-in pure Python (inspect_unity_il2cpp) โ no Unity required |
| Cryptor / Routine Reconstruction | Decompiled routine translation into safe C/Python scripts with ESIL register/memory equivalence verification and Obligation Ledger | r2ghidra + ESIL Simulator (reconstruct_feature_code) |
| Vulnerabilities & Crash Dumps | ASan/GDB crash triage, delta-debugging PoC minimization, source-to-sink taint analysis, angr symbolic path solving, ROP gadget chains | angr + pwntools + ROPgadget + GDB |
| Memory, Network & Disk Forensics | Process & code-injection hunting in RAM dumps, PCAP DNS/C2/stream reconstruction, NTFS MFT & deleted file recovery, artifact timeline correlation | Volatility3 + Scapy + Sleuth Kit + Binwalk |
โก Context Efficiency: Tiered Router, Compact Schema & Paging
Large reverse-engineering MCP servers often suffer from context window bloat: advertising 180+ verbose tool schemas and returning 50,000-line decompilations can exhaust an LLM's context in 2 turns. Reversecore MCP solves this with a 4-layer optimization architecture:
| Optimization Layer | How to Enable | Context Savings & Behavior |
|---|
| 1. Tiered Router Mode | REVERSECORE_PROFILE=tiered (or reversecore-mcp setup --tiered) | -94.4% prompt token overhead. Exposes 12 daily core tools + 3 router tools (call_expert_agent, search_tools, execute_domain_tool) backed by 8 domain sub-agents (vulnerability_hunter, forensics, malware_analyst, deobfuscator, symbolic_engine, diff_analyst, source_auditor, modern_runtime). |
| 2. Compact Schema Profile | REVERSECORE_SCHEMA_PROFILE=compact | ~65% smaller tools/list payload. Strips verbose docstring examples, flattens deep anyOf/oneOf unions, and caps JSON Schema depth at 10 while retaining full server-side Pydantic validation. |
| 3. Summary-First Paging | Pass detail="summary" to r2_decompile, Radare2_disassemble*, Radare2_list_strings, memory_extract_strings | Returns a compact structural digest + an evidence_id handle (ev_<12-hex>). Call inspect_analysis_view(evidence_id, facet, offset, limit, filter_query) to paginate or filter lines/strings/functions on demand. |
| 4. On-Demand Guidance | Built-in tools: search_guidance & read_guidance_section | Instead of stuffing 20,000 words of manuals into the system prompt, the agent queries built-in reversing playbooks (playbook:target-routing, playbook:go-rust-reversing, playbook:electron-asar, playbook:unity-il2cpp, playbook:epistemological-discipline) only when needed. |
Architecture
AI Client (Claude / Cursor / any MCP-compatible client)
โ MCP Protocol (stdio or HTTP/SSE)
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ FastMCP 3.4.11 Server โ
โ 194 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:
| 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 |
๐ Authoritative Tool Catalog & Parameter Reference (186 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 6 modular execution profiles (tiered, full, static, malware, forensics, vuln-research):
| Profile | Registered Tools | Schema Size | LLM Context Saving vs Full | Recommended Domain |
|---|
tiered | 15 | ~11.5 KB | -94.4% (~28,500 tokens) | โก Daily interactive AI pair programming (12 core tools + 3 sub-agent router tools accessing all 186 tools on demand) |
full | 186 | 144.2 KB | Baseline (0%) | Complete enterprise reverse engineering suite |
vuln-research | 138 | 96.4 KB | -33.1% (~10,000 tokens) | Fuzzing, ASan crash triage, CVE hunting, exploit research |
static | 132 | 91.2 KB | -36.8% (~11,100 tokens) | Disassembly, decompilation (r2ghidra), LIEF, modern runtimes, static triage |
malware | 100 | 76.5 KB | -46.9% (~14,100 tokens) | Threat triage, YARA scanning, deobfuscation, anti-analysis |
forensics | 81 | 51.8 KB | -64.1% (~19,300 tokens) | Memory forensics (Volatility3), network PCAP (Scapy), disk |
Exposing all 186 tools to an LLM on every turn wastes ~30,000+ tokens of prompt context. Tiered mode solves this by exposing only 15 high-frequency tools while retaining seamless access to all 186 tools via specialized Sub-Agents and a dynamic tool router:
-
Tier-1: Daily Core Tools (12 tools):
run_file, parse_binary_with_lief, get_server_health
Radare2_open_file, Radare2_close_file, Radare2_list_functions, Radare2_list_strings, Radare2_disassemble_function, Radare2_decompile_function
extract_iocs, run_yara, create_analysis_report
-
Tier-2: Domain Expert Sub-Agents & Universal Router (3 tools):
call_expert_agent: Dispatches high-level multi-step domain tasks to specialized Sub-Agents:
modern_runtime: Stripped Go (gopclntab) & Rust (.dep-v0 crates), Electron app.asar IPC/security audit, Unity IL2CPP (global-metadata.dat), feature code reconstruction (reconstruct_feature_code), paged view inspection (inspect_analysis_view), and on-demand guidance (search_guidance)
vulnerability_hunter: CVE scanning, dangerous API auditing, ROP gadget collection, heap analysis, crash triage
forensics: Network PCAP analysis, C2 extraction, Volatility3 memory dumps, SleuthKit disk carving
malware_analyst: IOC extraction, dormant backdoors, CAPA capability mapping, adaptive vaccines
deobfuscator: DIE packer detection, string decryption, API hash resolution, dead-code elimination
symbolic_engine: angr symbolic path reachability, constraint solving, dataflow taint tracing
diff_analyst: Semantic binary diffing, 1-day patch review, cross-binary annotation transfer
source_auditor: AST vulnerability scanning (Python) and regex pattern auditing (C/C++)
search_tools: Dynamic keyword and domain search across all 186 tools with parameter schemas and example invocations.
execute_domain_tool: Universal execution gateway to invoke any of the 186 specialized tools on demand with custom arguments.
Enable tiered mode via reversecore-mcp setup --tiered or export REVERSECORE_PROFILE=tiered.
| # | 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 |
| # | Tool | Backend | Description |
|---|
| 25 | audit_source_code | AST + Regex | Python AST scanning + C/C++ regex scanning for dangerous patterns |
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 |
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 |
| # | 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) |
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 |
| # | 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 194 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
โก One-Line Automated Setup (Recommended)
Automatically detects installed AI agents (Cursor, Claude Code, Windsurf, Claude Desktop, Antigravity, VS Code Cline/Roo Code, Codex) and registers Reversecore_MCP with automatic backups and zero manual JSON editing:
curl -fsSL https://raw.githubusercontent.com/sjkim1127/Reversecore_MCP/main/install.sh | bash
uvx --from reversecore-mcp reversecore-setup
pipx run reversecore-mcp setup
irm https://raw.githubusercontent.com/sjkim1127/Reversecore_MCP/main/install.ps1 | iex
Common Setup Options:
reversecore-mcp setup --tiered
reversecore-mcp setup --docker
reversecore-mcp setup --dry-run
reversecore-mcp setup --list
reversecore-mcp setup --remove
Manual Installation Options
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
Or manually:
docker compose --profile x86 up -d
docker compose --profile arm64 up -d
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:
๐ macOS
{
"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
{
"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
{
"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) |
REVERSECORE_FORENSICS_MAX_RECOVERED_BYTES | 500000000 | Maximum bytes recovered from one disk inode |
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:
| 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
Testing
pytest tests/ -v
pytest tests/unit/ -v
pytest tests/integration/ -v
pytest tests/unit/ --cov=reversecore_mcp --cov-fail-under=80
pytest tests/unit/test_cli_tools.py::TestRunFile::test_success -v
pytest tests/ -m security -v
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/
ruff format reversecore_mcp/
mypy reversecore_mcp/
bandit -r reversecore_mcp/
pip-audit
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:
| Service | Profile | Description |
|---|
reversecore-mcp | default, x86 | Intel/AMD x86_64 |
reversecore-mcp-arm64 | arm64, macos | Apple Silicon ARM64 |
redis | all profiles | Redis 7 Alpine for task queue and caching |
Resource limits: 2.0 CPU cores, 4 GB memory per container.
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
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 (194 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:
| Exception | Code | Type | When |
|---|
ReversecoreError | RCMCP-E000 | UNKNOWN_ERROR | Base class for all errors |
ValidationError | RCMCP-E001 | VALIDATION_ERROR | Invalid input, bad parameters |
ExecutionTimeoutError | RCMCP-E002 | TIMEOUT_ERROR | Tool exceeded timeout |
ToolNotFoundError | RCMCP-E003 | TOOL_ERROR | Required CLI tool not installed |
OutputLimitExceededError | RCMCP-E004 | OUTPUT_ERROR | Output exceeded max size |
ToolExecutionError | RCMCP-E005 | EXECUTION_ERROR | Subprocess returned non-zero |
BinaryAnalysisError | RCMCP-E100 | BINARY_ANALYSIS_ERROR | General binary analysis failure |
DecompilationError | RCMCP-E101 | DECOMPILATION_ERROR | r2ghidra decompilation failed |
DisassemblyError | RCMCP-E102 | DISASSEMBLY_ERROR | Radare2 disassembly failed |
StructureRecoveryError | RCMCP-E103 | STRUCTURE_RECOVERY_ERROR | C struct recovery failed |
SignatureGenerationError | RCMCP-E104 | SIGNATURE_GENERATION_ERROR | YARA/signature generation failed |
EmulationError | RCMCP-E105 | EMULATION_ERROR | ESIL emulation failed |
ToolTimeoutError | RCMCP-E200 | TOOL_TIMEOUT_ERROR | External tool timed out |
GhidraConnectionError | RCMCP-E201 | GHIDRA_CONNECTION_ERROR | r2ghidra connection issue |
Radare2Error | RCMCP-E202 | RADARE2_ERROR | Radare2 command failed |
WorkspaceError | RCMCP-E300 | WORKSPACE_ERROR | Workspace file access error |
SecurityViolationError | RCMCP-E301 | SECURITY_VIOLATION | Security policy violation |
PathTraversalError | RCMCP-E302 | PATH_TRAVERSAL | Path traversal attempt detected |
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.
Follow this pattern to add a new MCP tool:
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:
| Architecture | Key | r2 Arch | Bit Widths | PC Register | SP Register |
|---|
| Intel 32-bit | x86 | x86 | 32 | eip | esp |
| Intel/AMD 64-bit | x86_64 | x86 | 64 | rip | rsp |
| ARM 32-bit / Thumb | arm32 | arm | 16, 32 | r15 | r13 |
| ARM 64-bit (AArch64) | arm64 | arm | 64 | pc | sp |
| MIPS | mips | mips | 32, 64 | pc | sp |
| RISC-V | riscv | riscv | 32, 64 | pc | sp |
| PowerPC | ppc | ppc | 32, 64 | pc | r1 |
Alias resolution is handled automatically:
amd64 โ x86_64
aarch64 โ arm64
arm with bits=64 โ arm64
arm with bits=16 or bits=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:
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):
| Level | Backend | Key Format | TTL | Purpose |
|---|
| L1 | Redis | ghidra:decompile:{file_hash}:{function_address}:{decompiler} | 1 hour (3600s) | Fast, shared across sessions |
| L2 | SQLite | Table decompilation_cache | Persistent | Survives Redis restarts |
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:
| Item | How |
|---|
| Set API key | MCP_API_KEY=<strong-random-key> |
| Use non-root user | Built-in: container runs as appuser (UID 1000) |
| Set resource limits | Default: 2 CPU / 4 GB RAM in docker-compose.yml |
| Enable structured logging | LOG_FORMAT=json for log aggregation |
| Configure Redis | REDIS_URL=redis://<host>:6379/0 for task queue and caching |
| Set workspace path | REVERSECORE_WORKSPACE=/path/to/isolated/directory |
| Review rate limits | REVERSECORE_RATE_LIMIT=60 (requests/min, adjust as needed) |
| Enable sandbox | REVERSECORE_SANDBOX_ENABLED=true for dynamic analysis isolation |
Health Checks
The server provides HTTP health check endpoints for orchestration:
curl http://localhost:8000/health/live
curl http://localhost:8000/health/ready
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
Tool returns RCMCP-E003: Tool not found
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:
brew install radare2 yara binwalk sleuthkit
apt install radare2 yara binwalk sleuthkit
Timeout error (RCMCP-E002 / RCMCP-E200)
Analysis exceeded the configured timeout.
Solution: Increase the timeout:
export REVERSECORE_DEFAULT_TOOL_TIMEOUT=300
For large binaries (>100 MB), consider using quick-scan variants:
run_capa_quick instead of run_capa
detect_packer instead of detect_packer_deep
Path traversal error (RCMCP-E302)
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
Docker container won't start on Apple Silicon
Make sure you're using the ARM64 profile:
docker compose --profile arm64 up -d
Or use the auto-detection script:
Redis connection refused
The task queue requires a running Redis instance.
Solution: Start Redis alongside the main service:
docker compose --profile arm64 up -d
Or disable Redis-dependent features by not setting REDIS_URL.
r2ghidra decompilation produces empty output
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
Does this replace Ghidra or IDA Pro?
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.
Is a separate Ghidra or JDK installation needed?
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.
What MCP clients are supported?
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.
Can I analyze Windows PE files on Linux/macOS?
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.
How safe is it to analyze malware with this tool?
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.
What's the maximum file size?
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.