reverse-workbench-skill

Readme

<p align="center">
  <img src="reverse-skill.png" alt="reverse-workbench-skill" width="140" />
</p>

<h1 align="center">reverse-workbench-skill</h1>
<h3 align="center">Pi-oriented Cybersecurity Skills Router · 逆向技能路由包</h3>

<p align="center"><em style="font-family: Georgia, serif; font-size: 1.2em; color: #777;">Navigate the dark waters, sail against the stream.</em></p>

<p align="center">
  <a href="https://github.com/Asaiuta/reverse-workbench-skill"><img src="https://img.shields.io/badge/release-v1.0.0-blue" alt="release"></a>
  <a href="https://github.com/Asaiuta/reverse-workbench-skill/stargazers"><img src="https://img.shields.io/github/stars/Asaiuta/reverse-workbench-skill?style=flat&logo=github" alt="stars"></a>
  <a href="https://github.com/Asaiuta/reverse-workbench-skill/forks"><img src="https://img.shields.io/github/forks/Asaiuta/reverse-workbench-skill?style=flat&logo=github" alt="forks"></a>
  <a href="https://github.com/Asaiuta/reverse-workbench-skill/issues"><img src="https://img.shields.io/github/issues/Asaiuta/reverse-workbench-skill?style=flat&logo=github" alt="issues"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-Keep%20a%20Changelog-orange" alt="changelog"></a>
</p>

<br/>

<p align="center">
  <a href="#about">About</a> ·
  <a href="#getting-started">Getting Started</a> ·
  <a href="#usage">Usage</a> ·
  <a href="skills/MASTER-ROUTING.md">Fast route</a> ·
  <a href="skills/routing.md">Routing</a> ·
  <a href="skills/ops/">Ops contracts</a> ·
  <a href="README_AI.md">AI Bootstrap</a> ·
  <a href="#contributing">Contributing</a>
</p>

<p align="center">
  🌐 <a href="README_zh.md">中文</a>
</p>

<br/>

<a id="about"></a>

## About

