Crie um agente scanner de segurança OWASP com o Claude Code

Auditoria de segurança não é um interesse paralelo para mim. Eu fundei a xCyberSecurity, e auditorias no estilo OWASP de apps Laravel, sites WordPress e contas AWS são trabalho faturável que faço há anos. O agente deste post é esse fluxo de trabalho codificado no Claude Code, e a tese de todo este texto é esta: um scanner de segurança com IA vive ou morre pela arquitetura, não pelo prompt. Mais especificamente, você precisa separar a metodologia (uma skill) da execução (sub-agents com contexto limpo), porque a qualidade da auditoria se degrada na proporção exata de quão cheia está a janela de contexto quando o auditor chega ao seu código.

Por que um único prompt gigante de "escaneie meu repo" falha

A versão ingênua é uma sessão, uma instrução: audite este codebase contra o OWASP Top 10. O padrão de falha é previsível: as primeiras categorias recebem uma análise cuidadosa, mas, à medida que o contexto se enche com o conteúdo de arquivos das passadas anteriores, o modelo começa a passar os olhos pelas últimas. O formato do relatório também varia entre execuções, o que importa mais do que as pessoas pensam: uma auditoria que você não consegue comparar (diff) com a auditoria do mês passado é algo pontual, não um processo de segurança.

Auditores humanos têm o mesmo modo de falha, e é por isso que empresas de auditoria de verdade usam checklists e revisores novos para cada domínio. A correção corresponde um para um.

A arquitetura: uma skill para as regras, sub-agents para a leitura

A skill é a metodologia do auditor sênior, escrita uma única vez. A minha contém quatro seções:

1. Escopo e mapeamento de categorias. O OWASP Top 10 mapeado para o que cada categoria significa concretamente nas stacks que eu audito. Categorias abstratas produzem achados abstratos; a skill faz a tradução.
2. Uma rubrica de severidade. Crítica, alta, média, baixa, com definições ligadas à explorabilidade e ao raio de impacto, para que a severidade seja atribuída por regra e não por feeling. Esta é a seção pela qual os clientes realmente pagam, e foi a que exigiu mais iterações.
3. Um formato de relatório fixo. Achado, arquivo e linha, categoria, severidade, trecho de evidência, remediação, confiança. Em toda execução, o mesmo formato, para que as execuções sejam comparáveis ao longo do tempo.
4. Regras rígidas. Somente leitura, sempre: o scanner nunca edita código. Reportar tudo, inclusive achados de baixa confiança, marcados como tal, porque uma etapa de triagem posterior consegue filtrar ruído, mas não consegue recuperar um achado que nunca foi reportado. Nunca reproduzir segredos descobertos no corpo do relatório; referenciar apenas a localização deles.

Os sub-agents são para onde vai o orçamento de tokens. A sessão orquestradora despacha um sub-agent por categoria (ou por módulo, em codebases grandes), cada um com um contexto limpo que lê os arquivos relevantes a fundo e devolve apenas achados estruturados. O orquestrador nunca vê o conteúdo bruto dos arquivos, apenas os achados, que ele mescla, deduplica e ranqueia. É o mesmo padrão de contexto limpo que torna sistemas de agentes viáveis financeiramente em geral, aplicado a um domínio em que a leitura superficial não é um problema de custo, mas um problema de correção.

O que a skill verifica, porque eu verifico manualmente

O valor de codificar o seu próprio fluxo de trabalho, em vez de baixar o prompt de segurança genérico de outra pessoa, é que as verificações carregam o histórico dos seus trabalhos. As minhas incluem:

