mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/key_seam.py

@@ -0,0 +1,434 @@
+"""The one seam between the two planes: cloud owns identity, the harness verifies against it.
+
+Cloud and the harness are separate repositories with separate owners, and exactly one contract
+joins them: an API key presented by a caller is verified against cloud's verify surface. The
+authority for that contract is ``mostlyright-cloud/manifest/api-key.ts``. This module is the
+harness side of it and must stay byte-compatible with that file.
+
+Three rules are copied here verbatim from api-key.ts's header comment, because every one of them
+is security-load-bearing and every one of them looks like dead weight to a later reader:
+
+* Hash both sides to fixed-length digests before comparing. The comparison then runs over two
+  32-byte values whatever the caller presented.
+* **Never pre-check length.** A length pre-check answers "how long is the expected key" in the
+  time it takes to return, which is the question an attacker is asking.
+* **Never wrap the compare in try/except.** Throwing is measurably faster than a full compare, so
+  a raising path reintroduces exactly the timing channel that hashing exists to close. Digesting
+  first is what makes the compare total, so there is nothing left to catch.
+
+Fail-closed is the documented default for everything in this module. A key is authorized only by
+an explicit, well-formed allow from the verify surface reached over https. Any other outcome — a
+non-200 status, a redirect, a transport fault, a timeout, a body that is not strict JSON, a body
+over the cap, a body that names a different key — denies.
+
+The raw key never leaves this module. It goes out in one place, the ``x-api-key`` request header,
+and it appears in no return value, no :class:`KeyVerdict`, no serialized dict, no reason string,
+and no exception message. Only :func:`hash_key_id` output is safe to log.
+
+**Where this seam is enforced, and why not in the worker.** The enforcement point is named in
+:data:`CONSUMER_CALL_SITE`, and it is deliberately not this repository's hosted worker. Three
+measured facts establish that, and they are recorded here so a later reader does not "fix" an
+omission that is not one:
+
+1. ``hosted_bootstrap.launch`` hands the worker an environment of exactly three variables — PATH,
+   PYTHONDONTWRITEBYTECODE, PYTHONUNBUFFERED (the environment mapping at hosted_bootstrap.py:475).
+   No API key can reach the worker process through it. Passing one would mean deliberately
+   widening that barrier to carry a customer credential into the least-trusted process in the
+   system, which inverts the design the barrier exists to hold.
+2. ``mostlyright-studio``'s ``infra/tofu`` declares no ``MOSTLYRIGHT_API_KEY`` on the worker job,
+   so the credential is not present in that container today.
+3. The worker authenticates with an attempt-scoped capability token minted by Studio during the
+   bootstrap exchange, and its tenant coordinate is ``workspace_id``. The customer API key is
+   verified upstream, where the request enters the platform, before any job exists to run.
+
+So this module is the harness-side reference implementation and parity anchor for a check that
+runs at the API edge, not a library the worker forgot to call. It is intentionally not imported by
+``producer_main`` or ``verifier_main``; wiring it in there would punch a credential through the
+sanitization barrier to no benefit. ``tests/test_key_seam_consumer_contract.py`` pins the two
+implementations against each other.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import ssl
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+from urllib.error import HTTPError
+from urllib.parse import urlsplit
+from urllib.request import (
+    HTTPRedirectHandler,
+    HTTPSHandler,
+    ProxyHandler,
+    Request,
+    build_opener,
+)
+
+from mostlyright.data_harness.canonical import CanonicalJSONError, parse_json
+
+#: The environment variable holding the configured legacy v1 shared key. Matches
+#: ``LEGACY_API_KEY_ENV`` at api-key.ts:27 — one shared secret, one env var name, on both the
+#: sending and the receiving side.
+LEGACY_API_KEY_ENV = "MOSTLYRIGHT_API_KEY"
+
+#: The only header the credential is ever read from or sent in. Matches ``API_KEY_HEADER`` at
+#: manifest-handler.ts:25. Never a query string, never a URL path segment: those are logged by
+#: every proxy, load balancer, and browser history on the route.
+API_KEY_HEADER = "x-api-key"
+
+V2_LIVE_PREFIX = "mr_live_"
+V2_TEST_PREFIX = "mr_test_"
+
+#: Where a presented API key is actually refused or allowed, recorded in code because it is not in
+#: this repository and an unrecorded consumer reads as a missing one. Named consumers: the Studio
+#: API edge that authenticates a customer request before any run exists, and the worker-bootstrap
+#: exchange that mints the attempt-scoped capability the worker carries instead of a key
+#: (``mostlyright-cloud/manifest/manifest-handler.ts`` is the same check on the manifest surface).
+#: This module is the harness-side reference implementation and parity anchor for that check; see
+#: the module docstring for the three facts establishing why the worker must never hold a key.
+CONSUMER_CALL_SITE = (
+    "mostlyright-studio API edge and worker-bootstrap exchange; "
+    "mostlyright-cloud/manifest/manifest-handler.ts on the manifest surface"
+)
+
+#: A verify response is a verdict, not a payload. Anything larger than this is not a verdict, so
+#: the cap is small on purpose — it bounds memory and it bounds the time an attacker can hold the
+#: connection open. Compare ``MAX_BOOTSTRAP_RESPONSE_BYTES`` (hosted_bootstrap.py:50), which is
+#: large because a bootstrap envelope legitimately is.
+MAX_VERIFY_RESPONSE_BYTES = 8 * 1024
+
+#: A bounded wait. A verify surface that has not answered by now has failed, and a hang is a
+#: denial of service against every caller waiting behind it.
+VERIFY_TIMEOUT_SECONDS = 10.0
+
+MAX_URL_LENGTH = 2048
+
+#: The allow marker. A 200 alone is not an allow: an intercepting proxy, a captive portal, and a
+#: misrouted request all return 200 with a body that means nothing. The body must be a JSON object
+#: that says so explicitly.
+ALLOW_MARKER = "ok"
+
+
+class KeySeamError(RuntimeError):
+    """A typed key-seam failure.
+
+    Raised only for a structurally invalid call — a base URL that is not https, a key that is not
+    text. A rejected key is never an exception; it is a denying :class:`KeyVerdict`.
+
+    Like everything else here, the message never contains the raw key.
+    """
+
+
+def hash_key_id(key: str) -> str:
+    """Return a stable, irreversible identifier for ``key``.
+
+    Exactly cloud's ``hashKeyId`` (api-key.ts:49): the first 8 bytes of the SHA-256 digest of the
+    key's UTF-8 encoding, hex-encoded — 16 lowercase hex characters.
+
+    This is the only value derived from a key that is safe to log, record, or return. It is not
+    reversible and it is not a credential.
+
+    The coupling is load-bearing and invisible from either side alone: cloud's
+    ``dashboard/lib/usage.ts`` stores this same value in ``usage_events.key_id``. If either
+    implementation changes its truncation length or its string encoding, nothing raises anywhere —
+    usage counting for every key simply goes to zero, and attribution for a key becomes
+    unresolvable between the two planes. ``tests/test_key_seam.py`` pins the derivation with
+    literal vectors produced by running both implementations.
+    """
+
+    if not isinstance(key, str):
+        raise KeySeamError("an API key must be text")
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()[:16]
+
+
+def constant_time_equal(a: str, b: str) -> bool:
+    """Return whether ``a`` and ``b`` are equal, in time independent of either value.
+
+    Mirrors ``constantTimeEqual`` (api-key.ts:38). Both operands are digested to fixed 32-byte
+    SHA-256 values first, and only the digests reach :func:`hmac.compare_digest`.
+
+    The digest step is not decoration. It is what makes this function *total* — every pairing of
+    lengths, including empty and non-ASCII inputs, returns a bool and none raises — and it is what
+    makes the running time independent of the presented value's length. There is deliberately no
+    length pre-check (it would leak the expected key's length) and deliberately no try/except
+    around the compare (an early raise is faster than a full compare, which is the timing channel
+    this design closes).
+    """
+
+    if not isinstance(a, str) or not isinstance(b, str):
+        raise KeySeamError("a credential comparison takes two text values")
+    digest_a = hashlib.sha256(a.encode("utf-8")).digest()
+    digest_b = hashlib.sha256(b.encode("utf-8")).digest()
+    return hmac.compare_digest(digest_a, digest_b)
+
+
+def detect_key_format(key: str) -> str:
+    """Classify a presented credential's shape as ``v2-live``, ``v2-test``, or ``legacy``.
+
+    Mirrors ``detectKeyFormat`` (api-key.ts:87). **Purely descriptive: it authorizes nothing.**
+
+    A ``v2-live`` classification says only that a string starts with eight specified characters.
+    Every format still resolves through the
+    same verification, exactly as cloud's v0 does. This module must never mint a v2 key and must
+    never independently validate one; ``key_format`` on a :class:`KeyVerdict` is a label for
+    humans, never an input to the decision.
+    """
+
+    if not isinstance(key, str):
+        raise KeySeamError("an API key must be text")
+    if key.startswith(V2_LIVE_PREFIX):
+        return "v2-live"
+    if key.startswith(V2_TEST_PREFIX):
+        return "v2-test"
+    return "legacy"
+
+
+@dataclass(frozen=True)
+class KeyVerdict:
+    """The outcome of verifying one presented key.
+
+    Invariant: a verdict never carries the raw key. It carries ``key_id``, the irreversible
+    identifier from :func:`hash_key_id`, which is the value cloud records too — so the same key is
+    attributed identically on both sides of the seam.
+
+    ``reason`` is a plain-language phrase safe to show a user and safe to write to a log. It names
+    the class of fault only. It never contains, quotes, truncates, or measures the presented key,
+    and it never reports the expected key's length.
+
+    ``key_format`` is descriptive (see :func:`detect_key_format`) and never explains ``ok``.
+    """
+
+    ok: bool
+    key_id: str
+    key_format: str
+    reason: str
+
+    def __post_init__(self) -> None:
+        if type(self.ok) is not bool:
+            raise KeySeamError("a verdict must be allowed or denied, not something else")
+        for name in ("key_id", "key_format", "reason"):
+            value = getattr(self, name)
+            if type(value) is not str or not value:
+                raise KeySeamError(f"{name} must be a non-empty text value")
+        if len(self.key_id) != 16:
+            raise KeySeamError("key_id must be the 16-character identifier from hash_key_id")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain JSON-safe mapping, carrying the key id and never the key."""
+
+        return {
+            "ok": self.ok,
+            "key_id": self.key_id,
+            "key_format": self.key_format,
+            "reason": self.reason,
+        }
+
+
+class VerifyTransport(Protocol):
+    """Minimal redirect-free, proxy-free verify transport.
+
+    Deliberately the same shape as ``BootstrapTransport`` (hosted_bootstrap.py:57) so this
+    codebase has one transport idiom rather than two: a bootstrap transport satisfies this
+    protocol structurally, and a test stub written for one reads the same as a stub for the other.
+    """
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        maximum: int,
+    ) -> tuple[int, bytes]: ...
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    """Refuse every redirect.
+
+    Following a redirect would re-send the ``x-api-key`` header to a host named by the response
+    rather than by the caller, which is a credential handed to whoever answered. Returning ``None``
+    here makes urllib surface the 3xx as an ``HTTPError``, so the status reaches the caller as a
+    plain non-200 and denies. Mirrors hosted_bootstrap.py:70.
+    """
+
+    def redirect_request(
+        self,
+        request: Request,
+        file_pointer: Any,
+        code: int,
+        message: str,
+        headers: Any,
+        new_url: str,
+    ) -> None:
+        return None
+
+
+class UrlLibVerifyTransport:
+    """Small stdlib transport with ambient proxies and redirects disabled.
+
+    Ambient proxies are disabled because a proxy configured by the environment is another party
+    that would see the credential.
+    """
+
+    def __init__(self) -> None:
+        self._opener = build_opener(
+            ProxyHandler({}),
+            HTTPSHandler(context=ssl.create_default_context()),
+            _NoRedirect(),
+        )
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        maximum: int,
+    ) -> tuple[int, bytes]:
+        request = Request(url, data=body, headers=dict(headers), method=method)
+        try:
+            response = self._opener.open(request, timeout=VERIFY_TIMEOUT_SECONDS)
+        except HTTPError as error:
+            response = error
+        with response:
+            status = int(response.status)
+            content_length = response.headers.get("Content-Length")
+            if content_length is not None:
+                try:
+                    declared = int(content_length)
+                except ValueError as error:
+                    raise KeySeamError(
+                        "the verify response has an invalid content length"
+                    ) from error
+                if declared < 0 or declared > maximum:
+                    raise KeySeamError("the verify response exceeds its byte limit")
+            raw = response.read(maximum + 1)
+        if len(raw) > maximum:
+            raise KeySeamError("the verify response exceeds its byte limit")
+        return status, raw
+
+
+def _https_url(value: str, label: str) -> str:
+    """Return ``value`` when it is a plain absolute https URL, otherwise refuse it.
+
+    Mirrors ``hosted_bootstrap._https_url`` (hosted_bootstrap.py:147). It is copied rather than
+    imported for the reason recorded in ``deploy_target._https_url``: importing that module pulls
+    the whole hosted-worker stack in behind it and raises a bootstrap-specific error code. The
+    policy itself must stay identical — https only, absolute, no user information, no fragment, no
+    trailing slash.
+
+    Plain http is refused *before any request is attempted*, because the failure mode is not a bad
+    response, it is the credential already having been sent in the clear.
+    """
+
+    if not isinstance(value, str) or not 1 <= len(value) <= MAX_URL_LENGTH:
+        raise KeySeamError(f"{label} is not a usable URL")
+    if value.endswith("/"):
+        raise KeySeamError(f"{label} must not end with a slash")
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.fragment
+    ):
+        raise KeySeamError(
+            f"{label} must be an absolute https URL without user information or fragment"
+        )
+    return value
+
+
+def _denied(key_id: str, key_format: str, reason: str) -> KeyVerdict:
+    return KeyVerdict(ok=False, key_id=key_id, key_format=key_format, reason=reason)
+
+
+def _allow_body_is_valid(raw: bytes, key_id: str) -> tuple[bool, str]:
+    """Return whether ``raw`` is a well-formed allow body for ``key_id``, and why not if it is not.
+
+    Strict parse only: duplicate keys, byte-order marks, non-UTF-8 bytes, and non-integer numbers
+    are all rejected by :func:`canonical.parse_json`, so a body that two parsers would read
+    differently is never acted on.
+    """
+
+    try:
+        parsed = parse_json(raw)
+    except CanonicalJSONError:
+        return False, "the verify surface returned a body that is not strict JSON"
+    if not isinstance(parsed, dict):
+        return False, "the verify surface returned a body that is not a verdict object"
+    if parsed.get(ALLOW_MARKER) is not True:
+        return False, "the verify surface did not allow this key"
+    named = parsed.get("key_id")
+    if named is not None and named != key_id:
+        # The response is about some other key. Accepting it would let a captured allow for one
+        # key authorize another, and would attribute usage to the wrong key id on this side.
+        return False, "the verify surface answered about a different key"
+    return True, "the verify surface allowed this key"
+
+
+def verify_api_key(
+    key: str,
+    *,
+    base_url: str,
+    transport: VerifyTransport | None = None,
+) -> KeyVerdict:
+    """Verify one presented key against cloud's verify surface, failing closed.
+
+    The key is sent in the ``x-api-key`` header and nowhere else: never in the URL, never in a
+    query string, never in a log line, never in the returned verdict.
+
+    ``key_id`` and ``key_format`` are computed locally *before* any request, so a denial still
+    hands back a usable non-secret identifier — the caller can report and count a rejected key
+    without ever holding the key again.
+
+    Fail closed is the default and is exhaustive. Every one of the following denies:
+
+    * any status other than 200, including 401, 403, 429, 5xx, and any 3xx redirect;
+    * any transport exception at all — connection refused, TLS failure, timeout, DNS failure;
+    * a body that is not strict canonical JSON, or is not an object;
+    * a body larger than :data:`MAX_VERIFY_RESPONSE_BYTES`;
+    * a body without the explicit allow marker, or naming a different key id.
+
+    A non-https ``base_url`` raises :class:`KeySeamError` before any request is attempted, because
+    that is a caller configuration bug and there is no safe way to proceed with it.
+
+    Raises:
+        KeySeamError: when ``key`` is not text or ``base_url`` is not an absolute https URL.
+    """
+
+    if not isinstance(key, str):
+        raise KeySeamError("an API key must be text")
+    url = _https_url(base_url, "the verify URL")
+    key_id = hash_key_id(key)
+    key_format = detect_key_format(key)
+    client = UrlLibVerifyTransport() if transport is None else transport
+
+    # One broad boundary catch, on purpose. Anything that goes wrong past this point becomes a
+    # denying verdict with a reason naming the class of fault, never a propagating exception whose
+    # message, traceback frame, or repr could carry the key that was in scope when it was raised.
+    try:
+        status, raw = client.request(
+            "POST",
+            url,
+            {API_KEY_HEADER: key, "Accept": "application/json"},
+            b"",
+            MAX_VERIFY_RESPONSE_BYTES,
+        )
+    except Exception:
+        return _denied(key_id, key_format, "the verify surface could not be reached")
+
+    if not isinstance(status, int) or status != 200:
+        if isinstance(status, int) and 300 <= status < 400:
+            return _denied(key_id, key_format, "the verify surface redirected, which is refused")
+        return _denied(key_id, key_format, "the verify surface did not confirm this key")
+
+    if not isinstance(raw, (bytes, bytearray)):
+        return _denied(key_id, key_format, "the verify surface returned a body that is not bytes")
+    if len(raw) > MAX_VERIFY_RESPONSE_BYTES:
+        return _denied(key_id, key_format, "the verify surface returned an oversized body")
+
+    allowed, reason = _allow_body_is_valid(bytes(raw), key_id)
+    return KeyVerdict(ok=allowed, key_id=key_id, key_format=key_format, reason=reason)

