# What Technologies Does CubeSandbox Use for Sandboxing?

> Discover the technologies behind CubeSandbox's advanced sandboxing. Learn how it leverages Linux namespaces, cgroups, seccomp filters, and Cloud Hypervisor for robust security.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: deep-dive
- Published: 2026-07-05

---

**CubeSandbox implements a defense-in-depth sandboxing strategy using Linux kernel namespaces, cgroups, seccomp filters, and Cloud Hypervisor virtualization, all orchestrated through Rust libraries including rustjail and seccompiler.**

CubeSandbox is an open-source sandbox runtime developed by Tencent Cloud that isolates workloads through multiple layers of Linux kernel mechanisms and modern Rust-based libraries. Understanding what technologies are used by CubeSandbox for sandboxing reveals how the project achieves both security and performance without requiring privileged containers. This article examines the specific source files and implementation details that power its isolation layer.

## Linux Kernel Primitives for Process Isolation

### Namespace Virtualization (PID, IPC, UTS, Network, Mount)

The foundation of CubeSandbox’s process isolation lies in Linux namespaces. The `Namespace` struct in [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs) handles creation of separate **PID**, **IPC**, and **UTS** namespaces for each sandbox. These namespaces are reused across containers to provide a shared view when needed, while maintaining isolation from the host system.

The `setup_shared_namespaces` method (lines 71-84) initializes these namespaces:

```rust
// 1️⃣ Create a new sandbox and set up shared IPC/UTS namespaces
let mut sandbox = Sandbox::new(&logger)?;
sandbox.setup_shared_namespaces().await?;

```

*Source*: [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs) (lines 71-88)

### User Namespaces for Rootless Execution

When running as an unprivileged user, CubeSandbox relies on **user namespaces** to achieve root-less isolation. This capability is integrated into the same `setup_shared_namespaces` method in [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs), allowing the sandbox to map the container root user to a non-privileged host user.

### Resource Constraints with cgroups

Resource limits are enforced through the **cgroups** subsystem. Each container’s CPU set is added to the guest cgroup (`guest_cpuset`) to enforce CPU-pinning and memory limits. According to the source code in [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs) (lines 72-90), this integration ensures that sandboxed workloads cannot exceed their allocated system resources.

## System Call Filtering and Security

### Seccomp BPF Filters

To protect the host kernel, CubeSandbox generates fine-grained **seccomp** BPF filters that block unwanted system calls. The filter generation logic resides in [`hypervisor/vmm/src/seccomp_filters.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/seccomp_filters.rs), where distinct profiles are created for the VMM, API threads, and sandbox processes.

The filters are applied using the `seccompiler` crate as shown in [`hypervisor/vmm/src/lib.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/lib.rs):

```rust
// 2️⃣ Apply a seccomp filter to the VMM thread
let seccomp_filter = get_seccomp_filter(&seccomp_action, Thread::Vmm, hypervisor_type);
if !seccomp_filter.is_empty() {
    seccompiler::apply_filter(&seccomp_filter)?;
}

```

*Source*: [`hypervisor/vmm/src/lib.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/lib.rs) (lines 300-307)

### The seccompiler Crate Integration

The **seccompiler** crate generates and applies the seccomp BPF programs used throughout the system. As implemented in [`hypervisor/vmm/src/lib.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/lib.rs) (lines 24-37), this crate enables compile-time generation of syscall allow-lists, protecting the VMM and helper threads such as the signal-handler thread from exploitation.

## Container Abstraction and Virtualization

### rustjail Container Library

The **rustjail** crate provides the container abstraction layer through `BaseContainer` and `LinuxContainer` structs. Referenced in [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs) (lines 19-24), this library handles the underlying sandbox lifecycle, including creation, destruction, and PID namespace management.

### Cloud Hypervisor (KVM/Mshv)

