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

> Learn to perform pentesting with reverse-skill. This guide covers initializing cases, routing tasks, running scans, and generating reports for automated security testing.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-24

---

**To perform pentesting using reverse-skill, initialize an authorized case with [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)**, which maps task keywords to appropriate skill modules. The **fast-path entry point** is [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), which reads [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file via the **case-init** scripts (`skills/scripts/case-init.ps1` or [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
bash skills/scripts/refresh-tool-index.sh

```

This updates [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
bash skills/scripts/case-init.sh --hint "Pentest example.com"

```

This generates [`work/example.com/scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) via `skills/scripts/append-evidence.ps1`.

### Phase 2: Vulnerability Scanning

The framework invokes scanners based on target type:

```bash
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:

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

```

This confirmation gate, defined in [`references/pentest-loop.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) and produces professional deliverables:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh) prevent scanning without explicit scope approval documented in [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) to detect available tools, and execute [`skills/scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh) to create an authorized case with a valid [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md).