External/violin
1
0
Fork 0
mirror of https://github.com/Strategic-Automation/violin.git synced 2026-08-14 12:33:37 +02:00
Code Issues Packages Projects Releases Wiki Activity

Remove obsolete manual engagement bootstrap

Browse Source
This commit is contained in:
Violin
2026-07-12 17:11:57 +01:00
parent eae934bd5b
commit f2f95dd1e8
1 changed files with 28 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/pentest/playbooks/scoping.md
+28 -93
View File
@@ -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 <target-ip> "$ENG_DIR"
# python3 scripts/violin_guard.py init-engagement --ctf --session-id htb1 --host <target-ip> "$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
<!-- Legacy manual recovery reference.
# Resolve an ABSOLUTE ENG_DIR under the canonical engagement root so the skill
# tree and the violin-guard plugin tree never diverge (root-cause fix). The
# `eng-root` subcommand strips any leading "engagements/" and resolves the path
# against $VIOLIN_ENG_ROOT (default <repo>/engagements).
ENG_REL="engagements/<target-name>-$(date +%F)"
ENG_DIR="$(python scripts/violin_guard.py eng-root --eng-dir "$ENG_REL" | sed -n 's/^ENG_DIR=//p')"
if [ -z "$ENG_DIR" ]; then
# Fallback for environments without the guard CLI: resolve against repo root.
ENG_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)/engagements/<target-name>-$(date +%F)"
fi
echo "ENG_DIR=$ENG_DIR"
# Drop any stale pending-sync lock from a PRIOR session (approved a command,
# ran it, but exited before sync-done). This must run AFTER ENG_DIR is resolved.
python scripts/violin_guard.py sync-clear --eng-dir "$ENG_DIR" 2>/dev/null || true
# Publish the canonical engagement root as a SESSION-PERSISTENT absolute
# anchor so every phase playbook converges on the SAME tree. The guard's
# core.py already honors $VIOLIN_ENG_ROOT, so this also keeps the plugin and
# the skill tree aligned. Without this, phase playbooks re-declare a bare
# relative "engagements/..." path that resolves against the agent's CWD
# (e.g. /home/kali) and spawns a second, divergent tree (Issue D).
export VIOLIN_ENG_ROOT="$(dirname "$ENG_DIR")"
echo "VIOLIN_ENG_ROOT=$VIOLIN_ENG_ROOT" >> /tmp/eng_ctx.sh
mkdir -p "$ENG_DIR"/{scope,evidence/{recon/{passive,tech,active},vuln-research,exploitation,reporting,retrospective},state}
# Save for later phases
echo "ENG_DIR=$ENG_DIR" >> /tmp/eng_ctx.sh
# Bootstrap PTT (Pentesting Task Tree)
cp skills/pentest/templates/ptt.md "$ENG_DIR/state/ptt.md"
sed -i "s/<target> <YYYY-MM-DD>/<target-name> $(date +%F)/" "$ENG_DIR/state/ptt.md"
# Bootstrap hypothesis board
cp skills/pentest/templates/hypothesis-board.md "$ENG_DIR/hypotheses.md"
sed -i "s/<target> <YYYY-MM-DD>/<target-name> $(date +%F)/" "$ENG_DIR/hypotheses.md"
# Initialize command history
echo "# Command History — $(date +%F)" > "$ENG_DIR/state/history.md"
# Bootstrap resumable checkpoint state from the minimal template.
cp skills/pentest/templates/checkpoint.json "$ENG_DIR/state/checkpoint.json"
python - <<'PY'
import json, os, pathlib, datetime
path = pathlib.Path(os.environ["ENG_DIR"]) / "state" / "checkpoint.json"
data = json.loads(path.read_text(encoding="utf-8"))
data.update({
"engagement_id": pathlib.Path(os.environ["ENG_DIR"]).name,
"eng_dir": os.environ["ENG_DIR"],
"phase_current": "SCOPING",
"last_checkpoint": datetime.datetime.now(datetime.UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
})
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
PY
-->
```
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 <host>`. The recorded `Target:` field MUST contain the real host/IP (e.g. `10.129.45.228:80`), never the literal `<target>`. 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 `<target>`.
> `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 <host>`. The recorded `Target:` field MUST contain the real host/IP (e.g. `10.129.45.228:80`), never the literal `<target>`. 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 `<target>`.
### 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