Reverse Engineering MCP

MCP de nível de produção para Engenharia Reversa (inclui quase todas as ferramentas necessárias)

Documentação

revula

Servidor MCP de nível de produção para automação universal de engenharia reversa.

Conecte o Claude Desktop, IDEs compatíveis com MCP ou ferramentas personalizadas a um backend abrangente de engenharia reversa por meio do Model Context Protocol.

Recursos

Análise Estática (8 ferramentas)

Análise de binários: PE/ELF/Mach-O via LIEF com cálculo de hash e detecção de indicadores suspeitos
Desmontagem: Suporte a múltiplos backends, incluindo Capstone (sempre disponível), radare2 e objdump para x86/x64/ARM/MIPS/RISC-V
Extração de strings: Integração com FLOSS, fallback por regex, 17 padrões de classificação (URLs, IPs, criptografia, chaves de registro)
Análise de entropia: Entropia de Shannon com janela deslizante, análise por seção e detecção de empacotamento
Extração de símbolos: DWARF, PDB, LIEF universal; varredura de prólogo de funções para binários sem símbolos
Varredura YARA: Regras inline, regras de arquivo/diretório e suporte a regras da comunidade
Integração com Capa: Mapeamento ATT&CK, comportamentos MBC, enumeração de capacidades
Descompilação: Ghidra (headless), RetDec, Binary Ninja com cache

Análise Dinâmica (29 ferramentas)

Adaptador GDB: Protocolo completo GDB/MI com breakpoints, execução passo a passo, registradores, memória, backtrace e inspeção de heap
Adaptador LLDB: Integração nativa com a API SB para depuração em macOS/Linux
Adaptador Frida: Spawn/attach, injeção de scripts, interceptação de funções, varredura/despejo de memória e exportações RPC
Cobertura de código: DynamoRIO drcov, rastreamento de blocos com Frida Stalker e análise de cobertura

RE Android (24 ferramentas)

Análise de APK: Extração de manifesto, análise de permissões, enumeração de componentes e inspeção de recursos
Análise DEX: Listagem de classes/métodos, estatísticas de bytecode e extração de strings
Descompilação: Integração com jadx/apktool, desmontagem/montagem/patch em smali
Análise de binários nativos: Análise de .so ARM/AArch64 com detecção JNI
Interação com dispositivo: Ponte ADB com 12 ações (logcat, install, shell, dumpsys, screenshot)
Frida para Android: Bypass de root, hook de criptografia, bypass de SSL pinning, rastreamento de API e despejo de memória
Interceptação de tráfego: Integração com tcpdump/mitmproxy e extração de chaves SSL
Repack e assinatura: Reconstrução de APK com patches smali, zipalign + apksigner
Scanners de segurança: MobSF, Quark-Engine, Semgrep e detecção de vulnerabilidades no manifesto

Ferramentas RE Multiplataforma (7 ferramentas)

Rizin/r2: Análise automatizada com 13 ações e diff de binários
GDB Aprimorado: Análise de heap, busca de gadgets ROP, auxiliares de exploração (pattern create/find, checksec)
QEMU: Emulação em modo usuário (4 ações) e emulação completa de sistema (5 ações)

Desenvolvimento de Exploits (11 ferramentas)

Construtor de cadeia ROP: Busca de gadgets multiarquitetura (x86/x64/ARM/ARM64) com classificação semântica, geração automática de cadeias para execve/mprotect/syscalls, evitação de caracteres ruins e geração de scripts pwntools
Exploração de heap: Análise de chunks malloc, classificação de bins (tcache/fastbin/smallbin/largebin), geração de chunks falsos, codificação/decodificação safe-linking para glibc 2.32+ e modelos de técnicas (House of Force, Tcache Poisoning, Fastbin Dup, Unsafe Unlink)
Banco de dados libc: Extração de símbolos/offsets, identificação da libc a partir de endereços vazados, auxiliares para derrotar ASLR (cálculo de base, GOT-to-libc, PLT-to-GOT) e localizador de one-gadget RCE
Shellcode: Geração, codificação, análise de caracteres ruins, extração e teste de emulação
String de formato: Cálculo de offset, geração de payloads de escrita, sobrescrita de GOT e vazamento de endereços

