@agentforge-ai/sandbox 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,6 +1,75 @@
 export { DockerSandbox } from './docker-sandbox.js';
 export { ContainerPool } from './container-pool.js';
 export { SandboxManager, isDockerAvailable } from './sandbox-manager.js';
+import { SandboxProfile, SandboxProvider, NativeSandboxConfig, ExecOptions, ExecResult } from './types.js';
+export { DockerSandboxConfig, PoolConfig, PoolEntry, ResourceLimits, SandboxManagerConfig } from './types.js';
 export { BLOCKED_BIND_PREFIXES, DEFAULT_CAP_DROP, SecurityError, validateBind, validateBinds, validateCommand, validateImageName } from './security.js';
-export { DockerSandboxConfig, ExecOptions, ExecResult, PoolConfig, PoolEntry, ResourceLimits, SandboxManagerConfig, SandboxProvider } from './types.js';
 import 'dockerode';
+
+/**
+ * @module native-sandbox
+ *
+ * NativeSandbox — a lightweight process-level sandbox using platform-native
+ * isolation mechanisms as an alternative to Docker.
+ *
+ * Platform support:
+ * - macOS: `sandbox-exec` with Apple Seatbelt profiles (.sb)
+ * - Linux: `bwrap` (Bubblewrap) if available
+ * - Fallback: plain child_process with timeout + env filtering (no isolation)
+ *
+ * Security note: spawn() is used intentionally here because this module is the
+ * sandbox itself. Commands are passed through isolation wrappers (sandbox-exec /
+ * bwrap) that enforce the security policy. The env is sanitized before use.
+ */
+
+/**
+ * Conservative default profile for native sandboxes.
+ * Network access is disabled; only /tmp is accessible.
+ */
+declare const DEFAULT_SANDBOX_PROFILE: SandboxProfile;
+/**
+ * Detects which native isolation method is available on the current platform.
+ *
+ * @returns An object indicating availability and the method found.
+ */
+declare function isNativeSandboxAvailable(): Promise<{
+    available: boolean;
+    method: 'sandbox-exec' | 'bwrap' | 'none';
+}>;
+/**
+ * A sandbox provider that uses platform-native process isolation instead of Docker.
+ *
+ * Isolation strategy (in priority order):
+ * 1. macOS: `sandbox-exec` with Apple Seatbelt profiles
+ * 2. Linux: `bwrap` (Bubblewrap)
+ * 3. Fallback: plain child_process with timeout + env filtering (no isolation)
+ */
+declare class NativeSandbox implements SandboxProvider {
+    private readonly config;
+    private readonly profile;
+    private readonly id;
+    private running;
+    private isolationMethod;
+    constructor(config: NativeSandboxConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    isRunning(): Promise<boolean>;
+    getContainerId(): string | null;
+    /**
+     * Validates that a file path is within the allowed filesystem paths defined
+     * in the sandbox profile. Throws if the path is not allowed.
+     */
+    private _validatePath;
+    /**
+     * Builds a sanitized environment for child processes.
+     * Removes sensitive variables (secrets, tokens, credentials) and merges
+     * any additional environment variables provided by the caller.
+     */
+    private _buildSafeEnv;
+}
+
+export { DEFAULT_SANDBOX_PROFILE, ExecOptions, ExecResult, NativeSandbox, NativeSandboxConfig, SandboxProfile, SandboxProvider, isNativeSandboxAvailable };

package/dist/index.js

@@ -280,11 +280,11 @@ var DockerSandbox = class {
    *
    * @param path - Absolute path inside the container.
    */
-  async readFile(path) {
-    const result = await this.exec(`cat "${path.replace(/"/g, '\\"')}"`);
+  async readFile(path2) {
+    const result = await this.exec(`cat "${path2.replace(/"/g, '\\"')}"`);
     if (result.exitCode !== 0) {
       throw new Error(
-        `DockerSandbox.readFile: failed to read "${path}" (exit ${result.exitCode}): ${result.stderr}`
+        `DockerSandbox.readFile: failed to read "${path2}" (exit ${result.exitCode}): ${result.stderr}`
       );
     }
     return result.stdout;
@@ -296,13 +296,13 @@ var DockerSandbox = class {
    * @param path    - Absolute path inside the container.
    * @param content - UTF-8 string content.
    */
-  async writeFile(path, content) {
+  async writeFile(path2, content) {
     const b64 = Buffer.from(content, "utf8").toString("base64");
-    const cmd = `printf '%s' "${b64}" | base64 -d > "${path.replace(/"/g, '\\"')}"`;
+    const cmd = `printf '%s' "${b64}" | base64 -d > "${path2.replace(/"/g, '\\"')}"`;
     const result = await this.exec(cmd);
     if (result.exitCode !== 0) {
       throw new Error(
-        `DockerSandbox.writeFile: failed to write "${path}" (exit ${result.exitCode}): ${result.stderr}`
+        `DockerSandbox.writeFile: failed to write "${path2}" (exit ${result.exitCode}): ${result.stderr}`
       );
     }
   }
@@ -536,7 +536,254 @@ var ContainerPool = class {
 
 // src/sandbox-manager.ts
 import Dockerode2 from "dockerode";
+import { randomUUID as randomUUID4 } from "crypto";
+
+// src/native-sandbox.ts
+import { execFile, spawn } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
 import { randomUUID as randomUUID3 } from "crypto";
+var execFileAsync = promisify(execFile);
+var DEFAULT_SANDBOX_PROFILE = {
+  allowNetwork: false,
+  allowFS: ["/tmp"],
+  timeout: 30,
+  memory: 512
+};
+async function isNativeSandboxAvailable() {
+  if (process.platform === "darwin") {
+    try {
+      await execFileAsync("which", ["sandbox-exec"], { timeout: 5e3 });
+      return { available: true, method: "sandbox-exec" };
+    } catch {
+    }
+  }
+  if (process.platform === "linux") {
+    try {
+      await execFileAsync("which", ["bwrap"], { timeout: 5e3 });
+      return { available: true, method: "bwrap" };
+    } catch {
+    }
+  }
+  return { available: false, method: "none" };
+}
+function generateSeatbeltProfile(profile) {
+  const lines = [
+    "(version 1)",
+    "(deny default)",
+    // Always allow process execution so /bin/sh -c works
+    "(allow process-exec)",
+    "(allow process-fork)",
+    // Allow reading system libraries and frameworks
+    '(allow file-read* (subpath "/usr/lib"))',
+    '(allow file-read* (subpath "/usr/libexec"))',
+    '(allow file-read* (subpath "/System/Library"))',
+    '(allow file-read* (subpath "/Library/Preferences"))',
+    '(allow file-read* (literal "/dev/null"))',
+    '(allow file-read* (literal "/dev/urandom"))',
+    '(allow file-read* (literal "/dev/random"))',
+    // Allow sysctl reads (needed by many programs)
+    "(allow sysctl-read)",
+    // Allow signal sending to self
+    "(allow signal (target self))",
+    // Allow mach operations needed for basic process functionality
+    "(allow mach-lookup)"
+  ];
+  for (const allowedPath of profile.allowFS) {
+    lines.push(`(allow file-read* (subpath "${allowedPath}"))`);
+    lines.push(`(allow file-write* (subpath "${allowedPath}"))`);
+  }
+  if (profile.allowNetwork) {
+    lines.push("(allow network*)");
+  }
+  return lines.join("\n");
+}
+function buildBwrapArgs(profile, command, cwd) {
+  const args = [
+    "--ro-bind",
+    "/",
+    "/",
+    "--dev",
+    "/dev",
+    "--proc",
+    "/proc",
+    "--tmpfs",
+    "/tmp"
+  ];
+  for (const allowedPath of profile.allowFS) {
+    if (allowedPath === "/tmp") continue;
+    args.push("--bind", allowedPath, allowedPath);
+  }
+  if (!profile.allowNetwork) {
+    args.push("--unshare-net");
+  }
+  args.push("--unshare-user", "--unshare-pid", "--unshare-ipc", "--unshare-uts");
+  if (cwd) {
+    args.push("--chdir", cwd);
+  }
+  args.push("--", "/bin/sh", "-c", command);
+  return args;
+}
+var NativeSandbox = class {
+  config;
+  profile;
+  id;
+  running = false;
+  isolationMethod = "none";
+  constructor(config) {
+    this.config = config;
+    this.profile = config.profile ?? { ...DEFAULT_SANDBOX_PROFILE };
+    this.id = `native-${randomUUID3()}`;
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  async start() {
+    const { method } = await isNativeSandboxAvailable();
+    this.isolationMethod = method;
+    if (method === "none") {
+      console.warn(
+        "[NativeSandbox] No native isolation available (sandbox-exec / bwrap not found). Running with limited isolation (timeout + env filtering only). For stronger isolation, install Docker or use bwrap on Linux."
+      );
+    } else {
+      console.info(`[NativeSandbox] Using isolation method: ${method}`);
+    }
+    if (this.config.workingDirectory) {
+      await fs.mkdir(this.config.workingDirectory, { recursive: true });
+    }
+    this.running = true;
+  }
+  async stop() {
+    this.running = false;
+  }
+  async destroy() {
+    this.running = false;
+  }
+  // ---------------------------------------------------------------------------
+  // Execution
+  // ---------------------------------------------------------------------------
+  async exec(command, options) {
+    const timeoutMs = options?.timeout ?? this.profile.timeout * 1e3;
+    const cwd = options?.cwd ?? this.config.workingDirectory ?? os.tmpdir();
+    const extraEnv = options?.env ?? {};
+    return new Promise((resolve, reject) => {
+      let stdout = "";
+      let stderr = "";
+      const env = this._buildSafeEnv(extraEnv);
+      let proc;
+      if (this.isolationMethod === "sandbox-exec") {
+        const sbProfile = generateSeatbeltProfile(this.profile);
+        proc = spawn("sandbox-exec", ["-p", sbProfile, "/bin/sh", "-c", command], {
+          cwd,
+          env,
+          timeout: timeoutMs
+        });
+      } else if (this.isolationMethod === "bwrap") {
+        const bwrapArgs = buildBwrapArgs(this.profile, command, cwd);
+        proc = spawn("bwrap", bwrapArgs, {
+          env,
+          timeout: timeoutMs
+        });
+      } else {
+        proc = spawn("/bin/sh", ["-c", command], {
+          cwd,
+          env,
+          timeout: timeoutMs
+        });
+      }
+      proc.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+      proc.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+      proc.on("error", (err) => {
+        reject(new Error(`[NativeSandbox] exec error: ${err.message}`));
+      });
+      proc.on("close", (code) => {
+        resolve({
+          stdout,
+          stderr,
+          exitCode: code ?? 1
+        });
+      });
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // File I/O (with path validation)
+  // ---------------------------------------------------------------------------
+  async readFile(filePath) {
+    this._validatePath(filePath);
+    return fs.readFile(filePath, "utf-8");
+  }
+  async writeFile(filePath, content) {
+    this._validatePath(filePath);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, "utf-8");
+  }
+  // ---------------------------------------------------------------------------
+  // Health
+  // ---------------------------------------------------------------------------
+  async isRunning() {
+    return this.running;
+  }
+  getContainerId() {
+    return this.running ? this.id : null;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Validates that a file path is within the allowed filesystem paths defined
+   * in the sandbox profile. Throws if the path is not allowed.
+   */
+  _validatePath(filePath) {
+    const resolved = path.resolve(filePath);
+    const allowed = this.profile.allowFS.some((allowedPath) => {
+      const resolvedAllowed = path.resolve(allowedPath);
+      return resolved.startsWith(resolvedAllowed + path.sep) || resolved === resolvedAllowed;
+    });
+    if (!allowed) {
+      throw new Error(
+        `[NativeSandbox] Access denied: path "${filePath}" is not within allowed filesystem paths: ` + JSON.stringify(this.profile.allowFS)
+      );
+    }
+  }
+  /**
+   * Builds a sanitized environment for child processes.
+   * Removes sensitive variables (secrets, tokens, credentials) and merges
+   * any additional environment variables provided by the caller.
+   */
+  _buildSafeEnv(extra) {
+    const SENSITIVE_PATTERNS = [
+      /SECRET/i,
+      /TOKEN/i,
+      /PASSWORD/i,
+      /PASSWD/i,
+      /API_KEY/i,
+      /PRIVATE_KEY/i,
+      /CREDENTIAL/i,
+      /AUTH/i,
+      /AWS_/i,
+      /GCP_/i,
+      /AZURE_/i
+    ];
+    const safeEnv = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value === void 0) continue;
+      const isSensitive = SENSITIVE_PATTERNS.some((pattern) => pattern.test(key));
+      if (!isSensitive) {
+        safeEnv[key] = value;
+      }
+    }
+    Object.assign(safeEnv, extra);
+    return safeEnv;
+  }
+};
+
+// src/sandbox-manager.ts
 var E2BProviderStub = class {
   async start() {
     throw new Error(
@@ -609,6 +856,16 @@ var SandboxManager = class {
         );
       }
     }
+    if (this.config.provider === "native") {
+      const { available, method } = await isNativeSandboxAvailable();
+      if (!available) {
+        console.warn(
+          "[SandboxManager] No native isolation method found (sandbox-exec / bwrap). Sandboxes will run with limited isolation (timeout + env filtering only)."
+        );
+      } else {
+        console.info(`[SandboxManager] Native isolation available: ${method}`);
+      }
+    }
     this._registerShutdownHandlers();
   }
   /**
@@ -626,6 +883,18 @@ var SandboxManager = class {
       this.active.set(id2, stub);
       return stub;
     }
+    if (this.config.provider === "native") {
+      const nativeConfig = {
+        scope: overrides.scope,
+        profile: this.config.nativeConfig?.profile,
+        workingDirectory: this.config.nativeConfig?.workingDirectory
+      };
+      const sandbox2 = new NativeSandbox(nativeConfig);
+      await sandbox2.start();
+      const id2 = this._generateId(overrides.scope);
+      this.active.set(id2, sandbox2);
+      return sandbox2;
+    }
     const mergedConfig = {
       image: "node:22-slim",
       ...this.config.dockerConfig,
@@ -672,7 +941,7 @@ var SandboxManager = class {
   // Private helpers
   // ---------------------------------------------------------------------------
   _generateId(scope) {
-    return `agentforge-${scope}-${randomUUID3().slice(0, 8)}`;
+    return `agentforge-${scope}-${randomUUID4().slice(0, 8)}`;
   }
   _registerShutdownHandlers() {
     if (this.shutdownRegistered) return;
@@ -689,10 +958,13 @@ export {
   BLOCKED_BIND_PREFIXES,
   ContainerPool,
   DEFAULT_CAP_DROP,
+  DEFAULT_SANDBOX_PROFILE,
   DockerSandbox,
+  NativeSandbox,
   SandboxManager,
   SecurityError,
   isDockerAvailable,
+  isNativeSandboxAvailable,
   validateBind,
   validateBinds,
   validateCommand,