Reverse Engineering MCP

Production grade MCP for Reverse Engineering (includes almost all necessary tools)

revula

Production-grade MCP server for universal reverse engineering automation.

Connect Claude Desktop, MCP-compatible IDEs, or custom tooling to a broad reverse engineering backend through the Model Context Protocol.

Features
Quick Start
- Docker Installation
IDE & Client Setup
Configuration
Tool Availability
Architecture
Security Model
Testing
Scripts & Automation
Usage Examples
Performance & Limitations
Troubleshooting
Contributing
License

Features

Static Analysis (8 tools)

Binary Parsing: PE/ELF/Mach-O via LIEF with hash computation and suspicious indicator detection
Disassembly: Multi-backend support including Capstone (always available), radare2, and objdump for x86/x64/ARM/MIPS/RISC-V
String Extraction: FLOSS integration, regex fallback, 17 classifier patterns (URLs, IPs, crypto, registry keys)
Entropy Analysis: Shannon entropy with sliding window, per-section analysis, and packing detection
Symbol Extraction: DWARF, PDB, LIEF universal; function prologue scanning for stripped binaries
YARA Scanning: Inline rules, file/directory rules, and community rules support
Capa Integration: ATT&CK mapping, MBC behaviors, capability enumeration
Decompilation: Ghidra (headless), RetDec, Binary Ninja with caching

Dynamic Analysis (29 tools)

GDB Adapter: Full GDB/MI protocol with breakpoints, stepping, registers, memory, backtrace, and heap inspection
LLDB Adapter: Native SB API integration for macOS/Linux debugging
Frida Adapter: Spawn/attach, script injection, function interception, memory scan/dump, and RPC exports
Code Coverage: DynamoRIO drcov, Frida Stalker block tracing, and coverage analysis

Android RE (24 tools)

APK Parsing: Manifest extraction, permission analysis, component enumeration, and resource inspection
DEX Analysis: Class/method listing, bytecode stats, and string extraction
Decompilation: jadx/apktool integration, smali disassembly/assembly/patching
Native Binary Analysis: ARM/AArch64 .so analysis with JNI detection
Device Interaction: ADB bridge with 12 actions (logcat, install, shell, dumpsys, screenshot)
Frida for Android: Root bypass, crypto hooking, SSL pinning bypass, API tracing, and memory dump
Traffic Interception: tcpdump/mitmproxy integration with SSL key extraction
Repack and Sign: APK rebuild with smali patches, zipalign + apksigner
Security Scanners: MobSF, Quark-Engine, Semgrep, and manifest vulnerability detection

Cross-Platform RE Tools (7 tools)

Rizin/r2: Automated analysis with 13 actions and binary diffing
GDB Enhanced: Heap analysis, ROP gadget finding, exploit helpers (pattern create/find, checksec)
QEMU: User-mode emulation (4 actions) and full system emulation (5 actions)

Exploit Development (11 tools)

ROP Chain Builder: Multi-architecture gadget finding (x86/x64/ARM/ARM64) with semantic classification, automatic chain generation for execve/mprotect/syscalls, bad-char avoidance, and pwntools script generation
Heap Exploitation: Malloc chunk analysis, bin classification (tcache/fastbin/smallbin/largebin), fake chunk generation, safe-linking encode/decode for glibc 2.32+, and technique templates (House of Force, Tcache Poisoning, Fastbin Dup, Unsafe Unlink)
Libc Database: Symbol/offset extraction, libc identification from leaked addresses, ASLR defeat helpers (base calculation, GOT-to-libc, PLT-to-GOT), and one-gadget RCE finder
Shellcode: Generation, encoding, bad-char analysis, extraction, and emulation testing
Format String: Offset calculation, write payload generation, GOT overwrite, and address leaking

Anti-Analysis (2 tools)

Detection: Scan for anti-debug, anti-VM, anti-tamper, and packing indicators
Bypass Generation: Frida/GDB/patch/LD_PRELOAD scripts for ptrace, IsDebuggerPresent, timing, and VM checks

Malware Analysis (4 tools)

Triage: Multi-hash, IoC extraction, suspicious import scoring, and risk assessment
Sandbox Queries: VirusTotal, Hybrid Analysis, and MalwareBazaar API integration
YARA Generation: Auto-generate YARA rules from binary artifacts
Config Extraction: C2 URLs, IPs, domains, encryption keys, and mutexes

Firmware RE (3 tools)

Extraction: binwalk scan/extract, entropy analysis, and filesystem identification
Vulnerability Scanning: Hardcoded credentials, known CVEs, unsafe functions, and weak crypto
Base Address Detection: String reference analysis for firmware base address recovery

Protocol RE (3 tools)

PCAP Analysis: tshark-based with 8 actions (summary, flows, DNS, HTTP, TLS, filter, export, IoC)
Protocol Dissection: Binary structure inference, field boundary detection, and pattern analysis
Protocol Fuzzing: Mutation-based, boundary testing, field-specific, and template fuzzing

