@vellumai/assistant 0.3.0

package/src/__tests__/terminal-sandbox-docker.test.ts

@@ -0,0 +1,1064 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test';
+import { realpathSync, mkdirSync, existsSync } from 'node:fs';
+import * as realChildProcess from 'node:child_process';
+
+const execSyncMock = mock((_command: string, _opts?: unknown): unknown => undefined);
+const execFileSyncMock = mock(
+  (_file: string, _args?: readonly string[], _opts?: unknown): unknown => undefined,
+);
+
+mock.module('node:child_process', () => ({
+  ...realChildProcess,
+  execSync: execSyncMock,
+  execFileSync: execFileSyncMock,
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => ({
+    error: () => {},
+    warn: () => {},
+    info: () => {},
+    debug: () => {},
+  }),
+}));
+
+const { DockerBackend, _resetDockerChecks } = await import(
+  '../tools/terminal/backends/docker.js'
+);
+const { ToolError } = await import('../util/errors.js');
+const { DEFAULT_CONFIG } = await import('../config/defaults.js');
+
+const defaultImage = DEFAULT_CONFIG.sandbox.docker.image;
+
+// Use a real temp dir so realpathSync resolves correctly.
+const sandboxRoot = realpathSync('/tmp');
+
+beforeEach(() => {
+  _resetDockerChecks();
+  execSyncMock.mockReset();
+  execFileSyncMock.mockReset();
+  // Default: all preflight checks pass.
+  execSyncMock.mockImplementation(() => undefined);
+  execFileSyncMock.mockImplementation(() => undefined);
+});
+
+describe('DockerBackend — argument construction', () => {
+  test('returns docker as the command', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('echo hi', sandboxRoot);
+    expect(result.command).toBe('docker');
+  });
+
+  test('sandboxed flag is always true', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('pwd', sandboxRoot);
+    expect(result.sandboxed).toBe(true);
+  });
+
+  test('uses --rm for ephemeral containers', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--rm');
+  });
+
+  test('drops all capabilities', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--cap-drop=ALL');
+  });
+
+  test('sets no-new-privileges security option', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--security-opt=no-new-privileges');
+  });
+
+  test('disables network by default', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--network=none');
+  });
+
+  test('applies default resource limits', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--cpus=1');
+    expect(result.args).toContain('--memory=512m');
+    expect(result.args).toContain('--pids-limit=256');
+  });
+
+  test('passes host UID:GID via --user', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--user');
+    const userIdx = result.args.indexOf('--user');
+    expect(result.args[userIdx + 1]).toBe('1000:1000');
+  });
+
+  test('bind-mounts sandbox root to /workspace', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--mount');
+    const mountIdx = result.args.indexOf('--mount');
+    expect(result.args[mountIdx + 1]).toBe(
+      `type=bind,src=${sandboxRoot},dst=/workspace`,
+    );
+  });
+
+  test('uses default image from config', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain(defaultImage);
+  });
+
+  test('wraps command with bash -c by default', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const cmd = 'cat /etc/passwd | wc -l';
+    const result = backend.wrap(cmd, sandboxRoot);
+    const bashIdx = result.args.indexOf('bash');
+    expect(bashIdx).toBeGreaterThan(0);
+    expect(result.args.slice(bashIdx)).toEqual(['bash', '-c', cmd]);
+  });
+});
+
+describe('DockerBackend — read-only root and tmpfs', () => {
+  test('sets --read-only flag for container root filesystem', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--read-only');
+  });
+
+  test('mounts writable tmpfs at /tmp', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--tmpfs');
+    const tmpfsIdx = result.args.indexOf('--tmpfs');
+    expect(result.args[tmpfsIdx + 1]).toBe('/tmp:rw,nosuid,nodev,noexec');
+  });
+
+  test('--read-only appears before image name', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    const readOnlyIdx = result.args.indexOf('--read-only');
+    const imageIdx = result.args.indexOf(defaultImage);
+    expect(readOnlyIdx).toBeLessThan(imageIdx);
+  });
+
+  test('--tmpfs appears before image name', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    const tmpfsIdx = result.args.indexOf('--tmpfs');
+    const imageIdx = result.args.indexOf(defaultImage);
+    expect(tmpfsIdx).toBeLessThan(imageIdx);
+  });
+});
+
+describe('DockerBackend — path mapping', () => {
+  test('maps sandbox root to /workspace workdir', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('pwd', sandboxRoot);
+    const wdIdx = result.args.indexOf('--workdir');
+    expect(result.args[wdIdx + 1]).toBe('/workspace');
+  });
+
+  test('maps subdirectory to /workspace/<subdir>', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const subDir = `${sandboxRoot}/docker-sandbox-test-sub`;
+    if (!existsSync(subDir)) {
+      mkdirSync(subDir, { recursive: true });
+    }
+    const result = backend.wrap('pwd', subDir);
+    const wdIdx = result.args.indexOf('--workdir');
+    expect(result.args[wdIdx + 1]).toBe('/workspace/docker-sandbox-test-sub');
+  });
+});
+
+describe('DockerBackend — fail-closed on escape', () => {
+  test('throws ToolError when workdir is outside sandbox root', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    // /var is not under /tmp
+    const outsideDir = realpathSync('/var');
+    expect(() => backend.wrap('ls', outsideDir)).toThrow(ToolError);
+    expect(() => backend.wrap('ls', outsideDir)).toThrow(
+      'outside the sandbox root',
+    );
+  });
+
+  test('error message does not leak host working directory path', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const outsideDir = realpathSync('/var');
+    try {
+      backend.wrap('ls', outsideDir);
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ToolError);
+      // Should NOT contain the actual host paths
+      expect((err as Error).message).not.toContain(outsideDir);
+      expect((err as Error).message).not.toContain(sandboxRoot);
+    }
+  });
+
+  test('rejects path traversal via ../ in working directory', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const subDir = `${sandboxRoot}/docker-sandbox-test-sub`;
+    if (!existsSync(subDir)) {
+      mkdirSync(subDir, { recursive: true });
+    }
+    // ../../var should resolve outside sandbox root
+    const traversalDir = `${subDir}/../../var`;
+    expect(() => backend.wrap('ls', traversalDir)).toThrow(ToolError);
+    expect(() => backend.wrap('ls', traversalDir)).toThrow(
+      'outside the sandbox root',
+    );
+  });
+});
+
+describe('DockerBackend — unsafe path character rejection', () => {
+  test('rejects sandbox root containing a comma (mount argument injection)', () => {
+    const dirWithComma = `${sandboxRoot}/evil,dst=/etc,src=/`;
+    if (!existsSync(dirWithComma)) {
+      mkdirSync(dirWithComma, { recursive: true });
+    }
+    expect(() => new DockerBackend(dirWithComma, undefined, 1000, 1000)).toThrow(ToolError);
+    expect(() => new DockerBackend(dirWithComma, undefined, 1000, 1000)).toThrow(
+      'unsafe for Docker mount arguments',
+    );
+  });
+
+  test('rejects working directory containing a comma', () => {
+    const dirWithComma = `${sandboxRoot}/work,dir`;
+    if (!existsSync(dirWithComma)) {
+      mkdirSync(dirWithComma, { recursive: true });
+    }
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    expect(() => backend.wrap('ls', dirWithComma)).toThrow(ToolError);
+    expect(() => backend.wrap('ls', dirWithComma)).toThrow(
+      'unsafe for Docker mount arguments',
+    );
+  });
+});
+
+describe('DockerBackend — special characters in paths', () => {
+  test('handles spaces in sandbox root path', () => {
+    const dirWithSpaces = `${sandboxRoot}/docker sandbox test spaces`;
+    if (!existsSync(dirWithSpaces)) {
+      mkdirSync(dirWithSpaces, { recursive: true });
+    }
+    const backend = new DockerBackend(dirWithSpaces, undefined, 1000, 1000);
+    const result = backend.wrap('ls', dirWithSpaces);
+    // Args are separate argv segments, so spaces are safe
+    expect(result.args).toContain('--mount');
+    const mountIdx = result.args.indexOf('--mount');
+    expect(result.args[mountIdx + 1]).toContain(dirWithSpaces);
+    expect(result.sandboxed).toBe(true);
+  });
+
+  test('handles quotes in working directory name', () => {
+    const dirWithQuotes = `${sandboxRoot}/docker'sandbox"test`;
+    if (!existsSync(dirWithQuotes)) {
+      mkdirSync(dirWithQuotes, { recursive: true });
+    }
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', dirWithQuotes);
+    const wdIdx = result.args.indexOf('--workdir');
+    expect(result.args[wdIdx + 1]).toContain("docker'sandbox\"test");
+    expect(result.sandboxed).toBe(true);
+  });
+
+  test('handles dollar signs and backticks in paths', () => {
+    const dirWithShellChars = `${sandboxRoot}/docker$sandbox\`test`;
+    if (!existsSync(dirWithShellChars)) {
+      mkdirSync(dirWithShellChars, { recursive: true });
+    }
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', dirWithShellChars);
+    // Because we use argv segments (not shell interpolation), these are safe
+    expect(result.sandboxed).toBe(true);
+  });
+});
+
+describe('DockerBackend — argv segment safety', () => {
+  test('all args are discrete strings — no shell metacharacters are interpreted', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('echo $(whoami)', sandboxRoot);
+    // The command is passed as a single argv element after 'sh -c'
+    const cIdx = result.args.indexOf('-c');
+    expect(cIdx).toBeGreaterThan(0);
+    expect(result.args[cIdx + 1]).toBe('echo $(whoami)');
+    // The command itself is a single string, not split by the shell
+    expect(result.args.filter((a: string) => a === '$(whoami)').length).toBe(0);
+  });
+
+  test('every arg is a string type', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls -la', sandboxRoot);
+    for (const arg of result.args) {
+      expect(typeof arg).toBe('string');
+    }
+  });
+
+  test('no arg contains unintended shell operators', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    // None of the docker flag args (before the image) should contain ; | && etc.
+    const imageIdx = result.args.indexOf(defaultImage);
+    const flagArgs = result.args.slice(0, imageIdx);
+    for (const arg of flagArgs) {
+      expect(arg).not.toContain(';');
+      expect(arg).not.toContain('|');
+      expect(arg).not.toContain('&&');
+    }
+  });
+});
+
+describe('DockerBackend — UID:GID mapping', () => {
+  test('always includes --user flag with UID:GID', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 501, 20);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--user');
+    const userIdx = result.args.indexOf('--user');
+    expect(result.args[userIdx + 1]).toBe('501:20');
+  });
+
+  test('defaults to process UID:GID when not specified', () => {
+    const backend = new DockerBackend(sandboxRoot);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--user');
+    const userIdx = result.args.indexOf('--user');
+    const expected = `${process.getuid!()}:${process.getgid!()}`;
+    expect(result.args[userIdx + 1]).toBe(expected);
+  });
+
+  test('UID:GID format is always numeric colon-separated', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 0, 0);
+    const result = backend.wrap('ls', sandboxRoot);
+    const userIdx = result.args.indexOf('--user');
+    expect(result.args[userIdx + 1]).toMatch(/^\d+:\d+$/);
+  });
+});
+
+describe('DockerBackend — custom config', () => {
+  test('accepts custom image', () => {
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { image: 'alpine:3.19' },
+      1000,
+      1000,
+    );
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('alpine:3.19');
+    expect(result.args).not.toContain(defaultImage);
+  });
+
+  test('accepts custom resource limits', () => {
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { cpus: 4, memoryMb: 1024, pidsLimit: 512 },
+      1000,
+      1000,
+    );
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--cpus=4');
+    expect(result.args).toContain('--memory=1024m');
+    expect(result.args).toContain('--pids-limit=512');
+  });
+
+  test('accepts custom shell', () => {
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { shell: 'bash' },
+      1000,
+      1000,
+    );
+    const result = backend.wrap('echo hi', sandboxRoot);
+    const bashIdx = result.args.indexOf('bash');
+    expect(bashIdx).toBeGreaterThan(0);
+    expect(result.args.slice(bashIdx)).toEqual(['bash', '-c', 'echo hi']);
+  });
+
+  test('accepts custom network mode', () => {
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { network: 'bridge' },
+      1000,
+      1000,
+    );
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--network=bridge');
+  });
+});
+
+describe('DockerBackend — preflight: Docker CLI check', () => {
+  test('throws ToolError with install hint when docker CLI is missing', () => {
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('--version')
+        ) {
+          throw new Error('command not found: docker');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(ToolError);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(
+      'Docker CLI is not installed',
+    );
+  });
+
+  test('caches successful CLI check', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    backend.wrap('ls', sandboxRoot);
+    backend.wrap('ls', sandboxRoot);
+
+    // docker --version should only be called once (cached after success).
+    const versionCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('--version'),
+    );
+    expect(versionCalls.length).toBe(1);
+  });
+});
+
+describe('DockerBackend — preflight: Docker daemon check', () => {
+  test('throws ToolError with start hint when daemon is unreachable', () => {
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('info')
+        ) {
+          throw new Error('Cannot connect to the Docker daemon');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(ToolError);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(
+      'Docker daemon is not running',
+    );
+  });
+
+  test('caches successful daemon check', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    backend.wrap('ls', sandboxRoot);
+    backend.wrap('ls', sandboxRoot);
+
+    const infoCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('info'),
+    );
+    expect(infoCalls.length).toBe(1);
+  });
+});
+
+describe('DockerBackend — preflight: image availability check', () => {
+  test('auto-pulls image when not available locally', () => {
+    const pullImage = 'alpine:3.19';
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('inspect')
+        ) {
+          throw new Error('No such image');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, { image: pullImage }, 1000, 1000);
+    // Should succeed — auto-pull kicks in after inspect fails.
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.command).toBe('docker');
+
+    // Verify docker pull was called with the image.
+    const pullCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('pull'),
+    );
+    expect(pullCalls.length).toBe(1);
+    expect((pullCalls[0]![1] as string[])).toContain(pullImage);
+  });
+
+  test('throws ToolError when auto-pull also fails', () => {
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          (args.includes('inspect') || args.includes('pull'))
+        ) {
+          throw new Error('No such image / pull failed');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, { image: 'alpine:3.19' }, 1000, 1000);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(ToolError);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(
+      'Failed to pull Docker image',
+    );
+  });
+
+  test('includes image name in error message when pull fails', () => {
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          (args.includes('inspect') || args.includes('pull'))
+        ) {
+          throw new Error('No such image / pull failed');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { image: 'alpine:3.19' },
+      1000,
+      1000,
+    );
+    try {
+      backend.wrap('ls', sandboxRoot);
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ToolError);
+      expect((err as Error).message).toContain('alpine:3.19');
+    }
+  });
+
+  test('uses execFileSync (not execSync) for image check — no shell interpolation', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    backend.wrap('ls', sandboxRoot);
+
+    // execFileSync should have been called with 'docker' and argv array
+    const imageCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('inspect'),
+    );
+    expect(imageCalls.length).toBe(1);
+    // Verify the image name is a separate argv element, not interpolated into a string
+    const argv = imageCalls[0]![1] as string[];
+    expect(argv).toContain('image');
+    expect(argv).toContain('inspect');
+    expect(argv).toContain(defaultImage);
+  });
+
+  test('caches successful image check per image', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    backend.wrap('ls', sandboxRoot);
+    backend.wrap('ls', sandboxRoot);
+
+    const inspectCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('inspect'),
+    );
+    expect(inspectCalls.length).toBe(1);
+  });
+
+  test('caches successful auto-pull so subsequent calls skip pull', () => {
+    let inspectCallCount = 0;
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('inspect')
+        ) {
+          inspectCallCount++;
+          if (inspectCallCount <= 1) {
+            throw new Error('No such image');
+          }
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, { image: 'alpine:3.19' }, 1000, 1000);
+    backend.wrap('ls', sandboxRoot); // triggers inspect → pull → cache
+    backend.wrap('ls', sandboxRoot); // should use cache, no inspect or pull
+
+    const pullCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('pull'),
+    );
+    expect(pullCalls.length).toBe(1);
+  });
+});
+
+describe('DockerBackend — preflight: mount probe', () => {
+  test('throws ToolError with file sharing hint when mount fails', () => {
+    // Mount probe now uses execFileSync.
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('run')
+        ) {
+          throw new Error('mount failed');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(ToolError);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(
+      'File Sharing',
+    );
+  });
+
+  test('mount probe error does not leak host sandbox root path', () => {
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('run')
+        ) {
+          throw new Error('mount failed');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    try {
+      backend.wrap('ls', sandboxRoot);
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ToolError);
+      // Error message should be generic, not revealing the host path
+      expect((err as Error).message).not.toContain(sandboxRoot);
+    }
+  });
+
+  test('uses execFileSync (not execSync) for mount probe — no shell interpolation', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    backend.wrap('ls', sandboxRoot);
+
+    const mountCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('run') &&
+        (args[1] as string[]).includes('test'),
+    );
+    expect(mountCalls.length).toBe(1);
+    // Verify mount arg is passed as a single argv element
+    const argv = mountCalls[0]![1] as string[];
+    expect(argv).toContain('--rm');
+    expect(argv).toContain('--mount');
+  });
+
+  test('mount probe uses configured image, not hardcoded ubuntu:22.04', () => {
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { image: 'alpine:3.19' },
+      1000,
+      1000,
+    );
+    backend.wrap('ls', sandboxRoot);
+
+    const mountCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('run') &&
+        (args[1] as string[]).includes('test'),
+    );
+    expect(mountCalls.length).toBe(1);
+    const argv = mountCalls[0]![1] as string[];
+    expect(argv).toContain('alpine:3.19');
+    expect(argv).not.toContain('ubuntu:22.04');
+  });
+
+  test('caches successful mount probe per sandbox root', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    backend.wrap('ls', sandboxRoot);
+    backend.wrap('ls', sandboxRoot);
+
+    const mountCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('run') &&
+        (args[1] as string[]).includes('test'),
+    );
+    expect(mountCalls.length).toBe(1);
+  });
+});
+
+describe('DockerBackend — preflight: shell resolution', () => {
+  test('falls back to sh when configured shell is not available in image', () => {
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('run') &&
+          args.includes('bash')
+        ) {
+          throw new Error('executable file not found');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('echo hi', sandboxRoot);
+    // Should fall back to 'sh' instead of 'bash'
+    const imageIdx = result.args.indexOf(defaultImage);
+    expect(result.args[imageIdx + 1]).toBe('sh');
+    expect(result.args[imageIdx + 2]).toBe('-c');
+  });
+
+  test('throws when neither configured shell nor sh is available', () => {
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('run') &&
+          (args.includes('bash') || args.includes('sh'))
+        ) {
+          throw new Error('executable file not found');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(ToolError);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(
+      'is available in Docker image',
+    );
+  });
+
+  test('caches resolved shell per image', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    backend.wrap('ls', sandboxRoot);
+    backend.wrap('ls', sandboxRoot);
+
+    // Shell resolution docker run (with '-c' and 'true') should only happen once
+    const shellCalls = execFileSyncMock.mock.calls.filter(
+      (args) =>
+        args[0] === 'docker' &&
+        Array.isArray(args[1]) &&
+        (args[1] as string[]).includes('run') &&
+        (args[1] as string[]).includes('true'),
+    );
+    expect(shellCalls.length).toBe(1);
+  });
+});
+
+describe('DockerBackend — preflight check order', () => {
+  test('checks CLI before daemon', () => {
+    // All docker execFileSync calls fail, but we expect the CLI error first.
+    execFileSyncMock.mockImplementation(
+      (file: string) => {
+        if (file === 'docker') {
+          throw new Error('docker not available');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    try {
+      backend.wrap('ls', sandboxRoot);
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ToolError);
+      expect((err as Error).message).toContain('Docker CLI is not installed');
+    }
+  });
+
+  test('does not retry positive checks on subsequent calls', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    // First call succeeds and caches all checks.
+    backend.wrap('ls', sandboxRoot);
+
+    // Now make all docker commands fail.
+    execFileSyncMock.mockImplementation(
+      (file: string) => {
+        if (file === 'docker') {
+          throw new Error('docker unavailable');
+        }
+        return undefined;
+      },
+    );
+
+    // Should still succeed — all checks are cached.
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.command).toBe('docker');
+    expect(result.sandboxed).toBe(true);
+  });
+
+  test('re-checks negative results on subsequent calls', () => {
+    // Start with CLI failing.
+    execFileSyncMock.mockImplementation(
+      (file: string, args?: readonly string[]) => {
+        if (
+          file === 'docker' &&
+          Array.isArray(args) &&
+          args.includes('--version')
+        ) {
+          throw new Error('not found');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    expect(() => backend.wrap('ls', sandboxRoot)).toThrow(
+      'Docker CLI is not installed',
+    );
+
+    // Now make it succeed.
+    execFileSyncMock.mockImplementation(() => undefined);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.command).toBe('docker');
+  });
+});
+
+describe('DockerBackend — no unsandboxed fallback', () => {
+  test('wrap never returns sandboxed=false', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.sandboxed).toBe(true);
+  });
+
+  test('preflight failure always throws, never returns unsandboxed result', () => {
+    execFileSyncMock.mockImplementation(
+      (file: string) => {
+        if (file === 'docker') {
+          throw new Error('not available');
+        }
+        return undefined;
+      },
+    );
+
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    let threw = false;
+    try {
+      backend.wrap('ls', sandboxRoot);
+    } catch (err) {
+      threw = true;
+      expect(err).toBeInstanceOf(ToolError);
+    }
+    expect(threw).toBe(true);
+  });
+});
+
+describe('DockerBackend — complete hardening profile verification', () => {
+  test('all security flags are present in correct order before image', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    const imageIdx = result.args.indexOf(defaultImage);
+
+    // All of these must appear before the image name
+    const securityFlags = [
+      '--network=none',
+      '--cap-drop=ALL',
+      '--security-opt=no-new-privileges',
+      '--read-only',
+    ];
+    for (const flag of securityFlags) {
+      const idx = result.args.indexOf(flag);
+      expect(idx).toBeGreaterThan(-1);
+      expect(idx).toBeLessThan(imageIdx);
+    }
+  });
+
+  test('resource limits are all applied', () => {
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { cpus: 1, memoryMb: 256, pidsLimit: 64 },
+      1000,
+      1000,
+    );
+    const result = backend.wrap('ls', sandboxRoot);
+    expect(result.args).toContain('--cpus=1');
+    expect(result.args).toContain('--memory=256m');
+    expect(result.args).toContain('--pids-limit=64');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Baseline: default sandboxed bash uses network-disabled isolation
+// ---------------------------------------------------------------------------
+
+describe('DockerBackend — baseline: network isolation defaults', () => {
+  test('default config sets network to "none"', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('curl https://example.com', sandboxRoot);
+    expect(result.args).toContain('--network=none');
+    expect(result.sandboxed).toBe(true);
+  });
+
+  test('--network=none appears before the image argument', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('wget http://evil.com', sandboxRoot);
+    const networkIdx = result.args.indexOf('--network=none');
+    const imageIdx = result.args.indexOf(defaultImage);
+    expect(networkIdx).toBeGreaterThan(-1);
+    expect(networkIdx).toBeLessThan(imageIdx);
+  });
+
+  test('no other --network flag is present when using defaults', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    const networkArgs = result.args.filter((a: string) => a.startsWith('--network='));
+    expect(networkArgs).toEqual(['--network=none']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Per-invocation network override (proxied bash)
+// ---------------------------------------------------------------------------
+
+describe('DockerBackend — per-invocation network override', () => {
+  test('networkMode "proxied" overrides default to --network=bridge', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('curl http://127.0.0.1:8080', sandboxRoot, {
+      networkMode: 'proxied',
+    });
+    expect(result.args).toContain('--network=bridge');
+    expect(result.args).not.toContain('--network=none');
+  });
+
+  test('networkMode "off" preserves --network=none', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot, { networkMode: 'off' });
+    expect(result.args).toContain('--network=none');
+    expect(result.args).not.toContain('--network=bridge');
+  });
+
+  test('no networkMode option preserves config default (none)', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot, {});
+    expect(result.args).toContain('--network=none');
+  });
+
+  test('undefined options preserves config default (none)', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot, undefined);
+    expect(result.args).toContain('--network=none');
+  });
+
+  test('proxied mode overrides config-level network=none', () => {
+    // Explicitly set config network to 'none', then override per-invocation
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { network: 'none' },
+      1000,
+      1000,
+    );
+    const result = backend.wrap('wget http://proxy:3128', sandboxRoot, {
+      networkMode: 'proxied',
+    });
+    expect(result.args).toContain('--network=bridge');
+  });
+
+  test('proxied mode with config network=bridge still uses bridge', () => {
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { network: 'bridge' },
+      1000,
+      1000,
+    );
+    const result = backend.wrap('ls', sandboxRoot, { networkMode: 'proxied' });
+    expect(result.args).toContain('--network=bridge');
+  });
+
+  test('off mode with config network=bridge preserves config bridge', () => {
+    // When networkMode is 'off', we defer to the config-level network value,
+    // which happens to be 'bridge' here.
+    const backend = new DockerBackend(
+      sandboxRoot,
+      { network: 'bridge' },
+      1000,
+      1000,
+    );
+    const result = backend.wrap('ls', sandboxRoot, { networkMode: 'off' });
+    // 'off' means "no override" — config-level 'bridge' is used
+    expect(result.args).toContain('--network=bridge');
+  });
+
+  test('only one --network flag is present in proxied mode', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot, { networkMode: 'proxied' });
+    const networkArgs = result.args.filter((a: string) =>
+      a.startsWith('--network='),
+    );
+    expect(networkArgs).toEqual(['--network=bridge']);
+  });
+
+  test('all other security flags remain intact in proxied mode', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot, { networkMode: 'proxied' });
+    expect(result.args).toContain('--cap-drop=ALL');
+    expect(result.args).toContain('--security-opt=no-new-privileges');
+    expect(result.args).toContain('--read-only');
+    expect(result.args).toContain('--rm');
+    expect(result.sandboxed).toBe(true);
+  });
+
+  test('resource limits still apply in proxied mode', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot, { networkMode: 'proxied' });
+    expect(result.args).toContain('--cpus=1');
+    expect(result.args).toContain('--memory=512m');
+    expect(result.args).toContain('--pids-limit=256');
+  });
+
+  test('proxied mode adds --add-host=host.docker.internal:host-gateway', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('curl http://proxy:3128', sandboxRoot, {
+      networkMode: 'proxied',
+    });
+    expect(result.args).toContain('--add-host=host.docker.internal:host-gateway');
+  });
+
+  test('non-proxied mode does not add --add-host flag', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot);
+    const addHostArgs = result.args.filter((a: string) => a.startsWith('--add-host'));
+    expect(addHostArgs).toHaveLength(0);
+  });
+
+  test('--add-host appears before the image argument in proxied mode', () => {
+    const backend = new DockerBackend(sandboxRoot, undefined, 1000, 1000);
+    const result = backend.wrap('ls', sandboxRoot, { networkMode: 'proxied' });
+    const addHostIdx = result.args.indexOf('--add-host=host.docker.internal:host-gateway');
+    const imageIdx = result.args.indexOf(defaultImage);
+    expect(addHostIdx).toBeGreaterThan(-1);
+    expect(addHostIdx).toBeLessThan(imageIdx);
+  });
+});