OpenShell 网络策略教程:给编程 Agent 设出网白名单

编程 Agent 一旦能装包、调 API、拿着 token 干活,最难回答的问题就成了「它到底能连哪儿」。英伟达开源的 OpenShell(11 月刚进 CNCF)给出的答案是:沙箱默认一个外网都不许连,每条放行规则都要写明「哪个程序、连哪个域名、能发什么请求」。这篇按官方文档,把从默认拒绝到只读放行、再到给 MCP 工具设白名单的写法过一遍,附上审计模式、策略证明器和 Agent 自助申请权限的用法。
前置条件:一台能跑容器的机器
- Linux、Apple Silicon 的 macOS,或开了 WSL 2 的 Windows(官方标注为实验性),外加 Docker、Podman 或宿主机虚拟化。
- 安装 CLI 和本地网关:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh。要固定版本,在sh前加OPENSHELL_VERSION=v0.1.9,这是北京时间 11 月 18 日凌晨发布的最新版。 - 一个装了
curl的镜像。默认沙箱镜像是最小化的 Ubuntu,里面没有任何 Agent。
想让自己的编程 Agent 帮你写策略,可以先装官方 Skills:npx skills add NVIDIA/OpenShell。它教 Agent 操作 OpenShell CLI、写沙箱策略、排查网关和推理路由,不需要克隆源码。
策略文件管五件事,只有网络能热改
OpenShell 的策略是一个 YAML 文件,开头写 version: 1,下面最多五个段。官方文档把各段的执行方和生效时机列得很清楚:
| 段 | 管什么 | 谁来执行 | 何时生效 |
|---|---|---|---|
filesystem_policy | 哪些路径可读、可读写 | 内核 Landlock LSM | 沙箱启动时 |
landlock | 规则加载失败时还要不要启动 | 沙箱运行时 | 沙箱启动时 |
process | 进程以哪个用户、组运行 | Docker / Podman | 创建沙箱时 |
network_policies | 每个程序能连哪些目标、发哪些请求 | 沙箱网络代理 | 运行中随时 |
network_middlewares | 对已放行流量再检查、改写或拦截 | 沙箱网络代理 | 运行中随时 |
不给策略时,OpenShell 用一份严格的默认策略:工作目录可读写,/usr、/etc 等系统目录只读,/tmp 可写,网络规则为空,所以所有出站连接都被拒。策略来源有优先级:网关管理员设的全局策略最高,其次是沙箱自己保存的策略(创建时 --policy 指定),再次是镜像里自带的,最后才轮到默认策略。
第一步:看默认拒绝长什么样
官方入门教程用 GitHub 的 /zen 接口做演示,它不需要 token,每次返回一句格言。先建一个不挂凭据的沙箱:
openshell sandbox create \
--name demo \
--from registry.example.com/team/agent-tools:1.0 \
--no-auto-providers
进到沙箱 shell 后执行 curl -s https://api.github.com/zen,按文档会得到 curl: (56) Received HTTP code 403 from proxy after CONNECT:代理在 CONNECT 阶段就拒了,因为没有任何规则允许 curl 连这个域名。
别退出这个 shell,退出会结束沙箱主进程。另开一个宿主机终端看拒绝日志:
openshell logs demo --since 5m --source sandbox
每条拒绝都会记下目标地址、发起连接的程序和原因,例如 DENIED /usr/bin/curl(64) -> api.github.com:443 ... [reason:network connections not allowed by policy]。
第二步:一条命令开只读权限
还是在宿主机终端执行:
openshell policy update demo \
--rule-name github_api \
--binary /usr/bin/curl \
--add-endpoint api.github.com:443:read-only:rest:enforce \
--wait
--add-endpoint 的五段依次是主机、端口、访问预设、协议、执行模式。rest 让代理解开 TLS 逐个检查 HTTP 请求;read-only 只放行 GET、HEAD、OPTIONS;enforce 拦下其余请求。网络规则热加载,不用重启沙箱。等价的 YAML 是:
network_policies:
github_api:
endpoints:
- host: api.github.com
port: 443
protocol: rest
enforcement: enforce
access: read-only
binaries:
- path: /usr/bin/curl
回到沙箱再 curl 一次 /zen,能拿到格言。接着试一个写操作,向某个仓库 POST 建 issue:连接能建立,但代理检查到方法是 POST,返回 403,响应体里有 "error":"policy_denied" 和被拒的规则名。日志里这类请求级拒绝会标成 HTTP:POST [MED] DENIED,带完整方法和路径。
放行的单位是「程序 + 域名 + 请求」三元组。同一个 GitHub API,读能过,写会被拦。
真给 Agent 用时,把 --binary 换成 Agent 本体的路径,比如 /usr/local/bin/claude。规则对它启动的子进程同样生效,Agent 调起的工具也能用这条放行。
第三步:常用白名单照抄改
官方文档给了一组可直接改的模板,挑三个编程 Agent 最常用的:
PyPI 装包:包管理器下载只用 GET,所以 read-only 能装包、不能上传。endpoints 写 pypi.org 和 files.pythonhosted.org 两个主机,binaries 写 Python 解释器的真实路径(Ubuntu 24.04 上是 /usr/bin/python3.12),用 uv 的再加 /usr/local/bin/uv。
npm 装包:主机 registry.npmjs.org,binaries 写 Node 解释器,并加 allow_encoded_slash: true。
MCP 工具白名单:protocol: mcp 能按方法名和工具名放行,下面这段只允许初始化、列工具和调用 read_status,明确拒绝 delete_resource:
mcp_server:
endpoints:
- host: mcp.example.com
port: 443
path: /mcp
protocol: mcp
enforcement: enforce
rules:
- allow: { method: initialize }
- allow: { method: notifications/initialized }
- allow: { method: tools/list }
- allow: { method: tools/call, tool: read_status }
deny_rules:
- method: tools/call
tool: delete_resource
binaries:
- path: /usr/bin/python3.12
MCP 规则只认工具名,不检查参数,被放行的工具能收到服务器接受的任何参数。不写 mcp.versions 时只放行 2025-11-25 这一版协议,用无会话的 2026-07-28 版要显式列出。对 MCP 权限还不熟的,可以先看站内的 GitHub MCP 只读工具集,思路相通:先只给读。
规则之间没有先后顺序。多条规则同时命中时,放行的权限叠加,而任何一条命中的 deny 都优先于 allow。
第四步:先审计,再强制
新规则不确定会误伤什么,就把 enforcement 设成 audit:违规请求照常放行,只记日志。不写这个字段时默认就是 audit,所以生产规则一定要显式写 enforce。跑一轮真实任务后用 openshell logs <沙箱名> --since 5m --source sandbox 看违规记录,确认只剩预期内的再切过去。
改坏了可以回滚:openshell policy list <沙箱名> 看历史修订,openshell policy get <沙箱名> --rev 2 --base 导出旧版,再 openshell policy set ... --wait 应用。手写的完整策略,应用前先跑 openshell policy lint policy.yaml。
第五步:让证明器和 Agent 自己把关
边界检查:openshell-prover 用 SMT 求解器判断一份候选策略是否超出你定的边界策略,不需要网关。典型用法是主 Agent 给子 Agent 写策略时,检查它没有超出自己的权限上限:
openshell sandbox get my-sandbox --policy-only > candidate.yaml
openshell-prover check candidate.yaml --boundary boundary.yaml
返回 within_boundary(退出码 0)才算通过;exceeds_boundary(1)会附一条反例,比如 filesystem write /tmp。目前它覆盖文件系统、L4 网络、REST、进程和 Landlock,遇到 GraphQL 或 MCP 规则会返回 unsupported(退出码 3),这也要按失败处理。
策略顾问:默认关闭。打开后,Agent 被拦时可以自己提交一条范围很窄的放行申请,OpenShell 跑风险检查后放进待审队列:
openshell settings set <沙箱名> --key agent_policy_proposals_enabled --value true
openshell rule get <沙箱名> --status pending
openshell rule approve <沙箱名> --chunk-id <proposal-id>
openshell rule reject <沙箱名> --chunk-id <proposal-id> --reason "只放行 docs/ 路径"
拒绝理由会回传给 Agent,它可以改窄了再申请。顾问只能加网络规则,删不了规则,也动不了文件系统和进程设置。
常见坑
- 写了 pip 的路径却还是被拒。pip 是 Python 脚本,真正发起连接的是解释器;OpenShell 按内核报告的真实路径识别进程,符号链接不算。在沙箱里跑
readlink -f /usr/bin/python3拿真实路径,拒绝日志里也会显示它识别到的路径。 - npm 装带 scope 的包失败。
@types/node这类包的请求路径带%2F,OpenShell 默认拒绝,要加allow_encoded_slash: true。npm 的安全审计走 POST,read-only会拦,用npm install --no-audit或改成显式 rules(access和rules不能同时写)。 - 放行了域名,凭据却没带上。网络规则放行不等于允许发送凭据,凭据只会注入到 provider 配置允许的目标。这时该改 provider 绑定,别去放宽网络规则。
- 日志里看不到违规。策略事件是 INFO 级别,加了
--level warn会被过滤掉。 - 升级到 v0.1.9 后内网地址连不上。通配符域名规则不再单独放行私有 IP,需要补一条精确 endpoint 或
allowed_ips。
完成标准
- 新沙箱里 curl 任意外网返回代理 403,日志有对应的
NET:OPEN DENIED。 - 加规则后 GitHub API 的 GET 成功、POST 返回
policy_denied,全程没重启沙箱。 - 你的 Agent 用到的包源和 MCP 服务器各有一条规则,binaries 写的是真实路径,执行模式是
enforce。 - 子 Agent 的策略过一遍
openshell-prover check,结果是within_boundary。
OpenShell 加入 CNCF 的来龙去脉见站内快讯 OpenShell 进 CNCF;常驻 Agent 的整体安全分层,可以配合 OpenAI 常驻 Agent 安全实践一起看。
最后
如果你的 Agent 现在能随便连外网,先照第一、二步把官方入门教程跑一遍,再按 Agent 实际用到的包源和 API 逐条加白名单。