Como fazer auditoria de segurança com Claude Code

Não entregue segurança à IA sem critério

Claude Code pode acelerar uma auditoria de segurança. Ele consegue ler rotas, comparar pull requests, resumir riscos de dependências, procurar logs perigosos, localizar variáveis de ambiente e transformar hábitos de revisão em checklists. Isso é útil porque o risco real costuma ficar espalhado entre autenticação, autorização, jobs de cobrança, webhooks, CI e logs.

O erro é pedir “verifique a segurança” e tratar a resposta como prova. Auditoria não é uma impressão geral. É uma revisão com escopo, ativos, ameaças, controles, evidências e riscos restantes. Claude Code ajuda a investigar e organizar, mas a decisão de negócio, o nível de exposição pública e o release continuam sendo responsabilidade humana.

Este guia mostra um fluxo prático para usar Claude Code em auditorias sem publicar detalhes exploráveis. Ele cobre escopo, inventário de ativos, modelo de ameaça, revisão de dependências, autenticação e sessão, secrets, validação de entrada, logs e PII, gates de CI, recibo de evidências e quatro casos de uso. Como base externa, use OWASP Top 10, OWASP ASVS, NIST SSDF e a documentação do GitHub sobre secret scanning.

Defina o escopo primeiro

O primeiro entregável não é um patch. É um brief de auditoria. O escopo diz ao Claude Code o que inspecionar, o que não alterar, quais comandos pode executar e o que conta como concluído. Sem escopo, a IA tende a comentar arquivos óbvios e pode ignorar rotas admin, billing, jobs em background, scripts de deploy ou secrets de CI.

Copie este modelo e preencha antes de pedir findings.

# Security Audit Brief

## Goal
- Find serious issues in authentication, authorization, secrets, input validation, logging, and dependencies before release
- Produce evidence and remaining-risk notes, not just suggested fixes

## Scope
- Repository:
- Branch or PR:
- Feature or workflow:
- Directories Claude Code may inspect:
- Directories Claude Code must not change:
- Commands Claude Code may run:

## Priority areas
- Authentication and session handling
- Authorization and roles
- Input validation and output encoding
- Secrets and environment variables
- Dependencies and licenses
- Logs, PII, and audit events
- CI gates that should block release

## Completion criteria
- Record findings in the risk register
- Include only minimal reproduction context
- Do not include live secrets, customer data, or dangerous exploit instructions
- Record commands, results, skipped areas, and human-review items in the evidence receipt

Depois do brief, peça mapeamento antes de qualquer edição: “Liste rotas, middleware de autenticação, APIs externas, environment variables, pontos de log, jobs de CI e arquivos de alto risco. Ainda não modifique código.” Esse passo deixa a pessoa revisora perceber áreas esquecidas.

Monte inventário de ativos e modelo de ameaça

Segurança começa por saber o que proteger. Ativos incluem dados de usuários, status de cobrança, API keys, painel admin, audit logs, uploads, mensagens de suporte e dados de analytics. Um modelo de ameaça é um pequeno mapa: quem pode entrar, por qual entrada, o que pretende afetar e qual controle deve bloquear.

| Asset | Stored in | Entry point | Likely threat | Required control | Owner |
| --- | --- | --- | --- | --- | --- |
| User email address | users table | signup, admin | unauthorized access, log leakage | authorization, PII masking, audit log | backend |
| Billing status | billing table, Stripe | webhook, admin | tampering, duplicate processing | signature verification, idempotency, role checks | backend |
| API keys | env, secret manager | CI, runtime | repository leak, log exposure | secret scanning, rotation, least privilege | platform |
| Admin console | /admin | browser | privilege escalation | MFA, admin role, operation logs | product |

Entregue a tabela ao Claude Code e peça para adicionar trust boundaries e testes. Trust boundary é a fronteira entre o que você controla e o que deve ser tratado como não confiável. Entrada do navegador, webhook, CSV importado, Markdown, nome de arquivo e resposta de API externa precisam ser validados antes do uso.