Anti-Análise (2 ferramentas)

Detecção: Varredura por indicadores de anti-debug, anti-VM, anti-tamper e empacotamento
Geração de bypass: Scripts Frida/GDB/patch/LD_PRELOAD para ptrace, IsDebuggerPresent, timing e verificações de VM

Análise de Malware (4 ferramentas)

Triagem: Múltiplos hashes, extração de IoC, pontuação de imports suspeitos e avaliação de risco
Consultas a sandbox: Integração com APIs do VirusTotal, Hybrid Analysis e MalwareBazaar
Geração de YARA: Geração automática de regras YARA a partir de artefatos binários
Extração de configuração: URLs de C2, IPs, domínios, chaves de criptografia e mutexes

RE de Firmware (3 ferramentas)

Extração: Varredura/extração com binwalk, análise de entropia e identificação de sistema de arquivos
Varredura de vulnerabilidades: Credenciais embutidas, CVEs conhecidos, funções inseguras e criptografia fraca
Detecção de endereço base: Análise de referências a strings para recuperação do endereço base do firmware

RE de Protocolos (3 ferramentas)

Análise de PCAP: Baseada em tshark com 8 ações (resumo, fluxos, DNS, HTTP, TLS, filtro, exportação, IoC)
Dissecação de protocolos: Inferência de estrutura binária, detecção de limites de campos e análise de padrões
Fuzzing de protocolos: Baseado em mutação, teste de limites, específico de campo e fuzzing por modelo

Desempacotamento (4 ferramentas)

Detecção de empacotadores: UPX, Themida, VMProtect, ASPack, PECompact, MPRESS e outros
Desempacotamento UPX: Desempacotamento estático com backup automático
Desempacotamento dinâmico: Despejo de memória baseado em Frida com detecção de OEP
Reconstrução de PE: Correção de alinhamentos de seção, imports e ponto de entrada após despejo de memória

Desofuscação (3 ferramentas)

Desofuscação de strings: Força bruta XOR, variantes ROT, Base64, RC4 e reconstrução de strings em pilha
Detecção de flattening de fluxo de controle: Identificação de padrões CFF estilo OLLVM
Detecção de predicados opacos: Identificação de ramos sempre verdadeiros/falsos

Execução Simbólica (4 ferramentas)

Integração angr: Exploração de caminhos, resolução de restrições, geração de CFG e varredura de vulnerabilidades
Triton DSE: Execução simbólica dinâmica com estado concreto e simbólico

Especializações em Formatos Binários (4 ferramentas)

APK/DEX: Análise Android incluindo manifesto, permissões, bibliotecas nativas e parsing DEX
.NET IL: Metadados do assembly, listagem de tipos/métodos e desmontagem IL
Classe Java: Parsing de arquivos de classe, integração com javap e desmontagem de bytecode
WebAssembly: Parsing de seções WASM, extração de importações/exportações e desmontagem

Utilitários (8 ferramentas)

Ferramentas hex: Hexdump, busca de padrões (curingas estilo IDA) e diff binário
Criptografia: Hashing (MD5/SHA/TLSH/ssdeep), análise XOR e varredura de constantes criptográficas
Patch: Patch binário com backup e suporte a NOP-sled
Rede: Análise de PCAP com estatísticas de protocolo, extração DNS e detecção de beacons C2

Administração (2 ferramentas)

Status do servidor: Versão, contagem de ferramentas, estatísticas de cache, estatísticas de limite de taxa e ferramentas disponíveis
Gerenciamento de cache: Ver estatísticas, limpar cache e invalidar entradas específicas

Início Rápido

Pré-requisitos

Python 3.11 ou posterior
Linux recomendado (macOS e WSL2 suportados)
pip (ou uv / pipx para instalações isoladas)

Instalação

# 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

O instalador automatizado lida com verificação de versão do Python, instalação de dependências, detecção de ferramentas externas e geração de arquivos de configuração.

