angusdevgo/Seep-Reverse-Lab

Seep Reverse Lab – AI‑augmented Reverse‑Engineering Workbench

What it is – Seep Reverse Lab is a self‑contained, multi‑platform reverse‑engineering suite that lets you talk to an AI “agent” in plain English and have it automatically identify a binary’s platform, pick the right tooling (Radare2, JADX, Apktool, Frida, IDA Pro, etc.), run the analysis, generate a proof‑of‑concept patch or hook, and finally produce a three‑part security audit report. The whole pipeline is wrapped in a state‑machine called Lab Mode and is driven by a lightweight orchestrator named softseep.

---

Core Capabilities

Capability	How it works (as described in the README)
Natural‑language intent	You type something like lab: analyze FooBar.apk — find the premium check and bypass it. The agent parses the request, classifies the platform (APK + ARM64) and the task type, then routes the job through the appropriate skill chain.
Unified toolchain (23 MCP tools)	A custom MCP server (seep_mcp_server.py) exposes wrappers around Radare2, JADX, Apktool, Frida, IDA Pro, and other utilities. The agent calls these wrappers instead of you manually invoking each tool.
CWE‑602 client‑side authorization audit	The workflow includes an “airplane‑mode confirmation” step that verifies whether a feature gate is enforced locally or on the server, producing a concise CWE‑602 audit.
Context‑budget control	Certain commands (e.g., seep_r2_decompile with output_mode=fold or summary) automatically truncate the amount of data sent back to the LLM, reducing token usage by ~60‑90 %.
Self‑healing PoC loop	If a Frida script crashes, the agent maps the error, patches the script, and retries (up to three attempts) before handing off to a human.
Knowledge‑base integration	289 field‑journal entries are searchable via seep_kb_search. The agent always checks the KB first, enforcing a “zero‑waste recon” policy.
Offline‑ready	All required binaries (Radare2, JADX, etc.) are bundled (≈251 MB). After the one‑click install, no network access is needed for normal operation.
Multi‑agent support	Pre‑written prompt files let you run the same workflow with Pi Agent, Claude Code, DeepSeek Harness, or OpenAI Codex.

---

Architecture at a Glance

User Prompt → Lab‑Mode State Machine (disk‑backed flag)
    ↓
softseep Orchestrator
    ├─ Platform detection (PE / APK / ELF / Web)
    ├─ Task‑type classification (9 paradigms × 7‑gate decision tree)
    └─ Routing to one of:
        • seep MCP (23 native tools)
        • IDA‑Pro MCP bridge (optional)
        • Knowledge‑Base search
    ↓
Tool execution (Radare2, JADX, Frida, etc.)
    ↓
PoC generation → Sandbox execution → Self‑healing loop
    ↓
Airplane‑mode confirmation (CWE‑602 proof)
    ↓
3‑part consulting‑grade security report

The diagram in the README shows the same flow, with a persistent ~/.pi/agent/lab-mode.flag file that keeps context across model switches.

---

Quick‑Start Summary (from the README)

1. Prerequisites – Windows 10/11 x64 (recommended) or Linux/macOS, Python 3.11+, Node 18+, Git.
2. One‑click install – Run setup\install.ps1 (or double‑click check.bat). The script unpacks the bundled tools, installs the Python MCP package, registers the server, and runs a 35‑check health verifier.
3. Activate Lab Mode – In any supported chat interface type lab: followed by your natural‑language goal.
4. Run a task – Example: lab: analyze FooBar.apk — find the premium check and bypass it.
5. Get the report – After the autonomous loop finishes, the agent returns a three‑part audit (vulnerability detail, reproducible PoC, remediation advice).

---

Typical Use Cases

• Security auditors who need to quickly verify client‑side authorization checks (CWE‑602) across Windows, Android, or Linux binaries.
• Reverse‑engineering teams that want a single API surface for Radare2, JADX, Frida, and IDA Pro instead of juggling many command‑line tools.
• CTF / training labs where participants can focus on strategy while the agent handles the low‑level tooling and token budgeting.
• Incident‑response automation – the self‑healing PoC loop can be scripted to test patches on compromised binaries without manual re‑run.

---

Limitations & Caveats (as disclosed)

• Authorization required – The repository’s disclaimer stresses that you must have written permission from the asset owner before running any analysis.
• Model‑refusal mitigation – The system injects a BLOCK_NONE token and performs terminology mapping to keep LLMs from refusing security‑related requests; this is a custom workaround and may not work with every provider.
• Tool licensing – IDA Pro integration is optional and requires a separate commercial license.
• Platform support – While the README lists Windows, Android, Linux, and “Web”, the bundled binaries are primarily for x86/x64/ARM64; macOS support is not explicitly verified.
• Self‑healing loop – Limited to three retries; after that the agent hands off to a human operator.

---

Who Might Want This?

• Red‑team / penetration‑testing firms looking for a repeatable, AI‑driven workflow for client‑side binary audits.
• Security consultants who need to produce structured audit reports quickly.
• Reverse‑engineering researchers interested in a unified, agent‑native interface to popular open‑source tools.

---

Bottom Line

Seep Reverse Lab is a genuine, open‑source project that combines a rich set of reverse‑engineering utilities with an AI orchestration layer. It automates the end‑to‑end process of taking a natural‑language security request, selecting the right tooling, executing the analysis, and delivering a polished audit report—all while managing LLM token budgets and providing a self‑healing execution loop.