Halo Record 代理审计轨迹

为 AI 代理生成可由客户独立校验的防篡改审计轨迹。

Star 数
★ 86
最近更新
20 天前
License
Apache-2.0
主语言
Python

30 秒速览

运行形态
命令行工具代码库 / SDK自托管服务
可在哪里用
通用 · 跨平台Codex · Claude Code · OpenAI API · Claude API
费用
免费,无需付费服务
上手难度
低 · 几分钟可跑通
开始前需要
Pythonpip 或 uvShell / 命令行本地文件系统
典型场景
向客户安全团队交付 AI 代理处理其数据的可校验 Runtime Report,而不是仅提供文字说明的软件供应商。
不适合
  • 需要证明所有真实动作均被记录的团队
  • 要求内置保留、裁剪或彻底删除链上个人数据的团队
  • 无法为并行写入者建立独立链或互斥锁的系统
维护状态
近 30 天有提交最近提交 2026-11-01最新版本 v0.2.47(2026-11-01)

这个 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 事件写入同一记录格式。

  1. 向客户安全团队交付 AI 代理处理其数据的可校验 Runtime Report,而不是仅提供文字说明的软件供应商。
  2. 需要为 SOC 2、AIUC-1、AICM、ISO 42001、EU AI Act 或 NIST AI RMF 评审准备日志证据和日期范围导出的合规团队。
  3. 运行 LangChain、LangGraph、MCP 或 OpenTelemetry GenAI 工作负载,并希望把不同来源的动作统一封入一条链的平台团队。
  4. 希望记录 Claude Code 或 Codex 文件修改、Shell 命令和 MCP 调用,又不想修改代理代码的工程团队。
  5. 需要由客户或其他外部方持有周期性检查点,以发现已提交历史被改写或检查点中断的高信任场景。
  6. 需要把特定工具调用范围导出成 CSV 和校验清单,再上传至 Vanta、Drata 等 GRC 平台的审计团队。

安装与配置要点

摘自下方的安装和使用说明,以项目 README 的最新说明为准。

安装 / 启动命令
  • uvx --from halo-record halo demo --serve
  • pip 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 8721

Claude 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?

FollowAgents 源码审查 · FARS-2.1
表现良好
82/ 100 五分制 4.1 / 5
信任安全 19/29
可靠稳定 12/14
适用触发 16/18
规范维护 15/18
有效结果 12/13
证据核验 8/8
查看各维度的扣分理由
信任安全19 / 29 · 3.3/5

依赖声明为空、记录写入和网络外发均有明确边界,并提供默认透传与严格模式;这些支持较好的最小权限和依赖安全评分。网络例外需手动启用,但材料未展示每种敏感操作的交互确认,因此用户确认仅部分得分。README与SECURITY明确说明记录内容、脱敏局限、外发例外及写入失败行为;正则脱敏是尽力而为,且短文本可能原样保留,敏感数据处理未满分。可选见证、时间戳和邮件会产生外部效果;删除或更正记录的恢复流程材料不充分。项目名、作者和安全报告邮箱可追溯,但维护责任与更新承诺不够具体。

可靠稳定12 / 14 · 4.3/5

README、CLI和测试材料对空链、见证完整性、失败写入、严格模式及异步包装等行为描述具体且相互吻合,故静态自洽性及失败消息得高分。声明零运行依赖且配置列出 Python 版本,但示例还依赖可选生态和外部服务,依赖可用性仅得部分分;未据此推断实际运行结果。

适用触发16 / 18 · 4.4/5

材料覆盖原生记录、多个框架适配器、MCP、遥测导入、网关、编程助手钩子及买方侧平台日志,适用场景广。明确区分捕获与导入、边界证据与事后钩子,并说明哪些能力不能证明完整性;钩子触发和捕获边界也有具体描述。环境适配仅部分得分,因为说明集中于 Python/CLI 和给定钩子环境,且部分集成涉及外部组件。

规范维护15 / 18 · 4.2/5