Unpacking (4 tools)

Packer Detection: UPX, Themida, VMProtect, ASPack, PECompact, MPRESS, and more
UPX Unpacking: Static unpacking with automatic backup
Dynamic Unpacking: Frida-based memory dump with OEP detection
PE Rebuild: Fix section alignments, imports, and entry point after memory dump

Deobfuscation (3 tools)

String Deobfuscation: XOR brute force, ROT variants, Base64, RC4, and stack string reconstruction
Control Flow Flattening Detection: OLLVM-style CFF pattern identification
Opaque Predicate Detection: Always-true/false branch identification

Symbolic Execution (4 tools)

angr Integration: Path exploration, constraint solving, CFG generation, and vulnerability scanning
Triton DSE: Dynamic symbolic execution with concrete and symbolic state

Binary Format Specializations (4 tools)

APK/DEX: Android analysis including manifest, permissions, native libs, and DEX parsing
.NET IL: Assembly metadata, type/method listing, and IL disassembly
Java Class: Class file parsing, javap integration, and bytecode disassembly
WebAssembly: WASM section parsing, import/export extraction, and disassembly

Utilities (8 tools)

Hex Tools: Hexdump, pattern search (IDA-style wildcards), and binary diff
Crypto: Hashing (MD5/SHA/TLSH/ssdeep), XOR analysis, and crypto constant scanning
Patching: Binary patching with backup and NOP-sled support
Network: PCAP analysis with protocol stats, DNS extraction, and C2 beacon detection

Admin (2 tools)

Server Status: Version, tool count, cache stats, rate limit stats, and available tools
Cache Management: View stats, clear cache, and invalidate specific entries

Quick Start

Prerequisites

Python 3.11 or later
Linux recommended (macOS and WSL2 supported)
pip (or uv / pipx for isolated installs)

Install

# Clone
git clone https://github.com/president-xd/revula.git
cd revula

# Option 1: Automated install (recommended)
bash scripts/install/install_all.sh

# Option 2: Manual install
pip install -e .

# Option 3: Install with all optional dependencies
pip install -e ".[full]"

# Verify installation
python scripts/test/validate_install.py

The automated installer handles Python version checks, dependency installation, external tool detection, and configuration file generation.

Verify What's Available

python -c "from revula.config import get_config, format_availability_report; print(format_availability_report(get_config()))"

This prints a table showing which external tools and Python modules are detected on your system.

Docker Installation (Alternative)

Revula can be run in Docker for an isolated, stdio-only environment with core and common optional dependencies pre-configured:

# Build the Docker image
docker build -t revula:latest .

# Quick test
docker run --rm --entrypoint python revula:latest -c "import revula; print(revula.__version__)"
docker run --rm --entrypoint python revula:latest -c "from revula.server import _register_all_tools; from revula.tools import TOOL_REGISTRY; _register_all_tools(); print(TOOL_REGISTRY.count())"

# Run in stdio mode (for local MCP clients)
docker run -i --rm -v $(pwd)/workspace:/workspace -v revula-data:/root/.revula revula:latest

# Revula transport is stdio-only (no HTTP/SSE mode)
# Run it attached to your MCP client process
# (for Docker usage, run your MCP client inside the same container/environment)

What's included in the Docker image:

All core Python dependencies (capstone, LIEF, pefile, yara)
angr symbolic execution engine
Frida dynamic instrumentation
Ghidra headless analyzer
GDB/LLDB, radare2, rizin (+ rz-diff), binutils
ADB and Android tools (apktool, jadx, aapt, apksigner, smali/baksmali)
FLARE tools (FLOSS, capa)
RetDec, CFR, Detect-It-Easy (diec), DynamoRIO (drrun), UPX
Exploit tooling (msfvenom, one_gadget), checksec, mono tools (monodis/ikdasm), llvm-pdbutil
Network analysis tools (tcpdump, tshark, capinfos)

Testing the Docker build:

./scripts/docker/test.sh

For complete Docker documentation (stdio mode, volumes, compose usage, and troubleshooting), see DOCKER.md.

Note on Docker vs Native:

Docker provides an isolated environment with core tooling pre-installed
Native installation offers better performance and direct system access
Choose based on your security and portability requirements

IDE & Client Setup

How It Connects (Important)

Revula uses stdio transport only. The server reads JSON-RPC from stdin and writes to stdout. Every MCP client listed below launches revula as a local subprocess. There is no HTTP server, no SSE endpoint, and no remote connection.

What this means for you:

Revula must be installed on the same machine where your IDE/client runs.
If you use a remote server or Docker, you must run both the client and revula inside the same environment (or use SSH piping; see Custom / Other Clients).
Every client below uses the same revula command. The only difference is where you put the config.

