Auditoria e evidências

Cerca de 45 minutos min de leitura, com 9 exemplos em 9 seções.

Edição 2026.11.31 Exemplos aprovados em 19 de nov de 2026 108 de 108 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.31. Leia o original

Ao final deste capítulo, você será capaz de manter um registro de auditoria de cada decisão de acesso e de cada consulta, sem valores nele, encadeado de modo que qualquer edição apareça. Você o escreverá onde as decisões são tomadas e registrará a sua cabeça, isto é, o número e o hash do último registro, em um lugar onde o escritor do registro não possa alterá-la. Assim, uma edição em qualquer registro até essa cabeça, ou a remoção de qualquer um deles, ficará evidente. Você também aprenderá a explicar uma decisão antiga depois que a política tiver mudado, a confrontar o registro com o registro próprio do mecanismo de consulta sobre o que ele executou, e a gerar revisões de acesso e relatórios de evidências a partir do registro e das políticas, como código que qualquer pessoa possa executar novamente.

Quando o líder de suporte da plataforma de aprendizagem online que este livro governa pergunta por que um analista pôde ler o texto das avaliações na semana passada, ou quando um auditor pede que a plataforma demonstre que suas regras de acesso funcionam, ninguém consegue responder a partir dos registros. O capítulo 5 escreveu a política de acesso da plataforma em Rego, e a camada de imposição do capítulo 6, lib.enforce.Enforcer, pede à política uma decisão sobre cada tabela que uma consulta lê e reescreve a consulta para que DuckDB devolva apenas o que a decisão permite. A camada esquece cada decisão assim que a aplica. A solução óbvia, registrar o texto de cada consulta, cria uma segunda cópia do que a política protege: a consulta de um agente de suporte pode carregar o e-mail de um aluno na cláusula WHERE, e o capítulo 7 precisa apagar um aluno de todos os lugares aonde os dados dele foram.

Os termos do capítulo, como o livro os usa: um registro de auditoria é um registro de quem fez o quê, quando e com que resultado, mantido para que alguém possa verificá-lo depois. O registro de auditoria da plataforma contém um registro de decisão por consulta. Uma revisão da política é uma impressão digital de tudo de que uma decisão dependeu, além da requisição. Um registro é de adulteração evidente quando uma alteração nele pode ser detectada, embora não impedida. Uma revisão de acesso compara o que cada pessoa pode ler com o que ela de fato usa. Evidência é um relatório que mostra que um controle funciona, gerado a partir de registros, e não capturado de uma tela.

O código é o módulo compartilhado do livro lib.audit. Sua classe Audited envolve o Enforcer do capítulo 6 sem alterá-lo: ela grava um registro para cada consulta e só então deixa a camada executá-la. A maioria dos exemplos reproduz um dia de consultas da plataforma, lib.audit.DAY: 13 consultas em 1º de outubro de 2026, feitas por um agente de suporte, pelo financeiro, por um instrutor por meio do assistente do curso, pelo marketing, por um cientista de dados, pelo assistente em sua própria conta e por um usuário que a plataforma não conhece. Os exemplos executam DuckDB 2.0.0, sqlglot 30.33.0 e regopy 1.5.2.

Registre cada decisão onde ela é tomada

Última alteração na edição 2026.11.31

Um registro de auditoria só é tão completo quanto o que quem o escreve sabe. O motor de consultas conhece o SQL que executou, mas não sabe quem pediu nem por quê. A política conhece a sua decisão, mas não a consulta. Só a camada de imposição tem tudo isso ao mesmo tempo: o principal, isto é, o usuário ou programa que faz a solicitação, as tabelas e colunas que a consulta lê, a decisão de cada tabela e o SQL que ela entrega ao motor. É aí que o Open Policy Agent (OPA) escreve o seu próprio registro. Os logs de decisão do OPA contêm eventos que descrevem consultas de política, com a política consultada, a sua entrada, os metadados do bundle e outras informações que tornam possível a auditoria e a depuração offline (OPA, decision logs). Cada evento traz um decision_id, o path da regra consultada, o input, o result, um timestamp e bundles[_].revision, a revisão do bundle no momento da avaliação. O regopy, que executa a política dentro do Python, devolve apenas o valor da consulta e nada mais, de modo que a camada precisa montar ela mesma todos os outros campos.

O catálogo de controles de segurança do NIST oferece uma lista de verificação para esses campos. O controle AU-3 exige que os registros de auditoria estabeleçam seis coisas: (a) que tipo de evento ocorreu, (b) quando ocorreu, (c) onde, (d) a sua origem, (e) o seu resultado e (f) a identidade dos indivíduos, sujeitos ou objetos a ele associados (NIST SP 800-53 Rev. 5).

lib.audit.Audited recebe um catálogo e um Log, o arquivo de log de auditoria. O seu método sql recebe os mesmos argumentos que Enforcer.sql, mais via, o assistente que a enviou, quando houve um. Ele planeja a consulta, pergunta à política sobre cada tabela que a consulta lê, escreve um registro e só então entrega a consulta reescrita ao DuckDB. Assim, nenhuma consulta chega ao DuckDB por meio da camada sem um registro, e, quando o registro não pode ser escrito, a consulta não é executada. O Capítulo 6 deixou para este capítulo um caso: quando o assistente do curso responde instructor-17, a consulta é executada como o instrutor, e ambas as identidades pertencem ao log. A consulta do assistente para instructor-17, e a sua tentativa de associar nomes às avaliações, deixam cada uma um registro, mostrando o que um registro contém quando há duas identidades envolvidas:

decision-record.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""The course assistant's two queries, sent as instructor-17: one allowed, one denied, each recorded with both identities.The point rests on the `user` and `via` lines of both records and on the denial in record 2."""from lib import auditfrom lib.catalog import open_catalogfrom lib.enforce import Deniedfrom lib.platform import scratch# Chapter 6's enforcement layer, wrapped so that every query it's given is recorded before DuckDB runs anything.log = audit.Log(scratch() / "audit.jsonl")platform = audit.Audited(open_catalog(["crm.learners", "learning.reviews"]), log)# instructor-17 asks the course assistant how their reviews look. The assistant writes the SQL; the query runs as the# instructor, with the assistant recorded as the one that sent it.question = "select course_id, count(*) as reviews, round(avg(rating), 2) as rating from learning.reviews group by all"platform.sql(question, user="instructor-17", via="assistant-1").fetchall()# Then the assistant tries to put names to the ratings, which the instructor may not see. The denial is recorded before# it's raised, so the script only needs to go on.try:    platform.sql("select l.full_name, r.rating from learning.reviews as r join crm.learners as l using (learner_id)",                 user="instructor-17", via="assistant-1").fetchall()except Denied:    passfor record in log.records():    print(f"record {record['seq']}:")    print(audit.show(record))
Saídapython decision-record.py
record 1:
  seq: 1
  event: query
  time: 2026-10-01T09:00:00Z
  catalog: platform
  user: instructor-17
  via: assistant-1
  purpose: null
  query: SELECT course_id, COUNT(*) AS reviews, ROUND(AVG(rating), ?) AS rating FROM learning.reviews GROUP BY ALL
  outcome: allowed
  denial: null
  decision: {"table": "learning.reviews", "columns": ["course_id", "rating"], "allow": true, "row_filters": [{"column": "course_id", "in": [2, 75, 80, 87, 103, 134]}], "column_masks": {}, "reasons": ["instructor may read learning.reviews"]}
  policy_revision: f761e4ad08d4...
  rewritten_digest: 385c5cdabeae...
  prev_hash: 000000000000...
record 2:
  seq: 2
  event: query
  time: 2026-10-01T09:01:00Z
  catalog: platform
  user: instructor-17
  via: assistant-1
  purpose: null
  query: SELECT alias_1.full_name, alias_2.rating FROM learning.reviews AS alias_2 JOIN crm.learners AS alias_1 USING (learner_id)
  outcome: denied
  denial: instructor-17 may not read crm.learners: no group of this user may read this table
  decision: {"table": "crm.learners", "columns": ["full_name", "learner_id"], "allow": false, "row_filters": [], "column_masks": {}, "reasons": ["no group of this user may read this table"]}
  decision: {"table": "learning.reviews", "columns": ["learner_id", "rating"], "allow": true, "row_filters": [{"column": "course_id", "in": [2, 75, 80, 87, 103, 134]}], "column_masks": {}, "reasons": ["instructor may read learning.reviews"]}
  policy_revision: f761e4ad08d4...
  rewritten_digest: null
  prev_hash: 0d3e61eaadeb...

