前九篇把 Agent 的能力一路加满:会调工具、会记东西、会规划、会组队、能接外部服务。能力越强,风险越大——第 9 篇接上 MCP 之后,一个「调用外部服务」的动作背后可能是任意第三方系统;再往后,第 12 篇要做持久化、第 13 篇要上线,Agent 就真的要碰到真实数据了。
但到目前为止,所有工具都是「能调就调」。第 8 篇的角色白名单算第一次隔离,可它的粒度只到工具名:给不给 writeFile,不给「写哪个文件、写什么内容」。本篇要补上的是参数级的权限,以及权限之外的两件事——沙箱(工具物理上够不到的地方)与人工介入(策略定不了的个案)。
本篇产出的源码分布:
src/sandbox/
├─ types.ts 权限词汇表:决策三态 · 规则 · 策略 · 审批器 · 审计事件
├─ rules.ts 参数级规则 DSL:路径取值 + 匹配器 + 组合子
├─ policy.ts 策略引擎:顺序求值、默认拒绝、多策略合并
├─ paths.ts 路径沙箱:根目录 / 扩展名 / 大小 / 符号链接四道边界
├─ approver.ts 人工审批器:终端交互、超时、异常,全部按拒绝兜底
├─ audit.ts 审计日志:内存与 JSONL 文件两种实现
├─ defaults.ts 默认文件沙箱(data/ 目录 + 文本类扩展名)
├─ presets.ts 默认权限策略(10 条参数级规则)
└─ guard.ts ToolGuard:策略 → 审批 → 执行 → 审计,一条流水线
src/tools/
└─ dangerous.ts 高风险工具:writeFile / deleteFile / runCommand(自带硬边界)
新增 1493 行源码、638 行测试,测试总数从 94 涨到 151。
01 权限模型:两态不够用
最直觉的权限模型只有两个状态:允许、拒绝。但真实系统里有一大类操作既不该自动放行、也不该一票否决——写一个文件到 data/summary.txt 是吗?删一个文件呢?执行一条 git status?
这些操作需要有人看一眼再定。所以本篇的第一件事是把决策从两态扩成三态:
| 决策 | 含义 | 典型场景 |
|---|---|---|
allow |
直接执行 | 读沙箱内的资料、算数、抓白名单域名 |
ask |
交给人裁决 | 写文件、删文件、执行外部命令 |
deny |
直接拒绝 | 疑似凭据文件、越出沙箱、未知工具 |
参数级:为什么工具名级不够
工具名级的规则形如「writeFile 不给」。问题是同一个工具、不同参数,风险差着几个数量级:
writeFile({path: "notes.txt", content: "三行摘要"})
writeFile({path: "src/index.ts", content: "..."})
deleteFile({path: "old.txt"})
readFile({path: "notes.txt"})
readFile({path: "../.env"})
所以判定必须看参数值。本篇的请求对象长这样:
export interface PermissionRequest {
tool: string; // 被调用的工具名
args: Record<string, unknown>; // 已通过参数校验的参数
source?: string; // 调用来源(角色名、Agent 名)
}
args 进来之前已经过了 Zod / JSON Schema 校验——参数不合法就不该去打扰人审批,人只该为「格式正确但有风险」的调用买单。这一点决定了注册表里校验与授权的先后顺序(见第 06 节)。
02 规则 DSL:把策略写成代码
参数级规则如果用字符串表达式写(「tool == 'writeFile' && path.startsWith('src/')」),就要自己发明一套解析器、错误处理与转义规则。写成代码则直接受益于 TypeScript:类型检查、组合子、可单测。
先看取参数。路径支持点号与数组下标:
export function getArg(args: Record<string, unknown>, path: string): unknown {
// "nested.a.b" / "list[1].x" / "path"
// 路径不存在返回 undefined,不抛错
}
路径不存在返回 undefined 而不是抛错,是因为参数级规则经常要处理可选参数——webFetch 的 maxChars 可能没有,writeFile 的 append 可能没有。
匹配器是一组 (req) => boolean 的纯函数:
toolIs("readFile") // 工具名精确匹配
toolStartsWith("mcp__") // 工具名前缀匹配
argEquals("mode", "fast") // 参数等于
argIn("mode", ["fast", "safe"]) // 参数属于集合
argMatches("path", /\.txt$/) // 参数匹配正则
argStartsWith("path", "src/") // 参数前缀
argUrlHostIn("url", ["example.com"]) // URL 主机名白名单(支持子域)
argPathWithin("path", sandbox) // 参数是沙箱内的路径
组合子负责把匹配器拼成条件:
allOf(isReadTool, insideSandbox) // 与
anyOf(toolIs("a"), toolIs("b")) // 或
not(isReadTool) // 非
规则构造器给出「条件 + 决策」的组合:
denyRule(
"deny-secret-file",
"读取疑似凭据/密钥的文件一律拒绝",
allOf(isReadTool, looksSecret),
"该路径疑似包含密钥或凭据,禁止读取",
);
一个值得单独说的细节是匹配器抛异常时的处理。规则求值必须永远不炸:某条规则写错了(比如正则非法),正确行为是「这条规则不生效」,而不是「整个授权流程崩溃」。真要崩了,攻击者只要构造一个能触发规则异常的参数,就能拿到执行权。所以匹配器调用统一包了一层:
function safeMatch(matcher, req) {
try { return matcher(req); } catch { return false; }
}
默认策略长什么样
预设策略 defaultSandboxPolicy() 给出 10 条规则,顺序求值、第一条命中即生效:
| # | 规则 id | 决策 | 条件 |
|---|---|---|---|
| 1 | deny-secret-file |
deny | 读疑似凭据的文件(.env、*.pem、id_rsa…) |
| 2 | deny-outside-sandbox |
deny | 路径越出沙箱 |
| 3 | allow-read-in-sandbox |
allow | 只读工具且路径在沙箱内 |
| 4 | allow-calculator |
allow | 算数 |
| 5 | allow-fetch-known-host |
allow | webFetch 命中域名白名单 |
| 6 | ask-fetch-unknown-host |
ask | 其他域名 |
| 7 | ask-write-file |
ask | 写文件 |
| 8 | ask-delete-file |
ask | 删文件 |
| 9 | ask-run-command |
ask | 执行命令 |
| 10 | ask-write-source-code |
ask | 写 src/ 下的代码文件 |
规则 1 值得注意:读疑似凭据的文件是直接拒绝,连问都不问。问了人也没有用——那种文件本来就不该进上下文。
03 策略引擎:顺序求值 + 默认拒绝
引擎本身很短,短到全文可以贴出来:
evaluate(req: PermissionRequest): PermissionDecision {
for (const r of this.rules) {
let hit = false;
try {
hit = r.when(req);
} catch (err) {
this.onRuleError?.(r.id, err); // 规则有问题:跳过并告警
continue; // 关键:绝不因为异常而放行
}
if (hit) {
return { decision: r.decision, reason: r.reason ?? r.description, ruleId: r.id };
}
}
return { decision: this.defaultDecision, reason: this.defaultReason, ruleId: `${this.name}:default` };
}
三条设计原则:
多策略合并:红线不可被局部覆盖
真实系统里策略不止一套:组织级红线一套、当前角色的授权范围一套。合并方式不能是「后一套覆盖前一套」,而应该是取最严:
export function strictestOf(policies: Policy[], name = "strictest"): Policy {
const rank = { allow: 0, ask: 1, deny: 2 };
// 取 rank 最大者;某层策略求值异常 → 该层按 deny 计
}
于是「全局策略说 deny,角色策略说 allow」的结果是 deny。这一层还有个隐含收益:任何一层策略崩了,整体按拒绝处理,而不是因为下游故障放行。
04 人工介入:审批器的三个现实问题
ask 的处理看起来简单,实际有三个必须处理的现实问题。
第一,超时。 人可能不在线。超时必须按拒绝处理:
const result = await Promise.race([
this.approver.approve({ ...req, proposed }),
new Promise<ApprovalResult>((resolve) => {
timer = setTimeout(() => resolve({ approved: false, reason: "审批超时" }), this.approvalTimeoutMs);
}),
]);
第二,非交互环境。 CI、管道、后台任务里没有 TTY,此时 readline.question 要么永远挂着、要么读到 EOF 立刻返回空串。终端审批器显式检查 isTTY,非交互时直接拒绝而不是傻等:
if (!(this.input as NodeJS.ReadStream).isTTY) {
return { approved: false, reason: "当前不是交互式终端,无法进行人工审批,按拒绝处理" };
}
第三,审批器自己坏了。 审批器抛异常时按拒绝处理,并在理由里写明是审批系统的问题。
三条合起来就是本篇反复出现的那句话:拿不到明确同意,一律视为没同意。
审批器是可替换的接口,本篇给出五种实现:
| 实现 | 用途 |
|---|---|
ConsoleApprover |
终端交互(y/N + 超时),提示写 stderr,不污染 stdout |
CallbackApprover |
包装任意回调,接 IM / 网页 / 工单系统 |
SequenceApprover |
按预设序列返回结果,演示与测试用 |
StaticApprover |
固定结果 |
DenyAllApprover |
一律拒绝,等效于「没有审批人」 |
审批提示写 stderr 而不是 stdout 是个小决定,但影响可读性:Agent 的正常输出走 stdout,审批提示混进去会让「程序输出」和「人在说话」糊成一片。
05 沙箱:工具自带的硬边界
策略是软门禁,配置本身可能有 bug,也可能有内部人员忘了写规则。沙箱是围栏,写在工具内部,不随策略配置而放松。
本篇把第 4 篇散落在各工具里的路径检查抽成一个可配置的 PathSandbox,管四道边界:
new PathSandbox({
roots: [DATA_ROOT], // ① 根目录
allowedExtensions: [".txt", ".md", ".json", ".csv"], // ② 扩展名白名单
maxBytes: 1024 * 1024, // ③ 文件大小上限
followSymlinks: true, // ④ 解析符号链接
});
第 ④ 条值得单说。不解析软链的话,一个指向沙箱外的软链就能绕过前缀检查——路径字符串看着在 data/ 里,真实路径却在别处。本篇的解法是「向上找最近的存在祖先」再取真实路径,这样既能解析软链,也能对尚未创建的新文件(写入场景)给出正确判定:
private resolveSymlinks(target: string): string {
let current = target;
const tail: string[] = [];
for (let i = 0; i < 64; i++) {
try {
const real = realpathSync(current);
return tail.length ? resolve(real, ...tail) : real;
} catch {
const parent = resolve(current, "..");
if (parent === current) return target;
tail.unshift(current.slice(parent.length + 1));
current = parent;
}
}
return target;
}
第 ② 条同样重要:数据目录只放文本资料,二进制文件一律不许碰。扩展名白名单把「顺手写个可执行文件」这类风险挡在落盘之前。
一个必须统一的口径:相对路径以哪里为基准
这是本篇踩到的真坑。第 4 篇里 readFile 的路径相对 data/ 解析,searchFiles 的 root 却相对当前工作目录解析。两者混在一起会出真问题:
策略层判定「root = "data" 在沙箱内」(按 cwd 解析 → /data ✓),
工具实际访问的却是 /data(按 DATA_ROOT 解析 → /data/data)——
判定结论和实际访问路径不是同一个。
这类错位在真实系统里就是漏洞:策略说「在沙箱内」,工具却读到了沙箱外的文件。本篇的解法是把语义统一成一律相对沙箱根目录,并把检查收进 PathSandbox 一处。改完之后,readFile、searchFiles、writeFile、deleteFile 四个工具的路径语义完全一致,策略层与工具层看到的也是同一个路径。
代价是模型需要知道这个约定。第一版演示里模型写了 data/summary.txt,被解析成 data/data/summary.txt 而失败;把约定写进系统提示(「本地文件路径都相对 data/ 目录,例如 summary.txt」)之后,模型一次就写对了。
runCommand:两条硬限制
执行外部命令是风险最高的工具,本篇给它加了两条限制:
; rm -rf ...
..
const child = spawn(program, args.args ?? [], { cwd: process.cwd(), shell: false, stdio: [...] });
顺带一提:删文件工具刻意不支持目录删除。递归删目录的破坏力与一次手滑的距离太近,真有清理需求也应该逐文件删。
06 审计:事后能说清
沙箱解决「事前不让他做」,审计解决「事后说得清」。没有审计的权限系统一旦出事,只能靠猜。
本篇的审计事件记录四样东西:决策、命中规则、审批人、最终结果。最后一项容易被忽略:
decision=allow, outcome=executed 批准了,且执行成功
decision=allow, outcome=error 批准了,但执行失败
decision=deny, outcome=denied 策略拒绝
decision=deny, outcome=rejected 人工驳回
「批准了但执行失败」和「批准了且执行成功」在审计上必须可区分——前者意味着问题在工具侧,后者意味着这次授权确实产生了预期效果。
审计用 JSONL 追加写入,只追加、不修改、不删除。写入失败的处理有个取舍:写盘失败要报到 stderr,但不能因此让正常的工具调用跟着失败。否则攻击者只要把磁盘写满,就能让整个沙箱失效(拒绝服务)。折中做法是记录到 stderr,保证有痕迹,但不让业务停摆。