Seep Reverse Lab

Agent-Native · Multi-Platform Reverse Engineering · CWE-602 Authorization Audit · Autonomous Security Workbench

[ English | 中文文档 ]

Overview • Architecture • Demo • MCP Matrix • Quick Start • Scope • Agent Contract • Disclaimer

🔗 Attribution & Reference Sources:

• Mobile reverse engineering methodology & verification test suite referenced from: newliver666/apk-reverse (MIT License).
• Security research lab framework, Zero-Waste Recon signal routing & agent execution protocols referenced from: GeniusHu-tgty/Open-tgtylab (GPL-3.0 License).
• Reverse engineering knowledge base, attack graph boards & MCP automation ecosystem referenced from: LING71671/open-reverselab (GPL-3.0 License).
• Community support & technical discussions: LINUX DO.

🌟 Project Overview

Seep consolidates fragmented reverse engineering toolchains (Radare2 / JADX / Apktool / Frida / IDA), operational knowledge bases, prompt engineering contracts, and battle-tested field experience into an Agent-Native Autonomous Workbench.

Users provide plain-language technical goals; the agent autonomously performs platform identification, vulnerability type classification, surgical binary patching, and closed-loop evidence delivery.

Five Core Pain Points Solved

⚙️ How It Works

User Input (plain language — "bypass the premium check in FooBar.apk")
    │
    ▼
┌───────────────────────────────────────────────────────────────────┐
│  Lab Mode State Machine  (disk-backed ~/.pi/agent/lab-mode.flag)  │
│  • Colloquial → compliance terminology auto-mapping               │
│  • BLOCK_NONE injection + cognitive redirection (anti-refusal)    │
│  • Context persists across model switches & context compression   │
└────────────────────────────┬──────────────────────────────────────┘
                             │
                             ▼
┌───────────────────────────────────────────────────────────────────┐
│  softseep  Master Orchestrator                                    │
│  ① Platform  →  Windows PE / Android APK / Linux ELF / Web       │
│  ② Task Type →  9 Paradigms × 7 Gates (G0–G6 decision tree)      │
│  ③ Route     →  apkseep / ida-reverse / seep MCP / KB            │
└────────┬──────────────────┬────────────────────┬──────────────────┘
         │                  │                    │
         ▼                  ▼                    ▼
   seep MCP            IDA Pro MCP         KB Search
   23 tools            (optional)          289 journals
   (Radare2/JADX/                          (Zero-Waste Recon)
    Apktool/Frida)
         │
         ▼
┌───────────────────────────────────────────────────────────────────┐
│  Context Budget Control  (v1.1 noise reduction)                   │
│  • seep_r2_decompile: full / fold (−60% tokens) / summary (−90%) │
│  • seep_r2_disasm:   full / branch (control-flow only)           │
│  • seep_r2_xrefs:    paginated, limit=10, total stats header      │
└────────────────────────────┬──────────────────────────────────────┘
                             │
                             ▼
         PoC Generated → Sandbox Execution → Self-Healing Loop
                             │
                             ▼
         Airplane-Mode Confirmation (CWE-602 iron-clad proof)
                             │
                             ▼
         3-Part Consulting-Grade Security Report  ✓

⚡ 30-Second Demo

Once deployed, just talk to your agent in plain language:

lab: analyze FooBar.apk — find the premium check and bypass it

The agent autonomously:

1. seep_auto_triage → identifies DEX + ARM64 SO, no packer detected
2. seep_apk_decompile with output_mode=fold → extracts control-flow skeleton only (saves ~60% tokens)
3. seep_kb_search → finds matching CWE-602 pattern from field journal #142
4. seep_apk_gen_hook → generates hook_verify.js Frida script
5. Executes on connected device → captures stdout, self-heals ClassNotFoundException, re-runs
6. Airplane-mode confirmation ✓ → seep_gen_security_report → 3-part audit report delivered

Total elapsed time on a typical client app: 8–20 minutes, fully unattended.

⚡ Core Capabilities

