halo-record

Registri di runtime a prova di manomissione per agenti AI: la traccia di audit che il fornitore esegue ma non può modificare.

Ogni azione compiuta dal tuo agente (chiamate a strumenti, chiamate a modelli, accesso ai dati, approvazioni) diventa un record in un log a struttura append, concatenato tramite hash. Qualsiasi parte che detiene un checkpoint della catena può verificare che i record sottostanti non siano mai stati alterati, senza doversi fidare di chi li ha prodotti. Quando il team di sicurezza di un cliente chiede "cosa ha fatto il tuo agente con i nostri dati?", gli dai un link invece di un paragrafo. Le revisioni di sicurezza fanno già domande sull'AI accanto alla checklist SOC 2, e oggi una dichiarazione scritta è ancora sufficiente. La scommessa dietro questo progetto è che non lo sarà per molto.

Il formato del record è aperto e liberamente implementabile. Questo pacchetto è l'implementazione di riferimento: registratore, verificatore, client witness e server per i report.

Perché puoi fidarti di questo codice

Ti viene chiesto di inserire un registratore all'interno del tuo agente. Non dovresti prenderlo per buono:

• Zero dipendenze runtime. Solo libreria standard. pip install halo-record installa esattamente un pacchetto.
• Nessuna chiamata di rete, eccetto il witness, che è opzionale e riceve solo un conteggio di record e un'impronta digitale della catena. I contenuti dei record non lasciano mai la tua infrastruttura.
• I dati grezzi non entrano mai in un record. Gli argomenti vengono hashati e memorizzati solo come riepilogo oscurato — mai il valore grezzo. L'oscuramento è best-effort (regex su formati comuni di segreti e PII): trattalo come difesa in profondità, non come garanzia.
• Abbastanza piccolo da essere revisionato. ~4.300 righe di Python. Leggi tutto in un pomeriggio.
• Apache-2.0.

Demo in 60 secondi

Nessun agente richiesto. Con uv, niente da installare:

uvx --from halo-record halo demo --serve

o il metodo classico:

pip install halo-record
halo demo --serve

In entrambi i casi viene creato un fornitore fittizio di agenti di supporto con due clienti, vengono attestate le catene, vengono serviti i loro Runtime Report con accesso limitato, e viene aperta la console operatore nel browser. Poi prova il test di manomissione: cancella una riga da uno dei file .jsonl e ricarica. Il report lo rileva.

Registra il tuo agente

Una riga al confine:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # avvolge il tuo entrypoint; registra ogni chiamata a strumenti in ./audit.jsonl

Senza log=, i record vanno in ~/.halo/my-agent.jsonl (una catena per agente). Oppure usa l'adattatore per ciò che già esegui (vedi la matrice sotto). Poi genera il report:

halo report audit.jsonl -o report.html    # una catena -> HTML auto-verificante
halo serve ./records --port 8721          # tutti i tenant, con accesso per cliente

Il quickstart termina quando stai guardando il Runtime Report del tuo agente in un browser. Se hai ottenuto un file JSONL e nessun report, qualcosa non va: apri un issue.

Collegati a ciò che già esegui

Ogni record porta un tag source, quindi il report rivela come è stata raccolta ogni prova. I record catturati e quelli ingeriti vivono nella stessa catena.

Qualsiasi cosa che emetta span GenAI di OpenTelemetry (CrewAI, LlamaIndex e la maggior parte dei framework per agenti con strumentazione OTel) finisce nella catena tramite l'adattatore OTel, e il pacchetto TypeScript fornisce adattatori nativi per il Vercel AI SDK e l'ecosistema JS degli agenti. Manca un adattatore per il tuo stack? Apri un issue. La maggior parte degli adattatori sono circa un centinaio di righe.

Registra il tuo agente di coding

Claude Code attiva un hook PostToolUse dopo ogni chiamata a strumento. Punta a halo hook e ogni azione — scritture di file, comandi shell, chiamate a connettori MCP — diventa un record in una catena locale. Nessuna modifica al codice; una voce nelle impostazioni:

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

