防篡改的 AI 代理审计追踪 —— 哈希链式运行时记录,渲染为运行时报告,你的客户可以自行核查。
你的插桩捕获的每一个操作(工具调用、模型调用、数据访问、审批)都会成为仅追加、哈希链式日志中的一条 运行时记录;运行时报告 是将该链渲染为 HTML 页面,在读者浏览器中重新计算哈希链,并根据其验证过的记录渲染所显示的内容(对于不依赖页面自身代码的检查,可对 JSONL 运行 halo verify)。任何持有该链检查点的方都可以验证截至该检查点的记录自检查点生成以来未被篡改,而无需信任生成者——该检查点是承重部件:仅凭链本身,除运行记录器的一方外,对所有人都是防篡改的(LIMITS.md §1)。当客户的安全团队问“你的代理对我们的数据做了什么?”时,你递给他们一个链接,而不是一段文字。安全审查已经在 SOC 2 检查清单旁边提出 AI 问题——而且越来越多地,这些问题来自 ISO 42001、欧盟 AI 法案的记录保存条款以及客户自己的问卷。如今,书面保证仍然能通过。这个项目背后的赌注是,这种情况不会持续太久。
“二十年的取证经验教会你,证据只有在对方能够核查时才是证据……在一个充满要求信任的 AI 产品的领域里,[Halo] 是罕见的、旨在让信任变得不必要的那一个。”
Johannes Stillig,Tidebreak AI 创始人兼 CEO,某私人投资办公室集团 CISO
被 Help Net Security 报道 · 当周 Show HN 发布中排名前 4% · 在 Agentic Trust Controls 上针对五项控制措施列出
记录格式是开放的,可自由实现。本包是参考实现:记录器、验证器、见证客户端和报告服务器。
正在使用 halo-record,或正在考虑使用? 告诉我你是谁以及用途 → 谁在使用 halo-record?
有人要求你在你的代理中放入一个记录器。你不应盲目相信这一点:
pip install halo-record 只安装一个包。halo serve --verify-email(通过你在 $HALO_SMTP_HOST 中配置的服务器,经 SMTP 将一次性验证码和报告的主体名称发送到报告查看者输入的地址)。除非你主动调用,否则这些功能全部关闭;其他记录内容不会离开你的基础设施。summaries=False)完全不保留摘要。脱敏是尽力而为的(对常见密钥和 PII 格式使用正则表达式,外加熵兜底):请将其视为纵深防御,而非保证。你提供的 summary 之外的结果字段会用相同模式扫描并掩码,但不会被截断到 200 个字符(LIMITS §13)。每一层证明什么——本项目中的关键区分(LIMITS.md §1):你自己持有的链证明记录未被编辑,相对于某人已持有的链头;只有由运营者外部持有的检查点才能证明没有记录被删除;而没有任何哈希能证明每个操作都被捕获。
| 声明 | 自持链 | + 外部检查点 | + 可信捕获 |
|---|---|---|---|
| 检测对已建立产物的编辑 | ✔ | ✔ | ✔ |
| 检测对已提交历史的改写 | — | ✔ | ✔ |
| 检测缺失/延迟的检查点 | — | ✔(约定节奏) | ✔ |
| 证明每个操作都被记录 | — | — | 取决于捕获边界 |
安装前先看一个示例: 示例运行时报告——虚构数据、真实链,打开时其脚本会在你的浏览器中重新计算内嵌记录的哈希链。
无需 agent。使用 uv,无需安装任何东西:
uvx --from halo-record halo demo --serve
或以经典方式:
pip install halo-record
halo demo --serve
要么搭建一个虚构的支持代理供应商,包含两个客户,见证这些链(用一个本地见证文件代替操作员之外的一方——参见 LIMITS.md §1),提供它们受门控的 Runtime Reports,并在你的浏览器中打开操作员控制台。然后尝试篡改测试:从其中一个 .jsonl 文件中删除一行并重新加载。报告会捕获它。
在边界处写一行:
from halo_record import trace
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls
from halo import ... 便捷 shim 也会一并提供——但 PyPI 上的 halo 名称属于一个无关的终端 spinner 包,如果该包已安装,它会在导入时胜出。halo_record 没有歧义,因此示例使用它。
在没有 log= 的情况下,记录会写入 ~/.halo/my-agent.jsonl(每个 agent 一条链)。wrapper 封存运行边界;证据存在于每次调用的记录中。使用框架适配器(见下表)捕获这些记录——或者显式捕获,这也能展示委托链接是如何建立的:
from halo_record import Recorder, record_call
rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call: # one sealed record per tool call
call.result = crm.lookup("acct-9")
with record_call(rec, "payments.refund", {"amount": 120},
parent_id=rec.last_record_id()) as call: # child links to the action that spawned it
call.result = payments.refund(120)
然后渲染报告:
halo report audit.jsonl -o report.html # one chain -> HTML that re-verifies in the browser
halo serve ./records --port 8721 # all tenants, gated per customer
升级一个最初由 0.2.45 提供服务的目录?halo serve 会在启动时重新读取每个先前的授权。如果某个文件上的授权所对应的记录不携带 subject id(例如 agent.jsonl 这样的普通 Recorder 文件),该授权会被隔离,并在每次启动时连同用于重新签发它的 halo grant 命令一起打印出来——参见 LIMITS.md §17, "Serving a directory first served by 0.2.45"。
当你在浏览器中看到自己 agent 的 Runtime Report 时,快速入门就结束了。如果你只得到了一个 JSONL 文件而没有报告,说明出了问题:请提交一个 issue。
如果某个护栏或策略层检查了该操作,其判定结果可以随记录一起传递——这是一个可选块,记录该门控做出了什么决定,并像其他所有字段一样被封入哈希链:
from halo_record import build
build("tool_call", "security", tool="payments.refund",
verification={"status": "allowed", "verifier": "gate/1.2",
"policy_ref": "sha256:1f3a...",
"checked_at": "2026-08-01T12:00:00Z"})
关于命名的一点说明:该包导出了一个 record 函数(即装饰器),它会在包对象上遮蔽 halo_record.record 模块。当你需要该模块的内部内容时,应直接从模块路径导入——from halo_record.record import build——而不是使用 import halo_record.record as record。
其封存进记录后如下所示:
"verification": {"status": "allowed", "verifier": "gate/1.2", "policy_ref": "sha256:1f3a...", "checked_at": "2026-08-01T12:00:00Z"}
record_call(...) 接受相同的 verification= 关键字参数。status 在块内为必填项;verifier、policy_ref 和 checked_at 为可选项。各状态的含义如下:
| 状态 | 门禁报告的内容 | 操作是否执行? |
|---|---|---|
allowed | 它允许了该操作 | 是——操作已继续执行 |
blocked | 它拒绝了该操作 | 由集成决定,而非由该字段决定——记录仍可能携带结果,且仅凭一次拦截本身并不能证明未执行 |
modified | 它在执行前修改了该操作——action.input 描述的是已执行的操作,即修改后的形式 | 是,以修改后的形式执行 |
unverified | 它运行了(或被咨询过)但未作出判定——与缺失的块不同,后者意味着完全未作出验证声明 | 是——操作在无判定结果的情况下继续执行 |
该块由操作者的集成代码提供,并记录其报告的门禁所述内容——与 principal 具有相同的信任姿态(参见 LIMITS)。密封证明该状态在事后未被编辑;它并不证明检查确实发生、判定正确,或已被拦截的操作未执行。这并非独立验证。
要使 policy_ref 可作为证据使用,请使用规则集的内容哈希并保留规则集工件——无法解析的标签会使该字段沦为装饰。
| 在边界处捕获 | 从现有遥测数据中摄取 |
|---|---|
原生记录器(from halo_record import trace) | OpenTelemetry GenAI spans |
| MCP 拦截器 | LiteLLM 回调 |
| LangChain / LangGraph 回调 | Langfuse 导出 |
| OpenAI Agents SDK 钩子 | 任意网关 / 反向代理日志 |
| Claude Agent SDK 钩子 | Claude Code 和 Codex CLI 的 PostToolUse 钩子(在工具运行后触发) |
由 halo door 在买方侧读取的平台日志导出(GitHub 安全日志、Salesforce Event Monitoring) |
框架适配器和摄取路径会为每条记录打上 source 标签,因此报告会披露每条证据的收集方式。捕获的记录和摄取的记录位于同一条链中。
对于 LangChain / LangGraph,它是一个回调处理器:
from halo_record import Recorder
from halo_record.integrations.langchain import HaloCallbackHandler
recorder = Recorder("audit.jsonl")
result = my_chain.invoke(inputs, config={"callbacks": [HaloCallbackHandler(recorder)]}) # every tool call becomes a record
对于 MCP,一次调用即可封装客户端会话——随后,任何使用 MCP 的 agent 都会为每次工具调用发出记录,无论由哪个框架驱动:
from mcp import Client # mcp 2.x
from halo_record import Recorder
from halo_record.integrations.mcp import instrument_client_session
async def run(server): # an MCPServer, a server URL, or stdio parameters
async with Client(server) as client:
instrument_client_session(client, Recorder("audit.jsonl"), server="stripe")
await client.call_tool("charge", {"customer": "cus_123", "amount": 500}) # recorded
对被包装客户端上的每次 call_tool() 调用都会被记录,返回错误结果的工具会被封存为 error(适配器会同时读取 isError 和 mcp 2.x 的 is_error)。在 mcp 1.x 上,请传入已初始化的 ClientSession 而不是 Client;包装器是相同的。
对于网关或代理日志(Cloudflare AI Gateway、Portkey、模型前面的 nginx),将日志行映射到链中——明确标记为已摄取,而非边界捕获:
from halo_record.integrations.gateway import record_log
record_log(Recorder("audit.jsonl"), {"tool": "gen_ai:gpt-4o", "model": "gpt-4o", "status": 200, "subject": "acme-corp"})