kern-sandbox 0.1.16 → 0.1.19

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.1.16";
+const VERSION = "0.1.19";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -465,6 +465,11 @@ class ExecutionResult {
   }
 }
 
+/** A sandbox event `{type, message}` for `result.fault`. NB: `startup_failed` is decided from an
+ * UNFORGEABLE kern signal (a byte on fd 3 / `KERN_STARTED_FD` a workload can neither write nor
+ * suppress). Against a kern too old to send it, the binding falls back to a stderr heuristic that can
+ * only OVER-report - a workload can make its own exit look like a start failure - never MISS a real
+ * one, so it fails in the safe direction. Pair this binding with the matching (or newer) kern release. */
 function sandboxFault(type, message) {
   return { type, message };
 }
@@ -621,8 +626,14 @@ function looksLikeStartupFailure(stderr) {
     "error: oci:",
     "error: image:",
   ];
+  // kern also writes BENIGN `kern:` diagnostics that are NOT a box-start failure: the
+  // `--security-profile` posture banner, and `warning:`/`note:` lines. They start with `kern:` too, so
+  // without this skip a workload that merely exits non-zero WHILE one is on stderr (e.g. code run under
+  // securityProfile: "untrusted" that hits a network error) would be mislabeled `startup_failed`.
+  const benign = ["kern: security-profile=", "kern: warning:", "kern: note:"];
   for (const line of stderr.split("\n")) {
     const s = line.replace(/^\s+/, "");
+    if (benign.some((b) => s.startsWith(b))) continue;
     if (s.includes("sandbox setup failed") || markers.some((m) => s.startsWith(m))) return true;
   }
   return false;
@@ -1021,22 +1032,39 @@ class Sandbox {
     const argv = [...this._baseArgv(name, { network, timeoutS, isSetup }), "--", ...command];
     const childEnv = { ...process.env };
     if (!this.enforceLimits) childEnv.KERN_NO_SCOPE = "1";
+    // Unforgeable "box started" channel: kern writes one byte to fd 3 iff its sandbox setup SUCCEEDED
+    // and the command ran. The workload never holds fd 3, so it can neither forge nor suppress it -
+    // unlike kern's stderr, which it can. A new kern makes this the authority for `startup_failed`; an
+    // OLD kern never writes it, `boxStarted` stays false, and the stderr heuristic stands (backward
+    // compatible).
+    childEnv.KERN_STARTED_FD = "3";
 
     const started = process.hrtime.bigint();
     return new Promise((resolve, reject) => {
       let child;
+      let boxStarted = false;
       try {
         // detached: own process group, so we can signal the box + kern as a unit (killpg).
+        // The 4th stdio slot is fd 3: the child (kern) writes the started byte, the parent reads it.
         child = spawn(argv[0], argv.slice(1), {
           env: childEnv,
           detached: true,
-          stdio: ["ignore", "pipe", "pipe"],
+          stdio: ["ignore", "pipe", "pipe", "pipe"],
         });
       } catch (e) {
         this._removeEnvFile(name);
         return reject(new SandboxError(`could not spawn the box: ${e.message}`));
       }
 
+      const startedCh = child.stdio[3];
+      if (startedCh) {
+        // One byte (0x01) = the box started; stream end with no byte = never started / old kern.
+        startedCh.on("data", (b) => {
+          if (b.length && b[0] === 1) boxStarted = true;
+        });
+        startedCh.on("error", () => {});
+      }
+
       const out = cappedCollector(child.stdout, this.maxOutputBytes, cbOut);
       const err = cappedCollector(child.stderr, this.maxOutputBytes, cbErr);
       let timedOut = false;
@@ -1059,12 +1087,20 @@ class Sandbox {
         const stdout = out.buffer().toString("utf8");
         const stderr = err.buffer().toString("utf8");
         const rc = toRc(code, signal);
-        const fault = this._classify(rc, signal, stderr, timedOut, timeoutS);
-        // A box that FAILED TO START (kern exits 125) ran no user code, so REJECT rather than resolve a
-        // hollow ExecutionResult (empty stdout, exit 125). Mirrors the mount/config errors this SDK
-        // already throws up front; runtime events where the code DID run (timeout, OOM, escape) stay as
-        // data on `.fault`.
-        if (fault && fault.type === "startup_failed") {
+        let fault = this._classify(rc, signal, stderr, timedOut, timeoutS);
+        if (boxStarted && fault && fault.type === "startup_failed") {
+          // kern signalled the box STARTED, so a `startup_failed` here is only the stderr heuristic
+          // matching a marker the WORKLOAD wrote (code-based faults are decided first). The box
+          // demonstrably ran: this is the workload's own non-zero exit - reclassify to a normal result.
+          fault = null;
+        }
+        // A box that FAILED TO START ran no user code, so REJECT rather than resolve a hollow
+        // ExecutionResult (empty stdout). Gated on `rc === 125` (kern's box-not-started code) AND the
+        // startup_failed classification (which requires kern's own stderr marker): the confident pair
+        // that tells a genuine box-not-started apart from a workload that itself exited 125 (no marker ->
+        // fault null -> a normal result). An older kern (127) is returned as a data fault, not thrown.
+        // Runtime events where the code DID run (timeout, OOM, escape) stay as data on `.fault`.
+        if (rc === 125 && fault && fault.type === "startup_failed") {
           return reject(new SandboxError(fault.message || "the box failed to start"));
         }
         const files = before ? this._diff(before) : [];
@@ -1139,11 +1175,11 @@ class Sandbox {
       return sandboxFault("killed", "the box was killed (SIGKILL) - likely out of memory (exit 137)");
     if (rc === EXIT_SIGTERM || signal === "SIGTERM")
       return sandboxFault("timeout", "the box exceeded its time limit (reaped by kern's timeout backstop)");
-    // DETERMINISTIC box-not-started: kern exits 125 (Docker's convention) when it could not BUILD the
-    // box (a mount refused at runtime, an unmappable --user, a seccomp/AppArmor/cgroup setup error), so
-    // the workload never ran. Decided by exit code, no stderr marker needed; the caller REJECTS on it.
-    if (rc === 125) return sandboxFault("startup_failed", stderr.trim().slice(0, 500) || "the box failed to start");
-    // LAST resort heuristic (also catches an OLDER kern that still exits 127 for a setup failure).
+    // Box-not-started: a non-zero exit whose stderr carries kern's OWN setup markers (printed by the
+    // PARENT before the box runs). kern's box-not-started paths BOTH exit 125 AND print a `kern:` marker,
+    // so `rc === 125 && marker` is the reliable signal - the marker is REQUIRED so a workload that merely
+    // exits 125 ITSELF (the code ran and chose 125) is NOT mislabeled. `finish` REJECTS only on rc===125;
+    // a non-125 startup_failed (an older kern's 127, or a forged marker) is returned as DATA, not thrown.
     if (rc !== 0 && looksLikeStartupFailure(stderr))
       return sandboxFault("startup_failed", stderr.trim().slice(0, 500));
     // Any other non-zero exit (incl. 139 SIGSEGV) is the USER's code failing - a normal Result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.1.16",
+  "version": "0.1.19",
   "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and AI-generated code; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box in single-digit milliseconds, with no cloud, no account and no VM.",
   "keywords": [
     "sandbox",