Trilha de Auditoria

Intenção

Registrar, de forma imutável e consultável, quem pediu, o que o modelo viu, o que ele decidiu e o que o sistema executou. Serve para sistemas que decidem sobre dinheiro, dados ou pessoas e precisam responder por cada decisão depois.

Problema

Luana é gerente de compliance de uma fintech. O assistente financeiro do app agenda pagamentos com aprovação do cliente. Um cliente abriu uma reclamação no Banco Central: diz que nunca aprovou um Pix de R$ 2.300.

O time tinha traces de observabilidade, mas eles eram amostrados a 10%, ficavam guardados por 14 dias e não registravam o que o cliente viu na tela de aprovação. O log da aplicação dizia “pix agendado” e um id de usuário. Não havia como provar se o cliente aprovou, o que ele viu quando aprovou, nem por que o assistente sugeriu aquele pagamento.

Observabilidade serve para o time de engenharia entender o sistema. Auditoria serve para responder a um cliente, a um auditor ou a um juiz. As perguntas são diferentes, e o registro também.

A pergunta que este padrão responde: como guardar evidência suficiente para explicar e defender cada decisão que o sistema tomou?

Solução

Crie um registro de auditoria separado dos traces, com quatro propriedades:

• Completo para decisões que importam. Toda ação com efeito e toda decisão sobre pessoas gera um evento, sem amostragem.
• Autocontido. O evento guarda o que foi necessário para a decisão: quem pediu, qual entrada (ou referência a ela), versão do prompt e do modelo, o que o modelo propôs, o que foi mostrado ao humano, quem aprovou e o que foi executado.
• Imutável. Eventos só são acrescentados, nunca editados. Um encadeamento por hash ou um armazenamento com retenção bloqueada torna adulteração detectável.
• Consultável e com retenção definida. Dá para buscar por cliente, por ação e por período, pelo tempo que a regulação exige, com dados pessoais tratados conforme a LGPD.

Exemplo trabalhado

A reclamação chega em abril. O Pix foi em janeiro. Com o registro certo, Luana busca action=schedule_pix e o id do cliente e monta a história:

event_id:        a9f3...
ts:              2026-01-12T14:32:11Z
actor:           { type: "user", id: "cli_8821" }
action:          schedule_pix
prompt_version:  finance-assistant@7
model:           claude-sonnet-5-5
proposal:        { amount_brl: "2300.00", dest_name: "Fornecedor X", dest_key_type: "cnpj" }
shown_to_human:  { title: "Agendar Pix", amount: "R$ 2.300,00", dest: "Fornecedor X", key: "**.***.***/****-**" }
decision:        approved
reviewer:        cli_8821 (biometria no app)
execution:       { status: "ok", external_id: "E0000000020260112..." }
input_ref:       obj_91c2  (pedido original, em armazenamento separado)

Isso responde três perguntas do Banco Central. Quem pediu: o titular, autenticado. O que ele viu: valor, nome e chave mascarada. O que o banco executou: o id da transação bate com o Pix. Sem shown_to_human, sobra um “pix agendado” que não prova nada. Sem prompt_version, não dá para saber se o assistente daquela semana estava sugerindo o destinatário errado.

O trace de observabilidade daquele dia já tinha sido amostrado para fora e apagado na retenção de 14 dias. Auditoria não pode herdar essas duas propriedades.

Compare os dois registros:

Estrutura

flowchart LR
  U(["1. Pedido do usuário"]):::io --> A(["2. Modelo propõe"]):::llm
  A --> H((("3. Aprovação"))):::human
  H --> X["4. Execução"]:::tool
  U --> E["5. Montar evento"]:::tool
  A --> E
  H --> E
  X --> E
  E --> R["6. Mascarar e assinar"]:::tool
  R --> L[("7. Registro só de acréscimo")]:::store
  L --> Q{"8. Consulta e relatório"}

1. O pedido chega com a identidade de quem pediu.
2. O modelo propõe uma ação, com a justificativa.
3. A aprovação registra o que foi mostrado e a resposta.
4. A execução registra o resultado e o identificador externo (id da transação, do email).
5. Um evento junta tudo, com as versões de prompt, modelo e política.
6. Dados pessoais são mascarados ou separados, e o evento recebe o hash do anterior.
7. O evento vai para um armazenamento que só aceita acréscimos.
8. Compliance, suporte e engenharia consultam com permissões diferentes.

Pseudocódigo

schema AuditEvent {
    event_id: string, ts: datetime, actor: { type: "user" | "agent" | "reviewer", id: string },
    action: string, input_ref: string, prompt_version: string, model: string,
    proposal: any, rationale: string, shown_to_human: any?, decision: "approved" | "rejected" | "auto",
    execution: { status: string, external_id: string? }, prev_hash: string, hash: string
}

