Halo-record: Open-source audit trails for AI agents

Brian Kuan wrote halo-record, a small Python package that sits inside an AI agent and writes down the moves it makes: tool calls, model calls, data access, approvals. Each action becomes one line in a file that only ever gets appended to, and every line carries a hash of the line before it, a hash being a short fingerprint computed from content. Edit a record later and every fingerprint after it stops matching. The code is open source, and anyone can run that check with no key, no account and no permission from the vendor whose agent produced the log.

A customer’s security team asks what your agent did with their data, and the answer they get is a paragraph you wrote about yourself. A hash-chained log replaces the paragraph with a file the customer can test. Wrapping an agent takes one line of Python, and adapters pull records in from OpenTelemetry spans, LangChain, MCP servers and gateway logs, so the evidence can come from tooling you already run.

Raw arguments never enter a record. Values get hashed and kept as a redacted summary, and the redaction is pattern matching against common secret and personal-data formats. The package has no runtime dependencies and runs about 5,300 lines of Python, which matters when the recorder goes inside your own product.

Nothing was edited is not the same as nothing is missing

A chain you hold yourself proves one thing: no record was altered or reordered after it was written. It cannot prove that every record was written. Delete the embarrassing Tuesday, re-seal the chain, and the file stays internally consistent.

Closing that hole takes a witness, some party outside the operator’s control that periodically stores two numbers: how many records exist and the hash at the head of the chain. A witness you run yourself proves integrity to you and nothing to your customer. A hosted witness service is also how Kuan intends to fund the work.

Why a vendor would sign up for a log it cannot edit

“Vendors volunteer because it closes deals,” Kuan told Help Net Security. An agent vendor walks into a security review today carrying a certification built for deterministic software, an expensive new audit standard, or its own logs. On the last of those, he said: “handing a prospect your own logs and asking them to trust you breaks the oldest rule in assurance. It’s why SOC 2 requires an independent AICPA-accredited auditor in the first place.”

“It’s early. Adopters are mostly engineers and security researchers kicking the tires, but the mandate pressure is just starting to form, from standards like AIUC-1 that now require tamper-evident runtime logging, and from insurers starting to ask the same questions,” Kuan said.

Pressure of a less voluntary kind is arriving too. “July’s Hugging Face intrusion was run by an autonomous agent – roughly 17,600 actions over five days – and their own write-up says reconstructing what it did by hand was impractical, and that only some of the agent’s logs could be retrieved,” Kuan said. Take the arithmetic from that number: a responder reading one action per minute needs twelve straight days to get through the week.

The format is open, and that is on purpose

Kuan controls the record format today, and it is versioned, public and small enough that anyone can implement it without asking. “If a big platform ships its own incompatible version, that mostly proves the point – the market agrees the evidence matters,” he said. “And honestly, the more the format gets copied, the better – the format was never the moat. Any variant still faces the same question: can anyone besides the vendor verify it?”

Nobody gets certified by any of this. A report gives an assessor something checkable next to record-keeping language in the EU AI Act and the action receipts in the Cloud Security Alliance’s AARM model.

Halo-record is available for free on GitHub.

Must read:

• 20 open-source cybersecurity tools to keep your team ready for anything
• GitHub CISO on security strategy and collaborating with the open-source community

Subscribe to the Help Net Security ad-free monthly newsletter to stay informed on the essential open-source cybersecurity tools. Subscribe here!