Agent Harness 工程(I5):权限与沙箱——让否决改变控制流

一、失败现场

一个仓库巡检 agent 接到任务:读 notes 目录,把包含 TODO 的文件摘要写到 report.md;清理过期草稿时调用删除;需要读取评论时调用一个示例 issue API。工具表里有 read_file、list_dir、write_file、delete_file、run_command,以及一个声明了 API_TOKEN 的 call_api。演示时一切正常,一旦把模型换成会试探边界的对手,五种现场会同时出现。

  1. deny 只写日志。 策略函数返回 deny,日志里也写了 deny,但执行路径没有分支:if decision == Decision.DENY: logger.warning(...) 之后仍然调用 handler。事件流里能看到一条 policy_decision(decision=deny),transcript 里却是 delete_file 成功。对观察者来说,否决发生了;对外部世界来说,否决没有发生。
  2. 审批回调异常默认放行。 审批服务超时,代码想「不要因为审批服务挂了就阻塞任务」,于是 except Exception: approved = True。更隐蔽的写法是 approval = approver(request),然后 if approval:;回调返回 None 或一个非 Approval 对象时,真值判断把「没有答案」读成了「可以放行」。审批的价值在于它能把不确定变成拒绝;把异常变成放行,等于把最需要审查的那条路径交给了最不可靠的组件。
  3. ../ 越界。 os.path.join(root, "../../etc/passwd") 会把路径拼到工作区外;os.path.join(root, "/etc/passwd") 更直接,因为绝对路径会丢弃前面的 root。还有一种不带 .. 的逃逸:工作区里有一个 link -> /etc 的符号链接,字符串检查看不出问题,resolve() 之后目标已经在工作区外。
  4. 命令注入。 subprocess.run(command, shell=True) 把模型给出的字符串交给 shell。cat notes.txt; rm -rf . 里的分号会拆成两条命令;$(...)、反引号、换行、管道都能达到同样效果。即使过滤了分号,shell 的语法面仍然比想象中大。根因不是黑名单不够长,而是存在「字符串交给 shell」这个入口。
  5. 凭证与 PII 泄漏。 工具从环境变量读 API_TOKEN,又把 token 和评论里的邮箱一起返回;transcript 与检查点保存原文,tool_call 事件保存原始参数,审批界面也直接展示参数。脱敏只做在最终渲染层,秘密早已进入模型上下文、事件日志和磁盘。

示例脚本把这五种现场压缩成几段输出:

text 复制代码
0. 风险分级与可见性
  模型可见: ['read_file', 'list_dir', 'write_file']
  destructive 的 delete_file 可见: False
1. deny 改变控制流
  secret.txt: secret files are not readable
  泄漏 top secret: False
  public.txt: hello
2. 审批挂起与恢复
  第一次: suspended kind=approval tool=write_file risk=write
  文件已写入: False
  恢复后: completed 内容=approved
  拒绝后: permission_denied 文件已写入=False
3. ../ 越界
  error=sandbox_violation violation=path_escape
  读到 outside secret: False
4. 命令注入
  分号被当作普通参数: 'hi; rm -rf .'
  允许列表外: sandbox_violation violation=executable_not_allowed
5. 凭证作用域与脱敏
  credential_accessed=API_TOKEN(事件里没有值)
  输出: {"body": "contact [REDACTED:email]", "token": "[REDACTED:api_key]", "value": "demo"}
  原文泄漏 secret: False
  redaction counts= {'email': 1, 'api_key': 1}
  未声明凭证: peek -> API_TOKEN (credential_denied)

五种现场的共同点不是「少写了一个 if」,而是判断与执行在五个交接点上断了线:策略算出 deny,执行器却继续调用 handler;审批回调没有给出确定答案,执行器把 None 当成放行;路径检查用的是解析前的字符串,文件操作又按原始路径拼一次;工具收到的是 argv,进程启动却把它交给 shell;凭证 broker 只发放 token,结果落盘时又把 token 当普通文本写回历史。每一次断裂都不是判断错了,而是判断没有被执行点接住。

图里的左列是知道事实的判断点,右列是实际做动作的执行点。它们并不平级:执行器出现两次,路径与文件同属 Workspace,命令与进程是 command_tool 加 SubprocessSandbox;I5 要做的,是把右列接到左列上。

本文的中心判断是:

否决不是策略函数的一个返回值,而是执行路径上的一个分支:拒绝结果要回到模型、写进历史、留下审计;放行则先要回答这个工具能碰到什么------工作区、子进程、凭证与输出,各有一条边界。

这一层要回答三个问题:

  • 哪些调用需要拦,拦的依据是什么,模型看到的工具列表和真正的否决权是什么关系?
  • ask 由谁回答,答案怎样接回一个已经挂起的 run,崩溃之后会不会重复问或重复做?
  • 放行之后,工具还能碰到什么------文件、子进程、凭证、输出,各要什么边界?

本文按四块展开:判断与可见性(2.1)、审批(2.2)、放行后的四条边界(2.3),最后和一个产品级参考实现对一遍口径(2.4)。实现、验证、迁移与边界在后四节。

