kern-sandbox 0.1.12 → 0.1.14

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.6 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.8 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.
 
@@ -134,6 +134,10 @@ new Sandbox({
   pids,            // default 256
   timeoutS,        // default 30, MANDATORY per-call deadline
   network,         // default false (RELAXES ISOLATION)
+  capDrop,         // default ["ALL"]: capabilities dropped from every box. kern always drops
+                   // 13 dangerous ones; this drops the rest, which were held over the box's own
+                   // user namespace. Pass [] to keep them (needed only if the workload binds a
+                   // port below 1024 INSIDE the box).
   mounts,          // { hostSrc: boxTarget } or { src: [target, "ro"] }
   profiles,        // reusable kern.toml profiles: ["vcpu:heavy", "vgpio:leds", "vdisk:scratch"]
   env,             // { KEY: "value" }
@@ -177,7 +181,7 @@ can still WRITE an artifact to the workspace and `readFile` it if you prefer.
 **Warm kernel (kill the interpreter boot).** Each `runCode` starts a **fresh** interpreter, paying the
 CPython boot (~12 ms) every call. When you run many cells that share state (a REPL, a notebook, an
 agent's tool loop), open a `kernel()`: ONE warm interpreter in a long-lived box, fed cells over a pipe.
-In-memory state persists across cells and the per-cell cost drops from ~16 ms to **sub-millisecond**
+In-memory state persists across cells and the per-cell cost drops from ~14 ms to **sub-millisecond**
 (~300x). Same rich `results` capture as `runCode`.
 
 ```js

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.12";
+const VERSION = "0.1.14";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -552,6 +552,12 @@ function validateProfile(token) {
 // re-validates and SSRF-checks the resolved IPs; this is the binding's first gate.
 const DOMAIN_RE = /^(?=.{1,253}$)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]{2,63}$/;
 
+// A Linux capability name for `kern box --cap-drop`, with or without the CAP_ prefix, or the literal
+// ALL. Underscore-JOINED uppercase segments rather than "any of [A-Z0-9_]": the looser form accepts
+// "CAP_", because the optional prefix does not have to consume it. Not a way to smuggle a flag, but
+// a name kern rejects at box start, and validating here exists to fail at construction instead.
+const CAP_RE = /^(?=.{1,32}$)(?:CAP_)?[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/;
+
 /** Validate one egress-allowlist domain (an FQDN like "pypi.org") before it reaches the argv. */
 function validateDomain(domain) {
   if (typeof domain !== "string" || !DOMAIN_RE.test(domain))
@@ -562,6 +568,16 @@ function validateDomain(domain) {
   return domain;
 }
 
+/** Validate one capability name for `--cap-drop` before it reaches the argv. */
+function validateCap(name) {
+  if (typeof name !== "string" || !CAP_RE.test(name))
+    throw new SandboxError(
+      `invalid capability ${JSON.stringify(name)}: expected 'ALL' or an uppercase capability name ` +
+        "such as 'NET_BIND_SERVICE' or 'CAP_NET_BIND_SERVICE'",
+    );
+  return name;
+}
+
 /** Map a Node close event {code, signal} to a unix-style rc (128 + signum for a signal). */
 function toRc(code, signal) {
   if (typeof code === "number") return code;
@@ -765,6 +781,13 @@ class Sandbox {
     this.onStderr = opts.onStderr ?? null;
     this.enforceLimits = opts.enforceLimits ?? true;
     this.depsReadonly = opts.depsReadonly ?? false;
+    // Capabilities dropped from every box this sandbox starts, as kern's own `--cap-drop` takes them.
+    // The default drops the lot: kern already drops 13 dangerous capabilities unconditionally, but the
+    // rest were still held over the box's own user namespace, on the one code path whose purpose is
+    // running code nobody has read. Defence in depth rather than the boundary itself, and measured to
+    // cost nothing. It is NOT behaviour-free: a workload binding a port below 1024 INSIDE the box
+    // needs CAP_NET_BIND_SERVICE. Pass `capDrop: []` for the previous behaviour.
+    this.capDrop = opts.capDrop ?? ["ALL"];
     // trackFiles=true populates result.files by walking the workspace before AND after each call (O(N)
     // in file count); a long session that accretes files slows every runCode. false = result.files [], O(1).
     this.trackFiles = opts.trackFiles ?? true;
@@ -790,6 +813,17 @@ class Sandbox {
         this._mountArgs.push("-v", ro ? `${real}:${tgt}:ro` : `${real}:${tgt}`);
       }
     }
+    // A bare string has a .map-less shape here, but Array.from("ALL") would yield ["A","L","L"] and
+    // three bogus flags, so refuse the string by name and say what to write instead.
+    if (typeof this.capDrop === "string")
+      throw new SandboxError(
+        `capDrop must be an array of names, not a bare string: write capDrop: [${JSON.stringify(
+          this.capDrop,
+        )}] for one, or capDrop: [] to drop none`,
+      );
+    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)]);
     this._profileArgs = (this.profiles || []).map(validateProfile);
     this._egressAllow = (this.egressAllow || []).map(validateDomain);
     if (this._egressAllow.length && this.network)
@@ -881,6 +915,7 @@ class Sandbox {
       }
     }
     // kern's own --timeout is a tight BACKSTOP just beyond our deadline; OUR wait is the authority.
+    argv.push(...this._capDropArgs);
     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));
@@ -968,19 +1003,16 @@ class Sandbox {
       const err = cappedCollector(child.stderr, this.maxOutputBytes, cbErr);
       let timedOut = false;
       let settled = false;
-
-      const timer = setTimeout(() => {
-        timedOut = true;
-        this._teardown(child, name, childEnv);
-      }, timeoutS * 1000);
-
-      // Hard safety net: a CPU-bound box can survive our signals until kern's backstop reaps it; never
-      // hang the caller. If close hasn't fired a few seconds after our teardown, resolve anyway.
+      // Both timers are armed further down, once `finish` exists. They are declared here, as `let`,
+      // so the closures that clear them can never reference a binding in its temporal dead zone
+      // whatever the callback ordering turns out to be.
+      let timer = null;
       let hardTimer = null;
+
       const finish = (code, signal) => {
         if (settled) return;
         settled = true;
-        clearTimeout(timer);
+        if (timer) clearTimeout(timer);
         if (hardTimer) clearTimeout(hardTimer);
         // kern has read the file by the time it exits; leaving it behind would accrete one per call
         // in a persistent `workspace`.
@@ -1008,20 +1040,22 @@ class Sandbox {
       child.on("close", (code, signal) => {
         finish(code, signal);
       });
-      // arm the hard net only once we've decided to kill (teardown sets timedOut)
+      // Hard safety net: a CPU-bound box can survive our signals until kern's backstop reaps it;
+      // never hang the caller. If close hasn't fired a few seconds after our teardown, resolve anyway.
       const armHardNet = () => {
         if (hardTimer) return;
         hardTimer = setTimeout(() => finish(EXIT_SIGKILL, "SIGKILL"), 10000);
       };
-      // re-check shortly after the deadline in case teardown fired
-      const watch = setInterval(() => {
-        if (settled) {
-          clearInterval(watch);
-        } else if (timedOut) {
-          clearInterval(watch);
-          armHardNet();
-        }
-      }, 250);
+
+      timer = setTimeout(() => {
+        timedOut = true;
+        this._teardown(child, name, childEnv);
+        // Armed HERE, at the one place that decides to kill. It used to be noticed instead by a
+        // 250 ms setInterval that `finish` never cleared, so after every call that interval kept the
+        // event loop alive until its own next tick: measured 224 to 232 ms of dead time between a
+        // call resolving and the process being able to exit, against 19 to 27 ms of real work.
+        armHardNet();
+      }, timeoutS * 1000);
     });
   }
 
@@ -1726,7 +1760,24 @@ class Kernel {
       } catch {
         /* ignore */
       }
-      await new Promise((r) => setTimeout(r, 150));
+      // Wait for the exit EVENT, capped at 150 ms, rather than sleeping 150 ms unconditionally: that
+      // fixed sleep cost 152 ms on every close of a persistent kernel (measured) for a box that
+      // exits in a few. A child that is already gone has emitted `exit` and will not emit it again,
+      // so that case is tested directly instead of waited on.
+      if (child.exitCode === null && child.signalCode === null) {
+        await new Promise((resolve) => {
+          let t = null;
+          const onExit = () => {
+            if (t !== null) clearTimeout(t);
+            resolve();
+          };
+          t = setTimeout(() => {
+            child.removeListener("exit", onExit);
+            resolve();
+          }, 150);
+          child.once("exit", onExit);
+        });
+      }
       this._kill();
     } else {
       this._kill();

package/package.json

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