trebaud/swarm-audit

Auditoria em Enxame (Swarm Audit)

Inventário → dividir em seções → uma worktree e um agente auditor por seção → cada agente reporta achados validados ao orquestrador → auditoria de encadeamento sobre todos os achados → um relatório combinado. O orquestrador é a worktree onde você inicia. Mostre ao usuário cada artefato antes de prosseguir; ele decide escopo e agrupamento.

0. Pré-voo

Antes de qualquer outra coisa, resolva três questões. Pergunte cada uma delas (que estiver em aberto) em uma única chamada AskUserQuestion (diretamente se não houver ferramenta de pergunta), então pare até o usuário responder.

Modelo de ameaça. Encontre **/THREAT_MODEL.md, ignorando diretórios de dependências vendadas ou instaladas. Se existir um sem placeholders <…> de template, use-o. Caso contrário, pergunte, a menos que o usuário já tenha solicitado uma execução rápida:

• Construir um modelo de ameaça primeiro (Recomendado): cada auditor e crítico de seção usa seus controles e lista de escopo excluído, o que reduz falsos positivos em todo o enxame e revela bugs de lógica de negócio. Custa algumas rodadas de perguntas no início; auditorias posteriores o reutilizam.
• Execução rápida sem modelo: sem perguntas e sem modelo de ameaça; auditores de seção trabalham apenas a partir do inventário e do código. A maneira mais rápida de ver o que o enxame encontra; espere mais ruído.

Em Construir, execute a skill security-audit incluída neste plugin através da ferramenta Skill no orquestrador, pedindo apenas um modelo de ameaça, e aguarde THREAT_MODEL.md antes do passo 1.

Estratégia de divisão. Se os argumentos contiverem --by-group [N] ou --by-theme, use-a. Caso contrário, pergunte:

• Por tema (Recomendado): as seções seguem o que o código faz (auth, conta, pagamentos, pedidos, admin, uma por integração de terceiros). Cada auditor vê um fluxo completo, então bugs que abrangem vários pontos de entrada são encontrados. Os tamanhos variam.
• Por grupo: grupos de tamanho fixo de aproximadamente N pontos de entrada (pergunte N, padrão 25) na ordem do código-fonte. Carga de trabalho uniforme por auditor, sem decisões subjetivas, mas um fluxo pode ser cortado entre duas seções; a auditoria de encadeamento (passo 6) recupera parte disso.

Escopo. Se o usuário não nomeou nenhum, pergunte quais serviços, diretórios ou tipos de ponto de entrada cobrir, e o que deixar de fora.

1. Inventariar os pontos de entrada

Um ponto de entrada é qualquer lugar onde uma entrada externa alcança o código: rotas HTTP, handlers GraphQL/RPC, webhooks, consumidores de fila e eventos, jobs agendados que leem dados externos, comandos CLI, processadores de arquivo ou upload, handlers de mensagens, deep links ou IPC no lado do cliente.

• Encontre-os com um parser para a linguagem do repositório (compilador ou API de language server, ou tree-sitter), não com regex: registros abrangem linhas e recebem arrays. Mantenha o script no scratchpad para que possa ser reexecutado.
• Por ponto de entrada registre: tipo, nome ou método + caminho, quem pode alcançá-lo (público, logado, admin, interno, webhook assinado), guardas (auth, MFA, captcha, rate limit, schema de entrada, verificação de assinatura), handler, toda a cadeia de middleware, decorator, filter ou interceptor, arquivo:linha.
• Fácil de perder:
  • roteadores, controladores ou grupos de handlers aninhados registrados sob um prefixo, e funções auxiliares que registram em um objeto passado
  • handlers registrados globalmente dentro de um auxiliar: sem prefixo
  • middleware, filtros ou guardas herdados de um registro anterior de prefixo ou captura-tudo
  • um grupo de handlers registrado duas vezes: liste uma vez, anote o alias
  • pontos de entrada apenas de ambiente (staging, debug, feature flags): marque-os
  • pontos de entrada que uma dependência registra (servidores de auth, painéis admin, health checks, painéis de job): leia o código-fonte do pacote, adicione-os manualmente
• Descubra o que está faltando: faça grep no código cliente (web app, mobile app, proxy, outros serviços) por cada caminho ou mensagem que ele envia, e liste tudo registrado no nível superior. Pergunte ao usuário quais adicionar; diga quais você deixou de fora e por quê.
• Escreva o inventário em entry-points.md (ou o nome que o usuário der) na worktree do orquestrador.

2. Dividir em seções

