# vuln-pipeline demo: dr_libs

End-to-end walkthrough on the `drlibs` target — two real CVEs in single-header
C audio decoders, pinned to vulnerable commit `fb1b2dfc585c`.

| CVE | File | Class | Expected time to first crash |
|---|---|---|---|
| CVE-2026-29022 | `dr_wav.h` | Heap OOB write (`smpl` chunk two-pass desync) | ~6 min |
| CVE-2025-14369 | `dr_flac.h` | Integer overflow → wild malloc (DoS) | ~60–80 min, needs `--accept-dos` |

Full target details: [`targets/drlibs/README.md`](targets/drlibs/README.md).

## 0. Prerequisites

- Linux host with Docker.
- A model to drive the agents. The pipeline reads `VULN_PIPELINE_MODEL` from
  the environment (or `--model` per command); it is never read from target
  config. This walkthrough exports it once in step 2.

## 1. One-time setup

Installs the venv + pipeline, registers the gVisor `runsc` runtime, and starts
the egress-allowlist proxy on the `vp-internal` network. Safe to re-run.

```bash
scripts/setup_sandbox.sh
```

`bin/vp-sandboxed` is the entry point from here on — it checks the sandbox is
up, exports the runtime/proxy env, and execs `.venv/bin/vuln-pipeline`.

## 2. Auth

Pick one, per [`docs/agent-sandbox.md`](docs/agent-sandbox.md):

```bash
# Local dev / laptop (recommended for the demo)
claude setup-token                       # prints CLAUDE_CODE_OAUTH_TOKEN
export CLAUDE_CODE_OAUTH_TOKEN=<token>

# or: an API key
export ANTHROPIC_API_KEY=sk-ant-...

# or: Amazon Bedrock (see docs/agent-sandbox.md for the full setup)
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_BEARER_TOKEN_BEDROCK=...
```

Set the model once for the session — every `vuln-pipeline` subcommand reads it:

```bash
export VULN_PIPELINE_MODEL=<model-id>
```

## 3. Recon (read-only, ~6 min)

Runs a single agent that reads the source tree and proposes `focus_areas`.
Prints YAML to stdout — review before launching finds.

```bash
bin/vp-sandboxed recon drlibs
```

Expect ~14 areas including the WAV metadata-chunk path and FLAC allocation
sizing — both are where the target CVEs live.

## 4. Small first wave (calibration)

First-time use on a target: 3 parallel finds, capped turns, streaming reports.
Gives a feel for token burn and whether prompts are landing before scaling up.

```bash
bin/vp-sandboxed run drlibs \
    --auto-focus --runs 3 --parallel --stream --max-turns 100
```

The pipeline auto-builds `vuln-pipeline-drlibs:latest` from
`targets/drlibs/Dockerfile` on first run.

## 5. Full wave

Launch in the background so you can tail logs while it runs. `--accept-dos` is
required for the dr_flac CVE — it's DoS-class and the default quality bar
triages-and-skips it.

```bash
bin/vp-sandboxed run drlibs \
    --auto-focus --runs 15 --parallel --stream --accept-dos \
    2>&1 | tee drlibs_run.log &
```

Optionally add `--novelty` to have each report state FIXED/UNFIXED against
upstream `HEAD` (orchestrator shallow-clones `github.com/mackron/dr_libs`;
skip in air-gapped environments).

## 6. Watch it

```bash
RESULTS=$(ls -td results/drlibs/*/ | head -1)
tail -f drlibs_run.log                              # heartbeat + per-action progress
cat   $RESULTS/found_bugs.jsonl                     # crashes landed so far (raw ASAN excerpts)
ls    $RESULTS/run_*/result.json                    # graded runs
cat   $RESULTS/reports/judge_log.jsonl              # NEW / DUP_BETTER / DUP_SKIP per crash
cat   $RESULTS/reports/manifest.jsonl               # bug_NN assignments
ls    $RESULTS/reports/bug_*/report.json            # exploitability reports written so far
```

First report (`bug_00`, the dr_wav OOB write) typically lands within ~10
minutes of launch. Stragglers don't block disk writes — kill a stuck find with
`docker rm -f find_drlibs_<N>`.

## 7. Read the findings

```bash
RESULTS=$(command ls -td results/drlibs/*/ | head -1)
jq . "${RESULTS}reports/bug_00/report.json"
xxd  $RESULTS/reports/bug_00/poc.bin | head         # the crashing input
```

Each `report.json` is a structured exploitability analysis: primitive,
reachability from the real attack surface, escalation path, constraints, plus
an agent-judged severity.

## 8. (Optional) Patch phase

Generates a fix per unique crash and walks it through build → PoC-stops →
tests-pass → 50-turn re-attack. `targets/drlibs/config.yaml` already has the
required `build_command`.

```bash
bin/vp-sandboxed patch $RESULTS
cat $RESULTS/reports/bug_00/patch.diff
jq  . $RESULTS/reports/bug_00/patch_result.json     # t0_builds .. re_attack_clean
```

The ladder verifies the crash is gone, not that the diff is safe to upstream —
review `patch.diff` by hand (see
[`docs/patching.md#reviewing-generated-patches`](docs/patching.md#reviewing-generated-patches)).

## 9. Cleanup

```bash
docker ps -a --filter name=drlibs                   # any leftover agent containers
docker rm -f $(docker ps -aq --filter name=drlibs)  # if needed
```

Results stay on disk under `results/drlibs/<timestamp>/`. The target's
`dr_*.h` headers are fetched inside the docker build, so nothing lands in
your working tree.