Auditoria e evidências
Cerca de 45 minutos min de leitura, com 9 exemplos em 9 seções.
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
Nesta página
- Registre cada decisão onde ela é tomada
- Mantenha valores fora do registro
- Reproduza uma decisão antiga sob a política que a produziu
- Encadeie os registros para que uma edição apareça
- Faça a verificação cruzada do log contra o log de consultas do DuckDB
- Gerar a revisão de acesso a partir do registro
- Produza evidência como dados
- O que dá errado em produção
- O que este capítulo decidiu
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
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:
1"""The course assistant's two queries, sent as instructor-17: one allowed, one denied, each recorded with both identities.2The point rests on the `user` and `via` lines of both records and on the denial in record 2."""3from lib import audit4from lib.catalog import open_catalog5from lib.enforce import Denied6from lib.platform import scratch78# Chapter 6's enforcement layer, wrapped so that every query it's given is recorded before DuckDB runs anything.9log = audit.Log(scratch() / "audit.jsonl")10platform = audit.Audited(open_catalog(["crm.learners", "learning.reviews"]), log)1112# instructor-17 asks the course assistant how their reviews look. The assistant writes the SQL; the query runs as the13# instructor, with the assistant recorded as the one that sent it.14question = "select course_id, count(*) as reviews, round(avg(rating), 2) as rating from learning.reviews group by all"15platform.sql(question, user="instructor-17", via="assistant-1").fetchall()1617# Then the assistant tries to put names to the ratings, which the instructor may not see. The denial is recorded before18# it's raised, so the script only needs to go on.19try:20 platform.sql("select l.full_name, r.rating from learning.reviews as r join crm.learners as l using (learner_id)",21 user="instructor-17", via="assistant-1").fetchall()22except Denied:23 pass2425for record in log.records():26 print(f"record {record['seq']}:")27 print(audit.show(record))
python decision-record.pyrecord 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
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:
1"""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.2The printed lines the prose rests on are the asserts about the email and the four count lines at the end."""3from lib import audit4from lib.catalog import open_catalog5from lib.platform import load, scratch67log = audit.Log(scratch() / "audit.jsonl")8platform = audit.Audited(open_catalog(["crm.learners"]), log)910# agent-a05 looks up an EMEA learner by the email in a ticket, then by their ID. Neither value is ever printed.11learners = load("crm.learners").to_pylist()12learner = next(row for row in learners if row["support_region"] == "emea") # any EMEA learner will do, since the example needs only one13email, learner_id = learner["email"], learner["learner_id"]14platform.sql(f"select learner_id, full_name from crm.learners where email = '{email}'", "agent-a05").fetchall()15platform.sql(f"select email, phone from crm.learners where learner_id = {learner_id}", "agent-a05").fetchall()16platform.sql("select learner_id, email from crm.learners", "analyst-1").fetchall() # pseudonymized with the key1718for record in log.records():19 print("query in the record:", record["query"])20engine = audit.engine_queries(platform.enforcer.connection) # DuckDB's own query log, literals and all21print("the email, in the audit log:", email in log.path.read_text())22assert email not in log.path.read_text() # the record keeps `?` where the email was, so nothing matches23print("the email, in DuckDB's query log:", any(email in query for query in engine))24assert any(email in query for query in engine) # DuckDB logs the SQL text it runs, literals included25print("the pseudonymization key, in DuckDB's query log:", any(platform.enforcer.key in query for query in engine))26assert not any(platform.enforcer.key in query for query in engine)27print("its placeholder, in DuckDB's query log:", any("$pseudonym_key" in query for query in engine))28assert any("$pseudonym_key" in query for query in engine)2930# Guessing which learner the agent looked up, from a list of the platform's emails: rebuild the text DuckDB ran with31# each email, digest it, and compare. First with a plain SHA-256 of the query, as a log might keep, then with the32# record's keyed digest, by someone without the layer's key and by someone who holds it.33ran = next(query for query in engine if email in query)34guesses = [ran.replace(email, row["email"]) for row in learners] # the same text, with each learner's email in its place35logged = log.records()[0]["rewritten_digest"] # record 1 is the agent's lookup by email36print("emails tried:", f"{len(guesses):,}")37print("emails a plain SHA-256 of the query confirms:", sum(audit.sha256(g) == audit.sha256(ran) for g in guesses))38print("emails the keyed digest confirms, without the layer's key:",39 sum(audit.digest(g, "a-guessed-key") == logged for g in guesses)) # a wrong key, the only kind a guesser has40print("emails the keyed digest confirms, with the layer's key:", sum(audit.digest(g, platform.key) == logged for g in guesses))
python query-without-literals.pyquery 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:
1"""Eleven places to type a learner's values into a query, and what each record keeps of it: the query's shape, with a2`?` for each value and each name the catalog doesn't hold, and a numbered alias for each alias or CTE the query defines.3The printed count of records that hold the email, the name or the ID4is the line the prose rests on."""5import json6import re78from lib import audit9from lib.catalog import open_catalog10from lib.enforce import Denied11from lib.platform import load, scratch1213log = audit.Log(scratch() / "audit.jsonl")14platform = audit.Audited(open_catalog(["crm.learners"]), log)1516# An EMEA learner's email, name and ID, typed into agent-a05's queries as values and as names. None is ever printed.17learner = next(row for row in load("crm.learners").to_pylist() if row["support_region"] == "emea")18email, name, learner_id = learner["email"], learner["full_name"], learner["learner_id"]19cases = { # each query puts the same values in one more way20 "a string": f"select learner_id from crm.learners where email = '{email}'",21 "a dollar-quoted string": f"select learner_id from crm.learners where email = $${email}$$",22 "an escape string": f"select learner_id from crm.learners where email = e'{email}'",23 "a list": f"select learner_id from crm.learners where email in ['{email}']",24 "a number": f"select email from crm.learners where learner_id = {learner_id}",25 "a comment": f"select email from crm.learners where learner_id = {learner_id} -- {name}",26 "a name in double quotes": f'select learner_id from crm.learners where full_name = "{name}"', # a column, to DuckDB27 "a column alias": f'select learner_id as "{email}" from crm.learners',28 "a table alias": f'select "{name}".email from crm.learners as "{name}"',29 "a CTE's name": f'with "{email}" as (select learner_id from crm.learners) select learner_id from "{email}"',30 "a table the catalog doesn't hold": f'select learner_id from "{email}"',31}3233for query in cases.values():34 try:35 platform.sql(query, "agent-a05").fetchall() # a denial is recorded, then raised: the script carries on36 except Denied:37 pass3839# What each record keeps of its query. The email or the name anywhere in its line, or the ID in what it keeps, is a40# value that got through, and is never printed.41held = []42for case, line in zip(cases, log.lines()): # one record per query, in the order they ran43 record = json.loads(line)44 kept = record["query"] + (f" (denied: {record['denial']})" if record["denial"] else "")45 held.append(email in line or name in line or bool(re.search(rf"\b{learner_id}\b", kept))) # the ID as a whole word46 print(f"{case}:", "(holds a value)" if held[-1] else kept)47print("records holding the email, the name or the ID:", sum(held), "of", len(cases))
python query-shape-hard-cases.pya 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
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:
1"""Replays a logged decision under the revision it was made with and under the current one, after a change to the users2file alone. The printed email and match lines are the point: only the archived revision explains the record."""3from lib import audit, policy4from lib.catalog import open_catalog5from lib.platform import scratch67folder = scratch()8archive = audit.Archive(folder / "bundles") # every policy revision that has decided anything, by revision9log = audit.Log(folder / "audit.jsonl")1011# analyst-1 reads learners' emails, which the policy pseudonymizes.12platform = audit.Audited(open_catalog(["crm.learners"]), log, archive=archive)13platform.sql("select learner_id, email from crm.learners", "analyst-1").fetchall()14record = log.records()[0]1516# Later, a pull request adds analyst-1 to support for EMEA, as in chapter 6. Only users.toml changes, which reaches17# the policy through its data document, and no Rego.18data = policy.data_document()19data["platform"]["users"]["analyst-1"] = {"groups": ["data-science", "support"], "region": "emea"}20current, logged = audit.bundle(data=data), archive.get(record["policy_revision"]) # the bundle the record was decided under21print("logged under revision:", record["policy_revision"][:12])22print("current revision:", audit.revision(current)[:12])23modules_changed = current["modules"] != logged["modules"]24assert not modules_changed # no Rego changed, so the policy modules are the same25print("policy modules changed:", modules_changed)26data_changed = current["data"] != logged["data"]27assert data_changed # the data document is the only part that changed28print("data document changed:", data_changed)2930# Explain the logged decision by making it again, from the request the record holds, under each revision.31print("email, as logged:", record["decisions"][0]["column_masks"].get("email", "shown as stored"))32for name, revision in [("the current revision", current), ("the logged revision", logged)]:33 again = audit.replay(record, revision)34 matches = again == record["decisions"]35 assert matches == (revision is logged) # only the revision the record was decided under explains it36 print(f"under {name}, email:", again[0]["column_masks"].get("email", "shown as stored"))37 print(f"under {name}, the decision matches the log:", matches)
python explain-old-decision.pylogged 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
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.
1"""Replays the day's queries into a chained log, writes the head down at noon, then tampers with copies of the log five2ways and checks each against the chain alone and against the noon head. The point rests on the two checks of each3change: the chain finds the plain edit and the plain removal on its own, and only the head finds the rebuilt chain."""4import json56from lib import audit7from lib.catalog import open_catalog8from lib.platform import scratch910log = audit.Log(scratch() / "audit.jsonl")11platform = audit.Audited(open_catalog(["crm.learners", "learning.reviews", "billing.payments", "support.tickets"]), log)12audit.run_day(platform, [query for query in audit.DAY if query[0] < "12:00"]) # the morning; times compare as strings13anchor = log.head() # the head, written down at noon somewhere the log's writer can't reach14audit.run_day(platform, [query for query in audit.DAY if query[0] >= "12:00"]) # the afternoon15lines = log.lines()16print("records:", len(lines))17print("head written down at noon, at record:", anchor["records"])18print("record 3:", json.loads(lines[2])["user"], "reads", json.loads(lines[2])["query"]) # record 3 is index 2192021def rechained(lines: list[str]) -> list[str]:22 """The chain built again, every record renumbered and every prev_hash recomputed: what anyone who can rewrite the23 log's file can do."""24 rebuilt, previous = [], audit.GENESIS # the first record points at 64 zeros, not at a record25 for seq, line in enumerate(lines, start=1):26 rebuilt.append(audit.canonical(json.loads(line) | {"seq": seq, "prev_hash": previous}))27 previous = audit.sha256(rebuilt[-1])28 return rebuilt293031# Before noon, record 3 handed to another agent. After noon, record 12 (someone-else's denied read) removed, and the32# day's last two records cut off.33edited = lines[:2] + [audit.canonical(json.loads(lines[2]) | {"user": "agent-a01"})] + lines[3:] # index 2 is record 334removed = lines[:11] + lines[12:] # index 11 is record 1235for name, version in [("untouched", lines), ("record 3 edited", edited), ("record 3 edited, chain rebuilt", rechained(edited)),36 ("record 12 removed", removed), ("record 12 removed, chain rebuilt", rechained(removed)),37 ("last 2 records removed", lines[:-2])]:38 print(f"{name}, checked alone:", "; ".join(audit.check(version)) or "no problem found")39 print(f"{name}, checked against the noon head:", "; ".join(audit.check(version, anchor)) or "no problem found")
python chain-catches-edit.pyrecords: 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
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:
1"""DuckDB's query log checked against the audit log: first on the day's queries, then after two more queries through the2layer and a read around it. The point rests on the last check's unrecorded query, the one read that bypassed the layer."""3from lib import audit4from lib.catalog import open_catalog5from lib.platform import scratch67log = audit.Log(scratch() / "audit.jsonl")8platform = audit.Audited(open_catalog(["crm.learners", "learning.reviews", "billing.payments", "support.tickets"]), log)9day = audit.run_day(platform)10print("queries allowed:", day["allowed"])11print("queries denied:", day["denied"])1213# DuckDB's own query log, kept on the layer's connection, against the records written since the last check. The check14# then empties DuckDB's log, which holds the queries' values.15found = platform.check_engine_log()16print("queries DuckDB ran:", found["engine queries"])17print("queries DuckDB ran with no decision record:", len(found["unrecorded"]))1819# Two more queries through the layer: one whose caller never fetches it, and one the caller narrows to five rows.20platform.sql("select learner_id, country from crm.learners", "analyst-1") # the layer fetches it, so DuckDB logs it once21platform.sql("select learner_id, country from crm.learners", "analyst-1").limit(5).fetchall() # narrowed after the layer's fetch22# Then a notebook helper that was handed the layer's connection reads a learner's email with it, around the layer.23platform.enforcer.connection.sql("select email from crm.learners where learner_id = 541").fetchall() # no record for this one24found = platform.check_engine_log()25print("next check, records checked:", " to ".join(map(str, found["records checked"])))26print("next check, queries with no decision record:", len(found["unrecorded"]))27for query in found["unrecorded"]:28 print("unrecorded:", query)29print("next check, decision records DuckDB has no query for:", len(found["not in the engine log"]))
python query-log-cross-check.pyqueries 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
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:
1"""An access review of every user in the users file, and every user the log names, against the policy and the day's log,2with a stale group membership added to find. The printed `look at` lines and the grants-not-used count are what the prose3rests on."""4from lib import audit, policy5from lib.catalog import open_catalog6from lib.platform import TABLES, scratch78log = audit.Log(scratch() / "audit.jsonl")9platform = audit.Audited(open_catalog(["crm.learners", "learning.reviews", "billing.payments", "support.tickets"]), log)10audit.run_day(platform) # the day's queries, so that the review has a log to read1112# users.toml as the review finds it: analyst-2 is still listed in bi, a group the policy no longer has.13data = policy.data_document()14data["platform"]["users"]["analyst-2"] = {"groups": ["bi"]}15rows = audit.review(audit.bundle(data=data), log.records(), TABLES) # all eight of the platform's tables1617for row in rows:18 print(f"{row['user']}: may read {len(row['may read'])}, read {len(row['read'])}, denied {row['denied']}"19 + (f" (sent by {', '.join(row['denied via'])})" if row["denied via"] else ""))20 if row["unused"]: # a grant unused: a table the policy lets the user read, and the log never shows them reading21 print(" not used:", ", ".join(row["unused"]))22 for finding in row["findings"]:23 print(" look at:", finding)24print("users reviewed:", len(rows))25print("grants not used:", sum(len(row["unused"]) for row in rows))26print("users to look at:", sum(bool(row["findings"]) for row in rows)) # any finding at all needs a person27print("denied queries flagged at:", audit.settings()["review"]["denied_queries_flagged"]) # from governance/audit.toml
python access-review.pyagent-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-2está em um grupo que nenhuma regra conhece. A associação não concede nada hoje e concederia o que uma futura regra parabipermitir, por isso remova-a.someone-elsenão está emusers.toml, portanto uma entidade que a plataforma não conhece tentou ler os e-mails dos alunos.- A linha de
instructor-17mostramay 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 semviaa 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
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:
1"""The platform on Oct 1, after an erasure and the day's queries: the first evidence report, written to a file as data, with2each section's result printed. The printed checks, the erasure's lines and the head are what the prose rests on."""3import json4from datetime import timedelta56from lib import audit, retention7from lib.platform import scratch89# The platform on Oct 1: every table and pipeline output, chapter 7's erasure of learner 3590 at 07:00, then the day's10# queries through the audited layer.11catalog, graph = retention.open_platform(statistics_off=True) # statistics off for personal columns: each table rewritten under them, old files swept12log = audit.Log(scratch() / "audit.jsonl")13_, found, done = retention.erase_everywhere(catalog, graph, 3590, "erasure-0001", min_age=timedelta(0)) # zero: no file age guard14audit.record_erasure(log, "erasure-0001", done, retention.scan(catalog, found), at=audit.MIDNIGHT.replace(hour=7))15platform = audit.Audited(catalog, log)16audit.run_day(platform)1718# The first report, so there's no head from an earlier one to check the chain against.19report = audit.evidence(platform, catalog, anchor=None)20reports = scratch() # in production, another system, which the log's writer can't change21(reports / "evidence-2026-10-01.json").write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")22result = {name: section["result"] for name, section in report.items()}23print("sections:", ", ".join(report))24print("policy tests passed:", f"{result['policy tests']['passed']} of {result['policy tests']['of']}")25print("who-sees-what cases the policy agrees with:", f"{result['who sees what']['agree']} of {result['who sees what']['of']}")26for problem in result["classification coverage"]["problems"]:27 print("classification problem:", problem)28print("audit log records:", result["audit log"]["records"])29print("chain problems, checked alone:", len(result["audit log"]["chain problems"]))30print("queries DuckDB ran with no decision record:", len(result["engine cross-check"]["unrecorded"]))31print("decision records DuckDB has no query for:", len(result["engine cross-check"]["not in the engine log"]))32for erasure in result["erasures"]:33 print(f"erasure {erasure['request']}: {erasure['rows_deleted']} rows deleted, "34 f"{erasure['files_holding_the_person']} of {erasure['files_read']} files hold the person")35 for kept in erasure["kept"]:36 print(f"erasure {erasure['request']}, kept under an exception: {kept['table']}, decided by {kept['decided_by']},",37 f"{', '.join(kept['columns_erased'])} erased")38print("chain head written down, at record:", report["audit log"]["inputs"]["head"]["records"]) # the next report's anchor39print("engine cross-check, computed again from:", "; ".join(report["engine cross-check"]["computed again from"]))40print("engine cross-check, not computed again:", report["engine cross-check"]["not computed again"])
python evidence-report.pysections: 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
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:
1"""Code holding a layer's connection tries to switch DuckDB's query log off, first on a layer that doesn't lock its2configuration and then on one that does. The printed lines show the switch working on the first, failing on the second,3and the gap that emptying the log leaves in the second layer's check."""4import duckdb56from lib import audit7from lib.catalog import open_catalog8from lib.platform import scratch910AROUND = "select email from crm.learners where learner_id = 541" # a read around the enforcement layer11folder = scratch()1213# A layer that doesn't lock its configuration: code holding its connection tries a file log, then switches logging off.14unlocked = audit.Audited(open_catalog(["crm.learners"]), audit.Log(folder / "unlocked.jsonl"), lock=False)15connection = unlocked.enforcer.connection16try:17 connection.execute("set log_query_path = 'queries.log'") # the layer's connection refuses to write a file18except duckdb.Error as error:19 print("a query log in a file, on the layer's connection:", type(error).__name__)20connection.execute("CALL disable_logging()") # nothing stops the switch here21connection.sql(AROUND).fetchall() # so this read leaves nothing in DuckDB's log22for query in unlocked.check_engine_log()["unrecorded"]: # only the statements made before the switch remain23 print("unlocked, unrecorded:", query)2425# lib.audit's layer locks its configuration: switching the log off is refused, but emptying it isn't.26log = audit.Log(folder / "locked.jsonl")27locked = audit.Audited(open_catalog(["crm.learners"]), log)28locked.sql("select learner_id, email from crm.learners", "analyst-1").fetchall() # its entry in DuckDB's log is emptied below29connection = locked.enforcer.connection30try:31 connection.execute("CALL disable_logging()")32except duckdb.Error as error:33 print("locked, disable_logging():", type(error).__name__)34connection.sql(AROUND).fetchall()35connection.execute("CALL truncate_duckdb_logs()") # emptying isn't locked, so the log loses its entries36found = locked.check_engine_log()37print("locked, after truncate_duckdb_logs(), queries with no decision record:", len(found["unrecorded"]))38print("locked, decision records DuckDB has no query for:", len(found["not in the engine log"]))
python query-log-switched-off.pya 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.auditsilencia 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
- Um registro por consulta, gravado pela camada de imposição antes de a consulta ser executada.
lib.audit.Auditedenvolve oEnforcerdo 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.