• Por tema: agrupe pelo que o código faz, não pelo tamanho, e nunca misture dois limites de confiança (público, parceiro, interno, worker) em uma seção. Divida um tema grande demais para um auditor.
• Por grupo: corte o inventário em ordem em grupos de aproximadamente N; mantenha pontos de entrada de um mesmo arquivo juntos quando isso alterar um grupo em apenas alguns.
• Mostre a divisão proposta (nome, contagem, uma linha de conteúdo, decisões subjetivas) e aguarde aprovação antes de escrevê-la no arquivo de inventário.

3. Uma worktree por seção

Corte a worktree de cada seção a partir do commit atual do orquestrador, para que cada seção audite o código em que o usuário está. Use mori quando command -v mori o encontrar, caso contrário git simples:

	mori	git
Criar	mori new sec-audit-NN-<nome> --from <branch atual>; ele imprime o caminho da worktree (sob ~/.mori/worktrees/<repo>/) — registre-o	git worktree add ../<repo>-sec-audit-NN-<nome> -b sec-audit-NN-<nome>
Dependências	instaladas pelos passos post_create do .mori.json do repositório, se houver; caso contrário, instale você mesmo	instale você mesmo
Remover	verifique dirty em mori list --json, depois mori remove <branch> -f; delete o branch se ele permanecer	verifique git status nela, depois git worktree remove <dir> e git branch -D <branch>

Em HEAD detached, use git (git worktree add <dir> -b <branch> HEAD). Crie as worktrees em segundo plano.

• Copie para cada uma: AUDIT_SCOPE.md (a tabela da seção, as notas de coluna, "audite apenas esses pontos de entrada"), o inventário completo e, se o modelo de ameaça foi construído mas ainda não foi commitado, uma cópia dele no mesmo caminho.
• Crie a caixa de entrada no orquestrador: <orquestrador>/.security-audit/swarm/<secao>/.
• Para refazer a divisão: remova as worktrees antigas e seus branches como acima (nunca force a remoção de uma com mudanças que você não examinou), depois recrie.

4. Executar as auditorias de seção em paralelo

Escreva um briefing no scratchpad e dispare um agente em segundo plano por seção apontando para ele. O briefing deve dizer:

• Trabalhe apenas em WORKTREE; leia suas instruções de agente (CLAUDE.md, AGENTS.md). As únicas escritas fora de WORKTREE vão para INBOX (caminho absoluto para a caixa de entrada da seção no orquestrador).
• Use a skill security-audit incluída neste plugin (ou outra que o usuário nomeie), através da ferramenta Skill, com escopo em @AUDIT_SCOPE.md; em uma execução rápida, diga a ela que é uma execução rápida para que nunca pare para perguntar. Sem uma: rastreie cada entrada do ponto de entrada até o sink com arquivo:linha, prove que é alcançável após cada controle, descarte o que não for alcançável.
• Com um modelo de ameaça: leia-o completamente antes de rastrear; use seus pontos de entrada, controles e lista de escopo excluído; nunca o reescreva. Execução rápida: sem modelo de ameaça, não crie um. Nunca faça perguntas.
• Cada candidato vai para um subagente crítico novo que assume um falso positivo; se não for possível criar um, faça a autocrítica e informe isso por achado.
• Crítico/Alto: um teste com falha através do ponto de entrada real, executado com o executor de testes do repositório, deixado na árvore.
• Reporte cada achado para INBOX assim que seu crítico retornar, um arquivo por achado (NN-<slug>.md), para que nada seja perdido se a saída do agente for interrompida. Formato abaixo.
• Também reporte candidatos bloqueados: um fluxo que atinge um sink mas precisa de algo que a seção não pode fornecer (um id, um token, uma ação da vítima, um valor vazado, uma condição de corrida). Use status: blocked e nomeie exatamente o que está faltando; outra seção pode fornecê-lo.
• Também escreva o relatório da seção em WORKTREE/.security-audit/<secao>-<data>.md.
• Regras rígidas: siga as regras de segurança do repositório; sem migrações ou scripts de banco de dados, sem escritas no git, sem chamadas a serviços externos.
• Mensagem final: linha de veredito, uma linha por achado, quantos arquivos foram para INBOX, itens não verificados e como a skill de auditoria foi invocada.

Formato do arquivo de achado:

---
id: <secao>-NN
status: validated | blocked
severity: critical | high | medium | low | info
critic: independent | self
entry_point: <método + caminho ou nome do handler>
needs: <o que o atacante deve ter antes: tipo de conta, id, token, clique da vítima, timing>
gives: <o que o atacante tem depois: valor vazado, acesso de escrita, sessão, dinheiro, execução de código>
test: <caminho ou none>
---
Alegação de uma linha.

