Skip to content
Bugb Docs

What bugb needs

bugb needs a different set of tools depending on how far you intend to go. The model tier needs one. The verify tier needs four, and one of them is a coding agent that will edit your repository unattended.

This page is the check to run before either. It does not install anything — it tells you what each tier requires and how to prove it is there.

What each tier requires

Section titled “What each tier requires”
Tool Model tier Verify tier What it is for
bugb required required the loop itself
Python ≥ 3.11 required required bugb is a Python package
guardlink required required parses the annotations, produces the SARIF export
cxg — required executes the probes against the target
Docker — required for a lab stands the disposable target environment up
a coding-agent CLI — required the judgment points: annotation, recipe authoring, goal enrichment, write-back

The agent CLI is one of claude, codex, or gemini. The VS Code extension can supply the editor’s own model instead, through bugb’s bridge provider.

Prove you have them

Section titled “Prove you have them”

  1. bugb and Python.

    Terminal window
    bugb --version
    python3 -V
    bugb 0.1.0
    Python 3.12.13

  2. guardlink — the model tier’s one external dependency.

    Terminal window
    guardlink --version
    2.0.0

    If this fails, install it: npm install -g guardlink. See guardlink installation.

    At this point the model tier works. Everything below is for the verify tier.

  3. cxg — the engine that runs the probes.

    Terminal window
    cxg --version
    cxg 1.3.0

    See Install cxg. The pentest pipeline inside it is materialised separately, by cxg pentest install — see Pentest a web application.

  4. Docker — only if bugb is to stand a lab up for you. A run against a target you started yourself does not need it.

    Terminal window
    docker --version
    Docker version 29.4.0, build 9d7ad9f

  5. A coding-agent CLI.

    Terminal window
    claude --version
    2.1.234 (Claude Code)

    codex and gemini are the alternatives. Which one a run uses is the --agent flag, or the default_agent key in $BUGB_HOME/config.toml.

Where bugb keeps its state

Section titled “Where bugb keeps its state”

None of it is in your repository.

Path Holds
$BUGB_HOME (default ~/.bugb) everything below
$BUGB_HOME/runs/<run-id>/ one directory per run: manifest, journal, events, ledger, per-round goals, probe templates, cxg logs, reports
$BUGB_HOME/envs/<slug>/ the environment recipe for one target, replayed on later runs
$BUGB_HOME/config.toml optional; every field has a working default

Your repository receives exactly two things, and only on the verify tier: a bugb/run-<id> branch, and annotation comments committed to it. --no-checkpoint turns even that off. The reasoning is in Authorization and blast radius.

Override the location with --home, or by exporting BUGB_HOME.

Next

Section titled “Next”