Defending Code Reference Harness

Uma implementação de referência para descoberta e remediação autônoma de vulnerabilidades com o Claude, baseada em nossos aprendizados ao fazer parceria com equipes de segurança em várias organizações desde o lançamento do Claude Mythos Preview. Para um artigo sobre esses aprendizados junto com melhores práticas, veja a postagem do blog de acompanhamento (também disponível em blog-post.md). Para um passo a passo leve apenas com SDK do mesmo ciclo recon → find → triage → report → patch, veja o cookbook complementar.

Este repositório não é mantido e não está aceitando contribuições.

🔒 Quer uma opção gerenciada? A Anthropic oferece o Claude Security, um produto hospedado que encontra e corrige vulnerabilidades no seu código-fonte em vários projetos. O Claude Security escaneia seu repositório em busca de vulnerabilidades, aplica um pipeline de verificação em múltiplos estágios para reduzir falsos positivos e permite que você gerencie as descobertas ao longo do ciclo de vida: triagem, validação de correções e geração rápida de correções.

Este repositório é uma implementação de referência de código aberto baseada em melhores práticas gerais para encontrar vulnerabilidades usando o Claude. Você pode usá-lo para construir seu próprio pipeline de descoberta de vulnerabilidades, personalizar a lógica e pode ser usado com qualquer acesso que você tenha às APIs do Claude (incluindo Bedrock, Vertex ou Azure).

Conteúdo

• Habilidades do Claude Code: /quickstart, /threat-model, /vuln-scan, /triage, /patch, /customize: escopo interativo, varredura, triagem e correção. Abra este repositório no Claude Code e execute /quickstart para se orientar.
• harness/: o pipeline de referência autônomo (recon → find → verify → report → patch), configurado para encontrar vulnerabilidades de memória em C/C++ usando Docker e ASAN. Este harness é uma referência, não um produto. A forma geral, os prompts e o isolamento são reutilizáveis, mas o harness não funcionará em todas as bases de código imediatamente. Execute /customize para adaptá-lo à sua linguagem, detector ou classe de vulnerabilidade.

⚠️ Segurança: /quickstart, /threat-model, /vuln-scan e /triage apenas leem e escrevem arquivos. Executar /patch em descobertas estáticas (TRIAGE.json ou VULN-FINDINGS.json) também é somente leitura e escrita. /customize edita o código do harness e executa comandos de validação. Qualquer uma dessas habilidades é segura para executar sem sandbox, desde que você revise e aprove cada uso de ferramenta no Claude Code. O pipeline de referência autônomo (incluindo /patch nos resultados do pipeline) executa código do alvo, portanto, ele se recusa a ser executado fora de um sandbox gVisor a menos que explicitamente substituído. Para configurar, execute scripts/setup_sandbox.sh uma vez e, em seguida, invoque o pipeline via bin/vp-sandboxed. Consulte docs/security.md e para mais detalhes.

Primeiros Passos

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?

Leitura Adicional

• Postagem do Blog · A postagem do blog de acompanhamento com aprendizados + melhores práticas
• Pipeline · Como funciona: diagrama, estágios, flags de CLI
• Segurança · Isolamento, o que não montar
• Sandbox do agente · Isolamento gVisor + lista de permissões de egresso para cada agente
• Customização · Adaptar para minha stack; quais arquivos mudam e por quê
• Correção · Gerar e verificar correções para crashes verificados
• Solução de Problemas · Duplicatas, limites de taxa, fixação de modelo do subagente
• Salvaguardas · Bloqueio para trabalho cibernético perigoso

Aceleração

As equipes de segurança mais bem-sucedidas com as quais fizemos parceria são aquelas que se envolveram mais rapidamente. Embora seja tentador passar meses projetando o pipeline perfeito, recomendamos começar pequeno no Dia 1 e construir a partir daí à medida que os aprendizados surgem. As etapas abaixo seguem esse padrão e estabelecem um ritmo ambicioso (mas razoável) com base no que vimos.

Etapa 1 (Dia 1): Construir um modelo de ameaça e executar sua primeira varredura estática + triagem

