@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/defining-pentest-scope/references/PLAYBOOK.md

@@ -0,0 +1,238 @@
+# PLAYBOOK — Scope Templates and Hand-Off Patterns
+
+## Per-engagement-type scope templates
+
+### External web app pentest
+
+```yaml
+in_scope_targets:
+  - host: app.acme.example
+    notes: production web app
+  - host: api.acme.example
+    notes: REST API; rate-limit 60 req/min observed
+  - url: https://app.acme.example/admin/
+    notes: admin UI (test as authorized admin user)
+out_of_scope_targets:
+  - host: payments.acme.example
+    reason: PCI scope, separate authz required
+  - host: legal.acme.example
+    reason: third-party hosted; not customer's
+```
+
+### Internal network pentest
+
+```yaml
+in_scope_targets:
+  - cidr: 10.50.0.0/16
+    notes: corporate user range
+  - cidr: 10.51.0.0/16
+    notes: developer subnet
+  - cidr: 10.52.0.0/24
+    notes: test infrastructure
+out_of_scope_targets:
+  - cidr: 10.99.0.0/16
+    reason: production DB tier, separate authz
+  - cidr: 10.250.0.0/24
+    reason: physical surveillance VLAN
+  - cidr: 10.251.0.0/24
+    reason: VOIP (avoid call disruption)
+```
+
+### Red-team engagement
+
+```yaml
+in_scope_targets:
+  - cidr: 203.0.113.0/24
+    notes: customer ASN block 1
+  - cidr: 198.51.100.0/24
+    notes: customer ASN block 2
+  - host: "*.acme.example"
+    notes: any subdomain of acme.example
+  - cloud_account: aws:123456789012
+    notes: production AWS account
+out_of_scope_targets:
+  - host: ceo.acme.example
+    reason: executive personal device
+  - cidr: 203.0.113.250/32
+    reason: SOC bastion (would tip off SOC)
+```
+
+### Cloud account pentest (AWS)
+
+```yaml
+in_scope_targets:
+  - cloud_account: aws:123456789012
+    notes: prod-1 account; full read scope
+  - cloud_account: aws:210987654321
+    notes: prod-2 account; identity-services only
+out_of_scope_targets:
+  - cloud_account: aws:999999999999
+    reason: management account; out of agreed scope
+```
+
+### SaaS tenant pentest
+
+```yaml
+in_scope_targets:
+  - saas_tenant: okta:acme-corp
+    notes: customer Okta tenant; SSO config audit
+  - saas_tenant: auth0:acme
+    notes: customer Auth0 tenant
+out_of_scope_targets:
+  - saas_tenant: salesforce:acme
+    reason: separate vendor-authz required
+```
+
+Many SaaS vendors require explicit prior notification before
+pentesting (Salesforce, Okta, etc. all have their own pentest
+authorization forms). The skill flags `saas:` entries informationally;
+the operator should verify the vendor's own authz separately.
+
+## Allowlist emission patterns per scanner
+
+### nmap
+
+```bash
+python3 ./scripts/define_scope.py --roe roe.yaml --emit-allowlist /tmp/allowed.txt
+nmap -iL /tmp/allowed.txt -sV -oN nmap-scan.txt
+```
+
+### Burp Suite Target → Scope
+
+Burp uses regex-based scope rules. Convert the allowlist by
+escaping dots and accepting any port:
+
+```python
+# Quick converter
+import re
+with open("/tmp/allowed.txt") as f:
+    for line in f:
+        entry = line.strip()
+        # Convert hostname/CIDR to Burp regex
+        print(re.escape(entry))
+```
+
+Paste output into Burp's "Include in scope" with "Use advanced
+scope control" enabled.
+
+### AWS WAF allowlist
+
+```bash
+python3 - <<EOF
+import json
+ips = open("/tmp/allowed.txt").read().splitlines()
+v4 = [ip for ip in ips if ":" not in ip]
+print(json.dumps({"Addresses": v4}, indent=2))
+EOF
+```
+
+Pipe the output to `aws wafv2 update-ip-set` to install the
+allowlist.
+
+### Cloud security tools (ScoutSuite, Prowler, CloudSploit)
+
+Cloud scope is by account ID, not IP. Read the `cloud_account`
+entries from the normalized targets JSON:
+
+```bash
+jq -r '.[] | select(.type=="cloud") | .normalized' /tmp/targets.json
+```
+
+## Scope-extension protocol
+
+When testing reveals a target that should have been in scope but
+wasn't:
+
+1. Halt testing of the extension target.
+2. Request a scope amendment from the authorizer.
+3. Authorizer signs an extension YAML:
+
+   ```yaml
+   amendment_id: ACME-2026-Q2-PENTEST-001-AMEND-01
+   amendment_to: ACME-2026-Q2-PENTEST-001
+   amendment_date: 2026-06-15T10:00:00Z
+   in_scope_targets:
+     - host: newly-discovered.acme.example
+       notes: discovered during port-scan of cidr 203.0.113.0/24; serves admin UI
+   signature_block:
+     signer: jane.doe@acme.example
+     signed_at: 2026-06-15T11:00:00Z
+     signature: |
+       <signature>
+   ```
+
+4. Re-run this skill with `--extension`.
+5. Verify the new scope is clean before resuming testing.
+
+## Allowlist file format
+
+The `--emit-allowlist` output is one entry per line:
+
+```
+203.0.113.10
+203.0.113.0/24
+2001:db8::10
+2001:db8::/64
+```
+
+Hostnames are NOT in the allowlist (DNS resolves at scan time;
+see THEORY.md). The normalized targets JSON is the source of
+truth for hostnames + URLs + cloud accounts + SaaS tenants.
+
+## Normalized targets JSON format
+
+```json
+[
+  {"raw": "app.acme.example", "type": "hostname", "normalized": "app.acme.example"},
+  {"raw": "203.0.113.0/24", "type": "cidrv4", "normalized": "203.0.113.0/24"},
+  {"raw": "https://api.acme.example/v2", "type": "url", "normalized": "https://api.acme.example/v2"},
+  {"raw": "aws:123456789012", "type": "cloud", "normalized": "aws:123456789012"}
+]
+```
+
+Downstream skills consume this JSON via `--targets-file` argument
+patterns (planned across the cluster 1-4 skills).
+
+## Common scope-mistake patterns
+
+| Pattern | Fix |
+|---|---|
+| `host: 203.0.113.0/24` | Use `cidr:` not `host:` |
+| `host: https://app.acme.example` | Use `url:` not `host:` |
+| `cidr: 203.0.113.10` | Single IP without mask; CIDR /32 implied but explicit is better |
+| Hostname with trailing dot (`acme.example.`) | DNS-canonical form; strip the dot |
+| `*.acme.example/admin` | Mixes wildcard + path; not supported |
+| Cloud account with hyphenated number `aws:1234-5678-9012` | Use bare number, no hyphens |
+| Unicode in hostname (`münich.acme.example`) | Convert to Punycode (`xn--mnich-rta.acme.example`) |
+
+## Pre-scan gate (CI)
+
+```bash
+python3 ./scripts/define_scope.py --roe roe.yaml --min-severity high \
+    --format json --output scope-issues.json
+jq -e '. == []' scope-issues.json || {
+  echo "::error::Scope issues block testing"
+  exit 1
+}
+```
+
+This pattern works for engagements where the ROE is checked into
+a private engagement repo with CI.
+
+## Scope drift detection between engagements
+
+When running multiple engagements for the same customer over time,
+diff this engagement's scope against the previous:
+
+```bash
+python3 ./scripts/define_scope.py --roe engagements/acme-2026-q1/roe.yaml \
+    --emit-targets engagements/acme-2026-q1/targets.json
+python3 ./scripts/define_scope.py --roe engagements/acme-2026-q2/roe.yaml \
+    --emit-targets engagements/acme-2026-q2/targets.json
+diff <(jq -S .[].normalized engagements/acme-2026-q1/targets.json) \
+     <(jq -S .[].normalized engagements/acme-2026-q2/targets.json)
+```
+
+Scope changes between engagements are common (customer added new
+infra, decommissioned old) — but they should be explicit and
+documented, not silent.

