Atualizações do formato de auditoria que preservam evidências antigas

Uma atualização do formato de auditoria só é segura quando um investigador consegue verificar as evidências exportadas de ontem com as regras que valiam ontem. Um novo analisador que exibe uma tela plausível, uma migração de banco de dados concluída com sucesso e uma implantação aprovada não provam isso. Muitas vezes, eles escondem exatamente a falha importante: um registro cujos bytes continuam intactos, mas cujo significado, entrada do hash ou comportamento do verificador mudou.

Trate o formato de auditoria como um protocolo com uma longa vida útil. Seu aplicativo pode mudar toda semana. As evidências não podem. Quando alguém depende de um registro para explicar quem aprovou uma ação, qual credencial foi usada ou o que um agente enviou a um serviço externo, esse registro precisa manter uma interpretação estável muito depois de o código que o escreveu ter desaparecido.

Preserve os bytes antes da conveniência

O artefato autoritativo é a sequência original de bytes do registro, junto com o contexto necessário para verificá-la. Uma linha analisada no banco de dados atual é uma cópia de trabalho. Um objeto JSON exibido em um painel é uma visualização. Nenhum dos dois substitui os bytes de evidência que participaram de uma assinatura, de uma cadeia de hashes ou de um envelope autenticado.

Essa distinção parece excessivamente meticulosa até que uma atualização reescreva um campo. Suponha que a versão 1 armazene um destino SSH como uma string fornecida pelo usuário:

{"schema_version":1,"event":"ssh.execute","target":"[email protected]:22","command":"uptime"}

A versão 2 quer campos separados para poder filtrar por host e porta:

{"schema_version":2,"event":"ssh.execute","user":"build","host":"prod.example","port":22,"command":"uptime"}

Esses dois registros podem descrever a mesma ação, mas não são evidências intercambiáveis. Um codificador v2 pode normalizar um nome de host, inserir uma porta padrão ou rejeitar um destino aceito pela v1. Se você substituir o primeiro registro pelo segundo, terá feito uma nova afirmação sobre o evento antigo. Talvez seja uma afirmação correta, mas você não pode provar isso simplesmente apontando para os dados reescritos.

Mantenha três coisas separadas:

• Evidência original: bytes imutáveis, exatamente como foram aceitos na sequência de auditoria.
• Representação derivada: uma forma indexada, decodificada ou migrada, usada para pesquisa e exibição.
• Notas de interpretação: regras documentadas que explicam campos, valores padrão e comportamentos específicos de cada versão.

Uma representação derivada pode ser reconstruída. A evidência original, não. Armazene os originais em um pacote de evidências somente para acréscimo ou em um armazenamento de objetos, enderece-os pelo digest e faça cada item derivado apontar para esse digest. Se as regras de retenção exigirem uma exclusão, registre a exclusão como um evento próprio. Não compacte o histórico silenciosamente e chame o resultado de atualização.

Isso também vale quando o log usa registros criptografados. A criptografia protege o conteúdo contra leitores não autorizados; ela não torna uma migração com perda de dados inofensiva. O verificador ainda precisa identificar qual texto cifrado, cabeçalho e regra de cadeia produziram o resultado.

Dê uma versão explícita a cada registro

Inclua um schema_version explícito em cada registro antes de submetê-lo a hash ou assinatura. Não deduza a versão a partir de uma extensão de arquivo, de um número de migração do banco de dados, de uma versão do aplicativo ou da presença de um campo adicionado recentemente.

A inferência funciona até a primeira exportação forense. Um investigador recebe uma pasta de registros copiados de um backup, de um chamado de suporte ou de uma máquina que já não executa o aplicativo atual. O contexto ao redor está incompleto, enquanto o registro continua presente. Um registro que carrega sua própria versão informa ao verificador qual decodificador e quais regras ele precisa usar.

Use um número inteiro pequeno para um formato cujas regras você controla. Reserve a versão 0 como inválida, para que um campo ausente não se transforme silenciosamente em um formato legado. A versão deve ter uma função restrita: selecionar a gramática do registro e a receita de verificação. Não a transforme em um identificador geral de versão do produto.

Um envelope durável pode ter esta aparência:

{
  "schema_version": 3,
  "record_id": "01J8X7K5W3H0Q9M6P2R4A1C8ZD",
  "recorded_at": "2026-07-22T14:08:31.482Z",
  "kind": "http.request.completed",
  "previous_digest": "sha256:4a4d...",
  "payload": {
    "method": "POST",
    "authority": "api.example.test",
    "status": 201
  }
}

A versão pertence à entrada autenticada. Se um registro declarar a versão 3, mas o digest tiver sido calculado sem esse campo, um invasor capaz de editar os bytes armazenados poderá redirecionar o verificador para uma interpretação diferente. Inclua nos bytes protegidos todo campo que selecione um analisador, algoritmo de hash, regra de canonicalização ou algoritmo de assinatura.

Separe também a versão do esquema do registro da versão semântica do evento. A primeira responde: «Como faço para analisar e verificar estes bytes?» A segunda responde: «O que este evento significava quando foi emitido?»

Por exemplo, mudar actor de um nome de exibição livre para uma identidade estável de processo pode preservar o formato JSON e, ainda assim, mudar a afirmação. Isso não é apenas a versão 4 do esquema. É uma mudança semântica, e o investigador precisa encontrar na especificação das evidências uma explicação de quando o novo significado começa. O mesmo alerta vale quando um campo muda de unidade, quando um timestamp passa do horário local para UTC ou quando um status muda de uma resposta observada para uma decisão de política.

Congele a receita de verificação, não apenas os campos

Um esquema versionado fica incompleto se o verificador não consegue reconstruir a receita exata de bytes usada para autenticar um registro. O layout dos campos é apenas uma parte dessa receita.

Documente, para cada versão:

• a gramática aceita do registro e os campos obrigatórios;
• a codificação de texto ou binária e as regras de canonicalização;
• os algoritmos de digest e assinatura;
• o separador de domínio, se houver um;
• a regra de ligação da cadeia e a regra de gênese;
• o comportamento de falha para entradas malformadas ou desconhecidas.

A RFC 8785 explica por que o JSON precisa de uma representação determinística antes de operações criptográficas: o JSON comum permite várias serializações para o mesmo valor lógico, enquanto hashing e assinatura exigem bytes invariáveis. Seu JSON Canonicalization Scheme restringe a entrada e ordena as propriedades dos objetos de forma determinística. A especificação também alerta, por meio das restrições do formato, que nomes de propriedades duplicados e números fora da representação compatível não são detalhes inofensivos.

Esse padrão só é útil quando você nomeia o perfil exato. Dizer «fazemos hash de JSON» não é uma receita. Dizer «chamamos o serializador do runtime atual» é pior, porque uma atualização do runtime pode mudar o escape, a formatação numérica ou a ordenação sem nenhuma mudança deliberada na auditoria.

O mesmo problema aparece nos formatos binários. A RFC 8949 define requisitos de codificação determinística para CBOR e observa que uma convenção de ordenação anterior precisa de um modo de compatibilidade nomeado explicitamente. Um verificador não pode presumir com segurança que todos os produtores históricos usaram o mesmo significado para «canônico».

Não crie um verificador novo que analise qualquer JSON, o serialize novamente usando a biblioteca de hoje e depois faça o hash do resultado. Esse padrão quebra evidências antigas de duas formas. Ele pode rejeitar registros válidos segundo a receita anterior e aceitar um registro segundo uma receita nova que nunca produziu o digest original.

Em vez disso, mantenha a seleção da versão próxima do limite dos bytes:

read envelope bytes
  -\u003e identify protected schema_version
  -\u003e select verifier V1, V2, or V3
  -\u003e validate that version's grammar
  -\u003e reproduce that version's authenticated bytes
  -\u003e verify digest, signature, and chain link
  -\u003e decode a display model only after verification

O modelo de exibição vem por último de propósito. Um renderizador pode ser agradável. Um verificador não pode ser imaginativo.

Versões desconhecidas devem falhar de forma segura

Quando encontrar uma versão que não suporta, o verificador deve retornar explicitamente um resultado unsupported_version. Ele não deve tratar campos desconhecidos como descartáveis, presumir o layout mais recente nem executar um decodificador genérico de fallback.

