Design · Defending Code Reference Harness (DCRH)

High-Level Design (HLD)

↩ architecture.html · generated 2026-08-14

High-Level Design (HLD)

Defending Code Reference Harness (DCRH) — anthropics/defending-code-reference-harness. Companion to architecture.html (interactive) and LLD.md (implementation-level internals).

1. Components and responsibilities

Component Location Responsibility
Interactive skills .claude/skills/ (8 skills + _lib/) Read/write-file workflows run inside a live Claude Code session: scoping, static scan, triage, patch, D&R, customize.
CLI / dispatch harness/cli.py (1,424 LOC), dnr_harness/cli.py (518 LOC) Argument parsing and subcommand dispatch for both pipelines.
Agent transport harness/agent.py (436 LOC) Spawns and streams one claude -p subprocess per agent invocation; owns retry/resume-on-error.
Auth resolution harness/auth.py (470 LOC) Resolves API key / OAuth token / Bedrock credentials into an agent-container environment.
Sandbox / containers harness/docker_ops.py, sandbox.py, agent_image.py Builds target + agent Docker images, launches gVisor containers, manages the vp-internal egress-restricted network.
Target config harness/config.py (73 LOC) Resolves a target's config.yaml (focus_areas, known_bugs, github_url).
Detection stages harness/recon.py, find.py, asan.py, grade.py, judge.py, report.py, dedup.py, novelty.py The recon → find → grade → judge → report → dedup loop.
Remediation harness/patch.py, patch_grade.py (315 LOC) Drafts a fix per unique bug and runs a multi-tier grading/re-attack loop.
Artifacts / prompts harness/artifacts.py, harness/prompts/ (9 files) On-disk result layout (result.json, found_bugs.jsonl, manifest.jsonl) and every agent's prompt text.
Detection & response mirror dnr_harness/ (6 files, ~876 LOC) Same orchestration shape as harness/, applied to log corpora instead of source. Only cross-package import in the repo: dnr_harness → harness (6 references).

2. Technology stack

Layer Tech Notes
Agent runtime claude -p --output-format stream-json (Claude Code CLI) via docker exec Invoked with asyncio.create_subprocess_exec — a direct async subprocess wrapper, not a Python SDK. See §6 and LLD §9.
Isolation gVisor (runsc), Docker, vp-internal network + allowlist proxy Enforced in code (container/network config), not in prompts.
Target instrumentation ASAN (AddressSanitizer) via each target's Dockerfile Static/dynamic memory-error detection for the crash the find agent must reproduce 3/3.
Orchestration language Python ≥3.11, pyyaml is the only runtime dependency (pyproject.toml) No LangChain, no LangGraph, no anthropic Python SDK, no DeepAgents.
Persistence Flat files: JSON/JSONL on disk (results/<target>/<ts>/) No database. run_NNN/result.json, found_bugs.jsonl, reports/manifest.jsonl, reports/bug_NN/report.json.
Interactive layer Claude Code skills (Markdown SKILL.md + README.md per skill) No separate runtime — executes inside the user's Claude Code session.

3. Run / deployment model

bin/vp-sandboxed wraps both vuln-pipeline and dnr-pipeline: it verifies gVisor is registered and the egress proxy is running, then launches the requested subcommand. It refuses to start — rather than silently falling back to unsandboxed — if either check fails, unless --dangerously-no-sandbox is explicitly passed (throwaway-VM development only).

Setup vs. attack phase separation: target image build happens with normal network access (pulling dependencies, compiling with ASAN); the built image is then frozen (base images, commit SHAs, and dependency versions pinned in the Dockerfile) and agents run against that frozen image with no egress route except the model API.

A killed batch is resumable: run --runs N --resume <dir> (same --runs N the batch was launched with) skips runs whose result.json reached a terminal status and retries agent_failed / build_failed / error ones. The one non-resumable terminal state is error_max_turns, by design — resuming would multiply the turn cap.

4. Trust boundaries & security posture (design-level)

Full detail: Defending Code Harness Vault/DCRH/DCRH — Sandboxing and Trust Boundaries.md.

5. Quality mechanisms

  1. Verification over vibes. Every claimed crash is re-proven by a grader agent in a fresh container that receives only the PoC bytes — never the finder's reasoning. This is the single design decision most responsible for DCRH's low false-positive rate on execution-verified findings.
  2. Threat-model first. /threat-model produces threats (architectural properties), not vulnerabilities (concrete instances) — scoping the scanner and triage step before any code review happens, which is what actually cuts false positives (see docs/threat-model.md in the source repo).
  3. Adversarial grading loops, not just single-pass review: the grade/judge/report-grader stages in detection, and the multi-tier build+PoC+test+re-attack loop in patch.py / patch_grade.py, all exist to disprove a claim before it's trusted.
  4. Minimal cross-container information flow. Find → grade crosses only PoC bytes; hunt → grade (D&R) crosses only the submission. This is what makes a verdict meaningful rather than a rubber stamp — see LLD §6.

6. Agent runtime — direct CLI subprocess, not an agent framework

Unlike agent-framework-based harnesses that route model calls through LangChain, LangGraph, or a vendor Agent SDK, DCRH's harness/agent.py invokes the Claude Code CLI directly:

docker exec <container> claude -p --output-format stream-json ...

via asyncio.create_subprocess_exec, streaming the resulting JSONL to disk as it's produced. The module's own docstring states the reasoning explicitly: "The Agent SDK is itself a subprocess wrapper around the same CLI; going direct keeps the argv shape under our control (resume, tools, system-prompt)." Messages are stored as raw stream-json dicts, not SDK dataclasses — deliberately, so the transcript format doesn't depend on an SDK version.

Practically, this means: - No via:/backend abstraction layer. Every agent-spawning subcommand uses the same transport; there is no per-role backend routing config to reason about. - --model / VULN_PIPELINE_MODEL is the only model-selection surface, passed straight through to the CLI invocation — resolved once in cli.py, not re-derived per stage. - Retry/resume is hand-rolled, not framework-provided: on a 429/5xx, agent.py retries with backoff using the CLI's own --resume <session_id> to restore the full conversation, up to 20 times.

Full mechanics, including exactly why no LangChain/LangGraph/DeepAgents dependency exists in this repo: LLD §9.


Related: LLD.md · ../architecture.html · Defending Code Harness Vault/DCRH/DCRH — Architecture (HLD).md.