Skill security-audit da Cloudflare: auditoria de segurança com IA no seu app

Você gerou o app com IA, funciona, está no ar. E segurança? Ninguém olhou. Este material ensina a instalar uma skill open source da Cloudflare que transforma seu agente de código em auditor de segurança — e a interpretar o que ele devolve.

Skill = um pacote de instruções que o agente carrega quando reconhece a tarefa. Não é plugin de IDE nem serviço pago: é Markdown + validadores em Node, licença MIT, repositório público em github.com/cloudflare/security-audit-skill.

O que você vai ter no fim

A skill instalada no seu agente (Claude Code, Codex, Cursor ou qualquer um que suporte skills e sub-agentes).
Uma auditoria completa do seu projeto, em 6 fases, com relatório em Markdown e JSON.
Critério pra decidir o que corrigir primeiro sem sair correndo atrás de falso positivo.

Pré-requisitos

Node.js instalado (a skill usa validadores em Node pra checar o JSON de achados).
Um agente de código que suporte tool use e sub-agentes em paralelo — Claude Code é o caso testado aqui.
Seu projeto num diretório local (pode ser o monorepo inteiro).

A skill roda análise estática e pode executar código do projeto em fases de validação. Rode dentro de um ambiente que você controla (sua máquina, um container ou uma VM), nunca apontando pra produção.

Passo 1 — Instalar a skill

O instalador oficial é o npx skills. No diretório do seu projeto:

npx skills add https://github.com/cloudflare/security-audit-skill
--skill security-audit

Quer a skill disponível em todos os projetos da sua máquina? Use --global:

npx skills add https://github.com/cloudflare/security-audit-skill
--skill security-audit
--global

O que acontece: o instalador baixa a pasta skills/security-audit/ do repositório (o SKILL.md, os guias RECONNAISSANCE.md e HUNTING.md, os catálogos de classes de ataque e os validadores JSON) e registra no diretório de skills do seu agente.

No Claude Code, confirme que carregou: abra uma sessão nova no projeto e digite /security-audit. Se o comando aparecer no autocomplete, está instalado.

Passo 2 — Rodar a primeira auditoria

A skill dispara por linguagem natural. Estes três pedidos ativam o fluxo completo:

Auditoria do projeto inteiro

security audit this codebase

Foco numa pasta

find security vulnerabilities in ./src

Com pasta de saída definida

do a security review, output to ~/audits/meu-app

Em português funciona igual — o gatilho é a intenção, não a frase exata. Exemplo real que usamos num app Nuxt + Hono na Cloudflare:

Exemplo real (monorepo Nuxt + Hono)

Faça uma auditoria de segurança completa deste monorepo. Foque em apps/api (Hono em Cloudflare Workers) e apps/portal (Nuxt 4). Grave os relatórios em ./audits/2026-09.

Passo 3 — Entender as 6 fases (o que o agente está fazendo)

Enquanto roda, você vai ver o agente passar por seis etapas. Saber o que cada uma faz evita interromper no meio.

Reconhecimento — mapeia a arquitetura e grava architecture.md + coverage-ledger.json (o "livro-razão" do que foi olhado).
Caça guiada por cobertura — despacha "hunters" (sub-agentes) por classe de ataque: web/protocolos, cliente, supply chain, cloud, RPC, exaustão de recursos, isolamento de dados, LLMs, memória, desktop/mobile… Cada checagem entra no ledger, inclusive o que não foi coberto.
Validação de candidatos — um verificador novo, sem contexto do hunter, tenta derrubar cada achado. Isso é o que corta falso positivo.
Saída estruturada — cada veredito vai pro findings.json, validado contra um schema.
Verificação independente do registro — confere as afirmações do JSON contra o código; mudou algo material, re-verifica.
Relatório neutro — gera REPORT.md, FINDINGS-DETAIL.md e NEEDS-VALIDATION.md.

Auditoria completa de um monorepo médio leva dezenas de minutos e consome bastante contexto (vários sub-agentes). Deixe rodar. Pra iteração rápida, use o prompt de pasta (./src).

Passo 4 — Ler o relatório sem pânico

Abra REPORT.md primeiro. Cada achado tem um de três vereditos:

Veredito	Significa	O que fazer
`confirmed`	Rastro completo no código, resultado delimitado	Corrigir. É real.
`needs_validation`	Faltou um fato pra fechar (ex.: config de produção)	Você responde a pergunta e re-roda só esse item
`rejected`	Candidato derrubado na validação	Ignorar — está lá por transparência

Exemplo real do que a skill devolveu num app nosso (resumido):

Confirmed

Header confiável para identidade do ator

Local: apps/api/src/routes/arsenal/index.ts
Um endpoint público lia x-caller-profile-id do request para atribuir autoria. Um cliente externo autenticado poderia se passar por outro perfil.
Correção: derivar o ator só da sessão autenticada.

Needs validation

Rate limit por chave de API

O plugin está habilitado, mas a implementação depende de comparação = NULL que o banco não resolve. Confirmar em staging.

Não peça pro agente "corrigir tudo" de uma vez. Corrija um confirmed por commit, rode os testes, e re-rode a auditoria na pasta afetada. Segurança é iteração, não big bang.

Passo 5 — Transformar em rotina

Antes de cada deploy grande: find security vulnerabilities in ./apps/api.
Depois de adicionar autenticação, pagamento ou upload: auditoria completa.
Guarde os relatórios (./audits/AAAA-MM/) — comparar dois findings.json mostra se você está melhorando.

Re-auditoria focada após um fix

Re-execute a auditoria de segurança só em apps/api/src/routes/auth. Compare com ./audits/2026-09/findings.json e liste o que fechou e o que abriu.

Erros comuns

"A skill não ativou" — o agente precisa suportar skills. Confirme com o comando explícito (/security-audit no Claude Code) em vez de depender do gatilho automático.
Rodou em produção — nunca. Clone local, .env de desenvolvimento, banco descartável.
Tratou needs_validation como bug — não é. É pergunta aberta. Responda ou descarte com justificativa.
Ignorou o coverage-ledger.json — ele lista o que não foi auditado. Buraco de cobertura é achado também.

O que fazer nos próximos 30 minutos

A skill acha; quem corrige é você (com o agente). Não feche esta página sem fechar o primeiro ciclo — ele é curto de propósito:

Instale a skill — um git clone na pasta de skills do seu agente.
Rode na pasta mais perigosa do seu app: a que tem login, pagamento ou upload. Não é o projeto inteiro. É uma pasta.
Abra o REPORT.md e escolha UM confirmed. O primeiro da lista serve.
Corrija só esse, rode os testes, faça o commit.
Re-rode a auditoria naquela pasta e veja o achado sumir.

Cinco passos, um problema real a menos no seu app. É assim que segurança deixa de ser "um dia eu olho" e vira rotina.

Guarde o REPORT.md desse primeiro ciclo. Daqui a um mês, rodar de novo e comparar os dois é o jeito mais honesto de ver que você evoluiu como dev — não é sensação, é diff.

E quando o relatório apontar pro seu login — vai apontar, é onde mais aparece confirmed em app de vibe coder —, volte aqui no arsenal: é o próximo terreno que a gente vai cobrir em detalhe.