@erichll/pi-sandbox (英语)

pi-sandbox 是一个Linux和macOS 进程沙盒,用于 Pi 由 Anthropic 支持 @anthropic-ai/sandbox-runtime它保护主要代理Bash命令,并能 还在独立的沙盒内运行完整的进程后置子剂树.

目录

• 安保模式
• Linux 要求
• 子代理供应商
  • pi-subagents 本地背景工具边界
• 网络域政策
• 可选主机 IPC 倒置
• 其他可信任的读取路径
• 安装
• 发展
• 上游

安保模式

• Linux 使用气泡包挂载/ 网络命名空间和 seccomp .
• macOS使用生成的Seatbelt配置文件.
• 文件系统访问是一个静态政策:在允许的区域之外读取 在工作空间外写入失败 。 运行时文件系统否认 转换为动态赠款, 因为 Sandbox Runtime 不曝光一个 值得信赖的文件系统要求回调 .
• 网络策略被评价为静态否定、静态允许、动态 检讨. 每一个无与伦比的公共目的地都被送到 pi-auto-review 作为 罐头主机名和混凝土端口. 批准仅适用于 连接.
• 每个巴什指令和持久子代理会话都拥有一个单独的经纪人 进程和 Sandbox 运行时管理器。 因此,同时期工人保留 独立的政策、代理、批准和清理生命周期.
• 每个沙盒命令都有一个 可写入的私人临时目录(单位:千美元) 新鲜 pi-sandbox-tmp-* 添加到主机临时树的子目录 沙盒的读取/写出允许列表,带有命令的 TMPDIR, (中文(简体) ), TMP,以及 TEMP 指着它。 只有这个孤立的目录是可写入的——共享的 主机临时根( 例如 ). /tmp (本身)只读到沙盒——它 命令退出时删除。 如果没有主机临时目录 (例如只读) /tmp命令会降解为上一个已拒绝的调值 行为而不是失败.
• 项目和全球 Pi 安全配置, 信任的扩展树, 已安装的软件包、 Git 钩子和其他 Sandbox 运行时强制路径 继续保存.
• 默认情况下常见的工作空间秘密会被写入- 拒绝: root- level .env 变体, secrets/ 编号 : .secrets/外加浅扫描 .env*, (中文(简体) ), *.pem, (中文(简体) ), *.key, (中文(简体) ), *.p12,以及 *.pfx模板文件,例如: .env.example 保持可写。 在 macOS 上, 额外的软块也会被堵住 创建; Linux Sandbox 运行时只执行字节路径, 所以嵌入创建 新的秘密文件仍然是扫描组外的剩余风险.
• 可选主机IPC执行默认被禁用. 启用时, 每个 完整主机命令仍需要一发 pi-auto-review 或人类 批准并运行 在OS沙盒之外.

此 Pi 适配器不支持 Windows .

Linux 要求

在装入扩展名前安装本地助手 :

sudo apt-get install bubblewrap socat ripgrep

非特权用户命名空间必须可用 。 在Ubuntu24.04+上, 无论是 配置用于气泡包或禁用 AppArmor 配置文件 kernel.apparmor_restrict_unprivileged_userns。 。 。 .

macOS 使用内置的Seatbelt支持,但仍需要 ripgrep。 。 。 .

用于 Bun 编译的独立 Pi , 安装 节点.js 并包含其 bin 作为绝对条目的目录 PATH沙盒经纪人在其中运行 独立的节点进程; 内置子剂直接发射 Pi 可执行文件. 如果无法使用 node 找到,在执行前命令失败。 基于节点的 Pi 常规 bun cli.js 发射使用其现有的JavaScript运行时间.

子代理供应商