O Dia 1 é focado em ver todo o ciclo de ponta a ponta. Usando apenas as habilidades interativas, você construirá um modelo de ameaça, executará uma varredura estática com escopo definido por ele, fará a triagem dos resultados e rascunhará correções candidatas. Você terminará o dia com um modelo de ameaça, uma lista classificada de descobertas estáticas e patches candidatos.

As habilidades relevantes apenas leem e escrevem arquivos em seu repositório. Desde que você execute o Claude Code interativamente e aprove cada uso de ferramenta, nenhum sandbox é necessário.

# 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

Este fluxo produz THREAT_MODEL.md, VULN-FINDINGS.{json,md}, TRIAGE.{json,md} e PATCHES/.

Os candidatos a vulnerabilidade produzidos na Etapa 1 vêm da revisão estática do Claude sobre o código-fonte (nada é compilado ou executado), portanto, espere mais falsos positivos em alvos que não sejam canary. Na Etapa 2, você produzirá descobertas verificadas por execução.

Nota: no alvo canary, /triage pode descartar as descobertas da varredura como falsos positivos. entry.c anuncia-se como código de demonstração deliberadamente vulnerável, e /triage exclui corretamente bugs em código de teste/fixture. Para ver o fluxo completo de confirmação / deduplicação / falso positivo, execute-o no fixture curado (/triage .claude/skills/triage/fixtures/canary-findings.json --repo targets/canary) ou aponte as habilidades da Etapa 1 para seu próprio código.

Etapa 2 (Dia 2): Executar o pipeline de referência em uma biblioteca C/C++

No Dia 2, você passará das habilidades interativas para sua primeira execução autônoma usando o pipeline de referência. Você executará o ciclo completo recon → find → verify → report em seu ambiente em uma biblioteca de código aberto conhecidamente vulnerável e, em seguida, gerará um patch candidato para o que ele encontrar. Você terminará com um conjunto de crashes reproduzíveis, relatórios de explorabilidade e patches candidatos, além de uma noção de como o pipeline funciona.

Executar o pipeline é simples:

# 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

Os resultados do ciclo vão para um diretório results/drlibs/<timestamp>/. Com a flag --stream, o primeiro relatório aparecerá em minutos em reports/bug_NN/.

⚠️ run gera agentes autônomos. O pipeline executa cada agente dentro de um contêiner gVisor com egresso restrito à API do Claude. Subcomandos que geram agentes se recusam a iniciar fora dele, a menos que explicitamente substituídos. Para mais informações, veja docs/security.md e docs/agent-sandbox.md.

Nos bastidores, o pipeline percorre sete estágios:

1. Build: Compila o alvo em uma imagem Docker com ASAN (o detector de erros de memória para C e C++). O pipeline constrói esta imagem automaticamente na primeira execução usando o Dockerfile do alvo.
2. Recon: Um agente leve lê o código-fonte dentro de um contêiner com isolamento de rede e propõe uma partição, ou seja, "aqui estão N subsistemas distintos de análise de entrada que valem a pena atacar separadamente", para que agentes de busca paralelos explorem áreas diferentes em vez de convergirem para o mesmo bug. Sem a flag --auto-focus, o pipeline usa a lista focus_areas do config.yaml do alvo.
3. Find: N agentes executam em paralelo, cada um em seu próprio contêiner isolado. Cada agente lê o código-fonte, cria entradas malformadas e executa o binário ASAN até que uma determinada entrada produza um crash 3 de 3 vezes.
4. Verify: Um agente avaliador separado reproduz cada crash em um contêiner novo que o agente de busca não tocou. A única coisa que passa do agente de busca para o avaliador é a prova de conceito que ele produziu.
5. Dedupe: Um agente juiz compara crashes verificados com bugs já reportados e decide se cada um é um bug novo, um exemplo melhor de um bug conhecido ou uma duplicata a ser ignorada.
6. Report: Um agente de relatório escreve uma análise de explorabilidade estruturada por bug único, incluindo detalhes sobre classe de primitiva, alcançabilidade, caminho de escalada e severidade.
7. Patch (o comando de patch separado acima): Um agente de correção escreve uma correção proposta, e um agente avaliador confirma que o novo código compila, que a prova de conceito original não causa mais crash, que o conjunto de testes do alvo ainda passa e que um novo agente de busca não consegue encontrar uma maneira de contornar a correção.

