How CubeSandbox Provides Hardware-Level Isolation for Untrusted Code

CubeSandbox combines Linux kernel namespaces, cgroups, seccomp filtering, and optional KVM-based virtualization to create defense-in-depth isolation for running untrusted code safely.

CubeSandbox, an open-source sandboxing framework maintained by Tencent Cloud, implements hardware-level isolation for untrusted code through a multi-layered architecture that spans from kernel primitives to lightweight virtual machines. The system orchestrates containerization technologies alongside optional hardware virtualization to ensure that malicious or buggy workloads cannot compromise the host system or escape resource constraints.

Linux Kernel Isolation Primitives

CubeSandbox builds its security model on three fundamental Linux kernel mechanisms that create the initial isolation boundary before any code executes.

Namespace Isolation

The platform creates separate PID, network, mount, user, IPC, and UTS namespaces for each sandbox to prevent the workload from accessing host resources. In Cubelet/pkg/container/container.go, the implementation injects namespace context through containerd.WithSandbox to ensure process trees remain invisible to one another and the host. This isolation prevents the sandbox from seeing host processes, network interfaces, or filesystem mounts, effectively creating a private view of the operating system.

Resource Constraints with cgroups

To enforce CPU and memory limits, CubeSandbox initializes cgroup v1 or v2 controllers and pins the sandbox process to specific resource quotas. The logic in Cubelet/plugins/cube/internals/cgroup/local.go handles cgroup creation, sets hard limits on memory usage, and applies CPU share allocations. Even if untrusted code attempts exhaustive resource consumption, the cgroup boundary guarantees the workload cannot exceed its allocated CPU-shares or memory quota, protecting host stability.

Seccomp Syscall Filtering

CubeSandbox employs seccomp to whitelist only the specific system calls required by the sandboxed workload. The profile generation in Cubelet/pkg/container/seccomp/seccomp.go builds a restrictive seccomp filter from the requested syscall list and attaches it to the OCI runtime specification. This mechanism blocks any disallowed kernel operations, preventing privileged system calls that could lead to container escapes or kernel exploitation.

OCI Runtime Integration

CubeSandbox leverages the proven runc OCI runtime to launch containers within the established namespaces and cgroups. The file Cubelet/services/cubebox/runc_container_op.go generates OCI specifications, appends the seccomp and cgroup configurations, and delegates execution to containerd. This approach ensures compatibility with standard container tools while maintaining the custom isolation policies enforced by the CubeSandbox control plane.

Hardware Virtualization Layer (EnvD)

For workloads requiring true hardware boundaries, CubeSandbox optionally spins up minimal virtual machines using the EnvD project, which runs on KVM.

KVM-Based VM Creation

When a user requests hardware virtualization, the system invokes the EnvD launcher through sdk/go/envd.go, which accesses /dev/kvm to create a lightweight VM. The guest runs its own kernel with separate page tables, virtual CPUs, and memory spaces, establishing a hardware-level barrier that contains any kernel-level exploits within the VM boundary. The VM mounts a read-only root filesystem and executes user code inside its own isolated kernel environment.

Control Plane Orchestration

Higher-level lifecycle management for VM-backed sandboxes is coordinated through the CubeMaster control plane. The API definitions in CubeMaster/api/services/cubebox/v1/cubebox.pb.go expose RPCs for creating, pausing, resuming, and destroying these virtualized environments, allowing operators to manage hardware-isolated workloads at scale.

Defense in Depth: How the Layers Work Together

CubeSandbox implements a tiered security model where each layer provides a fallback if the previous boundary is compromised:

• Namespace isolation prevents visibility into host resources.
• cgroup limits enforce resource quotas regardless of process behavior.
• Seccomp restricts the attack surface by filtering dangerous syscalls.
• KVM virtualization provides a final hardware boundary that contains even kernel-level exploits.

This architecture allows most workloads to run at near-native speed using container isolation, while security-critical or highly untrusted code can trigger the heavier VM path for maximum protection.

Usage Example

The following Go SDK example demonstrates requesting a VM-backed sandbox:

import (
    "context"
    cubesandbox "github.com/TencentCloud/CubeSandbox/sdk/go"
)

func main() {
    ctx := context.Background()
    client, _ := cubesandbox.NewClient(nil)

    // Create a sandbox that runs inside a KVM VM (envd)
    sb, err := client.CreateSandbox(ctx, cubesandbox.CreateSandboxOptions{
        TemplateID: "tpl-envd", // template that enables EnvD
    })
    if err != nil { panic(err) }

    // Run a command inside the VM-backed sandbox
    out, err := sb.Files().Read(ctx, "/app/run.sh")
    // ...
}

The SDK automatically selects the VM path based on the template configuration, invoking the EnvD launcher defined in sdk/go/envd.go when hardware isolation is required.

Summary

• CubeSandbox isolates untrusted code using Linux namespaces for process and network separation, implemented in Cubelet/pkg/container/container.go.
• cgroup v1/v2 controllers enforce hard resource limits via Cubelet/plugins/cube/internals/cgroup/local.go.
• Seccomp profiles restrict system calls to a minimal whitelist, configured in Cubelet/pkg/container/seccomp/seccomp.go.
• The runc OCI runtime executes containers with these security policies through Cubelet/services/cubebox/runc_container_op.go.
• Optional KVM-based VMs via EnvD provide hardware-level isolation for maximum security, controlled through sdk/go/envd.go and the CubeMaster API.

Frequently Asked Questions

What is the difference between container isolation and VM isolation in CubeSandbox?

Container isolation uses Linux namespaces, cgroups, and seccomp to create a software boundary around the process, while VM isolation uses KVM to run the workload in a separate kernel with dedicated virtual CPUs and memory. The container path offers near-native performance suitable for most workloads, whereas the VM path provides hardware-level isolation for untrusted code that requires protection against kernel-level exploits.

How does CubeSandbox prevent container escape attacks?

CubeSandbox employs defense-in-depth by combining namespace isolation to hide host resources, seccomp filtering to block dangerous syscalls, and cgroup enforcement to limit resource exhaustion. If a container escape occurs despite these measures, the optional KVM virtualization layer acts as a final hardware boundary that prevents access to the host kernel.

Can operators customize which isolation layers are enabled?

Yes, operators define isolation policies through sandbox templates. The template configuration specifies whether to use standard container isolation or enable the EnvD VM layer, allowing flexible trade-offs between security overhead and resource usage. The Go SDK accepts these templates via the CreateSandboxOptions structure, automatically configuring the appropriate isolation stack.

Which source files handle the hardware virtualization setup?

The hardware virtualization path is initiated in sdk/go/envd.go, which interfaces with the EnvD launcher to create KVM guests. The CubeMaster control plane manages these VMs through the RPC definitions in CubeMaster/api/services/cubebox/v1/cubebox.pb.go, coordinating lifecycle operations across the distributed cluster.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}