在将 Coding Agent 引入企业团队或本地核心开发机时，很多开发者容易产生两种危险的幻觉：

• 幻觉一：以为大模型在终端里信誓旦旦地声明“我绝不会修改敏感文件”，系统就是安全的；
• 幻觉二：以为在进入项目时点了一下“信任该仓库（Project Trust）”，系统就自动拥有了沙箱保护。

在真实的操作系统层面，Pi 默认以当前终端登录用户的全部物理权限运行。这意味着如果模型遭遇了恶意的间接提示词注入（Prompt Injection），它调用的 bash 或 edit 工具就能够读取你的 ~/.ssh/id_rsa、偷窥你的 ~/.aws/credentials，甚至通过 curl 将企业私有代码静默外泄到公网服务器。

安全架构的第一准则，是分清每一道防线到底防什么、不防什么，绝不能把界面提示误当成物理沙箱。

一、首先建立真实的威胁模型（Threat Model）

在设计防御措施前，必须明确系统面临的四大攻击源与受保护资产：

要保护的核心资产包括：开发机上的私有源码、Git 提交历史、SSH/云平台凭据、宿主机进程安全以及内网核心服务。

二、纵深防御的四层安全边界

Pi 构建了一套从软性指导到硬性隔离的四层立体防御体系：

  flowchart TD
  L1["第一层：Prompt 软约束<br/>(AGENTS.md / Skill 指南)"] --> L2["第二层：Project Trust<br/>(项目级高影响资源加载拦截)"]
  L2 --> L3["第三层：工具运行时门禁<br/>(Extension 监听 tool_call 强制确认)"]
  L3 --> L4["第四层：系统物理隔离<br/>(Docker / micro-VM / 容器只读挂载)"]
  

1. 第一层：Prompt 软指导（软边界）
   • 通过 AGENTS.md 或 Skill 告知模型“发布前必须测试”、“不要动 .env”。
   • 局限：这仅仅是阅读理解指导，模型随时可能因 Prompt 注入而失控，完全不具备强制力。
2. 第二层：Project Trust（准入边界）
   • 当进入新目录时，询问用户是否信任当前项目。未信任时，坚决不加载 .pi/extensions（禁止执行代码）、不加载 .pi/settings.json（禁止修改运行参数）。
   • 局限：它只防恶意扩展的自动运行，不防模型调用内置工具操作文件；且 AGENTS.md 默认仍会被读取，仍存在文本注入可能。
3. 第三层：工具运行时门禁（策略边界）
   • 编写 Extension 监听 tool_call 事件。对于写入 .env、执行 sudo 或包含 rm -rf 的命令，强制阻断并唤起人工交互审批（且在无头模式下坚决 Fail-Closed 默认阻断）。
   • 局限：Extension 依然运行在 Pi 的同进程权限内，如果命令绕过正则，依然无法完全杜绝破坏。
4. 第四层：操作系统与沙箱隔离（硬边界）
   • 通过轻量级 Linux 容器（Docker）、微虚拟机（micro-VM / Gondolin）或 OpenShell 策略平台，在操作系统内核层面剥离 Root 权限、锁定只读文件系统并阻断非必要网络连接。
   • 价值：这是真正决定最坏破坏上限的物理底线！ 即使模型被彻底黑客控制，它能破坏的也仅仅是容器内的临时虚拟空间。

三、加固型 Plain Docker 沙箱实战

对于日常大多数高风险的代码审查或未知第三方代码分析任务，官方提供了基于 Docker 的隔离方案。

我们绝不能使用默认的 Root 容器，必须采用最小权限加固原则构建 Dockerfile.pi：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 采用轻量 Debian 底座
FROM node:24-bookworm-slim

# 安装必要依赖并以非 root 用户加固
RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/* \
  && npm install -g --ignore-scripts @earendil-works/pi-coding-agent \
  && useradd --create-home --uid 10001 agent \
  && install -d -o agent -g agent /home/agent/.pi/agent

WORKDIR /workspace
USER agent
ENTRYPOINT ["pi"]

运行加固容器的生产级指令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 构建镜像
docker build -t pi-sandbox -f Dockerfile.pi .

# 以极度收敛的安全配置启动
docker run --rm -it \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=256m \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --memory 2g \
  --pids-limit 256 \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace:rw" \
  -v pi-agent-home:/home/agent/.pi/agent \
  pi-sandbox

请仔细阅读以上参数背后的安全硬核考量：

• --read-only：容器的根文件系统彻底设为只读，恶意脚本根本无法在容器内静默安装 Rootkit 或修改系统动态库；
• --cap-drop ALL：剥离 Linux 内核的所有超级特权（Capabilities）；
• --security-opt no-new-privileges：坚决禁止子进程通过 setuid 二进制提权；
• --memory 2g 与 --pids-limit 256：锁定内存上限与进程总数，彻底防范 Fork 炸弹与内存撑爆攻击。

四、为什么 -v "$PWD:/workspace:rw" 仍然存在隐患？

在上面的命令中，我们将宿主机的当前工作目录挂载进了容器：-v "$PWD:/workspace:rw"。

请保持清醒：容器虽然保护了你的操作系统主目录和 SSH 密钥，但它无法保护被挂载的当前代码目录！ 容器内的写入会直接映射为宿主机当前目录的真实破坏。

对于处理完全不可信的外部 PR 或进行对抗性安全测试，最安全的工业流程是：

1. 完全解耦挂载：在容器内通过 git clone 临时拉取代码副本，绝不挂载本地核心工作目录；
2. 导出补丁审查：Agent 在隔离环境修改并跑通测试后，仅导出 git diff 格式的标准 Patch 文件；
3. 宿主机审查落地：由人类工程师在宿主机对 Patch 进行代码审查后，再执行合入。

五、上线前的七步安全核验清单

在把 Pi 正式纳入日常核心研发或自动化流水线前，请严格逐项对照以下清单：

1. 资产边界核验：当前工作目录下是否残留包含真实密码的 .env 或生产 API Token？
2. 身份权限核验：Pi 是否以低权限独立账号运行，坚决避免使用 root 或系统管理员运行；
3. 网络出口收敛：容器或沙箱是否配置了网络白名单，仅放行大模型官方 API 域名，阻断对公司内网敏感数据库的连通；
4. 无头模式兜底：所有涉及高危命令拦截的 Extension，是否已确认在缺少交互界面时严格执行 Fail-Closed 默认拒绝；
5. 供应链版本锁定：所安装的第三方 Pi Package 是否已在 package.json 中锁死明确哈希或版本号；
6. 落盘脱敏核验：会话日志（Session Log）导出或分享前，是否经过敏感信息自动脱敏处理；
7. 灾难自愈预案：如果工作区被意外修改，Git 树是否具备干净的回滚恢复基线。