flashnode 0.3.3__tar.gz → 0.3.4__tar.gz

{flashnode-0.3.3 → flashnode-0.3.4}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: flashnode
-Version: 0.3.3
+Version: 0.3.4
 Summary: Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/Zolli-Labs/flashnode
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flashruntime<0.5,>=0.4.2
+Requires-Dist: flashruntime<0.5,>=0.4.3
 Requires-Dist: psutil>=5.9
 Requires-Dist: websockets>=12
 Requires-Dist: cryptography>=42

{flashnode-0.3.3 → flashnode-0.3.4}/flashnode/agent/cli.py

@@ -174,9 +174,10 @@ def _work(args: list[str]) -> int:
     )
     parser.add_argument(
         "--runner",
-        choices=["subprocess", "docker", "argv"],
+        choices=["subprocess", "docker", "argv", "trusted"],
         default=os.environ.get("FLASHNODE_RUNNER", "subprocess"),
-        help="task execution tier (docker/argv need the docker CLI on PATH)",
+        help="task execution tier (docker/argv need the docker CLI on PATH; "
+             "trusted runs pool jobs unsandboxed — opt-in only)",
     )
     parser.add_argument("--max-tasks", type=int, default=None)
     parser.add_argument("--poll-seconds", type=float, default=1.0)
@@ -260,6 +261,19 @@ def _work(args: list[str]) -> int:
                     os.environ.get("FLASHNODE_MAX_OUTPUT_BYTES", str(2 * 1024**3))
                 ),
             )
+    elif opts.runner == "trusted":
+        # Deliberately OUTSIDE the ("docker", "argv") branch above: this
+        # tier has no container and no docker CLI dependency, so the docker
+        # doctor gate has nothing to check — same as subprocess. The only
+        # gate here is the operator typing --runner trusted at all.
+        from flashnode.executor.trusted_runner import TrustedArgvRunner
+
+        print(
+            "trusted runner: pool jobs from your team run UNSANDBOXED on this\n"
+            "machine — no container, no network isolation. Only continue if\n"
+            "every member of your pool is someone you trust to run code here."
+        )
+        runner = TrustedArgvRunner()
 
     workdir_base = os.environ.get("FLASHNODE_WORKDIR") or None
 
@@ -280,6 +294,11 @@ def _work(args: list[str]) -> int:
         # tasks burn every attempt against ArgvDockerRunner's payload
         # rejection before the job ever fails for real.
         module_capable=(opts.runner != "argv"),
+        # Set true ONLY by the explicit --runner trusted opt-in, never
+        # inferred — the scheduler's placement gate treats this field as
+        # fail-closed (flashruntime.scheduler), so a node that merely has a
+        # shell available must not advertise it.
+        unsandboxed_argv_capable=(opts.runner == "trusted"),
     )
     client.register(registration)
     from flashnode.doctor import NON_BLOCKING_STATUSES, run_checks

flashnode-0.3.4/flashnode/executor/trusted_runner.py