理论篇《Agent Harness 工程》 的 2.4 节把安全护栏列为六类能力之一:以能力不可见与 fail-closed 审批保护不可逆操作;5.4 与 5.5 节进一步给出失败方向与"不给大于问"的取舍。本文把这些判断落成可执行的权限管线:默认最小权限、隐藏高危工具、无审批通道时拒绝,路径解析后再做相对性判断。《拆解 Claude Code 的 Harness》 的第 5 节记录了一条默认拒绝的权限管线,以及「权限决定 whether,沙箱决定 how far」的分工。实现篇导读 把 I5 的范围限定为风险分级、审批挂起、策略规则、工作区隔离、子进程沙箱、凭证作用域、PII 脱敏与审计事件。I1 已经让循环会停,I2 已经让工具结果可配对,I3 已经把上下文预算与完整记录分开,I4 已经让挂起与恢复有状态可接;I5 补的是这些判断在「拒绝」与「放行之后」两个方向上如何落到执行路径上。

二、设计

第二章只回答两个问题:这一次调用能不能发生;发生之后,工具还能走多远。前者是权限门,后者是四条边界。还是开头那个巡检 agent:读 TODO 是 read,写 report.md 是 write,删过期草稿是 destructive;默认分别放行、问人、拒绝。

2.1 先声明,再判断

权限不能从工具名猜。工具注册时用 ToolSpec 交代四件事:是否只读(read_only)、风险档位(risk)、是否幂等(idempotent)、需要哪些凭证(credentials)。risk 必须按真实副作用写:只读是 READ,写文件是 WRITE,起进程是 EXEC,不可逆是 DESTRUCTIVE。ToolSpec 的 risk 缺省是 READ,所以写工具漏写 risk 就会按只读放行。只读和写/执行/破坏性同时声明,注册层必须直接拒绝------否则标上只读就能把 ask 骗成 allow。

四档风险的默认值:

风险 默认决策 模型可见 一句话理由
read allow 是 不改外部状态,仍受工作区约束
write ask 是 有副作用,通常还能收拾
exec ask 否 起进程,副作用不可枚举,默认不摆到模型面前
destructive deny 否 不可逆,默认不把入口摆到模型面前

默认最小权限不是抽象原则,是对过度代理风险^1^的直接回应:工具越多、权限越大,一次错误提议的后果越难局部化。这张表只是缺省,PermissionPolicy.defaults 可以整体改,规则可以按工具覆盖。

规则只写默认值不够用的地方:工具名模式、可选参数谓词、决策、理由;带谓词的规则不能改可见性。匹配是首条命中,所以 deny 要写在通用 allow 前面。谓词抛异常、默认表里没有对应档位,一律按 deny 处理------判断写错不该变成放行。

可见性是另一条轴:它只决定模型看不看得见,不决定能不能执行。隐藏 exec 与 destructive 工具,是减少模型手滑的机会;模型如果点名调用隐藏工具,执行器照样找得到 spec,权限门照样判断。隐藏不是拒绝,否决权在权限门。

一次调用的顺序是:

text 复制代码
spec / JSON → schema → 幂等重放 → 权限门 → 凭证 → 执行 → 脱敏

schema 在权限前,是让谓词面对结构合法的参数;幂等重放在权限前,是让已经执行过的调用不再触发审批。重放只覆盖声明了 idempotent=True 的写工具,只读工具不缓存。拒绝会作为这条调用的 tool result 回到模型、写进历史,不否决同批其他调用;只有挂起会停下整批,因为它在等一个当前进程里没有的答案(见 2.2)。

2.2 ask 没有答案,就是 no

ask 不是第三种 allow,它是一条还没有答案的问题。答案只有三个来源:

场景 通道 结果
宿主有同步审批界面 approver 回调 立即问,拿返回值
要跨进程、跨重启 检查点 + 挂起 run 以 suspended 结束,宿主稍后 resume
两者都没有 无 直接拒绝

没有通道时必须 deny。把 ask 降级成 allow,等于把"没人能批"变成"默认批准";降级成阻塞等待,进程可能挂在一个永远不来的回答上。运行时会写一条 approval_resolved(approved=False, source="unavailable"),让日志能区分"人拒绝了"和"根本没人可问"。

同步回调的失败也一律拒绝。现实里的写法常是 except Exception: approved = True,审批服务一挂,最需要审查的路径反而默认放行;回调返回 None 或一个不认识的类型,也不能当成同意。

跨进程审批靠挂起。权限门在副作用之前抛出 ToolSuspended,检查点里留下待审批的调用;宿主之后 resume(run_id, "approve: ...")。恢复值认 approve / deny(以及 approved、allow、denied、reject 等别名)加可选理由,其余值在写检查点之前就报错,不留半截状态。

审批请求带 call_id、工具、风险、规则、理由和参数摘要;恢复时只核对 call_id 与工具名,不一致就报错。配置了脱敏器时,参数给人看的是脱敏副本;arguments_digest 始终按原始参数算,用来核对"人批准的那次调用"和"即将执行的那次调用"是不是同一份内容。摘要不是签名,证明不了审批人身份。

