GSD 安全与信任边界实践：沙箱隔离、能力化安全模型与 AI 常见漏洞防护

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

本篇技术指南以 GSD 项目（docs/dev/building-coding-agents/24-security-trust-boundaries.md）的安全设计文档为主线，系统讲解如何把 Agent 当作"高能力但未经审查的承包商"来构建安全环境：包括不可逾越的硬边界、分层沙箱架构、能力化安全模型，以及针对 AI 生成代码的常见脆弱模式与配置落地方法。读完你将掌握在 GSD 中配置沙箱、白名单、凭据注入与安全覆盖的具体命令和参数。

1. 核心安全立场：让环境安全，而非让 Agent 受限

文档提出的第一个关键结论是：安全的重点不是通过限制 Agent 能力来"让 Agent 安全"，而是把环境设计得足够安全，让 Agent 在环境中可以最大限度地发挥能力。

Think of the agent as ahighly capable but unvetted contractor.Give them the codebase and dev environment. Don't give them production credentials, deployment access, or the ability to modify security infrastructure. The goal isn't to make the agent safe by limiting capabilities — it's to make theenvironmentsafe so the agent can be maximally capable within it.

这一定位直接决定了后续所有设计决策的方向：信任不放在 Agent 身上，而是放在环境的隔离、验证与审计机制上。因此 GSD 的整个安全体系由三个层次构成——硬边界（Hard Boundaries）、沙箱架构（Sandboxing Architecture）与能力化安全模型（Capability-Based Security Model）。

2. 硬边界：Agent 绝不应做的事（通用共识）

文档给出了所有 Agent 系统都应遵守的硬边界清单，这些属于"不需要讨论、必须遵守"的通用共识：

从 GSD 源码看，这条硬边界被落实为"全局配置优先"的原则：威胁模型明确针对克隆仓库中可能包含的恶意项目级配置，因此安全覆盖只允许来自全局设置与环境变量，项目级配置一律忽略。见 src/security-overrides.ts 第 4-6 行的注释：

// Both overrides are global-only (not project-level) because the threat model is // malicious project-level config in cloned repos. Global settings and env vars // represent the user's own authority on their machine.

3. 沙箱架构：五层纵深隔离

文档定义了沙箱架构的五层机制，GSD 仓库中有对应的真实实现：

3.1 执行层：Docker 沙箱模板

GSD 提供现成的沙箱镜像模板 Dockerfile.sandbox，其关键安全设计包括：

• 基于node:24-bookworm-slim精简基础镜像，只安装必要工具（git、curl、ca-certificates、openssh-client、gosu）；
• 创建非 root 用户gsd（UID 1000），容器内进程以低权限用户运行：

  RUN groupadd --gid 1000 gsd \ && useradd --uid 1000 --gid gsd --shell /bin/bash --create-home gsd

• 只暴露默认 Web UI 端口 3000（EXPOSE 3000）；
• 通过entrypoint.sh完成UID/GID 重映射 + 权限降级。

entrypoint.sh 中展示了完整的权限链：容器以 root 启动 → 根据宿主机PUID/PGID重映射gsd用户 → 预创建关键文件防止 bind-mount 把文件路径变成目录 → 基于哨兵文件（.bootstrapped）执行一次性初始化 → 最终用exec gosu "${GSD_USER}" "$@"替换进程并降级为非 root 用户，同时保证 PID 1 信号转发（SIGTERM/SIGINT）正确。

# 构建并使用沙箱模板（Docker Sandbox CLI，MicroVM 级隔离） docker sandbox create --template ./docker --name gsd-sandbox docker sandbox exec -it gsd-sandbox bash gsd auto "implement the feature described in issue #42"

也可以使用容器级隔离的 Compose 方案（docker-compose.yaml）：

cp docker/.env.example docker/.env # 编辑 docker/.env 填入你的 API 密钥 docker compose -f docker/docker-compose.yaml up -d docker exec -it gsd-sandbox bash gsd auto "implement the feature described in issue #42"

3.2 文件系统层：受控的工作区挂载

沙箱通过受限挂载把 Agent 的活动范围锁定在项目目录内。Compose 的卷配置（docker-compose.full.yaml）展示了推荐挂载方式：

volumes: - ../:/workspace # 项目根目录挂载进容器 - gsd-state:/home/gsd/.gsd # GSD 状态目录跨重启持久化 # - ~/.ssh:/home/gsd/.ssh:ro # SSH 密钥以只读方式挂载（可选） # - ~/.gitconfig:/home/gsd/.gitconfig:ro # 宿主机 git 配置（可选）

