网络与安全

CubeSandbox 的网络安全目标很明确：让沙箱能访问任务需要的外部服务，同时防止它访问不该访问的地址、拿到不该拿到的密钥，或绕过审计。

两层出网控制

层	组件	能判断什么
L3/L4	CubeVS	IP、CIDR、DNS 学习后的目标 IP、端口和连接状态。
L7	CubeEgress	scheme、SNI、Host、HTTP method、path、header 注入和审计。

CubeVS 负责“能不能连到这个网络目标”；CubeEgress 负责“这个 HTTP/HTTPS 请求是否符合策略”。

基础配置字段

创建沙箱时可以传网络配置：

from cubesandbox import Sandbox

with Sandbox.create(
    template="<template-id>",
    allow_internet_access=False,
    network={
        "allow_out": ["api.github.com"],
        "deny_out": ["169.254.169.254/32"],
        "rules": [],
    },
) as sb:
    ...

字段	说明
allow_internet_access	是否默认允许公网出网。设为 False 时安装 deny-all 兜底。
allow_out	允许的 IP、CIDR 或域名。域名通过 DNS 学习变成临时 IP allow。
deny_out	拒绝的 IP 或 CIDR，不支持域名。
rules	HTTP/HTTPS L7 规则，由 CubeEgress 执行。

策略优先级可以先记成：allow 优先于 deny，未命中时看默认是否允许公网。

常见策略

完全禁止公网

Sandbox.create(
    template="<template-id>",
    allow_internet_access=False,
)

适合离线代码执行、受控评测、数据处理。

只允许固定域名

Sandbox.create(
    template="<template-id>",
    allow_internet_access=False,
    network={"allow_out": ["api.github.com", "*.example.com"]},
)

域名 allow-list 依赖沙箱内的 DNS 查询学习 A 记录。如果程序跳过 DNS 直接连 IP，严格模式下不会自动放行。

限制 HTTP 方法和路径

from cubesandbox import Rule, Match, Action

rules = [
    Rule(
        name="allow_llm_chat",
        match=Match(
            scheme="https",
            sni="api.example.com",
            host="api.example.com",
            method=["POST"],
            path="/v1/*",
        ),
        action=Action(allow=True, audit="metadata"),
    )
]

Sandbox.create(
    template="<template-id>",
    allow_internet_access=False,
    network={"rules": rules},
)

在严格出网模式下，L7 规则应包含 host 或 sni，这样 CubeVS 才知道要把哪个网络目标送进 CubeEgress。

凭证注入

最安全的 API Key 使用方式是：沙箱内代码不持有密钥，由 CubeEgress 在出站请求上追加 header。

from cubesandbox import Rule, Match, Action, Inject

rules = [
    Rule(
        name="deepseek_api",
        match=Match(
            scheme="https",
            sni="api.deepseek.com",
            host="api.deepseek.com",
            method=["POST"],
            path="/v1/*",
        ),
        action=Action(
            allow=True,
            audit="metadata",
            inject=[
                Inject(
                    header="Authorization",
                    format="Bearer ${SECRET}",
                    secret="sk_xxxxxxxx",
                )
            ],
        ),
    )
]

这样密钥不会进入：

• 沙箱环境变量。
• 文件系统。
• 模型上下文。
• 用户代码日志。

审计日志会记录注入行为，但不会记录密钥明文。

访问审计

CubeEgress 审计日志默认在：

/data/log/cube-egress/access.jsonl

常见字段包括时间、沙箱 IP、目的 IP/端口、host、method、path、状态码、延迟和规则名。生产环境应把这类日志纳入集中日志或 SIEM。

公开访问与 TLS

如果要让外部用户访问沙箱内的 HTTP 服务，需要理解 CubeProxy 的两种路由方式：

模式	形式	适用情况
Host-based	<port>-<sandbox_id>.<domain>	有泛域名和 TLS 配置时体验最好。
Path-based	/sandbox/<sandbox_id>/<port>/...	不方便配置泛域名时更简单。

生产暴露前至少完成：

• 鉴权。
• HTTPS 与域名解析。
• 限制公开访问。
• 网络加固。

安全学习清单

你要理解的问题	去哪里看
L3/L4 出网策略如何合并和下发	出网网络策略
CubeEgress 如何匹配请求和注入凭证	安全代理
如何避免服务裸露到公网	网络加固
如何配置 API Key	鉴权
如何限制 WebUI / CubeAPI 对外访问	限制公开访问

下一步

继续阅读 运维与排障，把安全策略和实际日志、服务状态联系起来。