Pi 安全沙盒扩展

严格限制 Pi 的操作范围，对高危操作进行人工确认的安全扩展。

功能特性

✅ 已实现 (P0)

功能	描述
工作目录限制	禁止访问允许目录之外的文件
高危命令确认	rm -rf, sudo, curl | sh 等需确认
受保护路径	.env, .git 等文件特殊保护
配置系统	JSON 配置，支持项目级和用户级
审计日志	记录拦截、确认、允许的操作
非交互模式	支持 -p 模式的自动处理策略

📋 计划中 (P1/P2)

• 网络管道命令深度检测
• 配置热重载文件监听
• 规则统计报告
• 智能风险等级评估

安装

方式一：全局安装（推荐）

mkdir -p ~/.pi/agent/extensions
cp sandbox.ts ~/.pi/agent/extensions/

Pi 启动时自动加载。

方式二：项目级使用

pi -e ./sandbox.ts

方式三：通过 settings.json

{
  "extensions": [
    "/Users/bgs/Documents/YI/sandbox.ts"
  ]
}

配置

配置文件位置

1. 项目级（优先）: .pi/sandbox-config.json
2. 用户级: ~/.pi/sandbox-config.json

最小配置

{
  "allowedPaths": ["./"]
}

完整配置

{
  "allowedPaths": ["./", "/tmp"],
  "protectedPaths": [
    ".env",
    ".git/",
    "node_modules/",
    "*.secret"
  ],
  "dangerousPatterns": [
    "\\brm\\s+-rf",
    "\\bsudo\\s"
  ],
  "blockedCommands": [
    "\\brm\\s+-rf\\s+/\\s*$"
  ],
  "nonInteractiveMode": "block",
  "enableAuditLog": true
}
}

配置项说明

配置项	类型	默认值	说明
allowedPaths	string[]	[cwd]	允许操作的目录（绝对路径或相对路径）
protectedPaths	string[]	见代码	受保护路径，操作需额外确认
dangerousPatterns	string[]	见代码	需要确认的高危命令正则
blockedCommands	string[]	见代码	完全禁止的命令正则
nonInteractiveMode	string	"block"	非交互模式：block/allow/warn
enableAuditLog	boolean	true	是否启用审计日志

使用

启动提示

扩展加载成功后会显示：

🔒 安全沙盒已启用（默认配置）

或

🔒 安全沙盒已启用 (2 个允许目录)

越界操作拦截

🚫 安全沙盒：路径 "../../../etc/passwd" 超出允许范围
允许目录: /Users/bgs/Documents/YI

高危操作确认

⚠️ 高危操作确认

即将执行可能危险的操作:

  rm -rf ./node_modules

是否允许执行？

受保护路径确认

⚠️ 受保护的路径

即将修改受保护文件: .env

是否继续？

命令

命令	描述
/sandbox-status	显示当前配置和审计摘要
/sandbox-log	显示最近 20 条审计记录
/sandbox-reload	重新加载配置文件

/sandbox-status 示例输出

🔒 安全沙盒状态

配置来源: /Users/bgs/Documents/YI/.pi/sandbox-config.json
允许目录:
  • /Users/bgs/Documents/YI
  • /tmp

受保护路径:
  • .env
  • .git/
  • node_modules/

高危模式数: 15
禁止模式数: 3
非交互模式: block

审计记录: 42 条 | 阻止: 12 | 确认: 8 | 允许: 22

安全策略

风险等级

等级	命令示例	处理方式
Blocked	rm -rf /, dd if=/dev/zero of=/dev/sda	自动阻止，不可覆盖
Dangerous	rm -rf ./dir, sudo apt update	交互确认，非交互按配置处理
Safe	ls, cat, grep	直接允许

默认阻止的命令

• rm -rf / 或类似根目录删除
• dd 写入磁盘设备
• 重定向到 /dev/sd* 等磁盘设备

默认需要确认的命令

• rm -rf* - 递归强制删除
• sudo* - 特权命令
• curl | sh / wget | bash - 管道执行远程脚本
• git push --force - 强制推送
• git reset --hard - 强制重置
• chmod 777 - 全开权限
• npm install -g - 全局安装

非交互模式

当使用 -p (print) 模式或没有 UI 时：

模式	行为
block	高危操作自动阻止（默认）
allow	高危操作自动允许（不推荐）
warn	允许但输出警告到 stderr

技术实现

拦截点

1. tool_call 事件 - 拦截所有工具调用
2. user_bash 事件 - 拦截用户 bash 命令

核心类

• ConfigManager - 配置加载与合并
• PathGuard - 路径边界检查
• CommandRiskAnalyzer - 命令风险分析
• AuditLogger - 审计日志记录

路径检查

// 规范化路径并检查是否在允许目录内
const resolvedPath = resolve(cwd, inputPath);
const normalizedPath = normalize(resolvedPath);
const rel = relative(allowedPath, normalizedPath);
// 允许：!rel.startsWith("..") && !isAbsolute(rel)

故障排除

扩展未加载

检查文件位置是否正确：

ls ~/.pi/agent/extensions/sandbox.ts

配置未生效

检查配置文件语法：

python3 -m json.tool .pi/sandbox-config.json

重新加载配置：

/sandbox-reload

路径检查失败

确保使用绝对路径或相对于 cwd 的路径：

{
  "allowedPaths": ["/home/user/project", "./subdir"]
}

许可证

MIT