pentest-engagement

# Pentest Engagement Orchestrates a scoped pentest end-to-end via the `pentest-engagement` workflow. It is the breadth-complete, coverage-gated counterpart to the flag-shaped `htb-solve` — same engine (`coordinator-loop`, now with **interleaved per-finding validation** built into the loop), but driven by an attack-class **coverage matrix** instead of a flag, with surface expansion and root-cause severity baked in. ## When to use A real (non-CTF) engagement defined by a **scope** — either: - **WEB** — web / API / cloud apps defined by apex domains / asset URLs, **or** - **NETWORK** — a list of **IPs / CIDRs / ranges** (e.g. 1500 hosts) to scan for live services and vulnerabilities. The workflow **auto-detects** the mode in Setup (`engagement_kind`): predominantly IPs/CIDRs → network; apex domains / app URLs → web. For HackTheBox/CTF use `hackthebox` (htb-solve) instead. ## Run it **WEB** — from a scope file or inline: ``` Workflow('pentest-engagement', { scope_file: 'projects/pentest/<engagement>-scope.md' }) Workflow('pentest-engagement', { scope: { engagement_name, apex_domains:[], assets:[...], creds_env:[...], roe, business_tier } }) ``` **NETWORK** — inline IP/CIDR list or a scope file containing one (a plain newline list of IPs/CIDRs is accepted): ``` Workflow('pentest-engagement', { targets: ['10.0.0.0/24', '192.0.2.0/24', '198.51.100.7'] }) Workflow('pentest-engagement', { scope_file: 'projects/pentest/<engagement>-ips.txt', scan_profile: 'standard' }) ``` Options (shared): `maxConcurrent` (default = **prudent, derived from CPU cores** — ~half the cores, capped 2–8; never hundreds/thousands of parallel tasks), `dryRun`, `max_experiments`, `business_tier`, `report` (default true). Options (network): `scan_profile` `light` (bounded `1-1024` + curated less-common, for large/fast sweeps) / **`standard`** (full-range `-p-` on every reachable host, DEFAULT; two-stage SYN→`-sV` on found-open ports, host-count-guarded, message-bus + non-443-TLS aware) / `full` (`-p-` + bounded UDP); `udp` (top-50 UDP; off for light/standard, auto-on for full); `slice_size` (hosts per scan worker, auto ≈64 IP-list / 2 CIDR-heavy); `deepen_top` (deep-dive the N highest-value hosts, default 10, `0` to skip); `geo_vantages` (≤2 gcp zones for the 2nd-vantage allowlist re-probe; overrides the US+EU default), `auto_provision` (default true; `false` = detect+flag only, no cloud spend). On a source-IP/geo-allowlist signature the workflow auto-provisions a 2nd-geography vantage and re-probes the filtered hosts before concluding "no surface." Write the scope file per [`reference/scope-file-format.md`](reference/scope-file-format.md). Credentials are referenced by **env-var name only** and read from the repo `.env` via `python3 tools/env-reader.py` — never inline secret values. ## Phases (what the workflow does) 1. **Setup** — `env-reader` creds, parse scope, **classify kind** (web|network), **read CPU cores → prudent parallel-task cap**, `OUTPUT_DIR = projects/pentest/<date>_<engagement>/`, STARTED Slack (gated). 2. **Expand** *(WEB, the #1 fix)* — MANDATORY CT-log / passive-DNS / origin-discovery across every in-scope apex (`crt.sh`, `certspotter`, `subfinder`, origin-discovery for CDN/WAF-fronted hosts). Scope = the **discovered** surface, not the handoff. Builds the per-asset work list + seeds each asset's coverage matrix. **Scan** *(NETWORK, replaces Expand)* — slice the IP/CIDR set into machine-prudent batches; **one nmap worker per slice** (agents scale with *slices* ≈ dozens, never with IP count) runs the SAME pipeline: host discovery (reachability is unknown) → bounded common+less-common port/service scan → CVE surfacing (`nmap --script vulners`, `nuclei`, each CVE-ID enriched via `tools/nvd-lookup.py`) → writes a **uniform per-IP tree** `hosts/<ip>/{recon,host.json,findings}` + a merged `recon/inventory/`. 3. **Assess** *(single interleaved stage — no separate downstream validation pass)* — WEB: each asset → `coordinator-loop` (**coverage mode**), which validates **each candidate the instant it is materialized** on fresh blind agents (strict per-finding cure/drop loop) before search continues. NETWORK: bounded `coordinator-loop` deep-dives on **only** the `deepen_top` highest-value hosts, same interleaved per-finding validation (everything else is the uniform tool-scan, not a per-host agent). **Coverage-by-VALID:** a class is covered only by a `VALID`/`REPAIRED` finding, a justified N/A, or a genuine negative — a class whose candidates were all rejected/dropped stays `pending` and search keeps going. 4. **Correlate** — `attack-path-stitcher` + `risk-prioritiser` across all validated findings → ranked org roadmap. 5. **Report** *(deterministic — no agent authors the report)* — JS hands the resolved engagement block + exact commands to ONE finalize runner: `tools/report_data_build.py` merges the namespaced interim finding-JSONs into the canonical `report_data.json` (the sole-owner assembly), then the **format-dispatched** renderer runs — `transilience` → the canonical `generate_report.py` PDF skill, `custom` → `custom_report_cmd` (or a Markdown fallback). JS then **hard-gates**: `report_data` assembled ∧ (transilience: `WROTE` ∧ `bytes>0` ∧ the `[assets: …/formats/transilience-report-style]` provenance tag), retry-once → `BLOCKED`. Only `VALID`/`REPAIRED` findings appear (**drop-entirely** — `validated/` is confirmed-only by construction); **REJECTED** (`false-positives/`) and uncured **DROPPED** (`dropped/`) never appear and there is no gaps/assurance section. The finalize runner also runs `network_coverage_map.py` (swept-host tail) + `coverage_gate.py` over the whole engagement, writes `reports/coverage-matrix.json`, and the deliverable includes a deterministic **Attack Pattern Coverage** section (surface-unit × attack-class). **COMPLETE is a hard 100% gate**: it requires the report to assemble+render AND the coverage gate to report `complete:true` (every applicable cell covered) — for BOTH web and network (network additionally requires scan-completion). Any untested applicable cell → `INCOMPLETE_coverage` / `BLOCKED`. 6. **Package & deliver** — a verified `<report_id>_deliverable.zip` (`reports/ input/ logs/ artifacts/`), a short **stats summary** (`summary.md`: agents, findings by severity, elapsed; tokens/cost render `unavailable — no runtime token counter`), and the workflow returns `slack_offer: true`. **Post-run (main loop, outside the workflow):** because coordinators must not call `AskUserQuestion`, the *invoking* agent shows the returned `summary` and asks whether to post the `deliverable_zip` to Slack; on **yes**, `python3 tools/slack-send.py --channel "$PENTEST_SLACK_CHANNEL_ID"` (gated on a successful, COMPLETE engagement). **Report options:** `report_format` `transilience` (default) | `custom`; `custom_report_cmd` (the custom renderer, receives the `report_data.json` path + `reports/` dir); `prior_report` (a prior PDF or `report_data.json` — its title/sector/scope are **metadata-only**, never seeding the work list) + `version` to mint the cover version + "Supersedes" line. ## Determinism (be honest) The decision layer is a **frozen pure-JS** `computeVerdict` (parity-guarded, fixture-pinned), its operands are **frozen per engagement** via NVD/KEV `--cache-dir` snapshots (`artifacts/nvd-cache/`, `artifacts/kev-snapshot.json`), and the adversarial quorum is raised to **3**. Given identical inputs the verdict is provably identical. But a **fresh** live run is **highly reproducible, not 100%** — LLM sampling produces the booleans/numbers that feed the verdict, and live-target drift moves the inputs; that ceiling is inherent and stated plainly, not papered over. Byte-identical results are a guarantee **100% only on replay** of a frozen evidence set (the Phase-2 replay cache, `artifacts/validation-cache/`) — that is the sole context in which "same request → same result" is a guarantee rather than a strong tendency. ## Boundaries - Orchestrator only — never run the coordinator loop inline; the coverage/bookkeeping discipline needs the workflow boundary. - A **missing credential is not a global block** — the unauthenticated surface is always tested; only a no-reachable-asset scope blocks. - Reversible own-org/own-tenant writes are authorized by default (create-then-delete is non-destructive); destructive ops, DoS, brute force, and out-of-scope tenants are prohibited (set in RoE). ## References - [scope-file-format.md](reference/scope-file-format.md) — scope file schema + worked example - coverage-matrix.md — the canonical attack-class coverage contract (completion gate) - principles.md — scope-is-the-surface, reversible active exploitation, real-tools-first, root-cause severity - pentest-report.md — Transilience report structure + §7.1 root-cause severity - validator-role.md — engagement-validator attack-class coverage check (8)