open-reverselab

Open-ReverseLab — AI Reverse Engineering Agent & MCP Lab

Open-source AI-powered reverse-engineering platform for autonomous binary analysis, built for Claude Code, Codex, OpenCode and any MCP-compatible agent.

Ghidra · Frida · x64dbg · Rizin · PE · APK · Malware Analysis · CTF · Binary Analysis

An open-source reverse-engineering lab — executable knowledge base, 100+ MCP tools, Agent-native.

From an input signal to an evidence chain, every step is runnable.

[Ask DeepWiki] [License: GPL-3.0] [Sponsor: Sentry]

English · 简体中文

:handshake: Sponsored by Sentry

Sentry supports openreverselab with a sponsored account — error monitoring and performance tracing for the lab's toolchain.

Since Aug 2026 — see SPONSORS.md for the full sponsor list and how to become one.

What is ReverseLab

ReverseLab is an opinionated, runnable attack-knowledge base for reverse engineers, security researchers, CTF players, and AI Agents. Every article is structured as Scenario → Input signal → Method → Attack chain → MCP tool mapping, so a human or an Agent can pick up at any entry signal and walk the chain to evidence.

• 5 boards spanning web, mobile, Windows, and cross-domain reverse work.
• 180+ articles organized by attack surface, not by tooling.
• 100+ MCP tools exposed through reverse_lab_tools — curl, frida, ghidra, rizin, yara, triage, kb_router, … all callable from Claude Code, Codex, or any MCP-aware Agent.
• Directory-as-convention: every artifact has a fixed home (samples/, exports/, patches/, kb/, reports/). Drop-in a sample, follow the chain, ship the report.

The lab is built to be run, not browsed. If a step can't be executed, it doesn't belong in the KB.

Who is this for

Quick links

:book: Knowledge Base    :rocket: Quick start    :handshake: Contributing

Knowledge at a glance

kb/                                180+ articles, 5 boards
├── ctf-website/techniques/        26 categories, 118 articles — Web attack surface
├── apk-reverse/techniques/         8 categories,  23 articles — Android reverse
├── pe-reverse/techniques/          9 categories,  24 articles — Windows PE / binary
├── general/techniques/             5 categories,  17 articles — Crypto · Protocol · Cheat · IoT · SDR
└── windows/techniques/             platform-specific PE / config topics

The complete directory tree is available under kb/.

Quick start

Pick the path that matches your role, not your platform — the platform differences are below the role split.

For humans

Windows (recommended for first run) — double-click START_HERE.bat (or START_HERE.cmd) in the repo root. It checks Python, uv, Git, the reverse_lab_tools MCP server, runs real MCP smoke calls, and writes reports/misc/first-run-report.json plus reports/misc/mcp-smoke-report.json.

macOS / Linux — run ./START_HERE.sh from the repo root. It does the same first-run checks using POSIX shell wrappers under tools/bin/. Windows-only GUI/PE tools are skipped or reported as such.

# Pick the boards you actually need — the lab is modular.
.\scripts\misc\bootstrap.ps1                # core script wrappers (no downloads)
.\scripts\misc\install_tools.ps1 -CTF       # Web tools (sqlmap, nuclei, ffuf, jwt_tool, …)
.\scripts\misc\install_tools.ps1 -Android   # APK tools (apktool, jadx, frida, uber-apk-signer, …)
.\scripts\misc\install_tools.ps1 -Windows   # PE tools (cutter, pe-bear, procmon, …)
.\scripts\misc\install_tools.ps1 -Common    # Ghidra + Maven

macOS / Linux equivalent:

./scripts/misc/bootstrap.sh
export PATH="$PWD/tools/bin:$PWD/tools/ctf-website/bin:$PATH"
python scripts/misc/ai_toolcheck.py --board misc    # verify the fresh-clone core

Install only the boards you need. Don't dump the full toolchain if you're only doing web CTF.

After installing CTF / ExploitDB tools, Windows Defender may flag exploit samples or payload documentation — e.g. tools/ctf-website/exploitdb, kb/ctf-website/techniques/24-database/03-nosql-injection.md, docs/llms-full.txt. These contain security test payloads, webshells, shellcode, or ExploitDB samples and are expected components.

