# Agentes e skills para segurança e auditoria de código

Auditar código, encontrar vulnerabilidades e travar segredos antes do commit.

Segurança aplicacional raramente falha por falta de conhecimento, falha por falta de tempo. Uma chave de API que ficou num ficheiro de configuração, um endpoint que confia no identificador enviado pelo cliente, uma dependência transitiva com um CVE aberto há meses. Nada disto aparece nos testes e nada disto quebra o build. Costuma aparecer quando alguém de fora repara antes da equipa.

Os componentes desta página põem essa verificação dentro do fluxo de trabalho normal. Há agentes que reveem um diff à procura de falhas de autenticação, injeção e exposição de dados, comandos que varrem o repositório inteiro à procura de segredos ou de dependências vulneráveis, e uma automação que corre ferramentas de análise estática sempre que um ficheiro é gravado. O resultado é uma lista de problemas concretos, com ficheiro, linha e correção sugerida.

Comece pelo que dói mais no seu projeto. Se nunca fez uma auditoria, um agente generalista dá o retrato inicial. Se já tem revisão de código a funcionar, acrescente primeiro a deteção de segredos e a auditoria de dependências, que são as falhas mais baratas de corrigir. As skills de modelação de ameaças e de conformidade servem para trabalho planeado: use-as quando desenhar uma funcionalidade sensível ou preparar uma auditoria externa.


## Auditoria geral e revisão de código

O primeiro retrato do estado de segurança de um projeto e a revisão recorrente de cada alteração. É por aqui que se começa quando ainda não existe processo definido.

