kern-sandbox 0.1.14 → 0.1.16

package/README.md

@@ -33,10 +33,11 @@ import { runCode, withSandbox, Sandbox } from "kern-sandbox";
 npm install kern-sandbox
 ```
 
-You also need the `kern` binary on `PATH` (or point `$KERN_BIN` at it). One line on Linux:
+You also need the `kern` binary on `PATH` (or point `$KERN_BIN` at it). Build it on Linux (no
+prebuilt binaries are published yet):
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/getkern/kern/main/install.sh | sh
+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.
@@ -98,7 +99,10 @@ 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 |
-| `startup_failed` | kern could not start the box (bad image, pull error, ...) |
+
+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.
 
 ```js
 const r = await kern.runCode("while True: pass", { timeoutS: 5 });
@@ -135,7 +139,7 @@ new Sandbox({
   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
+                   // 14 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"] }
@@ -143,6 +147,11 @@ new Sandbox({
   env,             // { KEY: "value" }
   maxOutputBytes,  // default 64 MiB
   enforceLimits,   // default true; false is best-effort and NO faster (see the Python README)
+  securityProfile, // "untrusted" = seccomp allowlist + cap-drop ALL + read-only root, one opt-in bundle
+  apparmor,        // a PRE-LOADED AppArmor profile the box enters on exec (Docker's --security-opt
+                   // apparmor=), an LSM layer over seccomp; kern fails the box CLOSED if it isn't loaded.
+  requireLimits,   // default false; true = FAIL-CLOSED (refuse to start unless caps enforced). NOT
+                   // enforceLimits (that picks the cap PATH); mutually exclusive with KERN_ALLOW_UNCAPPED env.
   depsReadonly,    // default false
   trackFiles,      // default true: diff the workspace each call for result.files (O(files)); false = [], O(1)
   onStdout,        // (chunk: Buffer) => void, live stdout streaming (result.stdout still captured)
@@ -218,8 +227,9 @@ clear error otherwise). The Python binding uses the stdlib `tarfile` and has no
 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 allowlist mode is on the roadmap. See the project's
-[SECURITY.md](https://github.com/getkern/kern/blob/main/SECURITY.md).
+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).
 
 ## License
 

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.14";
+const VERSION = "0.1.16";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -387,8 +387,11 @@ const REFUSED_MOUNT_SOURCES = new Set([
   "/run/docker.sock",
 ]);
 
-/** A PROGRAMMER/config error, THROWN: bad argument, illegal mount, or `kern` not installed. Runtime
- * sandbox events (timeout, blocked escape, OOM-kill) are NOT thrown - they are data in result.fault. */
+/** A PROGRAMMER/config error, THROWN: bad argument, illegal mount, `kern` not installed, or the box
+ * FAILED TO START (kern exits 125 - a mount refused at runtime, an unmappable `--user`, a seccomp or
+ * AppArmor setup error). A box that never started ran no user code, so it rejects rather than resolve a
+ * hollow result. Runtime sandbox events where the code DID run (timeout, blocked escape, OOM-kill) are
+ * NOT thrown - they are data on `result.fault`. */
 class SandboxError extends Error {
   constructor(message) {
     super(message);
@@ -578,6 +581,24 @@ function validateCap(name) {
   return name;
 }
 
+// An AppArmor profile name for `kern box --apparmor`. Same discipline as validateCap: handed to kern as
+// its own argv element, so it must not start with a dash (-> another flag) or carry a space. Letters,
+// digits and ._- cover ordinary profile names (docker-default, unconfined, kern-box); kern fails closed
+// if the profile is not loaded. Namespaced names with / or : are intentionally not accepted here (use
+// the CLI). Compared byte-for-byte with the Python binding's _APPARMOR_RE by a parity test - keep them
+// identical and free of chars that need escaping in a regex literal (e.g. /).
+const APPARMOR_RE = /^[A-Za-z0-9_.][A-Za-z0-9_.-]{0,127}$/;
+
+/** Validate an AppArmor profile name for `--apparmor` before it reaches the argv. */
+function validateApparmor(name) {
+  if (typeof name !== "string" || !APPARMOR_RE.test(name))
+    throw new SandboxError(
+      `invalid AppArmor profile ${JSON.stringify(name)}: expected a loaded profile name like ` +
+        "'docker-default' or 'unconfined' (letters, digits and ._-, not starting with a dash)",
+    );
+  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;
@@ -780,9 +801,22 @@ class Sandbox {
     this.onStdout = opts.onStdout ?? null;
     this.onStderr = opts.onStderr ?? null;
     this.enforceLimits = opts.enforceLimits ?? true;
+    // `--require-limits`: refuse to start unless the memory/pids caps are ACTUALLY enforced (read back
+    // from the cgroup), rather than running best-effort uncapped - the fail-closed OOM / fork-bomb
+    // backstop. Distinct from `enforceLimits` (systemd-scope vs best-effort PATH); this makes an
+    // unenforceable cap fatal.
+    this.requireLimits = opts.requireLimits ?? false;
+    // `--security-profile "untrusted"`: an opt-in hardening BUNDLE (seccomp allowlist + cap-drop ALL +
+    // read-only root) for code nobody has read. The root goes read-only but a bound `mounts` path stays
+    // writable, so it composes with this SDK. null (default) leaves kern's normal posture.
+    this.securityProfile = opts.securityProfile ?? null;
+    // `--apparmor "<profile>"`: enter a pre-loaded AppArmor profile on the box's exec (Docker's
+    // `--security-opt apparmor=`), a kernel-enforced LSM layer over namespaces + seccomp. The profile
+    // must be loaded on the host; kern fails the box CLOSED if it is not. null (default) applies none.
+    this.apparmor = opts.apparmor ?? null;
     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
+    // The default drops the lot: kern already drops 14 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
@@ -826,6 +860,7 @@ class Sandbox {
     this._capDropArgs = this.capDrop.flatMap((c) => ["--cap-drop", validateCap(c)]);
     this._profileArgs = (this.profiles || []).map(validateProfile);
     this._egressAllow = (this.egressAllow || []).map(validateDomain);
+    if (this.apparmor !== null) validateApparmor(this.apparmor);
     if (this._egressAllow.length && this.network)
       throw new SandboxError(
         "egressAllow and network:true are mutually exclusive: egressAllow gives a restricted domain " +
@@ -920,6 +955,9 @@ class Sandbox {
     if (this.memoryMb !== null) argv.push("--memory", `${this.memoryMb}m`);
     if (this.cpus !== null) argv.push("--cpus", String(this.cpus));
     if (this.pids !== null) argv.push("--pids-limit", String(this.pids));
+    if (this.requireLimits) argv.push("--require-limits");
+    if (this.securityProfile !== null) argv.push("--security-profile", this.securityProfile);
+    if (this.apparmor !== null) argv.push("--apparmor", this.apparmor);
     // Network mode: egressAllow (a domain allowlist via an isolated netns + kern's filtering proxy)
     // governs the untrusted runCode/run boxes; the setup box keeps the full network it needs to install
     // deps. egressAllow and network are mutually exclusive (checked at construction).
@@ -1022,6 +1060,13 @@ class Sandbox {
         const stderr = err.buffer().toString("utf8");
         const rc = toRc(code, signal);
         const fault = this._classify(rc, signal, stderr, timedOut, timeoutS);
+        // A box that FAILED TO START (kern exits 125) ran no user code, so REJECT rather than resolve a
+        // hollow ExecutionResult (empty stdout, exit 125). Mirrors the mount/config errors this SDK
+        // already throws up front; runtime events where the code DID run (timeout, OOM, escape) stay as
+        // data on `.fault`.
+        if (fault && fault.type === "startup_failed") {
+          return reject(new SandboxError(fault.message || "the box failed to start"));
+        }
         const files = before ? this._diff(before) : [];
         resolve(
           new ExecutionResult({
@@ -1094,6 +1139,11 @@ class Sandbox {
       return sandboxFault("killed", "the box was killed (SIGKILL) - likely out of memory (exit 137)");
     if (rc === EXIT_SIGTERM || signal === "SIGTERM")
       return sandboxFault("timeout", "the box exceeded its time limit (reaped by kern's timeout backstop)");
+    // DETERMINISTIC box-not-started: kern exits 125 (Docker's convention) when it could not BUILD the
+    // box (a mount refused at runtime, an unmappable --user, a seccomp/AppArmor/cgroup setup error), so
+    // the workload never ran. Decided by exit code, no stderr marker needed; the caller REJECTS on it.
+    if (rc === 125) return sandboxFault("startup_failed", stderr.trim().slice(0, 500) || "the box failed to start");
+    // LAST resort heuristic (also catches an OLDER kern that still exits 127 for a setup failure).
     if (rc !== 0 && looksLikeStartupFailure(stderr))
       return sandboxFault("startup_failed", stderr.trim().slice(0, 500));
     // Any other non-zero exit (incl. 139 SIGSEGV) is the USER's code failing - a normal Result.
@@ -1717,6 +1767,9 @@ class Kernel {
 
   _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
+    // does not return a hollow result. timeout/killed stay as data on the returned result.
+    if (type === "startup_failed") throw new SandboxError(message || "the box failed to start");
     return new ExecutionResult({
       stdout: "",
       stderr: "",

package/package.json

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