---
name: pentest
description: >-
  Authorized pentest planning with mandatory ROE scope gate. Synthesizes phase
  checklists and findings. NOT for static audit (security-scanner), CTF
  labs (ctf-*), or C2/webshell tooling.
argument-hint: "<doctor|scope|triage|recon|web|api|osint|network|cloud|mobile|wireless|llm|internal|binary|blockchain|post-exploit|validate|report|help> [target]"
model: opus
license: MIT
user-invocable: true
metadata:
  author: wyattowalsh
  version: "2.1.0"
---

# Pentest

Synthesis skill for **authorized** offensive-security engagements. Produces
scope-gated plans, checklists, and structured findings — never vendored C2,
webshells, or autonomous exploit execution.

**Scope:** Pre-authorized penetration testing methodology and reporting. NOT for
unauthorized testing, malware/C2 operations, static pre-deploy audits
(security-scanner), or synthetic CTF-only puzzles (ctf-*).

## Canonical Vocabulary

| Term | Definition |
|------|------------|
| **ROE** | Rules of Engagement — signed authorization document defining targets, dates, contacts, and prohibited actions |
| **scope gate** | Mandatory `scope_check.py` pass before any recon, web, API, or OSINT offensive planning |
| **target** | Host, URL, CIDR, or application explicitly listed in the signed ROE |
| **phase** | Engagement stage from `scripts/phases.py` — each requires an active scope gate |
| **triage** | Route a signal to canonical playbook + optional external skill via `methodology-router.md` |
| **external index** | Planning lock `pentest-external-skill-index.json` via manifest + `lookup_external_slug.py` |
| **finding** | Structured JSON record of a suspected issue with severity, evidence, and remediation guidance |
| **playbook** | Checklist-driven methodology loaded from `references/playbooks/` — planning only |
| **synthesis** | Agent-authored plan/checklist/report assembled from references and operator context |
| **external runner** | Optional third-party CLI (e.g. Strix) the operator runs manually — this skill does not install or invoke attacks |
| **fail-closed** | Deny all offensive planning when scope is missing, expired, or target-out-of-scope |

## Tier Boundaries

| Tier | Skill | When to use | ROE required | Executes attacks |
|------|-------|-------------|--------------|------------------|
| **Static audit** | security-scanner | Pre-deployment SAST, secrets, deps, compliance heuristics | No | No — read-only code scan |
| **Authorized pentest** | pentest (this skill) | Live apps/APIs under signed engagement | **Yes** | No — planning/checklists only; operator runs approved tools |
| **CTF / lab** | ctf-* | Isolated challenge boxes, training flags, synthetic vuln labs | No (lab policy instead) | Only inside designated lab scope |

**Redirect rules:**

- "Scan my repo for secrets/CVEs before merge" → **security-scanner**
- "Hack this site without permission" → **refuse** — no ROE, no planning
- "Solve this HTB/CTF box" → **ctf-*** skills — not production pentest
- "We have signed ROE for staging.example.com" → **pentest** after scope gate

## Scope Gate (Mandatory)

Before **recon**, **web**, **api**, **osint**, or any extended phase mode (`network`, `cloud`, `mobile`, `wireless`, `llm`, `internal`, `binary`, `blockchain`, `post-exploit`):

1. Obtain `--target`, `--roe-file`, and the requested `--phase` from the operator.
2. Run:

```bash
uv run python scripts/scope_check.py \
  --target "<host-or-url>" \
  --roe-file "<path-to-roe.json>" \
  --phase "<mode>"
```

3. Parse JSON stdout. If `ok` is false or exit code is non-zero → **stop**. Present
   `deny_reason` and load `references/scope-and-roe.md` for remediation.
4. Record `engagement_id`, `phase`, and `allowed_phases` from the scope result in session notes.
5. Never proceed to playbooks, external runners, or attack-sounding commands without
   a passing scope gate in the current session.

**Empty or partial scope requests** (target without ROE, ROE without target, expired
ROE, out-of-scope host) are denied fail-closed.

## Dispatch

