How to Perform Pentesting Using reverse-skill: A Complete Guide to Automated Security Testing

To perform pentesting using reverse-skill, initialize an authorized case with case-init.sh, route tasks through the master-route script to the pentest-tools skill, execute reconnaissance and vulnerability scans via MCP backends, and generate auditable reports from the collected timeline.

reverse-skill is a platform-neutral routing package designed to guide AI agents and human operators through structured penetration testing workflows. According to the zhaoxuya520/reverse-skill source code, the framework enforces safe execution order through a single source of truth (skills/config/routing.json) and automated evidence collection, ensuring every scan remains within authorized scope.

Core Architecture of reverse-skill for Pentesting

The framework separates concerns into distinct layers that handle routing, authorization, tool execution, and reporting.

The Routing Core and Configuration

At the heart of the system lies skills/config/routing.json, which maps task keywords to appropriate skill modules. The fast-path entry point is skills/MASTER-ROUTING.md, which reads RULES.md to determine dispatch logic. When you submit a task like "perform a full port scan," the router matches keywords against 43 predefined routing entries and forwards the request to the pentest-tools skill.

Authorization and Case Guards

Before any ACT step executes, the framework checks for a valid scope.md file via the case-init scripts (skills/scripts/case-init.ps1 or case-init.sh). This enforces the auth = granted gate, preventing unauthorized scanning against out-of-scope targets. The script creates the work/<case>/scope.md structure that serves as the authorization boundary for the entire engagement.

Tool Index and MCP Backend

The Tool Index (skills/tool-index.md) provides an auto-generated catalog of locally detected tools and MCP servers. The MCP Backend exposes binaries as HTTP services, allowing agents to invoke tools like Nmap or SQLMap via API rather than direct shell execution. This abstraction supports Docker-based pentestMCP, modular mcp-security-hub, or single-tool MCPs as documented in skills/pentest-tools/SKILL.md.

Preparing Your Environment

Before launching scans, you must initialize the workspace and refresh the tool inventory.

Refreshing the Tool Index

Detect available penetration testing tools and MCP servers:

bash skills/scripts/refresh-tool-index.sh

This updates skills/tool-index.md with available binaries and service endpoints, ensuring the routing layer knows which backends are ready.

Initializing a Pentest Case

Create a new engagement with proper authorization documentation:

bash skills/scripts/case-init.sh --hint "Pentest example.com"

This generates work/example.com/scope.md and enforces the authorization gate. Without this step, the master-route script refuses to dispatch pentesting tasks.

The Pentesting Workflow in reverse-skill

reverse-skill orchestrates the standard recon → vuln-scan → exploit → post-exploitation loop while maintaining an audit trail.

Phase 1: Task Routing and Reconnaissance

Submit the primary routing request to activate the pentest-tools skill:

bash skills/scripts/master-route.sh --hint "Full port scan of example.com"

The skill automatically executes the reconnaissance pipeline defined in references/recon-pipeline.md:

1. Network mapping: nmap -sV -sC -O example.com
2. Subdomain enumeration: subfinder -d example.com
3. HTTP service detection: httpx -l subdomains.txt -status-code

Each command runs through the MCP API, with outputs stored in timeline.md via skills/scripts/append-evidence.ps1.

Phase 2: Vulnerability Scanning

The framework invokes scanners based on target type:

nuclei -u live.txt -t ~/nuclei-templates/ -severity critical,high

Alternative tools like ZAP or Nikto are selected according to the service fingerprinting results from the recon phase.

Phase 3: Controlled Exploitation

Tools such as SQLMap, FFUF, or Metasploit are called only after explicit confirmation from the operator or agent:

sqlmap -u "http://example.com/vuln?id=1" --batch --dbs

This confirmation gate, defined in references/pentest-loop.md, ensures exploitation attempts occur only after vulnerability verification.

Phase 4: Evidence Collection

Every command and output is appended to the case timeline using:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/append-evidence.ps1 \
  -Command "nmap -sV -sC -O example.com" -OutputFile "evidence/nmap.txt"

This evidence-first mindset guarantees traceability for post-mortem analysis and compliance reporting.

Generating Pentest Reports

Once the assessment loop completes, the docs-generator skill consumes timeline.md and produces professional deliverables:

bash skills/scripts/generate-report.sh --case example.com

The generator parses the structured timeline into markdown or HTML formats suitable for client delivery, including executive summaries and technical findings.

Summary

• reverse-skill uses skills/config/routing.json as the single source of truth for dispatching pentesting tasks to the appropriate skill modules.
• Authorization gates in skills/scripts/case-init.sh prevent scanning without explicit scope approval documented in scope.md.
• The MCP Backend abstracts tool execution through HTTP APIs, supporting Docker-based or modular server architectures.
• Evidence collection happens automatically via skills/scripts/append-evidence.ps1, ensuring every command is auditable.
• The pentest-tools skill enforces a structured workflow: reconnaissance, vulnerability scanning, controlled exploitation, and report generation.

Frequently Asked Questions

What is the minimum setup required to start pentesting with reverse-skill?

You need to clone the repository, run skills/scripts/refresh-tool-index.sh to detect available tools, and execute skills/scripts/case-init.sh to create an authorized case with a valid scope.md file. Without the authorization gate satisfied, the master router will refuse to dispatch pentesting tasks.

How does reverse-skill prevent unauthorized scanning?

The framework implements a Case Guard layer that checks for auth = granted in scope.md before any ACT step. The case-init scripts enforce this gate, ensuring the target network profile is explicitly defined and approved before the routing layer forwards commands to the pentest-tools skill.

Can I use reverse-skill with AI agents other than Claude?

Yes. The architecture is client-neutral and works with Claude Code, Codex, Cursor, OpenCode, or any other AI agent that can execute shell commands. The routing logic resides entirely in the repository's markdown and JSON files, requiring no client-specific code or plugins.

What tools does the pentest-tools skill support?

The skill supports a comprehensive toolbox including Nmap, Nuclei, SQLMap, FFUF, Subfinder, httpx, ZAP, Nikto, and Metasploit. The specific availability depends on your local installation or MCP server configuration as documented in skills/tool-index.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}