function record(ctx, proposal, review, execution):
    event = AuditEvent(
        actor = ctx.user, action = proposal.tool, input_ref = store_input(ctx.input),   # 1
        prompt_version = ctx.prompt_version, model = ctx.model,
        proposal = proposal.args, rationale = proposal.reason,                           # 2
        shown_to_human = review.preview, decision = review.decision,                     # 3
        execution = execution,                                                           # 4
    )
    event = redact_pii(event)                                                            # 6
    event.prev_hash = audit_log.last_hash()
    event.hash = sha256(canonical_json(event))
    audit_log.append(event)                                                              # 7

Cenários reais

• Assistente financeiro com aprovação. Cada Pix tem um evento com a sugestão do assistente, a tela mostrada, o horário da aprovação no app e o id da transação no banco.
• Triagem de currículos com controle de viés. Cada decisão de triagem guarda os critérios aplicados, a nota e a justificativa, para responder a pedidos de revisão do candidato e a auditorias de viés.
• Assistente jurídico. Cada parecer guarda as fontes citadas, a versão do prompt e o advogado que revisou.

Aplicabilidade

• O sistema executa ações com efeito financeiro, legal ou sobre dados de terceiros.
• Decisões afetam pessoas (crédito, contratação, saúde) e podem ser contestadas.
• Há regulação que exige guardar evidência por um período.
• Você precisa responder “por que o sistema fez isso?” meses depois.

Quando não usar

• Ferramentas internas sem efeito externo, como um resumidor de reuniões. Traces comuns bastam.
• Como substituto de observabilidade. A auditoria registra decisões; o trace registra tudo o que ajuda a depurar. Os dois convivem. Veja Observabilidade para IA.

Como implementar

1. Liste as decisões e ações que precisam de evidência, com o time jurídico ou de compliance.
2. Defina o schema do evento e o que cada campo prova.
3. Guarde a entrada completa num armazenamento protegido e ponha só a referência no evento, quando ela tiver dados sensíveis.
4. Registre a versão de tudo que influenciou a decisão: prompt, modelo, política de revisão, regras.
5. Grave na mesma transação da execução, ou com uma fila que garanta entrega.
6. Use armazenamento só de acréscimo e encadeamento por hash.
7. Defina retenção e acesso por papel.
8. Teste o caminho de consulta: dado um id de cliente, monte a história completa de uma ação.

O que cada campo prova

Escreva o schema como uma lista de perguntas, não como uma cópia do span:

A justificativa que o modelo escreve (rationale) ajuda quem lê daqui a seis meses. Não é prova. Prova é o que entrou, o que foi mostrado e o que saiu.

Cadeia de hash e concorrência

Cada evento guarda o hash do anterior e o próprio hash do conteúdo canônico, sem o campo hash. Se alguém editar um evento no meio, a cadeia quebra na verificação noturna. Isso não impede um administrador com acesso ao disco; impede a edição silenciosa na aplicação.

Gravações paralelas precisam de um único escritor por cadeia (fila, lock, ou uma cadeia por partição, por exemplo por actor.id). Sem isso, dois Pix no mesmo milissegundo apontam para o mesmo prev_hash e a verificação acusa conflito mesmo sem fraude.

Erros comuns

• Amostrar a auditoria. 10% serve para achar lentidão. Não serve para a reclamação do Pix que caiu nos outros 90%.
• Retenção de trace. Catorze dias não cobrem o prazo de uma reclamação no Banco Central nem o de um processo trabalhista na triagem de currículos.
• Logar “pix agendado”. Sem prévia, sem versão, sem id externo, o evento não reconstrói a ação.
• Dado pessoal no evento. CPF, chave Pix completa e o pedido cru vão para o armazenamento separado, com chave diferente. O evento leva máscara e referência. Aplique Mascaramento de Dados Pessoais antes de gravar.
• Tratar o rationale do modelo como prova. O modelo descreve o que ele acha que fez. O registro descreve o que o sistema fez.

A trilha começa na refatoração Adicionar Trace. Trace primeiro, para o time ver o sistema. Auditoria em cima, para o que precisa sobreviver ao debug.

Variações

• Auditoria derivada dos traces. Os spans de decisão são copiados para o registro de auditoria sem amostragem. Menos código, mas cuidado com o que o trace não guarda (o que foi mostrado ao humano).
• Registro externo. Um serviço de logs com retenção bloqueada pelo provedor, para que nem o time interno consiga apagar.
• Explicação gerada na hora. Um campo de justificativa curta escrito pelo modelo junto com a proposta. Útil para leitura, mas não é prova: a prova é o que o modelo viu e o que ele propôs.