注意注释掉的 SSH 密钥与 git 配置：即便需要让 Agent 操作 git，也只读挂载，Agent 无法修改宿主机上的密钥文件。同时PUID/PGID重映射避免了 bind-mount 卷上的权限冲突（docker/README.md 中建议用id -u/id -g查询宿主用户 ID 填入）。

3.3 命令层：危险命令拦截与命令前缀白名单

命令层的拦截逻辑分两个层面：

（a）内置安全前缀白名单：GSD 将"可以安全执行的命令前缀"集中定义在 packages/pi-coding-agent/src/core/resolve-config-value.ts 第 14-25 行的SAFE_COMMAND_PREFIXES中，用于!command解析：

export const SAFE_COMMAND_PREFIXES = [ "pass", "op", "aws", "gcloud", "vault", "security", "gpg", "bw", "gopass", "lpass", ];

这些前缀正是凭据管理器（pass、1Password 的op、Bitwarden 的bw、gopass、lpass）与云 CLI（aws、gcloud、vault、security），它们由 Agent 安全调用以获取短期/临时凭据，而不会把机密文本直接带入上下文。测试 packages/pi-coding-agent/src/core/resolve-config-value.test.ts 中有一个值得注意的用例：sops不在内置白名单中，因此默认会被拦截，必须显式加入白名单后才能使用——这印证了"新能力必须显式批准"的设计理念。

（b）用户级命令前缀覆盖：setAllowedCommandPrefixes()允许以全局设置或环境变量替换默认白名单。若传入空数组，会输出警告并阻断所有!command（见 resolve-config-value.ts 第 39-41 行）——这是 fail-closed 的默认行为。

3.4 网络层：SSRF 防护与出口白名单

网络访问在两层被限制：

（a）SSRF 防护：src/resources/extensions/search-the-web/url-utils.ts 中的isBlockedUrl()实现了一套完整的 SSRF 拦截逻辑：

• 协议校验：非https:/http:的 URL 一律拦截；
• 内置黑名单主机名：localhost、metadata.google.internal、instance-data（云元数据服务是 SSRF 的经典攻击目标）；
• 私有 IP 段拦截：覆盖127.*、10.*、172.16-31.*、192.168.*、169.254.*（链路本地地址）、0.*、::1、fc00:*、fd*（IPv6 ULA）、fe80:*（IPv6 链路本地），防止 Agent 通过 fetch 访问内网资源。

（b）出口域名白名单：文档要求"限制性防火墙，只白名单必要服务"。若你在沙箱中限制出站网络，GSD 需要放行的端点见 docker/README.md 的 Network Allowlisting 一节：

3.5 机密层：凭据注入而不是凭据暴露

沙箱内的 Agent 依然需要调用 LLM API，密钥如何进去？文档给出两条路径：

• Docker Sandbox（自动）：Docker 的代理层会把宿主机 shell 配置（~/.bashrc、~/.zshrc）中设置的 API key 自动转发进沙箱，密钥永不存储在沙箱内部；
• Docker Compose（手动）：复制docker/.env.example为docker/.env填入密钥，该文件被 gitignore 且永不提交。

两条路径都贯彻了"Agent 拿不到原始凭据"的原则——对应文档中"Vault 代理 + 短期令牌"的设计意图：Agent 通过受控通道使用凭据，而非在上下文中持有明文。

3.6 依赖层：批准清单

文档要求依赖走"批准的依赖清单 + 自动/人工批准"。GSD 沙箱内置工具由镜像固定（npm install -g gsd-pi@${GSD_VERSION}），版本通过构建参数锁定（如docker compose -f docker/docker-compose.yaml build --build-arg GSD_VERSION=2.51.0），新增依赖默认需要批准——与命令白名单的"显式加入才可用"逻辑一致，都属于 fail-closed 设计。

4. 能力化安全模型：编排器在沙箱之外，Agent 只有工具

这是文档中承上启下的关键架构：

The orchestrator runsoutsidethe sandbox. The agent requests operations through a controlled API. The orchestrator validates every request before executing. The agent doesn't have direct access to anything — it has access totools that the orchestrator mediates.

即：Agent 没有直接访问任何东西的能力，它拥有的只是编排器中介过的工具。编排器运行在沙箱之外，Agent 的一切操作都必须通过受控 API 提出请求，由编排器在执行前逐一验证。这个模型把"能力"从"访问权限"中解耦——即便 Agent 被诱导或出 bug，也无法绕开编排器直接触达系统资源。

