# google/nsjail architecture

> Architecture diagram of the GitHub repository google/nsjail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/nsjail
- Repository: https://github.com/google/nsjail

## Overview

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`](https://github.com/google/nsjail/blob/master/contain.cc) (Sandbox Setup), [`subproc.cc`](https://github.com/google/nsjail/blob/master/subproc.cc) (Subprocess Manager), [`nstun/ip.cc`](https://github.com/google/nsjail/blob/master/nstun/ip.cc) (IP Processing), [`nstun/nstun.cc`](https://github.com/google/nsjail/blob/master/nstun/nstun.cc) (NSTUN Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Configuration"]
  node_cli["CLI Parsing<br/>[cmdline.cc]"]
  node_config["Config Schema<br/>[config.proto]"]
end

subgraph group_runtime["Process Runtime"]
  node_runner["Mode Supervisor<br/>[nsjail.cc]"]
  node_subprocess["Subprocess Manager<br/>[subproc.cc]"]
end

subgraph group_isolation["Sandbox Controls"]
  node_sandbox["Sandbox Setup<br/>[contain.cc]"]
  node_mounts["Mount Setup<br/>[mnt.cc]"]
  node_mount_api["Mount API Backends<br/>[mnt_newapi.cc]"]
  node_identity["User Mapping<br/>[user.cc]"]
  node_capabilities["Capabilities<br/>[caps.cc]"]
  node_resource_limits["Resource Limits<br/>[cpu.cc]"]
  node_cgroups["Cgroup Controls<br/>[cgroup.cc]"]
  node_cgroups2["Cgroup v2<br/>[cgroup2.cc]"]
  node_seccomp["Syscall Filtering<br/>[contain.cc]"]
end

subgraph group_network["Networking"]
  node_network_setup["Network Setup<br/>[net.cc]"]
  node_nstun_runtime["NSTUN Runtime<br/>[nstun.cc]"]
  node_policy["Network Rules<br/>[policy.cc]"]
  node_ip["IP Processing<br/>[ip.cc]"]
  node_tcp["TCP Forwarding<br/>[tcp.cc]"]
  node_udp["UDP Forwarding<br/>[udp.cc]"]
  node_icmp["ICMP Handling<br/>[icmp.cc]"]
end

subgraph group_monitoring["Syscall Monitoring"]
  node_unotify["Syscall Notifications<br/>[unotify.cc]"]
  node_notify_syscalls["Notification Dispatch<br/>[syscall.cc]"]
  node_notify_stats["Notification Stats<br/>[stats.cc]"]
end

node_user(("Operator"))
node_target(("Isolated Program"))

node_user -->|"provides options"| node_cli
node_user -->|"provides config"| node_config
node_cli -->|"parses config"| node_config
node_cli -.->|"selects mode"| node_runner
node_runner -.->|"manages runs"| node_subprocess
node_subprocess -->|"starts sandbox"| node_sandbox
node_sandbox -->|"sets mounts"| node_mounts
node_mounts -.->|"uses backend"| node_mount_api
node_sandbox -->|"sets identity"| node_identity
node_sandbox -->|"sets capabilities"| node_capabilities
node_sandbox -->|"sets limits"| node_resource_limits
node_sandbox -->|"configures cgroup"| node_cgroups
node_sandbox -->|"configures v2"| node_cgroups2
node_sandbox -->|"configures filters"| node_seccomp
node_subprocess -->|"sets networking"| node_network_setup
node_network_setup -->|"initializes NSTUN"| node_nstun_runtime
node_subprocess -->|"manages NSTUN"| node_nstun_runtime
node_nstun_runtime -->|"evaluates rules"| node_policy
node_nstun_runtime -->|"processes packets"| node_ip
node_ip -->|"dispatches TCP"| node_tcp
node_ip -->|"dispatches UDP"| node_udp
node_ip -->|"dispatches ICMP"| node_icmp
node_subprocess -->|"starts notifications"| node_unotify
node_unotify -->|"dispatches events"| node_notify_syscalls
node_unotify -->|"records stats"| node_notify_stats
node_subprocess -->|"executes target"| node_target

click node_cli "https://github.com/google/nsjail/blob/master/cmdline.cc"
click node_config "https://github.com/google/nsjail/blob/master/config.proto"
click node_runner "https://github.com/google/nsjail/blob/master/nsjail.cc"
click node_subprocess "https://github.com/google/nsjail/blob/master/subproc.cc"
click node_sandbox "https://github.com/google/nsjail/blob/master/contain.cc"
click node_mounts "https://github.com/google/nsjail/blob/master/mnt.cc"
click node_mount_api "https://github.com/google/nsjail/blob/master/mnt_newapi.cc"
click node_identity "https://github.com/google/nsjail/blob/master/user.cc"
click node_capabilities "https://github.com/google/nsjail/blob/master/caps.cc"
click node_resource_limits "https://github.com/google/nsjail/blob/master/cpu.cc"
click node_cgroups "https://github.com/google/nsjail/blob/master/cgroup.cc"
click node_cgroups2 "https://github.com/google/nsjail/blob/master/cgroup2.cc"
click node_seccomp "https://github.com/google/nsjail/blob/master/contain.cc"
click node_network_setup "https://github.com/google/nsjail/blob/master/net.cc"
click node_nstun_runtime "https://github.com/google/nsjail/blob/master/nstun/nstun.cc"
click node_policy "https://github.com/google/nsjail/blob/master/nstun/policy.cc"
click node_ip "https://github.com/google/nsjail/blob/master/nstun/ip.cc"
click node_tcp "https://github.com/google/nsjail/blob/master/nstun/tcp.cc"
click node_udp "https://github.com/google/nsjail/blob/master/nstun/udp.cc"
click node_icmp "https://github.com/google/nsjail/blob/master/nstun/icmp.cc"
click node_unotify "https://github.com/google/nsjail/blob/master/unotify/unotify.cc"
click node_notify_syscalls "https://github.com/google/nsjail/blob/master/unotify/syscall.cc"
click node_notify_stats "https://github.com/google/nsjail/blob/master/unotify/stats.cc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config toneBlue
class node_runner,node_subprocess toneAmber
class node_sandbox,node_mounts,node_mount_api,node_identity,node_capabilities,node_resource_limits,node_cgroups,node_cgroups2,node_seccomp toneMint
class node_network_setup,node_nstun_runtime,node_policy,node_ip,node_tcp,node_udp,node_icmp toneRose
class node_unotify,node_notify_syscalls,node_notify_stats,node_user,node_target toneIndigo
```

