DOCSEARCHbyAlgolia
Submit Docs

Defending Code Reference Harness

repository·main·Indexed 27 days ago

https://github.com/anthropics/defending-code-reference-harness

A reference implementation for autonomous vulnerability discovery and remediation using Claude. It provides a framework for a recon → find → triage → report → patch loop, specifically configured for C/C++ memory vulnerabilities but customizable for other stacks. The harness includes the vuln-pipeline package (v0.2.1) for execution-verified discovery and log-based detection and response, utilizing gVisor-isolated sandboxes for secure target execution.

Tokens
31.5K
Snippets
56
Records
158
Agent score
90%

What's inside defending-code-reference-harness

  1. Understand the `canary` target system context

    main

    The canary target is a single-file (~85 LOC) C command-line tool designed as a fast smoke-test target for the vuln-pipeline.

    Key Characteristics:

    • Functionality: Reads a file from argv[1] into a 4 KB buffer and dispatches to one of three parser functions based on the first byte:
      • 'A' $\rightarrow$ parse_alpha
      • 'B' $\rightarrow$ parse_bravo
      • 'C' $\rightarrow$ parse_charlie
    • Build Environment: Built with gcc -O1 -fsanitize=address inside a gcc:14 Docker image.
    • Purpose: It is a crash-test fixture with deliberately planted bugs documented in the source comments and README.md. It has no production deployment or CVE history.

  2. Understand htslib vulnerability characteristics and expected results

    main

    The htslib target contains a 10-CVE cluster (CVE-2026-31962 through -31971) triggered by file-bytes-only inputs (crafted files).

    Vulnerability Breakdown

    CVESubsystemSeverityClass
    CVE-2026-31970bgzf.cHIGH 8.1Heap OOB write (integer overflow)
    CVE-2026-31962..31971cram/6 HIGH + 3 MEDIUMMix of heap BOF, OOB read/write, NULL-deref

    Expected Performance

    • BGZF (CVE-2026-31970): Expected to be found quickly (~5 min) due to the simple .gzi format.
    • CRAM codec cluster: Expected to take longer (~15–40 min) as it requires complex crafting of the CRAM container format (header → slice → per-record codec bytes).

    Parsing Surfaces (Entry Points)

    • BGZF index loader: Uses bgzf_open() and bgzf_index_load() for .gzi files.
    • Alignment reader: Uses sam_open(), sam_hdr_read(), and sam_read1() for SAM/BAM/CRAM files.

  3. Target Overview: alsa-lib (CVE-2026-25068)

    main

    The alsa-lib target focuses on the ALSA topology subsystem, which parses .tplg binary topology files and text-based SectionXXX configuration formats.

    Vulnerability Details:

    • CVE ID: CVE-2026-25068
    • Severity: MEDIUM 4.6 (NVD) / HIGH (Pipeline report grader)
    • Class: Heap OOB write (CWE-129 improper array index validation)
    • Root Cause: tplg_decode_control_mixer1() trusts num_channels from the .tplg binary, causing a loop to exceed the SND_TPLG_MAX_CHAN-element fixed array.
    • Pinned Commit: 63a981865a1c (v1.2.15.2)
    • Codebase Size: ~75k LOC total; ~10k LOC in src/topology/.

  4. Understand the threat model for dr_libs (dr_wav, dr_flac)

    main

    The dr_libs threat model covers two single-header C audio decoders: dr_wav.h and dr_flac.h. These libraries are pure parsers designed to be vendored directly into applications (e.g., game engines, media players).

    Key Security Context

    • Trust Boundary: The boundary exists between attacker-supplied bytes (untrusted audio files) and the embedding application's address space.
    • Execution Model: Parsing runs in-process at the embedder's privilege level using manually managed C (pointer arithmetic and malloc/realloc).
    • Primary Assets at Risk:
      • Host process integrity: Control-flow and memory integrity (Critical).
      • Adjacent process memory: Heap/stack data near decoder buffers (High).
      • Service availability: Bounded time and memory usage (Medium).
      • Decoded output integrity: Accuracy of PCM frames and metadata (Low).

  6. Run autonomous pipelines securely using bin/vp-sandboxed

    main

    The autonomous pipelines (vuln-pipeline, dnr-pipeline) execute target code and must be run in a sandboxed environment. Use the bin/vp-sandboxed command to launch the pipeline. This command ensures every agent is confined in a gVisor container with network egress restricted solely to the API.

    Security Warnings:

    • Agent-spawning subcommands will refuse to start outside of a sandbox unless you explicitly pass the --dangerously-no-sandbox flag.
    • Do not run autonomous agents in plain Docker (using runc) as they share the host's kernel. Use gVisor, Kata Container, or Firecracker microVMs for stronger isolation.
    • Never mount credential-bearing paths (e.g., ~/.aws, .env) into the agent's environment.
    • Avoid running containers with --privileged or host networking enabled.
    bin/vp-sandboxed

  7. Integrate `THREAT_MODEL.md` into scanning workflows

    main

    Once a THREAT_MODEL.md is generated, it should be used to scope subsequent scanning activities:

    • For /vuln-scan: The scanner automatically reads THREAT_MODEL.md as scoping context if it is present in the target directory.
    • For vuln-pipeline recon: The pipeline converts the threat model into focus_areas for the autonomous pipeline.

  8. Run the canary target for fast pipeline verification

    main

    The canary target is a deliberately vulnerable target used for rapid iteration and smoke-testing the vuln-pipeline. It contains three planted bugs designed to verify that pipeline changes, prompt tuning, focus-area steering, and reporting work end-to-end. A full run typically takes ~6 minutes.

    Use the canary target when:

    • Verifying pipeline changes after updates.
    • Iterating on prompts.
    • Validating the full pipeline (recon, find, grade, judge, report).
    • Performing a first run on a new installation to confirm Docker, Claude CLI, and entry points are functional.
    vuln-pipeline run canary --runs 3 --parallel --stream --model <model>

  9. Implement the Setup and Attack phase separation pattern

    main

    To minimize risk, separate the environment preparation from the execution phase using the following pattern:

    1. Setup Phase: Use docker build to pull dependencies and compile the target with normal network access.
    2. Freeze Phase: Pin base images, commit SHAs, and dependency versions in the Dockerfile to create a static snapshot.
    3. Attack Phase: Run agents against the frozen image on the vp-internal network. In this phase, network egress must be restricted via an allowlist proxy (defaulting to api.anthropic.com:443).

  10. Prepare for scanning: Map, Scope, and Equip

    main

    Before running scans on a codebase, follow these three steps to improve efficiency and accuracy:

    1. Map the system: Use the /threat-model skill to have the model distill a threat model. This identifies component relationships, trust boundaries, and exposure points. Use this map to prioritize services and run scans component-by-component.
    2. Partition the search space: Avoid agent duplication by assigning distinct slices of the codebase to different agents. You can partition by:
      • Focus area: Derived from the threat model (e.g., using the /vuln-scan skill).
      • Input-processing subsystems: Such as specific parsers, formats, or protocol stages.
    3. Equip with context and tools: Provide design docs, git history, and observability data (traces/logs). Instead of stuffing all context into the prompt, provide the model with tools to access it. Recommended tools include ripgrep for source trees, Ghidra for binaries, and httpx for web surfaces.

  11. Best practices for detection and response (D&R)

    main

    When using Claude for hunting and responding to active threats:

    • Start with files and local tools: Before building complex integrations, use grep, sort, and DuckDB on exported telemetry files.
    • Use logs for reachability: Use logs to ground static analysis. While static scanning shows what could be reached, logs show what is being reached. Use /dnr-hunt --repo to combine source analysis with log-driven hypotheses.
    • Seed ground truth: Before hunting unknowns, detonate a known exploit in a test environment to generate telemetry. Confirm the model can find the chain from that telemetry to calibrate expectations.
    • Distinguish probes from incidents: Most attack traffic is noise. Explicitly verdict things as benign with evidence to avoid alert fatigue.
    • Maintain a query ledger: For every query in /dnr-hunt, record the hypothesis, the query run, the result, and the next step. This makes investigations reviewable and ensures negative results are durable.
    • Verify via source and detonation: Never trust a finding from logs alone. A finding is only confirmed_exploited if it meets three criteria: log evidence, the flaw is located in source, and a PoC fires against a locally-running instance (or a mock application for libraries).
    • Propose, don't execute: The /dnr-respond command should only produce a plan (including what/why/risk-if-wrong for actions like blocking IPs or rotating credentials). Never allow the agent to execute containment actions directly.

  12. Add a Detection & Response target (kind: dnr)

    main

    Detection & Response (DNR) targets are runnable demo apps with a log corpus and a planted attack campaign. They are used by the dnr-pipeline rather than the find->grade pipeline.

    Key Requirements:

    • The config.yaml must include kind: dnr.
    • The target does not use a Dockerfile or entry.c. The pipeline builds the hunt-agent image automatically using a fixed stack (python3, python3-flask, python3-yaml, sqlite3, curl).
    • If your app requires other dependencies, you must edit DNR_APT_PACKAGES in dnr_harness/agent_image.py (this is the only place a DNR target requires a pipeline code change).
    • Spoiler Protection: To prevent the agent from seeing the answers, ground_truth and grader files must not be located inside the logs_dir or the app/ directory.