O registro 1 cobre os seis itens do AU-3. event é o tipo, e time indica quando, em UTC com um Z, já que o controle AU-8 pede carimbos de tempo que "usem o Tempo Universal Coordenado" ou declarem o seu deslocamento; os exemplos o tomam de um relógio fixo. catalog indica onde. user e via são a origem: a consulta foi executada como instructor-17, e assistant-1 a enviou. Junto com o table da decisão, elas são as identidades que o item f do AU-3 exige. query e o columns da decisão dizem o que foi lido, e outcome e o allow, row_filters, column_masks e reasons da decisão dizem como a consulta terminou, até os IDs de curso que o filtro de linhas manteve. As próximas seções explicam policy_revision, rewritten_digest e prev_hash.

O registro 2 é uma negação e contém as decisões de ambas as tabelas: a junção pode ler learning.reviews, mas não crm.learners, e uma tabela negada nega a consulta inteira. Sem via, o log diria que o instrutor tentou ler os nomes dos alunos. Com ele, um revisor sabe que o assistente escreveu aquela consulta e examina o comportamento do assistente tanto quanto o do instrutor.

Regra prática: Escreva o registro de auditoria na camada de imposição, onde se encontram o principal, a consulta e a decisão, e escreva-o antes de a consulta ser executada, de modo que uma falha na escrita interrompa a consulta. Registre cada identidade envolvida, a pessoa e qualquer assistente que atue em nome dela, e a decisão de cada tabela com os seus filtros, máscaras e motivos. Quando um motor impõe a política por conta própria, como o motor SQL Trino faz por meio do OPA, ative, em vez disso, o log de decisões do OPA e garanta que a sua entrada nomeie cada identidade envolvida: o opa.identity.extra-credentials-keys do Trino, por exemplo, encaminha as credenciais que ele lista "ao OPA como extraCredentials no contexto de identidade" (Trino 484, OPA access control).

Mantenha valores fora do registro

Última alteração na edição 2026.11.31

O registro de decisão guarda IDs, nomes de tabelas e de colunas, decisões e digests, e nenhum valor dos dados que sua consulta leu, porque tudo o que um log de auditoria guarda passa a ser dado a proteger. A discussão do NIST sobre o AU-3 alerta que a trilha de auditoria pode revelar informações pessoalmente identificáveis, sobretudo quando registra entradas, e seu aprimoramento AU-3(3) pede que o sistema limite essas informações nos registros de auditoria aos elementos que a avaliação de risco de privacidade nomeia (NIST SP 800-53 Rev. 5). Limitar, não remover: o item f do AU-3 pede o principal, por isso todo registro nomeia um, como instructor-17, a conta de um instrutor. O GDPR define dado pessoal como "qualquer informação relativa a uma pessoa singular identificada ou identificável" (GDPR, Artigo 4(1)), e uma pessoa é identificável direta ou indiretamente, em particular por meio de um identificador como um nome ou um identificador online. Um ID de conta como este pode ser esse identificador. A plataforma tem um motivo mais forte para manter os alunos fora: o capítulo 7 apaga um aluno de todas as tabelas que seus dados alcançaram, e apagar um registro da cadeia que este capítulo acrescenta não se distingue de adulteração.

O risco está no texto da consulta. Um agente de suporte que procura um aluno pelo e-mail de um chamado escreve esse e-mail na consulta. lib.audit.normalized mantém a forma da consulta e descarta seus valores: o sqlglot analisa a consulta, e cada literal, em qualquer sintaxe do DuckDB, torna-se ?. Também cada nome que o catálogo não contém, como um valor entre aspas duplas, exceto que um alias ou o nome de um CTE definido pela consulta torna-se alias_1, alias_2 e assim por diante. Os comentários, que podem conter qualquer coisa, são deixados de fora, e o motivo de uma negação é registrado com os mesmos valores retirados. O SQL que a camada entrega ao DuckDB é guardado apenas como rewritten_digest, um HMAC-SHA256 sob uma chave que só a camada possui, que a verificação cruzada confronta com o log do próprio DuckDB. O OPA parte da entrada inteira e pode ser instruído a descartar o que uma política nomear: "consulta o caminho data.system.log.mask antes de codificar e enviar os logs de decisão" (OPA, logs de decisão). A camada da plataforma nunca grava os valores.

Aqui agent-a05 procura um aluno da EMEA por e-mail e depois por ID, enquanto analyst-1 lê os e-mails dos alunos, que a política pseudonimiza. Nenhum valor é impresso; as linhas abaixo indicam onde cada um é guardado:

query-without-literals.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""A record keeps a query's shape and none of its values, while DuckDB's own query log keeps the email as it was typed.The printed lines the prose rests on are the asserts about the email and the four count lines at the end."""from lib import auditfrom lib.catalog import open_catalogfrom lib.platform import load, scratchlog = audit.Log(scratch() / "audit.jsonl")platform = audit.Audited(open_catalog(["crm.learners"]), log)# agent-a05 looks up an EMEA learner by the email in a ticket, then by their ID. Neither value is ever printed.learners = load("crm.learners").to_pylist()learner = next(row for row in learners if row["support_region"] == "emea")      # any EMEA learner will do, since the example needs only oneemail, learner_id = learner["email"], learner["learner_id"]platform.sql(f"select learner_id, full_name from crm.learners where email = '{email}'", "agent-a05").fetchall()platform.sql(f"select email, phone from crm.learners where learner_id = {learner_id}", "agent-a05").fetchall()platform.sql("select learner_id, email from crm.learners", "analyst-1").fetchall()      # pseudonymized with the keyfor record in log.records():    print("query in the record:", record["query"])engine = audit.engine_queries(platform.enforcer.connection)      # DuckDB's own query log, literals and allprint("the email, in the audit log:", email in log.path.read_text())assert email not in log.path.read_text()        # the record keeps `?` where the email was, so nothing matchesprint("the email, in DuckDB's query log:", any(email in query for query in engine))assert any(email in query for query in engine)  # DuckDB logs the SQL text it runs, literals includedprint("the pseudonymization key, in DuckDB's query log:", any(platform.enforcer.key in query for query in engine))assert not any(platform.enforcer.key in query for query in engine)print("its placeholder, in DuckDB's query log:", any("$pseudonym_key" in query for query in engine))assert any("$pseudonym_key" in query for query in engine)# Guessing which learner the agent looked up, from a list of the platform's emails: rebuild the text DuckDB ran with# each email, digest it, and compare. First with a plain SHA-256 of the query, as a log might keep, then with the# record's keyed digest, by someone without the layer's key and by someone who holds it.ran = next(query for query in engine if email in query)guesses = [ran.replace(email, row["email"]) for row in learners]    # the same text, with each learner's email in its placelogged = log.records()[0]["rewritten_digest"]                    # record 1 is the agent's lookup by emailprint("emails tried:", f"{len(guesses):,}")print("emails a plain SHA-256 of the query confirms:", sum(audit.sha256(g) == audit.sha256(ran) for g in guesses))print("emails the keyed digest confirms, without the layer's key:",      sum(audit.digest(g, "a-guessed-key") == logged for g in guesses))     # a wrong key, the only kind a guesser hasprint("emails the keyed digest confirms, with the layer's key:", sum(audit.digest(g, platform.key) == logged for g in guesses))
Saídapython query-without-literals.py
query in the record: SELECT learner_id, full_name FROM crm.learners WHERE email = ?
query in the record: SELECT email, phone FROM crm.learners WHERE learner_id = ?
query in the record: SELECT learner_id, email FROM crm.learners
the email, in the audit log: False
the email, in DuckDB's query log: True
the pseudonymization key, in DuckDB's query log: False
its placeholder, in DuckDB's query log: True
emails tried: 5,000
emails a plain SHA-256 of the query confirms: 1
emails the keyed digest confirms, without the layer's key: 0
emails the keyed digest confirms, with the layer's key: 1

Os registros guardam WHERE email = ? e WHERE learner_id = ?, e uma busca no log pelo e-mail não encontra nada. O log de consultas do DuckDB contém o e-mail, porque registra o texto SQL que o DuckDB executa, literais incluídos. A chave de pseudonimização não está ali: o capítulo 6 passa a chave como parâmetro, de modo que o log do DuckDB mostra o marcador $pseudonym_key onde a chave estaria.

Um resumo criptográfico com chave de uma consulta que continha um e-mail é um pseudônimo desse e-mail, e a chave é o que o mantém assim, como o capítulo 6 mostrou para os pseudônimos da plataforma. A reescrita é código no repositório, então qualquer pessoa com uma lista de e-mails, de uma exportação antiga ou de um vazamento, pode reconstruir o texto que o DuckDB executou para cada um e testá-lo. De 5,000 e-mails testados, um SHA-256 simples desse texto confirma 1: o aluno que o agente procurou. O resumo criptográfico com chave do registro confirma 0 sem a chave da camada, e 1 com ela. A chave permanece com a camada, longe de quem lê o log, e o mesmo vale para a verificação cruzada, que precisa dela.

O DuckDB recebe um valor de mais maneiras do que uma string entre aspas, e um nome também pode conter um. Um teste de regressão para normalized digita o mesmo e-mail, nome e ID do aluno nas consultas de agent-a05 de cada uma dessas maneiras. Essas requisições deixam estes rastros, um registro cada:

query-shape-hard-cases.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Eleven places to type a learner's values into a query, and what each record keeps of it: the query's shape, with a`?` for each value and each name the catalog doesn't hold, and a numbered alias for each alias or CTE the query defines.The printed count of records that hold the email, the name or the IDis the line the prose rests on."""import jsonimport refrom lib import auditfrom lib.catalog import open_catalogfrom lib.enforce import Deniedfrom lib.platform import load, scratchlog = audit.Log(scratch() / "audit.jsonl")platform = audit.Audited(open_catalog(["crm.learners"]), log)# An EMEA learner's email, name and ID, typed into agent-a05's queries as values and as names. None is ever printed.learner = next(row for row in load("crm.learners").to_pylist() if row["support_region"] == "emea")email, name, learner_id = learner["email"], learner["full_name"], learner["learner_id"]cases = {                                                 # each query puts the same values in one more way    "a string": f"select learner_id from crm.learners where email = '{email}'",    "a dollar-quoted string": f"select learner_id from crm.learners where email = $${email}$$",    "an escape string": f"select learner_id from crm.learners where email = e'{email}'",    "a list": f"select learner_id from crm.learners where email in ['{email}']",    "a number": f"select email from crm.learners where learner_id = {learner_id}",    "a comment": f"select email from crm.learners where learner_id = {learner_id} -- {name}",    "a name in double quotes": f'select learner_id from crm.learners where full_name = "{name}"',    # a column, to DuckDB    "a column alias": f'select learner_id as "{email}" from crm.learners',    "a table alias": f'select "{name}".email from crm.learners as "{name}"',    "a CTE's name": f'with "{email}" as (select learner_id from crm.learners) select learner_id from "{email}"',    "a table the catalog doesn't hold": f'select learner_id from "{email}"',}for query in cases.values():    try:        platform.sql(query, "agent-a05").fetchall()      # a denial is recorded, then raised: the script carries on    except Denied:        pass# What each record keeps of its query. The email or the name anywhere in its line, or the ID in what it keeps, is a# value that got through, and is never printed.held = []for case, line in zip(cases, log.lines()):               # one record per query, in the order they ran    record = json.loads(line)    kept = record["query"] + (f" (denied: {record['denial']})" if record["denial"] else "")    held.append(email in line or name in line or bool(re.search(rf"\b{learner_id}\b", kept)))     # the ID as a whole word    print(f"{case}:", "(holds a value)" if held[-1] else kept)print("records holding the email, the name or the ID:", sum(held), "of", len(cases))
Saídapython query-shape-hard-cases.py
a string: SELECT learner_id FROM crm.learners WHERE email = ?
a dollar-quoted string: SELECT learner_id FROM crm.learners WHERE email = ?
an escape string: SELECT learner_id FROM crm.learners WHERE email = ?
a list: SELECT learner_id FROM crm.learners WHERE email IN (?)
a number: SELECT email FROM crm.learners WHERE learner_id = ?
a comment: SELECT email FROM crm.learners WHERE learner_id = ?
a name in double quotes: SELECT learner_id FROM crm.learners WHERE full_name = ? (denied: Column '?' could not be resolved)
a column alias: SELECT learner_id AS alias_1 FROM crm.learners
a table alias: SELECT alias_1.email FROM crm.learners AS alias_1
a CTE's name: WITH alias_1 AS (SELECT learner_id FROM crm.learners) SELECT learner_id FROM alias_1
a table the catalog doesn't hold: SELECT learner_id FROM ? (denied: not a table in the catalog: "?")
records holding the email, the name or the ID: 0 of 11

Cada registro mantém a forma da consulta e nenhum de seus valores, tanto nas permitidas quanto nas negadas. A última linha conta os registros que contêm o e-mail, o nome ou o ID: 0 of 11.

Duas coisas se perdem. O texto normalizado também descarta valores e nomes inofensivos: no primeiro registro, ROUND(AVG(rating), 2) virou ROUND(AVG(rating), ?), e no segundo, os aliases r e l viraram alias_2 e alias_1. E o log não responde a "quem consultou este aluno?". Quando a plataforma precisar dessa resposta, por exemplo para um aluno que pergunta quem leu seus dados, guarde-a em um log de acesso separado, com IDs de alunos, um período de retenção e sem cadeia, que o apagamento do capítulo 7 alcança como qualquer outra tabela.

Regra prática: Registre a forma de uma consulta, nunca seus valores: substitua cada literal, em toda sintaxe que o motor aceita, e cada nome que o catálogo não contém, descarte os comentários, retire os mesmos valores dos motivos de negação, e guarde o SQL executado apenas como um resumo criptográfico com chave, cuja chave os leitores do log nunca recebem. Nunca use um hash simples de um texto que possa conter dados pessoais. Quando precisar saber quem leu os dados de uma pessoa, guarde isso em um log separado, que a retenção e o apagamento alcancem, e não no log à prova de adulteração.

Reproduza uma decisão antiga sob a política que a produziu

Última alteração na edição 2026.11.31

Um registro de decisão guarda a requisição, mas uma decisão depende de três coisas: a requisição, as regras da política e os dados que a política lê. As duas últimas mudam o tempo todo. A política da plataforma lê governance/users.toml, governance/metadata.toml e learning.courses, como o capítulo 5 estabeleceu; assim, um agente de suporte transferido para outra região, ou um curso adicionado a learning.courses, muda decisões sem que ninguém toque no Rego. Se um registro não diz nada sobre qual era a política, sua decisão não pode ser explicada depois que qualquer uma das duas mudar: reproduzida mais tarde, ela dá uma resposta diferente, e o log parece errado. O OPA registra a versão da política como bundles[_].revision. Para políticas que chamam funções integradas não determinísticas, como o horário ou uma requisição HTTP, o OPA também pode registrar os resultados delas em nd_builtin_cache, que existe para depuração e reprodução de decisões (OPA, logs de decisão). A política da plataforma não chama nenhuma delas.

lib.audit.bundle reúne os módulos da política e seu documento de dados, os fatos que a política lê, gerados a partir dessas três fontes, como o OPA as distribui em um bundle. lib.audit.revision é o SHA-256 desse bundle: uma impressão digital que muda quando qualquer regra muda, ou qualquer fato que a política lê. Cada registro carrega a revisão que o decidiu. lib.audit.Archive mantém todos os bundles que a camada já usou, sob a sua revisão, de modo que uma decisão possa ser refeita sob a política que a tomou. Um bundle contém regras e os atributos dos usuários da plataforma, não dados sobre os aprendizes; por isso, o arquivo pode ser mantido pelo mesmo tempo que o log.

Na plataforma, analyst-1 lê os e-mails dos aprendizes e obtém pseudônimos. Suponha que um pull request posterior o inclua no suporte para EMEA, a mudança que o capítulo 6 identificou com seu teste de quem-vê-o-quê. O registro antigo é reproduzido sob cada revisão:

explain-old-decision.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Replays a logged decision under the revision it was made with and under the current one, after a change to the usersfile alone. The printed email and match lines are the point: only the archived revision explains the record."""from lib import audit, policyfrom lib.catalog import open_catalogfrom lib.platform import scratchfolder = scratch()archive = audit.Archive(folder / "bundles")         # every policy revision that has decided anything, by revisionlog = audit.Log(folder / "audit.jsonl")# analyst-1 reads learners' emails, which the policy pseudonymizes.platform = audit.Audited(open_catalog(["crm.learners"]), log, archive=archive)platform.sql("select learner_id, email from crm.learners", "analyst-1").fetchall()record = log.records()[0]# Later, a pull request adds analyst-1 to support for EMEA, as in chapter 6. Only users.toml changes, which reaches# the policy through its data document, and no Rego.data = policy.data_document()data["platform"]["users"]["analyst-1"] = {"groups": ["data-science", "support"], "region": "emea"}current, logged = audit.bundle(data=data), archive.get(record["policy_revision"])     # the bundle the record was decided underprint("logged under revision:", record["policy_revision"][:12])print("current revision:", audit.revision(current)[:12])modules_changed = current["modules"] != logged["modules"]assert not modules_changed                      # no Rego changed, so the policy modules are the sameprint("policy modules changed:", modules_changed)data_changed = current["data"] != logged["data"]assert data_changed                             # the data document is the only part that changedprint("data document changed:", data_changed)# Explain the logged decision by making it again, from the request the record holds, under each revision.print("email, as logged:", record["decisions"][0]["column_masks"].get("email", "shown as stored"))for name, revision in [("the current revision", current), ("the logged revision", logged)]:    again = audit.replay(record, revision)    matches = again == record["decisions"]    assert matches == (revision is logged)      # only the revision the record was decided under explains it    print(f"under {name}, email:", again[0]["column_masks"].get("email", "shown as stored"))    print(f"under {name}, the decision matches the log:", matches)
Saídapython explain-old-decision.py
logged under revision: f761e4ad08d4
current revision: 0350e789b34d
policy modules changed: False
data document changed: True
email, as logged: pseudonymize
under the current revision, email: shown as stored
under the current revision, the decision matches the log: False
under the logged revision, email: pseudonymize
under the logged revision, the decision matches the log: True

A revisão mudou, de f761e4ad08d4 para 0350e789b34d, embora nenhum Rego tenha mudado. Os módulos da política são os mesmos, e o documento de dados, que agora lista a nova associação, não é. Uma impressão digital apenas dos arquivos da política teria deixado passar a mudança. Reproduzida sob a revisão atual, a decisão não coincide com o log: email é shown as stored, porque o suporte vê os dados de contato. Um investigador que tivesse apenas a política atual concluiria que o log, ou a camada, estava errado. Reproduzido sob a revisão registrada, obtida do arquivo, email é novamente pseudonymize, e a decisão coincide com o log.

A reprodução explica a decisão, não as linhas. Um filtro de linhas é reproduzido como uma regra, como a região do suporte ou o filtro de consentimento learner_consented, e quais linhas passaram por ele dependia dos dados daquele dia, que podem ter mudado desde então ou sido apagados. Essa separação é intencional: o log diz qual era a regra, e as tabelas, com seus próprios snapshots e retenção, dizem o que ela selecionou.

Regra prática: Atribua a cada decisão um hash de tudo de que ela dependeu além da requisição: os módulos da política e o seu documento de dados, juntos. Arquive cada revisão pelo tempo que você mantiver o log, e explique uma decisão antiga reproduzindo-a sob a sua própria revisão, nunca sob a atual. Se uma política lê o relógio ou chama outro serviço, registre também esses resultados, como faz o nd_builtin_cache do OPA.

Encadeie os registros para que uma edição apareça

Última alteração na edição 2026.11.31

Os registros de decisão da plataforma só servem como evidência se uma alteração neles puder ser detectada. A SP 800-53 pede que os sistemas "Protect audit information and audit logging tools from unauthorized access, modification, and deletion" (AU-9), e, em AU-9(3), que "Implement cryptographic mechanisms to protect the integrity of audit information and audit tools". A discussão de AU-9(3) oferece, como exemplo, "signed hash functions using asymmetric cryptography" (NIST SP 800-53 Rev. 5), que só quem detém uma chave privada consegue produzir. A cadeia da plataforma, abaixo, não é isso, e não protege nada por si só. O guia de gestão de logs do NIST, SP 800-92, descreve o mecanismo mais simples: um resumo criptográfico (message digest) para cada arquivo de log, armazenado com segurança, de modo que uma alteração em um log arquivado seja detectada (NIST SP 800-92). O guia é de 2006. Ele cita MD5 e SHA-1 como os resumos comuns de sua época, e sua própria nota de rodapé 25 recomenda o SHA-256, que a plataforma usa.

Um resumo por arquivo detecta a alteração de um arquivo fechado. Uma cadeia de hashes detecta a alteração de um log que ainda está crescendo: cada registro carrega um número de sequência, seq, e o SHA-256 da linha anterior, prev_hash, de modo que alterar um registro quebra o vínculo com o seguinte, e remover um deixa uma lacuna. lib.audit.check percorre a cadeia e informa cada quebra. Uma cadeia evidencia a adulteração, mas não a impede. Schneier e Kelsey projetaram um log no qual um atacante que assuma o controle da máquina de registro não consegue ler nem falsificar as entradas escritas antes. Mesmo assim, o atacante "can delete a block of entries (or the entire log file)", e a parte confiável à qual o log reporta só percebe na próxima vez em que a máquina se comunica com ela (Schneier and Kelsey, 1999). Uma cadeia simples como a da plataforma é mais fraca: quem puder escrever no arquivo pode reconstruí-la, renumerando à medida que avança. Assim, o que ela prova depende da cabeça da cadeia, o número de registros e o hash do último deles, anotados em um lugar onde quem escreve o log não consegue alterá-los. Uma edição ou remoção de qualquer registro até essa cabeça aparece, por mais que seja escondida. Depois da cabeça, uma cadeia reconstruída ou cortada passa em todas as verificações, e sem cabeça, também passa uma cadeia reconstruída desde o início. check usa a cabeça como âncora.

Para testar a cadeia, o exemplo reexecuta lib.audit.DAY, as 13 consultas que a plataforma recebeu em 1º de outubro, e anota a cabeça ao meio-dia, no registro 9. Em seguida, adultera cópias do log de cinco maneiras. Antes do meio-dia, o registro 3, a consulta de agent-a05 aos dados de contato de um aluno, é repassada a outro agente, uma vez como edição simples e outra com a cadeia reconstruída. Depois do meio-dia, o registro 12, a leitura negada feita por someone-else, o usuário que a plataforma não conhece, é removido, uma vez de forma simples e outra com a cadeia reconstruída; e os dois últimos registros do dia são cortados. Antes de executar, preveja quais das cinco a cadeia encontra por conta própria, e quais contra a cabeça do meio-dia.

chain-catches-edit.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Replays the day's queries into a chained log, writes the head down at noon, then tampers with copies of the log fiveways and checks each against the chain alone and against the noon head. The point rests on the two checks of eachchange: the chain finds the plain edit and the plain removal on its own, and only the head finds the rebuilt chain."""import jsonfrom lib import auditfrom lib.catalog import open_catalogfrom lib.platform import scratchlog = audit.Log(scratch() / "audit.jsonl")platform = audit.Audited(open_catalog(["crm.learners", "learning.reviews", "billing.payments", "support.tickets"]), log)audit.run_day(platform, [query for query in audit.DAY if query[0] < "12:00"])     # the morning; times compare as stringsanchor = log.head()                               # the head, written down at noon somewhere the log's writer can't reachaudit.run_day(platform, [query for query in audit.DAY if query[0] >= "12:00"])    # the afternoonlines = log.lines()print("records:", len(lines))print("head written down at noon, at record:", anchor["records"])print("record 3:", json.loads(lines[2])["user"], "reads", json.loads(lines[2])["query"])     # record 3 is index 2def rechained(lines: list[str]) -> list[str]:    """The chain built again, every record renumbered and every prev_hash recomputed: what anyone who can rewrite the    log's file can do."""    rebuilt, previous = [], audit.GENESIS          # the first record points at 64 zeros, not at a record    for seq, line in enumerate(lines, start=1):        rebuilt.append(audit.canonical(json.loads(line) | {"seq": seq, "prev_hash": previous}))        previous = audit.sha256(rebuilt[-1])    return rebuilt# Before noon, record 3 handed to another agent. After noon, record 12 (someone-else's denied read) removed, and the# day's last two records cut off.edited = lines[:2] + [audit.canonical(json.loads(lines[2]) | {"user": "agent-a01"})] + lines[3:]     # index 2 is record 3removed = lines[:11] + lines[12:]                                                                    # index 11 is record 12for name, version in [("untouched", lines), ("record 3 edited", edited), ("record 3 edited, chain rebuilt", rechained(edited)),                      ("record 12 removed", removed), ("record 12 removed, chain rebuilt", rechained(removed)),                      ("last 2 records removed", lines[:-2])]:    print(f"{name}, checked alone:", "; ".join(audit.check(version)) or "no problem found")    print(f"{name}, checked against the noon head:", "; ".join(audit.check(version, anchor)) or "no problem found")
Saídapython chain-catches-edit.py
records: 13
head written down at noon, at record: 9
record 3: agent-a05 reads SELECT full_name, email, phone FROM crm.learners WHERE learner_id = ?
untouched, checked alone: no problem found
untouched, checked against the noon head: no problem found
record 3 edited, checked alone: record 3 was changed: record 4 doesn't follow it
record 3 edited, checked against the noon head: record 3 was changed: record 4 doesn't follow it
record 3 edited, chain rebuilt, checked alone: no problem found
record 3 edited, chain rebuilt, checked against the noon head: the chain no longer passes through the head written down at record 9
record 12 removed, checked alone: record 12 is missing: record 13 follows record 11
record 12 removed, checked against the noon head: record 12 is missing: record 13 follows record 11
record 12 removed, chain rebuilt, checked alone: no problem found
record 12 removed, chain rebuilt, checked against the noon head: no problem found
last 2 records removed, checked alone: no problem found
last 2 records removed, checked against the noon head: no problem found

