Reverse Engineering MCP

MCP de nivel de producción para ingeniería inversa (incluye casi todas las herramientas necesarias)

Documentación

revula

Servidor MCP de nivel de producción para automatización universal de ingeniería inversa.

Conecta Claude Desktop, IDEs compatibles con MCP o herramientas personalizadas a un backend amplio de ingeniería inversa a través del Model Context Protocol.

Características

Análisis Estático (8 herramientas)

Análisis de Binarios: PE/ELF/Mach-O mediante LIEF con cálculo de hash y detección de indicadores sospechosos
Desensamblado: Soporte multi-backend incluyendo Capstone (siempre disponible), radare2 y objdump para x86/x64/ARM/MIPS/RISC-V
Extracción de Cadenas: Integración con FLOSS, respaldo con regex, 17 patrones de clasificación (URLs, IPs, criptografía, claves de registro)
Análisis de Entropía: Entropía de Shannon con ventana deslizante, análisis por secciones y detección de empaquetado
Extracción de Símbolos: DWARF, PDB, LIEF universal; escaneo de prólogos de funciones para binarios sin símbolos
Escaneo YARA: Reglas en línea, reglas de archivos/directorios y soporte de reglas comunitarias
Integración Capa: Mapeo ATT&CK, comportamientos MBC, enumeración de capacidades
Descompilación: Ghidra (headless), RetDec, Binary Ninja con caché

Análisis Dinámico (29 herramientas)

Adaptador GDB: Protocolo completo GDB/MI con puntos de interrupción, ejecución paso a paso, registros, memoria, backtrace e inspección de heap
Adaptador LLDB: Integración nativa de la API SB para depuración en macOS/Linux
Adaptador Frida: Spawn/attach, inyección de scripts, interceptación de funciones, escaneo/volcado de memoria y exportaciones RPC
Cobertura de Código: DynamoRIO drcov, seguimiento de bloques con Frida Stalker y análisis de cobertura

Ingeniería Inversa Android (24 herramientas)

Análisis de APK: Extracción de manifiesto, análisis de permisos, enumeración de componentes e inspección de recursos
Análisis DEX: Listado de clases/métodos, estadísticas de bytecode y extracción de cadenas
Descompilación: Integración con jadx/apktool, desensamblado/ensamblado/parcheo smali
Análisis de Binarios Nativos: Análisis de archivos .so ARM/AArch64 con detección JNI
Interacción con Dispositivos: Puente ADB con 12 acciones (logcat, install, shell, dumpsys, screenshot)
Frida para Android: Bypass de root, hooking criptográfico, bypass de fijación SSL, seguimiento de API y volcado de memoria
Interceptación de Tráfico: Integración con tcpdump/mitmproxy con extracción de claves SSL
Reempaquetado y Firma: Reconstrucción de APK con parches smali, zipalign + apksigner
Escáneres de Seguridad: MobSF, Quark-Engine, Semgrep y detección de vulnerabilidades en manifiesto

Herramientas RE Multiplataforma (7 herramientas)

Rizin/r2: Análisis automatizado con 13 acciones y comparación de binarios
GDB Mejorado: Análisis de heap, búsqueda de gadgets ROP, ayudas para explotación (pattern create/find, checksec)
QEMU: Emulación en modo usuario (4 acciones) y emulación completa de sistema (5 acciones)

Desarrollo de Exploits (11 herramientas)

Constructor de Cadenas ROP: Búsqueda de gadgets multi-arquitectura (x86/x64/ARM/ARM64) con clasificación semántica, generación automática de cadenas para execve/mprotect/syscalls, evitación de caracteres malos y generación de scripts pwntools
Explotación de Heap: Análisis de chunks malloc, clasificación de bins (tcache/fastbin/smallbin/largebin), generación de chunks falsos, codificación/decodificación safe-linking para glibc 2.32+ y plantillas de técnicas (House of Force, Tcache Poisoning, Fastbin Dup, Unsafe Unlink)
Base de Datos Libc: Extracción de símbolos/offsets, identificación de libc a partir de direcciones filtradas, ayudas para derrotar ASLR (cálculo de base, GOT-to-libc, PLT-to-GOT) y buscador de one-gadget RCE
Shellcode: Generación, codificación, análisis de caracteres malos, extracción y pruebas de emulación
Cadena de Formato: Cálculo de offsets, generación de payloads de escritura, sobrescritura GOT y filtrado de direcciones

