# 智能体出错时，审计日志却记在提问的人头上

> 按 RFC 8693 把触发用户和受托智能体分开记录，日志才能说清哪个工具用什么参数运行。

原文: https://fdetimes.net/zh/guides/agent-audit-log-user-and-agent/

设想这样一个场景：客户的客服智能体刚刚关闭了 40 个本该保持打开的工单。工单系统的日志显示，操作人是客服组长。

实际上，他只输入了一条请求。选工具、填参数、执行，都是智能体做的。客户问起谁该负责时，你拿不出任何证据。

问题出在日志，不在模型。模型上下文协议（MCP）的安全文档描述的正是这种情况：令牌被直接透传（passthrough）时，下游日志可能把请求记成来自另一个来源、另一个身份。

本指南要搭建的审计日志能回答三个问题：谁触发了操作，哪个智能体代其执行，调用了哪个工具、用了什么参数。

跟着做只需要 Python 3，外加一个用来挂载 hook 的 Claude Code 测试项目。下面的代码为学习做了简化。用于生产环境前，请对照 Claude Code 文档核对 hook 的配置语法。

## 正确的日志结构从四个问题开始

OWASP Logging Cheat Sheet 给出了基线：每条记录都必须回答何时、何地、何人、何事，并包含足够的信息供后续监控和分析。到了智能体场景，“何人”要难得多，因为一次操作至少涉及两个身份。

RFC 8693（OAuth 2.0 Token Exchange）明确区分了两种机制。冒充（impersonation）时，执行方获得原主体的全部权限，日志再也分不清两者。委托（delegation）时，智能体保留自己的身份。因此日志结构需要两个独立字段：`on_behalf_of` 记录用户，`actor` 记录智能体。

| 问题 | 记录中的字段 | 来源 |
|---|---|---|
| 何时 | `when`（UTC，ISO 8601） | 服务器时钟 |
| 何地 | `host`、`session_id` | 主机、hook 的 JSON 负载 |
| 何人 | `on_behalf_of`、`actor`、`actor_chain` | 令牌中的 `sub` 和 `act` 声明 |
| 何事 | `tool_name`、`tool_use_id`、参数 | hook 的 JSON 负载 |

**检查方法：**把这张表交给同事，问他仅凭这些字段能否回答“是哪个智能体关闭了那 40 个工单”。如果不能，说明结构还不完整。

## 第 1 步：用 hook 捕获每一次工具调用

Claude Code 的 hook 会在每次工具调用时运行，并收到一个 JSON 负载，其中包含 `session_id`、`tool_name`、`tool_input` 和 `tool_use_id`。有这四个字段，就能知道调用了哪个工具、用了什么参数、发生在哪个会话。hooks 文档里有一个 PreToolUse 示例：向日志文件追加内容，并用 matcher 过滤 MCP 工具。下面的代码就基于这个模式。

```python
#!/usr/bin/env python3
# audit_hook.py - 简化版，仅供学习
import json, sys, os, hashlib, datetime

LOG = os.path.expanduser("~/agent-audit.jsonl")
event = json.load(sys.stdin)  # hook 接收到的 JSON 负载

tool_input = event.get("tool_input") or {}
record = {
    "when": datetime.datetime.now(datetime.timezone.utc).isoformat(),
    "where": {"host": os.uname().nodename,
              "session_id": event.get("session_id")},
    "what": {"tool_name": event.get("tool_name"),
             "tool_use_id": event.get("tool_use_id"),
             "input_keys": sorted(tool_input.keys())},
}
```

把这个脚本注册为 PreToolUse hook。如果只想跟踪 MCP 工具，参照文档示例加上 matcher 即可。**检查方法：**让智能体随便调用一个工具，然后打开日志文件，应该能看到与刚才那次调用对应的 `tool_use_id`。

## 第 2 步：把用户和智能体分开

hook 告诉你发生了什么，而“何人”的答案在令牌里。RFC 8693 在 JWT 中定义了 `act` 声明来表达委托：`sub` 仍是用户，`act` 说明由谁执行。一个智能体调用另一个智能体时，`act` 声明会层层嵌套成一条链。

```python
def who_from_claims(claims: dict) -> dict:
    chain, act = [], claims.get("act")
    while act:                      # 最外层 act = 当前执行者
        chain.append(act.get("sub"))
        act = act.get("act")        # 嵌套 act = 上一个执行者
    return {"on_behalf_of": claims.get("sub"),
            "actor": chain[0] if chain else None,
            "actor_chain": chain}
```

有个细节容易忽略。RFC 8693 规定，嵌套 `act` 链中靠前的执行者仅供参考，令牌不对它们做任何约束。如果以后想追溯这条链，就得由日志自己保存。`actor_chain` 字段就是为此而设。

这个函数必须运行在接收请求的服务器上，因为令牌在那里。MCP 建议服务器只接受签发给自己的令牌，因为令牌透传会增加事故调查和审计的难度。

如果让用户的令牌穿过好几层，`actor` 永远是空的，你又回到了 40 个工单的局面。**检查方法：**解码智能体调用 API 时实际使用的一个令牌，先看清 `sub` 是谁，再下结论。

如果 `sub` 是用户，却没有 `act` 声明，说明令牌没有表达任何委托：智能体在冒充用户，或者直接透传了用户的令牌，下游日志无法区分两者。如果 `sub` 是智能体本身，即智能体用的是自己的令牌，那么没有 `act` 是正常的，因为它并没有代表任何人。

第二种情况下，`actor` 记录正确，但令牌没有说明是哪个用户触发了操作。这时 `on_behalf_of` 必须从用户会话中获取并单独记录，否则这条记录对“何人”只回答了一半。

**要点:** 只记录用户名的日志，永远说不清智能体代用户做了什么。

