开源项目Halo为AI代理提供防篡改运行时证据

背景

随着 AI Agent（智能体）在企业场景中的广泛部署，安全团队和合规审核方越来越迫切地需要回答一个核心问题：「你的 Agent 对我的数据做了什么？」传统做法是提供一段书面保证或截图，但这在审计透明度和可验证性上存在明显缺陷。SOC 2 检查清单旁边已经开始出现 AI 相关的问题，而目前书面承诺仍然被接受——但项目作者认为这种局面不会持续太久。Halo 项目的诞生正是为了填补这一空白：为 AI Agent 提供一种不可篡改（tamper-evident）的运行时证据，让任何一方无需信任记录者即可验证日志的真实性。

核心内容

Halo 是一个开源项目（Apache-2.0 许可），为 AI Agent 生成只能追加、哈希链式的运行时记录。Agent 的每一个动作——工具调用、模型调用、数据访问、审批等——都被记录为一条记录，追加到一个 append-only 的哈希链日志中。任何第三方都可以验证该日志从未被篡改，无需信任记录者。当客户安全团队询问「你的 Agent 对我们的数据做了什么？」时，你可以直接给他们一个链接，而不是一段文字说明。

记录器集成方式

在 Python 中，只需一行代码即可将 Halo 记录器接入 Agent 的入口函数：

from halo import trace
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")

这会将每个工具调用记录到 audit.jsonl 文件中。如果不指定 log=，记录将默认写入 ~/.halo/my-agent.jsonl。此外，Halo 还提供多种适配器（adapter），支持 CrewAI、LlamaIndex 等使用 OpenTelemetry GenAI spans 的框架，以及 Vercel AI SDK 和 JS Agent 生态（通过 TypeScript 包 halo-record-ts）。不同语言和框架的记录格式完全一致，可以互相验证。

安全与隐私设计

• 零运行时依赖：仅使用标准库，pip install halo-record 只安装一个包。
• 无网络调用：记录器不会主动联网，唯一可选的是 witness 功能（见证者），它只接收记录计数和链指纹（fingerprint），绝不传输记录内容，内容始终留在你的基础设施内。
• 原始输入不进入记录：参数被哈希化并存储为脱敏摘要，从不记录原始值。脱敏基于正则表达式匹配常见密钥和 PII 格式，属于深度防御措施而非绝对保证。
• 代码量极小：约 4300 行 Python，可在一下午读完，便于审计。

完整性（Integrity）与完备性（Completeness）

• 完整性：哈希链确保记录一旦写入就无法被编辑、删除或重排，内部始终保持一致。
• 完备性：但记录器操作者可以删除某一整天的记录然后重新封链，或者干脆从不写入记录，而链本身依然自洽。要证明完备性，需要记录者之外的第三方（witness）定期持有链的指纹（计数和头部哈希）。这个 witness 可以是自己运行的（用于自证），也可以是客户信任的（用于对外证明）。协议开放，任何人或组织都可以运行 witness。

Halo 项目通过提供托管且被认可的 witness 服务来自我维持（早期访问请联系 [email protected]）。

使用示例

快速部署演示（使用 uv 或 pip）：

uvx --from halo-record halo demo --serve
# 或
pip install halo-record
halo demo --serve

这会创建一个虚构的客服 Agent 供应商环境（含两个客户），见证链，提供有权限控制的 Runtime Report，并在浏览器中打开运营控制台。你可以尝试篡改测试：删除一个 .jsonl 文件中的某一行，刷新报告后它会被检测到。

生成 HTML 报告：

halo report audit.jsonl -o report.html   # 单个链 → 自验证 HTML
halo serve ./records --port 8721         # 多租户，按客户控制访问

命令参考

| 命令 | 说明 | |------|------| | 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 钩子 |

记录哈希计算方式

每条记录的哈希计算：取记录中除去 integrity.hash 字段的部分，并将 integrity.prev_hash 设为上一条记录的哈希值（首条记录 prev_hash 为 64 个零），然后按照 RFC 8785（JCS）规范序列化，再对字节进行 SHA-256 计算。验证时会重新计算每条哈希并检查每个链接。不需要任何密钥——这正是重点。

适配器矩阵

任何通过 OpenTelemetry 输出 GenAI spans 的框架（CrewAI、LlamaIndex 等）都可以通过 OTel 适配器接入链。TypeScript 包提供了针对 Vercel AI SDK 和 JS Agent 生态的原生适配器。缺少适配器？可以提 issue，大多数适配器大约 100 行代码。

关键要点

• 不可篡改的运行时证据：每条记录通过哈希链连接，任何篡改（编辑、删除、重排）都会导致链不一致，可被检测。
• 零信任记录：任何一方无需信任记录者即可验证完整性；完备性需要外部 witness（见证者）定期持有链指纹。
• 隐私优先：原始输入从不进入记录，只存储脱敏摘要和哈希；记录内容永不离境（除非选择 witness，但 witness 只接收计数值和指纹）。
• 极简审计：约 4300 行 Python，零运行时依赖，只有一个包，代码可在一下午读完。
• 跨语言互操作性：Python 和 TypeScript 版本采用完全相同的链格式和 witness 协议，记录可以互相验证。
• 适配主流框架：通过 OpenTelemetry 适配器支持 CrewAI、LlamaIndex 等，原生适配 Vercel AI SDK 和 JS Agent 生态。
• 报告自验证：生成的 HTML 报告本身包含哈希链验证逻辑，无需额外工具即可检查篡改。
• 与现有安全标准对齐：可以直接用于回答 SOC 2 中的 AI 问题、AIUC-1 运行时证据要求、OWASP Top 10 for LLM Applications 中的 Agent 风险、AARM（CSA）的 R5/R6 行动收据、EU AI Act 的日志义务、ISO 42001 / NIST AI RMF 的操作证据。
• 开源许可：Apache-2.0，鼓励商业使用和定制。

意义与影响

Halo 项目代表了一种将安全审计从信任问答转向可验证证据的重要趋势。当前 AI Agent 部署中，安全合规往往依赖书面保证和屏幕截图，而 Halo 提供了一种技术可审计的运行时记录，使得第三方（客户、审计员、监管机构）能够独立验证 Agent 的实际行为。它不是一个认证体系，而是一个证据层——产生审计框架不断要求的那个可验证的工件。

项目对多个现有标准体系的落地提供了实操支持：

• SOC 2：用可验证的 Runtime Report 替代截图和文字描述。
• AIUC-1：提供持续运行时证据，而不是审计时重建的证据。
• OWASP GenAI Security：记录 Agent 实际行为（过度权限、工具误用、敏感信息泄露）的运行时证据。
• AARM（Cloud Security Alliance）：充当 AARM 规范中要求的不可篡改行动收据（R5/R6），可与执行网关配合构成