feat(core): implement SandboxManager interface and config schema

- Add `sandbox` block to `ConfigSchema` with `enabled`, `allowedPaths`, and `networkAccess` properties. - Define the `SandboxManager` interface and request/response types. - Implement `NoopSandboxManager` fallback that silently passes commands through but rigorously enforces environment variable sanitization via `sanitizeEnvironment`. - Update config and sandbox tests to use the new `SandboxConfig` schema. - Add `createMockSandboxConfig` utility to `test-utils` for cleaner test mocking across the monorepo.
2026-03-16 00:51:25 -07:00 · 2026-03-09 11:20:13 -07:00
parent 09e99824d4
commit 863a0aa01e
11 changed files with 494 additions and 65 deletions
--- a/packages/cli/src/config/sandboxConfig.ts
+++ b/packages/cli/src/config/sandboxConfig.ts
@@ -31,7 +31,9 @@ const VALID_SANDBOX_COMMANDS: ReadonlyArray<SandboxConfig['command']> = [
  'lxc',
 ];

-function isSandboxCommand(value: string): value is SandboxConfig['command'] {
+function isSandboxCommand(
+  value: string,
+): value is Exclude<SandboxConfig['command'], undefined> {
  return (VALID_SANDBOX_COMMANDS as readonly string[]).includes(value);
 }

@@ -124,5 +126,7 @@ export async function loadSandboxConfig(
    process.env['GEMINI_SANDBOX_IMAGE_DEFAULT'] ??
    packageJson?.config?.sandboxImageUri;

-  return command && image ? { command, image } : undefined;
+  return command && image
+    ? { enabled: true, allowedPaths: [], networkAccess: false, command, image }
+    : undefined;
 }
--- a/packages/cli/src/gemini.test.tsx
+++ b/packages/cli/src/gemini.test.tsx
@@ -23,6 +23,7 @@ import {
 } from './gemini.js';
 import { loadCliConfig, parseArguments } from './config/config.js';
 import { loadSandboxConfig } from './config/sandboxConfig.js';
+import { createMockSandboxConfig } from '@google/gemini-cli-test-utils';
 import { terminalCapabilityManager } from './ui/utils/terminalCapabilityManager.js';
 import { start_sandbox } from './utils/sandbox.js';
 import { validateNonInteractiveAuth } from './validateNonInterActiveAuth.js';
@@ -189,15 +190,26 @@ vi.mock('./ui/utils/terminalCapabilityManager.js', () => ({

 vi.mock('./config/config.js', () => ({
  loadCliConfig: vi.fn().mockImplementation(async () => createMockConfig()),
-  parseArguments: vi.fn().mockResolvedValue({}),
+  parseArguments: vi
+    .fn()
+    .mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
+    }),
  isDebugMode: vi.fn(() => false),
 }));

 vi.mock('read-package-up', () => ({
-  readPackageUp: vi.fn().mockResolvedValue({
-    packageJson: { name: 'test-pkg', version: 'test-version' },
-    path: '/fake/path/package.json',
-  }),
+  readPackageUp: vi
+    .fn()
+    .mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
+      packageJson: { name: 'test-pkg', version: 'test-version' },
+      path: '/fake/path/package.json',
+    }),
 }));

 vi.mock('update-notifier', () => ({
@@ -231,10 +243,15 @@ vi.mock('./utils/relaunch.js', () => ({
 }));

 vi.mock('./config/sandboxConfig.js', () => ({
-  loadSandboxConfig: vi.fn().mockResolvedValue({
-    command: 'docker',
-    image: 'test-image',
-  }),
+  loadSandboxConfig: vi
+    .fn()
+    .mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
+      command: 'docker',
+      image: 'test-image',
+    }),
 }));

 vi.mock('./deferred.js', () => ({
@@ -536,6 +553,9 @@ describe('gemini.tsx main function kitty protocol', () => {
    );

    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      promptInteractive: false,
    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any

@@ -599,6 +619,9 @@ describe('gemini.tsx main function kitty protocol', () => {
      });

    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      promptInteractive: false,
    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any

@@ -618,14 +641,17 @@ describe('gemini.tsx main function kitty protocol', () => {
    const mockConfig = createMockConfig({
      isInteractive: () => false,
      getQuestion: () => '',
-      getSandbox: () => ({ command: 'docker', image: 'test-image' }),
+      getSandbox: () =>
+        createMockSandboxConfig({ command: 'docker', image: 'test-image' }),
    });

    vi.mocked(loadCliConfig).mockResolvedValue(mockConfig);
-    vi.mocked(loadSandboxConfig).mockResolvedValue({
-      command: 'docker',
-      image: 'test-image',
-    });
+    vi.mocked(loadSandboxConfig).mockResolvedValue(
+      createMockSandboxConfig({
+        command: 'docker',
+        image: 'test-image',
+      }),
+    );

    process.env['GEMINI_API_KEY'] = 'test-key';
    try {
@@ -666,6 +692,9 @@ describe('gemini.tsx main function kitty protocol', () => {
    );

    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      promptInteractive: false,
    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any
    vi.mocked(loadCliConfig).mockResolvedValue(
@@ -721,6 +750,9 @@ describe('gemini.tsx main function kitty protocol', () => {
    );

    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      promptInteractive: false,
      resume: 'session-id',
    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any
@@ -777,6 +809,9 @@ describe('gemini.tsx main function kitty protocol', () => {
    );

    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      promptInteractive: false,
      resume: 'latest',
    } as unknown as CliArgs);
@@ -827,6 +862,9 @@ describe('gemini.tsx main function kitty protocol', () => {
    );

    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      promptInteractive: false,
    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any
    vi.mocked(loadCliConfig).mockResolvedValue(
@@ -877,6 +915,9 @@ describe('gemini.tsx main function kitty protocol', () => {
    );

    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      promptInteractive: false,
    } as any); // eslint-disable-line @typescript-eslint/no-explicit-any
    vi.mocked(loadCliConfig).mockResolvedValue(
@@ -951,6 +992,9 @@ describe('gemini.tsx main function exit codes', () => {
      }),
    );
    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      promptInteractive: true,
    } as unknown as CliArgs);
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -967,10 +1011,12 @@ describe('gemini.tsx main function exit codes', () => {

  it('should exit with 41 for auth failure during sandbox setup', async () => {
    vi.stubEnv('SANDBOX', '');
-    vi.mocked(loadSandboxConfig).mockResolvedValue({
-      command: 'docker',
-      image: 'test-image',
-    });
+    vi.mocked(loadSandboxConfig).mockResolvedValue(
+      createMockSandboxConfig({
+        command: 'docker',
+        image: 'test-image',
+      }),
+    );
    vi.mocked(loadCliConfig).mockResolvedValue(
      createMockConfig({
        refreshAuth: vi.fn().mockRejectedValue(new Error('Auth failed')),
@@ -1010,6 +1056,9 @@ describe('gemini.tsx main function exit codes', () => {
      }),
    );
    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
      resume: 'invalid-session',
    } as unknown as CliArgs);

@@ -1051,7 +1100,11 @@ describe('gemini.tsx main function exit codes', () => {
        merged: { security: { auth: {} }, ui: {} },
      }),
    );
-    vi.mocked(parseArguments).mockResolvedValue({} as unknown as CliArgs);
+    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
+    } as unknown as CliArgs);
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    (process.stdin as any).isTTY = true;

@@ -1086,7 +1139,11 @@ describe('gemini.tsx main function exit codes', () => {
        merged: { security: { auth: { selectedType: undefined } }, ui: {} },
      }),
    );
-    vi.mocked(parseArguments).mockResolvedValue({} as unknown as CliArgs);
+    vi.mocked(parseArguments).mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
+    } as unknown as CliArgs);

    runNonInteractiveSpy.mockImplementation(() => Promise.resolve());

@@ -1156,7 +1213,12 @@ describe('project hooks loading based on trust', () => {
    const configModule = await import('./config/config.js');
    loadCliConfig = vi.mocked(configModule.loadCliConfig);
    parseArguments = vi.mocked(configModule.parseArguments);
-    parseArguments.mockResolvedValue({ startupMessages: [] });
+    parseArguments.mockResolvedValue({
+      enabled: true,
+      allowedPaths: [],
+      networkAccess: false,
+      startupMessages: [],
+    });

    const settingsModule = await import('./config/settings.js');
    loadSettings = vi.mocked(settingsModule.loadSettings);
--- a/packages/cli/src/utils/sandbox.test.ts
+++ b/packages/cli/src/utils/sandbox.test.ts
@@ -10,6 +10,7 @@ import os from 'node:os';
 import fs from 'node:fs';
 import { start_sandbox } from './sandbox.js';
 import { FatalSandboxError, type SandboxConfig } from '@google/gemini-cli-core';
+import { createMockSandboxConfig } from '@google/gemini-cli-test-utils';
 import { EventEmitter } from 'node:events';

 const { mockedHomedir, mockedGetContainerPath } = vi.hoisted(() => ({
@@ -137,10 +138,10 @@ describe('sandbox', () => {
  describe('start_sandbox', () => {
    it('should handle macOS seatbelt (sandbox-exec)', async () => {
      vi.mocked(os.platform).mockReturnValue('darwin');
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'sandbox-exec',
        image: 'some-image',
-      };
+      });

      interface MockProcess extends EventEmitter {
        stdout: EventEmitter;
@@ -173,19 +174,19 @@ describe('sandbox', () => {
    it('should throw FatalSandboxError if seatbelt profile is missing', async () => {
      vi.mocked(os.platform).mockReturnValue('darwin');
      vi.mocked(fs.existsSync).mockReturnValue(false);
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'sandbox-exec',
        image: 'some-image',
-      };
+      });

      await expect(start_sandbox(config)).rejects.toThrow(FatalSandboxError);
    });

    it('should handle Docker execution', async () => {
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'docker',
        image: 'gemini-cli-sandbox',
-      };
+      });

      // Mock image check to return true (image exists)
      interface MockProcessWithStdout extends EventEmitter {
@@ -231,10 +232,10 @@ describe('sandbox', () => {
    });

    it('should pull image if missing', async () => {
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'docker',
        image: 'missing-image',
-      };
+      });

      // 1. Image check fails
      interface MockProcessWithStdout extends EventEmitter {
@@ -300,10 +301,10 @@ describe('sandbox', () => {
    });

    it('should throw if image pull fails', async () => {
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'docker',
        image: 'missing-image',
-      };
+      });

      // 1. Image check fails
      interface MockProcessWithStdout extends EventEmitter {
@@ -338,10 +339,10 @@ describe('sandbox', () => {
    });

    it('should mount volumes correctly', async () => {
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'docker',
        image: 'gemini-cli-sandbox',
-      };
+      });
      process.env['SANDBOX_MOUNTS'] = '/host/path:/container/path:ro';
      vi.mocked(fs.existsSync).mockReturnValue(true); // For mount path check

@@ -395,10 +396,10 @@ describe('sandbox', () => {
    });

    it('should pass through GOOGLE_GEMINI_BASE_URL and GOOGLE_VERTEX_BASE_URL', async () => {
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'docker',
        image: 'gemini-cli-sandbox',
-      };
+      });
      process.env['GOOGLE_GEMINI_BASE_URL'] = 'http://gemini.proxy';
      process.env['GOOGLE_VERTEX_BASE_URL'] = 'http://vertex.proxy';

@@ -442,10 +443,10 @@ describe('sandbox', () => {
    });

    it('should handle user creation on Linux if needed', async () => {
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'docker',
        image: 'gemini-cli-sandbox',
-      };
+      });
      process.env['SANDBOX_SET_UID_GID'] = 'true';
      vi.mocked(os.platform).mockReturnValue('linux');
      vi.mocked(execSync).mockImplementation((cmd) => {
@@ -508,10 +509,10 @@ describe('sandbox', () => {

      it('should run lxc exec with correct args for a running container', async () => {
        process.env['TEST_LXC_LIST_OUTPUT'] = LXC_RUNNING;
-        const config: SandboxConfig = {
+        const config: SandboxConfig = createMockSandboxConfig({
          command: 'lxc',
          image: 'gemini-sandbox',
-        };
+        });

        const mockSpawnProcess = new EventEmitter() as unknown as ReturnType<
          typeof spawn
@@ -542,10 +543,10 @@ describe('sandbox', () => {

      it('should throw FatalSandboxError if lxc list fails', async () => {
        process.env['TEST_LXC_LIST_OUTPUT'] = 'throw';
-        const config: SandboxConfig = {
+        const config: SandboxConfig = createMockSandboxConfig({
          command: 'lxc',
          image: 'gemini-sandbox',
-        };
+        });

        await expect(start_sandbox(config)).rejects.toThrow(
          /Failed to query LXC container/,
@@ -554,20 +555,20 @@ describe('sandbox', () => {

      it('should throw FatalSandboxError if container is not running', async () => {
        process.env['TEST_LXC_LIST_OUTPUT'] = LXC_STOPPED;
-        const config: SandboxConfig = {
+        const config: SandboxConfig = createMockSandboxConfig({
          command: 'lxc',
          image: 'gemini-sandbox',
-        };
+        });

        await expect(start_sandbox(config)).rejects.toThrow(/is not running/);
      });

      it('should throw FatalSandboxError if container is not found in list', async () => {
        process.env['TEST_LXC_LIST_OUTPUT'] = '[]';
-        const config: SandboxConfig = {
+        const config: SandboxConfig = createMockSandboxConfig({
          command: 'lxc',
          image: 'gemini-sandbox',
-        };
+        });

        await expect(start_sandbox(config)).rejects.toThrow(/not found/);
      });
@@ -577,10 +578,10 @@ describe('sandbox', () => {
  describe('gVisor (runsc)', () => {
    it('should use docker with --runtime=runsc on Linux', async () => {
      vi.mocked(os.platform).mockReturnValue('linux');
-      const config: SandboxConfig = {
+      const config: SandboxConfig = createMockSandboxConfig({
        command: 'runsc',
        image: 'gemini-cli-sandbox',
-      };
+      });

      // Mock image check
      interface MockProcessWithStdout extends EventEmitter {
--- a/packages/cli/src/utils/sandbox.ts
+++ b/packages/cli/src/utils/sandbox.ts
@@ -217,6 +217,7 @@ export async function start_sandbox(

    // runsc uses docker with --runtime=runsc
    const command = config.command === 'runsc' ? 'docker' : config.command;
+    if (!command) throw new FatalSandboxError('Sandbox command is required');

    debugLogger.log(`hopping into sandbox (command: ${command}) ...`);

@@ -230,6 +231,7 @@ export async function start_sandbox(
    const isCustomProjectSandbox = fs.existsSync(projectSandboxDockerfile);

    const image = config.image;
+    if (!image) throw new FatalSandboxError('Sandbox image is required');
    const workdir = path.resolve(process.cwd());
    const containerWorkdir = getContainerPath(workdir);