halo-record

Manipulationssichere Audit-Trails für KI-Agenten — hash-verkettete Runtime Records, dargestellt als Runtime Report, den Ihre Kunden selbst überprüfen können.

Jede Aktion, die Ihre Instrumentierung erfasst (Tool-Aufrufe, Modell-Aufrufe, Datenzugriffe, Genehmigungen), wird zu einem Runtime Record in einem append-only, hash-verketteten Log; der Runtime Report ist diese Kette, dargestellt als HTML-Seite, die die Hash-Kette im Browser des Lesers neu berechnet und das Angezeigte aus den von ihr verifizierten Records rendert (für eine Prüfung, die nicht auf den Code der Seite selbst angewiesen ist, führen Sie halo verify auf der JSONL aus). Jede Partei, die einen Checkpoint der Kette besitzt, kann verifizieren, dass die Records bis zu diesem Checkpoint seit seiner Erstellung nicht verändert wurden, ohne demjenigen vertrauen zu müssen, der sie erzeugt hat — dieser Checkpoint ist das tragende Element: Die Kette allein ist manipulationssicher gegenüber allen außer der Partei, die den Recorder betreibt (LIMITS.md §1). Wenn das Sicherheitsteam eines Kunden fragt „Was hat Ihr Agent mit unseren Daten gemacht?", geben Sie ihm einen Link statt eines Absatzes. Sicherheitsüberprüfungen stellen bereits KI-Fragen neben der SOC-2-Checkliste — und zunehmend kommen diese Fragen aus ISO 42001, den Aufzeichnungspflicht-Artikeln des EU AI Act und den eigenen Fragebögen der Kunden. Heute besteht noch eine schriftliche Zusicherung. Die Wette hinter diesem Projekt ist, dass das nicht lange so bleiben wird.

Vorgestellt in Help Net Security (August 2026).

Das Record-Format ist offen und frei implementierbar. Dieses Paket ist die Referenzimplementierung: Recorder, Verifier, Witness-Client und Report-Server.

Nutzen Sie halo-record oder denken darüber nach? Sagen Sie mir, wer Sie sind und wofür → Who's using halo-record?

Prüfen Sie es selbst

Ihnen wird zugemutet, einen Recorder in Ihren Agenten einzubauen. Das sollten Sie nicht einfach glauben:

• Keine Laufzeitabhängigkeiten. Nur Standardbibliothek. pip install halo-record installiert genau ein Paket.
• Keine Netzwerkaufrufe, außer vier optionalen — Verankerung bei einem Witness (sendet die Subject-ID, eine Record-Anzahl und zwei Ketten-Fingerabdrücke — den Head und die Chain Root), das Zurücklesen der Checkpoints eines Witness (sendet die Subject-ID), der RFC-3161-Zeitstempel (sendet nur den State-Hash eines Checkpoints an eine Timestamp Authority) und halo serve --verify-email (sendet einen Einmalcode und den Subject-Namen des Reports per SMTP über den in $HALO_SMTP_HOST konfigurierten Server an die Adresse, die ein Report-Betrachter eingibt). Alle sind deaktiviert, sofern Sie sie nicht aufrufen; keine anderen Record-Inhalte verlassen Ihre Infrastruktur.
• Rohe Tool-Argumente werden gehasht, mit einer redigierten Zusammenfassung daneben. Argumente werden als kanonischer Hash plus Zusammenfassung gespeichert: der Argumenttext mit maskierten bekannten Secret- und PII-Mustern, auf 200 Zeichen begrenzt. Eine kurze Eingabe, die keinem Muster entspricht, erscheint vollständig in der Zusammenfassung; der Hash-Only-Modus (summaries=False) behält überhaupt keine Zusammenfassung. Die Redaktion ist Best-Effort (Regex über gängige Secret- und PII-Formate plus ein Entropie-Catch-All): Betrachten Sie sie als Defense-in-Depth, nicht als Garantie. Von Ihnen gelieferte Outcome-Felder jenseits von summary werden mit denselben Mustern gescannt und maskiert, aber nicht auf 200 Zeichen gekürzt (LIMITS §13).
• Klein genug zum Auditieren. ~8.700 Zeilen Python, einschließlich des eingebetteten JavaScript und CSS der Report-Seite (Code-Zeilen, ohne Leerzeilen, Kommentare und Docstrings). In einem Tag vollständig lesbar.
• Apache-2.0.
• Der Papierkram ist erstklassig. LIMITS.md (was die Kette nicht beweisen kann), PRIVACY.md (was Records enthalten und was Ihre Maschine verlässt), RETENTION.md (Betrieb unter einer Aufbewahrungsrichtlinie) und REVIEWERS.md — die unabhängige Prüfung mit vier Befehlen plus ein Zitierformat für Review-Befunde.

Was jede Ebene beweist — die tragende Unterscheidung in diesem Projekt (LIMITS.md §1): Eine Kette, die Sie selbst halten, beweist, dass Records nicht bearbeitet wurden, relativ zu einem Head, den jemand bereits hält; nur Checkpoints, die außerhalb des Betreibers gehalten werden, beweisen, dass keine entfernt wurden; und kein Hash beweist, dass jede Aktion erfasst wurde.

Behauptung	Selbst gehaltene Kette	+ Externe Checkpoints	+ Vertrauenswürdige Erfassung
Bearbeitungen an einem etablierten Artefakt erkennen	✔	✔	✔
Umschreiben committeter Historie erkennen	—	✔	✔
Fehlende/verspätete Checkpoints erkennen	—	✔ (vereinbarte Kadenz)	✔
Beweisen, dass jede Aktion aufgezeichnet wurde	—	—	hängt von der Erfassungsgrenze ab

Sehen Sie sich einen an, bevor Sie installieren: ein Beispiel-Runtime-Report — fiktive Daten, echte Kette, und sein Skript berechnet beim Öffnen die Hash-Kette der eingebetteten Records in Ihrem Browser neu.

60-Sekunden-Demo

Kein Agent erforderlich. Mit uv nichts zu installieren:

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

oder auf die klassische Weise:

pip install halo-record
halo demo --serve

Entweder scaffoldet es einen fiktiven Support-Agent-Anbieter mit zwei Kunden, bezeugt die Chains (mit einer lokalen Witness-Datei als Stellvertreter für eine außerhalb des Operators — siehe LIMITS.md §1), liefert deren gated Runtime Reports aus und öffnet die Operator-Konsole in deinem Browser. Probiere dann den Tamper-Test: Lösche eine Zeile aus einer der .jsonl-Dateien und lade neu. Der Report erkennt es.

Zeichne deinen eigenen Agenten auf

Eine Zeile an der Grenze:

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

Ein from halo import ... Convenience-Shim wird ebenfalls mitgeliefert — aber der Name halo auf PyPI gehört zu einem unabhängigen Terminal-Spinner-Paket, und wenn dieses Paket installiert ist, gewinnt es den Import. halo_record ist eindeutig, daher verwenden die Beispiele es.

Ohne log= gehen Records nach ~/.halo/my-agent.jsonl (eine Chain pro Agent). Der Wrapper versiegelt die Run-Grenze; die Evidenz liegt in den Per-Call-Records. Erfasse diese mit einem Framework-Adapter (Matrix unten) — oder explizit, was auch zeigt, wie Delegation verknüpft:

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)

Dann den Bericht rendern:

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