Skip to content
KitploitKITPLOIT
工具漏洞利用博客
Log in
提交
工具漏洞利用博客
提交

黑客、渗透测试和网络安全工具,武装您的安全武器库!

Kitploit 是一个黑客、网络安全和渗透测试工具的目录。发现最新的项目更新,查找漏洞、分析系统、自动化测试并加强你的安全。

订阅源联系隐私© 2026 Kitploit

工具目录

分类

查看所有分类
Loading categories
halo-record — 面向AI智能体的防篡改审计追踪:哈希链式运行时记录,零依赖,任何人可验证。 | Kitploit
工具/GitHubGitHub/bkuan001/halo-record
取证分析供应链安全事件响应AI 安全
GitHubbkuan001/halo-record

halo-record

面向AI智能体的防篡改审计追踪:哈希链式运行时记录,零依赖,任何人可验证。

查看仓库网站
63612018天前Kitploit 审核通过
分享

halo-record

防篡改的 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 只安装一个包。
  • 无网络调用,除了四个需主动启用的调用——锚定到见证者(发送主体 ID、记录数量和两个链指纹——链头和链根)、回读见证者的检查点(发送主体 ID)、RFC 3161 时间戳(仅将检查点的状态哈希发送给时间戳机构),以及 halo serve --verify-email(通过你在 $HALO_SMTP_HOST 中配置的服务器,经 SMTP 将一次性验证码和报告的主体名称发送到报告查看者输入的地址)。除非你主动调用,否则这些功能全部关闭;其他记录内容不会离开你的基础设施。
  • 原始工具参数会被哈希,并附带脱敏摘要。 参数以规范化哈希加摘要的形式存储:摘要为参数文本,其中已知的密钥和 PII 模式已被掩码,上限为 200 个字符。不匹配任何模式的短输入会完整出现在摘要中;仅哈希模式(summaries=False)完全不保留摘要。脱敏是尽力而为的(对常见密钥和 PII 格式使用正则表达式,外加熵兜底):请将其视为纵深防御,而非保证。你提供的 summary 之外的结果字段会用相同模式扫描并掩码,但不会被截断到 200 个字符(LIMITS §13)。
  • 小到可以审计。 约 8,700 行 Python,包括报告页面内嵌的 JavaScript 和 CSS(代码行数,不计空行、注释和文档字符串)。一天之内即可全部读完。
  • Apache-2.0。
  • 文档是一等公民。 LIMITS.md(链无法证明什么)、PRIVACY.md(记录包含什么以及什么会离开你的机器)、RETENTION.md(在保留策略下运行),以及 REVIEWERS.md——四命令独立检查,外加审查发现的引用格式。

每一层证明什么——本项目中的关键区分(LIMITS.md §1):你自己持有的链证明记录未被编辑,相对于某人已持有的链头;只有由运营者外部持有的检查点才能证明没有记录被删除;而没有任何哈希能证明每个操作都被捕获。

声明自持链+ 外部检查点+ 可信捕获
检测对已建立产物的编辑✔✔✔
检测对已提交历史的改写—✔✔
检测缺失/延迟的检查点—✔(约定节奏)✔
证明每个操作都被记录——取决于捕获边界

安装前先看一个示例: 示例运行时报告——虚构数据、真实链,打开时其脚本会在你的浏览器中重新计算内嵌记录的哈希链。

60 秒演示

无需 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"})
下载工具

最受欢迎

查看全部 →

发现我们社区最常用的工具。

暂无热门数据。

探索所有工具

浏览我们的工具集合

查看所有工具 →