教程2026-11-18 · 智涌AI

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

OpenShell 网络策略教程头图:左侧 OpenShell 网络策略大字和默认 0 条出网规则、策略文件 5 段、最新版本 v0.1.9 数据卡,右侧终端展示 openshell policy update 给 curl 开 GitHub API 只读权限,GET 返回 200、POST 返回 403 policy_denied

编程 Agent 一旦能装包、调 API、拿着 token 干活,最难回答的问题就成了「它到底能连哪儿」。英伟达开源的 OpenShell(11 月刚进 CNCF)给出的答案是:沙箱默认一个外网都不许连,每条放行规则都要写明「哪个程序、连哪个域名、能发什么请求」。这篇按官方文档,把从默认拒绝到只读放行、再到给 MCP 工具设白名单的写法过一遍,附上审计模式、策略证明器和 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,它可以改窄了再申请。顾问只能加网络规则,删不了规则,也动不了文件系统和进程设置。

常见坑

完成标准

OpenShell 加入 CNCF 的来龙去脉见站内快讯 OpenShell 进 CNCF;常驻 Agent 的整体安全分层,可以配合 OpenAI 常驻 Agent 安全实践一起看。

最后

如果你的 Agent 现在能随便连外网,先照第一、二步把官方入门教程跑一遍,再按 Agent 实际用到的包源和 API 逐条加白名单。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。