AI Agent 审计难题：Halo 用哈希链给每个工具调用加上防篡改证据

你的 AI Agent 产品收到了安全团队的邮件——”请提供上周所有 Agent 操作的技术审计报告”。你翻遍日志、截了一堆聊天记录截图，发出去后对方只回了三个字：”可信吗？”

这不是假设。AI Agent 正在进入企业采购流程，安全问卷已经开始问 Agent 层的问题。但当客户要求提供”Agent 用你的 API 密钥做了什么”的可验证记录时，供应链里没有层能给出答案。你给出一段文字保证，而你的客户需要的是他们自己也能验证的证据。

Halo（halo-record）是一个 Apache-2.0 的 Python 包，它在你的 Agent 边界注入一个不可逆的哈希链记录器：每个工具调用、模型调用、数据访问、审批操作都被序列化为一条记录，链式 SHA-256 哈希锁定，任何人都可以验证日志从未被篡改——无论对方是否信任你。

场景：安全团队要求提供可信的 Agent 操作记录

假设你运营一个基于 AI Agent 的代码审查 SaaS 平台。客户是一家金融科技公司，他们的合规团队需要知道：

• Agent 访问了哪些代码仓库？
• Agent 调用了哪些外部 API？
• Agent 做了什么数据库操作？
• 这些记录是否被事后修改过？

常规的做法是写一份 PDF 报告，附上日志截图。但这些截图可以被 PS，日志可以被 grep 删除后重写，客户没有任何技术手段验证你的诚信。

Halo 的做法完全不同：你在 Agent 入口加一行代码：

from halo import trace

agent = trace(run_code_review, profile="saas-agent", log="audit.jsonl")

从此每个工具调用自动写入 audit.jsonl——每条记录包含调用时间、工具名、参数哈希（而非原始值，保护客户敏感数据）、返回状态、前后哈希链指针。文件格式是纯 JSONL，没有二进制依赖。

然后一键生成自我验证的 HTML 报告：

halo report audit.jsonl -o report.html

这份 HTML 内嵌了完整哈希链和验证 JS——客户打开文件就能看到每条记录的状态，任何一行被删除或修改，报告立即显示红色警告。

60 秒搭建完整 demo

无需任何 Agent 框架，pypi 安装即可启动完整演示：

pip install halo-record
halo demo --serve

这会自动创建一个假想的客户服务 Agent 供应商，包含两个租户的审计链，启动报告服务在 localhost:8721。然后你可以在浏览器中打开 Operator Console，看到实时生成的审计记录。做破坏测试：随便删一行 .jsonl 文件内容再刷新，报告立即报错。

uvx --from halo-record halo demo --serve  # 用 uv 更快，无需安装

哈希链的信任模型

Halo 的设计哲学是：不信任记录者，信任链条。

每条记录的完整性哈希是这样计算的：

1. 取记录的全部字段（排除 integrity.hash 自身）
2. 将 integrity.prev_hash 设为上一条记录的实际哈希值（首条为 64 个零）
3. 按 RFC 8785（JSON Canonicalization Scheme）规范化
4. SHA-256 哈希

验证时重新计算每个哈希、检查每个链接——不需要任何密钥或秘钥，这是公开可验证的。

但有一个微妙问题：链式哈希能证明完整性（写入后未修改），不能证明完备性（记录者可以删除黑色星期五那天的整条链，重写然后重新密封，链内部仍然一致）。

完整的证明需要见证者（Witness）——外部的一方定期持有链的指纹（记录条数 + 头哈希，不包含任何记录内容）：

halo anchor audit.jsonl witness.jsonl           # 锚定检查点到见证者
halo anchor audit.jsonl witness.jsonl --check   # 验证完整性

你自己运行的见证者可以向你证明完整性，向你的客户证明则需要一个他们信任的第三方见证者。Halo 的协议是开放的，任何人都可以运行见证服务。

与现有 Agent 框架的集成矩阵

Halo 支持两种接入模式：在边界捕获（Native Recording）和从已有遥测导入（Ingest），支持以下框架：

每条记录携带 source 标签，报告中会标明证据的来源位置。

合规栈中的位置

Halo 生产的是证据层（Evidence Layer），不是认证本身。它在以下审计框架中提供可验证的运行证据：

• SOC 2 安全问卷：用可验证的 Runtime Report 替代截图和文字描述
• AIUC-1：持续运行时的 Agent 行为证据，替代审计时刻重构的证据
• OWASP GenAI Top 10：记录 Agent 实际的工具调用、数据访问，覆盖过度代理、工具滥用、敏感信息披露等风险
• EU AI Act：高风险 AI 系统的日志和记录保存义务
• ISO 42001 / NIST AI RMF：管理体系的运营证据

CLI 命令一览

halo verify    验证 schema + 哈希链（非零退出，CI 友好）
halo report    生成自我验证的 HTML Runtime Report
halo serve     按租户隔离提供 HTTP 报告服务
halo grant     指定报告接收者（邮箱或域名）
halo anchor    见证链头，或 --check 验证完整性
halo demo      搭建完整供应商演示
halo sample    生成一条合法的示例日志
halo hash      JSON 值的规范 SHA-256 计算
halo hook      Claude Code PostToolUse 钩子

TypeScript 版本

同样记录器支持 Node.js 生态：halo-record-ts（GitHub 同组织 bkuan001/halo-record-ts），相同链格式、相同见证协议。两种语言写的记录可以用统一的验证器验证。

快速开始

安装：

pip install halo-record

在 Agent 入口包装：

from halo import trace
agent = trace(your_agent_fn, profile="my-agent")

生成审计报告：

halo report ~/.halo/my-agent.jsonl -o report.html

Halo 的代码只有约 4300 行 Python，零运行时依赖（仅标准库），网络调用只存在于可选的见证者模式（且仅传输记录条数和头哈希）。Apache-2.0 开源许可证，可以在任何项目中自由使用。

相关链接：

• GitHub: bkuan001/halo-record
• TypeScript 版 halo-record-ts
• AARM 协议文档
• JSON Schema 字段参考