或经典方式：```
pip install halo-record
halo demo --serve

一个 `from halo import ...` 的便捷 shim 也会随附发布——但 PyPI 上的 `halo` 名称属于一个无关的终端 spinner 包，如果该包已安装，它会在导入时胜出。`halo_record` 没有歧义，因此示例使用它。

在没有 `log=` 的情况下，记录会写入 `~/.halo/my-agent.jsonl`（每个 agent 一条链）。wrapper 封存运行边界；证据存在于每次调用的记录中。使用框架适配器（见下方矩阵）捕获这些记录——或者显式捕获，这同时展示了委托链接是如何建立的：```python
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)

快速入门结束时，你会在浏览器中看到自己 agent 的 Runtime Report。如果你拿到的是 JSONL 文件而没有报告，说明出了问题：请提交 issue。

### 验证块

如果某个 guardrail 或策略层检查了该操作，其裁决结果可以附加在记录上——这是一个可选块，记录 gate 做出了什么决定，并像其他所有字段一样被封入哈希链：```python
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_call(...)` 接受相同的 `verification=` 关键字参数。`status` 在块内是必需的；`verifier`、`policy_ref` 和 `checked_at` 是可选的。每个状态的含义如下：

| 状态 | 门禁报告的内容 | 操作是否执行？ |
|---|---|---|
| `allowed` | 它允许了该操作 | 是——操作继续进行 |
| `blocked` | 它拒绝了该操作 | 由集成决定，而非此字段——记录仍可能携带结果，且阻止本身并不能证明未执行 |
| `modified` | 它在执行前修改了该操作——`action.input` 描述的是**已执行**的操作，即修改后的状态 | 是，以修改后的形式 |
| `unverified` | 它运行了（或被咨询了）但未做出判定——与缺失的块不同，后者意味着根本没有做出验证声明 | 是——操作在没有裁决的情况下继续进行 |

