kern-sandbox 0.1.32 → 0.1.34

package/README.md

@@ -1,8 +1,8 @@
 # kern-sandbox (Node.js / TypeScript)
 
-**[kern](https://github.com/getkern/kern)** is a fast, rootless sandbox and virtual resource
+**[kern](https://getkern.dev)** 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.5 ms** from an OCI image, out of one **1.52 MB** binary, with no daemon.
+that starts in **~3.5 ms** from an OCI image, out of one static 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.52 MB, with no cloud, no account, no VM.
+itself enforces. Kernel-enforced isolation (namespaces, cgroups v2, seccomp), local, with no cloud, no account, no VM.
 
 ```js
 const kern = require("kern-sandbox");
@@ -113,6 +113,16 @@ A non-zero exit from *your code* is **not** a fault (`fault` stays `null`): it i
 | `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 |
 
+| `exec_failed` | the box started but the command did not exist inside it. `runCode(code, {language:"node"})` on an image with no `node` is the ordinary way to reach it; the message names the binary AND the image, because the remedy is a different `language` or a different `image`. The `language` enum is a convenience, not a promise about the image: the default `python:3.12-slim` carries `python` and `bash`. A shell's own `command not found` inside your script stays an ordinary non-zero exit |
+
+**An enforced `pids` cap produces no fault, and that is deliberate.** When `pids` binds, the refused
+`fork` returns `EAGAIN`. Code that catches it exits 0, so the call reports `fault: null, success:
+true` and a contained fork bomb reads as a successful run. `EAGAIN` is an ordinary errno a program is
+allowed to handle, unlike a SIGKILL it cannot; labelling it a sandbox fault would misreport a process
+that exited cleanly. Code that does **not** catch it dies naming "Resource temporarily unavailable".
+The cap itself is enforced: on WSL2, `pids: 32` blocked at 29 forks while `pids: 256` let 120 through,
+same code and same image.
+
 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
 returned as a fault, because the code never ran.
@@ -137,7 +147,12 @@ Every relaxing option says so in its name or docs:
 - **mounts refused**: sensitive host sources (`/`, `/etc`, `/root`, `/proc`, `/sys`, `/dev`, the docker
   socket, `$HOME`) and escaping targets are refused even when asked.
 - **workspace I/O contained**: `writeFile`/`readFile` reject `..` escapes and open the final component
-  `O_NOFOLLOW`, so a symlink the box plants cannot redirect host I/O outside the workspace.
+  `O_NOFOLLOW`, so a symlink the box plants cannot redirect host I/O outside the workspace. They also
+  open `O_NONBLOCK` and refuse a descriptor that is not a REGULAR file. A symlink is not the only thing
+  a box can leave at a name: `mkfifo out.png` used to make `readFile("out.png")` wait for a writer that
+  never comes, with no timeout, so the box chose how long the host's call took. The flag alone would be
+  worse than the hang, because a non-blocking read of a writer-less FIFO returns zero bytes and the
+  call would report an EMPTY FILE. Both halves ship: it returns promptly, and it refuses.
 
 ### Options
 

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" | "oom" | "escape_blocked" | "killed" | "startup_failed";
+export type SandboxFaultType = "timeout" | "oom" | "escape_blocked" | "killed" | "startup_failed" | "exec_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.32";
+const VERSION = "0.1.34";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -624,6 +624,28 @@ function toRc(code, signal) {
 
 /** True iff kern (the PARENT, before the box exists) failed to start the box. Anchored on kern's OWN
  * diagnostic prefixes so the workload can't forge them by writing the marker to its own stderr. */
+const EXEC_FAILED_RE = /^kern: cannot start '([^']+)' in box: ([^\n]*)/m;
+
+/** The binary kern could not exec, or null.
+ *
+ * A THIRD state, and the reason this exists: kern signals "box started" on its unforgeable fd BEFORE
+ * it execs the workload, so an `execve` that fails with ENOENT leaves a box that demonstrably started
+ * and a command that never ran. The classifier gets that right (kern's own marker is on stderr, so it
+ * says `startup_failed`) and the caller then ERASES it, because "box started + a kern: marker" is its
+ * signal that a WORKLOAD forged the marker. For this case that inference is wrong: the workload never
+ * ran, so it cannot have written anything.
+ *
+ * Matched on kern's own wording rather than on exit 127 alone, because 127 is also what a shell
+ * returns for `command not found` inside a script the user wrote, which IS the user's failure.
+ *
+ * A workload CAN print this line and exit 127 to be labelled `exec_failed` instead of a plain
+ * failure. That is accepted: it downgrades nothing security-relevant, because timeout, OOM and
+ * blocked-escape are decided by EXIT CODE before any stderr is read. */
+function execFailureBinary(stderr) {
+  const m = EXEC_FAILED_RE.exec(stderr || "");
+  return m ? { what: m[1], reason: (m[2] || "").trim() } : null;
+}
+
 function looksLikeStartupFailure(stderr) {
   const markers = [
     "kern:",
@@ -1101,7 +1123,28 @@ class Sandbox {
         const stderr = err.buffer().toString("utf8");
         const rc = toRc(code, signal);
         let fault = this._classify(rc, signal, stderr, timedOut, timeoutS, capSignal);
-        if (boxStarted && fault && fault.type === "startup_failed") {
+        const execFail = execFailureBinary(stderr);
+        if (execFail !== null && rc !== 0) {
+          // BEFORE the suppression below, which would erase it: the box started, so that branch
+          // would read kern's own marker as a workload forgery.
+          //
+          // The REASON is carried through rather than assumed. The first version said "does not
+          // exist in the box" for every case, and exit 126 (EACCES: the file is there and is not
+          // executable) and a script whose interpreter line names a missing binary both got a
+          // message blaming the image for a file that exists.
+          const { what, reason } = execFail;
+          let detail;
+          if (reason.includes("No such file or directory")) {
+            detail =
+              `No such file or directory. The image '${this.image}' does not provide it, or its ` +
+              `interpreter line names something the image lacks.`;
+          } else if (reason.includes("Permission denied")) {
+            detail = "Permission denied: it is present in the box but not executable there.";
+          } else {
+            detail = reason || "the box could not execute it";
+          }
+          fault = sandboxFault("exec_failed", `'${what}' could not be started in the box: ${detail}`);
+        } else 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.
@@ -1264,15 +1307,29 @@ class Sandbox {
     const payload = Buffer.isBuffer(data) ? data : Buffer.from(String(data));
     let fd;
     try {
+      // O_NONBLOCK for the same reason as readFile, and the write side is the WORSE of the two: opening
+      // a FIFO for writing blocks until a reader appears, and with the flag it fails outright (ENXIO)
+      // instead. Either way the call returns to the caller rather than parking there.
       fd = fs.openSync(
         full,
-        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW,
+        fs.constants.O_WRONLY |
+          fs.constants.O_CREAT |
+          fs.constants.O_TRUNC |
+          fs.constants.O_NOFOLLOW |
+          fs.constants.O_NONBLOCK,
         0o644,
       );
     } catch (e) {
       throw new SandboxError(`cannot write ${JSON.stringify(rel)}: ${e.message}`);
     }
     try {
+      // The file the box left at this name has to be a REGULAR file before we write into it: writing
+      // into a device node or a socket the box planted is host I/O it chose the target of.
+      if (!fs.fstatSync(fd).isFile())
+        throw new SandboxError(
+          `refusing to write ${JSON.stringify(rel)}: not a regular file (a FIFO, device or socket ` +
+            `planted in the workspace can stall or redirect this write)`,
+        );
       fs.writeSync(fd, payload);
     } finally {
       fs.closeSync(fd);
@@ -1330,14 +1387,28 @@ class Sandbox {
     this._verifyParentDirs(full); // fast reject + nice error before we open (host-leak guard)
     let fd;
     try {
-      fd = fs.openSync(full, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      // O_NONBLOCK: opening a FIFO returns a descriptor instead of WAITING FOR A WRITER. Measured
+      // before this flag: a box that runs `mkfifo out.png` makes `readFile("out.png")` hang with no
+      // timeout and no way to interrupt it, so the box decides how long the host's call takes. That is
+      // a denial of service the workspace hands out for free, and O_NOFOLLOW does not touch it.
+      fd = fs.openSync(full, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
     } catch (e) {
       throw new SandboxError(`cannot read ${JSON.stringify(rel)}: ${e.message}`);
     }
     try {
       this._assertFdInWorkspace(fd, rel); // race-free backstop: a swapped-in parent symlink is caught here
+      // AND THE FLAG ALONE WOULD BE WORSE THAN THE HANG. A non-blocking read of a writer-less FIFO
+      // returns zero bytes, so `readFile` would answer `<Buffer >` and the caller would read an empty
+      // file where the box had planted a pipe. Refuse anything that is not a REGULAR file: FIFO,
+      // device, socket, directory. Judged on the OPEN DESCRIPTOR, not on a path that can be swapped.
+      const st = fs.fstatSync(fd);
+      if (!st.isFile())
+        throw new SandboxError(
+          `refusing to read ${JSON.stringify(rel)}: not a regular file (a FIFO, device or socket ` +
+            `planted in the workspace can stall or fake this read)`,
+        );
       // maxBytes caps the read so a file a not-fully-trusted box wrote can't OOM the host.
-      if (maxBytes !== null && fs.fstatSync(fd).size > maxBytes)
+      if (maxBytes !== null && st.size > maxBytes)
         throw new SandboxError(`${JSON.stringify(rel)} exceeds maxBytes=${maxBytes}`);
       return fs.readFileSync(fd);
     } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "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",
@@ -15,7 +15,7 @@
     "jupyter",
     "e2b"
   ],
-  "homepage": "https://github.com/getkern/kern/tree/main/bindings/node",
+  "homepage": "https://getkern.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/getkern/kern.git",