Saltar a contenido

Las páginas sin traducir se abren en inglés y se indican como inglés.

Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.

Registro de auditoría

Las filas de auditoría, el worker audit_verifier y la cadena de checkpoints están activados por defecto.

Loom escribe una fila en loom.audit_log por cada operación que cambia el estado de una forma de la que alguien pueda tener que rendir cuentas, además de algunos eventos que genera el propio servidor. El objetivo es que la manipulación sea detectable. Cada fila incluye un SHA-256 de su propio contenido, y un worker sella las ventanas horarias cerradas en una cadena de hashes. Un administrador de ClickHouse todavía puede editar la tabla; la siguiente pasada del verificador mostrará la edición o el borrado. Esto es una primitiva de ingeniería, no una certificación de cumplimiento normativo.

El registro de auditoría del panel: memorias guardadas, una memoria eliminada, una unión a un espacio de nombres y una concesión de permisos, de más reciente a más antigua

Qué deja una fila de auditoría

Origen event_type subject contiene
Cualquier operación declarada audit=True el nombre de la operación (memory.delete, grants.create) el audit_subject de la operación cuando lo declara (sin credencial, o con un hash para el texto que una eliminación debe alcanzar); si no, su entrada validada con cada valor de texto que no nombra nada convertido en hash, como JSON
memory.set (escrituras puntuales) memory.set clave, id de la memoria, content_sha256, source_class, veredicto, pinned. Nunca el valor
memory.update, memory.update_by_id el nombre de la operación clave, id de la memoria, content_sha256, source_class, versión y el veredicto de la comprobación de conflictos antes del marcado posterior a la escritura (duplicate para una versión escrita como tal, vacío cuando la fila revisada no tiene embedding: un tipo que no lo tiene, o un valor high). Nunca el valor
memory.bulk_set memory.bulk_set una fila solo con hashes por cada escritura
Cada revisión confirmada en Postgres memory.revision clave, id de la memoria, versión, content_sha256, source_class, estado, pinned, tombstoned y, como actor, el principal del token; si no, el de la etapa del pipeline; si no, - en una solicitud y process:loom para los trabajos propios de Loom. Se almacena junto con la revisión, por lo que no es fail-open: se reintenta hasta que se guarda o se aparca (autoridad de almacenamiento)
memory.import memory.bulk_set para los hechos que escribe; memory.import para los vínculos de categoría que escribe la fila solo con hashes de la escritura masiva; para los vínculos, count y category_links (clave y nombre de categoría). Nunca el texto
Una lectura de una fila high, o de evidencia retenida como high memory.sensitive_read (desde memory.get, memory.get_by_id, memory.bulk_get, memory.history, memory.evidence, namespace.snapshot, erasure.export y memory.export_evidence con include_high) clave e id de la memoria (memory.history y erasure.export añaden la versión); para la evidencia liberada, su tipo, sesión, índice de fragmento y claves vinculadas; para un turno de conversación que sirve erasure.export, su agente, id de hilo e id de mensaje; para un hilo, su agente e id de hilo
Una solicitud admitida a un espacio de nombres restringido namespace.restricted_access (desde una operación que lo nombra, audit.list que lo nombra (transporte op), la descarga y la subida de documentos, un inbox watch, admin/claim_release, admin/namespace.adopt, las emisiones de tokens delegados y el primer de MCP) op, transport, el token_id y los roles de quien llama; para una emisión, granted_to, el sujeto del nuevo token
Loom retira memorias por su cuenta memory.auto_supersede reason, count y retired: hasta 200 filas retiradas (id, clave, agente, usuario y sesión, la fila y la clave detrás de las que se retiró cada una, la etiqueta del juez, judge_verdict, judge_confidence, judge_model y judge_prompt_version para una retirada del conflict-resolver, y unconfirmed ("true") cuando la relectura no pudo confirmar la retirada). Nunca el valor. Si hay más filas, se dividen en varios eventos
memory.restore de una fila reemplazada memory.unsupersede clave, id de la memoria, superseded_by, el content_sha256 y la version restaurados
Una fila de grants.revoke tomada con otra grafía, o una de varias grants.revoke namespace, el subject almacenado, named (el sujeto que nombró la llamada) y landed ("unknown") cuando el insert de la fila falló. Junto a la fila propia de la operación, que contiene la entrada
El propio servidor budget.violated, ratelimit.exceeded, worker.failed, audit.tamper_detected, … aquello sobre lo que trata el evento

