bkuan001/halo-recordRegistri di controllo a prova di manomissione per agenti AI: Runtime Records concatenati tramite hash, senza dipendenze, verificabili da chiunque.
Audit trail a prova di manomissione per agenti AI — Runtime Record concatenati tramite hash, visualizzati come Runtime Report che i tuoi clienti possono verificare autonomamente.
Ogni azione catturata dalla tua strumentazione (chiamate a tool, chiamate a modelli, accesso ai dati, approvazioni) diventa un Runtime Record in un log append-only concatenato tramite hash; il Runtime Report è quella catena visualizzata come pagina HTML che ricalcola la catena di hash nel browser del lettore e visualizza ciò che mostra a partire dai record che ha verificato (per una verifica che non dipende dal codice della pagina stessa, esegui halo verify sul JSONL). Qualsiasi parte in possesso di un checkpoint della catena può verificare che i record fino a quel checkpoint non siano stati alterati da quando è stato acquisito, senza fidarsi di chi li ha prodotti — quel checkpoint è il pezzo portante: la catena da sola è a prova di manomissione contro chiunque tranne la parte che gestisce il recorder (LIMITS.md §1). Quando il team di sicurezza di un cliente chiede "cosa ha fatto il tuo agente con i nostri dati?", gli consegni un link invece di un paragrafo. Le revisioni di sicurezza pongono già domande sull'AI accanto alla checklist SOC 2 — e sempre più spesso quelle domande provengono da ISO 42001, dagli articoli sulla conservazione dei registri dell'EU AI Act e dai questionari dei clienti stessi. Oggi un'assicurazione scritta passa ancora. La scommessa dietro questo progetto è che non durerà a lungo.
In evidenza su Help Net Security (agosto 2026).
Il formato dei record è aperto e libero da implementare. Questo pacchetto è l'implementazione di riferimento: recorder, verifier, client witness e server dei report.
Stai usando halo-record, o ci stai pensando? Dimmi chi sei e per cosa → Chi sta usando halo-record?
Ti viene chiesto di inserire un recorder dentro il tuo agente. Non dovresti accettarlo sulla fiducia:
pip install halo-record installa esattamente un pacchetto.halo serve --verify-email (invia un codice monouso e il nome del soggetto del report, via SMTP attraverso il server che configuri in $HALO_SMTP_HOST, all'indirizzo inserito da chi visualizza il report). Tutte sono disattivate a meno che tu non le invochi; nessun altro contenuto dei record lascia la tua infrastruttura.summaries=False) non conserva alcun riepilogo. La redazione è best-effort (regex sui formati comuni di segreti e PII più un catch-all basato sull'entropia): trattala come difesa in profondità, non come garanzia. I campi di esito che fornisci oltre a summary vengono scansionati e mascherati con gli stessi pattern, ma non troncati a 200 caratteri (LIMITS §13).Cosa dimostra ciascun livello — la distinzione portante in questo progetto (LIMITS.md §1): una catena che possiedi tu stesso dimostra che i record non sono stati modificati, rispetto a una testa che qualcun altro già possiede; solo i checkpoint conservati al di fuori dell'operatore dimostrano che nessuno è stato rimosso; e nessun hash dimostra che ogni azione sia stata catturata.
| Affermazione | Catena auto-conservata | + Checkpoint esterni | + Cattura attendibile |
|---|---|---|---|
| Rilevare modifiche a un artefatto consolidato | ✔ | ✔ | ✔ |
| Rilevare la riscrittura della cronologia consolidata | — | ✔ | ✔ |
| Rilevare checkpoint mancanti/in ritardo | — | ✔ (cadenza concordata) | ✔ |
| Dimostrare che ogni azione è stata registrata | — | — | dipende dal confine di cattura |
Guardane uno prima di installare: un Runtime Report di esempio — dati fittizi, catena reale, e il suo script ricalcola nel tuo browser la catena di hash dei record incorporati quando lo apri.
Nessun agente richiesto. Con uv, niente da installare:
uvx --from halo-record halo demo --serve
o nel modo classico:
pip install halo-record
halo demo --serve
Either one scaffolds a fictional support-agent vendor with two customers, witnesses the chains (with a local witness file standing in for one outside the operator — see LIMITS.md §1), serves their gated Runtime Reports, and opens the operator console in your browser. Then try the tamper test: delete a line from one of the .jsonl files and reload. The report catches it.
Una riga al confine:
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 from halo import ... convenience shim viene fornito anch'esso — ma il nome halo su PyPI appartiene a un pacchetto terminal-spinner non correlato, e se quel pacchetto è installato vince l'import. halo_record è inequivocabile, quindi gli esempi lo usano.
Senza log=, i record vanno in ~/.halo/my-agent.jsonl (una catena per agente). Il wrapper sigilla il confine dell'esecuzione; l'evidenza risiede nei record per chiamata. Catturali con un adattatore di framework (matrice sotto) — o esplicitamente, il che mostra anche come si collegano le deleghe:
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)
Poi genera il report:
halo report audit.jsonl -o report.html # one chain -> HTML that re-verifies in the browser
halo serve ./records --port 8721 # all tenants, gated per customer