Como ler e agir sobre um relatório do CodeAuditAgent

Um relatório de segurança só é útil se virar correções mergeadas. Os relatórios do CodeAuditAgent são desenhados em torno disso: cada achado é específico o bastante para ser verificado rápido e vem com uma correção que você pode adaptar. Este guia explica cada parte de um relatório, como fazer a triagem quando você não tem uma pessoa dedicada à segurança, e como confirmar que suas correções funcionaram.

O que é auditado

Uma auditoria roda sobre um repositório público do GitHub ou sobre um trecho de código que você cola. Para repositórios, o CodeAuditAgent lê a branch padrão. Repositórios privados não podem ser auditados por URL, e ainda não há comentários em pull requests; os resultados ficam no painel e nas exportações.

O quanto de um repositório é lido depende do seu plano. O plano gratuito cobre 1 repositório, 3 auditorias por mês e até 20 arquivos por auditoria. O Starter, a US$ 49 por mês, cobre 5 repositórios, 50 auditorias e 40 arquivos por auditoria. O Pro, a US$ 199 por mês, cobre repositórios ilimitados, 500 auditorias e 80 arquivos por auditoria. Arquivos individuais maiores que 60 KB são ignorados. As contagens mensais de auditoria zeram no início de cada mês do calendário (UTC). Um trecho colado também é uma forma rápida de checar um arquivo específico que está te preocupando antes de auditar o repositório inteiro.

Quando arquivos ficam de fora por causa desses limites, o relatório é marcado como um retrato parcial. Leve esse rótulo a sério. Um relatório parcial limpo significa que os arquivos lidos parecem limpos, não que o repositório está. Se o código que mais importa para você foi omitido, audite-o como trecho colado ou num plano que cubra mais arquivos.

O score de risco

No topo de todo relatório há um score de risco de 0 a 100; a exportação em Markdown também informa a severidade geral ao lado dele. Mais alto significa mais risco. É um resumo dos achados daquela auditoria, útil para duas coisas: decidir com que urgência olhar um repositório e acompanhar se ele está melhorando ao longo do tempo.

Não leia demais em pequenas diferenças entre repositórios não relacionados. Um score é sempre relativo ao que foi auditado, e um retrato parcial enxerga menos código. Comparar o mesmo repositório antes e depois das correções é onde o número é mais significativo.

Severidade e confiança

Cada achado tem uma severidade e uma confiança. Elas respondem a perguntas diferentes: severidade é o quão ruim seria se o achado for real, e confiança é o quanto quem revisou está certo de que ele é real.

• Crítica: diretamente explorável e com impacto sério, como injeção num endpoint público, desvio de autenticação ou credenciais de produção expostas.
• Alta: uma vulnerabilidade real que precisa de alguma precondição, ou que tem impacto significativo porém limitado.
• Média: uma fraqueza que importa em combinação com outras falhas, ou que tem impacto moderado.
• Baixa: questões de endurecimento e lacunas de defesa em profundidade.
• Informativa: observações que vale conhecer, mas que não são vulnerabilidades por si sós.

A confiança é alta, média ou baixa. Um achado de confiança alta tem evidência clara no código que foi lido. Um achado de confiança baixa normalmente depende de algo que a auditoria não conseguiu ver, como um middleware em outro arquivo, uma política de banco ou um valor de configuração definido no deploy. Confiança baixa não quer dizer ignorar; quer dizer que uma pessoa deve checar o contexto faltante antes de corrigir.

Anatomia de um achado

Todo achado segue a mesma estrutura, então você consegue verificá-lo sempre na mesma ordem.

• Título e CWE: a classe de fraqueza, como CWE-639 para um desvio de autorização por chave controlada pelo usuário. A CWE indica que tipo de correção esperar.
• Localização: o arquivo e a linha, para você abrir o código direto.
• Evidência: o código relevante citado do arquivo. Confira se a citação corresponde ao seu código atual; se a linha já mudou, o achado pode estar desatualizado.
• Cenário de exploração: como um atacante usaria de fato a fraqueza, passo a passo. É a forma mais rápida de julgar se ela é real no seu contexto.
• Correção sugerida: uma mudança proposta no estilo do código ao redor.

Trate a correção como um ótimo ponto de partida, não como um commit pronto para merge. Ela é escrita a partir do código que a auditoria leu, então pode não conhecer suas funções auxiliares, suas convenções de ORM ou uma chamada em outro ponto da base de código. Uma correção típica é pequena e direcionada:

--- a/app/api/invoices/[id]/route.ts
+++ b/app/api/invoices/[id]/route.ts
@@
-  const invoice = await db.invoice.findUnique({ where: { id } });
+  const invoice = await db.invoice.findFirst({
+    where: { id, userId: session.user.id },
+  });
   if (!invoice) return Response.json({ error: 'not_found' }, { status: 404 });

Pontos positivos e próximos passos

Os relatórios também listam o que está bem feito: consultas parametrizadas usadas de forma consistente, segredos carregados do ambiente, uma configuração estrita de cookies. Vale a pena ler essa parte. Ela mostra quais padrões manter e copiar para o código novo, e é útil quando você precisa explicar o estado de uma base de código a outra pessoa.

A seção de próximos passos recomendados transforma os achados em um plano ordenado. Ela frequentemente agrupa achados relacionados, por exemplo várias verificações de propriedade ausentes que são melhor resolvidas com um único helper compartilhado em vez de cinco correções separadas.

Um fluxo de triagem para times pequenos

Sem uma pessoa de segurança, o risco não é ignorar um relatório; é passar um dia em achados de severidade baixa enquanto um crítico espera. Uma ordem simples funciona bem:

• Leia primeiro todos os achados críticos e altos. Para cada um, leia o cenário de exploração e decida: é real, não é real, ou precisa de contexto.
• Corrija os achados críticos reais no mesmo dia. Se a correção leva tempo, aplique uma mitigação temporária, como desativar o endpoint ou apertar uma verificação.
• Para achados que precisam de contexto, cheque a peça que falta: existe um middleware, uma política em nível de linha ou uma configuração que já impede isso? Anote a resposta.
• Coloque os achados altos no sprint atual, os médios no backlog, e junte os baixos e informativos numa rodada de endurecimento.
• Quando um achado não for real, registre o porquê. Essa anotação poupa a próxima pessoa de investigar tudo de novo.

Atribua cada achado a um único responsável. Achados que são do time inteiro tendem a não ser de ninguém.

O explorador de achados e as exportações

Depois de algumas auditorias, o explorador de achados é mais prático que os relatórios individuais. Ele lista achados de várias auditorias e os filtra por severidade, CWE e repositório. Filtrar por CWE é particularmente útil: se a mesma fraqueza aparece em três repositórios, isso normalmente aponta para um padrão compartilhado ou um helper ausente, e corrigir o padrão sai mais barato do que corrigir cada ocorrência.

Os achados podem ser exportados em CSV pelo explorador, o que é prático para importar num gerenciador de tarefas ou numa planilha. Relatórios individuais podem ser exportados em Markdown, que fica bom na descrição de um pull request, num wiki interno ou numa mensagem para quem vai fazer a correção.

Reaudite para confirmar a correção

Uma correção não está pronta enquanto você não a conferir. Depois do merge, rode uma nova auditoria no mesmo repositório. Cada relatório pode ser comparado com a auditoria anterior, então você vê quais achados sumiram, quais permanecem e se algo novo apareceu. O score de risco deve cair quando problemas reais são corrigidos; se não cair, olhe a comparação para entender por quê.

Mantenha a comparação justa. Se a primeira auditoria foi um retrato parcial e a segunda leu arquivos diferentes, a diferença reflete tanto a cobertura quanto as correções. As auditorias saem da sua cota mensal, então normalmente vale juntar várias correções antes de reauditar, em vez de rodar de novo a cada commit.

O que um relatório não cobre

Conhecer os limites ajuda a preencher as lacunas. As auditorias leem o seu código-fonte; elas não varrem dependências em busca de versões sabidamente vulneráveis, então mantenha também um scanner de dependências rodando, como o embutido no seu gerenciador de pacotes ou no GitHub. As auditorias não enxergam configuração de deploy, infraestrutura fora do repositório nem arquivos que foram ignorados. E, como qualquer revisor, humano ou de IA, a auditoria pode errar: a evidência e os níveis de confiança estão ali para você conferir rápido em vez de aceitar por fé.

Usado assim, um relatório vira uma lista curta e priorizada de mudanças com evidência anexada. Corrija as críticas, cheque as incertas, reaudite e acompanhe o score se mover.