Performing Penetration Testing
Overview
v3.0.0 of penetration-tester is a 25-skill pack. Each skill is
narrow and heavy-hitter compliant (≥250 LOC scripts, ≥2 reference
docs, 8-field SKILL.md frontmatter). This orchestrator routes
user intent to the right combination of narrow skills.
The 25 skills group into 7 clusters:
- Cluster 0 — this orchestrator
- Cluster 1 (5 skills) — Network / transport
- Cluster 2 (4 skills) — Information disclosure
- Cluster 3 (6 skills) — Source-code static analysis
- Cluster 4 (4 skills) — Dependency analysis
- Cluster 5 (3 skills) — Engagement governance
- Cluster 6 (3 skills) — Reporting
Cluster 5 + 6 are the v3 additions versus v2. Cluster 5 runs
BEFORE any scan and refuses to proceed if authorization is
missing or scope is malformed. Cluster 6 runs AFTER scans and
produces the deliverable artifacts (vulnerability report, OWASP
coverage report, executive summary, chain-of-custody archive).
Instructions
The orchestrator's job is intent routing — given a user utterance, decide which of the 25 narrow skills to invoke and in what order. Four steps:
Step 1 — Parse the user intent
Match the utterance against the intent-routing table below. The leftmost matching row determines the routing. If no exact match, default to the cluster-1-4 governance-first sequence and pare back based on context.
Step 2 — Run authorization-first
Before any cluster 1-4 scan invocation, run confirming-pentest-authorization. If it emits any CRITICAL finding, HALT — do not invoke any scan skill. The user must resolve the authorization issue before proceeding.
Step 3 — Run the matched skills in order
Invoke each skill from the routing-table row, in the listed order. Each skill emits its findings as JSON/JSONL/markdown via lib/report.py. Persist per-skill output into engagement/findings/<skill>-<date>.jsonl so the cluster 6 skills can consume them.
Step 4 — Compose deliverables
After scan skills complete, run cluster 6 in sequence: mapping-findings-to-owasp-top10, then composing-vulnerability-report, then generating-executive-summary, then recording-pentest-engagement for the chain-of-custody archive.
Intent routing (the table)
| User intent / trigger phrase | Skills to invoke (in order) |
|---|
| "pentest", "full security scan" | confirming-pentest-authorization → defining-pentest-scope → cluster 1-4 (all) → mapping-findings-to-owasp-top10 → composing-vulnerability-report → generating-executive-summary → recording-pentest-engagement |
| "check headers" / "scan URL" | confirming-pentest-authorization → checking-http-security-headers + analyzing-tls-config + detecting-ssl-cert-issues |
| "CORS check" | confirming-pentest-authorization → auditing-cors-policy |
| "check SSL" / "certificate" | analyzing-tls-config + detecting-ssl-cert-issues |
| "audit npm dependencies" | auditing-npm-dependencies |
| "audit python dependencies" / "pip-audit" | auditing-python-dependencies |
| "find vulnerable deps" | auditing-npm-dependencies + auditing-python-dependencies + tracing-transitive-vulnerabilities |
| "license check" / "GPL contamination" | checking-license-compliance |
| "find hardcoded secrets" / "credential scan" | scanning-for-hardcoded-secrets |
| "SQL injection scan" | detecting-sql-injection-patterns |
| "command injection scan" | detecting-command-injection-patterns |
| "code audit" / "static analysis" | cluster 3 (all 6 skills) |
| "OWASP scan" / "OWASP coverage" | cluster 1-4 → mapping-findings-to-owasp-top10 |
| "confirm authorization" / "verify ROE" | confirming-pentest-authorization |
| "define scope" / "generate allowlist" | defining-pentest-scope |
| "write report" / "generate exec summary" | composing-vulnerability-report → generating-executive-summary |
| "archive engagement" / "chain of custody" | recording-pentest-engagement |
When unsure which to invoke, prefer the governance-first sequence
(authorization + scope) and add cluster-1-4 skills based on what
the user described.
Full 25-skill index
Cluster 0 — Orchestration
performing-penetration-testing — this skill
Cluster 1 — Network / transport (5)
analyzing-tls-config — TLS protocol versions, cipher suites, HSTSdetecting-ssl-cert-issues — cert validity, expiry, chain integrityauditing-cors-policy — origin reflection, credential bypass, wildcardchecking-http-security-headers — CSP, HSTS, X-Frame-Options, etc.probing-dangerous-http-methods — TRACE, DELETE, PUT exposure
Cluster 2 — Information disclosure (4)
detecting-exposed-secrets-files — .env, .git, backup filesdetecting-debug-endpoints — /server-status, admin panelsfingerprinting-server-software — Server-header version exposuredetecting-directory-listing — Apache/nginx autoindex
Cluster 3 — Source-code static analysis (6)
scanning-for-hardcoded-secrets — AWS / GitHub / Stripe / Slack / API keysdetecting-sql-injection-patterns — string-concat SQL, unsanitized inputdetecting-command-injection-patterns — shell exec with user inputdetecting-eval-exec-usage — eval/exec with dynamic contentdetecting-insecure-deserialization — pickle/yaml.load/Marshal usedetecting-weak-cryptography — MD5/SHA1/DES, hardcoded IVs, ECB mode
Cluster 4 — Dependency analysis (4)
auditing-npm-dependencies — npm audit wrapper with v1/v2 parsersauditing-python-dependencies — pip-audit wrapper with OSV scoringchecking-license-compliance — SPDX classification + copyleft contaminationtracing-transitive-vulnerabilities — dep-graph leverage analysis
Cluster 5 — Engagement governance (3, new in v3)
confirming-pentest-authorization — Rules of Engagement validationdefining-pentest-scope — target enumeration + IP allowlistrecording-pentest-engagement — SHA-256 manifest + GPG signing
Cluster 6 — Reporting (3, new in v3)
composing-vulnerability-report — unified deliverable reportmapping-findings-to-owasp-top10 — A0X classification + coverage rollupgenerating-executive-summary — 0-100 risk score + top-3 priorities
End-to-end workflow
For a typical engagement, the orchestrator routes through:
+----------------------------------+
| confirming-pentest-authorization |
+-------------+--------------------+
| (CRITICAL halts here)
v
+----------------------------------+
| defining-pentest-scope |
+-------------+--------------------+
|
v
+-------------+-------------+-------------+-------------+
| Cluster 1 | Cluster 2 | Cluster 3 | Cluster 4 |
| (5 skills) | (4 skills) | (6 skills) | (4 skills) |
+-------------+-------------+-------------+-------------+
|
v
+----------------------------------+
| mapping-findings-to-owasp-top10 |
+-------------+--------------------+
|
v
+----------------------------------+
| composing-vulnerability-report |
+-------------+--------------------+
|
v
+----------------------------------+
| generating-executive-summary |
+-------------+--------------------+
|
v
+----------------------------------+
| recording-pentest-engagement |
+----------------------------------+
Backward compatibility
The v2 monolithic scripts (security_scanner.py,
dependency_auditor.py, code_security_scanner.py) remain in
scripts/ as the underlying engine for the original v2
invocation patterns. The v3 narrow skills re-implement and
extend that logic with the canonical lib/finding.py schema and
the shared lib/report.py output module.
If a downstream user has scripted invocations of the v2 scripts,
those still work. New work should use the narrow skills directly.
The orchestrator's old "Step 1 / Step 2 / Step 3" instructions
in v2 are subsumed by the intent-routing table above. The v2
checks correspond to:
| v2 invocation | v3 equivalent |
|---|
security_scanner.py URL --checks headers | checking-http-security-headers |
security_scanner.py URL --checks ssl | analyzing-tls-config + detecting-ssl-cert-issues |
security_scanner.py URL --checks cors | auditing-cors-policy |
security_scanner.py URL --checks endpoints | detecting-exposed-secrets-files + detecting-debug-endpoints |
security_scanner.py URL --checks methods | probing-dangerous-http-methods |
dependency_auditor.py DIR --scanners npm | auditing-npm-dependencies |
dependency_auditor.py DIR --scanners pip | auditing-python-dependencies |
code_security_scanner.py DIR --tools regex | cluster 3 skills (per pattern type) |
code_security_scanner.py DIR --tools bandit | cluster 3 skills (bandit pattern subset) |
Prerequisites
Per-skill prerequisites are documented in each skill's
SKILL.md. The shared module lib/ requires Python 3.9+ and
the standard library only.
Optional tools used by individual skills:
bandit (Python static-analysis backend, cluster 3)pip-audit (cluster 4 Python dependency audit)pipdeptree (cluster 4 transitive trace)gpg (cluster 5 evidence signing)npm (cluster 4 npm dependency audit)
Each skill emits a graceful INFO Finding when an optional
dependency is missing and falls back to a degraded but functional
mode where possible.
Authorization is non-negotiable
The orchestrator REFUSES to invoke cluster 1-4 skills until
confirming-pentest-authorization has emitted no CRITICAL or
HIGH findings against the ROE. The cost of running an authorized
scan is delay until the ROE is verified. The cost of running an
unauthorized scan is potential criminal liability under CFAA
(US), Computer Misuse Act (UK), or equivalent foreign statutes.
For details on the legal framework + ROE structure, see
confirming-pentest-authorization/references/THEORY.md.
Examples
Example 1 — Full engagement, end to end
User: "Run a full pentest on engagements/acme-2026-q2/"
Orchestrator routes:
confirming-pentest-authorization --roe engagements/acme-2026-q2/roe.yaml- (if no CRITICAL findings)
defining-pentest-scope --roe engagements/acme-2026-q2/roe.yaml
- Cluster 1-4 skills against each in-scope target, emitting per-skill JSONLs into
engagements/acme-2026-q2/findings/
mapping-findings-to-owasp-top10 engagements/acme-2026-q2/composing-vulnerability-report engagements/acme-2026-q2/generating-executive-summary engagements/acme-2026-q2/recording-pentest-engagement engagements/acme-2026-q2/ --sign --tar ...
Example 2 — Ad-hoc header check
User: "Check security headers on https://app.acme.example"
Orchestrator routes:
confirming-pentest-authorization (operator must confirm authz; fast path for own-system testing)checking-http-security-headers https://app.acme.example
Example 3 — Dependency audit
User: "Audit dependencies in /path/to/project"
Orchestrator routes:
auditing-npm-dependencies /path/to/project (if package.json present)auditing-python-dependencies /path/to/project (if Python project present)- (if either produced HIGH/CRITICAL findings)
tracing-transitive-vulnerabilities /path/to/project --audit-input <previous output>
Output
The orchestrator's output is the COMPOSITION of the called skills'
outputs. The canonical end-state deliverables of a full engagement:
engagement/findings/all-with-owasp.jsonl — enriched unified findingsengagement/reports/vulnerability-report.md — deep technical reportengagement/reports/owasp-coverage.md — OWASP A0X rollupengagement/reports/executive-summary.md — C-level / board summaryengagement/manifest.sha256 (+ optional .asc) — chain-of-custody manifestengagement/<archive>.tar.gz — portable archive
Error Handling
The orchestrator delegates error handling to each invoked skill.
Cluster 5 errors (missing ROE, missing scope) HALT the engagement.
Cluster 1-4 errors (scanner missing, network unreachable) emit
INFO findings and continue. Cluster 6 errors (missing source
findings) emit HIGH operational findings and continue with a
partial deliverable.
Resources
references/OWASP_TOP_10.md — OWASP Top 10 risks (legacy v2
reference; the canonical OWASP table is now in
mapping-findings-to-owasp-top10/references/THEORY.md)references/SECURITY_HEADERS.md — HTTP security header
implementation guidereferences/REMEDIATION_PLAYBOOK.md — copy-paste fix templates- Per-skill
THEORY.md + PLAYBOOK.md files under each
skills/<skill-name>/references/
v3.0.0 release notes
Released 2026-06-03. Major changes:
- 25 narrow heavy-hitter skills replace the v2 3-script monolith
- New cluster 5 (engagement governance) and cluster 6 (reporting)
- Canonical
lib/finding.py + lib/report.py schema across all skills
disallowed-tools defense-in-depth for high-risk patterns (rm, curl, wget, .env edits)- v2 scripts (
security_scanner.py, dependency_auditor.py,
code_security_scanner.py) preserved as backward-compatible
scripts under scripts/
Migration: existing v2 invocations continue to work. New work
should use the narrow skills directly. See the backward-compat
table above for the v2 → v3 mapping.
