O que foi planejado x o que foi implementado: auditando a discrepância

Objetivo

Um linter analisa o código isoladamente. Ele pode indicar que o código é internamente consistente; mas não pode dizer se o código faz o que você pretendia, pois não possui um modelo da sua intenção. Os bugs de segurança e correção de maior impacto estão nessa lacuna — uma permissão documentada, mas nunca aplicada; um endpoint “somente para cron” que qualquer pessoa pode chamar; um campo marcado como “somente público” que vaza dados privados.

Essa habilidade é o método para identificar essa lacuna. É o diferencial: ela só funciona quando a intenção foi documentada previamente (consulte a habilidade “artefatos de lançamento”), e é exatamente por isso que ferramentas genéricas não conseguem reproduzi-la.

Contexto

Use isso quando houver uma intenção documentada — permissions.md, architecture.md, variables.md, etc. Se esses documentos estiverem ausentes ou desatualizados, essa ausência é, por si só, a primeira constatação: você não pode auditar uma intenção que nunca registrou. Recomenda-se documentar primeiro e, depois, auditar.

Método

1. Estabeleça a intenção. Leia o /documentation/*.md conjunto como fonte de referência para o que deve ser verdade: quem pode acessar o quê, quais limites são confiáveis, quais dados são públicos. Trate os documentos como afirmações a serem verificadas, não como provas.

2. Reúna evidências de implementação. Leia o código que aplica (ou deixa de aplicar) cada afirmação. A evidência é um arquivo e uma linha citados — a verificação de autorização real, o filtro de consulta real, o sanitizador real. “Provavelmente é tratado a montante” não é evidência; o caminho do código é que é.

3. Compare a afirmação com o código, uma fronteira de cada vez. Para cada regra documentada, pergunte: existe um ponto de aplicação que realmente a implemente, no servidor, em todos os caminhos? Desconfie de comentários como “somente interno”, “somente para administradores” ou “validado em outro lugar” — verifique-os no código.

4. Classifique cada discrepância de acordo com sua relevância. Uma discrepância é relevante quando, ao ser transgredida, permite que um agente real acesse dados, dinheiro, infraestrutura ou outro locatário que não deveria. Ela não é relevante quando a única pessoa afetada é o próprio agente em seus próprios dados. Desconsidere desvios cosméticos; mantenha os desvios que ultrapassam limites.

5. Evite conclusões vagas. Cada conclusão deve indicar: a intenção documentada (cite o documento), a realidade implementada (cite o código), o invasor e a vítima, e a correção concreta. Se você não puder citar os dois lados da discrepância, trata-se de uma questão a ser investigada, não de uma conclusão a ser relatada.

O que importa

• Intenção: uma regra, um limite, um escopo ou uma classificação pública/privada documentada.
• Evidência de implementação: um ponto de aplicação citado (ou sua ausência comprovável) no código.
• Uma incompatibilidade relevante: a documentação diz uma coisa, o código faz outra, e a diferença ultrapassa um limite de confiança, custo, dados ou locatário.

Notas

• “Documentado, mas não aplicado” já é uma constatação por si só — classifique-a de acordo com o que a lacuna expõe.
• “Não documentado, mas aplicado” geralmente está tudo bem, mas sinalize isso: a documentação está desatualizada, o que enfraquece a próxima auditoria.
• Esse método alimenta as auditorias de segurança e desempenho; ele não substitui a análise detalhada delas — ele acrescenta o eixo da intenção que lhes falta.
• Nunca invente uma intenção para criar uma lacuna. Se a documentação não se pronuncia, diga que a documentação não se pronuncia.