Para mais detalhes, veja docs/pipeline.md.

Etapa 3 (Dias 3-5): Customizar o pipeline para seu alvo

Nos Dias 3-5, você customizará o harness para seu próprio alvo. Primeiro, você apontará as habilidades da Etapa 1 para seu código e, em seguida, usará /customize para adaptar o pipeline à sua stack. No final da semana, você terá um diretório targets/<seu-serviço>/ contra o qual o pipeline pode executar, validado com uma única execução de teste do pipeline e pronto para escalar na Etapa 4.

Embora o pipeline de referência seja projetado para encontrar vulnerabilidades de memória em código C e C++, sua forma é genérica. Adaptá-lo para uma nova classe de vulnerabilidade ou linguagem significa apenas responder às seguintes perguntas para sua stack alvo:

Antes de customizar, aponte as habilidades da Etapa 1 para seu próprio código. Como lembrete, elas são somente leitura e escrita, portanto podem ser executadas sem sandbox.

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

Em seguida, use os artefatos produzidos por essas habilidades na habilidade /customize, que modifica o harness para sua base de código.

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

Quando /customize terminar, você terá um diretório targets/my-service/ configurado. Valide-o com uma execução de teste do pipeline antes de escalar.

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

Para mais detalhes, veja docs/customizing.md.

Etapa 4 (Semana 2): Iniciar varredura, triagem e correção autônomas

Na Semana 2, você usará o pipeline que customizou na Etapa 3 em seus próprios alvos, adicionando um ciclo externo ao ciclo interno do pipeline – execute várias varreduras do pipeline, faça a triagem das descobertas dessas execuções, corrija com base na priorização e repita.

# 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>

⚠️ Siga as mesmas diretrizes de isolamento da Etapa 2

Uma determinada execução do pipeline já verifica e deduplica suas próprias descobertas. /triage funciona entre várias execuções do pipeline. Quando apontado para o diretório results/, ele colapsa duplicatas em todas as execuções (e quaisquer descobertas estáticas de /vuln-scan, se presentes), recalibra as classificações de severidade de acordo com seu modelo de ameaça e tenta encaminhar cada descoberta para o proprietário do componente.

Quando possível, corrigir descobertas rapidamente ajuda a manter o ciclo externo o mais produtivo possível. Quando as descobertas são corrigidas, o modelo não pode reencontrá-las e, em vez disso, descobrirá problemas novos, geralmente mais profundos. Conforme você executa mais ondas do pipeline, o número de descobertas provavelmente diminuirá, mas a complexidade provavelmente aumentará. Se a correção rápida não for possível, mesmo apenas registrar descobertas anteriores no known_bugs do alvo pode ajudar a direcionar execuções futuras para bugs mais novos.

Triagem e correção autônomas ainda são questões em aberto, e este harness de referência não as resolve completamente. As estratégias de verificação em /patch ajudam a elevar o padrão, mas a severidade e a priorização são, em última análise, julgamentos sobre seu ambiente, e patches verificados nem sempre são integráveis. Muitos parceiros relataram essas etapas como seus gargalos atuais, e você deve alocar tempo real de engenharia para elas.

Para mais detalhes, veja docs/triage.md e docs/patching.md.

Perspectivas Futuras

Após a aceleração inicial, as equipes com as quais trabalhamos tenderam a investir em algumas direções:

1. Revisar todos os seus repositórios internos e dependências de código aberto-chave, classificando quais são os mais importantes para escanear (por exemplo, com base em sua exposição, histórico de CVEs, criticidade para o negócio) e, em seguida, trabalhar escaneando a lista em ordem de prioridade.
2. Configurar infraestrutura personalizada para varredura, a fim de mover as varreduras para fora de laptops ou VMs avulsas. As equipes mais bem-sucedidas resistem ao impulso de construir a plataforma de varredura perfeita antes de escalar.
3. Incorporar varreduras em seu SDLC. Algumas equipes configuraram varreduras recorrentes (por exemplo, diárias, semanais) ou adicionaram varreduras em seus pipelines de CI.
4. Testar e experimentar com os modelos para descobrir o que funciona melhor para elas.