Design · Defending Code Reference Harness (DCRH)

Low-Level Design (LLD)

↩ architecture.html · generated 2026-08-14

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

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:


Related: HLD.md · ../architecture.html · Defending Code Harness Vault/DCRH/DCRH — Graph Intelligence Findings.md.