Por conta própria, a cadeia detecta a edição simples, record 3 was changed: record 4 doesn't follow it, e a remoção simples, record 12 is missing: record 13 follows record 11, e mais nada. Ela deixa passar as duas cadeias reconstruídas, que são consistentes do início ao fim, e o corte, pois nenhum registro vem depois do último para denunciá-lo.

Uma cabeça protege apenas os registros escritos antes dela. Contra a cabeça do meio-dia, a edição feita antes do meio-dia ainda aparece mesmo com a cadeia reconstruída, the chain no longer passes through the head written down at record 9. Tudo o que foi escondido depois do meio-dia passa: a remoção com a cadeia reconstruída dá no problem found, e o corte dá no problem found.

Por isso, a regra sobre valores não é opcional. Apagar um aluno de um log encadeado significa alterar ou remover um registro, e onde uma verificação consegue enxergar isso, ela não consegue distingui-lo de adulteração. Um log que não guarda dados sobre alunos não encontra o apagamento do capítulo 7. Os identificadores de quem faz consultas são outro assunto: dê ao log um período de retenção e inicie uma nova cadeia a cada período, com sua última cabeça anotada, para que um período inteiro possa ser excluído quando expirar.

Verificar uma cadeia exige reler todos os registros. Crosby e Wallach descrevem logs em forma de árvore que podem provar "that individual logged events are still present, and that the log, as seen now, is consistent with how it was seen in the past", com provas de tamanho logarítmico, uma melhoria sobre construções lineares anteriores (Crosby and Wallach, 2009). Para o log próprio de uma plataforma, recomendamos uma cadeia verificada diariamente, e uma árvore quando partes externas auditarem um log grande demais para ser relido.

Regra prática: Encadeie cada registro ao anterior com SHA-256 e um número de sequência, e conte com a cadeia para proteger apenas os registros até a última cabeça anotada fora do controle da camada. Anote a cabeça com frequência, em um armazenamento somente de acréscimo ou em outro sistema com outras credenciais, tantas vezes quanto o número de registros desprotegidos que você puder aceitar; se esse número for zero, envie cada registro para fora da máquina assim que for escrito. Verifique a cadeia contra a última cabeça de forma agendada. Se você precisar do que AU-9(3) descreve, faça com que cada cabeça seja assinada por um sistema cuja chave a camada nunca possui. Nunca encadeie um registro que possa, um dia, precisar ser apagado em nome de uma só pessoa; deixe períodos inteiros expirarem.

Faça a verificação cruzada do log contra o log de consultas do DuckDB

Última alteração na edição 2026.11.27

O log de auditoria da plataforma registra cada consulta que passa pela camada de imposição, e somente essas. Uma consulta executada diretamente na conexão DuckDB da camada, por um auxiliar de notebook ou por um teste que recebeu a conexão, não recebe decisão nem registro. Percebê-la exige um segundo registro, mantido pelo próprio motor. O DuckDB 2.0.0 tem um, desativado por padrão: seu framework de logging possui um tipo QueryLog, que registra as consultas que o DuckDB executa, ativado com CALL enable_logging('QueryLog') e lido na view duckdb_logs (DuckDB, logging). Uma configuração separada, log_query_path, indica um arquivo para onde as consultas são registradas (DuckDB, configuração), e a conexão da camada recusa essa opção, como mostra a seção sobre produção.

O log do DuckDB não é um log de auditoria. Cada entrada guarda o texto SQL, com os IDs de conexão, de transação e de consulta, além de um carimbo de tempo: nenhum usuário e nenhuma decisão. Ele enxerga apenas a consulta reescrita, e pertence ao processo que ele registra. O que ele pode fazer é verificar o log de auditoria: toda consulta que o DuckDB executou deve corresponder ao SQL que algum registro de decisão lhe entregou. Audited liga o log do DuckDB e bloqueia a configuração da conexão ao iniciar. Audited.check_engine_log compara cada consulta do log do DuckDB, por meio de um digest com chave, com o rewritten_digest dos registros escritos desde a última verificação e, em seguida, esvazia o log do DuckDB, que guarda os valores das consultas. A consulta de uma relação é executada “quando um método da seção Output lê a relação, e é executada novamente a cada leitura” (DuckDB, API relacional), e uma relação restringida executa um SQL próprio, que nenhum registro entregou ao DuckDB. Por isso, Audited.sql busca cada resultado por conta própria, uma única vez, e devolve as linhas como uma relação em uma conexão própria: o que quer que quem chama faça com ela, o log do DuckDB guarda cada consulta permitida uma única vez.

A primeira verificação reexecuta as consultas do dia (13 registros) e as confere. Em seguida, duas consultas a mais passam pela camada, uma que quem chama nunca busca e outra que é restringida a cinco linhas, e um auxiliar de notebook lê o e-mail de um aluno com a conexão da camada, por fora da camada. Segue-se uma segunda verificação:

query-log-cross-check.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""DuckDB's query log checked against the audit log: first on the day's queries, then after two more queries through thelayer and a read around it. The point rests on the last check's unrecorded query, the one read that bypassed the layer."""from lib import auditfrom lib.catalog import open_catalogfrom lib.platform import scratchlog = audit.Log(scratch() / "audit.jsonl")platform = audit.Audited(open_catalog(["crm.learners", "learning.reviews", "billing.payments", "support.tickets"]), log)day = audit.run_day(platform)print("queries allowed:", day["allowed"])print("queries denied:", day["denied"])# DuckDB's own query log, kept on the layer's connection, against the records written since the last check. The check# then empties DuckDB's log, which holds the queries' values.found = platform.check_engine_log()print("queries DuckDB ran:", found["engine queries"])print("queries DuckDB ran with no decision record:", len(found["unrecorded"]))# Two more queries through the layer: one whose caller never fetches it, and one the caller narrows to five rows.platform.sql("select learner_id, country from crm.learners", "analyst-1")        # the layer fetches it, so DuckDB logs it onceplatform.sql("select learner_id, country from crm.learners", "analyst-1").limit(5).fetchall()    # narrowed after the layer's fetch# Then a notebook helper that was handed the layer's connection reads a learner's email with it, around the layer.platform.enforcer.connection.sql("select email from crm.learners where learner_id = 541").fetchall()    # no record for this onefound = platform.check_engine_log()print("next check, records checked:", " to ".join(map(str, found["records checked"])))print("next check, queries with no decision record:", len(found["unrecorded"]))for query in found["unrecorded"]:    print("unrecorded:", query)print("next check, decision records DuckDB has no query for:", len(found["not in the engine log"]))
Saídapython query-log-cross-check.py
queries allowed: 9
queries denied: 4
queries DuckDB ran: 9
queries DuckDB ran with no decision record: 0
next check, records checked: 14 to 15
next check, queries with no decision record: 1
unrecorded: SELECT email FROM crm.learners WHERE learner_id = ?
next check, decision records DuckDB has no query for: 0

A verificação cruzada associa as consultas do dia aos seus registros: 9 foram permitidas e 4 negadas, e o DuckDB executou 9: uma para cada consulta permitida e nenhuma para as negadas, e 0 sem registro.

