방어 코드 참조 하네스 (Defending Code Reference Harness)

Claude Mythos 미리보기 출시 이후 여러 조직의 보안 팀과 협력하여 얻은 학습을 바탕으로 Claude를 이용한 자율 취약점 발견 및 수정을 위한 참조 구현체입니다. 이러한 학습 내용과 모범 사례에 대한 자세한 내용은 함께 제공되는 블로그 게시물을 참조하세요(blog-post.md에서도 확인 가능). 동일한 정찰 → 발견 → 분류 → 보고 → 패치 루프에 대한 가벼운 SDK 전용 연습은 함께 제공되는 쿡북을 참조하세요.

이 저장소는 유지 관리되지 않으며 기여를 받지 않습니다.

🔒 관리형 옵션을 원하시나요? Anthropic은 여러 프로젝트의 소스 코드에서 취약점을 찾아 수정하는 호스팅 제품인 Claude Security를 제공합니다. Claude Security는 저장소의 취약점을 스캔하고, 다단계 검증 파이프라인을 적용하여 가양성을 줄이며, 발견 사항을 분류, 수정 검증, 신속한 수정 생성 등의 라이프사이클을 통해 관리할 수 있도록 합니다.

이 저장소는 Claude를 사용하여 취약점을 찾기 위한 일반적인 모범 사례를 기반으로 한 오픈소스 참조 구현입니다. 이를 사용하여 자체 취약점 발견 파이프라인을 구축하고, 로직을 사용자 정의할 수 있으며, Claude API에 대한 모든 액세스 권한(Bedrock, Vertex 또는 Azure 포함)과 함께 사용할 수 있습니다.

목차

• Claude Code 스킬: /quickstart, /threat-model, /vuln-scan, /triage, /patch, /customize: 대화형 범위 지정, 스캔, 분류 및 패치. 이 저장소를 Claude Code에서 열고 /quickstart를 실행하여 방향을 잡으세요.
• harness/: Docker와 ASAN을 사용하여 C/C++ 메모리 취약점을 찾도록 구성된 자율 참조 파이프라인(정찰 → 발견 → 확인 → 보고 → 패치)입니다. 이 하네스는 참조용이며 제품이 아닙니다. 일반적인 구조, 프롬프트 및 샌드박싱은 재사용 가능하지만, 하네스가 모든 코드베이스에서 즉시 작동하지는 않습니다. /customize를 실행하여 언어, 탐지기 또는 취약점 클래스에 맞게 이식하세요.

⚠️ 보안: /quickstart, /threat-model, /vuln-scan, /triage는 파일만 읽고 씁니다. 정적 발견 사항(TRIAGE.json 또는 VULN-FINDINGS.json)에 대해 /patch를 실행하는 것도 마찬가지로 읽기 및 쓰기 전용입니다. /customize는 하네스 코드를 편집하고 유효성 검사 명령을 실행합니다. 이러한 스킬은 Claude Code에서 각 도구 사용을 검토하고 승인하는 한 샌드박스 없이 실행해도 안전합니다. 자율 참조 파이프라인(파이프라인 결과에 대한 /patch 포함)은 대상 코드를 실행하므로 명시적으로 재정의하지 않는 한 gVisor 샌드박스 외부에서 실행을 거부합니다. 설정을 위해 scripts/setup_sandbox.sh를 한 번 실행한 다음 bin/vp-sandboxed를 통해 파이프라인을 호출하세요. 자세한 내용은 docs/security.md 및 docs/agent-sandbox.md를 참조하세요.

시작하기

git clone https://github.com/anthropics/defending-code-reference-harness
cd defending-code-reference-harness
claude

# 30-sec intro + guided first run on the canary target
> /quickstart

> /quickstart how do I port the pipeline to Java?
> /quickstart how do I triage all these bugs?

추가 자료

• 블로그 게시물 · 학습 내용 + 모범 사례를 담은 블로그 게시물
• 파이프라인 · 작동 방식: 다이어그램, 단계, CLI 플래그
• 보안 · 샌드박싱, 마운트하지 말아야 할 사항
• 에이전트 샌드박스 · 각 에이전트의 gVisor 격리 + 이그레스 허용 목록
• 사용자 정의](docs/customizing.md) · 내 스택으로 이식; 변경되는 파일과 이유
• 패치 · 확인된 크래시에 대한 수정 사항 생성 및 검증
• 문제 해결 · 중복, 속도 제한, 하위 에이전트 모델 고정
• 보호 장치 · 위험한 사이버 작업 차단