这一点在 GSD 中同样体现为"编排器在沙箱外、Agent 在沙箱内"的部署形态：宿主侧的编排进程负责验证，容器内只运行gsd命令本身。docker-compose.yaml中容器仅挂载项目目录与.gsd状态卷，宿主机其他目录与进程对容器不可见，即"Agent 的世界就是开发环境"的执行层落实。

5. 微妙风险：AI 特有的不安全模式

文档特别指出一个容易被忽视的事实：Agent 引入漏洞往往不是出于恶意，而是通过"看起来很合理的不安全模式"。典型三类：

• 字符串拼接构造 SQL 查询（应改用参数化查询）；
• 为图方便禁用 CORS（应保留跨域校验）；
• 为调试而记录敏感数据（应脱敏并限制日志级别）。

因此，安全 lint 规则应专门针对这些"AI 常见模式"进行调优，而不是只按人类开发者的常见错误配置。这意味着安全护栏的默认值应当覆盖 Agent 的"便利性倾向"：例如 GSD 对fetch_page工具默认启用 SSRF 拦截、对命令默认拒绝未批准前缀，都是对这一原则的实现。

6. 落地配置：安全覆盖（Security Overrides）

GSD 把上述原则转化为一组用户可配置的安全覆盖参数，集中在 src/security-overrides.ts 中统一应用。该文件的优先级设计为：环境变量 > settings.json 全局设置 > 内置默认值（见文件第 8 行注释）。

6.1 命令前缀白名单覆盖

通过GSD_ALLOWED_COMMAND_PREFIXES环境变量或全局settings.json中的allowedCommandPrefixes覆盖内置的SAFE_COMMAND_PREFIXES：

# 环境变量方式（逗号分隔） export GSD_ALLOWED_COMMAND_PREFIXES="pass,op,aws,gcloud,vault,security,gpg,bw,gopass,lpass,sops"

对应settings.json：

{ "allowedCommandPrefixes": ["pass", "op", "aws", "gcloud", "vault", "security", "gpg", "bw", "gopass", "lpass", "sops"] }

从 settings-manager.ts 第 220 行可知：该配置为global-only，项目设置中会被忽略——这是防止克隆仓库在项目级配置中偷偷放宽命令限制的关键设计（对应硬边界"禁止 Agent 修改自身安全约束"）。

6.2 网络白名单覆盖（SSRF 豁免）

通过GSD_FETCH_ALLOWED_URLS或全局设置中的fetchAllowedUrls设置豁免 SSRF 拦截的主机名：

export GSD_FETCH_ALLOWED_URLS="api.github.com,registry.npmjs.org"

{ "fetchAllowedUrls": ["api.github.com", "registry.npmjs.org"] }

同样为 global-only。这些主机名会被注入 url-utils.ts 的fetchAllowedHostnames集合，isBlockedUrl()会先检查豁免清单，再检查内置黑名单与私有 IP 段（见该文件第 42-56 行）。

7. 从文档到实践：完整的安全边界检查清单

结合文档五条硬边界与 GSD 的落地实现，将理论映射为可直接核查的安全清单：

8. 已知限制与适用前提

• 沙箱网络策略需要配合防火墙/代理才能真正"白名单化"——Docker 容器默认 bridge 网络本身不提供出站过滤，文档要求的"限制性防火墙"属于部署环境责任；
• Docker Sandbox CLI 需 Docker Desktop 4.58+（macOS/Windows），Linux 支持为实验性；Compose 方案提供容器级隔离作为替代（docker/README.md 的 Known Limitations）；
• Docker 自带的命名 Agent（claude、codex 等）由 Docker 自身注册，第三方工具无法注册新命名 Agent，GSD 改用通用 shell 沙箱类型 + 自定义模板；
• 沙箱运行 Ubuntu（Debian）环境，macOS 专属依赖可能无法在沙箱内工作，需在宿主侧验证环境一致性。

这些限制并不削弱信任边界的有效性——它们只是提示：沙箱是安全环境的最后一层，而非全部。硬边界共识 + 五层沙箱架构 + 编排器中介的能力化模型，共同构成了"环境安全、Agent 自由"的完整体系。

延伸阅读：本文安全设计出自 docs/dev/building-coding-agents/24-security-trust-boundaries.md，同系列其余章节（如 17-irreversible-operations-safety-architecture.md、20-error-taxonomy-routing.md）可配合阅读；沙箱部署细节见 docker/README.md，源码入口见 security-overrides.ts 与 resolve-config-value.ts。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用