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

4 阅读12分钟

一、失败现场

一个仓库巡检 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 事件保存原始参数,审批界面也直接展示参数。脱敏只做在最终渲染层,秘密早已进入模型上下文、事件日志和磁盘。

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

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。

四档风险的默认值:

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

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

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

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

一次调用的顺序是:

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,这类检查与使用之间的竞态就是 TOCTOU3。

写入用同目录临时文件加 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/ 按职责拆成几个文件:

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 是首匹配规则加默认决策:

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。

可见性单独走一条路径:

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:

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:

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 检查点,再执行待审批调用。

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 工作区

路径先做词法检查:

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)

再做解析与相对性检查:

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 放在同一个父目录下:

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 在任何进程启动之前拒绝不合法形状:

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 过工作区检查,然后用新会话启动:

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 凭证、脱敏与审计

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

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。执行器给每个工具发的回调只把凭证名写进事件:

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。

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

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_decisiontool、decision、risk、rule、arguments_digest否,只有参数摘要
approval_requestedtool、risk、rule、arguments、arguments_digest配置脱敏器时参数已替换
approval_resolvedapproved、reason、by、source配置脱敏器时理由已替换
sandbox_deniedviolation、detail不含原始参数;detail 可能含路径
credential_accessedname否
credential_deniedname、reason否
redaction_appliedcounts否

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。全量运行:

$ .venv/bin/python -m pytest
...
188 passed, 1 skipped

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

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

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

失败现场当前用例断言
deny 只写日志test_deny_rule_prevents_secret_read、test_destructive_tool_is_denied_before_handler、test_loop_records_denial_without_side_effecthandler 未执行,模型收到 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.gateNone不配置就不走权限门,保持 I1–I4 行为生产环境传入 PermissionGate(PermissionPolicy())
ToolSpec.risk缺省 READ;写/执行/破坏性必须显式声明写工具漏写风险会按只读放行写工具补 WRITE,起进程补 EXEC,不可逆补 DESTRUCTIVE
可见性READ/WRITE 可见,EXEC/DESTRUCTIVE 隐藏run_command、delete_file 从模型列表消失确实需要时加 expose=True 的规则
审批通道无回调、无检查点时为 deny原来能直接跑的写工具会失败配置 approver 或启用检查点
检查点版本2v1 检查点被拒绝让旧 run 在旧版本收尾,或丢弃未完成 run
credentials不配置 broker 时,声明凭证的工具被拒绝API 工具不可用配置 CredentialBroker 与缺失的凭证
redactorNone不脱敏建议默认开启,按数据形态补模式
工具声明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… ↩