网络

sandbox 的出站访问用 E2B SDK 的创建参数 allowInternetAccess 与 network 设置，之后用 sandbox.updateNetwork() 修改。网关把这些设置转换为 Kibotos 的网络策略决定 Workspace 的出站流量能去哪里的规则：mode、目的地规则，以及引用的 Egress 或 Resolver。新的 Workspace 默认不能访问网络。，也可以让 sandbox 的出站 TCP 经调用方自己的 SOCKS5 代理离开。

支持的接口与参数复制标题链接

应用端口的入站访问见应用端口。

出网策略复制标题链接

下面的创建参数拒绝全部出网，只放行一个网段：

const sandbox = await Sandbox.create('kibotos-minimal', {
  ...connectionOptions,
  allowInternetAccess: false,
  network: { allowOut: ['140.82.112.0/20'] },
});

connectionOptions 代表 apiKey、domain 等连接参数，写法见 E2B 兼容中的示例。

请求与策略的对应复制标题链接

网关把每个请求转换为一个策略 mode 与若干目的地规则：

拒绝全部 IPv4 指 allow_internet_access: false，或 denyOut 含 0.0.0.0/0（SDK 的 ALL_TRAFFIC）。E2B 的 sandbox 只有 IPv4 出网，这在 E2B 上就是拒绝全部出网，所以在 Kibotos 上网关同时拒绝 IPv6。

判定顺序与地址族规则见原生 API 的网络策略。

条目复制标题链接

条目写法与 E2B 相同：

• 每项一个地址或 CIDR。denyOut 不接受域名。
• 未指定地址中只接受 0.0.0.0/0，::/0 返回 400。
• 带主机位的 CIDR 按网络地址生效，getInfo() 仍回显原样。
• 两张表合计最多 256 项，网关补上的 ::/0 也计入，超出返回 400。
• 私有与特殊用途地址在 allowOut 里也放不开。被拒绝的连接立即失败，不会等到超时。

allowOut 里的域名与域名模式返回 501，能力名 network egress allowlist domains；与 E2B 一样，不带 ALL_TRAFFIC 的域名先返回 400。rules 返回 501。两者都列在不支持的能力中。

DNS复制标题链接

带 allowOut 或 denyOut 时，sandbox 的 DNS 查询仍然可用。guest 只把查询发往 node 的链路 DNS 地址，由 node 转给部署的 DNS 服务器，两张表都不影响它。

E2B 上这时 DNS 也被拒绝，除非 allowOut 包含解析服务器。

修改网络复制标题链接

与 E2B 一样，修改会整体替换出站配置，没给出的字段被清空。

• 空的修改请求清空全部条目并打开公网访问。
• 网关确认新策略已在 node 上生效后返回 204，最多等待 30 秒。
• 超时时网关返回 500，并说明修改可能已被接受。
• 并发修改返回 409。
• 修改网络不延长 sandbox 的有效期，也不更换 token。

出站代理复制标题链接

egressProxy 让 sandbox 的出站 TCP 经调用方自己的 SOCKS5 代理离开。网关把代理保存为一个 Egress调用方运营的 SOCKS5 出口代理。Workspace 的网络策略引用它之后，发往指定网段的 TCP 连接从调用方的网络离开。，在网络策略里引用它，目的网段为 0.0.0.0/0 与 ::/0。Egress 本身的含义与管理见 Egress。

下面的创建参数让出站 TCP 经一个用口令认证的代理离开：

const sandbox = await Sandbox.create('kibotos-minimal', {
  ...connectionOptions,
  network: {
    egressProxy: {
      address: 'proxy.example.com:1080',
      username: 'sandbox',
      password: process.env.PROXY_PASSWORD,
    },
  },
});

之后要修改代理时，调用 sandbox.updateNetwork({ egressProxy })，带上完整的代理设置。

代理字段复制标题链接

• SDK 2.46.1 的 egressProxy 只有这三个字段，没有 TLS 设置。网关连代理不使用 TLS。
• egressProxy 里出现其他键返回 400。

经代理的流量复制标题链接

• 转发范围：denyOut 先判定，被拒绝的连接不会到达代理；其余新建 TCP 连接全部经代理，不做私有地址的拦截，所以代理所在网络里的地址也能连到。
• 不经代理的流量：DNS 查询仍发往 node 的链路 DNS 地址，由 node 转给部署的 DNS 服务器，不经代理；其他 UDP 在 PUBLIC_INTERNET 下本来就不放行，也不经代理。到被代理目的地的 ping 被拒绝。
• 代理不可用时：连接直接失败，不回退为直连。
• 拒绝全部出网又带代理：策略不能是 DENY_ALL，网关改用 PUBLIC_INTERNET，deny 为 0.0.0.0/0 与 ::/0。全部连接仍被拒绝，只有 DNS 查询可用。

修改与清除代理复制标题链接

• 带 egressProxy 的修改原地更新这个 sandbox 的 Egress，每次都要带上口令。sandbox 原来没有代理时新建一个。
• 原地更新不改变策略的 revision。网关等这个 Egress 的新 revision 在 node 上生效后才返回 204。
• 修改不带 egressProxy 时清除代理：网关先解除引用、确认生效后再删除 Egress。
• 策略被其他客户端改成引用别的 Egress 时，网关只解除引用，不修改也不删除那个 Egress。

Egress 的清理复制标题链接

• 删除 sandbox 后，网关删除它的 Egress。
• 到期被删除的 sandbox 的 Egress，以及网关中途失败留下的 Egress，由每个网关实例每 5 分钟一次的清理删除。
• 创建不满 10 分钟的 Egress 不在清理范围内。

查询时的字段回显复制标题链接

GET /sandboxes/{id} 与列表接口返回实际生效的网络配置。在 SDK 中用 getInfo() 读取这些字段，见 Sandbox 与生命周期。

口令只写：getInfo() 与列表接口的 network.egressProxy 不含口令。

注意复制标题链接

• 目的地规则需要 ctrl 支持。ctrl 没有宣告 workspace.network_policy.destination_rules 时，带条目的请求返回 501，能力名 network egress allow and deny lists，不会退化成只按开关生效。
• 代理需要 ctrl 支持 Egress。ctrl 没有宣告 workspace.network_policy.egress.socks5 时，带 egressProxy 的请求返回 501，能力名 network egress proxy，不会退化成直连。

下一步复制标题链接

• 应用端口：访问 sandbox 里的 HTTP 与 WebSocket 服务。
• 网络策略：原生策略怎样判定一个目的地址。
• Egress：用 kibo 或原生 API 管理调用方自带的代理。