该块由操作者的集成代码提供，并记录其报告的门禁所述内容——与 `principal` 相同的信任姿态（参见 [LIMITS](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#11-verification-status-is-the-gates-report-not-halos-finding)）。密封证明状态在事后未被编辑；它并不证明检查确实发生、裁决正确，或已阻止的操作未执行。这不是独立验证。

要使 `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` 钩子（在工具运行后触发） |

框架适配器和摄取路径会为每条记录打上 `source` 标签，因此报告会披露每条证据的收集方式。捕获的记录和摄取的记录位于同一条链中。

对于 LangChain / LangGraph，它是一个回调处理器：```python
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

对于网关或代理日志（Cloudflare AI Gateway、Portkey、模型前方的 nginx），将日志行映射到链中——明确标记为已摄取，而非边界捕获：```python
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"})

将其添加到 `~/.claude/settings.json`，记录会写入 `~/.halo/audit.jsonl`（可通过 `$HALO_LOG` 覆盖）。不接触任何数据、网络或外部状态的纯编排工具会被跳过——该链记录的是信任边界操作，而非思考过程。设置 `HALO_HASH_ONLY=1` 可仅记录内容哈希而不记录摘要。设置 `HALO_AGENT_VERSION`（以及可选的 `HALO_AGENT_MODEL`）可将每条记录绑定到产生它的 agent 构建版本——当审计人员询问某个时间窗口内运行的是哪个版本时，导出结果会按列给出答案，而不是靠回忆。

Codex CLI 提供相同的生命周期钩子，事件结构也相同（钩子默认开启）。将其添加到 `~/.codex/hooks.json`，Codex 的 shell 命令、`apply_patch` 编辑和 MCP 调用就会写入同一条链：```json
{
  "hooks": {
    "PostToolUse": [
      {"matcher": ".*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

## 使用示例

### 基本用法

```bash
# 扫描单个目标
python3 cve_2025_55182.py -t https://target.example.com

# 使用代理扫描
python3 cve_2025_55182.py -t https://target.example.com -p http://127.0.0.1:8080

# 从文件扫描多个目标
python3 cve_2025_55182.py -f targets.txt

# 使用自定义超时和线程数扫描
python3 cve_2025_55182.py -f targets.txt -T 15 -c 20

# 使用自定义载荷扫描
python3 cve_2025_55182.py -t https://target.example.com -P "custom_payload_here"

# 详细输出
python3 cve_2025_55182.py -t https://target.example.com -v

# 使用自定义 User-Agent 扫描
python3 cve_2025_55182.py -t https://target.example.com -A "Mozilla/5.0 (Custom)"

# 使用自定义请求头扫描
python3 cve_2025_55182.py -t https://target.example.com -H "X-Custom-Header: value"

# 将结果保存到文件
python3 cve_2025_55182.py -f targets.txt -o results.txt

# 组合多个选项
python3 cve_2025_55182.py -f targets.txt -p http://127.0.0.1:8080 -T 15 -c 20 -v -o results.txt

[+] 正在扫描目标: https://target.example.com
[+] 目标可访问
[+] 正在测试漏洞...
[!] 目标易受攻击: https://target.example.com
[+] 利用成功
[+] 命令输出: uid=33(www-data) gid=33(www-data) groups=33(www-data)

快照被密封在与操作记录相同的哈希链中。一个良好的默认设置是在开始时生成一个会话级快照，并在规则、Skills、hooks、MCP 工具注册表或压缩策略发生变化时生成新快照。为保持长会话精简，具有相同 `authority.snapshot_id` 的连续记录在第一个完整快照之后会被压缩：后续记录仅保留 `{"snapshot_id": "...", "same_as_previous": true}`。指针仍保持哈希链式连接，但庞大的 refs/omissions/stale-if 块不会在每个操作上重复。（压缩是按记录器进程进行的：hook 式捕获为每次工具调用生成一个进程，当上一个完整快照不是尾部记录时，会重新存储完整主体，因此短生命周期进程以链大小为代价换取复用保护。）

SDK 用户直接附加相同的块——`build(..., authority={...})` 或 `record_call(..., authority={...})`；仅哈希捕获是相同的接口（在任意一个上设置 `summaries=False`）：```python
from halo_record import Recorder, record_call

rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"},
                 authority={"snapshot_id": "auth_1", "rules_hash": "sha256:..."},
                 summaries=False) as call:              # hash-only: no summaries, no excerpts
    call.result = crm.lookup("acct-9")

任何暴露 post-action hook 的 agent 运行时都可以喂入同一条命令——该 hook 从 stdin 读取一个 JSON 事件并追加一条记录。

一条链，同一时间只有一个写入者。链是一个链表：两个写入者读取同一个 head 并都进行追加，就会使其分叉（两条记录声称拥有同一个前驱），验证过程会指出受影响的记录。`Recorder` 通过 sidecar 锁（此处为 POSIX `flock`；TypeScript 包中为锁目录）串行化自身的追加操作，而 `halo hook` 通过 `Recorder` 进行追加，因此上述 hook 设置已被覆盖。任何直接写入链文件的操作——手写的 hook、并行 worker、日志转发器——都必须在“读取 head 然后追加”这一序列期间持有等效的排他锁，或者写入按进程划分的链。[LIMITS.md 第 9 节](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#9-single-writer-chains)完整涵盖了这一点，包括跨语言边界。

## 当记录失败时

两种集成方式会以相反的方向失败，这是有意为之——选择那种其失败方式你可以承受的：

- **框架适配器（LangChain，通过 callback manager 实现的 hooks）失败时保持开放。** 如果记录无法写入（磁盘已满、权限不足），agent 的操作会正常完成，而记录则丢失。LangChain handler 会向 stderr 打印一条醒目的警告并统计丢失数量（`handler.lost_records`），但链本身无法显示一条从未被写入的记录——停滞的链仍然能通过验证。按固定节奏设置的 witness checkpoint 才是让停滞的链变得可见的关键：一个预期到达却从未到达的 checkpoint 就是警报。
- **原生 `trace()` 包装器失败时保持关闭。** 如果记录无法写入，异常会传播到 agent 的操作中——没有证据，就没有操作。更严格，但它可能会中断你的 agent。

两种默认行为都不适合所有人；要清楚你正在运行的是哪一种。

## 完整性 vs. 完备性（请阅读这一部分）

要精确理解每一层所证明的内容——因为它们是不同的主张，而这些差异正是关键所在：

自持链证明的是**相对于已确立 head 的完整性**：给定某人已经持有的链 head，其背后记录中的任何编辑、重排序或删除都会变得可检测。就其本身而言——在操作者之外的任何人看到 head 之前——链证明的是内部一致性，而非历史：操作者可以丢弃一条记录并重新密封，而新文件仍能通过验证。链在其 head 离开操作者控制的那一刻就变得**具有历史承诺性**。

这就是 witness：操作者之外的一方持有链的周期性 checkpoint——subject id、记录数量，以及两个链指纹（head 和链根）；确切的有效载荷，仅此而已。Checkpoint 使重写已承诺的历史变得可检测，而错过的 checkpoint 本身就是一个可见事件：```
halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

`--check` 确认令牌绑定此链状态并读取其经证实的时间，但**不会**验证 TSA 的签名——这是有意留给标准工具处理，以便审查者无需信任我们的任何代码。要独立验证时间（这正是你交给安全审查者的内容）：```
# tsa.token_b64 lives in the witness log; decode the latest one to a standard .tsr file
python3 -c 'import json,base64; cps=[json.loads(l) for l in open("witness.jsonl") if l.strip()]; t=[c["tsa"] for c in cps if c.get("tsa")][-1]; open("token.tsr","wb").write(base64.b64decode(t["token_b64"])); print(t["digest"])'
curl -s -o tsa-ca.pem https://freetsa.org/files/cacert.pem     # CA for the default TSA (a commercial TSA publishes its own)
openssl ts -verify -digest <the digest printed above> -in token.tsr -CAfile tsa-ca.pem   # → "Verification: OK"

没有任何设置强制这一点——这是你调用记录器时的一种纪律。
它使擦除变得可行；它不是匿名化，而且目前还没有内置的
保留或清理机制。
[LIMITS.md 第 13 节](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#13-personal-data-and-erasure) 列出了完整的字段
清单，解释了为什么即使映射已不存在，存储的输入指纹仍能确认一个可猜测的值，
并以审查者应当提出的问题作为结尾。

记录一次模型调用（买方的第一个问题：“哪个模型看到了我的数据？”）：```python
from halo_record import record_model_call

record_model_call(rec, provider="anthropic", model="claude-sonnet-4-6",
                  zdr=True, purpose="draft support reply",
                  subject="acme")   # tool=model.generate, scope=model:anthropic

这会为审计窗口写入两个文件：CSV（每个记录的操作一行，从左到右分组为*何时 → 发生了什么 → 谁 → 依据什么授权 → 标记了什么 → 来源 → 如何验证*，包括对调用及其结果的脱敏通俗语言摘要、产生每次调用的 agent 构建和模型、其代表运行的身份、导致该调用的记录、其授权决策和范围，以及任何个人数据类别或摄入的威胁标记）和一个清单（`evidence.csv.manifest.json`），该清单将 CSV 与其来源关联起来——链的头哈希将其链接到它所来自的可验证日志，而 `csv_sha256` 是导出文件自身的哈希，因此导出后被编辑的 CSV 将不再与其清单匹配。当某个控制仅覆盖特定操作时，使用 `--tool` 缩小范围；清单会记录该过滤器，因此限定范围的导出会披露它是一个子集，而不会被读作整个总体。将两者上传到你的日志记录或监控控制项；当审查者想要自行验证链时，附上 Runtime Report HTML。该导出会拒绝在验证失败的链上运行。

原生推送集成——证据自动落入你的平台——已在路线图中。上述文件路径目前适用于任何接受上传证据的平台。

## CLI```
halo verify   validate schema + hash chain (exit 1 broken, 3 empty chain; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
              (--from/--to: a date-windowed report covering only the review period)
halo policy   corroborate a chain against a declarative policy pack
              (per-rule pass / violation / evidence-gap; exit 1 violated, 3 nothing in scope)
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo viewers  list who has unlocked a gated report
halo anchor   witness a chain head, or --check completeness (exit 1 incomplete, 3 unwitnessed)
halo witness-serve  run a witness over HTTP: vendors anchor chain heads, viewers fetch checkpoints
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo export   date-bounded evidence export: CSV + manifest tied to the chain head
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook