Low-Level Design (LLD)
Defending Code Reference Harness (DCRH) — implementation-level internals. Companion to
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: pipelineheader plus acyber-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 (skillsvalue) via.claude/settings.json. Removable viaVULN_PIPELINE_NO_TELEMETRY=1(pipeline) or a.claude/settings.local.jsonoverride (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 viadocker 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 incli.py, threaded down to everyrun_agent()call. Compare to a LangGraph-based system, which typically resolves model/vendor per node via a config object (e.g. VVAH'sdeepagents/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 · ../architecture.html ·
Defending Code Harness Vault/DCRH/DCRH — Graph Intelligence Findings.md.