Verifique o Que Está Disponível

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

Isso imprime uma tabela mostrando quais ferramentas externas e módulos Python são detectados no seu sistema.

Instalação via Docker (Alternativa)

O Revula pode ser executado em Docker para um ambiente isolado, somente stdio, com dependências principais e opcionais comuns pré-configuradas:

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

O que está incluído na imagem Docker:

Todas as dependências Python principais (capstone, LIEF, pefile, yara)
Mecanismo de execução simbólica angr
Instrumentação dinâmica Frida
Analisador headless Ghidra
GDB/LLDB, radare2, rizin (+ rz-diff), binutils
ADB e ferramentas Android (apktool, jadx, aapt, apksigner, smali/baksmali)
Ferramentas FLARE (FLOSS, capa)
RetDec, CFR, Detect-It-Easy (diec), DynamoRIO (drrun), UPX
Ferramentas de exploração (msfvenom, one_gadget), checksec, ferramentas mono (monodis/ikdasm), llvm-pdbutil
Ferramentas de análise de rede (tcpdump, tshark, capinfos)

Testando a build Docker:

./scripts/docker/test.sh

Para documentação completa do Docker (modo stdio, volumes, uso com compose e solução de problemas), consulte DOCKER.md.

Nota sobre Docker vs. nativo:

Docker fornece um ambiente isolado com ferramentas principais pré-instaladas
A instalação nativa oferece melhor desempenho e acesso direto ao sistema
Escolha com base em seus requisitos de segurança e portabilidade

Configuração de IDE e Cliente

Como Ele Se Conecta (Importante)

O Revula usa apenas transporte stdio. O servidor lê JSON-RPC do stdin e escreve para stdout. Cada cliente MCP listado abaixo inicia o Revula como um subprocesso local. Não há servidor HTTP, endpoint SSE ou conexão remota.

O que isso significa para você:

O Revula deve estar instalado na mesma máquina onde seu IDE/cliente é executado.
Se você usar um servidor remoto ou Docker, deve executar tanto o cliente quanto o Revula no mesmo ambiente (ou usar pipes SSH; consulte Personalizado / Outros Clientes).
Cada cliente abaixo usa o mesmo comando revula. A única diferença é onde você coloca a configuração.

Antes de Começar

Certifique-se de que o Revula está instalado e o comando funciona:

# 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

Se revula não estiver no PATH, use o caminho completo em cada configuração abaixo.

1. Claude Desktop

Status: Totalmente suportado. Este é o cliente principal.

Locais dos arquivos de configuração:

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

Opção A: Configuração automática (recomendada)

python scripts/setup/setup_claude_desktop.py

Isso detecta automaticamente seu SO, encontra o arquivo de configuração e mescla a entrada do Revula. Ele cria um backup antes.

Opção B: Configuração manual

Adicione ao seu claude_desktop_config.json:

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

Se o Revula estiver em um virtualenv:

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

Se estiver usando uvx (zero-instalação):

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

Após editar: Saia e reabra o Claude Desktop. Verifique o ícone de ferramentas MCP para confirmar que 116 ferramentas estão disponíveis.

2. Claude Code (CLI)

Status: Totalmente suportado.

Opção A: Comando CLI (recomendado)

claude mcp add revula -- revula

O Claude Code iniciará o Revula como um subprocesso quando necessário.

Opção B: Configuração manual

Edite ~/.claude.json (ou ~/.claude/settings.json dependendo da versão):

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

3. VS Code (GitHub Copilot)

Status: Suportado. Requer a extensão GitHub Copilot com suporte a MCP (VS Code 1.99+).

Importante: O suporte a MCP no VS Code está disponível através da extensão GitHub Copilot Chat. Certifique-se de que você tenha:

VS Code 1.99 ou posterior
Extensão GitHub Copilot instalada e ativa
MCP habilitado nas configurações: "chat.mcp.enabled": true

Opção A: Configuração do workspace (já incluída neste repositório)

Este repositório inclui .vscode/mcp.json:

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