단계별 적응

저희가 협력한 가장 성공적인 보안 팀은 가장 빠르게 직접 작업을 시작한 팀이었습니다. 완벽한 파이프라인을 설계하는 데 몇 달을 보내고 싶은 유혹이 있지만, 1일차에 작게 시작하여 학습이 진행됨에 따라 구축해 나갈 것을 권장합니다. 아래 단계는 이러한 패턴을 따르며, 우리가 본 바를 기반으로 야심 차지만 합리적인 속도를 설정합니다.

1단계 (1일차): 위협 모델 구축 및 첫 번째 정적 스캔 + 분류 실행

1일차는 전체 루프를 종단 간 확인하는 데 중점을 둡니다. 대화형 스킬만 사용하여 위협 모델을 구축하고, 이에 따라 범위가 지정된 정적 스캔을 실행하고, 반환된 결과를 분류하고, 후보 수정 사항을 초안 작성합니다. 하루가 끝나면 위협 모델, 정적 발견 사항의 순위 목록 및 후보 패치를 갖게 됩니다.

관련 스킬은 저장소의 파일만 읽고 씁니다. Claude Code를 대화형으로 실행하고 각 도구 사용을 승인하는 한 샌드박스가 필요하지 않습니다.

# Pin every subagent to the model you want
export CLAUDE_CODE_SUBAGENT_MODEL=<model-id>
claude

# 0. intro + guided first run
> /quickstart

# 1. Build a threat model (aim before you shoot)
> /threat-model bootstrap targets/canary

# 2. Run a static scan, scoped by that threat model
> /vuln-scan targets/canary

# 3. Verify, dedupe, and rank what came back
> /triage targets/canary/VULN-FINDINGS.json

# 4. Generate candidate fixes for the verified findings
> /patch ./TRIAGE.json --repo targets/canary

이 흐름은 THREAT_MODEL.md, VULN-FINDINGS.{json,md}, TRIAGE.{json,md} 및 PATCHES/를 생성합니다.

1단계에서 생성된 취약점 후보는 Claude의 소스 정적 검토(아무것도 빌드하거나 실행하지 않음)에서 비롯되므로, 카나리 대상이 아닌 경우 더 많은 가양성이 예상됩니다. 2단계에서는 실행 검증된 발견 사항을 생성합니다.

참고: 카나리 대상에서 /triage는 스캔 결과를 가양성으로 기각할 수 있습니다. entry.c는 의도적으로 취약한 데모 코드임을 알리며, /triage는 테스트/픽스처 코드의 버그를 올바르게 제외합니다. 전체 확인/중복 제거/가양성 흐름을 보려면 큐레이트된 픽스처에서 실행하거나(/triage .claude/skills/triage/fixtures/canary-findings.json --repo targets/canary) 1단계 스킬을 자체 코드에 사용하세요.

2단계 (2일차): C/C++ 라이브러리에서 참조 파이프라인 실행

2일차에는 대화형 스킬에서 참조 파이프라인을 사용한 첫 번째 자율 실행으로 넘어갑니다. 알려진 취약점이 있는 오픈소스 라이브러리를 대상으로 환경에서 전체 정찰 → 발견 → 확인 → 보고 루프를 실행한 다음, 발견된 사항에 대한 후보 패치를 생성합니다. 재현 가능한 크래시, 악용 가능성 보고서 및 후보 패치와 함께 파이프라인 작동 방식에 대한 감을 얻게 됩니다.

파이프라인 실행은 간단합니다:

# One-time setup
python3 -m venv .venv && .venv/bin/pip install -e .
./scripts/setup_sandbox.sh   # installs gVisor, builds the agent images, and verifies isolation; note: requires Docker
export ANTHROPIC_API_KEY=sk-ant-...   # or CLAUDE_CODE_OAUTH_TOKEN, or Bedrock — see docs/agent-sandbox.md

# Run the recon → find → verify → report loop
bin/vp-sandboxed run drlibs --model <model-id> --runs 3 --parallel --stream --auto-focus
# Generate a candidate patch for each finding
bin/vp-sandboxed patch results/drlibs/<timestamp>/ --model <model-id>

# Or, ask Claude Code to launch the pipeline and watch the run for you
claude
> run the pipeline on drlibs and explain findings as they come

