flashnode 0.2.0__py3-none-any.whl

flashnode/executor/docker_runner.py

@@ -0,0 +1,108 @@
+"""Tier-2 task runner: allowlisted container execution.
+
+Same `run(payload, workdir, inputs) → outdir` interface as
+`SubprocessRunner`; execution happens inside `docker run` with the AGENTS.md
+security contract: image allowlist (fail closed, checked before any
+subprocess), `--network none`, cpu/memory limits, read-only rootfs with the
+work directory as the only writable mount, host-uid user mapping (no root in
+the container's world), and a wall-clock timeout. The docker socket is used
+*by the agent* to launch the task — it is never mounted into the task.
+
+The task sees exactly one directory: its workdir bound at `/work`
+(spec.json in, inputs under /work/inputs, outputs to /work/out) — so
+spec.json is written with *container* paths, not host paths.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from flashnode.executor.hardening import CONTAINER_WORKDIR, container_name, harden_args
+from flashnode.executor.images import DEFAULT_ALLOWED_IMAGE_PREFIXES, image_is_allowed
+from flashnode.executor.runner import DEFAULT_ALLOWED_MODULES, TaskExecutionError
+
+
+class DockerRunner:
+    def __init__(
+        self,
+        allowed_images: frozenset[str] = frozenset(),
+        allowed_modules: frozenset[str] = DEFAULT_ALLOWED_MODULES,
+        cpus: float = 2.0,
+        memory_gb: float = 2.0,
+        timeout_seconds: float = 900.0,
+        allowed_image_prefixes: frozenset[str] = DEFAULT_ALLOWED_IMAGE_PREFIXES,
+    ):
+        # `allowed_images` now defaults to empty because the built-in
+        # namespace prefix is what a volunteer runs on. An empty exact list
+        # is no longer the "refusing to start" condition it once was — see
+        # executor/images.py for the two-knob model.
+        self.allowed_images = allowed_images
+        self.allowed_image_prefixes = allowed_image_prefixes
+        self.allowed_modules = allowed_modules
+        self.cpus = cpus
+        self.memory_gb = memory_gb
+        self.timeout_seconds = timeout_seconds
+
+    def run(self, payload: dict, workdir: Path, inputs: dict[str, Path]) -> Path:
+        module = payload.get("module", "")
+        if module not in self.allowed_modules:
+            raise TaskExecutionError(f"module {module!r} is not allowlisted — refusing to run")
+        image = payload.get("image")
+        if not image:
+            raise TaskExecutionError("payload carries no image — the docker runner requires one")
+        if not image_is_allowed(image, self.allowed_images, self.allowed_image_prefixes):
+            raise TaskExecutionError(f"image {image!r} is not allowlisted — refusing to run")
+
+        workdir = Path(workdir)
+        outdir = workdir / "out"
+        outdir.mkdir(parents=True, exist_ok=True)
+        (workdir / "spec.json").write_text(
+            json.dumps(
+                {
+                    "task_id": payload.get("task_id", ""),
+                    "params": payload.get("params", {}),
+                    # container paths: the task only ever sees /work
+                    "inputs": {
+                        name: f"{CONTAINER_WORKDIR}/{Path(path).relative_to(workdir)}"
+                        for name, path in inputs.items()
+                    },
+                }
+            )
+        )
+
+        name = container_name(payload.get("task_id"))
+        argv = [
+            "docker", "run", "--rm", "--name", name,
+            *harden_args(workdir, cpus=self.cpus, memory_gb=self.memory_gb),
+            image,
+            "python", "-m", module,
+            "--spec", f"{CONTAINER_WORKDIR}/spec.json",
+            "--out", f"{CONTAINER_WORKDIR}/out",
+        ]
+        try:
+            proc = subprocess.run(
+                argv, capture_output=True, timeout=self.timeout_seconds, check=False
+            )
+        except subprocess.TimeoutExpired:
+            # subprocess.run's timeout kills the docker CLIENT process, not
+            # the daemon-side container — it keeps running unless we kill it
+            # by name ourselves (same fix as ArgvDockerRunner; the leak was
+            # the reason hardening.py's container_name() is shared at all).
+            try:
+                subprocess.run(["docker", "kill", name], capture_output=True, timeout=10, check=False)
+            except Exception:
+                pass
+            raise TaskExecutionError(f"task exceeded {self.timeout_seconds}s wall clock")
+        except OSError as exc:
+            # `docker` missing/removed mid-run raises FileNotFoundError here
+            # (a subclass of OSError). Degrade to a failed task, not a dead
+            # agent — execute_one only catches TaskExecutionError/LeaseLost.
+            raise TaskExecutionError(f"docker is unavailable: {exc}") from exc
+        if proc.returncode != 0:
+            tail = proc.stderr.decode(errors="replace")[-800:]
+            raise TaskExecutionError(f"task exited {proc.returncode}: {tail}")
+        if not (outdir / "metrics.json").is_file():
+            raise TaskExecutionError("task produced no metrics.json — nothing to commit")
+        return outdir

flashnode/executor/hardening.py

@@ -0,0 +1,141 @@
+"""The container security contract, in one place.
+
+Every sandboxed runner builds its `docker run` flags here. Keeping this in a
+single function is deliberate: two runners maintaining their own flag lists
+drift, and the drift is invisible — the runner that quietly lost
+`--cap-drop=ALL` still passes all its behavioural tests.
+
+Changing this function changes the guarantee for ALL runners.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import uuid
+from pathlib import Path, PureWindowsPath
+
+CONTAINER_WORKDIR = "/work"
+
+# Docker container names must match [a-zA-Z0-9][a-zA-Z0-9_.-]*. We prefix
+# with "flashnode-" (always alnum-first) so the sanitized task_id segment
+# only has to avoid illegal characters, not worry about its own leading
+# character.
+_NAME_ILLEGAL = re.compile(r"[^A-Za-z0-9_.-]")
+
+
+def container_name(task_id: object) -> str:
+    """A Docker-legal, collision-resistant name for this attempt's container.
+
+    Shared by every sandboxed runner (docker_runner, argv_runner) so a
+    timed-out `docker run` can be killed by the SAME name it was launched
+    with — the whole reason this lives in hardening.py rather than being
+    reimplemented per runner (AGENTS.md: a single security-contract seam,
+    not two copies that can drift).
+
+    task_id comes from an untrusted payload — sanitize it into the name
+    rather than interpolating it raw. A random suffix (not task_id alone)
+    guarantees uniqueness even when two concurrent attempts share a task_id
+    (e.g. a retried attempt racing a slow-to-expire prior one).
+    """
+    safe = _NAME_ILLEGAL.sub("-", str(task_id or ""))
+    suffix = uuid.uuid4().hex[:8]
+    return f"flashnode-{safe}-{suffix}" if safe else f"flashnode-{suffix}"
+
+
+def _user_flag() -> list[str]:
+    """The `--user` flag, or nothing, depending on what the platform can
+    actually prove about identity.
+
+    - POSIX (`os.getuid`/`os.getgid` exist): pass the invoking user's real
+      uid:gid, exactly as before. Files written into the bind-mounted
+      workdir come back owned by the caller, not root.
+    - Windows: `os.getuid`/`os.getgid` don't exist, and Docker Desktop does
+      not map a host identity into the Linux container the way a native
+      Linux daemon does — there is no host uid to pass. Omitting `--user`
+      here is safe ONLY because every curated image
+      (flashml-cloud/images/*/Dockerfile) ends in a fixed non-root `USER`;
+      see that directory's README.md and flashml-cloud's
+      docs/superpowers/plans/2026-08-01-windows-hosts.md ("The trap at the
+      centre of this plan"). If any curated image ever regresses to
+      running as root, this omission silently runs strangers' code as
+      container root on every Windows host.
+    - Anything else: refuse. Security fields fail closed
+      (flashruntime/CLAUDE.md rule 3) — an unrecognised platform must not
+      silently produce a container running as an unknown, possibly root,
+      identity.
+    """
+    if hasattr(os, "getuid"):
+        return ["--user", f"{os.getuid()}:{os.getgid()}"]
+    if sys.platform == "win32":
+        return []
+    raise RuntimeError(
+        f"cannot determine a safe --user for platform {sys.platform!r}: "
+        "no os.getuid/os.getgid and not win32 — refusing to run "
+        "unprivileged-in-name-only"
+    )
+
+
+def _bind_mount_source(workdir: Path) -> str:
+    """Render `workdir` as the source half of `-v src:dst`, in a form
+    Docker's flag parser won't misinterpret.
+
+    `-v` splits its argument on ':'. A POSIX path never contains one, so it
+    passes through byte-identical (this must not change — see the plan's
+    Global Constraints). A Windows path (`C:\\Users\\phong\\...`) contains
+    both backslashes AND a drive-letter colon, which is ambiguous with the
+    src:dst separator itself — that raw form is what breaks the split.
+
+    Detecting "is this a Windows path" by `isinstance(..., PureWindowsPath)`
+    rather than `sys.platform == "win32"` is deliberate: a real `Path`
+    passed in while running on Windows already IS a `WindowsPath`, a
+    `PureWindowsPath` subclass, so the same branch handles the live case
+    and lets tests exercise it on any host with a synthetic
+    `PureWindowsPath` — no `sys.platform` gate to bit-rot in CI.
+
+    Rewrites `C:\\Users\\phong\\work` to `/c/Users/phong/work`: lowercase
+    drive letter, forward slashes, exactly one ':' left in the whole
+    argument (the src:dst separator). This is the form Docker Desktop's
+    Windows CLI accepts for bind-mount sources.
+    """
+    if isinstance(workdir, PureWindowsPath):
+        drive = workdir.drive  # e.g. "C:" — empty for a driveless path
+        if not drive:
+            raise ValueError(
+                f"Windows workdir {workdir!r} has no drive letter — cannot "
+                "build a Docker Desktop bind-mount source from it"
+            )
+        letter = drive.rstrip(":").lower()
+        rest = "/".join(workdir.parts[1:])
+        return f"/{letter}/{rest}" if rest else f"/{letter}"
+    return str(workdir)
+
+
+def harden_args(
+    workdir: Path,
+    *,
+    cpus: float,
+    memory_gb: float,
+    pids_limit: int = 512,
+) -> list[str]:
+    """Docker flags common to every sandboxed task."""
+    return [
+        # the job never reaches the volunteer's LAN or the internet; the
+        # agent is the courier for inputs, outputs, and checkpoints
+        "--network", "none",
+        "--read-only",
+        "--tmpfs", "/tmp:rw,noexec,nosuid,size=256m",
+        *_user_flag(),
+        "--cap-drop=ALL",
+        "--security-opt=no-new-privileges",
+        f"--pids-limit={pids_limit}",
+        "--cpus", str(cpus),
+        # equal values: with a larger memory-swap the memory cap is
+        # bypassable by swapping
+        "--memory", f"{memory_gb}g",
+        "--memory-swap", f"{memory_gb}g",
+        "--ulimit", "nofile=1024:1024",
+        "-v", f"{_bind_mount_source(workdir)}:{CONTAINER_WORKDIR}",
+        "-w", CONTAINER_WORKDIR,
+    ]