package/skills/defining-pentest-scope/references/THEORY.md

@@ -0,0 +1,170 @@
+# THEORY — Scope as the Load-Bearing Artifact
+
+## Why scope is the load-bearing legal artifact
+
+Authorization is the gate (see `confirming-pentest-authorization`),
+but SCOPE is the perimeter the authorization applies to. A signed
+ROE that says "test ACME's stuff" authorizes nothing in practice
+because it doesn't define ACME's stuff. The scope list is the
+projection of "what we're allowed to touch" into a list of concrete
+targets a tester or tool can verify against.
+
+The skill's purpose is to convert the human-readable ROE scope
+section into a machine-readable, syntactically-validated, conflict-
+checked artifact that downstream cluster 1-4 skills can consume
+without ambiguity.
+
+## Target-type taxonomy
+
+Real-world scope lists mix several target types. The taxonomy:
+
+| Type | Use | Validation |
+|---|---|---|
+| Hostname | `app.acme.example` | Valid DNS character set, length |
+| Wildcard | `*.acme.example` | Wildcard prefix + valid suffix |
+| IPv4 | `203.0.113.10` | Valid 4-octet form |
+| IPv4 CIDR | `203.0.113.0/24` | Valid network + mask |
+| IPv6 | `2001:db8::10` | Valid hex form |
+| IPv6 CIDR | `2001:db8::/32` | Valid network + mask |
+| URL with path | `https://app.acme.example/api` | Valid URL parse + non-empty netloc |
+| Cloud account | `aws:123456789012` | Recognized cloud prefix |
+| SaaS tenant | `okta:acme-corp` | Recognized SaaS prefix |
+
+Mixing types in one list is normal; the skill's `--emit-targets`
+output preserves the type tagging so downstream tools can route
+each entry to the right scanner.
+
+## Why DNS resolution is NOT done at scope-definition time
+
+It would be tempting to resolve every hostname to its current IP
+at scope-definition time and bake the IPs into the allowlist. This
+is wrong, for two reasons:
+
+1. **DNS resolution is itself a probe.** A DNS query against the
+   target's authoritative DNS server (or against a recursive
+   resolver that forwards to it) is detectable by sophisticated
+   defenders. By the governance model, no probes happen before
+   scope is locked.
+
+2. **DNS changes during the engagement.** Resolving `app.acme.example`
+   to `203.0.113.10` at scope-definition time, then having the
+   customer's load balancer rotate to `203.0.113.11` mid-engagement,
+   means the tester's IP allowlist is stale. Hostname-based scope
+   resolves at scan time and tracks current DNS state.
+
+The downstream cluster 1 skills resolve hostnames at scan time
+themselves. The allowlist this skill emits contains the explicit
+IPs/CIDRs the ROE listed, not resolved hostnames.
+
+## CIDR overlap detection
+
+Python's `ipaddress` module provides exact CIDR-overlap checks
+via `IPv4Network.overlaps()` / `IPv6Network.overlaps()`. The skill
+uses these directly.
+
+A subtle case: `203.0.113.0/24` overlaps `203.0.113.128/25` (the
+second is a sub-range of the first). If the ROE has the /24 in
+in-scope and the /25 in out-of-scope, the skill emits a CRITICAL
+finding: probing within the /25 sub-range would violate the
+exclusion.
+
+The customer's authorizer decides the resolution:
+
+- Narrow in-scope to `203.0.113.0/25` (excludes the /25 explicitly)
+- Remove the out-of-scope /25 entry (broaden authorization)
+- Keep both and require per-target check at scan time
+
+## Known third-party SaaS ranges
+
+The skill ships an illustrative (NOT exhaustive) map of well-known
+cloud / CDN / SaaS ranges. The most common ones in customer scope
+lists by accident:
+
+- AWS — customer mistakes their AWS-hosted endpoint's CDN front
+  for their own infrastructure.
+- Cloudflare — customer's domain resolves to Cloudflare; the IP
+  is Cloudflare's, not the customer's.
+- GitHub — customer's hosted-status page or docs site is on GitHub
+  Pages.
+- Vercel / Netlify — customer's marketing site frontend.
+
+Probing these without separate authorization is testing the SaaS
+vendor's infrastructure, which is almost universally prohibited
+without the SaaS vendor's own pentest-authorization process.
+
+Real engagements should consult the authoritative published IP
+ranges:
+
+- AWS: https://ip-ranges.amazonaws.com/ip-ranges.json
+- Cloudflare: https://www.cloudflare.com/ips/
+- GCP: https://www.gstatic.com/ipranges/cloud.json
+- Azure: published quarterly as a JSON file
+
+A future skill enhancement could ingest these authoritative
+sources at scope-definition time and verify against current data.
+
+## Reserved ranges
+
+The skill flags RFC1918 (`10/8`, `172.16/12`, `192.168/16`),
+link-local (`169.254/16`), multicast (`224/4`), loopback
+(`127/8`), and IPv6 equivalents.
+
+In an internal pentest, RFC1918 ranges are expected — these are
+the customer's internal networks. The skill flags them as MEDIUM
+rather than HIGH/CRITICAL: "verify intentional." The customer's
+acknowledgement of the internal-pentest context resolves the
+finding.
+
+In an external pentest, RFC1918 in scope is a configuration error —
+the tester would be testing their own network, not the customer's.
+The skill cannot determine engagement type from the ROE alone, so
+the operator interprets the finding in context.
+
+## Wildcard subdomain semantics
+
+`*.acme.example` is a scope-by-pattern. It says "any subdomain of
+acme.example is in scope." The skill flags wildcards as INFO
+because they're not malformed but they ARE broad — the customer
+should confirm intent.
+
+Wildcard expansion happens at scan time, when the tester:
+
+1. Enumerates subdomains via passive sources (Certificate
+   Transparency, DNS history, brute-force).
+2. Each enumerated subdomain is checked against the wildcard's
+   pattern.
+3. Matched subdomains become concrete targets.
+
+The cluster 2 fingerprinting skills handle subdomain enumeration.
+
+## Scope hygiene patterns
+
+Three patterns characterize well-defined scope lists:
+
+1. **Explicit inclusion + explicit exclusion.** Always have both
+   lists, even if one is empty. "Nothing else is included"
+   beats "I assume the rest is excluded."
+
+2. **Type-tagged entries.** Use the schema's `host:` / `cidr:` /
+   `url:` keys explicitly. Bare string entries work but require
+   the skill to guess the type, which can produce subtle errors.
+
+3. **Notes on every entry.** Why is this in scope? Why is this
+   out? Future you, six months from now, won't remember.
+
+## When scope changes mid-engagement
+
+The protocol:
+
+1. Tester requests amendment via the engagement's documented
+   communication channel.
+2. Authorizer signs an amendment YAML referencing the original
+   ROE's `engagement_id`.
+3. Tester archives the amendment alongside the original ROE.
+4. Re-run this skill with `--extension` pointing at the
+   amendment.
+5. The new combined scope becomes the authoritative scope from
+   the amendment timestamp forward.
+
+Never extend scope by verbal agreement. The whole point of the
+ROE schema is that scope changes are auditable.