Reversecore Mcp

Reversecore_MCP

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.

👻 Reversecore Signature: Ghost Trace (Preview)

"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.

🕵️‍♂️ Orphan Function Detection: Identifies hidden code blocks that are never called during normal execution but exist in the binary (potential backdoors).
💣 Logic Bomb Hunter: Scans for "Magic Value" triggers (e.g., specific dates, hardcoded keys) that activate malicious payloads.
👻 Hybrid Emulation: Uses 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.

🧠 Reversecore Signature: Neural Decompiler (Preview)

"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.

📝 Semantic Variable Renaming: Automatically renames iVar1, v2 to meaningful names like sock_fd, file_handle based on API usage context.
🏗️ Structure Inference: Detects pointer arithmetic patterns (*(ptr + 4)) and intelligently converts them into structure field accesses (ptr->field_4).
💡 Smart Annotation: Adds high-level comments to explain "Magic Values" and complex logic blocks, making the code instantly understandable.

🔱 Reversecore Signature: Trinity Defense System (Preview)

"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:

Phase 1 (DISCOVER): Ghost Trace scans for hidden threats - orphan functions, logic bombs, and dormant malware
Phase 2 (UNDERSTAND): Neural Decompiler analyzes threat intent by refining code and identifying malicious patterns
Phase 3 (NEUTRALIZE): Adaptive Vaccine generates YARA detection rules and (optionally) binary patches to neutralize threats

Key Features:

🔄 Full Automation: One command analyzes the entire binary from discovery to defense generation
🎯 Intent Inference: Automatically classifies threats (backdoor, time bomb, data exfiltration, etc.)
🛡️ Defense Generation: Auto-generates YARA rules for immediate deployment
📊 Actionable Reports: Provides specific recommendations for each threat type

"Complete defense automation: Detect → Analyze → Neutralize"

💻 System Requirements

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)

Key Features

Core Reverse Engineering

Security-First Design: No shell=True, comprehensive input validation, path sanitization
High Performance: Streaming output for large files, configurable limits, adaptive polling
Comprehensive Toolset: Ghidra, Radare2, strings, binwalk, YARA, Capstone, LIEF support
Advanced Analysis: CFG visualization, ESIL emulation, smart decompilation
C++ Structure Recovery: Transform "this + 0x4" → "Player.health" with Ghidra data type propagation
Cross-Reference Analysis: Discover code context - who calls what, understand program flow
Defense Integration: Automatic YARA rule generation from analysis
Docker Ready: Pre-configured containerized deployment with all dependencies
MCP Compatible: Works with Cursor AI, Claude Desktop, and other MCP clients
Production Ready: Extensive error handling, logging, rate limiting, and monitoring
Thread-Safe: Concurrent-safe metrics collection with async/sync support
AI-Optimized: Full-cycle workflow from upload to defense signature generation

FastMCP Advanced Features ⭐ NEW

Progress Reporting: Real-time progress indicators for long-running operations
- scan_workspace: Live file count updates
- match_libraries: Function categorization progress
Client Logging: Error messages and warnings displayed directly in client
- Enhanced debugging with contextual error messages
- Transparent fallback notifications
Image Content: Direct PNG image generation for CFGs
- Visual function flow graphs in chat
- Automated graphviz integration
Dynamic Resources: Binary Virtual File System with URI templates
- reversecore://{filename}/strings - Extract strings
- reversecore://{filename}/iocs - IOC summary
- reversecore://{filename}/func/{address}/code - Decompiled code
- reversecore://{filename}/func/{address}/asm - Assembly
- reversecore://{filename}/func/{address}/cfg - Control flow graph
Lifespan Management: Automated server lifecycle handling
- Dependency validation on startup
- Automatic temp file cleanup on shutdown
AI Sampling: Tools can ask AI for help during execution
- analyze_with_ai: Get AI opinions on ambiguous data
- suggest_function_name: AI-powered function naming
Server Composition: Mount sub-servers for microservice architecture
- Modular deployment support
- Easy integration with specialized analysis servers
Authentication: Enterprise-ready API key authentication for HTTP mode
- Secure team deployments
- Environment-based configuration

Performance Optimizations ⚡ NEW

Connection Pooling: Persistent radare2 connections with LRU eviction
- Eliminates subprocess spawn overhead
- Up to 10x faster for repeated analysis
JVM Reuse: Persistent Ghidra JVM lifecycle management
- Eliminates 5-10s startup time per decompilation
- Caches open projects for instant reuse
Binary Metadata Caching: Intelligent caching with file modification tracking
- Prevents redundant analysis of unchanged files
- Automatic cache invalidation on file updates
Circuit Breaker: Automatic failure resilience
- Prevents cascading failures when tools are unstable
- Auto-recovery after timeout
Resource Management: Background cleanup tasks
- Periodic cleanup of stale cache entries
- Automatic temp file removal
Enhanced Metrics: Comprehensive monitoring
- Cache hit/miss rates for performance tuning
- Circuit breaker state tracking

📑 Table of Contents

Overview
Architecture
- Project Structure
- Design Principles
Technical Decisions
Installation
- Using Docker (Recommended)
- Local Installation
MCP Client Integration
- Cursor AI Setup
- Other MCP Clients
Usage
- Project Goal
- API Examples
Available Tools
Performance
Security
Error Handling
Development
Troubleshooting
FAQ
Contributing
License

📝 Author's Note

This 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.

AI Usage Guide (Rules for AI)

🎯 CRITICAL: AI Agents should ALWAYS use the built-in Prompt system (/prompt) instead of manually orchestrating tool calls.

Why Use Prompts?

The built-in prompts automatically handle:

✅ Correct tool ordering and SOP enforcement
✅ File path validation (container paths)
✅ Security rules (no shell injection)
✅ Performance optimization (batch operations)
✅ Error handling and fail-fast logic

