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 Ihr Agent ausführt (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 selbstverifizierende HTML-Seite. Jede Partei, die einen Checkpoint der Kette besitzt, kann verifizieren, dass die dahinterliegenden Records nie 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.

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

Überprüfen Sie es selbst

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

• Keine Runtime-Abhängigkeiten. Nur Standardbibliothek. pip install halo-record installiert genau ein Paket.
• Keine Netzwerkaufrufe, außer drei optionalen — Verankerung bei einem Witness (sendet die Subject-ID, eine Record-Anzahl und zwei Chain-Fingerprints — den Head und die Chain Root), das Zurücklesen der Checkpoints eines Witness (sendet die Subject-ID) und der RFC-3161-Zeitstempel (sendet nur den State-Hash eines Checkpoints an eine Timestamp Authority). Alle sind deaktiviert, sofern Sie sie nicht aufrufen; Record-Inhalte verlassen niemals Ihre Infrastruktur.
• Rohe Tool-Argumente werden gehasht, mit einer redigierten Zusammenfassung daneben. Argumente werden als kanonischer Hash plus einer 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 bereitgestellte Outcome-Felder jenseits von summary werden so versiegelt, wie sie sind (LIMITS §13).
• Klein genug zum Auditieren. ~5.300 Zeilen Python (Codezeilen, ohne Leerzeilen und Kommentare). In einem Nachmittag 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 editiert 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	Selbstgehaltene Kette	+ Externe Checkpoints	+ Vertrauenswürdige Erfassung
Edits an einem etablierten Artefakt erkennen	✔	✔	✔
Umschreiben der committeten 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 er verifiziert sich selbst in Ihrem Browser, während Sie zusehen.

60-Sekunden-Demo

Kein Agent erforderlich. Mit uv gibt es nichts zu installieren:``` uvx --from halo-record halo demo --serve

oder auf die klassische Weise:```
pip install halo-record
halo demo --serve

Entweder scaffoldet man einen fiktiven Support-Agent-Anbieter mit zwei Kunden, beobachtet die Chains (mit einer lokalen Witness-Datei als Stellvertreter für eine außerhalb des Operators — siehe LIMITS.md §1), serviert deren gated Runtime Reports und öffnet die Operator-Konsole im Browser. Dann den Tamper-Test versuchen: eine Zeile aus einer der .jsonl-Dateien löschen und neu laden. Der Report erkennt es.

Den eigenen Agenten aufzeichnen

Eine Zeile an der Grenze:```python 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 Pro-Call-Records. Erfasse diese mit einem Framework-Adapter (Matrix unten) — oder explizit, was auch zeigt, wie Delegation verknüpft:```python
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 -> self-verifying HTML halo serve ./records --port 8721 # all tenants, gated per customer

Der Quickstart endet, wenn Sie den Runtime Report Ihres eigenen Agenten im Browser sehen. Wenn Sie eine JSONL-Datei ohne Report erhalten haben, ist etwas schiefgelaufen: Öffnen Sie ein Issue.

### Der Verifikationsblock

Wenn eine Guardrail- oder Policy-Schicht die Aktion geprüft hat, kann ihr Urteil am Datensatz mitgeführt werden — ein optionaler Block, der festhält, was das Gate entschieden hat, und der wie jedes andere Feld in die Hash-Kette versiegelt wird:```python
from halo_record import build