kern-sandbox 0.2.7 → 0.2.9

package/README.md

@@ -129,7 +129,7 @@ A non-zero exit from *your code* is **not** a fault (`fault` stays `null`): it i
 | `oom` | the kernel's OOM killer took the box against its own memory cap. Read from a descriptor the code in the box cannot write, so it is an observation and not a guess from the exit code |
 | `killed` | SIGKILL with **no** OOM reported: an external kill (`kern stop`, a signal, the host out of memory), or a cap that did not bind here, which the message names |
 | `exec_failed` | the box started, the command did not exist inside it. `{language:"node"}` on an image with no `node` is the ordinary way there; the message names the binary AND the image |
-| `startup_failed` | your `timeoutS` fired while kern was still BUILDING the box, so the code never ran. A longer timeout does not help: a bind source on a dead NFS export does this |
+| `startup_failed` | the box never ran, and kern said why in `stderr`. Two shapes: your `timeoutS` fired while kern was still BUILDING the box (run it again: a fast second call was a cold image read), or kern refused to build it at all (an image that cannot be pulled, a mount it will not make) |
 
 ```js
 const r = await kern.runCode("while True: pass", { timeoutS: 5 });
@@ -216,6 +216,14 @@ cannot exfiltrate elsewhere. Mutually exclusive with `network: true`. The `setup
 network to install dependencies; the allowlist governs the run phase, which is the one executing code
 you did not read.
 
+It is a **route-level** boundary, not proxy variables a program can ignore. Measured inside the box: a
+raw socket to an IP returns `ENETUNREACH`, DNS does not resolve, and a request to a domain outside the
+list is refused by the tunnel with `403`, while the same socket under `network: true` connects. The other
+edge of that: a client which does not speak to an HTTP proxy has no path out at all, so a Postgres, MySQL
+or Redis connection under `egressAllow` cannot resolve its host. For a database, the setting today is
+`network: true`.
+
+
 `kernel()` returns a `Kernel`, and a refused mount throws `MountRefused` rather than the generic
 `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.

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.7";
+const VERSION = "0.2.9";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -446,6 +446,26 @@ const REFUSED_MOUNT_SOURCES = new Set([
   "/run/docker.sock",
 ]);
 
+/** Credential directories, refused as a COMPONENT anywhere in the source. The set above is absolute
+ * paths, so it refused `$HOME` and accepted `$HOME/.ssh`: MEASURED, a box mounted with `~/.ssh` listed
+ * `id_ed25519` and `authorized_keys`. Refusing the parent and allowing its most sensitive child is the
+ * wrong way round, and it is the scenario a prompt-injected agent is steered into ("read ~/.aws"). These
+ * match by NAME because they live under a per-user home. No escape hatch, same as `/etc`: a job that
+ * needs one credential should be given that one file in the workspace. */
+const REFUSED_MOUNT_COMPONENTS = new Set([
+  ".ssh",
+  ".aws",
+  ".gnupg",
+  ".kube",
+  ".docker",
+  ".azure",
+  ".password-store",
+  ".netrc",
+  ".git-credentials",
+  ".pypirc",
+  ".npmrc",
+]);
+
 /** 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
@@ -837,6 +857,13 @@ function validateMount(source, target) {
       `refusing to mount the sensitive host path ${JSON.stringify(real)} into a sandbox ` +
         "(this would defeat the isolation)",
     );
+  for (const part of real.split(path.sep))
+    if (REFUSED_MOUNT_COMPONENTS.has(part))
+      throw new MountRefused(
+        `refusing to mount ${JSON.stringify(real)}: ${JSON.stringify(part)} holds credentials, and code ` +
+          "in the box would read them. If the job needs one secret, write THAT FILE into the workspace " +
+          "(sbx.writeFile) or mount a directory that holds only it",
+      );
   return [real, target];
 }
 
@@ -1227,6 +1254,15 @@ class Sandbox {
   constructor(opts = {}) {
     this.image = opts.image ?? DEFAULT_IMAGE;
     this.setup = opts.setup ?? null;
+    // `setup` is ONE SHELL COMMAND, and a list of package names is the natural first guess. Without this
+    // it reaches `_runSetup` and dies as `TypeError: cmd.trim is not a function`, an internal error where
+    // a sentence belongs (the Python binding had the same edge, as an AttributeError).
+    if (this.setup !== null && typeof this.setup !== "string")
+      throw new SandboxError(
+        `setup must be a shell command STRING, not ${Array.isArray(this.setup) ? "an array" : typeof this.setup}: ` +
+          'write setup: "pip install pandas matplotlib" for packages, or any one line the setup box ' +
+          "should run (it runs once, with the network on)",
+      );
     this.workspace = opts.workspace ?? null;
     this.memoryMb = opts.memoryMb === undefined ? 512 : opts.memoryMb;
     this.cpus = opts.cpus ?? null;
@@ -1875,7 +1911,21 @@ class Sandbox {
   _wsPath(rel) {
     // Lexical containment: normalize `..`/`.`, require it stays under the workspace base. Symlinks in
     // the final component are neutralized by O_NOFOLLOW on the actual open below.
+    //
+    // AN ABSOLUTE PATH IS NOT A WORKSPACE PATH, and it takes its own check because `path.join` KEEPS the
+    // base for an absolute second argument while Python's `os.path.join` DROPS it. The same three lines
+    // therefore refused in the Python binding and silently resolved `<workspace>/etc/passwd` here:
+    // MEASURED, `readFile("/etc/passwd")` returned a decoy the box had planted at that relative path and
+    // `writeFile("/etc/passwd")` wrote into it. The boundary held either way; the ANSWER was a different
+    // file's contents than the one asked for, which is worse than an error. A caller who passes a host
+    // path is asking for a host file, so the honest answer is a refusal.
     const base = this._ws;
+    if (path.isAbsolute(rel))
+      throw new SandboxError(
+        `path escapes the workspace: ${JSON.stringify(rel)} is absolute, and these calls take a path ` +
+          "RELATIVE to the workspace. Nothing outside it is readable or writable through them, and an " +
+          "absolute path is NOT reinterpreted as a workspace one",
+      );
     const full = path.normalize(path.join(base, rel));
     if (full !== base && !full.startsWith(base + path.sep))
       throw new SandboxError(`path escapes the workspace: ${JSON.stringify(rel)}`);
@@ -1933,7 +1983,7 @@ class Sandbox {
         0o644,
       );
     } catch (e) {
-      throw new SandboxError(`cannot write ${JSON.stringify(rel)}: ${e.message}`);
+      throw pathRefusal("write", rel, e);
     }
     try {
       // The file the box left at this name has to be a REGULAR file before we write into it: writing
@@ -2006,7 +2056,7 @@ class Sandbox {
       // 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}`);
