FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • OWASP 要求每条日志都回答何时、何地、何人、何事。到了智能体场景,“何人”包含两部分:用户,以及代其执行的智能体。
  • RFC 8693 下的委托会保留智能体自身的身份,冒充则抹掉了这条界线。MCP 中的令牌透传同样会让日志记错身份。
  • 模型产生的工具输入和输出都是不可信文本。记录前先做清洗,内容只在显式开启时才记录,并加上篡改检测。
两条审计日志记录的对比。改进前:只有存放用户的 sub 字段,没有 act 字段,智能体的操作看起来像用户亲手所为。改进后:on_behalf_of 存放用户,actor 存放智能体(高亮显示),actor_chain 列出之前的智能体,智能体保留了自己的身份。
日志若只记录 sub,智能体的每个操作看起来都像用户做的。加上 actor 和 actor_chain,日志才能回答到底是谁干的。来源:RFC 8693(OAuth 2.0 Token Exchange),见文中引用。

设想这样一个场景:客户的客服智能体刚刚关闭了 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 设计了区分用户和智能体的审计轨迹,并可通过哈希链校验完整性;招聘方进一步追问时,把日志文件拿出来给他看。

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

这篇文章对你有帮助吗?

5 个信源
路线图上的下一篇 · 阶段 6: 价值度量64 处改动拖垮客户 Agent,六轮评测揪出元凶git bisect 早已负责二分查找,真正的功夫在于设一个能容忍 LLM 噪声的评测阈值。