Manual tool calls are error-prone and inefficient. Use prompts.

Available Analysis Prompts

Select the appropriate prompt based on your analysis goal:

🔍 `full_analysis_mode`

Use for: Comprehensive malware/binary analysis (A to Z)

SOP: Reconnaissance → Filtering → Deep Analysis → Reporting
Duration: 5-15 minutes
Tools: All tools including Ghidra, Decompilation, Emulation

⚡ `basic_analysis_mode`

Use for: Quick triage and threat assessment

SOP: Identification → Strings/IOCs → API Summary → Quick Report
Duration: 1-3 minutes
Tools: Lightweight only (no Ghidra/Decompile)

🎮 `game_analysis_mode`

Use for: Game client reverse engineering

Focus: Anti-Cheat detection, structure recovery, network protocol analysis
Targets: Unity/Unreal games, game hacks, cheat detection

🔧 `firmware_analysis_mode`

Use for: Firmware and IoT device analysis

Focus: File system extraction, architecture identification, hardcoded secrets
Targets: Router firmware, embedded systems, IoT devices

🐛 `vulnerability_research_mode`

Use for: Bug hunting and exploit development

Focus: Dangerous API usage, mitigation checks, fuzzing candidates
Targets: Network services, parsers, privileged binaries

🔐 `crypto_analysis_mode`

Use for: Cryptographic implementation analysis

Focus: Algorithm identification, key management, weak crypto detection
Targets: DRM, license validators, encrypted communications

How to Use Prompts

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:

Unknown file → basic_analysis_mode first
Confirmed malware → full_analysis_mode
Game client → game_analysis_mode
Firmware image → firmware_analysis_mode
Security audit → vulnerability_research_mode
License/DRM check → crypto_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.

Overview

What is MCP?

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.

What is Reversecore_MCP?

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:

CLI Tools

file: Identify file types and metadata
strings: Extract printable strings from binaries
radare2: Disassemble and analyze binary executables
binwalk: Analyze and extract embedded files from firmware

Python Libraries

yara-python: Pattern matching and malware detection
capstone: Multi-architecture disassembly engine
lief: Binary parsing and analysis (PE, ELF, Mach-O)

Why Reversecore_MCP?

Traditional reverse engineering workflows require:

Manual tool invocation and output parsing
Deep knowledge of tool-specific command syntax
Careful handling of security concerns
Performance optimization for large files

Reversecore_MCP handles all of this automatically, allowing AI agents to focus on analysis rather than tool management. The server provides:

✅ Automatic security validation of all inputs
✅ Streaming output for large files (preventing OOM)
✅ Graceful error handling with user-friendly messages
✅ Performance optimization with configurable limits
✅ Comprehensive logging for debugging and auditing

Architecture

Project Structure

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

Design Principles

1. Modularity

Tools are organized by category (CLI vs. library) in separate modules
Each tool module exports a registration function that registers tools with the FastMCP server
server.py acts as the central registration point, importing and registering all tool modules

2. Security First

No shell=True: All subprocess calls use list-based arguments, never shell commands
No shlex.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 commands
Input validation: File paths and command strings are validated before use
Path resolution: All file paths are resolved to absolute paths to prevent directory traversal

3. Robustness

Comprehensive error handling: All tool functions catch exceptions and return user-friendly error messages
Never raise unhandled exceptions to the MCP layer
Graceful degradation: Tools return error strings instead of crashing

4. Performance

Streaming output: Large outputs are streamed in chunks to prevent OOM
Configurable limits: Output size and execution time limits are configurable per tool
Truncation warnings: When output is truncated, a warning is included in the response

Technical Decisions

Security: Command Injection Prevention

Decision: Do NOT use shlex.quote() when passing arguments as a list to subprocess.run().

Rationale:

When using subprocess.run(["r2", "-q", "-c", r2_command, file_path]), arguments are passed directly to the process without shell interpretation
shlex.quote() is only needed when constructing shell commands (with shell=True)
Using shlex.quote() on list arguments would break commands like "pdf @ main" by adding quotes that radare2 would interpret literally
Best Practice: Always use list arguments, never shell=True, validate and sanitize user input at the application layer

Implementation:

All subprocess calls use list-based arguments
Input validation functions in core/security.py validate file paths and command strings
File paths are resolved to absolute paths and checked against allowed directories (if configured)

Scalability: FastMCP Modular Architecture

Decision: Use registration functions pattern for tool organization.

Rationale:

FastMCP does not have a router system like FastAPI's APIRouter
FastMCP supports MCPMixin for component-based organization, but a simpler pattern is sufficient for this use case
Each tool module exports a register_*_tools(mcp: FastMCP) function that registers all tools in that module

Implementation 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)

Performance: Large Output Handling

Decision: Implement streaming subprocess execution with configurable output limits.

Rationale:

Large files (GB-scale) can cause OOM when using capture_output=True
Need to support both streaming (for large outputs) and full capture (for small outputs)
Should provide configurable max output size limits

Implementation:

core/execution.py provides execute_subprocess_streaming() function
Uses subprocess.Popen with stdout=subprocess.PIPE
Reads output in 8KB chunks with size limits
Returns truncated output with warning when limit is reached
Tools like run_strings accept max_output_size parameter

Dependencies: Version Management Strategy

Decision: Use Dockerfile with pinned package versions + r2pipe for radare2 integration.

Rationale:

Subprocess approach: Simple but fragile - CLI output format changes between versions
r2pipe approach: More stable API, better error handling, structured data access
Hybrid approach: Use r2pipe for radare2 (primary), keep subprocess as fallback
Pin versions in Dockerfile to ensure reproducibility

Implementation:

Dockerfile installs system packages from Debian repos (latest stable versions)
Python dependencies are specified in requirements.txt with version constraints
r2pipe is used for radare2 operations (when implemented)
Subprocess-based radare2 wrapper is kept as fallback

