postern 0.1.0__tar.gz

postern-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,156 @@
+# 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/pyproject.toml

@@ -0,0 +1,110 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "postern"
+version = "0.1.0"
+description = "Run untrusted Python in an OS-isolated sandbox whose only exit is a set of host-defined, typed calls."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Centre for Population Genomics" }]
+keywords = ["sandbox", "bubblewrap", "isolation", "untrusted-code", "seccomp", "rpc", "agent", "tool-use"]
+# The core has NO runtime dependencies — pure stdlib (subprocess, socket, json),
+# bubblewrap at the OS layer. gRPC hatch and provider adapters are extras.
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Topic :: Security",
+    "Topic :: Software Development :: Interpreters",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+# The gRPC hatch: serve any grpc.aio servicer over the sandbox UDS, method-allowlisted.
+grpc = ["grpcio>=1.60"]
+
+[project.urls]
+Repository = "https://github.com/populationgenomics/postern"
+Issues = "https://github.com/populationgenomics/postern/issues"
+
+# Supply-chain age gate: never resolve a release younger than 7 days (relative,
+# in-repo so CI and contributors inherit it).
+[tool.uv]
+exclude-newer = "7 days"
+
+# grpcio (the `grpc` extra) is in the dev groups so the hatch tests run and
+# pyright resolves postern.grpc + the hatch tests; consumers opt in via the
+# `grpc` extra.
+[dependency-groups]
+test = ["pytest", "grpcio>=1.60"]
+# typing-extensions: type-check-only backport of typing.Self for the 3.10 floor
+# (see src/postern/_sandbox.py) — not a runtime dependency.
+lint = ["ruff", "pyright", "pre-commit", "pytest", "grpcio>=1.60", "typing-extensions"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+postern = ["py.typed", "_seccomp.bpf", "_seccomp.spec"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+select = [
+    "A", "B", "C", "D", "E", "F", "G", "I", "N", "Q", "S", "W",
+    "ANN", "ARG", "BLE", "COM", "DTZ", "ERA", "EXE", "ICN", "ISC",
+    "PGH", "PIE", "PL", "PT", "PYI", "RET", "RSE", "RUF",
+    "SIM", "SLF", "T10", "TID", "UP", "YTT",
+]
+fixable = ["ALL"]
+ignore = [
+    "COM812",
+    "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107",
+    "ISC001",
+    "PLR0913",
+    "PLR2004",
+    "Q000", "Q003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# The in-sandbox shim is stdlib-only, dynamic (host.<attr> dispatch), run as a
+# script and never imported by the package — held to correctness, not API rigor.
+"src/postern/_guest.py" = ["T201", "BLE001", "ANN", "D", "SLF001"]
+"src/postern/_sandbox.py" = ["S603"]
+"tests/**" = ["S101", "S102", "S603", "S607", "SLF001", "ANN", "D", "PLR2004", "T201"]
+# Runnable examples: gRPC servicer methods are PascalCase; print is the UI; no
+# package __init__; they import generated stubs not present at lint time.
+"examples/**" = ["N802", "T201", "ANN", "D", "S", "INP001", "ARG"]
+# Build-time tooling (not shipped): imports libseccomp, prints, no package init.
+"tools/**" = ["T201", "ANN", "D", "S", "INP001", "E402", "SLF001"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
+
+[tool.pyright]
+# Check against the floor of requires-python; run via `uv run --group lint` so
+# the uv-managed environment supplies the imports.
+pythonVersion = "3.10"
+include = ["src", "tests"]
+exclude = ["**/__pycache__", "src/postern/_guest.py"]
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

postern-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

postern-0.1.0/src/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-0.1.0/src/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())