Halo Record 代理审计轨迹
为 AI 代理生成可由客户独立校验的防篡改审计轨迹。
- Star 数
- ★ 86
- 最近更新
- 20 天前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 82/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code · OpenAI API · Claude API
- 费用
- 免费,无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 向客户安全团队交付 AI 代理处理其数据的可校验 Runtime Report,而不是仅提供文字说明的软件供应商。
- 不适合
- 需要证明所有真实动作均被记录的团队
- 要求内置保留、裁剪或彻底删除链上个人数据的团队
- 无法为并行写入者建立独立链或互斥锁的系统
- 维护状态
- 近 30 天有提交最近提交 2026-11-01最新版本 v0.2.47(2026-11-01)
- 源码审查
- 82/100 · 表现良好
这个 Agent 能做什么,适合哪些场景?
Halo Record 是一个零运行时依赖的 Python 参考实现,用哈希链记录 AI 代理的工具调用、模型调用、数据访问、审批及运行边界。它提供 Recorder、trace、record_call、框架适配器、验证器、见证客户端、报告服务器和 CLI,并可接入 MCP、LangChain/LangGraph、OpenAI Agents SDK、Claude Agent SDK、OpenTelemetry GenAI、LiteLLM、Langfuse及网关日志。记录以追加式 JSONL 链保存在本地文件系统,可渲染成在浏览器内重新校验的 Runtime Report,也可导出 CSV 与绑定源链头的清单。外部见证检查点可发现已提交历史被重写或预期检查点缺失,RFC 3161 时间戳还能证明某个链头不晚于特定时间存在。它是证据层而非认证或执行网关:哈希不能证明每个动作都被捕获,验证状态也只是集成代码所报告的结果。核心功能可在本地运行;网络仅用于主动调用的远程见证、读取检查点或时间戳服务。
应用在动作边界调用 Recorder、trace()、record_call() 或框架适配器,将调用输入的规范哈希、经过尽力脱敏且最多 200 字符的摘要、结果、主体、来源、父记录以及可选的 verification 和 authority 块封入记录。每条记录使用 RFC 8785 规范化后计算 SHA-256,并通过 integrity.prev_hash 连接前一条记录;halo verify 会重新计算哈希并检查格式和链接。halo report 生成自校验 HTML,halo serve 按客户提供受控报告,halo export 输出日期范围内的 CSV 和清单,halo policy 对声明式策略包给出通过、违规或证据缺口。halo anchor 将链头、链根、记录数和主体 ID 提交给本地或远程见证,并可附加 RFC 3161 时间戳;记录正文不会随见证请求发出。现有系统还可通过 MCP 客户端拦截、LangChain 回调、OpenTelemetry GenAI spans、LiteLLM 回调、Langfuse 导出、网关日志以及 Claude Code 或 Codex 的 PostToolUse 事件写入同一记录格式。
- 向客户安全团队交付 AI 代理处理其数据的可校验 Runtime Report,而不是仅提供文字说明的软件供应商。
- 需要为 SOC 2、AIUC-1、AICM、ISO 42001、EU AI Act 或 NIST AI RMF 评审准备日志证据和日期范围导出的合规团队。
- 运行 LangChain、LangGraph、MCP 或 OpenTelemetry GenAI 工作负载,并希望把不同来源的动作统一封入一条链的平台团队。
- 希望记录 Claude Code 或 Codex 文件修改、Shell 命令和 MCP 调用,又不想修改代理代码的工程团队。
- 需要由客户或其他外部方持有周期性检查点,以发现已提交历史被改写或检查点中断的高信任场景。
- 需要把特定工具调用范围导出成 CSV 和校验清单,再上传至 Vanta、Drata 等 GRC 平台的审计团队。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
uvx --from halo-record halo demo --servepip install halo-record
- 配置文件
~/.claude/settings.json~/.codex/hooks.json~/.halo/audit.jsonl
如何安装或部署这个 Agent?
本地演示不需要代理、账户或 API 凭据。使用 uv 可直接运行:
uvx --from halo-record halo demo --serve也可以通过 pip 安装后启动:
pip install halo-record
halo demo --serve演示会创建虚构供应商及两个客户的记录,使用本地见证文件建立检查点,启动 Runtime Report 服务并打开操作台。Apache-2.0 包本身可免费使用;只有主动选择远程见证或 RFC 3161 时间戳时才需要网络。
如何使用这个 Agent?
在自己的 Python 代理入口记录运行边界:
from halo_record import trace
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")要捕获具体工具调用,需要在每个工具边界增加 record_call() 或使用适配器:
from halo_record import Recorder, record_call
rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call:
call.result = crm.lookup("acct-9")
with record_call(rec, "payments.refund", {"amount": 120},
parent_id=rec.last_record_id()) as call:
call.result = payments.refund(120)随后验证并生成报告:
halo verify audit.jsonl
halo report audit.jsonl -o report.html如需浏览一个目录内按客户隔离的报告,可运行:
halo serve ./records --port 8721Claude Code 可将以下内容加入 ~/.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
]
}
}Codex 可将以下内容加入 ~/.codex/hooks.json:
{
"hooks": {
"PostToolUse": [
{"matcher": ".*", "hooks": [{"type": "command", "command": "halo hook"}]}
]
}
}两种钩子默认写入 ~/.halo/audit.jsonl,可用 HALO_LOG 改写路径;HALO_HASH_ONLY=1 可关闭摘要。若要承诺已提交历史,可建立并检查见证点:
halo anchor audit.jsonl witness.jsonl
halo anchor audit.jsonl witness.jsonl --check这个 Agent 有哪些优点和局限?
- 运行时仅使用 Python 标准库;核心记录和本地验证无需外部服务或网络。
- 开放记录格式、RFC 8785 规范化和 SHA-256 链允许第三方独立实现验证器,无需持有密钥。
- 同时覆盖原生边界捕获和现有遥测摄取,并通过
source标签公开证据来自何处。 - 外部检查点明确加强历史完整性;还支持 RFC 3161 时间证明,而不会向见证发送记录正文。
- 可交付自校验 HTML、策略判定结果,以及带源链头和文件哈希清单的 CSV 审计证据。
- 项目明确记录完整性、捕获完整性和可信捕获之间的边界,避免把哈希链描述成全面证明。
- 自持链只能相对既有链头发现编辑;在链头交给外部方之前,操作者仍可能删记录后重新封链。
- 任何哈希链都不能证明所有真实动作经过记录器;完整性仍取决于插桩位置和捕获边界。
- 默认脱敏是正则和熵检测的尽力措施,姓名、邮寄地址及自由文本等内容可能永久进入追加式链。
- 没有内置保留或裁剪功能;删除链内记录会破坏后续验证,个人数据治理需要外部假名映射纪律。
- 链要求单写者语义;绕过
Recorder的并行写入必须自行持有等效互斥锁或使用每进程独立链。 - 框架回调默认故障开放,写入失败时动作仍会执行且记录可能永久丢失;只有周期性见证才能暴露链停滞。
这个 Agent 与同类方案有什么区别?
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Halo Record 代理审计轨迹 当前 | 82 · 表现良好 | 命令行工具免费 | ★ 86 | 20 天前 | Python | Codex · Claude Code · OpenAI API · Claude API |
| OpenInference | 66 · 存在缺口 | 代码库 / SDK免费 | ★ 1.3k | 今天 | Python | OpenAI API · Claude API |
| Prismor | 61 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 583 | 今天 | Python | Codex · Claude Code · OpenAI API · Claude API |
| Cordum Agent Control Plane | 75 · 存在缺口 | 自托管服务免费 | ★ 507 | 3 天前 | Go | Claude Code |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
依赖声明为空、记录写入和网络外发均有明确边界,并提供默认透传与严格模式;这些支持较好的最小权限和依赖安全评分。网络例外需手动启用,但材料未展示每种敏感操作的交互确认,因此用户确认仅部分得分。README与SECURITY明确说明记录内容、脱敏局限、外发例外及写入失败行为;正则脱敏是尽力而为,且短文本可能原样保留,敏感数据处理未满分。可选见证、时间戳和邮件会产生外部效果;删除或更正记录的恢复流程材料不充分。项目名、作者和安全报告邮箱可追溯,但维护责任与更新承诺不够具体。
README、CLI和测试材料对空链、见证完整性、失败写入、严格模式及异步包装等行为描述具体且相互吻合,故静态自洽性及失败消息得高分。声明零运行依赖且配置列出 Python 版本,但示例还依赖可选生态和外部服务,依赖可用性仅得部分分;未据此推断实际运行结果。
材料覆盖原生记录、多个框架适配器、MCP、遥测导入、网关、编程助手钩子及买方侧平台日志,适用场景广。明确区分捕获与导入、边界证据与事后钩子,并说明哪些能力不能证明完整性;钩子触发和捕获边界也有具体描述。环境适配仅部分得分,因为说明集中于 Python/CLI 和给定钩子环境,且部分集成涉及外部组件。
README分层组织并提供安装、快速开始、代码示例、故障处理和多份限制/隐私/保留说明;信息架构、安装说明、示例和已知限制充分。LICENSE与元数据均指向 Apache-2.0。模块与导入命名存在 `halo` 同名冲突,README虽说明解决方式,命名稳定性仍扣分。包版本为 0.2.47,但所给材料没有变更日志内容;维护责任有作者、安全邮箱和问题入口,但持续维护责任说明有限。
输出为可分享的 HTML 报告及 JSONL 链,并在浏览器和 CLI 复核;对外部检查者的可用性明确。哈希链、外部检查点及捕获边界的区分提供了清楚的审计价值。成本效益得部分分:核心依赖轻、演示易上手,但生产证据质量依赖正确的捕获部署、外部见证和操作配置。
主要安全与完整性主张可追到 README、LIMITS/PRIVACY/SECURITY 的引用说明、CLI行为及所给测试源码;CI配置也显示测试与样例验证的自动化安排。不同来源对写入失败、见证和链验证边界相互支持。文档明确区分记录字段所声称的内容与 Halo 实际能证明的内容,并披露演示数据为虚构、验证状态限制及未捕获行为的边界,因此静态可核验性得高分;本评估未执行代码或测试。
- 脱敏是尽力而为;短小且未匹配已知模式的参数摘要可能以原文保存。对敏感输入使用 `summaries=False`,并避免把自由文本或私密策略内容写入记录。
- 哈希链本身不能证明记录完整或捕获了每个动作;需要由操作方之外持有的检查点,并将记录器放在 Agent 无法关闭的位置。记录发生在动作之后,严格模式报错后重试可能重复外部副作用。
最近版本
来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。
-
v0.2.47 0.2.47
发布说明摘录
Release 0.2.47 Buyer-side door. halo door reads a platform log export the buyer already holds (a GitHub security log, or Salesforce Event Monitoring CSVs including Agentforce actions and callouts), seals it on ingest, and renders a page of what one outside agent did: the actions, the credentials used, where it reached, which rules broke, and what the export cannot show. The page re-verifies the embedded chain in the browser and withholds its summary, narrative, and rules when verification fails. Two synthetic sample exports ship in the package; halo door --sample runs …在 GitHub 查看 ↗ -
v0.2.46 halo-record 0.2.46
发布说明摘录
halo-record 0.2.46 A security and evidence-integrity release. Upgrading is recommended for everyone; read the upgrade notes if you run halo serve. Security - Tenant isolation: per-subject chain files with digest-suffixed names; grants and share links are keyed by subject id; halo grant refuses names whose report halo serve would withhold; grants from 0.2.45 are carried only when unambiguous and otherwise quarantined and printed at startup. …在 GitHub 查看 ↗ -
发布说明摘录
- The IBAN matcher is built from 4-character blocks and, when a match runs past the account number into the words that follow it, retries shorter endpoints before giving up — so "DE89 … 00 today" and "…013000EUR" mask whole instead of passing through unmasked. Tab, non-breaking-space, and double-space separators are accepted; a card match inside an accepted IBAN no longer co-classifies it. The api_key pattern accepts underscore and hyphen segments (sk-ant-…). …在 GitHub 查看 ↗
常见问题
本地使用是否需要付费服务或模型 API 密钥?
它能证明代理的每个动作都被记录了吗?
记录器失败时,代理会不会停止?
trace() 原生包装器故障关闭,写入异常会传播并中断动作。LangChain 等框架适配器故障开放:动作继续执行,丢失记录会通过警告和计数器报告,但链本身无法显示从未写入的事件。工具参数和客户数据会发送到外部见证吗?
能否让多个工作进程写同一个链文件?
Recorder 自带侧边锁;直接写文件的并行进程应使用等效锁,或分别写入独立链。Halo Record 代理审计轨迹 开源吗?
Halo Record 代理审计轨迹 安全吗?
Halo Record 代理审计轨迹 还在维护吗?
Halo Record 代理审计轨迹 是谁开发的?
谢谢反馈,我们会据此改进页面。