nono-py

Python bindings for nono, a capability-based sandboxing library.

nono provides OS-enforced sandboxing using Landlock (Linux) and Seatbelt (macOS). Once a sandbox is applied, unauthorized operations are structurally impossible.

Installation

pip install nono-py

From source

Requires Rust toolchain and maturin:

pip install maturin
maturin develop

Usage

from nono_py import CapabilitySet, AccessMode, apply, is_supported

# Check platform support
if not is_supported():
    print("Sandboxing not supported on this platform")
    exit(1)

# Build capability set
caps = CapabilitySet()
caps.allow_path("/tmp", AccessMode.READ_WRITE)
caps.allow_path("/home/user/project", AccessMode.READ)
caps.allow_file("/etc/hosts", AccessMode.READ)
caps.block_network()

# Apply sandbox (irreversible!)
apply(caps)

# Now the process can only access granted paths
# Network access is blocked
# This applies to all child processes too

API Reference

Sandboxing

CapabilitySet + apply()

Sandbox the current process (irreversible):

caps = CapabilitySet()
caps.allow_path("/tmp", AccessMode.READ_WRITE)
caps.block_network()
apply(caps)  # Process is now sandboxed

sandboxed_exec

Run a command in a sandboxed child process. The parent stays unsandboxed and can call this repeatedly with different capabilities:

caps = CapabilitySet()
caps.allow_path("/workspace", AccessMode.READ_WRITE)
caps.block_network()
result = sandboxed_exec(
    caps,
    ["python", "agent.py"],
    cwd="/workspace",
    timeout_secs=30.0,
)
print(result.stdout, result.exit_code)

sandboxed_exec does not inherit the parent process environment by default. Pass only the variables the child needs through env=[("NAME", "value")]. Full parent environment inheritance requires inherit_env=True; dynamic-loader variables such as LD_* and DYLD_* are rejected.

On timeout, sandboxed_exec kills the sandboxed command's process group so ordinary forked descendants are terminated with the direct child.

sandboxed_exec(..., max_processes=N) sets RLIMIT_NPROC in the child before exec. This is only meaningful when sandboxed executions run as a dedicated Unix UID, because the kernel counts all processes already owned by that real UID, not only processes in the sandbox tree. On a normal shared user account, setting a small value such as 8 can make the sandboxed program's first fork() fail with EAGAIN because the user already owns more than eight processes; it does not provide a reliable per-sandbox fork limit. Use cgroup pids.max or a dedicated container/microVM boundary for strong per-execution fork containment.

On Linux kernels before 6.7, proxy_only() uses a seccomp notification supervisor. The default listener handoff works under the unmodified Docker/containerd and AWS Fargate seccomp profile with all capabilities dropped; it does not require CAP_SYS_PTRACE, a privileged container, or a custom profile. NONO_PY_PROXY_HANDOFF=pidfd temporarily selects the one-release legacy rollback path. That legacy path may require a custom profile allowing only pidfd_getfd on ECS-EC2/EKS and is not suitable for Fargate.

For one compatibility release, sandboxed_exec(..., enforcement_mode="auto") retains the Landlock-first network behavior. Pass enforcement_mode="seccomp" to layer a static seccomp baseline under Landlock: plain block_network() denies non-Unix sockets, and policies with TCP port exceptions deny UDP, raw/non-IP sockets, and io_uring_setup(). The io_uring denial also affects programs using it only for file I/O. A future release will promote this baseline into Python's "auto" mode; "landlock" remains the explicit Landlock-only selection.

Unix-domain socket grants are trusted IPC channels. nono-py scrubs inherited descriptors before exec, but an allowed Unix peer can deliberately pass an already-connected Internet socket with SCM_RIGHTS; creation-time seccomp and Landlock connect/bind rules cannot retroactively restrict that descriptor.

Network Proxy

Domain-filtered network access for sandboxed children. The proxy intercepts outbound HTTP requests and enforces a host allowlist. For API calls, it performs credential injection: the sandboxed process sends a dummy token, and the proxy transparently swaps in the real API key (loaded from the OS keyring) before forwarding upstream. The sandboxed process never sees the real secret.

