Metadata-Version: 2.4
Name: nsjail-python
Version: 0.4.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: binary
Requires-Dist: nsjail-bin; extra == 'binary'
Provides-Extra: build
Requires-Dist: nsjail-bin-build; extra == 'build'
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'
Provides-Extra: system
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
# Core library only (expects nsjail on PATH or installed separately)
pip install nsjail-python

# Include pre-built nsjail binary (Linux x86_64/aarch64)
pip install nsjail-python[binary]

# Build nsjail from source during install (needs gcc, make, protoc, etc.)
pip install nsjail-python[build]

# Add protobuf validation support
pip install nsjail-python[proto]
```

## 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
