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)
- Agent containers are the untrusted execution surface. They run
claude -pagainst target-derived data (source, ASAN traces, build/test output) that a malicious target author could in principle embed instructions in. - gVisor is the syscall/filesystem boundary — agent
Read/Write/Bashsee only the container filesystem, on gVisor's own kernel, not the host's. vp-internalhas no internet route. The only egress path is an allowlist proxy (defaultapi.anthropic.com:443, or the Bedrock/Vertex equivalent).- The patch agent is the highest-stakes case — its output is a diff a human may apply
to a real codebase. Target-derived text in the patch prompt is wrapped in
<untrusted_data>blocks with a per-call random id; the agent is told to treat it as data, not instructions. Mitigation, not guarantee — every generated diff should be reviewed. - Orchestration code is trusted and unsandboxed — it never runs target code or
model-chosen commands; only the
claude -psubprocess (inside its container) does. - The D&R hunt container never contains the answer key, grader, or log generator — enforced by what gets baked into the image at build time, not by runtime convention.
Full detail: Defending Code Harness Vault/DCRH/DCRH — Sandboxing and Trust Boundaries.md.
5. Quality mechanisms
- 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.
- Threat-model first.
/threat-modelproduces 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 (seedocs/threat-model.mdin the source repo). - 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. - 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.