kern-sandbox 0.1.17 → 0.1.20

package/README.md

@@ -2,7 +2,7 @@
 
 **[kern](https://github.com/getkern/kern)** is a fast, rootless sandbox and virtual resource
 runtime for any workload, including untrusted and AI-generated code: a real, kernel-enforced box
-that starts in **3.4 ms** from an OCI image, out of one **~1.8 MB** binary, with no daemon.
+that starts in **3.4 ms** from an OCI image, out of one **1.58 MB** binary, with no daemon.
 **kern-sandbox**
 is its Node / TypeScript binding: run untrusted or agent-generated code in a fresh, isolated box, from Node.
 
@@ -11,7 +11,7 @@ package is on PyPI: [`kern-sandbox`](https://pypi.org/project/kern-sandbox/).
 
 It is a thin, dependency-free wrapper around the [`kern`](https://github.com/getkern/kern) binary:
 a fresh, isolated box per call, network off by default, hard resource caps, and a timeout the binding
-itself enforces. Kernel-enforced isolation (namespaces, cgroups v2, seccomp), local, about 1.8 MB, with no cloud, no account, no VM.
+itself enforces. Kernel-enforced isolation (namespaces, cgroups v2, seccomp), local, about 1.58 MB, with no cloud, no account, no VM.
 
 ```js
 const kern = require("kern-sandbox");
@@ -98,7 +98,8 @@ A non-zero exit from *your code* is **not** a fault (`fault` stays `null`): it i
 |---|---|
 | `timeout` | the call exceeded `timeoutS`; the binding killed the box |
 | `escape_blocked` | a syscall was blocked by the seccomp filter (SIGSYS) |
-| `killed` | the box was SIGKILLed, most often the cgroup OOM-killer |
+| `oom` | the box was SIGKILLed with a `memoryMb` cap in effect: a breached `memory.max` is the cgroup OOM-killer (`memory.oom.group=1` kills the whole box) |
+| `killed` | the box was SIGKILLed with **no** memory cap set, so the cause is ambiguous (host pressure, an external kill) and is not attributed to OOM |
 
 A box that fails to **start** (kern exits 125: a mount refused at runtime, an unmappable `--user`, a
 seccomp/AppArmor/cgroup setup error, or a pull/image error) is **thrown** as a `SandboxError`, not
@@ -225,11 +226,12 @@ clear error otherwise). The Python binding uses the stdlib `tarfile` and has no
 ## Honest threat model
 
 kern is a **kernel-boundary** sandbox for **your own or semi-trusted** code (CI, dev, edge, your
-agents' code). Its seccomp filter is a **denylist**: right for semi-trusted agent code, **not** a hard
-boundary against deliberately hostile multi-tenant code. For that, reach for a microVM (Firecracker /
-Kata) or gVisor. A deny-by-default seccomp **allowlist** ships as opt-in today: pass
-`securityProfile: "untrusted"` (or the `KERN_SECCOMP=allowlist` env); making it the default is future
-work. See the project's [SECURITY.md](https://github.com/getkern/kern/blob/main/SECURITY.md).
+agents' code). Its default seccomp filter is a **deny-by-default allowlist** (moby's own default
+filter minus kern's 35 escape syscalls): right for semi-trusted agent code, **not** a hard boundary
+against deliberately hostile multi-tenant code. For that, reach for a microVM (Firecracker / Kata) or
+gVisor. The wider denylist is the opt-out (`KERN_SECCOMP=denylist`), and `securityProfile: "untrusted"`
+bundles the allowlist with `--cap-drop ALL` + `--read-only`. See the project's
+[SECURITY.md](https://github.com/getkern/kern/blob/main/SECURITY.md).
 
 ## License
 

package/index.d.ts

@@ -2,7 +2,7 @@
 // Run LLM/agent-generated code in a fast, local, daemonless kernel sandbox.
 
 /** What stopped the code at the SANDBOX level. Reported as data on a result, never thrown. */
-export type SandboxFaultType = "timeout" | "escape_blocked" | "killed" | "startup_failed";
+export type SandboxFaultType = "timeout" | "oom" | "escape_blocked" | "killed" | "startup_failed";
 
 export interface SandboxFault {
   type: SandboxFaultType;

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
@@ -1137,8 +1171,15 @@ class Sandbox {
       );
     if (rc === EXIT_SIGSYS || signal === "SIGSYS")
       return sandboxFault("escape_blocked", "a syscall was blocked by the seccomp filter (SIGSYS)");
-    if (rc === EXIT_SIGKILL || signal === "SIGKILL")
-      return sandboxFault("killed", "the box was killed (SIGKILL) - likely out of memory (exit 137)");
+    if (rc === EXIT_SIGKILL || signal === "SIGKILL") {
+      // A memory-capped box SIGKILLed is the cgroup OOM-killer - what a breached memory.max does (kern
+      // sets memory.oom.group=1, so the whole box dies at once). Claim `oom` when a --memory cap was in
+      // effect: that is a fact WE set on the argv, not the workload's stderr, so it costs no security
+      // discipline. Uncapped, the cause is ambiguous (host pressure, an external kill) - keep `killed`.
+      if (this.memoryMb !== null)
+        return sandboxFault("oom", "the box exceeded its memory cap and was OOM-killed (SIGKILL, exit 137)");
+      return sandboxFault("killed", "the box was killed (SIGKILL); no memory cap was set to attribute it to OOM");
+    }
     if (rc === EXIT_SIGTERM || signal === "SIGTERM")
       return sandboxFault("timeout", "the box exceeded its time limit (reaped by kern's timeout backstop)");
     // Box-not-started: a non-zero exit whose stderr carries kern's OWN setup markers (printed by the
@@ -1720,8 +1761,8 @@ class Kernel {
       return this._teardownResult("killed", `the kernel reply exceeded the ${this._cap}-byte cap`, started);
     if (reply === null) {
       const err = this._stderr.toString("utf8");
-      const kind = looksLikeStartupFailure(err) ? "startup_failed" : "killed";
-      return this._teardownResult(kind, err.trim() || "the kernel box exited", started);
+      const [kind, dflt] = this._kernelDeathFault(err);
+      return this._teardownResult(kind, err.trim() || dflt, started);
     }
     return this._resultFromReply(reply, started);
   }
@@ -1767,6 +1808,19 @@ class Kernel {
     });
   }
 
+  /** Why the resident kernel box died mid-cell, as `[type, defaultMessage]`. A kern setup marker on
+   * stderr means it never came up (startup_failed). Otherwise, with a memoryMb cap in force, the cgroup
+   * OOM-killer is the dominant cause of a kernel that disappears while running a cell - the SAME
+   * attribution (from the same non-workload signal, the --memory flag WE set) as the one-shot _classify
+   * SIGKILL path. A kernel death has no per-cell exit code to route through _classify, so the OOM
+   * attribution lives here too. Uncapped, the cause is ambiguous -> `killed`. */
+  _kernelDeathFault(err) {
+    if (looksLikeStartupFailure(err)) return ["startup_failed", "the kernel box failed to start"];
+    if (this._sbx.memoryMb !== null)
+      return ["oom", "the kernel box was OOM-killed (it exceeded its memory cap)"];
+    return ["killed", "the kernel box exited"];
+  }
+
   _teardownResult(type, message, started) {
     this._kill();
     // Same rule as the one-shot path: a box that never STARTED (the kernel failed to boot) throws, it

package/package.json

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