init

Author: EliFuzz

.github/workflows/integration-tests.yml

@@ -0,0 +1,54 @@
+name: Tests
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  integration-tests:
+    name: Tests (${{ matrix.os }} / ${{ matrix.arch }})
+    runs-on: ${{ matrix.runner }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: x86-64
+            runner: ubuntu-24.04
+            os: linux
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+            os: linux
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.1
+
+      - name: Prepare environment
+        if: matrix.os == 'linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bubblewrap libseccomp-dev gcc socat ripgrep apparmor-profiles zsh qemu-user-static binfmt-support
+          sudo chmod u+s $(which bwrap)
+          bwrap --ro-bind / / --unshare-net true && echo "bwrap namespace creation works" || echo "bwrap namespace creation still fails"
+
+      - name: Install Node dependencies and build
+        run: bun install --frozen-lockfile && bun run build && bun run postbuild
+
+      - name: Lint code
+        run: bun run lint
+
+      - name: Run tests
+        run: bun run test

.gitignore

@@ -0,0 +1,15 @@
+# Node.js
+node_modules
+dist
+
+# Logs
+logs
+*.log
+
+# OS
+Thumbs.db
+Desktop.ini
+.DS_Store
+
+#IDE
+.vscode

README.md

@@ -1 +1,102 @@
-# sandbox
+# SandBox
+
+Lightweight, OS-native sandboxing solution on macOS (`sandbox-exec`) and Linux (`bubblewrap`).
+
+## Features
+
+- agentic code execution (AI agents): with minimal risk of data leaks or system compromise
+- secure-by-default dual isolation: Untrusted code runs with strong restrictions - filesystem isolation prevents secret exfiltration (e.g. SSH keys), while network isolation blocks unrestricted outbound access
+- minimal performance overhead: No containers / VMs required
+- blazingly fast startup times: milliseconds
+- cross-platform: macOS and Linux support
+- highly configurable: fine-grained control over network and filesystem access
+- easy to use: CLI and Node.js library
+
+## Usage
+
+### CLI
+
+```bash
+vsbx <command>                    # Run command sandboxed
+vsbx --debug <command>            # Debug logging
+vsbx --settings <file> <command>  # Custom config
+```
+
+### Node.js Library
+
+```javascript
+import { type SandboxRuntimeConfig } from "@/core/sandbox/sandbox-config";
+import { SandboxManager } from "@/core/manager/sandbox-manager";
+import { spawn } from "node:child_process";
+
+const config: SandboxRuntimeConfig = {
+  network: {
+    allowedDomains: ["example.com", "api.github.com"],
+    deniedDomains: [],
+  },
+  filesystem: {
+    denyRead: ["~/.ssh"],
+    allowWrite: [".", "/tmp"],
+    denyWrite: [".env"],
+  },
+};
+
+await SandboxManager.initialize(config);
+const sandboxedCommand = await SandboxManager.wrapWithSandbox(
+  "curl https://example.com",
+);
+const child = spawn(sandboxedCommand, { shell: true, stdio: "inherit" });
+
+child.on("exit", (code) => console.log(`Command exited with code ${code}`));
+await SandboxManager.reset();
+```
+
+## Configuration
+
+```json
+{
+  "network": {
+    "allowedDomains": [
+      "api.github.com",
+      "registry.npmjs.org",
+      "objects.githubusercontent.com"
+    ]
+  },
+  "filesystem": {
+    "denyRead": ["~/.ssh", "~/.aws", "~/.config/gh"],
+    "allowWrite": ["."]
+  }
+}
+```
+
+### Configuration Options
+
+```json
+{
+  "network": {
+    "allowedDomains":           string[],     // wildcards *. ok, empty = no network
+    "deniedDomains":            string[],     // checked first, blocks even if in allowed
+    "allowUnixSockets":         string[],     // macOS mostly - dangerous!
+    "allowLocalBinding":        boolean       // default false - very dangerous
+  },
+  "filesystem": {
+    "denyRead":                 string[],     // empty = read everywhere
+    "allowWrite":               string[],     // empty = write nowhere ← most important!
+    "denyWrite":                string[]      // exceptions inside allowWrite (stronger priority)
+  },
+  "ignoreViolations": {                       // rare - mostly for tooling workarounds
+    "<command-pattern>":        string[]
+  },
+  "enableWeakerNestedSandbox":  boolean,      // only for running inside Docker (much weaker!)
+  "mandatoryDenySearchDepth":   number        // Linux only - how deep to scan for dangerous files (default: 3)
+}
+```
+
+### Default Permissions
+
+| Resource             | Default State              | Restriction Style      | How to open access                    |
+| -------------------- | -------------------------- | ---------------------- | ------------------------------------- |
+| Network              | Completely blocked         | Allow-list only        | `allowedDomains: ["..."]`             |
+| Filesystem - Read    | Allowed everywhere         | Deny-list only         | `denyRead: ["~/.ssh"]`                |
+| Filesystem - Write   | Completely blocked         | Allow-list + deny-list | `allowWrite: ["."]` + `denyWrite: []` |
+| Unix sockets (Linux) | Creation blocked (seccomp) | Explicit allow         | `allowUnixSockets: [...]`             |