La columna Audit de la referencia de operaciones generada lista las operaciones que audita el transporte (la marca audit de cada Operation); las escrituras de memoria de la tabla anterior escriben su propia fila y no llevan marca allí. Ninguna operación de lectura se declara audit=True; una lectura de una fila high escribe memory.sensitive_read (arriba). audit.list es audit=False: leer el registro solo añade la fila de acceso restringido para un espacio de nombres restringido.

El transporte escribe la fila después de que el handler tenga éxito (emit_op_audit en server/transport/_common.py, para HTTP y MCP). La escritura es fail-open: un insert fallido se registra en el log y se pierde la fila; la operación se completa igualmente.

Para una operación audit=True, el sujeto es su audit_subject cuando lo declara; si no, la entrada validada tal como la da forma audit.input_subject. Los campos que nombran sobre qué actuó la llamada o quién actuó (los campos de identidad, los principales subject, actor, grantee, owner_email, requester, approver y decision_maker, version, y los nombres que terminan en el sufijo id, key, URI, name, org, agent, namespace o _by) y los campos tipados como número, booleano, fecha u hora, Literal o Enum se quedan tal como se enviaron; un campo cuyo nombre indica una credencial (audit.is_credential en server/observability/audit.py) se convierte en hash sea cual sea su sufijo. Un campo que contiene un modelo anidado sigue la misma regla, y una lista de modelos se convierte en hash completa. Los principales y los campos _by que se conservan tal como se enviaron son datos personales que una eliminación no borra de loom.audit_log. Cualquier otro valor (un valor de memoria, el razonamiento de una decisión, un motivo, los campos de un registro, las filas de un snapshot restaurado) se almacena como {"sha256", "chars"}, su SHA-256 y su longitud (el hash que llevaría el content_sha256 de una memoria, de modo que coincida con el de un valor movido), ya que la eliminación no alcanza a loom.audit_log. Tres filas que escribe un handler por sí mismo almacenan texto con esa forma bajo el nombre del campo: el rationale de memory.cross_promote y de memory.copy_to, el reason de memory.proposal_accept y de memory.proposal_reject (una decisión que toma la política del propietario registra en su lugar el modo y los umbrales de la política), y el closed de triple.follows_row_supersession, cuyo actor es el principal que escribe o process:loom. El hash de un valor corto se puede recuperar por prueba y error; la regla mantiene el texto largo fuera del registro, no cada palabra. Una operación cuya entrada lleva una credencial (la contraseña de una fuente de tracker, el token de acceso de un repositorio) declara un audit_subject que la omite. Concede permisos sobre loom.audit_log como sobre los datos que describe.

La fila

loom.audit_log es una MergeTree particionada por mes y ordenada por (org, namespace, event_type, ts), con un índice bloom-filter sobre request_id.

Columna Significado
ts UTC, precisión de milisegundos
event_type nombre de la op o evento del servidor
org, namespace el tenant que autorizó la puerta
actor el sujeto del token (anonymous cuando la autenticación está desactivada); la fila propia de una escritura de memoria (memory.set, memory.bulk_set, memory.update, memory.update_by_id) lo nombra kind:subject, - sin token
subject texto JSON; el llamante decide si lo analiza
request_id se une con loom.agent_events y con el encabezado de respuesta X-Request-Id
row_hash SHA-256 sobre la fila canónica
build_commit, instance, instance_label qué build y qué proceso escribió la fila
consumer el cliente en nombre del cual se hizo la solicitud
token_id la credencial que hizo la solicitud (su jti, o si no, un prefijo del hash del token)

El hash cubre ts, event_type, org, namespace, actor, subject y request_id como JSON ASCII con claves ordenadas (_canonical en server/observability/audit.py). Los sellos de build, instancia, consumer y token quedan fuera del hash, de modo que añadir una columna de sello no invalida las filas antiguas.

audit.list, erasure.export y namespace.snapshot devuelven el subject de una fila erasure.failed o erasure.abandoned con el motivo del fallo recortado al paso y al tipo de error, por lo que un hash recalculado a partir de esas filas puede diferir del almacenado. dev/verify_audit_chain.py comprueba las filas almacenadas.

Hashes por fila y checkpoints