Before You Start

Make sure revula is installed and the command works:

# Should print the MCP protocol handshake (Ctrl+C to exit)
revula

# If you installed in a venv, activate it first:
source /path/to/venv/bin/activate
revula

# Or use the full path:
/path/to/venv/bin/revula

If revula is not in your PATH, use the full path in every config below.

1. Claude Desktop

Status: Fully supported. This is the primary client.

Config file locations:

Platform	Path
Linux	`~/.config/Claude/claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
WSL2	`/mnt/c/Users/<YOU>/AppData/Roaming/Claude/claude_desktop_config.json`

Option A: Automatic setup (recommended)

python scripts/setup/setup_claude_desktop.py

This auto-detects your OS, finds the config file, and merges the revula entry. It creates a backup first.

Option B: Manual setup

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "revula": {
      "command": "revula",
      "args": []
    }
  }
}

If revula is in a virtualenv:

{
  "mcpServers": {
    "revula": {
      "command": "/home/you/venvs/revula/bin/revula",
      "args": []
    }
  }
}

If using uvx (zero-install):

{
  "mcpServers": {
    "revula": {
      "command": "uvx",
      "args": ["revula"]
    }
  }
}

After editing: Quit and reopen Claude Desktop. Check the MCP tools icon to confirm 116 tools are available.

2. Claude Code (CLI)

Status: Fully supported.

Option A: CLI command (recommended)

claude mcp add revula -- revula

Claude Code will start revula as a subprocess when needed.

Option B: Manual config

Edit ~/.claude.json (or ~/.claude/settings.json depending on version):

{
  "mcpServers": {
    "revula": {
      "command": "revula",
      "args": []
    }
  }
}

3. VS Code (GitHub Copilot)

Status: Supported. Requires GitHub Copilot extension with MCP support (VS Code 1.99+).

Important: MCP support in VS Code is available through the GitHub Copilot Chat extension. Make sure you have:

VS Code 1.99 or later
GitHub Copilot extension installed and active
MCP enabled in settings: "chat.mcp.enabled": true

Option A: Workspace config (already included in this repo)

This repo ships with .vscode/mcp.json:

{
  "servers": {
    "revula": {
      "command": "revula",
      "args": [],
      "env": {}
    }
  }
}

Just open this project in VS Code and Copilot will discover the MCP server automatically.

Option B: User-level config (global, all projects)

Open VS Code settings (Ctrl+,) → search "mcp" → edit settings.json:

{
  "chat.mcp.enabled": true,
  "mcp": {
    "servers": {
      "revula": {
        "command": "revula",
        "args": [],
        "env": {}
      }
    }
  }
}

Option C: Create .vscode/mcp.json in any project

Copy the file from this repo or create it manually:

mkdir -p .vscode
cat > .vscode/mcp.json << 'EOF'
{
  "servers": {
    "revula": {
      "command": "revula",
      "args": [],
      "env": {}
    }
  }
}
EOF

After editing: Reload VS Code window (Ctrl+Shift+P → "Developer: Reload Window"). The MCP tools should appear in Copilot Chat.

4. Cursor

Status: Supported. Cursor has built-in MCP support.

Config file: ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project).

This repo ships with .cursor/mcp.json for per-project use.

Option A: Per-project (already included)

The .cursor/mcp.json in this repo:

{
  "mcpServers": {
    "revula": {
      "command": "revula",
      "args": []
    }
  }
}

Option B: Global config

mkdir -p ~/.cursor
cat > ~/.cursor/mcp.json << 'EOF'
{
  "mcpServers": {
    "revula": {
      "command": "revula",
      "args": []
    }
  }
}
EOF

After editing: Restart Cursor. Check Settings → MCP to verify revula appears.

5. Windsurf (Codeium)

Status: Supported. Windsurf Cascade supports MCP servers.

Config file: ~/.codeium/windsurf/mcp_config.json

mkdir -p ~/.codeium/windsurf
cat > ~/.codeium/windsurf/mcp_config.json << 'EOF'
{
  "mcpServers": {
    "revula": {
      "command": "revula",
      "args": []
    }
  }
}
EOF

After editing: Restart Windsurf. The Cascade panel should show revula tools.

6. Continue.dev

Status: Supported. Continue has MCP support in recent versions.

Config file: ~/.continue/config.json

Add to your existing config.json:

{
  "mcpServers": [
    {
      "name": "revula",
      "command": "revula",
      "args": []
    }
  ]
}

If you use config.yaml:

mcpServers:
  - name: revula
    command: revula
    args: []

After editing: Restart your IDE. Continue should detect the MCP server.

7. Zed

Status: Supported. Zed has native MCP support via context servers.

Config file: ~/.config/zed/settings.json (Linux/macOS)

Add to your settings.json:

{
  "context_servers": {
    "revula": {
      "command": "revula",
      "args": []
    }
  }
}

After editing: Restart Zed. The context server should appear in the Assistant panel.

8. Custom / Other Clients

Any MCP client that supports stdio transport will work with revula. The protocol is standard JSON-RPC over stdin/stdout.

Direct invocation:

# Start the server (reads from stdin, writes to stdout, logs to stderr)
revula

Over SSH (remote machine):

# Run revula on a remote machine with stdio piped through SSH
ssh user@remote-host revula

In Docker:

FROM python:3.11-slim
RUN pip install revula
# The entrypoint speaks stdio MCP
ENTRYPOINT ["revula"]

docker build -t revula .
# Use docker as the command in your client config:
# "command": "docker", "args": ["run", "-i", "--rm", "revula"]

Python client (programmatic):

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(command="revula", args=[])
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print(f"Connected: {len(tools.tools)} tools available")
            # Call a tool
            result = await session.call_tool("re_entropy", {"binary_path": "/bin/ls"})
            print(result)

asyncio.run(main())

Universal Setup Script

Configure any client with one command:

# Interactive: pick a client from the menu
python scripts/setup/setup_ide.py

# Configure a specific client
python scripts/setup/setup_ide.py --client vscode
python scripts/setup/setup_ide.py --client cursor
python scripts/setup/setup_ide.py --client claude-desktop
python scripts/setup/setup_ide.py --client windsurf
python scripts/setup/setup_ide.py --client zed

# Configure all detected clients at once
python scripts/setup/setup_ide.py --all

# Print all configs without writing files (review first)
python scripts/setup/setup_ide.py --print-only

# Override the command (e.g., full path to venv)
python scripts/setup/setup_ide.py --client cursor --command "/home/you/venv/bin/revula"

The script auto-detects how to run revula (PATH, uvx, or python -m), creates backups before writing, and merges into existing configs.

Configuration

Config File

Create ~/.revula/config.toml (or use the interactive generator):

python scripts/setup/setup_config_toml.py

Example configuration:

[tools.ghidra_headless]
path = "/opt/ghidra/support/analyzeHeadless"

[tools.radare2]
path = "/usr/bin/radare2"

[tools.jadx]
path = "/usr/local/bin/jadx"

[tools.retdec_decompiler]
path = "/usr/local/bin/retdec-decompiler"

[security]
max_memory_mb = 512
default_timeout = 60
max_timeout = 600
allowed_dirs = ["/home/user/samples", "/tmp/analysis"]

[rate_limit]
enabled = true
global_rpm = 120
per_tool_rpm = 30
burst_size = 10

[tool_naming]
namespace = "revula"
include_legacy_names = false

[execution]
subprocess_retries = 1
subprocess_retry_backoff_ms = 250

Environment Variables

Environment variables override config file values:

export GHIDRA_HEADLESS=/opt/ghidra/support/analyzeHeadless  # Ghidra headless binary
export RADARE2_PATH=/usr/bin/radare2                         # radare2 binary
export RIZIN_PATH=/usr/local/bin/rizin                       # rizin binary
export RETDEC_PATH=/usr/local/bin/retdec-decompiler         # RetDec decompiler binary
export RZ_DIFF_PATH=/usr/local/bin/rz-diff                  # rizin diff tool
export MSFVENOM_PATH=/usr/bin/msfvenom                      # metasploit payload generator
export REVULA_DEFAULT_TIMEOUT=120                            # Subprocess timeout (seconds)
export REVULA_MAX_MEMORY_MB=1024                             # Memory limit (MB)
export REVULA_GLOBAL_RPM=240                                 # Global tool-call rate limit
export REVULA_PER_TOOL_RPM=60                                # Per-tool rate limit
export REVULA_BURST_SIZE=20                                  # Token bucket burst size
export REVULA_TOOL_NAMESPACE=revula                          # Public MCP tool prefix
export REVULA_INCLUDE_LEGACY_TOOL_NAMES=false                # Expose deprecated re_* aliases
export REVULA_SUBPROCESS_RETRIES=2                           # Retry transient subprocess failures
export REVULA_SUBPROCESS_RETRY_BACKOFF_MS=400                # Initial retry backoff (ms)

Tool Availability

revula degrades gracefully. Tools that depend on missing backends return clear error messages instead of crashing. Here is what each category needs:

Category	Always Available	Needs External Tool	Needs Python Module
Static	PE/ELF parsing, entropy, strings	`objdump`, `radare2`, `ghidra`, `retdec`, `floss`, `capa`	`capstone` ✓, `lief` ✓, `pefile` ✓, `yara` ✓
Dynamic		`gdb`, `lldb`	`frida`
Android	APK manifest/DEX parsing (via zipfile)	`jadx`, `apktool`, `adb`, `zipalign`, `apksigner`, `tcpdump`	`frida`, `quark-engine`
Platform		`rizin`, `radare2`, `gdb`, `qemu-user`, `qemu-system-*`	`r2pipe`, `binaryninja`
Exploit	ROP chain builder, heap analysis, libc database, format string helpers		`capstone` ✓, `pwntools`, `keystone-engine`
Anti-Analysis	Pattern scanning (via `lief` + `capstone`)
Malware	File hashing, IoC extraction, risk scoring		`yara` ✓, `ssdeep`, `tlsh`
Firmware		`binwalk`, `sasquatch`
Protocol	Binary protocol dissection, fuzzing	`tshark`	`scapy`
Unpacking	Packer signature detection	`upx`	`frida`
Deobfuscation	XOR/ROT/Base64 deobfuscation		`capstone` ✓
Symbolic			`angr`, `triton` (source-build only; tool auto-enables when installed)
Binary Formats		`aapt`, `javap`, `monodis`, `wasm2wat`
Utilities	Hex dump, binary diff, patching	`tshark`	`scapy`, `ssdeep`, `tlsh`

✓ = included in core dependencies (always installed).

Installing Optional Dependencies

# Frida (dynamic instrumentation)
pip install frida frida-tools

# angr (symbolic execution, large install ~2 GB)
pip install angr

# radare2 bindings
pip install r2pipe

# Fuzzy hashing
pip install ssdeep tlsh

# Network analysis
pip install scapy

# Everything at once
pip install -e ".[full]"

Installing External Tools (Debian/Ubuntu/Kali)

# Core analysis/tooling from distro repos
sudo apt install gdb binutils binwalk checksec apksigner mono-utils mono-devel ruby-full llvm-19

# Android RE
sudo apt install apktool jadx android-sdk adb zipalign

# Network
sudo apt install tshark

# For full optional toolchain coverage (radare2/rizin/upx/drrun/msfvenom/retdec/diec/cfr),
# use the maintained installer:
bash scripts/install/install_all.sh

Architecture

src/revula/                     # 19,400+ LOC across 63 Python files
├── __init__.py                 # Version (__version__ = "0.1.0")
├── config.py                   # Tool detection, TOML config, env var loading
├── sandbox.py                  # Secure subprocess execution, path validation
├── session.py                  # Session lifecycle manager (debuggers, Frida)
├── server.py                   # MCP server entrypoint (stdio transport)
├── cache.py                    # LRU result cache with TTL
├── rate_limit.py               # Token-bucket rate limiter
└── tools/
    ├── __init__.py             # Tool registry + @register_tool decorator
    ├── static/                 # 8 files: PE/ELF, disasm, strings, entropy, symbols, YARA, capa, decompile
    ├── dynamic/                # 4 files: GDB, LLDB, Frida, coverage
    ├── android/                # 9 files: APK, DEX, decompile, native, device, frida, traffic, repack, scanners
    ├── platform/               # 3 files: Rizin, GDB-enhanced, QEMU
    ├── exploit/                # 5 files: ROP builder, heap exploitation, libc database, shellcode, format strings
    ├── antianalysis/           # 1 file:  anti-debug/VM detection and bypass generation
    ├── malware/                # 1 file:  triage, sandbox queries, YARA gen, config extraction
    ├── firmware/               # 1 file:  extraction, vuln scanning, base address detection
    ├── protocol/               # 1 file:  PCAP analysis, protocol dissection, fuzzing
    ├── deobfuscation/          # 1 file:  string deobfuscation, CFF, opaque predicates
    ├── unpacking/              # 1 file:  packer detection, UPX, dynamic unpack, PE rebuild
    ├── symbolic/               # 1 file:  angr + Triton
    ├── binary_formats/         # 1 file:  .NET, Java, WASM
    ├── utils/                  # 4 files: hex, crypto, patching, network
    └── admin/                  # 1 file:  server status, cache management

How It Works

Startup. server.py loads config.py, which probes the system for external tools (via shutil.which) and Python modules (via importlib.util.find_spec). Results are cached in a ServerConfig singleton.
Tool Registration. Each tool file uses @TOOL_REGISTRY.register() to declare its name, description, input/output schemas, annotations, and async handler. Tools self-register on import.
Request Dispatch. When a tools/call request arrives, the server resolves namespaced aliases, validates arguments (Pydantic-first with JSON Schema fallback), checks rate limits, checks cache eligibility, dispatches the handler, and returns protocol-level isError metadata.
Subprocess Execution. All external tool invocations go through sandbox.safe_subprocess(), which enforces shell=False, sets RLIMIT_AS and RLIMIT_CPU, validates paths, and captures stdout/stderr.
Result Caching. Deterministic operations (disassembly, parsing) are cached with a configurable TTL. Mutating operations (patching, Frida injection) bypass the cache automatically.
Session Management. Long-lived debugger and Frida sessions are tracked by SessionManager, with automatic cleanup after 30 minutes of idle time.

Infrastructure Components

Component	Purpose	Key Detail
ResultCache	Avoid redundant subprocess calls	LRU, 256 entries, 10-minute TTL
RateLimiter	Prevent resource exhaustion	Token-bucket with config/env overrides
ToolRegistry	Decorator-based tool dispatch	Annotations + strict schema hardening + structured errors
SessionManager	Debugger/Frida persistence	Auto-cleanup after 30 min idle
sandbox.py	Secure execution layer	`shell=False`, RLIMIT enforcement, path validation

Security Model

revula operates on the principle that user-supplied arguments are untrusted. The following hardening measures are applied:

Subprocess Isolation

No shell=True: Every subprocess call uses shell=False with explicit argument lists. This is enforced by a CI test (test_no_shell_true) that scans every source file.
No eval() / exec(): No dynamic code evaluation of user input.
No f-string injection: User-supplied values are never interpolated into python3 -c code strings. Values are passed via sys.argv, stdin, or environment variables. Enforced by test_no_fstring_in_subprocess_python_code.
JavaScript escaping: All user-controlled values interpolated into Frida JavaScript strings pass through _js_escape(), which escapes backslashes, quotes, newlines, and other injection vectors.
Resource limits: Every subprocess gets RLIMIT_AS (512 MB default) and RLIMIT_CPU (60 s default) via resource.setrlimit().
Timeout enforcement: asyncio.wait_for() wraps all subprocess calls.

Path Validation

Fail-closed: validate_path() rejects all paths when no allowed_dirs are configured (falls back to get_config().security.allowed_dirs). It does not silently pass.
Traversal blocked: .. components are rejected after os.path.realpath() resolution.
Absolute paths required: Relative paths are rejected.
Validated everywhere: All file-accepting tool handlers call validate_path() before any file I/O.

Frida Hardening

Script size limit: Frida scripts are capped at 1 MB to prevent memory exhaustion.
Memory dump limit: Memory dumps are capped at 100 MB.
JS injection prevention: Class names, method names, module names, and other user-supplied values are escaped before interpolation into JavaScript templates.

Temporary Files

No tempfile.mktemp(): All temporary files use tempfile.NamedTemporaryFile() or tempfile.mkdtemp() to prevent TOCTOU race conditions.
No hardcoded /tmp paths: All temporary paths use the tempfile module.

Rate Limiting & Caching

Global limit: 120 requests per minute (configurable).
Per-tool limit: 30 requests per minute (configurable).
Result cache policy: fail-closed explicit opt-in per tool (cacheable=True); mutating/stateful tools are never cached by default.
Session TTL: Idle sessions auto-cleaned after 30 minutes.

Testing

# Run full test suite
python -m pytest tests/ --timeout=30

# With coverage
python -m pytest tests/ --cov=revula --cov-report=html --timeout=30

# Verbose output
python -m pytest tests/ -v --timeout=30

# Specific test suites
python -m pytest tests/test_infra.py -v      # Cache, rate limiter, sessions
python -m pytest tests/test_core.py -v       # Config, sandbox, tool registry
python -m pytest tests/test_static.py -v     # Static analysis tools
python -m pytest tests/test_android.py -v    # Android module tests
python -m pytest tests/test_exploit.py -v    # ROP, heap, libc tools (32 tests)
python -m pytest tests/test_tools_new.py -v  # Exploit, malware, firmware, protocol, etc.
python -m pytest tests/test_security.py -v   # Security invariant tests

# Using the test runner script
bash scripts/test/run_tests.sh

Test Categories

Suite	Tests	Covers
`test_infra.py`	Cache, rate limiter, session manager	Infrastructure correctness
`test_core.py`	Config loading, sandbox, tool registry	Core module behavior
`test_static.py`	Entropy, hex, crypto, strings, symbols	Static analysis tools
`test_android.py`	APK parse, DEX, device, Frida Android	Android module tests
`test_tools_new.py`	Exploit, malware, firmware, protocol, antianalysis, platform, deobfuscation, symbolic, unpacking, binary formats	All remaining tool categories
`test_security.py`	`shell=True` scan, injection scan, `mktemp` scan, hardcoded `/tmp` scan, path validation, JS escaping, shellcode validation	Security regression tests

Security Tests

The TestVulnerabilityHardeningV3 suite in test_security.py enforces:

No f-string code injection: Scans all source files for "-c" arguments containing f-strings.
No tempfile.mktemp(): Prevents TOCTOU race conditions.
No hardcoded /tmp/ paths: Enforces use of the tempfile module.
Fail-closed path validation: Verifies validate_path() rejects paths when allowed_dirs is empty.
Frida JS escaping: Verifies _js_escape() blocks injection payloads.
Shellcode hex validation: Verifies non-hex input is rejected, not passed to subprocess.

Scripts & Automation

Primary automation scripts live in scripts/:

Installation

Script	Purpose
`scripts/install/install_all.sh`	Master installer: Python check, deps, external tools, config
`scripts/install/install_verify.sh`	Post-install verification: checks all dependencies and paths

Setup

Script	Purpose
`scripts/setup/setup_ide.py`	Universal IDE/client configurator for Claude Desktop, VS Code, Cursor, Windsurf, Zed, and Continue
`scripts/setup/setup_claude_desktop.py`	Claude Desktop-specific auto-configurator (legacy, still functional)
`scripts/setup/setup_config_toml.py`	Interactive config.toml generator
`scripts/setup/setup_android_device.sh`	Prepare an Android device for RE (root, frida-server, certs)

Testing & Development

Script	Purpose
`scripts/test/run_tests.sh`	Run full test suite with coverage
`scripts/test/validate_install.py`	Comprehensive installation validator
`scripts/dev/add_tool.py`	Scaffold a new tool module (creates file, registers, adds test)
`scripts/dev/lint_and_type.sh`	Run ruff + mypy
`scripts/utils/download_frida_server.py`	Download frida-server for a target architecture

Docker

Script	Purpose
`scripts/docker/test.sh`	Automated Docker build and stdio-oriented smoke checks
`scripts/docker/validate.sh`	Docker configuration validation

Usage Examples

Static Analysis: Analyze a PE Binary

Ask Claude: "Analyze this binary for me: /home/user/samples/malware.exe"

Behind the scenes, Claude can call:

re_pe_elf to parse PE headers, sections, imports, and exports
re_strings to extract and classify strings (URLs, IPs, crypto constants)
re_entropy to check for packing (high entropy sections)
re_yara_scan to scan with YARA rules
re_capa_scan to map to ATT&CK techniques

Dynamic Analysis: Debug with GDB

Ask Claude: "Debug /home/user/crackme and find the password check"

Claude can orchestrate:

re_gdb with action start to launch the binary under GDB
re_disasm to disassemble key functions
re_gdb with action breakpoint to set breakpoints at comparison instructions
re_gdb with action continue and registers to run and inspect state

Android: Reverse an APK

Ask Claude: "Analyze this APK for security issues: /home/user/app.apk"

Claude can call:

re_apk_parse to extract manifest, permissions, and components
re_dex_analyze to list classes and find suspicious methods
re_android_decompile to decompile with jadx
re_android_scanner to run security scanners
re_antianalysis_detect to check for anti-tampering

Malware Triage

Ask Claude: "Triage this suspected malware sample"

Claude can call:

re_malware_triage for hashes, IoCs, import analysis, and risk score
re_malware_config to extract C2 URLs and encryption keys
re_malware_yara_gen to generate a YARA rule for the sample
re_malware_sandbox to query VirusTotal/Hybrid Analysis

Exploit Development

Ask Claude: "Build a ROP chain to call execve('/bin/sh') in this binary"

Claude can orchestrate:

re_rop_gadgets to find useful gadgets (pop rdi, pop rsi, syscall) with semantic classification
re_rop_chain to automatically build an execve chain with proper register setup
re_libc_offsets to extract system/execve/binsh offsets from libc
re_aslr_defeat to calculate base addresses from leaked pointers
re_heap_chunk to analyze malloc chunks and bin classification for heap exploits
re_heap_technique to get templates for House of Force, Tcache Poisoning, etc.

Performance & Limitations

What Works Well Without Optional Dependencies

With just the core install (pip install -e .), you get full functionality for:

PE/ELF/Mach-O parsing and header analysis
Multi-architecture disassembly (via Capstone)
String extraction and classification
Shannon entropy analysis and packing detection
YARA rule scanning
Binary patching
Hex dump and pattern search
File hashing (MD5, SHA-1, SHA-256)
ROP gadget finding and chain building (via Capstone)
Heap exploitation helpers (chunk analysis, bin classification, safe-linking)
Libc database tools (symbol extraction, offset calculation, ASLR defeat)
Format string payload calculation
XOR/ROT/Base64 deobfuscation
Anti-analysis pattern detection

What Needs External Tools

These tools produce clear "tool not found" errors when backends are missing:

Decompilation requires Ghidra, RetDec, or Binary Ninja
Dynamic analysis requires GDB, LLDB, or Frida
Android RE requires jadx, apktool, and ADB
Symbolic execution requires angr (large dependency, ~2 GB)
Network analysis requires tshark or scapy
Firmware extraction requires binwalk

Performance Expectations

Startup: ~1 second (probes system for available tools via shutil.which and importlib.util.find_spec)
Static analysis: Sub-second for most operations on files under 100 MB
Disassembly: Capstone disassembles ~1 MB/s; radare2 adds full analysis overhead
Subprocess calls: Each external tool invocation has ~50-200 ms overhead from process spawn
Caching: Result caching is explicit opt-in per tool; unless enabled, calls execute fresh
Rate limiting: 120 requests/minute global, 30/minute per tool (configurable)

Known Limitations

No Windows native support. Designed for Linux. macOS works for most tools. Windows requires WSL2.
stdio transport only. There is no HTTP/SSE server. Revula must run on the same machine as your IDE (or be piped via SSH/Docker). This is a deliberate design choice for security: MCP over stdio is simpler and avoids exposing a network socket.
No GUI. This is a headless MCP server. Use Claude Desktop, VS Code Copilot, Cursor, or another MCP client for the interface.
Large binary analysis. Files over 500 MB may hit the default memory limit (512 MB). Increase via REVULA_MAX_MEMORY_MB.
angr install size. The angr optional dependency is ~2 GB and takes several minutes to install.
Frida version coupling. Frida client and server versions must match exactly. Use scripts/utils/download_frida_server.py to get the right version.
Single-user design. The server handles one MCP client at a time via stdio. There is no multi-tenant isolation. Each IDE/client spawns its own server process.
IDA Pro integration. Requires IDA Pro with the REST API plugin. Not included.

Troubleshooting

Server Won't Start

# Check Python version (need 3.11+)
python --version

# Check MCP is installed
python -c "import mcp; print(mcp.__version__)"

# Run and capture server logs from stderr
revula 2> revula.log
tail -f revula.log

Tool Says "not found"

# Check what's available
python -c "from revula.config import get_config, format_availability_report; print(format_availability_report(get_config()))"

# The report shows ✓/✗ for every external tool and Python module.
# Install what you need and restart the server.

Path Validation Errors

Error: Path /some/path is not within allowed directories

Add the directory to your config:

[security]
allowed_dirs = ["/home/user/samples", "/tmp/analysis", "/some/path"]

Alternatively, set the value via environment variable. The server will use the config file's allowed_dirs as a fallback.

Rate Limit Exceeded

Error: Rate limit exceeded for tool re_disasm

Rate limits are currently initialized from code defaults (global_rpm=120, per_tool_rpm=30, burst_size=10). If you need different limits, adjust RateLimitConfig(...) in src/revula/server.py and restart.

Frida Connection Issues

# Check Frida version match
frida --version
frida-server --version  # on device

# Download matching server
python scripts/utils/download_frida_server.py --arch arm64

Tests Failing

# Run with verbose output
python -m pytest tests/ -v --timeout=30 --tb=long

# Clear bytecode cache (fixes stale imports)
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null
python -m pytest tests/ --timeout=30

Android Device Not Detected

# Run the device setup script
bash scripts/setup/setup_android_device.sh

# Manual check
adb devices
adb shell id  # should show root or shell

Contributing

Adding a New Tool

Use the scaffold generator:

python scripts/dev/add_tool.py

This creates the tool file, registers it in the category __init__.py, and generates a test stub.

Code Quality

# Lint and type-check
bash scripts/dev/lint_and_type.sh

# Run full test suite
python -m pytest tests/ --timeout=30 -q

# Validate install
python scripts/test/validate_install.py

Guidelines

Every tool handler is async and returns list[dict] (MCP content blocks).
All subprocess calls go through sandbox.safe_subprocess().
All file paths must be validated via sandbox.validate_path().
No shell=True, no eval(), no f-string interpolation into subprocess code.
Every new tool needs at least one test.

License

Released under the GNU General Public License. See LICENSE for details.

İlgili Sunucular

Draw-it MCP

An AI-powered drawing application for your browser. Draw, save, and get AI-powered insights.

Solentic

First native Solana staking MCP server. 26 tools for complete staking workflows — stake, unstake, withdraw, verify, simulate, and more. Zero custody design, ~6% APY.

Omics AI MCP Server

Interact with Omics AI Explorer networks for genomics research and data analysis.

CryptoAPIs MCP Prepare Transactions

MCP server for building unsigned transactions on multiple blockchains via Crypto APIs

Maker MCP Server

DAI stability data, vault info, and governance parameters on MakerDAO.

GiveReady

Search 41,000+ verified nonprofits across 29 cause areas, submit enrichments back to thin profiles, and donate via x402 USDC with zero platform fees.

Mnemo Cortex

Persistent cross-agent semantic memory for AI agents. Recall past sessions, share knowledge across agents. Multi-agent (isolated writes, shared reads), local-first (SQLite + FTS5), works with any LLM — local Ollama at $0 or cloud APIs like Gemini and OpenAI. Integrations for Claude Code, Claude Desktop, and OpenClaw.

NebulaFinger MCP

An MCP server interface for the NebulaFinger fingerprint recognition tool.

Cast

MCP server for Google Cast — discover devices, play media, control volume, launch apps, and manage queues over stdio

MCP Claude Spotify

An integration for Claude Desktop to interact with Spotify using the Model Context Protocol (MCP).