> **If you are an AI Agent, jump to [README_AI.md](README_AI.md) and follow the instructions strictly.**
>
> **Agent-harness users:** this is a standard **Agent Skills** bundle. Install it once with `scripts/install-skill.ps1` (Windows) or `scripts/install-skill.sh` (Unix) — the shared location `~/.agents/skills/` is picked up by **pi**, **Codex CLI**, and **DSH**; `--claude` also mirrors it for **Claude Code**. See [跨 Agent 支持](#cross-agent-support).

This repository is an independently maintained, cross-agent reverse-engineering and security-analysis skill router — archive triage, reproducible Ghidra-headless exports, HTTP/service fingerprinting, and a domain skill matrix. It no longer tracks any upstream codebase and follows its own release line.

When an AI agent (Claude Code, Codex CLI, Cursor, etc.) encounters an APK, a binary, frontend JS encryption, a CTF challenge, or a pentesting target, this package routes it to the right methodology, checks available tools, and executes a repeatable workflow instead of guessing commands.

```
User task
  → RULES.md
  → MASTER-ROUTING / master-route.ps1 (PRIMARY)
  → case-init / scope.md (auth + network_profile; no target ACT until ready)
  → Scenario skill → tools / MCP / scripts
  → timeline + Evidence→Finding→Path → report + field-journal
```

**Why this exists:**
- AI agents don't know whether to use jadx, apktool, Frida, IDA, or BurpSuite for a given task
- APK, ELF, JS, PCAP, and CTF tasks each need different playbooks
- Tools, MCP servers, and scripts are scattered across machines
- The same mistakes get repeated because experience isn't reused

PRIMARY ladder: [skills/MASTER-ROUTING.md](skills/MASTER-ROUTING.md) · Full matrix: [skills/routing.md](skills/routing.md) · Ops: [skills/ops/](skills/ops/)


<p align="right">(<a href="#about">back to top</a>)</p>

### Built With

<p align="left">
  <img src="https://skillicons.dev/icons?i=py,nodejs,powershell,bash,java,docker,git&theme=light" /><br/>
  <code>IDA Pro</code> · <code>radare2</code> · <code>Ghidra</code>
</p>

<p align="right">(<a href="#about">back to top</a>)</p>

<a id="getting-started"></a>

## Getting Started

### Prerequisites

- **Java / JDK** — for jadx and apktool
- **Node.js 22.12+** — for JS toolchain and MCP servers
- **Python 3.x** — for Frida and helper scripts
- **A code AI client** — Claude Code, Codex CLI, Cursor, etc.

### Installation

```bash
git clone https://github.com/Asaiuta/reverse-workbench-skill.git
cd reverse-workbench-skill
```

Install the skill bundle for your agent harness(es):

| Host | Install | Invocation |
|------|---------|-----------|
| **pi** | `powershell -File scripts/install-skill.ps1` ^(Win) / `bash scripts/install-skill.sh` (Unix) | `/skill:reverse-workbench-skill`（`/reload` 后生效） |
| **Codex CLI** | 同上（默认位置 `$HOME/.agents/skills` 即 Codex USER scope） | `/skills` 或 `$reverse-workbench-skill` |
| **DSH** | 同上（DSH user-agents scope，rank 500）；项目级可用 `--project <dir>`（`<dir>/.agents/skills`，rank 200） | web 端 skill 目录 / skill 工具 |
| **Claude Code** | 追加 `-Claude`(Win) / `--claude`(Unix) 参数 | `/skills`（重启后生效） |
| **其他 Agent Skills 宿主** | 将 `SKILL.md` 所在目录复制到对应 skills 目录 | 依宿主而定 |

> 单机只需安装一次：pi / Codex CLI / DSH 共用 `~/.agents/skills/reverse-workbench-skill/`。技能保持**仅显式调用**（`disable-model-invocation: true`，Codex 侧为 `allow_implicit_invocation: false`）。

<a id="cross-agent-support"></a>

### Cross-Agent Support

| 宿主 | 发现位置 | 优先级/特性 |
|------|----------|-------------|
| pi | `~/.agents/skills/`、`~/.pi/agent/skills/` | `/skill:<name>` 命令，`disable-model-invocation` |
| Codex CLI | `$CWD/.agents/skills`(REPO) → `$HOME/.agents/skills`(USER) → `/etc/codex/skills`(ADMIN) | 支持 symlink；自动检测变更 |
| DSH | `<root>/.dsh/skills`(100) → `<root>/.agents/skills`(200) → `$DSH_HOME/skills`(400) → `~/.agents/skills`(500) | `ctx.skills` 注册表 + skill 工具；`disable-model-invocation` |
| Claude Code | `~/.claude/skills/`、项目 `.claude/skills/` | `/skills` 选择器 |

Then refresh the tool index per platform:

| Platform | Command |
|----------|---------|
| Windows | `powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1` |
| Linux / macOS | `bash skills/scripts/refresh-tool-index.sh` |
| Kali Linux | `bash kali/scripts/refresh-tool-index.sh` |

Check [skills/tool-index.md](skills/tool-index.md) to see detected tools.

Platform-specific docs:
- **Kali Linux** → [kali/README-kali.md](kali/README-kali.md)
- **Ubuntu/Debian** → [docs/platforms/linux.md](docs/platforms/linux.md)
- **macOS** → [docs/platforms/macos.md](docs/platforms/macos.md)

<p align="right">(<a href="#getting-started">back to top</a>)</p>

<a id="usage"></a>

## Usage

### Supported scenarios

| Scenario | Entry |
|----------|-------|
| APK / Android analysis | `skills/apk-reverse/` |
| iOS / mobile | `skills/mobile-reverse/` |
| Unknown file / archive / evidence bundle | `skills/archive-file-triage/` |
| Reproducible Ghidra batch exports | `skills/ghidra-headless/` |
| Ghidra reverse engineering | `skills/ghidra-reverse/` |
| HTTP liveness / TLS / service fingerprinting | `skills/pentest-tools/observer-ward/` |
| Binary reverse (exe/dll/so/elf) | `skills/ida-reverse/` / `skills/radare2/` |
| .NET / C# | `skills/dotnet-reverse/` |
| Frontend JS / encrypted params | `skills/js-reverse/` |
| DSL VM / custom JS opcode VM | `skills/reverse-engineering/dsl-vm-reverse/` |
| HTTP capture / request replay | anything-analyzer + `js-reverse/` |
| Malware / YARA | `skills/malware-analysis/` |
| Penetration testing / scanning | `skills/pentest-tools/` |
| Attack chain / red-team orchestration | `skills/attack-chain/` |
| CTF competition | `CTF-Sandbox-Orchestrator/` (40+ sub-skills) |
| Firmware / IoT | `skills/firmware-pentest/` |
| Patch diff / N-day | `skills/patch-diff-exploit/` |
| Cross-version symbol migration / DWARF recovery | `skills/binary-diff/` |
| Linux/ELF DWARF symbol recovery | `skills/binary-diff/references/dwarf-symbol-recovery.md` |
| Pwn / exploit development | `skills/pwn-chain/` |
| Binary-mitigation strategy matrix (`checksec` → approach) | `skills/pwn-chain/references/protection-bypass-matrix.md` |
| EDR bypass | `skills/edr-bypass-re/` |
| API / GraphQL | `skills/api-security/` |
| Supply chain / SBOM | `skills/supply-chain-security/` |
| LLM / AI security | `skills/llm-security/` |
| OLLVM deobfuscation | `skills/reverse-engineering/references/ollvm-deobfuscation.md` |
| Diagrams / reports | `skills/diagram-generator/` / `skills/docs-generator/` |

### Key files

| File | Purpose |
|------|---------|
| [README_AI.md](README_AI.md) | AI agent bootstrap and configuration |
| [RULES.md](RULES.md) | Global routing rules (scope gate before ACT) |
| [skills/MASTER-ROUTING.md](skills/MASTER-ROUTING.md) | PRIMARY fast ladder |
| [skills/routing.md](skills/routing.md) | Task → skill routing matrix |
| [skills/SKILL.md](skills/SKILL.md) | Master entry point |
| [skills/tool-index.md](skills/tool-index.md) | Local tool status (auto-generated) |
| [skills/scripts/master-route.ps1](skills/scripts/master-route.ps1) | One-shot PRIMARY triage |
| [skills/scripts/case-init.ps1](skills/scripts/case-init.ps1) | Case dir: scope / timeline / workitems |
| [skills/ops/](skills/ops/) | Scope, Evidence chain, roles, timeline (skill-router form) |

### Repository layout

```
.
├── README.md / README_zh.md / README_AI.md
├── RULES.md / RULES_zh.md
├── skills/
│   ├── MASTER-ROUTING.md / SKILL.md / routing.md
│   ├── ops/                   # ops contracts
│   ├── scripts/               # master-route, case-init, bootstrap, verify
│   ├── field-journal/
│   ├── apk-reverse/ mobile-reverse/ js-reverse/ dotnet-reverse/
│   ├── ida-reverse/ radare2/ reverse-engineering/ malware-analysis/
│   ├── pentest-tools/ attack-chain/ pwn-chain/ firmware-pentest/
│   ├── api-security/ supply-chain-security/ llm-security/
│   └── ...
├── CTF-Sandbox-Orchestrator/
├── docs/
├── kali/                      # see kali/README-kali.md
└── work/                      # local cases (gitignored)
```

<p align="right">(<a href="#usage">back to top</a>)</p>

<a id="contributing"></a>

## Contributing

Contributions are welcome! Fork the repo, create a feature branch, and open a PR.

1. Fork the Project
2. `git checkout -b feature/AmazingFeature`
3. `git commit -m 'Add some AmazingFeature'`
4. `git push origin feature/AmazingFeature`
5. Open a Pull Request

<a id="license"></a>

## License

`reverse-workbench-skill` is licensed under the **MIT License** (see [LICENSE](LICENSE)). The methodology originated from the reverse-skill skill router; per MIT terms its copyright notice is retained in the LICENSE file.

**Bundled components and third-party dependencies:**
- **CTF-Sandbox-Orchestrator/** is distributed under **GNU GPLv3**.
- **Pentest Swarm AI**: Original project is **AGPL-3.0**. This repo only invokes it via CLI or MCP and does not include its source code
- Other tools (jadx, frida, nmap, burpsuite-mcp, etc.) are subject to their respective official licenses

<p align="right">(<a href="#license">back to top</a>)</p>

<a id="acknowledgments"></a>

## Acknowledgments

Thanks to all open-source tool authors. This project integrates tools across reverse engineering, penetration testing, CTF, and security analysis — every tool is the fruit of community effort.

Special thanks to the OLLVM deobfuscation ecosystem and everyone who helped validate samples, report issues, and improve the project.

<p align="right">(<a href="#acknowledgments">back to top</a>)</p>