Halo: Tamper-Evident Runtime Evidence for AI Agents

Halo: Tamper-Evident Runtime Evidence for AI Agents

Halo provides verifiable audit trails for AI agent actions

Halo is an open-source framework designed to create tamper-evident runtime records for AI agents. It transforms every agent action—including tool calls, model calls, data access, and approvals—into an append-only, hash-chained log. This allows third parties to verify that an agent's operational history has not been altered without needing to trust the vendor who produced the logs.

Technical Architecture and Integrity Model

Halo ensures the integrity of its records using a hash-chaining mechanism based on the JSON Canonicalization Scheme (RFC 8785).

The Hashing Process

To compute a record's hash, Halo takes the record (excluding the current hash) and sets the integrity.prev_hash field to the hash of the previous record. The resulting data is canonicalized and processed via SHA-256. The first record in any chain begins with a prev_hash of 64 zeros. Verification involves recomputing every hash in the sequence to ensure no links have been broken or modified.

Integrity vs. Completeness

There is a critical distinction between the integrity of a log and its completeness:

  • Integrity: A self-held chain proves that nothing was edited or reordered after the fact.
  • Completeness: A self-held chain cannot prove that records were not deleted entirely or that the recorder was never activated.

To solve the completeness problem, Halo utilizes a witness. A witness is an external party that holds periodic fingerprints (a record count and a head hash) of the chain. By comparing the current chain against a trusted witness's fingerprint, users can verify that no records were omitted.

Security and Privacy Design

Halo is built with a "zero-trust" approach to the recorder itself, emphasizing a small audit surface and data privacy:

  • Zero Runtime Dependencies: The Python implementation relies solely on the standard library, meaning pip install halo-record installs only one package.
  • No Network Calls: Except for the optional witness client, the library makes no network calls. Record contents remain within the user's infrastructure.
  • Data Redaction: Raw inputs never enter a record. Arguments are hashed and stored as redacted summaries using best-effort regex for common secrets and PII formats.
  • Auditability: The codebase is approximately 4,300 lines of Python, making it small enough for a manual security audit.

Integration and Compatibility

Halo provides multiple ways to capture agent activity, supporting both direct instrumentation and telemetry ingestion.

Native Recording

Developers can wrap an agent entry point with a single line of code: agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")

Ecosystem Adapters

Halo supports a wide range of existing AI frameworks and tools through adapters:

  • Frameworks: OpenTelemetry GenAI spans (used by CrewAI and LlamaIndex), LangChain, LangGraph, and the OpenAI Agents SDK.
  • Coding Agents: Claude Code can be integrated via the PostToolUse hook in ~/.claude/settings.json, allowing every file write or shell command to be recorded in a local chain.
  • TypeScript Support: A companion package, halo-record-ts, provides native adapters for the Vercel AI SDK and the JavaScript agent ecosystem.

Compliance and Regulatory Mapping

Halo serves as an evidence layer for various security and AI compliance frameworks rather than a certification tool. It produces the artifacts required for:

  • SOC 2 and Security Questionnaires: Replacing prose and screenshots with verifiable Runtime Reports.
  • EU AI Act: Meeting logging and record-keeping obligations for high-risk AI systems.
  • OWASP GenAI Security Project: Providing evidence for risks like excessive agency and tool misuse.
  • AARM (CSA): Producing the tamper-evident action receipts (R5/R6) specified by the Cloud Security Alliance.
  • ISO 42001 / NIST AI RMF: Providing operational evidence for management-system controls.

Sources