02 Tool System → MODULE 03 · PERMISSION SYSTEM

Permission System

Agent 的安全门 — 先设边界,再给自由

上一章我们给了 Agent 一双"万能手"(工具系统)。但一个能执行任何命令的 Agent,就像一个没有刹车的赛车——跑得快,但容易翻车。

权限系统就是 Agent 的刹车和安全气囊:在工具执行之前,先过三道安检。

向下滚动开始学习↓
01 · 核心概念

🚧 三道闸门权限系统

每个工具调用都要经过三道检查,就像机场安检一样层层把关。

类比:机场安检流程
你带着行李去坐飞机:
① 第一关:违禁品清单(炸药、刀具)→ 命中就直接没收,没得商量
② 第二关:X 光扫描(检查可疑物品)→ 发现可疑的拿出来细看
③ 第三关:人工开箱检查(需要你配合确认)→ 打开箱子给安检员看

Agent 的三道闸门完全一样:拒绝列表 → 规则匹配 → 用户审批

GATE 01

🚫 拒绝列表

永远禁止的操作。命中即拒绝,没有例外。

rm -rf / sudo shutdown mkfs
GATE 02

🔍 规则匹配

需要检查的操作。匹配规则后决定是询问还是拒绝。

写外部路径 删除文件 危险命令
GATE 03

👤 用户审批

需要你确认的操作。你可以选择允许或拒绝。

允许?(y/n)
核心思想:安全不能靠信任模型,要靠代码。LLM 可能被提示注入攻击诱导执行危险命令。权限系统在代码层面硬性拦截,不给模型"越狱"的机会。
02 · 决策流程

🚦 权限决策是怎么做的?

当 Agent 想执行一个工具时,权限系统会按顺序过三道关。

🔧
工具调用
→
🚫
拒绝列表?
→
🔍
规则匹配?
→
👤
用户审批?
→
✅
执行工具
权限结果含义后续动作
allow放行直接执行工具 ✅
deny拒绝返回错误信息 ❌
ask需要确认弹出提示问用户 ⏸️

🟢 命中拒绝列表

命令: sudo apt install xxx
→ 闸门1 检查:包含 "sudo"
→ 结果:DENY,直接拒绝

🟡 匹配规则 + 用户确认

命令: rm temp.txt
→ 闸门1:不在拒绝列表 ✅
→ 闸门2:匹配 CommandRule
→ 闸门3:ASK,问用户

03 · 代码详解

📝 PermissionPipeline 逐行拆解

权限管线是整个系统的核心。它实现了三道闸门的检查逻辑。

1 class PermissionPipeline:
📌 权限管线类,管理所有规则和拒绝模式。
2 def __init__(self):
3 self._rules = []
4 self._deny_patterns = [
5 "rm -rf /", "sudo", "shutdown",
6 "reboot", "mkfs", "dd if=", "> /dev/sda"
7 ]
🚫 拒绝列表:这些字符串一旦出现在命令中,就直接拒绝。没有商量余地。就像机场的"绝对禁止物品清单"。
8 def check(self, tool_name, tool_input) -> PermissionDecision:
⚡ 核心方法:接收工具名和参数,返回权限决策。
9 # 闸门 1: 拒绝列表
10 deny = self._check_deny_list(tool_name, tool_input)
11 if deny:
12 return PermissionDecision(result="DENY", reason=deny)
🚫 第一道闸门:检查命令是否包含禁止模式。命中 → 直接返回 DENY,后面都不用看了。
13 # 闸门 2: 规则匹配
14 for rule in self._rules:
15 if rule.matches(tool_name, tool_input):
16 if rule.should_ask():
17 return PermissionDecision(result="ASK")
18 elif rule.should_deny():
19 return PermissionDecision(result="DENY")
🔍 第二道闸门:遍历所有规则。匹配的规则决定是"问用户"还是"直接拒绝"。
20 # 默认放行
21 return PermissionDecision(result="ALLOW")
✅ 三道闸门都没拦住 → 默认放行。这体现了"默认允许"策略(也可以改成"默认拒绝"更安全)。

🚫 DenyListRule — 拒绝列表规则

DenyListRule
class DenyListRule(PermissionRule): def matches(self, tool_name, tool_input) -> bool: if tool_name != "bash": return False # 只检查 bash 命令 command = tool_input.get("command", "") # 检查命令是否包含任何禁止模式 return any(p in command for p in self.patterns) def should_deny(self) -> bool: return True # 命中就拒绝