Basta abrir este projeto no VS Code e o Copilot descobrirá o servidor MCP automaticamente.

Opção B: Configuração no nível do usuário (global, todos os projetos)

Abra as configurações do VS Code (Ctrl+,) → pesquise "mcp" → edite settings.json:

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

Opção C: Crie .vscode/mcp.json em qualquer projeto

Copie o arquivo deste repositório ou crie-o manualmente:

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

Após editar: Recarregue a janela do VS Code (Ctrl+Shift+P → "Developer: Reload Window"). As ferramentas MCP devem aparecer no Copilot Chat.

4. Cursor

Status: Suportado. O Cursor tem suporte MCP integrado.

Arquivo de configuração: ~/.cursor/mcp.json (global) ou .cursor/mcp.json (por projeto).

Este repositório inclui .cursor/mcp.json para uso por projeto.

Opção A: Por projeto (já incluído)

O .cursor/mcp.json neste repositório:

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

Opção B: Configuração global

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

Após editar: Reinicie o Cursor. Verifique em Configurações → MCP se o revula aparece.

5. Windsurf (Codeium)

Status: Suportado. O Windsurf Cascade suporta servidores MCP.

Arquivo de configuração: ~/.codeium/windsurf/mcp_config.json

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

Após editar: Reinicie o Windsurf. O painel Cascade deve mostrar as ferramentas do revula.

6. Continue.dev

Status: Suportado. O Continue tem suporte MCP em versões recentes.

Arquivo de configuração: ~/.continue/config.json

Adicione ao seu config.json existente:

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

Se você usa config.yaml:

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

Após editar: Reinicie sua IDE. O Continue deve detectar o servidor MCP.

7. Zed

Status: Suportado. O Zed tem suporte MCP nativo via servidores de contexto.

Arquivo de configuração: ~/.config/zed/settings.json (Linux/macOS)

Adicione ao seu settings.json:

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

Após editar: Reinicie o Zed. O servidor de contexto deve aparecer no painel Assistant.

8. Clientes Personalizados / Outros

Qualquer cliente MCP que suporte transporte stdio funcionará com o revula. O protocolo é JSON-RPC padrão sobre stdin/stdout.

Invocação direta:

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

Via SSH (máquina remota):

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

No 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 Configuração Universal

Configure qualquer cliente com um 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"

O script detecta automaticamente como executar o revula (PATH, uvx ou python -m), cria backups antes de gravar e mescla nas configurações existentes.

Configuração

Arquivo de Configuração

Crie ~/.revula/config.toml (ou use o gerador interativo):

python scripts/setup/setup_config_toml.py

Exemplo de configuração:

[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

Variáveis de Ambiente

As variáveis de ambiente sobrescrevem os valores do arquivo de configuração:

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)

Disponibilidade de Ferramentas

O revula degrada graciosamente. Ferramentas que dependem de backends ausentes retornam mensagens de erro claras em vez de travar. Aqui está o que cada categoria precisa:

Categoria	Sempre Disponível	Precisa de Ferramenta Externa	Precisa de Módulo Python
Estática	Parsing de PE/ELF, entropia, strings	`objdump`, `radare2`, `ghidra`, `retdec`, `floss`, `capa`	`capstone` ✓, `lief` ✓, `pefile` ✓, `yara` ✓
Dinâmica		`gdb`, `lldb`	`frida`
Android	Parsing de manifesto APK/DEX (via zipfile)	`jadx`, `apktool`, `adb`, `zipalign`, `apksigner`, `tcpdump`	`frida`, `quark-engine`
Plataforma		`rizin`, `radare2`, `gdb`, `qemu-user`, `qemu-system-*`	`r2pipe`, `binaryninja`
Exploração	Construtor de cadeias ROP, análise de heap, banco de dados libc, auxiliares de format string		`capstone` ✓, `pwntools`, `keystone-engine`
Anti-Análise	Varredura de padrões (via `lief` + `capstone`)
Malware	Hash de arquivos, extração de IoC, pontuação de risco		`yara` ✓, `ssdeep`, `tlsh`
Firmware		`binwalk`, `sasquatch`
Protocolo	Dissecação de protocolo binário, fuzzing	`tshark`	`scapy`
Desempacotamento	Detecção de assinatura de packer	`upx`	`frida`
Desofuscação	Desofuscação XOR/ROT/Base64		`capstone` ✓
Simbólica			`angr`, `triton` (somente build de fonte; a ferramenta se ativa automaticamente quando instalada)
Formatos Binários		`aapt`, `javap`, `monodis`, `wasm2wat`
Utilitários	Hex dump, diff binário, patching	`tshark`	`scapy`, `ssdeep`, `tlsh`

