How google/nsjail works
NsJail is a Linux process-isolation tool. Users supply command-line options or a protobuf configuration, then select a one-shot, listener, direct-exec, or rerun mode; NsJail launches the target under configured namespaces, filesystem constraints, resource limits, and syscall filtering. Network isolation includes interface setup and optional NSTUN userland forwarding. The map emphasizes these documented stages and the subprocess/runtime entry point. Several subsystem links rely on README descriptions or source-index references; unsampled implementation details are not inferred.
Main entry points: contain.cc Sandbox Setup · subproc.cc Subprocess Manager · ip.cc IP Processing · nstun.cc NSTUN Runtime
Components 25
Configuration
- CLI Parsing
cmdline.cc - Config Schema
config.proto
Process Runtime
- Mode Supervisor
nsjail.cc - Subprocess Manager
subproc.cc
Sandbox Controls
- Sandbox Setup
contain.cc - Mount Setup
mnt.cc - Mount API Backends
mnt_newapi.cc - User Mapping
user.cc - Capabilities
caps.cc - Resource Limits
cpu.cc - Cgroup Controls
cgroup.cc - Cgroup v2
cgroup2.cc - Syscall Filtering
contain.cc
Networking
- Network Setup
net.cc - NSTUN Runtime
nstun/nstun.cc - Network Rules
nstun/policy.cc - IP Processing
nstun/ip.cc - TCP Forwarding
nstun/tcp.cc - UDP Forwarding
nstun/udp.cc - ICMP Handling
nstun/icmp.cc
Syscall Monitoring
- Syscall Notifications
unotify/unotify.cc - Notification Dispatch
unotify/syscall.cc - Notification Stats
unotify/stats.cc
Other components
- Operator
- Isolated Program
Connections 26
- Operator → CLI Parsing: provides options
- Operator → Config Schema: provides config
- CLI Parsing → Config Schema: parses config
cmdline.cc - CLI Parsing → Mode Supervisor: selects mode
- Mode Supervisor → Subprocess Manager: manages runs
- Subprocess Manager → Sandbox Setup: starts sandbox
subproc.cc - Sandbox Setup → Mount Setup: sets mounts
contain.cc - Mount Setup → Mount API Backends: uses backend
- Sandbox Setup → User Mapping: sets identity
contain.cc - Sandbox Setup → Capabilities: sets capabilities
contain.cc - Sandbox Setup → Resource Limits: sets limits
contain.cc - Sandbox Setup → Cgroup Controls: configures cgroup
contain.cc - Sandbox Setup → Cgroup v2: configures v2
contain.cc - Sandbox Setup → Syscall Filtering: configures filters
contain.cc - Subprocess Manager → Network Setup: sets networking
subproc.cc - Network Setup → NSTUN Runtime: initializes NSTUN
net.cc - Subprocess Manager → NSTUN Runtime: manages NSTUN
subproc.cc - NSTUN Runtime → Network Rules: evaluates rules
nstun/nstun.cc - NSTUN Runtime → IP Processing: processes packets
nstun/nstun.cc - IP Processing → TCP Forwarding: dispatches TCP
nstun/ip.cc - IP Processing → UDP Forwarding: dispatches UDP
nstun/ip.cc - IP Processing → ICMP Handling: dispatches ICMP
nstun/ip.cc - Subprocess Manager → Syscall Notifications: starts notifications
subproc.cc - Syscall Notifications → Notification Dispatch: dispatches events
unotify/unotify.cc - Syscall Notifications → Notification Stats: records stats
unotify/unotify.cc - Subprocess Manager → Isolated Program: executes target