关键顺序只有一句:先把宿主的决定写进 RUNNING 检查点,再执行待审批的调用。 决定没落盘就崩溃,恢复后只能重新问人;执行完、结果没落盘就崩溃,恢复后会再执行一次。前者是安全的重复问,后者要靠下游幂等兜住。审批解决"谁允许",不解决"执行与记录之间的窗口"。

挂起和审批不能同时出现在一个检查点里:suspended 表示"还没有答案",running + approval 表示"答案有了,但调用还没完成"。混在一起,恢复逻辑就分不清该问人还是该执行。检查点版本因此升到 2,v1 直接拒绝。

2.3 放行之后,还有四条边界

权限门只回答"能不能调用"。调用开始之后,工具还能碰到四样东西:文件、进程、凭证、输出。四条边界各管一段:

边界 规则 仍然防不住
工作区 解析后的真实路径必须在 root 之下;..、绝对路径、符号链接逃逸都拒绝 子进程仍可按绝对路径读写;TOCTOU 仍存在
子进程 只收 argv 列表,不走 shell;可执行文件、环境、cwd、超时、rlimit 都收紧 允许的二进制仍能读它能读的文件
凭证 工具声明什么就只发什么;没声明就发空(配置 broker 时);声明了但缺 broker 直接拒绝 进程内 handler 仍可读 os.environ
输出 进入历史、缓存、审批界面前脱敏 没固定格式的秘密、编码后的秘密

工作区先拒绝路径,再谈读写。路径穿越常见四类^2^:..、绝对路径、符号链接逃逸、检查后替换最终组件。前两类在字符串阶段就能拒;第三类要 resolve() 之后再看 is_relative_to(root);第四类靠打开文件时的 O_NOFOLLOW,这类检查与使用之间的竞态就是 TOCTOU^3^。

写入用同目录临时文件加 os.replace,读者要么看到旧文件,要么看到新文件;接口语义以 Python os 文档为准^4^。读取只接受普通文件、UTF-8,读写都有大小上限;写入的父目录必须存在,也不能写到工作区根目录。工作区防的是手滑,不是防同机攻击者; 子进程和本地攻击者仍能绕过它。

子进程的第一条规则是不给 shell 。接口收 argv 列表,分号就只是 echo 的一个普通参数;sh 不在允许列表里,sh -c 在执行前就被拒绝。允许列表只放 cat、grep、sed 这类文本工具,sh、bash、python、rm 都不在;argv 最多 64 项、单项 8KB,stdout/stderr 各 64KB,默认超时 10 秒。

移除入口比过滤字符串可靠,这条在 Python subprocess 的安全说明里也是首要建议^5^。环境变量按白名单重建,LD_PRELOAD、PYTHONPATH 不在其中,子进程收不到;PATH 固定为 os.defpath,不从宿主继承。进程用新会话启动,超时杀整个进程组;资源上限用 RLIMIT_* 设置^6^,是尽力而为的第二道闸。这仍然是进程级护栏:允许列表里的 cat 照样能读 /etc/passwd。

凭证与 PII 泄漏属于敏感信息暴露风险^7^。第一道边界不是脱敏,是根本不发给不需要它的工具 。call_api 声明了 API_TOKEN,read_file 没声明,就只能拿到空 scope;get("OTHER_TOKEN") 直接拒绝,不会回落到全局环境变量。每次读取和拒绝都留事件,事件里只有凭证名,没有值。

输出在进入历史、重放缓存、审批界面之前脱敏;默认覆盖私钥、API key、GitHub token、AWS key、Bearer token、邮箱、手机号。它不覆盖模型输出、用户输入、transcript 里的原始参数和 model_response / tool_call 事件------这些是审计底稿,在底稿上做不可逆替换,审计就没法核对了。代价是:秘密一旦进了这些位置,脱敏追不回来。脱敏是减少泄漏面,不是把秘密擦掉。

2.4 和 Claude Code 对一遍

《拆解 Claude Code 的 Harness》 第 5 节的权限管线大致是:deny 规则 → 工具自身检查 → 安全检查 → 权限模式 → allow 规则 → ask。有两点值得借鉴:安全检查不能被"自动放行"绕过;沙箱放在进程启动点,权限决定 whether,沙箱决定 how far。

本文的实现更小:默认 READ allow、WRITE ask、EXEC ask、DESTRUCTIVE deny,模型默认只看见 READ/WRITE;工作区和沙箱检查放在工具内部,ALLOW 也不能让 ../ 成功;沙箱只到进程级,没有操作系统级 seatbelt / bwrap。

差异里最值得记住的不是规则顺序,而是这句:参考实现敢在某些模式下自动放行,是因为它同时在进程启动点放了真正的操作系统沙箱;只抄"自动放行"不抄沙箱,得到的是一个更快的漏洞。 本文的沙箱不完整,所以写操作保持 ask,破坏性保持 deny,不用"反正有沙箱"来为宽松默认辩护。

三、实现

本文代码在 nano-harness,对应模块 src/nano_harness/policy/。

src/nano_harness/policy/ 按职责拆成几个文件:

text 复制代码
src/nano_harness/policy/
├── policy.py       # PermissionPolicy、PolicyRule、PermissionGate
├── approval.py     # Approval、ApprovalRequest、参数摘要与恢复值
├── workspace.py    # 工作区路径、读写、删除、原子替换
├── sandbox.py      # 子进程 argv、环境、输出上限、rlimit
├── credentials.py  # CredentialBroker、ScopedCredentials
├── redaction.py    # 默认模式与递归脱敏
└── types.py        # Decision、RiskLevel 重导出

接线点在 src/nano_harness/tools/executor.py、src/nano_harness/loop.py 与 src/nano_harness/lifecycle.py。下面只挑决定行为的片段。

3.1 策略与可见性

PermissionPolicy.decide 是首匹配规则加默认决策:

python 复制代码
def decide(self, spec, arguments):
    risk = spec.risk
    arguments = arguments or {}
    for rule in self.rules:
        if not rule.matches_tool(spec.name):
            continue
        try:
            matched = rule.matches_arguments(arguments)
        except Exception as exc:
            return PolicyDecision(
                Decision.DENY,
                risk,
                f"rule {rule.name} failed: {type(exc).__name__}",
                rule.name,
            )
        if matched:
            return PolicyDecision(
                rule.decision,
                risk,
                rule.reason or f"matched rule {rule.name}",
                rule.name,
            )
    return PolicyDecision(
        self.defaults.get(risk, Decision.DENY),
        risk,
        f"default for {risk.value} risk",
        None,
    )

谓词异常在循环里被转成 DENY,异常消息不进入理由;未知风险用 self.defaults.get(risk, Decision.DENY) 兜底。PolicyRule.matches_tool 用 fnmatch.fnmatchcase 匹配完整名字,matches_arguments 在没有 when 时直接返回 True。

可见性单独走一条路径:

python 复制代码
def visible(self, specs):
    visible = []
    for spec in specs:
        exposed = None
        for rule in self.rules:
            if (
                rule.when is None
                and rule.expose is not None
                and rule.matches_tool(spec.name)
            ):
                exposed = rule.expose
                break
        if exposed is None:
            exposed = spec.risk in self.visible_risks
        if exposed:
            visible.append(spec)
    return tuple(visible)

只有 when is None 的规则才能设置 expose;带参数的规则不参与可见性。默认可见集合是 {READ, WRITE},所以 run_command 与 delete_file 不进模型工具列表。执行器仍然保留全部 spec,模型如果直接点名调用隐藏工具,权限门照常判断。

3.2 审批门与恢复

PermissionGate.check 先看恢复时预加载的审批决定,再走策略。预加载的决定来自 resolve,只核对 call_id 与 tool;不一致直接抛 ValueError:

python 复制代码
approved = self._approvals.get(call.id)
if approved is not None:
    if approved.call_id and approved.call_id != call.id:
        raise ValueError("approval call_id does not match the pending call")
    if approved.tool and approved.tool != spec.name:
        raise ValueError("approval tool does not match the pending call")
    return None if approved.approved else _denied(...)

回调通道最重要的是 fail-closed:异常、None、非 Approval 返回值都转成拒绝,并写一条 approval_resolved:

python 复制代码
try:
    approval = self._approver(call, spec, arguments)
except Exception as exc:
    return Approval(False, f"approver failed: {type(exc).__name__}",
                    source="callback", by="callback",
                    call_id=call.id, tool=spec.name)
if not isinstance(approval, Approval):
    return Approval(False, "approver returned an unrecognized value", ...)

没有回调、但能挂起时,check 生成 ApprovalRequest,发 approval_requested,抛 ToolSuspended(kind="approval")。两者都没有时,发 approval_resolved(source="unavailable") 并拒绝。

挂起/恢复的关键落盘顺序在 LifecycleLoop.resume 里:先解析决定,写 RUNNING + approval 检查点,再执行待审批调用。

python 复制代码
approval = self._tools.resolve_approval(
    pending.id, value or "", tool=pending.name
)
self._save(
    run_id, RunStatus.RUNNING, messages, turns, usage,
    pending_call=pending, approval=approval,
)
# 之后才执行 pending

parse_resume_value 在写检查点之前运行,非法值直接抛 ValueError;写完 RUNNING + approval 检查点之后,执行器才拿到预加载的决定。执行结果落盘后,后续检查点不再携带 approval,避免一个已经完成的决定被下一次恢复重复使用。

检查点版本升到 2。Checkpoint.__post_init__ 要求 approval 只能出现在 RUNNING 状态,且 approval 必须带 pending call;from_dict 对 v1 直接抛 CheckpointError。这不是格式洁癖:v1 没有 approval 字段,接受它会让「答案已落盘但调用未执行」和「还没有答案」两种状态无法区分。

3.3 工作区

路径先做词法检查:

python 复制代码
def _candidate(self, relative):
    if not relative or not relative.strip():
        raise WorkspaceViolation("empty_path", "path must not be empty")
    if "\x00" in relative:
        raise WorkspaceViolation("nul_byte", "path must not contain NUL bytes")
    pure = PurePosixPath(relative)
    if pure.is_absolute():
        raise WorkspaceViolation("absolute_path", ...)
    if ".." in pure.parts:
        raise WorkspaceViolation("path_escape", ...)
    return self.root.joinpath(*pure.parts)

