Metadata-Version: 2.5
Name: bravos
Version: 0.3.1
Summary: Continuous SAST and whitebox pentest orchestrator
Project-URL: Homepage, https://bugb.io
Project-URL: Bug Tracker, https://bugb.io
Author: Bugb Technologies
License: Copyright (c) 2026 Bugb Technologies. All rights reserved.
        
        Bugb Technologies grants you a free, worldwide, non-exclusive, perpetual right to install and use
        this software for any purpose, including commercial use, at no charge.
        
        This software is not open source. Except with Bugb Technologies' prior written permission, you may
        not redistribute it, sell it, or distribute a modified or derivative version of it. All rights not
        expressly granted here are reserved by Bugb Technologies.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
        NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
        DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: appsec,guardlink,pentest,sarif,security,threat-model
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Free To Use But Restricted
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: cryptography<51,>=42
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.29.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: hatchling>=1.24; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# bravos

**Point it at a repo and it runs an autonomous whitebox pentest loop — annotating, probing, and verifying until every threat is confirmed or cleared.**

> `bravos` is the command, and the only one this package installs. It was called `bugb` up to
> 0.1.0; everything that name wrote is still read, so upgrading needs no migration — see
> [Upgrading from `bugb`](#upgrading-from-bugb).
> Free to use — see [LICENSE](LICENSE).

bravos drives [guardlink](https://guardlink.bugb.io) (threat-model annotation + SARIF export) and
cert-x-gen (`cxg pentest`, authenticated probe execution) in a closed loop. You describe what you
want in plain language; bravos derives a reviewable plan, stands up a lab, captures identities, then
annotates under rotating attack perspectives, synthesises pentest goals, runs real probes, writes
confirmed findings back into the source, and repeats — until several consecutive healthy rounds
surface nothing new and it can say *why* it stopped.

```
        ┌──────────────────────────  round N (lens L)  ──────────────────────────┐
  brief │  annotate → export → synthesise → probe → write-back → report          │
   ───▶ │   (agent)   (SARIF)   (goals)     (cxg)    (@confirmed)  (advisory)     │ ──▶ converged
        └───────────────────────────────────┬────────────────────────────────────┘
                                             ▼
                                   rotate lens · evaluate convergence
```

Every threat ends the run with a verdict and a reason: **CONFIRMED**, **REFUTED**, **mitigation-held**,
or an honest **not-tested** with the gap explained. Confirmed findings become `@confirmed`
annotations in the code and GitHub-style advisories with the exact probe that proved them.

---

## Contents

- [Quickstart](#quickstart)
- [Upgrading from `bugb`](#upgrading-from-bugb)
- [The web interface](#the-web-interface)
- [How a scan works](#how-a-scan-works)
- [Command reference](#command-reference)
- [Gate a build without a target](#gate-a-build-without-a-target)
- [Ask the code graph from a terminal](#ask-the-code-graph-from-a-terminal)
- [Send a run to a server — and what a push uploads](#send-a-run-to-a-server--and-what-a-push-uploads)
- [Point a coding agent at bravos (MCP)](#point-a-coding-agent-at-bravos-mcp)
- [Why bravos isn't naive](#why-bravos-isnt-naive)
- [Architecture](#architecture)
- [Testing](#testing)
- [Authorization](#authorization)

---

## Quickstart

**Install** (free to use, Python ≥ 3.11).

```bash
pipx install bravos          # or: pip install bravos
```

**Requirements:** `guardlink` on `PATH` for the model tier (`npm install -g guardlink`) — it is what
maintains the annotations. The verify tier additionally needs `cxg` and Docker (`cxg pentest
install`), plus one coding-agent CLI — `claude`, `codex`, or `gemini` — or your editor's own model,
for the judgment points.

**The graph tier needs no licence, no toolchain and no annotations in your code — but it does need
the graph binaries, and not every wheel carries them.** They travel inside the wheel itself rather
than being downloaded on first use, so whether
[`bravos graph build`](#ask-the-code-graph-from-a-terminal) and `bravos graph` work depends on which
wheel this install came from: a wheel is built for one platform and carries the binaries for it,
and the pure-Python `py3-none-any` wheel on the index carries none. `bravos setup --check` is the
answer for the install in front of you — it reports **GRAPH TIER** available or unavailable, and
when the binaries are there, which platform they were built for and which commit of the graph they
came from.

**The analyzer is licensed, and having the binary is not having the licence.** `bravos-cli` runs
the deterministic SAST analysis, and every `bravos sast scan` verifies a signed licence before it
starts one. Put yours at `~/.bravos/licence.jwt` or in `$BRAVOS_LICENCE` — which takes the token
itself as well as a path, for a CI runner that holds secrets and not files. The file the portal
downloads, `bravos-license.jwt`, works as it is in `~/.bravos/`. Verification is
**offline**: no network call, no account lookup, and an air-gapped machine verifies exactly as well
as a connected one for as long as its licence is unexpired. Without one `bravos setup --check`
reports the SAST channel **unavailable**, and `bravos sast scan` refuses with exit 3 — *this
machine cannot do it* — rather than exit 0 over an empty report, because a scan that could not run
and a scan that found nothing are different answers.

**On a licensed machine, `bravos setup` installs the analyzer.** With your consent, as for every
other install: it checks the licence first and fetches nothing without one, verifies the analyzer's
signature before anything is written, and stages it under `~/.bravos/analyzer/` together with its
rules, gitleaks, osv-scanner, kics and zizmor — the set the CI runner image carries — plus the
runner image's pinned Semgrep in an environment of its own. `bravos sast scan` and `bravos sast
gate` then run on your laptop the way they run in CI. How it works, and every way it refuses:
[`docs/design/analyzer-laptop-install.md`](docs/design/analyzer-laptop-install.md).

**The analyzer brings six prerequisites of its own, and each one is a class of finding.** They are
ordinary open-source scanners, every one of them freely usable, and the analyzer drives them rather
than reimplementing them:

| tool | what it covers | without it |
|---|---|---|
| `semgrep` | the primary engine, and the one *required* stage | the analyzer exits before it scans — there is no report to read |
| `gitleaks` | committed secrets, working tree **and git history** | the scan completes and reports itself degraded; the secret class is not in it |
| `osv-scanner` | dependency advisories, from your lockfiles | the scan completes and reports itself degraded; nothing else reads a lockfile |
| `kics` | Terraform, Kubernetes, Dockerfiles, CloudFormation, CI configs | thinner infrastructure coverage |
| `zizmor` | GitHub Actions workflows | the workflows in `.github/` are not read |
| `checkov` | extra infrastructure breadth — **opt-in**, nothing runs it unless asked | nothing; it is off by default |

`bravos setup --check` lists them under the SAST channel with what each one is and how to get it,
and says beside the channel's verdict what an otherwise-available channel is **not** doing — so
`SAST CHANNEL available (secret scanning is off — gitleaks is not installed)` is a thing you can
read on one line rather than infer from a row further down.

**Without the analyzer install, `bravos setup` installs the two that a single command can install
everywhere.** `semgrep` and
`zizmor` publish to PyPI, so `bravos setup --yes` runs `pipx install …` for them with your consent,
exactly as it installs guardlink for a machine that has npm. `pipx` rather than `pip` because these
are command-line tools rather than libraries: `pip install` is refused outright by the
externally-managed interpreters that Homebrew, Debian, Ubuntu and Fedora ship, and on the
interpreters that accept it, it installs an engine into whichever environment happens to be active
— which is yours, not ours. The rest are single-file binaries with no one command that works
everywhere, so bravos names the route and leaves the choice to you. **An absent prerequisite never
changes this command's exit code**: the SAST channel is additive, and a machine that only wants the
free tiers is still a ready machine.

**`setup --check` proves the SAST channel rather than probing it.** Asking the analyzer for
`--version` and `analyze --help` establishes that a binary is reachable and has the verb — not that
a scan completes, which is a different question and the one a caller is actually asking. So when
the analyzer is present the check runs a real `bravos analyze` over a six-line fixture bravos owns,
through the same adapter `bravos sast scan` uses, and reports the analyzer's own verdict in three
states: **available** (the engine ran and its rules matched), **degraded** (the engine ran and
matched nothing — scans will complete and under-report), and **unavailable** (a required stage did
not run, so findings would be a floor rather than a result). Each of the last two carries the
reason, and the analyzer's own sentence naming the fix. It costs a few seconds and writes only
under `$BRAVOS_HOME`; `--no-scan-proof` skips it, and every surface then reports `(unproved)`
because the verdict rests on probes a broken scan can pass.

The fastest path is to describe the scan and let bravos derive a plan:

```bash
bravos intake "Thorough pentest of my app at /path/to/repo. It runs on
https://app.example.com, logins admin@example.com/Admin123! and user@example.com/User123!.
I've annotated with guardlink before but not deeply — go deep and find chained exploits.
I want all confirmed vulnerabilities."
```

bravos reads the brief *and* the repository, then prints a plan you can argue with:

```
  PLAN 20260729-032359-portainer-2.39.2   derived from your brief

  WHAT BRAVOS UNDERSTOOD
    Go deep on portainer past the annotations it already carries and confirm
    chained exploits against the running instance.
    ↳ your brief and this sentence are both carried into every annotation round

  codebase     portainer-2.39.2                               ok
  target       http://localhost:9054                          ok
  auth         credentials from your brief — refreshes itself ok
  lenses       unauth → mitigation-audit → stduser → crosstenant → chained
  depth        deep — up to 20 rounds, 4 dry to converge      ok
  agent        codex                                          ok

  FOUND IN THE REPOSITORY
    annotations  233   exposures 43   confirmed 2
    suppressed   17 pair(s) hidden from the export
```

**Approving the plan is the consent** — for the actions it lists, and for the words behind them:
your brief and that one-sentence reading are carried into every annotation round's prompt, so what
you asked for steers what gets annotated. Anything that reads as a credential is starred out of both
first. Then run the whole loop unattended:

```bash
bravos auto --plan 20260729-032359-portainer-2.39.2
```

Or skip intake and drive it directly against a running target:

```bash
bravos auto /path/to/repo --target http://localhost:9054 --auth alice,bob \
  --attestation "Authorized self-test, <name>"
```

Interrupt any time and pick up where it stopped:

```bash
bravos resume            # list resumable runs
bravos resume <run-id>   # continue from the interrupted phase
```

---

## Upgrading from `bugb`

This CLI was called `bugb` up to 0.1.0. Everything it wrote under that name is still read, so an
in-place upgrade needs no migration step — with one exception, the command itself:

| What you have | What happens |
|---|---|
| the `bugb` command in scripts and CI | **replace it with `bravos`.** This package installs one command, and `bugb` is not it |
| `~/.bugb` full of runs | used as the state root while `~/.bravos` holds no runs of its own |
| `.bugb/` committed in a repository — `policy.toml`, `sast-policy.toml`, `verifications.json`, `sessions/` | read as it stands; the CI gate keeps the threshold you committed |
| `$BUGB_TOKEN`, `$BUGB_SERVER_URL`, `$BUGB_HOME` in a pipeline | still read |
| `git config bugb.server.url` / `bugb.projectId` in a checkout | still read, so a repository keeps pushing under the same name |
| `bugb/run-*` branches, `bugb/baseline/*` and `bugb/annotated/*` tags | still recognised, so a run resumed across the upgrade finds its baseline |
| auth profiles captured before the rename | still carry their bearer token |

Each of the state rows says so once on **stderr** — never stdout, so `bravos ci --format json`
stays a document a pipeline can parse. New state is always written under the new name, so migrating is
whenever you like:

```bash
mv ~/.bugb ~/.bravos                          # your runs, ledgers and promoted templates
git mv .bugb .bravos                          # a repository's committed policy and sessions
git config bravos.server.url "$(git config bugb.server.url)"
```

The old names are read, not supported forever; they stop being read in a future release.

---

## The web interface

```bash
bravos dashboard  # → http://127.0.0.1:8787
```

A single self-contained page (standard library only — no build step, no external assets, works
offline, strict CSP). Auto light/dark, GitHub-style. Four views:

- **New scan** — the landing page. Write a brief in plain language, pick example templates, review
  the derived plan.
- **Plans** — every derived plan; approve one to get the run command.
- **Repositories** — findings organised per codebase. Each repo splits into a **Guardlink findings**
  table (every exposure, marked *tested* / *not tested* with the reason the loop recorded — the gap
  of what is still unprobed) and **Advisories** (cxg-verified findings, *Verified* / *Closed*). An
  advisory reads like a GitHub security advisory and embeds the **exact cxg probe** that produced the
  verdict, with save-and-run commands so you can reproduce it.
- **Runs** — a live master-detail view of every run, with stat tiles, a rounds timeline, and a
  streaming event log.

Deliberately **not** a control plane: it derives, approves, and displays — then hands you the CLI
command. The CLI stays the only thing that executes a scan, so there's no second path that can
drift from it. Loopback only; credentials are redacted before anything reaches the browser.

---

## How a scan works

### 1 · Intake → a reviewable plan

An agent reads your brief; bravos measures the repository; a second agent call commits to specifics
grounded in what's actually there — the login shape read from the auth handler, the lens rotation,
and an explicit list of what it couldn't determine. Three auth modes fall out of what you wrote:

| You said | Mode | Behaviour |
|---|---|---|
| nothing about auth, no env | `SEED` | a seed script creates ≥2 equal-privilege users, then self-heals |
| a credentials table | `CREDENTIALS` | fully unattended; re-authenticates forever |
| "I need a browser to log in" | `BROWSER` | flagged at plan time; the run pauses there |

Because every real brief says *"I've annotated a few times,"* the plan seeds a **round-0 baseline**
first, so round one measures only what it *adds* rather than counting the whole backlog as new.

### 2 · Environment & self-healing identities

A recipe is authored once per target (`bravos env init`) and replayed deterministically after that —
an environment that differs between rounds makes verdicts incomparable. bravos captures sessions with
its **own headless login**, because cert-x-gen's hardcodes `POST /api/auth/login` with
`{email,password}` and a `csrf_token` cookie, which throws on real targets (Portainer is
`POST /api/auth` with `{Username,Password}`, a JWT in the body, and an `X-CSRF-Token` *response
header*). `LoginSpec` makes all of that data. When sessions expire mid-scan, bravos re-authenticates
itself; it pauses only when a login genuinely needs a human.

### 3 · Lenses

Six perspectives, rotated deterministically: `unauth`, `mitigation-audit`, `stduser`,
`crosstenant`, `admin`, `chained`. Round 1 is always `unauth` (no identities, so it fails fast on a
broken env). `mitigation-audit` is scheduled second on purpose: a single `@mitigates` removes every
exposure sharing its pair from the export, so a control that's 90% correct is more dangerous than
none — it silently ends the investigation. Asking *"does the declared control actually hold?"* is
what produced a real bind-mount CVE.

### 4 · Goals

Each goal is assembled from eight slots, all but one fully deterministic:

| Slot | Source |
|---|---|
| scope | exposure + resolved route |
| actor | lens + seeded identities |
| chain | the declared `@flows` edge this exposure consumes — empty unless the run chains (see below) |
| **preamble** | environment recipe (`goal_preamble`) — e.g. a CSRF handshake |
| directives | the approved plan (the operator's emphasis, the OAST canary) |
| mechanism | the SARIF message, verbatim |
| baseline | lens (the control that must still hold) |
| success | per vulnerability class |

The **preamble** is the highest-leverage slot: without the target's CSRF handshake every mutating
request 403s, the vulnerable code is never reached, and cxg reports the mitigation as holding — a
false negative indistinguishable from a clean result. It lives in the recipe, written once per
target. Only concrete exploit bodies and unresolved routes need an agent, batched into one call
per round.

### 5 · Probe, classify, correlate

Goals run concurrently, each in its own session directory. Neither cxg's exit code nor its report
body is trusted alone: exit `0` covers a clean scan, a scan that skipped every probe for lack of
identities, *and* a scan aborted by a 5xx hard-kill, while a scan that **stopped early** writes a
report whose findings list is indistinguishable from a clean one's. bravos reads both, plus the
three places cxg says its own scan did not finish — exit `3`, the `scan_truncated_before_completion`
report caveat, and the audit log's `scan_end` footer. Any one of them on its own is believed, and
the run is `TRUNCATED`: untested, never clean. A value bravos *cannot read* is refused rather than
coerced: `caveats` or `scope_stats` written in a shape this bravos does not understand is never read
as "nothing to report", and since those two are what would say the scan finished and reached the
target, refusing either blocks the clean path — the run is `ERROR`, not `CLEAN`. **Only CONFIRMED
and CLEAN may move a verdict** — every other outcome leaves the threat in the backlog, because a
scan that never reached the target is not evidence. Findings are traced back to their exposure by
a deterministic template join (verified against cxg's own cache-key function); anything ambiguous
is `UNCORRELATED` and never written back. Tracing a finding is not on its own a licence to sign for
it: when a finding's own `threat_id` names an exposure this run's goal never asked about, bravos
reports its best reading and still refuses to write a `@confirmed` for it, or to close the exposure
as a control that held — a refusal to sign beats a precise wrong claim in someone else's
repository (`docs/prd/threat-id-design.md` §5).

### 6 · Write-back & the ledger

Confirmed findings become `@confirmed` annotations next to the vulnerable line —
**verified by re-parsing the model**, not by trusting the agent — so the knowledge is durable and
guardlink stops re-surfacing them. The **ledger** (every exposure bravos has ever seen, with a
verdict and reason) is the dedup authority: a `CONFIRMED` exposure is terminal and never re-goaled,
so the loop never re-tests the same thing.

### 7 · Convergence

A round is **dry** only if it found nothing, was healthy, *and* left nothing untested — a threat
cxg reported it could not reach, or a coverage statement bravos could not read, keeps the round out
of the streak either way. A round degraded by timeouts or dead sessions is neutral — it neither
advances nor resets the streak, because its emptiness proves nothing. The loop stops after N
consecutive healthy dry rounds, when every lens is retired, or on a budget ceiling — each with a
recorded reason.

---

## Command reference

| Command | What it does |
|---|---|
| `bravos intake "<brief>"` | Turn a plain-language brief into a reviewable plan (repeat `--scope-host <name>` when part of the app answers on a second hostname, e.g. an API — probes otherwise reach the target's own host only; add `--service-url <repo>=<url>` to send that member repository's probes to its own address rather than to `--target`) |
| `bravos dashboard` | Local setup + results page (loopback) |
| `bravos auto <repo>` / `--plan <id>` | The whole loop, one command (drives interactive SSO/MFA logins inline; `--no-capture` pauses instead; add `--chain-declared-flows` to test declared cross-service `@flows` edges as chains — see below) |
| `bravos resume [<id>]` | List resumable runs, or continue one (keeps the run's `--ai-provider` and `--chain-declared-flows`) |
| `bravos run <repo>` | Drive rounds against a supplied `--target` |
| `bravos round <repo> --lens L` | Plan + execute a single round (the other verb that takes `--chain-declared-flows`) |
| `bravos plan <repo> --lens L` | Show the goals and cxg commands a round *would* run |
| `bravos inspect <repo>` | Threat-model state + where guardlink's view is lossy |
| `bravos env init\|up\|login\|health\|down` | Stand up / manage a disposable lab |
| `bravos env auth <slug> [--check]` | Login readiness per identity + the exact capture command (`--check` probes the target) |
| `bravos env rm <slug> [--auth]` | Forget a saved recipe so the repo is re-planned from the brief (`--auth` also clears its sessions) |
| `bravos ledger --run <id>` | Every verdict and its reason |
| `bravos ci [--run <id>]` | Judge a run's ledger against `.bravos/policy.toml`: PASS / WARN / FAIL (exit 1 = breach, 2 = could not evaluate; `--policy-template` prints a commented starter; `--format json` for pipelines — [guide](docs/ci/README.md#the-gate-with-no-target-and-no-agent), [design](docs/design/ci-gate-design.md)) |
| `bravos push [--run <id>]` | Upload a run to your team's Bravos server: the ledger, the run summary, the guardlink dashboard, the per-finding advisories, and the code graph's security surface (`--no-graph` sends everything but the last — [exactly what is uploaded](#send-a-run-to-a-server--and-what-a-push-uploads)) |
| `bravos sast scan\|gate` | The separate deterministic-SAST channel: its own report, its own `.bravos/sast-policy.toml`, its own exit code |
| `bravos graph build <repo>` | Index a repository into its code graph — ships in the wheel, needs no licence and no annotations ([below](#ask-the-code-graph-from-a-terminal)) |
| `bravos graph [<question>]` | Ask the code graph from a terminal — bare, it lists what this repository's graph can answer; `bravos graph callers 'src/ci.py::gate'`, `bravos graph reachable-exposures <symbol>`, `--json` for pipelines ([below](#ask-the-code-graph-from-a-terminal)) |
| `bravos mcp` | Serve bravos to a coding agent over stdio — the threat model, the ledger and the code graph as MCP tools ([below](#point-a-coding-agent-at-bravos-mcp)) |
| `bravos doctor` | What this machine can run and what would change that — the same report as `bravos setup --check`, under the name the analyzer uses (`--json` for pipelines) |
| `bravos version` | Which build this is — the verb form of `--version` |

Runs that edit code or send traffic require an explicit `--attestation` — recorded in cxg's audit
log as your assertion that the target is yours to test — unless it came from an approved plan.
`<repo>` also accepts a folder that holds several repositories, provided each repository directly
beneath it is initialised with `guardlink init`; the run then sees all of their weaknesses. Work
lands on a `bravos/run-<id>` branch, one commit per phase, so every round is reviewable and
revertible.

### Gate a build without a target

**A working CI gate needs no target, no agent and no credentials.** `bravos model`
reads the repository's guardlink annotations into a ledger — guardlink, git and node, nothing
else, and no traffic leaves the machine. It is not read-only, though: left to itself it checks the
checkout out onto a `bravos/run-<id>` branch and publishes nine files into it, so the recipe below
passes `--no-publish --no-checkpoint` to suppress both. `bravos ci` judges that ledger against a policy file that
lives in the repository beside the code it gates. Measured end to end: **0.9 s + 0.1 s.**

```bash
bravos model . --no-publish --no-checkpoint   # produce the ledger, touch no files
bravos ci                                     # judge it — this step's exit code is the job's
```

By default it **warns rather than blocks**: every live finding is named, in the terminal and in
`--format json`, and the build stays green. A team turns the dial when they are ready, and can set
a different floor per verdict class — a *reproduced* exploit is not the same news as one nobody has
tested yet:

```toml
# .bravos/policy.toml     ·     bravos ci --policy-template > .bravos/policy.toml
fail_on = ["confirmed", "unverified"]

[fail_on_severity]
default    = "none"
confirmed  = "high"        # reproduced: fail from high up
unverified = "critical"    # declared but untested: fail only on criticals
```

The three outcomes are `PASS` (nothing found), `WARN` (found, below your floor — exit 0) and
`FAIL` (exit 1). Read them from the `verdict` field in JSON: `passed` is true for both of the
first two, which is exactly the distinction the warning tier exists to expose.

`bravos model` and `bravos annotate` also publish `.guardlink/report.json` — the file
`bravos analyze`'s CodeGraph ingests — and refresh the eight agent instruction files, so the next
coding agent opened in the repository reads the model as it stands. `bravos inspect` reports when
those have gone stale without fixing them. Full guide: [docs/ci/README.md](docs/ci/README.md).

### Testing an attack that crosses between services

`--chain-declared-flows` (off by default) makes a run test a declared cross-service data flow as one
chained attack instead of two unrelated findings. When the threat model declares

```
// @flows #web-checkout -> #api-refund via refund_token -- "the checkout page mints the token the API trusts"
```

and *both* ends are exposures in the run, the goal that tests the consumer names the provider and
its template budget is widened to cover it, so the probe engine can generate the pair together: one
template that plants the value and one that spends it. Without the flag the provider is usually
outranked and the connection is found and then discarded.

Four things to know before turning it on:

- **It costs money.** Roughly 120s and one AI generation call per extra template, on partnered goals
  only. One declared edge costs one template however many exposures its source asset has.
  `cxg.chain_partner_cap` (default 2) bounds how many declared edges one goal may be widened for;
  edges beyond the cap are reported as untested, never dropped silently.
- **Only a generating run derives an edge, and a run that cannot chain says so at launch.**
  `--fast` gives a goal one template, and one template has no partner to pair with; a partnered goal
  steps around the reuse cache in both directions — it will not replay a probe generated before the
  goal named a partner, and it stores none of its own, because its two templates were written
  against two different files and an entry records one — so it pays for generation on every run;
  and a `--from-registry` pass synthesises no goals, so it never chains and never reports a
  dropped edge.
  Every replay path (`bravos replay`, carry-and-verify, `--from-registry`) does fire with chaining
  enabled, so a stored chained probe runs as written and one whose provider is absent is reported as
  skipped rather than counted as a probe that found nothing.
- **Nothing discovers a flow, and the line has to be somewhere the probe engine reads.** A human or
  an assistant has to write the `@flows` line. An unwritten connection is indistinguishable from an
  application that has none. cert-x-gen reads declarations only from the source files it walks
  itself — `.ts/.tsx/.js/.jsx/.py/.rb/.go/.rs/.java/.php/.html` — so a declaration in a `.gal`
  sidecar (`guardlink.annotation_mode = "external"`, which means *every* declaration) or in a
  language it does not walk is refused rather than paid for. External annotation mode is named at
  launch, since it disables the capability wholesale; a single declaration in a language cxg does
  not read is refused without a line of its own, so write the crossing in a file it walks.
- **A crossing between two addresses needs each service's address.** A generated template is built
  against the run's single `--target`, so without a mapping both ends of a crossing are probed
  there — and if your provider and consumer answer at different addresses (another hostname, or the
  same host on another port) the provider probe is aimed at the wrong service, where it 404s, and
  the edge is reported dropped for a reason that is neither the ranker nor the annotation. Say
  where each repository answers:

  ```console
  bravos intake --scope-host web.example.com \
                --scope-host api.example.com \
                --service-url web=https://web.example.com \
                --service-url api=https://api.example.com \
                "test shop/ at https://web.example.com"
  ```

  The key is the **first path segment** of a finding's path as guardlink records it — the member
  repository's directory in a folder of initialised repositories, or the top-level package
  directory in a monorepo initialised at its own root, since guardlink records a finding under
  `api/src/refund.ts` either way. It addresses *everything* beneath that segment, so a **nested
  workspace cannot be addressed per service today**: a root laid out as `apps/web` and `apps/api`
  has one first segment, `apps`, and mapping it sends both services' probes to the one address.
  Bravos does not refuse that — it cannot tell a package directory from any other, and refusing
  would mean asserting they are separate services. Where you have **declared a `@flows` crossing**
  between two of those child directories, the launch notice names them and the one address they
  share. That reads your threat model, so it can only speak once one exists: at approval time the
  rule above — the key is a first path segment — is what you reason with.
  What is refused before you approve it is a key that matches
  **nothing** — that is the disclosure failure, because you would believe traffic goes to one
  service while it goes to another. A key that matches *everything* is not refused: on a codebase
  whose sources all sit under `src/`, `--service-url src=<url>` is accepted and directs every
  probe there, because both halves are declared — you named the directory and you named the
  address, and nothing is inferred. Refusing it would be bravos overriding an explicit,
  unambiguous instruction because it looks redundant, which is not a judgement this tool is
  entitled to make. Nothing is derived: a repository you do not map keeps resolving against
  `--target`, exactly as before. Every host you send to must also be authorised with `--scope-host` —
  including the target's own if you map its repository, as above — and a mapping naming a host the
  plan does not authorise is refused when you type it, not when the run starts. `--scope-host` takes
  a HOST and not an address deliberately: it authorises where traffic *may* go, and that permission
  ignores ports, while where a probe is actually *sent* is the full URL you map here. The plan
  states the mapping as its own row on all three approval surfaces, and the run repeats it at
  launch, because a stale address turns every probe for that repository into a 404 that reads as
  the application defending itself.

  **Put each service's mount point in its own URL.** The `api_base` on your env recipe is the
  target's mount point, and it is applied only to services at the target's own **origin** — scheme,
  host *and* port — so map `api=https://api.example.com/v2`, not `api=https://api.example.com`, if
  that service answers under `/v2`. A service on the target's own hostname but another port
  (`--target http://localhost:3000` with `--service-url api=http://localhost:8080`) is a different
  origin and carries its own mount point too: map `api=http://localhost:8080/v1` if it answers under
  `/v1`. Only the repository sitting at the target's own origin is the exception: it keeps the
  recipe's `api_base`, so mapping it does not cost you the mount point you already configured.

Write the annotation in the form the probe engine parses: flat ids on both ends (`#api-refund`, not
`#api.refund`) and a mandatory `via <channel>`. `guardlink link-project` currently teaches a
different cross-repo form that cert-x-gen's parser rejects; if your repository's agent instructions
show that form, the form above is the one that works.

---

## Ask the code graph from a terminal

The code graph answers sixteen questions — who calls this, what it calls, what a change reaches,
what is in this file, what is declared exposed, what this repository says it protects, which
declared exposures no test reaches, who signed for a risk and when that lapses, and *which declared
exposures control entering here touches*. Until `bravos graph` the only way to ask any of them was
to wire up an MCP server.

**The graph ships inside the wheel and needs no licence.** The two binaries are
`codegraph-build`, which indexes a repository, and `codegraph-mcp`, which answers questions about
one. Neither needs a key, a server, or a single annotation in your code. They are carried by the
wheel rather than fetched, so an install has them only if the wheel it came from was built with
them — the `py3-none-any` wheel on the index was not; `bravos setup --check` reports under
**GRAPH TIER** whether this install can answer, separately from the licensed analyzer. With them
in place, index once, then ask:

```console
$ bravos graph build .               # index this repository — seconds to a couple of minutes
  indexed      13,138 nodes · 50,278 edges · 445 files
  annotations  424 GuardLink annotation(s) read from the source
  address      d11a187631d9bbae (git-remote) · main
```

A repository with no annotations still gets a graph and still answers every structural question —
the security columns are blank because the model is silent, which the output says out loud rather
than leaving you to read as "clean". `bravos sast scan` also builds a graph on its way to a scan,
but that is the licensed analyzer; `bravos graph build` is the free route to the same graph.

```console
$ bravos graph                       # what this repository's graph can be asked
$ bravos graph search gate           # find a symbol — results carry its exact address
$ bravos graph callers 'src/bravos/commands/ci.py::gate'
$ bravos graph reachable-exposures handle_request --max-depth 6 --json
```

`bravos graph` fronts whatever the graph advertises rather than a list kept here, so a question the
graph learns is answerable the day it lands — with its own `--help`, generated from the tool's own
schema (`bravos graph <question> --help`).

**A symbol is addressed exactly.** `evaluate`, `Scanner.evaluate`, or `src/scan.ts::evaluate` — the
last being the graph's own node id, which is what `bravos graph search` prints. A name several
symbols carry is refused *with its candidates* rather than answered about an arbitrary one of them:

```console
$ bravos graph callers evaluate
bravos: Symbol 'evaluate' is ambiguous: 4 symbols carry that exact name

  CANDIDATES
    src/bravos/commands/ci.py::evaluate    function, line 210
    src/bravos/commands/sast.py::evaluate  method, line 318
    …

  next   bravos graph callers 'src/bravos/commands/ci.py::evaluate'
```

Exit codes follow the scheme in `bravos --help`: **2** when a different word would work (an
ambiguous symbol, a question this graph does not have, a repository nobody has indexed — the
refusal names `bravos graph build <repo>`), **3** when this installation carries no graph binary,
and the refusal says so.

---

## Send a run to a server — and what a push uploads

`bravos push` uploads one run to **your** Bravos server — the one your team operates, under your
licence, behind your token. Everything else in bravos is local; this is the one command that sends
anything anywhere.

```console
$ export BRAVOS_SERVER_URL=https://bravos.example.internal
$ export BRAVOS_TOKEN=…
$ bravos push                        # the latest run for this repository

  pushed 2026-09-11T09-14-02Z  →  github.com/org/repo
    sent        214
    appended    214
    duplicates  0
    summary     yes   main
    dashboard   yes   /repo/threat-dashboard.html
    advisories  yes   6 stored
    graph       yes   567 symbols, 111 declared exposures
    templates   yes   4 promoted @main
```

Every line names what went and what the server did with it, so a push that quietly skipped
something is not a push that looks identical to one that did not.

### What a push uploads

*"What does your scanner send?"* is the first question worth asking about any tool like this, so the
answer is here rather than in a source comment. Five things cross the wire, each on its own
endpoint:

| | What | Where it comes from |
|---|---|---|
| **Ledger events** | every verdict the run recorded: the exposure key, the verdict, the reason, the round, the lens, and the evidence attached to a confirmation | `ledger.jsonl`, which the run already wrote |
| **Run summary** | how the run was configured and how healthy it was: branch, commit, target URL, providers, status, termination reason, per-round counts, lens stats, persona labels, coverage flags | `manifest.json`, `lenses.json`, `profiles.json` |
| **Guardlink dashboard** | the generated `threat-dashboard.html`, as an opaque blob the server stores and serves back unparsed | your codebase, when it has one |
| **Finding advisories** | per confirmed finding: the advisory write-up, the confirmation evidence, the probe's request trail, and the probe id | the run's own `report/finding-artifacts.json` |
| **Graph security surface** | see below | the code graph, read at push time |

The first four have been crossing since their channels shipped. The fifth is new, and it is the one
that carries detail about your code rather than about a finding, so it gets the long answer.

### The graph security surface, in full

**What it is:** the security-relevant subset of your code graph — *not* the graph. On this
repository the graph holds 12,512 symbols and 37,533 edges; the surface carries 567 symbols and 532
edges, about 292 KiB. It scales with your threat model, not with your repository: a codebase 3.3×
larger, measured, produced a *smaller* surface.

**What is in it:**

1. **Repository-relative file paths** — `src/bravos/remote/client.py`, never `/home/you/work/…`.
2. **Symbol names** — function, method and class names, and their `file::symbol` addresses.
3. **Line numbers** — of declarations, and of the call sites that reach them.
4. **Your declared threat model, verbatim** — asset names, threat ids, control ids, severities, CWE
   references, and **the rationale prose you wrote in your own `@exposes` / `@mitigates`
   annotations**. It is sent as written.
5. **Your risk-acceptance register** — including **the name of the person who signed** for each
   accepted risk, and the date that signature lapses.
6. **One hop of call graph** — for each declared exposure, the symbols that call into it, capped at
   64 per exposure.
7. **Counts about the whole graph** — files, symbols, call edges, exposures, so you can check the
   fraction above against your own repository.

**What is not in it:**

- **No source code.** Not a line, not a snippet, not a function body.
- **No absolute paths** — not your checkout, not `$BRAVOS_HOME`, not a temp directory.
- **No machine, user or host identity.** No hostname, no username, no environment.
- **No credentials, tokens or target URLs.**
- **No file contents, content hashes or diffs.**
- **No symbol that neither carries a declaration nor calls one** — on this repository, 11,507 of
  12,074 symbols never leave the machine.

**The honest framing.** This is materially more than a summary, and it is sent because a team
looking at a shared server should see what one developer sees locally. The reason that trade is
acceptable is that **the server is yours** — you host it, you licence it, you hold the token. That
is a mitigating fact, not a reason to be vague about the list above.

**If you would rather not send it:**

```console
$ bravos push --no-graph      # the ledger, summary, dashboard and advisories; no surface
```

The push reports it on the same line, so the choice is visible in the log rather than silent.

**Sending it is re-runnable and cheap to store.** The surface is identified by a hash of its own
content, computed without the run id or any timestamp, so an unchanged repository pushed every day
for a week costs your server **one** stored surface and seven associations — not seven copies. The
server answers `stored: false` and the push prints `already on the server`.

The full field-by-field contract, the measurement behind the subset, and what an older server does
with a newer payload are versioned alongside the server that implements them; `bravos push --help`
names what each channel carries, and `--no-graph` sends everything but this one.

---

## Point a coding agent at bravos (MCP)

`bravos mcp` is an [MCP](https://modelcontextprotocol.io) server on stdio. It exposes what bravos
already knows about this machine's repositories — the threat model, the findings ledger, the run
history, and the code graph — as tools an agent can call while it works. Nothing it serves sends
traffic to a target. One tool writes: `generate_model` checks the repository out onto a
`bravos/run-<id>` branch and publishes the model into the working tree — nine files, `CLAUDE.md`,
`AGENTS.md` and `.github/copilot-instructions.md` among them. Every other tool reads.

Add it to a host that reads `mcp.json` (Claude Code, Cursor, Windsurf, VS Code):

```json
{
  "mcpServers": {
    "bravos": { "command": "bravos", "args": ["mcp"] }
  }
}
```

Or, in Claude Code: `claude mcp add bravos -- bravos mcp`.

It serves **13 tools**:

| Tools | What the agent gets |
|---|---|
| `list_repositories`, `get_repository`, `get_advisory` | Which repositories have been scanned, one repository's guardlink exposure table, and the full write-up plus probe evidence for one finding |
| `list_runs`, `get_run`, `get_events`, `get_report`, `get_artifact` | Run history, one run's whole picture, its event stream, and its reports and artifacts |
| `generate_model` | Builds the threat-model report and dashboard from the annotations a repository already carries — the only tool that runs anything, and the only one that **writes**: it checks the repository out onto a `bravos/run-<id>` branch, leaves it there, and publishes nine files into the working tree |
| `request_verification` | Returns the intake → approve → `auto` flow filled in for a run. It fires no probe: approving the plan is a human decision, and the server will not make it |
| `codegraph_tools`, `codegraph_query` | The code graph — callers, callees, a change's blast radius, structural outlines, and which declared exposures are reachable from an entry point (the same answers are on the CLI as [`bravos graph`](#ask-the-code-graph-from-a-terminal)) |
| `list_environments` | The disposable labs this machine has recipes for |

The graph tools are the reason to point an agent here rather than at plain text search: they know
which symbols touch a declared asset or threat. They proxy `codegraph-mcp`, which **ships inside
this package** — an installation that does not carry one (a wheel built for another platform, a
source checkout) answers `codegraph_unavailable` with the route to fix it rather than with an empty
result. The other eleven tools work regardless. `bravos setup --check` says what this installation
carries; the graph it reads is built by `bravos graph build <path>`.

---

## Why bravos isn't naive

Several obvious designs are wrong. bravos exists because it handles the sharp edges the tools leave:

- **Pair collisions.** guardlink identifies an exposure by `asset::threat` alone, so `guardlink
  diff` can't see a *new* weakness in a pair it already knows — the round reads "nothing added." On
  Portainer 2.39.2 that's 21 findings collapsing to 16 identities, hiding both host-escape CVEs.
  bravos keys on `(asset, threat, file, hash(message))`.
- **Suppressed exposures.** guardlink's SARIF drops any exposure whose pair carries a `@mitigates`
  or `@accepts` *anywhere* — 17 pairs on the reference corpus, including a confirmed cross-tenant
  IDOR. bravos seeds them into the ledger and, for the mitigation-audit lens, restates them into the
  export so cxg can actually test the control.
- **Annotation gates.** An agent that writes `@accepts` (deleting a pair from the export) halts the
  run; a `@mitigates` over an unverified pair is kept but recorded as *suppressed* and must be
  proven; an edit that is not an annotation the parser reads is reverted. The agent can't silently
  bury a finding, and it can't land a dead one either — an annotation written where guardlink does
  not read (a Python docstring, say) contributes nothing to the export, so it is reverted rather
  than left looking like work. That last gate then reports what it actually established, derived
  from the same read that judged the files rather than from a list of known-bad target shapes,
  and it claims only what it inspected — the lines the round ADDED to SOURCE files: *enforced*
  when every changed path was accounted for and the round did nothing outside that; *enforced
  for what it inspected*, naming each limit, when it did (lines the round removed, or what it
  wrote to a `.guardlink/` definition file or a `.gal`, neither of which is source the
  annotation oracle can judge); and *not enforced*, naming the files, when a changed path could
  not be read, put back, or confirmed put back. A target under no version control, a
  subdirectory of its repository rather than the root, and a repository whose files are staged
  but not yet committed all reach that last standing on their own, as does any other shape that
  leaves a changed path unaccounted for. What it still cannot see is anything `git status` does
  not report even when asked about ignored paths — a nested repository, an `--assume-unchanged`
  file — and, among the ignored paths it does see, a write into one git was *already ignoring*
  when the round began, since it compares those by name. A file it was not yet ignoring is caught
  either way: the round-start digest tells a rewrite from a file that was simply already there.
  A **submodule's contents** are a different case and not that one: git does report a submodule,
  as the gitlink entry `web` in a whole-tree status, and it is the source pathspec that filters
  it out, because `*.go` matches files and a gitlink is not one. So the gate reads the
  superproject and cannot judge what a round did inside a submodule — and when one has moved,
  gone dirty, or could not be asked about, it says so, naming it among the things it did not
  inspect, rather than reporting a clean bill over a repository it never opened.
- **cxg's exit code lies, and so can its report body.** How bravos reads both — and how it catches
  a scan that stopped early before an empty findings list becomes a clean bill of health — is in
  [Probe, classify, correlate](#5--probe-classify-correlate). It also captures the generated probe
  templates into the run tree so every advisory can show the exact code that produced its verdict.
- **The tools move; bravos would not notice.** guardlink and cert-x-gen ship on their own
  schedules, and every reader here is a hand-written pick of named keys — a key that grew or a block
  written in a new shape is not an error, it is simply never seen, and the run reports the nothing it
  got back as a clean result. So bravos declares what it needs of each artifact and takes a census
  against the one that actually arrived: a field nothing consumes, a value it has no meaning for, a
  value it refused, or a question the artifact never answered is listed in the run's health banner
  in the web interface. It marks the numbers as a floor, not a failure — a tool that grew a field
  hasn't made the findings wrong, only bravos's reading of it incomplete.
- **State lives outside the repo.** `guardlink status`/`validate` rewrite seven agent-instruction
  files on every call, so in-repo state would churn inside the very commits used as diff baselines.
  All run state is under `$BRAVOS_HOME` (default `~/.bravos`); the target repo only ever receives
  commits on a `bravos/run-<id>` branch.

---

## Architecture

A deterministic state machine owns the loop; AI coding-agent CLIs are invoked headlessly **only at
explicit judgment points** — annotation, environment-recipe generation, goal enrichment, write-back.

```
models/       pure dataclasses, no I/O
adapters/     one external surface each (guardlink, cxg, agent), ProcRunner injected
env/          recipes, provisioning, the login adapter, auth recovery
phases/       p00 preflight · p10 env · p20 auth · p30 annotate · p40 export
              p50 synthesise · p60 pentest · p70 write-back · p80 report
web/          self-contained page + read-only API
orchestrator  sequencing only; convergence, lenses, ledger, journal
```

Dependency direction is `models ← adapters ← phases ← orchestrator`; phases never import each other.
Runs are journalled and resumable at phase granularity — interrupt at round 3, resume, and no
completed step re-executes.

---

## Testing

```bash
.venv/bin/python -m pytest -m "not contract and not slow"   # fast unit + web suite
.venv/bin/python -m pytest -m contract                       # real guardlink binary
```

Fixtures under `tests/fixtures/portainer/` are verbatim artifacts from a completed manual run, so
the suite asserts against data the tools actually produced.

---

## Authorization

bravos sends real exploit traffic and lets a coding agent edit the target repository. Use it only
against systems you are authorised to test. Every run records an attestation, binds work to a
dedicated branch, and keeps all other state outside your repository.

---

## License

Free to use for any purpose, including commercial — see [LICENSE](LICENSE). Not open source:
redistributing, reselling, or shipping a modified version needs Bugb Technologies' written
permission. Questions: [bugb.io](https://bugb.io).