Engenheiros costumam resistir a isso porque querem compatibilidade futura. Ela é adequada para um aplicativo que lê campos opcionais de apresentação. É perigosa na verificação de evidências, pois um campo que parece opcional pode controlar posteriormente a interpretação autenticada.

Use um formato de resultado que separe falhas das evidências das limitações da ferramenta:

{
  "record_id": "01J8X7K5W3H0Q9M6P2R4A1C8ZD",
  "schema_version": 4,
  "status": "unsupported_version",
  "verified": false,
  "supported_versions": [1, 2, 3],
  "reason": "Verifier 2.7.0 has no verification recipe for schema version 4"
}

Esse resultado diz algo preciso: a ferramenta não estabeleceu a autenticidade. Ele não acusa o registro de adulteração nem finge que o registro é válido. Mantenha invalid, incomplete, unsupported_version e verified distintos tanto na saída dos comandos quanto nas APIs.

Uma cadeia de hashes acrescenta outro requisito de compatibilidade. O histórico da cadeia não pode ser presumido a partir de um único digest final. O verificador precisa das regras específicas da versão para o primeiro registro, a ordenação dos registros, a codificação do digest pai e qualquer formato de checkpoint. A Certificate Transparency oferece um modelo mental adequado: a RFC 9162 define provas de consistência que mostram que uma árvore anterior é o mesmo prefixo de uma árvore posterior, em vez de pedir aos auditores que confiem em um novo hash de raiz informado.

Sua sequência de auditoria pode não usar uma árvore de Merkle, mas a lição permanece. Quando as regras da cadeia mudarem, prove a continuidade na fronteira. Crie um checkpoint v1 terminal contendo seu digest final verificado, a contagem de registros e a versão. Faça o primeiro registro v2 autenticar esse checkpoint em um campo definido. O verificador v2 deve verificar os dois lados com suas próprias regras antes de declarar um único histórico contínuo.

Nunca una dois históricos armazenando um digest antigo como comentário ou campo de exibição. A união precisa fazer parte da entrada protegida.

Migrações devem produzir derivados, nunca substitutos

Uma boa migração cria um derivado novo e reproduzível ao lado da evidência de origem. Ela registra proveniência suficiente para que outra pessoa possa recriar o mesmo resultado e compará-lo com a origem.

Para cada registro ou lote migrado, capture:

{
  "source_digest": "sha256:4a4d...",
  "source_schema_version": 1,
  "migration_id": "audit-v1-to-v2",
  "migration_build": "2.7.0+e31c9f4",
  "output_digest": "sha256:77c8...",
  "migrated_at": "2026-07-22T14:12:09Z"
}

O horário migrated_at descreve o derivado, não o evento original. Não substitua recorded_at nem apresente um registro v2 gerado como se tivesse sido emitido pelo sistema antigo. Esse erro já causou mais confusão em investigações internas do que qualquer falha evidente do analisador.

Algumas migrações não podem ser sem perdas. Um registro v1 pode ter uma única string target, enquanto a v2 exige um URI estruturado. Se a análise falhar ou houver ambiguidade, preserve a string de origem e registre um status explícito da migração. Não invente um valor estruturado só porque seu novo índice quer um.

Por exemplo:

{
  "source_digest": "sha256:4a4d...",
  "migration_status": "partial",
  "derived": {
    "target_raw": "[email protected]:22",
    "host": "prod.example",
    "port": 22
  },
  "unresolved": ["user"]
}

Isso pode parecer menos organizado do que uma linha totalmente preenchida. É mais honesto. Um investigador futuro poderá ver tanto o que o registro antigo dizia quanto o que a migração inferiu.

Evite a recomendação popular de passar todas as entradas antigas pelo gravador atual e chamar isso de atualização. Ela é popular porque simplifica um caminho de código e torna os relatórios uniformes. Está errada para evidências porque os gravadores normalmente aplicam valores padrão atuais, omitem campos obsoletos e normalizam valores. O resultado pode ser útil para pesquisa, mas é uma tradução, não o testemunho original.

Um corpus permanente de fixtures detecta falhas silenciosas

