bkuan001/halo-recordRastros de auditoría a prueba de manipulaciones para agentes de IA: Runtime Records encadenados por hash, sin dependencias, verificables por cualquiera.
Rastros de auditoría a prueba de manipulación para agentes de IA — Registros de Runtime encadenados por hash, renderizados como un Informe de Runtime que tus clientes pueden verificar por sí mismos.
Cada acción que tu instrumentación captura (llamadas a herramientas, llamadas a modelos, acceso a datos, aprobaciones) se convierte en un Registro de Runtime en un log de solo anexado y encadenado por hash; el Informe de Runtime es esa cadena renderizada como una página HTML que recalcula la cadena de hash en el navegador del lector y renderiza lo que muestra a partir de los registros que verificó (para una comprobación que no dependa del propio código de la página, ejecuta halo verify sobre el JSONL). Cualquier parte que posea un checkpoint de la cadena puede verificar que los registros hasta ese checkpoint no han sido alterados desde que se tomó, sin confiar en quien los produjo — ese checkpoint es la pieza fundamental: la cadena por sí sola es a prueba de manipulación frente a todos excepto la parte que opera el registrador (LIMITS.md §1). Cuando el equipo de seguridad de un cliente pregunta "¿qué hizo tu agente con nuestros datos?", les entregas un enlace en lugar de un párrafo. Las revisiones de seguridad ya hacen preguntas sobre IA junto a la lista de verificación de SOC 2 — y cada vez más esas preguntas provienen de ISO 42001, los artículos de mantenimiento de registros del Reglamento de IA de la UE y los propios cuestionarios de los clientes. Hoy una garantía por escrito todavía pasa. La apuesta detrás de este proyecto es que no lo hará por mucho tiempo.
Destacado en Help Net Security (agosto de 2026).
El formato de registro es abierto y libre de implementar. Este paquete es la implementación de referencia: registrador, verificador, cliente testigo y servidor de informes.
¿Usas halo-record, o lo estás considerando? Cuéntame quién eres y para qué → ¿Quién usa halo-record?
Te están pidiendo que pongas un registrador dentro de tu agente. No deberías aceptarlo por fe:
pip install halo-record instala exactamente un paquete.halo serve --verify-email (envía un código de un solo uso y el nombre del sujeto del informe, por SMTP a través del servidor que configures en $HALO_SMTP_HOST, a la dirección que introduce un visor del informe). Todas están desactivadas a menos que las invoques; ningún otro contenido de los registros sale de tu infraestructura.summaries=False) no conserva ningún resumen. La redacción es de mejor esfuerzo (regex sobre formatos comunes de secretos y PII más un comodín de entropía): trátala como defensa en profundidad, no como una garantía. Los campos de resultado que proporciones más allá de summary se escanean y enmascaran con los mismos patrones, pero no se recortan a 200 caracteres (LIMITS §13).Lo que prueba cada capa — la distinción fundamental en este proyecto (LIMITS.md §1): una cadena que tú mismo posees prueba que los registros no fueron editados, en relación con una cabeza que alguien ya posee; solo los checkpoints mantenidos fuera del operador prueban que ninguno fue eliminado; y ningún hash prueba que cada acción fue capturada.
| Afirmación | Cadena propia | + Checkpoints externos | + Captura confiable |
|---|---|---|---|
| Detectar ediciones a un artefacto establecido | ✔ | ✔ | ✔ |
| Detectar la reescritura de historial comprometido | — | ✔ | ✔ |
| Detectar checkpoints faltantes/tardíos | — | ✔ (cadencia acordada) | ✔ |
| Probar que cada acción fue registrada | — | — | depende del límite de captura |
Ve uno antes de instalar: un Informe de Runtime de ejemplo — datos ficticios, cadena real, y su script recalcula la cadena de hash de los registros incrustados en tu navegador cuando lo abres.
No se requiere agente. Con uv, nada que instalar:
uvx --from halo-record halo demo --serve
o de la forma clásica:
pip install halo-record
halo demo --serve
Cualquiera de los dos crea un proveedor ficticio de agentes de soporte con dos clientes, es testigo de las cadenas (con un archivo testigo local que representa a uno fuera del operador — véase LIMITS.md §1), sirve sus Runtime Reports restringidos y abre la consola del operador en tu navegador. Luego prueba la prueba de manipulación: elimina una línea de uno de los archivos .jsonl y recarga. El informe lo detecta.
Una línea en el límite:
from halo_record import trace
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls
Un shim de conveniencia from halo import ... también se incluye — pero el nombre halo en PyPI pertenece a un paquete terminal-spinner no relacionado, y si ese paquete está instalado, gana la importación. halo_record no es ambiguo, por lo que los ejemplos lo usan.
Sin log=, los registros van a ~/.halo/my-agent.jsonl (una cadena por agente). El wrapper sella el límite de ejecución; la evidencia vive en los registros por llamada. Captúralos con un adaptador de framework (matriz a continuación) — o explícitamente, lo que también muestra cómo se vinculan las delegaciones:
from halo_record import Recorder, record_call
rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call: # one sealed record per tool call
call.result = crm.lookup("acct-9")
with record_call(rec, "payments.refund", {"amount": 120},
parent_id=rec.last_record_id()) as call: # child links to the action that spawned it
call.result = payments.refund(120)
Luego renderiza el informe: