03 安全与权限
Agent 安全从口号变标配:拦截、权限策略、沙箱与供应链审查
1. 这个方向的插件试图解决什么问题
Pi 扩展和 bash 工具默认与当前系统用户拥有同等权限,既能读写 .env 与 ~/.ssh,也能执行破坏性命令或通过 npm postinstall 引入第三方供应链风险。这一方向的扩展在工具执行前与包安装前建立可验证防线。
单纯靠系统提示词“请不要删除文件”或“不要读取密钥”没有约束力。模型一旦误判参数、或者被外部文本里的提示词注入诱导,依然会直接调用 bash 或 write 工具。
安全问题分为四层:命令与路径规则拦截、集中式权限审批、OS 级文件系统与网络沙箱隔离、以及安装第三方 Pi 扩展包前的供应链安全审计。
2. 在 Pi 里怎么体现
Pi 的 tool_call 事件会在任意内置或自定义工具实际执行前触发,扩展可以直接返回 { block: true, reason } 阻断调用,或通过 ctx.ui.confirm() 弹出交互式确认框。
同时,Pi 允许项目级 .pi/settings.json 在授予 project_trust 前不加载本地扩展,因此扩展安全生态既覆盖运行时的 tool_call 拦截(如 cc-safety-net、@gotgenes/pi-permission-system、pi-sandbox),也覆盖安装前的包审计(如 pi-vetter)与规则监督(如 pi-warden、pi-agent-foreman)。
涉及的 Pi 事件钩子与注册接口
3. 代表包与生态实例
下表包名均核实自 npm、GitHub 与 pi.dev/packages(核对日期 2026-11-22)。前 3 项已上线独立机制详评页,正文不展示容易过期的静态下载量快照。
| 包名 | 分发形态 | 主要作用 | 详情 / 源码 |
|---|---|---|---|
cc-safety-net | npm | 编码 Agent CLI 钩子,在工具执行前解析命令语义,阻断破坏性操作与密钥文件访问。 | |
@gotgenes/pi-permission-system | npm | 为 Pi 提供集中式、确定性的权限门禁扩展,统一管控工具、bash、MCP 与技能调用。 | |
pi-vetter | npm | 面向 Pi 扩展包的安装前安全审查工具,基于多维证据输出 ALLOW/ASK/DENY 判定。 | |
pi-deltabox | npm | 由 deltabox-lite 驱动的 Pi 原生沙箱会话扩展,支持 diff 审查、提交与中止回滚。 | |
pi-sandbox | npm | 带有交互式权限提示的 Pi 操作系统级沙箱扩展,限制进程文件系统与网络访问。 | |
pi-warden | npm | 依据 pi-warden.md 校验每次文件写入,阻断违规修改、打破死循环并压缩超大工具输出。 | |
pi-verdict | npm | 极简权限门禁扩展,使用决策分类器自动评估工具调用风险。 | |
pi-guardrails | npm | 针对 GitHub 操作的权限扩展,默认放行读取并对远程写操作与身份校验触发确认。 | |
pi-agent-foreman | npm | 监督型拦截扩展,识别 Agent 声明未完成却提前结束回合的情况并自动驱动继续执行。 |
4. 怎么装
pi install npm:cc-safety-net - 规则拦截器(如 cc-safety-net)与 OS 沙箱(如 pi-sandbox)解决的是不同层次的问题:前者做语义命令解析拦截,后者做进程级文件系统与网络边界隔离,可以组合使用。
- 安装任何社区扩展前,可先用 pi-vetter 的 /vet 命令检查依赖漏洞、Sigstore 签名或仿冒包风险,再决定是否放行安装。
- 部分安全策略扩展会屏蔽或重写高危命令参数,建议先在测试目录验证与现有构建脚本的兼容性。
5. 和同类怎么选
| 包名 | 防护层级 | 工作原理 | 典型用途 |
|---|---|---|---|
cc-safety-net | 命令与密钥访问拦截(非沙箱) | 解析 bash AST/命令语义,在执行前阻断破坏性命令与密钥文件读取 | 防止 rm -rf、git reset --hard 或误读 .env / SSH 密钥 |
@gotgenes/pi-permission-system | 集中式权限门禁系统 | 在 tool_call、input、before_agent_start 等节点对工具/bash/MCP 做确定性策略判定 | 团队统一管理可放行、需确认与禁止的工具操作矩阵 |
pi-vetter | 安装与更新前供应链审查 | 在执行安装/更新前拉取 OSV 漏洞、Sigstore 与风险信号,输出 ALLOW/ASK/DENY 证据链 | 在正式运行 pi install 前把关第三方扩展安全性 |
pi-sandbox | OS 级沙箱 + 交互授权 | 利用操作系统级沙箱限制子进程的文件系统读写与网络出口 | 运行不可信代码或需要强隔离的自动化任务 |
pi-deltabox | 原生沙箱会话与 diff/提交控制 | 基于 deltabox-lite 提供可对比 diff、提交或中止的沙箱会话 | 让改动先落在隔离沙箱,确认后再落盘或丢弃 |
pi-verdict | 极简自动模式权限分类门 | 参考 Claude Code Auto Mode,通过独立小模型分类器判定高危 tool_call | 在“全手动确认”和“全自动放行”之间找平衡 |
pi-warden | 项目规则强制监督 | 每次写入按 pi-warden.md 校验,识别未验证的完成声明并打破死循环 | 强制 Agent 遵守仓库代码规范与完成校验红线 |
pi-guardrails | GitHub 写入确认门禁 | 允许 GitHub 只读查询,对远程写操作与身份做强制确认 | 避免 Agent 未经授权直接 push、建 PR 或修改线上仓库 |
pi-agent-foreman | 未完成任务监督拦截 | 当 Agent 声明未完成工作却停下时自动拦截并推回继续执行 | 基于 Jev 单步决策模型监督未完成宣称,自动推回继续执行 |
看完「03 安全与权限」后的下一步
可先读已公开的入门实操文章,或点击下方制作中项目表达关注度(不收集邮箱或隐私)
从 Claude Code / Codex 切到 Pi:最小可用配置单与实机演示视频
已上线入门参考: 《Pi 入门笔记》 (比 Codex 更自由,但也更折腾)
说明:此处未向后台提交个人资料或邮件表单。配置单与实机演示视频正在制作中,你的匿名点击已计入站点热度,用于排定优先录制方向。
Coding Agent 实战交付课:如何可控地把想法做成线上产品
由 kuhung 策划主讲。面向希望把 Coding Agent 用到真实工程与产品交付的开发者,讲清需求拆解、上下文控制、安全边界与上线验证。
说明:此处未向后台提交报名或收集任何个人信息。课程模块仍在筹备阶段,你的匿名点击将作为模块排期的优先参考。