Compatibilidade é um recurso de teste, não uma promessa em uma nota de lançamento. Crie um corpus de evidências para cada versão de esquema lançada e execute-o contra cada build de verificador que declare suporte a essa versão.

O corpus precisa de mais do que alguns registros de caminho feliz. Mantenha fixtures exatas em bytes para estes casos:

• um registro válido normal e uma cadeia válida com vários registros;
• timestamps de fronteira, texto Unicode, valores opcionais vazios e limites numéricos aceitos por essa versão;
• um registro com um byte do payload alterado;
• um registro com o digest pai alterado ou a sequência reordenada;
• entradas malformadas, duplicadas, truncadas e de versão desconhecida.

Armazene os resultados esperados, não apenas os objetos decodificados esperados. O teste deve verificar o resultado da evidência e a categoria do diagnóstico. Um verificador que marca corretamente um registro válido como inválido ainda falhou. Um verificador que transforma um registro malformado em uma exceção genérica do analisador falhou de forma menos dramática, mas tornou as investigações mais difíceis.

Use um manifesto que fixe os digests das fixtures e o comportamento esperado do verificador:

fixture: v1/0007-http-request.json
sha256: 4a4d5f0c...
expect:
  status: verified
  schema_version: 1
  chain_position: 7

fixture: v1/0007-http-request-tampered.json
sha256: 91af2a7d...
expect:
  status: invalid
  error_code: payload_digest_mismatch

Depois, teste mais de uma direção.

1. O verificador mais antigo ainda mantido deve verificar seu corpus original.
2. O verificador atual deve verificar todos os corpus históricos mantidos.
3. Um gravador candidato deve criar registros que o verificador atual aceite sob a nova versão.
4. Uma migração candidata deve preservar o digest de origem declarado e produzir o derivado esperado.
5. Todo verificador deve rejeitar fixtures criadas para versões futuras não compatíveis.

Não reescreva as fixtures esperadas sempre que um teste falhar. Primeiro inspecione os bytes, a versão do verificador selecionada e o código da falha. Atualizações de fixtures devem ser raras, revisadas como uma mudança de protocolo e acompanhadas de uma justificativa que diferencie uma fixture nova intencional de evidências alteradas.

Adicione testes baseados em propriedades aos analisadores, mas não os confunda com o corpus permanente. Entradas aleatórias encontram falhas e casos-limite estranhos. Fixtures nomeadas preservam os casos que você aprendeu da forma difícil, inclusive registros de versões reais depois que o conteúdo sensível foi removido.

Teste a fronteira da atualização como um investigador faria

O maior risco normalmente está na fronteira entre versões, não em cada versão isoladamente. Escreva um cenário que comece antes da atualização e termine depois dela. Em seguida, pergunte se uma pessoa independente conseguiria explicar toda a sequência.

Considere uma cadeia em que a v1 registra a aprovação de uma sessão de agente, várias chamadas HTTP e a revogação da sessão. A versão 2 introduz um campo de resultado de solicitação mais detalhado e uma nova codificação de checksum. O teste deve começar com um registro de gênese v1, acrescentar entradas v1 válidas, criar o checkpoint de fronteira documentado, acrescentar entradas v2 e exportar o pacote completo.

O relatório de verificação esperado precisa mostrar a transição claramente:

$ audit verify evidence-bundle
verified v1 records: 18
verified v1 terminal digest: sha256:6c12...e98a
verified v1-to-v2 continuity checkpoint
verified v2 records: 6
chain status: verified

Agora execute as falhas que as atualizações de produção costumam criar:

• remova o registro v1 final, mas mantenha os registros v2;
• altere o digest v1 do checkpoint;
• use um registro v2 com um rótulo de versão v1;
• exporte apenas o segmento v2 e peça um veredito sobre o histórico completo;
• execute um verificador anterior à v2 contra o pacote misto.

Um sistema correto dará respostas diferentes. As três primeiras situações são inválidas. A quarta pode ser verificada como um segmento parcial se o pacote declarar seu checkpoint inicial, mas não pode afirmar que verificou o histórico completo. A quinta retorna unsupported_version depois de relatar as evidências v1 que conseguiu verificar, se o desenho do comando permitir relatórios parciais. Ela não deve declarar o pacote inteiro como verificado.

