kern-sandbox 0.2.28 → 0.2.30

package/README.md

@@ -73,6 +73,11 @@ cargo install --git https://github.com/getkern/kern getkern --locked
 kern needs a Linux kernel with unprivileged user namespaces + cgroup v2. On Windows it runs under WSL2.
 Node 18+.
 
+The first call on a machine that has never run it is the slow one: it pulls `python:3.12-slim` before
+it can start a box. Every call after that reads the cached image, and the `startup_failed` row below
+has the measured cost of that first read, which on a slow machine is large enough to trip a short
+`timeoutS`.
+
 **On a Mac this package installs but cannot run**, and it says so rather than sending you after a
 download that does not exist: kern is Linux-only, because macOS has no namespaces and no cgroups. Run
 inside a Linux VM (colima, Lima, OrbStack, UTM), install `kern` and this package there, and it behaves
@@ -259,6 +264,28 @@ or Redis connection under `egressAllow` cannot resolve its host. For a database,
 `SandboxError`, so a caller can tell "this sandbox will not do that" from "the sandbox broke".
 `DEFAULT_TMPFS_MB` and `version` are exported for callers that assert on them.
 
+## The image decides more than the runtime does
+
+`run_code` that imports two standard-library modules measures **46.8 ms** on the default
+`python:3.12-slim`, against 13.8 ms for one that imports nothing. That tag ships 164 `.py` files in
+the standard library and 9 `.pyc`, so every import compiles its source. Precompiling the bytecode is
+one line and is worth **29 ms**, which is more than the box, the interpreter start and every runtime
+flag combined:
+
+```dockerfile
+FROM python:3.12-slim
+RUN python3 -m compileall -q -j 0 /usr/local/lib/python3.12
+```
+
+| `run_code` | `python:3.12-slim` | precompiled |
+|---|---:|---:|
+| `print(1)` | 13.82 ms | 12.27 ms |
+| `import json,re` | **46.82 ms** | **17.66 ms** |
+
+Build it once and pass it: `run_code(..., image="my-python")`. The default stays the stock tag,
+because an SDK that silently required a custom image would be worse than one that costs 29 ms and
+says so. Measured on an Intel i7-14700KF, Linux 7.0.0, idle; [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md) has the method.
+
 ## Prewarming: a box ready before the call arrives
 
 `prewarm: N` keeps N boxes started in advance, each holding a booted interpreter that has run nothing,

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.2.28";
+const VERSION = "0.2.29";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -1418,6 +1418,46 @@ class Sandbox {
     if (!(this.timeoutS > 0)) throw new SandboxError("timeoutS must be a positive number of seconds");
     if (!(this.maxOutputBytes > 0)) throw new SandboxError("maxOutputBytes must be positive");
 
+    // SHAPE GUARDS BEFORE ANYTHING CONSUMES THESE, the twin of the Python binding's and added after
+    // the same outside review swept the constructor argument by argument.
+    //
+    // THE JS FAILURE IS WORSE THAN THE PYTHON ONE, which is why this is not just symmetry. Python
+    // raises `AttributeError: 'list' object has no attribute 'items'` - useless, but obviously a
+    // type error. `Object.entries()` does NOT throw on an array or a string: it hands back index
+    // keys. MEASURED, `mounts: ["/tmp:/x"]` reached the mount validator as source `"0"` and reported
+    // `mount source must be an absolute host path, got "0"`, naming a value the caller never wrote,
+    // and `mounts: "/tmp:/x"` walked the string character by character and reported `cannot mount
+    // over the box essential mount "/"`. Both refuse, so nothing unsafe happened; both send the
+    // reader to look at a "0" or a "/" that exists nowhere in their code.
+    //
+    // `tmpfs` is deliberately NOT here: it documents an array form (a list of paths) and already
+    // refuses a bare string by name.
+    for (const [name, value] of [
+      ["mounts", this.mounts],
+      ["env", this.env],
+    ]) {
+      if (value === null || value === undefined) continue;
+      if (typeof value !== "object" || Array.isArray(value)) {
+        const example = name === "env" ? `{ KEY: "value" }` : `{ "/host/path": "/in/box" }`;
+        throw new SandboxError(
+          `${name} must be a plain object, not ${Array.isArray(value) ? "an array" : typeof value}: ` +
+            `write ${name}: ${example}`,
+        );
+      }
+    }
+    // A CALLBACK THAT IS NOT A FUNCTION is never called and says nothing, so the caller sees a
+    // sandbox that produces no output and has nothing to debug.
+    for (const [name, cb] of [
+      ["onStdout", this.onStdout],
+      ["onStderr", this.onStderr],
+    ]) {
+      if (cb !== null && cb !== undefined && typeof cb !== "function") {
+        throw new SandboxError(
+          `${name} must be a function (it is handed one chunk at a time), not ${typeof cb}`,
+        );
+      }
+    }
+
     this._mountArgs = [];
     const boundTargets = new Set();
     if (this.mounts) {
@@ -1489,6 +1529,22 @@ class Sandbox {
     if (!Array.isArray(this.capDrop))
       throw new SandboxError("capDrop must be an array of capability names");
     this._capDropArgs = this.capDrop.flatMap((c) => ["--cap-drop", validateCap(c)]);
+    // SKIP THE UID RANGE EXACTLY WHEN THE CAPABILITY IT SERVES IS BEING DROPPED ANYWAY, which is the
+    // default and costs a quarter of a cold box. `kern box --image` maps a sub-uid RANGE by default
+    // (so an image that degrades privilege in its entrypoint works), and mapping it forks two SETUID
+    // HELPERS. MEASURED: `parent:idmap` 22 us single-uid against ~1048 us ranged, and the whole box
+    // 3234 against 4298 us on this class's argv - paired, core-pinned, -1083 us (25%).
+    //
+    // IT BUYS THIS SANDBOX NOTHING when `ALL` is dropped, measured rather than argued: `setuid(1000)`
+    // inside a cell is refused either way under `--cap-drop ALL` (EPERM with the range, EINVAL
+    // without). WITHOUT it the range does work, so this is conditional: `capDrop: []` is a documented
+    // choice and keeps both the capability and the range.
+    //
+    // KEPT IDENTICAL TO THE PYTHON BINDING, including the condition: two spellings of one rule drift,
+    // and a caller who moved between the SDKs would meet a different box shape in each.
+    this._singleUid = this.capDrop.some(
+      (c) => String(c).toUpperCase().replace(/^CAP_/, "") === "ALL",
+    );
     this._profileArgs = (this.profiles || []).map(validateProfile);
     this._egressAllow = (this.egressAllow || []).map(validateDomain);
     if (this.apparmor !== null) validateApparmor(this.apparmor);
@@ -1633,6 +1689,7 @@ class Sandbox {
     }
     // kern's own --timeout is a tight BACKSTOP just beyond our deadline; OUR wait is the authority.
     argv.push(...this._capDropArgs);
+    if (this._singleUid) argv.push("--no-uid-range");
     argv.push("--timeout", String(Math.floor(timeoutS) + 5));
     if (this.memoryMb !== null) argv.push("--memory", `${this.memoryMb}m`);
     if (this.cpus !== null) argv.push("--cpus", String(this.cpus));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kern-sandbox",
-  "version": "0.2.28",
-  "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and LLM-generated code; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box, one per call, with no cloud, no account and no VM.",
+  "version": "0.2.30",
+  "description": "kern is a fast, rootless sandbox and virtual resource runtime; kern-sandbox is its Node/TypeScript binding. Run semi-trusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box, one per call, with no cloud, no account and no VM. A kernel boundary, not a microVM: for deliberately hostile multi-tenant code, use one.",
   "keywords": [
     "sandbox",
     "kern",