Playbook de Segurança para Agentes

Um playbook de segurança open-source para agentes de IA. Procedimentos estruturados e fundamentados na OWASP que capacitam agentes a executar tarefas de engenharia de segurança — da revisão de código às auditorias de segurança de agentes de IA.

Índice

• Por que usar?
• O que é isso?
• Início Rápido
• Catálogo de Skills
• Agentes
• Exemplo de Saída
• Plays
• Arquitetura
• Fundação OWASP
• Projetos Relacionados
• Contribuindo

Por que usar?

Sem um playbook, pedir a um agente de IA para "revisar meu código em busca de problemas de segurança" entrega uma checklist superficial. Com estes plays, o agente segue um procedimento estruturado e fundamentado na OWASP — testando sistematicamente cada classe de vulnerabilidade e produzindo achados com mapeamentos CWE, referências cruzadas ao OpenCRE, trechos de evidência e código de remediação específico.

• Metodologia consistente — Toda avaliação segue um procedimento documentado, e não prompts ad-hoc. Os resultados são reproduzíveis entre execuções e revisores.
• Saída estruturada e acionável — Os achados incluem severidade, CWE, evidência e etapas de remediação com exemplos de código. Sem alertas vagos.
• Rastreabilidade entre padrões — Os achados vinculam-se a CWE, ASVS, WSTG e NIST 800-53 via OpenCRE para mapeamento de conformidade.
• 17 skills de segurança — Da varredura de CVEs em dependências ao teste de injeção de prompt e à modelagem de ameaças multiagente. Instale como plugin do Claude Code ou use de forma independente.
• Funciona além do Claude Code — As skills são plugins do Claude Code; os plays são procedimentos autônomos que qualquer agente de IA pode seguir.

O que é isso?

Isto não é um framework nem uma biblioteca. Não há código para importar.

Cada play é um procedimento de segurança passo a passo com checklists, critérios de decisão e modelos de saída. Um agente de IA segue o procedimento para produzir achados consistentes e baseados em evidências. Pense nele como o playbook de um analista de SOC — mas escrito para agentes de IA executarem.

Início Rápido

Com Claude Code (recomendado):

Passo 1 — Registre o marketplace de plugins:

/plugin marketplace add OWASP/secure-agent-playbook

Passo 2 — Instale um conjunto de skills:

/plugin install code-security-skills@agent-security-playbook
/plugin install ai-security-skills@agent-security-playbook

Passo 3 — Use as skills mencionando a tarefa na conversa:

"Review this code for security issues"
"Scan my dependencies for CVEs"
"Audit this MCP server configuration"
"Test this chatbot for prompt injection"

O Claude ativará automaticamente a skill relevante com base no contexto. Consulte o Catálogo de Skills para ver todas as skills disponíveis e o Exemplo de Saída para ver como são os resultados.

Plugin de organização — Para administradores de organizações Claude que instalam via Organization Plugins:

1. Acesse o último release
2. Baixe o secure-agent-playbook.zip dos assets do release
3. Envie o zip em Configurações da organização > Plugins > Adicionar plugin

Nota: Não use o botão "Download ZIP" do GitHub — ele aninha os arquivos em um subdiretório que o validador de plugins rejeita. Use sempre o zip dos assets do release.

Desenvolvimento local — Para testar a partir de um clone local em vez do GitHub:

/plugin marketplace add /path/to/agent-security-playbook
/plugin install code-security-skills@agent-security-playbook
/plugin install ai-security-skills@agent-security-playbook

Sem Claude Code:

Consulte os plays diretamente como procedimentos para qualquer agente de IA ou uso manual:

• Aponte seu agente para um play: "Siga o procedimento em plugins/ai-security-skills/plays/agent-security-audit.md"
• Ou use os plays como checklists para revisões de segurança manuais

Catálogo de Skills

Segurança de Código e Infraestrutura (code-security-skills)

Segurança de IA e Agentes (ai-security-skills)

Agentes

Os agentes são especialistas de segurança autônomos que invocam skills e produzem relatórios estruturados. Cada agente tem um system prompt focado, acesso a ferramentas com escopo definido e skills pré-carregadas. Use-os individualmente ou como uma equipe coordenada.

Uso independente — invoque qualquer agente diretamente:

"Use code-security-reviewer to review src/"
"Use dependency-auditor to scan this project"

Avaliação em equipe — com agent teams habilitados, o líder da equipe despacha especialistas em paralelo e consolida os achados em um único relatório:

"Run a full security assessment of this project"

O líder da equipe define o escopo do alvo, despacha os especialistas relevantes (pulando aqueles cuja área de foco não está presente), elimina achados duplicados, identifica cadeias de risco entre domínios e produz um relatório unificado usando templates/report.md.

O recurso agent teams requer CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Consulte a documentação do Claude Code para configuração. Agentes individuais funcionam sem esta flag.

Exemplo de Saída

Executar "Review src/auth/ for security issues" em uma base de código Node.js/Express produz achados como estes:

Security Code Review — src/auth/
Scope: Node.js/Express, server-side, processes user credentials
Findings: CRITICAL 1 | HIGH 2 | MEDIUM 1 | LOW 0

[CRITICAL] Injeção de SQL na Consulta de Usuário

• CWE: CWE-89
• OpenCRE: CRE-764-507 — Prevenção de Injeção
• Ref. OWASP: A03:2021 Injection
• Local: src/auth/login.js:42
• Impacto: O atacante pode extrair toda a tabela de usuários, contornar a autenticação ou executar SQL arbitrário por meio do parâmetro id manipulado
• Evidência:
  root@kitploit:~

  // src/auth/login.js:42
  const user = await db.query("SELECT * FROM users WHERE id=" + req.params.id);
  

• Remediação: Use consultas parametrizadas:
  root@kitploit:~

  const user = await db.query("SELECT * FROM users WHERE id = $1", [req.params.id]);
  

• Confiança: ALTA

Cada skill produz achados estruturados com severidade, CWE, evidência e código de remediação. Consulte examples/ para ver exemplos completos de relatórios de avaliação.

Plays

Plays de Segurança de IA/Agentes

O diferencial — procedimentos de segurança construídos especificamente para a era dos agentes de IA. Inclusos no plugin ai-security-skills.

Plays de Análise de Código e Dependências

Valor prático imediato para qualquer base de código. Inclusos no plugin code-security-skills.

Planejados

• Tier 2: Modelagem de ameaças, verificação ASVS, endurecimento de infraestrutura
• Tier 3: Checklist de testes WSTG, orquestração de DAST, mapeamento de superfície de ataque
• Tier 5: Avaliação de maturidade SAMM, mapeamento de conformidade, relatórios agregados

Arquitetura

Design em três camadas — cada camada vive dentro da pasta de origem do plugin, de modo que a instalação via marketplace empacota tudo o que as skills precisam:

• plugins/<name>/agents/ — Especialistas de segurança autônomos com system prompts focados, localizados dentro de cada plugin. Cada agente invoca uma ou mais skills, opera em um contexto isolado e produz relatórios estruturados. Pode trabalhar sozinho ou como uma equipe coordenada.
• plugins/<name>/skills/ — Arquivos SKILL.md autocontidos que seguem a especificação Agent Skills. Distribuídos por meio de plugins/code-security-skills/ e plugins/ai-security-skills/, registrados no marketplace via .claude-plugin/marketplace.json. Cada skill resume um procedimento e referencia seu play correspondente dentro do mesmo plugin.
• plugins/<name>/plays/ — Procedimentos de referência completos com checklists detalhados, tabelas, critérios de decisão e exemplos. As skills referenciam estes arquivos para uma cobertura abrangente.
• plugins/<name>/templates/ e plugins/<name>/data/ — Modelos de saída (finding.md, ) e conjuntos de dados de referência da OWASP (FIASSE v1.0.4, ASVS v5.0, prompts de código seguro) que as skills carregam em tempo de execução.

Os agentes orquestram, as skills executam e os plays fornecem o procedimento completo. Contribuidores editam os plays. Isso significa que o playbook funciona com qualquer agente de IA (basta apontá-lo para um play), enquanto os usuários do Claude Code obtêm instalação baseada em plugins com agentes e skills.

Fundação OWASP

Todos os plays referenciam padrões e conjuntos de dados da OWASP:

• OWASP Top 10 — Riscos de aplicações web
• OWASP API Security Top 10 — Riscos específicos de APIs
• OWASP Top 10 for LLM Applications — Riscos de IA/LLM
• OWASP Agentic Security Initiative — Riscos de agentes autônomos (Top 10 para Aplicações Agênticas)
• OWASP ASVS — Requisitos de verificação de segurança
• OWASP MASVS — Padrão de Verificação de Segurança de Aplicações Móveis
• OWASP AISVS — Padrão de Verificação de Segurança de IA
• OWASP WSTG — Metodologia de testes
• OWASP SAMM — Modelo de maturidade de programas de segurança
• OWASP Cheat Sheet Series — Orientação de segurança para desenvolvedores
• OWASP FIASSE — Framework para Engenharia Inerentemente Adaptativa e Segurável (v1.0.4)

Projetos Relacionados

Contribuindo

Consulte CONTRIBUTING.md para diretrizes detalhadas.

Novos plays devem:

• Resolver uma tarefa de segurança bem definida
• Incluir condições de acionamento claras (quando este play deve ser executado?)
• Seguir um procedimento estruturado com checkpoints
• Produzir achados usando o formato templates/finding.md do próprio plugin
• Referenciar padrões OWASP quando aplicável
• Preferir ferramentas existentes (semgrep, trivy, osv-scanner, trufflehog) em vez de reimplementar a detecção
• Estar na pasta plays/ do plugin apropriado para serem distribuídos com a instalação do marketplace

Licença

Licenciado sob Creative Commons Attribution 4.0 International (CC-BY-4.0). Consulte THIRD_PARTY_NOTICES.md para a atribuição de conteúdo upstream de projetos OWASP.