engagement
Persistent authorization, scope, and progress state for a bug-bounty engagement, plus first-class ingestion of an existing recon directory. Establishes the authorization+scope gate ONCE per engagement
SKILL.mdskills/engagement/SKILL.md
GitHubEngagement — persistent authorization, scope & recon-folder ingestion
This skill owns the engagement manifest: the one durable record that lets the whole ecosystem run a hunt continuously instead of re-asking the user for permission at every step. It is the memory behind "understand the engagement once, then work."
Scripts (stdlib, run isolated — python3 -I <script>):
scripts/engagement.py— create/reuse/update the manifest; classify targets; resume.scripts/ingest_recon.py— ingest a supplied recon directory into a hunt inventory.
Schema: schemas/engagement.schema.json. Format + resume rules: docs/ENGAGEMENT.md.
1. Establish the engagement ONCE (the only authorization gate)
At the start of a hunt, run the authorization + scope gate a single time:
- Identify the program and the scope the user supplied (program page, a scope file, or an explicit statement that the targets belong to a program they are authorized to hunt).
- Read any supplied rules, exclusions, testing restrictions, required headers, and rate limits. Extract them from the supplied page/files/workspace automatically — do not ask the user to retype what is already in front of you.
- Write the manifest:
python3 -I scripts/engagement.py --workspace recon init \
--program hackerone:acme --scope-source <url-or-path> \
--roots "*.acme.com, api.acme.io" --exclude "blog.acme.com, *.vendor.com" \
--rate-limit 5 --restrictions "no automated scanning; no DoS; payment flows need approval" \
--header "X-H1: <researcher-tag>" --posture production
init is idempotent: if a manifest for the same program already exists it is
reused (status reused), not re-gated — this is how resume avoids re-confirming
scope. A different program in the same workspace is a conflict: a new or materially
changed scope gets its own workspace/engagement. Authorization is never carried from
one program to unrelated targets.
Never pass raw credentials, cookies, API tokens, or session secrets to the manifest. The
script refuses secret-shaped values (exit 2) so they cannot enter persistent state. The
researcher-tag/required headers stored here are non-secret identifiers only.
2. Once established, stop re-asking
When authorization.established is true for the engagement, do not:
- re-ask whether the target is authorized,
- ask for approval before each request, URL, vulnerability class, specialist, or batch,
- ask the user to choose each next phase,
- ask "should I continue?" after each success,
- redo the scope-confirmation when resuming with a valid saved state.
Automatically choose the next logical action and continue until the workflow is complete, a genuine blocker occurs, or the permitted testing boundary is reached. If an essential detail is genuinely missing or contradictory, ask one consolidated question after exhausting the local files, supplied materials, and accessible program info — never turn one gap into a sequence of prompts. For non-essential gaps, use documented defaults that respect program rules and continue.
Human approval is still required for genuinely consequential actions (see
docs/SAFETY.md): destructive/disruptive production testing, a material scope ambiguity,
anything the program prohibits or restricts, mass test-account creation, payment-flow
testing, and any external report submission. Automation removes repeated confirmations,
never these gates.
3. Scope classification (never silently test the wrong thing)
python3 -I scripts/engagement.py --workspace recon classify app.acme.com blog.acme.com evil.com
Each target is in_scope, out_of_scope, or needs_clarification. Rules: exclusions
beat inclusions (an excluded host is never tested even when it shows up inside an in-scope
app's crawl output); a host matching no in-scope root is needs_clarification and is not
tested. Wildcards (*.acme.com, *.cloud.acme.com) match subdomains; a bare apex matches
only itself. Out-of-scope assets are recorded separately and never enter the hunt queue.
4. Recon: fresh vs supplied (decide, don't re-run blindly)
- Fresh recon needed → hand off to
recon-engine(scripts/recon.shis the standard active engine, vendored from the canonical repoM0st8fa/Recon-Script). Before the run, verify the engine is current:python3 -I <recon-engine>/scripts/recon_sync.py status --dir <clone>and, ifstale/missing,recon_sync.py ensure --dir <clone>(thensetup.shif the toolchain is absent). Then checkrecon.status: ifrunningor results already exist, do not launch a duplicate scan. - User supplied a recon directory → ingest it instead of running recon again:
python3 -I scripts/ingest_recon.py <recon_dir> --workspace recon
This inventories the directory recursively, reads run config/logs first (recording which
tools ran, failed, or were skipped — a failed tool is missing evidence, never coverage),
extracts URLs from .txt/.csv/.json/.jsonl, and builds a deduplicated master
inventory (inventory.jsonl) that preserves meaningful variants (method, param-set,
endpoint — a POST is never collapsed onto a GET, a parameterized URL never onto its bare
path) with source provenance. In-scope URLs get a suggested specialist route and
test_status: pending; out-of-scope URLs go to excluded_inventory.jsonl and are never
scheduled. Re-running the ingest preserves prior test_status, evidence, and
findings (resume-safe).
5. Schedule every distinct in-scope URL
python3 -I scripts/ingest_recon.py <recon_dir> --workspace recon --next-batch 50
python3 -I scripts/ingest_recon.py <recon_dir> --workspace recon --next-batch 50 --route bb-authz
Process all distinct in-scope URLs, not just the homepage or the first few lines —
batch and prioritize, but impose no arbitrary cap that leaves the rest untested. Route by
endpoint semantics: object/API endpoints → api-security/bb-authz/idor-runner,
parameterized search → bb-sqli/bb-xss, redirect/fetch params → bb-ssrf, JS bundles →
js-recon/js-audit, auth/account endpoints → bb-oauth/signup-agent. Mark each URL's
test_status done as you go; resume from the inventory, never from scratch.
6. Progress, resume & coverage
python3 -I scripts/engagement.py --workspace recon resume # next incomplete phase
python3 -I scripts/engagement.py --workspace recon set --phase routing --add-completed "inventory built"
Before declaring a hunt complete, review the inventory: which in-scope URLs were analyzed, which checks passed/failed, which remain. Do not claim full coverage while eligible work remains, or while a tool failure left a gap. Pass the manifest + inventory to specialists so they inherit scope, completed work, and evidence instead of restarting the interview.
Boundaries
Authorized, scoped, minimal-impact testing only. The manifest records authorization; it
does not grant it, and it never overrides program exclusions, rate limits, or prohibited
actions. See docs/SAFETY.md.