Installation

Using Docker (Recommended)

Build the Docker Image

# Build the Docker image
docker build -t reversecore-mcp .

Run the Server

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:

All files to be analyzed must be placed in the mounted workspace directory (/app/workspace)
The REVERSECORE_WORKSPACE environment variable sets the allowed workspace path
YARA rule files can be placed in /app/rules (read-only) or in the workspace directory

Local Installation

Install 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

MCP Client Integration

⚠️ 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 AI setup (stdio standard connection)

1) Add the MCP server in Cursor

Cursor → Settings → Cursor Settings → MCP → Add new global MCP server
Add the following to ~/.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.

2) Verify

From the Cursor command palette or MCP panel, run "List available tools for server reversecore"
If you see the tools listed (e.g., "Found N tools ..."), the connection is working

(Optional) HTTP mode connection

If you prefer to use HTTP mode instead, you can run the server manually and configure Cursor to connect to it:

Run the server:

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

Configure Cursor:

{
  "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.

Other MCP Clients

⚠️ 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:

Stdio mode (standard): Use MCP_TRANSPORT=stdio and configure your client to launch the server as a subprocess. This is the recommended mode for most use cases.
HTTP mode (alternative): Start the server in HTTP mode with 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.

Usage

Project Goal

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.

Real-World Use Cases

Malware Triage

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

Security Research

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

Binary Analysis

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

Firmware Analysis

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.

Analysis Prompts (Expert Mode)

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:

Reconnaissance: Identify file type (run_file), extract IOCs (run_strings + extract_iocs), check for packers.
Filtering: Filter out standard library functions (match_libraries) to focus on user code.
Deep Analysis: Analyze suspicious functions using X-Refs (analyze_xrefs), structure recovery (recover_structures), and smart decompilation (smart_decompile). Safely emulate code if needed (emulate_machine_code).
Reporting: Generate YARA rules (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.

Basic Analysis Prompt (Rapid Mode)

For quick triage, use the basic_analysis_mode prompt.

How to use: Select the basic_analysis_mode prompt and provide the filename.

SOP Workflow:

Identification: Identify file type (run_file) and check for packing (parse_binary_with_lief).
Strings & IOCs: Extract strings (run_strings) and identify IOCs (extract_iocs).
Capabilities: Quickly list imports (run_radare2 with "ii") to infer behavior.
Quick Triage Report: Summarize findings and estimate malicious probability.

Specialized Analysis Prompts

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.

API Examples

The server exposes tools that can be called by AI agents via the MCP protocol. Below are examples of how to use each tool:

1. Identify File Type (`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

2. Extract Strings (`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

3. Disassemble with radare2 (`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 function
afl - List all functions
ii - List imports
iz - List strings in data section
afi @ main - Show function info

4. Scan with YARA (`run_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

5. Disassemble with Capstone (`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:

x86 (32-bit and 64-bit)
ARM, ARM64
MIPS, PowerPC, SPARC
And more...

6. Parse Binary with LIEF (`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

Natural Language Interaction

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

Best Practices

For AI Agents

Start broad, then narrow: Use run_file for identification, then targeted tools
Set appropriate timeouts: Large files may need 5-10 minutes
Use output limits: Prevent overwhelming responses with max_output_size
Combine tools: Multiple tools provide better context than any single tool

For Users

Organize workspace: Keep samples in organized directories
Use YARA rules: Build a library of rules for common threats
Review logs: Check logs for errors and performance issues
Isolate environment: Always analyze malware in isolated systems

Available Tools

CLI Tools

Basic Analysis Tools

run_file: Identify file type using the file command
- Returns file type, encoding, architecture information
- Fast identification for initial triage
- Example: PE32 executable (GUI) Intel 80386, for MS Windows
run_strings: Extract printable strings from binary files
- Configurable minimum string length
- Streaming support for large files
- Configurable output size limits (default: 10MB)
- Example use: Extract URLs, file paths, debug strings
run_radare2: Execute radare2 commands on binary files
- Disassemble functions, analyze control flow
- Extract function signatures and symbols
- Configurable output limits and timeouts
- Example: pdf @ main to disassemble main function
run_binwalk: Analyze and extract embedded files from firmware/images
- Identify embedded file systems and archives
- Entropy analysis for packed sections
- Signature-based file detection
- Note: Extraction not enabled in v1.0 (analysis only)

Workspace Management Tools

copy_to_workspace: Copy files from any location to workspace
- Supports Claude Desktop uploads (/mnt/user-data/uploads)
- Supports Cursor, Windsurf, and other AI platforms
- Custom filename support
- Safety checks (max 5GB file size)
- Example: Copy uploaded samples to analysis workspace
list_workspace: List all files in workspace directory
- Shows available samples for analysis
- File count statistics
- Useful for verifying file availability before analysis
scan_workspace: Batch scan all files in the workspace
- ⚡ Batch Mode: Runs run_file, parse_binary_with_lief, and run_yara in parallel
- Auto-Discovery: Finds all files matching patterns (default: all)
- Performance: Uses async concurrency to scan 100+ files in seconds
- Use Case: Initial triage of a new malware set or firmware image
- Example: scan_workspace(["*.exe", "*.dll"])

Advanced Analysis Tools

generate_function_graph: Create Control Flow Graph (CFG) visualizations
- Transform assembly → visual flowchart for AI understanding
- Supports multiple output formats:
  - mermaid: LLM-optimized flowchart syntax (default)
  - json: Raw radare2 graph data for processing
  - dot: Graphviz format for external rendering
- Uses radare2's agfj command internally
- Example: generate_function_graph("/app/workspace/sample.exe", "main", "mermaid")
- Value: Transforms complex assembly into visual graphs
emulate_machine_code: Safe code execution simulation with ESIL
- Predict code behavior without running it
- Virtual CPU emulation (no actual execution)
- Configurable instruction count (1-1000, safety limit)
- Register state tracking after emulation
- Use cases:
  - De-obfuscation: Reveal XOR-encrypted strings
  - Safe malware analysis: Predict behavior without risk
  - Register value prediction: See outcomes before execution
- Example: emulate_machine_code("/app/workspace/malware.exe", "0x401000", 100)
- Security: Sandboxed ESIL VM, no host system impact
smart_decompile: Transform assembly into readable pseudo-C code
- Decompiler Options:
  - Ghidra (default): Industry-standard decompiler with superior type recovery
  - radare2 (fallback): Lightweight alternative for quick analysis
- Transforms assembly into clean C-like code
- Uses Ghidra's DecompInterface engine or radare2's pdc command
- Extracts function metadata (variables, arguments, complexity, signature)
- Shows logical structure (if/else, loops, calls)
- AI-friendly output for further refinement
- Automatic fallback mechanism ensures decompilation always works
- Use cases:
  - Malware analysis: Understand malicious behavior quickly
  - Vulnerability research: Find security flaws in binary code
  - Game hacking: Understand game mechanics from compiled code
  - Software auditing: Review closed-source components
- Example: smart_decompile("/app/workspace/sample.exe", "main")
- Example with radare2: smart_decompile("/app/workspace/sample.exe", "main", use_ghidra=False)
- Value: Faster analysis than raw assembly with better type information
generate_yara_rule: Automatic malware signature generation
- Analysis → Defense pipeline automation
- Extracts opcode bytes from functions
- Formats as production-ready YARA rules
- Configurable byte length (1-1024, default 64)
- YARA-compliant rule naming validation
- Includes metadata (date, address, source file)
- Use cases:
  - Malware detection: Create signatures for new variants
  - Threat hunting: Search similar patterns across systems
  - Incident response: Deploy detection rules for active threats
  - Security research: Build rule repositories from findings
- Example: generate_yara_rule("/app/workspace/malware.exe", "main", 64, "trojan_xyz")
- Value: Bridges gap between analysis and defense
analyze_xrefs: Analyze cross-references (X-Refs) for functions and data
- Priority 2: Code Context Discovery
- Find WHO calls this and WHAT it calls - Essential for understanding behavior
- Identifies all references TO and FROM a given address
- Provides critical context: callers, callees, data references
- Use cases:
  - Malware analysis: "Who calls this Connect function?" reveals C2 behavior
  - Password hunting: "What functions reference this 'Password' string?"
  - Vulnerability research: "What uses this vulnerable API?"
  - Game hacking: "Where is Player health accessed from?"
- AI Collaboration: Build call graphs, identify patterns, focus token budget
- Supports analysis types: "all", "to" (callers), "from" (callees)
- Returns structured JSON with caller/callee relationships
- Example: analyze_xrefs("/app/workspace/malware.exe", "sym.decrypt", "to")
- Value: Reduces hallucination by providing real code relationships
recover_structures: Recover C++ class structures and data types
- Priority 1: The C++ Analysis Game-Changer
- Transform "this + 0x4" → "Player.health" - Make code meaningful
- Uses Ghidra's powerful data type propagation (or radare2 fallback)
- Recovers structure layouts from memory access patterns
- Generates C structure definitions with field names and types
- Essential for C++ binaries (Many game clients and commercial apps)
- Use cases:
  - Game hacking: Recover Player, Entity, Weapon structures
  - Malware analysis: Understand malware configuration structures
  - Vulnerability research: Find buffer overflow candidates
  - Software auditing: Document undocumented data structures
- AI Collaboration: AI identifies patterns like "Vector3", you apply definitions
- Supports both Ghidra (superior) and radare2 (faster) backends
- Example: recover_structures("/app/workspace/game.exe", "Player::update")
- Example (radare2): recover_structures("/app/workspace/binary", "main", use_ghidra=False)
- Value: Structure definitions clarify code understanding
diff_binaries: Compare two binary files to identify code changes
- Priority 1: Binary Diffing for Patch Analysis
- Essential for vulnerability research and 1-day exploit development
- Uses radare2's radiff2 to compare binaries
- Returns similarity score and detailed list of changes
- Supports whole-binary comparison or function-specific comparison
- Use cases:
  - Patch Analysis: Compare pre-patch vs post-patch to find security fixes
  - Game Hacking: Find offset changes after game updates
  - Malware Variant Analysis: Identify what changed between malware samples
  - Firmware Diff: Compare router firmware versions to find vulnerabilities
- Example (whole binary): diff_binaries("/app/workspace/v1.exe", "/app/workspace/v2.exe")
- Example (function): diff_binaries("/app/workspace/old.exe", "/app/workspace/new.exe", "main")
- Output: Similarity score, change types (new/removed/modified blocks), addresses
- Value: Automates the tedious process of finding what changed between versions
match_libraries: Identify and filter known library functions
- Priority 2: Library Signature Matching for Noise Reduction
- Reduces analysis scope significantly by filtering out standard libraries
- Uses radare2's zignatures (FLIRT-compatible) to match known functions
- Automatically identifies strcpy, malloc, OpenSSL, zlib, MFC, etc.
- Returns list of library functions vs user functions
- Use cases:
  - Large Binary Analysis: Skip analysis of 1000+ library functions in 25MB+ files
  - Game Client Analysis: Filter out Unreal Engine/Unity standard library
  - Malware Analysis: Focus on custom malware code, skip Windows API wrappers
  - Token Optimization: Reduce AI token usage by focusing on relevant code
- Example: match_libraries("/app/workspace/large_app.exe")
- Example (custom DB): match_libraries("/app/workspace/game.exe", "/app/rules/game_engine.sig")
- Output: Noise reduction percentage, library matches, user function list
- Value: Filters out library functions to focus on user code

Reversecore Signature Tools (Preview)

Reversecore's proprietary signature technologies that transcend traditional reverse engineering:

ghost_trace: Hybrid analysis for detecting dormant malware and logic bombs
- "Detecting the Undetectable" - Find threats that evade sandbox detection
- Combines static analysis with AI-driven partial emulation
- Discovers orphan functions (never-called code blocks)
- Identifies magic value triggers (time bombs, backdoor activators)
- Uses ESIL emulation to verify malicious behavior without execution
- Use cases:
  - Logic Bomb Detection: Find time-based or trigger-based malware
  - Backdoor Discovery: Identify hidden functionality in binaries
  - Dormant Malware: Detect conditional threats that sandbox misses
  - APT Analysis: Uncover sophisticated, context-aware threats
- Example: ghost_trace("/app/workspace/suspicious.exe")
- Example (verify hypothesis): ghost_trace("/app/workspace/malware.exe", focus_function="sym.hidden", hypothesis={"registers": {"eax": "0xDEADBEEF"}})
- Value: Predicts future malicious behavior that hasn't happened yet
neural_decompile: AI-simulated code refinement for human-readable output
- "Restoring Developer Intent" - Transform mechanical code into natural code
- Refines raw Ghidra output into human-like C code
- Automatic semantic variable renaming (iVar1 → sock_fd, buffer_ptr)
- Structure inference from pointer arithmetic (*(ptr + 4) → ptr->field_4)
- Smart annotation with explanatory comments for magic values
- Use cases:
  - Malware Analysis: Quickly understand complex malicious logic
  - Vulnerability Research: Identify security flaws efficiently
  - Code Understanding: Make reverse-engineered code readable
  - Documentation: Generate understandable documentation from binaries
- Example: neural_decompile("/app/workspace/binary.exe", "0x401000")
- Value: Bridges the gap between assembly and developer's original intent
adaptive_vaccine: Automated defense generation from threat analysis
- "Turn Analysis into Defense" - Generate YARA rules and binary patches
- Auto-generates production-ready YARA detection rules
- Creates binary patches with VA → file offset conversion
- Architecture-aware (x86, x86_64, ARM) with proper endianness
- Automatic file backups before patching
- Dry-run mode for safe preview
- Use cases:
  - Incident Response: Rapidly deploy detection rules
  - Threat Hunting: Create IoCs from analysis findings
  - Malware Neutralization: Patch out malicious functionality
  - Defense Automation: Bridge analysis → protection gap
- Example (YARA): adaptive_vaccine(threat_report, action="yara")
- Example (patch preview): adaptive_vaccine(threat_report, action="patch", file_path="/app/workspace/malware.exe", dry_run=True)
- Value: Automates the defensive response workflow
trinity_defense: Integrated 3-phase automated threat detection and neutralization
- "Complete Defense Automation" - Ghost Trace finds, Neural Decompiler understands, Adaptive Vaccine stops
- Phase 1 (DISCOVER): Ghost Trace scans for hidden threats
- Phase 2 (UNDERSTAND): Neural Decompiler analyzes intent with confidence scoring
- Phase 3 (NEUTRALIZE): Adaptive Vaccine generates defenses
- Parallel processing for 10x performance improvement
- Confidence-based intent inference (reduces false positives)
- Detailed actionable recommendations:
  - Immediate actions (ISOLATE, BLOCK, MONITOR, DEPLOY)
  - Investigation procedures
  - Remediation strategies
- Modes:
  - "discover": Phase 1 only (quick scan)
  - "analyze": Phase 1+2 (full understanding)
  - "full": All 3 phases (complete automation)
- Use cases:
  - Automated Incident Response: Full analysis in one command
  - APT Detection: Coordinate detection across all phases
  - Security Operations: Reduce analyst workload with automation
  - Threat Intelligence: Generate comprehensive threat reports
- Example (full analysis): trinity_defense("/app/workspace/apt.exe", mode="full")
- Example (quick scan): trinity_defense("/app/workspace/sample.bin", mode="discover")
- Value: End-to-end automated defense from detection to neutralization

Library Tools

run_yara: Scan files using YARA rules
- Supports custom rule files
- Returns detailed match information (rule, namespace, tags, strings)
- JSON-formatted output for easy parsing
- Configurable timeout (default: 300s)
disassemble_with_capstone: Disassemble binary code using Capstone
- Multi-architecture support: x86, x86-64, ARM, ARM64, MIPS, etc.
- Configurable offset and size
- Returns formatted assembly with addresses
- Example: Disassemble shellcode or specific code sections
parse_binary_with_lief: Parse binary files with LIEF
- Supports PE, ELF, and Mach-O formats
- Extract headers, sections, imports, exports
- Identify security features (ASLR, DEP, code signing)
- Maximum file size: 1GB (configurable)
extract_iocs: Extract Indicators of Compromise from text
- Regex-based extraction: Finds IPv4, URLs, and Emails
- Noise Reduction: Filters large outputs (like strings) into actionable data
- Use Case: Analyze strings output or decompiled code for C2 servers
- Example: extract_iocs(run_strings_output)
trace_execution_path: Find exploit paths from user input to dangerous sinks
- Vulnerability Reachability: Traces calls backwards from system, strcpy, etc.
- Backtrace Analysis: Maps out how execution reaches the target function
- Use Case: Verify if user input (e.g., recv) can reach a vulnerable sink
- Example: trace_execution_path("/app/workspace/vuln.exe", "system")
scan_for_versions: Detect open-source library versions and CVEs
- Version Detective: Scans binary for version strings (OpenSSL, GCC, etc.)
- SCA: Identifies software composition and potential vulnerabilities
- Use Case: Find outdated libraries like OpenSSL 1.0.1 (Heartbleed)
- Example: scan_for_versions("/app/workspace/firmware.bin")
analyze_variant_changes: Map malware lineage and evolution
- Lineage Mapper: Combines binary diffing with CFG analysis
- Evolutionary Analysis: Identifies how logic changed between variants
- Use Case: Track malware evolution (e.g., "Lazarus v1 vs v2")
- Example: analyze_variant_changes("old.exe", "new.exe")

Full-Cycle Reverse Engineering Workflow

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:

X-Refs: Provide context - understand WHO uses suspicious code
Structures: Make C++ binaries readable - transform offsets to names
CFG: Visualize logic flow for AI comprehension
Emulation: Safely predict behavior without execution
Decompilation: Get high-level pseudo-C for analysis
Trace: Verify exploitability by finding paths to sinks
YARA: Bridge analysis → defense with detection signatures

3. Identify suspicious function

run_radare2("/app/workspace/malware.exe", "afl~decrypt")

4. Visualize control flow

generate_function_graph("/app/workspace/malware.exe", "sym.decrypt", "mermaid")

5. Emulate to reveal obfuscated strings

emulate_machine_code("/app/workspace/malware.exe", "sym.decrypt", 200)

6. Decompile for high-level understanding

smart_decompile("/app/workspace/malware.exe", "sym.decrypt")

7. Generate detection signature

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

Security is a top priority in Reversecore_MCP. The server implements multiple layers of protection:

Security Features

Command Injection Prevention

No shell=True: All subprocess calls use list-based arguments
No shell interpretation: Arguments passed directly to processes
No shlex.quote(): Not needed with list arguments (would break commands)
Validated commands: All user inputs validated before execution

Path Traversal Protection

Absolute path resolution: All paths converted to absolute form
Directory whitelisting: Only workspace and read-only dirs accessible
Path validation: Checked against allowed directories before access
Symlink handling: Paths resolved to prevent symlink attacks

Input Validation

Type checking: All parameters validated for correct types
Range validation: Numeric parameters checked for valid ranges
Command sanitization: Radare2 commands validated against safe patterns
File existence checks: Verified before tool execution

Resource Limits

Output size limits: Prevent memory exhaustion (default: 10MB)
Execution timeouts: Prevent runaway processes (default: 300s)
Rate limiting: HTTP mode rate limiting (default: 60 req/min)
File size limits: LIEF parsing limited to 1GB

Security Best Practices

When deploying Reversecore_MCP:

Use Docker: Containerization provides process isolation
Mount minimal directories: Only mount necessary workspace paths
Read-only rules: Place YARA rules in read-only directories
Network isolation: In HTTP mode, use firewall rules or reverse proxy
Monitor logs: Enable logging to detect suspicious activity
Keep updated: Regularly update base image and dependencies

Workspace Configuration

# 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

Security Auditing

✅ No shell=True usage anywhere in codebase
✅ All file paths validated before access
✅ No arbitrary code execution capabilities
✅ Comprehensive input validation
✅ Error messages don't leak sensitive information
✅ CodeQL security scanning enabled

For security issues, please see our security policy or contact the maintainers directly.

Error Handling

ToolResult Contract (Public API)

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"
  }
}

Standard Error Codes

VALIDATION_ERROR – File paths or parameters failed validation
TOOL_NOT_FOUND – Required CLI binary (file/strings/binwalk) is missing on host
TIMEOUT – Tool exceeded the configured execution deadline
OUTPUT_LIMIT – Streaming output exceeded the configured max_output_size
DEPENDENCY_MISSING – Python dependency such as yara or capstone isn’t installed
INTERNAL_ERROR – Unexpected failure surfaced through the handle_tool_errors decorator

Clients should always branch on status, inspect error_code, and surface hint/details verbatim so users know how to remediate issues quickly.

Development

Adding New Tools

Create tool function in the appropriate module:
- reversecore_mcp/tools/cli_tools.py for CLI tools
- reversecore_mcp/tools/lib_tools.py for library-based tools
Follow 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.

Register the tool in the module's registration function:

def register_cli_tools(mcp: FastMCP) -> None:
    mcp.tool(run_file)
    mcp.tool(run_strings)
    mcp.tool(my_tool)  # Add your tool here

Test your tool:

pytest tests/unit/test_cli_tools.py -k test_my_tool

Testing

# 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

Code Quality

# 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/

Building Docker Image

# 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/

Troubleshooting

Common Issues and Solutions

"Connection failed" in MCP client

Symptoms: Claude Desktop or Cursor shows connection error

Solutions:

Verify Docker is running: docker ps
Check if container is running: docker ps | grep reversecore
View logs: docker logs reversecore-mcp
Restart container: docker restart reversecore-mcp
Check port binding: netstat -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

"File not found" when analyzing files

Symptoms: Tool returns file not found error

Solutions:

Ensure file is in mounted workspace:
```
ls -la /path/to/your/samples/
```

Check Docker volume mount:

docker inspect reversecore-mcp | grep -A 10 Mounts

Verify file path uses container path:
- ✅ Correct: /app/workspace/sample.exe
- ❌ Wrong: /home/user/samples/sample.exe

Check REVERSECORE_WORKSPACE environment variable:

docker exec reversecore-mcp env | grep REVERSECORE

"Permission denied" errors

Symptoms: Cannot access files or directories

Solutions:

Check directory permissions on host:

ls -la /path/to/samples/
# Should be readable by all or by UID 1000 (typical Docker user)

Fix permissions if needed:
```
chmod -R 755 /path/to/samples/
```

On Linux, check SELinux/AppArmor:

# Add :z flag to docker run for SELinux
-v ./samples:/app/workspace:z

High CPU usage

Symptoms: Container consuming excessive CPU

Solutions:

Check for runaway processes:
```
docker exec reversecore-mcp ps aux
```

Review tool timeout settings:

# Reduce timeouts if needed
docker run -e TOOL_TIMEOUT=60 ...

Enable rate limiting (HTTP mode):
```
docker run -e RATE_LIMIT=30 ...
```
Review logs for repeated errors:
```
docker logs reversecore-mcp --tail 100
```

"Module not found" errors

Symptoms: Import errors when starting server

Solutions:

Verify Python dependencies:
```
docker exec reversecore-mcp pip list
```

Rebuild Docker image:

docker build --no-cache -t reversecore-mcp .

For local installation, check PYTHONPATH:

export PYTHONPATH=/path/to/Reversecore_MCP:$PYTHONPATH

Radare2 command failures

Symptoms: r2 commands return errors or unexpected output

Solutions:

Test command manually:
```
r2 -q -c "pdf @ main" /path/to/binary
```
Check command syntax (no shell metacharacters):
- ✅ Correct: pdf @ main
- ❌ Wrong: pdf @ main && echo done
Verify file is a supported format:
```
file /path/to/binary
```
Increase timeout for large binaries:
```
{"timeout": 600}
```

YARA scanning issues

Symptoms: YARA returns no matches or errors

Solutions:

Verify rule file syntax:
```
yara -c /path/to/rules.yar
```
Check rule file location:
- Rules in workspace: /app/workspace/rules.yar
- Rules in read-only dir: /app/rules/rules.yar

Test rule manually:

yara /path/to/rules.yar /path/to/sample

Review rule file permissions:
```
ls -la /path/to/rules.yar
```

Large file processing slow

Symptoms: Tools timeout or hang on large files

Solutions:

Increase timeout:
```
{"timeout": 900}  // 15 minutes
```
Reduce output size limits if applicable:
```
{"max_output_size": 5242880}  // 5MB
```
Use targeted analysis:
- For strings: increase min_length to reduce output
- For r2: use specific commands instead of full analysis
- For LIEF: extract specific sections only
Enable streaming where available

Debug Mode

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

Getting Help

If you encounter issues not covered here:

Check GitHub Issues
Enable debug logging and review output
Create a new issue with:
- Detailed description of the problem
- Steps to reproduce
- Log output (with sensitive data removed)
- Environment details (OS, Docker version, etc.)

FAQ

General Questions

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:

Cursor AI (via HTTP or stdio)
Claude Desktop (via HTTP)
Custom MCP clients following the protocol specification

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.

Installation & Setup

Q: Should I use Docker or local installation?

A: Docker is strongly recommended because:

All dependencies pre-installed and version-locked
Isolated environment for malware analysis
Consistent behavior across platforms
Easy to update and redeploy

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:

500MB for Docker image
1GB for Docker layer cache
Additional space for your analysis files
Optional: Space for log files

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+.

Usage & Features

Q: What's the maximum file size I can analyze?

A: It depends on the tool:

file, strings, radare2: No hard limit, but output is limited (default 10MB)
YARA: No file size limit, scans use memory-efficient methods
Capstone: Specify offset and size, no practical limit
LIEF: 1GB default limit (configurable via LIEF_MAX_FILE_SIZE)

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:

Make multiple tool calls (AI agent handles this)
Implement a custom script that calls tools in sequence
Use batch processing features (planned for future release)

Q: How do I add custom YARA rules?

A: Place YARA rule files in:

Workspace directory: /app/workspace/rules/ (read-write)
Rules directory: /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:

Disassembly: pdf, pd, pdc
Analysis: aaa, afl, afi, afv
Information: iI, iz, ii
Hexdump: px, pxw, pxq

Commands that modify files or execute code are blocked.

Performance & Optimization

Q: Why is my analysis slow?

A: Common causes:

Large files with default timeout (increase timeout)
Expensive radare2 commands (use targeted commands)
Large output (reduce max_output_size or increase min_length for strings)
First-time container startup (subsequent runs are faster)

See Performance section for optimization tips.

Q: How many requests can it handle?

A: In HTTP mode:

Default rate limit: 60 requests/minute per client
No concurrency limit (limited by system resources)
Tested with multiple simultaneous clients

For higher throughput, increase RATE_LIMIT or deploy multiple instances.

Q: Will it run out of memory?

A: No, with proper configuration:

Streaming output prevents OOM on large files
Configurable output limits (default 10MB)
Tools use memory-efficient processing
LIEF has 1GB file size limit

Security & Safety

Q: Is it safe to analyze malware with this tool?

A: The tool provides several safety features:

No arbitrary code execution
Input validation and path sanitization
Sandboxed in Docker container
No write access to arbitrary locations

However, always analyze malware in a dedicated, isolated environment (VM, air-gapped system).

Q: Can AI agents execute arbitrary commands?

A: No. The server:

Uses allow-list approach for commands
No shell=True anywhere in code
Validates all inputs before execution
Blocks commands with shell metacharacters
Restricts file access to workspace only

Q: How are secrets handled?

A: No secrets or credentials are required. File access is controlled via:

Docker volume mounts (read-only where possible)
Environment variables for path configuration
No network access to external resources (by design)

Q: What data is logged?

A: Configurable via LOG_LEVEL:

INFO: Tool invocations, errors, performance metrics
DEBUG: Full command arguments, output sizes, timing details
Logs don't include file contents or sensitive analysis results
Structured JSON logging available (LOG_FORMAT=json)

Troubleshooting

Q: I get "file not found" but the file exists

A: Check path mapping:

Host path: /home/user/samples/file.exe
Container path: /app/workspace/file.exe (use this in tool calls)
Mount in docker run: -v /home/user/samples:/app/workspace

Q: 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.

Development

Q: How do I add a new tool?

A: See Development section for detailed steps. In summary:

Add function to appropriate module (cli_tools.py or lib_tools.py)
Use @log_execution decorator
Follow error handling patterns
Register in register_*_tools() function
Add tests

Q: How do I contribute?

A: See Contributing section. We welcome:

Bug reports and feature requests
Documentation improvements
New tool implementations
Performance optimizations
Security enhancements

Q: Where can I get help with development?

A: Check:

Existing code for patterns and examples
Tests for usage examples
Documentation in docs/ directory
GitHub Issues for discussions
Inline code comments for implementation details

Contributing

We welcome contributions to Reversecore_MCP! Here's how you can help:

Ways to Contribute

Report Bugs: Open an issue with detailed reproduction steps
Suggest Features: Propose new tools or enhancements
Improve Documentation: Fix typos, add examples, clarify instructions
Submit Code: Add new tools, fix bugs, optimize performance
Write Tests: Improve test coverage and quality
Security: Report security issues responsibly (see security policy)

Contribution Guidelines

Fork and Clone:

# Fork the repository under your GitHub account first, then clone your fork
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP

Create a Branch:

git checkout -b feature/your-feature-name

Make Changes:
- Follow existing code style and patterns
- Add tests for new functionality
- Update documentation as needed
- Run linters and tests
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 .

Commit and Push:

git add .
git commit -m "Add: descriptive commit message"
git push origin feature/your-feature-name

Open Pull Request:
- Describe your changes clearly
- Reference related issues
- Include test results
- Wait for review

Code Standards

Security First: Never use shell=True, always validate inputs
Error Handling: Return error strings, don't raise to MCP layer
Performance: Use streaming for large outputs, respect limits
Documentation: Add docstrings and update README for new features
Testing: Write unit tests for new code paths
Type Hints: Use type annotations for all function signatures

Testing Requirements

All PRs must:

✅ Pass all existing tests
✅ Include tests for new functionality
✅ Maintain or improve test coverage
✅ Pass linting checks (ruff, black)
✅ Pass security scans (CodeQL, if applicable)

Review Process

Automated tests run on PR submission
Maintainer reviews code and provides feedback
Address feedback and update PR
Once approved, maintainer merges PR

Questions?

Feel free to:

Open a discussion in GitHub Discussions
Comment on related issues
Reach out to maintainers

Thank you for contributing! 🙏

License

MIT License - see LICENSE file for details.

Third-Party Dependencies

This project uses several open-source tools and libraries:

Radare2: LGPL-3.0 (radare.org)
YARA: Apache 2.0 (virustotal.github.io/yara)
Capstone: BSD License (capstone-engine.org)
LIEF: Apache 2.0 (lief-project.github.io)
FastMCP: Apache 2.0 (github.com/jlowin/fastmcp)
binwalk: MIT License (github.com/ReFirmLabs/binwalk)

Please review and comply with each dependency's license terms.

Acknowledgments

Special thanks to:

The Radare2 team for their powerful reverse engineering framework
The YARA project for pattern matching capabilities
The Capstone team for multi-architecture disassembly
The LIEF project for binary parsing utilities
The FastMCP maintainers for the MCP framework
All contributors and users of Reversecore_MCP

Sample Analysis Reports

For detailed malware analysis examples and case studies, please visit our Wiki.

Built with ❤️ for the reverse engineering and security research community

Reversecore Mcp Overview

What is Reversecore Mcp about?

How to use Reversecore Mcp?

Key Features

Use Cases

FAQ

Reversecore Mcp's README

Reversecore_MCP

👻 Reversecore Signature: Ghost Trace (Preview)

🧠 Reversecore Signature: Neural Decompiler (Preview)

🔱 Reversecore Signature: Trinity Defense System (Preview)

💻 System Requirements

Key Features

Core Reverse Engineering

FastMCP Advanced Features ⭐ NEW

Performance Optimizations ⚡ NEW

📑 Table of Contents

📝 Author's Note

AI Usage Guide (Rules for AI)

Why Use Prompts?

Available Analysis Prompts

🔍 full_analysis_mode

⚡ basic_analysis_mode

🎮 game_analysis_mode

🔧 firmware_analysis_mode

🐛 vulnerability_research_mode

🔐 crypto_analysis_mode

How to Use Prompts

Overview

What is MCP?

What is Reversecore_MCP?

CLI Tools

Python Libraries

Why Reversecore_MCP?

Architecture

Project Structure

Design Principles

1. Modularity

2. Security First

3. Robustness

4. Performance

Technical Decisions

Security: Command Injection Prevention

Scalability: FastMCP Modular Architecture

Performance: Large Output Handling

Dependencies: Version Management Strategy

Installation

Using Docker (Recommended)

Build the Docker Image

Run the Server

Local Installation

MCP Client Integration

Cursor AI setup (stdio standard connection)

1) Add the MCP server in Cursor

2) Verify

(Optional) HTTP mode connection

Other MCP Clients

Usage

Project Goal

Real-World Use Cases

Malware Triage

Security Research

Binary Analysis

Firmware Analysis

Analysis Prompts (Expert Mode)

Basic Analysis Prompt (Rapid Mode)

Specialized Analysis Prompts

API Examples

1. Identify File Type (run_file)

2. Extract Strings (run_strings)

3. Disassemble with radare2 (run_radare2)

4. Scan with YARA (run_yara)

5. Disassemble with Capstone (disassemble_with_capstone)

6. Parse Binary with LIEF (parse_binary_with_lief)

Natural Language Interaction

Best Practices

For AI Agents

For Users

Available Tools

🔍 `full_analysis_mode`

⚡ `basic_analysis_mode`

🎮 `game_analysis_mode`

🔧 `firmware_analysis_mode`

🐛 `vulnerability_research_mode`

🔐 `crypto_analysis_mode`

1. Identify File Type (`run_file`)

2. Extract Strings (`run_strings`)

3. Disassemble with radare2 (`run_radare2`)

4. Scan with YARA (`run_yara`)

5. Disassemble with Capstone (`disassemble_with_capstone`)

6. Parse Binary with LIEF (`parse_binary_with_lief`)