How execution moves
from scope to evidence.
The harness handles context, scope, tools, and execution. Security workflows live in inspectable skill packages. The agent dispatches, triages, and reports through the same controlled path.
bin/bb-init ──→ RunContext (.bb/context.env + .bb/context.json)
│
bin/bb-validate ──→ scope + registry checks
│
bin/bb-run ──→ skill.yaml → scripts/ + runbooks/ + payloads/
│ │
│ tool registry (99 tools)
│ safety tiers + circuit breaker
│ │
bin/bb-hunt ──→ autonomous: recon → domain-model → technique-kb → planner → execute → report
bounded by time budget, resumable
The execution path
Every engagement follows the same loop, whether run manually or via bb-hunt:
Target + Scope
bb-init writes the RunContext. Scope file defines authorization. No scope, no intrusive.
Assets + Surfaces
Recon enumerates, domain-model classifies archetype, technique-kb maps applicable bug classes.
Ranked Test Plan
Planner generates a prioritized plan from the model. You run what matters, not everything.
Rate-Limited Workflows
Skill workflows run with safety-tier gating and circuit-breaker backoff.
Impact + PoC
Impact-verifier checks preconditions and evidence. Scanner output is not a finding.
Evidence Pack
Reporting assembles request, response, PoC, screenshot, CVSS, and manifest.
What Lives Where
| Path | Role |
|---|---|
bin/bb-init | Creates .bb/context.env + .bb/context.json |
bin/bb-validate | Checks context and registry health |
bin/bb-run | Executes one workflow from .claude/skills/<skill>/skill.yaml |
bin/bb-hunt | Autonomous campaign (thin wrapper over campaign skill) |
bin/bb-tools | Install, verify, lock external tools |
tools/registry/*.yaml | Canonical tool definitions |
.claude/skills/<skill>/ | SKILL.md, skill.yaml, scripts, runbooks, payloads |
RunContext
bb-init writes these variables for every workflow to consume:
TARGET # primary target domain OUTDIR # output dir for this run SCOPE_FILE # authorization file RATE_LIMIT # requests per second USER_AGENT # security research UA