| $ARGUMENTS | Mode | Action |
|------------|------|--------|
| `doctor` | doctor | Run `scripts/doctor.py` — skill asset and policy readiness |
| `scope <target>` | scope | Run `scripts/scope_check.py` with `--roe-file`, `--target`, and `--phase`; echo `restricted_phases` when ROE-gated |
| `triage <signal>` | triage | Load `references/methodology-router.md`; map signal → playbook + external slug |
| `recon <target>` | recon | Scope gate → `references/playbooks/recon.md` |
| `web <target>` | web | Scope gate → `references/playbooks/web.md` (+ injection/auth playbooks as needed) |
| `api <target>` | api | Scope gate → `references/playbooks/api.md` |
| `osint <target>` | osint | Scope gate → `references/playbooks/osint.md` (passive only per ROE) |
| `network <target>` | network | Scope gate → `references/playbooks/network.md` |
| `cloud <target>` | cloud | Scope gate → `references/playbooks/cloud.md` |
| `mobile <target>` | mobile | Scope gate → `references/playbooks/mobile.md` |
| `wireless <target>` | wireless | Scope gate → `references/playbooks/wireless.md` (explicit ROE) |
| `llm <target>` | llm | Scope gate → `references/playbooks/llm.md` |
| `internal <target>` | internal | Scope gate → `references/playbooks/internal.md` |
| `binary <target>` | binary | Scope gate → `references/playbooks/binary.md` |
| `blockchain <target>` | blockchain | Scope gate → `references/playbooks/blockchain.md` |
| `post-exploit <target>` | post-exploit | Scope gate → `references/playbooks/post-exploit.md` (explicit ROE only) |
| `validate` | validate | Run `scripts/check.py`; verify findings JSON against schema |
| `report` | report | Aggregate session findings via `scripts/findings_emit.py` patterns |
| `help` or *(empty)* | help | Show modes, scope gate, tier boundaries, reference index |
| Unrecognized | — | Ask for clarification; do not assume authorization |

## Mode: doctor

Read-only environment and policy checks. No offensive actions.

1. Run: `uv run python scripts/doctor.py --format json`
2. When the skill is globally installed, set `WAGENTS_REPO_ROOT` to the agents clone so
   `repo-root` and lock-index checks can resolve `planning/research-lock/`.
3. Present checks grouped by `ok`, `warn`, `fail`.
4. If `forbidden-tooling` is `fail`, stop — engagement cannot use this skill until
   operator removes C2/webshell references from the request.
5. Load `references/external-runners.md` only when operator asks about optional CLIs.

## Mode: scope

Validate authorization before any other offensive mode.

1. Require `--target`, `--roe-file`, and `--phase`. If any are missing, run
   `scope_check.py` without them to produce the deny JSON and explain required fields.
2. On pass: summarize `engagement_id`, `phase`, `allowed_phases`, `restricted_phases`,
   `expires_at`, and in-scope target match.
3. On deny: cite `deny_reason`; do not load playbooks.

## Mode: triage

Route methodology depth without loading all upstream repos.

1. Parse signal from `$ARGUMENTS` (e.g. `sqli`, `xss`, `kerberos`, `llm-injection`).
2. Load `references/methodology-router.md` — resolve canonical slug from dedup table.
3. Load matching `references/playbooks/*.md` section (one file at a time).
4. Surface `install_command` via `scripts/lookup_external_slug.py` only when operator requests deeper upstream body.
5. **Quarantine:** EXT-084 entries are inspect-only — never auto-install.

## Mode: recon

Post-authorization attack-surface **planning** only.

1. Pass scope gate (see Scope Gate).
2. Confirm `recon` is in `allowed_phases` from scope result.
3. Load `references/playbooks/recon.md` (and `references/osint.md` when passive).
4. Produce a phased plan: asset inventory hypotheses, DNS/WHOIS/certificate angles,
   technology fingerprinting **commands the operator may run** — do not run them from
   this skill's scripts.
5. Emit planned checkpoints as draft findings only after operator supplies evidence.

## Mode: web

Web application testing **planning** only.

1. Pass scope gate; confirm `web` in `allowed_phases`.
2. Load `references/playbooks/web.md` one section at a time.
3. Build a prioritized test checklist mapped to OWASP categories — no exploit payloads
   executed by skill scripts.
4. For each confirmed issue the operator reports, emit via `findings_emit.py` (pass
   `--scope-json` from the current scope gate result when binding findings to engagement).

## Mode: api

API security testing **planning** only.

1. Pass scope gate; confirm `api` in `allowed_phases`.
2. Load `references/playbooks/api.md`.
3. Produce authn/authz, input validation, rate-limit, and BOLA test matrices.
4. Reference OpenAPI/GraphQL discovery steps for the operator; never call live targets
   from bundled scripts.

## Mode: osint

Passive open-source intelligence **planning** only.

1. Pass scope gate; confirm `osint` in `allowed_phases`.
2. Load `references/osint.md`.
3. Stay within ROE `prohibited_actions` — no social engineering, harassment, or
   out-of-scope third-party data collection.
4. Output source list, query templates, and verification steps for the operator.

## Mode: post-exploit