루프의 결과는 results/drlibs/<timestamp>/ 디렉터리에 저장됩니다. --stream 플래그를 사용하면 첫 번째 보고서가 reports/bug_NN/ 아래에 몇 분 안에 나타납니다.

⚠️ run은 자율 에이전트를 생성합니다. 파이프라인은 각 에이전트를 Claude API로의 이그레스가 제한된 gVisor 컨테이너 내에서 실행합니다. 에이전트를 생성하는 하위 명령은 명시적으로 재정의하지 않는 한 외부에서 시작을 거부합니다. 자세한 내용은 docs/security.md 및 docs/agent-sandbox.md를 참조하세요.

내부적으로 파이프라인은 7단계를 거칩니다:

1. 빌드: ASAN(C 및 C++용 메모리 오류 탐지기)을 사용하여 대상을 Docker 이미지로 컴파일합니다. 파이프라인은 대상의 Dockerfile을 사용하여 첫 번째 실행 시 이 이미지를 자동으로 빌드합니다.
2. 정찰: 경량 에이전트가 네트워크 격리 컨테이너 내에서 소스를 읽고 파티션을 제안합니다. 예: "여기에 별도로 공격할 가치가 있는 N개의 고유한 입력 파싱 하위 시스템이 있습니다". 이렇게 하면 병렬 찾기 에이전트가 동일한 버그에 수렴하는 대신 다른 영역을 탐색합니다. --auto-focus 플래그가 없으면 파이프라인은 대상의 config.yaml에 있는 focus_areas 목록을 사용합니다.
3. 찾기: N개의 에이전트가 각각 자체 격리 컨테이너에서 병렬로 실행됩니다. 각 에이전트는 소스를 읽고, 잘못된 입력을 만들고, 주어진 입력이 3회 중 3회 크래시를 생성할 때까지 ASAN 바이너리를 실행합니다.
4. 확인: 별도의 채점자 에이전트가 찾기 에이전트가 건드리지 않은 새 컨테이너에서 각 크래시를 재현합니다. 찾기 에이전트에서 채점자로 넘어가는 유일한 것은 생성된 개념 증명입니다.
5. 중복 제거: 판사 에이전트가 확인된 크래시를 이미 보고된 버그와 비교하고 각각이 새로운 버그인지, 알려진 버그의 더 나은 예인지, 건너뛸 중복인지 결정합니다.
6. 보고: 보고 에이전트가 고유 버그별로 구조화된 악용 가능성 분석을 작성합니다. 여기에는 기본 요소 클래스, 도달 가능성, 에스컬레이션 경로 및 심각도에 대한 세부 정보가 포함됩니다.
7. 패치(위의 별도 패치 명령): 패치 에이전트가 제안된 수정 사항을 작성하고, 채점자 에이전트가 새 코드가 빌드되고, 원래 개념 증명 입력이 더 이상 크래시되지 않으며, 대상의 테스트 스위트가 여전히 통과하고, 새로운 찾기 에이전트가 수정 사항을 우회할 방법을 찾을 수 없는지 확인합니다.

자세한 내용은 docs/pipeline.md를 참조하세요.

3단계 (3-5일차): 대상에 맞게 파이프라인 사용자 정의

3-5일차에는 자체 대상에 맞게 하네스를 사용자 정의합니다. 먼저 1단계 스킬을 코드에 적용한 다음 /customize를 사용하여 파이프라인을 스택으로 이식합니다. 주말까지 파이프라인이 실행될 수 있는 targets/<your-service>/ 디렉터리를 확보하고, 단일 스모크 실행으로 검증한 후 4단계에서 확장할 준비를 마칩니다.

참조 파이프라인은 C 및 C++ 코드의 메모리 취약점을 찾도록 설계되었지만, 그 형태는 일반적입니다. 새로운 취약점 클래스나 언어로 이식하려면 대상 스택에 대해 다음 질문에 답하기만 하면 됩니다:

사용자 정의하기 전에 1단계 스킬을 자체 코드에 사용하세요. 참고로 이들은 읽기 및 쓰기 전용이므로 샌드박스 없이 실행할 수 있습니다.

claude

> /quickstart how do I customize this for ~/code/my-service?

> /threat-model bootstrap-then-interview ~/code/my-service
> /vuln-scan ~/code/my-service
> /triage ~/code/my-service/VULN-FINDINGS.json --repo ~/code/my-service

