API Reference¶

Core Model¶

class nsjail.NsJailConfig(name: 'str | None' = None, description: 'list[str]' = <factory>, mode: 'Mode' = <Mode.ONCE: 1>, hostname: 'str' = 'NSJAIL', cwd: 'str' = '/', no_pivotroot: 'bool' = False, port: 'int' = 0, bindhost: 'str' = '::', max_conns: 'int' = 0, max_conns_per_ip: 'int' = 0, time_limit: 'int' = 600, daemon: 'bool' = False, max_cpus: 'int' = 0, nice_level: 'int' = 19, log_fd: 'int | None' = None, log_file: 'str | None' = None, log_level: 'LogLevel | None' = None, keep_env: 'bool' = False, envar: 'list[str]' = <factory>, keep_caps: 'bool' = False, cap: 'list[str]' = <factory>, silent: 'bool' = False, skip_setsid: 'bool' = False, stderr_to_null: 'bool' = False, pass_fd: 'list[int]' = <factory>, disable_no_new_privs: 'bool' = False, forward_signals: 'bool' = False, disable_tsc: 'bool' = False, rlimit_as: 'int' = 4096, rlimit_as_type: 'RLimitType' = <RLimitType.VALUE: 0>, rlimit_core: 'int' = 0, rlimit_core_type: 'RLimitType' = <RLimitType.VALUE: 0>, rlimit_cpu: 'int' = 600, rlimit_cpu_type: 'RLimitType' = <RLimitType.VALUE: 0>, rlimit_fsize: 'int' = 1, rlimit_fsize_type: 'RLimitType' = <RLimitType.VALUE: 0>, rlimit_nofile: 'int' = 32, rlimit_nofile_type: 'RLimitType' = <RLimitType.VALUE: 0>, rlimit_nproc: 'int' = 1024, rlimit_nproc_type: 'RLimitType' = <RLimitType.SOFT: 1>, rlimit_stack: 'int' = 8, rlimit_stack_type: 'RLimitType' = <RLimitType.SOFT: 1>, rlimit_memlock: 'int' = 64, rlimit_memlock_type: 'RLimitType' = <RLimitType.SOFT: 1>, rlimit_rtprio: 'int' = 0, rlimit_rtprio_type: 'RLimitType' = <RLimitType.SOFT: 1>, rlimit_msgqueue: 'int' = 1024, rlimit_msgqueue_type: 'RLimitType' = <RLimitType.SOFT: 1>, disable_rl: 'bool' = False, persona_addr_compat_layout: 'bool' = False, persona_mmap_page_zero: 'bool' = False, persona_read_implies_exec: 'bool' = False, persona_addr_limit_3gb: 'bool' = False, persona_addr_no_randomize: 'bool' = False, clone_newnet: 'bool' = True, clone_newuser: 'bool' = True, clone_newns: 'bool' = True, clone_newpid: 'bool' = True, clone_newipc: 'bool' = True, clone_newuts: 'bool' = True, clone_newcgroup: 'bool' = True, clone_newtime: 'bool' = False, uidmap: 'list[IdMap]' = <factory>, gidmap: 'list[IdMap]' = <factory>, mount_proc: 'bool' = False, mount: 'list[MountPt]' = <factory>, seccomp_policy_file: 'str | None' = None, seccomp_string: 'list[str]' = <factory>, seccomp_log: 'bool' = False, cgroup_mem_max: 'int' = 0, cgroup_mem_memsw_max: 'int' = 0, cgroup_mem_swap_max: 'int' = -1, cgroup_mem_mount: 'str' = '/sys/fs/cgroup/memory', cgroup_mem_parent: 'str' = 'NSJAIL', cgroup_pids_max: 'int' = 0, cgroup_pids_mount: 'str' = '/sys/fs/cgroup/pids', cgroup_pids_parent: 'str' = 'NSJAIL', cgroup_net_cls_classid: 'int' = 0, cgroup_net_cls_mount: 'str' = '/sys/fs/cgroup/net_cls', cgroup_net_cls_parent: 'str' = 'NSJAIL', cgroup_cpu_ms_per_sec: 'int' = 0, cgroup_cpu_mount: 'str' = '/sys/fs/cgroup/cpu', cgroup_cpu_parent: 'str' = 'NSJAIL', cgroupv2_mount: 'str' = '/sys/fs/cgroup', use_cgroupv2: 'bool' = False, detect_cgroupv2: 'bool' = False, iface_no_lo: 'bool' = False, iface_own: 'list[str]' = <factory>, macvlan_iface: 'str | None' = None, macvlan_vs_ip: 'str' = '192.168.0.2', macvlan_vs_nm: 'str' = '255.255.255.0', macvlan_vs_gw: 'str' = '192.168.0.1', macvlan_vs_ma: 'str' = '', macvlan_vs_mo: 'str' = 'private', user_net: 'UserNet | None' = None, exec_bin: 'Exe | None' = None)¶

class nsjail.MountPt(src: 'str | None' = None, prefix_src_env: 'str | None' = None, src_content: 'bytes | None' = None, dst: 'str | None' = None, prefix_dst_env: 'str | None' = None, fstype: 'str | None' = None, options: 'str | None' = None, is_bind: 'bool' = False, rw: 'bool' = False, is_dir: 'bool | None' = None, mandatory: 'bool' = True, is_symlink: 'bool' = False, nosuid: 'bool' = False, nodev: 'bool' = False, noexec: 'bool' = False)¶

class nsjail.IdMap(inside_id: 'str' = '', outside_id: 'str' = '', count: 'int' = 1, use_newidmap: 'bool' = False)¶