✓ = incluído nas dependências principais (sempre instalado).

Instalando Dependências Opcionais

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

Instalando Ferramentas 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

Arquitetura

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

Como Funciona

Inicialização. server.py carrega config.py, que verifica o sistema em busca de ferramentas externas (via shutil.which) e módulos Python (via importlib.util.find_spec). Os resultados são armazenados em cache em um singleton ServerConfig.
Registro de Ferramentas. Cada arquivo de ferramenta usa @TOOL_REGISTRY.register() para declarar seu nome, descrição, esquemas de entrada/saída, anotações e handler assíncrono. As ferramentas se registram automaticamente na importação.
Despacho de Requisições. Quando uma requisição tools/call chega, o servidor resolve aliases com namespace, valida argumentos (Pydantic primeiro com fallback para JSON Schema), verifica limites de taxa, verifica elegibilidade de cache, despacha o handler e retorna metadados de nível de protocolo isError.
Execução de Subprocessos. Todas as invocações de ferramentas externas passam por sandbox.safe_subprocess(), que aplica shell=False, define RLIMIT_AS e RLIMIT_CPU, valida caminhos e captura stdout/stderr.
Cache de Resultados. Operações determinísticas (desmontagem, parsing) são armazenadas em cache com TTL configurável. Operações de mutação (patching, injeção Frida) ignoram o cache automaticamente.
Gerenciamento de Sessões. Sessões de longa duração de debugger e Frida são rastreadas por SessionManager, com limpeza automática após 30 minutos de inatividade.

Componentes de Infraestrutura

Componente	Finalidade	Detalhe Principal
ResultCache	Evita chamadas redundantes de subprocesso	LRU, 256 entradas, TTL de 10 minutos
RateLimiter	Previne esgotamento de recursos	Token-bucket com sobrescritas de config/env
ToolRegistry	Despacho de ferramentas baseado em decorator	Anotações + endurecimento estrito de esquema + erros estruturados
SessionManager	Persistência de debugger/Frida	Limpeza automática após 30 min de inatividade
sandbox.py	Camada de execução segura	`shell=False`, aplicação de RLIMIT, validação de caminhos

Modelo de Segurança

O revula opera com o princípio de que argumentos fornecidos pelo usuário não são confiáveis. As seguintes medidas de endurecimento são aplicadas:

Isolamento de Subprocessos

Sem shell=True: Cada chamada de subprocesso usa shell=False com listas de argumentos explícitas. Isso é aplicado por um teste de CI (test_no_shell_true) que verifica cada arquivo de código-fonte.
Sem eval() / exec(): Sem avaliação dinâmica de código de entrada do usuário.
Sem injeção de f-string: Valores fornecidos pelo usuário nunca são interpolados em strings de código python3 -c. Os valores são passados via sys.argv, stdin ou variáveis de ambiente. Aplicado por test_no_fstring_in_subprocess_python_code.
Escapamento de JavaScript: Todos os valores controlados pelo usuário interpolados em strings JavaScript do Frida passam por _js_escape(), que escapa barras invertidas, aspas, quebras de linha e outros vetores de injeção.
Limites de recursos: Cada subprocesso recebe RLIMIT_AS (512 MB padrão) e RLIMIT_CPU (60 s padrão) via resource.setrlimit().
Aplicação de timeout: asyncio.wait_for() envolve todas as chamadas de subprocesso.

Validação de Caminhos

