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 事件钩子与注册接口

tool_call(返回 block: true)before_agent_startsession_startctx.ui.confirm()pi.setActiveTools()pi.registerCommand()

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 更自由,但也更折腾)

出口 1(配置单与实机演示制作中)

Coding Agent 实战交付课:如何可控地把想法做成线上产品

由 kuhung 策划主讲。面向希望把 Coding Agent 用到真实工程与产品交付的开发者,讲清需求拆解、上下文控制、安全边界与上线验证。

出口 2(实战交付课筹备中)