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, unsafe_pickle_output: bool = False, _io_dir: Path | None = None) → Any¶

Call a function inside an nsjail sandbox.

The function and its arguments are pickled into the jail (the parent is trusted, and rich callables must cross the boundary). The result is returned via a safe, non-executing JSON transport by default: nothing the jailed code writes can execute in the parent.

Because JSON is the return transport, results must be JSON-serializable. To return rich Python objects, set unsafe_pickle_output=True – but this unpickles jail-controlled bytes in the parent and is only safe when the jailed code is fully trusted (a jailed attacker can then escape the sandbox via a malicious __reduce__). Off by default; see GHSA-w6j4-3xhv-r968.

@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.