kern-sandbox 0.1.19 → 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

@@ -1171,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
@@ -1754,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);
   }
@@ -1801,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.19",
+  "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",