Auditoría y evidencia
Unos 38 minutos de lectura, con 9 ejemplos en 9 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.31. Lee el original
En esta página
- Registra cada decisión donde se toma
- Mantén los valores fuera del registro
- Repetir una decisión antigua con su propia política
- Encadena los registros para que una edición se note
- Contrasta el registro con el registro de consultas de DuckDB
- Genera la revisión de accesos a partir del registro
- Producir evidencia como datos
- Qué sale mal en producción
- Lo que decidió este capítulo
Al terminar este capítulo podrás llevar un registro de auditoría de cada decisión de acceso y de cada consulta, sin valores en su interior y encadenado de forma que cualquier edición quede en evidencia. Lo escribirás en el punto donde se toman las decisiones, y anotarás su cabeza, es decir, el número y el hash de su último registro, en un lugar donde el escritor del registro no pueda modificarlo. Así, cualquier edición o eliminación de un registro hasta esa cabeza quedará al descubierto. También aprenderás a explicar una decisión antigua después de que la política haya cambiado, a contrastar el registro con el propio registro del motor de consultas sobre lo que ejecutó, y a generar revisiones de acceso e informes de evidencia a partir del registro y de las políticas, como código que cualquiera pueda volver a ejecutar.
Cuando el responsable de soporte de la plataforma de aprendizaje en línea que gobierna este libro pregunta por qué un analista pudo leer el texto de las reseñas la semana pasada, o cuando un auditor le pide demostrar que sus reglas de acceso funcionan, nadie puede responder a partir de los registros. El capítulo 5 escribió la política de acceso de la plataforma en Rego, y la capa de cumplimiento del capítulo 6, lib.enforce.Enforcer, solicita a la política una decisión sobre cada tabla que lee una consulta y reescribe la consulta para que DuckDB devuelva solo lo que la decisión permite. Una vez aplicada, la capa olvida cada decisión. La solución evidente, registrar el texto de cada consulta, crea una segunda copia de lo que la política protege: la consulta de un agente de soporte puede contener el correo electrónico de un estudiante en su cláusula WHERE, y el capítulo 7 tiene que borrar a un estudiante de todos los lugares a los que llegaron sus datos.
Los términos del capítulo, tal como los usa el libro: un registro de auditoría es un registro de quién hizo qué, cuándo y con qué resultado, conservado para que alguien pueda verificarlo después. El registro de auditoría de la plataforma contiene un registro de decisión por cada consulta. Una revisión de la política es una huella digital de todo aquello de lo que dependió una decisión, además de la petición. Un registro es a prueba de manipulaciones cuando un cambio en él puede detectarse, aunque no impedirse. Una revisión de acceso compara lo que cada persona puede leer con lo que realmente usa. La evidencia es un informe que demuestra que un control funciona, generado a partir de registros y no capturado de una pantalla.
El código es el módulo compartido del libro, lib.audit. Su clase Audited envuelve el Enforcer del capítulo 6 sin modificarlo: escribe un registro por cada consulta y después deja que la capa la ejecute. La mayoría de los ejemplos reproducen un día de consultas de la plataforma, lib.audit.DAY: 13 consultas del 1 de octubre de 2026, realizadas por un agente de soporte, por finanzas, por un instructor a través del asistente del curso, por marketing, por un científico de datos, por el asistente con su propia cuenta y por un usuario que la plataforma no conoce. Los ejemplos usan DuckDB 2.0.0, sqlglot 30.33.0 y regopy 1.5.2.
Registra cada decisión donde se toma
Un registro de auditoría solo es tan completo como lo que sabe quien lo escribe. El motor de consultas conoce el SQL que ejecutó, pero no quién lo pidió ni por qué. La política conoce su decisión, pero no la consulta. Solo la capa de cumplimiento tiene todo a la vez: el principal, es decir, el usuario o programa que pide, las tablas y columnas que lee la consulta, la decisión de cada tabla y el SQL que entrega al motor. Ahí es donde Open Policy Agent (OPA) escribe su propio registro. Los registros de decisiones de OPA contienen eventos que describen las consultas de política, con la política consultada, su entrada, los metadatos del bundle y otra información que hace posible la auditoría y la depuración sin conexión (OPA, decision logs). Cada evento lleva un decision_id, el path de la regla consultada, el input, el result, un timestamp y bundles[_].revision, la revisión del bundle en el momento de la evaluación. regopy, que ejecuta la política dentro de Python, devuelve solo el valor de la consulta y nada más, de modo que la capa tiene que construir por sí misma todos los demás campos.
El catálogo de controles de seguridad de NIST ofrece una lista de verificación para esos campos. El control AU-3 pide que los registros de auditoría establezcan seis cosas: (a) qué tipo de evento ocurrió, (b) cuándo ocurrió, (c) dónde, (d) su origen, (e) su resultado y (f) la identidad de las personas, sujetos u objetos asociados a él (NIST SP 800-53 Rev. 5).
lib.audit.Audited toma un catálogo y un Log, el archivo del registro de auditoría. Su método sql recibe los mismos argumentos que Enforcer.sql, más via, el asistente que lo envió, cuando hubo uno. Planifica la consulta, pregunta a la política por cada tabla que lee la consulta, escribe un registro y solo entonces entrega la consulta reescrita a DuckDB. Así, ninguna consulta llega a DuckDB a través de la capa sin un registro, y cuando el registro no se puede escribir, la consulta no se ejecuta. El capítulo 6 dejó en este capítulo un caso: cuando el asistente del curso responde instructor-17, la consulta se ejecuta como el instructor, y ambas identidades deben constar en el registro. La consulta del asistente para instructor-17, y su intento de asociar nombres a las calificaciones, dejan cada uno un registro, que muestra lo que contiene un registro cuando intervienen dos identidades:
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...
El registro 1 cubre los seis elementos de AU-3. event es el tipo, y time indica cuándo, en UTC con una Z, ya que el control AU-8 pide marcas de tiempo que "usen el Tiempo Universal Coordinado" o indiquen su desfase; los ejemplos lo toman de un reloj fijo. catalog indica dónde. user y via son el origen: la consulta se ejecutó como instructor-17, y assistant-1 la envió. Junto con el table de la decisión, son las identidades que pide el elemento f de AU-3. query y el columns de la decisión indican qué se leyó, y outcome y el allow, row_filters, column_masks y reasons de la decisión indican cómo terminó, hasta los ID de curso que conservó el filtro de filas. Las siguientes secciones explican policy_revision, rewritten_digest y prev_hash.
El registro 2 es una denegación, y contiene las decisiones de ambas tablas: la unión puede leer learning.reviews pero no crm.learners, y una tabla denegada deniega la consulta completa. Sin via, el registro diría que el instructor intentó leer los nombres de los alumnos. Con él, un revisor sabe que el asistente escribió esa consulta y examina el comportamiento del asistente además del del instructor.
Regla práctica: Escribe el registro de auditoría en la capa de cumplimiento, donde se encuentran el principal, la consulta y la decisión, y escríbelo antes de que se ejecute la consulta, de modo que una escritura fallida detenga la consulta. Registra todas las identidades involucradas, la persona y cualquier asistente que actúe en su nombre, y la decisión de cada tabla con sus filtros, máscaras y motivos. Cuando un motor aplica la política por sí mismo, como el motor SQL Trino a través de OPA, activa en su lugar el registro de decisiones de OPA y asegúrate de que su entrada nombre todas las identidades involucradas: la opa.identity.extra-credentials-keys de Trino, por ejemplo, reenvía las credenciales que enumeran "a OPA como extraCredentials en el contexto de identidad" (Trino 484, OPA access control).
Mantén los valores fuera del registro
El registro de decisiones guarda identificadores, nombres de tablas y columnas, decisiones y resúmenes criptográficos, y ningún valor de los datos que leyó su consulta, porque todo lo que contiene un registro de auditoría se convierte en datos que hay que proteger. El análisis de NIST sobre AU-3 advierte que la traza de auditoría puede revelar información personal identificable, sobre todo cuando registra entradas, y su mejora AU-3(3) pide que los sistemas limiten esa información en los registros de auditoría a los elementos que nombra la evaluación de riesgos para la privacidad (NIST SP 800-53 Rev. 5). Limitar, no eliminar: el punto f de AU-3 pide el principal (la identidad que actúa), así que cada registro nombra uno, como instructor-17, la cuenta de un instructor. El RGPD define los datos personales como "toda información sobre una persona física identificada o identificable" (RGPD, artículo 4, apartado 1), y una persona es identificable de forma directa o indirecta, en particular mediante un identificador como un nombre o un identificador en línea. Un ID de cuenta como este puede ser uno de esos identificadores. La plataforma tiene una razón aún más clara para mantener fuera a los estudiantes: el capítulo 7 borra a un estudiante de cada tabla a la que llegaron sus datos, y borrar un solo registro de la cadena que añade este capítulo no se distingue de una manipulación.
El riesgo está en el texto de la consulta. Un agente de soporte que busca a un estudiante por el correo electrónico de un ticket escribe ese correo en la consulta. lib.audit.normalized conserva la forma de la consulta y descarta sus valores: sqlglot analiza la consulta, y cada literal, en cualquiera de las sintaxis de DuckDB, se convierte en ?. Lo mismo ocurre con cada nombre que el catálogo no contiene, como un valor escrito entre comillas dobles, salvo que un alias o el nombre de una CTE definidos por la consulta se convierten en alias_1, alias_2 y así sucesivamente. Los comentarios, que pueden contener cualquier cosa, se omiten, y el motivo de una denegación se registra con los mismos valores eliminados. El SQL que la capa entrega a DuckDB se guarda solo como rewritten_digest, un HMAC-SHA256 con una clave que solo tiene la capa, y la verificación cruzada lo compara con el registro propio de DuckDB. OPA parte en cambio de la entrada completa, y puede configurarse para descartar lo que una política indique: "consulta la ruta data.system.log.mask antes de codificar y subir los registros de decisiones" (OPA es el sujeto: consulta esa ruta) (OPA, registros de decisiones). La capa de la plataforma nunca escribe los valores.
Aquí agent-a05 busca a un estudiante de EMEA por correo electrónico y luego por ID, mientras que analyst-1 lee los correos de los estudiantes, que la política seudonimiza. Ninguno de los valores se imprime; las líneas siguientes indican dónde se guarda cada uno:
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
Los registros conservan WHERE email = ? y WHERE learner_id = ?, y una búsqueda del correo en el registro no encuentra nada. El registro de consultas de DuckDB sí contiene el correo, porque registra el texto SQL que DuckDB ejecuta, con sus literales. La clave de seudonimización no está ahí: el capítulo 6 pasa la clave como parámetro, así que el registro de DuckDB muestra el marcador $pseudonym_key donde estaría la clave.
Un resumen criptográfico con clave de una consulta que contenía un correo es un seudónimo de ese correo, y es la clave lo que lo mantiene así, como mostró el capítulo 6 con los seudónimos de la plataforma. La reescritura es código del repositorio, así que cualquiera con una lista de correos, de una exportación antigua o de una filtración, puede reconstruir el texto que DuckDB ejecutó para cada uno y comprobarlo. De 5,000 correos probados, un SHA-256 simple de ese texto confirma 1: el estudiante que consultó el agente. El resumen con clave del registro confirma 0 sin la clave de la capa, y 1 con ella. La clave permanece en la capa, lejos de quien lee el registro, y lo mismo ocurre con la verificación cruzada, que la necesita.
DuckDB recibe un valor de más formas que una cadena entre comillas, y un nombre también puede contenerlo. Una prueba de regresión para normalized escribe el mismo correo, nombre e ID de la estudiante en las consultas de agent-a05 de cada una de esas formas. Esas solicitudes dejan estas huellas, un registro por cada una:
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 conserva la forma de la consulta y ninguno de sus valores, tanto en las permitidas como en las denegadas. La última línea cuenta los registros que contienen el correo, el nombre o el ID: 0 of 11.
Se pierden dos cosas. El texto normalizado también elimina valores y nombres inocuos: en el primer registro, ROUND(AVG(rating), 2) se convirtió en ROUND(AVG(rating), ?), y en el segundo, los alias r y l pasaron a ser alias_2 y alias_1. Y el registro no puede responder a "¿quién consultó a esta estudiante?". Cuando la plataforma necesita esa respuesta, por ejemplo para una estudiante que pregunta quién ha leído sus datos, debe guardarla en un registro de acceso aparte, con los ID de estudiante, un periodo de conservación y sin cadena, que el borrado del capítulo 7 alcanza como a cualquier otra tabla.
Regla práctica: Registra la forma de una consulta, nunca sus valores: sustituye cada literal, en cada sintaxis que admita el motor, y cada nombre que el catálogo no contenga, elimina los comentarios, quita los mismos valores de los motivos de denegación, y guarda el SQL ejecutado solo como un resumen con clave cuya clave nunca reciben los lectores del registro. Nunca uses un hash simple de un texto que pueda contener datos personales. Cuando necesites saber quién leyó los datos de una persona, guárdalo en un registro separado al que sí alcancen la conservación y el borrado, no en el registro a prueba de manipulaciones.
Repetir una decisión antigua con su propia política
Un registro de decisión guarda la solicitud, pero una decisión depende de tres cosas: la solicitud, las reglas de la política y los datos que la política lee. Las dos últimas cambian todo el tiempo. La política de la plataforma lee governance/users.toml, governance/metadata.toml y learning.courses, tal como lo configura el capítulo 5, así que un agente de soporte trasladado a otra región, o un curso añadido a learning.courses, cambia decisiones sin que nadie toque Rego. Si un registro no dice nada sobre cuál era la política, su decisión no puede explicarse una vez que cambie cualquiera de las dos cosas: repetida más tarde, da una respuesta distinta, y el registro parece incorrecto. OPA registra la versión de la política como bundles[_].revision. Para las políticas que llaman a funciones integradas no deterministas, como la hora o una solicitud HTTP, OPA también puede registrar sus resultados en nd_builtin_cache, que existe para la depuración y la repetición de decisiones (OPA, registros de decisiones). La política de la plataforma no llama a ninguna.
lib.audit.bundle reúne los módulos de la política y su documento de datos, los hechos que la política lee, generados a partir de esas tres fuentes, tal como OPA los distribuye en un paquete. lib.audit.revision es el SHA-256 de ese paquete: una huella que cambia cuando cambia cualquier regla, o cualquier hecho que lea la política. Cada registro lleva la revisión que lo decidió. lib.audit.Archive guarda todos los paquetes que ha usado la capa, bajo su revisión, de modo que una decisión puede volver a tomarse con la política que la tomó. Un paquete contiene reglas y los atributos de los usuarios de la plataforma, no datos sobre los estudiantes, así que el archivo puede conservarse tanto como el registro.
En la plataforma, analyst-1 lee los correos electrónicos de los estudiantes y obtiene seudónimos. Supongamos que una solicitud de cambios posterior lo añade al soporte para EMEA, el cambio que detectó la prueba de quién-ve-qué del capítulo 6. El registro antiguo se repite bajo cada revisión:
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
La revisión cambió, de f761e4ad08d4 a 0350e789b34d, aunque no cambió ningún Rego. Los módulos de la política son los mismos, pero el documento de datos, que ahora incluye la nueva pertenencia, no lo es (el documento de datos sí cambió). Una huella de los archivos de política por sí sola habría pasado por alto el cambio. Repetida bajo la revisión actual, la decisión no coincide con el registro: email es shown as stored, porque el soporte ve los datos de contacto. Un investigador que solo tuviera la política actual concluiría que el registro, o la capa, era incorrecto. Repetida bajo la revisión registrada del archivo, email vuelve a ser pseudonymize, y la decisión coincide con el registro.
La repetición explica la decisión, no las filas. Un filtro de filas se repite como una regla, como la región del soporte o el filtro de consentimiento learner_consented, y qué filas lo superaron dependió de los datos de ese día, que pueden haber cambiado después o haberse borrado. Esa separación es deliberada: el registro dice cuál era la regla, y las tablas, con sus propias instantáneas y su propia retención, dicen con qué filas coincidió.
Regla práctica: Genera una huella de cada decisión con un hash de todo aquello de lo que dependió, aparte de la solicitud: los módulos de la política y su documento de datos, juntos. Archiva cada revisión mientras conserves el registro, y explica una decisión antigua repitiéndola bajo su propia revisión, nunca bajo la actual. Si una política lee el reloj o llama a otro servicio, registra también esos resultados, como lo hace nd_builtin_cache de OPA.
Encadena los registros para que una edición se note
Los registros de decisiones de la plataforma son evidencia solo si puede detectarse un cambio en ellos. SP 800-53 pide a los sistemas que "Protect audit information and audit logging tools from unauthorized access, modification, and deletion" (AU-9), y, en AU-9(3), que "Implement cryptographic mechanisms to protect the integrity of audit information and audit tools". Su discusión de AU-9(3) ofrece, como ejemplo, "signed hash functions using asymmetric cryptography" (NIST SP 800-53 Rev. 5), que solo puede producir quien posee una clave privada. La cadena de la plataforma, que se muestra a continuación, no es eso, y no protege nada por sí sola. La guía de NIST sobre gestión de registros, SP 800-92, describe el mecanismo más sencillo: un resumen criptográfico (message digest) para cada archivo de registro, almacenado de forma segura, de modo que un cambio en un registro archivado se detecte (NIST SP 800-92). La guía es de 2006. Nombra MD5 y SHA-1 como los resúmenes habituales de su época, y su propia nota 25 recomienda SHA-256, que usa la plataforma.
Un resumen por archivo detecta un cambio en un archivo cerrado. Una cadena de hashes detecta un cambio en un registro que todavía está creciendo: cada registro lleva un número de secuencia, seq, y el SHA-256 de la línea anterior, prev_hash, de modo que cambiar un registro rompe el enlace con el siguiente, y eliminar uno deja un hueco. lib.audit.check recorre la cadena e informa de cada rotura. Una cadena es evidente ante manipulaciones, no a prueba de manipulaciones. Schneier y Kelsey diseñaron un registro en el que un atacante que toma el control de la máquina de registro no puede leer ni falsificar las entradas escritas antes. Incluso allí, el atacante "can delete a block of entries (or the entire log file)", y la parte de confianza a la que reporta el registro lo advierte solo la próxima vez que la máquina contacta con ella (Schneier and Kelsey, 1999). Una cadena simple como la de la plataforma es más débil: cualquiera que pueda escribir el archivo puede reconstruirla, renumerando a medida que avanza. Por eso lo que demuestra depende de la cabeza de la cadena, el número de registros y el hash del último, anotados en un lugar donde quien escribe el registro no pueda cambiarlos. Una edición o una eliminación de cualquier registro hasta esa cabeza se muestra, por muy oculta que esté. Después de la cabeza, una cadena reconstruida o recortada pasa todas las comprobaciones, y sin cabeza, también las pasa una cadena reconstruida desde el principio. check toma la cabeza como ancla.
Para probar la cadena, el ejemplo reproduce lib.audit.DAY, las 13 consultas que la plataforma recibió el 1 de octubre, y anota la cabeza a mediodía, en el registro 9. Después altera copias del registro de cinco maneras. Antes de mediodía, el registro 3, la consulta de agent-a05 sobre los datos de contacto de un estudiante, se entrega a otro agente, una vez como edición simple y otra con la cadena reconstruida. Después de mediodía, se elimina el registro 12, la lectura denegada de someone-else, el usuario que la plataforma no conoce, una vez simplemente y otra con la cadena reconstruida; y se cortan los dos últimos registros del día. Antes de ejecutarlo, predice cuáles de las cinco encuentra la cadena por sí sola y cuáles frente a la cabeza de mediodía.
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 sí sola, la cadena detecta la edición simple, record 3 was changed: record 4 doesn't follow it, y la eliminación simple, record 12 is missing: record 13 follows record 11, y nada más. No detecta las dos cadenas reconstruidas, que son coherentes de principio a fin, ni el corte, ya que no hay ningún registro posterior al último que lo note.
Una cabeza protege solo los registros escritos antes de ella. Frente a la cabeza de mediodía, la edición hecha antes de mediodía sigue apareciendo aunque la cadena esté reconstruida, the chain no longer passes through the head written down at record 9. Todo lo ocultado después de mediodía pasa: la eliminación con la cadena reconstruida da no problem found, y el corte da no problem found.
Por eso la regla sobre los valores no es opcional. Borrar a un estudiante de un registro encadenado significa cambiar o eliminar un registro, y allí donde una comprobación puede verlo, no puede distinguirlo de una manipulación (en ambos casos la cadena se rompe). Un registro que no contiene datos sobre estudiantes nunca se encuentra con el borrado del capítulo 7. Los identificadores de quienes hacen consultas son otra cuestión: dale al registro un periodo de retención, y empieza una cadena nueva en cada periodo, con su última cabeza anotada, para que un periodo completo pueda eliminarse cuando caduque.
Comprobar una cadena exige releer cada registro. Crosby y Wallach describen registros en forma de árbol que pueden demostrar "that individual logged events are still present, and that the log, as seen now, is consistent with how it was seen in the past", con pruebas de tamaño logarítmico, una mejora sobre construcciones lineales anteriores (Crosby and Wallach, 2009). Para el registro propio de una plataforma recomendamos una cadena comprobada a diario, y un árbol cuando partes externas auditan un registro demasiado grande para releerlo.
Regla práctica: Encadena cada registro con el anterior mediante SHA-256 y un número de secuencia, y cuenta con que la cadena proteja solo los registros hasta la última cabeza anotada fuera del control de la capa. Anota la cabeza con frecuencia, en un almacén de solo adición o en otro sistema con otras credenciales, tan a menudo como permita el número de registros sin protección que puedas aceptar; si ese número es cero, envía cada registro fuera de la máquina en cuanto se escriba. Comprueba la cadena frente a la última cabeza según un calendario. Si necesitas lo que describe AU-9(3), haz que cada cabeza la firme un sistema cuya clave la capa nunca posea. Nunca encadenes un registro que algún día pueda tener que borrarse por una sola persona; deja que expiren periodos completos.
Contrasta el registro con el registro de consultas de DuckDB
El registro de auditoría de la plataforma registra cada consulta que pasa por la capa de cumplimiento, y solo esas. Una consulta ejecutada directamente sobre la conexión de DuckDB de la capa, por un auxiliar de cuaderno o por una prueba a la que se le entregó la conexión, no obtiene ninguna decisión ni ningún registro. Para detectarla hace falta un segundo registro, que lleva el propio motor. DuckDB 2.0.0 tiene uno, desactivado por defecto: su framework de logging tiene un tipo QueryLog, que registra las consultas que DuckDB ejecuta, se activa con CALL enable_logging('QueryLog') y se lee desde la vista duckdb_logs (DuckDB, logging). Un ajuste aparte, log_query_path, indica un archivo al que registrar las consultas (DuckDB, configuration), y la conexión de la capa lo rechaza, como muestra la sección sobre producción.
El registro de DuckDB no es un registro de auditoría. Cada entrada contiene el texto SQL, con los identificadores de conexión, transacción y consulta, y una marca de tiempo: no hay usuario ni decisión. Solo ve la consulta reescrita, y pertenece al proceso que registra, es decir, al proceso al que da seguimiento. Lo que sí puede hacer es comprobar el registro de auditoría: cada consulta que DuckDB ejecutó debería ser el SQL que algún registro de decisión le entregó. Audited activa el registro de DuckDB y bloquea la configuración de la conexión al arrancar. Audited.check_engine_log compara cada consulta del registro de DuckDB, mediante un resumen con clave, con el rewritten_digest de los registros escritos desde la última comprobación, y después vacía el registro de DuckDB, que contiene los valores de las consultas. Una relación ejecuta su consulta "cuando un método de la sección Output lee la relación, y la ejecuta de nuevo en cada lectura" (DuckDB, relational API), y una relación acotada ejecuta SQL propio, que ningún registro entregó a DuckDB. Por eso Audited.sql obtiene cada resultado por sí mismo, una vez, y devuelve las filas como una relación en una conexión propia: haga lo que haga quien la llama, el registro de DuckDB contiene cada consulta permitida una sola vez.
La primera comprobación repasa las 13 consultas del día y las verifica. Después pasan por la capa otras dos consultas: una que quien la llama nunca obtiene y otra que se acota a cinco filas, y un auxiliar de cuaderno lee el correo de un estudiante con la conexión de la capa, por fuera de ella. Sigue una segunda comprobación:
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
La comprobación cruzada relaciona las consultas del día con sus registros: 9 fueron permitidas y 4 denegadas, y DuckDB ejecutó 9: una por cada consulta permitida y ninguna para las denegadas, y 0 sin registro.
La siguiente comprobación encuentra la lectura por fuera de la capa y nada más. La comprobación abarca los registros 14 to 15, las dos consultas que pasaron por la capa, y no lanza ninguna alarma. La lectura por fuera de la capa aparece como 1 sin registro de decisión, impresa sin sus valores. La última línea comprueba en sentido contrario, buscando registros cuya consulta DuckDB no tiene: 0 aquí.
Lo que la comprobación detecta depende de quién tenga la conexión. Detecta una lectura por fuera de la capa hecha por código que no toca el registro de DuckDB, como este auxiliar de cuaderno, una prueba o un trabajo al que se le entregó la conexión por error. No detecta el código que tiene la conexión y pretende ocultarse. Una lectura hecha después de una comprobación, con el registro de DuckDB vaciado de nuevo antes de la siguiente consulta de la capa, no deja nada que ninguno de los dos sentidos pueda encontrar. Además, la función write_log de DuckDB recibe el tipo de registro como argumento, así que puede escribir entradas QueryLog (DuckDB source, v2.0.0); el bloqueo de la configuración no detiene una función. Una garantía frente a ese código exige que el registro del motor se escriba fuera del proceso que tiene la conexión.
La comprobación también encuentra los atajos propios de la capa, como el observe del capítulo 6, que lee la tabla almacenada con la conexión de la capa sin ningún usuario detrás. Da a estas consultas registros propios, con la capa como usuario, en lugar de excepciones en la comprobación.
Regla práctica: Activa el registro de consultas propio del motor allí donde apliques políticas, obtén cada resultado dentro de la capa y comprueba el registro periódicamente frente a los registros escritos desde la última comprobación, en ambos sentidos: cada consulta que el motor ejecutó debe corresponder a un registro, y cada registro permitido debe corresponder a una consulta. Después vacíalo, ya que conserva los valores de las consultas. Trata una discrepancia como un incidente que hay que explicar, no como ruido que hay que filtrar. Cuenta con que la comprobación detecte errores, no el código que tiene la conexión y pretende ocultarse: frente a ese código, solo sirve un registro escrito fuera del proceso. Nunca uses el registro del motor como registro de auditoría: no tiene usuario ni decisión.
Genera la revisión de accesos a partir del registro
El registro de auditoría de la plataforma indica qué leyó cada persona, y la política indica qué puede leer cada persona; una revisión de accesos pone ambos lado a lado. SP 800-53 pide a las organizaciones revisar las cuentas para verificar el cumplimiento de los requisitos de gestión de cuentas (AC-2 j), y revisar a una frecuencia establecida los privilegios asignados a roles y clases, para validar su necesidad, reasignándolos o retirándolos cuando sea necesario (AC-6(7)) (NIST SP 800-53 Rev. 5). Una lista de quién tiene qué rol no responde ninguna de las dos cosas, porque no dice nada sobre la necesidad. El código puede calcular los hechos que necesita una revisión: qué permite la política a cada persona, qué muestra el registro que usó, qué le fue denegado y las membresías que apuntan a algo inexistente. Decidir si se retira un acceso sigue siendo una decisión de los responsables de los datos.
lib.audit.review evalúa la política de la plataforma para cada usuario de users.toml frente a cada tabla, lee el registro y enumera, para cada usuario, las tablas que puede leer, las que leyó, los permisos que no usó, sus consultas denegadas junto con el asistente que las envió, y cualquier caso que alguien deba revisar. Para que encuentre algo obsoleto, el ejemplo añade a analyst-2, todavía listado en bi, a los usuarios de un grupo que la política ya no tiene, como ocurre cuando se retira un grupo y nadie edita el archivo de usuarios:
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
Durante el 1 de octubre, el día que reproduce lib.audit.DAY, 14 permisos no se usaron, y agent-a01 y agent-a09 no leyeron nada en absoluto. Un solo día es demasiado poco para retirar el acceso a nadie, ya que el soporte trabaja por turnos y finanzas lee algunas tablas solo al cerrar el mes, así que estos recuentos son pistas, no decisiones. Un permiso sin uso durante un período de revisión completo, como un trimestre, es lo que hay que llevar al responsable de la tabla. 3 usuarios necesitan que alguien los revise:
analyst-2está en un grupo que ninguna regla conoce. La membresía no concede nada hoy, pero concedería lo que permita en el futuro una regla parabi, así que debe retirarse.someone-elseno está enusers.toml, de modo que un principal que la plataforma no conoce intentó leer los correos de los alumnos.- La línea de
instructor-17dicemay read 3, read 1, denied 3 (sent by assistant-1). En los dos minutos posteriores a responder la primera pregunta del instructor, el asistente probó con alumnos, luego con alumnos unidos a revisiones, luego con tickets. Eso es un asistente que prueba tablas una por una, y sinviala revisión habría culpado al instructor.
El umbral para marcar, 3 consultas denegadas, es una regla práctica, guardada en governance/audit.toml con su razonamiento, de modo que cambiarlo sea un cambio revisado, igual que un cambio de política.
Regla práctica: Genera las revisiones de accesos a partir de la política y del registro de auditoría, nunca a partir de una lista de membresías de roles: lo que cada persona puede leer frente a lo que leyó, sus denegaciones y las membresías que la política ya no reconoce. Ejecútalas sobre un período lo bastante largo para abarcar el ritmo de cada trabajo, como un trimestre, y envía cada hallazgo al responsable de la tabla o grupo al que se refiere. Retira todo permiso que nadie usó en el período, salvo que su responsable explique por qué es necesario.
Producir evidencia como datos
El chequeo de la cadena, la validación cruzada y la revisión de accesos valen más cuando alguien ajeno al equipo puede verificarlos. El Reglamento General de Protección de Datos (RGPD) de la UE asigna esa obligación a la organización, como su principio de responsabilidad proactiva: "El responsable del tratamiento será responsable del cumplimiento de lo dispuesto en el apartado 1 y capaz de demostrarlo («responsabilidad proactiva»)" (RGPD, artículo 5, apartado 2). Qué cuenta como demostrarlo es una cuestión para juristas; esta sección muestra lo que el código puede producir. Los procedimientos de evaluación de NIST para la gestión de cuentas nombran los registros que examina un evaluador, entre ellos los registros de autorización de acceso, las revisiones de cumplimiento de la gestión de cuentas y los registros de auditoría del sistema (NIST SP 800-53A Rev. 5, en el catálogo OSCAL de NIST). Una captura de pantalla de una consola no es ninguno de estos: nadie puede volver a ejecutarla, compararla con la del trimestre anterior ni saber qué política mostraba.
lib.audit.evidence construye el informe de la plataforma a partir de registros y código, en estas secciones:
- la política, con el resumen criptográfico de cada módulo y del documento de datos;
- las pruebas unitarias de la política, del capítulo 5;
- la tabla de quién ve qué, contrastada con la política;
- la cobertura de clasificación, de las comprobaciones de metadatos del capítulo 2;
- el chequeo de la cadena del registro de auditoría;
- la validación cruzada con el registro de DuckDB;
- las supresiones que consigna el registro de auditoría;
- la revisión de accesos.
Cada sección indica la revisión de la política con la que se calculó, los resúmenes criptográficos de sus entradas y lo que hace falta para volver a calcularla: el paquete archivado, los archivos de prueba, metadata.toml y los esquemas de las tablas, el registro de auditoría. La validación cruzada del motor solo puede recalcularse en parte, y así lo indica. Conserva el resumen con clave de cada consulta que ejecutó DuckDB, de modo que quien tenga el registro puede rehacer sus dos recuentos, pero solo la capa podía leer el registro de DuckDB, una vez, antes de vaciarlo. Genera el informe del 1 de octubre, con cada tabla y salida de pipeline del catálogo, la supresión del capítulo 7 de un estudiante registrada a las 07:00, y las consultas del día:
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
El informe muestra lo que falla además de lo que pasa, porque un informe que solo puede mostrar comprobaciones superadas no es evidencia de nada. La política supera 12 of 12 pruebas unitarias y coincide con 12 of 12 casos de quién ve qué. La cobertura de clasificación no está limpia: ai.review_corpus y marketing.audience no tienen metadatos, las lagunas que encontraron los capítulos 2 y 4 y que, mientras tanto, la política trata como sensibles.
Las comprobaciones propias del registro salen limpias, pero demuestran menos de lo que parecen. La cadena tiene 0 problemas, medidos por separado, ya que ningún informe anterior anotó una cabeza de la cadena. La validación cruzada detecta errores, no código que pretenda ocultar (arriba). DuckDB ejecutó 0 consultas sin registro de decisión, y 0 registros no tienen consulta.
Las líneas de la supresión, 25 rows deleted, 0 of 115 files hold the person y billing.payments, decided by legal team, card_number erased, proceden de la supresión del capítulo 7, tal como la registra el registro de auditoría: el identificador de la solicitud, las tablas, los recuentos, cada tabla conservada por una excepción con el motivo que indica governance/retention.toml, y el resultado del escaneo, nunca el identificador ni los valores del estudiante, de modo que el registro es seguro para encadenarlo. El Comité Europeo de Protección de Datos recomienda que los responsables "Verifiquen que la supresión se ha llevado a cabo y sean capaces de demostrarla" (CEPD, 2026); esta línea registra lo que encontró el propio escaneo de la plataforma. El informe también anota la cabeza de la cadena, en el registro 14. Guardado en otro sistema, es el ancla contra la que el siguiente informe comprueba la cadena: una modificación o eliminación de cualquier registro hasta ese punto se mostrará entonces, y un registro posterior queda protegido solo cuando un encabezado posterior lo cubra.
El informe no afirma nada sobre ninguna ley ni marco normativo. Indica qué se comprobó, con qué política, a partir de qué entradas y con qué resultado.
Regla práctica: Genera la evidencia a partir de registros con código, con periodicidad y en cada cambio de política, y estampa un sello en cada sección con la revisión de la política, los resúmenes criptográficos de sus entradas y lo que hace falta para volver a calcularla, indicando qué partes nadie puede. Guarda los informes donde el escritor del registro no pueda modificarlos, incluye los hallazgos fallidos en lugar de filtrarlos y haz que cada informe compruebe la cadena frente al encabezado que escribió el anterior. Nunca envíes una captura de pantalla cuando se pueda generar un informe; el capítulo 10 ejecuta comprobaciones como estas en cada pull request.
Qué sale mal en producción
Nada se rompe cuando un registro de auditoría deja de ser completo, verdadero o leído. El fallo que más importa es el registro que el código auditado puede apagar, y el registro de consultas de DuckDB es de ese tipo: pertenece al proceso que registra. Dos capas de aplicación de políticas enfrentan el mismo ataque. La primera no bloquea su configuración, como cualquier capa construida sin lib.audit; el código que tiene su conexión intenta registrar en un archivo, apaga el registro y después lee el correo de un alumno saltándose la capa. La segunda es la de lib.audit, bloqueada; ese código intenta apagar el registro, lee saltándose la capa y luego vacía el registro:
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
En la capa no bloqueada, disable_logging() funciona, y la lectura que sigue no deja rastro. La verificación cruzada solo encuentra las sentencias anteriores al silencio: el SET log_query_path rechazado y el propio CALL disable_logging(). El rechazo es un PermissionException, porque el capítulo 6 prohíbe que la conexión de la capa toque archivos.
En la capa bloqueada, el apagado falla y el vaciado del registro no. Apagar falla con un InvalidInputException, pero truncate_duckdb_logs() funciona, y después la comprobación encuentra 0 consultas sin registrar. La comprobación en sentido contrario detecta el hueco: 1 registro de decisión no tiene consulta en el registro de DuckDB, así que algo vació el registro. Solo lo detecta porque un registro cayó en el tramo vaciado; el código que vuelve a escribir entradas con write_log dejaría el registro con aspecto completo.
Nada de esto detiene al código que tiene la conexión. En producción, aplica las políticas en un motor que funcione como servicio propio, como Trino con OPA, de modo que su registro se escriba fuera del proceso de quien hace la consulta. Guarda los registros de auditoría en otro sistema, como pide el control AU-9(2): "Store audit records [Assignment: frequency] in a repository that is part of a physically different system or system component than the system or component being audited" (NIST SP 800-53 Rev. 5). Te recomendamos enviar cada registro en cuanto se escribe, y mantener el encabezado de la cadena en otro lugar.
Otras formas en que el rastro de auditoría falla:
- Registros que nadie lee. La guía de gestión de registros de NIST defiende leerlos: las revisiones rutinarias ayudan a identificar incidentes de seguridad, infracciones de políticas, actividad fraudulenta y problemas operativos poco después de que ocurran (§2.2, NIST SP 800-92). Un registro que solo se escribe cuesta almacenamiento y no protege nada. Programa la revisión de acceso y el informe de evidencias, asigna un responsable a cada hallazgo y alerta de lo que no puede esperar a un trimestre, como un usuario marcado por consultas denegadas.
- Decisiones que no se pueden explicar después de cambiar una política. Un registro sin revisión de la política, o una revisión sin paquete archivado, se reproduce con la política actual y se contradice. Calcula la huella del documento de datos junto con la de las reglas, ya que un cambio en el documento de datos altera las decisiones tanto como un cambio en las reglas.
- Registros que contienen datos personales. Los datos personales llegan a los registros por muchas vías: literales de consulta, el propio registro de consultas del motor, mensajes de error que imprimen valores, como mostró el capítulo 6 con los errores de conversión de DuckDB, y la salida de depuración de la capa. Las advertencias de un analizador son otra vía más: la advertencia de sqlglot cuando conserva una sentencia como texto cita la sentencia (código fuente de sqlglot, v30.24.0), así que
lib.auditsilencia a sqlglot mientras analiza la consulta de un usuario. Limita el registro de auditoría a identificadores y resúmenes (digests), y da a cualquier otro registro un periodo de retención que la supresión alcance. - Un registro de decisiones que no está completo. OPA puede descartar eventos de decisión según la regla, mediante
system.log.drop, y "OPA will drop events if the rate limit is exceeded" (OPA, decision logs). Cuenta las consultas del motor frente a los registros de decisión, como hace la verificación cruzada, en lugar de suponer que todas las decisiones quedaron registradas. - Un encabezado guardado junto al registro. Un ancla almacenada donde el escritor del registro puede modificarla no detecta nada que la cadena no detecte. Guárdala en otro sistema, con otras credenciales.
Lo que decidió este capítulo
- Un registro por consulta, escrito por la capa de cumplimiento antes de que la consulta se ejecute.
lib.audit.Auditedenvuelve aEnforcerdel capítulo 6 sin cambiarlo, y obtiene cada resultado por sí mismo. El registro cubre los seis elementos de AU-3, entre ellos el principal y el asistente que enviaron la consulta. - Los registros contienen identificadores, nunca valores. Cada literal, en cualquiera de las sintaxis de DuckDB, y cada nombre que el catálogo no contiene se sustituye, tanto en la consulta como en el motivo de la denegación, y los comentarios se eliminan. El SQL que ejecutó DuckDB se conserva como un resumen HMAC-SHA256 bajo una clave que solo posee la capa, ya que con la clave el resumen confirma una suposición. Las supresiones se registran por el identificador de la solicitud.
- Cada registro indica su revisión de política, el SHA-256 de los módulos de la política y del documento de datos, y cada revisión se archiva para poder repetir su evaluación.
- Los registros se encadenan con SHA-256 y se numeran, y la cadena protege solo los registros hasta el último encabezado anotado fuera del control de la capa. Cada informe de evidencias anota ese encabezado; recomendamos hacerlo con más frecuencia.
- El registro de consultas de DuckDB es una verificación cruzada para detectar errores, no el registro de auditoría. La capa lo activa, bloquea su configuración, lo compara en ambos sentidos con los registros desde la última comprobación y luego lo vacía. El código que tiene la conexión puede burlarlo.
- Las revisiones de acceso y los informes de evidencias se generan a partir de la política, el registro y el catálogo, y cada sección lleva la marca de su revisión de política y de sus entradas. El umbral para marcar las consultas denegadas, 3, es una regla práctica en
governance/audit.toml. Un rastro de auditoría solo es tan bueno como lo que el código auditado no puede cambiar, y las comprobaciones de este capítulo indican qué partes del sistema puede cambiar. El registro que importa es aquel que el código auditado no tiene forma de desactivar.
Este capítulo, en esta edición
Edición 2026.11.31Ejemplos verificados el 19 de nov de 2026Superan la prueba 9 de 9 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.31.