Fail-closed: validate_path() rejeita todos os caminhos quando nenhum allowed_dirs está configurado (recorre a get_config().security.allowed_dirs). Não passa silenciosamente.
Traversal bloqueado: Componentes .. são rejeitados após a resolução de os.path.realpath().
Caminhos absolutos obrigatórios: Caminhos relativos são rejeitados.
Validado em todos os lugares: Todos os handlers de ferramentas que aceitam arquivos chamam validate_path() antes de qualquer I/O de arquivo.

Endurecimento do Frida

Limite de tamanho de script: Scripts Frida são limitados a 1 MB para evitar esgotamento de memória.
Limite de dump de memória: Dumps de memória são limitados a 100 MB.
Prevenção de injeção JS: Nomes de classes, nomes de métodos, nomes de módulos e outros valores fornecidos pelo usuário são escapados antes da interpolação em templates JavaScript.

Arquivos Temporários

Sem tempfile.mktemp(): Todos os arquivos temporários usam tempfile.NamedTemporaryFile() ou tempfile.mkdtemp() para prevenir condições de corrida TOCTOU.
Sem caminhos /tmp codificados: Todos os caminhos temporários usam o módulo tempfile.

Limitação de Taxa e Cache

Limite global: 120 requisições por minuto (configurável).
Limite por ferramenta: 30 requisições por minuto (configurável).
Política de cache de resultados: fail-closed com opt-in explícito por ferramenta (cacheable=True); ferramentas de mutação/com estado nunca são armazenadas em cache por padrão.
TTL de sessão: Sessões ociosas são limpas automaticamente após 30 minutos.

Testes

# 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

Categorias de Teste

Suíte	Testes	Cobre
`test_infra.py`	Cache, limitador de taxa, gerenciador de sessões	Corretude da infraestrutura
`test_core.py`	Carregamento de config, sandbox, registro de ferramentas	Comportamento do módulo principal
`test_static.py`	Entropia, hex, cripto, strings, símbolos	Ferramentas de análise estática
`test_android.py`	Parse de APK, DEX, dispositivo, Frida Android	Testes do módulo Android
`test_tools_new.py`	Exploração, malware, firmware, protocolo, anti-análise, plataforma, desofuscação, simbólica, desempacotamento, formatos binários	Todas as categorias restantes de ferramentas
`test_security.py`	Varredura de `shell=True`, varredura de injeção, varredura de `mktemp`, varredura de `/tmp` codificado, validação de caminhos, escapamento JS, validação de shellcode	Testes de regressão de segurança

Testes de Segurança

A suíte TestVulnerabilityHardeningV3 em test_security.py aplica:

Sem injeção de código f-string: Verifica todos os arquivos de código-fonte em busca de argumentos "-c" contendo f-strings.
Sem tempfile.mktemp(): Previne condições de corrida TOCTOU.
Sem caminhos /tmp/ codificados: Aplica o uso do módulo tempfile.
Validação de caminhos fail-closed: Verifica se validate_path() rejeita caminhos quando allowed_dirs está vazio.
Escapamento JS do Frida: Verifica se _js_escape() bloqueia payloads de injeção.
Validação de hex de shellcode: Verifica se entrada não-hex é rejeitada, não passada ao subprocesso.

Scripts e Automação

Os scripts principais de automação ficam em scripts/:

Instalação

Script	Finalidade
`scripts/install/install_all.sh`	Instalador principal: verificação de Python, dependências, ferramentas externas, config
`scripts/install/install_verify.sh`	Verificação pós-instalação: verifica todas as dependências e caminhos

Configuração

Script	Finalidade
`scripts/setup/setup_ide.py`	Configurador universal de IDE/cliente para Claude Desktop, VS Code, Cursor, Windsurf, Zed e Continue
`scripts/setup/setup_claude_desktop.py`	Auto-configurador específico do Claude Desktop (legado, ainda funcional)
`scripts/setup/setup_config_toml.py`	Gerador interativo de config.toml
`scripts/setup/setup_android_device.sh`	Prepara um dispositivo Android para RE (root, frida-server, certificados)