Post-exploitation **planning** only when ROE explicitly allows it.

1. Pass scope gate; confirm `post-exploit` in `allowed_phases` (see `restricted_phases` in scope JSON).
2. Load `references/playbooks/post-exploit.md`.
3. Produce containment-aware persistence/lateral-movement **planning matrices** — no C2
   install commands, implants, or live exploitation from bundled scripts.
4. Refuse C2/Havoc/Sliver/Cobalt Strike skill installs; document-only upstream references only.

## Mode: validate

Deterministic skill and findings validation.

1. Run: `uv run python scripts/check.py`
2. If validating ad-hoc findings JSON, compare against `references/findings-schema.md`.
3. Report validation status; do not mutate ROE or targets.

## Mode: report

Session report synthesis.

1. Collect findings emitted during the engagement (JSON lines or array).
2. Validate each record against `references/findings-schema.md`.
3. Group by severity; include scope metadata (`engagement_id`, `target`, ROE hash).
4. Use `scripts/findings_emit.py --aggregate` when normalizing operator-supplied notes.
5. Executive summary must state authorization basis and prohibited actions respected.

## Mode: help

1. Show dispatch table, scope gate steps, and tier boundary table.
2. List reference files with read-when guidance.
3. Remind: this skill does not install Strix or other runners — see
   `references/external-runners.md`.

### Help _(empty)_

Show dispatch table, scope gate steps, tier boundaries, and reference index. Offer examples:

```text
/pentest help
/pentest doctor
/pentest scope staging.example.com
/pentest recon staging.example.com
/pentest web https://staging.example.com/app
/pentest api https://staging.example.com/api
/pentest osint staging.example.com
/pentest validate
/pentest report
```

## Reference File Index

Load ONE reference at a time. Do not preload all references.

| File | Content | Read When |
|------|---------|-----------|
| `references/scope-and-roe.md` | ROE format, scope gate policy, deny reasons | Scope deny or ROE questions |
| `references/findings-schema.md` | JSON finding fields and severity rules | Emitting or validating findings |
| `references/methodology-router.md` | Compact signal → playbook → slug routing | `triage` or depth routing |
| `references/external-skill-index.manifest.json` | Pointer to planning-lock full index | Operator requests upstream body |
| `references/playbooks/*.md` | Phase and technique checklists (22 files) | Matching phase after scope pass |
| `references/osint.md` | Passive OSINT templates (legacy index) | `recon` or `osint` after scope pass |
| `references/provenance.md` | Synthesis sources, hybrid repos, no C2 policy | Methodology questions or audit trail |
| `references/external-runners.md` | Optional external CLIs (Strix, etc.) — no install | Operator asks about tooling |

## Scripts

| Script | When to Run |
|--------|-------------|
| `scripts/phases.py` | SSOT for `VALID_PHASES` (imported by scope/findings) |
| `scripts/scope_check.py` | **Always** before offensive planning — fail-closed without ROE |
| `scripts/doctor.py` | `doctor` mode or pre-engagement readiness |
| `scripts/findings_emit.py` | Emit or aggregate structured findings JSON (schema v1.1) |
| `scripts/lookup_external_slug.py` | Resolve signal/slug install metadata from planning lock |
| `scripts/validate_external_index.py` | Maintainer check for planning-lock index policy |
| `scripts/check.py` | `validate` mode or CI/skill maintenance |

## Critical Rules

1. **Scope gate first** — no recon, web, api, or osint planning without passing `scope_check.py`
2. **Fail-closed** — missing `--target` or `--roe-file` denies immediately
3. **No attack execution in scripts** — bundled Python is planning, validation, and JSON only
4. **No C2 or webshell vendoring** — refuse requests for implants, reverse shells, or malware staging
5. **No unauthorized testing** — without signed ROE, redirect to security-scanner (static) or refuse
6. **CTF is not pentest** — redirect synthetic lab work to ctf-* skills
7. **Operator-run tools only** — cite commands for the operator; skill scripts do not probe targets
8. **Respect ROE phases** — deny playbooks when phase not in `allowed_phases`
9. **Respect prohibited_actions** — DOS, social engineering, production data exfiltration when banned
10. **Structured findings** — use `findings_emit.py` and `references/findings-schema.md`
11. **Load ONE reference at a time** — progressive disclosure
12. **Present plan before deep checklist** — approval gate for invasive operator steps
13. **Never store live credentials** — redact secrets in findings and reports
14. **External runners are optional** — document in `external-runners.md`; never auto-install Strix
15. **Read-only ROE** — scripts validate ROE files; they do not create or modify authorization