Runbox

Overview

Runbox is a lightweight Linux sandboxing system built from scratch in C. Its main purpose is educational: to help understand and implement standard sandboxing practices, process isolation, and resource management using Linux namespaces and related features.

Table of Contents

• Features
• Prerequisites
• Build Instructions
• Usage
• Supported Flags
• Cgroups
• TODO
• License
• Contributing

Features

• User Namespace: Isolates user and group IDs for contained processes.
• PID Namespace: Provides a separate isolated process tree.
• Mount Namespace: Creates an isolated filesystem using tmpfs and mounts essential directories as read-only.
• IPC Namespace: Provides isolation for System V IPC objects (message queues, semaphores, shared memory) and POSIX message queues, giving the namespace its own independent set of IPC resources.
• UTS Namespace: Provides isolation of system identifiers like hostname and NIS domain name, giving each namespace its own values.
• Network Namespace: Runbox currently supports full network isolation (default) or no isolation (--enable-network). More advanced setups like veth pairs, custom interfaces, or controlled connectivity are planned.
• Pivot Root: Replaces the process’s root filesystem with an isolated one using pivot_root.
• Minimal Shell Environment: Launches an interactive shell inside the sandbox.
• Limited Capabilities: Drops powerful privileges (like CAP_SYS_ADMIN, CAP_NET_ADMIN) and keeps only safe defaults for basic operations.
• Seccomp: Implements a syscall allowlist filter using BPF to restrict the sandbox to essential syscalls required by the shell and filesystem operations (currently architecture-specific to aarch64).
• Cgroups v2: Uses cgroups v2 for limiting resource usage by the sandbox. Currently supports cpu, memory & pids resource limitation

Prerequisites

• Linux (tested on Ubuntu-24.04 arm64 LTS)
• GCC (or compatible C compiler)
• make

Build Instructions

make

Usage

Runbox is intended to be run from the command line. After building, you can start a sandboxed shell:

./build/runbox --enable-network --cpu=6
# You should see a shell prompt like: runbox@root:/#
# Try running commands like 'ls', 'ps', 'ipcs' etc. inside the sandbox.

This will launch a shell inside an isolated environment. The root filesystem is set to /tmp/runbox and essential binaries are bind-mounted read-only.

Supported Flags

Runbox supports several command-line flags for configuring the sandbox:

• --cpu=<value> Limit CPU quota using cgroups v2 (use 0 for "max")
• --memory=<value> Limit memory usage (supports values like 256M, 1G, or "max")
• --pids=<value> Limit maximum number of processes (use "max" for no limit)
• --enable-network Allow the sandbox to keep network access (disabled by default)

You can combine multiple flags:

./build/runbox --cpu=2 --memory=512M --pids=10 --enable-network

Cgroups

Runbox uses a dedicated delegated cgroup subtree under /sys/fs/cgroup/runbox/. Each sandbox instance creates a child cgroup for the process running as PID 1 inside the PID namespace.

Internally Runbox:

• Validates controller availability on the host
• Enables cpu, memory, and pids in cgroup.subtree_control
• Creates a per-sandbox cgroup directory
• Writes the sandbox PID to cgroup.procs
• Applies limits using cpu.max, memory.max, and pids.max

TODO

• Full network namespace support (veth pairs, virtual interfaces, controlled connectivity)
• Add support for cgroups for resource management.
• Integrate seccomp or syscall filtering.

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please open issues or pull requests for suggestions, bug reports, or improvements.

---