• Laravel: mass assignment via $fillable permissivo demais ou $guarded = [], DB::select bruto com strings interpoladas, ausência de autorização no route model binding (o clássico IDOR), APP_DEBUG=true em configurações de produção, validação morando nos controllers em vez de Form Requests, onde ela acaba sendo pulada pelo próximo endpoint, e queue jobs que confiam nos próprios payloads.
• WordPress: verificações de nonce ausentes em ações que alteram estado, verificações de capability confundidas com verificações de autenticação, acesso direto a arquivos sem guards de ABSPATH e $wpdb->query com input não preparado em plugins customizados, que é onde sites de clientes realmente são invadidos.
• AWS IAM: ações curinga em recursos curinga, usuários com senha de console e sem MFA, e access keys mais antigas do que o desenvolvedor que as criou.

Nada nessa lista é exótico. Esse é o ponto. Auditorias falham por cobertura e consistência, não por falta de engenhosidade, e um agente é implacável exatamente com as coisas chatas que humanos pulam no quadragésimo arquivo.

Testando contra um app feito para falhar

Você não aponta um scanner novo para o codebase de um cliente logo de cara. Construa um app deliberadamente vulnerável como alvo de teste e plante nele os clássicos: hash de senha com MD5, SQL concatenado com strings em um endpoint de busca, um IDOR em uma rota de visualização, uma API key hardcoded em um arquivo de configuração, ausência de rate limiting no login e stack traces verbosos em modo de produção.

Detectar os problemas plantados é a condição para passar, mas os resultados informativos estão nas bordas. Fique de olho em falsos positivos de um tipo específico: código seguro, mas feio, como um input que foi validado mais acima de uma forma que o sub-agent da categoria não conseguia ver. Faça os sub-agents reportarem a suposição por trás de cada achado ("supõe que $request->input chega a esta query sem validação"), o que transforma um falso positivo de ruído em um descarte de um segundo. Depois verifique a consistência: execuções repetidas no mesmo commit devem produzir relatórios materialmente idênticos, que é a propriedade que torna o agente digno de CI.

Integrando ao fluxo de trabalho

Dois pontos de integração valem o que custam. Um scan pré-commit ou pré-merge roda com escopo no diff, apenas nas categorias relevantes para os arquivos alterados, barato o suficiente para rodar em todo PR. Um scan completo agendado roda semanalmente contra a main com a varredura completa de categorias, e o relatório dele é comparado (diff) com o da semana anterior. Achados novos devem acionar um humano; achados que desapareceram devem ser verificados como realmente corrigidos, e não ocultados por acidente. Se você roda agentes com esse nível de acesso ao repo, o lado de permissões e onboarding da segurança de agentes merece tanta atenção quanto o lado do scan; um scanner com acesso de escrita é, ele próprio, um achado.

Onde isso quebra, com honestidade

O agente não entende a sua lógica de negócio. Ele consegue ver que uma rota não tem verificação de autorização; não consegue saber que a intenção era "usuários só podem ver faturas da própria organização, a menos que sejam revendedores". Autorização de lógica de negócio continua sendo trabalho humano, informado pelo mapa do agente. Ele não testa o comportamento em runtime, então complementa, em vez de substituir, scanners de dependências e ferramentas DAST; ele lê código, e sistemas em execução se comportam mal de maneiras que a revisão de código não consegue ver. E ele não assina o relatório. Quando os achados vão para um cliente, um humano capaz de defender cada linha coloca o nome nele. O meu.

Eu também não entregaria isso a alguém que nunca auditou nada, porque a skill codifica um julgamento que você precisa ter antes de conseguir codificá-lo. Um agente como este torna as auditorias mais rápidas e mais consistentes. Ele não as torna possíveis; anos fazendo-as manualmente, sim.

Quer a auditoria, e não a construção?

Se o que você realmente precisa é auditar o seu app Laravel, site WordPress ou conta AWS, isso é literalmente o que eu faço, com este agente como primeira passada e os meus olhos como a segunda. O lado de segurança dos meus serviços cobre auditorias de código no estilo OWASP até a remediação, e todo trabalho termina com o formato de relatório comparável por diff descrito acima, em vez de um PDF de screenshots. Traga-me um codebase; eu trago o scanner e a assinatura.