Anti-Análisis (2 herramientas)

Detección: Escaneo de indicadores anti-debug, anti-VM, anti-manipulación y empaquetado
Generación de Bypass: Scripts Frida/GDB/parche/LD_PRELOAD para ptrace, IsDebuggerPresent, temporización y comprobaciones de VM

Análisis de Malware (4 herramientas)

Triaje: Multi-hash, extracción de IoC, puntuación de importaciones sospechosas y evaluación de riesgos
Consultas a Sandbox: Integración de API de VirusTotal, Hybrid Analysis y MalwareBazaar
Generación YARA: Generación automática de reglas YARA a partir de artefactos binarios
Extracción de Configuración: URLs C2, IPs, dominios, claves de cifrado y mutexes

Ingeniería Inversa de Firmware (3 herramientas)

Extracción: Escaneo/extracción con binwalk, análisis de entropía e identificación de sistemas de archivos
Escaneo de Vulnerabilidades: Credenciales codificadas, CVEs conocidos, funciones inseguras y criptografía débil
Detección de Dirección Base: Análisis de referencias a cadenas para recuperar la dirección base del firmware

Ingeniería Inversa de Protocolos (3 herramientas)

Análisis PCAP: Basado en tshark con 8 acciones (resumen, flujos, DNS, HTTP, TLS, filtro, exportación, IoC)
Disección de Protocolos: Inferencia de estructura binaria, detección de límites de campos y análisis de patrones
Fuzzing de Protocolos: Basado en mutaciones, pruebas de límites, específico de campos y fuzzing con plantillas

Desempaquetado (4 herramientas)

Detección de Empaquetadores: UPX, Themida, VMProtect, ASPack, PECompact, MPRESS y más
Desempaquetado UPX: Desempaquetado estático con copia de seguridad automática
Desempaquetado Dinámico: Volcado de memoria basado en Frida con detección de OEP
Reconstrucción PE: Corrección de alineaciones de secciones, importaciones y punto de entrada después del volcado de memoria

Ofuscación (3 herramientas)

Desofuscación de Cadenas: Fuerza bruta XOR, variantes ROT, Base64, RC4 y reconstrucción de cadenas en pila
Detección de Aplanamiento de Flujo de Control: Identificación de patrones CFF estilo OLLVM
Detección de Predicados Opacos: Identificación de ramas siempre-verdadero/falso

Ejecución Simbólica (4 herramientas)

Integración angr: Exploración de rutas, resolución de restricciones, generación de CFG y escaneo de vulnerabilidades
Triton DSE: Ejecución simbólica dinámica con estado concreto y simbólico

Especializaciones de Formatos Binarios (4 herramientas)

APK/DEX: Análisis de Android incluyendo manifiesto, permisos, librerías nativas y análisis DEX
.NET IL: Metadatos de ensamblados, listado de tipos/métodos y desensamblado IL
Clase Java: Análisis de archivos de clase, integración con javap y desensamblado de bytecode
WebAssembly: Análisis de secciones WASM, extracción de importaciones/exportaciones y desensamblado

Utilidades (8 herramientas)

Herramientas Hex: Hexdump, búsqueda de patrones (comodines estilo IDA) y comparación de binarios
Criptografía: Hash (MD5/SHA/TLSH/ssdeep), análisis XOR y escaneo de constantes criptográficas
Parcheo: Parcheo de binarios con copia de seguridad y soporte de NOP-sled
Red: Análisis PCAP con estadísticas de protocolos, extracción DNS y detección de balizas C2

Administración (2 herramientas)

Estado del Servidor: Versión, número de herramientas, estadísticas de caché, estadísticas de límite de velocidad y herramientas disponibles
Gestión de Caché: Ver estadísticas, limpiar caché e invalidar entradas específicas

Inicio Rápido

Requisitos Previos

Python 3.11 o posterior
Linux recomendado (macOS y WSL2 compatibles)
pip (o uv / pipx para instalaciones aisladas)

