nsjail-python 0.1.0__py3-none-any.whl

nsjail/enums.py

@@ -0,0 +1,27 @@
+# GENERATED from nsjail config.proto — DO NOT EDIT
+# Re-run: python -m _codegen.generate
+
+from enum import IntEnum
+
+
+class Mode(IntEnum):
+    LISTEN = 0
+    ONCE = 1
+    RERUN = 2
+    EXECVE = 3
+
+
+class LogLevel(IntEnum):
+    DEBUG = 0
+    INFO = 1
+    WARNING = 2
+    ERROR = 3
+    FATAL = 4
+
+
+class RLimitType(IntEnum):
+    VALUE = 0
+    SOFT = 1
+    HARD = 2
+    INF = 3
+

nsjail/exceptions.py

@@ -0,0 +1,29 @@
+"""Exception types for nsjail-python."""
+
+
+class NsjailError(Exception):
+    """Base exception for all nsjail-python errors."""
+
+
+class UnsupportedCLIField(NsjailError):
+    """Raised when a config field has no CLI flag equivalent."""
+
+    def __init__(self, field_name: str) -> None:
+        self.field_name = field_name
+        super().__init__(
+            f"Config field {field_name!r} has no CLI flag equivalent. "
+            f"Use textproto rendering instead, or pass on_unsupported='skip'."
+        )
+
+
+class NsjailNotFound(NsjailError):
+    """Raised when the nsjail binary cannot be found."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "nsjail binary not found. Install it via:\n"
+            "  pip install nsjail-python          # includes pre-built binary\n"
+            "  pip install nsjail-python[build]    # build from source\n"
+            "  apt-get install nsjail              # system package\n"
+            "Or specify the path: Runner(nsjail_path='/path/to/nsjail')"
+        )

nsjail/presets.py

@@ -0,0 +1,74 @@
+"""Opinionated preset configurations and composable modifiers."""
+
+from __future__ import annotations
+
+from nsjail.config import Exe, MountPt, NsJailConfig
+from nsjail.enums import Mode
+
+
+def apply_readonly_root(
+    cfg: NsJailConfig,
+    *,
+    writable: list[str] | None = None,
+) -> None:
+    cfg.mount.append(MountPt(src="/", dst="/", is_bind=True, rw=False))
+
+    for path in writable or []:
+        if path == "/tmp":
+            cfg.mount.append(
+                MountPt(dst="/tmp", fstype="tmpfs", rw=True, is_dir=True)
+            )
+        else:
+            cfg.mount.append(
+                MountPt(src=path, dst=path, is_bind=True, rw=True)
+            )
+
+
+def apply_cgroup_limits(
+    cfg: NsJailConfig,
+    *,
+    memory_mb: int | None = None,
+    cpu_ms_per_sec: int | None = None,
+    pids_max: int | None = None,
+) -> None:
+    if memory_mb is not None:
+        cfg.cgroup_mem_max = memory_mb * 1024 * 1024
+    if cpu_ms_per_sec is not None:
+        cfg.cgroup_cpu_ms_per_sec = cpu_ms_per_sec
+    if pids_max is not None:
+        cfg.cgroup_pids_max = pids_max
+
+
+def apply_seccomp_log(cfg: NsJailConfig) -> None:
+    cfg.seccomp_log = True
+
+
+def sandbox(
+    *,
+    command: list[str],
+    cwd: str = "/",
+    timeout_sec: int = 600,
+    memory_mb: int | None = None,
+    cpu_ms_per_sec: int | None = None,
+    pids_max: int | None = None,
+    network: bool = False,
+    writable_dirs: list[str] | None = None,
+) -> NsJailConfig:
+    cfg = NsJailConfig(
+        mode=Mode.ONCE,
+        cwd=cwd,
+        time_limit=timeout_sec,
+        clone_newnet=not network,
+    )
+
+    cfg.exec_bin = Exe(path=command[0], arg=command[1:])
+
+    apply_readonly_root(cfg, writable=writable_dirs)
+    apply_cgroup_limits(
+        cfg,
+        memory_mb=memory_mb,
+        cpu_ms_per_sec=cpu_ms_per_sec,
+        pids_max=pids_max,
+    )
+
+    return cfg

nsjail/runner.py

@@ -0,0 +1,274 @@
+"""Runner for executing nsjail sandboxes."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, fields as dc_fields
+from pathlib import Path
+from typing import Any
+
+from nsjail.config import NsJailConfig
+from nsjail.exceptions import NsjailNotFound
+from nsjail.serializers import to_file
+
+
+def _try_companion_binary() -> Path | None:
+    """Try to find the nsjail binary from companion packages."""
+    for module_name in ("nsjail_bin", "nsjail_bin_build"):
+        try:
+            mod = __import__(module_name)
+            return mod.binary_path()
+        except (ImportError, AttributeError, FileNotFoundError):
+            continue
+    return None
+
+
+def resolve_nsjail_path(explicit_path: str | None) -> Path:
+    """Resolve the nsjail binary path.
+
+    Precedence: explicit path > system PATH > companion package > error.
+    """
+    if explicit_path is not None:
+        return Path(explicit_path)
+
+    system = shutil.which("nsjail")
+    if system is not None:
+        return Path(system)
+
+    companion = _try_companion_binary()
+    if companion is not None:
+        return companion
+
+    raise NsjailNotFound()
+
+
+def merge_configs(
+    base: NsJailConfig,
+    overrides: NsJailConfig,
+    *,
+    override_fields: set[str],
+    extra_args: list[str] | None = None,
+) -> NsJailConfig:
+    """Merge an override config into a base config.
+
+    Scalars in override_fields replace the base value.
+    Lists in override_fields are appended.
+    extra_args are appended to exec_bin.arg.
+    """
+    merged = copy.deepcopy(base)
+
+    for f in dc_fields(NsJailConfig):
+        if f.name not in override_fields:
+            continue
+
+        override_val = getattr(overrides, f.name)
+        base_val = getattr(merged, f.name)
+
+        if isinstance(base_val, list):
+            base_val.extend(override_val)
+        else:
+            setattr(merged, f.name, override_val)
+
+    if extra_args and merged.exec_bin is not None:
+        merged.exec_bin.arg.extend(extra_args)
+
+    return merged
+
+
+@dataclass
+class NsJailResult:
+    """Result of running nsjail."""
+
+    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
+
+
+class Runner:
+    """Configurable nsjail executor with optional baked-in config."""
+
+    def __init__(
+        self,
+        *,
+        nsjail_path: str | None = None,
+        base_config: NsJailConfig | None = None,
+        render_mode: str = "textproto",
+        capture_output: bool = True,
+        keep_config: bool = False,
+    ) -> None:
+        self._nsjail_path = nsjail_path
+        self._base_config = copy.deepcopy(base_config) if base_config else NsJailConfig()
+        self._render_mode = render_mode
+        self._capture_output = capture_output
+        self._keep_config = keep_config
+
+    def _prepare_run(
+        self,
+        overrides: NsJailConfig | None,
+        override_fields: set[str] | None,
+        extra_args: list[str] | None,
+    ) -> tuple[list[str], Path | None, NsJailConfig]:
+        """Resolve binary, merge configs, and render to args.
+
+        Returns (nsjail_args, config_path, merged_cfg).
+        config_path is None when render_mode is 'cli'.
+        """
+        nsjail_bin = resolve_nsjail_path(self._nsjail_path)
+
+        if overrides is not None and override_fields:
+            cfg = merge_configs(
+                self._base_config, overrides,
+                override_fields=override_fields, extra_args=extra_args,
+            )
+        elif extra_args:
+            cfg = merge_configs(
+                self._base_config, NsJailConfig(),
+                override_fields=set(), extra_args=extra_args,
+            )
+        else:
+            cfg = copy.deepcopy(self._base_config)
+
+        config_path: Path | None = None
+        if self._render_mode == "textproto":
+            tmp = tempfile.NamedTemporaryFile(
+                mode="w", suffix=".cfg", delete=False, prefix="nsjail_"
+            )
+            config_path = Path(tmp.name)
+            to_file(cfg, config_path)
+            tmp.close()
+            nsjail_args = [str(nsjail_bin), "--config", str(config_path)]
+        else:
+            from nsjail.serializers.cli import to_cli_args
+            cli_args = to_cli_args(cfg, on_unsupported="skip")
+            nsjail_args = [str(nsjail_bin)] + cli_args
+
+        if cfg.exec_bin and self._render_mode == "cli":
+            nsjail_args.append("--")
+            nsjail_args.append(cfg.exec_bin.path)
+            nsjail_args.extend(cfg.exec_bin.arg)
+
+        return nsjail_args, config_path, cfg
+
+    def _make_result(
+        self,
+        returncode: int,
+        stdout: bytes,
+        stderr: bytes,
+        config_path: Path | None,
+        nsjail_args: list[str],
+    ) -> NsJailResult:
+        """Build an NsJailResult from raw subprocess output."""
+        timed_out = returncode == 109
+        signaled = returncode > 100 and not timed_out
+        oom_killed = returncode == 137
+
+        return NsJailResult(
+            returncode=returncode,
+            stdout=stdout,
+            stderr=stderr,
+            config_path=config_path,
+            nsjail_args=nsjail_args,
+            timed_out=timed_out,
+            oom_killed=oom_killed,
+            signaled=signaled,
+            inner_returncode=returncode if returncode < 100 else None,
+        )
+
+    def run(
+        self,
+        overrides: NsJailConfig | None = None,
+        *,
+        override_fields: set[str] | None = None,
+        extra_args: list[str] | None = None,
+        timeout: float | None = None,
+    ) -> NsJailResult:
+        nsjail_args, config_path, _cfg = self._prepare_run(overrides, override_fields, extra_args)
+
+        try:
+            result = subprocess.run(
+                nsjail_args,
+                capture_output=self._capture_output,
+                timeout=timeout,
+            )
+        finally:
+            if config_path and not self._keep_config:
+                config_path.unlink(missing_ok=True)
+                config_path = None
+
+        return self._make_result(
+            returncode=result.returncode,
+            stdout=result.stdout if self._capture_output else b"",
+            stderr=result.stderr if self._capture_output else b"",
+            config_path=config_path,
+            nsjail_args=nsjail_args,
+        )
+
+    async def async_run(
+        self,
+        overrides: NsJailConfig | None = None,
+        *,
+        override_fields: set[str] | None = None,
+        extra_args: list[str] | None = None,
+        timeout: float | None = None,
+    ) -> NsJailResult:
+        """Run nsjail asynchronously."""
+        nsjail_args, config_path, cfg = self._prepare_run(
+            overrides, override_fields, extra_args
+        )
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *nsjail_args,
+                stdout=asyncio.subprocess.PIPE if self._capture_output else None,
+                stderr=asyncio.subprocess.PIPE if self._capture_output else None,
+            )
+            if timeout is not None:
+                stdout, stderr = await asyncio.wait_for(
+                    proc.communicate(), timeout=timeout
+                )
+            else:
+                stdout, stderr = await proc.communicate()
+        finally:
+            if config_path and not self._keep_config:
+                config_path.unlink(missing_ok=True)
+                config_path = None
+
+        return self._make_result(
+            proc.returncode,
+            stdout if self._capture_output else b"",
+            stderr if self._capture_output else b"",
+            config_path,
+            nsjail_args,
+        )
+
+    def fork(
+        self,
+        *,
+        overrides: NsJailConfig | None = None,
+        override_fields: set[str] | None = None,
+        nsjail_path: str | None = None,
+    ) -> Runner:
+        if overrides and override_fields:
+            new_base = merge_configs(
+                self._base_config, overrides, override_fields=override_fields
+            )
+        else:
+            new_base = copy.deepcopy(self._base_config)
+
+        return Runner(
+            nsjail_path=nsjail_path or self._nsjail_path,
+            base_config=new_base,
+            render_mode=self._render_mode,
+            capture_output=self._capture_output,
+            keep_config=self._keep_config,
+        )

nsjail/serializers/__init__.py

@@ -0,0 +1,26 @@
+"""Serializers for NsJailConfig: textproto, CLI args, protobuf."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from nsjail.serializers.textproto import to_textproto
+from nsjail.serializers.cli import to_cli_args
+
+
+def to_file(cfg: Any, path: str | Path, *, validate: bool = False) -> None:
+    if validate:
+        try:
+            from nsjail.serializers.protobuf import to_protobuf
+        except ImportError:
+            raise ImportError(
+                "Validation requires the protobuf extra: pip install nsjail-python[proto]"
+            ) from None
+        to_protobuf(cfg)
+
+    text = to_textproto(cfg)
+    Path(path).write_text(text + "\n")
+
+
+__all__ = ["to_textproto", "to_cli_args", "to_file"]

nsjail/serializers/cli.py

@@ -0,0 +1,69 @@
+"""Serialize NsJailConfig to nsjail CLI arguments."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import fields as dc_fields
+from enum import IntEnum
+from typing import Any, Literal
+
+from nsjail._field_meta import FIELD_REGISTRY
+from nsjail.exceptions import UnsupportedCLIField
+
+logger = logging.getLogger(__name__)
+
+
+def to_cli_args(
+    cfg: Any,
+    *,
+    on_unsupported: Literal["raise", "warn", "skip"] = "raise",
+) -> list[str]:
+    args: list[str] = []
+    cls_name = type(cfg).__name__
+
+    for f in dc_fields(cfg):
+        key = (cls_name, f.name)
+        meta = FIELD_REGISTRY.get(key)
+        if meta is None:
+            continue
+
+        value = getattr(cfg, f.name)
+
+        # Skip defaults and None
+        if meta.is_repeated:
+            if not value:
+                continue
+        elif meta.is_message:
+            if value is None:
+                continue
+        else:
+            from nsjail.serializers.textproto import _is_default
+            if _is_default(value, meta):
+                continue
+
+        # Check CLI support
+        if not meta.cli_supported or meta.cli_flag is None:
+            if on_unsupported == "raise":
+                raise UnsupportedCLIField(f.name)
+            elif on_unsupported == "warn":
+                logger.warning(
+                    "Config field %r has no CLI equivalent, skipping", f.name
+                )
+            continue
+
+        # Render the field
+        if meta.is_repeated:
+            for item in value:
+                args.append(meta.cli_flag)
+                args.append(str(item))
+        elif isinstance(value, bool):
+            if value:
+                args.append(meta.cli_flag)
+        elif isinstance(value, IntEnum):
+            args.append(meta.cli_flag)
+            args.append(str(int(value)))
+        else:
+            args.append(meta.cli_flag)
+            args.append(str(value))
+
+    return args