class nsjail.Exe(path: 'str | None' = None, arg: 'list[str]' = <factory>, arg0: 'str | None' = None, exec_fd: 'bool' = False)¶

Enums¶

class nsjail.Mode(*values)¶

class nsjail.LogLevel(*values)¶

class nsjail.RLimitType(*values)¶

Builder¶

class nsjail.Jail¶

Fluent builder for NsJailConfig.

async async_run(*, runner: Runner | None = None, **run_kwargs: object) → NsJailResult¶: Execute the built config asynchronously via a Runner.

mounts(mount_list: list[MountPt]) → Jail¶: Add a list of MountPt entries to the config.

run(*, runner: Runner | None = None, **run_kwargs: object) → NsJailResult¶: Execute the built config via a Runner.

seccomp(policy: SeccompPolicy | str) → Jail¶: Add a seccomp policy. Accepts a SeccompPolicy, preset, or raw Kafel string.

Presets¶

Opinionated preset configurations and composable modifiers.

Runner¶

class nsjail.Runner(*, nsjail_path: str | None = None, base_config: NsJailConfig | None = None, render_mode: str = 'textproto', capture_output: bool = True, keep_config: bool = False, collect_cgroup_stats: bool = False, cgroup_poll_interval: float = 0.1)¶

Configurable nsjail executor with optional baked-in config.

async async_run(overrides: NsJailConfig | None = None, *, override_fields: set[str] | None = None, extra_args: list[str] | None = None, timeout: float | None = None) → NsJailResult¶: Run nsjail asynchronously.

class nsjail.NsJailResult(returncode: int, stdout: bytes, stderr: bytes, config_path: Path | None, nsjail_args: list[str], timed_out: bool, oom_killed: bool, signaled: bool, inner_returncode: int | None, cgroup_stats: CgroupStats | None = None)¶: Result of running nsjail.

Serializers¶

nsjail.serializers.to_textproto(obj: Any, indent: int = 0) → str¶

nsjail.serializers.to_cli_args(cfg: Any, *, on_unsupported: Literal['raise', 'warn', 'skip'] = 'raise') → list[str]¶

nsjail.serializers.to_file(cfg: Any, path: str | Path, *, validate: bool = False) → None¶

Seccomp¶

class nsjail.SeccompPolicy(name: str = 'policy')¶: Builder for Kafel seccomp policy strings.

nsjail.MINIMAL = <nsjail.seccomp.SeccompPolicy object>¶: Builder for Kafel seccomp policy strings.

nsjail.DEFAULT_LOG = <nsjail.seccomp.SeccompPolicy object>¶: Builder for Kafel seccomp policy strings.

nsjail.READONLY = <nsjail.seccomp.SeccompPolicy object>¶: Builder for Kafel seccomp policy strings.

Cgroup Stats¶

class nsjail.CgroupStats(memory_peak_bytes: int | None = None, memory_current_bytes: int | None = None, cpu_usage_ns: int | None = None, cpu_user_ns: int | None = None, cpu_system_ns: int | None = None, pids_current: int | None = None)¶: Resource usage stats captured from cgroup stat files.

class nsjail.cgroup.CgroupMonitor(cgroup_path: Path, poll_interval: float = 0.1, use_v2: bool = False, *, v1_memory_path: Path | None = None, v1_cpu_path: Path | None = None, v1_pids_path: Path | None = None)¶: Background thread that polls cgroup stat files.

Mount Helpers¶

nsjail.bind_tree(path: str, *, readonly: bool = True, dst: str | None = None) → list[MountPt]¶: Bind-mount a directory into the sandbox.

nsjail.bind_paths(paths: list[str], *, readonly: bool = True) → list[MountPt]¶: Bind-mount multiple directories into the sandbox.

nsjail.overlay_mount(lower: str, upper: str, work: str, dst: str) → list[MountPt]¶: Set up an overlay filesystem with read-only base and writable upper layer.

nsjail.system_libs() → list[MountPt]¶: Read-only bind mounts for common system library and binary paths.

nsjail.dev_minimal() → list[MountPt]¶: Minimal /dev entries needed by most programs.

nsjail.python_env() → list[MountPt]¶: Mount the current Python installation read-only.

nsjail.proc_mount() → list[MountPt]¶: Mount /proc filesystem.

nsjail.tmpfs_mount(path: str, *, size: str | None = None) → list[MountPt]¶: Create a tmpfs mount with optional size limit.

Jailed Execution¶

nsjail.jail_call(func: Callable, args: tuple = (), kwargs: dict | None = None, *, memory_mb: int | None = None, timeout_sec: int = 600, cpu_ms_per_sec: int | None = None, pids_max: int | None = None, network: bool = False, writable_dirs: list[str] | None = None, extra_mounts: list[MountPt] | None = None, nsjail_path: str | None = None, transport: Literal['tmpfs', 'pipe'] = 'tmpfs', python_path: str | None = None, _io_dir: Path | None = None) → Any¶

Call a function inside an nsjail sandbox.

Security note: Uses pickle for serialization between parent and child processes within the same trust domain (like multiprocessing). The sandbox is the security boundary, not pickle.

@nsjail.jailed¶: Decorator that runs the function inside an nsjail sandbox on each call.

class nsjail.JailContext(**jail_kwargs: Any)¶

Context manager for multiple sandboxed function calls.

call(func: Callable, *args: Any, **kwargs: Any) → Any¶: Call a function inside the sandbox.

Exceptions¶

class nsjail.exceptions.NsjailError¶: Base exception for all nsjail-python errors.

class nsjail.exceptions.UnsupportedCLIField(field_name: str)¶: Raised when a config field has no CLI flag equivalent.

class nsjail.exceptions.NsjailNotFound¶: Raised when the nsjail binary cannot be found.