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.

---

Table of Contents

• Features
• Quick Start
  • Docker Installation
• IDE & Client Setup
  • How It Connects (Important)
  • Claude Desktop
  • Claude Code (CLI)
  • VS Code (GitHub Copilot)
  • Cursor
  • Windsurf (Codeium)
  • Continue.dev
  • Zed
  • Custom / Other Clients
  • Universal Setup Script
• 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

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

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

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

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

5. Result Caching. Deterministic operations (disassembly, parsing) are cached with a configurable TTL. Mutating operations (patching, Frida injection) bypass the cache automatically.

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

1. re_pe_elf to parse PE headers, sections, imports, and exports
2. re_strings to extract and classify strings (URLs, IPs, crypto constants)
3. re_entropy to check for packing (high entropy sections)
4. re_yara_scan to scan with YARA rules
5. 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:

1. re_gdb with action start to launch the binary under GDB
2. re_disasm to disassemble key functions
3. re_gdb with action breakpoint to set breakpoints at comparison instructions
4. 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:

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

Malware Triage

Ask Claude: "Triage this suspected malware sample"

Claude can call:

1. re_malware_triage for hashes, IoCs, import analysis, and risk score
2. re_malware_config to extract C2 URLs and encryption keys
3. re_malware_yara_gen to generate a YARA rule for the sample
4. 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:

1. re_rop_gadgets to find useful gadgets (pop rdi, pop rsi, syscall) with semantic classification
2. re_rop_chain to automatically build an execve chain with proper register setup
3. re_libc_offsets to extract system/execve/binsh offsets from libc
4. re_aslr_defeat to calculate base addresses from leaked pointers
5. re_heap_chunk to analyze malloc chunks and bin classification for heap exploits
6. 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

1. No Windows native support. Designed for Linux. macOS works for most tools. Windows requires WSL2.
2. 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.
3. No GUI. This is a headless MCP server. Use Claude Desktop, VS Code Copilot, Cursor, or another MCP client for the interface.
4. Large binary analysis. Files over 500 MB may hit the default memory limit (512 MB). Increase via REVULA_MAX_MEMORY_MB.
5. angr install size. The angr optional dependency is ~2 GB and takes several minutes to install.
6. Frida version coupling. Frida client and server versions must match exactly. Use scripts/utils/download_frida_server.py to get the right version.
7. 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.
8. 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.