halo-record

Enregistrements d'exécution inviolables pour les agents IA : la piste d'audit que le fournisseur exploite mais ne peut pas modifier.

Chaque action de votre agent (appels d'outils, appels de modèles, accès aux données, approbations) devient un enregistrement dans un journal à structure append-only et à chaînage par hachage. Toute partie détenant un point de contrôle de la chaîne peut vérifier que les enregistrements qui la précèdent n'ont jamais été altérés, sans avoir à faire confiance à celui qui les a produits. Quand l'équipe de sécurité d'un client demande « qu'a fait votre agent avec nos données ? », vous lui remettez un lien au lieu d'un paragraphe. Les revues de sécurité posent déjà des questions sur l'IA à côté de la checklist SOC 2, et aujourd'hui une assurance écrite suffit encore. Le pari de ce projet est que cela ne durera pas.

Le format d'enregistrement est ouvert et librement implémentable. Ce paquet est l'implémentation de référence : enregistreur, vérificateur, client témoin et serveur de rapports.

Pourquoi vous pouvez faire confiance à ce code

On vous demande de placer un enregistreur à l'intérieur de votre agent. Vous ne devriez pas l'accepter sur parole :

• Zéro dépendance d'exécution. Uniquement la bibliothèque standard. pip install halo-record installe exactement un paquet.
• Aucun appel réseau, sauf celui du témoin, qui est facultatif et ne reçoit qu'un nombre d'enregistrements et une empreinte de chaîne. Le contenu des enregistrements ne quitte jamais votre infrastructure.
• Les entrées brutes n'entrent jamais dans un enregistrement. Les arguments sont hachés et stockés uniquement sous forme de résumé expurgé — jamais la valeur brute. L'expurgation est au mieux (regex sur les formats courants de secrets et de données personnelles) : traitez-la comme une défense en profondeur, pas comme une garantie.
• Assez petit pour être audité. ~4 300 lignes de Python. Lisez-le en un après-midi.
• Apache-2.0.

Démo de 60 secondes

Aucun agent requis. Avec uv, rien à installer :

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

ou la méthode classique :

pip install halo-record
halo demo --serve

L'un ou l'autre génère un fournisseur fictif d'agent d'assistance client avec deux clients, atteste les chaînes, sert leurs rapports d'exécution protégés et ouvre la console opérateur dans votre navigateur. Essayez ensuite le test d'altération : supprimez une ligne de l'un des fichiers .jsonl et rechargez. Le rapport le détecte.

Enregistrez votre propre agent

Une ligne à la frontière :

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

Sans log=, les enregistrements vont dans ~/.halo/my-agent.jsonl (une chaîne par agent). Ou utilisez l'adaptateur pour ce que vous exécutez déjà (voir la matrice ci-dessous). Ensuite, générez le rapport :

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

Le démarrage rapide se termine lorsque vous voyez le rapport d'exécution de votre propre agent dans un navigateur. Si vous obtenez un fichier JSONL et aucun rapport, quelque chose ne va pas : ouvrez une issue.

Branchez-vous sur ce que vous exécutez déjà

Chaque enregistrement porte une balise source, de sorte que le rapport révèle comment chaque élément de preuve a été collecté. Les enregistrements capturés et ingérés vivent dans la même chaîne.

Tout ce qui émet des spans GenAI OpenTelemetry (CrewAI, LlamaIndex et la plupart des frameworks d'agents avec instrumentation OTel) atterrit dans la chaîne via l'adaptateur OTel, et le paquet TypeScript fournit des adaptateurs natifs pour le Vercel AI SDK et l'écosystème d'agents JS. Un adaptateur manque pour votre stack ? Ouvrez une issue. La plupart des adaptateurs font environ une centaine de lignes.

Enregistrez votre agent de codage

Claude Code déclenche un hook PostToolUse après chaque appel d'outil. Pointez-le vers halo hook et chaque action — écritures de fichiers, commandes shell, appels de connecteurs MCP — devient un enregistrement dans une chaîne locale. Aucune modification de code ; une seule entrée de configuration :

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

Ajoutez cela à ~/.claude/settings.json et les enregistrements atterrissent dans ~/.halo/audit.jsonl (surchargez avec $HALO_LOG). Les outils de pure orchestration qui ne touchent ni données, ni réseau, ni état externe sont ignorés — la chaîne enregistre les actions franchissant la frontière de confiance, pas la réflexion. Définissez HALO_HASH_ONLY=1 pour enregistrer les hachages de contenu sans résumés. Définissez HALO_AGENT_VERSION (et éventuellement HALO_AGENT_MODEL) pour lier chaque enregistrement à la version de l'agent qui l'a produit — lorsqu'un auditeur demande quelle version tournait sur une fenêtre donnée, l'export répond par colonne plutôt que de mémoire.

Si vous avez besoin que le rapport réponde à la question « sous quelles règles cette exécution a-t-elle eu lieu ? », définissez HALO_AUTHORITY_FILE sur un instantané JSON de l'autorité effective pour la session. Restez respectueux de la vie privée : hachages et références, pas de prompts bruts, de texte de politique privée, de secrets ni de schémas d'outils complets.

{
  "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'instantané est scellé dans la même chaîne de hachage que les enregistrements d'actions. Une bonne valeur par défaut est un instantané au niveau de la session au démarrage, plus un nouvel instantané lorsque les règles, Skills, hooks, registres d'outils MCP ou la politique de compactage changent. Pour garder les longues sessions légères, les enregistrements consécutifs portant le même authority.snapshot_id sont compactés après le premier instantané complet : les enregistrements suivants ne conservent que {"snapshot_id": "...", "same_as_previous": true}. Le pointeur reste chaîné par hachage, mais le bloc volumineux refs/omissions/stale-if n'est pas répété à chaque action. Ensuite, comme d'habitude :

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

Tout runtime d'agent qui expose un hook post-action peut alimenter la même commande — le hook lit un événement JSON sur stdin et ajoute un enregistrement.

Intégrité vs exhaustivité (lisez cette partie)

Soyez précis sur ce que chaque couche prouve — car ce sont des revendications différentes, et ce sont ces différences qui comptent :

Une chaîne auto-détenue prouve l'intégrité par rapport à une tête établie : étant donné une tête de chaîne que quelqu'un détient déjà, toute modification, réorganisation ou suppression dans les enregistrements qui la précèdent devient détectable. À elle seule — avant que quiconque en dehors de l'opérateur ait vu une tête — une chaîne prouve une cohérence interne, pas un historique : un opérateur pourrait supprimer un enregistrement et re-sceller, et le nouveau fichier se vérifierait. La chaîne devient historiquement engagée au moment où sa tête quitte le contrôle de l'opérateur.

C'est le rôle du témoin : une partie extérieure à l'opérateur qui détient des empreintes périodiques de la chaîne (un compte et un hachage de tête, rien d'autre). Les points de contrôle rendent détectable la réécriture d'un historique engagé, et un point de contrôle manqué est lui-même un événement visible :

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

Une dernière frontière, énoncée clairement : ni la chaîne ni le témoin ne prouvent que chaque action du monde réel est passée par l'enregistreur. C'est l'exhaustivité de capture — une propriété de l'endroit où se trouve l'enregistreur dans la pile (instrumentation native, hooks, ingestion par passerelle), pas d'un quelconque hachage. Les enregistrements portent une balise source précisément pour cette raison.

N'importe qui peut exécuter un témoin. Un témoin que vous exécutez vous-même engage l'historique envers vous ; l'engager envers votre client nécessite un témoin en qui il a des raisons d'avoir confiance. Le protocole est ouvert dans les deux cas.

Un témoin hébergé et reconnu est ce qui permettra à ce projet de se pérenniser. Accès anticipé : [email protected].

Où cela se situe dans une pile de conformité

halo-record est une couche de preuve, pas une certification. Il produit l'artefact que les référentiels d'évaluation ne cessent de demander en des termes différents :

• Questionnaires de sécurité et revues SOC 2 : répondez aux sections IA avec un rapport d'exécution vérifiable au lieu de captures d'écran et de prose.
• AIUC-1 : produit la journalisation inviolable (E015.4) et les enregistrements de chaîne d'exécution complète avec événements d'autorisation (E015.2) exigés par les contrôles de responsabilité (Accountability) de la norme — une preuve d'exécution continue, non reconstruite au moment de l'audit.
• OWASP (GenAI Security Project) : la preuve d'exécution derrière les risques de comportement d'agents de l'OWASP Top 10 for Agentic Applications 2026 et du LLM Top 10 — détournement d'objectif, mauvais usage des outils, abus d'identité et de privilèges — enregistrée comme ce que l'agent a réellement fait, avec quels outils et quelles données.
• AARM (CSA) : produit le reçu d'action inviolable spécifié par AARM (R5/R6) — chaîné et attesté indépendamment. halo-record est la couche de reçu ; associez-le à une passerelle d'application des règles pour un système AARM complet. Voir AARM.md.
• Agentic Trust Controls : les enregistrements d'exécution derrière les contrôles de preuve de l'ATC — journalisation d'actions inviolable (RBM-03) et attestation d'autorité (AID-05) dans un seul enregistrement chaîné, avec la couche témoin au-delà des deux. Voir ATC.md.
• EU AI Act : obligations de journalisation et de tenue de registres pour les systèmes d'IA à haut risque.
• ISO 42001 / NIST AI RMF : la preuve opérationnelle derrière les contrôles de système de management.

Rien de tout cela ne certifie quoi que ce soit par lui-même. Cela donne à votre évaluateur quelque chose de vérifiable à examiner. Les limites — ce que halo-record ne fait délibérément pas, et quoi dire lorsqu'un réviseur demande — sont documentées dans 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

Modèle d'intégrité

Pour calculer le hachage d'un enregistrement : prenez l'enregistrement en excluant integrity.hash, avec integrity.prev_hash défini sur le hachage de l'enregistrement précédent ; canonisez avec RFC 8785 (JSON Canonicalization Scheme) ; appliquez SHA-256 aux octets. Le prev_hash du premier enregistrement est 64 zéros. La vérification recalcule chaque hachage et vérifie chaque lien. Aucun secret requis ; c'est tout l'intérêt.

Vous pensez pouvoir altérer une chaîne sans que le vérificateur s'en aperçoive ? Les tentatives et résultats sont ici.

Référence complète des champs : halo-record.schema.json.

TypeScript

Le même enregistreur est disponible pour Node : halo-record-ts. Même format de chaîne, même protocole de témoin. Les enregistrements écrits dans l'un ou l'autre langage se vérifient avec l'un ou l'autre vérificateur.

Contribuer

Les issues, discussions et pull requests sont les bienvenues — voir CONTRIBUTING.md pour les règles de base (en bref : tests requis, petites PR, les modifications de schéma sont d'abord discutées).

Licence

Apache-2.0