by sjkim1127
Provides a security‑first MCP server that enables AI agents to orchestrate Ghidra, Radare2, and YARA for fully automated reverse‑engineering and malware‑analysis workflows.
Reversecore Mcp delivers an enterprise‑grade MCP server that wraps industry‑standard reverse‑engineering tools (Ghidra, Radare2, strings, binwalk, YARA, Capstone, LIEF) behind a unified, secure API. AI assistants can invoke these tools via natural‑language prompts to perform end‑to‑end binary analysis, structure recovery, control‑flow visualization, emulation, and automatic signature generation.
stdio mode or connect to the HTTP endpoint (http://host:8000/mcp).run_file, run_strings, run_radare2, smart_decompile, generate_yara_rule) either directly via the MCP protocol or through the built‑in prompts such as full_analysis_mode.ToolResult object with status, data, and optional metadata. Errors are returned as structured ToolError objects.shell=True, strict path validation, sandboxed Docker deployment.full_analysis_mode, basic_analysis_mode, etc.) to enforce SOPs and reduce token usage.full_analysis_mode) that discovers, understands, and neutralizes threats, producing YARA rules and optional binary patches.Q: Which AI clients are supported? A: Any MCP‑compatible client works; tested with Cursor AI (recommended) and Claude Desktop (HTTP mode).
Q: Do I need to install dependencies manually? A: No. The Docker image contains radare2, Ghidra, YARA, Capstone, LIEF, and all required runtimes. Local installation is possible but requires manual setup of those tools.
Q: How are files accessed securely?
A: Only paths inside the configured workspace (/app/workspace) are allowed. All inputs are resolved to absolute paths and validated against a whitelist. Symlinks are resolved to prevent traversal attacks.
Q: Can I add custom YARA rules?
A: Place them in the read‑only rules directory (/app/rules) or inside the workspace. The server automatically discovers .yar/.yara files for run_yara and adaptive_vaccine.
Q: What are the resource limits? A: Default output size per tool is 10 MiB, execution timeout 300 s, and LIEF parsing is capped at 1 GiB. All limits are configurable via environment variables.
Q: How do I enable detailed logging?
A: Set LOG_LEVEL=DEBUG and optionally LOG_FORMAT=json when starting the container.
Q: Is the server safe for malware analysis? A: Yes. The server runs inside an isolated Docker container, disallows shell injection, and never executes untrusted code—only static analysis and sandboxed ESIL emulation are performed.
![]()
An enterprise-grade MCP (Model Context Protocol) server that empowers AI agents to perform comprehensive reverse engineering workflows through natural language commands. From basic triage to advanced decompilation, structure recovery, cross-reference analysis, and defense signature generation, Reversecore_MCP provides a secure, performant interface to industry-standard reverse engineering tools, enabling AI assistants to conduct end-to-end malware analysis and security research.
"Detecting the Undetectable"
Ghost Trace is a proprietary hybrid analysis technology exclusive to Reversecore_MCP that transcends the limits of traditional static and dynamic analysis. It identifies "Logic Bombs" and "Dormant Malware" that evade sandbox detection by combining static code analysis with AI-driven partial emulation.
radare2 ESIL to surgically emulate only the suspicious code paths with AI-injected context, verifying malicious behavior without running the full program.Ghost Trace allows you to predict future malicious behavior that hasn't happened yet.
"Restoring Developer Intent"
The Neural Decompiler transcends traditional decompilation by transforming raw, mechanical C code into "human-like" natural code. It uses advanced heuristics and pattern matching (simulating AI understanding) to restore the original developer's intent.
iVar1, v2 to meaningful names like sock_fd, file_handle based on API usage context.*(ptr + 4)) and intelligently converts them into structure field accesses (ptr->field_4)."Ghost Trace finds it. Neural Decompiler understands it. Adaptive Vaccine stops it."
Trinity Defense System (TDS) is the ultimate integrated defense framework that orchestrates all three signature technologies into a fully automated threat detection and neutralization pipeline.
3-Phase Automated Defense:
Key Features:
"Complete defense automation: Detect → Analyze → Neutralize"
| Category | Minimum Specification | Recommended Specification |
|---|---|---|
| Use Case | Single file analysis, basic CLI tools (file, strings), lightweight YARA scanning | Large-scale parallel scanning, Ghidra decompilation, angr symbolic execution, Docker builds |
| CPU | 4+ cores (Intel i5 / Ryzen 5 equivalent) | 8+ cores with P-cores (M3/M4 Pro, Ryzen 7/9, Intel i7/i9) |
| RAM | 16 GB | 32 GB+ (or 24 GB unified memory on Mac) |
| Storage | 512 GB SSD (SATA3 or faster) | 1 TB NVMe SSD (PCIe 4.0+ recommended) |
| OS | Linux / macOS (Docker required) | Linux / macOS (Unix-based systems recommended) |
Full-Cycle Capabilities: Upload → Analysis → X-Refs (Context) → Structures (C++ Recovery) → Visualization (CFG) → Emulation (ESIL) → Decompilation (Pseudo-C) → Defense (YARA Rules)
scan_workspace: Live file count updatesmatch_libraries: Function categorization progressreversecore://{filename}/strings - Extract stringsreversecore://{filename}/iocs - IOC summaryreversecore://{filename}/func/{address}/code - Decompiled codereversecore://{filename}/func/{address}/asm - Assemblyreversecore://{filename}/func/{address}/cfg - Control flow graphanalyze_with_ai: Get AI opinions on ambiguous datasuggest_function_name: AI-powered function namingThis project is a toy project created with the assistance of AI. It was developed for analyzing C++ files and serves as an educational exploration of reverse engineering tools integrated with the Model Context Protocol (MCP). While designed as a learning project, it demonstrates production-ready practices in security, performance, and architecture.
🎯 CRITICAL: AI Agents should ALWAYS use the built-in Prompt system (
/prompt) instead of manually orchestrating tool calls.
The built-in prompts automatically handle:
Manual tool calls are error-prone and inefficient. Use prompts.
Select the appropriate prompt based on your analysis goal:
full_analysis_modeUse for: Comprehensive malware/binary analysis (A to Z)
basic_analysis_modeUse for: Quick triage and threat assessment
game_analysis_modeUse for: Game client reverse engineering
firmware_analysis_modeUse for: Firmware and IoT device analysis
vulnerability_research_modeUse for: Bug hunting and exploit development
crypto_analysis_modeUse for: Cryptographic implementation analysis
Example Usage:
User: "Analyze /app/workspace/sample.exe for malware"
AI: [Selects full_analysis_mode prompt]
→ Automatically executes: Recon → Filter → Deep Analysis → Report
Prompt Selection Guide:
basic_analysis_mode firstfull_analysis_modegame_analysis_modefirmware_analysis_modevulnerability_research_modecrypto_analysis_mode⚠️ For Advanced Users Only: If you must manually call tools (not recommended), refer to the Tool Documentation and ensure proper file paths (
/app/workspace/...), no shell metacharacters, and correct VA vs Offset usage.
The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. It provides a universal interface for AI assistants to interact with various services while maintaining security and performance.
Reversecore_MCP is a specialized MCP server designed for reverse engineering and malware analysis workflows. It provides a secure, standardized interface for AI agents to interact with industry-standard reverse engineering tools:
file: Identify file types and metadatastrings: Extract printable strings from binariesradare2: Disassemble and analyze binary executablesbinwalk: Analyze and extract embedded files from firmwareyara-python: Pattern matching and malware detectioncapstone: Multi-architecture disassembly enginelief: Binary parsing and analysis (PE, ELF, Mach-O)Traditional reverse engineering workflows require:
Reversecore_MCP handles all of this automatically, allowing AI agents to focus on analysis rather than tool management. The server provides:
Reversecore_MCP/
├── reversecore_mcp/ # Main package directory
│ ├── __init__.py
│ ├── tools/ # Tool definitions (MCP tools)
│ │ ├── __init__.py
│ │ ├── cli_tools.py # CLI tool wrappers (radare2, strings, file, binwalk)
│ │ └── lib_tools.py # Library wrappers (YARA, Capstone, LIEF, IOC extraction)
│ └── core/ # Core utilities and infrastructure
│ ├── __init__.py
│ ├── command_spec.py # Command specifications and validation
│ ├── config.py # Configuration management
│ ├── decorators.py # Function decorators (logging, metrics)
│ ├── error_formatting.py # Error message formatting
│ ├── error_handling.py # Error handling decorators
│ ├── exceptions.py # Custom exception classes
│ ├── execution.py # Safe subprocess execution
│ ├── ghidra_helper.py # Ghidra integration utilities
│ ├── logging_config.py # Logging configuration
│ ├── metrics.py # Performance metrics collection
│ ├── result.py # Tool result models (ToolSuccess, ToolError)
│ ├── security.py # Input validation and path sanitization
│ └── validators.py # Input validators
├── docs/ # Documentation
│ ├── FILE_COPY_TOOL_GUIDE.md
│ ├── PERFORMANCE_IMPROVEMENT_REPORT.md
│ ├── PERFORMANCE_IMPROVEMENT_REPORT_V2.md
│ ├── XREFS_AND_STRUCTURES_IMPLEMENTATION.md
│ └── sample_reports/ # Sample malware analysis reports
├── tests/ # Test suite
│ ├── __init__.py
│ ├── conftest.py # Pytest configuration and fixtures
│ ├── fixtures/ # Test data and fixtures
│ ├── integration/ # Integration tests
│ └── unit/ # Unit tests
├── server.py # Server entry point (FastMCP initialization)
├── Dockerfile # Containerized deployment configuration
├── requirements.txt # Python dependencies
├── requirements-dev.txt # Development dependencies
├── pytest.ini # Pytest configuration
├── .gitignore # Git ignore patterns
├── .trivyignore # Trivy security scanner ignore patterns
├── LICENSE # MIT License
└── README.md # This file
server.py acts as the central registration point, importing and registering all tool modulesshell=True: All subprocess calls use list-based arguments, never shell commandsshlex.quote() on list arguments: When using subprocess.run(["cmd", arg1, arg2]), arguments are passed directly to the process without shell interpretation, so quoting is unnecessary and would break commandsDecision: Do NOT use shlex.quote() when passing arguments as a list to subprocess.run().
Rationale:
subprocess.run(["r2", "-q", "-c", r2_command, file_path]), arguments are passed directly to the process without shell interpretationshlex.quote() is only needed when constructing shell commands (with shell=True)shlex.quote() on list arguments would break commands like "pdf @ main" by adding quotes that radare2 would interpret literallyshell=True, validate and sanitize user input at the application layerImplementation:
core/security.py validate file paths and command stringsDecision: Use registration functions pattern for tool organization.
Rationale:
MCPMixin for component-based organization, but a simpler pattern is sufficient for this use caseregister_*_tools(mcp: FastMCP) function that registers all tools in that moduleImplementation Pattern:
# tools/cli_tools.py
def register_cli_tools(mcp: FastMCP) -> None:
mcp.tool(run_strings)
mcp.tool(run_radare2)
# server.py
from reversecore_mcp.tools import cli_tools, lib_tools
mcp = FastMCP(name="Reversecore_MCP")
cli_tools.register_cli_tools(mcp)
lib_tools.register_lib_tools(mcp)
Decision: Implement streaming subprocess execution with configurable output limits.
Rationale:
capture_output=TrueImplementation:
core/execution.py provides execute_subprocess_streaming() functionsubprocess.Popen with stdout=subprocess.PIPErun_strings accept max_output_size parameterDecision: Use Dockerfile with pinned package versions + r2pipe for radare2 integration.
Rationale:
Implementation:
requirements.txt with version constraintsr2pipe is used for radare2 operations (when implemented)# Build the Docker image
docker build -t reversecore-mcp .
Reversecore_MCP supports two transport modes. Stdio mode is now the standard.
Stdio Mode (Standard/Recommended):
# Run with stdio transport (for local AI clients like Cursor)
docker run -it \
-v ./my_samples:/app/workspace \
-e REVERSECORE_WORKSPACE=/app/workspace \
-e MCP_TRANSPORT=stdio \
reversecore-mcp
🚀 Performance Tip: Using RAM Disk (tmpfs)
For 10x faster analysis (especially for I/O-heavy tools like radare2), mount the workspace as a RAM disk:
docker run -it \
-v ./my_samples:/app/samples:ro \
--tmpfs /app/workspace:rw,size=4g \
-e REVERSECORE_WORKSPACE=/app/workspace \
-e MCP_TRANSPORT=stdio \
reversecore-mcp
Note: When using tmpfs, the workspace starts empty. You must copy files from /app/samples to /app/workspace using the copy_to_workspace tool before analysis.
HTTP Mode (Alternative):
# Run with HTTP transport on port 8000
# Mount your samples directory to /app/workspace
docker run -d \
-p 8000:8000 \
-v ./my_samples:/app/workspace \
-e REVERSECORE_WORKSPACE=/app/workspace \
-e MCP_TRANSPORT=http \
--name reversecore-mcp \
reversecore-mcp
Important Notes:
/app/workspace)REVERSECORE_WORKSPACE environment variable sets the allowed workspace path/app/rules (read-only) or in the workspace directoryInstall system dependencies:
# On Debian/Ubuntu
sudo apt-get install radare2 yara libyara-dev binutils openjdk-17-jre-headless
Install Python dependencies:
pip install -r requirements.txt
Configure environment variables:
Create a .env file in the project root with the following content:
GHIDRA_INSTALL_DIR=/path/to/ghidra_11.4.2_PUBLIC
REVERSECORE_WORKSPACE=/path/to/workspace
Note: You must download and extract Ghidra 11.4.2 manually for local installation.
Run the server:
# Stdio mode (Standard)
MCP_TRANSPORT=stdio python server.py
# (Optional) HTTP mode
MCP_TRANSPORT=http python server.py
⚠️ Note on Claude Desktop: Using Reversecore_MCP with Claude Desktop is not recommended. Claude Desktop has limitations with stdio transport, inconsistent process lifecycle management, and lacks proper workspace isolation features required for secure reverse engineering workflows. We strongly recommend using Cursor AI or other MCP clients that support HTTP transport with proper containerization.
Reversecore_MCP works with MCP-compatible clients. This guide focuses on Cursor AI, which is the recommended client for this server.
~/.cursor/mcp.json (Windows: C:\Users\<USER>\.cursor\mcp.json).{
"mcpServers": {
"reversecore": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "C:/Reversecore_Workspace:/app/workspace",
"-e", "REVERSECORE_WORKSPACE=/app/workspace",
"-e", "MCP_TRANSPORT=stdio",
"reversecore-mcp"
]
}
}
}
To add it per-project instead, create a .cursor/mcp.json file in your project root with the same contents.
If you prefer to use HTTP mode instead, you can run the server manually and configure Cursor to connect to it:
docker run -d \
-p 8000:8000 \
-v ./my_samples:/app/workspace \
-e REVERSECORE_WORKSPACE=/app/workspace \
-e MCP_TRANSPORT=http \
--name reversecore-mcp \
reversecore-mcp
{
"mcpServers": {
"reversecore": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}
If the server is running correctly, you should be able to open http://127.0.0.1:8000/docs in your browser.
⚠️ Note on Claude Desktop: Using Reversecore_MCP with Claude Desktop is not recommended. Claude Desktop has limitations with stdio transport, inconsistent process lifecycle management, and lacks proper workspace isolation features required for secure reverse engineering workflows. We strongly recommend using Cursor AI or other MCP clients that support HTTP transport with proper containerization.
Reversecore_MCP follows the standard MCP protocol and should work with any MCP-compatible client. Configure the client to connect to:
MCP_TRANSPORT=stdio and configure your client to launch the server as a subprocess. This is the recommended mode for most use cases.MCP_TRANSPORT=http and point the client to http://127.0.0.1:8000/mcp (or your configured host/port). This mode is useful for remote access or when stdio is not supported.For clients that support MCP over stdio (like Cursor AI), use the stdio mode for better integration. For clients that only support HTTP, ensure the Reversecore_MCP server is running in HTTP mode and accessible at the configured endpoint.
Reversecore_MCP is designed to enable AI agents to perform reverse engineering tasks through natural language commands. The server wraps common reverse engineering CLI tools and Python libraries, making them accessible to AI assistants for automated triage and analysis workflows.
Quickly identify suspicious files and extract indicators of compromise (IOCs):
AI Agent: "Analyze sample.exe in my workspace. What type of file is it and does it contain any suspicious strings?"
→ Uses run_file + run_strings to identify PE executable and extract URLs, IPs, suspicious API calls
Automate detection of known malware families using YARA rules:
AI Agent: "Scan all files in workspace with my malware detection rules"
→ Uses run_yara to match against custom rulesets and identify threats
Deep dive into executable structure and behavior:
AI Agent: "Disassemble the main function and identify what APIs it calls"
→ Uses run_radare2 to disassemble code and extract function calls
Analyze embedded systems and extract firmware components:
AI Agent: "What file systems are embedded in this firmware image?"
→ Uses run_binwalk to identify embedded file systems, bootloaders, etc.
Reversecore_MCP provides a built-in expert mode prompt (full_analysis_mode) that enforces a Standard Operating Procedure (SOP) for comprehensive analysis.
How to use:
Select the full_analysis_mode prompt in your MCP client and provide the filename.
SOP Workflow:
run_file), extract IOCs (run_strings + extract_iocs), check for packers.match_libraries) to focus on user code.analyze_xrefs), structure recovery (recover_structures), and smart decompilation (smart_decompile). Safely emulate code if needed (emulate_machine_code).generate_yara_rule) and write a final comprehensive report.Language Support: The prompt automatically adapts to the user's language (English, Korean, Chinese, etc.) while keeping technical terms intact.
For quick triage, use the basic_analysis_mode prompt.
How to use:
Select the basic_analysis_mode prompt and provide the filename.
SOP Workflow:
run_file) and check for packing (parse_binary_with_lief).run_strings) and identify IOCs (extract_iocs).run_radare2 with "ii") to infer behavior.Reversecore_MCP offers domain-specific prompts for targeted analysis:
game_analysis_mode: Focuses on Game Logic, Anti-Cheat, and Network Protocol.firmware_analysis_mode: Focuses on File System Extraction, Architecture ID, and Hardcoded Secrets.vulnerability_research_mode: Focuses on Bug Hunting, Dangerous API usage, and Mitigation checks.crypto_analysis_mode: Focuses on Cryptographic Constants, Algorithms, and Key Management.The server exposes tools that can be called by AI agents via the MCP protocol. Below are examples of how to use each tool:
run_file)Tool Call:
{
"tool": "run_file",
"arguments": {
"file_path": "/app/workspace/sample.exe"
}
}
Response:
{
"status": "success",
"data": "PE32 executable (GUI) Intel 80386, for MS Windows",
"metadata": {
"bytes_read": 128,
"tool": "run_file"
}
}
Error Response:
{
"status": "error",
"error_code": "VALIDATION_ERROR",
"message": "File path is outside allowed directories: /tmp/payload.exe",
"hint": "Copy the sample under REVERSECORE_WORKSPACE before calling run_file",
"details": {
"allowed_directories": ["/app/workspace"],
"path": "/tmp/payload.exe"
}
}
Use Case: Initial file identification during triage
run_strings)Tool Call:
{
"tool": "run_strings",
"arguments": {
"file_path": "/app/workspace/sample.exe",
"min_length": 4,
"max_output_size": 10000000,
"timeout": 300
}
}
Response:
{
"status": "success",
"data": "Hello World\nGetProcAddress\nLoadLibraryA\nkernel32.dll\nhttp://malicious-domain.com/payload\nC:\\Windows\\System32\\cmd.exe\n...",
"metadata": {
"bytes_read": 1048576,
"tool": "run_strings"
}
}
Use Case: Extract URLs, file paths, API names, debug strings for IOC extraction
run_radare2)Tool Call:
{
"tool": "run_radare2",
"arguments": {
"file_path": "/app/workspace/sample.exe",
"r2_command": "pdf @ main",
"max_output_size": 10000000,
"timeout": 300
}
}
Response:
{
"status": "success",
"data": " ;-- main:\n/ (fcn) sym.main 42\n| sym.main ();\n| 0x00401000 55 push rbp\n| 0x00401001 4889e5 mov rbp, rsp\n| 0x00401004 4883ec20 sub rsp, 0x20\n| 0x00401008 488d0d... lea rcx, str.Hello_World\n| 0x0040100f e8... call sym.imp.printf\n...",
"metadata": {
"bytes_read": 4096,
"tool": "run_radare2"
}
}
Use Case: Analyze function behavior, control flow, identify malicious code patterns
Common Commands:
pdf @ main - Disassemble main functionafl - List all functionsii - List importsiz - List strings in data sectionafi @ main - Show function inforun_yara)Tool Call:
{
"tool": "run_yara",
"arguments": {
"file_path": "/app/workspace/sample.exe",
"rule_file": "/app/rules/malware.yar",
"timeout": 300
}
}
Response:
{
"status": "success",
"data": {
"matches": [
{
"rule": "SuspiciousPE",
"namespace": "default",
"tags": ["malware", "trojan"],
"meta": {"author": "analyst", "description": "Detects suspicious PE behavior"},
"strings": [
{
"identifier": "$s1",
"offset": 1024,
"matched_data": "48656c6c6f20576f726c64"
},
{
"identifier": "$api1",
"offset": 2048,
"matched_data": "437265617465526d6f746554687265616445"
}
]
}
],
"match_count": 1
}
}
Use Case: Automated malware family detection, compliance scanning, threat hunting
disassemble_with_capstone)Tool Call:
{
"tool": "disassemble_with_capstone",
"arguments": {
"file_path": "/app/workspace/sample.exe",
"offset": 0,
"size": 1024,
"arch": "x86",
"mode": "64"
}
}
Response:
{
"status": "success",
"data": "0x0:\tpush\trbp\n0x1:\tmov\trbp, rsp\n0x4:\tsub\trsp, 0x20\n0x8:\tlea\trcx, [rip + 0x100]\n0xf:\tcall\t0x200\n...",
"metadata": {
"instruction_count": 64
}
}
Use Case: Quick disassembly of specific code sections, shellcode analysis
Supported Architectures:
parse_binary_with_lief)Tool Call:
{
"tool": "parse_binary_with_lief",
"arguments": {
"file_path": "/app/workspace/sample.exe",
"timeout": 300
}
}
Response:
{
"status": "success",
"data": {
"format": "PE",
"architecture": "x86-64",
"entrypoint": "0x1400",
"sections": [
{
"name": ".text",
"virtual_address": "0x1000",
"size": 16384,
"entropy": 6.42
},
{
"name": ".data",
"virtual_address": "0x5000",
"size": 4096,
"entropy": 3.21
}
],
"imports": [
{
"library": "kernel32.dll",
"functions": ["CreateFileA", "ReadFile", "WriteFile"]
}
],
"exports": [],
"security_features": {
"has_nx": true,
"has_aslr": true,
"has_pie": false,
"has_canary": true
}
}
}
Use Case: Extract metadata, analyze binary structure, identify security features
When using with AI assistants, you can use natural language instead of direct API calls:
Example Conversations:
User: "I have a suspicious executable called malware.exe in my workspace.
Can you analyze it and tell me what it does?"
AI Agent:
1. Uses run_file to identify file type
2. Uses run_strings to extract IOCs
3. Uses run_yara to check against known malware signatures
4. Uses run_radare2 to analyze main function
5. Provides comprehensive report with findings
User: "Scan all PE files in my workspace for ransomware indicators"
AI Agent:
1. Lists files in workspace
2. For each PE file:
- Uses run_yara with ransomware rules
- Uses run_strings to look for ransom notes
- Checks for suspicious API calls
3. Summarizes results with risk assessment
User: "What security features are enabled in this binary?"
AI Agent:
1. Uses parse_binary_with_lief to extract security info
2. Reports ASLR, DEP/NX, stack canaries, code signing status
3. Provides recommendations based on findings
run_file for identification, then targeted toolsmax_output_sizerun_file: Identify file type using the file command
PE32 executable (GUI) Intel 80386, for MS Windowsrun_strings: Extract printable strings from binary files
run_radare2: Execute radare2 commands on binary files
pdf @ main to disassemble main functionrun_binwalk: Analyze and extract embedded files from firmware/images
copy_to_workspace: Copy files from any location to workspace
/mnt/user-data/uploads)list_workspace: List all files in workspace directory
scan_workspace: Batch scan all files in the workspace
run_file, parse_binary_with_lief, and run_yara in parallelscan_workspace(["*.exe", "*.dll"])generate_function_graph: Create Control Flow Graph (CFG) visualizations
mermaid: LLM-optimized flowchart syntax (default)json: Raw radare2 graph data for processingdot: Graphviz format for external renderingagfj command internallygenerate_function_graph("/app/workspace/sample.exe", "main", "mermaid")emulate_machine_code: Safe code execution simulation with ESIL
emulate_machine_code("/app/workspace/malware.exe", "0x401000", 100)smart_decompile: Transform assembly into readable pseudo-C code
pdc commandsmart_decompile("/app/workspace/sample.exe", "main")smart_decompile("/app/workspace/sample.exe", "main", use_ghidra=False)generate_yara_rule: Automatic malware signature generation
generate_yara_rule("/app/workspace/malware.exe", "main", 64, "trojan_xyz")analyze_xrefs: Analyze cross-references (X-Refs) for functions and data
"all", "to" (callers), "from" (callees)analyze_xrefs("/app/workspace/malware.exe", "sym.decrypt", "to")recover_structures: Recover C++ class structures and data types
recover_structures("/app/workspace/game.exe", "Player::update")recover_structures("/app/workspace/binary", "main", use_ghidra=False)diff_binaries: Compare two binary files to identify code changes
diff_binaries("/app/workspace/v1.exe", "/app/workspace/v2.exe")diff_binaries("/app/workspace/old.exe", "/app/workspace/new.exe", "main")match_libraries: Identify and filter known library functions
match_libraries("/app/workspace/large_app.exe")match_libraries("/app/workspace/game.exe", "/app/rules/game_engine.sig")Reversecore's proprietary signature technologies that transcend traditional reverse engineering:
ghost_trace: Hybrid analysis for detecting dormant malware and logic bombs
ghost_trace("/app/workspace/suspicious.exe")ghost_trace("/app/workspace/malware.exe", focus_function="sym.hidden", hypothesis={"registers": {"eax": "0xDEADBEEF"}})neural_decompile: AI-simulated code refinement for human-readable output
neural_decompile("/app/workspace/binary.exe", "0x401000")adaptive_vaccine: Automated defense generation from threat analysis
adaptive_vaccine(threat_report, action="yara")adaptive_vaccine(threat_report, action="patch", file_path="/app/workspace/malware.exe", dry_run=True)trinity_defense: Integrated 3-phase automated threat detection and neutralization
"discover": Phase 1 only (quick scan)"analyze": Phase 1+2 (full understanding)"full": All 3 phases (complete automation)trinity_defense("/app/workspace/apt.exe", mode="full")trinity_defense("/app/workspace/sample.bin", mode="discover")run_yara: Scan files using YARA rules
disassemble_with_capstone: Disassemble binary code using Capstone
parse_binary_with_lief: Parse binary files with LIEF
extract_iocs: Extract Indicators of Compromise from text
strings) into actionable dataextract_iocs(run_strings_output)trace_execution_path: Find exploit paths from user input to dangerous sinks
system, strcpy, etc.recv) can reach a vulnerable sinktrace_execution_path("/app/workspace/vuln.exe", "system")scan_for_versions: Detect open-source library versions and CVEs
scan_for_versions("/app/workspace/firmware.bin")analyze_variant_changes: Map malware lineage and evolution
analyze_variant_changes("old.exe", "new.exe")Reversecore_MCP now supports a complete end-to-end analysis workflow:
📥 Upload/Copy → 📊 Analysis → 🔗 X-Refs (Context) → 🏗️ Structures (C++ Recovery) →
🔍 Visualization (CFG) → 🔮 Emulation (ESIL) → 📝 Decompilation (Pseudo-C) → 🛡️ Defense (YARA)
Example Complete Workflow:
# 1. Copy sample to workspace
copy_to_workspace("/path/to/upload/malware.exe")
# 2. Basic triage
run_file("/app/workspace/malware.exe")
run_strings("/app/workspace/malware.exe")
# 3. Identify suspicious function
run_radare2("/app/workspace/malware.exe", "afl~decrypt")
# 4. Analyze cross-references - WHO calls this and WHAT it calls
analyze_xrefs("/app/workspace/malware.exe", "sym.decrypt", "all")
# Returns: callers, callees, data references - understand the context
# 5. Recover C++ structures - make "this + 0x4" meaningful
recover_structures("/app/workspace/malware.exe", "sym.decrypt")
# Returns: struct definitions transforming offsets to named fields
# 6. Visualize control flow
generate_function_graph("/app/workspace/malware.exe", "sym.decrypt", "mermaid")
# 7. Emulate to reveal obfuscated strings
emulate_machine_code("/app/workspace/malware.exe", "sym.decrypt", 200)
# 8. Decompile for high-level understanding
smart_decompile("/app/workspace/malware.exe", "sym.decrypt")
# 9. Trace exploit paths
trace_execution_path("/app/workspace/malware.exe", "system")
# 10. Generate detection signature
generate_yara_rule("/app/workspace/malware.exe", "sym.decrypt", 128, "malware_decrypt")
Why This Workflow Works:
run_radare2("/app/workspace/malware.exe", "afl~decrypt")
generate_function_graph("/app/workspace/malware.exe", "sym.decrypt", "mermaid")
emulate_machine_code("/app/workspace/malware.exe", "sym.decrypt", 200)
smart_decompile("/app/workspace/malware.exe", "sym.decrypt")
generate_yara_rule("/app/workspace/malware.exe", "sym.decrypt", 128, "malware_decrypt")
## Performance
Reversecore_MCP is optimized for production workloads and large-scale analysis:
### Key Performance Features
#### Streaming Output Processing
- Handles files up to GB scale without memory issues
- 8KB chunk-based reading with configurable limits
- Automatic truncation with warnings when limits exceeded
- Default max output: 10MB per tool invocation
#### Adaptive Polling (Windows)
- Reduces CPU usage for long-running operations
- Starts at 50ms polling interval, adapts to 100ms max
- Resets to 50ms when data is received
- Maintains responsiveness while minimizing resource usage
#### Optimized Path Validation
- Significant reduction in path conversion overhead
- Cached string conversions for repeated validations
- Early returns for common cases
- Efficient directory checks with minimal filesystem calls
#### YARA Processing Improvements
- Faster match processing for large result sets
- Eliminates redundant attribute lookups
- Optimized type checking with `isinstance()`
- Optimized for large result sets
#### Memory-Efficient Operations
- Enumerate-based iteration instead of list slicing
- No intermediate list creation for large datasets
- Lazy evaluation where possible
- Configurable limits prevent OOM conditions
### Performance Benchmarks
| Operation | Performance | Notes |
|-----------|-------------|-------|
| File Type Detection | < 100ms | For typical binaries |
| String Extraction | Streaming | No memory limit with streaming |
| YARA Scanning | 2,500 matches/sec | Large ruleset performance |
| Path Validation | 1,000 validations/sec | Cached conversions |
| Disassembly | Depends on size | Configurable output limits |
| CFG Generation | < 2 seconds | Mermaid format for 50-node graphs |
| ESIL Emulation | < 1 second | For 50-200 instruction sequences |
| Smart Decompile | 2-5 seconds | Function complexity dependent |
| YARA Rule Gen | < 1 second | For 64-1024 byte patterns |
| Metrics Collection | Thread-safe | 1000 concurrent ops validated |
### Configuration
Performance can be tuned via environment variables:
```bash
# Maximum output size per tool (bytes)
TOOL_MAX_OUTPUT_SIZE=10485760 # 10MB default
# LIEF maximum file size (bytes)
LIEF_MAX_FILE_SIZE=1000000000 # 1GB default
# Tool timeouts (seconds)
TOOL_TIMEOUT=300 # 5 minutes default
# Rate limiting (requests per minute, HTTP mode only)
RATE_LIMIT=60 # 60 requests/minute default
Security is a top priority in Reversecore_MCP. The server implements multiple layers of protection:
When deploying Reversecore_MCP:
# Recommended Docker configuration
docker run -d \
-p 127.0.0.1:8000:8000 \ # Bind to localhost only
-v ./samples:/app/workspace:ro \ # Read-only if possible
-v ./rules:/app/rules:ro \ # YARA rules read-only
-e REVERSECORE_WORKSPACE=/app/workspace \
-e REVERSECORE_READ_DIRS=/app/rules \
--security-opt=no-new-privileges \ # Additional security
--cap-drop=ALL \ # Drop all capabilities
--name reversecore-mcp \
reversecore-mcp
shell=True usage anywhere in codebaseFor security issues, please see our security policy or contact the maintainers directly.
Every MCP tool now returns a Pydantic ToolResult union consisting of:
ToolSuccess: { "status": "success", "data": <string|dict>, "metadata": { ... } }ToolError: { "status": "error", "error_code": "...", "message": "...", "hint": "...", "details": { ... } }The contract is intentionally small so AI agents can branch on status and inspect structured metadata without parsing natural-language strings.
metadata typically includes diagnostic context such as bytes_read, instruction_count, or tool-specific timings, while details carries structured fields for error surfaces (e.g., allowed_directories, timeout_seconds).
Success Example:
{
"status": "success",
"data": "ELF 64-bit LSB executable, x86-64, dynamically linked, not stripped",
"metadata": {
"bytes_read": 512,
"tool": "run_file",
"execution_time": 0.12
}
}
Error Example:
{
"status": "error",
"error_code": "VALIDATION_ERROR",
"message": "File path is outside allowed directories: /tmp/payload.bin",
"hint": "Place samples under REVERSECORE_WORKSPACE or add a read-only path via REVERSECORE_READ_DIRS",
"details": {
"allowed_directories": ["/app/workspace"],
"path": "/tmp/payload.bin"
}
}
VALIDATION_ERROR – File paths or parameters failed validationTOOL_NOT_FOUND – Required CLI binary (file/strings/binwalk) is missing on hostTIMEOUT – Tool exceeded the configured execution deadlineOUTPUT_LIMIT – Streaming output exceeded the configured max_output_sizeDEPENDENCY_MISSING – Python dependency such as yara or capstone isn’t installedINTERNAL_ERROR – Unexpected failure surfaced through the handle_tool_errors decoratorClients should always branch on status, inspect error_code, and surface hint/details verbatim so users know how to remediate issues quickly.
Create tool function in the appropriate module:
reversecore_mcp/tools/cli_tools.py for CLI toolsreversecore_mcp/tools/lib_tools.py for library-based toolsFollow the ToolResult pattern:
from reversecore_mcp.core.decorators import log_execution
from reversecore_mcp.core.error_handling import handle_tool_errors
from reversecore_mcp.core.metrics import track_metrics
from reversecore_mcp.core.result import ToolResult, success
@log_execution(tool_name="my_tool")
@track_metrics("my_tool")
@handle_tool_errors
def my_tool(file_path: str, param: str, timeout: int = 300) -> ToolResult:
"""Tool description for MCP clients."""
validated = validate_file_path(file_path)
output, bytes_read = execute_subprocess_streaming(
["tool", "--flag", param, str(validated)],
timeout=timeout,
)
return success(output, bytes_read=bytes_read)
log_execution adds structured logging, track_metrics records latency/error metrics, and handle_tool_errors converts raised exceptions into ToolError responses automatically.
def register_cli_tools(mcp: FastMCP) -> None:
mcp.tool(run_file)
mcp.tool(run_strings)
mcp.tool(my_tool) # Add your tool here
pytest tests/unit/test_cli_tools.py -k test_my_tool
# Install development dependencies
pip install -r requirements-dev.txt
# Run all tests
pytest tests/
# Run with coverage (target: 80%+ coverage)
pytest tests/ --cov=reversecore_mcp --cov-report=html --cov-report=term --cov-fail-under=80
# Current test stats (as of latest commit)
# - Total tests: 172 passed, 6 skipped
# - Coverage: 87% (exceeds 80% threshold)
# - Key test suites:
# - CFG Tools: 9 tests (Mermaid/JSON/DOT format validation)
# - ESIL Emulation: 11 tests (register state parsing, safety limits)
# - Smart Decompile: 12 tests (pseudo-C generation, metadata extraction)
# - Thread Safety: 8 tests (concurrent metrics collection)
# - Command Validation: 31 tests (security regression prevention)
# Run specific test file
pytest tests/unit/test_cli_tools.py
# Run specific test suite
pytest tests/unit/test_smart_decompile.py -v
pytest tests/unit/test_cfg_tools.py -v
pytest tests/unit/test_emulation_tools.py -v
# Run with verbose output
pytest tests/ -v
# Format code with black
black reversecore_mcp/ tests/
# Lint with ruff
ruff check reversecore_mcp/ tests/
# Type checking with mypy
mypy reversecore_mcp/
# Security scanning with bandit
bandit -r reversecore_mcp/
# Build the image
docker build -t reversecore-mcp:dev .
# Test the image
docker run --rm reversecore-mcp:dev python -c "import reversecore_mcp; print('OK')"
# Run tests in container
docker run --rm reversecore-mcp:dev pytest /app/tests/
Symptoms: Claude Desktop or Cursor shows connection error
Solutions:
docker psdocker ps | grep reversecoredocker logs reversecore-mcpdocker restart reversecore-mcpnetstat -an | grep 8000 (should show LISTENING)For stdio mode:
# Test the command directly
MCP_TRANSPORT=stdio python -m reversecore_mcp.server
# Should not exit immediately, wait for input
Symptoms: Tool returns file not found error
Solutions:
ls -la /path/to/your/samples/
docker inspect reversecore-mcp | grep -A 10 Mounts
/app/workspace/sample.exe/home/user/samples/sample.exedocker exec reversecore-mcp env | grep REVERSECORE
Symptoms: Cannot access files or directories
Solutions:
ls -la /path/to/samples/
# Should be readable by all or by UID 1000 (typical Docker user)
chmod -R 755 /path/to/samples/
# Add :z flag to docker run for SELinux
-v ./samples:/app/workspace:z
Symptoms: Container consuming excessive CPU
Solutions:
docker exec reversecore-mcp ps aux
# Reduce timeouts if needed
docker run -e TOOL_TIMEOUT=60 ...
docker run -e RATE_LIMIT=30 ...
docker logs reversecore-mcp --tail 100
Symptoms: Import errors when starting server
Solutions:
docker exec reversecore-mcp pip list
docker build --no-cache -t reversecore-mcp .
export PYTHONPATH=/path/to/Reversecore_MCP:$PYTHONPATH
Symptoms: r2 commands return errors or unexpected output
Solutions:
r2 -q -c "pdf @ main" /path/to/binary
pdf @ mainpdf @ main && echo donefile /path/to/binary
{"timeout": 600}
Symptoms: YARA returns no matches or errors
Solutions:
yara -c /path/to/rules.yar
/app/workspace/rules.yar/app/rules/rules.yaryara /path/to/rules.yar /path/to/sample
ls -la /path/to/rules.yar
Symptoms: Tools timeout or hang on large files
Solutions:
{"timeout": 900} // 15 minutes
{"max_output_size": 5242880} // 5MB
Enable detailed logging for troubleshooting:
# HTTP mode with debug logging
docker run -d \
-p 8000:8000 \
-v ./samples:/app/workspace \
-e REVERSECORE_WORKSPACE=/app/workspace \
-e MCP_TRANSPORT=http \
-e LOG_LEVEL=DEBUG \
-e LOG_FORMAT=json \
--name reversecore-mcp \
reversecore-mcp
# View logs
docker logs -f reversecore-mcp
If you encounter issues not covered here:
Q: What is MCP and why should I use it?
A: MCP (Model Context Protocol) is a standardized protocol for connecting AI assistants to external tools and data sources. Using Reversecore_MCP allows AI agents to perform reverse engineering tasks without requiring manual tool invocation or output parsing. It's particularly useful for automating malware triage, binary analysis, and security research workflows.
Q: Is Reversecore_MCP free to use?
A: Yes, Reversecore_MCP is open source under the MIT license. You can use it for personal, academic, or commercial purposes.
Q: What AI assistants are compatible?
A: Reversecore_MCP works with any MCP-compatible client. Tested clients include:
Q: Can I use this for malware analysis?
A: Yes, that's one of the primary use cases. The server is designed with security in mind (sandboxing, input validation, no code execution) and provides tools commonly used in malware analysis workflows. However, always analyze malware in an isolated environment.
Q: Should I use Docker or local installation?
A: Docker is strongly recommended because:
Use local installation only for development or if Docker isn't available.
Q: Can I run this on Windows?
A: Yes, through Docker Desktop. Native Windows installation is possible but requires manual installation of tools (radare2, binwalk) which may have Windows-specific issues. Docker provides the most consistent experience.
Q: How much disk space do I need?
A: Approximately:
Q: What Python version do I need?
A: Python 3.11 or higher. The project uses modern Python features and type hints that require 3.11+.
Q: What's the maximum file size I can analyze?
A: It depends on the tool:
For very large files, use streaming tools (strings, radare2) and specify output limits.
Q: Can I analyze multiple files at once?
A: Currently, each tool invocation analyzes one file. To analyze multiple files:
Q: How do I add custom YARA rules?
A: Place YARA rule files in:
/app/workspace/rules/ (read-write)/app/rules/ (read-only, recommended)Mount additional directories via REVERSECORE_READ_DIRS:
docker run -e REVERSECORE_READ_DIRS=/app/rules,/app/custom_rules ...
Q: Can I extract files with binwalk?
A: Currently, binwalk is analysis-only (no extraction) for security reasons. This prevents uncontrolled file creation in the workspace. File extraction may be added in a future release with appropriate safeguards.
Q: What radare2 commands are supported?
A: Read-only commands only, validated against a whitelist. Supported commands include:
pdf, pd, pdcaaa, afl, afi, afviI, iz, iipx, pxw, pxqCommands that modify files or execute code are blocked.
Q: Why is my analysis slow?
A: Common causes:
See Performance section for optimization tips.
Q: How many requests can it handle?
A: In HTTP mode:
For higher throughput, increase RATE_LIMIT or deploy multiple instances.
Q: Will it run out of memory?
A: No, with proper configuration:
Q: Is it safe to analyze malware with this tool?
A: The tool provides several safety features:
However, always analyze malware in a dedicated, isolated environment (VM, air-gapped system).
Q: Can AI agents execute arbitrary commands?
A: No. The server:
Q: How are secrets handled?
A: No secrets or credentials are required. File access is controlled via:
Q: What data is logged?
A: Configurable via LOG_LEVEL:
Q: I get "file not found" but the file exists
A: Check path mapping:
/home/user/samples/file.exe/app/workspace/file.exe (use this in tool calls)-v /home/user/samples:/app/workspaceQ: How do I see what the tool is actually doing?
A: Enable debug logging:
docker run -e LOG_LEVEL=DEBUG ...
docker logs -f reversecore-mcp
This shows full command lines, timing, and output sizes.
Q: How do I add a new tool?
A: See Development section for detailed steps. In summary:
Q: How do I contribute?
A: See Contributing section. We welcome:
Q: Where can I get help with development?
A: Check:
We welcome contributions to Reversecore_MCP! Here's how you can help:
# Fork the repository under your GitHub account first, then clone your fork
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
git checkout -b feature/your-feature-name
Make Changes:
Test Your Changes:
# Run tests
pytest tests/
# Run linters
ruff check reversecore_mcp/ tests/
black --check reversecore_mcp/ tests/
# Test Docker build
docker build -t reversecore-mcp:test .
git add .
git commit -m "Add: descriptive commit message"
git push origin feature/your-feature-name
shell=True, always validate inputsAll PRs must:
Feel free to:
Thank you for contributing! 🙏
MIT License - see LICENSE file for details.
This project uses several open-source tools and libraries:
Please review and comply with each dependency's license terms.
Special thanks to:
For detailed malware analysis examples and case studies, please visit our Wiki.
Built with ❤️ for the reverse engineering and security research community
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by chaitin
A self‑hosted web application firewall and reverse proxy that protects web applications from attacks and exploits by filtering, monitoring, and blocking malicious HTTP/S traffic.
by safedep
Provides enterprise‑grade open source software supply chain security by scanning source code, dependencies, containers and SBOMs, detecting vulnerabilities and malicious packages, and enforcing policy as code.
by semgrep
Offers an MCP server that lets LLMs, agents, and IDEs run Semgrep scans to detect security vulnerabilities in source code.
by PortSwigger
Enables Burp Suite to communicate with AI clients via the Model Context Protocol, providing an MCP server and bundled stdio proxy.
by cycodehq
Boost security in the development lifecycle via SAST, SCA, secrets, and IaC scanning.
by mobb-dev
Provides automatic security vulnerability remediation for code via a command‑line interface and an MCP server, leveraging findings from popular SAST tools such as Checkmarx, CodeQL, Fortify, and Snyk.
by ChristophEnglisch
Provides AI‑powered administration of Keycloak users and realms through the Model Context Protocol, enabling automated creation, deletion, and listing of users and realms from MCP clients such as Claude Desktop.
by Spathodea-Network
Provides a Model Context Protocol server that enables querying and retrieving threat intelligence data from OpenCTI through a standardized interface.
by firstorderai
Provides seamless access to two‑factor authentication codes and passwords for AI agents, enabling automated login while maintaining security.