pentest

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:

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:

/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