Skip to content

README.md

Latest commit

 

History

History
463 lines (368 loc) · 26.7 KB

README.md

File metadata and controls

463 lines (368 loc) · 26.7 KB
Raw

Seep Reverse Lab Logo

Seep Reverse Lab

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

Release License Platform Architecture

MCP Tools Knowledge Base MANUAL SOPs LINUX DO

[ 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

Pain Point Solution
🔧 Toolchain Fragmentation 23 MCP tools wrapping Radare2, JADX, Apktool, Frida — unified API, zero manual switching
🧠 Agent Decision Drift softseep orchestrator: two-stage auto-classification (Platform × 9 Task Types) + 7-gate decision tree
🛡️ Model Refusal in Security Audits Three-tier mitigation: BLOCK_NONE injection + transparent terminology mapping + cognitive redirection
📚 Ephemeral Knowledge 289 technical field journals + 14 desensitized paradigms + "search KB before executing" enforced discipline
📦 Setup Friction One-click install.ps1 → supports Pi Agent, Claude Code, DeepSeek Harness (DSH), Codex / OpenCode

⚙️ 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

Seep Autonomous Reversing Workflow

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)
  • 🌐 Transport-Layer Compliance Relay: Optional localhost relay rewrites colloquial user input into compliant terminology before it leaves the machine — covering any Agent that supports a custom baseUrl (Pi Agent / Claude Code / Codex). Zero new dependencies, zero disk writes, context-injection guarded.
  • 🔌 Offline-Ready: All toolchains pre-bundled (251 MB), zero network dependencies after setup

📋 Directory Structure

📁 Full Directory Tree (click to expand) 
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 & self-check scripts
└── MANUAL\                        ← 5 Tactical SOP guides
    ├── PREREQUISITES.md           ← Environment requirements
    ├── IDA-PRO.md                 ← Commercial IDA Pro integration guide
    ├── 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

🛠️ MCP Tool Matrix

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

Category Tool Functionality Token Mode
Health seep_status Verifies Radare2, JADX, Apktool, KB readiness —
seep_ida_status Probes IDA Pro MCP service connectivity —
Binary (R2) seep_r2_info Architecture, bitness, DEP/ASLR/Canary/PIE —
seep_r2_strings Extracts strings with regex + section filtering limit=
seep_r2_functions Functions, imports, exports, entry points limit=
seep_r2_disasm Disassembly with cross-references full / branch
seep_r2_decompile C-like pseudocode via pdc engine full / fold / summary
seep_r2_xrefs Cross-reference graph, paginated limit=10 default
seep_r2_diff Code / hex diff between two binaries —
seep_r2_asm Assemble ↔ disassemble machine code —
seep_r2_cmd Raw Radare2 pipeline commands —
Android seep_apk_info APK manifest, permissions, signatures (no Java) —
seep_apk_decompile JADX full Java source decompilation —
seep_apk_unpack Apktool resource + Smali disassembly —
seep_apk_smali_search Smali pattern search (crypto keys, auth gates) limit=
seep_apk_gen_hook Ready-to-run Frida hooks with stack traces —
Knowledge Base seep_kb_search Full-text search across 289 field journals limit=
seep_kb_read Full technical reference retrieval by topic —
seep_kb_checklist Emergency triage checklists & attack matrices —
seep_kb_payloads Security test seeds (JWT, SSRF, SSTI, SQLi) —
Orchestration seep_task_init Initializes isolated audit sandbox directory —
seep_auto_triage Automated full-sample health check —
seep_gen_security_report Synthesizes 3-part compliance security report —

💡 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

Agent Instruction File MCP Config Setup Procedure
Pi Agent Tool/prompts/SYSTEM.md ~/.pi/agent/mcp.json install.ps1 writes user configs & skills automatically. Restart Pi after installation.
Claude Code CLAUDE.md (project root) .mcp.json (project root) Run powershell .\setup\generate-configs.ps1 to resolve paths, then launch claude in root.
DeepSeek Harness Tool/prompts/AGENTS.md DSH-PROFILE.md Run setup\generate-configs.ps1 to produce cordis.generated.yml (official - insert: format), use dsh web --patch ... or paste into profile.
OpenCode / Codex AGENTS.md (project root) opencode.jsonc Generated by setup\generate-configs.ps1 (compliant with official OpenCode mcp schema), launch opencode in root.