For hardware-level isolation, CubeSandbox launches guest VMs using **Cloud Hypervisor** with KVM or Mshv backends. The `Vm::new` function in [`hypervisor/vmm/src/vm.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/vm.rs) initializes the virtual CPU, memory, and devices:

```rust
// 3️⃣ Launch the guest VM (KVM or Mshv) using Cloud‑Hypervisor
let vm = Vm::new(vmm_config, vm_config, seccomp_action, hypervisor_type)?;
vm.start()?;

```

*Source*: [`hypervisor/vmm/src/vm.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/vm.rs) (lines 30-45)

## Storage and Network Isolation

### Reflink and OverlayFS Storage

Persistent sandbox storage leverages **reflink** technology for efficient copy-on-write snapshots. The `ReflinkPool` struct in [`Cubelet/storage/pool.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/pool.rs) manages volume creation and snapshotting without duplicating data blocks:

```rust
// 5️⃣ Create a copy‑on‑write snapshot using the reflink pool
let pool = ReflinkPool::new(&base_path);
let snapshot_id = pool.create_snapshot(&sandbox_path)?;

```

*Source*: [`Cubelet/storage/pool.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/pool.rs) (lines 73-85)

### Network Namespaces and Virtual Interfaces

Network isolation is implemented through **network namespaces**, **veth** pairs, and Linux bridges. The `Network` component in [`agent/src/network.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/network.rs) creates virtual Ethernet interfaces, attaches them to bridges, and configures NAT/iptables rules for egress traffic:

```rust
// 4️⃣ Attach a network interface to the sandbox bridge
let net = Network::new();
net.create_veth_pair(&sandbox_id)?;
net.attach_to_bridge("cubesandbox0")?;

```

*Source*: [`agent/src/network.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/network.rs)

### Filesystem Isolation Mechanisms

When the underlying filesystem is not `rootfs`, CubeSandbox falls back to **chroot**-style isolation controlled by the `no_pivot_root` flag (lines 82-84 in [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs)). The system also implements `BindWatcher` to monitor bind-mount changes dynamically, and maintains a `pcimap` (lines 58-59) to translate guest PCI addresses to host-side addresses for device passthrough.

## Summary

- **Linux namespaces** (PID, IPC, UTS, network, mount) and user namespaces provide process and rootless isolation according to [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs).
- **cgroups** enforce resource limits through the `guest_cpuset` mechanism.
- **Seccomp** BPF filters generated by the `seccompiler` crate restrict system calls for the VMM and sandbox threads.
- The **rustjail** library provides the container abstraction and lifecycle management in Rust.
- **Cloud Hypervisor** (KVM/Mshv) provides hardware virtualization for guest workloads via [`hypervisor/vmm/src/vm.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/vm.rs).
- **Reflink-based storage** pools in [`Cubelet/storage/pool.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/pool.rs) enable efficient copy-on-write snapshots.
- **Network isolation** uses veth pairs, bridges, and network namespaces implemented in [`agent/src/network.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/network.rs).

## Frequently Asked Questions

### Does CubeSandbox require root privileges to run sandboxes?

No, CubeSandbox can run as an unprivileged user by leveraging **Linux user namespaces** for root-less isolation. The `setup_shared_namespaces` method in [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs) (lines 71-84) handles this mapping, allowing the container root user to operate with restricted privileges on the host.

### How does CubeSandbox prevent malicious system calls from reaching the host kernel?

CubeSandbox generates fine-grained **seccomp BPF filters** in [`hypervisor/vmm/src/seccomp_filters.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/seccomp_filters.rs) and applies them using the `seccompiler` crate. These filters explicitly allow only necessary system calls for the VMM, API threads, and sandbox processes, blocking all others before they reach the kernel.

### What hypervisor does CubeSandbox use for virtualization?

CubeSandbox uses **Cloud Hypervisor** with KVM or Mshv backends, implemented in [`hypervisor/vmm/src/vm.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/vm.rs). The `Vm::new` function initializes the virtual machine environment, providing hardware-level isolation between the guest workload and the host system.

### How does CubeSandbox handle storage snapshots efficiently?

CubeSandbox uses **reflink-aware storage pools** implemented in [`Cubelet/storage/pool.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/pool.rs) to create copy-on-write snapshots without duplicating data. The `ReflinkPool` struct manages these operations, while OverlayFS provides the layered filesystem abstraction for container root filesystems.