nsjail

NsJail

Linux process isolation tool using namespaces, resource limits, and seccomp-bpf syscall filters.

Features

• Multiple isolation modes: TCP listener (inetd-style), standalone single-run, continuous re-execution
• Namespace isolation: UTS, MOUNT, PID, IPC, NET, USER, CGROUPS, TIME
• Filesystem constraints: chroot(), pivot_root(), read-only mounts, custom /proc and tmpfs
• Resource limits: CPU time, memory, file descriptors, process count
• Syscall filtering: Kafel seccomp-bpf policies
• Network isolation: Cloned/isolated Ethernet interfaces, MACVLAN support, userland networking (pasta)
• Cgroup integration: Memory, PID, CPU, net_cls control (v1 and v2)
• Configuration: Protobuf-based config files or command-line arguments

Installation

Build from source

# Install dependencies (Debian/Ubuntu)
sudo apt-get install autoconf bison flex gcc g++ git libprotobuf-dev libnl-route-3-dev libtool make pkg-config protobuf-compiler

git clone https://github.com/google/nsjail.git
cd nsjail
make

Docker

docker build -t nsjail .
docker run --privileged --rm -it nsjail nsjail --user 99999 --group 99999 --chroot / -- /bin/bash

Quick Start

Basic isolated shell

./nsjail -Mo --chroot / --user 99999 --group 99999 -- /bin/bash

Network service (inetd-style)

./nsjail -Ml --port 9000 --chroot /chroot --user 99999 --group 99999 -- /bin/sh -i

Re-running process (useful for fuzzing)

./nsjail -Mr --chroot / -- /bin/echo "test"

Usage

Execution Modes

Common Options

…

Configuration Files

NsJail uses Protocol Buffers for configuration. Schema: config.proto

Example configuration

…

Load with:

./nsjail --config myconfig.cfg

Override command:

./nsjail --config myconfig.cfg -- /usr/bin/id

Example Configs

• bash-with-fake-geteuid.cfg: Bash with fake root UID
• firefox-with-net-wayland.cfg: Sandboxed Firefox with networking
• home-documents-with-xorg-no-net.cfg: Document viewer with X11, no network

Use Cases

CTF Challenge Hosting

Isolate networked services for security challenges:

./nsjail -Ml --port 8000 \
  --chroot /srv/ctf \
  --user 65534 --group 65534 \
  --time_limit 60 \
  --rlimit_as 128 \
  --rlimit_cpu 10 \
  -- /srv/ctf/challenge

Fuzzing

Continuously re-run potentially crashing programs:

./nsjail -Mr \
  --chroot / \
  --user 99999 \
  --time_limit 10 \
  --rlimit_as 512 \
  --seccomp_string 'ALLOW { ... } DEFAULT KILL' \
  -- /path/to/target @@

Desktop Application Sandboxing

Run untrusted GUI applications:

./nsjail --config configs/firefox-with-net-wayland.cfg

Minimal Environment Execution

Run program with minimal filesystem access:

./nsjail -Mo \
  -R /lib/x86_64-linux-gnu \
  -R /lib64 \
  -R /usr/bin/find \
  -R /dev/urandom \
  -- /usr/bin/find /

Advanced Features

Userland Networking (pasta)

Uses pasta for userspace networking without root privileges:

./nsjail --user 1000 --group 1000 \
  --use_pasta \
  --chroot / \
  -- /usr/bin/curl https://example.com

Or via config:

user_net {
  enable: true
  ip: "10.255.255.2"
  gw: "10.255.255.1"
  ip6: "fc00::2"
  gw6: "fc00::1"
  tcp_ports: "80,443"
  enable_dns: true
}

MACVLAN Network Isolation

Clone physical interface (requires root):

sudo ./nsjail \
  --macvlan_iface eth0 \
  --macvlan_vs_ip 192.168.1.100 \
  --macvlan_vs_nm 255.255.255.0 \
  --macvlan_vs_gw 192.168.1.1 \
  -- /bin/bash

Seccomp-bpf Filtering

Kafel policy syntax:

./nsjail --seccomp_string '
POLICY example {
  ALLOW {
    read, write, open, close,
    mmap, munmap, brk,
    exit_group
  }
  DEFAULT KILL
}
USE example DEFAULT KILL
' -- /bin/program

Cgroups Resource Control

./nsjail \
  --cgroup_mem_max $((512*1024*1024)) \
  --cgroup_pids_max 32 \
  --cgroup_cpu_ms_per_sec 800 \
  -- /bin/cpu_intensive_program

Troubleshooting

Permission Denied Errors

1. CLONE_NEWUSER required: Run with --disable_clone_newuser (requires root) or ensure user namespaces are enabled:

   bash复制

   sysctl kernel.unprivileged_userns_clone  # Should be 1

2. Mount errors: Check that /proc is not overmounted:

   bash复制

   cat /proc/mounts | grep /proc

Resource Not Available

Check available namespaces:

ls -la /proc/self/ns/

Disable unsupported namespaces (e.g., --disable_clone_newcgroup for kernel < 4.6).

Debugging

Enable verbose logging:

./nsjail -v --config myconfig.cfg

Documentation

• Configuration schema: config.proto
• Seccomp policies: Kafel documentation
• Example configs: configs/

Contact

• Mailing list: [email protected]
• Issues: GitHub Issues

This is not an official Google product.