HomeDocsBlogDownload

Building a Sandbox Engine: Isolating Untrusted Code in Electron

When your desktop security tool scans files that might contain malicious code, there's a fundamental tension: you need to analyze the code deeply enough to understand its behavior, but you absolutely cannot let it execute with full system access. This is the sandbox problem, and solving it inside Electron presented unique challenges we hadn't anticipated.

In this post, I'll walk through how we built ClaudeArmor's sandbox engine โ€” the component responsible for safely analyzing potentially dangerous code patterns without risking the developer's machine.

Architecture Overview

ClaudeArmor's sandbox uses a three-layer isolation model. Each layer adds defense-in-depth, so a bypass at one level doesn't compromise the system:

Layer 1: Electron Process Isolation

Electron's architecture gives us the first isolation boundary for free โ€” but only if you configure it correctly. Every BrowserWindow that handles untrusted content runs with strict sandboxing enabled:

// main.js โ€” Creating the sandboxed analysis window
const analysisWindow = new BrowserWindow({
  show: false, // Headless โ€” no UI needed
  webPreferences: {
    sandbox: true,
    contextIsolation: true,
    nodeIntegration: false,
    nodeIntegrationInWorker: false,
    webSecurity: true,
    allowRunningInsecureContent: false,
    preload: path.join(__dirname, 'preload-sandbox.js')
  }
});

With sandbox: true, the renderer process runs inside Chromium's OS-level sandbox. On Windows, this uses restricted tokens and job objects. On macOS, it uses the sandbox-exec profile. On Linux, it combines seccomp-bpf filters with namespace isolation.

The key insight: the sandboxed renderer never touches the file system directly. The main process reads files, strips them to plain text, and passes the content through IPC. The sandbox only ever sees string data โ€” never file handles or paths.

Layer 2: The IPC Bridge

IPC (Inter-Process Communication) is where many Electron apps introduce vulnerabilities. An overly permissive IPC bridge effectively negates the sandbox. We designed ours with an explicit allowlist:

// preload-sandbox.js โ€” Minimal, allowlisted API
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('sandboxAPI', {
  // Only these 4 methods are available to sandbox code
  analyzeCode: (content) =>
    ipcRenderer.invoke('sandbox:analyze', content),
  reportFinding: (finding) =>
    ipcRenderer.invoke('sandbox:report', finding),
  getThreatPolicies: () =>
    ipcRenderer.invoke('sandbox:get-rules'),
  heartbeat: () =>
    ipcRenderer.invoke('sandbox:heartbeat')
});

// No access to:
// - File system (fs)
// - Network requests (net, http)
// - Child processes (child_process)
// - Environment variables (process.env)
// - Native modules

On the main process side, every IPC message is validated with strict schema checking before processing. We use zod schemas to ensure the sandboxed process can't send malformed data that might exploit the main process:

// main.js โ€” IPC handler with schema validation
const FindingSchema = z.object({
  rule: z.string().max(128),
  severity: z.enum(['low', 'medium', 'high', 'critical']),
  line: z.number().int().positive(),
  snippet: z.string().max(500),
  // No file paths โ€” sandboxed code doesn't know them
});

ipcMain.handle('sandbox:report', async (event, data) => {
  const parsed = FindingSchema.safeParse(data);
  if (!parsed.success) {
    log.warn('Invalid finding from sandbox', parsed.error);
    return { ok: false };
  }
  return processFinding(parsed.data);
});

Layer 3: Isolated Analysis Workers

Within the sandboxed boundary, dedicated isolated workers execute behavioral and structural analysis. This provides an additional defense-in-depth boundary so untrusted payloads can never impact the host session.

// sandbox-renderer.js โ€” Worker-based analysis
const worker = new Worker('analysis-worker.js');

worker.onmessage = (e) => {
  if (e.data.type === 'finding') {
    window.sandboxAPI.reportFinding(e.data.finding);
  }
};

// Worker has no access to:
// - The DOM (it's a Worker, not a Window)
// - The preload bridge (contextIsolation)
// - The main process (no IPC access)
// - The file system (inherited from sandbox)

The Watchdog: Killing Runaway Analysis

Even in a sandbox, malicious code patterns can attempt resource exhaustion โ€” infinite loops, memory bombs, or CPU-intensive regex patterns (ReDoS). Our watchdog system monitors each sandboxed analysis session:

What We Learned

Building this system taught us several hard-won lessons:

  1. Never trust the renderer โ€” even when it's your own code running there. The whole point of defense-in-depth is that any single layer can be compromised.
  2. IPC is your attack surface โ€” the bridge between sandbox and main process is the critical security boundary. Make it as small as possible.
  3. Test with real malware โ€” we maintain a collection of 500+ known-malicious code samples to validate that our sandbox contains them effectively.
  4. Performance matters โ€” a sandbox that's too slow will be disabled by impatient developers. We spent weeks optimizing worker thread pooling to keep scan times under 5 seconds.

The full sandbox engine is open source as part of ClaudeArmor. You can explore the implementation in our GitHub repository.

Protect Your AI Workstations

Deploy ClaudeArmor's zero-trust micro-sandbox across your engineering team.

View Defense Passes โ†’
๐Ÿ› ๏ธ

James Park

Systems Engineer at ClaudeArmor. Focused on process isolation and low-level security primitives. Previously at Chromium and Cloudflare Workers.