president-xd/revula
GitHub: president-xd/revula
基于 MCP 协议的生产级逆向工程自动化服务器，允许 AI 模型直接调用 Ghidra、Frida 等工具进行二进制分析与漏洞挖掘。
Stars: 2 | Forks: 0
# revula
**用于通用逆向工程自动化的生产级 MCP 服务器。**
将 Claude Desktop、兼容 MCP 的 IDE 或自定义工具连接到完整的逆向工程后端。一个服务器，涵盖所有 RE 工具，通过 [Model Context Protocol](https://modelcontextprotocol.io/) 进行编排。
## 目录
- [功能特性](#features)
- [快速开始](#quick-start)
- [IDE 与客户端设置](#ide--client-setup)
- [连接方式（重要）](#how-it-connects-important)
- [Claude Desktop](#1-claude-desktop)
- [Claude Code (CLI)](#2-claude-code-cli)
- [VS Code (GitHub Copilot)](#3-vs-code-github-copilot)
- [Cursor](#4-cursor)
- [Windsurf (Codeium)](#5-windsurf-codeium)
- [Continue.dev](#6-continuedev)
- [Zed](#7-zed)
- [自定义/其他客户端](#8-custom--other-clients)
- [通用设置脚本](#universal-setup-script)
- [配置](#configuration)
- [工具可用性](#tool-availability)
- [架构](#architecture)
- [安全模型](#security-model)
- [测试](#testing)
- [脚本与自动化](#scripts--automation)
- [使用示例](#usage-examples)
- [性能与限制](#performance--limitations)
- [故障排除](#troubleshooting)
- [贡献](#contributing)
- [许可证](#license)
## 功能特性
### 静态分析（8 个工具）
- **二进制解析：** 通过 LIEF 解析 PE/ELF/Mach-O，包含哈希计算和可疑指标检测
- **反汇编：** 多后端支持，包括 Capstone（始终可用）、radare2 和 objdump，支持 x86/x64/ARM/MIPS/RISC-V
- **字符串提取：** FLOSS 集成、正则回退、17 种分类器模式（URL、IP、加密、注册表键）
- **熵分析：** 带滑动窗口的香农熵、分段分析以及加壳检测
- **符号提取：** DWARF、PDB、LIEF 通用；针对 stripped 二进制文件的函数序言扫描
- **YARA 扫描：** 内联规则、文件/目录规则以及社区规则支持
- **Capa 集成：** ATT&CK 映射、MBC 行为、能力枚举
- **反编译：** Ghidra（无头模式）、RetDec、Binary Ninja，带缓存
### 动态分析（29 个工具）
- **GDB 适配器：** 完整的 GDB/MI 协议，支持断点、单步执行、寄存器、内存、回溯和堆检查
- **LLDB 适配器：** 用于 macOS/Linux 调试的原生 SB API 集成
- **Frida 适配器：** Spawn/attach、脚本注入、函数拦截、内存扫描/转储以及 RPC 导出
- **代码覆盖率：** DynamoRIO drcov、Frida Stalker 块追踪以及覆盖率分析
### Android RE（24 个工具）
- **APK 解析：** Manifest 提取、权限分析、组件枚举和资源检查
- **DEX 分析：** 类/方法列表、字节码统计和字符串提取
- **反编译：** jadx/apktool 集成、smali 反汇编/汇编/修补
- **原生二进制分析：** 带 JNI 检测的 ARM/AArch64 .so 分析
- **设备交互：** 包含 12 个操作的 ADB 桥接（logcat、install、shell、dumpsys、screenshot）
- **Frida for Android：** Root 绕过、加密 hook、SSL pinning 绕过、API 追踪和内存转储
- **流量拦截：** tcpdump/mitmproxy 集成以及 SSL 密钥提取
- **重打包与签名：** 带 smali 补丁、zipalign + apksigner 的 APK 重建
- **安全扫描器：** MobSF、Quark-Engine、Semgrep 以及 manifest 漏洞检测
### 跨平台 RE 工具（7 个工具）
- **Rizin/r2：** 包含 13 个操作的自动化分析和二进制差异比对
- **GDB Enhanced：** 堆分析、ROP gadget 查找、exploit 辅助（pattern create/find、checksec）
- **QEMU：** 用户模式仿真（4 个操作）和全系统仿真（5 个操作）
### 漏洞利用开发（2 个工具）
- **Shellcode：** 生成、编码、坏字符分析、提取和仿真测试
- **格式化字符串：** 偏移计算、写入 payload 生成、GOT 覆盖和地址泄露
### 反分析（2 个工具）
- **检测：** 扫描反调试、反虚拟机、反篡改和加壳指标
- **绕过生成：** 针对 ptrace、IsDebuggerPresent、时序和 VM 检查的 Frida/GDB/patch/LD_PRELOAD 脚本
### 恶意软件分析（4 个工具）
- **分类：** 多重哈希、IoC 提取、可疑导入评分和风险评估
- **沙箱查询：** VirusTotal、Hybrid Analysis 和 MalwareBazaar API 集成
- **YARA 生成：** 从二进制工件自动生成 YARA 规则
- **配置提取：** C2 URL、IP、域名、加密密钥和互斥体
### 固件 RE（3 个工具）
- **提取：** binwalk 扫描/提取、熵分析和文件系统识别
- **漏洞扫描：** 硬编码凭据、已知 CVE、不安全函数和弱加密
- **基址检测：** 用于固件基址恢复的字符串引用分析
### 协议 RE（3 个工具）
- **PCAP 分析：** 基于 tshark，包含 8 个操作（summary、flows、DNS、HTTP、TLS、filter、export、IoC）
- **协议剖析：** 二进制结构推断、字段边界检测和模式分析
- **协议模糊测试：** 基于变异、边界测试、字段特定和模板模糊测试
### 脱壳（4 个工具）
- **加壳检测：** UPX、Themida、VMProtect、ASPack、PECompact、MPRESS 等
- **UPX 脱壳：** 带自动备份的静态脱壳
- **动态脱壳：** 基于 Frida 的内存转储，带 OEP 检测
- **PE 重建：** 修复内存转储后的节对齐、导入表和入口点
### 反混淆（3 个工具）
- **字符串反混淆：** XOR 暴力破解、ROT 变体、Base64、RC4 和栈字符串重建
- **控制流平坦化检测：** OLLVM 风格的 CFF 模式识别
- **不透明谓词检测：** 恒真/恒假分支识别
### 符号执行（4 个工具）
- **angr 集成：** 路径探索、约束求解、CFG 生成和漏洞扫描
- **Triton DSE：** 带具体和符号状态的动态符号执行
### 二进制格式专项（4 个工具）
- **APK/DEX：** Android 分析，包括 manifest、权限、原生库和 DEX 解析
- **.NET IL：** 程序集元数据、类型/方法列表和 IL 反汇编
- **Java Class：** 类文件解析、javap 集成和字节码反汇编
- **WebAssembly：** WASM 段解析、导入/导出提取和反汇编
### 实用工具（8 个工具）
- **十六进制工具：** 十六进制转储、模式搜索（IDA 风格通配符）和二进制差异比对
- **加密：** 哈希（MD5/SHA/TLSH/ssdeep）、XOR 分析和加密常量扫描
- **修补：** 带备份和 NOP-sled 支持的二进制修补
- **网络：** 带协议统计、DNS 提取和 C2 信标检测的 PCAP 分析
### 管理（2 个工具）
- **服务器状态：** 版本、工具数量、缓存统计、速率限制统计和可用工具
- **缓存管理：** 查看统计、清除缓存和使特定条目失效
## 快速开始
### 前置条件
- Python 3.11 或更高版本
- 推荐使用 Linux（支持 macOS 和 WSL2）
- `pip`（或用于隔离安装的 `uv` / `pipx`）
### 安装
```
# 克隆
git clone https://github.com/revula/revula.git
cd revula
# 选项 1：自动安装（推荐）
bash scripts/install/install_all.sh
# 选项 2：手动安装
pip install -e .
# 选项 3：安装所有可选依赖项
pip install -e ".[full]"
# 验证安装
python scripts/test/validate_install.py
```
自动安装程序处理 Python 版本检查、虚拟环境创建、依赖项安装、外部工具检测和配置文件生成。
### 验证可用内容
```
python -c "from revula.config import get_config, format_availability_report; print(format_availability_report(get_config()))"
```
这将打印一个表格，显示系统上检测到的外部工具和 Python 模块。
## IDE 与客户端设置
### 连接方式（重要）
**Revula 仅使用 stdio 传输。** 服务器从 stdin 读取 JSON-RPC 并写入 stdout。下面列出的每个 MCP 客户端都将 revula 作为本地子进程启动。没有 HTTP 服务器，没有 SSE 端点，也没有远程连接。
**这对您意味着：**
- Revula 必须安装在您的 IDE/客户端运行的**同一台机器**上。
- 如果您使用远程服务器或 Docker，则必须在同一环境中运行客户端和 revula（或使用 SSH 管道；请参阅 [自定义/其他客户端](#8-custom--other-clients)）。
- 下面的每个客户端都使用相同的 `revula` 命令。唯一的区别是配置放置的_位置_。
### 开始之前
确保已安装 revula 且命令有效：
```
# 应该打印 MCP protocol handshake（Ctrl+C 退出）
revula
# 如果您安装在 venv 中，请先激活它：
source /path/to/venv/bin/activate
revula
# 或者使用完整路径：
/path/to/venv/bin/revula
```
如果 `revula` 不在您的 PATH 中，请在下面的所有配置中使用完整路径。
### 1. Claude Desktop
**状态：** 完全支持。这是主要客户端。
**配置文件位置：**
| 平台 | 路径 |
|----------|------|
| 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//AppData/Roaming/Claude/claude_desktop_config.json` |
**选项 A：自动设置（推荐）**
```
python scripts/setup/setup_claude_desktop.py
```
这会自动检测您的操作系统，找到配置文件，并合并 revula 条目。它会先创建备份。
**选项 B：手动设置**
添加到您的 `claude_desktop_config.json`：
```
{
"mcpServers": {
"revula": {
"command": "revula",
"args": []
}
}
}
```
如果 revula 在 virtualenv 中：
```
{
"mcpServers": {
"revula": {
"command": "/home/you/venvs/revula/bin/revula",
"args": []
}
}
}
```
如果使用 `uvx`（零安装）：
```
{
"mcpServers": {
"revula": {
"command": "uvx",
"args": ["revula"]
}
}
}
```
**编辑后：** 退出并重新打开 Claude Desktop。检查 MCP 工具图标以确认 107 个工具可用。
### 2. Claude Code (CLI)
**状态：** 完全支持。
**选项 A：CLI 命令（推荐）**
```
claude mcp add revula -- revula
```
Claude Code 将在需要时作为子进程启动 revula。
**选项 B：手动配置**
编辑 `~/.claude.json`（或 `~/.claude/settings.json`，取决于版本）：
```
{
"mcpServers": {
"revula": {
"command": "revula",
"args": []
}
}
}
```
### 3. VS Code (GitHub Copilot)
**状态：** 支持。需要带有 MCP 支持的 GitHub Copilot 扩展（VS Code 1.99+）。
**重要：** VS Code 中的 MCP 支持通过 GitHub Copilot Chat 扩展提供。请确保您拥有：
- VS Code 1.99 或更高版本
- 已安装并激活 GitHub Copilot 扩展
- 在设置中启用 MCP：`"chat.mcp.enabled": true`
**选项 A：工作区配置（已包含在此仓库中）**
此仓库随附 `.vscode/mcp.json`：
```
{
"servers": {
"revula": {
"command": "revula",
"args": [],
"env": {}
}
}
}
```
只需在 VS Code 中打开此项目，Copilot 就会自动发现 MCP 服务器。
**选项 B：用户级配置（全局，所有项目）**
打开 VS Code 设置（`Ctrl+,`）→ 搜索 "mcp" → 编辑 `settings.json`：
```
{
"chat.mcp.enabled": true,
"mcp": {
"servers": {
"revula": {
"command": "revula",
"args": [],
"env": {}
}
}
}
}
```
**选项 C：在任何项目中创建 `.vscode/mcp.json`**
复制此仓库中的文件或手动创建：
```
mkdir -p .vscode
cat > .vscode/mcp.json << 'EOF'
{
"servers": {
"revula": {
"command": "revula",
"args": [],
"env": {}
}
}
}
EOF
```
**编辑后：** 重新加载 VS Code 窗口（`Ctrl+Shift+P` → "Developer: Reload Window"）。MCP 工具应出现在 Copilot Chat 中。
### 4. Cursor
**状态：** 支持。Cursor 具有内置的 MCP 支持。
**配置文件：** `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（每个项目）。
此仓库随附 `.cursor/mcp.json` 用于每个项目的使用。
**选项 A：每个项目（已包含）**
此仓库中的 `.cursor/mcp.json`：
```
{
"mcpServers": {
"revula": {
"command": "revula",
"args": []
}
}
}
```
**选项 B：全局配置**
```
mkdir -p ~/.cursor
cat > ~/.cursor/mcp.json << 'EOF'
{
"mcpServers": {
"revula": {
"command": "revula",
"args": []
}
}
}
EOF
```
**编辑后：**启 Cursor。检查 Settings → MCP 以验证 revula 是否出现。
### 5. Windsurf (Codeium)
**状态：** 支持。Windsurf Cascade 支持 MCP 服务器。
**配置文件：** `~/.codeium/windsurf/mcp_config.json`
```
mkdir -p ~/.codeium/windsurf
cat > ~/.codeium/windsurf/mcp_config.json << 'EOF'
{
"mcpServers": {
"revula": {
"command": "revula",
"args": []
}
}
}
EOF
```
**编辑后：** 重启 Windsurf。Cascade 面板应显示 revula 工具。
### 6. Continue.dev
**状态：** 支持。最新版本的 Continue 支持 MCP。
**配置文件：** `~/.continue/config.json`
添加到您现有的 `config.json`：
```
{
"mcpServers": [
{
"name": "revula",
"command": "revula",
"args": []
}
]
}
```
如果您使用 `config.yaml`：
```
mcpServers:
- name: revula
command: revula
args: []
```
**编辑后：** 重启您的 IDE。Continue 应检测到 MCP 服务器。
### 7. Zed
**状态：** 支持。Zed 通过上下文服务器提供原生 MCP 支持。
**配置文件：** `~/.config/zed/settings.json` (Linux/macOS)
添加到您的 `settings.json`：
```
{
"context_servers": {
"revula": {
"command": "revula",
"args": []
}
}
}
```
**编辑后：** 重启 Zed。上下文服务器应出现在 Assistant 面板中。
### 8. 自定义/其他客户端
**任何支持 stdio 传输的 MCP 客户端都可以与 revula 一起使用。** 该协议是 stdin/stdout 上的标准 JSON-RPC。
**直接调用：**
```
# 启动服务器（从 stdin 读取，写入 stdout，日志输出到 stderr）
revula
```
**通过 SSH（远程机器）：**
```
# 在远程机器上运行 revula，并通过 SSH 管道传输 stdio
ssh user@remote-host revula
```
**在 Docker 中：**
```
FROM python:3.11-slim
RUN pip install revula
# 入口点使用 stdio MCP
ENTRYPOINT ["revula"]
```
```
docker build -t revula .
# 在客户端配置中使用 docker 作为命令：
# "command": "docker", "args": ["run", "-i", "--rm", "revula"]
```
**Python 客户端（编程方式）：**
```
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())
```
### 通用设置脚本
使用一个命令配置任何客户端：
```
# 交互式：从菜单中选择一个客户端
python scripts/setup/setup_ide.py
# 配置特定客户端
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
# 一次性配置所有检测到的客户端
python scripts/setup/setup_ide.py --all
# 打印所有配置而不写入文件（先查看）
python scripts/setup/setup_ide.py --print-only
# 覆盖命令（例如，venv 的完整路径）
python scripts/setup/setup_ide.py --client cursor --command "/home/you/venv/bin/revula"
```
该脚本自动检测如何运行 revula（PATH、uvx 或 python -m），在写入前创建备份，并合并到现有配置中。
## 配置
### 配置文件
创建 `~/.revula/config.toml`（或使用交互式生成器）：
```
python scripts/setup/setup_config_toml.py
```
示例配置：
```
[tools]
ghidra_install = "/opt/ghidra"
r2_path = "/usr/bin/radare2"
ida_path = "/opt/idapro"
jadx_path = "/usr/local/bin/jadx"
[security]
max_memory_mb = 512
timeout_seconds = 60
allowed_dirs = ["/home/user/samples", "/tmp/analysis"]
[cache]
dir = "~/.revula/cache"
max_entries = 256
ttl_seconds = 600
[rate_limit]
global_rpm = 120
per_tool_rpm = 30
```
### 环境变量
环境变量覆盖配置文件值：
```
export GHIDRA_INSTALL=/opt/ghidra # Ghidra installation path
export REVULA_TIMEOUT=120 # Subprocess timeout (seconds)
export REVULA_MAX_MEMORY=1024 # Memory limit (MB)
export VT_API_KEY=your-key-here # VirusTotal API key
export HA_API_KEY=your-key-here # Hybrid Analysis API key
```
## 工具可用性
revula 会优雅地降级。依赖缺失后端的工具会返回清晰的错误消息而不是崩溃。以下是每个类别所需的条件：
| 类别 | 始终可用 | 需要外部工具 | 需要 Python 模块 |
|----------|-----------------|--------------------|--------------------|
| **Static** | PE/ELF 解析、熵、字符串 | `objdump`, `radare2`, `ghidra`, `retdec`, `floss`, `capa` | `capstone` ✓, `lief` ✓, `pefile` ✓, `yara` ✓ |
| **Dynamic** | | `gdb`, `lldb` | `frida` |
| **Android** | APK manifest/DEX 解析（通过 zipfile） | `jadx`, `apktool`, `adb`, `zipalign`, `apksigner`, `tcpdump` | `frida`, `quark-engine` |
| **Platform** | | `rizin`, `radare2`, `gdb`, `qemu-user`, `qemu-system-*` | `r2pipe`, `binaryninja` |
| **Exploit** | 格式化字符串计算器 | | `pwntools`, `keystone-engine` |
| **Anti-Analysis** | 模式扫描（通过 `lief` + `capstone`） | | |
| **Malware** | 文件哈希、IoC 提取、风险评分 | | `yara` ✓, `ssdeep`, `tlsh` |
| **Firmware** | | `binwalk`, `sasquatch` | |
| **Protocol** | 二进制协议剖析、模糊测试 | `tshark` | `scapy` |
| **Unpacking** | 加壳签名检测 | `upx` | `frida` |
| **Deobfuscation** | XOR/ROT/Base64 反混淆 | | `capstone` ✓ |
| **Symbolic** | | | `angr`, `triton` |
| **Binary Formats** | | `aapt`, `javap`, `monodis`, `wasm2wat` | |
| **Utilities** | 十六进制转储、二进制差异比对、修补 | `tshark` | `scapy`, `ssdeep`, `tlsh` |
✓ = 包含在核心依赖项中（始终安装）。
### 安装可选依赖项
```
# 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]"
```
### 安装外部工具（Debian/Ubuntu/Kali）
```
# Core analysis
sudo apt install gdb binutils radare2 binwalk upx-ucl
# Android RE
sudo apt install apktool jadx android-sdk adb zipalign apksigner
# Network
sudo apt install tshark
# Ghidra：从 https://ghidra-sre.org/ 下载
export GHIDRA_INSTALL=/opt/ghidra
```
## 架构
```
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/ # 2 files: shellcode generation, format string exploitation
├── 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
```
### 工作原理
1. **启动。** `server.py` 加载 `config.py`，后者探测系统的外部工具（通过 `shutil.which`）和 Python 模块（通过 `importlib.util.find_spec`）。结果缓存在 `ServerConfig` 单例中。
2. **工具注册。** 每个工具文件使用 `@TOOL_REGISTRY.register()` 声明其名称、描述、JSON Schema 和异步处理程序。工具在导入时自行注册。
3. **请求调度。** 当 `tools/call` 请求到达时，服务器在 `TOOL_REGISTRY` 中查找处理程序，根据 JSON Schema 验证参数，检查速率限制，检查结果缓存，并调度到处理程序。
4. **子进程执行。** 所有外部工具调用都通过 `sandbox.safe_subprocess()` 进行，该函数强制执行 `shell=False`，设置 `RLIMIT_AS` 和 `RLIMIT_CPU`，验证路径，并捕获 stdout/stderr。
5. **结果缓存。** 确定性操作（反汇编、解析）以可配置的 TTL 进行缓存。变更操作（修补、Frida 注入）自动绕过缓存。
6. **会话管理。** 长期存在的调试器和 Frida 会话由 `SessionManager` 跟踪，在 30 分钟空闲后自动清理。
### 基础设施组件
| 组件 | 用途 | 关键细节 |
|-----------|---------|------------|
| **ResultCache** | 避免冗余的子进程调用 | LRU，256 个条目，10 分钟 TTL |
| **RateLimiter** | 防止资源耗尽 | 令牌桶，120 全局 / 30 每工具 RPM |
| **ToolRegistry** | 基于装饰器的工具调度 | 处理程序调用前的 JSON Schema 验证 |
| **SessionManager** | 调试器/Frida 持久化 | 30 分钟空闲后自动清理 |
| **sandbox.py** | 安全执行层 | `shell=False`，RLIMIT 强制执行，路径验证 |
## 安全模型
revula 基于**用户提供的参数不可信**的原则运行。应用了以下加固措施：
### 子进程隔离
- **禁止 `shell=True`：** 每个子进程调用都使用带有显式参数列表的 `shell=False`。这由 CI 测试（`test_no_shell_true`）强制执行，该测试扫描每个源文件。
- **禁止 `eval()` / `exec()`：** 不对用户输入进行动态代码评估。
- **禁止 f-string 注入：** 用户提供的值永远不会插值到 `python3 -c` 代码字符串中。值通过 `sys.argv`、`stdin` 或环境变量传递。由 `test_no_fstring_in_subprocess_python_code` 强制执行。
- **JavaScript 转义：** 所有插入 Frida JavaScript 字符串的用户控制值都通过 `_js_escape()` 传递，该函数转义反斜杠、引号、换行符和其他注入向量。
- **资源限制：** 每个子进程通过 `resource.setrlimit()` 获得 `RLIMIT_AS`（默认 512 MB）和 `RLIMIT_CPU`（默认 60 秒）。
- **超时强制执行：** `asyncio.wait_for()` 包装所有子进程调用。
### 路径验证
- **失败即关闭：** 当未配置 `allowed_dirs` 时，`validate_path()` 拒绝所有路径（回退到 `get_config().security.allowed_dirs`）。它不会静默通过。
- **遍历受阻：** 在 `os.path.realpath()` 解析后拒绝 `..` 组件。
- **需要绝对路径：** 拒绝相对路径。
- **到处验证：** 所有接受文件的工具处理程序在任何文件 I/O 之前都会调用 `validate_path()`。
### Frida 加固
- **脚本大小限制：** Frida 脚本上限为 1 MB，以防止内存耗尽。
- **内存转储限制：** 内存转储上限为 100 MB。
- **JS 注入预防：** 类名、方法名、模块名和其他用户提供的值在插入 JavaScript 模板之前进行转义。
### 临时文件
- **禁止 `tempfile.mktemp()`：** 所有临时文件使用 `tempfile.NamedTemporaryFile()` 或 `tempfile.mkdtemp()` 以防止 TOCTOU 竞争条件。
- **无硬编码 `/tmp` 路径：** 所有临时路径使用 `tempfile` 模块。
### 速率限制与缓存
- **全局限制：** 每分钟 120 个请求（可配置）。
- **每工具限制：** 每分钟 30 个请求（可配置）。
- **缓存 TTL：** 只读结果 10 分钟 TTL，256 条目 LRU。
- **会话 TTL：** 空闲会话在 30 分钟后自动清理。
## 测试
```
# 运行所有 161 个测试
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_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
```
### 测试类别（161 个测试）
| 套件 | 测试 | 覆盖范围 |
|-------|-------|--------|
| `test_infra.py` | 缓存、速率限制器、会话管理器 | 基础设施正确性 |
| `test_core.py` | 配置加载、沙箱、工具注册表 | 核心模块行为 |
| `test_static.py` | 熵、十六进制、加密、字符串、符号 | 静态分析工具 |
| `test_android.py` | APK 解析、DEX、设备、Frida Android | Android 模块测试 |
| `test_tools_new.py` | Exploit、Malware、Firmware、Protocol、antianalysis、platform、deobfuscation、symbolic、unpacking、binary formats | 所有剩余工具类别 |
| `test_security.py` | `shell=True` 扫描、注入扫描、`mktemp` 扫描、硬编码 `/tmp` 扫描、路径验证、JS 转义、shellcode 验证 | 安全回归测试 |
### 安全测试
`test_security.py` 中的 `TestVulnerabilityHardeningV3` 套件强制执行：
- **无 f-string 代码注入：** 扫描所有源文件中包含 f-string 的 `"-c"` 参数。
- **无 `tempfile.mktemp()`：** 防止 TOCTOU 竞争条件。
- **无硬编码 `/tmp/` 路径：** 强制使用 `tempfile` 模块。
- **失败即关闭路径验证：** 验证当 `allowed_dirs` 为空时 `validate_path()` 拒绝路径。
- **Frida JS 转义：** 验证 `_js_escape()` 阻止注入 payload。
- **Shellcode 十六进制验证：** 验证非十六进制输入被拒绝，而不是传递给子进程。
## 脚本与自动化
所有脚本都在 `scripts/` 中并已完全实现：
### 安装
| 脚本 | 用途 |
|--------|---------|
| `scripts/install/install_all.sh` | 主安装程序：Python 检查、venv、deps、外部工具、配置 |
| `scripts/install/install_verify.sh` | 安装后验证：检查所有依赖项和路径 |
### 设置
| 脚本 | 用途 |
|--------|---------|
| `scripts/setup/setup_ide.py` | Claude Desktop、VS Code、Cursor、Windsurf、Zed 和 Continue 的通用 IDE/客户端配置器 |
| `scripts/setup/setup_claude_desktop.py` | Claude Desktop 专用自动配置器（旧版，仍可运行） |
| `scripts/setup/setup_config_toml.py` | 交互式 config.toml 生成器 |
| `scripts/setup/setup_android_device.sh` | 准备用于 RE 的 Android 设备（root、frida-server、certs） |
### 测试与开发
| 脚本 | 用途 |
|--------|---------|
| `scripts/test/run_tests.sh` | 运行带覆盖率的完整测试套件 |
| `scripts/test/validate_install.py` | 全面的安装验证器（526 行） |
| `scripts/dev/add_tool.py` | 脚手架一个新的工具模块（创建文件、注册、添加测试） |
| `scripts/dev/lint_and_type.sh` | 运行 ruff + mypy |
| `scripts/utils/download_frida_server.py` | 为目标架构下载 frida-server |
## 使用示例
### 静态分析：分析 PE 二进制文件
询问 Claude：*"Analyze this binary for me: /home/user/samples/malware.exe"*
在幕后，Claude 可以调用：
1. `re_pe_elf` 解析 PE 头、节、导入和导出
2. `re_strings` 提取和分类字符串（URL、IP、加密常量）
3. `re_entropy` 检查加壳（高熵节）
. `re_yara_scan` 使用 YARA 规则进行扫描
5. `re_capa_scan` 映射到 ATT&CK 技术
### 动态分析：使用 GDB 调试
询问 Claude：*"Debug /home/user/crackme and find the password check"*
Claude 可以编排：
1. `re_gdb`，操作为 `start` 以在 GDB 下启动二进制文件
2. `re_disasm` 反汇编关键函数
3. `re_gdb`，操作为 `breakpoint` 以在比较指令处设置断点
4. `re_gdb`，操作为 `continue` 和 `registers` 以运行并检查状态
### Android：逆向 APK
询问 Claude：*"Analyze this APK for security issues: /home/user/app.apk"*
Claude 可以调用：
1. `re_apk_parse` 提取 manifest、权限和组件
2. `re_dex_analyze` 列出类并查找可疑方法
3. `re_android_decompile` 使用 jadx 反编译
4. `re_android_scanner` 运行安全扫描器
5. `re_antianalysis_detect` 检查反篡改
### 恶意软件分类
询问 Claude：*"Triage this suspected malware sample"*
Claude 可以调用：
1. `re_malware_triage` 进行哈希、IoC、导入分析和风险评分
2. `re_malware_config` 提取 C2 URL 和加密密钥
3. `re_malware_yara_gen` 为样本生成 YARA 规则
4. `re_malware_sandbox` 查询 VirusTotal/Hybrid Analysis
## 性能与限制
### 在没有可选依赖项的情况下运行良好的功能
仅使用核心安装（`pip install -e .`），您将获得以下完整功能：
- PE/ELF/Mach-O 解析和头分析
- 多架构反汇编（通过 Capstone）
- 字符串提取和分类
- 香农熵分析和加壳检测
- YARA 规则扫描
- 二进制修补
- 十六进制转储和模式搜索
- 文件哈希（MD5、SHA-1、SHA-256）
- 格式化字符串 payload 计算
- XOR/ROT/Base64 反混淆
- 反分析模式检测
### 需要外部工具的功能
当后端缺失时，这些工具会产生清晰的“tool not found”错误：
- **反编译** 需要 Ghidra、RetDec 或 Binary Ninja
- **动态分析** 需要 GDB、LLDB 或 Frida
- **Android RE** 需要 jadx、apktool 和 ADB
- **符号执行** 需要 angr（大型依赖项，约 2 GB）
- **网络分析** 需要 tshark 或 scapy
- **固件提取** 需要 binwalk
### 性能预期
- **启动：** 约 1 秒（通过 `shutil.which` 和 `importlib.util.find_spec` 探测系统可用工具）
- **静态分析：** 对于 100 MB 以下的大多数操作，亚秒级完成
- **反汇编：** Capstone 反汇编速度约 1 MB/s；radare2 增加完整的分析开销
- **子进程调用：** 每次外部工具调用因进程生成有约 50-200 ms 开销
- **缓存：** 对确定性工具（反汇编、解析）的重复调用从缓存瞬间返回
- **速率限制：** 120 请求/分钟（全局），30/分钟（每工具）（可配置）
### 已知限制
1. **无 Windows 原生支持。** 为 Linux 设计。macOS 适用于大多数工具。Windows 需要 WSL2。
2. **仅 stdio 传输。** 没有 HTTP/SSE 服务器。Revula 必须在您的 IDE 所在的同一台机器上运行（或通过 SSH/Docker 管道传输）。这是出于安全的故意设计选择：基于 stdio 的 MCP 更简单，避免了暴露网络套接字。
3. **无 GUI。** 这是一个无头 MCP 服务器。使用 Claude Desktop、VS Code Copilot、Cursor 或其他 MCP 客户端作为界面。
4. **大型二进制分析。** 超过 500 MB 的文件可能会达到默认内存限制（512 MB）。通过 `REVULA_MAX_MEMORY` 增加。
5. **angr 安装大小。** `angr` 可选依赖项约 2 GB，需要几分钟安装。
6. **Frida 版本耦合。** Frida 客户端和服务器版本必须完全匹配。使用 `scripts/utils/download_frida_server.py` 获取正确的版本。
7. **单用户设计。** 服务器通过 stdio 一次处理一个 MCP 客户端。没有多租户隔离。每个 IDE/客户端生成自己的服务器进程。
8. **IDA Pro 集成。** 需要带有 REST API 插件的 IDA Pro。不包含在内。
## 故障排除
### 服务器无法启动
```
# Check Python version (need 3.11+)
python --version
# Check MCP is installed
python -c "import mcp; print(mcp.__version__)"
# Run with debug logging
REVULA_LOG_LEVEL=DEBUG revula
```
### 工具提示“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.
```
### 路径验证错误
```
Error: Path /some/path is not within allowed directories
```
将目录添加到您的配置：
```
[security]
allowed_dirs = ["/home/user/samples", "/tmp/analysis", "/some/path"]
```
或者，通过环境变量设置值。服务器将使用配置文件的 `allowed_dirs` 作为回退。
### 超出速率限制
```
Error: Rate limit exceeded for tool re_disasm
```
在配置中增加限制：
```
[rate_limit]
global_rpm = 240
per_tool_rpm = 60
```
### Frida 连接问题
```
# Check Frida version match
frida --version
frida-server --version # on device
# Download matching server
python scripts/utils/download_frida_server.py --arch arm64
```
### 测试失败
```
# 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 设备
```
# Run the device setup script
bash scripts/setup/setup_android_device.sh
# Manual check
adb devices
adb shell id # should show root or shell
```
## 贡献
### 添加新工具
使用脚手架生成器：
```
python scripts/dev/add_tool.py
```
这将创建工具文件，在类别 `__init__.py` 中注册它，并生成测试存根。
### 代码质量
```
# 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
```
### 指南
- 每个工具处理程序都是 `async` 并返回 `list[dict]`（MCP 内容块）。
- 所有子进程调用都通过 `sandbox.safe_subprocess()` 进行。
- 所有文件路径必须通过 `sandbox.validate_path()` 验证。
- 禁止 `shell=True`、`eval()` 以及将 f-string 插值到子进程代码中。
- 每个新工具至少需要一个测试。
## 许可证
根据 GNU 通用公共许可证发布。有关详细信息，请参阅 [LICENSE](LICENSE)。
标签：ATT&CK映射, Capa, Capstone, Claude Desktop, Cloudflare Workers, Cursor, DAST, DeepSeek, DNS 反向解析, DWARF, ELF解析, FLARE, FLOSS, IP 地址批量处理, LIEF, MCP服务器, PDB, PE解析, radare2, VS Code, Wayback Machine, YARA, 二进制分析, 云安全监控, 云安全运维, 云资产可视化, 云资产清单, 反汇编, 后端服务, 恶意软件分析, 情报收集, 数据展示, 漏洞研究, 熵值分析, 生产级, 符号提取, 红队, 网络信息收集, 网络安全, 网络安全审计, 网络调试, 脚本检测, 自动化, 身份验证强制, 逆向工具, 逆向工程, 速率限制处理, 配置审计, 隐私保护, 静态分析