그런 다음 이 스킬에서 생성된 아티팩트를 /customize 스킬에서 사용합니다. 이 스킬은 코드베이스에 맞게 하네스를 수정합니다.

> /customize use ~/code/my-service/{THREAT_MODEL.md,VULN-FINDINGS.json} and ./TRIAGE.md

/customize가 완료되면 targets/my-service/ 디렉터리가 설정됩니다. 확장하기 전에 파이프라인의 스모크 실행으로 검증하세요.

bin/vp-sandboxed run my-service --model <model-id> --runs 1

자세한 내용은 docs/customizing.md를 참조하세요.

4단계 (2주차): 자율 스캐닝, 분류 및 패치 시작

2주차에는 3단계에서 사용자 정의한 파이프라인을 자체 대상에 사용하여 내부 파이프라인 루프에 외부 루프를 추가합니다. 여러 파이프라인 스캔을 실행하고, 이러한 실행 전체에서 발견 사항을 분류하고, 우선순위에 따라 패치하고, 반복합니다.

# Scan - run a wave of parallel runs against your target
bin/vp-sandboxed run my-service --model <model-id> --runs 5 --parallel --stream --auto-focus

# Triage - dedupe and rank every finding across all waves using your threat model
> /triage results/my-service/ --repo ~/code/my-service --auto --votes 5

# Patch - generate and validate fixes, starting with what triage ranked the highest
> /patch results/my-service/<timestamp>/ --model <model-id>

⚠️ 2단계와 동일한 샌드박스 지침을 따르세요.

주어진 파이프라인 실행은 이미 자체 발견 사항을 확인하고 중복을 제거합니다. /triage는 여러 파이프라인 실행에 걸쳐 작동합니다. results/ 디렉터리를 가리키면 모든 실행 간의 중복(및 존재하는 경우 /vuln-scan의 정적 발견 사항)을 병합하고, 위협 모델에 대해 심각도 등급을 재조정하며, 각 발견 사항을 구성 요소 소유자에게 라우팅하려고 시도합니다.

가능하면 발견 사항을 신속하게 패치하는 것이 외부 루프를 최대한 생산적으로 유지하는 데 도움이 됩니다. 발견 사항이 수정되면 모델이 이를 다시 찾을 수 없으며 대신 일반적으로 더 깊은 새로운 문제를 표면화합니다. 더 많은 파이프라인 웨이브를 실행할수록 발견 사항의 수는 줄어들 가능성이 높지만 복잡성은 증가할 가능성이 높습니다. 신속한 패치가 불가능한 경우, 이전 발견 사항을 대상의 known_bugs에 기록하는 것만으로도 향후 실행을 최신 버그로 유도하는 데 도움이 될 수 있습니다.

자율 분류 및 패치는 여전히 해결되지 않은 문제이며, 이 참조 하네스는 이를 완전히 해결하지 못합니다. /patch의 검증 전략은 기준을 높이는 데 도움이 되지만, 심각도와 우선순위는 궁극적으로 사용자 환경에 대한 판단이며, 검증된 패치가 항상 업스트림에 적용 가능한 것은 아닙니다. 많은 파트너가 이러한 단계를 현재 병목 현상으로 보고했으며, 이에 대한 실제 엔지니어링 시간을 할당해야 합니다.

자세한 내용은 docs/triage.md 및 docs/patching.md를 참조하세요.

향후 전망

초기 적응 후, 저희가 협력한 팀들은 다음과 같은 몇 가지 방향에 투자하는 경향이 있었습니다:

1. 모든 내부 저장소와 주요 오픈소스 종속성을 검토하고, 스캔할 가장 중요한 항목(예: 노출, CVE 이력, 비즈니스 중요성 기준)의 순위를 매긴 다음, 우선순위 순서대로 목록을 스캔합니다.
2. 스캔을 노트북이나 임시 VM에서 이동하기 위해 맞춤형 스캔 인프라를 구축합니다. 가장 성공적인 팀은 확장하기 전에 완벽한 스캐닝 플랫폼을 구축하려는 충동을 극복합니다.
3. SDLC에 스캔을 통합합니다. 일부 팀은 정기 스캔(예: 일별, 주별)을 설정하거나 CI 파이프라인에 스캔을 추가했습니다.
4. 모델을 테스트하고 실험하여 자신에게 가장 적합한 것을 찾습니다.