
halo-record v0.2.32
Registri di controllo a prova di manomissione per agenti AI: Runtime Records concatenati tramite hash, senza dipendenze, verificabili da chiunque.
halo-record
Audit trail a prova di manomissione per agenti AI — Runtime Record concatenati tramite hash, resi 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 resa 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 un controllo 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 preso, senza fidarsi di chi li ha prodotti — quel checkpoint è il pezzo portante: la catena da sola è a prova di manomissione contro tutti tranne che contro chi gestisce il registratore (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.
"Vent'anni di informatica forense ti insegnano che una prova è una prova solo se l'altra parte può verificarla... in un settore pieno di prodotti AI che chiedono fiducia, [Halo] è quello raro progettato per rendere la fiducia superflua."
Johannes Stillig, Fondatore e CEO di Tidebreak AI e Group CISO presso un family office di investimenti privati
Segnalato su Help Net Security · Top 4% dei lanci Show HN di quella settimana · Inserito in Agentic Trust Controls rispetto a cinque controlli
Il formato dei record è aperto e libero da implementare. Questo pacchetto è l'implementazione di riferimento: registratore, verificatore, client witness e server dei report.
Stai usando halo-record, o ci stai pensando? Dimmi chi sei e per cosa → Chi usa halo-record?
Verificalo tu stesso
Ti viene chiesto di inserire un registratore dentro il tuo agente. Non dovresti accettarlo sulla fiducia:
- Zero dipendenze a runtime. Solo libreria standard.
pip install halo-recordinstalla esattamente un pacchetto. - Nessuna chiamata di rete, tranne quattro opt-in — l'ancoraggio a un witness (invia l'id del soggetto, un conteggio dei record e due impronte della catena — la testa e la radice della catena), la lettura dei checkpoint di un witness (invia l'id del soggetto), il timestamp RFC 3161 (invia solo l'hash di stato di un checkpoint a una Timestamp Authority) e
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 un visualizzatore del report). Tutte sono disattivate a meno che tu non le invochi; nessun altro contenuto dei record lascia la tua infrastruttura. - Gli argomenti grezzi degli strumenti vengono sottoposti a hash, con accanto un riepilogo redatto. Gli argomenti sono memorizzati come hash canonico più un riepilogo: il testo dell'argomento con i pattern noti di segreti e PII mascherati, limitato a 200 caratteri. Un input breve che non corrisponde ad alcun pattern appare per intero nel riepilogo; la modalità solo-hash (
summaries=False) non conserva alcun riepilogo. La redazione è best-effort (regex sui formati comuni di segreti e PII più un catch-all entropico): trattala come difesa in profondità, non come garanzia. I campi di esito che fornisci oltre asummaryvengono scansionati e mascherati con gli stessi pattern, ma non troncati a 200 caratteri (LIMITS §13). - Abbastanza piccolo da essere verificato. ~8.700 righe di Python, inclusi JavaScript e CSS incorporati nella pagina del report (righe di codice, esclusi righe vuote, commenti e docstring). Puoi leggerlo tutto in un giorno.
- Apache-2.0.
- La documentazione è di prim'ordine. LIMITS.md (cosa la catena non può dimostrare), PRIVACY.md (cosa contengono i record e cosa lascia la tua macchina), RETENTION.md (operare sotto una politica di conservazione) e REVIEWERS.md — il controllo indipendente in quattro comandi più un formato di citazione per i risultati della revisione.
Cosa dimostra ciascun livello — la distinzione portante in questo progetto (LIMITS.md §1): una catena che tieni tu stesso dimostra che i record non sono stati modificati, rispetto a una testa che qualcuno 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 storia consolidata | — | ✔ | ✔ |
| Rilevare checkpoint mancanti/in ritardo | — | ✔ (cadenza concordata) | ✔ |
| Dimostrare che ogni azione è stata registrata | — | — | dipende dal confine di cattura |
Vedine uno prima di installare: un Runtime Report di esempio — dati fittizi, catena reale, e il suo script ricalcola la catena di hash dei record incorporati nel tuo browser quando lo apri.
Demo da 60 secondi
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
Oppure crea lo scaffold di un fornitore fittizio di agenti di supporto con due clienti, osserva le catene (con un file di testimonianza locale che sostituisce una testimonianza esterna all'operatore — vedi LIMITS.md §1), fornisce i loro Runtime Report soggetti a controllo e apre la console dell'operatore nel tuo browser. Poi prova il test di manomissione: elimina una riga da uno dei file .jsonl e ricarica. Il report lo rileva.
Registra il tuo agente
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
Anche uno shim di comodità from halo import ... viene fornito — ma il nome halo su PyPI appartiene a un pacchetto terminal-spinner non correlato, e se quel pacchetto è installato vince l'import. halo_record non è ambiguo, quindi gli esempi lo usano.
Senza log=, i record vanno in ~/.halo/my-agent.jsonl (una catena per agente). Il wrapper sigilla il confine di 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")