README分层组织并提供安装、快速开始、代码示例、故障处理和多份限制/隐私/保留说明;信息架构、安装说明、示例和已知限制充分。LICENSE与元数据均指向 Apache-2.0。模块与导入命名存在 `halo` 同名冲突,README虽说明解决方式,命名稳定性仍扣分。包版本为 0.2.47,但所给材料没有变更日志内容;维护责任有作者、安全邮箱和问题入口,但持续维护责任说明有限。

有效结果12 / 13 · 4.6/5

输出为可分享的 HTML 报告及 JSONL 链,并在浏览器和 CLI 复核;对外部检查者的可用性明确。哈希链、外部检查点及捕获边界的区分提供了清楚的审计价值。成本效益得部分分:核心依赖轻、演示易上手,但生产证据质量依赖正确的捕获部署、外部见证和操作配置。

证据核验8 / 8 · 5.0/5

主要安全与完整性主张可追到 README、LIMITS/PRIVACY/SECURITY 的引用说明、CLI行为及所给测试源码;CI配置也显示测试与样例验证的自动化安排。不同来源对写入失败、见证和链验证边界相互支持。文档明确区分记录字段所声称的内容与 Halo 实际能证明的内容,并披露演示数据为虚构、验证状态限制及未捕获行为的边界,因此静态可核验性得高分;本评估未执行代码或测试。

风险与缓解建议
  • 脱敏是尽力而为;短小且未匹配已知模式的参数摘要可能以原文保存。对敏感输入使用 `summaries=False`,并避免把自由文本或私密策略内容写入记录。
  • 哈希链本身不能证明记录完整或捕获了每个动作;需要由操作方之外持有的检查点,并将记录器放在 Agent 无法关闭的位置。记录发生在动作之后,严格模式报错后重试可能重复外部副作用。
证据充分度:低 评估于 2026年11月8日 审查版本 2b3b355f03a3
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/halo-record.svg?lang=zh)](https://followagents.com/zh/agents/halo-record)
<a href="https://followagents.com/zh/agents/halo-record"><img src="https://followagents.com/badge/halo-record.svg?lang=zh" alt="FARS 评测"></a>

最近版本

来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。

  1. 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 查看 ↗
  2. 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 查看 ↗
  3. v0.2.45
    发布说明摘录
    - 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 密钥?
不需要。软件采用 Apache-2.0,演示、记录、验证、报告及本地见证均可在本机完成。远程见证和 RFC 3161 时间戳是主动选择的网络功能。
它能证明代理的每个动作都被记录了吗?
不能。链能证明已建立链头之后的记录未被无痕修改;外部检查点能发现已提交历史被改写,但捕获是否完整取决于记录器位于调用栈中的位置。
记录器失败时,代理会不会停止?
trace() 原生包装器故障关闭,写入异常会传播并中断动作。LangChain 等框架适配器故障开放:动作继续执行,丢失记录会通过警告和计数器报告,但链本身无法显示从未写入的事件。
工具参数和客户数据会发送到外部见证吗?
不会。见证载荷仅包含主体 ID、记录数、链头和链根指纹;RFC 3161 服务只接收检查点状态哈希。不过本地链中的摘要脱敏并非保证,敏感字段仍需由集成方控制。
能否让多个工作进程写同一个链文件?
只有在完整的读取链头至追加记录过程受到互斥保护时才安全。Recorder 自带侧边锁;直接写文件的并行进程应使用等效锁,或分别写入独立链。
Halo Record 代理审计轨迹 开源吗?
开源。源码在 GitHub(bkuan001/halo-record),许可证是 Apache-2.0。
Halo Record 代理审计轨迹 安全吗?
FollowAgents 的 FARS 评审(2026年11月8日)给 Halo Record 代理审计轨迹 的“信任与安全”打了 19/29 分。评审检查的 8 项安全措施没有完全缺失的。
Halo Record 代理审计轨迹 还在维护吗?
在维护。GitHub 上最近一次提交是 2026-11-01,在最近 30 天内。最新版本是 v0.2.47(2026-11-01)。
Halo Record 代理审计轨迹 是谁开发的?
Halo Record 代理审计轨迹 由 GitHub 账号 bkuan001 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念