供应商是从配置中选择的(~/.pi/agent/extensions/pi-sandbox/config.json 全球或 .pi/extensions/pi-sandbox/config.json 项目-当地:

{
  "subagents": {
    "provider": "builtin"
  }
}

支持的模式 :

• builtin (默认) : 记录进程支持 subagent 工具与沙盒 每一个完整的工序树.
• pi-subagents: 让 pi-subagents >=0.83.0 按要求自行指挥 下文描述的本土-背景工具边界.
• off:只保护巴什.

pi-subagents 本地背景工具边界

这个供应商需要Pi 1.4.0, typebox >=1.4.3 财务报告和审定财务报表 pi-subagents >=0.83.0 (确定于0.83.0和0.83.1)和 未关闭 如果其公共天花板 API、模块布局、发现、拥有或运行时间路径 缝合漂流. 对等依赖是无上指针的地板 加载器明确出口和布局检查为正门. 在节点上 加载器别名 @earendil-works/pi-tui 运行中的 Pi 软件包的主机端点 . 在Bun上,包括编译的Pi,它通过了Pi's pi-tui 财务报告和审定财务报表 typebox 模块 将对象嵌入其内部加载器中,这样这些同位素就可以被嵌入到 Pi 中 安装在旁边 pi-subagents。 。 。 . 配置保护模式和不空的峡谷白名单 :

{
  "subagents": {
    "provider": "pi-subagents",
    "protection": "native-background-tools",
    "allowedNativeAgents": ["worker", "reviewer", "scout"]
  }
}

这个 pi-subagents 配置时间 ~/.pi/agent/extensions/subagent/config.json 还必须包含 "scheduledRuns": { "enabled": false }每次发射都必须明确规定 async: true。只支持直接的单剂发射。 公开 workflowScript 编号 : workflowScriptPath 儿童妨碍环境 上游扩展,所以两者 与命名的工作流程,时间表, 配置突变、恢复、链接附件、嵌入子剂和外部 赛跑者。 未知的管理动作被拒绝而不是默认信任.

指导仅限于直接出生的儿童,必须明确规定 options: { "steeringRecovery": false } (遗留的顶级拼写也 工作) (中文(简体) ). 使用完整的运行ID, 而不是前缀或 dir在引导前 适配器重新验证代理白名单并读取主机拥有的运行状态 : 所有权本身并不是保护。 目标需要沙盒的天花板 和它自己的儿童运行时间确认,包括同期会后 继承。 缺少/无效证明、链接路径或不再允许代理 块方向盘; 检查或停止运行。 这不是改装a 沙盒放在一个已经运行的无保护的孩子身上。 现状/停机坪仍然可用. 此状态文件检查是最佳的, 不是证明: 主机侧写器 访问 Async 运行时目录可以伪造 JSON 证明,包括 a 允许在此写入父工具 。 没有程序-当地发射-接收登记 ,因此保留恢复兼容性;单独保护运行时间 如果敌对作者在范围中.

每个儿童都受到上游能力上限的制约 bash, (中文(简体) ), read, (中文(简体) ), grep, (中文(简体) ), find,以及 ls。孩子装入环境扩展,必须 确认 @erichll:pi-sandbox;因此,只能通过 沙盒巴什工具 . write, (中文(简体) ), edit,MCP和其他扩展工具不是 可用.

在发布之前,运行 决定性和模型支持的部分 npm run gate:pi-subagents。见 docs/compat-notes.md 用于记录的相容性接合以及每个接合方式 升级时核实.

配置解析器拒绝不正确的 JSON, 未知的字段和未知的 而不是默默地削弱孤立.

网络域政策

域授权可以全局配置于 ~/.pi/agent/extensions/pi-sandbox/config.json 或项目所在地 .pi/extensions/pi-sandbox/config.json (与工会语义相融合):

{
  "network": {
    "strictAllowlist": false,
    "allowedDomains": [
      "github.com",
      "*.github.com",
      "registry.npmjs.org:443"
    ],
    "deniedDomains": [
      "uploads.github.com",
      "*:22"
    ]
  }
}

条目支持精确域, 严格子域通配符, 如 *.example.com,可选 :port 限制。 一个赤裸的 * (可选择) 仅允许在 deniedDomains价值被调整 已破损, 且配置不整齐或未知无法关闭 .

优先是决定:

1. 一个匹配 deniedDomains 条目拒绝连接.
2. 否则,一个匹配 allowedDomains 入境可以不经审查.
3. 否则,如果 strictAllowlist 实值 true,则该连接不包含 引用运行时请求回调,模式审查,或人类批准.
4. 否则, Cononical 公共主机名和端口会输入现有的 一发自动审查或人类批准流程.

两个阵列默认为空并 strictAllowlist 默认为 false,保留 现有的每个连接批准行为。 设置只接受布尔值 . 使用严格的模式和一个空的许可列表,所有代理目的地都会被拒绝. deniedDomains: ["*"] 块也允许条目,因为拒绝规则具有优先权. 同样的网络政策适用于主要代理Bash、用户Bash、内置子代理和 由被保护的本地装入的沙盒 Bash 工具 pi-subagents 孩子们.

对于仅限于明确批准的推断终点的工人:

{
  "subagents": { "provider": "builtin" },
  "network": {
    "strictAllowlist": true,
    "allowedDomains": ["inference.example.com:443"],
    "deniedDomains": []
  },
  "hostIPC": { "mode": "off" }
}

将示例主机名替换为您批准的端点 。 全球和项目 strictAllowlist 值与逻辑 OR 合并: 项目不能严格禁用 需要全球模式。 域列表仍然组成工会,所以一个项目 可添加 允许目的地。两个文件都是可信任的政策输入;全局允许列表 不属于项目许可的行政上限.

严格模式不能与 hostIPC.mode: "ask",因为主机执行 就能逃脱网络沙盒 有效配置在之前被拒绝 创建工具或工人;设置 Host-IPC 模式 off之后检查此选项 global/ project合并,并在嵌入式Host-IPC 覆盖后再次合并.

注册扩展名时装入配置 。 现有持久性 工人通过后续行动来维持其政策,发放工人得到的津贴相同 配置策略 。 重新装入扩展名并创建应用文件的新工作者 更改; 没有配置热重装 。 经纪人启动失败从不重试 沙盒外的工人 和无法提供的审批服务不能放松 严格网络否定.

域允许列表不是一个完整的数据-损失-防止边界. A 类 多租户或用户可加载的目的地,例如 github.com 能够自己是 过滤通道; 只授予您想要的狭窄域和端口 . 真正的软件包管理流量可能需要额外的主机- 例如 PyPI 常用下载 files.pythonhosted.org。 。 。 . pi-sandbox 永远不会推断或 默地添加了这些域.

原生背景跑跑者初始化本身位于OS沙盒外. 只有孩子的巴什修改通道被沙箱所覆盖. 选择 builtin 何时 整个工作流程树必须被 Sandbox Runtime 控制.

可选主机 IPC 倒置

一些主机服务只曝光OS沙盒无法使用的Unix套接字. 信任的全球配置可以启用一个由批准驱动的本地 Bash 这些命令的后端 :

{
  "hostIPC": {
    "mode": "ask",
    "preflightCommandPrefixes": ["tmux", "/usr/bin/tmux"],
    "retryOnUnixSocketError": true
  }
}

mode 实值 off 默认且仅接受 off 或者说 ask前缀为 修饰相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相相去相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 前缀仅在 开始修剪命令,并必须在白空或结束时结束 命令。 前缀选择要审查的命令;它们从来不授权执行. 审阅员和一发奖金必须服从全权指挥和工作 目录.

与 retryOnUnixSocketError 启用, 未选择飞行前的命令 仍然在 Sandbox 运行时间第一。 只考虑一个主机重试 在非零退出之后,其stderr 识别了两者 Operation not permitted 以及一个插座/连接/IPC操作。 原产出保留 警告说,第一次尝试可能已经是局部的 效应。 成功, 超时, 或中止的命令永远不会被重试 .

主机转发器在内部内置的子代理中被故意拒绝 这个版本。 这也不符合 network.strictAllowlist: true。 。 。 .

其他可信任的读取路径

信任的全球配置可能会将绝对路径附加到沙盒中 默认读取许可列表 。 这对安装在下面的可执行文件有用 以其他方式拒绝的主目录 :

{
  "subagents": {
    "provider": "builtin"
  },
  "filesystem": {
    "additionalAllowRead": [
      "/home/user/.local/bin/rtk"
    ]
  }
}

filesystem.additionalAllowRead 必须是一系列绝对路径。 这些 路径扩展默认;它们不替换工作空间、节点.js,或 Sandbox 运行时读取权限 。 尽量缩小条目 选择精确的可执行路径,而不是允许整个 bin 目录.

持续内在会议支助 start, (中文(简体) ), follow_up, (中文(简体) ), wait, (中文(简体) ), status, (中文(简体) ), stop并筑巢 handoff 操作。 最多四届是现场直播 一次,而筑巢深度被封为三.

项目级别配置和只读保护

除了用户级配置 ~/.pi/agent/extensions/pi-sandbox/config.json, (中文(简体) ), pi-sandbox 支持放置在以下位置的项目级别配置:

.pi/extensions/pi-sandbox/config.json

目前,项目配置与全球配置合并:

• 阵列政策additionalAllowRead, (中文(简体) ), allowedDomains, (中文(简体) ), deniedDomains, (中文(简体) ), preflightCommandPrefixes(a) 组成一个分裂的联盟.
• 斯卡拉尔设置( S)provider, (中文(简体) ), mode, (中文(简体) ), retryOnUnixSocketError)允许项目级别覆盖.
• network.strictAllowlist 使用逻辑 OR : true 在两个文件中都允许它. 这两个配置文件都可信;项目允许列表添加仍然有效.
• 合并配置不能同时启用严格的允许列表和Host-IPC ask。 。 。 .

