Skip to main content

​
Jailer (Security Isolation)

The Jailer is a defense-in-depth security layer that sandboxes the shim process, inspired by Firecracker’s jailer. It provides OS-level isolation on top of hardware virtualization. Source: boxlite/src/jailer/ Key responsibilities:
  • OS-level process isolation for shim
  • Syscall filtering and sandboxing
  • Resource limit enforcement
  • Environment sanitization

​
Security Layers Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                              HOST OS                                │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                      JAILER BOUNDARY                          │  │
│  │  ┌─────────────────────────────────────────────────────────┐  │  │
│  │  │                  SHIM PROCESS (sandboxed)               │  │  │
│  │  │  ┌───────────────────────────────────────────────────┐  │  │  │
│  │  │  │              VM (libkrun/KVM)                     │  │  │  │
│  │  │  │  ┌─────────────────────────────────────────────┐  │  │  │  │
│  │  │  │  │            GUEST (untrusted)                │  │  │  │  │
│  │  │  │  └─────────────────────────────────────────────┘  │  │  │  │
│  │  │  └───────────────────────────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
Each layer provides independent protection. Even if the guest VM is compromised, the jailer boundary constrains what the shim process can do on the host.

​
Platform-Specific Isolation

Linux provides the most comprehensive set of isolation primitives:

​
Namespace Isolation

  • Mount namespace: Isolates filesystem mount points so the shim sees only its own mounts
  • PID namespace: Isolates the process ID space; the shim cannot see host processes
  • Network namespace: Isolates network interfaces and routing tables

​
Filesystem Isolation

  • Chroot/pivot_root: Restricts the shim’s view of the filesystem to a minimal directory tree
  • Prevents access to host files outside the Box’s working directory

​
Syscall Filtering

  • Seccomp BPF: Berkeley Packet Filter programs that restrict which system calls the shim process can make
  • Only the minimum required syscalls are permitted
  • Unauthorized syscalls cause the process to be killed immediately

​
Privilege Dropping

  • The shim process drops to an unprivileged user after setup
  • Prevents privilege escalation even if a vulnerability is exploited

​
Resource Limits

  • cgroups v2: Enforces CPU, memory, and I/O limits on the shim process
  • Prevents a single Box from consuming all host resources

​
Security Configuration

use boxlite::SecurityOptions;

// Maximum security (recommended for untrusted workloads)
let security = SecurityOptions::maximum();

// Custom configuration
let security = SecurityOptions {
    jailer_enabled: true,
    seccomp_enabled: true,  // Linux only
    chroot_enabled: true,   // Linux only
    close_fds: true,
    sanitize_env: true,
    resource_limits: Some(ResourceLimits::default()),
};

​
Configuration Options

OptionDescriptionPlatform
jailer_enabledEnable the jailer sandbox around the shim processAll
seccomp_enabledEnable seccomp BPF syscall filteringLinux
chroot_enabledEnable chroot/pivot_root filesystem isolationLinux
close_fdsClose inherited file descriptors in the shimAll
sanitize_envStrip environment variables before launching shimAll
resource_limitsApply CPU, memory, and I/O resource constraintsAll
Disabling the jailer or seccomp filtering reduces isolation strength. Only do so for debugging purposes in trusted development environments. Always use SecurityOptions::maximum() for untrusted workloads.

​
Threat Model

The security architecture is designed to defend against:
  • Guest escape: A compromised guest VM attempting to access the host
  • Shim exploitation: Vulnerabilities in the shim process being used to escalate privileges
  • Resource exhaustion: A Box consuming excessive host resources (CPU, memory, disk, network)
  • Information leakage: A Box accessing data from other Boxes or the host
For the complete threat model and security design rationale, see the source at boxlite/src/jailer/THREAT_MODEL.md.