Escrevendo o relatório de auditoria que ninguém quer ler, para que leiam

Já escrevi centenas de relatórios de auditoria e sei exatamente o que acontece com um ruim. É aberto, rolado e encaminhado para outra pessoa com um 'o que acha?'. Ninguém lê a página nove. O achado crítico da página nove continua em produção. Então parei de escrever relatórios que provam o quanto encontrei e comecei a escrever relatórios que fazem as coisas serem corrigidas. A diferença é estrutura, e dá para aprender.

A primeira página é o relatório inteiro

Quem abre o documento tem cinco minutos, talvez menos. A primeira página precisa funcionar sozinha: o que olhei, o que encontrei que importa, em que ordem, e o que fazer primeiro. Três achados, no máximo cinco, cada um em duas frases: o que quebra e o que custa. Se o leitor fecha o documento depois da primeira página e corrige essas três coisas, a auditoria deu certo. Tudo depois da primeira página é evidência de apoio para quem quiser.

Ordene por consequência, não por categoria

Gente de segurança ordena por pontuação de vulnerabilidade. Engenheiros ordenam por dificuldade da correção. Nenhum dos dois é o que a pessoa que decide precisa. Ordeno pelo que acontece se não for corrigido, nos termos que o negócio já usa: perde dados de clientes, perde dinheiro, perde disponibilidade, perde confiança, e depois todo o resto. Um índice faltando que faz o checkout dar timeout sob carga fica acima de um header teoricamente explorável, porque um acontece toda sexta e o outro exige um atacante que não apareceu. A ordem é a decisão editorial mais importante do documento, e gasto nela tanto tempo quanto em qualquer achado.

Todo achado tem as mesmas quatro partes

O quê: uma frase, concreta, nomeando o componente. Evidência: como vi, de forma reproduzível, com a query, a requisição ou a captura de tela. Impacto: o que faz com um usuário, um cliente ou a empresa, em palavras simples. Correção: o próximo passo, com uma estimativa de esforço honesta o bastante para planejar em cima. Nenhum achado sem evidência, porque evidência encerra discussões. Nenhum achado sem correção, porque um problema sem próximo passo é só ansiedade. Se não consigo propor uma correção, digo isso e rebaixo a prioridade.

Escreva na língua do leitor

O relatório não é para mim nem para outros auditores. É para um líder de engenharia que precisa decidir o que fazer nesta sprint, e para um fundador ou diretor que precisa decidir o que financiar. Então escrevo 'um webhook duplicado gera uma segunda cobrança no cartão do cliente' e não 'o endpoint carece de garantias de idempotência'. O detalhe técnico vai na seção de evidência, onde o engenheiro que vai corrigir consegue encontrar. A frase do topo precisa ser entendida por alguém que nunca viu a base de código e nunca vai ver.

Uma auditoria que só lista problemas soa como ataque, e as pessoas se defendem de ataques em vez de agir sobre eles. Todo sistema que já olhei faz alguma coisa bem, e digo isso, de forma específica, perto do topo. Não para amaciar o golpe. Porque é verdade, e porque um time que ouve suas forças nomeadas com precisão confia no mesmo autor quando as fraquezas são nomeadas. Também diz a eles o que não quebrar enquanto corrigem todo o resto.

O teste de um bom relatório

Seis semanas depois da entrega, faço uma pergunta: quais achados foram corrigidos? Se a resposta é os três primeiros, o relatório funcionou. Se a resposta é 'ainda estamos discutindo', o relatório falhou, por mais minucioso que fosse. Já encontrei falhas que ninguém mais encontrou, em sistemas que muita gente capaz tinha revisado. Isso não vale nada se o achado morre num documento que ninguém leu além da primeira rolagem. Escrever o relatório para que seja lido não é uma habilidade extra em cima da auditoria. É o último, e mais importante, passo da própria auditoria.