Aggiungila a ~/.claude/settings.json e i record finiscono in ~/.halo/audit.jsonl (sovrascrivibile con $HALO_LOG). Gli strumenti di pura orchestrazione che non toccano dati, rete o stato esterno vengono saltati — la catena registra azioni al confine di fiducia, non il pensiero. Imposta HALO_HASH_ONLY=1 per registrare hash dei contenuti senza riepiloghi. Imposta HALO_AGENT_VERSION (e opzionalmente HALO_AGENT_MODEL) per associare ogni record alla build dell'agente che lo ha prodotto — quando un revisore chiede quale versione era in esecuzione in una certa finestra, l'esportazione risponde per colonna invece che a memoria.

Se hai bisogno che il report risponda a "sotto quali regole è avvenuta questa esecuzione?", imposta HALO_AUTHORITY_FILE su un'istantanea JSON dell'autorità effettiva per la sessione. Mantienila privacy-safe: hash e riferimenti, non prompt grezzi, testo di policy private, segreti o schemi completi degli strumenti.

{
  "snapshot_id": "auth_2026_07_08T1100Z",
  "captured_at": "2026-07-08T11:00:00Z",
  "scope": "session",
  "workspace": {"path_hash": "sha256:...", "git_commit": "abc1234"},
  "refs": [
    {"kind": "project_rules", "id": "CLAUDE.md", "hash": "sha256:...", "loaded": true, "truncated": false},
    {"kind": "mcp_tool_registry", "id": "filesystem", "hash": "sha256:..."}
  ],
  "omissions": [{"kind": "private_policy", "reason": "customer_secret", "hash": "sha256:..."}],
  "stale_if": ["project_rules_hash_changed", "mcp_tool_registry_hash_changed"]
}

HALO_AUTHORITY_FILE=./authority.json halo hook

L'istantanea viene sigillata nella stessa catena di hash dei record delle azioni. Una buona impostazione predefinita è un'istantanea a livello di sessione all'inizio, più una nuova istantanea quando cambiano regole, Skills, hook, registri di strumenti MCP o policy di compattazione. Per mantenere leggere le sessioni lunghe, i record consecutivi con lo stesso authority.snapshot_id vengono compattati dopo la prima istantanea completa: i record successivi mantengono solo {"snapshot_id": "...", "same_as_previous": true}. Il puntatore rimane nella catena di hash, ma il blocco ingombrante di refs/omissions/stale-if non viene ripetuto per ogni azione. Poi, come di consueto:

halo verify ~/.halo/audit.jsonl
halo report ~/.halo/audit.jsonl -o report.html

Qualsiasi runtime per agenti che esponga un hook post-azione può alimentare lo stesso comando — l'hook legge un singolo evento come JSON su stdin e aggiunge un record.

Integrità vs. completezza (leggi questa parte)

Sii preciso su cosa dimostra ogni livello — perché sono affermazioni diverse, e le differenze sono il punto:

Una catena detenuta da sé prova l'integrità rispetto a un capo stabilito: dato un capo di catena che qualcuno già possiede, qualsiasi modifica, riordino o cancellazione nei record sottostanti diventa rilevabile. Da sola — prima che qualcuno al di fuori dell'operatore abbia visto un capo — una catena prova coerenza interna, non storia: un operatore potrebbe eliminare un record e risigillare, e il nuovo file sarebbe verificato. La catena diventa storicamente impegnata nel momento in cui il suo capo esce dal controllo dell'operatore.

Ecco il witness: una parte al di fuori dell'operatore che conserva impronte digitali periodiche della catena (un conteggio e un hash del capo, nient'altro). I checkpoint rendono rilevabile la riscrittura della storia impegnata, e un checkpoint mancato è di per sé un evento visibile:

halo anchor audit.jsonl witness.jsonl           # ancora un checkpoint a un witness locale
halo anchor audit.jsonl witness.jsonl --check   # verdetto di completezza rispetto ad esso

Un altro confine, dichiarato esplicitamente: né la catena né il witness provano che ogni azione del mondo reale sia passata attraverso il registratore. Questa è la completezza della cattura — una proprietà di dove si trova il registratore nello stack (strumentazione nativa, hook, ingestione tramite gateway), non di alcun hash. I record portano un tag source proprio per questo motivo.