mostlyright/data_harness/linux_process_boundary.py

@@ -0,0 +1,262 @@
+"""Shared Linux/amd64 process hardening for hosted untrusted-data children."""
+
+from __future__ import annotations
+
+import ctypes
+import errno
+import platform
+import resource
+import sys
+
+_AUDIT_ARCH_X86_64 = 0xC000003E
+_PR_SET_DUMPABLE = 4
+_PR_GET_CHILD_SUBREAPER = 37
+_PR_SET_CHILD_SUBREAPER = 36
+_PR_SET_SECCOMP = 22
+_PR_SET_NO_NEW_PRIVS = 38
+_SECCOMP_MODE_FILTER = 2
+_SECCOMP_RET_KILL_PROCESS = 0x80000000
+_SECCOMP_RET_ERRNO = 0x00050000
+_SECCOMP_RET_ALLOW = 0x7FFF0000
+_BPF_LD_W_ABS = 0x20
+_BPF_JMP_JEQ_K = 0x15
+_BPF_JMP_JSET_K = 0x45
+_BPF_RET_K = 0x06
+_X32_SYSCALL_BIT = 0x40000000
+_NETWORK_SYSCALLS_X86_64 = (
+    41,  # socket
+    42,  # connect
+    43,  # accept
+    44,  # sendto
+    45,  # recvfrom
+    46,  # sendmsg
+    47,  # recvmsg
+    48,  # shutdown
+    49,  # bind
+    50,  # listen
+    51,  # getsockname
+    52,  # getpeername
+    53,  # socketpair
+    54,  # setsockopt
+    55,  # getsockopt
+    288,  # accept4
+    299,  # recvmmsg
+    307,  # sendmmsg
+    425,  # io_uring_setup
+    426,  # io_uring_enter
+    427,  # io_uring_register
+)
+_PROCESS_CREATION_SYSCALLS_X86_64 = (
+    56,  # clone
+    57,  # fork
+    58,  # vfork
+    435,  # clone3
+)
+_PROCESS_HANDLE_SYSCALLS_X86_64 = (
+    101,  # ptrace
+    310,  # process_vm_readv
+    311,  # process_vm_writev
+    312,  # kcmp
+    434,  # pidfd_open
+    438,  # pidfd_getfd
+)
+_PROCESS_CONTAINMENT_SYSCALLS_X86_64 = (
+    109,  # setpgid
+    112,  # setsid
+    272,  # unshare
+    308,  # setns
+)
+_CLONE_NAMESPACE_FLAGS = (
+    0x00000080  # CLONE_NEWTIME
+    | 0x00020000  # CLONE_NEWNS
+    | 0x02000000  # CLONE_NEWCGROUP
+    | 0x04000000  # CLONE_NEWUTS
+    | 0x08000000  # CLONE_NEWIPC
+    | 0x10000000  # CLONE_NEWUSER
+    | 0x20000000  # CLONE_NEWPID
+    | 0x40000000  # CLONE_NEWNET
+)
+_PROCESS_ESCAPE_SYSCALLS_X86_64 = tuple(
+    sorted(
+        (
+            *_PROCESS_CREATION_SYSCALLS_X86_64,
+            *_PROCESS_HANDLE_SYSCALLS_X86_64,
+            *_PROCESS_CONTAINMENT_SYSCALLS_X86_64,
+        )
+    )
+)
+_DENIED_CHILD_SYSCALLS_X86_64 = tuple(
+    sorted((*_NETWORK_SYSCALLS_X86_64, *_PROCESS_ESCAPE_SYSCALLS_X86_64))
+)
+
+
+class _SockFilter(ctypes.Structure):
+    _fields_ = (
+        ("code", ctypes.c_ushort),
+        ("jt", ctypes.c_ubyte),
+        ("jf", ctypes.c_ubyte),
+        ("k", ctypes.c_uint32),
+    )
+
+
+class _SockFprog(ctypes.Structure):
+    _fields_ = (
+        ("length", ctypes.c_ushort),
+        ("filter", ctypes.POINTER(_SockFilter)),
+    )
+
+
+def _child_subreaper_enabled() -> bool:
+    """Return this Linux process's child-subreaper state.
+
+    A short-lived, capability-free session monitor becomes a subreaper before it creates the
+    capability child.  If that child is force-killed, its sandbox process groups are reparented to
+    the monitor instead of the long-lived Service or container init, where the monitor can kill and
+    reap only those newly adopted descendants.  Other platforms have no equivalent primitive and
+    do not run hosted session isolation.
+    """
+
+    if sys.platform != "linux":
+        return False
+    value = ctypes.c_int()
+    libc = ctypes.CDLL(None, use_errno=True)
+    libc.prctl.restype = ctypes.c_int
+    libc.prctl.argtypes = (
+        ctypes.c_int,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+    )
+    if libc.prctl(_PR_GET_CHILD_SUBREAPER, ctypes.addressof(value), 0, 0, 0) != 0:
+        failure = ctypes.get_errno()
+        raise OSError(failure, "unable to inspect hosted session child-subreaper state")
+    return bool(value.value)
+
+
+def _set_child_subreaper(enabled: bool) -> None:
+    """Set the Linux child-subreaper state used by the session process monitor."""
+
+    if sys.platform != "linux":
+        return
+    libc = ctypes.CDLL(None, use_errno=True)
+    libc.prctl.restype = ctypes.c_int
+    libc.prctl.argtypes = (
+        ctypes.c_int,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+    )
+    if libc.prctl(_PR_SET_CHILD_SUBREAPER, int(enabled), 0, 0, 0) != 0:
+        failure = ctypes.get_errno()
+        raise OSError(failure, "unable to configure hosted session child-subreaper")
+
+
+def _disable_process_dumpability() -> None:
+    """Prevent same-UID subprocesses from reading a coordinator's live authority."""
+
+    if sys.platform != "linux":
+        return
+    libc = ctypes.CDLL(None, use_errno=True)
+    libc.prctl.restype = ctypes.c_int
+    libc.prctl.argtypes = (
+        ctypes.c_int,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+    )
+    if libc.prctl(_PR_SET_DUMPABLE, 0, 0, 0, 0) != 0:
+        failure = ctypes.get_errno()
+        raise OSError(failure, "unable to disable hosted coordinator dumpability")
+
+
+def _install_networkless_seccomp(*, allow_descendants: bool = False) -> None:
+    """Install an exec-inherited Linux/amd64 filter denying network creation and I/O.
+
+    The one-shot Courier child also denies process creation because it has no reason to fork.
+    Long-lived research-session parser children may retain their already-bounded thread/process
+    allowance; their descendants inherit this filter and the outer container cgroup, so the
+    network denial cannot be escaped by forking. Allowing descendants never restores ptrace,
+    cross-process memory access, or pidfd handles against the same-UID trusted coordinator.
+    """
+
+    if sys.platform != "linux" or platform.machine().lower() not in {"x86_64", "amd64"}:
+        raise OSError(errno.ENOTSUP, "hosted seccomp requires Linux/amd64")
+    instructions: list[tuple[int, int, int, int]] = [
+        (_BPF_LD_W_ABS, 0, 0, 4),
+        (_BPF_JMP_JEQ_K, 1, 0, _AUDIT_ARCH_X86_64),
+        (_BPF_RET_K, 0, 0, _SECCOMP_RET_KILL_PROCESS),
+        (_BPF_LD_W_ABS, 0, 0, 0),
+        (_BPF_JMP_JSET_K, 0, 1, _X32_SYSCALL_BIT),
+        (_BPF_RET_K, 0, 0, _SECCOMP_RET_ERRNO | errno.EPERM),
+    ]
+    denied_syscalls = _DENIED_CHILD_SYSCALLS_X86_64
+    if allow_descendants:
+        denied_syscalls = tuple(
+            sorted(
+                (
+                    *_NETWORK_SYSCALLS_X86_64,
+                    *_PROCESS_HANDLE_SYSCALLS_X86_64,
+                    *_PROCESS_CONTAINMENT_SYSCALLS_X86_64,
+                )
+            )
+        )
+        # Native runtimes need ordinary clone/fork for threads and bounded parser helpers. Keep
+        # them in the process group and namespace the trusted launcher created: classic clone is
+        # admitted only without namespace flags, while clone3 is reported unavailable so libc
+        # falls back to inspectable classic clone rather than passing an opaque struct pointer the
+        # classic seccomp filter cannot safely dereference.
+        instructions.extend(
+            (
+                (_BPF_JMP_JEQ_K, 0, 3, 56),  # clone
+                (_BPF_LD_W_ABS, 0, 0, 16),  # seccomp_data.args[0], low 32 bits
+                (_BPF_JMP_JSET_K, 0, 1, _CLONE_NAMESPACE_FLAGS),
+                (_BPF_RET_K, 0, 0, _SECCOMP_RET_ERRNO | errno.EPERM),
+                (_BPF_LD_W_ABS, 0, 0, 0),
+                (_BPF_JMP_JEQ_K, 0, 1, 435),  # clone3
+                (_BPF_RET_K, 0, 0, _SECCOMP_RET_ERRNO | errno.ENOSYS),
+            )
+        )
+    for syscall_number in denied_syscalls:
+        instructions.extend(
+            (
+                (_BPF_JMP_JEQ_K, 0, 1, syscall_number),
+                (_BPF_RET_K, 0, 0, _SECCOMP_RET_ERRNO | errno.EPERM),
+            )
+        )
+    instructions.append((_BPF_RET_K, 0, 0, _SECCOMP_RET_ALLOW))
+    filters = (_SockFilter * len(instructions))(
+        *(_SockFilter(*instruction) for instruction in instructions)
+    )
+    program = _SockFprog(
+        length=len(filters),
+        filter=ctypes.cast(filters, ctypes.POINTER(_SockFilter)),
+    )
+    libc = ctypes.CDLL(None, use_errno=True)
+    libc.prctl.restype = ctypes.c_int
+    libc.prctl.argtypes = (
+        ctypes.c_int,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+    )
+    resource.setrlimit(resource.RLIMIT_CORE, (0, 0))
+    _disable_process_dumpability()
+    if libc.prctl(_PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != 0:
+        failure = ctypes.get_errno()
+        raise OSError(failure, "unable to set hosted child no_new_privs")
+    if (
+        libc.prctl(
+            _PR_SET_SECCOMP,
+            _SECCOMP_MODE_FILTER,
+            ctypes.addressof(program),
+            0,
+            0,
+        )
+        != 0
+    ):
+        failure = ctypes.get_errno()
+        raise OSError(failure, "unable to install hosted child seccomp")