仅读的安全保证数字 : 项目层面的配置在沙箱政策中得到明确保护(denyWrite, (中文(简体) ), 表示可读取的沙盒任务 .pi/extensions/pi-sandbox/config.json 但永远不能 从沙盒里篡改或覆盖它.

pi install npm:@erichll/pi-auto-review
pi install npm:@erichll/pi-sandbox

不在本地安装安全软件包 。 开发装载从 此寄存器需要 PI_AUTO_REVIEW_ALLOW_UNTRUSTED_DEV=1。 。 。 .

发展

从单列波根:

npm install
npm run check
npm test
npm run gate:pi-subagents

gate:pi-subagents 验证被钉住的发展依赖的一揽子布局, 发现行为, 能力上限和在孤立的临时代理中受保护的发射政策 目录。 它从未读取或更新出品的 Pi 配置. 模型支持 接受要求 PI_SUBAGENTS_GATE_MODEL 和已导出匹配 证书; 缺少的先决条件报告为 SKIP。当前对等点 地平面为Pi 1.4.0,有Pi-subagents 0.83.0,开发基线为: pi-subagents 0.83.1,两者均使用 typebox >=1.4.3。 。 。 . pi-tui >=1.4.0 是明确的主机对等点,而不是捆绑 运行时间依赖。 见 docs/compat-notes.md 记录的确定性 和模型支持的验证结果.

测试套房包含真正的 Linux Sandbox Runtime 执行 当它的本土 依赖性被安装,加上决定性的经纪人,网络批准, 工艺清理、货币和跨平台管弦测试.

上游

Sandbox Runtime是一个Apache-2.0许可的研究预览: https://github.com/ 人类-实验/sandbox-runtime (中文(简体) )。 。 。 .