Testes e Desenvolvimento

Script	Finalidade
`scripts/test/run_tests.sh`	Executa a suíte completa de testes com cobertura
`scripts/test/validate_install.py`	Validador abrangente de instalação
`scripts/dev/add_tool.py`	Cria um novo módulo de ferramenta (cria arquivo, registra, adiciona teste)
`scripts/dev/lint_and_type.sh`	Executa ruff + mypy
`scripts/utils/download_frida_server.py`	Baixa frida-server para uma arquitetura alvo

Docker

Script	Finalidade
`scripts/docker/test.sh`	Build automatizado do Docker e verificações smoke orientadas a stdio
`scripts/docker/validate.sh`	Validação de configuração do Docker

Exemplos de Uso

Análise Estática: Analisar um Binário PE

Pergunte ao Claude: "Analise este binário para mim: /home/user/samples/malware.exe" Por trás dos bastidores, o Claude pode chamar:

re_pe_elf para analisar cabeçalhos PE, seções, imports e exports
re_strings para extrair e classificar strings (URLs, IPs, constantes criptográficas)
re_entropy para verificar empacotamento (seções com entropia alta)
re_yara_scan para escanear com regras YARA
re_capa_scan para mapear para técnicas ATT&CK

Análise Dinâmica: Depuração com GDB

Pergunte ao Claude: "Depurar /home/user/crackme e encontrar a verificação de senha"

O Claude pode orquestrar:

re_gdb com a ação start para iniciar o binário sob GDB
re_disasm para desmontar funções-chave
re_gdb com a ação breakpoint para definir breakpoints em instruções de comparação
re_gdb com a ação continue e registers para executar e inspecionar o estado

Android: Reverter um APK

Pergunte ao Claude: "Analisar este APK em busca de problemas de segurança: /home/user/app.apk"

O Claude pode chamar:

re_apk_parse para extrair manifest, permissões e componentes
re_dex_analyze para listar classes e encontrar métodos suspeitos
re_android_decompile para descompilar com jadx
re_android_scanner para executar scanners de segurança
re_antianalysis_detect para verificar anti-adulteração

Triagem de Malware

Pergunte ao Claude: "Fazer triagem desta amostra de malware suspeita"

O Claude pode chamar:

re_malware_triage para hashes, IoCs, análise de imports e pontuação de risco
re_malware_config para extrair URLs de C2 e chaves de criptografia
re_malware_yara_gen para gerar uma regra YARA para a amostra
re_malware_sandbox para consultar VirusTotal/Hybrid Analysis

Desenvolvimento de Exploits

Pergunte ao Claude: "Construir uma cadeia ROP para chamar execve('/bin/sh') neste binário"

O Claude pode orquestrar:

re_rop_gadgets para encontrar gadgets úteis (pop rdi, pop rsi, syscall) com classificação semântica
re_rop_chain para construir automaticamente uma cadeia execve com configuração adequada de registradores
re_libc_offsets para extrair offsets de system/execve/binsh da libc
re_aslr_defeat para calcular endereços base a partir de ponteiros vazados
re_heap_chunk para analisar chunks do malloc e classificação de bins para exploits de heap
re_heap_technique para obter modelos para House of Force, Tcache Poisoning, etc.

Desempenho e Limitações

O Que Funciona Bem Sem Dependências Opcionais

Apenas com a instalação principal (pip install -e .), você tem funcionalidade completa para:

Análise de cabeçalhos e parsing de PE/ELF/Mach-O
Desmontagem multi-arquitetura (via Capstone)
Extração e classificação de strings
Análise de entropia de Shannon e detecção de empacotamento
Escaneamento com regras YARA
Aplicação de patches em binários
Hex dump e busca de padrões
Hash de arquivos (MD5, SHA-1, SHA-256)
Encontrar gadgets ROP e construção de cadeias (via Capstone)
Ferramentas de exploração de heap (análise de chunks, classificação de bins, safe-linking)
Ferramentas de banco de dados libc (extração de símbolos, cálculo de offsets, quebra de ASLR)
Cálculo de payloads de format string
Desofuscação XOR/ROT/Base64
Detecção de padrões anti-análise