É nesse ponto que as equipes descobrem que seus diários e painéis escondem as fronteiras de origem. Uma interface que reúne os registros em uma única linha do tempo pode funcionar, desde que identifique a transição de esquema e permita ao revisor inspecionar o envelope original. Não faça o investigador deduzir uma mudança de formato pelo aparecimento repentino de um campo.

Mantenha o verificador pequeno o suficiente para sobreviver ao aplicativo

O verificador de auditoria deve ter menos dependências e menos privilégios do que o aplicativo que produz os registros. Se ler evidências antigas exige iniciar um aplicativo gráfico, conectar-se a uma conta, abrir um cofre de credenciais ou baixar um pacote de compatibilidade, seu plano de evidências depende de condições que desaparecerão no pior momento possível.

Separe as responsabilidades:

• O aplicativo grava registros e apresenta a atividade ao vivo.
• Um verificador compacto lê um pacote exportado, seleciona receitas versionadas e emite um relatório legível por máquina.
• Um renderizador pode transformar registros verificados em tabelas e linhas do tempo sem participar da decisão de autenticidade.

Torne o verificador determinístico. Dado o mesmo pacote e as mesmas opções de comando, ele deve retornar os mesmos códigos de status e a mesma estrutura de relatório. Inclua no relatório o identificador da versão do verificador, mas não permita que esse identificador altere o resultado da evidência.

Para o Sallyport, sp audit verify é a verificação certa para preservar em um manual de atualização, pois verifica offline a cadeia de hashes criptografada sobre o texto cifrado e não precisa da chave do cofre. Salve o relatório do comando ao lado de uma exportação intocada antes de alterar o aplicativo. Depois, verifique novamente essa mesma exportação.

A palavra «offline» exige disciplina. Ela significa que o verificador consegue estabelecer o resultado da cadeia a partir das evidências disponíveis e das receitas de verificação incorporadas. Não significa que ele consiga reconstruir registros ausentes, decidir quem operou uma máquina ou provar que um usuário entendeu um cartão de aprovação. Um relatório bem projetado diz exatamente qual afirmação foi verificada.

Publique a especificação do formato de evidências junto com o código-fonte e as fixtures do verificador. Uma versão do código sem o corpus de fixtures deixa os futuros responsáveis tentando adivinhar a compatibilidade. Um corpus sem uma receita escrita deixa-os tentando adivinhar se um teste aprovado reflete uma regra deliberada ou um acidente de uma implementação.

Defina uma política de aposentadoria antes da primeira emergência

Você só pode deixar de oferecer suporte a um formato histórico depois de decidir o que acontecerá com as evidências que o utilizam. Essa decisão pertence à segurança, ao jurídico, às operações e às pessoas que investigam incidentes. Ela não deve surgir como consequência acidental da exclusão de um pacote antigo.

Escreva uma tabela de suporte que indique as versões mantidas, as versões do verificador capazes de lê-las, o período esperado de retenção das evidências e o processo para um arquivo excepcional. Se pretende aposentar um leitor, forneça um verificador de arquivo independente e congele primeiro seu corpus de fixtures. Mantenha as instruções de build e os checksums esperados junto da documentação das evidências.

Não prometa suporte perpétuo sem pensar. Algoritmos envelhecem, sistemas operacionais mudam e analisadores antigos podem carregar falhas de segurança. Mas preserve uma forma de verificar as evidências retidas. Às vezes, isso significa uma ferramenta de arquivo em sandbox que aceita apenas arquivos locais. Às vezes, significa manter uma imagem de contêiner ou máquina virtual com hashes registrados. A escolha depende do seu ambiente; a obrigação é não pedir a um investigador futuro que reconstrua de memória uma cadeia de ferramentas desaparecida.

A primeira ação é concreta: exporte um pequeno pacote real de evidências, execute o verificador e anote todas as regras versionadas das quais o comando depende. Se você não consegue descrever essa receita e reproduzir o resultado depois de uma atualização de teste, ainda não tem um plano de atualização. Tem apenas a esperança de que as evidências antigas continuem legíveis.