## Components

### Configuration

- [CLI Parsing](https://github.com/google/nsjail/blob/master/cmdline.cc): `cmdline.cc`
- [Config Schema](https://github.com/google/nsjail/blob/master/config.proto): `config.proto`

### Process Runtime

- [Mode Supervisor](https://github.com/google/nsjail/blob/master/nsjail.cc): `nsjail.cc`
- [Subprocess Manager](https://github.com/google/nsjail/blob/master/subproc.cc): `subproc.cc`

### Sandbox Controls

- [Sandbox Setup](https://github.com/google/nsjail/blob/master/contain.cc): `contain.cc`
- [Mount Setup](https://github.com/google/nsjail/blob/master/mnt.cc): `mnt.cc`
- [Mount API Backends](https://github.com/google/nsjail/blob/master/mnt_newapi.cc): `mnt_newapi.cc`
- [User Mapping](https://github.com/google/nsjail/blob/master/user.cc): `user.cc`
- [Capabilities](https://github.com/google/nsjail/blob/master/caps.cc): `caps.cc`
- [Resource Limits](https://github.com/google/nsjail/blob/master/cpu.cc): `cpu.cc`
- [Cgroup Controls](https://github.com/google/nsjail/blob/master/cgroup.cc): `cgroup.cc`
- [Cgroup v2](https://github.com/google/nsjail/blob/master/cgroup2.cc): `cgroup2.cc`
- [Syscall Filtering](https://github.com/google/nsjail/blob/master/contain.cc): `contain.cc`

### Networking

- [Network Setup](https://github.com/google/nsjail/blob/master/net.cc): `net.cc`
- [NSTUN Runtime](https://github.com/google/nsjail/blob/master/nstun/nstun.cc): `nstun/nstun.cc`
- [Network Rules](https://github.com/google/nsjail/blob/master/nstun/policy.cc): `nstun/policy.cc`
- [IP Processing](https://github.com/google/nsjail/blob/master/nstun/ip.cc): `nstun/ip.cc`
- [TCP Forwarding](https://github.com/google/nsjail/blob/master/nstun/tcp.cc): `nstun/tcp.cc`
- [UDP Forwarding](https://github.com/google/nsjail/blob/master/nstun/udp.cc): `nstun/udp.cc`
- [ICMP Handling](https://github.com/google/nsjail/blob/master/nstun/icmp.cc): `nstun/icmp.cc`

### Syscall Monitoring

- [Syscall Notifications](https://github.com/google/nsjail/blob/master/unotify/unotify.cc): `unotify/unotify.cc`
- [Notification Dispatch](https://github.com/google/nsjail/blob/master/unotify/syscall.cc): `unotify/syscall.cc`
- [Notification Stats](https://github.com/google/nsjail/blob/master/unotify/stats.cc): `unotify/stats.cc`

### Other components

- **Operator**
- **Isolated Program**

## Connections

- Operator → CLI Parsing: provides options
- Operator → Config Schema: provides config
- CLI Parsing → Config Schema: parses config (evidence: `cmdline.cc`)
- CLI Parsing → Mode Supervisor: selects mode
- Mode Supervisor → Subprocess Manager: manages runs
- Subprocess Manager → Sandbox Setup: starts sandbox (evidence: `subproc.cc`)
- Sandbox Setup → Mount Setup: sets mounts (evidence: `contain.cc`)
- Mount Setup → Mount API Backends: uses backend
- Sandbox Setup → User Mapping: sets identity (evidence: `contain.cc`)
- Sandbox Setup → Capabilities: sets capabilities (evidence: `contain.cc`)
- Sandbox Setup → Resource Limits: sets limits (evidence: `contain.cc`)
- Sandbox Setup → Cgroup Controls: configures cgroup (evidence: `contain.cc`)
- Sandbox Setup → Cgroup v2: configures v2 (evidence: `contain.cc`)
- Sandbox Setup → Syscall Filtering: configures filters (evidence: `contain.cc`)
- Subprocess Manager → Network Setup: sets networking (evidence: `subproc.cc`)
- Network Setup → NSTUN Runtime: initializes NSTUN (evidence: `net.cc`)
- Subprocess Manager → NSTUN Runtime: manages NSTUN (evidence: `subproc.cc`)
- NSTUN Runtime → Network Rules: evaluates rules (evidence: `nstun/nstun.cc`)
- NSTUN Runtime → IP Processing: processes packets (evidence: `nstun/nstun.cc`)
- IP Processing → TCP Forwarding: dispatches TCP (evidence: `nstun/ip.cc`)
- IP Processing → UDP Forwarding: dispatches UDP (evidence: `nstun/ip.cc`)
- IP Processing → ICMP Handling: dispatches ICMP (evidence: `nstun/ip.cc`)
- Subprocess Manager → Syscall Notifications: starts notifications (evidence: `subproc.cc`)
- Syscall Notifications → Notification Dispatch: dispatches events (evidence: `unotify/unotify.cc`)
- Syscall Notifications → Notification Stats: records stats (evidence: `unotify/unotify.cc`)
- Subprocess Manager → Isolated Program: executes target