Varias réplicas del servidor escriben de forma concurrente, por lo que una cadena de hashes de fila a fila se bifurcaría. En su lugar, cada fila lleva su propio hash y las escrituras no necesitan coordinación. Un hash por fila detecta una fila modificada, pero no una eliminada; la cadena de checkpoints cubre las eliminaciones (el diseño está en arquitectura de seguridad):

  1. Cuando una ventana de LOOM_AUDIT_CHECKPOINT_WINDOW_SECONDS (1 h) lleva cerrada LOOM_AUDIT_CHECKPOINT_GRACE_SECONDS (10 min), el worker audit_verifier la sella en loom.audit_checkpoints: el número de filas, un SHA-256 sobre los hashes de fila ordenados y un checkpoint_hash que incluye el hash del checkpoint anterior.
  2. Cada pasada vuelve a contar las últimas LOOM_AUDIT_CHECKPOINT_VERIFY_WINDOWS (24) ventanas selladas y vuelve a comprobar los enlaces.

Un solo worker sella, de modo que la cadena tiene un único escritor y la ruta de la solicitud no paga ningún coste. Una eliminación solo se manifiesta después de que su ventana se selle, y solo mientras la ventana se vuelve a contar.

classify en server/insights/domain/audit_checkpoints.py clasifica un recuento:

Hallazgo Significado ¿Manipulación?
deletion menos filas de las selladas sí
modification mismo número de filas, digest distinto sí
chain el hash propio de un checkpoint no se recalcula, o no apunta a su predecesor sí
late_insert más filas de las selladas: un backfill o un insert asíncrono muy tardío no por sí solo; se reporta

Una ventana vacía también se sella, con el digest de la cadena vacía, de modo que una fila insertada en ella más tarde provoca una discrepancia.

El worker verificador

audit_verifier (server/insights/workers/audit_verifier.py) se ejecuta cada LOOM_AUDIT_VERIFIER_INTERVAL_SECONDS (una hora) en el proceso que tiene el lease de los workers. Cada pasada:

  1. Vuelve a calcular el hash de cada fila de la última hora (10,000 filas por página, como máximo 500,000; si se supera el límite, informa truncated).
  2. Verifica las ventanas selladas y después sella las ventanas cerradas, como máximo LOOM_AUDIT_CHECKPOINT_MAX_SEAL_PER_PASS (48) por pasada. Un error en este paso se registra como un fallo parcial y nunca bloquea la comprobación por fila.
  3. Escribe una fila audit.tamper_detected por las roturas no informadas antes (subject.break_keys), de modo que una rotura se informa una sola vez, no cada hora.

El resultado de la pasada (rows_checked, breaks, windows_sealed, windows_verified, checkpoint_breaks, new_breaks, truncated) se registra en loom.worker_status como el de todos los workers; consulta los workers.

Retraso de los checkpoints

loom.audit.checkpoint_lag_windows cuenta las ventanas de una hora entre el window_end sellado más reciente y el momento actual. Se lee directamente de loom.audit_checkpoints, por lo que informa incluso cuando el sellador está caído.

Lectura Significado
0 o 1 saludable: la cadena va por detrás el periodo de gracia
en aumento constante el sellador está detenido: el worker está deshabilitado, falla o no tiene el lease
en descenso un backfill tras una detención; cada pasada sella como máximo 48 ventanas
0 sin checkpoints nunca se ha sellado nada (el indicador marca 0 en una tabla vacía)

Consulta telemetría para el resto del catálogo.

Lectura del registro

audit.list pagina las filas del solicitante de la más reciente a la más antigua con un cursor keyset opaco. Una página nunca termina en medio de una escritura: las filas que una solicitud escribió en el mismo milisegundo llegan en una sola página, por lo que una página puede contener más de limit filas.

Campo Significado
org obligatorio
namespace un espacio de nombres que el solicitante puede leer (si no, una página vacía); omítelo para todos
event_type coincidencia exacta
since filas con ts >= since
limit 1–500, por defecto 50
cursor next_cursor de la página anterior; vuelve a pasar los filtros junto con él
fields proyecta las filas de salida a estos campos

La op requiere viewer y aplica sus propios alcances. Un espacio de nombres indicado pasa la misma validación que una lectura del mismo; indicar uno que no puedes leer devuelve una página vacía, no un 403. Sin namespace, un administrador de la organización cuyo token declara * lee la organización, salvo los espacios de nombres y colecciones restringidos que no puede leer, y un administrador de la plataforma lee la organización, salvo los espacios de nombres restringidos que no puede leer, sea cual sea su declaración (una sesión del panel nombra solo los espacios de nombres propios de la persona). Cualquier otro solicitante, incluido un administrador de la organización cuyo token enumera espacios de nombres, lee los espacios de nombres a los que llegan su token o sus permisos.

