halo-record

Manipulationssichere Laufzeitaufzeichnungen für KI-Agenten: das Prüfprotokoll, das der Anbieter führt, aber nicht ändern kann.

Jede Aktion, die Ihr Agent ausführt (Tool-Aufrufe, Modellaufrufe, Datenzugriffe, Genehmigungen), wird zu einem Datensatz in einem append-basierten, hash-verketteten Log. Jede Partei, die einen Prüfpunkt der Kette besitzt, kann verifizieren, dass die dahinterliegenden Datensätze nie verändert wurden, ohne dem Erzeuger vertrauen zu müssen. Wenn das Sicherheitsteam eines Kunden fragt: „Was hat Ihr Agent mit unseren Daten gemacht?“, übergeben Sie einen Link statt eines Absatzes. Sicherheitsprüfungen stellen bereits KI-Fragen neben der SOC-2-Checkliste, und heute wird eine schriftliche Zusicherung noch akzeptiert. Die Wette hinter diesem Projekt ist, dass das nicht mehr lange so bleibt.

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

Warum Sie diesem Code vertrauen können

Sie werden gebeten, 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 dem Witness, der optional ist und nur eine Datensatzanzahl und einen Chain-Fingerprint erhält. Datensatzinhalte verlassen nie Ihre Infrastruktur.
• Rohe Eingaben gelangen nie in einen Datensatz. Argumente werden gehasht und nur als geschwärzte Zusammenfassung gespeichert — nie der Rohwert. Die Schwärzung ist Best-Effort (Regex über gängige Secret- und PII-Formate): Behandeln Sie sie als Defense-in-Depth, nicht als Garantie.
• Klein genug zum Prüfen. ~4.300 Zeilen Python. Sie können alles an einem Nachmittag lesen.
• Apache-2.0.

60-Sekunden-Demo

Kein Agent erforderlich. Mit uv ist nichts zu installieren:

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

oder auf klassische Weise:

pip install halo-record
halo demo --serve

Beide Varianten erzeugen einen fiktiven Support-Agent-Anbieter mit zwei Kunden, hinterlegen Witness-Prüfpunkte für die Chains, stellen deren zugriffsgeschützte Runtime-Reports bereit und öffnen die Operator-Konsole in Ihrem Browser. Probieren Sie dann den Manipulationstest: Löschen Sie eine Zeile aus einer der .jsonl-Dateien und laden Sie neu. Der Report erkennt es.

Eigenen Agenten aufzeichnen

Eine Zeile an der Grenze:

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

Ohne log= gehen die Aufzeichnungen nach ~/.halo/my-agent.jsonl (eine Chain pro Agent). Oder nutzen Sie den Adapter für das, was Sie bereits ausführen (siehe Matrix unten). Rendern Sie dann den Report:

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

Der Schnellstart endet, wenn Sie den Runtime-Report Ihres eigenen Agenten in einem Browser betrachten. Wenn Sie eine JSONL-Datei erhalten haben, aber keinen Report, stimmt etwas nicht: Eröffnen Sie ein Issue.

Anbindung an das, was Sie bereits ausführen

Jeder Datensatz trägt ein source-Tag, sodass der Report offenlegt, wie jedes Beweisstück gesammelt wurde. Erfasste und eingespeiste Datensätze leben in derselben Chain.

Alles, was OpenTelemetry-GenAI-Spans emittiert (CrewAI, LlamaIndex und die meisten Agent-Frameworks mit OTel-Instrumentierung), landet über den OTel-Adapter in der Chain, und das TypeScript-Paket enthält native Adapter für das Vercel AI SDK und das JS-Agenten-Ökosystem. Fehlt ein Adapter für Ihren Stack? Eröffnen Sie ein Issue. Die meisten Adapter umfassen etwa hundert Zeilen.

Ihren Coding-Agenten aufzeichnen

Claude Code löst nach jedem Tool-Aufruf einen PostToolUse-Hook aus. Richten Sie ihn auf halo hook aus, und jede Aktion — Dateischreibvorgänge, Shell-Befehle, MCP-Connector-Aufrufe — wird zu einem Datensatz in einer lokalen Chain. Keine Codeänderungen; nur ein Eintrag in den Einstellungen:

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

