nsjail-python 0.1.0__tar.gz

nsjail_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v

nsjail_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

nsjail_python-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+*.so
+_vendor/*/
+!_vendor/nsjail

nsjail_python-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "_vendor/nsjail"]
+	path = _vendor/nsjail
+	url = https://github.com/google/nsjail.git

nsjail_python-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev

nsjail_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nsjail-python contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nsjail_python-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: nsjail-python
+Version: 0.1.0
+Summary: Python wrapper for Google's nsjail sandboxing tool
+Project-URL: Homepage, https://github.com/teaguesterling/nsjail-python
+Project-URL: Documentation, https://nsjail-python.readthedocs.io
+Project-URL: Repository, https://github.com/teaguesterling/nsjail-python
+Project-URL: Issues, https://github.com/teaguesterling/nsjail-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: container,isolation,nsjail,sandbox,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: furo; extra == 'dev'
+Requires-Dist: grpcio-tools; extra == 'dev'
+Requires-Dist: protobuf>=4.0; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: sphinx; extra == 'dev'
+Provides-Extra: proto
+Requires-Dist: protobuf>=4.0; extra == 'proto'
+Description-Content-Type: text/markdown
+
+# nsjail-python
+
+Python wrapper for Google's nsjail sandboxing tool
+
+[![PyPI](https://img.shields.io/pypi/v/nsjail-python)](https://pypi.org/project/nsjail-python/)
+[![Python Version](https://img.shields.io/pypi/pyversions/nsjail-python)](https://pypi.org/project/nsjail-python/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install nsjail-python
+```
+
+Optional extras:
+
+```bash
+pip install nsjail-python[proto]   # Enable protobuf validation
+pip install nsjail-python[system]  # Use system-provided nsjail
+pip install nsjail-python[build]   # Build nsjail from source
+```
+
+## Quick Start
+
+### Low-level: NsJailConfig dataclass
+
+```python
+from nsjail import NsJailConfig, MountPt, Exe
+
+cfg = NsJailConfig(
+    hostname="sandbox",
+    time_limit=30,
+    mount=[MountPt(src="/", dst="/", is_bind=True, rw=False)],
+    exec_bin=Exe(path="/bin/sh", arg=["-c", "echo hello"]),
+)
+```
+
+### Mid-level: sandbox() preset
+
+```python
+from nsjail import sandbox
+
+cfg = sandbox(
+    command=["python", "script.py"],
+    memory_mb=512,
+    timeout_sec=60,
+    writable_dirs=["/workspace", "/tmp"],
+)
+```
+
+### High-level: Jail() fluent builder
+
+```python
+from nsjail import Jail
+
+cfg = (
+    Jail()
+    .sh("pytest tests/ -v")
+    .memory(512, "MB")
+    .timeout(60)
+    .readonly_root()
+    .writable("/workspace")
+    .writable("/tmp", tmpfs=True, size="64M")
+    .no_network()
+    .build()
+)
+```
+
+## Serialization
+
+```python
+from nsjail.serializers import to_textproto, to_cli_args, to_file
+
+# Protobuf text format (for --config flag)
+print(to_textproto(cfg))
+
+# CLI arguments
+args = to_cli_args(cfg, on_unsupported="skip")
+
+# Write to file
+to_file(cfg, "sandbox.cfg")
+```
+
+## Running nsjail
+
+```python
+from nsjail import Runner, Jail
+
+runner = Runner(
+    base_config=Jail()
+        .command("python", "-m", "pytest")
+        .memory(512, "MB")
+        .timeout(300)
+        .readonly_root()
+        .writable("/workspace")
+        .build(),
+)
+
+result = runner.run(extra_args=["tests/unit/", "-x"])
+print(result.returncode, result.stdout)
+```
+
+## Documentation
+
+Full documentation is available at [nsjail-python.readthedocs.io](https://nsjail-python.readthedocs.io).
+
+## License
+
+MIT

nsjail_python-0.1.0/README.md

@@ -0,0 +1,109 @@
+# nsjail-python
+
+Python wrapper for Google's nsjail sandboxing tool
+
+[![PyPI](https://img.shields.io/pypi/v/nsjail-python)](https://pypi.org/project/nsjail-python/)
+[![Python Version](https://img.shields.io/pypi/pyversions/nsjail-python)](https://pypi.org/project/nsjail-python/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install nsjail-python
+```
+
+Optional extras:
+
+```bash
+pip install nsjail-python[proto]   # Enable protobuf validation
+pip install nsjail-python[system]  # Use system-provided nsjail
+pip install nsjail-python[build]   # Build nsjail from source
+```
+
+## Quick Start
+
+### Low-level: NsJailConfig dataclass
+
+```python
+from nsjail import NsJailConfig, MountPt, Exe
+
+cfg = NsJailConfig(
+    hostname="sandbox",
+    time_limit=30,
+    mount=[MountPt(src="/", dst="/", is_bind=True, rw=False)],
+    exec_bin=Exe(path="/bin/sh", arg=["-c", "echo hello"]),
+)
+```
+
+### Mid-level: sandbox() preset
+
+```python
+from nsjail import sandbox
+
+cfg = sandbox(
+    command=["python", "script.py"],
+    memory_mb=512,
+    timeout_sec=60,
+    writable_dirs=["/workspace", "/tmp"],
+)
+```
+
+### High-level: Jail() fluent builder
+
+```python
+from nsjail import Jail
+
+cfg = (
+    Jail()
+    .sh("pytest tests/ -v")
+    .memory(512, "MB")
+    .timeout(60)
+    .readonly_root()
+    .writable("/workspace")
+    .writable("/tmp", tmpfs=True, size="64M")
+    .no_network()
+    .build()
+)
+```
+
+## Serialization
+
+```python
+from nsjail.serializers import to_textproto, to_cli_args, to_file
+
+# Protobuf text format (for --config flag)
+print(to_textproto(cfg))
+
+# CLI arguments
+args = to_cli_args(cfg, on_unsupported="skip")
+
+# Write to file
+to_file(cfg, "sandbox.cfg")
+```
+
+## Running nsjail
+
+```python
+from nsjail import Runner, Jail
+
+runner = Runner(
+    base_config=Jail()
+        .command("python", "-m", "pytest")
+        .memory(512, "MB")
+        .timeout(300)
+        .readonly_root()
+        .writable("/workspace")
+        .build(),
+)
+
+result = runner.run(extra_args=["tests/unit/", "-x"])
+print(result.returncode, result.stdout)
+```
+
+## Documentation
+
+Full documentation is available at [nsjail-python.readthedocs.io](https://nsjail-python.readthedocs.io).
+
+## License
+
+MIT

nsjail_python-0.1.0/_codegen/cli_flags.py

@@ -0,0 +1,73 @@
+"""Hand-maintained mapping of proto field names to CLI flags.
+
+The code generator merges this table into _field_meta.py.
+Fields not listed here are assumed to have no CLI equivalent.
+"""
+
+# (message_name, field_name) -> (cli_flag, cli_supported)
+CLI_FLAGS: dict[tuple[str, str], tuple[str, bool]] = {
+    ("NsJailConfig", "name"): ("--name", True),
+    ("NsJailConfig", "hostname"): ("--hostname", True),
+    ("NsJailConfig", "cwd"): ("--cwd", True),
+    ("NsJailConfig", "port"): ("--port", True),
+    ("NsJailConfig", "bindhost"): ("--bindhost", True),
+    ("NsJailConfig", "max_conns"): ("--max_conns", True),
+    ("NsJailConfig", "max_conns_per_ip"): ("--max_conns_per_ip", True),
+    ("NsJailConfig", "time_limit"): ("--time_limit", True),
+    ("NsJailConfig", "daemon"): ("--daemon", True),
+    ("NsJailConfig", "max_cpus"): ("--max_cpus", True),
+    ("NsJailConfig", "nice_level"): ("--nice_level", True),
+    ("NsJailConfig", "keep_env"): ("--keep_env", True),
+    ("NsJailConfig", "envar"): ("--env", True),
+    ("NsJailConfig", "silent"): ("--silent", True),
+    ("NsJailConfig", "skip_setsid"): ("--skip_setsid", True),
+    ("NsJailConfig", "stderr_to_null"): ("--stderr_to_null", True),
+    ("NsJailConfig", "pass_fd"): ("--pass_fd", True),
+    ("NsJailConfig", "disable_no_new_privs"): ("--disable_no_new_privs", True),
+    ("NsJailConfig", "forward_signals"): ("--forward_signals", True),
+    ("NsJailConfig", "disable_tsc"): ("--disable_tsc", True),
+    ("NsJailConfig", "oom_score_adj"): ("--oom_score_adj", True),
+    ("NsJailConfig", "log_fd"): ("--log_fd", True),
+    ("NsJailConfig", "log_file"): ("--log", True),
+    ("NsJailConfig", "keep_caps"): ("--keep_caps", True),
+    ("NsJailConfig", "cap"): ("--cap", True),
+    ("NsJailConfig", "rlimit_as"): ("--rlimit_as", True),
+    ("NsJailConfig", "rlimit_core"): ("--rlimit_core", True),
+    ("NsJailConfig", "rlimit_cpu"): ("--rlimit_cpu", True),
+    ("NsJailConfig", "rlimit_fsize"): ("--rlimit_fsize", True),
+    ("NsJailConfig", "rlimit_nofile"): ("--rlimit_nofile", True),
+    ("NsJailConfig", "rlimit_nproc"): ("--rlimit_nproc", True),
+    ("NsJailConfig", "rlimit_stack"): ("--rlimit_stack", True),
+    ("NsJailConfig", "disable_rl"): ("--disable_rl", True),
+    ("NsJailConfig", "clone_newnet"): (None, True),
+    ("NsJailConfig", "clone_newuser"): (None, True),
+    ("NsJailConfig", "clone_newns"): (None, True),
+    ("NsJailConfig", "clone_newpid"): (None, True),
+    ("NsJailConfig", "clone_newipc"): (None, True),
+    ("NsJailConfig", "clone_newuts"): (None, True),
+    ("NsJailConfig", "clone_newcgroup"): (None, True),
+    ("NsJailConfig", "clone_newtime"): (None, True),
+    ("NsJailConfig", "uidmap"): ("--uid_mapping", True),
+    ("NsJailConfig", "gidmap"): ("--gid_mapping", True),
+    ("NsJailConfig", "mount_proc"): ("--mount_proc", True),
+    ("NsJailConfig", "no_pivotroot"): ("--no_pivotroot", True),
+    ("NsJailConfig", "seccomp_policy_file"): ("--seccomp_policy", True),
+    ("NsJailConfig", "seccomp_string"): ("--seccomp_string", True),
+    ("NsJailConfig", "seccomp_log"): ("--seccomp_log", True),
+    ("NsJailConfig", "cgroup_mem_max"): ("--cgroup_mem_max", True),
+    ("NsJailConfig", "cgroup_mem_memsw_max"): ("--cgroup_mem_memsw_max", True),
+    ("NsJailConfig", "cgroup_mem_swap_max"): ("--cgroup_mem_swap_max", True),
+    ("NsJailConfig", "cgroup_pids_max"): ("--cgroup_pids_max", True),
+    ("NsJailConfig", "cgroup_net_cls_classid"): ("--cgroup_net_cls_classid", True),
+    ("NsJailConfig", "cgroup_cpu_ms_per_sec"): ("--cgroup_cpu_ms_per_sec", True),
+    ("NsJailConfig", "use_cgroupv2"): ("--use_cgroupv2", True),
+    ("NsJailConfig", "detect_cgroupv2"): ("--detect_cgroupv2", True),
+    ("NsJailConfig", "iface_no_lo"): ("--iface_no_lo", True),
+    ("NsJailConfig", "iface_own"): ("--iface_own", True),
+    ("NsJailConfig", "macvlan_iface"): ("--macvlan_iface", True),
+    ("NsJailConfig", "macvlan_vs_ip"): ("--macvlan_vs_ip", True),
+    ("NsJailConfig", "macvlan_vs_nm"): ("--macvlan_vs_nm", True),
+    ("NsJailConfig", "macvlan_vs_gw"): ("--macvlan_vs_gw", True),
+    ("NsJailConfig", "macvlan_vs_ma"): ("--macvlan_vs_ma", True),
+    ("NsJailConfig", "macvlan_vs_mo"): ("--macvlan_vs_mo", True),
+}