reverse-skill

1. Project Overview

reverse-skill is a cybersecurity skills router that guides AI coding agents (and the humans working alongside them) through structured, repeatable workflows for reverse engineering, penetration testing, and CTF-style security tasks — replacing ad-hoc guesswork with a rule-based routing system that selects the right methodology and tools for a given target.

2. Background & Positioning

• Core mission: AI agents are increasingly asked to analyze APKs, binaries, encrypted JavaScript, firmware, or run CTF challenges, but they generally lack a systematic way to decide which technique or tool applies to which situation. reverse-skill closes this gap by encoding expert routing logic — "User task → RULES.md → MASTER-ROUTING → case initialization → scenario-specific skill → evidence collection → reporting" — so that agents follow a consistent, auditable path instead of improvising.
• Differentiation: Rather than being a single tool or wrapper around one utility, reverse-skill is a routing and orchestration layer sitting on top of the existing security tooling ecosystem (jadx, apktool, Frida, Burp, YARA, and more). Its value lies in the 43 routing rules and 173 regression tests that keep task classification consistent, plus a client-neutral design that works the same way across Claude Code, Cursor, Cline, and other AI coding environments.

3. Feature Categories

• 📱 Mobile Analysis — APK and iOS app analysis; representative skills include static decompilation, dynamic instrumentation, and certificate/signature inspection. Purpose: uncover app behavior and vulnerabilities in mobile binaries.
• 🧩 Binary Reverse Engineering — Handling of ELF, EXE, DLL, and SO files; disassembly, symbol recovery, and control-flow analysis. Purpose: turn compiled binaries back into understandable logic.
• 🔐 .NET / C# Decompilation — Recovery of source-level structure from .NET assemblies. Purpose: analyze managed-code applications without original source.
• 🕸️ JavaScript Encryption Analysis — Deobfuscation and decryption-routine tracing for frontend/web JavaScript. Purpose: understand client-side encryption logic used by web apps and APIs.
• 🛡️ Malware Detection & YARA — Signature-based and behavioral malware analysis. Purpose: classify and detect malicious samples using YARA rules.
• 🎯 Penetration Testing & Scanning — Structured scanning and exploitation workflows for authorized targets. Purpose: assess exposure of systems under an explicit test scope.
• 🏁 CTF Competitions — 42 dedicated CTF sub-skills covering common challenge categories (pwn, crypto, web, reverse, forensics). Purpose: provide competition-ready workflows for capture-the-flag events.
• 🔌 Firmware & IoT Assessment — Extraction and analysis of embedded firmware images. Purpose: evaluate IoT device security posture.
• 💥 Exploit Development & Pwn Chains — Guided construction of proof-of-concept exploit chains. Purpose: validate vulnerability impact in controlled environments.
• 🌐 API & GraphQL Security — Endpoint discovery and authorization/logic testing for APIs. Purpose: identify insecure API design and access-control gaps.
• 📦 Supply Chain Analysis — Dependency and build-pipeline inspection. Purpose: detect tampering or malicious packages in the software supply chain.
• 🤖 LLM / AI Security — Assessment of prompt injection, model abuse, and agent-specific attack surfaces. Purpose: extend traditional security review to AI-powered systems.

4. Key Highlights

• Rule-based routing engine — 43 routing rules (R0–R44) defined in routing.json act as the single source of truth for how tasks are classified and dispatched.
• Regression-tested reliability — 173 regression test cases validate routing decisions, reducing the risk that a rule change silently breaks an existing workflow.
• Cross-platform CI — Automated validation on both Windows and Ubuntu ensures routing and scripts behave consistently across operating systems.
• Client-neutral design — Works uniformly across Claude Code, Cursor, Cline, and other AI coding assistants, so teams aren't locked into one agent platform.
• Structured case lifecycle — Every task flows through case initialization, evidence collection, and reporting, producing auditable output rather than one-off scratch work.
• Explicit authorization gates — RULES.md enforces scope and authorization checks before any offensive-style workflow proceeds, keeping usage aligned with authorized testing only.

5. Use Cases by Role

• General developers: Use the JavaScript encryption analysis and .NET decompilation skills to understand third-party code or debug obfuscated dependencies.
• Security engineers / penetration testers: Leverage the full routing system — mobile, binary, API, and exploit-development skills — to run consistent, well-documented engagements against authorized targets.
• CTF players: Use the 42 CTF sub-skills as a ready-made playbook for pwn, crypto, web, reverse, and forensics challenge categories.
• AI agent builders: Integrate reverse-skill as a routing layer so that any Claude Code / Cursor / Cline-based agent can reliably pick the right security methodology instead of guessing.

