kern-sandbox 0.1.19 → 0.1.21

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 and a `memoryMb` cap was **in force**: a breached `memory.max` is the cgroup OOM-killer (`memory.oom.group=1` kills the whole box). kern reports whether the cap actually bound on an unforgeable per-box channel (2nd byte of `KERN_STARTED_FD`), so this is an *enforced-cap* OOM |
+| `killed` | a SIGKILL **not** attributed to a cgroup OOM: no `memoryMb` cap was set, or kern reported the cap did not bind here (no cgroup delegation), so it is host pressure / an external kill. Older kern (no enforcement byte) falls back to `oom` when a cap was set |
 
 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

@@ -1043,6 +1043,7 @@ class Sandbox {
     return new Promise((resolve, reject) => {
       let child;
       let boxStarted = false;
+      let capSignal = 0; // 2nd started byte: 0 undetermined/old-kern, 1 memory cap enforced, 2 not enforced
       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.
@@ -1058,9 +1059,11 @@ class Sandbox {
 
       const startedCh = child.stdio[3];
       if (startedCh) {
-        // One byte (0x01) = the box started; stream end with no byte = never started / old kern.
+        // Byte 0 (0x01) = the box started; stream end with no byte = never started / old kern. Byte 1
+        // (a NEWER kern only, same atomic write) = the memory-cap enforcement signal; absent = 0.
         startedCh.on("data", (b) => {
           if (b.length && b[0] === 1) boxStarted = true;
+          if (b.length >= 2) capSignal = b[1];
         });
         startedCh.on("error", () => {});
       }
@@ -1087,7 +1090,7 @@ class Sandbox {
         const stdout = out.buffer().toString("utf8");
         const stderr = err.buffer().toString("utf8");
         const rc = toRc(code, signal);
-        let fault = this._classify(rc, signal, stderr, timedOut, timeoutS);
+        let fault = this._classify(rc, signal, stderr, timedOut, timeoutS, capSignal);
         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
@@ -1161,7 +1164,7 @@ class Sandbox {
     }
   }
 
-  _classify(rc, signal, stderr, timedOut, timeoutS) {
+  _classify(rc, signal, stderr, timedOut, timeoutS, capSignal = 0) {
     // ORDER IS A SECURITY PROPERTY: deterministic-by-exit-code classes are decided BEFORE the stderr
     // heuristic, because stderr is a channel the workload controls.
     if (timedOut)
@@ -1171,8 +1174,23 @@ 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). `capSignal` is kern's UNFORGEABLE
+      // enforcement byte (2nd byte of KERN_STARTED_FD, not the workload's stderr): 1 = enforced, 2 =
+      // requested but NOT enforced here, 0 = undetermined (old kern / no --memory). Claim `oom` when a
+      // --memory cap was set AND kern did not report it unenforced (capSignal !== 2): enforced (1) is a
+      // certain cgroup OOM, undetermined (0) keeps the pre-signal heuristic. When kern reports the cap did
+      // not bind (2), a SIGKILL cannot be attributed to the box's cgroup - keep the honest `killed`.
+      if (this.memoryMb !== null && capSignal !== 2)
+        return sandboxFault("oom", "the box exceeded its memory cap and was OOM-killed (SIGKILL, exit 137)");
+      if (capSignal === 2)
+        return sandboxFault(
+          "killed",
+          "the box was SIGKILLed, but its memory cap was not enforced here (no cgroup delegation), so it is not attributed to a cgroup OOM",
+        );
+      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
@@ -1637,6 +1655,10 @@ class Kernel {
     this._waiters = []; // FIFO of { resolve, timer }; one reply per request keeps them in order
     this._stderr = Buffer.alloc(0);
     this._dead = false;
+    // kern's memory-cap enforcement byte (2nd byte of KERN_STARTED_FD). For a RESIDENT box kern writes
+    // it only at box teardown (a cell kills the kernel), so it arrives ~concurrent with the death we
+    // detect on stdout; read once, bounded, on death (`_readCapSignal`). 0 = undetermined / old kern.
+    this._capSignal = 0;
   }
 
   async _open() {
@@ -1648,14 +1670,21 @@ class Kernel {
     this._name = uniqueName();
     this._childEnv = { ...process.env };
     if (!sbx.enforceLimits) this._childEnv.KERN_NO_SCOPE = "1";
+    this._childEnv.KERN_STARTED_FD = "3"; // same unforgeable channel; here for the enforcement byte only
     const argv = [
       ...sbx._baseArgv(this._name, { network: sbx.network, timeoutS: KERNEL_BACKSTOP_S }),
       "--", "python3", "-S", `${WORKSPACE}/${this._driver}`,
     ];
-    // detached: own process group so we can killpg the box + kern as a unit, like _spawn.
+    // detached: own process group so we can killpg the box + kern as a unit, like _spawn. fd 3 carries
+    // the started/enforcement bytes; the workload never holds it.
     this._child = spawn(argv[0], argv.slice(1), {
-      env: this._childEnv, detached: true, stdio: ["pipe", "pipe", "pipe"],
+      env: this._childEnv, detached: true, stdio: ["pipe", "pipe", "pipe", "pipe"],
     });
+    const startedCh = this._child.stdio[3];
+    if (startedCh) {
+      startedCh.on("data", (b) => { if (b.length >= 2) this._capSignal = b[1]; });
+      startedCh.on("error", () => {});
+    }
     this._child.on("error", () => { this._dead = true; this._flush(null); });
     this._child.on("close", () => { this._dead = true; this._flush(null); });
     this._child.stdout.on("data", (d) => this._onData(d));
@@ -1754,8 +1783,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, await this._readCapSignal());
+      return this._teardownResult(kind, err.trim() || dflt, started);
     }
     return this._resultFromReply(reply, started);
   }
@@ -1801,6 +1830,43 @@ 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 this is the runCode counterpart of the
+   * one-shot _classify SIGKILL branch - a kernel death has no per-cell exit code. `capSignal` is kern's
+   * unforgeable enforcement byte (0 = old kern / undetermined, 1 = memory cap enforced, 2 = requested
+   * but NOT enforced): with a memoryMb cap AND not-reported-unenforced (`!== 2`), the cgroup OOM-killer
+   * is the cause -> `oom`; when kern reports the cap did not bind (2), the kill is not attributable to
+   * the box's cgroup -> `killed`; uncapped is also `killed`. */
+  _kernelDeathFault(err, capSignal = 0) {
+    if (looksLikeStartupFailure(err)) return ["startup_failed", "the kernel box failed to start"];
+    if (this._sbx.memoryMb !== null && capSignal !== 2)
+      return ["oom", "the kernel box was OOM-killed (it exceeded its memory cap)"];
+    if (capSignal === 2)
+      return [
+        "killed",
+        "the kernel box was SIGKILLed, but its memory cap was not enforced here (no cgroup delegation), so it is not attributed to a cgroup OOM",
+      ];
+    return ["killed", "the kernel box exited"];
+  }
+
+  /** kern's memory-cap enforcement byte for the resident box, read ONCE on kernel death. kern writes
+   * the two-byte KERN_STARTED_FD signal only at box teardown (a resident box exits when a cell kills it),
+   * ~concurrent with the death detected on stdout. The fd-3 `data` handler in `_open` records the byte
+   * as it arrives; this awaits a BOUNDED window (the fd's own `end`, or 1 s) so the read is deterministic
+   * rather than a race, then returns the byte (0 = EOF / old kern / not yet -> the memoryMb heuristic). */
+  async _readCapSignal() {
+    const ch = this._child && this._child.stdio && this._child.stdio[3];
+    if (!ch) return 0;
+    if (this._capSignal === 0 && !ch.destroyed) {
+      await new Promise((res) => {
+        const t = setTimeout(res, 1000);
+        ch.once("end", () => { clearTimeout(t); res(); });
+        ch.once("error", () => { clearTimeout(t); res(); });
+      });
+    }
+    return this._capSignal;
+  }
+
   _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.19",
+  "version": "0.1.21",
   "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",