手搓AI Agent第10篇:参数级权限、沙箱隔离与人工介入

发布时间 2026-11-19
来源 博客园_首页
字数 6,838 字
查看原文 反馈

智能总结

该系列用 Node.js 22 和 TypeScript 从零构建通用工具型 Agent,第 10 篇为其加入可信边界:权限决策从允许/拒绝两态扩展为 allow、ask、deny 三态,并把规则细化到参数级;

同时设计路径沙箱(限制根目录、扩展名、大小和符号链接)与人工审批器,超时或异常一律按拒绝处理,所有决策 fail-closed。

前九篇把 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,保证有痕迹,但不让业务停摆。

正文超过 1 万字上限,本页为节选 · 查看原文