Reversecore_MCP - A security-first MCP server that empowers AI agent

项目说明

<di="center">

<img src="icon.png" alt="Re MCP" width="480" />

Re MCP

AI-Powered Reverse Engineering & Security Analysis Context Protocol

*An MCP server that gives AI assistants like Claude and Cursor the ability to perform reverse engineering, malware analysis, research, digital forensics, and source code auditing through natural language.*

---

![CI/CD]()
![Python]()
![FastMCP]()
![PyPI]()
![Docker]()
![OpenSSF Scorecard]()
![H]()

![Watch the Demo]()
![SafeSkill ]()

</div>

---

Table of Contents

---

What is Re MCP?

Re MCP is a Model Context Protocol server that wraps 151 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:

The AI assistant breaks this into tool calls:

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, adapti generation, autonomous hunting |
| research | Dangerous API detection, ROP gadget discovery, heap exploit analysis, crash triage, PoC generation |
| Digital forensics | Memory forensics (), 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, , email delivery |

---

Architecture

The ser 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 a; Python 3.10 and 3.11 installs omit angr.

Core Infrastructure (37 modules)

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

| Module | Purpose |
|---|---|
| config.py | Pydantic BaseSettings with 34+ en |
| security.py | Input sanitization, command argument |
| .py | File and binary path 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 |
| e.py | E classification system: OBSERVED, INFERRED, POSSIBLE |
| resilience.py | Retry, circuit-breaker, and timeout decorator patterns |
| task_queue.py | Background task queue + 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 () |
| analysis_cache.py | Multi-le cache (L1: Redis, L2: SQLite) |
| result.py | ToolSuccess / ToolError Pydantic models |
| exceptions.py | 17 exception classes with RCMCP-E* error codes |
| decorators.py | , |
| error_handling.py | 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 (3-5x faster than stdlib json) |
| logging_config.py | Loguru-based structured logging |
| report_generator.py | Report rendering engine (Markdown, PDF ) |
| resource_manager.py | MCP resource lifecycle management |
| sast/python_ast_scanner.py | Python AST-based scanner |
| sast/regex_scanner.py | C/C++ regex-based scanner |
| sast/rule_manager.py | SAST rule loading and management |

---

Tool Catalog (151 Tools)

> 📖 Authoritative Tool Catalog & Parameter Reference (151 Tools)
> 📊 Tool Profile Footprint & Context Benchmark Matrix

Every tool returns a structured ToolResult — either a ToolSuccess with typed data or a ToolError with an RCMCP-E* error code. Tools are organized into 11 domain plugins across 5 modular execution profiles (full, static, malware, forensics, ):

| Profile | Registered Tools | Schema Size | LLM Context Saving vs Full | Recommended Domain |
|---|:---:|:---:|:---:|---|
| full | 151 | 112.6 KB | Baseline (0%) | Complete enterprise reverse engineering suite |
| | 103 | 70.2 KB | -37.7% (~10,800 tokens) | Fuzzing, ASan crash triage, C, exploit research |
| static | 97 | 64.8 KB | -42.5% (~12,200 tokens) | Disassembly, decompilation (r2ghidra), LIEF, static triage |
| malware | 65 | 59.4 KB | -47.2% (~13,600 tokens) | Threat triage, YARA scanning, deobfuscation, anti-analysis |
| forensics | 57 | 36.4 KB | -67.7% (~19,500 tokens) | Memory forensics (), network PCAP (Scapy), disk |

---

🔍 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 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_ad | Radare2 + YARA | Ad YARA rules with beha indicators |
| 12 | scan_for_ | LIEF + strings | Scan binary for embedded strings |
| 13 | extract_rtti_info | Radare2 | Extract C++ RTTI (Run-Time Type Information) |
| 14 | diff_binaries | Radare2 | Semantic binary diff between two file |
| 15 | analyze_ | Radare2 | Analyze changes between binary |
| 16 | match_libraries | Radare2 | Identify statically linked libraries by function fingerprint |
| 17 | patch_diff_1day | Radare2 + heuristics | Automated patch diff analysis for 1-day research |
| 18 | analyze_patch_diff_auto | Radare2 + inference | Automated patch 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 | | 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 | Remo older than a threshold |
| 41 | list_analysis_sessions | List all acti |
| 42 | export_memory_store | Export all memories to a portable format |
| 43 | import_memory_store | Import memories from an export file |

Ser (2 tools)