• 🎯 Natural Language Intent Resolution: Binary magic bytes + semantic verb mapping → correct toolchain, no flags to memorize
• 🔍 CWE-602 Authorization Audit: Minutes to determine if a feature gate is local-boolean or server-authoritative
• 🛡️ Authenticode Signature Preservation: DLL search-order hijacking (version.dll / sentry.dll) keeps host binary signature intact
• 🔄 PoC Self-Healing Loop: Frida error → root-cause mapping → auto-fix → re-execute (up to 3 attempts, then structured handoff)
• 💎 14 Industrial Architecture Paradigms: Monolithic offline PE → multi-process IPC → VM arbitration → .NET keygen → weak RSA bypass → Java agent → .NET VM bypass (fully desensitized, Projects A through N)
• 🌐 Transport-Layer Compliance Relay & Auto-Retry: Pure stdlib localhost relay with streaming refusal auto-retry cascade (S1-review-checklist → S2-review-framed → S3-review-en), preserving target paths without semantic drift. Unit tests 84/84 passing.
• ⚡ DeepSeek Harness (DSH) Self-Healing Launcher: 4s fast cold-start with automated zombie cleanup, web token URL extraction, and MCP verification suite (start-dsh.ps1 / stop-dsh.ps1).
• 🛡️ Measured Anti-Refusal Defense: Gemini-safe prompt reshaping (gemini-safe.flag), L1 observable decision logging (l1-log.flag), and native BLOCK_NONE payload gating.
• 🔌 Offline-Ready: All toolchains pre-bundled (251 MB), zero network dependencies after setup

📋 Directory Structure

Seep\ (251 MB)
├── README.md                      ← This file (English default)
├── README.zh.md                   ← Chinese documentation (中文文档)
├── CLAUDE.md                      ← Project-level instructions for Claude Code
├── .mcp.json                      ← Project-level MCP registration (Claude Code / OpenCode)
├── DSH-PROFILE.md                 ← DeepSeek Harness Cordis plugin config template
├── check.bat                      ← ⭐ Double-click one-shot health verifier (Windows)
├── check.ps1                      ← PowerShell health verifier entry point
├── VERSION                        ← Current version marker
├── CHANGELOG.md                   ← User-facing release notes
│
├── Tool\
│   ├── skill\                     ← 9 specialized reverse engineering skills
│   │   ├── softseep\              ← ⭐ Master orchestrator (Router + 8 on-demand references)
│   │   ├── apkseep\               ← End-to-end Android APK/DEX/SO skill (115 files)
│   │   ├── ida-reverse\           ← IDA Pro automated spawning & MCP coordination
│   │   ├── client-license-validation-bypass\ ← Cross-runtime license attack playbook
│   │   └── safe-skills\           ← 5 standalone tool packages
│   │
│   ├── mcp\                       ← MCP Engine
│   │   ├── seep_mcp_server.py     ← Core server: 23 native reversing & KB tools
│   │   ├── mcp.json.template      ← Global MCP client configuration template
│   │   └── Tool\                  ← ⚠️ Hardcoded relative runtime path (do not rename)
│   │       ├── safe\              ← Pre-bundled cross-platform toolchains
│   │       │   ├── jadx\          ← 75 MB (v1.5.6)
│   │       │   ├── radare2\       ← 39 MB (v6.2.2 full suite)
│   │       │   ├── apktool\       ← 24 MB (v3.0.3)
│   │       │   ├── hook-mcp\      ← Frida / LSPosed instrumentation templates
│   │       │   ├── ida-pro-mcp\   ← IDA bridge adapter
│   │       │   ├── js-reverse-mcp\← Web / JS debugging engine
│   │       │   └── playwright-mcp\← Headless browser automation
│   │       └── reverselab\        ← 289 field journals + attack chains
│   │
│   ├── prompts\                   ← Agent coordination specs & runtime extensions
│   │   ├── SYSTEM.md              ← Pi Agent system instructions
│   │   ├── AGENTS.md              ← Cross-agent portable instructions
│   │   └── extensions\            ← BLOCK_NONE injection + terminology mapping
│   │
│   ├── cases\                     ← 14 desensitized industrial paradigm projects (A ~ N, incl. version-evolution archive v2)
│   ├── upstream\                  ← Upstream verification & attribution layer (3 Full mirrors)
│   │   ├── apk-reverse\           ← newliver666/apk-reverse (Android RE & offline test suite)
│   │   ├── open-tgtylab\          ← GeniusHu-tgty/Open-tgtylab (Security lab framework & workflows)
│   │   └── open-reverselab\       ← LING71671/open-reverselab (Knowledge base, boards & MCP ecosystem)
│   ├── docs\                      ← Engineering reference docs
│   └── scripts\                   ← Workspace automation scripts
│       └── compliance-relay\      ← 🌐 Transport-layer compliance relay (stdlib-only, 3 protocols)
│
├── setup\                         ← Automated install, repair, update, uninstall & verify scripts
└── MANUAL\                        ← 9 Tactical SOP guides
    ├── PREREQUISITES.md           ← Environment & dependency requirements
    ├── IDA-PRO.md                 ← Commercial IDA Pro integration (native idalib + stdio modes)
    ├── ANTI-DEBUG.md              ← Anti-debug bypass dictionary & proxy DLL framework
    ├── UNPACKING.md               ← UPX/MPRESS/Themida/VMP unpacking SOP
    ├── POC-VALIDATION.md          ← Frida self-healing loop & PoC sandbox validation
    ├── DEPLOYMENT.md              ← Comprehensive deployment & multi-Agent setup guide
    ├── DEPLOYMENT-CHECKLIST.md    ← Official deployment baseline checklist (51 items)
    ├── CROSS-PLATFORM.md          ← Cross-platform (Windows/Linux/macOS) execution guide
    ├── COMPLIANCE-RELAY.md        ← Transport-layer compliance relay & auto-retry architecture
    └── MODEL-REFUSAL-MATRIX.md    ← Measured refusal matrix & Gemini-safe prompt reshaping