Trace: source `arquivo:linha` → … → sink `arquivo:linha`.
Repro: entrada exata (requisição, mensagem, arquivo) em bloco de código.
Controles verificados: o que foi examinado e por que não impede isso.

needs e gives são o que a auditoria de encadeamento une: escreva-os concretamente ("um id de pedido da vítima", não "alguns dados").

Você pode auditar uma seção você mesmo inline. Espere que o limite de subagentes concorrentes bloqueie alguns críticos.

5. Re-verificar antes de encadear

Quando cada agente de seção tiver terminado, leia a caixa de entrada e compare as contagens de arquivos com a mensagem final de cada agente. Então execute você mesmo um crítico novo em:

• qualquer Alto ou Crítico com critic: self
• qualquer achado marcado como provisório, condicional ou "depende de <outro serviço>": leia o código desse serviço se você o tiver e resolva a questão. Bugs na fronteira entre dois serviços são os que cada seção perde sozinha.

Atualize o arquivo de achado com a severidade do crítico e mantenha o original em uma linha was:.

6. Auditoria de encadeamento

Uma última auditoria no orquestrador sobre toda a caixa de entrada, com o inventário e o modelo de ameaça (se houver) à mão. Execute-a inline ou como um agente com a caixa de entrada completa em seu briefing.

1. Deduplicar. Mescle achados com a mesma causa raiz (mesmo sink e mesmo controle faltante) em um, listando cada seção e ponto de entrada que o atinge. Dois pontos de entrada em um bug são um achado com um raio de explosão maior, não dois achados.
2. Juntar. Para cada par, verifique se o gives de um achado satisfaz o needs de outro, incluindo candidatos blocked. Também procure pelas escalações habituais:
   • vazamento de informação (id, email, token, URL interna) → IDOR, account takeover ou SSRF que precisava disso
   • enumeração de usuário + falta de rate limit → credential stuffing ou brute force de OTP
   • self-XSS ou injeção de HTML + CSRF ou login CSRF → XSS armazenado em uma vítima
   • open redirect + fluxo OAuth ou magic-link → roubo de token
   • mass assignment ou validação fraca + um consumer privilegiado downstream (worker, admin view, webhook)
   • condição de corrida + saldo, cupom, limite ou ação única → ganho repetido
   • duas brechas de lógica de negócio de baixo impacto que juntas movem dinheiro ou contornam um limite
3. Provar cada cadeia. Rastreie-a de ponta a ponta com arquivo:linha em cada elo e a entrada exata em cada passo. Um elo que não está no código não é uma cadeia: não invente um, e não conte um elo que precisa de uma pré-condição que nenhum achado ou ação pública fornece.
4. Criticar cada cadeia com um novo subagente, em paralelo. Ele assume que os passos não se conectam na prática (usuários diferentes, sessões diferentes, tokens expirados, ordenação, um passo já corrigido por outro controle) e retorna a severidade da cadeia: impacto do ganho final × probabilidade de todos os passos juntos, ou "cleared".
5. Testar cada cadeia Crítica ou Alta com um teste com falha que conduza cada passo através dos pontos de entrada reais, na worktree do orquestrador.
6. Escreva cada cadeia em <orquestrador>/.security-audit/swarm/chains/NN-<slug>.md no formato de achado, com links: listando os ids dos achados. Mantenha também os achados componentes.

7. Relatório combinado

Escreva .security-audit/<escopo>-combined-<data>.md no orquestrador:

1. Linha de veredito com contagens após deduplicação, cadeias contadas separadamente ("3 cadeias, 2 aumentam severidade"). Em uma execução rápida, abra com a linha de execução rápida do references/REPORT_FORMAT.md da skill security-audit.
2. Cadeias primeiro: os passos como uma lista numerada com entrada e arquivo:linha, ganho final, severidade antes e depois do encadeamento, crítico, caminho do teste. Diga qual correção única quebra cada cadeia.
3. Descrições de Crítico/Alto: reprodutor com a entrada exata, trace com arquivo:linha, ganho e pré-requisitos, correção, crítico, caminho do teste e o que o teste não prova.
4. Tabela de Médios, lista de Baixos (recolhida), candidatos bloqueados que nada desbloqueou (recolhida: são pistas, não achados).
5. Padrões entre seções.
6. Lacunas de cobertura e itens não verificados (agentes interrompidos, discrepâncias de contagem na caixa de entrada, configuração de produção, comportamento de terceiros, críticos auto-revisados).
7. Tabela de seções com o caminho do relatório em cada worktree.

Nada é commitado. Lidere o resumo do chat com as cadeias e a tabela de Crítico/Alto, e diga qual correção enviar primeiro: prefira a que quebra o maior número de cadeias.