Project Sandbox Toolkit

Executive Overview

Modern software engineering relies on thousands of unvetted third-party packages, npm install scripts, and autonomous AI agents capable of executing shell commands. Running untrusted code directly on a workstation host is a severe security vulnerability.

The Project Sandbox Toolkit implements an uncompromising Structural Zero-Trust runtime architecture. It wraps builds, test suites, and third-party codebases in hardened Docker containers and disposable Windows Sandbox (.wsb) profiles, ensuring untrusted code runs in hermetically sealed isolation cells where host drives and credentials are inaccessible.

---

Technical Architecture

1. Hardened Docker Launcher (sandbox-docker.ps1)

The container launcher applies defense-in-depth flags before starting any untrusted execution:

• --cap-drop=ALL: Drops all Linux kernel capabilities to prevent container breakout exploits.
• --security-opt=no-new-privileges:true: Prevents child processes from gaining additional privileges via setuid binaries.
• --read-only: Enforces an immutable root filesystem; temporary writes are confined to ephemeral RAM disks (tmpfs).
• --network none: Evaluates tests and builds in an air-gapped environment. Network access must be explicitly unlocked with time-bounded leases only when downloading vetted dependencies.

# Launch an air-gapped hardened container for untrusted analysis
pwsh sandbox-docker.ps1 `
  -TargetDir "C:\Users\philg\Dev\untrusted-repo" `
  -Image "node:22-alpine" `
  -NetworkMode "none" `
  -MountMode "ro"

---

2. Disposable Windows Sandbox (sandbox-win.ps1)

For testing native Windows binaries, interactive GUI apps, or Windows-specific toolchains:

• Dynamic .wsb Generation: Generates an ephemeral Windows Sandbox XML configuration on the fly.
• Read-Only Host Mapping: Maps the host directory to the guest as strictly read-only (<ReadOnly>true</ReadOnly>), preventing guest alterations or ransomware from propagating back to host disk.
• Zero Host Contamination: The virtualized Windows instance is cleanly wiped from RAM upon closing the window.

---

3. Project-Level Descriptors (.sandbox.json)

Every project repository contains a declarative .sandbox.json file defining its required execution boundaries:

{
  "$schema": "https://philgear.dev/schemas/sandbox-v1.json",
  "project": "digital-duty-of-care-toolkit",
  "image": "mcr.microsoft.com/powershell:lts-alpine-3.20",
  "network": "none",
  "mounts": [
    {
      "host": ".",
      "container": "/workspace",
      "mode": "ro"
    }
  ],
  "tmpfs": ["/tmp:rw,noexec,nosuid,size=128m"],
  "security": {
    "capDrop": ["ALL"],
    "noNewPrivileges": true,
    "readOnlyRoot": true
  }
}

---

Verification & Reproducibility

By combining immutable container images, strict capability dropping, and air-gapped default networking, the Project Sandbox Toolkit guarantees hermetic reproducibility and provides complete defense against supply-chain poisoning, trojanized npm packages, and rogue agentic tool calls.