Chiunque può eseguire un witness. Un witness che esegui tu stesso impegna la storia verso di te; impegnarla verso il tuo cliente richiede un witness di cui loro abbiano motivo di fidarsi. Il protocollo è aperto in entrambi i casi.

Un witness ospitato e riconosciuto è il modo in cui questo progetto si sosterrà. Accesso anticipato: [email protected].

Dove si colloca in uno stack di conformità

halo-record è un livello di evidenza, non una certificazione. Produce l'artefatto che i framework di valutazione continuano a chiedere con parole diverse:

• Questionari di sicurezza e revisioni SOC 2: rispondi alle sezioni AI con un Runtime Report verificabile invece che con screenshot e prosa.
• AIUC-1: produce la registrazione a prova di manomissione (E015.4) e i record completi della catena di esecuzione con eventi di autorizzazione (E015.2) richiesti dai controlli di responsabilità dello standard — evidenza runtime continua, non ricostruita al momento dell'audit.
• OWASP (GenAI Security Project): l'evidenza runtime dietro i rischi di comportamento degli agenti nel OWASP Top 10 for Agentic Applications 2026 e nel LLM Top 10 — dirottamento degli obiettivi, uso improprio degli strumenti, abuso di identità e privilegi — registrata come ciò che l'agente ha effettivamente fatto, con quali strumenti e dati.
• AARM (CSA): produce la ricevuta di azione a prova di manomissione specificata da AARM (R5/R6) — concatenata e attestata indipendentemente. halo-record è il livello di ricevuta; accoppialo con un gateway di enforcement per un sistema AARM completo. Vedi AARM.md.
• Agentic Trust Controls: i record runtime dietro i controlli di evidenza dell'ATC — registrazione delle azioni a prova di manomissione (RBM-03) e attestazione dell'autorità (AID-05) in un unico record concatenato, con il livello witness oltre entrambi. Vedi ATC.md.
• EU AI Act: obblighi di registrazione e conservazione dei log per sistemi AI ad alto rischio.
• ISO 42001 / NIST AI RMF: l'evidenza operativa dietro i controlli del sistema di gestione.

Niente di tutto questo certifica nulla da solo. Dà al tuo valutatore qualcosa di verificabile da guardare. I confini — ciò che halo-record deliberatamente non fa, e cosa dire quando un revisore chiede — sono documentati in LIMITS.md.

CLI

halo verify   convalida schema + catena di hash (exit code non zero in caso di fallimento; adatto a CI)
halo report   genera una catena come Runtime Report HTML auto-verificante
              (--from/--to: un report con finestra temporale che copre solo il periodo di revisione)
halo serve    serve report per tenant su HTTP, accesso con ambito per cliente
halo grant    designa un destinatario del report (email o dominio)
halo anchor   attesta un capo di catena, oppure --check per la completezza
halo demo     crea la demo completa del fornitore (registrazione -> witness -> report con accesso limitato)
halo export   esportazione di evidenze con limite temporale: CSV + manifest legato al capo della catena
halo sample   emette un log di esempio valido
halo hash     sha256 canonico di un valore JSON
halo hook     hook PostToolUse di Claude Code

Modello di integrità

Per calcolare l'hash di un record: prendi il record escludendo integrity.hash, con integrity.prev_hash impostato all'hash del record precedente; canonicalizza con RFC 8785 (JSON Canonicalization Scheme); SHA-256 dei byte. Il prev_hash del primo record è 64 zeri. La verifica ricalcola ogni hash e controlla ogni collegamento. Nessun segreto richiesto; questo è il punto.

Pensi di poter manomettere una catena senza che il verificatore se ne accorga? Tentativi e risultati sono qui.

Riferimento completo dei campi: halo-record.schema.json.

TypeScript

Lo stesso registratore è disponibile per Node: halo-record-ts. Stesso formato di catena, stesso protocollo witness. I record scritti in un linguaggio si verificano con l'altro verificatore.

Contribuire

Issue, discussioni e pull request sono benvenuti — vedi CONTRIBUTING.md per le regole di base (versione breve: test richiesti, PR piccole, le modifiche allo schema vengono discusse prima).

Licenza

Apache-2.0