@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/confirming-pentest-authorization/references/PLAYBOOK.md

@@ -0,0 +1,189 @@
+# PLAYBOOK — ROE Templates and Authorization Flow
+
+## Default ROE template
+
+```yaml
+engagement_id: <CLIENT>-<YEAR>-<QUARTER>-PENTEST-<NN>
+authorizer:
+  name: ""
+  email: ""
+  role: ""                  # CISO, CTO, VP Eng, Director of Security, etc.
+  organization: ""
+in_scope_targets:
+  - host: ""
+    notes: ""
+out_of_scope_targets:
+  - host: ""
+    reason: ""
+time_window:
+  start: "2026-MM-DDT00:00:00Z"
+  end:   "2026-MM-DDT23:59:59Z"
+emergency_contact:
+  name: ""
+  phone: ""
+  email: ""
+rules:
+  - No exploitation of confirmed findings without written prompt approval.
+  - No password cracking against production accounts.
+  - Testing pauses during declared business-hours blackout windows.
+  - All findings are confidential until report delivery.
+signature_block:
+  signer: ""
+  signed_at: "2026-MM-DDTHH:MM:SSZ"
+  signature: |
+    <PGP signature, DocuSign envelope ID, or equivalent attestation>
+```
+
+## Per-engagement-type variants
+
+### External web-app pentest
+
+`in_scope_targets` is hosts/URLs. `rules` typically include "no
+DoS, no brute-force against rate-limited endpoints, no testing
+during peak hours (specify the window)."
+
+### Internal network pentest
+
+`in_scope_targets` is CIDRs. `out_of_scope_targets` typically
+excludes the company VOIP range, the surveillance camera VLAN,
+and any PCI scope without separate authz. `rules` typically include
+"no exploit of the domain controller, no lateral movement past
+the documented hop limit."
+
+### Red-team engagement
+
+`in_scope_targets` may be the entire ASN, with explicit `out_of_scope`
+exclusions. `rules` typically include "exfiltration attempts are
+in scope; persistence mechanisms must be reversible; physical
+intrusion is/isn't included." Time window is often months.
+
+### Purple-team engagement
+
+ROE has an explicit clause acknowledging the SOC is informed.
+Adds a `coordination_contact` field for the SOC liaison.
+
+### Cloud account pentest (AWS/Azure/GCP)
+
+`in_scope_targets` includes account IDs / subscription IDs.
+`rules` typically include "no creation of new principal
+identities beyond the documented test identity; no modification
+of production IAM roles."
+
+### SaaS integration pentest
+
+`in_scope_targets` is the customer's tenant in the SaaS app.
+`rules` typically include the SaaS vendor's own policy
+(many SaaS vendors require explicit prior notification before
+testing).
+
+## Authorization escalation flow
+
+When the prospective authorizer says "yes, you can test," the
+escalation flow inside the customer's organization typically:
+
+1. **Operational owner agreement** — the team that owns the
+   system signs off that testing is welcome.
+2. **Security leadership approval** — CISO or equivalent
+   approves the engagement scope.
+3. **Legal review** — the customer's counsel reviews the ROE
+   for indemnification, liability cap, and scope clarity.
+4. **Executive sign-off** — for high-value or high-risk
+   engagements, CFO/COO/CEO sign as the binding party.
+
+The skill's `.allowed-authorizers` list captures step 2 + 4
+identities — security leadership + executive sign-off — as the
+authoritative signers. Operational owners are not in the
+allowlist by default because they typically don't bind the
+organization legally.
+
+## Time-window extension procedure
+
+When an in-progress engagement needs more time:
+
+1. Tester requests extension via the engagement's documented
+   communication channel.
+2. Authorizer (or delegate from the allowlist) signs a new ROE
+   with the extended `time_window.end`.
+3. Tester archives BOTH the original ROE and the extension; the
+   skill is re-run against the extension and produces a fresh
+   authorization record.
+
+Never run the skill on a ROE whose time window has been verbally
+or informally extended. The whole point of the schema is to make
+extensions auditable.
+
+## Emergency-stop protocol
+
+A pentest can need to stop immediately when:
+
+- The customer's SOC detects testing activity and treats it as a
+  real attack (the test pre-notification didn't reach the SOC
+  team on shift).
+- An out-of-scope system is accidentally probed.
+- The tester's tools cause an unexpected outage.
+- The customer requests a halt for any reason.
+
+The ROE's `emergency_contact` field is the call-immediately
+number. Halting is a hard stop:
+
+1. Cease all active tools.
+2. Notify the emergency_contact verbally.
+3. Document the stop time + reason.
+4. Re-run the authorization skill before resuming. If anything
+   in the ROE changed (e.g. scope amendment), the skill produces
+   the new authorization record.
+
+## Allowed-authorizers file format
+
+```
+# .allowed-authorizers — one signer identity per line
+# Comments OK. Email addresses or PGP key fingerprints.
+
+jane.doe@acme.example
+john.smith@acme.example
+0xDEADBEEFCAFE1234
+```
+
+Maintained by the tester's business-development team. Updates
+should require a co-sign from a second person to prevent
+single-actor manipulation.
+
+## Storage and retention
+
+The ROE itself is part of the engagement evidence chain. Store
+it in the engagement's evidence directory, NOT in the customer's
+codebase under test:
+
+```
+engagements/
+└── acme-2026-q2/
+    ├── roe.yaml
+    ├── allowed-authorizers
+    ├── evidence/
+    │   ├── authz-check-20260601.json
+    │   ├── authz-check-20260615.json   # after time-window extension
+    │   └── ...
+    └── findings/
+        └── ...
+```
+
+Retention: keep ROEs for at least the statute-of-limitations
+period for unauthorized-access offences in the relevant
+jurisdiction (typically 5-7 years). Some customers require
+longer retention for SOC2 / ISO 27001 evidence.
+
+## When the customer signs a "blanket" pentest authorization
+
+Some customers issue a blanket annual or multi-year authorization
+covering all engagements with a given pentester. This is legally
+valid but operationally risky:
+
+- Scope drift across engagements becomes invisible.
+- Personnel changes on either side can void the blanket
+  implicitly.
+- Time-window enforcement disappears.
+
+Recommended: write a per-engagement ROE that references the
+blanket authorization but adds specific scope + time window.
+The blanket establishes the relationship; the per-engagement
+ROE establishes what's authorized today.