6. Getting Started

Find what you need — start from the routing entry points:

cat MASTER-ROUTING.md
cat RULES.md

Install / integrate — clone the repository and run the platform-specific refresh script to detect available security tools (requires JDK, Node.js 22.12+, and Python 3.x):

git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill
# run the refresh script for your platform, e.g.:
./scripts/refresh.sh        # Kali/Ubuntu/macOS
scripts/refresh.ps1         # Windows

Contribute — standard fork-and-PR workflow:

git checkout -b feature/my-skill
git commit -m "Add my-skill"
git push origin feature/my-skill
# then open a Pull Request on GitHub

7. Project Structure

reverse-skill/
├── skills/              # Core routing rules, workflows, and domain-specific skills
├── CTF-Sandbox/         # 42 CTF sub-skills (GPLv3-licensed orchestrator)
├── scripts/             # Master routing, case initialization, and test scripts
├── docs/                # Platform-specific guidance (Kali, Ubuntu/Debian, macOS)
└── work/                # Local case data (gitignored)

Key files:

• MASTER-ROUTING.md — the primary fast-track routing ladder for incoming tasks.
• routing.json — single source of truth for the 43 routing rules.
• README_AI.md — bootstrap instructions written specifically for AI agents.
• RULES.md — global scope gates and authorization checks that must pass before any skill executes.

8. Related Ecosystem

• Upstream tools it wraps or depends on: jadx and apktool (Android decompilation), Frida (dynamic instrumentation), Burp Suite (web/API testing), YARA (malware signatures).
• AI agent platforms it integrates with: Claude Code, Cursor, Cline, and other compatible AI coding environments.
• Complementary infrastructure sponsors: Atlas Cloud (AI inference platform) and Kite AI (identity/payment infrastructure for the agent economy) support the project's operation.

9. License

• ✅ Use, copy, modify, and distribute the core project under the MIT License, including for commercial purposes, provided the copyright notice is retained.
• ✅ Use the CTF-Sandbox-Orchestrator component, which is separately licensed under GPLv3 — copyleft terms apply if you redistribute modified versions.
• ❌ Do not use any skill in this project against systems you do not own or lack explicit authorization to test — this is a hard requirement stated in the project's own rules, not just a general legal caveat.
• ℹ️ Bundled or referenced third-party tools (jadx, Frida, Burp, etc.) retain their own original licenses, which may differ from MIT/GPLv3 and should be reviewed separately.

10. FAQ

Q: Do I need all the prerequisite tools installed before using reverse-skill?
A: No — the refresh scripts (scripts/refresh.sh / scripts/refresh.ps1) detect which tools are already available on your system and route tasks accordingly; missing tools are reported rather than assumed.

Q: Can I use reverse-skill for real-world penetration testing, not just CTFs?
A: Yes, but only against systems you own or have explicit written authorization to test — this is enforced by the scope and authorization gates in RULES.md.

Q: Which AI coding assistants does this work with?
A: The routing system is client-neutral and has been validated with Claude Code, Cursor, and Cline; any compatible AI coding environment should be able to consume the same routing files.

Q: Why does the CTF-Sandbox-Orchestrator use a different license (GPLv3) than the rest of the project (MIT)?
A: It's a separately maintained submodule with its own licensing decision; check the license file inside CTF-Sandbox/ before redistributing that component specifically.

Q: How do I add a new skill or routing rule?
A: Fork the repository, add your skill under skills/ (or CTF-Sandbox/ for CTF-specific ones), update routing.json if a new rule is needed, ensure the regression tests pass, and open a pull request.

11. Quick Links

• Repository: https://github.com/zhaoxuya520/reverse-skill
• Routing entry point: MASTER-ROUTING.md (in the repository root)
• Contributing: standard GitHub fork-and-pull-request workflow (see repository root for any CONTRIBUTING guidance)
• Community/discussions: GitHub Issues and Pull Requests on the repository

12. Summary

reverse-skill turns ad-hoc, trial-and-error security analysis into a structured, rule-driven workflow that AI agents and human practitioners can follow consistently across mobile, binary, web, firmware, and CTF domains. It is best suited for security engineers, CTF participants, and AI agent builders who need reliable, auditable routing between security tasks and the right tools — always within the bounds of authorized testing.