Instalación

# 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

El instalador automatizado gestiona la verificación de la versión de Python, la instalación de dependencias, la detección de herramientas externas y la generación de archivos de configuración.

Verificar Qué Está Disponible

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

Esto imprime una tabla que muestra qué herramientas externas y módulos de Python se detectan en tu sistema.

Instalación con Docker (Alternativa)

Revula se puede ejecutar en Docker para un entorno aislado solo-stdio con dependencias opcionales principales y comunes preconfiguradas:

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

Qué incluye la imagen Docker:

Todas las dependencias principales de Python (capstone, LIEF, pefile, yara)
Motor de ejecución simbólica angr
Instrumentación dinámica Frida
Analizador headless Ghidra
GDB/LLDB, radare2, rizin (+ rz-diff), binutils
ADB y herramientas de Android (apktool, jadx, aapt, apksigner, smali/baksmali)
Herramientas FLARE (FLOSS, capa)
RetDec, CFR, Detect-It-Easy (diec), DynamoRIO (drrun), UPX
Herramientas de explotación (msfvenom, one_gadget), checksec, herramientas mono (monodis/ikdasm), llvm-pdbutil
Herramientas de análisis de red (tcpdump, tshark, capinfos)

Prueba de la compilación Docker:

./scripts/docker/test.sh

Para documentación completa de Docker (modo stdio, volúmenes, uso con compose y solución de problemas), consulta DOCKER.md.

Nota sobre Docker vs. Nativo:

Docker proporciona un entorno aislado con herramientas principales preinstaladas
La instalación nativa ofrece mejor rendimiento y acceso directo al sistema
Elige según tus requisitos de seguridad y portabilidad

Configuración de IDE y Clientes

Cómo se Conecta (Importante)

Revula usa solo transporte stdio. El servidor lee JSON-RPC desde stdin y escribe en stdout. Cada cliente MCP listado a continuación lanza revula como un subproceso local. No hay servidor HTTP, ni endpoint SSE, ni conexión remota.

Qué significa esto para ti:

Revula debe estar instalado en la misma máquina donde se ejecuta tu IDE/cliente.
Si usas un servidor remoto o Docker, debes ejecutar tanto el cliente como revula en el mismo entorno (o usar tuberías SSH; consulta Clientes Personalizados / Otros).
Cada cliente a continuación usa el mismo comando revula. La única diferencia es dónde colocas la configuración.

Antes de Empezar

Asegúrate de que revula esté instalado y que el comando funcione:

# 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

Si revula no está en tu PATH, usa la ruta completa en cada configuración a continuación.

1. Claude Desktop

Estado: Totalmente compatible. Este es el cliente principal.

Ubicaciones de archivos de configuración:

