bkuan001/halo-record

来源: https://github.com/bkuan001/halo-record

halo-record

防篡改 AI 代理运行时记录：供应商运行但无法编辑的审计追踪。

你的代理执行的每个操作（工具调用、模型调用、数据访问、审批）都会成为一条记录，追加到一个只增、哈希链日志中。任何一方都可以验证日志从未被篡改，而无需信任其创建者。当客户的安防团队问“你的代理对我们的数据做了什么？”时，你提供一个链接，而不是一段文字。安全审查已经在 SOC 2 检查清单旁边询问 AI 问题，今天书面的保证还能通过。这个项目押注的是，这种局面不会持续太久。

记录格式是开放的，任何人都可以自由实现。这个包是参考实现：包含记录器、验证器、见证客户端和报告服务器。

为什么你可以信任这段代码

你被要求在代理中嵌入一个记录器。你不应该盲目相信它：

• 零运行时依赖。 仅使用标准库。pip install halo-record 只安装一个包。
• 无网络调用，除了见证功能（可选），它只接收记录计数和链指纹。记录内容永远不会离开你的基础设施。
• 原始输入永远不会进入记录。 参数会被哈希处理，只存储为摘要形式——绝不包含原始值。摘要是尽力而为的（基于常见密钥和 PII 格式的正则表达式）：请视其为纵深防御，而非绝对保障。
• 代码量小，便于审计。 ≈4,300 行 Python。一下午就能读完。
• Apache-2.0 许可。

60 秒演示

无需代理。使用 uv (https://docs.astral.sh/uv/)，无需安装任何东西：

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

或者用传统方式：

pip install halo-record halo demo --serve

以上任一种方式都会搭建一个虚构的客服代理供应商，包含两个客户，见证链，提供其受控的运行时报告，并在浏览器中打开运营控制台。然后尝试篡改测试：删除一个 .jsonl 文件中的某一行并刷新。报告会检测出来。

记录你自己的代理

在边界处添加一行代码：

``python from halo import trace

agent = trace(run_my_agent, profile=“my-agent”, log=“audit.jsonl”) # 包装你的入口点；记录每次工具调用到 ./audit.jsonl ``

如果不带 log=，记录会被写入 ~/.halo/my-agent.jsonl（每个代理一条链）。或者使用适用于你现有运行环境的适配器（见下方表格）。然后生成报告：

halo report audit.jsonl -o report.html # 单链 -> 自验证 HTML halo serve ./records --port 8721 # 所有租户，按客户授权

快速入门到此结束，你应该可以在浏览器中看到你自己的代理的运行时报告了。如果得到了 JSONL 文件但没有报告，说明有问题：请提交 Issue。

与你已有的环境集成

每条记录都带有 source 标签，因此报告会披露每条证据是如何收集的。捕获的记录和摄取的记录存在于同一条链中。

任何发射 OpenTelemetry GenAI spans 的框架（CrewAI、LlamaIndex 以及大多数带有 OTel 插件的代理框架）都可以通过 OTel 适配器进入链中，而 TypeScript 包 (https://github.com/bkuan001/halo-record-ts) 则为 Vercel AI SDK 和 JS 代理生态系统提供了原生适配器。缺少你的技术栈的适配器？请提交 Issue。大多数适配器大约只有一百行代码。

完整性 vs. 完整性（请阅读这一部分）

自持的链证明了完整性：事后没有任何内容被编辑或重新排序。但它不能证明全面性：记录器的操作者可以删除问题数据并重新密封链，或者根本从不写入记录，而链仍然内部一致。

全面性需要一个独立于操作者控制的第三方定期持有链的指纹（一个计数和一个头部哈希，仅此而已）。这就是见证者：

halo anchor audit.jsonl witness.jsonl # 将检查点锚定到本地见证者 halo anchor audit.jsonl witness.jsonl --check # 根据它进行完整性判定

任何人都可以运行见证者。你自己运行的见证者可以向你自己证明完整性；要向你的客户证明全面性，需要一个他们信任的见证者。协议在任何情况下都是开放的。

托管、公认的见证者是该项目得以持续发展的方式。有关早期接入，请联系 [email protected]。

在合规栈中的定位

halo-record 是一个证据层，而不是认证。它生成评估框架不断用不同措辞要求的工件：

• 安全调查问卷和 SOC 2 审查： 用可验证的运行时报告代替截图和文本来回答 AI 部分。
• AIUC-1： 为代理行为要求提供持续的运行时证据，而不是在审计时重建证据。
• OWASP（GenAI 安全项目）： 为 OWASP 十大 LLM 应用风险中的代理行为风险和 Agentic Security Initiative 提供运行时证据——过度代理、工具滥用、敏感信息泄露——记录为代理实际做了什么、用了哪些工具和哪些数据。
• AARM（CSA）： 生成 AARM 规范（R5/R6）中规定的防篡改操作收据——采用链式结构并独立见证。halo-record 是收据层；与执行网关搭配使用可构建完整的 AARM 系统。参见 AARM.md。
• EU AI 法案： 高风险 AI 系统的日志和记录义务。
• ISO 42001 / NIST AI RMF： 管理体系中控制措施的运营证据。

这些本身并不认证任何东西。但它们能给你的评估人员提供一些可验证的数据。

CLI

halo verify 验证模式 + 哈希链（失败时非零退出；适合 CI） halo report 将链渲染为自验证 HTML 运行时报告 halo serve 通过 HTTP 提供按租户划分的报告，按客户权限访问 halo grant 指定报告接收者（邮箱或域名） halo anchor 见证链头，或 --check 全面性 halo demo 搭建完整的供应商演示（记录 -> 见证 -> 受控报告） halo sample 输出一个有效的示例日志 halo hash 计算 JSON 值的规范 SHA-256 halo hook Claude Code PostToolUse 钩子

完整性模型

计算记录的哈希方法：取记录（排除 integrity.hash），并将 integrity.prev_hash 设置为前一条记录的哈希；使用 RFC 8785（JSON 规范化方案）进行规范化；对结果字节进行 SHA-256。第一条记录的 prev_hash 为 64 个零。验证会重新计算每一个哈希并检查每一个链接。不需要任何密钥——这就是关键。

完整字段参考：halo-record.schema.json

TypeScript

Node.js 也提供了相同的记录器：halo-record-ts (https://github.com/bkuan001/halo-record-ts)。相同的链格式，相同的见证协议。以任意一种语言写入的记录都可以用任意一种验证器来验证。

许可

Apache-2.0