Dê trilhas de revisão específicas

Revisão de dependências inclui package.json, lockfiles, imagens Docker, GitHub Actions, versões de runtime e dependências transitivas. npm audit é apenas um sinal. Peça para Claude Code separar risco alcançável em produção de ruído de desenvolvimento, explicar breaking changes e listar os testes que provam que a atualização não quebrou o sistema.

Revisão de autenticação e sessão deve cobrir login, logout, reset de senha, MFA, OAuth, flags de cookie, expiração de sessão, CSRF e autorização no servidor. “O usuário está logado” e “o usuário pode fazer esta ação” são perguntas diferentes. APIs admin, ações de billing, downloads, IDs de usuário em rotas e webhooks repetíveis são pontos comuns de falha.

Revisão de secrets deve incluir .env, secrets de CI, configs de exemplo, README, logs, screenshots e fixtures de teste. Claude Code não deve imprimir secrets reais no chat. Ao encontrar algo suspeito, o relatório deve registrar caminho, tipo, recomendação de rotação e owner, com o valor mascarado. No GitHub, confirme secret scanning e push protection.

Validação de entrada deve seguir o fluxo dos dados: onde entram, onde são salvos, renderizados ou enviados. Não peça payloads perigosos. Peça validação na fronteira, normalização, escaping, type checks e testes. Para times iniciantes, seguir data flow é mais confiável do que decorar nomes de vulnerabilidades.

Logs e PII exigem procurar e-mails, nomes, endereços, tokens, cookies, headers de autenticação, IDs de pagamento e textos livres. Um console.log de desenvolvimento pode virar problema de retenção em produção. Logs devem conter o mínimo necessário para debug e auditoria, não request bodies completos.

Quatro casos de uso

O primeiro caso é auditoria SaaS antes do release. Antes de publicar billing, convites, configurações de organização ou área admin, faça Claude Code ler PR diff, migrations, rotas, webhooks, testes e CI. O objetivo é um risk register para a reunião de release, não uma promessa ampla de segurança.

O segundo caso é auditoria de handoff de repositório GitHub. Ao herdar um repo, o conhecimento perigoso costuma estar em scripts de deploy, secrets de CI, nomes de ambientes, runbooks manuais e pastas sem owner. Peça uma checklist da primeira semana: o que rotacionar, o que documentar, quais gates de CI faltam e quais áreas exigem revisão humana.

O terceiro caso é auditoria depois de incidente. Após queda ou suspeita de vazamento, não corrija só a linha que causou o problema. Peça busca de padrões parecidos, revisão de PII em logs, testes de regressão, novos gates de CI e atualização de runbook. Relatórios públicos devem explicar impacto e correção sem espalhar detalhes operacionais exploráveis.

O quarto caso é revisão de segurança de PR gerado por IA. Código gerado pode parecer limpo e ainda esquecer autorização, audit logs, tratamento de erro ou testes. Peça para Claude Code revisar apenas o impacto de segurança do diff: attack surface, permissões, secrets, dados pessoais, dependências e cobertura de CI.

Registre riscos e evidências

Finding precisa de evidência. Severidade sozinha não basta. O registro deve guardar impacto, prova, ação recomendada, prioridade, status e responsável.

| ID | Risk | Impact | Evidence | Recommended action | Priority | Status | Owner |
| --- | --- | --- | --- | --- | --- | --- | --- |
| SEC-001 | Missing authorization on admin API | Another user's data may be changed | routes/admin.ts has no role check | Add middleware and regression tests | High | Open | backend |
| SEC-002 | Webhook logs include email | Unnecessary PII retention | logs/webhook-sample.txt | Mask email and reduce retention | Medium | Open | platform |

O recibo de evidências evita que a auditoria vire apenas uma conversa difícil de rastrear.

# Security Audit Evidence Receipt