Plataforma	Ruta
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`

Opción A: Configuración automática (recomendada)

python scripts/setup/setup_claude_desktop.py

Esto detecta automáticamente tu sistema operativo, encuentra el archivo de configuración y fusiona la entrada de revula. Crea una copia de seguridad primero.

Opción B: Configuración manual

Añade a tu claude_desktop_config.json:

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

Si revula está en un virtualenv:

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

Si usas uvx (instalación cero):

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

Después de editar: Cierra y vuelve a abrir Claude Desktop. Revisa el icono de herramientas MCP para confirmar que hay 116 herramientas disponibles.

2. Claude Code (CLI)

Estado: Totalmente compatible.

Opción A: Comando CLI (recomendado)

claude mcp add revula -- revula

Claude Code iniciará revula como subproceso cuando sea necesario.

Opción B: Configuración manual

Edita ~/.claude.json (o ~/.claude/settings.json según la versión):

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

3. VS Code (GitHub Copilot)

Estado: Compatible. Requiere la extensión GitHub Copilot con soporte MCP (VS Code 1.99+).

Importante: El soporte MCP en VS Code está disponible a través de la extensión GitHub Copilot Chat. Asegúrate de tener:

VS Code 1.99 o posterior
Extensión GitHub Copilot instalada y activa
MCP habilitado en la configuración: "chat.mcp.enabled": true

Opción A: Configuración del espacio de trabajo (ya incluida en este repositorio)

Este repositorio incluye .vscode/mcp.json:

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

Solo abre este proyecto en VS Code y Copilot descubrirá el servidor MCP automáticamente.

Opción B: Configuración a nivel de usuario (global, todos los proyectos)

Abre la configuración de VS Code (Ctrl+,) → busca "mcp" → edita settings.json:

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

Opción C: Crea .vscode/mcp.json en cualquier proyecto

Copia el archivo de este repositorio o créalo manualmente:

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

Después de editar: Recarga la ventana de VS Code (Ctrl+Shift+P → "Developer: Reload Window"). Las herramientas MCP deberían aparecer en Copilot Chat.

4. Cursor

Estado: Compatible. Cursor tiene soporte MCP integrado.

Archivo de configuración: ~/.cursor/mcp.json (global) o .cursor/mcp.json (por proyecto).

Este repositorio incluye .cursor/mcp.json para uso por proyecto.

Opción A: Por proyecto (ya incluido)

El .cursor/mcp.json en este repositorio:

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

Opción B: Configuración global

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

Después de editar: Reinicia Cursor. Revisa Settings → MCP para verificar que revula aparece.

5. Windsurf (Codeium)

Estado: Compatible. Windsurf Cascade admite servidores MCP.

Archivo de configuración: ~/.codeium/windsurf/mcp_config.json

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

Después de editar: Reinicia Windsurf. El panel Cascade debería mostrar las herramientas de revula.

6. Continue.dev

Estado: Compatible. Continue tiene soporte MCP en versiones recientes.

Archivo de configuración: ~/.continue/config.json

Añade a tu config.json existente:

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

Si usas config.yaml:

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

Después de editar: Reinicia tu IDE. Continue debería detectar el servidor MCP.

7. Zed

Estado: Compatible. Zed tiene soporte MCP nativo mediante servidores de contexto.

Archivo de configuración: ~/.config/zed/settings.json (Linux/macOS)

Añade a tu settings.json:

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

Después de editar: Reinicia Zed. El servidor de contexto debería aparecer en el panel Assistant.

8. Clientes Personalizados / Otros

Cualquier cliente MCP que admita transporte stdio funcionará con revula. El protocolo es JSON-RPC estándar sobre stdin/stdout.

Invocación directa:

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

Vía SSH (máquina remota):

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

En 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"]

Cliente Python (programático):

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

Script de Configuración Universal

Configura cualquier cliente con un solo comando:

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

El script detecta automáticamente cómo ejecutar revula (PATH, uvx o python -m), crea copias de seguridad antes de escribir y se integra en configuraciones existentes.

Configuración

Archivo de Configuración

Crea ~/.revula/config.toml (o usa el generador interactivo):

python scripts/setup/setup_config_toml.py

Ejemplo de configuración:

[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

Variables de Entorno

Las variables de entorno anulan los valores del archivo de configuración:

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)

Disponibilidad de Herramientas

revula se degrada con elegancia. Las herramientas que dependen de backends faltantes devuelven mensajes de error claros en lugar de fallar. Esto es lo que necesita cada categoría:

Categoría	Siempre disponible	Necesita herramienta externa	Necesita módulo Python
Estático	Análisis PE/ELF, entropía, cadenas	`objdump`, `radare2`, `ghidra`, `retdec`, `floss`, `capa`	`capstone` ✓, `lief` ✓, `pefile` ✓, `yara` ✓
Dinámico		`gdb`, `lldb`	`frida`
Android	Análisis de manifiesto APK/DEX (vía zipfile)	`jadx`, `apktool`, `adb`, `zipalign`, `apksigner`, `tcpdump`	`frida`, `quark-engine`
Plataforma		`rizin`, `radare2`, `gdb`, `qemu-user`, `qemu-system-*`	`r2pipe`, `binaryninja`
Explotación	Constructor de cadenas ROP, análisis de heap, base de datos libc, ayudantes de format string		`capstone` ✓, `pwntools`, `keystone-engine`
Anti-Análisis	Escaneo de patrones (vía `lief` + `capstone`)
Malware	Hash de archivos, extracción de IoC, puntuación de riesgo		`yara` ✓, `ssdeep`, `tlsh`
Firmware		`binwalk`, `sasquatch`
Protocolo	Disección de protocolos binarios, fuzzing	`tshark`	`scapy`
Desempaquetado	Detección de firmas de packers	`upx`	`frida`
Desofuscación	Desofuscación XOR/ROT/Base64		`capstone` ✓
Simbólico			`angr`, `triton` (solo compilación desde fuente; la herramienta se auto-habilita cuando está instalada)
Formatos Binarios		`aapt`, `javap`, `monodis`, `wasm2wat`
Utilidades	Volcado hexadecimal, diff binario, parcheo	`tshark`	`scapy`, `ssdeep`, `tlsh`

✓ = incluido en las dependencias principales (siempre instalado).

Instalación de Dependencias Opcionales

# 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]"

Instalación de Herramientas Externas (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

Arquitectura

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

Cómo Funciona

Inicio. server.py carga config.py, que sondea el sistema en busca de herramientas externas (vía shutil.which) y módulos Python (vía importlib.util.find_spec). Los resultados se almacenan en caché en un singleton ServerConfig.
Registro de Herramientas. Cada archivo de herramienta usa @TOOL_REGISTRY.register() para declarar su nombre, descripción, esquemas de entrada/salida, anotaciones y manejador asíncrono. Las herramientas se auto-registran al importarse.
Despacho de Solicitudes. Cuando llega una solicitud tools/call, el servidor resuelve alias con espacios de nombres, valida argumentos (Pydantic primero con respaldo JSON Schema), verifica límites de tasa, comprueba elegibilidad de caché, despacha el manejador y devuelve metadatos isError a nivel de protocolo.
Ejecución de Subprocesos. Todas las invocaciones de herramientas externas pasan por sandbox.safe_subprocess(), que aplica shell=False, establece RLIMIT_AS y RLIMIT_CPU, valida rutas y captura stdout/stderr.
Caché de Resultados. Las operaciones deterministas (desensamblado, análisis) se almacenan en caché con un TTL configurable. Las operaciones mutantes (parcheo, inyección Frida) omiten la caché automáticamente.
Gestión de Sesiones. Las sesiones de depurador y Frida de larga duración son rastreadas por SessionManager, con limpieza automática después de 30 minutos de inactividad.

Componentes de Infraestructura

Componente	Propósito	Detalle Clave
ResultCache	Evita llamadas redundantes a subprocesos	LRU, 256 entradas, TTL de 10 minutos
RateLimiter	Previene el agotamiento de recursos	Token-bucket con anulaciones de config/env
ToolRegistry	Despacho de herramientas basado en decoradores	Anotaciones + endurecimiento estricto de esquemas + errores estructurados
SessionManager	Persistencia de depurador/Frida	Limpieza automática después de 30 min de inactividad
sandbox.py	Capa de ejecución segura	`shell=False`, aplicación de RLIMIT, validación de rutas

Modelo de Seguridad

revula opera bajo el principio de que los argumentos proporcionados por el usuario no son confiables. Se aplican las siguientes medidas de endurecimiento:

Aislamiento de Subprocesos

Sin shell=True: Cada llamada a subprocesos usa shell=False con listas de argumentos explícitas. Esto se aplica mediante una prueba de CI (test_no_shell_true) que escanea cada archivo fuente.
Sin eval() / exec(): Sin evaluación dinámica de código de entrada del usuario.
Sin inyección f-string: Los valores proporcionados por el usuario nunca se interpolan en cadenas de código python3 -c. Los valores se pasan vía sys.argv, stdin o variables de entorno. Aplicado por test_no_fstring_in_subprocess_python_code.
Escapado de JavaScript: Todos los valores controlados por el usuario interpolados en cadenas JavaScript de Frida pasan por _js_escape(), que escapa barras invertidas, comillas, saltos de línea y otros vectores de inyección.
Límites de recursos: Cada subproceso recibe RLIMIT_AS (512 MB por defecto) y RLIMIT_CPU (60 s por defecto) vía resource.setrlimit().
Aplicación de tiempo de espera: asyncio.wait_for() envuelve todas las llamadas a subprocesos.

Validación de Rutas

Fail-closed: validate_path() rechaza todas las rutas cuando no hay allowed_dirs configurados (se respalda en get_config().security.allowed_dirs). No pasa silenciosamente.
Traversal bloqueado: Los componentes .. se rechazan después de la resolución os.path.realpath().
Rutas absolutas requeridas: Las rutas relativas se rechazan.
Validado en todas partes: Todos los manejadores de herramientas que aceptan archivos llaman a validate_path() antes de cualquier E/S de archivos.

Endurecimiento de Frida

Límite de tamaño de script: Los scripts de Frida están limitados a 1 MB para prevenir el agotamiento de memoria.
Límite de volcado de memoria: Los volcados de memoria están limitados a 100 MB.
Prevención de inyección JS: Los nombres de clases, métodos, módulos y otros valores proporcionados por el usuario se escapan antes de la interpolación en plantillas JavaScript.

Archivos Temporales

Sin tempfile.mktemp(): Todos los archivos temporales usan tempfile.NamedTemporaryFile() o tempfile.mkdtemp() para prevenir condiciones de carrera TOCTOU.
Sin rutas /tmp codificadas: Todas las rutas temporales usan el módulo tempfile.

Límite de Tasa y Caché

Límite global: 120 solicitudes por minuto (configurable).
Límite por herramienta: 30 solicitudes por minuto (configurable).
Política de caché de resultados: opt-in explícito fail-closed por herramienta (cacheable=True); las herramientas mutantes/con estado nunca se almacenan en caché por defecto.
TTL de sesión: Las sesiones inactivas se limpian automáticamente después de 30 minutos.

Pruebas

# 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

Categorías de Pruebas

Suite	Pruebas	Cubre
`test_infra.py`	Caché, limitador de tasa, gestor de sesiones	Corrección de infraestructura
`test_core.py`	Carga de configuración, sandbox, registro de herramientas	Comportamiento del módulo principal
`test_static.py`	Entropía, hex, cripto, cadenas, símbolos	Herramientas de análisis estático
`test_android.py`	Análisis APK, DEX, dispositivo, Frida Android	Pruebas del módulo Android
`test_tools_new.py`	Explotación, malware, firmware, protocolo, anti-análisis, plataforma, desofuscación, simbólico, desempaquetado, formatos binarios	Todas las categorías de herramientas restantes
`test_security.py`	Escaneo `shell=True`, escaneo de inyección, escaneo `mktemp`, escaneo de `/tmp` codificados, validación de rutas, escapado JS, validación de shellcode	Pruebas de regresión de seguridad

Pruebas de Seguridad

La suite TestVulnerabilityHardeningV3 en test_security.py aplica:

Sin inyección de código f-string: Escanea todos los archivos fuente en busca de argumentos "-c" que contengan f-strings.
Sin tempfile.mktemp(): Previene condiciones de carrera TOCTOU.
Sin rutas /tmp/ codificadas: Aplica el uso del módulo tempfile.
Validación de rutas fail-closed: Verifica que validate_path() rechaza rutas cuando allowed_dirs está vacío.
Escapado JS de Frida: Verifica que _js_escape() bloquea payloads de inyección.
Validación hexadecimal de shellcode: Verifica que la entrada no hexadecimal se rechaza, no se pasa al subproceso.

Scripts y Automatización

Los scripts principales de automatización se encuentran en scripts/:

Instalación

Script	Propósito
`scripts/install/install_all.sh`	Instalador maestro: verificación de Python, dependencias, herramientas externas, configuración
`scripts/install/install_verify.sh`	Verificación post-instalación: comprueba todas las dependencias y rutas

Configuración

Script	Propósito
`scripts/setup/setup_ide.py`	Configurador universal de IDE/cliente para Claude Desktop, VS Code, Cursor, Windsurf, Zed y Continue
`scripts/setup/setup_claude_desktop.py`	Auto-configurador específico de Claude Desktop (legado, aún funcional)
`scripts/setup/setup_config_toml.py`	Generador interactivo de config.toml
`scripts/setup/setup_android_device.sh`	Prepara un dispositivo Android para RE (root, frida-server, certificados)

Pruebas y Desarrollo

Script	Propósito
`scripts/test/run_tests.sh`	Ejecuta la suite de pruebas completa con cobertura
`scripts/test/validate_install.py`	Validador integral de instalación
`scripts/dev/add_tool.py`	Genera un nuevo módulo de herramienta (crea archivo, registra, añade prueba)
`scripts/dev/lint_and_type.sh`	Ejecuta ruff + mypy
`scripts/utils/download_frida_server.py`	Descarga frida-server para una arquitectura objetivo

Docker

Script	Propósito
`scripts/docker/test.sh`	Build automatizado de Docker y comprobaciones de humo orientadas a stdio
`scripts/docker/validate.sh`	Validación de configuración de Docker

Ejemplos de Uso

Análisis Estático: Analizar un Binario PE

Pregunta a Claude: "Analiza este binario por mí: /home/user/samples/malware.exe" Entre bastidores, Claude puede llamar:

re_pe_elf para analizar cabeceras PE, secciones, importaciones y exportaciones
re_strings para extraer y clasificar cadenas (URLs, IPs, constantes criptográficas)
re_entropy para comprobar empaquetado (secciones de alta entropía)
re_yara_scan para escanear con reglas YARA
re_capa_scan para mapear a técnicas ATT&CK

Análisis Dinámico: Depurar con GDB

Pregunta a Claude: "Depura /home/user/crackme y encuentra la comprobación de contraseña"

Claude puede orquestar:

re_gdb con la acción start para lanzar el binario bajo GDB
re_disasm para desensamblar funciones clave
re_gdb con la acción breakpoint para establecer puntos de interrupción en instrucciones de comparación
re_gdb con la acción continue y registers para ejecutar e inspeccionar el estado

Android: Ingeniería Inversa de un APK

Pregunta a Claude: "Analiza este APK en busca de problemas de seguridad: /home/user/app.apk"

Claude puede llamar:

re_apk_parse para extraer el manifiesto, los permisos y los componentes
re_dex_analyze para listar clases y encontrar métodos sospechosos
re_android_decompile para descompilar con jadx
re_android_scanner para ejecutar escáneres de seguridad
re_antianalysis_detect para comprobar la protección contra manipulación

Triaje de Malware

Pregunta a Claude: "Haz triaje de esta muestra de malware sospechosa"

Claude puede llamar:

re_malware_triage para hashes, IoCs, análisis de importaciones y puntuación de riesgo
re_malware_config para extraer URLs de C2 y claves de cifrado
re_malware_yara_gen para generar una regla YARA para la muestra
re_malware_sandbox para consultar VirusTotal/Hybrid Analysis

Desarrollo de Exploits

Pregunta a Claude: "Construye una cadena ROP para llamar a execve('/bin/sh') en este binario"

Claude puede orquestar:

re_rop_gadgets para encontrar gadgets útiles (pop rdi, pop rsi, syscall) con clasificación semántica
re_rop_chain para construir automáticamente una cadena execve con la configuración adecuada de registros
re_libc_offsets para extraer offsets de system/execve/binsh de libc
re_aslr_defeat para calcular direcciones base a partir de punteros filtrados
re_heap_chunk para analizar chunks de malloc y clasificación de bins para exploits de heap
re_heap_technique para obtener plantillas para House of Force, Tcache Poisoning, etc.

Rendimiento y Limitaciones

Qué Funciona Bien Sin Dependencias Opcionales

Con solo la instalación principal (pip install -e .), obtienes funcionalidad completa para:

Análisis de PE/ELF/Mach-O y de cabeceras
Desensamblado multiarquitectura (vía Capstone)
Extracción y clasificación de cadenas
Análisis de entropía de Shannon y detección de empaquetado
Escaneo de reglas YARA
Parcheo de binarios
Volcado hexadecimal y búsqueda de patrones
Hash de archivos (MD5, SHA-1, SHA-256)
Búsqueda de gadgets ROP y construcción de cadenas (vía Capstone)
Utilidades de explotación de heap (análisis de chunks, clasificación de bins, safe-linking)
Herramientas de base de datos libc (extracción de símbolos, cálculo de offsets, evasión de ASLR)
Cálculo de payloads de format string
Desofuscación XOR/ROT/Base64
Detección de patrones anti-análisis

Qué Requiere Herramientas Externas

Estas herramientas producen errores claros de "herramienta no encontrada" cuando faltan los backends:

Descompilación requiere Ghidra, RetDec o Binary Ninja
Análisis dinámico requiere GDB, LLDB o Frida
Ingeniería inversa de Android requiere jadx, apktool y ADB
Ejecución simbólica requiere angr (dependencia grande, ~2 GB)
Análisis de red requiere tshark o scapy
Extracción de firmware requiere binwalk

Expectativas de Rendimiento

Inicio: ~1 segundo (sondea el sistema en busca de herramientas disponibles mediante shutil.which y importlib.util.find_spec)
Análisis estático: Menos de un segundo para la mayoría de operaciones en archivos de menos de 100 MB
Desensamblado: Capstone desensambla ~1 MB/s; radare2 añade sobrecarga de análisis completo
Llamadas a subprocesos: Cada invocación de herramienta externa tiene ~50-200 ms de sobrecarga por el lanzamiento del proceso
Caché: El almacenamiento en caché de resultados es una opción explícita por herramienta; a menos que esté habilitado, las llamadas se ejecutan de nuevo
Límite de peticiones: 120 peticiones/minuto globales, 30/minuto por herramienta (configurable)

Limitaciones Conocidas

Sin soporte nativo para Windows. Diseñado para Linux. macOS funciona con la mayoría de herramientas. Windows requiere WSL2.
Solo transporte stdio. No hay servidor HTTP/SSE. Revula debe ejecutarse en la misma máquina que tu IDE (o canalizarse vía SSH/Docker). Es una decisión de diseño deliberada por seguridad: MCP sobre stdio es más simple y evita exponer un socket de red.
Sin GUI. Este es un servidor MCP sin interfaz gráfica. Usa Claude Desktop, VS Code Copilot, Cursor u otro cliente MCP para la interfaz.
Análisis de binarios grandes. Los archivos de más de 500 MB pueden alcanzar el límite de memoria predeterminado (512 MB). Auméntalo mediante REVULA_MAX_MEMORY_MB.
Tamaño de instalación de angr. La dependencia opcional angr es de ~2 GB y tarda varios minutos en instalarse.
Acoplamiento de versiones de Frida. Las versiones del cliente y del servidor de Frida deben coincidir exactamente. Usa scripts/utils/download_frida_server.py para obtener la versión correcta.
Diseño de un solo usuario. El servidor gestiona un cliente MCP a la vez mediante stdio. No hay aislamiento multiinquilino. Cada IDE/cliente genera su propio proceso de servidor.
Integración con IDA Pro. Requiere IDA Pro con el plugin de API REST. No incluido.

Solución de Problemas

El Servidor No Se Inicia

# 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

La Herramienta Dice "no encontrada"

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

Errores de Validación de Rutas

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

Añade el directorio a tu configuración:

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

Alternativamente, establece el valor mediante una variable de entorno. El servidor usará el allowed_dirs del archivo de configuración como respaldo.

Límite de Peticiones Superado

Error: Rate limit exceeded for tool re_disasm

Los límites de peticiones se inicializan actualmente desde los valores predeterminados del código (global_rpm=120, per_tool_rpm=30, burst_size=10). Si necesitas límites diferentes, ajusta RateLimitConfig(...) en src/revula/server.py y reinicia.

Problemas de Conexión con Frida

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

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

Pruebas Fallando

# 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

Dispositivo Android No Detectado

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

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

Contribuciones

Añadir una Nueva Herramienta

Usa el generador de plantillas:

python scripts/dev/add_tool.py

Esto crea el archivo de la herramienta, la registra en la categoría __init__.py y genera un stub de prueba.

Calidad del Código

# 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

Directrices

Cada manejador de herramienta es async y devuelve list[dict] (bloques de contenido MCP).
Todas las llamadas a subprocesos pasan por sandbox.safe_subprocess().
Todas las rutas de archivo deben validarse mediante sandbox.validate_path().
Sin shell=True, sin eval(), sin interpolación de f-strings en el código de subprocesos.
Cada herramienta nueva necesita al menos una prueba.

Licencia

Publicado bajo la Licencia Pública General de GNU. Consulta LICENSE para más detalles.