kern-sandbox 0.1.17 → 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.17";
+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,7 +1087,13 @@ 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);
+        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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.1.17",
+  "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",