📖 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.

# 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.

Flag Effect
-DryRun / --dry-run Show what would happen, modify nothing
-NoPull / --no-pull Skip git pull (for ZIP-based installs)

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

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 7-section health verifier (37 checks) using any of these methods:

Method Command
⭐ Double-click (easiest) check.bat in project root
PowerShell powershell -ExecutionPolicy Bypass -File .\check.ps1
Agent chat Send check (or doctor / 检查) — agent runs and reports inline

Seep Health Verifier Dashboard (35 Checks Passed)

🎮 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)

Shortcut Action
poc <target> CWE-602 client-side authorization audit + verification code
find-auth <target> Locate license, subscription, expiry, hardware-binding functions
hook <function> Generate Frida hook with stack trace + return-value override
gen-patch <offset> Binary patch bytes or proxy DLL scaffold
triage <sample> Full triage: architecture, imports, packers, strings
check Run 7-section workbench health verifier inline
report Synthesize active directory evidence → 3-part audit report

🔬 Technical Scope

Click to expand full technical scope

1. Client-Side Authorization Audit (CWE-602)

Authority Attribution: Airplane mode + loopback hijacking + timestamp offset testing to classify gates as server-authoritative vs. local-boolean within minutes.

Fourteen Industrial Paradigms — all fully desensitized:

Project Architecture Key Technique
A Monolithic offline PE Scalar return override (mov eax,1; ret)
B Multi-process hybrid Proxy DLL dispatch + 3-tier state persistence (v12.0 → v6.8.1 evolution: single winhttp naked thunk hijack + auto-update blocker)
C Resource template + UI Bijective bit-permutation decoding + IAT hook on SetDlgItemTextW
D Recompile-induced non-uniform shift AOB dual-state signature migration (3 versions) + PE gating + ACL locking + optional-site version adaptation + runtime call-stack locating
E EXECryptor VM arbitration 2-point Call redirection to memory stubs
F .NET dynamic deobfuscation Harmony memory dump + 96-bit combined hash keygen
G Self-referential SHA-384 5-byte function-entry patch + watchdog persistence
H Ed25519 pubkey replacement In-place ciphertext replacement via derived keystream
I Weak-modulus RSA Sliding-window bypass + activation injection on export entry
J Online Card/Key Authorization Protocol decryption + memory patching + local credential spoofing
K .NET WPF + Themida Packing Memory dump unpacking + privilege decision branching + registry state freeze
L Qt5 C++ Client Proxy DLL hook + 11 privilege decision constant-folds + local LLM translation gateway
M Java + install4j Dual-Layer DLL search-order hijack (version.dll IAT hook) + JVM native ClassFile bytecode patching (burp.Zfqu / burp.Zwxg.Zu) + license/AI token preference seeding
N .NET x64 + VM Obfuscation Runtime memory extraction + privilege flag inversion + silent auto-injection

2. Android & DEX/SO Analysis

  • Surgical DEX same-length patching with automated Adler-32 / SHA-1 recalculation
  • Packer classification: Java2C / native payload / extraction shell / private DEX-VMP
  • Runtime anti-analysis: root detection bypass, SSL pinning circumvention, Frida-RPC bridging
  • Repack pipeline: STORED resources.arsc + 4-byte Zipalign + v1+v2+v3 signing

3. Binary / Native (PE / ELF / Mach-O)

  • Headless Radare2: architecture ID, entropy scan, symbol recovery, C-like decompilation
  • Full IDA Pro MCP integration: Hex-Rays decompilation, xrefs, struct recovery
  • Anti-tamper defeat: deliberate crash stubs, raw svc syscall detection, kernel anti-debug

4. CTF & Challenge Workflows

  • Attack-network routing: Signal → seep_kb_search → template assembly → MCP execution
  • Web: JWT, KID injection, SSRF chains, SSTI, deserialization gadget chains, Protobuf decoding
  • Seed libraries (seep_kb_payloads) + emergency checklists (seep_kb_checklist)

🤖 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

Star History Chart