智能体出错时,审计日志却记在提问的人头上
按 RFC 8693 把触发用户和受托智能体分开记录,日志才能说清哪个工具用什么参数运行。
要点速览
- OWASP 要求每条日志都回答何时、何地、何人、何事。到了智能体场景,“何人”包含两部分:用户,以及代其执行的智能体。
- RFC 8693 下的委托会保留智能体自身的身份,冒充则抹掉了这条界线。MCP 中的令牌透传同样会让日志记错身份。
- 模型产生的工具输入和输出都是不可信文本。记录前先做清洗,内容只在显式开启时才记录,并加上篡改检测。
设想这样一个场景:客户的客服智能体刚刚关闭了 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 工具。下面的代码就基于这个模式。
#!/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 声明会层层嵌套成一条链。
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),因此只应在显式开启时记录内容。
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 建议内置一种机制,用来发现记录被修改或删除,并尽快把日志复制到只读存储。一个简单做法是哈希链:每一行都保存上一行的哈希。
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 完全相同的方式重新计算每个哈希。
#!/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 设计了区分用户和智能体的审计轨迹,并可通过哈希链校验完整性;招聘方进一步追问时,把日志文件拿出来给他看。
交给智能体的工作越多,“这是谁干的?”这个问题就会被问得越频繁。最有说服力的回答,是一份在事故发生前就已存放在只读存储里的日志文件。
这篇文章对你有帮助吗?
感谢你的反馈!