curl -s "$LOOM_BASE_URL/v1/audit.list" \
  -H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"org": "acme", "namespace": "support", "event_type": "memory.delete", "limit": 100}'
from loom import Agent

async with Agent(org="acme", namespace="support", agent="auditor") as admin:
    page = await admin.audit.list(event_type="memory.delete", limit=100)
    while page.get("next_cursor"):
        page = await admin.audit.list(
            event_type="memory.delete", cursor=page["next_cursor"], limit=100
        )

La vista Audit log del panel de administración lee la misma op. Oculta los eventos del servidor (budget.violated, ratelimit.exceeded, worker.failed) tras un interruptor y muestra el resumen de borrados junto a la lista.

Para seguir una solicitud a través del ledger y del registro de auditoría:

SELECT ts, event_type, actor, subject FROM loom.audit_log WHERE request_id = '<id>';
SELECT * FROM loom.agent_events WHERE request_id = '<id>';

Verificación sin conexión

dev/verify_audit_chain.py recalcula el hash de cada fila de una ventana con row_matches_hash del worker. Código de salida 0 = todo correcto, 1 = discrepancia, 2 = no se pudo verificar. Una discrepancia se identifica por partición, ts, request_id y hash almacenado, nunca por actor, subject ni namespace.

python dev/verify_audit_chain.py --org acme --ts-since <YYYY-MM-DD> --json

Borrado y el registro de auditoría

Un borrado conserva el rastro de auditoría, incluida su propia fila de auditoría; el censo de residuos no exige que loom.audit_log esté vacío. Para un alcance user_id, la exportación compara subject por subcadena, ya que la tabla no tiene una columna user_id. Consulta retención y borrado.

Configuración

Ajuste Valor por defecto Efecto
LOOM_AUDIT_VERIFIER_ENABLED true ejecuta el worker del verificador
LOOM_AUDIT_VERIFIER_INTERVAL_SECONDS 3600 cadencia de cada pasada
LOOM_AUDIT_CHECKPOINT_WINDOW_SECONDS 3600 duración de la ventana
LOOM_AUDIT_CHECKPOINT_GRACE_SECONDS 600 cuánto tiempo debe estar cerrada una ventana antes de sellarse
LOOM_AUDIT_CHECKPOINT_VERIFY_WINDOWS 24 ventanas selladas que se recuentan en cada pasada
LOOM_AUDIT_CHECKPOINT_MAX_SEAL_PER_PASS 48 límite de ventanas selladas por pasada
LOOM_BUDGET_VIOLATION_AUDIT_INTERVAL_S 60 como máximo una fila budget.violated por op en cada intervalo (después de la ráfaga)
LOOM_BUDGET_VIOLATION_AUDIT_BURST 5 infracciones por ventana que aún escriben su propia fila

Todos los ajustes están en la referencia de configuración.

Límites y modos de fallo

  • Escrituras fail-open. Si falla la inserción de auditoría, se pierde la fila y la operación nunca falla, salvo en un memory.restore que deshace una retirada y en un namespace.restore, que dependen de su registro. Una fila se inserta directamente mientras se ejecuta su trabajo, no se pone en cola: la fila de una operación, antes de su respuesta; la de un borrado desacoplado, a medida que se ejecuta cada paso. Una caída pierde solo las filas del trabajo en curso (con LOOM_RESTRICTED_AUDIT_INLINE=false, también la fila de un acceso restringido escrita después de su respuesta). Bajo la autoridad de Postgres, la fila de auditoría de una escritura de memoria es duradera en Postgres antes de que la escritura responda (auditoría).
  • Detección, no prevención. Cualquiera con acceso de escritura a la tabla de ClickHouse puede alterarla. El verificador muestra el cambio; no puede deshacerlo.
  • Retrospección acotada. La comprobación por fila lee la última hora; el nuevo recuento de checkpoints cubre las últimas 24 ventanas selladas. Una edición más antigua que ambas no es reexaminada por el worker. Ejecuta dev/verify_audit_chain.py sobre las particiones más antiguas.
  • Una inserción tardía no es manipulación. Un backfill en una ventana antigua se informa como late_insert.
  • Sin TTL por defecto. Las filas de auditoría caducan solo con una ventana de retención: LOOM_RETENTION_AUDIT_LOG_DAYS mayor que 0 para toda la tabla, o el retention_days de un espacio de nombres para las filas de ese espacio de nombres (retención configurada).

Relacionado