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:
- Time limit: Each file analysis gets a maximum of 10 seconds. The watchdog kills the worker thread if exceeded.
- Memory limit: Worker threads are capped at 128MB via V8's
--max-old-space-sizeflag. - Heartbeat: The sandbox must send a heartbeat every 2 seconds. A missed heartbeat triggers termination and restart.
- Crash recovery: If a sandboxed renderer crashes, the main process automatically spawns a replacement and resumes scanning.
What We Learned
Building this system taught us several hard-won lessons:
- 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.
- IPC is your attack surface โ the bridge between sandbox and main process is the critical security boundary. Make it as small as possible.
- Test with real malware โ we maintain a collection of 500+ known-malicious code samples to validate that our sandbox contains them effectively.
- 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.