再做解析与相对性检查:

python 复制代码
def _resolve(self, relative, *, must_exist):
    candidate = self._candidate(relative)
    try:
        resolved = candidate.resolve(strict=must_exist)
    except FileNotFoundError as exc:
        raise FileMissing(f"{relative!r} does not exist") from exc
    if not resolved.is_relative_to(self.root):
        raise WorkspaceViolation("path_escape", ...)
    return resolved

_candidate 拒绝空路径、NUL、绝对路径与 ..;_resolve 用真实目标做 is_relative_to,覆盖符号链接逃逸。read_text 先用 _resolve 确认目标仍在工作区,再用 O_NOFOLLOW 打开候选路径;读取前检查普通文件与大小上限,解码按 UTF-8。write_text 与 delete 在最终组件是符号链接时拒绝;写入父目录必须存在,不能写工作区根目录,大小有上限。

原子写把临时文件、fsync 和 os.replace 放在同一个父目录下:

python 复制代码
dir_fd = os.open(parent, os.O_RDONLY | os.O_DIRECTORY)
temp_name = f".{name}.{os.getpid()}.{os.urandom(6).hex()}.tmp"
fd = os.open(temp_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=dir_fd)
try:
    # 写循环、os.fsync(fd)
    os.replace(temp_name, name, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
finally:
    # 清理临时文件、关闭 dir_fd

O_EXCL 避免复用已存在的临时名,dir_fd 让替换相对于已打开的父亲目录进行,fsync 保证内容在替换前落盘。目录项本身没有单独 fsync,所以掉电后 rename 是否保留取决于文件系统语义;这一层把「不会读到半截文件」做扎实,但没有承诺「掉电后一定看到新文件」。

3.4 子进程

run 在任何进程启动之前拒绝不合法形状:

python 复制代码
if isinstance(argv, (str, bytes)):
    raise SandboxViolation("shell_string", "argv must be a list of strings")
if not command:
    raise SandboxViolation("empty_argv", "argv must contain an executable")
if len(command) > self._policy.max_arguments:
    raise SandboxViolation("too_many_arguments", ...)
for item in command:
    if "\x00" in item:
        raise SandboxViolation("nul_byte", ...)
    if len(item.encode("utf-8")) > self._policy.max_argument_bytes:
        raise SandboxViolation("argument_too_large", ...)
if command[0] not in self._policy.allowed_executables:
    raise SandboxViolation("executable_not_allowed", ...)

通过之后用固定 PATH 解析可执行文件,环境只复制 allowlist,PATH 固定为 os.defpath,cwd 过工作区检查,然后用新会话启动:

python 复制代码
process = subprocess.Popen(
    [executable, *command[1:]],
    cwd=str(workdir),
    env=environment,
    stdin=subprocess.PIPE if stdin is not None else subprocess.DEVNULL,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    start_new_session=True,
    preexec_fn=self._limits(limit),
)

两个 reader 线程按 8KB 分块读 stdout/stderr,捕获对象在达到上限后继续排空但不再保存,最后把 [truncated] 标出来。超时路径 killpg(process.pid, SIGKILL) 杀整个进程组,然后抛 TimeoutError;非零退出则原样返回 SandboxResult。

_limits 把 RLIMIT_CPU 设为 ceil(timeout) + 1,并设置 RLIMIT_FSIZE、RLIMIT_NOFILE、RLIMIT_AS、RLIMIT_CORE。每个限制都先和自己的 soft/hard limit 取小,设置失败时静默跳过;这是「尽力而为」,不是「一定生效」。preexec_fn 在 fork 之后、exec 之前运行,在多线程宿主里有已知风险;生产宿主应把命令执行移到辅助进程或容器里。

3.5 凭证、脱敏与审计

凭证作用域的核心是一次复制,只复制被授予的名字:

python 复制代码
def scope(self, granted, *, on_access=None, on_denied=None):
    allowed = frozenset(granted)
    values = {
        name: value
        for name, value in self._values.items()
        if name in allowed
    }
    return ScopedCredentials(values, allowed, on_access, on_denied)

ScopedCredentials.get 先看名字是否在 allowed 里,再看值是否存在;两种失败都调用 on_denied 并抛 CredentialDenied。执行器给每个工具发的回调只把凭证名写进事件:

python 复制代码
def on_access(name):
    self._emit(CREDENTIAL_ACCESSED, turn, call_id=call.id,
               tool=spec.name, name=name)

def on_denied(name, reason):
    self._emit(CREDENTIAL_DENIED, turn, call_id=call.id,
               tool=spec.name, name=name, reason=reason)

如果工具没有声明凭证但宿主配置了 broker,执行器发放 scope(());这样未声明访问会走 on_denied,留下 credential_denied。如果工具声明了凭证但 broker 缺失或名字缺失,_scope_credentials 在 handler 之前发出拒绝事件并抛 CredentialDenied。

脱敏在成功结果进入缓存之前发生:

python 复制代码
content, redactions = self._invoke(
    spec, call.arguments, turn, attempts, key, call_id=call.id,
)
# _invoke 里对成功结果做 redactor(result),返回 (content, counts)

成功结果在 _invoke 里、错误在 _failed 里、审批参数与恢复理由在 PermissionGate 里脱敏。任一处配置了 Redactor 时生效,每次替换发 redaction_applied,只带模式名与次数。

审计事件的关键字段如下:

事件 关键字段 是否包含原始参数或秘密
policy_decision tool、decision、risk、rule、arguments_digest 否,只有参数摘要
approval_requested tool、risk、rule、arguments、arguments_digest 配置脱敏器时参数已替换
approval_resolved approved、reason、by、source 配置脱敏器时理由已替换
sandbox_denied violation、detail 不含原始参数;detail 可能含路径
credential_accessed name 否
credential_denied name、reason 否
redaction_applied counts 否

HarnessLoop 与 LifecycleLoop 会把 EventLog 绑定到执行器,执行器再转发给权限门;单独用 ToolExecutor 时,显式传 events 或调用 bind_events。

model_response 与 tool_call 仍然带原始参数,这是审计底稿的一部分;它们不经过脱敏。事件消费者如果只需要判断结果,应该只订阅 policy_decision 这类带摘要的事件;需要原始参数的审计,必须把接收端放在受控存储里。脱敏不是事件层的默认行为,而是结果、错误与审批界面的行为。

四、验证

测试环境是本机 .venv:Python 3.12.7、jsonschema 4.26.0、pytest 9.2.0。全量运行:

text 复制代码
$ .venv/bin/python -m pytest
...
188 passed, 1 skipped

I5 的用例已经并入当前测试集,不再按当时的文件拆分计数;直接相关的文件如下:

文件 用例数 覆盖
tests/test_policy.py 20 风险与可见性、规则、审批 fail-closed、请求字段与绑定、重放、工作区、sandbox、凭证、脱敏、事件
tests/test_lifecycle.py 12 检查点、挂起恢复、审批落盘、流式
tests/test_injection_defense.py 3 不可信边界、拒绝无副作用
tests/test_tools.py 8 schema、重试、幂等重放

失败现场与当前用例的对应关系:

失败现场 当前用例 断言
deny 只写日志 test_deny_rule_prevents_secret_read、test_destructive_tool_is_denied_before_handler、test_loop_records_denial_without_side_effect handler 未执行,模型收到 denied
审批异常默认放行 test_approver_failure_is_fail_closed、test_approver_unexpected_value_is_fail_closed 回调异常或返回值非法时工具不执行
../ 越界 test_workspace_escape_is_reported、test_workspace_limits_and_symlinks 越界返回 path_escape,符号链接被拒绝
命令注入 test_sandbox_rejects_shell_strings_and_disallowed_commands、test_sandbox_limits_env_and_exit 分号只是参数;sh 被允许列表拒绝;环境变量不泄漏
凭证与 PII 泄漏 test_credentials_are_scoped、test_executor_enforces_declared_credentials、test_redaction_patterns_and_executor、test_redaction_default_patterns、test_credential_and_redaction_events 事件只有凭证名;七类默认模式命中;输出与缓存不含原文
审批落盘 test_approval_request_fields_and_binding、test_approval_is_persisted_before_execution、test_running_checkpoint_carries_approval、test_v1_checkpoint_is_rejected 决定先落盘;v1 检查点拒绝

示例脚本的输出在上面已经给出,六个场景都从真实运行得到,不是手写预期。审批场景里第一次运行返回 suspended,文件不存在;approve 之后文件写入;另一次 deny 之后文件仍不存在。凭证场景里 credential_accessed 只带名字,输出里的邮箱与 token 被替换,未声明的 peek 得到 credential_denied。

测试全绿不等于护栏成立。至少还有四类东西没有被这些用例证明:

  • 脚本模型不能证明真实模型不会绕路。 测试里的模型是脚本化的,它只会发出预先写好的调用;真实模型可能在被拒绝后换一个工具、换一个路径,或者把敏感内容放进下一轮参数。拒绝路径的测试只证明「这一条被拦住」,不证明「所有路径都被想到」。
  • 审批测试没有验证审批人身份。 回调里说 approved=True 的是测试代码;运行时只记录 by 字符串,不认证它。谁能调用 resume、谁有资格代表某个审批人,仍是宿主责任。
  • 工作区测试没有关闭 TOCTOU。 测试覆盖了静态的 ..、绝对路径、符号链接,但没有构造「检查后替换父目录」的并发竞态。O_NOFOLLOW 保护最终组件,父目录的竞态仍在。
  • 沙箱测试没有证明主机不可读。 测试验证了 argv、允许列表、环境、输出上限与超时,没有验证 cat /etc/passwd 会失败------因为它不会失败。沙箱是进程级护栏,不是文件系统或网络 jail。

这四条不是测试缺口,而是本层设计边界在测试上的投影。把它们写成「已知未覆盖」,比用「188 passed」暗示「权限已经安全」更诚实。

五、迁移

从 I1--I4 迁移过来,需要关注的配置与默认值如下。除第一行外,下表描述的是给 ToolExecutor 配上 PermissionGate 之后的行为;保持 gate=None 时,权限判断不会发生。

改动 缺省行为 影响 迁移动作
ToolExecutor.gate None 不配置就不走权限门,保持 I1--I4 行为 生产环境传入 PermissionGate(PermissionPolicy())
ToolSpec.risk 缺省 READ;写/执行/破坏性必须显式声明 写工具漏写风险会按只读放行 写工具补 WRITE,起进程补 EXEC,不可逆补 DESTRUCTIVE
可见性 READ/WRITE 可见,EXEC/DESTRUCTIVE 隐藏 run_command、delete_file 从模型列表消失 确实需要时加 expose=True 的规则
审批通道 无回调、无检查点时为 deny 原来能直接跑的写工具会失败 配置 approver 或启用检查点
检查点版本 2 v1 检查点被拒绝 让旧 run 在旧版本收尾,或丢弃未完成 run
credentials 不配置 broker 时,声明凭证的工具被拒绝 API 工具不可用 配置 CredentialBroker 与缺失的凭证
redactor None 不脱敏 建议默认开启,按数据形态补模式
工具声明 idempotent=False 崩溃后不自动重放 确有幂等语义的写工具显式声明

gate=None 是兼容默认,不是安全默认。它的作用是让前四篇的示例与测试在原配置下继续运行;安全默认应由宿主显式选择。PermissionPolicy() 自身的默认值是 READ allow、WRITE ask、EXEC ask、DESTRUCTIVE deny,可见集合默认只有 READ/WRITE;这个默认值才是本文推荐的起点。

检查点版本升到 2 后,v1 会被拒绝,而不是尝试迁移。原因写在 3.2:v1 没有 approval 字段,无法区分「答案已落盘」和「还没有答案」;与其猜,不如让旧 run 在旧版本收尾。这是一个教学项目的选择,生产系统如果必须兼容旧检查点,需要自己定义迁移与回滚策略。

还有两个容易忽略的兼容点。第一,恢复不重新评估策略:挂起时记下的是「这个调用需要审批」,resume 只解析恢复值并执行,不会拿当前策略再判一次;如果宿主在挂起期间换掉了 gate 或策略,批准的调用仍会按旧调用的参数执行,也不会再产生 policy_decision 事件。挂起期间应保持执行器配置不变。第二,审批挂起只有在启用检查点时才会发生;没有检查点的宿主必须提供同步回调,否则 ask 会直接变成 deny。这两条都应该在宿主启动时检查,而不是等到第一次写操作失败才发现。

六、边界

本文交付的是一层可演示、可测试的权限与隔离,不是生产级安全边界。下面这些限制会直接影响结论的适用范围:

这里做到的 这里做不到 生产环境的替代
工作区文件路径隔离 子进程仍可访问绝对路径 容器、chroot、OS 级文件系统沙箱
argv 与可执行文件允许列表 允许的二进制仍可读它能读的文件 seccomp、只读挂载、最小镜像
进程级 rlimit 与超时 不是 cgroup,资源统计与隔离有限 cgroup v2、容器运行时
审批回调与恢复值 审批人身份认证、四眼原则 宿主 IAM、工单、签名审批
凭证作用域 进程内 handler 仍可读 os.environ 子进程隔离、短时凭证、外部 secret manager
模式化脱敏 未匹配的秘密、编码后的秘密 数据分类、DLP、最小化收集
审计事件回调 不可篡改存储、留存与访问控制 外部审计日志、WORM 存储

其余边界按影响排序:

  • 不是操作系统沙箱。 没有 namespace、seccomp、文件系统挂载或网络策略。允许列表里的命令仍然能读进程有权限读的绝对路径,能访问的环境取决于宿主;read_only 只作用于工作区里的文件工具,不约束子进程。要对抗恶意多租户,必须使用 OS 或容器级隔离。
  • 不是网络边界。 没有出站白名单、DNS 控制或流量审计。一个被允许的进程能建立什么连接,取决于操作系统与网络配置;凭证作用域只限制「工具从 broker 拿什么」,不限制「进程能往哪里发」。
  • TOCTOU 仍存在。 路径检查与打开之间、父目录检查与临时文件创建之间,都有竞态窗口;O_NOFOLLOW 只覆盖最终组件。CWE-367 描述的就是这类问题^3^。同一台机器上的本地攻击者仍可能利用它。
  • 审批身份不由运行时认证。 Approval.by 是字符串,resume 的 host 也是字符串;运行时不知道谁在调用。把审批接到真实的人或系统,需要宿主层的认证、授权与审计。
  • 隐藏不是禁止。 可见性只影响模型看到的工具列表;模型可以点名调用隐藏工具,权限门仍会判断。隐藏降低尝试概率,不构成安全边界。
  • 策略谓词是代码。 谓词可以写错、可以有意放行、可以依赖外部状态;异常会 fail-closed,但错误的 True 不会被运行时发现。策略需要测试与审查,不能当作形式化证明。
  • 重放不重新看策略。 已执行调用的幂等重放按调用身份返回缓存结果;如果策略在两次调用之间收紧,重放仍会成功。这是「已发生事实」与「当前策略」的取舍,宿主需要在策略变更时决定是否作废旧 run。
  • 凭证只在 broker API 上生效。 进程内 handler 仍可以直接 os.environ["API_TOKEN"],也可以读文件、读配置;作用域约束的是「通过 ScopedCredentials 的访问」,不是「进程能读到的所有字节」。真正的隔离要把工具放到独立进程或独立凭证域。
  • 脱敏是模式匹配。 没有固定格式的秘密不会被识别,编码后的秘密不会被识别,正常文本可能被误伤;它不覆盖模型输出、用户输入、transcript 参数与 model_response / tool_call 事件。秘密一旦进入这些位置,就不能靠脱敏追回。
  • 审计不是不可篡改日志。 事件通过回调交给宿主,运行时不做签名、链式哈希、留存或访问控制;tool_call 与 model_response 还带原始参数。审计接收端必须被当作敏感系统来保护。
  • 平台限制。 resource 与 preexec_fn 是 Unix 取向;Windows 上这套实现不能直接运行。多线程宿主里 preexec_fn 有风险,应把命令执行移到辅助进程或容器。没有租约与 fencing token 时,两个消费者仍可能同时恢复同一个 run。
  • 不在本层范围。 多租户、认证、配额、限流、成本控制、生产级沙箱、提示注入的内容定界都不在这里。提示注入影响的是「模型会不会被工具输出说服」,属于 I9 的装配与不可信内容边界;本文只处理「模型提议的调用能不能执行、执行时能碰到什么」。

把边界收在一起,本文能保证的是:一次被权限门拒绝的调用不会产生副作用,拒绝结果会回到模型并留下审计;一次被放行的调用仍然受工作区、子进程、凭证与输出四条边界的约束。 它不能保证的是:模型不会找到另一条路,审批人一定是被授权的人,进程读不到它有权读的绝对路径,或者所有秘密都被模式识别出来。把这些说清楚,权限层才不是一层看起来很像安全的装饰。

术语

术语 说明
风险级别 工具声明的 read、write、exec、destructive 四档,决定默认决策与默认可见性
策略规则 工具名模式、可选参数谓词、决策与理由组成的首匹配规则
可见性 模型工具列表里是否出现某个工具,不等于该工具被允许调用
审批通道 把 ask 变成答案的路径:同步回调、检查点挂起/恢复,或不存在
挂起 run 以 suspended 结束,检查点留下待审批调用,等待 resume
恢复值 approve / deny 加可选理由,由宿主在 resume 时提供
工作区 文件工具可触碰的根目录;路径必须相对、解析后仍在根目录内
沙箱 这里指子进程的 argv、环境、cwd、超时与 rlimit 约束,不是 OS jail
凭证作用域 按工具声明发放的凭证视图,只暴露被授予的名字
脱敏 用模式替换结果、错误与审批文本中的敏感片段
审计事件 记录策略决定、审批、沙箱、凭证与脱敏动作的结构化事件

参考文档

Footnotes

  1. OWASP Top 10 for LLM Applications 2025:LLM06 Excessive Agency --- genai.owasp.org/llmrisk/llm... ↩

  2. OWASP Community:Path Traversal --- owasp.org/www-communi... ↩

  3. MITRE CWE-367:Time-of-check Time-of-use (TOCTOU) Race Condition --- cwe.mitre.org/data/defini... ↩ ↩2

  4. Python 文档:os --- 文件描述符、O_NOFOLLOW、dir_fd 与 os.replace --- docs.python.org/3/library/o... ↩

  5. Python 文档:subprocess --- Security Considerations --- docs.python.org/3/library/s... ↩

  6. Python 文档:resource --- Resource usage information --- docs.python.org/3/library/r... ↩

  7. OWASP Top 10 for LLM Applications 2025:LLM02 Sensitive Information Disclosure --- genai.owasp.org/llmrisk/llm... ↩

相关推荐
Baihai_IDP1 小时前
大模型 API 真的在赔本赚吆喝吗?聊聊 Token 背后的真实成本
人工智能·llm·aigc
谙弆悕博士1 小时前
多智能体架构详解:黑板共享架构(共享存储交互型)
人工智能·架构·大模型·agent·多智能体·黑板架构·anggraph
后端小肥肠2 小时前
公众号里流量很夯的漫画赛道:趣味漫画创作全拆解
人工智能·aigc·agent
lbk_runtime3 小时前
跨阶段分离:技评、编码、自测为什么分会场
agent
xyphf_和派孔明3 小时前
第六章: AI Agent长期记忆的存储引擎介绍
langchain·llm·agent
xyphf_和派孔明3 小时前
第四章: AI Agent短期记忆的信息管理机制设计
langchain·llm·agent
赵大仁3 小时前
Agent 工具调用可靠性:超时、重试、幂等与人工确认怎么设计
python·agent·幂等·工具调用·人工确认
阿里云云原生3 小时前
Velox 的 2026 年终总结:面向 Agent 的执行层演进!
agent
双鱼大猫3 小时前
opencode 吃掉 100G 空间:Agent 会话数据要分级清理
人工智能·agent·ai编程
学无止境小袁同学4 小时前
OpenAI Agents SDK 模板操作手册(可直接操作)
大模型·openai·agent·sdk·大模型应用