nsjail/serializers/protobuf.py

@@ -0,0 +1,22 @@
+"""Convert NsJailConfig dataclass to compiled protobuf message.
+
+Requires the [proto] extra: pip install nsjail-python[proto]
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.protobuf import text_format
+
+from nsjail.serializers.textproto import to_textproto
+
+
+def to_protobuf(cfg: Any) -> Any:
+    """Convert a NsJailConfig to a compiled protobuf message."""
+    from nsjail._proto import config_pb2
+
+    text = to_textproto(cfg)
+    msg = config_pb2.NsJailConfig()
+    text_format.Parse(text, msg)
+    return msg

nsjail/serializers/textproto.py

@@ -0,0 +1,91 @@
+"""Pure Python serializer for protobuf text format."""
+
+from __future__ import annotations
+
+from dataclasses import fields as dc_fields
+from enum import IntEnum
+from typing import Any
+
+from nsjail._field_meta import FIELD_REGISTRY, FieldMeta
+
+
+def to_textproto(obj: Any, indent: int = 0) -> str:
+    lines: list[str] = []
+    prefix = "  " * indent
+    cls_name = type(obj).__name__
+
+    for f in dc_fields(obj):
+        key = (cls_name, f.name)
+        meta = FIELD_REGISTRY.get(key)
+        if meta is None:
+            continue
+
+        value = getattr(obj, f.name)
+
+        if meta.is_repeated:
+            if not value:
+                continue
+            if meta.is_message:
+                for item in value:
+                    lines.append(f"{prefix}{f.name} {{")
+                    inner = to_textproto(item, indent + 1)
+                    if inner.strip():
+                        lines.append(inner)
+                    lines.append(f"{prefix}}}")
+            else:
+                for item in value:
+                    lines.append(f"{prefix}{f.name}: {_format_scalar(item, meta)}")
+        elif meta.is_message:
+            if value is None:
+                continue
+            lines.append(f"{prefix}{f.name} {{")
+            inner = to_textproto(value, indent + 1)
+            if inner.strip():
+                lines.append(inner)
+            lines.append(f"{prefix}}}")
+        else:
+            if _is_default(value, meta):
+                continue
+            lines.append(f"{prefix}{f.name}: {_format_scalar(value, meta)}")
+
+    return "\n".join(lines)
+
+
+def _is_default(value: Any, meta: FieldMeta) -> bool:
+    if value is None and meta.default is None:
+        return True
+    if value is None:
+        return False
+    if meta.default is None:
+        return False
+    if isinstance(value, IntEnum):
+        return int(value) == meta.default
+    return value == meta.default
+
+
+def _format_scalar(value: Any, meta: FieldMeta) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, IntEnum):
+        return value.name
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, str):
+        return f'"{_escape_string(value)}"'
+    if isinstance(value, bytes):
+        return f'"{_escape_bytes(value)}"'
+    return str(value)
+
+
+def _escape_string(s: str) -> str:
+    return s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+def _escape_bytes(b: bytes) -> str:
+    parts: list[str] = []
+    for byte in b:
+        if 32 <= byte < 127 and byte != ord("\\") and byte != ord('"'):
+            parts.append(chr(byte))
+        else:
+            parts.append(f"\\x{byte:02x}")
+    return "".join(parts)