Halo: Open-Source Tamper-Evident Runtime Evidence for AI Agents

Verifiable Audit Trails for AI Agent Actions

Halo is an open-source project that provides tamper-evident runtime records for AI agents. It creates an append-only, hash-chained log of every action an agent takes—including tool calls, model calls, data access, and approvals—allowing any party to verify that the log has not been altered without needing to trust the vendor who produced it.

This system shifts the burden of proof from written assurances and screenshots to a verifiable technical artifact, specifically designed to meet the demands of security reviews, SOC 2 checklists, and emerging AI regulations.

Core Technical Architecture

Hash-Chained Integrity Model

To ensure records cannot be edited or reordered without detection, Halo uses a hash-chaining mechanism. Each record's hash is computed by taking the record (excluding its own hash), setting the integrity.prev_hash to the hash of the previous record, and canonicalizing the data using RFC 8785 (JSON Canonicalization Scheme) before applying SHA-256. The first record in a chain begins with a prev_hash of 64 zeros.

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 record was created.
  • Completeness: A self-held chain cannot prove that the operator did not delete an entire section of the log (e.g., "the bad day") and re-seal the chain, or simply fail to write a record.

To solve for completeness, Halo introduces the witness. A witness is an external party that holds periodic fingerprints (a record count and a head hash) of the chain. By anchoring a checkpoint to a witness, a user can verify that the log is complete and has not been truncated or omitted.

Security and Privacy Design

To minimize the risk of introducing vulnerabilities or leaking sensitive data, Halo is built with a strict security posture:

  • Zero Runtime Dependencies: The Python implementation uses only the standard library, meaning pip install halo-record installs exactly one package.
  • No Network Calls: Except for the optional witness client, the recorder makes no network calls. Record contents never leave the local infrastructure.
  • PII Redaction: Raw inputs never enter a record. Arguments are hashed and stored as redacted summaries. While the project uses regex-based redaction for common secrets and PII formats as a defense-in-depth measure, it is not a guaranteed filter.
  • Auditability: The codebase is small (~4,300 lines of Python), making it feasible for a security team to audit the entire project in a short timeframe.

Integration and Ecosystem Support

Framework Compatibility

Halo can be integrated into AI agent workflows through several methods:

  • Native Recorder: Using from halo import trace to wrap an agent's entry point.
  • Telemetry Ingestion: Support for OpenTelemetry GenAI spans, which allows compatibility with frameworks like CrewAI and LlamaIndex.
  • Adapters: Native adapters exist for LiteLLM callbacks, LangChain/LangGraph callbacks, OpenAI Agents SDK hooks, and the Vercel AI SDK (via the halo-record-ts TypeScript package).

Recording Coding Agents

For tools like Claude Code, Halo integrates via the PostToolUse hook. By adding a specific command to the ~/.claude/settings.json file, every file write, shell command, and MCP connector call is recorded into a local chain without requiring changes to the agent's core code.

Compliance Mapping

Halo serves as an evidence layer for various global AI compliance and security frameworks:

  • SOC 2 & Security Questionnaires: Replaces prose and screenshots with a verifiable Runtime Report.
  • EU AI Act: Provides the logging and record-keeping required for high-risk AI systems.
  • OWASP GenAI Security Project: Records actual agent behavior to provide evidence against risks like excessive agency and tool misuse.
  • AARM (CSA): Produces the tamper-evident action receipts (R5/R6) specified by the Cloud Security Alliance.
  • ISO 42001 / NIST AI RMF: Supplies operational evidence for management-system controls.

CLI Reference

Command Purpose
halo verify Validates the schema and hash chain; returns non-zero exit on failure for CI/CD integration.
halo report Renders a chain as a self-verifying HTML Runtime Report.
halo serve Serves per-tenant reports over HTTP with customer-scoped access.
halo anchor Witnesses a chain head or checks completeness against a witness.
halo hook Specifically for Claude Code PostToolUse hooks.

Sources

Related

  • Project
    openkursar/hello-halo

    An AI workstation that enables the creation of autonomous AI Digital Humans to automate web-based tasks 24/7 using a local-first, script-driven browser automation framework.

  • Project
    Ed1s0nZ/CyberStrikeAI

    CyberStrikeAI is an open‑source Go platform that lets security teams drive penetration‑testing workflows with natural‑language prompts. An Eino‑based agent interprets intent, runs a curated set of 100+ security tools, records evidence, and stores the whole attack chain for replay. The system includes a web UI, role‑based access control, RAG knowledge base, optional C2/WebShell, and plugins for Burp Suite and browsers. One‑click deployment (`run.sh`) builds the server, creates a Python virtual environment, and starts an HTTPS service. It is licensed under Apache 2.0 and intended for authorized, ethical testing only.

  • Project
    context-labs/HALO

    An RLM-based agent optimizer that analyzes production execution traces to identify systemic failure modes and provide recommendations for improving agent harnesses.

  • Project
    NVIDIA/OpenShell

    OpenShell is an open‑source, policy‑driven runtime that isolates autonomous AI agents (Claude, OpenCode, Codex, Copilot, etc.) in sandboxed containers. Declarative YAML policies control filesystem, network, process and model‑API access, preventing credential leaks and data exfiltration. The platform provides a CLI, a k9s‑style TUI, provider management for API keys, optional GPU passthrough, and experimental Kubernetes/Helm deployment.

  • Project
    emiliaprotocol/emilia-protocol

    A security protocol and enforcement layer that creates a verifiable boundary for autonomous agents, ensuring they only perform actions they have explicit authority to actually execute.