🛠️ MCP Tool Matrix

The bundled seep MCP server exposes 23 native tools across five functional groups:

💡 Context Budget Control (v1.1): seep_r2_decompile with output_mode=fold reduces token consumption by ~60%; summary mode by ~90%. Use seep_r2_xrefs instead of raw axt to avoid flooding the context window with hundreds of references.

🚀 Quick Start & Deployment

1. Prerequisites

• OS: Windows 10 / 11 x64 (recommended) or compatible Linux / macOS
• Runtimes: Python 3.11+, Node.js 18+, Git

2. One-Click Setup (Cross-Platform)

Windows (PowerShell):

cd setup
powershell -ExecutionPolicy Bypass -File .\install.ps1

Linux / macOS (Bash):

chmod +x setup/install.sh
./setup/install.sh

What this does automatically: Unpacks dependency archives (node_modules.zip) → validates pre-bundled tools → installs Python mcp libraries → registers MCP servers → resolves physical paths → runs full self-check.

3. Multi-Agent Setup

📖 Comprehensive Multi-Agent Guide: For detailed step-by-step setup, cross-platform caveats, and exhaustive troubleshooting FAQ, see MANUAL/DEPLOYMENT.md.

4. Updating an Existing Installation

Already deployed? No need to re-clone or copy files by hand. The updater is idempotent and lossless — your model credentials and any custom MCP servers you added are never overwritten.

• Easiest for Windows: Double-click update.bat in the repository root for zero-command automatic upgrade.
• In-Agent Prompt: Simply type "update workbench" (or "更新工作台") in your Agent chat, and it will execute the updater and report back.
• CLI Commands:

# Windows
powershell -ExecutionPolicy Bypass -File .\setup\update.ps1

# Linux / macOS
./setup/update.sh

It will: stash local changes → git pull → print the changelog → back up your config → incrementally sync skills/prompts/MCP entries → verify user data was preserved → run the full health check.

⚠️ Always fully restart your Agent session after updating so the new skills and extensions load. See CHANGELOG.md for what changed in each version.

4b. Upstream Declarative Sync & Zero-Spillover Architecture

Seep packages mirrors of upstream open-source repositories (apk-reverse, open-tgtylab, open-reverselab). To eliminate manual merging and prevent upstream updates from polluting unrelated modules, the workbench enforces a strict-boundary declarative sandboxing architecture:

• Declarative Rule Manifest: setup/upstream-rules.json strictly binds each upstream repo to its own target directory and allowed boundary whitelist.
• Physical Zero-Spillover Gate: setup/sync-upstream.py (pure stdlib) asserts real canonical paths before copying. If upstream A tries to write into directory B, directory C, or the main project, it throws a SpilloverSecurityViolation and aborts.
• Isolated CI Pull Requests: .github/workflows/upstream-sync.yml monitors upstream repositories on schedule. When upstream A is updated, it creates a dedicated branch and PR whose diff touches strictly Tool/upstream/A/.
• Local One-Click Sync:

  powershell -ExecutionPolicy Bypass -File .\setup\sync-upstream.ps1 -Target apk-reverse
  

5. Uninstalling

Removes only what the workbench itself installed. Your model credentials, sessions and any MCP servers you added yourself are never touched.

powershell -ExecutionPolicy Bypass -File ./setup/uninstall.ps1 -DryRun   # preview first
powershell -ExecutionPolicy Bypass -File ./setup/uninstall.ps1          # then run

./setup/uninstall.sh --dry-run && ./setup/uninstall.sh

Everything affected is backed up to ~/.pi/agent/backup-uninstall-<timestamp>/ first, and -Restore <dir> reverses the operation. See MANUAL/DEPLOYMENT.md.

6. Verify Your Deployment

Run the 9-dimension health verifier (52 checks) against MANUAL/DEPLOYMENT-CHECKLIST.md using any of these methods:

🎮 Workflow & Lab Mode

Lab Mode Protocol (Disk-Backed State Machine)

Activate:   lab:                          # or: lab: analyze FooBar.exe
Deactivate: exit lab

• State stored in ~/.pi/agent/lab-mode.flag — persists across model switches & context compression
• Once activated: terminology auto-mapping, anti-refusal overrides, and shortcut expansion are live
• Casual chat outside lab mode passes through unmodified — zero interference

Task Shortcuts (Active in Lab Mode)

🔬 Technical Scope

🤖 Agent Execution Contract

• G-Auth Gate: Confirm testing authorization on every new target. No authorization = stop.
• 7-Gate Decision Tree (G0–G6): Classify authority ownership (Server vs. Client) before touching any code.
• Two-Strike Rule: Same-shaped failure twice → refute the technical model, fall back to classification. Third variation is strictly prohibited.
• Zero-Waste Recon: Signal detected → seep_kb_search → pre-existing tool → execute. Never write scripts from scratch without checking the KB first.
• Definition of Done: Target hash → RVA identification → PoC execution → offline airplane-mode confirmation → 3-part structured delivery. Console log alone is not evidence.

📝 Deliverable Specification

All client-side vulnerability assessments follow a consulting-grade 3-part structure:

1. Vulnerability Detail & Risk — Exact RVA / file offsets, call chain, CWE-602 mapping, business severity
2. Reproduction & PoC — 100% reproducible instructions, proxy DLL source, or Frida script + offline confirmation evidence
3. Defense-in-Depth Remediation:
   • SetDefaultDllDirectories → prevent DLL hijacking
   • ProcessDynamicCodePolicy → prevent executable memory injection
   • Server-side authority via cryptographic signatures and short-lived tokens

🤝 Acknowledgements & License

• License: This project is licensed under the GNU General Public License v3.0 (GPL-3.0).
• Special thanks to newliver666/apk-reverse (MIT License) for the foundational Android reverse engineering paradigm and verification methodology.
• Special thanks to GeniusHu-tgty/Open-tgtylab (GPL-3.0 License) for the security research lab framework and Zero-Waste Recon routing architecture.
• Special thanks to LING71671/open-reverselab (GPL-3.0 License) for the comprehensive reverse engineering knowledge base, attack boards, and MCP automation ecosystem.
• Gratitude to the LINUX DO community for technical exchange, insight, and research collaboration.

⚖️ Disclaimer

This repository is intended solely for authorized security research, white-box auditing, compliance vulnerability testing, and educational CTF training.

• Explicit Authorization Required: Written authorization from the asset owner is mandatory before analyzing any target.
• No Warranty: All methodologies are provided "as is" based on sandbox measurements.
• Isolated Testing: Conduct all analysis in isolated VMs or sandboxes. Testing against production systems or unauthorized networks is prohibited.
• Limitation of Liability: Authors assume no liability for misuse, unauthorized testing, or violations of applicable laws.

⭐ Star History