flashnode/executor/images.py

@@ -0,0 +1,161 @@
+"""Which container images this host will run, and why it is a prefix.
+
+A volunteer installs FlashNode and runs `flashnode work`. They do not build
+an image, do not log in to a registry, and do not maintain a list of image
+references — the built-in allowlist below is what makes that true. When the
+cloud publishes a new curated image, hosts pick it up on their next task
+with no action from their owner.
+
+WHY A NAMESPACE PREFIX RATHER THAN EXACT REFERENCES
+---------------------------------------------------
+Exact matching was the original design and it does not survive contact with
+more than a handful of machines: every published image would strand every
+host until its owner edited an env var, which in practice means the fleet
+runs a mix of versions and security fixes never fully land.
+
+The prefix is a namespace *we* control and publish to. It is genuinely
+weaker than three fixed strings, and the honest reason that is acceptable
+is this: the coordinator already tells a node which module to run, which
+argv to execute, and which inputs to fetch. An attacker who could name an
+arbitrary image has, by then, long since been able to name arbitrary work.
+The image allowlist defends against a *confused* coordinator naming
+something off-namespace — say `alpine` with a mounted socket — not against
+a fully compromised one. Pinning exact tags buys nothing against the latter
+while costing the whole fleet its ability to be updated.
+
+See M1_DECISIONS.md D16.
+
+WHAT THIS STILL REFUSES
+-----------------------
+- Anything outside the namespace, including near-misses that merely contain
+  it (`evil.example.com/ghcr.io/zolli-labs/flashml-x`).
+- References with no explicit tag or digest. Docker would silently append
+  `:latest`, which is a floating pointer to whatever was pushed last — the
+  exact mutability the curated-image tags are immutable to avoid.
+- Malformed references, rather than passing them to `docker run` and hoping
+  its parser agrees with ours about where the name ends.
+
+TWO DIFFERENT KNOBS, TWO DIFFERENT DIRECTIONS
+---------------------------------------------
+- ``FLASHNODE_ALLOWED_IMAGES`` (env, passed here as ``allowed_exact``) is
+  ADDITIVE. It is an operator/testing escape hatch — self-hosting the whole
+  stack, or an integration test running `python:3.11-alpine`. Anyone who can
+  set it can already run anything on that machine, so it grants nothing they
+  did not have.
+- ``policy.json`` ``allowed_images`` is SUBTRACTIVE. That is the host
+  *owner's* safety policy and it intersects with whatever the above permits
+  (see flashnode/config): an owner can forbid more, never permit code the
+  build does not trust.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "DEFAULT_ALLOWED_IMAGE_PREFIXES",
+    "InvalidImageReference",
+    "image_is_allowed",
+    "split_reference",
+]
+
+#: Namespace the cloud publishes curated task images to. Must stay in step
+#: with REGISTRY_PREFIX in flashml-cloud's apps/api/flashml_cloud_api/
+#: images.py — the e2e suite asserts every reference that API can emit is
+#: accepted here, because this seam has broken four times before and neither
+#: repo's own tests can see it (M1_DECISIONS.md D12).
+DEFAULT_ALLOWED_IMAGE_PREFIXES = frozenset({"ghcr.io/zolli-labs/flashml-"})
+
+# Deliberately stricter than the distribution spec. A reference we cannot
+# confidently parse is one we cannot confidently authorize, and every
+# reference we actually need is a plain lowercase path — so the safe reading
+# is to reject the exotic rest rather than approximate it.
+# Structure: an optional `host[:port]/`, then one or more lowercase path
+# components.
+#
+# The leading group exists for the port. A private registry is reached as
+# `registry.example:5000/team/img:2.0`, and while split_reference() gets the
+# tag boundary right (only a ':' after the final '/' can start a tag), the
+# name it hands back still carries that ':5000' — so a name pattern with no
+# room for a port would reject every self-hosted registry as malformed.
+#
+# The trailing path group is `*`, not `+`: a single-component name like
+# `python` is valid Docker Hub shorthand, and an owner who explicitly
+# allowlists one has named something real. It can never match a namespace
+# prefix (those all contain '/'), so permitting the shape costs nothing.
+_NAME_RE = re.compile(
+    r"^(?:[a-z0-9]+(?:[.-][a-z0-9]+)*(?::[0-9]{1,5})?/)?"
+    r"[a-z0-9]+(?:[._-][a-z0-9]+)*"
+    r"(?:/[a-z0-9]+(?:[._-][a-z0-9]+)*)*$"
+)
+_TAG_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$")
+_DIGEST_RE = re.compile(r"^sha256:[a-f0-9]{64}$")
+
+
+class InvalidImageReference(ValueError):
+    """A reference that could not be parsed, so could not be authorized."""
+
+
+def split_reference(image: str) -> tuple[str, str]:
+    """Split ``image`` into ``(name, tag_or_digest)``.
+
+    Raises ``InvalidImageReference`` for anything malformed or lacking an
+    explicit version. Splitting is done here, once, rather than at each call
+    site: authorizing the *whole* string by prefix would let a crafted tag
+    smuggle the namespace past the check, so every caller must be comparing
+    the same parsed name this function returns.
+    """
+    if not isinstance(image, str) or not image or image.strip() != image:
+        raise InvalidImageReference(f"not a usable image reference: {image!r}")
+    if any(c.isspace() or ord(c) < 32 for c in image):
+        raise InvalidImageReference(f"image reference contains whitespace or control characters: {image!r}")
+
+    # Digest form wins: `name@sha256:...` has no tag to strip afterwards.
+    if "@" in image:
+        name, _, digest = image.partition("@")
+        version = digest
+        if not _DIGEST_RE.match(digest):
+            raise InvalidImageReference(f"unsupported digest in {image!r} (want sha256:<64 hex>)")
+    else:
+        # A tag cannot contain '/', so only a ':' after the final '/' can be
+        # a tag separator — anything earlier is a registry port.
+        head, sep, tail = image.rpartition(":")
+        if sep and "/" not in tail:
+            name, version = head, tail
+            if not _TAG_RE.match(version):
+                raise InvalidImageReference(f"malformed tag in {image!r}")
+        else:
+            # No explicit version. Docker would default to `:latest`; we
+            # refuse instead, because a floating tag means the image a host
+            # runs is not the image the cloud validated the job against.
+            raise InvalidImageReference(
+                f"image {image!r} has no explicit tag or digest — refusing to "
+                "let docker default it to :latest"
+            )
+
+    if ".." in name or not _NAME_RE.match(name):
+        raise InvalidImageReference(f"malformed image name in {image!r}")
+    return name, version
+
+
+def image_is_allowed(
+    image: str,
+    allowed_exact: frozenset[str] = frozenset(),
+    allowed_prefixes: frozenset[str] = DEFAULT_ALLOWED_IMAGE_PREFIXES,
+) -> bool:
+    """Whether this host will run ``image``.
+
+    Fails closed: an unparseable reference is not allowed, never an
+    exception the caller might treat as an unrelated failure.
+
+    ``allowed_exact`` is the host owner's explicit list (env var or
+    policy.json) and is matched against the FULL reference — an owner naming
+    one exact pinned image means that image, not its namespace.
+    """
+    try:
+        name, _version = split_reference(image)
+    except InvalidImageReference:
+        return False
+    if image in allowed_exact:
+        return True
+    return any(name.startswith(prefix) for prefix in allowed_prefixes)