A próxima verificação encontra a leitura por fora da camada e mais nada. A verificação cobre os registros 14 to 15, as duas consultas pela camada, e não dispara alarme. A leitura por fora da camada aparece como 1 consulta sem registro de decisão, impressa sem os seus valores. A última linha verifica no sentido inverso, para registros de cuja consulta o DuckDB não tem rastro: 0 aqui.

O que a verificação detecta depende de quem tem a conexão. Ela detecta uma leitura por fora da camada feita por código que não mexe no log do DuckDB, como este auxiliar de notebook, um teste ou um job que recebeu a conexão por engano. Ela não detecta código que tem a conexão e pretende se esconder. Uma leitura feita após uma verificação, com o log do DuckDB esvaziado de novo antes da próxima consulta da camada, não deixa nada para nenhuma das duas direções encontrar. E a função write_log do DuckDB recebe o tipo de log como argumento, de modo que pode gravar entradas QueryLog (código-fonte do DuckDB, v2.0.0); o bloqueio de configuração não impede uma função. Uma garantia contra esse tipo de código exige que o log do motor seja gravado fora do processo que tem a conexão.

A verificação também encontra os atalhos próprios da camada, como o observe do capítulo 6, que lê a tabela armazenada na conexão da camada sem nenhum usuário por trás. Dê a essas consultas registros próprios, com a camada como usuário, em vez de exceções na verificação.

Regra prática: Ative o log de consultas nativo do motor sempre que impuser políticas, busque cada resultado dentro da camada e verifique o log periodicamente contra os registros escritos desde a última verificação, nos dois sentidos: toda consulta executada pelo motor deve corresponder a um registro, e todo registro permitido deve corresponder a uma consulta. Depois, esvazie o log, pois ele guarda os valores das consultas. Trate uma divergência como um incidente a ser explicado, não como ruído a ser filtrado. Conte com a verificação para pegar erros, não código que tem a conexão e pretende ocultar algo: contra isso, só um log gravado fora do processo ajuda. Nunca use o log do motor como log de auditoria: ele não tem usuário nem decisão.

Gerar a revisão de acesso a partir do registro

Última alteração na edição 2026.11.27

O registro de auditoria da plataforma diz o que cada pessoa leu, e a política diz o que cada pessoa pode ler; uma revisão de acesso põe os dois lado a lado. A SP 800-53 pede que as organizações revisem contas quanto à conformidade com os requisitos de gestão de contas (AC-2 j), e que revisem, em frequência definida, os privilégios atribuídos a papéis e classes, para validar a necessidade deles, reatribuindo-os ou removendo-os quando necessário (AC-6(7)) (NIST SP 800-53 Rev. 5). Uma lista de quem ocupa cada papel não responde a nenhuma das duas, porque não diz nada sobre necessidade. Código pode calcular os fatos de que uma revisão precisa: o que a política permite a cada pessoa, o que o registro mostra que ela usou, o que lhe foi negado e as associações a grupos que não apontam para nada. Decidir se o acesso será removido continua sendo uma decisão dos responsáveis pelos dados.

lib.audit.review avalia a política da plataforma para cada usuário em users.toml contra cada tabela, lê o registro e lista, para cada usuário, as tabelas que ele pode ler, as tabelas que ele leu, as concessões que não usou, suas consultas negadas com o assistente que as enviou, e tudo o que alguém deveria analisar. Para dar a ele algo defasado para encontrar, o exemplo adiciona analyst-2 aos usuários, ainda listado em bi, um grupo que a política não tem mais, como acontece quando um grupo é desativado e ninguém edita o arquivo de usuários:

access-review.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""An access review of every user in the users file, and every user the log names, against the policy and the day's log,with a stale group membership added to find. The printed `look at` lines and the grants-not-used count are what the proserests on."""from lib import audit, policyfrom lib.catalog import open_catalogfrom lib.platform import TABLES, scratchlog = audit.Log(scratch() / "audit.jsonl")platform = audit.Audited(open_catalog(["crm.learners", "learning.reviews", "billing.payments", "support.tickets"]), log)audit.run_day(platform)      # the day's queries, so that the review has a log to read# users.toml as the review finds it: analyst-2 is still listed in bi, a group the policy no longer has.data = policy.data_document()data["platform"]["users"]["analyst-2"] = {"groups": ["bi"]}rows = audit.review(audit.bundle(data=data), log.records(), TABLES)      # all eight of the platform's tablesfor row in rows:    print(f"{row['user']}: may read {len(row['may read'])}, read {len(row['read'])}, denied {row['denied']}"          + (f" (sent by {', '.join(row['denied via'])})" if row["denied via"] else ""))    if row["unused"]:            # a grant unused: a table the policy lets the user read, and the log never shows them reading        print("  not used:", ", ".join(row["unused"]))    for finding in row["findings"]:        print("  look at:", finding)print("users reviewed:", len(rows))print("grants not used:", sum(len(row["unused"]) for row in rows))print("users to look at:", sum(bool(row["findings"]) for row in rows))     # any finding at all needs a personprint("denied queries flagged at:", audit.settings()["review"]["denied_queries_flagged"])     # from governance/audit.toml
Saídapython access-review.py
agent-a01: may read 2, read 0, denied 0
  not used: crm.learners, support.tickets
agent-a05: may read 2, read 2, denied 0
agent-a09: may read 2, read 0, denied 0
  not used: crm.learners, support.tickets
analyst-1: may read 6, read 2, denied 0
  not used: billing.payments, learning.courses, learning.enrollments, learning.events
analyst-2: may read 0, read 0, denied 0
  look at: in group bi, which the policy doesn't know
assistant-1: may read 2, read 1, denied 0
  not used: learning.courses
finance-1: may read 3, read 1, denied 0
  not used: learning.courses, learning.enrollments
instructor-17: may read 3, read 1, denied 3 (sent by assistant-1)
  not used: learning.courses, learning.enrollments
  look at: 3 denied queries
marketing-1: may read 2, read 1, denied 0
  not used: learning.courses
someone-else: may read 0, read 0, denied 1
  look at: not in users.toml
users reviewed: 10
grants not used: 14
users to look at: 3
denied queries flagged at: 3

Em 1º de outubro, o dia que lib.audit.DAY reproduz, 14 concessões não foram usadas, e agent-a01 e agent-a09 não leram nada. Um dia é curto demais para remover o acesso de quem quer que seja, já que o suporte trabalha em turnos e as finanças leem algumas tabelas apenas quando fecham o mês; portanto, estas contagens são indícios, não decisões. Uma concessão não usada durante um período inteiro de revisão, como um trimestre, é o que deve ser levado ao responsável pela tabela. 3 usuários precisam de uma pessoa que os analise:

  • analyst-2 está em um grupo que nenhuma regra conhece. A associação não concede nada hoje e concederia o que uma futura regra para bi permitir, por isso remova-a.
  • someone-else não está em users.toml, portanto uma entidade que a plataforma não conhece tentou ler os e-mails dos alunos.
  • A linha de instructor-17 mostra may read 3, read 1, denied 3 (sent by assistant-1). Nos dois minutos após responder à primeira pergunta do instrutor, o assistente tentou alunos, depois alunos unidos a avaliações, depois chamados. Isso é um assistente testando tabelas uma a uma, e sem via a revisão teria culpado o instrutor.

O limite para sinalização, a partir de 3 consultas negadas, é uma regra empírica, mantida em governance/audit.toml com sua justificativa, para que alterá-lo seja uma mudança revisada, como uma mudança de política.

Regra prática: Gere revisões de acesso a partir da política e do registro de auditoria, nunca a partir de uma lista de associações a papéis: o que cada pessoa pode ler contra o que leu, suas negações e as associações a grupos que a política já não reconhece. Execute-as em um período longo o bastante para o ritmo de todos os trabalhos, como um trimestre, e envie cada achado ao responsável pela tabela ou pelo grupo a que se refere. Remova uma concessão que ninguém usou no período, a menos que seu responsável explique por que ela é necessária.

Produza evidência como dados

Última alteração na edição 2026.11.27

A verificação da cadeia, o cruzamento e a revisão de acessos valem mais quando alguém de fora da equipe pode verificá-los. O Regulamento Geral de Proteção de Dados (RGPD) da UE impõe esse dever à organização, como seu princípio de responsabilização: "O responsável pelo tratamento é responsável pelo cumprimento do disposto no n.º 1 e tem de poder comprová-lo ('responsabilidade')" (RGPD, artigo 5.º, n.º 2). O que conta como comprovar é questão para juristas; esta seção mostra o que o código pode produzir. Os procedimentos de avaliação do NIST para gestão de contas nomeiam os registros que um avaliador examina, entre eles registros de autorização de acesso, revisões de conformidade da gestão de contas e registros de auditoria do sistema (NIST SP 800-53A Rev. 5, no catálogo OSCAL do NIST). Uma captura de tela de um console não é nenhum deles: ninguém consegue executá-la de novo, compará-la com a do trimestre passado nem dizer qual política ela mostrava.

lib.audit.evidence monta o relatório da plataforma a partir de registros e código, nestas seções:

  • a política, com o resumo criptográfico de cada módulo e do documento de dados;
  • os testes unitários da política, do capítulo 5;
  • a tabela de quem vê o quê, verificada contra a política;
  • a cobertura de classificação, a partir das verificações de metadados do capítulo 2;
  • a verificação da cadeia do log de auditoria;
  • o cruzamento com o log do DuckDB;
  • as eliminações que o log registra;
  • a revisão de acessos.

Cada seção indica a revisão da política com que foi calculada, os resumos criptográficos de suas entradas e o que alguém precisa para calculá-la de novo: o pacote arquivado, os arquivos de teste, metadata.toml e os esquemas das tabelas, o log de auditoria. O cruzamento com o motor só pode ser calculado de novo em parte, e a seção diz isso. Ela guarda o resumo criptográfico com chave de cada consulta que o DuckDB executou, de modo que quem tiver o log pode refazer suas duas contagens; mas só a camada podia ler o log do DuckDB, uma única vez, antes de esvaziá-lo. Gere o relatório de 1 de outubro, com cada tabela e saída de pipeline do catálogo, a eliminação de um aluno registrada às 07:00 do capítulo 7, e as consultas do dia:

evidence-report.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""The platform on Oct 1, after an erasure and the day's queries: the first evidence report, written to a file as data, witheach section's result printed. The printed checks, the erasure's lines and the head are what the prose rests on."""import jsonfrom datetime import timedeltafrom lib import audit, retentionfrom lib.platform import scratch# The platform on Oct 1: every table and pipeline output, chapter 7's erasure of learner 3590 at 07:00, then the day's# queries through the audited layer.catalog, graph = retention.open_platform(statistics_off=True)      # statistics off for personal columns: each table rewritten under them, old files sweptlog = audit.Log(scratch() / "audit.jsonl")_, found, done = retention.erase_everywhere(catalog, graph, 3590, "erasure-0001", min_age=timedelta(0))    # zero: no file age guardaudit.record_erasure(log, "erasure-0001", done, retention.scan(catalog, found), at=audit.MIDNIGHT.replace(hour=7))platform = audit.Audited(catalog, log)audit.run_day(platform)# The first report, so there's no head from an earlier one to check the chain against.report = audit.evidence(platform, catalog, anchor=None)reports = scratch()          # in production, another system, which the log's writer can't change(reports / "evidence-2026-10-01.json").write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")result = {name: section["result"] for name, section in report.items()}print("sections:", ", ".join(report))print("policy tests passed:", f"{result['policy tests']['passed']} of {result['policy tests']['of']}")print("who-sees-what cases the policy agrees with:", f"{result['who sees what']['agree']} of {result['who sees what']['of']}")for problem in result["classification coverage"]["problems"]:    print("classification problem:", problem)print("audit log records:", result["audit log"]["records"])print("chain problems, checked alone:", len(result["audit log"]["chain problems"]))print("queries DuckDB ran with no decision record:", len(result["engine cross-check"]["unrecorded"]))print("decision records DuckDB has no query for:", len(result["engine cross-check"]["not in the engine log"]))for erasure in result["erasures"]:    print(f"erasure {erasure['request']}: {erasure['rows_deleted']} rows deleted, "          f"{erasure['files_holding_the_person']} of {erasure['files_read']} files hold the person")    for kept in erasure["kept"]:        print(f"erasure {erasure['request']}, kept under an exception: {kept['table']}, decided by {kept['decided_by']},",              f"{', '.join(kept['columns_erased'])} erased")print("chain head written down, at record:", report["audit log"]["inputs"]["head"]["records"])     # the next report's anchorprint("engine cross-check, computed again from:", "; ".join(report["engine cross-check"]["computed again from"]))print("engine cross-check, not computed again:", report["engine cross-check"]["not computed again"])
Saídapython evidence-report.py
sections: policy, policy tests, who sees what, classification coverage, audit log, engine cross-check, erasures, access review
policy tests passed: 12 of 12
who-sees-what cases the policy agrees with: 12 of 12
classification problem: ai.review_corpus: no metadata
classification problem: marketing.audience: no metadata
audit log records: 14
chain problems, checked alone: 0
queries DuckDB ran with no decision record: 0
decision records DuckDB has no query for: 0
erasure erasure-0001: 25 rows deleted, 0 of 115 files hold the person
erasure erasure-0001, kept under an exception: billing.payments, decided by legal team, card_number erased
chain head written down, at record: 14
engine cross-check, computed again from: the audit log; the engine digests, for the two counts
engine cross-check, not computed again: the reading of DuckDB's log, and the unrecorded queries' shapes: the layer read that log once, then emptied it

O relatório mostra o que falha tanto quanto o que passa, porque um relatório que só mostra verificações aprovadas não é evidência de nada. A política passa em 12 of 12 testes unitários e concorda com 12 of 12 casos de quem vê o quê. A cobertura de classificação não está limpa: ai.review_corpus e marketing.audience não têm metadados, as lacunas que os capítulos 2 e 4 encontraram e que a política, enquanto isso, trata como sensíveis.

As verificações do próprio log voltam limpas, mas provam menos do que parecem. A cadeia tem 0 problemas, verificada isoladamente, já que nenhum relatório anterior registrou a ponta da cadeia. O cruzamento pega erros, não código que pretende esconder (acima). O DuckDB executou 0 consultas sem registro de decisão, e 0 registros de decisão não têm consulta.

As linhas da eliminação, 25 rows deleted, 0 of 115 files hold the person e billing.payments, decided by legal team, card_number erased, vêm da eliminação do capítulo 7, como o log a registra: o ID da solicitação, as tabelas, as contagens, cada tabela com uma exceção mantida pelo motivo que governance/retention.toml informa, e o resultado da varredura, nunca o ID ou os valores do aluno, de modo que o registro pode ser encadeado com segurança. O Conselho Europeu para a Proteção de Dados recomenda que os responsáveis pelo tratamento "Verifiquem que a eliminação foi realizada e consigam comprová-la" (CEPD, 2026); esta linha registra o que a própria varredura da plataforma encontrou. O relatório também registra a ponta da cadeia, no registro 14. Guardada em outro sistema, ela é a âncora contra a qual o próximo relatório verifica a cadeia: uma edição ou remoção de qualquer registro até ela aparecerá então, e um registro posterior só fica protegido quando uma ponta posterior o cobrir.

O relatório não afirma nada sobre nenhuma lei ou arcabouço. Ele declara o que foi verificado, sob qual política, a partir de quais entradas e com que resultado.

Regra prática: Gere evidência a partir de registros com código, em intervalos regulares e a cada mudança de política, e carimbe cada seção com a revisão da política, os resumos criptográficos de suas entradas e o que é preciso para calculá-la de novo, dizendo quais partes ninguém consegue. Guarde os relatórios onde quem escreve no log não possa alterá-los, inclua os achados que falham em vez de filtrá-los, e faça cada relatório verificar a cadeia contra a ponta que o anterior registrou. Nunca envie uma captura de tela quando um relatório puder ser gerado; o capítulo 10 executa verificações como essas em cada pull request.

O que dá errado em produção

Última alteração na edição 2026.11.27

Nada quebra quando um rastro de auditoria deixa de ser completo, verdadeiro ou lido. A falha que mais importa é o log que o código auditado pode desligar, e o log de consultas do DuckDB é desse tipo: ele pertence ao processo que registra. Duas camadas de imposição de regras enfrentam o mesmo ataque. A primeira não bloqueia sua configuração, como qualquer camada construída sem lib.audit; o código que detém sua conexão tenta registrar em um arquivo, desliga o log e, em seguida, lê o e-mail de um aluno contornando a camada. A segunda é a de lib.audit, bloqueada; esse código tenta desligar o log, lê contornando a camada e, depois, esvazia o log:

query-log-switched-off.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Code holding a layer's connection tries to switch DuckDB's query log off, first on a layer that doesn't lock itsconfiguration and then on one that does. The printed lines show the switch working on the first, failing on the second,and the gap that emptying the log leaves in the second layer's check."""import duckdbfrom lib import auditfrom lib.catalog import open_catalogfrom lib.platform import scratchAROUND = "select email from crm.learners where learner_id = 541"       # a read around the enforcement layerfolder = scratch()# A layer that doesn't lock its configuration: code holding its connection tries a file log, then switches logging off.unlocked = audit.Audited(open_catalog(["crm.learners"]), audit.Log(folder / "unlocked.jsonl"), lock=False)connection = unlocked.enforcer.connectiontry:    connection.execute("set log_query_path = 'queries.log'")       # the layer's connection refuses to write a fileexcept duckdb.Error as error:    print("a query log in a file, on the layer's connection:", type(error).__name__)connection.execute("CALL disable_logging()")                       # nothing stops the switch hereconnection.sql(AROUND).fetchall()                                  # so this read leaves nothing in DuckDB's logfor query in unlocked.check_engine_log()["unrecorded"]:            # only the statements made before the switch remain    print("unlocked, unrecorded:", query)# lib.audit's layer locks its configuration: switching the log off is refused, but emptying it isn't.log = audit.Log(folder / "locked.jsonl")locked = audit.Audited(open_catalog(["crm.learners"]), log)locked.sql("select learner_id, email from crm.learners", "analyst-1").fetchall()     # its entry in DuckDB's log is emptied belowconnection = locked.enforcer.connectiontry:    connection.execute("CALL disable_logging()")except duckdb.Error as error:    print("locked, disable_logging():", type(error).__name__)connection.sql(AROUND).fetchall()connection.execute("CALL truncate_duckdb_logs()")                  # emptying isn't locked, so the log loses its entriesfound = locked.check_engine_log()print("locked, after truncate_duckdb_logs(), queries with no decision record:", len(found["unrecorded"]))print("locked, decision records DuckDB has no query for:", len(found["not in the engine log"]))
Saídapython query-log-switched-off.py
a query log in a file, on the layer's connection: PermissionException
unlocked, unrecorded: CALL disable_logging()
unlocked, unrecorded: SET log_query_path = ?
locked, disable_logging(): InvalidInputException
locked, after truncate_duckdb_logs(), queries with no decision record: 0
locked, decision records DuckDB has no query for: 1

Na camada sem bloqueio, disable_logging() funciona, e a leitura que vem em seguida não deixa rastro. A verificação cruzada encontra apenas as instruções anteriores ao silêncio: a SET log_query_path recusada e a própria CALL disable_logging(). A recusa aparece como PermissionException, porque o capítulo 6 proíbe que a conexão da camada acesse arquivos.

Na camada bloqueada, desligar o log falha, mas esvaziá-lo não. Desligar falha com InvalidInputException, mas truncate_duckdb_logs() funciona, e depois a verificação encontra 0 consultas sem registro. A verificação no sentido inverso percebe a lacuna: 1 registro de decisão não tem consulta no log do DuckDB, então algo esvaziou o log. Ela só percebe porque um registro caiu no trecho esvaziado; um código que regrava as entradas com write_log deixaria o log com aparência íntegra.

Nada disso impede o código que detém a conexão. Em produção, aplique a regra em um motor que roda como serviço próprio, como o Trino com OPA, de modo que seu log seja gravado fora do processo de quem faz consultas. Armazene os registros de auditoria em outro sistema, como pede o controle AU-9(2): “Armazenar os registros de auditoria [Atribuição: frequência] em um repositório que faça parte de um sistema ou componente fisicamente diferente do sistema ou componente auditado” (NIST SP 800-53 Rev. 5). Recomendamos enviar cada registro no momento em que é gravado e manter, mais uma vez, a cabeça da cadeia em outro lugar.

Mais três maneiras pelas quais o rastro falha:

  • Logs que ninguém lê. O guia do NIST sobre gestão de logs defende a leitura deles: revisões de rotina ajudam a identificar incidentes de segurança, violações de política, atividades fraudulentas e problemas operacionais logo após ocorrerem (§2.2, NIST SP 800-92). Um log que apenas é gravado custa armazenamento e não protege nada. Agende a revisão de acesso e o relatório de evidências, atribua um responsável a cada achado e configure alertas para o que não pode esperar um trimestre, como um usuário sinalizado por consultas negadas.
  • Decisões que não podem ser explicadas depois que uma política mudou. Um registro sem uma revisão da política, ou uma revisão sem um pacote arquivado, é reexecutado sob a política atual e se contradiz. Calcule a impressão digital do documento de dados junto com as regras, pois uma mudança no documento de dados altera decisões tão certamente quanto uma mudança nas regras.
  • Logs que guardam dados pessoais. Dados pessoais chegam aos logs por muitos caminhos: literais das consultas, o próprio log de consultas do motor, mensagens de erro que imprimem valores, como o capítulo 6 mostrou para os erros de conversão do DuckDB, e a saída de depuração da camada. Os avisos de um analisador sintático são mais um: o aviso do sqlglot quando ele mantém uma instrução como texto cita a instrução (código-fonte do sqlglot, v30.24.0), então lib.audit silencia o sqlglot enquanto ele analisa a consulta de um usuário. Restrinja o log de auditoria a IDs e resumos criptográficos, e defina para todos os outros logs um período de retenção que a eliminação alcance.
  • Um log de decisões que não está completo. O OPA pode descartar eventos de decisão por regra, por meio de system.log.drop, e “O OPA descartará eventos se o limite de taxa for excedido” (OPA, logs de decisão). Confronte o número de consultas do motor com os registros de decisão, como faz a verificação cruzada, em vez de presumir que toda decisão foi registrada.
  • Uma cabeça da cadeia guardada junto ao log. Uma âncora armazenada onde quem escreve o log pode alterá-la não detecta nada que a cadeia não detecte. Mantenha-a em outro sistema, sob outras credenciais.

O que este capítulo decidiu

Última alteração na edição 2026.11.27
  • Um registro por consulta, gravado pela camada de imposição antes de a consulta ser executada. lib.audit.Audited envolve o Enforcer do capítulo 6 sem alterá-lo e busca cada resultado por conta própria. O registro cobre os seis itens da AU-3, entre eles o principal e o assistente que enviou a consulta.
  • Os registros guardam IDs, nunca valores. Todo literal, em qualquer uma das sintaxes do DuckDB, e todo nome que o catálogo não contém são substituídos, tanto na consulta quanto no motivo da negação, e os comentários são removidos. O SQL que o DuckDB executou é mantido como um resumo HMAC-SHA256 sob uma chave que só a camada possui, pois, com a chave, o resumo confirma um palpite. As exclusões são registradas pelo ID da solicitação.
  • Todo registro indica a revisão da sua política, o SHA-256 dos módulos da política e do documento de dados, e toda revisão é arquivada para reprodução.
  • Os registros são encadeados com SHA-256 e numerados, e a cadeia protege apenas os registros até a última cabeça da cadeia anotada fora do controle da camada. Cada relatório de evidências anota a cabeça; recomendamos fazer isso com mais frequência.
  • O log de consultas do DuckDB serve como verificação cruzada de erros, não como o log de auditoria. A camada o ativa, bloqueia sua configuração, confere-o nos dois sentidos com os registros desde a última verificação e, então, o esvazia. Código que tenha a conexão pode burlá-lo.
  • As revisões de acesso e os relatórios de evidências são gerados a partir da política, do log e do catálogo, com cada seção marcada com a revisão da política e com suas entradas. O limite para sinalizar consultas negadas, 3, é uma regra prática em governance/audit.toml. Uma trilha de auditoria só vale o que vale aquilo que o código auditado não consegue alterar, e as verificações deste capítulo indicam quais partes do sistema ele consegue alterar. O registro que importa é aquele que o código auditado não tem como desligar.

Este capítulo, nesta edição

Edição 2026.11.31Exemplos aprovados em 19 de nov de 20269 de 9 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.31.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 8 de 10: Auditoria e evidências

  1. Registre cada decisão onde ela é tomada
  2. Mantenha valores fora do registro
  3. Reproduza uma decisão antiga sob a política que a produziu
  4. Encadeie os registros para que uma edição apareça
  5. Faça a verificação cruzada do log contra o log de consultas do DuckDB
  6. Gerar a revisão de acesso a partir do registro
  7. Produza evidência como dados
  8. O que dá errado em produção
  9. O que este capítulo decidiu

Voltar ao topoTodos os capítulos