# Low-Level Design (LLD)

Defending Code Reference Harness (DCRH) — implementation-level internals. Companion to
[HLD.md](HLD.md). All facts below verified against the cloned source
(`anthropics/defending-code-reference-harness`) and the real Graphify/CodeGraph runs in
`Defending Code Harness Vault/DCRH/DCRH — Graph Intelligence Findings.md`, not paraphrased
from the README.

## 1. Data contracts

| Contract | Defined in | Carries |
|---|---|---|
| `CrashArtifact` | `harness/artifacts.py` (inferred — most-connected data class in the repo, 33 edges per Graphify) | Crash bytes + ASAN signature, passed between find, grade, and dedup. |
| `AgentResult` | `harness/agent.py` | Raw `stream-json` message list + parsed tagged output from one agent run (30 edges). |
| `TargetConfig` | `harness/config.py` | Resolved `config.yaml`: `focus_areas`, `known_bugs`, `github_url` (26 edges). |
| `PatchVerdict` | `harness/patch_grade.py` | Structured pass/fail record from the fix↔grade loop (21 edges). |

No ORM, no database schema — every contract above is a plain Python dataclass
(`from dataclasses import dataclass` per `agent.py`'s imports) serialized to JSON/JSONL on
disk. This is a deliberate simplicity choice: the entire persistence layer is
`results/<target>/<timestamp>/` as a directory tree, not a service.

## 2. Config resolution (`harness/config.py`, 73 LOC)

`TargetConfig` is resolved from `targets/<name>/config.yaml`. Fields include hand-written
`focus_areas` (used unless `--auto-focus` triggers `recon.py` to generate them instead),
`known_bugs` (steers future runs away from prior findings), and `github_url` (read only on
the **host**, by `novelty.py`, never inside an agent container — see §6 below). Pure YAML
parsing and dataclass construction; no model calls.

## 3. Auth / credential resolution (`harness/auth.py`, 470 LOC)

The single most-connected function in the repo is `resolve_auth_env()` (51 edges per
Graphify's god-node ranking) — nearly every agent-spawning code path routes through it
before a container starts. It resolves, in order of precedence, an API key
(`ANTHROPIC_API_KEY`), an OAuth token (`CLAUDE_CODE_OAUTH_TOKEN`), or Bedrock credentials,
and materializes the result into the environment the agent container receives.

`_bedrock_env()` (28 edges) handles the Bedrock case specifically: it prefers
`AWS_BEARER_TOKEN_BEDROCK` (single-purpose, no IAM lateral-movement risk) over long-lived
access keys, and deliberately does **not** support instance-profile/IMDS credentials — the
agent container has no route to `169.254.169.254` and no STS egress, so hostile target
code inside the container cannot steal the instance role or pivot via `AssumeRole`.
`AWS_PROFILE` and `~/.aws` are never forwarded; on a machine that only has role
credentials, they must be materialized into the environment beforehand (e.g. via
`aws configure export-credentials --format env`).

Bedrock model ids use a cross-region inference-profile prefix (`us.`, `eu.`, `apac.`,
`global.`) that must match the deployment's actual region group; `auth.py` prints a
preflight warning when it detects a bare foundation-model id that would otherwise fail on
first call.

## 4. Agent transport & retry (`harness/agent.py`, 436 LOC)

`run_agent()` (31 edges, the second-highest-connectivity function in the repo) is an
`async` subprocess wrapper: `asyncio.create_subprocess_exec` runs
`docker exec <container> claude -p --output-format stream-json ...` and streams the
resulting newline-delimited JSON to disk with `fsync` after each message, so a mid-run
kill leaves a readable transcript.

`parse_xml_tag()` (31 edges) and `AgentResult.find_tagged_message()` pull structured
submission blocks (e.g. a crash file path, a verdict) out of an agent's free-text
response: agents often emit their structured tags followed by a short "Done!" message, so
naive last-message parsing would return the prose instead — the method scans backwards
for the tags.

**Retry/resume state machine** (deterministic, no model call): on a 429/5xx, the Claude
CLI itself first retries with backoff; if those retries exhaust, `agent.py` runs its own
retry loop (up to 20 times), relaunching with the CLI's `--resume <session_id>` to restore
the full conversation so the agent continues from the failed turn rather than starting
over. The one exception is `error_max_turns`: exhausting the turn budget is terminal by
design (resuming would multiply the cap); a crash submitted before the cap is still
salvaged and graded, only the un-submitted remainder is lost.

## 5. Sandbox & container lifecycle (`harness/docker_ops.py`, `sandbox.py`, `agent_image.py`)

`agent_container()` (22 edges) is the function every stage's agent actually runs inside.
Responsibilities, all deterministic:
- Build the target's ASAN image on first run (cached for reuse across find/grade/re-attack).
- Build a second image with the Claude Code CLI installed, for the agent process.
- Register/verify `runsc` (gVisor) as the container runtime instead of `runc`.
- Attach the container to `vp-internal`, a Docker network with no default internet route;
  egress is only reachable through a proxy container that allowlists the model API host.
- Extract PoC bytes back to the host via `docker exec cat` (host-side `docker cp` cannot
  reach gVisor's tmpfs).

## 6. Deterministic vs. LLM-driven work, stage by stage

This is the practical answer to "where is the AI, exactly, and where isn't it":

| Stage / module | Deterministic (no model call) | LLM-driven |
|---|---|---|
| Build (`docker_ops.py`) | 100% — image build, gVisor registration, network setup | none |
| Recon (`recon.py`) | YAML parsing of the returned partition | Proposing `focus_areas` from reading the source |
| Find (`find.py`, `asan.py`) | ASAN signature parsing, the 3-of-3 reproduction check | Crafting malformed input; deciding what to try next |
| Grade (`grade.py`) | `result.json` write; the fresh-container isolation itself | Re-verifying whether the PoC bytes reproduce a real crash |
| Judge (`judge.py`) | `manifest.jsonl` read/append | The new-bug / cleaner-duplicate / skip decision (no-tools agent) |
| Report (`report.py`) | `report.json` schema assembly | Writing the exploitability analysis; grading it for evidence-backed claims |
| Novelty (`novelty.py`, optional) | 100% — host-side `git clone` + `git log` extraction | none (only *augments* the report agent's prompt) |
| Dedup (`dedup.py`) | 100% — signature clustering | none; the only fully agent-free vuln-pipeline subcommand besides sandbox checks |
| Patch (`patch.py`, `patch_grade.py`) | Build success/fail, PoC-no-longer-crashes check, test-suite pass/fail — all deterministic gates the loop must clear | Drafting the fix; the optional `--style` advisory judge |
| Auth (`auth.py`) | 100% — credential precedence resolution | none |
| Agent transport (`agent.py`) | 100% — retry/resume state machine, transcript streaming | none (it is the transport the model call travels over, not a decision-maker) |
| D&R hunt (`dnr_harness/`) | Image construction excluding the answer key; the grade container's PoC re-fire (execution, not a model judgment — "substring checks can be gamed, execution can't") | Hunting the corpus; writing `INCIDENTS.json` |

**Pattern**: every stage that produces a *claim* (a crash is real, a bug is novel, a fix
works) pairs the model's claim with a deterministic gate that must independently agree
before the claim is written to disk as accepted. No stage trusts the model's own assertion
about whether it succeeded.

## 7. Prompt injection mitigation

The find and report agents' blast radius is limited by construction: isolated container,
egress restricted to the API, output is files a human reads. The **patch agent** is the
highest-stakes case because its output is a diff that may be applied to a real codebase.
`harness/prompts/untrusted.py` wraps target-derived text (ASAN traces, source excerpts) in
`<untrusted_data>` blocks with a per-call random id, instructing the agent to treat the
content as data, not instructions. This is a mitigation, not a guarantee — every generated
diff should be reviewed before being upstreamed.

## 8. Observability & accounting

- **Transcripts**: one JSONL file per agent run, written incrementally with `fsync`, so a
  killed or still-running batch is inspectable on disk (`filter for "type":"tool_use"`
  shows exactly what commands an agent ran — the fastest way to debug prompt iteration).
- **Usage marker**: pipeline agent API requests carry a declared, removable
  `anthropic-cyber-runbook: pipeline` header plus a `cyber-runbook/<version>` User-Agent
  token, for Anthropic's own telemetry attribution — static structural metadata only, no
  request content. Interactive skill sessions send only the header (`skills` value) via
  `.claude/settings.json`. Removable via `VULN_PIPELINE_NO_TELEMETRY=1` (pipeline) or a
  `.claude/settings.local.json` override (skills). Not sent at all when authenticating via
  Bedrock/Vertex, since those providers rewrite the User-Agent and don't forward custom
  headers to Anthropic.
- **Rate-limit sizing**: roughly 10K uncached input tokens/min and 2K output tokens/min per
  running agent is the repo's own planning rule of thumb; concurrent agents are sized at
  ~100 per 1M input-TPM of account headroom.

## 9. Why no LangChain/LangGraph/Agent SDK

A direct source-tree search (`pyproject.toml` plus a recursive grep for
`langchain|langgraph|deepagents|agent.?sdk` across `harness/` and `dnr_harness/`) turns up
**zero occurrences** of any of them. The only runtime dependency declared in
`pyproject.toml` is `pyyaml`. This is a real architectural difference from
agent-framework-based harnesses (e.g. the sibling VVAH project, which routes S10/S11
through a DeepAgents/LangGraph backend selectable via a `via:` config key) — DCRH has no
such abstraction layer at all:

- **One transport for every stage.** `harness/agent.py::run_agent()` is the single code
  path every agent-spawning subcommand (recon, find, grade, judge, report, patch, and the
  D&R hunt/grade mirrors) goes through. There is no per-stage backend selection to
  configure or reason about.
- **The CLI *is* the agent runtime.** `claude -p --output-format stream-json`, invoked as
  a subprocess via `docker exec`, is both the model-calling mechanism and the tool-use
  loop (Read/Write/Bash/Grep, as permitted by the container). No separate
  orchestration graph, no explicit state machine of "nodes" and "edges" for agent
  reasoning — the Claude Code CLI's own agent loop does that internally, and DCRH's Python
  code only manages the process lifecycle around it (spawn, stream, retry, extract
  result).
- **Model selection is a single flag.** `--model` / `VULN_PIPELINE_MODEL`, resolved once in
  `cli.py`, threaded down to every `run_agent()` call. Compare to a LangGraph-based system,
  which typically resolves model/vendor per node via a config object (e.g. VVAH's
  `deepagents/options.py::build_model()`).
- **Trade-off, stated plainly.** This buys DCRH simplicity and a very small dependency
  surface (one third-party package) at the cost of the flexibility a graph-based
  orchestration framework provides — e.g. no built-in support for expressing the pipeline
  itself as a graph of conditional agent hand-offs, no framework-level checkpointing of
  agent *reasoning* state (only of pipeline *results*, via the `results/` directory
  layout and `--resume`). For a reference implementation whose whole premise is "read this
  and port it to your stack," that trade-off favors readability over generality.

---
Related: [HLD.md](HLD.md) · [../architecture.html](../architecture.html) ·
`Defending Code Harness Vault/DCRH/DCRH — Graph Intelligence Findings.md`.