Custo, latência e falhas

Grave o evento na mesma transação da execução, ou numa fila com entrega garantida e conciliação. Assíncrono sem conciliação é o jeito educado de perder o Pix que mais vai ser contestado.

Os números de armazenamento abaixo são ilustrativos. Suponha 5 mil Pix por dia, 2 KB por evento mascarado, e o pedido completo de 20 KB só no armazenamento separado.

Gigabytes por ano são baratos perto de não conseguir responder ao Banco Central. O custo que dói é dado pessoal demais no evento, não o disco.

Como avaliar

• Cobertura: toda execução com efeito tem um evento correspondente. Rode a conciliação todo dia.
• Reconstrução: escolha ações ao acaso e monte a história completa só com o registro. Se faltar algo, o schema está incompleto.
• Integridade: verifique a cadeia de hashes periodicamente.

{ "check": "reconstruct", "action_id": "pix-88123", "must_include": ["actor", "proposal", "shown_to_human", "decision", "external_id", "prompt_version"] }

O teste de reconstrução é o eval deste padrão. Uma pessoa do time jurídico, sem acesso ao código, tenta contar a história do Pix só com o evento. Se ela pergunta “mas o que o cliente viu?”, falta campo. Se ela pergunta “esse Pix saiu mesmo?”, falta external_id.

Em produção

• Conciliação diária entre o sistema de execução (banco, email, ERP) e o registro de auditoria.
• Alerta para qualquer execução sem evento.
• Acesso ao registro só por papéis definidos, com o próprio acesso auditado.
• Rotina de resposta a pedidos de titular de dados (LGPD): o que foi guardado sobre a pessoa e por quê.

Segurança

O registro concentra informação sensível. Separe dados pessoais em armazenamento próprio, com chave de acesso diferente, e guarde só referências no evento quando possível. Aplique Mascaramento de Dados Pessoais antes da gravação e defina retenção de acordo com a base legal.

Prós e contras

Código

As duas abas gravam um evento autocontido, encadeado por hash, num armazenamento só de acréscimo.

import hashlib
import json
import uuid
from datetime import datetime, timezone


def canonical(obj: dict) -> str:
    return json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":"))


def record(db, ctx, proposal: dict, review: dict, execution: dict) -> dict:
    prev = db.fetch_one("SELECT hash FROM audit_log ORDER BY seq DESC LIMIT 1")
    event = {
        "event_id": str(uuid.uuid4()),
        "ts": datetime.now(timezone.utc).isoformat(),
        "actor": {"type": "user", "id": ctx.user_id},                  # 1
        "action": proposal["tool"],
        "input_ref": ctx.input_ref,                                    # entrada guardada à parte
        "prompt_version": ctx.prompt_version,
        "model": ctx.model,
        "proposal": proposal["args"],                                  # 2
        "rationale": proposal.get("reason", ""),
        "shown_to_human": review.get("preview"),                       # 3
        "decision": review["decision"],
        "reviewer": review.get("reviewer"),
        "execution": execution,                                        # 4
        "prev_hash": prev["hash"] if prev else "genesis",
    }
    payload = canonical(event)
    event["hash"] = hashlib.sha256(payload.encode()).hexdigest()       # 6
    # 7. a tabela só tem permissão de INSERT para este serviço
    db.execute("INSERT INTO audit_log (event_id, body, hash) VALUES (%s, %s, %s)",
               (event["event_id"], payload, event["hash"]))
    return event

import { createHash, randomUUID } from "node:crypto";

type AuditEvent = {
  event_id: string; ts: string;
  actor: { type: "user" | "agent" | "reviewer"; id: string };
  action: string; input_ref: string; prompt_version: string; model: string;
  proposal: unknown; rationale: string; shown_to_human: unknown;
  decision: "approved" | "rejected" | "auto"; reviewer?: string;
  execution: { status: string; external_id?: string };
  prev_hash: string; hash?: string;
};

const canonical = (o: unknown): string =>
  JSON.stringify(o, (_k, v) =>
    v && typeof v === "object" && !Array.isArray(v)
      ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)))
      : v,
  );

export async function record(
  log: { lastHash(): Promise<string | null>; append(e: AuditEvent): Promise<void> },
  e: Omit<AuditEvent, "event_id" | "ts" | "prev_hash" | "hash">,
): Promise<AuditEvent> {
  const event: AuditEvent = {
    ...e,
    event_id: randomUUID(),
    ts: new Date().toISOString(),
    prev_hash: (await log.lastHash()) ?? "genesis",
  };
  event.hash = createHash("sha256").update(canonical(event)).digest("hex"); // 6
  await log.append(event); // 7. armazenamento só de acréscimo
  return event;
}

Teste seu entendimento