Fügen Sie das zu ~/.claude/settings.json hinzu, und die Aufzeichnungen landen in ~/.halo/audit.jsonl (überschreibbar mit $HALO_LOG). Reine Orchestrierungswerkzeuge, die keine Daten, kein Netzwerk und keinen externen Zustand berühren, werden übersprungen — die Chain zeichnet Aktionen an der Vertrauensgrenze auf, nicht das Denken. Setzen Sie HALO_HASH_ONLY=1, um Inhalts-Hashes ohne Zusammenfassungen aufzuzeichnen. Setzen Sie HALO_AGENT_VERSION (und optional HALO_AGENT_MODEL), um jeden Datensatz an den Agenten-Build zu binden, der ihn erzeugt hat — wenn ein Prüfer nach der Version fragt, die in einem bestimmten Zeitraum lief, beantwortet der Export das spaltenweise statt aus dem Gedächtnis.

Wenn der Report beantworten soll, „unter welchen Regeln fand diese Ausführung statt?“, setzen Sie HALO_AUTHORITY_FILE auf einen JSON-Snapshot der wirksamen Autorität für die Sitzung. Halten Sie es datenschutzfreundlich: Hashes und Referenzen, keine Roh-Prompts, keine privaten Richtlinientexte, keine Geheimnisse und keine vollständigen Toolschemata.