| # | Tool | Description |
|---|---|---|
| 44 | get_ser | Uptime, memory usage, loaded tools, Python |
| 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 (Ghidra engine embedded in r2, no J) |
| 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 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_reco | 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 | Retrie |
| 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 | adapti | YARA + Radare2 | Generate detection YARA rules + binary patches to neutralize threats |
| 78 | | 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_ | Radare2 + angr | Autonomous hunting pipeline |
| 84 | analyze_heap_exploit | Radare2 + heuristics | Heap exploitation analysis (UAF, double-free, o) |

---

🕵️ Digital Forensics Plugin (22 tools)

Memory Forensics (6 tools)

| # | Tool | Backend | Description |
|---|---|---|---|
| 85 | memory_analyze | | Full memory dump analysis |
| 86 | memory_list_processes | | List running processes from memory dump |
| 87 | memory_detect_injections | | Detect code injection in process memory |
| 88 | memory_extract_strings | | Extract strings from process memory |
| 89 | memory_dump_module | | Dump a loaded module from memory |
| 90 | memory_list_symbols | | 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_reco | Sleuth Kit | Reco 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_ | Sleuth Kit | 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 ser (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 acti sessions |
| 114 | add_ioc | Collect and tag IOCs during a li |
| 115 | add_analysis_note | Add categorized notes (finding, warning, behavior) |
| 116 | add_mitre_technique | Document MITRE ATT&CK technique IDs |
| 117 | set_se | Set session se (low/medium/high/critical) |
| 118 | create_analysis_report | Render report in 4 modes: full_analysis, quick_triage, ioc_summary, executi |
| 119 | generate_ | Generate a VEX ( 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 e 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 comprehensi: 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 |
| apt_hunting_mode | APT-specific hunting: lateral mo, persistence, data exfiltration |
| malware_defense_mode | Defense-oriented: generate detection rules and mitigations |
| unpacking_mode | Analyze and bypass packing/obfuscation (Themida, , 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 |
|---|---|
| ode | Bug hunting: buffer o, 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_ | Autonomous hunting pipeline |

C & Exploit De (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 research |
| cde | Full C 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 e before proceeding) and e classification rules that prevent the AI from stating speculation as fact. Every finding must be labeled as OBSERVED (directly ), INFERRED (logically derived from static analysis), or POSSIBLE (requires further ).

---

MCP Resources (11 URIs)

Resources are read-only data endpoints that AI clients can access through URI templates. They complement tools by pro structured data without requiring explicit tool calls.

Static Resources

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

Dynamic Resources (Per-Binary Filesystem)

These URIs resol and invoke the corresponding analysis tools on demand:

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

---

Quick Start

Option 1 — PyPI (Simplest)

> Prerequisites: Radare2 must be installed on your system (r2 --). 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:

Option 3 — Build from Source (Docker Compose)

Or manually:

Option 4 — Python (Local De)

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

---

Connect to Your AI Client

Add the ser 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 Compose, this mode channels stdio directly into the running container. Zero startup latency, persistent memory, and full tool a.

> Replace re with re if you are on Intel/AMD.

---

🌐 Option 2: SSE HTTP Mode

For network-based streaming (Ser Events):

---

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

Runs a fresh, isolated container for every session:

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

</details>

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

</details>

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

</details>

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

---

Configuration

All settings can be provided or a .env file (see .en). Settings are managed BaseSettings with the RE prefix.

Core Settings

| | Default | Description |
|---|---|---|
| MCP_TRANSPORT | stdio | Transport mode: stdio or http |
| RE | ./ (cwd) | Analysis workspace directory |
| RE | "" | Comma-separated list of additional read-only directories |
| RE | false | Raise errors for missing paths instead of warnings |
| REORS | false | Enable structured error responses with error codes |
| REIMEOUT | 120 | Default tool execution timeout in seconds |
| REE | 10000000 | Maximum output size for tools (bytes) |
| RERECO | 500000000 | Maximum bytes recovered from one disk inode |

HTTP Mode Settings

| | Default | Description |
|---|---|---|
| MCP_HOST | 0.0.0.0 | Host interface to bind (auto-o 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) |
| RE | 60 | Max requests per minute (HTTP mode only, ) |
| MAX_UPLOAD_SIZE | 100000000 | Maximum upload size (100 MB default) |
| FILE_RETENTION_MINUTES | 1440 | Retention period for uploaded files (24h default) |

Radare2 Settings

| | Default | Description |
|---|---|---|
| RE | 3 | Number of Radare2 connections in the pool |
| RET | 30 | Timeout for acquiring a connection from the pool |
| RE | "" | Comma-separated list of r2 extension classes (module:ClassName) |
| REJECTS | 3 | Max cached r2ghidra decompiler projects |
| REONS | "" | Comma-separated list of Ghidra extension classes |
| MAX_EMULATION_INSTRUCTIONS | 1000 | Maximum ESIL emulation instructions |

Sandbox Settings

| | Default | Description |
|---|---|---|
| RED | false | Enable sandbox execution for dynamic analysis tools |
| RE | auto | Sandbox mode: auto, host, container, disabled |
| RE_IMAGE | re:latest | Docker image for sandbox execution |
| REMIT | 1.0 | CPU core limit for sandbox containers |
| RE_LIMIT | 512m | Memory limit for sandbox containers |
| REIMIT | 100 | PID limit for sandbox containers |
| RE | nobody | Non-root user for sandbox execution |

Storage & Queue

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

Logging

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

Plugins & SAST

| | Default | Description |
|---|---|---|
| RE | "" | Comma-separated directories to scan for extension plugins |
| REH | "" | 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, ne strings (execution.py) |
| Path tra pre | () and () resol and confine access to the workspace (.py) |
| TOCTOU mitigation | bypass_cache=True flag re- paths to prevent race conditions |
| Input sanitization | All parameters sanitized before execution (security.py) |
| CSRF protection | Dashboard forms require token-based CSRF (dashboard/__init__.py) |

Network & Authentication

| Control | Implementation |
|---|---|
| Timing-attack-safe auth | secrets.compare_digest() for API key comparison (web/auth.py) |
| Restricted auth | 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 |
| 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 unre CVEs |
| Container scanning | Tri Docker images for (LOW through CRITICAL) |
| Exploit safety gate | POC templates scanned with Bandit; Hypothesis DAST fuzzing; container isolation |

Structured Error Handling

All 17 exception classes carry RCMCP-E* error codes for programmatic handling. See Error Handling for the full hierarchy.

---

De

Setup

Testing

Test status:

Test markers:

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

Code Quality

Pre-commit Hooks

The following hooks run automatically on every commit:

1. Ruff — lint with auto-fix + format check
2. trailing-whitespace — remo whitespace
3. end-of-file-fixer — ensure files end with newline
4. check-yaml / check-json — YAML/JSON syntax
5. check-added-large-files — block files > 1 MB
6. check-merge-conflict — detect unresol markers
7. detect-pri — 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.

> Zero-bypass policy: CI/CD failures are ne 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:

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

Layer 2: Application Image (Dockerfile)

Inherits from the base image and copies application code:

Build time: ~60 seconds.

Docker Compose

Three services with architecture-specific profiles:

| Service | Profile | Description |
|---|---|---|
| re | default, x86 | Intel/AMD x86_64 |
| re | 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 en (any OS) |
| Docker | 20.10+ | 24.0+ |
| Python (local mode) | 3.10 | 3.11 or 3.12 |

---

Project Structure

Other directories:

---

Error Handling

All custom exceptions inherit from Re and carry structured error codes:

| Exception | Code | Type | When |
|---|---|---|---|
| Re | RCMCP-E000 | UNKNOWN_ERROR | Base class for all errors |
| | RCMCP-E001 | | 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 |
| StructureReco | RCMCP-E103 | STRUCTURE_RECO | 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 |
| Security | RCMCP-E301 | SECURITY_ | Security policy |
| PathTra | RCMCP-E302 | PATH_TRA | Path tra 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.

---

Adding New Tools

Follow this pattern to add a new MCP tool:

Then register it in the appropriate plugin's __init__.py and add tests in tests/unit/.

---

Contributing

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

Please read the Contributing Guide for code standards, docstring con (Google-style), and the pull request checklist.

---

Documentation

| Document | Description |
|---|---|
| Installation Guide | Detailed setup for all en |
| Architecture Guide | System design & component details |
| Contributing Guide | Code standards, docstrings, PR workflow |
| Testing Guide | Test patterns, fixtures, and co |
| API Reference | Tool and module reference |
| User Guide | Analysis workflows |

---

Usage Examples

Example 1: Basic Malware Triage

Example 2: Research with Taint Analysis

Example 3: Digital Forensics In

Example 4: Patch Diffing for 1-day Research

---

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:

Tools like Radare2_esil_emulate, assemble_instructions, and r2_simulate_patch use this registry to configure the analysis en correctly for any target binary.

---

Result Cache System

Two caching layers minimize redundant computation:

Tool Result Cache (result_cache.py)

The decorator caches any tool's output based on a SHA256 hash of the binary file and the tool's keyword arguments:

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(), through the get_tool_metrics tool.

Analysis Cache (analysis_cache.py)

A multi-le 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 | Survi restarts |

Import/Export: The export_analysis_cache and import_analysis_cache tools allow saving cache state to/from rcpack files for sharing between en.

---

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:

How It Works

Storage: Async SQLite database at the path configured by MEMORY_DB_PATH (default: ~/.re/memory.db).

Portability: Use export_memory_store and import_memory_store to transfer the entire memory database between en.

---

Web Dashboard

When running in HTTP mode (MCP_TRANSPORT=http), a web dashboard is a at . It provides:

Tech stack: FastAPI + Jinja2 templates + HTMX (loaded locally from dashboard/static/, no CDN dependency for CSP compliance).

Security features:

---

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 | RE=/path/to/isolated/directory |
| Review rate limits | RE=60 (requests/min, adjust as needed) |
| Enable sandbox | RED=true for dynamic analysis isolation |

Health Checks

The ser HTTP health check endpoints for orchestration:

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 TCP connectivity to port 8000 every 30 seconds. Docker and Kubernetes will automatically restart unhealthy containers.

---

Troubleshooting

Common Issues

<details>
<summary><b>Tool returns RCMCP-E003: Tool not found</b></summary>

The required CLI tool is not installed in the en.

Solution: If using Docker, the tool is in the base image:

If using local Python installation, install the missing tool:

</details>

<details>
<summary><b>Timeout error (RCMCP-E002 / RCMCP-E200)</b></summary>

Analysis exceeded the configured timeout.

Solution: Increase the timeout:

For large binaries (>100 MB), consider using quick-scan :

<details>
<summary><b>Path tra error (RCMCP-E302)</b></summary>

You referenced a file outside the workspace directory.

Solution: Copy the file into the workspace first:

Or mount additional directories as read-only:

</details>

<details>
<summary><b>Docker container won't start on Apple Silicon</b></summary>

Make sure you're using the ARM64 profile:

Or use the auto-detection script:

</details>

<details>
<summary><b>Redis connection refused</b></summary>

The task queue requires a running Redis instance.

Solution: Start Redis alongside the main service:

Or disable Redis-dependent features by not setting REDIS_URL.
</details>

<details>
<summary><b>r2ghidra decompilation produces empty output</b></summary>

This usually means the function wasn't analyzed first.

Solution: Run analysis before decompilation:

</details>

---

FAQ

<details>
<summary><b>Does this replace Ghidra or IDA Pro?</b></summary>

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 interacti workflow of a full disassembler. Its purpose is to let AI assistants perform analysis tasks programmatically.
</details>

<details>
<summary><b>Is a separate Ghidra or JDK installation needed?</b></summary>

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.
</details>

<details>
<summary><b>What MCP clients are supported?</b></summary>

Any client that implements the Model Context Protocol specification. Tested with: Claude Desktop, Cursor, Windsurf, and Google Antigravity. The ser both stdio and HTTP/SSE transports.
</details>

<details>
<summary><b>Can I analyze Windows PE files on Linux/macOS?</b></summary>

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 ha depending on the target architecture.
</details>

<details>
<summary><b>How safe is it to analyze malware with this tool?</b></summary>

The Docker container provides isolation: non-root user, no network by default in CI, resource limits. For li analysis, we recommend running in a dedicated VM or using the sandbox feature (RED=true). Static analysis tools (r2, YARA, strings) ne the target binary.
</details>

<details>
<summary><b>What's the maximum file size?</b></summary>

Default limits:

All limits are configurable .
</details>

---

Acknowledgments

This project is built on the work of many open-source projects:

| Project | Role in Re MCP |
|---|---|
| Radare2 | Disassembly, emulation, binary analysis |
| r2ghidra | Ghidra decompiler engine for Radare2 |
| FastMCP | MCP ser |
| YARA | Pattern matching for malware detection |
| LIEF | Binary format parsing (PE, ELF, Mach-O) |
| CAPA | Mandiant FLARE capability detection |
| angr | Symbolic execution engine |
| Capstone | Disassembly framework |
| Keystone | Assembly framework |
| pwntools | Exploit de toolkit |
| ROPgadget | ROP gadget finder |
| | Memory forensics framework |
| Scapy | Network packet analysis |
| Sleuth Kit | Disk forensics toolkit |
| Binwalk | Firmware analysis |
| Detect It Easy | Packer/compiler detection |

---

License

MIT — see LICENSE for details.

---

<di="center">

GitHub · PyPI · FastMCP Docs · MCP Spec · Radare2 · YARA

</div>

项目信息

开发语言：Python

Star 数：207

技术要点

该项目属于病毒分析方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A security-first MCP server that empowers AI agents to perform automated reverse engineering, malware analysis, forensics, vulnerability research, and SAST — powered by Radare2, YARA, LIEF, Capstone, and more.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。