from nono_py import ProxyConfig, RouteConfig, start_proxy

config = ProxyConfig(
    allowed_hosts=["api.openai.com", "*.anthropic.com"],
    routes=[
        RouteConfig(prefix="/openai", upstream="https://api.openai.com", credential_key="openai-key"),
    ],
)
proxy = start_proxy(config)

# Inject only the current proxy/session env vars into the sandboxed child
env = proxy.sandbox_env(extra_env=[("NONO_SESSION_ID", "session-001")])
result = sandboxed_exec(caps, ["python", "agent.py"], env=env)

# Audit trail
events = proxy.drain_audit_events()
proxy.shutdown()

Filesystem Snapshots

Content-addressable snapshots with Merkle-committed state and rollback:

from nono_py import SnapshotManager, ExclusionConfig

mgr = SnapshotManager(
    session_dir="~/.nono/rollbacks/session-001",
    tracked_paths=["/workspace"],
    exclusion=ExclusionConfig(exclude_patterns=["node_modules", "__pycache__"]),
)
mgr.create_baseline()

# ... agent runs and modifies files ...

manifest, changes = mgr.create_incremental()
for change in changes:
    print(f"{change.change_type}: {change.path}")

# Roll back
mgr.restore_to(snapshot_number=0)

Audit Trail

Append-only, Merkle-chained audit logging with tamper detection:

from nono_py.audit import AlphaRecorder, verify_log, iter_session, session_started, session_ended

recorder = AlphaRecorder()
with open("audit-events.ndjson", "w") as f:
    recorder.write(f, session_started(started="2026-01-01T00:00:00Z", command=["agent"]))
    recorder.write(f, session_ended(ended="2026-01-01T00:05:00Z", exit_code=0))

# Verify integrity — detects any tampering
result = verify_log("/path/to/session")
assert result["records_verified"]

Resource Limiting

Run a command under a memory ceiling and/or a process-count cap by driving the tested nono CLI (Linux + cgroup v2):

• memory= sets memory.max: a tree that exceeds it is OOM-killed (exit 137, surfaced as result.oom_killed).
• max_processes= sets pids.max: at the cap the kernel refuses new fork/clone with EAGAIN. Nothing is killed — the offending process just fails to spawn — so there is no fixed exit code, only the command's own non-zero status.

from nono_py import AccessMode, CapabilitySet
from nono_py import limited

caps = CapabilitySet()
caps.allow_path("/work", AccessMode.READ_WRITE)

result = limited.run(caps, ["python", "hog.py"], memory="512M", max_processes=64)
if result.oom_killed:
    print("process exceeded its memory cap and was killed")
elif not result.ok:
    print(f"failed ({result.returncode}): {result.stderr}")

Enforcement lives in the nono binary (found on PATH, via NONO_BIN, or nono_bin=), not in-process — resource limits need an un-sandboxed supervisor parent, unlike apply(). Filesystem grants and block_network() are translated to CLI flags; proxy_only() is not carried across the subprocess boundary.

Other Classes

• QueryContext - Check permissions without applying the sandbox
• SandboxState - Serialize/restore capability sets as JSON
• SupportInfo - Platform support details
• Policy / ResolvedPolicy - Load and resolve policy.json documents
• SessionMetadata - Session audit trail with Merkle roots and network events
• ExecResult - Result of sandboxed_exec (stdout, stderr, exit_code)
• InjectMode - Credential injection method enum

Functions

• apply(caps) - Apply sandbox (irreversible)
• sandboxed_exec(caps, command, ...) - Run command in sandboxed child
• start_proxy(config) - Start network filtering proxy
• is_supported() / support_info() - Platform support
• load_policy(json) / load_embedded_policy() - Policy loading
• embedded_policy_json() - Raw embedded policy JSON
• validate_deny_overlaps(paths, caps) - Validate deny paths against capabilities

Platform Support

Development

# Install dev dependencies
pip install maturin pytest mypy

# Build and install for development
make dev

# Run tests
make test

# Run linters
make lint

# Format code
make fmt

License

Apache-2.0