halo-record

Manipulationssichere Laufzeitaufzeichnungen für KI-Agenten: das Audit-Trail, das der Anbieter führt, aber nicht bearbeiten kann.

Jede Aktion, die Ihr Agent ausführt (Tool-Aufrufe, Modellaufrufe, Datenzugriffe, Freigaben), wird zu einem Datensatz in einem append-basierten, hash-verketteten Log. Jede Partei, die einen Checkpoint der Chain besitzt, kann verifizieren, dass die dahinterliegenden Datensätze nie verändert wurden – ohne demjenigen vertrauen zu müssen, der sie erzeugt hat. Wenn das Sicherheitsteam eines Kunden fragt: „Was hat Ihr Agent mit unseren Daten gemacht?“, übergeben Sie einen Link statt eines Absatzes. Sicherheitsüberprüfungen stellen bereits KI-Fragen zusätzlich zur SOC-2-Checkliste, und heute genügt noch eine schriftliche Zusicherung. Die Wette hinter diesem Projekt ist, dass das nicht mehr lange gilt.

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 ungeprüft hinnehmen:

• Keine Laufzeitabhängigkeiten. Nur die Standardbibliothek. pip install halo-record installiert genau ein Paket.
• Keine Netzwerkaufrufe, mit Ausnahme des Witness, der optional ist und nur eine Datensatzanzahl und einen Chain-Fingerprint erhält. Datensatzinhalte verlassen niemals Ihre Infrastruktur.
• Rohe Eingaben gelangen nie in einen Datensatz. Argumente werden gehasht und nur als geschwärzte Zusammenfassung gespeichert – niemals als Rohwert. Die Schwärzung ist Best-Effort (Regex über gängige Secret- und PII-Formate): Betrachten Sie sie als Defense-in-Depth, nicht als Garantie.
• Klein genug zum Prüfen. ~4.300 Zeilen Python. Lesen Sie alles an einem Nachmittag.
• Apache-2.0.

60-Sekunden-Demo

Kein Agent erforderlich. Mit uv ist nichts zu installieren:

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

oder auf klassischem Weg:

pip install halo-record
halo demo --serve

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

Ihren 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 Datensätze nach ~/.halo/my-agent.jsonl (eine Chain pro Agent). Oder nutzen Sie den Adapter für das, was Sie bereits betreiben (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 ist abgeschlossen, wenn Sie den Runtime-Report Ihres eigenen Agents in einem Browser sehen. Wenn Sie eine JSONL-Datei erhalten haben, aber keinen Report, stimmt etwas nicht: Eröffnen Sie ein Issue.

Anbinden an das, was Sie bereits betreiben

Jeder Datensatz trägt ein source-Tag, sodass der Report offenlegt, wie jedes Beweisstück erfasst wurde. Erfasste und übernommene 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-Agent-Ö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 feuert nach jedem Tool-Aufruf einen PostToolUse-Hook. 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; 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 Datensätze landen in ~/.halo/audit.jsonl (überschreibbar mit $HALO_LOG). Reine Orchestrierungs-Tools, die weder Daten noch Netzwerk noch externen Zustand berühren, werden übersprungen – die Chain zeichnet Aktionen an der Vertrauensgrenze auf, keine Denkprozesse. 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 Agent-Build zu binden, der ihn erzeugt hat – wenn ein Prüfer nach der Version fragt, die in einem bestimmten Zeitfenster lief, beantwortet der Export das spaltenweise statt aus dem Gedächtnis.

Wenn der Report die Frage beantworten soll „Nach welchen Regeln fand dieser Lauf statt?“, setzen Sie HALO_AUTHORITY_FILE auf einen JSON-Snapshot der für die Sitzung gültigen Autorität. Halten Sie ihn datenschutzfreundlich: Hashes und Referenzen statt roher Prompts, privater Richtlinientexte, Geheimnisse oder vollständiger Tool-Schemata.

{
  "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-Chain wie die Aktionsdatensätze versiegelt. Eine gute Standardeinstellung ist ein Snapshot auf Sitzungsebene zu Beginn sowie ein neuer Snapshot, wenn sich Regeln, Skills, Hooks, MCP-Tool-Registries 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. Danach das Übliche:

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

Jede Agent-Laufzeitumgebung, 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 Aussagen, und genau darin liegt der Punkt:

Eine selbst gehaltene Chain beweist Integrität relativ zu einem etablierten Head: Wenn jemand einen Chain-Head bereits 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 Head gesehen hat – beweist eine Chain interne Konsistenz, nicht Geschichte: Ein Betreiber könnte einen Datensatz entfernen und neu versiegeln, und die neue Datei würde die Verifizierung bestehen. Die Chain wird in dem Moment historisch verankert, in dem ihr Head die Kontrolle des Betreibers verlässt.

Das ist der Witness: eine Partei außerhalb des Betreibers, die periodische Fingerprints der Chain hält (eine Anzahl und einen Head-Hash, sonst nichts). Checkpoints machen das Umschreiben verankerter Geschichte erkennbar, und ein versäumter Checkpoint 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 ausgesprochen: Weder die Chain noch der Witness beweist, dass jede reale Aktion durch den Recorder lief. Das ist Erfassungsvollständigkeit – eine Eigenschaft davon, wo der Recorder im Stack sitzt (native Instrumentierung, Hooks, Gateway-Ingestion), nicht eines Hashes. Datensätze tragen aus genau diesem Grund ein source-Tag.

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

Dieses Projekt trägt sich durch einen gehosteten, anerkannten Witness. Early Access: [email protected].

Einordnung in den Compliance-Stack

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

• Sicherheitsfragebögen und SOC-2-Reviews: Beantworten Sie die KI-Abschnitte mit einem verifizierbaren Runtime-Report statt mit Screenshots und Prosa.
• AIUC-1: erzeugt die manipulationssichere Protokollierung (E015.4) und Datensätze der vollständigen Ausführungskette mit Autorisierungsereignissen (E015.2), die die Accountability-Kontrollen des Standards verlangen – kontinuierliche Laufzeitbelege, nicht erst zum Prüfungszeitpunkt rekonstruiert.
• OWASP (GenAI Security Project): die Laufzeitbelege hinter den Risiken des Agentenverhaltens im OWASP Top 10 for Agentic Applications 2026 und im LLM Top 10 – Goal Hijacking, 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 durch einen unabhängigen Witness verankert. 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 Laufzeitdatensätze hinter den Evidence-Kontrollen der 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 KI-Systeme mit hohem Risiko.
• ISO 42001 / NIST AI RMF: die operativen Belege 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 Reviewer 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, setzen Sie integrity.prev_hash auf den Hash des vorherigen Datensatzes; kanonisieren Sie mit RFC 8785 (JSON Canonicalization Scheme); wenden Sie SHA-256 auf die Bytes an. Der prev_hash des ersten Datensatzes besteht aus 64 Nullen. Die Verifizierung 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 auch für Node verfügbar: halo-record-ts. Gleiches Chain-Format, gleiches Witness-Protokoll. Datensätze, die in einer der beiden Sprachen geschrieben wurden, lassen sich mit beiden Verifiern prüfen.

Mitwirken

Issues, Diskussionen und Pull-Requests sind willkommen – die Grundregeln finden Sie in CONTRIBUTING.md (Kurzfassung: Tests erforderlich, kleine PRs, Schemaänderungen werden zuerst besprochen).

Lizenz

Apache-2.0