📁 PathRule — 路径安全规则

PathRule
class PathRule(PermissionRule): def matches(self, tool_name, tool_input) -> bool: if tool_name not in ("read_file", "write_file", "edit_file"): return False path = Path(tool_input.get("path")).resolve() # 检查路径是否在允许的目录外 return not any( path.is_relative_to(allowed) for allowed in self.allowed_paths ) def should_ask(self) -> bool: return True # 外部路径需要确认
04 · 规则类型

📋 三种内置规则

🚫

硬拒绝规则

永远不允许的操作。比如 rm -rf /、sudo、shutdown。命中即拒绝,不需要问用户。

📁

路径规则

限制文件操作只能在指定目录内。超出范围的操作需要用户确认。防止 Agent 读写系统文件。

⚡

命令规则

特定命令模式需要确认。比如 rm、chmod 777。匹配后询问用户是否允许执行。

05 · 动手实践

🧰 创建自定义规则

1

创建规则类

继承 PermissionRule,实现 matches、should_ask/should_deny、get_reason。

2

注册到管线

调用 pipeline.add_rule(MyRule()) 即可生效。

3

自动执行

权限系统会在每次工具调用前自动检查你的规则。

06 · 实战测验

🧪 检验你的理解!

📝 选择题

Q1当命令 "sudo rm -rf /" 进入权限系统时,会在第几道闸门被拦截?
Q2权限系统的核心设计哲学是什么?
Q3PathRule 的作用是什么?
Q4PermissionDecision 有哪三种可能的结果?
Q5为什么三道闸门要按顺序执行,而不能并行?
0/5
答对题数
07 · 深入探索

🔬 想了解更多?

🏰 最小权限原则

▼

最小权限原则(Principle of Least Privilege)是安全设计的基石:只授予完成任务所需的最低权限。

在 Agent 中这意味着:只允许访问当前工作目录,而不是整个文件系统。只允许执行项目相关命令,而不是系统管理命令。

实现方式:PathRule 的 allowed_paths 只设为 [os.getcwd()]——当前目录就够了。

📊 审计日志:记录一切

▼

审计日志记录每一次工具调用的详情:谁调用了什么工具、参数是什么、结果是什么。这对于安全审计和问题排查至关重要。

实现方式:通过 PostToolUse Hook 记录日志。这是 Hook 系统(04章)和权限系统的完美协作。

日志应该记录:工具名、输入参数、执行结果、时间戳、权限决策。

🤔 为什么用"字符串包含"而不是正则表达式?

▼

DenyListRule 使用简单的 pattern in command 字符串包含检查,而不是正则表达式。为什么?

简单即安全:正则表达式容易写出有漏洞的匹配规则。比如 rm -rf 的正则如果写成 rm\s+-rf,攻击者可以用 rm -rf(两个空格)绕过。

字符串包含虽然"粗暴",但覆盖面更广。"sudo" in command 不管 sudo 出现在命令的哪个位置都能匹配。

当然,生产环境通常会用更精细的策略,比如 AST 解析命令结构。

🔄 权限系统与 Hook 系统的关系

▼

权限系统实际上是通过 PreToolUse Hook 接入 Agent Loop 的。也就是说,权限检查是 Hook 系统的一个"插件"。

这种设计的好处:权限系统不需要修改 Agent Loop 的代码。它只是一个注册在 PreToolUse 事件上的 Hook 函数。

这也意味着你可以完全替换权限系统——只要新的实现也注册为 PreToolUse Hook。这就是"开闭原则"的又一次体现。

08 · 总结

📋 本节核心要点

🎯 你学到了什么

  • 三道闸门:拒绝列表 → 规则匹配 → 用户审批,层层把关
  • 安全靠代码不靠模型:权限系统在代码层面硬性拦截
  • PermissionPipeline:核心管线,实现短路检查逻辑
  • 三种规则:DenyListRule(硬拒绝)、PathRule(路径限制)、CommandRule(命令确认)
  • 三种决策:allow(放行)、deny(拒绝)、ask(问用户)
  • 自定义规则:继承 PermissionRule → 注册到管线 → 自动生效
  • 通过 Hook 接入:权限检查是 PreToolUse Hook 的一个实现
🔗
知识串联:01 心脏(循环)→ 02 双手(工具)→ 03 安全门(权限)。现在 Agent 能做事了,也知道什么不该做。下一章讲Hook 系统——给 Agent 的循环加上"万能插座",让功能可插拔。