{
  "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

Der Snapshot wird in dieselbe Hash-Kette wie die Aktionsdatensätze versiegelt. Eine gute Standardeinstellung ist ein Sitzungs-Snapshot zu Beginn plus ein neuer Snapshot, wenn sich Regeln, Skills, Hooks, MCP-Tool-Registrierungen oder die Kompaktierungsrichtlinie ändern. Um lange Sitzungen schlank zu halten, werden aufeinanderfolgende Datensätze mit derselben authority.snapshot_id nach dem ersten vollständigen Snapshot kompaktiert: Spätere Datensätze behalten nur {"snapshot_id": "...", "same_as_previous": true}. Der Zeiger bleibt hash-verkettet, aber der umfangreiche refs/omissions/stale-if-Block wird nicht bei jeder Aktion wiederholt. Dann das Übliche:

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

Jede Agentenlaufzeit, die einen Post-Action-Hook bereitstellt, kann denselben Befehl speisen — der Hook liest ein Ereignis als JSON von stdin und hängt einen Datensatz an.

Integrität vs. Vollständigkeit (diesen Teil lesen)

Seien Sie präzise, was jede Ebene beweist — denn es sind unterschiedliche Behauptungen, und genau diese Unterschiede sind der springende Punkt:

Eine selbst gehaltene Chain beweist Integrität relativ zu einem etablierten Kopf: Wenn jemand bereits einen Chain-Kopf besitzt, wird jede Änderung, Umordnung oder Löschung in den dahinterliegenden Datensätzen erkennbar. Für sich allein — bevor jemand außerhalb des Betreibers einen Kopf gesehen hat — beweist eine Chain innere Konsistenz, nicht Geschichte: Ein Betreiber könnte einen Datensatz verwerfen und neu versiegeln, und die neue Datei würde verifizieren. Die Chain wird in dem Moment historisch verbindlich, in dem ihr Kopf die Kontrolle des Betreibers verlässt.

Das ist der Witness: eine Partei außerhalb des Betreibers, die periodische Fingerabdrücke der Chain hält (eine Anzahl und einen Kopf-Hash, sonst nichts). Prüfpunkte machen das Umschreiben der verbindlichen Geschichte erkennbar, und ein versäumter Prüfpunkt ist selbst ein sichtbares Ereignis:

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

Noch eine Grenze, klar gesagt: Weder die Chain noch der Witness beweist, dass jede reale Aktion durch den Recorder lief. Das ist Erfassungsvollständigkeit — eine Eigenschaft des Ortes, an dem der Recorder im Stack sitzt (native Instrumentierung, Hooks, Gateway-Einspeisung), nicht irgendeines Hashes. Datensätze tragen genau aus diesem Grund ein source-Tag.

Jeder kann einen Witness betreiben. Ein Witness, den Sie selbst betreiben, verankert die Geschichte bei Ihnen; sie bei Ihrem Kunden zu verankern, erfordert einen Witness, dem der Kunde Grund hat zu vertrauen. Das Protokoll ist in beiden Fällen offen.

Ein gehosteter, anerkannter Witness ist die Art, wie sich dieses Projekt selbst trägt. Early Access: [email protected].

Wo das in einem Compliance-Stack steht

halo-record ist eine Beweisebene, keine Zertifizierung. Es erzeugt das Artefakt, das Bewertungsrahmenwerke immer wieder mit anderen Worten verlangen:

• Sicherheitsfragebögen und SOC-2-Prüfungen: Beantworten Sie die KI-Abschnitte mit einem verifizierbaren Runtime-Report statt mit Screenshots und Prosa.
• AIUC-1: erzeugt die manipulationssichere Protokollierung (E015.4) und die Aufzeichnungen der vollständigen Ausführungskette mit Autorisierungsereignissen (E015.2), die die Accountability-Kontrollen des Standards verlangen — kontinuierliche Laufzeitbeweise, nicht erst bei der Prüfung rekonstruiert.
• OWASP (GenAI Security Project): die Laufzeitbeweise hinter den Agentenverhaltensrisiken im OWASP Top 10 for Agentic Applications 2026 und im LLM Top 10 — Zielentführung, Tool-Missbrauch, Identitäts- und Privilegienmissbrauch — aufgezeichnet als das, was der Agent tatsächlich getan hat, mit welchen Tools und Daten.
• AARM (CSA): erzeugt die manipulationssichere Aktionsquittung, die AARM spezifiziert (R5/R6) — verkettet und unabhängig bezeugt. halo-record ist die Quittungsebene; kombinieren Sie es mit einem Enforcement-Gateway für ein vollständiges AARM-System. Siehe AARM.md.
• Agentic Trust Controls: die Laufzeitaufzeichnungen hinter den Evidenzkontrollen des ATC — manipulationssichere Aktionsprotokollierung (RBM-03) und Autoritätsattestierung (AID-05) in einem verketteten Datensatz, mit der Witness-Ebene darüber hinaus. Siehe ATC.md.
• EU AI Act: Protokollierungs- und Aufbewahrungspflichten für Hochrisiko-KI-Systeme.
• ISO 42001 / NIST AI RMF: die operativen Beweise hinter den Kontrollen des Managementsystems.

Nichts davon zertifiziert für sich genommen irgendetwas. Es gibt Ihrem Prüfer etwas Verifizierbares an die Hand. Die Grenzen — was halo-record bewusst nicht tut und was Sie sagen sollten, wenn ein Prüfer fragt — sind in LIMITS.md dokumentiert.

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

Integritätsmodell

Um den Hash eines Datensatzes zu berechnen: Nehmen Sie den Datensatz ohne integrity.hash, wobei integrity.prev_hash auf den Hash des vorherigen Datensatzes gesetzt ist; kanonisieren Sie mit RFC 8785 (JSON Canonicalization Scheme); SHA-256 über die Bytes. Das prev_hash des ersten Datensatzes besteht aus 64 Nullen. Die Verifikation berechnet jeden Hash neu und prüft jede Verknüpfung. Kein Geheimnis erforderlich; genau das ist der Punkt.

Glauben Sie, Sie können eine Chain manipulieren, ohne dass der Verifier es bemerkt? Versuche und Ergebnisse finden Sie hier.

Vollständige Feldreferenz: halo-record.schema.json.

TypeScript

Derselbe Recorder ist für Node verfügbar: halo-record-ts. Gleiches Kettenformat, gleiches Witness-Protokoll. In beiden Sprachen geschriebene Datensätze lassen sich mit beiden Verifiern verifizieren.

Mitwirken

Issues, Diskussionen und Pull-Requests sind willkommen — siehe CONTRIBUTING.md für die Grundregeln (Kurzfassung: Tests erforderlich, kleine PRs, Schemaänderungen werden zuerst besprochen).

Lizenz

Apache-2.0