- **security-auditor** (Agentes): Ponto de partida quando ainda não existe processo de segurança: percorre controlos, configurações e código, e devolve lacunas priorizadas com evidência em vez de uma lista genérica. [ficha](https://doutorai.pt/componentes/agents__security-auditor)
- **se-security-reviewer** (Agentes): Revisão focada num diff ou num módulo, com o plano ajustado ao tipo de código: OWASP Top 10 para APIs web, OWASP LLM Top 10 quando existe integração com modelos de linguagem. [ficha](https://doutorai.pt/componentes/agents__se-security-reviewer)
- **read-only-auditor** (Agentes): Os hooks declarados no frontmatter bloqueiam Write, Edit e Bash durante toda a auditoria, o que os torna adequados a revisões pré-merge ou de conformidade onde nada pode ser alterado. [ficha](https://doutorai.pt/componentes/agents__read-only-auditor)
- **security-review** (Skills): Checklist que se ativa enquanto escreve a funcionalidade e não depois: autenticação, entrada do utilizador, novos endpoints, pagamentos e tudo o que mexa em segredos. [ficha](https://doutorai.pt/componentes/skills__security-review)
- **vulnerability-scanner** (Skills): Para quem precisa de mapear a superfície de ataque e ordenar o que corrigir primeiro, com princípios OWASP atualizados e um script de validação que corre sobre o projeto. [ficha](https://doutorai.pt/componentes/skills__vulnerability-scanner)

## APIs, base de dados e integrações

Cada camada tem falhas próprias. Estes componentes conhecem os padrões de ataque específicos de cada uma, em vez de aplicarem a mesma checklist a tudo.

- **api-security-audit** (Agentes): Especializado em APIs REST: tokens JWT mal validados, escalonamento de privilégios no controlo de acessos e injeção em SQL, NoSQL ou comandos do sistema. [ficha](https://doutorai.pt/componentes/agents__api-security-audit)
- **api-security-best-practices** (Skills): Serve na fase de desenho, antes de existir código para auditar: padrões de autenticação, autorização, validação de entrada e limitação de pedidos para REST, GraphQL e WebSocket. [ficha](https://doutorai.pt/componentes/skills__api-security-best-practices)
- **graphql-security-specialist** (Agentes): GraphQL levanta problemas que não existem em REST, como consultas aninhadas sem limite. Trata a validação de consultas e a autorização ao nível dos resolvers. [ficha](https://doutorai.pt/componentes/agents__graphql-security-specialist)
- **supabase-security-audit** (Comandos): Quando o projeto assenta em Supabase, o risco real está nas políticas de Row Level Security e nas chaves expostas ao cliente. É exatamente isso que este comando revê. [ficha](https://doutorai.pt/componentes/commands__supabase-security-audit)
- **mcp-security-auditor** (Agentes): Para quem publica servidores MCP: revê a implementação de OAuth, o desenho de permissões por papel e os pontos onde o servidor expõe mais do que devia. [ficha](https://doutorai.pt/componentes/agents__mcp-security-auditor)

## Segredos, dependências e cadeia de fornecimento

Boa parte das falhas não está na lógica que escreveu, está no que trouxe de fora ou no que ficou esquecido no repositório. São também as mais rápidas de corrigir.

- **security-scanner** (Automações): Automação que corre a seguir a cada Edit ou Write. Se tiver semgrep, bandit ou gitleaks instalados, o aviso aparece no momento em que o ficheiro é gravado. [ficha](https://doutorai.pt/componentes/hooks__security-scanner)
- **secrets-scanner** (Comandos): Varrimento pontual do repositório à procura de chaves de API, palavras-passe e certificados, incluindo commits antigos cuja mensagem sugere que mexeram em credenciais. [ficha](https://doutorai.pt/componentes/commands__secrets-scanner)
- **dependency-audit** (Comandos): Chama o auditor nativo do ecossistema (npm, pip, cargo) e cruza numa só passagem vulnerabilidades conhecidas, pacotes desatualizados e questões de licenciamento. [ficha](https://doutorai.pt/componentes/commands__dependency-audit)
- **supply-chain-security** (Agentes): Vai além da lista de CVE: deteta typosquatting, confusão de dependências e protestware, e gera SBOM em SPDX ou CycloneDX para quem tem de entregar esse documento. [ficha](https://doutorai.pt/componentes/agents__supply-chain-security)
- **supply-chain-guard** (Skills): Parte de indicadores de ataques reais em npm, PyPI, crates.io e GitHub Actions, o que ajuda quando existe suspeita concreta sobre um pacote comprometido. [ficha](https://doutorai.pt/componentes/skills__supply-chain-guard)
- **secrets-management** (Skills): Encontrar os segredos é metade do trabalho, guardá-los é a outra: cobre Vault, AWS Secrets Manager, rotação automática e privilégio mínimo em pipelines de CI/CD. [ficha](https://doutorai.pt/componentes/skills__secrets-management)

## Ameaças, endurecimento e conformidade

Trabalho planeado em vez de reativo: perceber o que pode correr mal antes de escrever o código e conseguir provar depois que os controlos existem.

- **security-threat-model** (Skills): Produz um modelo de ameaças ancorado no repositório real, com fronteiras de confiança, ativos, capacidades do atacante e caminhos de abuso, em vez de um documento genérico. [ficha](https://doutorai.pt/componentes/skills__security-threat-model)
- **threat-modeling-expert** (Skills): A metodologia por trás do exercício: STRIDE, PASTA e árvores de ataque, útil quando a revisão é de arquitetura e ainda não existe código para analisar. [ficha](https://doutorai.pt/componentes/skills__threat-modeling-expert)
- **security-hardening** (Comandos): Depois de saber o que falta, aplica controlos concretos: cabeçalhos HTTP, configuração de autenticação, cifra e definições ao nível da infraestrutura. [ficha](https://doutorai.pt/componentes/commands__security-hardening)
- **gdpr-dsgvo-expert** (Skills): Indicado para produtos com utilizadores na União Europeia, com avaliações de impacto sobre a proteção de dados e verificação de conformidade com o RGPD. [ficha](https://doutorai.pt/componentes/skills__gdpr-dsgvo-expert)
- **compliance-specialist** (Agentes): Quando um cliente pede evidência de SOC 2, PCI DSS ou ISO, ajuda na preparação da auditoria: recolha de evidência, políticas de segurança e avaliação de risco. [ficha](https://doutorai.pt/componentes/agents__compliance-specialist)

## Onde colocar cada componente no projeto

Os agentes desta página são ficheiros Markdown que vivem em .claude/agents/ dentro do repositório, ou em ~/.claude/agents/ se quiser tê-los em todos os projetos. As skills vão para .claude/skills/, cada uma na sua pasta, e o Claude Code carrega-as quando o pedido corresponde à descrição. Os comandos ficam em .claude/commands/ e passam a estar disponíveis como atalho com o nome do ficheiro. A automação de análise estática é diferente: é um bloco de configuração que se acrescenta ao settings.json, na secção de hooks PostToolUse. Guarde tudo no controlo de versões, para que a equipa inteira tenha os mesmos controlos e para que uma alteração às regras fique registada.

## Combinar os três tempos da revisão

Estes componentes funcionam melhor em camadas, cada uma com a sua cadência. A automação de análise estática corre a cada gravação de ficheiro e apanha o erro óbvio enquanto ainda está fresco. Os comandos de varrimento de segredos e de auditoria de dependências correm uma vez por semana ou antes de cada release, porque analisam o repositório todo e demoram mais. Os agentes de revisão entram antes de fundir uma alteração que toque em autenticação, pagamentos, uploads ou consultas à base de dados. A modelação de ameaças fica fora deste ciclo: faz-se no início de uma funcionalidade sensível e revisita-se quando a arquitetura muda.

## O que estas ferramentas não resolvem

Vale a pena ser claro sobre os limites. Vários destes componentes dependem de ferramentas externas instaladas na máquina, como semgrep, bandit, gitleaks ou o auditor do gestor de pacotes. Sem elas, a análise reduz-se ao que o modelo consegue ler no código. Uma revisão assistida por modelo também produz falsos positivos e pode não ver uma falha de lógica de negócio que só faz sentido para quem conhece o produto. Nada disto substitui um teste de intrusão autorizado nem uma auditoria independente quando existe obrigação contratual ou regulatória. Trate os resultados como uma lista de pistas a confirmar, não como um certificado.

## Perguntas frequentes

### Preciso de instalar ferramentas externas para isto funcionar?

Depende do componente. Os agentes e as skills trabalham a partir da leitura do código e funcionam sem instalação adicional. Já a automação de análise estática invoca semgrep, bandit e gitleaks, e a auditoria de dependências chama npm audit, pip ou cargo audit. Se essas ferramentas não existirem na máquina, os comandos seguem em frente sem erro, mas a cobertura fica bastante menor.

### Se só puder adotar um componente, qual escolho?

Para a maioria dos projetos, o varrimento de segredos. Uma chave de API deixada num commit é a falha mais frequente, a mais fácil de explorar e a mais rápida de corrigir. Logo a seguir vem a auditoria de dependências, porque expõe risco herdado sem exigir alterações ao seu código. A revisão de código completa faz mais sentido depois de estas duas estarem resolvidas.

### Isto substitui um teste de intrusão ou uma auditoria externa?

Não. Estes componentes fazem análise defensiva sobre código e configuração a que já tem acesso, o que apanha uma parte grande dos problemas mas não valida se uma falha é realmente explorável em produção. Se tiver obrigações contratuais, de certificação ou de setor regulado, continua a precisar de um teste autorizado feito por terceiros.

### Posso correr uma auditoria sem risco de alterar o código do cliente?

Sim. O agente de auditoria só de leitura bloqueia as ferramentas Write, Edit e Bash através de hooks declarados no seu próprio frontmatter, ou seja, a restrição é aplicada pelo Claude Code e não depende de o modelo se lembrar dela. É a opção indicada para revisões pré-merge e para trabalho em repositórios de terceiros.

### Algum destes componentes ajuda no RGPD?

A skill de RGPD e DSGVO cobre avaliações de impacto sobre a proteção de dados e verificação de conformidade, e o agente de conformidade ajuda a preparar auditorias em enquadramentos como SOC 2, PCI DSS e ISO. São apoio à documentação e à identificação de lacunas. A decisão jurídica final continua a pertencer ao responsável pela proteção de dados.


Fonte: https://doutorai.pt/para/seguranca-e-auditoria - Doutor AI, selecao feita a mao da biblioteca tecnica.