halo-record

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

Ogni azione compiuta dal tuo agente (chiamate a strumenti, chiamate al modello, accesso ai dati, approvazioni) diventa un record in un log a struttura append e concatenato tramite hash. Qualsiasi soggetto in possesso di un checkpoint della catena può verificare che i record precedenti 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 consegni un link invece di un paragrafo. Le revisioni di sicurezza già pongono domande sull'AI accanto alla checklist SOC 2, e oggi una garanzia scritta è ancora sufficiente. La scommessa dietro questo progetto è che non lo sarà ancora a lungo.

Il formato dei record è aperto e libero da implementare. Questo pacchetto è l'implementazione di riferimento: registratore, verificatore, client witness e server di report.

Perché puoi fidarti di questo codice

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

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

Demo in 60 secondi

Nessun agente richiesto. Con uv, nulla da installare:

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

oppure nel modo classico:

pip install halo-record
halo demo --serve

Entrambi generano un fornitore fittizio di agenti di supporto con due clienti, attestano le catene, servono i loro Runtime Report con accesso controllato e aprono la console 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 import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # wraps your entrypoint; records every tool call to ./audit.jsonl

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

halo report audit.jsonl -o report.html    # one chain -> self-verifying HTML
halo serve ./records --port 8721          # all tenants, gated per customer

Il quickstart termina quando stai guardando il Runtime Report del tuo agente in un browser. Se hai ottenuto un file JSONL ma nessun report, qualcosa non va: apri una 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 acquisiti vivono nella stessa catena.

Qualsiasi cosa emetta span GenAI 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 include adattatori nativi per Vercel AI SDK e per l'ecosistema di agenti JS. Manca un adattatore per il tuo stack? Apri una issue. La maggior parte degli adattatori è di circa un centinaio di righe.

Registra il tuo agente di coding

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

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

Aggiungila a ~/.claude/settings.json e i record finiranno 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 le azioni al confine di fiducia, non i pensieri. Imposta HALO_HASH_ONLY=1 per registrare hash di contenuti senza riepiloghi. Imposta HALO_AGENT_VERSION (e opzionalmente HALO_AGENT_MODEL) per legare ogni record alla build dell'agente che lo ha prodotto — quando un auditor chiede quale versione era in esecuzione in una data finestra, l'export risponde con una colonna invece che a memoria.

Se hai bisogno che il report risponda a «in base a quali regole è avvenuta questa esecuzione?», imposta HALO_AUTHORITY_FILE su uno snapshot JSON dell'autorità effettiva per la sessione. Mantienilo privacy-safe: hash e riferimenti, non prompt grezzi, testi 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

Lo snapshot viene sigillato nella stessa catena hash dei record delle azioni. Una buona impostazione predefinita è uno snapshot a livello di sessione all'avvio, più un nuovo snapshot quando cambiano regole, Skills, hook, registry di strumenti MCP o la policy di compattazione. Per mantenere leggere le sessioni lunghe, i record consecutivi con lo stesso authority.snapshot_id vengono compattati dopo il primo snapshot completo: i record successivi mantengono solo {"snapshot_id": "...", "same_as_previous": true}. Il puntatore resta concatenato tramite hash, ma il blocco voluminoso refs/omissions/stale-if non viene ripetuto a ogni azione. Poi, il solito:

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 evento come JSON dallo 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 in tuo possesso dimostra l'integrità rispetto a una testa consolidata: data una testa di catena che qualcuno già possiede, qualsiasi modifica, riordinamento o cancellazione nei record precedenti diventa rilevabile. Da sola — prima che chiunque al di fuori dell'operatore abbia visto una testa — una catena dimostra la coerenza interna, non la storia: un operatore potrebbe eliminare un record e risigillare, e il nuovo file risulterebbe valido. La catena diventa storicamente vincolata nel momento in cui la sua testa esce dal controllo dell'operatore.

Questo è il witness: un soggetto esterno all'operatore che conserva impronte periodiche della catena (un conteggio e un hash della testa, nient'altro). I checkpoint rendono rilevabile la riscrittura della storia vincolata, e un checkpoint mancato è di per sé un evento visibile:

halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

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

Chiunque può eseguire un witness. Un witness che esegui tu stesso vincola la storia a te; vincolarla al tuo cliente richiede un witness di cui lui abbia 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 sull'AI con un Runtime Report verificabile invece di screenshot e prosa.
• AIUC-1: produce la registrazione a prova di manomissione (E015.4) e i record dell'intera catena di esecuzione con eventi di autorizzazione (E015.2) richiesti dai controlli di Accountability dello standard — evidenza runtime continua, non ricostruita al momento dell'audit.
• OWASP (GenAI Security Project): l'evidenza runtime dietro i rischi comportamentali degli agenti nell'OWASP Top 10 for Agentic Applications 2026 e nell'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 in modo indipendente. halo-record è il livello delle ricevute; abbinalo a 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 record per i sistemi di AI ad alto rischio.
• ISO 42001 / NIST AI RMF: l'evidenza operativa dietro i controlli dei sistemi di gestione.

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

CLI

halo verify   validate schema + hash chain (non-zero exit on failure; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
              (--from/--to: a date-windowed report covering only the review period)
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo anchor   witness a chain head, or --check completeness
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo export   date-bounded evidence export: CSV + manifest tied to the chain head
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook

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); applica SHA-256 ai byte. Il prev_hash del primo record è 64 zeri. La verifica ricalcola ogni hash e controlla ogni collegamento. Nessun segreto richiesto; è proprio 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 uno dei due linguaggi si verificano con entrambi i verificatori.

Contributi

Issue, discussioni e pull request sono benvenute — 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