O Que Precisa de Ferramentas Externas

Estas ferramentas geram erros claros de "ferramenta não encontrada" quando os backends estão ausentes:

Descompilação requer Ghidra, RetDec ou Binary Ninja
Análise dinâmica requer GDB, LLDB ou Frida
Engenharia reversa de Android requer jadx, apktool e ADB
Execução simbólica requer angr (dependência grande, ~2 GB)
Análise de rede requer tshark ou scapy
Extração de firmware requer binwalk

Expectativas de Desempenho

Inicialização: ~1 segundo (verifica as ferramentas disponíveis no sistema via shutil.which e importlib.util.find_spec)
Análise estática: Sub-segundo para a maioria das operações em arquivos abaixo de 100 MB
Desmontagem: Capstone desmonta ~1 MB/s; radare2 adiciona a sobrecarga da análise completa
Chamadas de subprocessos: Cada invocação de ferramenta externa tem ~50-200 ms de sobrecarga devido à criação do processo
Cache: O cache de resultados é opt-in explícito por ferramenta; a menos que ativado, as chamadas são executadas do zero
Limite de taxa: 120 requisições/minuto globais, 30/minuto por ferramenta (configurável)

Limitações Conhecidas

Sem suporte nativo a Windows. Projetado para Linux. macOS funciona para a maioria das ferramentas. Windows requer WSL2.
Somente transporte stdio. Não há servidor HTTP/SSE. O Revula deve ser executado na mesma máquina que sua IDE (ou enviado via SSH/Docker). Esta é uma decisão de design deliberada por segurança: MCP sobre stdio é mais simples e evita expor um socket de rede.
Sem GUI. Este é um servidor MCP headless. Use Claude Desktop, VS Code Copilot, Cursor ou outro cliente MCP para a interface.
Análise de binários grandes. Arquivos acima de 500 MB podem atingir o limite de memória padrão (512 MB). Aumente via REVULA_MAX_MEMORY_MB.
Tamanho da instalação do angr. A dependência opcional angr tem ~2 GB e leva vários minutos para instalar.
Acoplamento de versão do Frida. As versões do cliente e do servidor Frida devem corresponder exatamente. Use scripts/utils/download_frida_server.py para obter a versão correta.
Design de usuário único. O servidor lida com um cliente MCP por vez via stdio. Não há isolamento multi-tenant. Cada IDE/cliente inicia seu próprio processo de servidor.
Integração com IDA Pro. Requer IDA Pro com o plugin REST API. Não incluído.

Solução de Problemas

O Servidor Não 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

Ferramenta Diz "não 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.

Erros de Validação de Caminho

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

Adicione o diretório à sua configuração:

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

Como alternativa, defina o valor via variável de ambiente. O servidor usará o allowed_dirs do arquivo de configuração como fallback.

Limite de Taxa Excedido

Error: Rate limit exceeded for tool re_disasm

Os limites de taxa são inicializados atualmente a partir dos padrões do código (global_rpm=120, per_tool_rpm=30, burst_size=10). Se você precisar de limites diferentes, ajuste RateLimitConfig(...) em src/revula/server.py e reinicie.

Problemas de Conexão com Frida

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

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

Testes Falhando

# 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 Não 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

Contribuindo

Adicionar uma Nova Ferramenta

Use o gerador de scaffold:

python scripts/dev/add_tool.py

Isso cria o arquivo da ferramenta, registra-o na categoria __init__.py e gera um stub de teste.

Qualidade de 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

Diretrizes

Cada handler de ferramenta é async e retorna list[dict] (blocos de conteúdo MCP).
Todas as chamadas de subprocesso passam por sandbox.safe_subprocess().
Todos os caminhos de arquivo devem ser validados via sandbox.validate_path().
Sem shell=True, sem eval(), sem interpolação de f-string em código de subprocesso.
Cada nova ferramenta precisa de pelo menos um teste.

Licença

Publicado sob a GNU General Public License. Consulte LICENSE para detalhes.