We recommend minimal path exclusions rather than excluding the entire repo:

Add-MpPreference -ExclusionPath "D:\open-reverselab\tools\ctf-website\exploitdb"

If individual documents are flagged, handle them case-by-case.

For AI Agents

1. Clone into a dedicated local directory, e.g. <workspace>/open-reverselab.
2. Claude Code: cd <workspace>/open-reverselab, then start your session.
3. Codex APP: Open the existing open-reverselab folder directly (no re-clone needed).
4. Automated AI install: send the contents of templates/prompts/ai-install.en.md to your Agent.
5. Create a task: python scripts/misc/new_task.py --board ctf-website --name <name>.
6. Verify real MCP invocation whenever switching machines or updating configs:

   uv run --project tools/skills/mcp/ReverseLabToolsMCP \
     python scripts/misc/mcp_smoke_check.py --write-report
   

Context chain — Agents load context through this sequence:

CLAUDE.md → AGENTS.md → AI-USAGE.md → boards/<board>/AI-USAGE.md

Use codex-session-patcher for one-click configuration of project-level .codex/ and MCP servers.

When first opening this project with an AI Agent, it inspects your local environment (OS, toolchains, reverse-engineering libraries, devices, sanitized env vars, network, workspace) following the protocol in AGENTS.md, and caches a snapshot at ~/.open-reverselab/env/env.md (%USERPROFILE%\.open-reverselab\env\env.md on Windows).

This file is host-level and shared across sessions: subsequent sessions read it directly without re-probing, unless 7 days have passed or the protocol version has bumped. It remains local and is never committed. Sensitive variables are redacted (keys marked "SET", proxies stripped of credentials).

Post-install verification

python scripts/misc/lab_healthcheck.py
python scripts/misc/ai_toolcheck.py --board misc
python scripts/misc/public_release_check.py

--board misc checks the fresh-clone core Agent scripts and lightweight tools. Run full python scripts/misc/ai_toolcheck.py only after installing Android / Windows / CTF boards.

Repository layout

The repository uses directory-as-convention. Put artifacts where they belong and the tooling finds them automatically.

samples/      Original samples + _quarantine/ + unpacked/   — never modified
exports/      Tool outputs (triage / IOC / YARA / Sigma / Procmon / Ghidra summaries)
patches/      Patch artifacts (originals are never modified)
notes/        Analysis notes
reports/      Final reports
scripts/      Automation scripts
projects/     Ghidra project files
templates/    Note / report / rule templates · AI install prompts
kb/           Reusable attack knowledge base — see "Knowledge at a glance"
tools/        Toolchain (binaries, wrappers, registry, MCP)
cases/        Lightweight index — no large file copies

Don't commit large samples, full PCAPs, or memory dumps. Index them in cases/ and link to a private store.

Community & contributing

• Contributing — see .github/CONTRIBUTING.md. Bug reports, KB article PRs, new MCP tool wrappers, and board additions are all welcome.
• Code of Conduct — .github/CODE_OF_CONDUCT.md (Contributor Covenant).
• Security issues — read SECURITY policy before opening a public issue.
• Publication guidance — PUBLICATION.md covers what is OK to publish, what stays in private cases, and AI/ML training protections.

Sponsors

ReverseLab is sustained by people and organizations that fund the infrastructure, tooling, and review time.

Want to sponsor? See SPONSORS.md or email belloshehubz@gmail.com — we list every sponsor, big or small, with the support they provide.

Star History

Disclaimer

By accessing or using this project, you agree to be bound by the full disclaimer — covering all versions and branches, all users (direct and indirect), all derivatives, legal compliance across all jurisdictions (including export controls and data protection laws), authorized purposes only, prohibited uses, no warranty, limitation of liability, mandatory disclaimer retention in derivatives, AI/ML training protections, and more.

:page_facing_up: Full legal text: DISCLAIMER.md · 中文版

License

GPL-3.0-only. See LICENSE. By contributing, you agree your contributions are licensed under the same terms.