- Target:
- Date:
- Reviewer:
- Scope provided to Claude Code:
- Commands executed:
- Files or directories inspected:
- High-risk findings:
- Fixed items:
- Skipped or out-of-scope areas:
- Decisions requiring human review:
- Release recommendation:

Checklist para PR review

Para pull requests, mantenha uma checklist curta no prompt. Ela funciona muito bem com mudanças geradas por IA, porque puxa a discussão para risco e evidência antes de estilo.

## Security PR Review

- [ ] Scope is clear and no unrelated files are changed
- [ ] Authenticated users cannot access another user's data
- [ ] Admin or billing actions require explicit authorization
- [ ] Inputs are validated at the boundary
- [ ] Outputs are escaped or rendered safely
- [ ] No secrets, tokens, cookies, or PII are printed to logs
- [ ] Dependency changes have a reason and test evidence
- [ ] Errors do not reveal internals
- [ ] CI includes lint, tests, typecheck, and security-relevant checks
- [ ] Risk register and evidence receipt are updated

Checklist de comandos

Os comandos mudam conforme o stack, mas um projeto Node ou TypeScript pode começar assim. Peça ao Claude Code para explicar cada comando antes de executar e parar se uma falha mudar o risco.

git status --short
npm ci
npm audit --audit-level=moderate
npm run lint
npm run typecheck
npm test
rg -n "TODO|FIXME|console\\.log|process\\.env|localStorage|innerHTML|dangerouslySetInnerHTML" src
git diff --check

Resultados de rg são pistas, não vereditos. process.env pode estar correto, e innerHTML pode ser aceitável se for sanitizado. Peça para Claude Code separar evidência, hipótese e passo de confirmação.

Falhas e armadilhas comuns

A maior falha é prompt vago. “Veja a segurança” costuma produzir resposta rasa. Um bom prompt cita escopo, ativos, prazo de release, comandos permitidos, fluxos críticos e formato de saída. Um relatório que diz claramente “não revisado” vale mais que uma conclusão confiante sem prova.

A segunda falha é não deixar evidência. Se ninguém sabe quais comandos rodaram, quais arquivos foram inspecionados e o que ficou fora, a auditoria não apoia decisão de release. Confirme as afirmações do Claude Code com CI, testes, diffs, logs e configuração.

Outra falha perigosa é publicar detalhe demais. Não coloque URLs reais, tokens, dados de clientes ou instruções passo a passo em issues e artigos públicos. A comunicação pública deve focar impacto e remediação. Reproduções sensíveis ficam em sistema restrito.

Não ignore secrets e logs. Um app pode ter código razoável e ainda vazar por logs de CI, screenshots de debug, .env de exemplo ou erros verbosos. Mudanças de auth, pagamentos, dados pessoais e admin precisam de revisão humana obrigatória.

Leve para CI e hábitos do time

Auditoria pontual envelhece rápido. Adicione gates de CI para lint, typecheck, tests, dependency audit, secret scanning, busca de APIs perigosas e regras de log. Nem todo warning precisa bloquear. Na prática, High bloqueia, Medium vira ticket com prazo e Low entra na manutenção periódica.

Também revise as permissões do Claude Code com o guia de permissões. Combine com gestão de secrets, casos de falha de segurança e code review com Claude Code. Se o time quer transformar isso em política, gates de CI e brief específico do repo, comece por treinamento e consultoria Claude Code.

Resumo

Claude Code é mais útil em auditorias quando a pessoa define o sistema ao redor: escopo, ativos, threat model, trilhas de revisão, risk register, evidence receipt, CI e aprovação humana para decisões críticas. Sem essa estrutura, o relatório pode soar bem sem explicar o risco real.

Quando Masa aplicou esse fluxo nas revisões pré-release do ClaudeCodeLab, o maior ganho veio do risk register e do evidence receipt. Fazer Claude Code inventariar rotas, logs, environment variables e CI antes da revisão humana deixou as perguntas pendentes mais visíveis. O resultado não foi uma garantia de segurança perfeita, mas uma decisão de release mais clara.