package/skills/confirming-pentest-authorization/references/THEORY.md

@@ -0,0 +1,167 @@
+# THEORY — Pentest Authorization as a Legal Primitive
+
+## The legal line
+
+Computer-access laws across major jurisdictions criminalize
+unauthorized access. The notable statutes:
+
+| Jurisdiction | Statute | Key provision |
+|---|---|---|
+| United States | CFAA (18 USC §1030) | Accessing a protected computer "without authorization" or "exceeding authorized access" |
+| United Kingdom | Computer Misuse Act 1990 | Unauthorized access (§1), unauthorized acts impairing computer operation (§3) |
+| European Union | Directive 2013/40/EU | Illegal access, illegal system interference, illegal data interference |
+| Singapore | Computer Misuse Act 1993 | Same shape; offence of unauthorized access |
+| Australia | Criminal Code Act 1995 §477 | Unauthorized access, modification, or impairment |
+
+The defining word in every statute is "authorization." A pentester
+with explicit written authorization to access in-scope systems is
+performing a legal security service. Without that authorization,
+the same activity is a crime.
+
+Authorization is not implicit. "I assumed they wanted me to test
+their system" is not a defense. "They paid me to do security work"
+is not sufficient if the system tested was outside the contracted
+scope. The pentest industry has standardized the Rules of
+Engagement (ROE) document as the artifact that establishes
+authorization with the precision the law expects.
+
+## OSSTMM, PTES, and ROE history
+
+Two open-source frameworks gave the industry its ROE template:
+
+- **OSSTMM** (Open Source Security Testing Methodology Manual,
+  ISECOM, 2001 onward) — defined the scope-fingerprinting process
+  and what the engagement-letter checklist must cover.
+- **PTES** (Penetration Testing Execution Standard, 2010 onward)
+  — formalized the pre-engagement phase, including ROE structure.
+
+Both predate the cloud / API era and reflect a network-pentest
+mental model. Modern engagements add fields for cloud accounts,
+SaaS integrations, and ML-model probing that the original templates
+don't anticipate. The schema this skill validates incorporates
+common modern fields (SaaS scope, time windows, emergency contact)
+on top of the OSSTMM/PTES foundation.
+
+## Signature options
+
+The "signature" on a ROE is whatever evidence the authorizer's
+counsel and your counsel agree establishes binding intent. Common
+forms:
+
+| Method | Strength | Effort |
+|---|---|---|
+| PGP / GPG signature on YAML/text ROE | Cryptographic; high | Moderate (both parties need GPG setup) |
+| S/MIME signed PDF | Cryptographic; high | Moderate (certificate management) |
+| DocuSign or HelloSign e-signature | Legally recognized in most jurisdictions; high | Low |
+| Email with explicit "I authorize" statement, archived | Legally recognized but weaker (email impersonation risk) | Low |
+| Wet-ink signature on printed ROE | Strongest in court; high | High (slow, physical) |
+| Slack DM "yeah go ahead" | Often inadmissible; do NOT rely on | Trivial |
+
+The skill validates the structural presence of a `signature_block`
+in the ROE. Cryptographic verification (actually checking that a
+PGP signature was made by the claimed key) is a separate step the
+operator runs with `gpg --verify` before this skill runs. The
+skill checks "is this ROE structurally signed?" not "is this
+signature cryptographically valid?" — those are different gates,
+and conflating them in one tool produces brittle failure modes.
+
+## Scope-creep failure modes
+
+Engagements that go wrong tend to follow common patterns:
+
+### "Just one more system"
+
+Tester finds an interesting adjacent system mid-engagement and
+probes it. Adjacent system was NOT in the ROE. SOC team escalates.
+Legal asks for the ROE. ROE doesn't cover the adjacent system.
+Conversation gets expensive.
+
+Mitigation: the skill's `--check-target` flag explicitly tests
+whether a target is in scope BEFORE any probe runs. The
+orchestrator should call it for every fresh target.
+
+### "I assumed prod was off-limits"
+
+Tester avoids "obvious" production systems but probes systems
+labeled "staging" that turn out to be production-attached.
+Outage results.
+
+Mitigation: ROE schema requires explicit `in_scope_targets` AND
+`out_of_scope_targets`. The list of out-of-scope items is
+prophylactic — if a target isn't on either list, the tester must
+ask before proceeding.
+
+### "We extended verbally"
+
+Engagement's time window expires, but the customer says verbally
+"keep going for another week." Tester continues. Incident occurs.
+ROE shows the time window as expired. The verbal extension is
+unprovable.
+
+Mitigation: time-window expiry is a CRITICAL finding in this
+skill. The skill refuses to declare an engagement authorized if
+the current time is outside the window, regardless of any other
+field's state.
+
+### "The CISO's assistant said it was fine"
+
+ROE was signed by someone whose authority over the systems was
+unclear or absent. CISO denies authorizing.
+
+Mitigation: the `.allowed-authorizers` file establishes which
+signer identities are accepted. Maintained by the tester's
+business-development team; new authorizers require vetting
+before being added.
+
+## ROE template fields and why each matters
+
+| Field | Why it's in the schema |
+|---|---|
+| `engagement_id` | Unambiguously identifies the engagement; lets multiple ROEs coexist without confusion |
+| `authorizer.name + email + role` | Identifies who is authorizing; their role establishes that they have authority |
+| `authorizer.organization` | Customer org; useful when the authorizer is a contractor or an MSP |
+| `in_scope_targets` | The list. Without it, nothing is authorized |
+| `out_of_scope_targets` | Prophylactic; clarifies known boundaries |
+| `time_window.start + end` | Engagement is only authorized within this window |
+| `emergency_contact` | Who to call if the test triggers an unexpected outage or law-enforcement contact |
+| `rules` | Custom restrictions (no password spray on prod accounts, etc.) |
+| `signature_block` | Establishes binding intent and which party is bound |
+| `signature_block.signed_at` | When binding was established |
+
+## Why "halt on CRITICAL" is the right policy
+
+The orchestrator routes to this skill FIRST and refuses to proceed
+to cluster 1-4 skills if any CRITICAL finding emerges. The
+rationale:
+
+- A scan that produces findings against an unauthorized target
+  exposes the tester to legal liability.
+- Even informational scans (port scans, DNS probes) against
+  unauthorized targets can constitute unauthorized access under
+  some statutes.
+- The cost of halting is a delayed engagement. The cost of
+  proceeding without authorization is criminal exposure. The
+  asymmetry is severe; the discipline is the only constraint.
+
+## Cryptographic verification — out of scope here
+
+PGP signature verification (does the signature on this ROE actually
+match the public key of the claimed signer?) is performed by a
+separate operator-run step:
+
+```bash
+gpg --verify roe.yaml.asc roe.yaml
+```
+
+The skill does not invoke GPG because:
+
+1. Many ROEs are signed via DocuSign or similar (no PGP at all).
+2. PGP key management is its own discipline — the skill would
+   become a key-management tool.
+3. Separating "structural presence of signature" from
+   "cryptographic validity of signature" makes failures easier
+   to diagnose.
+
+A future enhancement could add `--verify-pgp` to bridge the two,
+with explicit key-store configuration. For now, the skill checks
+structure; the operator checks cryptography.