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 engines (coordinator-loop, validate-findings), 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 web / API / cloud engagement defined by a scope file (assets, credentials, rules of engagement) — not a CTF/flag target. For HackTheBox/CTF use hackthebox (htb-solve) instead.

Run it

Workflow('pentest-engagement', { scope_file: 'projects/pentest/<engagement>-scope.md' })

or inline scope:

Workflow('pentest-engagement', { scope: { engagement_name, apex_domains:[], assets:[...], creds_env:[...], roe, business_tier } })

Options: maxConcurrent (default 3), dryRun (expand surface + work list only, no exploitation), max_experiments, business_tier, report (default true).

Write the scope file per 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, OUTPUT_DIR = projects/pentest/<date>_<engagement>/, STARTED Slack (gated).
2. Expand (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.
3. Assess — each asset → coordinator-loop in coverage mode (drives the OWASP API+Web attack-class matrix to completion; reversible active exploitation; root-cause severity) → validate-findings (authoritative).
4. Correlate — attack-path-stitcher + risk-prioritiser across all validated findings → ranked org roadmap.
5. Report — Transilience PDF over the validated + ranked set. COMPLETE only when every asset's coverage is satisfied; otherwise INCOMPLETE_coverage with the untested classes named.

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 — 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)