postern 0.1.0__py3-none-any.whl

postern/__init__.py

@@ -0,0 +1,36 @@
+"""postern — untrusted code in a sealed sandbox with one typed doorway.
+
+Run untrusted Python in an OS-isolated `Sandbox` (bubblewrap: empty network
+namespace, surgical filesystem, dropped capabilities, seccomp) whose *only*
+interface to the outside is a hatch — host-provided gRPC methods, gated by an
+allowlist, that the guest calls with the generated stub. The security boundary
+is that method set, not a coarse permission flag.
+
+    from postern import Sandbox, SandboxProfile
+    from postern.grpc import GrpcHatch
+    import greeter_pb2_grpc
+
+    hatch = GrpcHatch(allowlist={'/greeter.Greeter/SayHello'})
+    hatch.add_servicer(greeter_pb2_grpc.add_GreeterServicer_to_server, MyGreeter())
+
+    profile = SandboxProfile.with_venv('/opt/analysis-env')   # pandas, grpcio, stubs
+    Sandbox(profile, hatch=hatch).run_python(guest_code)
+
+The bare `Sandbox` has no third-party dependencies and no cloud dependency — it
+is a Linux + bubblewrap primitive. The gRPC hatch lives behind the ``grpc``
+extra; provider/runtime adapters behind their own.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from postern._sandbox import IsolationError, ProcResult, Sandbox, SandboxProfile, available
+
+try:
+    __version__ = importlib.metadata.version('postern')
+except importlib.metadata.PackageNotFoundError:
+    # Running from a source tree without an install.
+    __version__ = '0.0.0+unknown'
+
+__all__ = ['IsolationError', 'ProcResult', 'Sandbox', 'SandboxProfile', '__version__', 'available']

postern/_guest.py

@@ -0,0 +1,32 @@
+"""In-sandbox entrypoint for `Sandbox.run_python`.
+
+Runs *inside* the bubblewrap sandbox, so it is stdlib-only. It applies the
+process-count limit (a fork-bomb backstop set here rather than via a fork-time
+callback in the host) and then execs the guest code.
+
+The guest reaches the hatch by dialing the bound Unix socket with an ordinary
+gRPC channel + the generated stub — that machinery lives in the guest's own
+environment, not here. The socket path is exported as ``POSTERN_HATCH``.
+"""
+
+import os
+import resource
+import sys
+
+
+def main() -> None:
+    nproc = int(os.environ.get('POSTERN_NPROC') or 0)
+    if nproc:
+        resource.setrlimit(resource.RLIMIT_NPROC, (nproc, nproc))
+    # Address-space backstop: a partial guard against a memory bomb starving the
+    # co-located trusted worker (F3). It is per-process, not a true total-memory
+    # bound — a cgroup memory.max set by the worker/deploy is the real fix.
+    as_bytes = int(os.environ.get('POSTERN_AS') or 0)
+    if as_bytes:
+        resource.setrlimit(resource.RLIMIT_AS, (as_bytes, as_bytes))
+    code = os.environ.get('POSTERN_CODE', '')
+    exec(code, {'__name__': '__main__'})  # noqa: S102 — executing guest code is the whole point
+
+
+if __name__ == '__main__':
+    sys.exit(main())

postern/_sandbox.py

@@ -0,0 +1,348 @@
+"""The hardened isolation core: a bubblewrap-launched sandbox.
+
+`Sandbox` runs a program (or a snippet of Python) under bubblewrap with the
+hardened profile: an empty network namespace (no egress at all), a surgical
+read-only view of the base system directories plus one writable workspace,
+`--cap-drop ALL`, `--new-session`, a seccomp denylist, and an `RLIMIT_NPROC`
+fork-bomb backstop. The guest's only channel to the outside is whatever
+`Hatch` the caller binds in — nothing else is reachable.
+
+The base system directories come from the host by default, or from a curated
+``rootfs`` directory (a minimal base assembled at image-build time) — the latter
+hides the host's userland entirely. The Python environment the guest runs
+against is a read-only bind (`SandboxProfile.with_venv`), never installed at
+run time (there is no egress to install from).
+
+Linux + bubblewrap + unprivileged user namespaces only. :func:`available`
+reports whether the runtime can launch here.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import dataclasses
+import os
+import pathlib
+import shutil
+import subprocess
+import tempfile
+import typing
+from collections.abc import Sequence
+
+from postern import _seccomp
+
+if typing.TYPE_CHECKING:
+    # `typing.Self` is 3.11+, but postern supports 3.10; the backport is
+    # type-check-only (guarded here), so the runtime stays dependency-free.
+    from typing_extensions import Self
+
+_GUEST_DIR = '/run/postern'
+_GUEST_SOCK = f'{_GUEST_DIR}/hatch.sock'
+_GUEST_SHIM = f'{_GUEST_DIR}/_guest.py'
+_GUEST_STUBS = f'{_GUEST_DIR}/stubs'
+_GUEST_WORKSPACE = '/workspace'
+_SHIM_SRC = str(pathlib.Path(__file__).with_name('_guest.py'))
+_SYSTEM_DIRS = ('/usr', '/lib', '/lib64', '/bin', '/sbin')
+
+
+class Hatch(typing.Protocol):
+    """What `Sandbox` needs of a hatch: a UDS path and a serving context."""
+
+    @property
+    def socket_path(self) -> str: ...
+
+    def accepting(self) -> contextlib.AbstractContextManager[typing.Any]: ...
+
+
+def available() -> bool:
+    """Whether a sandbox can launch here (bubblewrap present on the PATH)."""
+    return shutil.which('bwrap') is not None
+
+
+class IsolationError(RuntimeError):
+    """A boot-time isolation self-test found a load-bearing control unenforced.
+
+    Raised by :meth:`Sandbox.verify`. It exists so a worker can *fail closed* at
+    startup — refuse to serve — rather than silently run untrusted code with
+    weaker isolation than intended (the F1/F5 silent-degradation risk).
+    """
+
+
+@dataclasses.dataclass
+class ProcResult:
+    """The outcome of one guest run."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+@dataclasses.dataclass
+class SandboxProfile:
+    """The hardened bubblewrap profile. Defaults are the secure baseline.
+
+    Attributes:
+        workspace: Host directory bound read-write at ``/workspace`` (the guest's
+            cwd), persisting across calls for the Sandbox's lifetime and readable
+            from the host (e.g. to checkpoint). ``None`` makes the Sandbox create
+            a private temp dir (removed on ``close()``); pass a path to own its
+            location and lifetime.
+        rootfs: A curated base directory whose ``/usr``, ``/lib`` … are bound as
+            the guest's system dirs. ``None`` binds the *host's* system dirs —
+            convenient for dev but exposes the host userland read-only; point at
+            a minimal rootfs (assembled at build time) to hide it.
+        python: Interpreter argv0 for :meth:`Sandbox.run_python` (an absolute
+            path when it lives in a bound venv).
+        ro_binds: Extra ``(host, guest)`` read-only binds beyond the base system
+            dirs — e.g. a venv (see :meth:`with_venv`).
+        stubs: Importable modules to inject at ``/run/postern/stubs`` (added to
+            the guest's ``PYTHONPATH``) — a directory, or a list of individual
+            files. Lets one shared rootfs carry the heavy base while per-agent
+            gRPC stubs are bound in selectively (kept in lockstep with the hatch
+            allowlist).
+        env: Environment for the guest (``--clearenv`` wipes everything first).
+        seccomp: Load the syscall denylist.
+        rlimit_nproc: Per-run process-count cap (fork-bomb backstop).
+        rlimit_as: Per-process address-space cap in bytes (memory-bomb backstop),
+            applied by the guest shim. ``None`` leaves it unlimited. This is a
+            *partial* guard — it bounds one process, not the guest's total
+            memory; a cgroup ``memory.max`` set by the worker/deploy is the real
+            isolation from the co-located trusted worker (F3). Leave it unset for
+            legitimately memory-hungry workloads and rely on the cgroup.
+        guest_uid: uid the guest runs as (``--uid``). Defaults to ``65534``
+            (nobody) so the guest is **non-root inside its user namespace** —
+            defusing a seccomp-gap namespace/cap re-acquisition (F2) and, when
+            run as root, dropping to a non-root real uid even if the user
+            namespace silently fails to materialise (F1's degraded case). The
+            guest's ``/workspace`` and ``/tmp`` are made writable to suit; a
+            caller-owned ``workspace`` dir is chmod'd world-writable at launch so
+            the non-root guest can use it. ``None`` keeps the legacy uid-0-in-
+            userns behaviour.
+        guest_gid: gid the guest runs as (``--gid``). Defaults to ``65534``.
+            ``None`` leaves the gid unset.
+    """
+
+    workspace: pathlib.Path | None = None
+    rootfs: pathlib.Path | None = None
+    python: str = 'python3'
+    ro_binds: list[tuple[str, str]] = dataclasses.field(default_factory=list)
+    stubs: str | os.PathLike[str] | Sequence[str | os.PathLike[str]] | None = None
+    env: dict[str, str] = dataclasses.field(default_factory=lambda: {'PATH': '/usr/local/bin:/usr/bin:/bin'})
+    seccomp: bool = True
+    rlimit_nproc: int = 1024
+    rlimit_as: int | None = None
+    guest_uid: int | None = 65534
+    guest_gid: int | None = 65534
+
+    @classmethod
+    def with_venv(cls, venv: str | pathlib.Path, **kwargs: typing.Any) -> SandboxProfile:  # noqa: ANN401
+        """A profile that binds ``venv`` read-only and runs its interpreter.
+
+        The venv is bound at its own path so the interpreter's `pyvenv.cfg` /
+        `site.py` resolution finds its site-packages unchanged. Pass ``rootfs``
+        through ``kwargs`` to also hide the host userland.
+        """
+        path = pathlib.Path(venv).resolve()
+        binds = [*kwargs.pop('ro_binds', []), (str(path), str(path))]
+        return cls(python=str(path / 'bin' / 'python'), ro_binds=binds, **kwargs)
+
+
+def build_base_argv(profile: SandboxProfile, seccomp_fd: int | None) -> list[str]:
+    """The bwrap flags for ``profile`` (excluding the trailing ``-- argv``)."""
+    root = str(profile.rootfs) if profile.rootfs is not None else ''
+    # --unshare-all leaves the user and cgroup namespaces *best-effort*
+    # (--unshare-user-try / --unshare-cgroup-try): if the kernel can't provide a
+    # user namespace, bwrap silently continues WITHOUT one and the guest runs as
+    # real root (F1's silent degradation). Re-list them strict so a missing
+    # namespace is a hard launch failure instead — bwrap's own docs say to use
+    # --unshare-user if you rely on it for security. --unshare-all still supplies
+    # the strict ipc/pid/net/uts (and any namespace it gains in future versions).
+    argv = ['bwrap', '--unshare-all', '--unshare-user', '--unshare-cgroup']
+    argv += ['--new-session', '--cap-drop', 'ALL', '--die-with-parent', '--clearenv']
+    # Run the guest as a non-root uid/gid (F2): inside the userns it then holds
+    # no capabilities to re-gain namespaces through a seccomp gap, and if the
+    # userns silently fails to materialise (F1) a root host still drops to a
+    # non-root real uid rather than running the guest as real root.
+    if profile.guest_uid is not None:
+        argv += ['--uid', str(profile.guest_uid)]
+    if profile.guest_gid is not None:
+        argv += ['--gid', str(profile.guest_gid)]
+    for d in _SYSTEM_DIRS:
+        # /usr is mandatory (plain --ro-bind); the rest are ``-try`` so a path
+        # absent on this base (e.g. /lib64) is skipped, not fatal.
+        flag = '--ro-bind' if d == '/usr' else '--ro-bind-try'
+        argv += [flag, root + d, d]
+    argv += ['--ro-bind-try', root + '/etc/ld.so.cache', '/etc/ld.so.cache']
+    for host, guest in profile.ro_binds:
+        argv += ['--ro-bind-try', host, guest]
+    # '/tmp' is the guest's in-sandbox mountpoint (a fresh tmpfs), not a host
+    # path; '--perms 1777' gives it the sticky world-writable mode a non-root
+    # guest needs (and that a real /tmp has anyway).
+    argv += ['--proc', '/proc', '--dev', '/dev', '--perms', '1777', '--tmpfs', '/tmp']  # noqa: S108
+    if profile.workspace is not None:
+        argv += ['--bind', str(profile.workspace), _GUEST_WORKSPACE]
+    else:
+        argv += ['--perms', '1777', '--tmpfs', _GUEST_WORKSPACE]
+    argv += ['--chdir', _GUEST_WORKSPACE]
+    env = dict(profile.env)
+    if profile.stubs is not None:
+        argv += _stub_binds(profile.stubs)
+        prior = env.get('PYTHONPATH')
+        env['PYTHONPATH'] = _GUEST_STUBS if not prior else f'{_GUEST_STUBS}:{prior}'
+    for key, val in env.items():
+        argv += ['--setenv', key, val]
+    if seccomp_fd is not None:
+        argv += ['--seccomp', str(seccomp_fd)]
+    return argv
+
+
+def _stub_binds(stubs: str | os.PathLike[str] | Sequence[str | os.PathLike[str]]) -> list[str]:
+    """Bwrap flags injecting importable stubs at ``/run/postern/stubs``.
+
+    A directory is bound whole; a sequence of files is bound each to its
+    basename under the stubs dir (so a common rootfs can carry the base while
+    the per-service stubs are injected selectively).
+    """
+    if isinstance(stubs, (str, os.PathLike)):
+        return ['--ro-bind', os.fspath(stubs), _GUEST_STUBS]
+    binds: list[str] = []
+    for entry in stubs:
+        path = os.fspath(entry)
+        binds += ['--ro-bind', path, f'{_GUEST_STUBS}/{pathlib.Path(path).name}']
+    return binds
+
+
+class Sandbox:
+    """A hardened bubblewrap sandbox with an optional typed :class:`Hatch`."""
+
+    def __init__(self, profile: SandboxProfile | None = None, *, hatch: Hatch | None = None) -> None:
+        self._profile = profile or SandboxProfile()
+        self._hatch = hatch
+        # The workspace persists for this Sandbox's lifetime and is bound
+        # read-write at /workspace (the guest's cwd). An explicit profile path is
+        # caller-owned; otherwise a private temp dir is created here and removed
+        # on close(). Either way the host can read it between calls (e.g. to
+        # checkpoint) via the ``workspace`` property.
+        if self._profile.workspace is not None:
+            self._workspace = pathlib.Path(self._profile.workspace)
+            self._own_workspace = False
+            self._workspace.mkdir(parents=True, exist_ok=True)
+        else:
+            self._workspace = pathlib.Path(tempfile.mkdtemp(prefix='postern-ws-'))
+            self._own_workspace = True
+
+    @property
+    def workspace(self) -> pathlib.Path:
+        """The host directory bound read-write at ``/workspace`` (the guest cwd)."""
+        return self._workspace
+
+    def _launch(
+        self,
+        argv: list[str],
+        *,
+        timeout: float,
+        setenv: dict[str, str] | None = None,
+        extra_binds: list[str] | None = None,
+    ) -> ProcResult:
+        if not available():
+            raise RuntimeError('bubblewrap (bwrap) not found on PATH; postern requires Linux + bubblewrap')
+        # A non-root guest cannot write a workspace dir owned by (and mode-locked
+        # to) the host user, so open it up. The dir is private to this single-
+        # tenant sandbox, so world-writable is immaterial (see F9).
+        if self._profile.guest_uid not in (None, 0):
+            with contextlib.suppress(OSError):
+                self._workspace.chmod(0o777)
+        seccomp = _seccomp.load_filter() if self._profile.seccomp else None
+        fd = seccomp.fileno() if seccomp is not None else None
+        try:
+            cmd = build_base_argv(dataclasses.replace(self._profile, workspace=self._workspace), fd)
+            for key, val in (setenv or {}).items():
+                cmd += ['--setenv', key, val]
+            cmd += extra_binds or []
+            cmd += ['--', *argv]
+            proc = subprocess.Popen(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                pass_fds=(fd,) if fd is not None else (),
+            )
+            try:
+                out, err = proc.communicate(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                out, err = proc.communicate()
+                return ProcResult(124, out or '', (err or '') + '\n[postern] timed out')
+            return ProcResult(proc.returncode, out or '', err or '')
+        finally:
+            if seccomp is not None:
+                seccomp.close()
+
+    def run(self, argv: list[str], *, timeout: float = 60) -> ProcResult:
+        """Run ``argv`` inside the sandbox and return its result.
+
+        The raw primitive: it does not serve the hatch or set ``RLIMIT_NPROC``
+        (those are :meth:`run_python`'s job). Use it for a non-Python entrypoint
+        that manages its own limits.
+        """
+        return self._launch(list(argv), timeout=timeout)
+
+    def run_python(self, code: str, *, timeout: float = 60) -> ProcResult:
+        """Run untrusted Python ``code`` inside the sandbox.
+
+        With a :class:`Hatch`, the hatch UDS is bound in and its path exported as
+        ``POSTERN_HATCH``; the guest reaches the host's allowlisted gRPC methods
+        by dialing ``unix:$POSTERN_HATCH`` with the generated stub (grpcio and
+        the stubs come from the bound environment). The guest shim applies
+        ``RLIMIT_NPROC`` before running the code.
+        """
+        binds = ['--ro-bind', _SHIM_SRC, _GUEST_SHIM]
+        env = {
+            'POSTERN_CODE': code,
+            'POSTERN_NPROC': str(self._profile.rlimit_nproc),
+            'POSTERN_AS': str(self._profile.rlimit_as or 0),
+            'POSTERN_HATCH': '',
+        }
+        argv = [self._profile.python, '-u', _GUEST_SHIM]
+        if self._hatch is None:
+            return self._launch(argv, timeout=timeout, setenv=env, extra_binds=binds)
+        binds += ['--bind', self._hatch.socket_path, _GUEST_SOCK]
+        env['POSTERN_HATCH'] = _GUEST_SOCK
+        with self._hatch.accepting():
+            return self._launch(argv, timeout=timeout, setenv=env, extra_binds=binds)
+
+    def verify(self, *, timeout: float = 30) -> None:
+        """Fail fast at startup unless the sandbox actually launches here.
+
+        A boot-time gate: call once against the profile you will serve with, and
+        refuse to run untrusted code if it raises. Every control is already
+        fail-closed on the launch path — the strict ``--unshare-{user,net,…}``
+        flags make bwrap abort if it cannot create the namespaces, apply
+        ``--uid`` or drop capabilities (F1/F2/F5), and :func:`_seccomp.load_filter`
+        refuses an architecture the filter doesn't cover (F4). So there is nothing
+        to *probe* for at runtime (a successful launch is the proof, as in
+        Chrome's sandbox): this just triggers one trivial launch so a broken
+        platform — no user namespace, gVisor, an uncovered arch — surfaces as an
+        :class:`IsolationError` at startup rather than on the first real request.
+        """
+        if not self._profile.seccomp:
+            raise IsolationError('seccomp is disabled; refusing to treat this as a hardened sandbox')
+        result = self.run_python('pass', timeout=timeout)
+        if not result.ok:
+            raise IsolationError(f'sandbox failed to launch: {result.stderr.strip() or result.returncode}')
+
+    def close(self) -> None:
+        """Remove the workspace if this Sandbox created it (a no-op for a caller-owned path)."""
+        if self._own_workspace:
+            shutil.rmtree(self._workspace, ignore_errors=True)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

postern/_seccomp.py

@@ -0,0 +1,181 @@
+"""The seccomp-BPF denylist: a maintained, multi-arch backstop.
+
+Defense in depth on top of the empty network namespace and dropped capabilities:
+block the syscalls that would let guest code re-gain namespaces, mount, trace,
+load code into the kernel, or fake terminal input. It is a denylist (default
+allow) — a backstop, not the primary boundary.
+
+The filter is compiled **ahead of time** by ``tools/gen_seccomp.py`` (which uses
+libseccomp) and committed as ``_seccomp.bpf`` next to this module. The runtime
+only *loads* that blob and hands its fd to ``bwrap --seccomp`` — so installing or
+running postern needs no libseccomp, keeping the core dependency-free. The blob
+is a single multi-arch program (x86_64, x86, x32, aarch64, arm); on any other
+architecture its default-allow would make it a silent no-op, so :func:`load_filter`
+**refuses to load it** there (fail closed) rather than run with an unenforced
+filter — that arch check is the only thing that isn't self-evident from the
+kernel accepting the filter, so there is no runtime probe.
+
+The syscall lists below are the source of truth the generator consumes; they are
+derived from Flatpak's seccomp policy (``common/flatpak-run.c``). Editing them
+requires regenerating the blob — see ``tools/gen_seccomp.sh``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.resources
+import json
+import platform
+import tempfile
+import typing
+
+_BPF_RESOURCE = '_seccomp.bpf'
+_SPEC_RESOURCE = '_seccomp.spec'
+
+# The machine architectures the committed blob actually carries a program for
+# (the ``uname -m`` names for ``tools/gen_seccomp._ARCHES``). On anything else
+# the filter's default-allow makes it a silent no-op, so ``load_filter`` refuses
+# to load it there rather than run with a filter that enforces nothing.
+COVERED_ARCHES: frozenset[str] = frozenset(
+    {'x86_64', 'amd64', 'i386', 'i486', 'i586', 'i686', 'aarch64', 'arm64', 'armv6l', 'armv7l', 'armv8l', 'arm'}
+)
+
+
+def arch_is_covered(machine: str | None = None) -> bool:
+    """Whether the committed filter carries a program for ``machine``.
+
+    Defaults to the running host's ``platform.machine()``. False means the blob
+    would load but enforce nothing here (default-allow no-op).
+    """
+    return (machine or platform.machine()).lower() in COVERED_ARCHES
+
+
+# Blocked with EPERM: escape-enabling or dangerous syscalls the guest never
+# legitimately needs. (Flatpak's main blocklist plus its non-devel additions —
+# ptrace and perf_event_open.)
+BLOCKED_EPERM: tuple[str, ...] = (
+    # Re-gaining namespaces / changing the mount or root view (bwrap already set
+    # ours up before applying this filter).
+    'unshare',
+    'setns',
+    'mount',
+    'umount2',
+    'pivot_root',
+    'chroot',
+    # Kernel keyring.
+    'add_key',
+    'keyctl',
+    'request_key',
+    # Tracing / profiling other processes.
+    'ptrace',
+    'perf_event_open',
+    # Scary VM / NUMA memory ops.
+    'move_pages',
+    'mbind',
+    'get_mempolicy',
+    'set_mempolicy',
+    'migrate_pages',
+    # Misc: read the kernel log, load a shared lib by inode, toggle accounting,
+    # manipulate quotas.
+    'syslog',
+    'uselib',
+    'acct',
+    'quotactl',
+    # Kernel modules, eBPF, kexec, reboot, swap. Redundant with --cap-drop ALL
+    # (each needs a capability the guest lacks) but kept as cheap defense in
+    # depth — postern blocked these before adopting Flatpak's list.
+    'bpf',
+    'init_module',
+    'finit_module',
+    'delete_module',
+    'kexec_load',
+    'kexec_file_load',
+    'reboot',
+    'swapon',
+    'swapoff',
+)
+
+# Blocked with ENOSYS (not EPERM): clone3 and the new mount API. seccomp cannot
+# inspect clone3's argument struct, so it is refused wholesale; returning ENOSYS
+# (rather than EPERM) lets glibc fall back to the classic clone/mount paths
+# instead of treating the call as a hard failure.
+BLOCKED_ENOSYS: tuple[str, ...] = (
+    'clone3',
+    'open_tree',
+    'move_mount',
+    'fsopen',
+    'fsconfig',
+    'fsmount',
+    'fspick',
+    'mount_setattr',
+)
+
+# Argument-filtered rules (generator applies these). clone's flags are arg0 on
+# every architecture postern targets; ioctl's request is arg1.
+CLONE_NEWUSER = 0x10000000  # block clone(CLONE_NEWUSER, ...) — the gap unshare/setns alone leave open
+TIOCSTI = 0x5412  # fake terminal input (CVE-2017-5226)
+TIOCLINUX = 0x541C  # ditto via the linux console ioctl
+
+# The libseccomp Arch names the generator compiles into the blob. Kept here as
+# the source of truth (not in the generator) so the drift digest below covers
+# them without this module importing libseccomp.
+GEN_ARCHES: tuple[str, ...] = ('X86_64', 'X86', 'X32', 'AARCH64', 'ARM')
+
+# Deliberately NOT blocked: socket / socketpair. Network isolation is the empty
+# netns's job (no interface, no route); the guest needs socket(AF_UNIX) to reach
+# the hatch UDS, so blocking it breaks the hatch while adding nothing.
+
+
+def spec_digest() -> str:
+    """A stable digest of the syscall spec the committed blob was built from.
+
+    Hashes the source-of-truth rule lists and the generator's arch set, so a
+    change to them that was *not* followed by regenerating ``_seccomp.bpf`` is
+    detectable with no libseccomp dependency — the generator records this digest
+    (and the blob's own hash) in ``_seccomp.spec``, and a test compares. It does
+    not prove the blob is what libseccomp would emit today (only the CI
+    regenerate-and-diff does); it catches the common drift of editing a list and
+    forgetting to regenerate.
+    """
+    payload = json.dumps(
+        {
+            'blocked_eperm': list(BLOCKED_EPERM),
+            'blocked_enosys': list(BLOCKED_ENOSYS),
+            'clone_newuser': CLONE_NEWUSER,
+            'tiocsti': TIOCSTI,
+            'tioclinux': TIOCLINUX,
+            'gen_arches': list(GEN_ARCHES),
+        },
+        sort_keys=True,
+    ).encode()
+    return hashlib.sha256(payload).hexdigest()
+
+
+def manifest() -> dict[str, str]:
+    """Build the ``_seccomp.spec`` manifest for the currently committed blob."""
+    blob = importlib.resources.files('postern').joinpath(_BPF_RESOURCE).read_bytes()
+    return {'source_digest': spec_digest(), 'bpf_sha256': hashlib.sha256(blob).hexdigest()}
+
+
+def load_filter() -> typing.IO[bytes]:
+    """Load the prebuilt BPF denylist into an open temp file positioned at 0.
+
+    The caller passes its fd to ``bwrap --seccomp`` and keeps it open for the
+    child's lifetime, then closes it. Fails closed rather than run with an
+    unenforced filter: raises on an architecture the blob doesn't cover (where it
+    would be a default-allow no-op), or if the blob is missing from the install
+    (a packaging error).
+    """
+    if not arch_is_covered():
+        raise RuntimeError(
+            f'seccomp filter has no coverage for this architecture ({platform.machine()!r}); refusing to run '
+            'untrusted code with an unenforced filter (set SandboxProfile(seccomp=False) to override deliberately)'
+        )
+    data = importlib.resources.files('postern').joinpath(_BPF_RESOURCE).read_bytes()
+    if not data:
+        raise RuntimeError(f'seccomp filter {_BPF_RESOURCE!r} is missing or empty; the postern install is broken')
+    f = tempfile.TemporaryFile()  # noqa: SIM115 — returned open; caller passes its fd to bwrap and closes it
+    f.write(data)
+    f.flush()
+    f.seek(0)
+    return f

postern/_seccomp.spec

@@ -0,0 +1,4 @@
+{
+  "bpf_sha256": "350c6f323ad63c1c983ff17c27dcaaa63c6074267e3bdd4cea54d7c2011c4df2",
+  "source_digest": "171ece416a12a2641278c8178f39b921bec4298c887c4a3b85a6dac6954c83a7"
+}

postern/grpc.py

@@ -0,0 +1,126 @@
+"""The gRPC escape hatch: the sandbox's typed doorway to the outside.
+
+A `GrpcHatch` serves host-provided `grpc` servicers over the sandbox's Unix
+domain socket, gated by a **method allowlist** — only the exact
+``/package.Service/Method`` names you list are reachable; anything else is
+`PERMISSION_DENIED`. The servicer runs in the trusted host process; the guest
+calls it with the generated stub over ``unix:$POSTERN_HATCH``. The proto is the
+typed contract, so arguments and results are typed and language-neutral, and the
+allowlist is the capability grant — the security boundary is that method set.
+
+Requires the ``grpc`` extra (``pip install 'postern[grpc]'``). ``import
+postern.grpc`` only where you use it; the bare `Sandbox` stays dependency-free.
+
+    from postern import Sandbox, SandboxProfile
+    from postern.grpc import GrpcHatch
+    import greeter_pb2_grpc
+
+    hatch = GrpcHatch(allowlist={'/greeter.Greeter/SayHello'})
+    hatch.add_servicer(greeter_pb2_grpc.add_GreeterServicer_to_server, MyGreeter())
+    sandbox = Sandbox(SandboxProfile.with_venv('/opt/env'), hatch=hatch)
+    sandbox.run_python(guest_code)   # guest dials unix:$POSTERN_HATCH with the stub
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+import typing
+from collections.abc import Callable, Generator
+from concurrent import futures
+
+import grpc
+
+
+class _Allowlist(grpc.ServerInterceptor):
+    """Reject any method whose full name is not in the allowlist."""
+
+    def __init__(self, allowed: typing.Iterable[str]) -> None:
+        self._allowed = frozenset(allowed)
+
+    def intercept_service(
+        self,
+        continuation: Callable[[grpc.HandlerCallDetails], grpc.RpcMethodHandler | None],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> grpc.RpcMethodHandler | None:
+        method = getattr(handler_call_details, 'method', None)
+        if method in self._allowed:
+            return continuation(handler_call_details)
+
+        def deny(_request: object, context: grpc.ServicerContext) -> typing.NoReturn:
+            context.abort(grpc.StatusCode.PERMISSION_DENIED, f'{method} is not on the hatch allowlist')
+
+        # A unary deny handler aborts before any message flows. Streaming methods
+        # on the deny path may surface a cardinality mismatch client-side, but the
+        # call is still refused; allowed methods keep their real (any-cardinality)
+        # handler via ``continuation``.
+        return grpc.unary_unary_rpc_method_handler(deny)
+
+
+class GrpcHatch:
+    """Serve allowlisted `grpc` servicers over the sandbox's UDS."""
+
+    def __init__(
+        self,
+        allowlist: typing.Iterable[str],
+        *,
+        socket_path: str | os.PathLike[str] | None = None,
+        max_workers: int = 8,
+    ) -> None:
+        if socket_path is None:
+            self._dir = tempfile.mkdtemp(prefix='postern-')
+            self._path = os.path.join(self._dir, 'hatch.sock')
+        else:
+            self._dir = None
+            self._path = os.fspath(socket_path)
+        self._server = grpc.server(
+            futures.ThreadPoolExecutor(max_workers=max_workers),
+            interceptors=[_Allowlist(allowlist)],
+        )
+        self._server.add_insecure_port(f'unix:{self._path}')
+        self._started = False
+
+    @property
+    def socket_path(self) -> str:
+        return self._path
+
+    def add_servicer(self, register: Callable[[typing.Any, grpc.Server], None], servicer: object) -> None:
+        """Register a servicer via its generated ``add_<Service>Servicer_to_server``."""
+        register(servicer, self._server)
+
+    def start(self) -> None:
+        """Start serving (idempotent).
+
+        A gRPC server cannot be restarted, so the hatch serves from here until
+        :meth:`close` — reused across many calls.
+        """
+        if not self._started:
+            self._server.start()
+            self._started = True
+            # Deterministic socket perms, not umask-dependent (F9). The guest
+            # runs as a non-root uid, so it must be able to connect; host-side
+            # isolation rests on the 0700 mkdtemp dir above, which keeps other
+            # host users from reaching the socket at all.
+            with contextlib.suppress(OSError):
+                os.chmod(self._path, 0o666)  # noqa: S103 — intentional; see the comment above
+
+    @contextlib.contextmanager
+    def accepting(self) -> Generator[GrpcHatch, None, None]:
+        """Ensure the hatch is serving for the block.
+
+        It stays up afterwards so a later call can reuse it, and is stopped only
+        by :meth:`close`.
+        """
+        self.start()
+        yield self
+
+    def close(self) -> None:
+        if self._started:
+            self._server.stop(0)
+            self._started = False
+        with contextlib.suppress(OSError):
+            os.unlink(self._path)
+        if self._dir is not None:
+            with contextlib.suppress(OSError):
+                os.rmdir(self._dir)

postern-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: postern
+Version: 0.1.0
+Summary: Run untrusted Python in an OS-isolated sandbox whose only exit is a set of host-defined, typed calls.
+Author: Centre for Population Genomics
+License: MIT
+Project-URL: Repository, https://github.com/populationgenomics/postern
+Project-URL: Issues, https://github.com/populationgenomics/postern/issues
+Keywords: sandbox,bubblewrap,isolation,untrusted-code,seccomp,rpc,agent,tool-use
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.60; extra == "grpc"
+Dynamic: license-file
+
+# postern
+
+Run untrusted Python in an OS-isolated sandbox whose **only** exit is a set of
+host-defined, typed gRPC methods.
+
+A postern is the small guarded gate through an otherwise sealed wall. That is the
+model: guest code runs with no network, no filesystem beyond a workspace, no
+capabilities — and reaches the outside world only by calling the specific gRPC
+methods the host allowlists. The security boundary is that method set, not a
+coarse permission flag.
+
+```python
+from postern import Sandbox, SandboxProfile
+from postern.grpc import GrpcHatch
+import greeter_pb2_grpc
+
+hatch = GrpcHatch(allowlist={'/greeter.Greeter/SayHello'})
+hatch.add_servicer(greeter_pb2_grpc.add_GreeterServicer_to_server, MyGreeter())
+
+profile = SandboxProfile.with_venv('/opt/analysis-env')   # pandas, grpcio, stubs
+result = Sandbox(profile, hatch=hatch).run_python(guest_code)
+# guest dials unix:$POSTERN_HATCH with the generated stub; a non-allowlisted
+# method → PERMISSION_DENIED; there is no network.
+```
+
+## Why
+
+Coarse sandbox permissions (`--allow-net`, `--allow-read`) are the wrong grain
+for untrusted agent/tool code: you rarely want "the network", you want "this one
+method that fetches this one resource". postern inverts the default — the guest
+gets **nothing** except the host methods you allowlist, each a typed proto shape.
+Whatever a method can reach (a database, a credentialed API, a compute backend)
+the guest reaches only through that shape, never directly.
+
+This is the design [enclave](https://github.com/populationgenomics/enclave-py)
+prototyped over WebAssembly (WASI-compiled CPython). postern delivers the same
+"fine-grained function injection is the boundary" promise over a different
+substrate — **OS isolation (bubblewrap) + a gRPC-over-UDS hatch** — which means
+real CPython with arbitrary third-party packages (no custom toolchain), and
+typed, language-neutral arguments/results (proto, `buf breaking`-gateable).
+
+## Isolation
+
+`Sandbox` launches the guest under [bubblewrap](https://github.com/containers/bubblewrap):
+
+- **empty network namespace** — no egress of any kind (a socket can be created
+  but has no route). The user and cgroup namespaces are unshared **strictly**
+  (`--unshare-user`/`--unshare-cgroup`, not `--unshare-all`'s best-effort `-try`
+  variants), so a host that can't provide a user namespace is a hard launch
+  failure rather than a silent fall-through to a real-root guest;
+- **surgical filesystem** — read-only base system dirs + one writable
+  `/workspace`; no `/etc`, `/home`, `/root`, or host application code;
+- **`--cap-drop ALL`**, **`--new-session`** (anti terminal-injection),
+  **`--die-with-parent`**, **`--clearenv`**;
+- **non-root guest** — the guest runs as uid/gid `65534` (`nobody`), so it holds
+  no capabilities inside its user namespace, and if the userns fails to
+  materialise on a root host it still drops to a non-root real uid
+  (`SandboxProfile(guest_uid=None)` restores the legacy uid-0-in-userns);
+- a **seccomp denylist** blocking escape-enabling syscalls (`unshare`, `setns`,
+  `mount`, `ptrace`, `bpf`, `keyctl`, …). `socket` is deliberately *not* blocked
+  — network isolation is the netns's job, and the guest needs `socket(AF_UNIX)`
+  for the hatch;
+- **`RLIMIT_NPROC`** as a fork-bomb backstop (set inside the guest), and an
+  optional **`RLIMIT_AS`** memory backstop (`SandboxProfile(rlimit_as=...)`, off
+  by default; a cgroup `memory.max` at the deploy layer is the real isolation).
+
+The hatch UDS is bind-mounted in as the single controlled opening. Because the
+RPC rides that socket, the guest's own stdin/stdout/stderr stay free.
+
+**Fail-closed boot check.** Every control is enforced on the launch path: the
+strict `--unshare-*` flags make bwrap abort if it can't create the namespaces,
+apply `--uid`, or drop capabilities, and the seccomp loader refuses an uncovered
+architecture — so a successful launch *is* the proof (no runtime probe, like
+Chrome's sandbox). `Sandbox(profile).verify()` just triggers one trivial launch
+at startup so a broken platform (no user namespace, gVisor, uncovered arch)
+raises `IsolationError` there rather than on the first request. Call it at worker
+startup and refuse to serve if it raises (`examples/worker.py` does this).
+
+## The environment (getting pandas etc. in)
+
+The sandbox has no egress, so packages are provisioned **ahead of time** and
+mounted read-only — never `pip install`ed at run time.
+
+- `SandboxProfile.with_venv('/opt/env')` binds a venv read-only (at its own path,
+  so its `site.py` resolution works) and runs its interpreter. The venv holds the
+  guest's libraries **and** its hatch client (grpcio + the generated stubs).
+- `SandboxProfile(rootfs='/opt/guest-root')` binds a curated base directory as the
+  guest's system dirs *instead of the host's* — hiding the host userland
+  entirely. Build it at image-build time (build-time Docker is fine; only
+  *runtime* container engines are excluded): `docker export` a container into a
+  dir, or ship a single squashfs/erofs image file mounted read-only via FUSE
+  (`squashfuse`, unprivileged, Cloud-Run-compatible) and point `rootfs` at the
+  mountpoint. `bwrap --ro-overlay` can stack OCI layer dirs without flattening.
+
+## Requirements
+
+Linux with **bubblewrap** and unprivileged user namespaces (a Cloud Run gen2 Job,
+or any such host). `postern.available()` reports whether a sandbox can launch.
+The seccomp filter is a prebuilt multi-arch BPF blob (x86_64, x86, x32, aarch64,
+arm); on any other architecture it would be a default-allow no-op, so `Sandbox`
+**refuses to launch** there (fail-closed) rather than run with an unenforced
+filter — set `SandboxProfile(seccomp=False)` to override deliberately. Not
+runnable on macOS except against a Linux target — `import postern` works
+anywhere, `Sandbox.run*` needs the OS.
+
+**Ubuntu 23.10+ / 24.04** restrict unprivileged user namespaces by default
+(`kernel.apparmor_restrict_unprivileged_userns=1`), which bubblewrap needs —
+the symptom is `bwrap: setting up uid map: Permission denied` or `loopback:
+Failed RTM_NEWADDR`. Lift it with `sudo sysctl -w
+kernel.apparmor_restrict_unprivileged_userns=0`, or install an AppArmor profile
+that grants bwrap `userns`. Cloud Run gen2 does not have this restriction.
+
+The bare `Sandbox` has **no third-party dependencies and no cloud dependency** —
+it is a Linux primitive. The gRPC hatch pulls `grpcio` via the `grpc` extra.
+
+## Install
+
+```bash
+pip install postern              # the bare sandbox (no deps)
+pip install 'postern[grpc]'      # + the gRPC hatch
+```
+
+## Public API
+
+- `Sandbox(profile=None, *, hatch=None)` — `.run(argv)`, `.run_python(code)` → `ProcResult(returncode, stdout, stderr, ok)`; `.verify()` (fail-closed boot check, raises `IsolationError`).
+- `SandboxProfile(workspace=None, rootfs=None, python='python3', ro_binds=[], stubs=None, env=..., seccomp=True, rlimit_nproc=1024, rlimit_as=None, guest_uid=65534, guest_gid=65534)` and `SandboxProfile.with_venv(venv, **kw)`. `stubs=` injects a dir or list of files at `/run/postern/stubs` (on `PYTHONPATH`) — a shared rootfs carries the heavy base, per-agent stubs bind in selectively.
+- `postern.grpc.GrpcHatch(allowlist, *, socket_path=None)` — `.add_servicer(register_fn, servicer)`; `with hatch.accepting(): ...`. (`grpc` extra.)
+- `available()` — bubblewrap present?
+
+See `examples/e2e_greeter.py` for an end-to-end run (typed hatch call + pandas,
+verified on a Linux host).
+
+## Deploy: bundle the rootfs into the Job image
+
+For a Cloud Run Job you build an image anyway, so bundle the guest rootfs into
+it and let postern bind it — no runtime container engine. `examples/Dockerfile`
+is the recipe: a multi-stage build that (1) generates the stubs, (2) builds a
+minimal guest rootfs (`python:slim` + grpcio + your data libs + the client
+stubs), and (3) assembles the worker (bubblewrap + `postern[grpc]` + your
+servicer) with the guest rootfs copied to `/opt/guest-root`. The worker
+(`examples/worker.py`) binds it with `SandboxProfile(rootfs='/opt/guest-root')`,
+so the guest sees only that curated image, never the worker's userland. Cloud
+Run gen2 provides the unprivileged user namespaces bubblewrap needs.
+
+## Roadmap
+
+- **Checkpoint/restore** — a `Store` protocol + durable-glob workspace snapshots
+  for run-lived state continuity.
+- **`overlay=` profile mode** — emit `bwrap --ro-overlay` to stack layers with a
+  tmpfs upper, instead of a single `--ro-bind` rootfs.
+- **Agent-runtime adapters** — drive the sandbox from Anthropic Managed Agents,
+  Google ADK, or MCP (the same sandbox, provider-agnostic).
+
+## License
+
+MIT.

postern-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+postern/__init__.py,sha256=mWBSquR1Eonz9cQ1b8vskULsz59G-jHDKR5Kac_TNcY,1512
+postern/_guest.py,sha256=sbjFJxOEfNC8Jk7kzFIsF7x1EfIMTaU7gvcpruiUYwo,1262
+postern/_sandbox.py,sha256=CSC3L_xQyhojzFD38PtDAWe1wEkPrvIkAaaIO2s2qQg,16445
+postern/_seccomp.bpf,sha256=NQxvMjrWPByYP_F8J9yqpjxgdCZ-O91M6lTXwgEcTfI,1736
+postern/_seccomp.py,sha256=62cpnI8SmmLaNWxJgTAS6vu-wX2-5ZObE6HLrNd5HUQ,7348
+postern/_seccomp.spec,sha256=c2U7_As5LtF2p1knXkstIgx9z86W7jGZ9V5UHEx2Yr8,174
+postern/grpc.py,sha256=ZMgLl-68_Pcx50PyJELmnQce_ieJ8W7eCS8Iv62Mof4,4967
+postern/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+postern-0.1.0.dist-info/licenses/LICENSE,sha256=lwIanGu698z5WiBedbwEOdUJLQb_G4FOFgucqExVIS0,1087
+postern-0.1.0.dist-info/METADATA,sha256=IGXM0MCz4VuUZGYfhDuzDTpypmyI1ec9TP2zzm-hXXQ,9766
+postern-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+postern-0.1.0.dist-info/top_level.txt,sha256=jiA-kL8y47RlY1WHPrOJ-5CCc-3r3SQ3LEOmZxsYyiE,8
+postern-0.1.0.dist-info/RECORD,,

postern-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

postern-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Centre for Population Genomics
+
+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.

postern-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+postern