From f2f95dd1e8562cec27c848e5151210c60da4bffe Mon Sep 17 00:00:00 2001 From: Violin Date: Sun, 12 Jul 2026 17:11:57 +0100 Subject: [PATCH] Remove obsolete manual engagement bootstrap --- skills/pentest/playbooks/scoping.md | 121 +++++++--------------------- 1 file changed, 28 insertions(+), 93 deletions(-) diff --git a/skills/pentest/playbooks/scoping.md b/skills/pentest/playbooks/scoping.md index 6fa9e5b..fc8aa80 100644 --- a/skills/pentest/playbooks/scoping.md +++ b/skills/pentest/playbooks/scoping.md @@ -1,7 +1,7 @@ # Scoping Playbook > **Purpose:** Define, document, and maintain the exact boundaries of a pentest -> The scope file (`$ENG_DIR/scope/scope.yaml`) is the single source of truth — +> The scope file (`$ENG_DIR/scope/scope.yaml`) is the single source of truth — > never test outside it and never change it without re-approval. ## Capabilities (this phase) @@ -33,90 +33,25 @@ python3 scripts/violin_guard.py init-engagement --host "$ENG_DIR" # python3 scripts/violin_guard.py init-engagement --ctf --session-id htb1 --host "$ENG_DIR" ``` -The legacy manual bootstrap below is retained only as a recovery reference; -use `init-engagement` for normal work. - -Run this before capturing any data — it creates the directory structure, PTT, and hypothesis board for this engagement: - -```bash - - -``` - All subsequent evidence, findings, and scope files go under `$ENG_DIR/`. Never write evidence to the skills directory. > **Guard-required scope fields (must be present or `validate_scope_data` returns REVIEW):** > The shipped `scope-template.yaml` already includes these, but if you hand-write `scope.yaml` you MUST include them: -> - **`authorized_parties:`** — a TOP-LEVEL key (NOT nested under `authorisation:`), a non-empty list of approving parties, e.g. `authorized_parties: ["lab owner (user)"]`. Missing/empty → REVIEW. -> - **`rules_of_engagement.allowed_actions:`** — non-empty list of explicitly permitted actions, e.g. `["host/port discovery", "banner grabbing", "version detection"]`. Empty list `[]` → REVIEW. +> - **`authorized_parties:`** — a TOP-LEVEL key (NOT nested under `authorisation:`), a non-empty list of approving parties, e.g. `authorized_parties: ["lab owner (user)"]`. Missing/empty → REVIEW. +> - **`rules_of_engagement.allowed_actions:`** — non-empty list of explicitly permitted actions, e.g. `["host/port discovery", "banner grabbing", "version detection"]`. Empty list `[]` → REVIEW. > `validate_scope_data` (scripts/guard/core.py) emits REVIEW (exit 2) for either gap; the command gate still proceeds but the warning must be cleared before reporting. > **Hypothesis target format (must match the real host):** -> `record-hypothesis` now derives the target host from the engagement directory name (e.g. `engagements/10.129.45.228-2026-07-08` → host `10.129.45.228`) or from an explicit `--target `. The recorded `Target:` field MUST contain the real host/IP (e.g. `10.129.45.228:80`), never the literal ``. The hypothesis guard (`_hypothesis_guard`) only passes a command whose host appears in an active hypothesis's `Target:`. If you hand-edit `hypotheses.md`, set `Target:` to the real host, not ``. +> `record-hypothesis` now derives the target host from the engagement directory name (e.g. `engagements/10.129.45.228-2026-07-08` → host `10.129.45.228`) or from an explicit `--target `. The recorded `Target:` field MUST contain the real host/IP (e.g. `10.129.45.228:80`), never the literal ``. The hypothesis guard (`_hypothesis_guard`) only passes a command whose host appears in an active hypothesis's `Target:`. If you hand-edit `hypotheses.md`, set `Target:` to the real host, not ``. ### Hypothesis Board Already created during bootstrap (step 0 above). The board is the agent's working memory for the engagement. It tracks: -- **Active theories** — unconfirmed vulnerability hypotheses with status and next steps -- **Observations** — raw discoveries that don't yet form a theory -- **Investigation chains** — how theories connect and lead to new ones -- **Research log** — web research performed during the engagement with triggers -- **Resolved theories** — validated or rejected theories feeding reporting/retrospective +- **Active theories** — unconfirmed vulnerability hypotheses with status and next steps +- **Observations** — raw discoveries that don't yet form a theory +- **Investigation chains** — how theories connect and lead to new ones +- **Research log** — web research performed during the engagement with triggers +- **Resolved theories** — validated or rejected theories feeding reporting/retrospective See `skills/pentest/templates/hypothesis-board.md` for the full template and usage instructions. @@ -162,7 +97,7 @@ needed but cover every item below. > CVEs?_ 3. **Technical focus areas** - > _Are there specific vulnerability classes you want prioritised — for + > _Are there specific vulnerability classes you want prioritised — for > example SQL injection, XSS, IDOR, SSRF, API security, authentication > bypasses, or privilege escalation?_ @@ -172,23 +107,23 @@ needed but cover every item below. > access)?_ 5. **Risk tolerance / forbidden actions** - > _Are there any actions you explicitly forbid — credential stuffing, social + > _Are there any actions you explicitly forbid — credential stuffing, social > engineering, post-exploitation, persistence, stealth evasion, malware, or > destructive payloads? (These are forbidden by default.)_ 6. **Time window** - > _What is the testing period — specific dates and times — and should we + > _What is the testing period — specific dates and times — and should we > restrict testing to business hours or go 24/7?_ 7. **Target environment** > _Is this a production, staging, or isolated test environment? Are there > any third-party or shared services that must not be affected?_ -8. **Tooling environment** — Auto-detect first: +8. **Tooling environment** — Auto-detect first: ```bash # Detect OS - uname -s # Darwin → macOS, Linux → Linux, MINGW*/MSYS → Windows + uname -s # Darwin → macOS, Linux → Linux, MINGW*/MSYS → Windows # Check Docker command -v docker && docker info --format '{{.OSType}}' 2>/dev/null @@ -221,7 +156,7 @@ template at `skills/pentest/templates/scope-template.yaml`. ```bash # Copy the template and fill it in cp skills/pentest/templates/scope-template.yaml $ENG_DIR/scope/scope.yaml -# — edit $ENG_DIR/scope/scope.yaml with the captured data — +# — edit $ENG_DIR/scope/scope.yaml with the captured data — ``` The scope file MUST be committed to the engagement repository alongside the @@ -247,13 +182,13 @@ approval. > | **Rate limit** | {max_requests_per_second} req/s | > > **Default prohibitions (no changes unless explicitly agreed):** -> - ❌ No credential stuffing -> - ❌ No social engineering -> - ❌ No post-exploitation -> - ❌ No persistence -> - ❌ No stealth / evasion techniques -> - ❌ No malware or payload delivery -> - ❌ No destructive payloads (DROP tables, rm -rf, etc.) +> - ❌ No credential stuffing +> - ❌ No social engineering +> - ❌ No post-exploitation +> - ❌ No persistence +> - ❌ No stealth / evasion techniques +> - ❌ No malware or payload delivery +> - ❌ No destructive payloads (DROP tables, rm -rf, etc.) > > **Please confirm:** Do you approve this scope, including all targets, > exclusions, mode, depth, and rules of engagement? Reply with "approved" and @@ -280,12 +215,12 @@ vector that falls **outside** the current scope file: ## 6. Re-scoping -Any change to the scope — whether expanding targets, adjusting rules of -engagement, changing the mode, or modifying exclusions — requires the same +Any change to the scope — whether expanding targets, adjusting rules of +engagement, changing the mode, or modifying exclusions — requires the same rigour as the initial scope. 1. **Update** `$ENG_DIR/scope/scope.yaml` with the proposed changes. -2. **Ask for re-approval** via `clarify` — present the diff or updated summary +2. **Ask for re-approval** via `clarify` — present the diff or updated summary just like in step 4. 3. **Do not continue testing** until the updated scope has been explicitly approved. @@ -305,9 +240,9 @@ This applies equally to: ## Stop Conditions -- Discovery of an asset outside the agreed scope → pause and re-scope -- Client requests to stop testing → cease immediately -- Critical finding in production → pause and notify +- Discovery of an asset outside the agreed scope → pause and re-scope +- Client requests to stop testing → cease immediately +- Critical finding in production → pause and notify ## Blocked Actions