+      throw pathRefusal("read", rel, e);
     }
     try {
       this._assertFdInWorkspace(fd, rel); // race-free backstop: a swapped-in parent symlink is caught here
@@ -2399,6 +2449,28 @@ function kernelDriver(outCap, resCap, hello = false) {
  * sends a cell over a length-prefixed pipe to the resident driver and resolves to an ExecutionResult with
  * captured stdout/stderr, exit code and rich `results`. In-memory state persists across cells; the box
  * stays network-off and resource-capped. `close()` (or a per-cell timeout) tears the box down. */
+/** The message for a host-side open the workspace boundary refused.
+ *
+ * ELOOP here is not a filesystem oddity, it is the boundary working: the final component is opened
+ * O_NOFOLLOW, so a symlink the BOX planted at a path the host is about to touch fails instead of
+ * redirecting. Raw, it reads `ELOOP: too many symbolic links encountered`, which sends a reader looking
+ * for a broken link chain when what happened is an attempt to reach a host file. */
+function pathRefusal(verb, rel, e) {
+  if (e && e.code === "ELOOP")
+    return new SandboxError(
+      `refusing to ${verb} ${JSON.stringify(rel)}: a component of that path is a SYMLINK. Host-side ` +
+        "reads and writes never follow one (O_NOFOLLOW), because a link planted inside the workspace is " +
+        "how a box reaches a host file it was not given (the kernel reports this as ELOOP). Remove it, " +
+        "or name the file you meant",
+    );
+  if (e && e.code === "ENXIO")
+    return new SandboxError(
+      `refusing to ${verb} ${JSON.stringify(rel)}: it is a FIFO with no reader. Opening one for writing ` +
+        "would block until the box chose to read, so the open is non-blocking and fails instead",
+    );
+  return new SandboxError(`cannot ${verb} ${JSON.stringify(rel)}: ${e && e.message ? e.message : e}`);
+}
+
 class Kernel {
   constructor(sbx, timeoutS) {
     this._sbx = sbx;

package/package.json

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