Seep-Reverse-Lab README

The project's README from github.com/angusdevgo/Seep-Reverse-Lab. As one markdown file: README.md.

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

📋 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
│
├── 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
│
├── 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

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

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

📝 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

⚖️ Disclaimer

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

⭐ Star History

Star History Chart

Seep-Reverse-Lab (angusdevgo/Seep-Reverse-Lab)

Searching Database…

1.7K ·GitHub
Seep-Reverse-Lab
这是什么？Seep Reverse Lab 是一个面向智能体的逆向工程与安全审计工作台，让 AI 编程智能体自主运行 Radare2、JADX、Apktool 和 Frida 来分诊二进制文件、反编译 APK，并判断应用的功能开关是在本地强制执行还是由服务器校验（即 CWE-602 授权审计）。
这是我自己运行的 CLI 工具，还是由 AI 智能体来驱动？它是一个暴露 23 个工具的 MCP 服务器；你用自然语言与连接的编程智能体对话，由智能体替你调用这些工具，而不是你自己敲参数。
怎么把它跑起来？在 Windows 上运行一键式 install.ps1（或在 Linux/macOS 上运行对应的 Bash 安装器）来解压内置工具并注册 MCP 服务器，然后使用生成的配置文件把它连接到你的智能体（Pi Agent、Claude Code、DeepSeek Harness 或 OpenCode/Codex）。
需要先安装 Python 和 Node.js 吗？需要，运行安装器之前必须先装好 Python 3.11+、Node.js 18+ 和 Git。
如果生成的 PoC 脚本一直失败会怎样？自愈循环最多重试三次（报错、根因映射、自动修复、重新执行）；如果第二次出现同样形态的失败，智能体必须放弃该方法并退回重新分类，而不是尝试第三种变体。
支持哪些操作系统？Windows 10/11 x64 是推荐目标平台，兼容的 Linux 和 macOS 环境可通过 Bash 安装器获得支持。
它需要联网才能工作吗？不需要，所有工具链（约 251 MB）都已预先捆绑，初始安装之后运行时零网络依赖。
GPL-3.0 许可证有什么附带条件吗？有，它采用 GPL-3.0，并且明确构建在其他 GPL-3.0 安全研究项目之上，因此衍生作品继承同样的 copyleft 义务。
lab 模式是什么？为什么需要激活它？lab 模式是一个存盘的状态标志，为安全测试解锁术语自动映射和抗拒答覆盖；它在切换模型后依然保留，而 lab 模式之外的正常聊天不受影响。
CWE-602 审计实际如何判定授权是在服务器端还是本地？它使用飞行模式测试、回环劫持和时间戳偏移检查，来判定一个功能开关是由本地布尔值决定还是由服务器决定，通常几分钟内就能完成。
23 个内置 MCP 工具分成哪几组？健康检查、Radare2 二进制分析、Android 工具（JADX/Apktool/Frida）、一个含 289 篇日志的知识库搜索，以及 seepautotriage 和 seepgensecurityreport 等编排工具。
用它测试目标需要明确的授权吗？需要，Agent Execution Contract 强制一个 G-Auth 闸门：在每个新目标上开展任何工作之前，都要求已确认的测试授权。
What are similar projects?rea, ablation, dsh-redteam-model, rea, ida-pro-mcp, awesome-reverse-engineering, reverse-skill, T3MP3ST
Which topics is it in?mcp-tools, pi-agent, decompiler, malware-analysis, ctf, binary-analysis, vulnerability, lua, pentesting, penetration-testing, static-analysis, dsh
Creator
angusdevgo
Size
214.7 MB
Stars
1.7K
Updated
CommitOct 16
Age
25d
Commits · 90 Days