Defending Code Reference Harness (DCRH) — Architecture Overview
Consolidated technical reference. Source of truth for the individual notes
is the Obsidian vault (Defending Code Harness Vault/DCRH/); this file is a
single-page superset for sharing or printing. Repo analyzed:
anthropics/defending-code-reference-harness (not maintained, reference
implementation, Claude Security is the managed equivalent).
1. What it is
A crash-testing crew for source code. A recon agent maps the codebase into attack-surface areas. Several isolated "find" agents each try to break a different area by feeding malformed input to a memory-safety-instrumented build until it crashes reproducibly (3 times out of 3). A "grade" agent — in a clean container that never saw the finder's reasoning, only the crash bytes — re-confirms the crash is real. A "judge" checks it isn't a duplicate. A "report" agent writes up what an attacker could do with it, and a separate grader scores that report for evidence. A "patch" agent then drafts a fix, and a grading loop hammers the fix (rebuild, re-run the original crash, run the test suite, try a fresh find agent against it) before it's trusted. A parallel crew does the same verification-first thinking over logs instead of source: hunt for a campaign that's already happened.
2. Two halves
| Layer | Location | Executes target code? | Sandbox required? |
|---|---|---|---|
| Interactive skills | .claude/skills/ (8 skills) |
No (except D&R skills run a local demo app) | No — human approves each tool use in Claude Code |
| Autonomous pipelines | harness/ (vuln-pipeline), dnr_harness/ (dnr-pipeline) |
Yes | Yes — gVisor via bin/vp-sandboxed |
3. The eight interactive skills
/quickstart · /threat-model (bootstrap / interview / bootstrap-then-interview)
· /vuln-scan · /triage · /patch · /dnr-hunt · /dnr-respond · /customize
(plus /verify, contributor-only tooling). Full table with read/write scope:
DCRH — Interactive Skills.md in the vault.
4. vuln-pipeline stages
Build → Recon (optional) → Find (N parallel) → Grade (fresh container) →
Judge (--stream only) → Report → Dedup (post-hoc) → Patch. Full stage
table with artifacts: DCRH — Pipeline Stages.md.
5. dnr-pipeline (mirror track)
generate_logs.py → Hunt container (app + logs, read-only, no answer key by
image construction) → INCIDENTS.json → fresh Grade container (answer key +
scorer, independently re-fires every PoC). Full detail: DCRH — Detection
and Response.md.
6. Module map (verified against source, this commit)
harness/— 29 files, ~4,381 LOC. Hub:cli.py(1,424 LOC, dispatches every subcommand). Key modules:agent.py(spawn/streamclaude -p),docker_ops.py/sandbox.py/agent_image.py(containers/gVisor),recon.py,find.py,asan.py,grade.py,judge.py,dedup.py,novelty.py,report.py,patch.py/patch_grade.py,artifacts.py,auth.py(470 LOC — API key/OAuth/Bedrock),config.py,prompts/(9 files, incl.untrusted.pyfor the patch-prompt injection guard).dnr_harness/— 6 files, ~876 LOC.cli.py(518 LOC, hub) →agent_image.py→config.py→prompts.py/system_prompt.py.- Only cross-package import edge:
dnr_harness → harness(6 refs) — seetool-outputs/module_graph.jsonfor the raw analysis.
7. Trust boundaries and sandboxing
- gVisor is the syscall/filesystem boundary for every agent container.
vp-internalDocker network has no internet route; egress only via an allowlist proxy (defaultapi.anthropic.com:443).bin/vp-sandboxedverifies both before launching agents; refuses to start otherwise (--dangerously-no-sandboxoverrides, throwaway-VM dev only).- Patch-prompt target-derived text is wrapped in
<untrusted_data>blocks with a per-call random id (prompt-injection mitigation, not a guarantee — review every generated diff). - Orchestration code is trusted/unsandboxed; only
claude -pagent processes run inside gVisor.
Full detail: DCRH — Sandboxing and Trust Boundaries.md.
8. Data flow diagrams and interactive HTML
Mermaid source: diagrams/01_architecture.mmd, diagrams/02_data_flow_pipeline.mmd,
diagrams/03_data_flow_dnr.mmd. Interactive HTML (generated by
tools/gen_html.py, zero-JS-required <details> expand/collapse, Mermaid
rendered via CDN): docs/architecture.html (full explainer: skills,
pipeline stages, module flow, trust boundaries, tech stack),
docs/data-flow.html (all three diagrams rendered), and
diagrams/module-graph.html (module→file drill-down). Same diagrams are
also embedded inline in the vault's DCRH — Data Flow.md.
9. Graph intelligence
Both Graphify (graphifyy, tree-sitter AST + community detection) and
CodeGraph (@colbymchenry/codegraph, Rust kernel + SQLite) were
installed and run against the cloned repo. Graphify: 1,459 nodes, 2,832
edges, 91 communities — top god-node resolve_auth_env() (51 edges).
CodeGraph: 1,352 nodes, 3,343 edges across 76 files — impact run_agent
showed 43 affected symbols. Full exports: tool-outputs/graphify/
(graph.html, GRAPH_TREE.html, GRAPH_REPORT.md) and
tool-outputs/codegraph/ (codegraph.db, status.json). A lighter
Python-ast cross-check (file-level import edges only, no install
required) is in tool-outputs/module_graph.json / .md. Full writeup:
DCRH — Graph Intelligence Findings.md.
10. Ramp-up process (repo's own recommended pace)
Day 1 (interactive skills on targets/canary) → Day 2 (first autonomous
run on targets/drlibs) → Days 3–5 (/customize to your stack) → Week 2
(scanning waves + cross-run triage + patch) → Optional (detection &
response demo). Verbatim commands: DCRH — Process and Runbooks.md.
11. Glossary
See DCRH — Glossary.md for every term (threat vs. vulnerability,
focus_areas, ASAN, PoC, gVisor, usage marker, etc.).
Full note set (vault): Defending Code Harness Vault/DCRH/ — start at
DCRH — Map of Content.md.