Uma equipa de hackers contra a tua app

O que é e porque importa

Antes de lançar uma app feita com IA, a pergunta é sempre a mesma: há um buraco que eu não vejo? Tu usas a app por dentro, com a tua conta, e funciona. Quem a quer partir olha para ela de fora.

O Claude Security é um plugin oficial do Claude Code, e não é uma verificação única: é uma equipa de agentes. Um desenha o mapa da tua arquitetura, outro constrói o modelo de ameaças, ou seja, quem atacaria a tua app, por onde e para levar o quê, e outros procuram vulnerabilidades. Cada falha encontrada é analisada por agentes verificadores independentes antes de entrar no relatório, por isso o relatório fica curto e sem falsos alarmes. No fim prepara as correções como patches, e és tu que as aplicas.

Os hackers são falsos no bom sentido: o plugin lê o teu código, na tua sessão, e não ataca a app online nem a base de dados verdadeira. Serve para quem está prestes a lançar uma app com dados de pessoas.

O estado, verificado na documentação oficial do Claude Code a 22 de outubro de 2026: a página do plugin não o apresenta como pré-visualização nem como beta, e instala-se a partir do marketplace oficial da Anthropic. Não o confundas com o serviço gerido com o mesmo nome que vigia os repositórios em contínuo: esse é um produto à parte, para o plano Enterprise.

1. O que precisas

• Um plano pago do Claude, a API da Anthropic ou um fornecedor como Amazon Bedrock, Google Cloud ou Microsoft Foundry. A análise usa os workflows dinâmicos do Claude Code, um script que coordena muitos agentes ao mesmo tempo. No plano Pro ligas-os no /config, na linha Dynamic workflows.
• Python 3 acessível como python3 (experimenta python3 --version). O plugin usa só a biblioteca padrão, não instala nada, e se a tua versão for demasiado antiga o menu dele avisa-te.
• Git, para analisar só as alterações e para os patches. A análise completa funciona também sem ele. Serve Mac, Linux ou Windows.

Não há uma chave à parte: o plugin não chama modelos por conta própria, usa a tua sessão, e os agentes correm no modelo que escolheste com /model. Cada análise conta no teu consumo, pode usar muitos tokens e precisa do Claude Code aberto até terminar.

2. Instala o plugin

Na pasta do projeto, inicia o Claude Code com claude e escreve:

/plugin install claude-security@claude-plugins-official

Abre-se a ficha do plugin, onde escolhes para quem o instalar: para ti em todos os projetos, para todos os do repositório ou só para ti neste repositório. Se o resumo disser «Run /reload-plugins to apply.», escreve /reload-plugins. Se, pelo contrário, disser que o plugin não está no marketplace, atualiza o catálogo com /plugin marketplace update claude-plugins-official e tenta de novo.

3. Lança a análise

1. Escreve /claude-security e escolhe Scan codebase.
2. O plugin lê o repositório e propõe-te tudo ou uma parte, por exemplo a API ou o login, com o número de ficheiros e o custo relativo de cada opção. Se não souberes, responde «I don't know» e ele escolhe.
3. Confirma: antes disso não arranca nada. Depois deixa o Claude Code aberto. O detalhe, agente a agente e com os tokens de cada um, vês com /workflows, e a partir daí também podes parar tudo.

Funciona melhor no modo auto, onde um segundo modelo revê as ações no teu lugar e os agentes não te pedem autorização a cada passo. Num projeto grande vai zona a zona: login, pagamentos, API.

Só as alterações, antes de juntar

Se trabalhas num ramo, o menu propõe-te analisar só o que mudou em relação à base; também podes pedir um único commit ou um pull request teu que esteja aberto. Só conta o que já está num commit. Também se pode pedir por palavras:

/claude-security analisa só as alterações do meu ramo

4. Lê o relatório

Cada análise escreve no repositório uma pasta CLAUDE-SECURITY-<data e hora>. É a única coisa que muda no projeto, e tem o seu próprio .gitignore, para não acabar num commit por engano. Lá dentro:

• CLAUDE-SECURITY-RESULTS.md, o relatório para ler: cada falha tem um código (F1, F2…), o impacto, um cenário de ataque, a gravidade, o grau de confiança e o que fazer.
• As mesmas falhas em .jsonl para programas e em .sarif, o formato padrão que o GitHub code scanning e outras ferramentas de segurança leem, com a categoria CWE de cada falha.
• Um carimbo, CLAUDE-SECURITY-REVISION-<commit>.json, que diz que commit foi analisado e com que esforço, para que cada relatório fique ligado ao código que descreve.

Começa pelas falhas mais graves e com confiança alta, e antes de corrigir pede que te expliquem o cenário:

Abre o relatório do Claude Security e explica-me a falha F1 como se eu não soubesse nada de segurança: quem a pode explorar, o que consegue, por que ecrã ou endereço da app passa e qual é a probabilidade. Diz-me se toca em dados de utilizadores reais. Não alteres nada.

5. As correções aplicas tu

Escreve outra vez /claude-security, escolhe Suggest patches e depois as falhas. Cada patch nasce numa cópia à parte do repositório e é revisto por outro agente, que corre os testes, se existirem. Só chega se fechar essa falha, não abrir outras e não mudar mais nada; se não, recebes uma nota a explicar porquê.

Os patches vão para patches/ dentro do relatório, um por falha (F1.patch, F2.patch…), e nunca são aplicados sozinhos. Aplicas um a partir do terminal assim:

git apply CLAUDE-SECURITY-<timestamp>/patches/F1.patch

Um patch por pull request, para que cada um seja revisto e testado sozinho. Ou pede ao Claude:

Aplica o patch F1 do relatório do Claude Security num ramo novo, corre os testes e abre um pull request só com essa alteração. Na descrição escreve a falha, a correção e como a testaste.

Se o código alterado não tiver testes, a nota do patch diz isso: verifica-o à mão antes de juntar. E se esse código mudou entretanto, a falha é saltada e o plugin propõe-te uma análise nova.

6. Os quatro buracos típicos das apps feitas com IA

• A base de dados aberta. O Supabase quer Row Level Security em cada tabela exposta: sem ela, a chave pública que está na app pode bastar para ler e escrever. No Firebase procura allow read, write: if true, que a documentação diz para nunca usar em produção. O teste ao vivo: guia PORTA (strikt.fit/porta).
• A chave secreta no código da app. A do Supabase (secret, ou service_role) nunca no browser, numa app publicada ou no GitHub. E as variáveis VITE_, NEXT_PUBLIC_ e EXPO_PUBLIC_ acabam no código que chega ao browser ou à app: nada de chaves aí. Guia CHIAVI (strikt.fit/chiavi).
• O endpoint que não verifica quem pede. Um endpoint é um endereço do servidor, como /api/encomendas/123. O caso clássico: verifica o login, mas não que a encomenda 123 é tua, e então mudas o número e lês a de outra pessoa. É o primeiro risco do OWASP API Security Top 10 de 2023. A verificação faz-se no servidor, não num botão escondido.
• Nenhum limite de pedidos. Se um endpoint chama uma IA ou envia emails ou SMS, qualquer pessoa o chama mil vezes e a conta chega a ti: é o quarto risco da mesma lista. Guia LIMITE (strikt.fit/limite).

Para uma primeira olhadela rápida, antes da análise a sério:

Verifica no código desta app os quatro buracos clássicos das apps feitas com IA e, para cada um, diz-me ficheiro, linha e gravidade: 1) tabelas da base de dados sem regras de acesso (Row Level Security no Supabase, regras de segurança no Firebase) ou com regras que deixam qualquer pessoa com login ler tudo; 2) chaves secretas no código que chega ao browser ou à app, incluindo as variáveis NEXT_PUBLIC_, VITE_ e EXPO_PUBLIC_; 3) endpoints que não verificam quem faz o pedido e se o objeto pedido é seu; 4) endpoints sem limite de pedidos, sobretudo os que custam dinheiro (IA, email, SMS). Não alteres nada e nunca mostres o valor das chaves.

É uma só passagem, sem os verificadores do plugin. E as regras da base de dados criadas no painel, e não no código, nem esta verificação nem o plugin as veem: para essas precisas do teste ao vivo.

Os erros mais comuns

• Começar com um repositório grande inteiro. Da primeira vez escolhe uma zona, como o login ou a API, e vê quanto consome em /workflows.
• Pedir a análise das alterações com o trabalho ainda sem commit. Essa só olha para os commits.
• Aplicar todos os patches de uma vez. Um por pull request, cada um revisto e testado.
• Tomar uma análise limpa por uma app segura. As análises mudam de uma execução para outra e leem o código, não as definições online: repete-as e faz também os testes ao vivo.
• Tirar do código uma chave secreta encontrada e ficar por aí. Tem de ser revogada e substituída, porque fica no histórico.

Checklist

• Plano pago ou API, workflows dinâmicos ligados (no Pro, a partir do /config).
• python3 e git a funcionar, plugin instalado.
• Primeira análise numa zona com dados de pessoas: login, pagamentos, API.
• Relatório lido a começar pelas falhas mais graves.
• Patches aplicados um por pull request, os que não têm testes verificados à mão.
• Os quatro buracos típicos verificados também ao vivo.
• Análise repetida antes de cada lançamento importante.

Perguntas frequentes