Skip to content
Back to search

revula

A fully functional and production-grade reverse engineering MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/president-xd--revula/badge.svg)](/listings/president-xd--revula)

HTML

<a href="/listings/president-xd--revula"><img src="/api/listings/president-xd--revula/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

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

Install

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

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

# Option 2: Manual install
pip install -e .

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

# Verify installation
python scripts/test/validate_install.py

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

Verify What's Available

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

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

Docker Installation (Alternative)

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

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

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

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

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

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

**Testing the Docker build:**

./scripts/docker/test.sh

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

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,170 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # revula
  2. **Production-grade MCP server for universal reverse engineering automation.**
  3. Connect Claude Desktop, MCP-compatible IDEs, or custom tooling to a broad reverse engineering backend through the [Model Context Protocol](https://modelcontextprotocol.io/).
  4. ---
  5. ## Table of Contents
  6. - [Features](#features)
  7. - [Quick Start](#quick-start)
  8. - [Docker Installation](#docker-installation-alternative)
  9. - [IDE & Client Setup](#ide--client-setup)
  10. - [How It Connects (Important)](#how-it-connects-important)
  11. - [Claude Desktop](#1-claude-desktop)
  12. - [Claude Code (CLI)](#2-claude-code-cli)
  13. - [VS Code (GitHub Copilot)](#3-vs-code-github-copilot)
  14. - [Cursor](#4-cursor)
  15. - [Windsurf (Codeium)](#5-windsurf-codeium)
  16. - [Continue.dev](#6-continuedev)
  17. - [Zed](#7-zed)
  18. - [Custom / Other Clients](#8-custom--other-clients)
  19. - [Universal Setup Script](#universal-setup-script)
  20. - [Configuration](#configuration)
  21. - [Tool Availability](#tool-availability)
  22. - [Architecture](#architecture)
  23. - [Security Model](#security-model)
  24. - [Testing](#testing)
  25. - [Scripts & Automation](#scripts--automation)
  26. - [Usage Examples](#usage-examples)
  27. - [Performance & Limitations](#performance--limitations)
  28. - [Troubleshooting](#troubleshooting)
  29. - [Contributing](#contributing)
  30. - [License](#license)
  31. ---
  32. ## Features
  33. ### Static Analysis (8 tools)
  34. - **Binary Parsing:** PE/ELF/Mach-O via LIEF with hash computation and suspicious indicator detection
  35. - **Disassembly:** Multi-backend support including Capstone (always available), radare2, and objdump for x86/x64/ARM/MIPS/RISC-V
  36. - **String Extraction:** FLOSS integration, regex fallback, 17 classifier patterns (URLs, IPs, crypto, registry keys)
  37. - **Entropy Analysis:** Shannon entropy with sliding window, per-section analysis, and packing detection
  38. - **Symbol Extraction:** DWARF, PDB, LIEF universal; function prologue scanning for stripped binaries
  39. - **YARA Scanning:** Inline rules, file/directory rules, and community rules support
  40. - **Capa Integration:** ATT&CK mapping, MBC behaviors, capability enumeration
  41. - **Decompilation:** Ghidra (headless), RetDec, Binary Ninja with caching
  42. ### Dynamic Analysis (29 tools)
  43. - **GDB Adapter:** Full GDB/MI protocol with breakpoints, stepping, registers, memory, backtrace, and heap inspection
  44. - **LLDB Adapter:** Native SB API integration for macOS/Linux debugging
  45. - **Frida Adapter:** Spawn/attach, script injection, function interception, memory scan/dump, and RPC exports
  46. - **Code Coverage:** DynamoRIO drcov, Frida Stalker block tracing, and coverage analysis
  47. ### Android RE (24 tools)
  48. - **APK Parsing:** Manifest extraction, permission analysis, component enumeration, and resource inspection
  49. - **DEX Analysis:** Class/method listing, bytecode stats, and string extraction
  50. - **Decompilation:** jadx/apktool integration, smali disassembly/assembly/patching
  51. - **Native Binary Analysis:** ARM/AArch64 .so analysis with JNI detection
  52. - **Device Interaction:** ADB bridge with 12 actions (logcat, install, shell, dumpsys, screenshot)
  53. - **Frida for Android:** Root bypass, crypto hooking, SSL pinning bypass, API tracing, and memory dump
  54. - **Traffic Interception:** tcpdump/mitmproxy integration with SSL key extraction
  55. - **Repack and Sign:** APK rebuild with smali patches, zipalign + apksigner
  56. - **Security Scanners:** MobSF, Quark-Engine, Semgrep, and manifest vulnerability detection
  57. ### Cross-Platform RE Tools (7 tools)
  58. - **Rizin/r2:** Automated analysis with 13 actions and binary diffing
  59. - **GDB Enhanced:** Heap analysis, ROP gadget finding, exploit helpers (pattern create/find, checksec)
  60. - **QEMU:** User-mode emulation (4 actions) and full system emulation (5 actions)
  61. ### Exploit Development (11 tools)
  62. - **ROP Chain Builder:** Multi-architecture gadget finding (x86/x64/ARM/ARM64) with semantic classification, automatic chain generation for execve/mprotect/syscalls, bad-char avoidance, and pwntools script generation
  63. - **Heap Exploitation:** Malloc chunk analysis, bin classification (tcache/fastbin/smallbin/largebin), fake chunk generation, safe-linking encode/decode for glibc 2.32+, and technique templates (House of Force, Tcache Poisoning, Fastbin Dup, Unsafe Unlink)
  64. - **Libc Database:** Symbol/offset extraction, libc identification from leaked addresses, ASLR defeat helpers (base calculation, GOT-to-libc, PLT-to-GOT), and one-gadget RCE finder
  65. - **Shellcode:** Generation, encoding, bad-char analysis, extraction, and emulation testing
  66. - **Format String:** Offset calculation, write payload generation, GOT overwrite, and address leaking
  67. ### Anti-Analysis (2 tools)
  68. - **Detection:** Scan for anti-debug, anti-VM, anti-tamper, and packing indicators
  69. - **Bypass Generation:** Frida/GDB/patch/LD_PRELOAD scripts for ptrace, IsDebuggerPresent, timing, and VM checks
  70. ### Malware Analysis (4 tools)
  71. - **Triage:** Multi-hash, IoC extraction, suspicious import scoring, and risk assessment
  72. - **Sandbox Queries:** VirusTotal, Hybrid Analysis, and MalwareBazaar API integration
  73. - **YARA Generation:** Auto-generate YARA rules from binary artifacts
  74. - **Config Extraction:** C2 URLs, IPs, domains, encryption keys, and mutexes
  75. ### Firmware RE (3 tools)
  76. - **Extraction:** binwalk scan/extract, entropy analysis, and filesystem identification
  77. - **Vulnerability Scanning:** Hardcoded credentials, known CVEs, unsafe functions, and weak crypto
  78. - **Base Address Detection:** String reference analysis for firmware base address recovery
  79. ### Protocol RE (3 tools)
  80. - **PCAP Analysis:** tshark-based with 8 actions (summary, flows, DNS, HTTP, TLS, filter, export, IoC)
  81. - **Protocol Dissection:** Binary structure inference, field boundary detection, and pattern analysis
  82. - **Protocol Fuzzing:** Mutation-based, boundary testing, field-specific, and template fuzzing
  83. ### Unpacking (4 tools)
  84. - **Packer Detection:** UPX, Themida, VMProtect, ASPack, PECompact, MPRESS, and more
  85. - **UPX Unpacking:** Static unpacking with automatic backup
  86. - **Dynamic Unpacking:** Frida-based memory dump with OEP detection
  87. - **PE Rebuild:** Fix section alignments, imports, and entry point after memory dump
  88. ### Deobfuscation (3 tools)
  89. - **String Deobfuscation:** XOR brute force, ROT variants, Base64, RC4, and stack string reconstruction
  90. - **Control Flow Flattening Detection:** OLLVM-style CFF pattern identification
  91. - **Opaque Predicate Detection:** Always-true/false branch identification
  92. ### Symbolic Execution (4 tools)
  93. - **angr Integration:** Path exploration, constraint solving, CFG generation, and vulnerability scanning
  94. - **Triton DSE:** Dynamic symbolic execution with concrete and symbolic state
  95. ### Binary Format Specializations (4 tools)
  96. - **APK/DEX:** Android analysis including manifest, permissions, native libs, and DEX parsing
  97. - **.NET IL:** Assembly metadata, type/method listing, and IL disassembly
  98. - **Java Class:** Class file parsing, javap integration, and bytecode disassembly
  99. - **WebAssembly:** WASM section parsing, import/export extraction, and disassembly
  100. ### Utilities (8 tools)
  101. - **Hex Tools:** Hexdump, pattern search (IDA-style wildcards), and binary diff
  102. - **Crypto:** Hashing (MD5/SHA/TLSH/ssdeep), XOR analysis, and crypto constant scanning
  103. - **Patching:** Binary patching with backup and NOP-sled support
  104. - **Network:** PCAP analysis with protocol stats, DNS extraction, and C2 beacon detection
  105. ### Admin (2 tools)
  106. - **Server Status:** Version, tool count, cache stats, rate limit stats, and available tools
  107. - **Cache Management:** View stats, clear cache, and invalidate specific entries
  108. ---
  109. ## Quick Start
  110. ### Prerequisites
  111. - Python 3.11 or later
  112. - Linux recommended (macOS and WSL2 supported)
  113. - `pip` (or `uv` / `pipx` for isolated installs)
  114. ### Install
  115. ```bash
  116. # Clone
  117. git clone https://github.com/president-xd/revula.git
  118. cd revula
  119. # Option 1: Automated install (recommended)
  120. bash scripts/install/install_all.sh
  121. # Option 2: Manual install
  122. pip install -e .
  123. # Option 3: Install with all optional dependencies
  124. pip install -e ".[full]"
  125. # Verify installation
  126. python scripts/test/validate_install.py
  127. ```
  128. The automated installer handles Python version checks, dependency installation, external tool detection, and configuration file generation.
  129. ### Verify What's Available
  130. ```bash
  131. python -c "from revula.config import get_config, format_availability_report; print(format_availability_report(get_config()))"
  132. ```
  133. This prints a table showing which external tools and Python modules are detected on your system.
  134. ### Docker Installation (Alternative)
  135. Revula can be run in Docker for an isolated, stdio-only environment with core and common optional dependencies pre-configured:
  136. ```bash
  137. # Build the Docker image
  138. docker build -t revula:latest .
  139. # Quick test
  140. docker run --rm --entrypoint python revula:latest -c "import revula; print(revula.__version__)"
  141. 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())"
  142. # Run in stdio mode (for local MCP clients)
  143. docker run -i --rm -v $(pwd)/workspace:/workspace -v revula-data:/root/.revula revula:latest
  144. # Revula transport is stdio-only (no HTTP/SSE mode)
  145. # Run it attached to your MCP client process
  146. # (for Docker usage, run your MCP client inside the same container/environment)
  147. ```
  148. **What's included in the Docker image:**
  149. - All core Python dependencies (capstone, LIEF, pefile, yara)
  150. - angr symbolic execution engine
  151. - Frida dynamic instrumentation
  152. - Ghidra headless analyzer
  153. - GDB/LLDB, radare2, rizin (+ rz-diff), binutils
  154. - ADB and Android tools (apktool, jadx, aapt, apksigner, smali/baksmali)
  155. - FLARE tools (FLOSS, capa)
  156. - RetDec, CFR, Detect-It-Easy (diec), DynamoRIO (drrun), UPX
  157. - Exploit tooling (msfvenom, one_gadget), checksec, mono tools (monodis/ikdasm), llvm-pdbutil
  158. - Network analysis tools (tcpdump, tshark, capinfos)
  159. **Testing the Docker build:**
  160. ```bash
  161. ./scripts/docker/test.sh
  162. ```
  163. For complete Docker documentation (stdio mode, volumes, compose usage, and troubleshooting), see **[DOCKER.md](DOCKER.md)**.
  164. **Note on Docker vs Native:**
  165. - Docker provides an isolated environment with core tooling pre-installed
  166. - Native installation offers better performance and direct system access
  167. - Choose based on your security and portability requirements
  168. ---
  169. ## IDE & Client Setup
  170. ### How It Connects (Important)
  171. **Revula uses stdio transport only.** The server reads JSON-RPC from stdin and writes to stdout. Every MCP client listed below launches revula as a local subprocess. There is no HTTP server, no SSE endpoint, and no remote connection.
  172. **What this means for you:**
  173. - Revula must be installed on the **same machine** where your IDE/client runs.
  174. - If you use a remote server or Docker, you must run both the client and revula inside the same environment (or use SSH piping; see [Custom / Other Clients](#8-custom--other-clients)).
  175. - Every client below uses the same `revula` command. The only difference is _where_ you put the config.
  176. ### Before You Start
  177. Make sure revula is installed and the command works:
  178. ```bash
  179. # Should print the MCP protocol handshake (Ctrl+C to exit)
  180. revula
  181. # If you installed in a venv, activate it first:
  182. source /path/to/venv/bin/activate
  183. revula
  184. # Or use the full path:
  185. /path/to/venv/bin/revula
  186. ```
  187. If `revula` is not in your PATH, use the full path in every config below.
  188. ---
  189. ### 1. Claude Desktop
  190. **Status:** Fully supported. This is the primary client.
  191. **Config file locations:**
  192. | Platform | Path |
  193. |----------|------|
  194. | Linux | `~/.config/Claude/claude_desktop_config.json` |
  195. | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
  196. | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
  197. | WSL2 | `/mnt/c/Users/<YOU>/AppData/Roaming/Claude/claude_desktop_config.json` |
  198. **Option A: Automatic setup (recommended)**
  199. ```bash
  200. python scripts/setup/setup_claude_desktop.py
  201. ```
  202. This auto-detects your OS, finds the config file, and merges the revula entry. It creates a backup first.
  203. **Option B: Manual setup**
  204. Add to your `claude_desktop_config.json`:
  205. ```json
  206. {
  207. "mcpServers": {
  208. "revula": {
  209. "command": "revula",
  210. "args": []
  211. }
  212. }
  213. }
  214. ```
  215. If revula is in a virtualenv:
  216. ```json
  217. {
  218. "mcpServers": {
  219. "revula": {
  220. "command": "/home/you/venvs/revula/bin/revula",
  221. "args": []
  222. }
  223. }
  224. }
  225. ```
  226. If using `uvx` (zero-install):
  227. ```json
  228. {
  229. "mcpServers": {
  230. "revula": {
  231. "command": "uvx",
  232. "args": ["revula"]
  233. }
  234. }
  235. }
  236. ```
  237. **After editing:** Quit and reopen Claude Desktop. Check the MCP tools icon to confirm 116 tools are available.
  238. ---
  239. ### 2. Claude Code (CLI)
  240. **Status:** Fully supported.
  241. **Option A: CLI command (recommended)**
  242. ```bash
  243. claude mcp add revula -- revula
  244. ```
  245. Claude Code will start revula as a subprocess when needed.
  246. **Option B: Manual config**
  247. Edit `~/.claude.json` (or `~/.claude/settings.json` depending on version):
  248. ```json
  249. {
  250. "mcpServers": {
  251. "revula": {
  252. "command": "revula",
  253. "args": []
  254. }
  255. }
  256. }
  257. ```
  258. ---
  259. ### 3. VS Code (GitHub Copilot)
  260. **Status:** Supported. Requires GitHub Copilot extension with MCP support (VS Code 1.99+).
  261. **Important:** MCP support in VS Code is available through the GitHub Copilot Chat extension. Make sure you have:
  262. - VS Code 1.99 or later
  263. - GitHub Copilot extension installed and active
  264. - MCP enabled in settings: `"chat.mcp.enabled": true`
  265. **Option A: Workspace config (already included in this repo)**
  266. This repo ships with `.vscode/mcp.json`:
  267. ```json
  268. {
  269. "servers": {
  270. "revula": {
  271. "command": "revula",
  272. "args": [],
  273. "env": {}
  274. }
  275. }
  276. }
  277. ```
  278. Just open this project in VS Code and Copilot will discover the MCP server automatically.
  279. **Option B: User-level config (global, all projects)**
  280. Open VS Code settings (`Ctrl+,`) → search "mcp" → edit `settings.json`:
  281. ```json
  282. {
  283. "chat.mcp.enabled": true,
  284. "mcp": {
  285. "servers": {
  286. "revula": {
  287. "command": "revula",
  288. "args": [],
  289. "env": {}
  290. }
  291. }
  292. }
  293. }
  294. ```
  295. **Option C: Create `.vscode/mcp.json` in any project**
  296. Copy the file from this repo or create it manually:
  297. ```bash
  298. mkdir -p .vscode
  299. cat > .vscode/mcp.json << 'EOF'
  300. {
  301. "servers": {
  302. "revula": {
  303. "command": "revula",
  304. "args": [],
  305. "env": {}
  306. }
  307. }
  308. }
  309. EOF
  310. ```
  311. **After editing:** Reload VS Code window (`Ctrl+Shift+P` → "Developer: Reload Window"). The MCP tools should appear in Copilot Chat.
  312. ---
  313. ### 4. Cursor
  314. **Status:** Supported. Cursor has built-in MCP support.
  315. **Config file:** `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project).
  316. This repo ships with `.cursor/mcp.json` for per-project use.
  317. **Option A: Per-project (already included)**
  318. The `.cursor/mcp.json` in this repo:
  319. ```json
  320. {
  321. "mcpServers": {
  322. "revula": {
  323. "command": "revula",
  324. "args": []
  325. }
  326. }
  327. }
  328. ```
  329. **Option B: Global config**
  330. ```bash
  331. mkdir -p ~/.cursor
  332. cat > ~/.cursor/mcp.json << 'EOF'
  333. {
  334. "mcpServers": {
  335. "revula": {
  336. "command": "revula",
  337. "args": []
  338. }
  339. }
  340. }
  341. EOF
  342. ```
  343. **After editing:** Restart Cursor. Check Settings → MCP to verify revula appears.
  344. ---
  345. ### 5. Windsurf (Codeium)
  346. **Status:** Supported. Windsurf Cascade supports MCP servers.
  347. **Config file:** `~/.codeium/windsurf/mcp_config.json`
  348. ```bash
  349. mkdir -p ~/.codeium/windsurf
  350. cat > ~/.codeium/windsurf/mcp_config.json << 'EOF'
  351. {
  352. "mcpServers": {
  353. "revula": {
  354. "command": "revula",
  355. "args": []
  356. }
  357. }
  358. }
  359. EOF
  360. ```
  361. **After editing:** Restart Windsurf. The Cascade panel should show revula tools.
  362. ---
  363. ### 6. Continue.dev
  364. **Status:** Supported. Continue has MCP support in recent versions.
  365. **Config file:** `~/.continue/config.json`
  366. Add to your existing `config.json`:
  367. ```json
  368. {
  369. "mcpServers": [
  370. {
  371. "name": "revula",
  372. "command": "revula",
  373. "args": []
  374. }
  375. ]
  376. }
  377. ```
  378. If you use `config.yaml`:
  379. ```yaml
  380. mcpServers:
  381. - name: revula
  382. command: revula
  383. args: []
  384. ```
  385. **After editing:** Restart your IDE. Continue should detect the MCP server.
  386. ---
  387. ### 7. Zed
  388. **Status:** Supported. Zed has native MCP support via context servers.
  389. **Config file:** `~/.config/zed/settings.json` (Linux/macOS)
  390. Add to your `settings.json`:
  391. ```json
  392. {
  393. "context_servers": {
  394. "revula": {
  395. "command": "revula",
  396. "args": []
  397. }
  398. }
  399. }
  400. ```
  401. **After editing:** Restart Zed. The context server should appear in the Assistant panel.
  402. ---
  403. ### 8. Custom / Other Clients
  404. **Any MCP client that supports stdio transport will work with revula.** The protocol is standard JSON-RPC over stdin/stdout.
  405. **Direct invocation:**
  406. ```bash
  407. # Start the server (reads from stdin, writes to stdout, logs to stderr)
  408. revula
  409. ```
  410. **Over SSH (remote machine):**
  411. ```bash
  412. # Run revula on a remote machine with stdio piped through SSH
  413. ssh user@remote-host revula
  414. ```
  415. **In Docker:**
  416. ```dockerfile
  417. FROM python:3.11-slim
  418. RUN pip install revula
  419. # The entrypoint speaks stdio MCP
  420. ENTRYPOINT ["revula"]
  421. ```
  422. ```bash
  423. docker build -t revula .
  424. # Use docker as the command in your client config:
  425. # "command": "docker", "args": ["run", "-i", "--rm", "revula"]
  426. ```
  427. **Python client (programmatic):**
  428. ```python
  429. import asyncio
  430. from mcp import ClientSession, StdioServerParameters
  431. from mcp.client.stdio import stdio_client
  432. async def main():
  433. server_params = StdioServerParameters(command="revula", args=[])
  434. async with stdio_client(server_params) as (read, write):
  435. async with ClientSession(read, write) as session:
  436. await session.initialize()
  437. tools = await session.list_tools()
  438. print(f"Connected: {len(tools.tools)} tools available")
  439. # Call a tool
  440. result = await session.call_tool("re_entropy", {"binary_path": "/bin/ls"})
  441. print(result)
  442. asyncio.run(main())
  443. ```
  444. ---
  445. ### Universal Setup Script
  446. Configure any client with one command:
  447. ```bash
  448. # Interactive: pick a client from the menu
  449. python scripts/setup/setup_ide.py
  450. # Configure a specific client
  451. python scripts/setup/setup_ide.py --client vscode
  452. python scripts/setup/setup_ide.py --client cursor
  453. python scripts/setup/setup_ide.py --client claude-desktop
  454. python scripts/setup/setup_ide.py --client windsurf
  455. python scripts/setup/setup_ide.py --client zed
  456. # Configure all detected clients at once
  457. python scripts/setup/setup_ide.py --all
  458. # Print all configs without writing files (review first)
  459. python scripts/setup/setup_ide.py --print-only
  460. # Override the command (e.g., full path to venv)
  461. python scripts/setup/setup_ide.py --client cursor --command "/home/you/venv/bin/revula"
  462. ```
  463. The script auto-detects how to run revula (PATH, uvx, or python -m), creates backups before writing, and merges into existing configs.
  464. ---
  465. ## Configuration
  466. ### Config File
  467. Create `~/.revula/config.toml` (or use the interactive generator):
  468. ```bash
  469. python scripts/setup/setup_config_toml.py
  470. ```
  471. Example configuration:
  472. ```toml
  473. [tools.ghidra_headless]
  474. path = "/opt/ghidra/support/analyzeHeadless"
  475. [tools.radare2]
  476. path = "/usr/bin/radare2"
  477. [tools.jadx]
  478. path = "/usr/local/bin/jadx"
  479. [tools.retdec_decompiler]
  480. path = "/usr/local/bin/retdec-decompiler"
  481. [security]
  482. max_memory_mb = 512
  483. default_timeout = 60
  484. max_timeout = 600
  485. allowed_dirs = ["/home/user/samples", "/tmp/analysis"]
  486. [rate_limit]
  487. enabled = true
  488. global_rpm = 120
  489. per_tool_rpm = 30
  490. burst_size = 10
  491. [tool_naming]
  492. namespace = "revula"
  493. include_legacy_names = false
  494. [execution]
  495. subprocess_retries = 1
  496. subprocess_retry_backoff_ms = 250
  497. ```
  498. ### Environment Variables
  499. Environment variables override config file values:
  500. ```bash
  501. export GHIDRA_HEADLESS=/opt/ghidra/support/analyzeHeadless # Ghidra headless binary
  502. export RADARE2_PATH=/usr/bin/radare2 # radare2 binary
  503. export RIZIN_PATH=/usr/local/bin/rizin # rizin binary
  504. export RETDEC_PATH=/usr/local/bin/retdec-decompiler # RetDec decompiler binary
  505. export RZ_DIFF_PATH=/usr/local/bin/rz-diff # rizin diff tool
  506. export MSFVENOM_PATH=/usr/bin/msfvenom # metasploit payload generator
  507. export REVULA_DEFAULT_TIMEOUT=120 # Subprocess timeout (seconds)
  508. export REVULA_MAX_MEMORY_MB=1024 # Memory limit (MB)
  509. export REVULA_GLOBAL_RPM=240 # Global tool-call rate limit
  510. export REVULA_PER_TOOL_RPM=60 # Per-tool rate limit
  511. export REVULA_BURST_SIZE=20 # Token bucket burst size
  512. export REVULA_TOOL_NAMESPACE=revula # Public MCP tool prefix
  513. export REVULA_INCLUDE_LEGACY_TOOL_NAMES=false # Expose deprecated re_* aliases
  514. export REVULA_SUBPROCESS_RETRIES=2 # Retry transient subprocess failures
  515. export REVULA_SUBPROCESS_RETRY_BACKOFF_MS=400 # Initial retry backoff (ms)
  516. ```
  517. ---
  518. ## Tool Availability
  519. revula degrades gracefully. Tools that depend on missing backends return clear error messages instead of crashing. Here is what each category needs:
  520. | Category | Always Available | Needs External Tool | Needs Python Module |
  521. |----------|-----------------|--------------------|--------------------|
  522. | **Static** | PE/ELF parsing, entropy, strings | `objdump`, `radare2`, `ghidra`, `retdec`, `floss`, `capa` | `capstone` ✓, `lief` ✓, `pefile` ✓, `yara` ✓ |
  523. | **Dynamic** | | `gdb`, `lldb` | `frida` |
  524. | **Android** | APK manifest/DEX parsing (via zipfile) | `jadx`, `apktool`, `adb`, `zipalign`, `apksigner`, `tcpdump` | `frida`, `quark-engine` |
  525. | **Platform** | | `rizin`, `radare2`, `gdb`, `qemu-user`, `qemu-system-*` | `r2pipe`, `binaryninja` |
  526. | **Exploit** | ROP chain builder, heap analysis, libc database, format string helpers | | `capstone` ✓, `pwntools`, `keystone-engine` |
  527. | **Anti-Analysis** | Pattern scanning (via `lief` + `capstone`) | | |
  528. | **Malware** | File hashing, IoC extraction, risk scoring | | `yara` ✓, `ssdeep`, `tlsh` |
  529. | **Firmware** | | `binwalk`, `sasquatch` | |
  530. | **Protocol** | Binary protocol dissection, fuzzing | `tshark` | `scapy` |
  531. | **Unpacking** | Packer signature detection | `upx` | `frida` |
  532. | **Deobfuscation** | XOR/ROT/Base64 deobfuscation | | `capstone` ✓ |
  533. | **Symbolic** | | | `angr`, `triton` (source-build only; tool auto-enables when installed) |
  534. | **Binary Formats** | | `aapt`, `javap`, `monodis`, `wasm2wat` | |
  535. | **Utilities** | Hex dump, binary diff, patching | `tshark` | `scapy`, `ssdeep`, `tlsh` |
  536. ✓ = included in core dependencies (always installed).
  537. ### Installing Optional Dependencies
  538. ```bash
  539. # Frida (dynamic instrumentation)
  540. pip install frida frida-tools
  541. # angr (symbolic execution, large install ~2 GB)
  542. pip install angr
  543. # radare2 bindings
  544. pip install r2pipe
  545. # Fuzzy hashing
  546. pip install ssdeep tlsh
  547. # Network analysis
  548. pip install scapy
  549. # Everything at once
  550. pip install -e ".[full]"
  551. ```
  552. ### Installing External Tools (Debian/Ubuntu/Kali)
  553. ```bash
  554. # Core analysis/tooling from distro repos
  555. sudo apt install gdb binutils binwalk checksec apksigner mono-utils mono-devel ruby-full llvm-19
  556. # Android RE
  557. sudo apt install apktool jadx android-sdk adb zipalign
  558. # Network
  559. sudo apt install tshark
  560. # For full optional toolchain coverage (radare2/rizin/upx/drrun/msfvenom/retdec/diec/cfr),
  561. # use the maintained installer:
  562. bash scripts/install/install_all.sh
  563. ```
  564. ---
  565. ## Architecture
  566. ```
  567. src/revula/ # 19,400+ LOC across 63 Python files
  568. ├── __init__.py # Version (__version__ = "0.1.0")
  569. ├── config.py # Tool detection, TOML config, env var loading
  570. ├── sandbox.py # Secure subprocess execution, path validation
  571. ├── session.py # Session lifecycle manager (debuggers, Frida)
  572. ├── server.py # MCP server entrypoint (stdio transport)
  573. ├── cache.py # LRU result cache with TTL
  574. ├── rate_limit.py # Token-bucket rate limiter
  575. └── tools/
  576. ├── __init__.py # Tool registry + @register_tool decorator
  577. ├── static/ # 8 files: PE/ELF, disasm, strings, entropy, symbols, YARA, capa, decompile
  578. ├── dynamic/ # 4 files: GDB, LLDB, Frida, coverage
  579. ├── android/ # 9 files: APK, DEX, decompile, native, device, frida, traffic, repack, scanners
  580. ├── platform/ # 3 files: Rizin, GDB-enhanced, QEMU
  581. ├── exploit/ # 5 files: ROP builder, heap exploitation, libc database, shellcode, format strings
  582. ├── antianalysis/ # 1 file: anti-debug/VM detection and bypass generation
  583. ├── malware/ # 1 file: triage, sandbox queries, YARA gen, config extraction
  584. ├── firmware/ # 1 file: extraction, vuln scanning, base address detection
  585. ├── protocol/ # 1 file: PCAP analysis, protocol dissection, fuzzing
  586. ├── deobfuscation/ # 1 file: string deobfuscation, CFF, opaque predicates
  587. ├── unpacking/ # 1 file: packer detection, UPX, dynamic unpack, PE rebuild
  588. ├── symbolic/ # 1 file: angr + Triton
  589. ├── binary_formats/ # 1 file: .NET, Java, WASM
  590. ├── utils/ # 4 files: hex, crypto, patching, network
  591. └── admin/ # 1 file: server status, cache management
  592. ```
  593. ### How It Works
  594. 1. **Startup.** `server.py` loads `config.py`, which probes the system for external tools (via `shutil.which`) and Python modules (via `importlib.util.find_spec`). Results are cached in a `ServerConfig` singleton.
  595. 2. **Tool Registration.** Each tool file uses `@TOOL_REGISTRY.register()` to declare its name, description, input/output schemas, annotations, and async handler. Tools self-register on import.
  596. 3. **Request Dispatch.** When a `tools/call` request arrives, the server resolves namespaced aliases, validates arguments (Pydantic-first with JSON Schema fallback), checks rate limits, checks cache eligibility, dispatches the handler, and returns protocol-level `isError` metadata.
  597. 4. **Subprocess Execution.** All external tool invocations go through `sandbox.safe_subprocess()`, which enforces `shell=False`, sets `RLIMIT_AS` and `RLIMIT_CPU`, validates paths, and captures stdout/stderr.
  598. 5. **Result Caching.** Deterministic operations (disassembly, parsing) are cached with a configurable TTL. Mutating operations (patching, Frida injection) bypass the cache automatically.
  599. 6. **Session Management.** Long-lived debugger and Frida sessions are tracked by `SessionManager`, with automatic cleanup after 30 minutes of idle time.
  600. ### Infrastructure Components
  601. | Component | Purpose | Key Detail |
  602. |-----------|---------|------------|
  603. | **ResultCache** | Avoid redundant subprocess calls | LRU, 256 entries, 10-minute TTL |
  604. | **RateLimiter** | Prevent resource exhaustion | Token-bucket with config/env overrides |
  605. | **ToolRegistry** | Decorator-based tool dispatch | Annotations + strict schema hardening + structured errors |
  606. | **SessionManager** | Debugger/Frida persistence | Auto-cleanup after 30 min idle |
  607. | **sandbox.py** | Secure execution layer | `shell=False`, RLIMIT enforcement, path validation |
  608. ---
  609. ## Security Model
  610. revula operates on the principle that **user-supplied arguments are untrusted**. The following hardening measures are applied:
  611. ### Subprocess Isolation
  612. - **No `shell=True`:** Every subprocess call uses `shell=False` with explicit argument lists. This is enforced by a CI test (`test_no_shell_true`) that scans every source file.
  613. - **No `eval()` / `exec()`:** No dynamic code evaluation of user input.
  614. - **No f-string injection:** User-supplied values are never interpolated into `python3 -c` code strings. Values are passed via `sys.argv`, `stdin`, or environment variables. Enforced by `test_no_fstring_in_subprocess_python_code`.
  615. - **JavaScript escaping:** All user-controlled values interpolated into Frida JavaScript strings pass through `_js_escape()`, which escapes backslashes, quotes, newlines, and other injection vectors.
  616. - **Resource limits:** Every subprocess gets `RLIMIT_AS` (512 MB default) and `RLIMIT_CPU` (60 s default) via `resource.setrlimit()`.
  617. - **Timeout enforcement:** `asyncio.wait_for()` wraps all subprocess calls.
  618. ### Path Validation
  619. - **Fail-closed:** `validate_path()` rejects all paths when no `allowed_dirs` are configured (falls back to `get_config().security.allowed_dirs`). It does not silently pass.
  620. - **Traversal blocked:** `..` components are rejected after `os.path.realpath()` resolution.
  621. - **Absolute paths required:** Relative paths are rejected.
  622. - **Validated everywhere:** All file-accepting tool handlers call `validate_path()` before any file I/O.
  623. ### Frida Hardening
  624. - **Script size limit:** Frida scripts are capped at 1 MB to prevent memory exhaustion.
  625. - **Memory dump limit:** Memory dumps are capped at 100 MB.
  626. - **JS injection prevention:** Class names, method names, module names, and other user-supplied values are escaped before interpolation into JavaScript templates.
  627. ### Temporary Files
  628. - **No `tempfile.mktemp()`:** All temporary files use `tempfile.NamedTemporaryFile()` or `tempfile.mkdtemp()` to prevent TOCTOU race conditions.
  629. - **No hardcoded `/tmp` paths:** All temporary paths use the `tempfile` module.
  630. ### Rate Limiting & Caching
  631. - **Global limit:** 120 requests per minute (configurable).
  632. - **Per-tool limit:** 30 requests per minute (configurable).
  633. - **Result cache policy:** fail-closed explicit opt-in per tool (`cacheable=True`); mutating/stateful tools are never cached by default.
  634. - **Session TTL:** Idle sessions auto-cleaned after 30 minutes.
  635. ---
  636. ## Testing
  637. ```bash
  638. # Run full test suite
  639. python -m pytest tests/ --timeout=30
  640. # With coverage
  641. python -m pytest tests/ --cov=revula --cov-report=html --timeout=30
  642. # Verbose output
  643. python -m pytest tests/ -v --timeout=30
  644. # Specific test suites
  645. python -m pytest tests/test_infra.py -v # Cache, rate limiter, sessions
  646. python -m pytest tests/test_core.py -v # Config, sandbox, tool registry
  647. python -m pytest tests/test_static.py -v # Static analysis tools
  648. python -m pytest tests/test_android.py -v # Android module tests
  649. python -m pytest tests/test_exploit.py -v # ROP, heap, libc tools (32 tests)
  650. python -m pytest tests/test_tools_new.py -v # Exploit, malware, firmware, protocol, etc.
  651. python -m pytest tests/test_security.py -v # Security invariant tests
  652. # Using the test runner script
  653. bash scripts/test/run_tests.sh
  654. ```
  655. ### Test Categories
  656. | Suite | Tests | Covers |
  657. |-------|-------|--------|
  658. | `test_infra.py` | Cache, rate limiter, session manager | Infrastructure correctness |
  659. | `test_core.py` | Config loading, sandbox, tool registry | Core module behavior |
  660. | `test_static.py` | Entropy, hex, crypto, strings, symbols | Static analysis tools |
  661. | `test_android.py` | APK parse, DEX, device, Frida Android | Android module tests |
  662. | `test_tools_new.py` | Exploit, malware, firmware, protocol, antianalysis, platform, deobfuscation, symbolic, unpacking, binary formats | All remaining tool categories |
  663. | `test_security.py` | `shell=True` scan, injection scan, `mktemp` scan, hardcoded `/tmp` scan, path validation, JS escaping, shellcode validation | Security regression tests |
  664. ### Security Tests
  665. The `TestVulnerabilityHardeningV3` suite in `test_security.py` enforces:
  666. - **No f-string code injection:** Scans all source files for `"-c"` arguments containing f-strings.
  667. - **No `tempfile.mktemp()`:** Prevents TOCTOU race conditions.
  668. - **No hardcoded `/tmp/` paths:** Enforces use of the `tempfile` module.
  669. - **Fail-closed path validation:** Verifies `validate_path()` rejects paths when `allowed_dirs` is empty.
  670. - **Frida JS escaping:** Verifies `_js_escape()` blocks injection payloads.
  671. - **Shellcode hex validation:** Verifies non-hex input is rejected, not passed to subprocess.
  672. ---
  673. ## Scripts & Automation
  674. Primary automation scripts live in `scripts/`:
  675. ### Installation
  676. | Script | Purpose |
  677. |--------|---------|
  678. | `scripts/install/install_all.sh` | Master installer: Python check, deps, external tools, config |
  679. | `scripts/install/install_verify.sh` | Post-install verification: checks all dependencies and paths |
  680. ### Setup
  681. | Script | Purpose |
  682. |--------|---------|
  683. | `scripts/setup/setup_ide.py` | Universal IDE/client configurator for Claude Desktop, VS Code, Cursor, Windsurf, Zed, and Continue |
  684. | `scripts/setup/setup_claude_desktop.py` | Claude Desktop-specific auto-configurator (legacy, still functional) |
  685. | `scripts/setup/setup_config_toml.py` | Interactive config.toml generator |
  686. | `scripts/setup/setup_android_device.sh` | Prepare an Android device for RE (root, frida-server, certs) |
  687. ### Testing & Development
  688. | Script | Purpose |
  689. |--------|---------|
  690. | `scripts/test/run_tests.sh` | Run full test suite with coverage |
  691. | `scripts/test/validate_install.py` | Comprehensive installation validator |
  692. | `scripts/dev/add_tool.py` | Scaffold a new tool module (creates file, registers, adds test) |
  693. | `scripts/dev/lint_and_type.sh` | Run ruff + mypy |
  694. | `scripts/utils/download_frida_server.py` | Download frida-server for a target architecture |
  695. ### Docker
  696. | Script | Purpose |
  697. |--------|---------|
  698. | `scripts/docker/test.sh` | Automated Docker build and stdio-oriented smoke checks |
  699. | `scripts/docker/validate.sh` | Docker configuration validation |
  700. ---
  701. ## Usage Examples
  702. ### Static Analysis: Analyze a PE Binary
  703. Ask Claude: *"Analyze this binary for me: /home/user/samples/malware.exe"*
  704. Behind the scenes, Claude can call:
  705. 1. `re_pe_elf` to parse PE headers, sections, imports, and exports
  706. 2. `re_strings` to extract and classify strings (URLs, IPs, crypto constants)
  707. 3. `re_entropy` to check for packing (high entropy sections)
  708. 4. `re_yara_scan` to scan with YARA rules
  709. 5. `re_capa_scan` to map to ATT&CK techniques
  710. ### Dynamic Analysis: Debug with GDB
  711. Ask Claude: *"Debug /home/user/crackme and find the password check"*
  712. Claude can orchestrate:
  713. 1. `re_gdb` with action `start` to launch the binary under GDB
  714. 2. `re_disasm` to disassemble key functions
  715. 3. `re_gdb` with action `breakpoint` to set breakpoints at comparison instructions
  716. 4. `re_gdb` with action `continue` and `registers` to run and inspect state
  717. ### Android: Reverse an APK
  718. Ask Claude: *"Analyze this APK for security issues: /home/user/app.apk"*
  719. Claude can call:
  720. 1. `re_apk_parse` to extract manifest, permissions, and components
  721. 2. `re_dex_analyze` to list classes and find suspicious methods
  722. 3. `re_android_decompile` to decompile with jadx
  723. 4. `re_android_scanner` to run security scanners
  724. 5. `re_antianalysis_detect` to check for anti-tampering
  725. ### Malware Triage
  726. Ask Claude: *"Triage this suspected malware sample"*
  727. Claude can call:
  728. 1. `re_malware_triage` for hashes, IoCs, import analysis, and risk score
  729. 2. `re_malware_config` to extract C2 URLs and encryption keys
  730. 3. `re_malware_yara_gen` to generate a YARA rule for the sample
  731. 4. `re_malware_sandbox` to query VirusTotal/Hybrid Analysis
  732. ### Exploit Development
  733. Ask Claude: *"Build a ROP chain to call execve('/bin/sh') in this binary"*
  734. Claude can orchestrate:
  735. 1. `re_rop_gadgets` to find useful gadgets (pop rdi, pop rsi, syscall) with semantic classification
  736. 2. `re_rop_chain` to automatically build an execve chain with proper register setup
  737. 3. `re_libc_offsets` to extract system/execve/binsh offsets from libc
  738. 4. `re_aslr_defeat` to calculate base addresses from leaked pointers
  739. 5. `re_heap_chunk` to analyze malloc chunks and bin classification for heap exploits
  740. 6. `re_heap_technique` to get templates for House of Force, Tcache Poisoning, etc.
  741. ---
  742. ## Performance & Limitations
  743. ### What Works Well Without Optional Dependencies
  744. With just the core install (`pip install -e .`), you get full functionality for:
  745. - PE/ELF/Mach-O parsing and header analysis
  746. - Multi-architecture disassembly (via Capstone)
  747. - String extraction and classification
  748. - Shannon entropy analysis and packing detection
  749. - YARA rule scanning
  750. - Binary patching
  751. - Hex dump and pattern search
  752. - File hashing (MD5, SHA-1, SHA-256)
  753. - ROP gadget finding and chain building (via Capstone)
  754. - Heap exploitation helpers (chunk analysis, bin classification, safe-linking)
  755. - Libc database tools (symbol extraction, offset calculation, ASLR defeat)
  756. - Format string payload calculation
  757. - XOR/ROT/Base64 deobfuscation
  758. - Anti-analysis pattern detection
  759. ### What Needs External Tools
  760. These tools produce clear "tool not found" errors when backends are missing:
  761. - **Decompilation** requires Ghidra, RetDec, or Binary Ninja
  762. - **Dynamic analysis** requires GDB, LLDB, or Frida
  763. - **Android RE** requires jadx, apktool, and ADB
  764. - **Symbolic execution** requires angr (large dependency, ~2 GB)
  765. - **Network analysis** requires tshark or scapy
  766. - **Firmware extraction** requires binwalk
  767. ### Performance Expectations
  768. - **Startup:** ~1 second (probes system for available tools via `shutil.which` and `importlib.util.find_spec`)
  769. - **Static analysis:** Sub-second for most operations on files under 100 MB
  770. - **Disassembly:** Capstone disassembles ~1 MB/s; radare2 adds full analysis overhead
  771. - **Subprocess calls:** Each external tool invocation has ~50-200 ms overhead from process spawn
  772. - **Caching:** Result caching is explicit opt-in per tool; unless enabled, calls execute fresh
  773. - **Rate limiting:** 120 requests/minute global, 30/minute per tool (configurable)
  774. ### Known Limitations
  775. 1. **No Windows native support.** Designed for Linux. macOS works for most tools. Windows requires WSL2.
  776. 2. **stdio transport only.** There is no HTTP/SSE server. Revula must run on the same machine as your IDE (or be piped via SSH/Docker). This is a deliberate design choice for security: MCP over stdio is simpler and avoids exposing a network socket.
  777. 3. **No GUI.** This is a headless MCP server. Use Claude Desktop, VS Code Copilot, Cursor, or another MCP client for the interface.
  778. 4. **Large binary analysis.** Files over 500 MB may hit the default memory limit (512 MB). Increase via `REVULA_MAX_MEMORY_MB`.
  779. 5. **angr install size.** The `angr` optional dependency is ~2 GB and takes several minutes to install.
  780. 6. **Frida version coupling.** Frida client and server versions must match exactly. Use `scripts/utils/download_frida_server.py` to get the right version.
  781. 7. **Single-user design.** The server handles one MCP client at a time via stdio. There is no multi-tenant isolation. Each IDE/client spawns its own server process.
  782. 8. **IDA Pro integration.** Requires IDA Pro with the REST API plugin. Not included.
  783. ---
  784. ## Troubleshooting
  785. ### Server Won't Start
  786. ```bash
  787. # Check Python version (need 3.11+)
  788. python --version
  789. # Check MCP is installed
  790. python -c "import mcp; print(mcp.__version__)"
  791. # Run and capture server logs from stderr
  792. revula 2> revula.log
  793. tail -f revula.log
  794. ```
  795. ### Tool Says "not found"
  796. ```bash
  797. # Check what's available
  798. python -c "from revula.config import get_config, format_availability_report; print(format_availability_report(get_config()))"
  799. # The report shows ✓/✗ for every external tool and Python module.
  800. # Install what you need and restart the server.
  801. ```
  802. ### Path Validation Errors
  803. ```
  804. Error: Path /some/path is not within allowed directories
  805. ```
  806. Add the directory to your config:
  807. ```toml
  808. [security]
  809. allowed_dirs = ["/home/user/samples", "/tmp/analysis", "/some/path"]
  810. ```
  811. Alternatively, set the value via environment variable. The server will use the config file's `allowed_dirs` as a fallback.
  812. ### Rate Limit Exceeded
  813. ```
  814. Error: Rate limit exceeded for tool re_disasm
  815. ```
  816. Rate limits are currently initialized from code defaults (`global_rpm=120`, `per_tool_rpm=30`, `burst_size=10`).
  817. If you need different limits, adjust `RateLimitConfig(...)` in `src/revula/server.py` and restart.
  818. ### Frida Connection Issues
  819. ```bash
  820. # Check Frida version match
  821. frida --version
  822. frida-server --version # on device
  823. # Download matching server
  824. python scripts/utils/download_frida_server.py --arch arm64
  825. ```
  826. ### Tests Failing
  827. ```bash
  828. # Run with verbose output
  829. python -m pytest tests/ -v --timeout=30 --tb=long
  830. # Clear bytecode cache (fixes stale imports)
  831. find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null
  832. python -m pytest tests/ --timeout=30
  833. ```
  834. ### Android Device Not Detected
  835. ```bash
  836. # Run the device setup script
  837. bash scripts/setup/setup_android_device.sh
  838. # Manual check
  839. adb devices
  840. adb shell id # should show root or shell
  841. ```
  842. ---
  843. ## Contributing
  844. ### Adding a New Tool
  845. Use the scaffold generator:
  846. ```bash
  847. python scripts/dev/add_tool.py
  848. ```
  849. This creates the tool file, registers it in the category `__init__.py`, and generates a test stub.
  850. ### Code Quality
  851. ```bash
  852. # Lint and type-check
  853. bash scripts/dev/lint_and_type.sh
  854. # Run full test suite
  855. python -m pytest tests/ --timeout=30 -q
  856. # Validate install
  857. python scripts/test/validate_install.py
  858. ```
  859. ### Guidelines
  860. - Every tool handler is `async` and returns `list[dict]` (MCP content blocks).
  861. - All subprocess calls go through `sandbox.safe_subprocess()`.
  862. - All file paths must be validated via `sandbox.validate_path()`.
  863. - No `shell=True`, no `eval()`, no f-string interpolation into subprocess code.
  864. - Every new tool needs at least one test.
  865. ---
  866. ## License
  867. Released under the GNU General Public License. See [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.