Cubesandbox on Fenglai

Agent (cube-agent) 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/agent/ 全量 Rust 源码目的: 系统性梳理 cube-agent (沙箱内 Guest Agent) 的架构、处理流程与安全配置每节都带文件位置证据,可以直接引用。 1. 概述 cube-agent 是每个 MicroVM sandbox 内部的 PID 1 init 进程,派生自 Kata Containers agent。它作为沙箱内所有容器的根进程,管理容器生命周期、I/O 转发、网络配置和设备热插拔。属性值语言 Rust 2021 edition 编译目标 x86_64-unknown-linux-musl (静态链接) 运行时间 tokio (多线程) 通信协议 ttrpc over vsock 协议端口 vsock:1024 (默认) OCI 运行时 rustjail (fork 隔离) 可观测性 Prometheus 指标 + OpenTelemetry vsock 导出父进程 PID 1 (init) 构建系统 Makefile + cargo (SECCOMP 可配置) 核心职责:

CubeAPI 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/07 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeAPI/ 全量 Rust 源码目的: 系统性梳理 CubeAPI (CubeSandbox 的 HTTP 网关) 的架构、处理流程与安全配置配套文档: ../安全边界/T1-cubeapi-ingress.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 CubeAPI 是 CubeSandbox 项目的 HTTP API 网关,对外提供 E2B-兼容的 REST API,让客户端能创建/查询/销毁 sandbox。属性值语言 Rust (异步运行时 tokio) Web 框架 axum + tower (HTTP 路由 / 中间件) RPC 框架 ttrpc (与下游 CubeMaster / Cubelet 通信) 依赖 (Cargo.toml) axum = "0.7", tower-http, reqwest, utoipa, tokio, seccompiler 默认监听 0.0.0.0:3000 (可通过 --bind 改) 上游服务 CubeMaster (gRPC over ttrpc) 目标兼容 E2B OpenAPI (templateID, sandboxID, envVars, metadata) 核心职责:

CubeEgress 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeEgress/ 全量 Lua + 配置目的: 系统性梳理 CubeEgress (出站透明代理) 的架构、处理流程与安全配置每节都带文件位置证据,可以直接引用。 1. 概述 CubeEgress 是 CubeSandbox 项目的出站透明代理,基于 OpenResty (nginx + LuaJIT) 构建,通过内核 TPROXY 透明地拦截来自 sandbox 的所有出站 TCP 80/443 流量并执行安全策略。属性值语言 Lua (9 模块,~1800 行) + Bash (入口/脚本) 运行时 OpenResty (nginx + LuaJIT, TPROXY 补丁) 基础镜像 openresty-tproxy (自定义 nginx 1.29.2 + TPROXY) 监听地址 192.168.0.1:8080 (HTTP) + 192.168.0.1:8443 (HTTPS MITM) 管理 API 127.0.0.1:9090/admin/v1/ 上游证书验证 proxy_ssl_verify on, 深度 4 核心职责:

Cubelet 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/Cubelet/ 全量 Go 源码目的: 系统性梳理 Cubelet (CubeSandbox 的节点代理) 的架构、处理流程与安全配置配套文档: security-boundaries/T3-cubelet.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 Cubelet 是 CubeSandbox 的节点级代理,运行在每个物理计算节点上。它是 containerd 的 fork 扩展版本,增加了 MicroVM sandboxing 支持。属性值语言 Go 1.24.8 + Rust (cubecow 存储引擎通过 CGo 链接) 运行时 containerd 扩展版 (OCI兼容) RPC 协议 ttrpc (与 CubeShim 通信) + gRPC (与 network-agent 通信) HTTP API 节点元数据上报 (与 CubeMaster) CLI 工具 cubecli (管理/调试) 存储后端 cubecow (XFS reflink 写时复制引擎) 网络后端 TAP 设备 + eBPF TC 过滤器配置 TOML 配置文件 + YAML 动态热重载核心职责:

CubeMaster 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/07 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeMaster/ 全量 Go 源码 + 配置 + 部署脚本目的: 系统性梳理 CubeMaster (CubeSandbox 的控制面 + 调度器) 的架构、处理流程与安全配置配套文档: ../安全边界/T2-operator-trust.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 CubeMaster 是 CubeSandbox 项目的控制面 + 调度中心,接收来自 CubeAPI 的 gRPC 请求,完成: 配置加载与 hotswap 热重载沙箱规格 (sandboxspec) 处理与持久化节点调度 (scheduler) 与下游 Cubelet 通信 (ttrpc) host-mount 路径白名单校验模板中心 (templatecenter) 镜像拉取元数据缓存 (Redis) 与状态存储 (MySQL) 属性值语言 Go (1.21+) RPC 框架 ttrpc (与上游 CubeAPI / 下游 Cubelet 通信) HTTP API http_port: 8089 (conf.

CubeNet 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeNet/ 全量 Go + eBPF C 源码目的: 系统性梳理 CubeNet (网络虚拟化 eBPF 数据面) 的架构、处理流程与安全配置配套文档: security-boundaries/T4-cubenet-datapath.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 CubeNet 是 CubeSandbox 的网络虚拟化与安全执行层,提供基于 eBPF 的内核态数据面,负责 sandbox 网络连接、NAT、策略执行和连接跟踪。属性值语言 Go (用户态管理) + C (eBPF 内核数据面) eBPF 库 github.com/cilium/ebpf v0.17.3 TC 管理 github.com/florianl/go-tc 网卡管理 github.com/vishvananda/netlink (间接) vmlinux bpftool BTF dump (amd64 + arm64) 用户态包 cubevs (Go library) 内核态 src/*.bpf.c (BPF TC 程序) 诊断工具 cubevsmapdump (CLI) 依赖 (go.

CubeProxy 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeProxy/ 全量 Lua + Go 源码目的: 系统性梳理 CubeProxy (数据面反向代理) 的架构、处理流程与安全配置 1. 概述 CubeProxy 是 CubeSandbox 的面向客户端的数据面反向代理，运行在 OpenResty (nginx + LuaJIT) 之上，负责将传入的 HTTP/HTTPS 请求路由到正确的 sandbox 容器后端。属性值语言 Lua (数据面) + Go (sidecar 自动暂停/恢复) 运行时 OpenResty 1.21.4.1-6-alpine-fat sidecar Go 1.25.7 静态编译 (CGO_ENABLED=0, netgo+osusergo) 监听端口 8080 (TLS) + 8081 (明文) 管理 API 127.0.0.1:8082 (状态/元数据管理) sidecar HTTP 127.0.0.1:8083 (内部恢复端点) 服务发现 Redis (cube:v1:shared:sandbox:proxy:*) sidecar 流 Redis Stream (cube:v1:shared:sandbox:lifecycle:events) 上游服务 CubeMaster (HTTP POST /cube/sandbox/update) 构建方式 Go sidecar 主机静态编译 + COPY 进 Docker 镜像核心职责:

CubeShim 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeShim/ 全量 Rust 源码目的: 系统性梳理 CubeShim (containerd Shim v2) 的架构、处理流程与安全配置配套文档: security-boundaries/T3-cubesandbox-node.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 CubeShim 是 CubeSandbox 的 containerd Shim v2 实现 (io.containerd.cube.v2),作为 containerd 与 KVM MicroVM 之间的桥梁。属性值语言 Rust 2021 edition (rust-toolchain 1.77.2) 框架 containerd-shim-rs (Shim v2 ttrpc) 依赖 (Cargo.toml) tokio, cube-hypervisor, containerd-shim, protobuf, ttrpc 二进制 containerd-shim-cube-rs (shim daemon) + cube-runtime (CLI 工具) 上游 containerd (通过 Shim v2 API) 下游 cube-agent (vsock/ttrpc) + cube-hypervisor (KVM) 核心职责:

Hypervisor (cube-hypervisor) 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/hypervisor/ 全量 Rust 源码目的: 系统性梳理 cube-hypervisor (KVM VMM) 的架构、处理流程与安全配置每节都带文件位置证据,可以直接引用。 1. 概述 cube-hypervisor 是 CubeSandbox 的 KVM 虚拟机监视器 (VMM),基于开源 Cloud Hypervisor 定制,负责任何 MicroVM 的创建、启动、暂停、恢复、快照等生命周期管理。属性值语言 Rust 2021 edition (MSRV 1.77.0) 版本 28.0.0 基础项目 Cloud Hypervisor (开源 VMM) Hypervisor KVM (x86-64 + AArch64) + 可选 MSHV CLI clap 参数解析日志 /data/log/CubeVmm/vmm.log 管理 API Unix socket HTTP REST API 程序化 API VmmInstance (mpsc 通道) 工作空间 26 个 crate 核心职责:

Network-Agent 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/network-agent/ 全量 Go 源码目的: 系统性梳理 network-agent (节点网络编排代理) 的架构、处理流程与安全配置配套文档: 暂无独立安全边界文档 (进程边界隶属于 Cubelet 节点域) 1. 概述 network-agent 是 CubeSandbox 的节点级网络编排组件,从 Cubelet 中拆分出的独立守护进程,负责管理计算节点上沙箱的 TAP 设备、IP 分配、端口代理和 eBPF 集成。属性值语言 Go 1.24.8 API 协议 HTTP + gRPC + Unix socket (SCM_RIGHTS) 健康检查 127.0.0.1:19090 IPAM CIDR 192.168.0.0/18 (默认) 端口范围 20000-29999 状态存储 JSON 文件持久化依赖 cubevs (CubeNet eBPF 库), cubelog, CubeEgress 通信 localhost loopback (Unix socket + TCP) 核心职责:

SDK (Python + Go) 架构与使用指南

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/sdk/ 全量 Python + Go 源码目的: 系统性梳理 CubeSandbox 的客户端 SDK 的架构与使用方法 1. 概述 CubeSandbox 提供 Python 和 Go 两个官方 SDK，封装了与 CubeAPI 的所有交互，包括沙箱创建、代码执行、文件操作、快照管理、模板管理等。属性 Python SDK Go SDK 包名 cubesandbox v0.3.0 github.com/tencentcloud/CubeSandbox/sdk/go 语言版本 Python >= 3.9 Go 1.22 HTTP 客户端 httpx >= 0.27 + requests net/http (标准库) API 兼容 E2B 兼容 E2B 兼容关键依赖 httpx, requests 标准库 (零外部依赖) 配置环境变量 (CUBE_*) 环境变量 (CUBE_/E2B_) 许可协议 Apache-2.0 Apache-2.0 核心职责:

WebUI (Dashboard) 架构、处理流程与安全配置

Wed, 08 Jul 2026 00:00:00 +0800

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/web/ 全量 React/TypeScript 源码目的: 系统性梳理 WebUI (管理控制台) 的架构、处理流程与安全配置每节都带文件位置证据，可以直接引用。 1. 概述 WebUI 是 CubeSandbox 的浏览器端管理控制台，基于 React 18 + TypeScript 构建，提供沙箱、模板、节点、API 密钥和集群可观测性的可视化界面。属性值语言 TypeScript (React 18) 构建工具 Vite 6 路由 react-router-dom v6 数据获取 TanStack Query v5 样式 Tailwind CSS v3 + HSL 变量 UI 组件 Radix UI (shadcn 风格) 状态管理 Zustand v5 国际化 i18next API 客户端 openapi-typescript (生成类型) Mock 工具 MSW (Mock Service Worker) 开发端口 5173 代理 Vite proxy /cubeapi → 127.

CubeSandbox 安全机制清单

Mon, 06 Jul 2026 23:21:04 +0800

调研时间: 2026/07/03

T5 CubeProxy inbound — Internet → Sandbox

Mon, 06 Jul 2026 23:20:49 +0800

一句话定位: 公网用户通过 *.cube.app 通配域名进入 CubeProxy,再反向代理到 sandbox 暴露端口的入站面。

T4 Egress — Guest → Internet

Mon, 06 Jul 2026 23:20:09 +0800

一句话定位: Guest 内 sandbox 通过 host 网络栈出到互联网 (LLM API / 第三方服务 / 模型下载) 的强制审计面。

T3 KVM CORE BOUNDARY — Host ↔ Guest

Mon, 06 Jul 2026 23:19:20 +0800

一句话定位: 整个 CubeSandbox 安全模型的基石 —— 宿主进程与 Guest OS kernel 之间的硬件级隔离面。

T2 Operator Trust — 运维 → 配置 / 镜像

Mon, 06 Jul 2026 23:18:21 +0800

一句话定位: 运维人员将可信根 (配置、镜像、模板、二进制) 注入 host 信任域的入口。

T1 CubeAPI ingress — 外部 → CubeAPI

Mon, 06 Jul 2026 23:17:46 +0800

一句话定位: 公网用户 / LLM API / 第三方服务进入 CubeSandbox 的唯一访问入口。

5.3 CVE 修复链

Sat, 04 Jul 2026 14:35:12 +0800

CubeSandbox 依赖许多 Rust crate、Linux 内核、seccomp filter、cloud-hypervisor,这些依赖项自身会有 CVE。项目通过:

5.2 日志与诊断

Sat, 04 Jul 2026 14:34:50 +0800

CubeSandbox 把日志分成:

5.1 部署前预检 (Preflight)

Sat, 04 Jul 2026 14:34:29 +0800

预检(preflight check)是部署脚本在真正安装前对 host 环境的硬约束检查。CubeSandbox 在 deploy/one-click/online-install.sh:50-180 的 checkearlyprefli

4.8 端口与服务拓扑

Sat, 04 Jul 2026 14:34:09 +0800

CubeSandbox 各组件在 host 上分配明确端口,互不冲突:

4.7 跨服务凭据

Sat, 04 Jul 2026 14:33:47 +0800

CubeSandbox 部署依赖多个组件:

4.6 WebUI 数字助理 (DB-backed session)

Sat, 04 Jul 2026 14:33:28 +0800

CubeSandbox 自带 WebUI 控制台,登入后由后端数据库(mysql/postgres)管理 session,不发 cookie,而是用 x-session-token header 携带不透明 token。

4.5 多租户隔离

Sat, 04 Jul 2026 14:33:05 +0800

CubeSandbox 的多租户基于 containerd namespaces(namespaces.WithNamespace(ctx, ns))+ tenant label + Redis keyspace 三层组合。

4.4 /health 豁免

Sat, 04 Jul 2026 14:32:46 +0800

Every request (except /health) must carry an Authorization: Bearer <token> or X-API-Key: <key> header

4.3 共享 HTTP 客户端(连接池上限)

Sat, 04 Jul 2026 14:32:26 +0800

CubeAPI 启动时创建一个全局共享的 reqwest::Client 实例,所有外部 HTTP 调用(auth callback、webhook、镜像拉取)都通过它发出。

4.2 per-API-key 速率限制

Sat, 04 Jul 2026 14:32:07 +0800

CubeSandbox 在 API 层用了 token bucket 限流,按 API key 维度分配独立配额。每条请求到来:

4.1 外部 auth callback

Sat, 04 Jul 2026 14:31:49 +0800

CubeSandbox 自身不实现 OAuth/JWT 之类的内嵌认证,而是把"是否放行"的决定委托给一个外部 HTTP 服务。每次接收请求,CubeAPI 都会把请求转发给外部 authcallbackurl,由 callback 返回

3.8 no_reaper / no_sub_reaper

Sat, 04 Jul 2026 14:31:29 +0800

Linux 进程树的"reaper"机制决定:谁负责回收"孤儿进程"(parent 死掉但子进程还活着)。在 Linux 中:

3.7 vsock 主机-客机通信

Sat, 04 Jul 2026 14:31:07 +0800

vsock 是 Linux 内核内嵌的 VM 主机-客机通信机制。它有一个独立地址族(AFVSOCK),使用 CID(contiguous identifier) 标识 host / guest:

3.6 OCI 容器兼容 (containerd-shim v2)

Sat, 04 Jul 2026 14:30:43 +0800

CubeShim 是 containerd shim v2 的实现,注册到 containerd 时 runtime type 是:

3.5 文件系统隔离 (overlayfs / virtiofs)

Sat, 04 Jul 2026 14:30:15 +0800

CubeSandbox 的文件系统层级是两层:

3.4.3 网络隔离 - TAP 设备隔离 + sysctl

Sat, 04 Jul 2026 14:29:52 +0800

这层包含两个相辅相成的组件:TAP 设备的命名/地址惯例与支持 TPROXY 的 sysctl。

3.4.2 网络隔离 - L7 透明代理 (CubeEgress)

Sat, 04 Jul 2026 14:29:28 +0800

CubeEgress 是 L7 透明代理 / HTTPS MITM,在 host 上拦截 sandbox 的 80/443 出站:

3.4.1 网络隔离 - 主机侧 eBPF (CubeVS)

Sat, 04 Jul 2026 14:29:05 +0800

CubeVS 是 CubeSandbox 的内核态 L3/L4 网络安全层。三个 eBPF 程序挂在 TC (traffic control) 钩子点,在内核态直接做策略执行,不必到 user space:

3.3 快照 / 克隆安全

Sat, 04 Jul 2026 14:28:44 +0800

CubeSandbox 的 snapshot / clone / rollback 是核心差异化特性。它基于 CubeCoW 引擎(docs/blog/posts/2026-06-03-cubesandbox-v0.3.0-snapshot

3.2 jailer / 进程隔离

Sat, 04 Jul 2026 14:28:24 +0800

Jailer 模式起源于 AWS Firecracker:把 VMM 进程(chroot 进空目录 + 切到非 root 用户 + 给新 cgroup + 加 seccomp filter + drop all caps)。这样,即使 VM

3.1 rootless / 非特权运行

Sat, 04 Jul 2026 14:28:01 +0800

Rootless 模式指 sandbox 的"模板导出"或"镜像拉取"过程不需要以 root 用户运行。CubeSandbox 通过 umoci –rootless 来导出 OCI 镜像,不需要 root 创建文件系统。

2.7 未启用的内核机制(重要!)

Sat, 04 Jul 2026 14:27:44 +0800

不是所有"听起来该用"的安全机制 CubeSandbox 都启用了。这篇列了 4 个经过调研确认未使用 / 默认 permissive 的内核机制,以及 CubeSandbox 选/不选它的原因。

2.6 审计 (Audit)

Sat, 04 Jul 2026 14:27:06 +0800

Linux Audit(CONFIGAUDIT=y)是一个内核子系统,记录系统调用、文件访问、安全决策等关键事件到 audit log(/var/log/audit/audit.log 或 netlink 转发)。CubeSandbox 内

2.5 host 启动参数硬化 (grub cmdline)

Sat, 04 Jul 2026 14:26:45 +0800

Host kernel 引导参数(grub cmdline)是内核启动时的关键开关。CubeSandbox 在 deploy/pvm/grub/hostgrubconfig.sh:18-22 中合并下列项:

2.4 Namespaces (PID/Net/Mount/UTS/IPC/User/Cgroup)

Sat, 04 Jul 2026 14:26:25 +0800

Linux namespace 把"全局唯一资源"切成多个互不可见的实例。CubeSandbox 用到的共有 7 类:

2.3 cgroups (资源限制)

Sat, 04 Jul 2026 14:26:05 +0800

cgroups(control groups)是 Linux 内核的资源计数与限制机制。把同一个 hierarchy 下的进程归到一个 cgroup,该 cgroup 的所有进程共享一套配额。典型可限制的资源:

2.2 Linux Capabilities(细粒度)

Sat, 04 Jul 2026 14:25:41 +0800

Linux 把传统 root 权限切成 40+ 个细粒度 capability(CAPCHOWN、CAPNETADMIN、CAPSYSADMIN 等)。每个进程同时持 5 个 capability set:

2.1 seccomp / seccomp-bpf (三层部署)

Sat, 04 Jul 2026 14:25:22 +0800

seccomp 是 Linux 内核的 syscall 过滤机制:

1.7 virtio Rate Limiter (TokenBucket)

Sat, 04 Jul 2026 14:24:56 +0800

TokenBucket (令牌桶) 是一种经典流量整形算法:

1.6 启动流程安全配置

Sat, 04 Jul 2026 14:24:39 +0800

Cloud-hypervisor 拉起一个 microVM 时,会把命令行参数(-append)注入到 guest kernel 的 cmdline。这些 cmdline 设置不是简单的版本号,而是一组对 guest kernel 行为的安

1.5 设备透传 (IOMMU / VFIO)

Sat, 04 Jul 2026 14:24:19 +0800

设备透传 (device passthrough) 把宿主机上的物理 PCI 设备(nic / disk)直接挂给某个 VM,VM 内能看到这块设备的真实 PCI BAR 与寄存器,而无需 hypervisor 的全设备模拟。

1.4 virtio 设备隔离

Sat, 04 Jul 2026 14:21:54 +0800

virtio 是虚拟机内最常见的"半虚拟化"IO 设备协议,CubeSandbox 中所有 guest ↔ host 数据通路(网络、磁盘、文件系统)都走 virtio。每个 virtio 设备的隔离由 3 个层面共同保证:

1.3 vCPU / 内存隔离

Sat, 04 Jul 2026 14:21:41 +0800

每个 sandbox 实例的 vCPU 数、内存大小、CPU 拓扑结构都通过 annotation cube.vmmres 显式声明,由 CubeShim 注入到 cloud-hypervisor 的 VM 配置里。三个核心要素:

1.2 独立 Guest Kernel(消除共享内核风险)

Sat, 04 Jul 2026 14:21:30 +0800

“独立 Guest Kernel” 指每个 sandbox 启动一台 microVM,VM 内运行的是专属的内核镜像(cube-guest-image-cpu.img),而不是像传统 Linux 容器那样 host kernel 通过 na

1.1 cloud-hypervisor (KVM microVM) 作主 VMM

Sat, 04 Jul 2026 14:21:19 +0800

cloud-hypervisor 是 RustVMM 基金会下的一个 KVM hypervisor,针对 microVM 场景(单租户、启动快、内存极小、安全)做了专门优化。腾讯在 CubeSandbox 中将其内部命名为 cube-hyp

CubeSandbox 安全机制详解

Sat, 04 Jul 2026 14:21:03 +0800

基于《CubeSandbox 安全机制清单.md》(2026/07/03 调研)