Trilhas de Auditoria Assinadas para Chamadas de Ferramentas do Claude Code

Um guia prático no estilo "cookbook" para recibos criptograficamente assinados em cada chamada de ferramenta do Claude Code. Esta é a habilidade de ensino. Para a implementação em tempo de execução, instale o plugin protect-mcp.

O que isso oferece a você

Cada chamada de ferramenta (Bash, Edit, Write, WebFetch) é:

1. Avaliada contra uma política Cedar antes da execução. Se a política negar a chamada, a ferramenta não será executada.
2. Assinada como um recibo Ed25519 após a execução. Os recibos são canônicos JCS e verificáveis offline por qualquer pessoa com a chave pública.

Um auditor, regulador ou contraparte pode verificar cada recibo posteriormente (Passo 5). Nenhuma chamada de rede, nenhuma consulta a fornecedor, nenhuma confiança no operador.

Quando usar o padrão

• Ambientes regulamentados (finanças, saúde, infraestrutura crítica) onde você precisa de evidências à prova de adulteração do comportamento do agente
• Pipelines de CI/CD onde você deseja provar que um portão de política foi mantido para cada etapa automatizada de compilação
• Colaboração multipartidária onde uma contraparte deseja verificar o comportamento do seu agente sem confiar no seu operador
• Contextos de conformidade (Artigo 12 do EU AI Act, proveniência SLSA para software construído por agentes) onde o registro padrão não é suficiente

Passo 1: Instale a configuração do hook

Instale o plugin protect-mcp com /plugin install protect-mcp. Seus hooks executam evaluate.sh antes de cada chamada de ferramenta e sign.sh após ela. Ambos os scripts leem o evento do hook do stdin, pois o Claude Code não define variáveis TOOL_NAME ou TOOL_INPUT. Veja references/hook-wiring.md para a configuração do hook e o que cada script passa para o protect-mcp.

O protect-mcp 0.7.4 não cria a chave de assinatura e, sem uma chave, os recibos ficam sem assinatura. Crie ./protect-mcp.key uma vez. O comando nunca substitui uma chave existente:

if [ ! -e ./protect-mcp.key ]; then
  d=$(mktemp -d) && npx protect-mcp@0.7.4 init --dir "$d" && mv "$d/keys/gateway.json" ./protect-mcp.key
fi

Forneça aos auditores o valor publicKey desse arquivo. Não comite o arquivo, pois ele também contém a chave privada.

Adicione a chave privada e o diretório de recibos a .gitignore:

echo "/protect-mcp.key" >> .gitignore
echo "/receipts/" >> .gitignore

Passo 2: Escreva uma política Cedar

Crie ./protect.cedar a partir do exemplo em references/cedar-policy.md. Ele permite ferramentas somente leitura e uma lista curta de comandos Bash, nega encadeamento de shell e comandos destrutivos, e limita gravações no projeto com segmentos de .. negados.

Passo 3: Use o Claude Code normalmente

Inicie o Claude Code. Cada chamada de ferramenta passa por ambos os hooks:

You: Please read the README and summarize it.

Claude: I will read README.md.
  [PreToolUse: Read ./README.md -> allow]
  [Tool: Read executes]
  [PostToolUse: receipt rcpt-a8f3c9d2 signed to ./receipts/]

... summary of README ...

Uma sessão de 20 chamadas de ferramenta anexa 20 recibos a ./receipts/receipts.jsonl.

Passo 4: Inspecione um recibo

O protect-mcp 0.7.4 anexa cada recibo como uma linha de ./receipts/receipts.jsonl. Imprima o mais novo:

tail -n 1 ./receipts/receipts.jsonl | python3 -m json.tool

O recibo é um envelope v2 assinado que nomeia a ferramenta e não contém chave pública. Veja references/receipt-format.md para um exemplo e os campos assinados.

Passo 5: Verifique os recibos

Passe o valor publicKey de ./protect-mcp.key para o verificador:

PUB=$(node -p 'JSON.parse(require("fs").readFileSync("./protect-mcp.key")).publicKey')
npx @veritasacta/verify@0.9.2 --replay-chain ./receipts/receipts.jsonl --key "$PUB"

Códigos de saída:

Passo 6: Demonstre a detecção de adulteração

Altere o decision do recibo mais novo de allow para deny:

python3 -c "
import json
path = './receipts/receipts.jsonl'
lines = open(path).read().splitlines()
r = json.loads(lines[-1])
r['payload']['decision'] = 'deny'
lines[-1] = json.dumps(r)
open(path, 'w').write('\n'.join(lines) + '\n')
"

npx @veritasacta/verify@0.9.2 --replay-chain ./receipts/receipts.jsonl --key "$PUB"

O verificador sai com o código 1 e relata qual linha falhou. A assinatura Ed25519 não corresponde mais aos bytes canônicos JCS do

…