## 第 3 步：把每个参数都当作不可信文本

工具参数由模型生成，而模型可能已被提示注入操控。OWASP 要求所有事件数据在记录前都要清洗，以防日志注入。

假设某个参数里有一个换行符，后面跟着一行伪造的 JSON：原样写入这个字符串，攻击者就在你的日志里造出了一条自己的记录。

简单的防御办法是始终用 `json.dumps` 写入。它会转义换行符，保证每条记录恰好占一行。第二个问题是个人数据。OpenTelemetry GenAI 约定提醒，消息内容很可能包含个人身份信息（PII），因此只应在显式开启时记录内容。

```python
if os.environ.get("AUDIT_LOG_CONTENT") == "1":   # 需显式开启
    record["what"]["input"] = {k: str(v)[:500] for k, v in tool_input.items()}
```

默认情况下，日志只保留参数的键名。这已经足以知道智能体调用了 `delete` 工具、带有 `ticket_id` 键，又不会存下客户的邮箱地址。500 个字符的上限只是示例，可按实际需要设定。

## 第 4 步：让日志难以被悄悄改动

谁都能改的审计日志，就不再是证据。OWASP 建议内置一种机制，用来发现记录被修改或删除，并尽快把日志复制到只读存储。一个简单做法是哈希链：每一行都保存上一行的哈希。

```python
def last_hash():
    try:
        with open(LOG, "rb") as f:
            return json.loads(f.readlines()[-1])["hash"]
    except (FileNotFoundError, IndexError):
        return "0" * 64

record["prev"] = last_hash()
body = json.dumps(record, sort_keys=True, ensure_ascii=False)
record["hash"] = hashlib.sha256(body.encode()).hexdigest()
with open(LOG, "a", encoding="utf-8") as f:
    f.write(json.dumps(record, ensure_ascii=False) + "\n")
```

这个简化版在多个 hook 同时写入时不会给文件加锁，而且只能发现篡改，不能阻止篡改。阻止篡改要靠把日志送到只读存储。校验时，需要一个脚本从文件开头逐行读取，按 hook 完全相同的方式重新计算每个哈希。

```python
#!/usr/bin/env python3
# verify_chain.py - 从第一行开始重新计算哈希链
import json, hashlib, os, sys

LOG = os.path.expanduser("~/agent-audit.jsonl")
prev = "0" * 64
with open(LOG, encoding="utf-8") as f:
    for n, line in enumerate(f, 1):
        rec = json.loads(line)
        h = rec.pop("hash")
        body = json.dumps(rec, sort_keys=True, ensure_ascii=False)
        if rec.get("prev") != prev or hashlib.sha256(body.encode()).hexdigest() != h:
            sys.exit(f"哈希链在第 {n} 行断开")
        prev = h
print("哈希链完整")
```

**检查方法：**在日志未被改动时运行 `python3 verify_chain.py`，应该看到“哈希链完整”。然后手动改掉第五行的一个字符再运行一次，脚本应准确报告哈希链在第 5 行断开。如果整行删除，下一行的 `prev` 字段对不上，脚本同样会在那里停下。

## 第 5 步：权限扩大时也要记录

危险操作往往伴随着申请更多权限。MCP 建议记录权限范围提升（scope elevation）事件，包括申请的范围和实际授予的范围，并附上关联 ID。同一份文档还提醒，捆绑过宽的权限范围会让审计轨迹充满噪声，掩盖用户的真实意图。

权限授予和随后的工具调用使用同一个关联 ID。调查时就能读出完整经过：用户要求了什么，智能体申请了哪些权限，实际授予到什么程度，智能体又用这些权限做了什么。

## 常见错误

最常见的错误是只记录 `sub`、不记录 `act`，结果智能体的每个操作看起来都像用户亲手做的。第二个错误是“为了方便调试”打开完整的提示词日志，让日志变成不受控的 PII 仓库。

第三个错误是把日志放在智能体所在的机器上，而智能体又有文件写权限，于是智能体自己就能改自己的日志。

如果想接入现有的可观测性体系，OpenTelemetry GenAI 约定定义了 `invoke_agent` 操作和一个智能体标识属性。沿用这些约定的字段名，客户的运维团队不用你解释就能读懂日志。

## 这项技能在实际工作中何时用得上？

设想客户的安全团队问你：出了事故之后，你打算怎么追溯智能体的操作？

如果你能在会上当场打开四问日志结构、讲清 `act` 链、运行篡改检测脚本，对话就会进入细节，而不是停留在一句承诺上。

一个只会说“我们有日志”的前线部署工程师（FDE），其实什么也没回答。

看 FDE 岗位描述时，留意“enterprise security review”“compliance”“agent governance”这类说法。简历上别写“做过日志”，要写你按 RFC 8693 设计了区分用户和智能体的审计轨迹，并可通过哈希链校验完整性；招聘方进一步追问时，把日志文件拿出来给他看。

交给智能体的工作越多，“这是谁干的？”这个问题就会被问得越频繁。最有说服力的回答，是一份在事故发生前就已存放在只读存储里的日志文件。

**本周动手试试:**

- 在 Claude Code 测试项目中安装本文的审计 hook，执行 10 次工具调用，然后手动修改一行日志，运行 verify_chain.py，看它报错
- 取一个智能体调用 API 时使用的令牌，解码后查看 sub 是谁，以及旁边是否有 act 声明
- 针对日志写一个查询，回答：过去 24 小时内，哪个智能体代表用户 X 调用了写数据的工具？

## 信源

- [Logging - OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)

- [OAuth 2.0 Token Exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693.html)

- [Security Best Practices - Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices)

- [Hooks reference - Claude Code Docs](https://code.claude.com/docs/en/hooks)

- [Semantic Conventions for GenAI agent and framework spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md)
