--- name: defining-pentest-scope description: | Parse the ROE scope definition, enumerate every in-scope target (hostnames, IPs, CIDRs, URLs, cloud accounts, SaaS tenants), validate syntax, detect overlap with out-of-scope or known third-party SaaS ranges, and emit a normalized target list plus IP allowlist for scanning tools. Runs after confirming-pentest- authorization and before any cluster 1-4 scan. Use when: starting an engagement, expanding scope mid-engagement, validating that a target list matches the ROE, or generating an allowlist for an external scanner. Threshold: malformed syntax, in-scope overlap with out-of-scope, reserved or third-party SaaS ranges without acknowledgement. Trigger with: "define scope", "enumerate targets", "validate target list", "generate IP allowlist". allowed-tools: - Read - Bash(python3:*) - Glob disallowed-tools: - Bash(rm:*) - Bash(curl:*) - Bash(wget:*) - Bash(nmap:*) - Write(.env) - Edit(.env) version: 3.0.0-dev author: Jeremy Longshore license: MIT compatibility: Designed for Claude Code tags: - security - engagement-governance - scope - target-enumeration - pentest --- # Defining Pentest Scope ## Overview A pentest scope is a list of permission boundaries. Get it wrong and you either (a) miss real exposure by failing to test something the customer expected covered, or (b) probe something you weren't allowed to touch and turn the engagement into a liability event. Both failure modes share a root cause: the scope list was a vague narrative ("test the marketing site and the API") rather than a machine-readable, syntactically-validated, conflict-checked artifact. This skill takes the in-scope and out-of-scope sections from a ROE and produces three deliverables: 1. **Normalized target list** — every entry parsed into a structured form (host vs CIDR vs URL path vs cloud account vs SaaS tenant), with explicit type tagging. Downstream cluster 1-4 skills consume this list rather than raw strings. 2. **IP allowlist** — flat list of IPv4 and IPv6 addresses / CIDRs ready to paste into scanner configurations (nmap target list, Burp scope file, AWS WAF allowlist, etc.). 3. **Conflict report** — Findings flagging syntactically-malformed entries, overlap between in-scope and out-of-scope, inclusion of reserved ranges (RFC1918, link-local, multicast), and known third-party SaaS infrastructure that needs separate authz. The skill does NOT perform DNS resolution or network probing — that would itself be a "first probe" of the target, which by the governance model must happen AFTER scope is locked. ## When the skill produces findings | Finding | Severity | Threshold | Affected control | |---|---|---|---| | Malformed target syntax | **HIGH** | Entry doesn't parse as host / CIDR / URL / account-id | (legal) | | In-scope overlaps out-of-scope | **CRITICAL** | An in-scope target falls within an out-of-scope CIDR | (legal) | | Reserved range without acknowledgement | **HIGH** | RFC1918, link-local (169.254/16), multicast (224/4), broadcast in in-scope list | (operational) | | Known third-party SaaS in scope | **HIGH** | In-scope IP matches a known SaaS range (AWS, Cloudflare, GitHub, etc.) without separate authz | (legal) | | Duplicate target | **INFO** | Same target appears multiple times | (operational) | | Wildcard subdomain (e.g. `*.acme.example`) | **INFO** | Wildcards expand at scan time | (informational) | | All targets validated cleanly | **INFO** | Positive confirmation | (informational) | ## Prerequisites - Python 3.9+ - ROE file at `./roe.yaml` (or pass `--roe FILE`) - Optional `.scope-extension.yaml` listing additional targets added mid-engagement (each must reference an authz amendment) ## Target syntax forms | Form | Example | Notes | |---|---|---| | Hostname | `app.acme.example` | DNS-resolvable name | | Wildcard subdomain | `*.acme.example` | Resolved at scan time; flag for explicit acknowledgement | | IPv4 address | `203.0.113.10` | Single host | | IPv4 CIDR | `203.0.113.0/24` | Network range | | IPv6 address | `2001:db8::10` | Single host | | IPv6 CIDR | `2001:db8::/32` | Network range | | URL with path | `https://app.acme.example/api/v2` | Path-restricted scope | | Cloud account ID | `aws:123456789012` or `gcp:acme-prod` | Cloud control-plane scope | | SaaS tenant | `okta:acme-corp` or `auth0:acme` | SaaS-tenant scope | ## Instructions ### Step 1 — Provide the scope source The skill reads the ROE's `in_scope_targets` and `out_of_scope_targets` sections by default. Override with `--roe FILE` if the engagement ROE isn't at the default path. ### Step 2 — Run the scope definition ```bash python3 ./scripts/define_scope.py --roe engagements/acme-2026-q2/roe.yaml ``` Options: ``` Usage: define_scope.py [OPTIONS] Options: --roe FILE Path to ROE YAML (default: ./roe.yaml) --emit-allowlist FILE Write flat IP allowlist to FILE --emit-targets FILE Write normalized target list to FILE --extension FILE Additional scope extension YAML --output FILE Findings output --format FMT json | jsonl | markdown (default: markdown) --min-severity SEV default info ``` ### Step 3 — Review the conflict report CRITICAL findings (overlap between in-scope and out-of-scope) must be resolved before any scan runs. Either narrow the in-scope range or remove the out-of-scope overlap; the customer's authorizer decides which. HIGH findings (malformed targets, third-party SaaS, reserved ranges) require explicit acknowledgement — either fix the entry or document in the ROE why the range is intentionally included. ### Step 4 — Hand off the allowlist ```bash python3 ./scripts/define_scope.py --roe engagements/acme-2026-q2/roe.yaml \ --emit-allowlist /tmp/allowed-ips.txt \ --emit-targets /tmp/normalized-targets.json ``` The allowlist file is one IP/CIDR per line, ready to paste into: - nmap: `nmap -iL /tmp/allowed-ips.txt` - AWS WAF rule: convert to JSON via your standard tooling - Burp Suite: paste into Target → Scope → Include - This pack's cluster 1 skills: pass via the target argument ## Examples ### Example 1 — Generate scope artifacts for a new engagement ```bash python3 ./scripts/define_scope.py \ --roe engagements/acme-2026-q2/roe.yaml \ --emit-allowlist engagements/acme-2026-q2/scope/allowed-ips.txt \ --emit-targets engagements/acme-2026-q2/scope/normalized-targets.json \ --output engagements/acme-2026-q2/scope/scope-report.md ``` ### Example 2 — Validate a mid-engagement scope extension ```bash python3 ./scripts/define_scope.py \ --roe engagements/acme-2026-q2/roe.yaml \ --extension engagements/acme-2026-q2/scope-extension-20260615.yaml ``` The extension YAML follows the same target format. The skill validates that every extension entry has an associated authorization reference and emits a CRITICAL finding for any extension entry that doesn't. ### Example 3 — Pre-scan validation gate ```bash python3 ./scripts/define_scope.py --roe engagements/acme-2026-q2/roe.yaml \ --min-severity high \ --format json --output /tmp/scope-issues.json jq -e '. == []' /tmp/scope-issues.json || { echo "Scope issues block scan"; exit 1; } ``` ## Output JSON / JSONL / Markdown per `lib/report.py`. Exit codes: 0 clean, 1 high/critical, 2 error. Each Finding includes: - `id` — `scope::::` (e.g. `scope::malformed::foo[bar`) - `severity` — CRITICAL / HIGH / MEDIUM / INFO - `category` — `engagement-scope` - `summary` — what's wrong with the entry - `evidence` — original entry, parsed form, conflict source, line in ROE ## Error Handling - **ROE missing** → emits CRITICAL finding, exits 1. - **In-scope section missing or empty** → CRITICAL finding, exits 1. - **Unparseable entry** → HIGH finding per entry, scan continues for other entries. - **Extension file referenced but missing** → HIGH finding. - **IPv6 CIDR with very large mask** (e.g. `::/0`) → CRITICAL — almost certainly a typo; refuse to expand. ## Resources - `references/THEORY.md` — Why scope is the load-bearing artifact of pentest legality, target-type taxonomy, known SaaS-range classification (AWS, Cloudflare, GCP, Azure), DNS resolution policy (when/whether to resolve at scope-definition time), CIDR-overlap detection theory - `references/PLAYBOOK.md` — Per-engagement-type scope templates (web app, internal network, red team, cloud account, SaaS tenant), scope-extension protocol, allowlist-emission patterns per scanner, common scope-mistake patterns