@@ -0,0 +1,83 @@
+"""Trusted-pool argv execution: no container, no sandbox, by explicit
+operator opt-in only.
+
+This runner exists for hosts that CANNOT run Docker — Colab notebooks and
+provider pods are themselves containers — inside a team pool whose members
+chose to trust each other. It is not a security boundary and never claims
+to be: the placement contract (pool + allowFallback + the operator's
+--runner trusted opt-in) is what keeps strangers' code away from it.
+
+Same interface as SubprocessRunner/ArgvDockerRunner:
+run(payload, workdir, inputs) -> outdir.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from flashnode.executor.runner import TaskExecutionError, task_env
+
+_CONTAINER_WORKDIR = "/work"
+
+
+class TrustedArgvRunner:
+    def __init__(self, timeout_seconds: float = 600.0):
+        self.timeout_seconds = timeout_seconds
+        # Evidence attributes, same contract and same reset rule as
+        # SubprocessRunner: a stale value is a measurement of a DIFFERENT
+        # run wearing this one's name.
+        self.last_exit_code: int | None = None
+        #: Always "" — no image bytes executed; echoing the payload's image
+        #: reference would claim a container ran when none did.
+        self.last_image_digest: str = ""
+
+    def run(self, payload: dict, workdir: Path, inputs: dict[str, Path]) -> Path:
+        self.last_exit_code = None
+        workdir = Path(workdir)
+        argv = payload.get("argv")
+        if not isinstance(argv, list) or not argv or not all(
+            isinstance(a, str) for a in argv
+        ):
+            raise TaskExecutionError(
+                "trusted runner requires a payload with a string-list 'argv'"
+            )
+        # Rewrite /work-prefixed TOKENS onto the real workdir. Token-wise,
+        # never substring: an argument that merely contains "/work" belongs
+        # to the submitter. The compiled argv uses /work because the docker
+        # runners bind the workdir there; this runner has no container, so
+        # /work is a naming convention to honour, not a mount to make.
+        rewritten = [
+            str(workdir) + a[len(_CONTAINER_WORKDIR):]
+            if a == _CONTAINER_WORKDIR or a.startswith(_CONTAINER_WORKDIR + "/")
+            else a
+            for a in argv
+        ]
+        outdir = workdir / "out"
+        outdir.mkdir(parents=True, exist_ok=True)
+        try:
+            proc = subprocess.run(
+                rewritten,
+                cwd=workdir,
+                env=task_env(),
+                timeout=self.timeout_seconds,
+                capture_output=True,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise TaskExecutionError(
+                f"task exceeded {self.timeout_seconds}s"
+            ) from exc
+        except OSError as exc:
+            raise TaskExecutionError(f"could not start task: {exc}") from exc
+        self.last_exit_code = proc.returncode
+        if proc.returncode != 0:
+            tail = proc.stderr.decode(errors="replace")[-2000:]
+            raise TaskExecutionError(
+                f"task exited {proc.returncode}: {tail}"
+            )
+        if not (outdir / "metrics.json").is_file():
+            # Same rule as both sibling runners: an exit-0 workload that
+            # wrote no metrics is a task failure HERE, attributably — not a
+            # mysterious commit rejection three hops later.
+            raise TaskExecutionError("task produced no metrics.json — nothing to commit")
+        return outdir

{flashnode-0.3.3 → flashnode-0.3.4}/flashnode/inventory/capabilities.py

@@ -62,7 +62,8 @@ def _parse_k8s_memory(value: str) -> int:
 def discover(node_id: str, kubernetes_node: str,
              node_meta: dict | None = None,
              argv_capable: bool = False,
-             module_capable: bool = True) -> NodeRegistration:
+             module_capable: bool = True,
+             unsandboxed_argv_capable: bool = False) -> NodeRegistration:
     """Build the registration payload. `node_meta` is the Kubernetes Node
     object (status/metadata) when the agent has API access; None degrades to
     host-level probes only."""
@@ -127,6 +128,8 @@ def discover(node_id: str, kubernetes_node: str,
         # coordinator's module gate is fail-open (unlike argv_capable), so
         # the default here matches every caller that doesn't pass it.
         module_capable=module_capable,
+        # Set by the agent only for `--runner trusted` — never inferred.
+        unsandboxed_argv_capable=unsandboxed_argv_capable,
         # The LABELS of the datasets this host owner lends to tasks
         # (FLASHNODE_LOCAL_DATA) — never the paths. The coordinator needs the
         # names to place a job that requires `patients` on a machine that has

{flashnode-0.3.3 → flashnode-0.3.4}/flashnode.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: flashnode
-Version: 0.3.3
+Version: 0.3.4
 Summary: Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits.
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/Zolli-Labs/flashnode
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flashruntime<0.5,>=0.4.2
+Requires-Dist: flashruntime<0.5,>=0.4.3
 Requires-Dist: psutil>=5.9
 Requires-Dist: websockets>=12
 Requires-Dist: cryptography>=42

{flashnode-0.3.3 → flashnode-0.3.4}/flashnode.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ flashnode/executor/hardening.py
 flashnode/executor/images.py
 flashnode/executor/loop.py
 flashnode/executor/runner.py
+flashnode/executor/trusted_runner.py
 flashnode/identity/__init__.py
 flashnode/identity/credentials.py
 flashnode/identity/enrol.py
@@ -42,6 +43,7 @@ tests/test_archives.py
 tests/test_argv_runner.py
 tests/test_capabilities.py
 tests/test_checkpoint_relay.py
+tests/test_cli_trusted.py
 tests/test_credentials.py
 tests/test_docker_runner.py
 tests/test_doctor.py
@@ -57,5 +59,6 @@ tests/test_interfaces.py
 tests/test_local_data.py
 tests/test_loop_counters.py
 tests/test_status.py
+tests/test_trusted_runner.py
 tests/test_work_gate.py
 tests/test_work_status.py

{flashnode-0.3.3 → flashnode-0.3.4}/flashnode.egg-info/requires.txt

@@ -1,4 +1,4 @@
-flashruntime<0.5,>=0.4.2
+flashruntime<0.5,>=0.4.3
 psutil>=5.9
 websockets>=12
 cryptography>=42

{flashnode-0.3.3 → flashnode-0.3.4}/pyproject.toml

@@ -15,7 +15,12 @@ name = "flashnode"
 # flashruntime 0.4.2's ExecutionEvidence — see the floor below. Bumped even
 # though nothing breaks: an agent whose wire behaviour differs must not share
 # a version string with one that predates it.
-version = "0.3.3"
+# 0.3.4 adds `--runner trusted` (TrustedArgvRunner): unsandboxed argv
+# execution, opt-in only, for hosts that cannot run Docker (Colab, provider
+# pods) inside a team pool whose members trust each other. `discover()` now
+# passes `unsandboxed_argv_capable` to NodeRegistration — see the floor
+# below for why that moves the pin in this commit, not just at tag time.
+version = "0.3.4"
 description = "Open host agent for the FlashML fragmented-compute network: join, benchmark, execute sandboxed ML tasks, earn contribution credits."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -49,7 +54,15 @@ dependencies = [
     # not exist in the published 0.4.1 wheel. The agent raises ImportError and
     # never registers at all. The release workflow's `resolvable` job runs
     # `flashnode --help` against PyPI alone precisely to catch this.
-    "flashruntime>=0.4.2,<0.5",
+    # Raised again to >=0.4.3 for `--runner trusted`: `discover()` now passes
+    # `unsandboxed_argv_capable` to NodeRegistration, a field 0.4.2's model
+    # does not declare. Unlike the two floors above, this is not an
+    # import-time ImportError — it is pydantic refusing an unknown kwarg at
+    # CALL time, inside `flashnode work`, on every runner tier, not just
+    # trusted. Same import-time-hard-failure shape as 0.3.2/0.3.3 in effect
+    # (the agent never registers), so the floor moves in this commit, not at
+    # tag time.
+    "flashruntime>=0.4.3,<0.5",
     "psutil>=5.9",
     "websockets>=12",
     "cryptography>=42",

flashnode-0.3.4/tests/test_cli_trusted.py

@@ -0,0 +1,74 @@
+"""--runner trusted: the opt-in wiring. The flag is the ONLY path to
+unsandboxed_argv_capable=True — discover() must default it False for every
+other caller (security fields fail closed)."""
+
+from flashnode.inventory.capabilities import discover
+
+
+def test_discover_defaults_unsandboxed_argv_capable_false():
+    reg = discover("n-1", kubernetes_node="")
+    assert reg.unsandboxed_argv_capable is False
+
+
+def test_discover_can_opt_in():
+    reg = discover("n-1", kubernetes_node="", unsandboxed_argv_capable=True)
+    assert reg.unsandboxed_argv_capable is True
+    assert reg.argv_capable is False  # trusted is NOT the containerised contract
+
+
+def test_trusted_runner_selected_for_runner_trusted(monkeypatch, tmp_path, capsys):
+    """--runner trusted must:
+      - build a TrustedArgvRunner (passed to ExecutorLoop)
+      - register with unsandboxed_argv_capable=True, argv_capable=False
+      - NEVER invoke the docker doctor gate (trusted is outside the
+        ("docker", "argv") branch, same as subprocess)
+      - print a plain-words warning that pool jobs run unsandboxed
+
+    Mirrors test_agent.py::test_work_cli_sets_module_capable_from_runner_choice.
+    """
+    import flashnode.inventory.capabilities as capabilities_mod
+    from flashnode.agent import cli
+    from flashnode.executor import CoordinatorClient, ExecutorLoop
+    from flashnode.executor.trusted_runner import TrustedArgvRunner
+
+    monkeypatch.setenv("FLASHNODE_STATE_DIR", str(tmp_path))
+
+    # The docker doctor gate must not run for --runner trusted. Rather than
+    # counting calls, make one explode: any invocation fails the test loudly
+    # and precisely where it happened.
+    def _boom(**kw):
+        raise AssertionError("doctor.run_checks must not run for --runner trusted")
+
+    monkeypatch.setattr("flashnode.doctor.run_checks", _boom)
+
+    captured = {}
+    real_discover = capabilities_mod.discover
+
+    def spy_discover(*args, **kwargs):
+        reg = real_discover(*args, **kwargs)
+        captured["registration"] = reg
+        return reg
+
+    monkeypatch.setattr(capabilities_mod, "discover", spy_discover)
+    monkeypatch.setattr(CoordinatorClient, "register", lambda self, reg: None)
+
+    real_init = ExecutorLoop.__init__
+
+    def spy_init(self, *args, **kwargs):
+        captured["runner"] = kwargs.get("runner")
+        return real_init(self, *args, **kwargs)
+
+    monkeypatch.setattr(ExecutorLoop, "__init__", spy_init)
+    monkeypatch.setattr(ExecutorLoop, "run", lambda self, max_tasks=None: 0)
+
+    rc = cli.main(["work", "--runner", "trusted", "--coordinator", "http://localhost:1"])
+
+    assert rc == 0
+    assert isinstance(captured["runner"], TrustedArgvRunner)
+
+    reg = captured["registration"]
+    assert reg.unsandboxed_argv_capable is True
+    assert reg.argv_capable is False
+
+    out = capsys.readouterr().out
+    assert "unsandboxed" in out.lower()

flashnode-0.3.4/tests/test_trusted_runner.py

@@ -0,0 +1,92 @@
+"""TrustedArgvRunner: pool argv payloads, no container, /work rewritten.
+
+The compiled argv names CONTAINER paths (`python /work/inputs/code/train.py`
+— the docker runners bind the workdir at /work). Here there is no container,
+so every argv token starting with /work is rewritten onto the real workdir.
+Rewriting tokens, not substrings: an argument that merely CONTAINS "/work"
+is the submitter's business.
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from flashnode.executor.runner import TaskExecutionError
+from flashnode.executor.trusted_runner import TrustedArgvRunner
+
+
+def _payload(argv):
+    return {"argv": argv, "isolation": {"tier": "sandboxed", "allowFallback": True},
+            "pool": "p-1"}
+
+
+def test_runs_the_argv_with_work_prefix_rewritten(tmp_path):
+    workdir = tmp_path
+    code = workdir / "inputs" / "code"
+    code.mkdir(parents=True)
+    (code / "train.py").write_text(
+        "import json, pathlib, sys\n"
+        "out = pathlib.Path(sys.argv[1]); out.mkdir(parents=True, exist_ok=True)\n"
+        "(out / 'metrics.json').write_text(json.dumps({'ok': True}))\n"
+    )
+    runner = TrustedArgvRunner()
+    outdir = runner.run(
+        _payload(["python", "/work/inputs/code/train.py", "/work/out"]),
+        workdir, {"code": code},
+    )
+    assert json.loads((outdir / "metrics.json").read_text()) == {"ok": True}
+    assert runner.last_exit_code == 0
+
+
+def test_refuses_a_payload_without_argv(tmp_path):
+    with pytest.raises(TaskExecutionError):
+        TrustedArgvRunner().run({"module": "flashml_workloads.sklearn_trial"},
+                                tmp_path, {})
+
+
+def test_refuses_a_non_list_argv(tmp_path):
+    with pytest.raises(TaskExecutionError):
+        TrustedArgvRunner().run(_payload("python /work/x.py"), tmp_path, {})
+
+
+def test_nonzero_exit_raises_and_records_the_code(tmp_path):
+    (tmp_path / "inputs").mkdir()
+    runner = TrustedArgvRunner()
+    with pytest.raises(TaskExecutionError):
+        runner.run(_payload(["python", "-c", "raise SystemExit(3)"]), tmp_path, {})
+    assert runner.last_exit_code == 3
+
+
+def test_environment_is_scrubbed(tmp_path, monkeypatch):
+    """The task must not inherit the agent's secrets — same whitelist as
+    SubprocessRunner (task_env). The out path travels as an argv token so
+    the /work rewrite applies to it."""
+    monkeypatch.setenv("FLASHNODE_MACHINE_TOKEN", "fmk_secret")
+    probe = tmp_path / "probe.py"
+    probe.write_text(
+        "import json, os, pathlib, sys\n"
+        "out = pathlib.Path(sys.argv[1]); out.mkdir(parents=True, exist_ok=True)\n"
+        "(out / 'env.txt').write_text(str('FLASHNODE_MACHINE_TOKEN' in os.environ))\n"
+        "(out / 'metrics.json').write_text(json.dumps({'env_scrubbed': True}))\n"
+    )
+    runner = TrustedArgvRunner()
+    runner.run(_payload(["python", str(probe), "/work/out"]), tmp_path, {})
+    assert (tmp_path / "out" / "env.txt").read_text() == "False"
+
+
+def test_exit_zero_without_metrics_json_raises(tmp_path):
+    """Mirrors SubprocessRunner/ArgvDockerRunner: metrics.json is
+    load-bearing; exit 0 without it is a task error, not a success."""
+    probe = tmp_path / "probe.py"
+    probe.write_text("print('did nothing')\n")
+    runner = TrustedArgvRunner()
+    with pytest.raises(TaskExecutionError, match="metrics.json"):
+        runner.run(_payload(["python", str(probe)]), tmp_path, {})
+    assert runner.last_exit_code == 0
+
+
+def test_image_digest_is_always_empty():
+    """No container ran; claiming an image digest would be fabricated
+    evidence (the SubprocessRunner rule)."""
+    assert TrustedArgvRunner().last_image_digest == ""