PR #25298: refactor(core): abstract OS sandbox managers and fix virtual command permissions

• Repository: google-gemini/gemini-cli
• Author: ehedlund
• State: closed | merged: False
• Link: https://github.com/google-gemini/gemini-cli/pull/25298

Description (problem / solution / changelog)

Summary

This PR introduces a significant architectural refactor to the Sandbox Management system across all supported platforms (macOS, Linux, Windows), vastly improving security, maintainability, and testing infrastructure. Most importantly, it closes a critical security vulnerability regarding the escalation of virtual command permissions.

Details

Architectural Changes:

• Abstract Base Class: Introduced AbstractOsSandboxManager to standardize the command preparation pipeline (sanitization, overrides, path resolution) using the Template Method pattern. OS-specific managers (MacOsSandboxManager, LinuxSandboxManager, WindowsSandboxManager) now extend this base class, reducing duplicated orchestration logic.
• Path Utilities: Core path utilities (sanitizePaths, getPathIdentity) were relocated from the bloated sandboxManager.ts to a dedicated utils/paths.ts and renamed to deduplicateAbsolutePaths and toPathKey. This enforces consistent path case-insensitivity rules across the agent lifecycle.

Behavioral & Security Fixes:

• Virtual Command Privilege Escalation (CRITICAL FIX): Previously, virtual __write commands were spoofed as cat on POSIX systems during early pipeline adjustments to bypass isToolApproved checks. This incorrectly granted the sandboxed tee process full workspaceWrite permissions. The AbstractOsSandboxManager now injects the targeted write path into the dynamic fileSystem permissions array before path resolution, keeping workspaceWrite = false and ensuring the sandbox restricts access solely to the target file.
• Governance File Verification: touch() operations for governance files (.git, .gitignore, .geminiignore) are now universally enforced by the abstract base class prior to sandbox execution. Previously, macOS skipped this step, leaving workspaces vulnerable to malicious .git initialization if absent.
• Windows Case-Insensitivity: isKnownSafeCommand now explicitly enforces case-insensitivity matching against the approvedTools list.

Testing Enhancements:

• Deleted the monolithic sandboxManager.test.ts.
• Introduced abstractOsSandboxManager.test.ts and structurally standardized LinuxSandboxManager.test.ts, MacOsSandboxManager.test.ts, and WindowsSandboxManager.test.ts with consistent describe groupings for delegated methods.
• Added more test cases to sandboxManager.integration.test.ts, including coverage for Plan Mode.

Related Issues

Fixes https://github.com/google-gemini/gemini-cli/issues/24932.

How to Validate

1. Run the workspace test suite: npm run test -w @google/gemini-cli-core
2. Execute the global preflight: npm run preflight
3. Verify the behavior of virtual __write commands inside a restricted sandbox environment (e.g. Plan Mode) to ensure only the specified target file is writable and the rest of the workspace remains read-only.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

Changed files

• packages/core/src/policy/sandboxPolicyManager.ts (modified, +4/-4)
• packages/core/src/sandbox/abstractOsSandboxManager.test.ts (added, +315/-0)
• packages/core/src/sandbox/abstractOsSandboxManager.ts (added, +326/-0)
• packages/core/src/sandbox/linux/LinuxSandboxManager.test.ts (modified, +59/-17)
• packages/core/src/sandbox/linux/LinuxSandboxManager.ts (modified, +43/-139)
• packages/core/src/sandbox/linux/bwrapArgsBuilder.test.ts (modified, +28/-2)
• packages/core/src/sandbox/linux/bwrapArgsBuilder.ts (modified, +12/-2)
• packages/core/src/sandbox/macos/MacOsSandboxManager.test.ts (modified, +62/-166)
• packages/core/src/sandbox/macos/MacOsSandboxManager.ts (modified, +35/-118)
• packages/core/src/sandbox/macos/seatbeltArgsBuilder.test.ts (modified, +1/-1)
• packages/core/src/sandbox/macos/seatbeltArgsBuilder.ts (modified, +1/-1)
• packages/core/src/sandbox/utils/sandboxReadWriteUtils.ts (modified, +18/-25)
• packages/core/src/sandbox/windows/WindowsSandboxManager.test.ts (modified, +463/-413)
• packages/core/src/sandbox/windows/WindowsSandboxManager.ts (modified, +103/-155)
• packages/core/src/services/sandboxManager.integration.test.ts (modified, +608/-372)
• packages/core/src/services/sandboxManager.test.ts (removed, +0/-465)
• packages/core/src/services/sandboxManager.ts (modified, +0/-236)
• packages/core/src/tools/shell.ts (modified, +4/-9)
• packages/core/src/utils/paths.test.ts (modified, +59/-0)
• packages/core/src/utils/paths.ts (modified, +39/-0)

PR #25307: test(core): improve sandbox integration test coverage and fix OS-specific failures

• Repository: google-gemini/gemini-cli
• Author: ehedlund
• State: closed | merged: True
• Link: https://github.com/google-gemini/gemini-cli/pull/25307

Description (problem / solution / changelog)

Summary

This PR significantly improves the integration test coverage for the sandbox environments across all major operating systems (Linux, macOS, Windows). In the process of expanding this test suite to rigorously verify sandbox boundaries and policies, several OS-specific failures were identified and resolved, including initialization inefficiencies and a Bubblewrap permission bug on Linux.

Details

Test Coverage Enhancements (Primary)

• Expanded sandboxManager.integration.test.ts to comprehensively exercise sandbox boundaries across Linux, macOS, and Windows.
• Added explicit verification for edge cases including recursive directory protection, symlink traversal restrictions, and governance file modification prevention.
• Added explicit verification for writing to authorized paths when the workspace is otherwise read-only (Plan Mode).
• Refactored Workspace Setup: Migrated the integration test suite from beforeAll to beforeEach for workspace initialization. Each test case now receives a fresh, isolated temporary directory to prevent state leakage (critical for Windows ACL checks). Added an afterEach cleanup block that specifically tracks and removes isolated test directories, drastically reducing the disk footprint during testing.
• Improved unit testing for bwrapArgsBuilder (Linux) and MacOsSandboxManager (macOS).

Sandbox Logic Fixes (Secondary)

• Linux (bwrap) Security:
  • Fixed a bug where write access to policy-authorized paths was incorrectly denied if the path did not yet exist and the command was not explicitly recognized as a write command.
  • The builder now grants read-write access (--bind-try) to any path in policyAllowed and its parent directory, unless the command is an explicit read-only virtual command (__read), in which case the parent directory is safely bound as read-only.
• Linux (bwrap) & Windows Optimization:
  • Refactored sandbox initialization (ensureGovernanceFilesExist) to ensure that governance files (e.g., .git, .gitignore) are secured and verified exactly once per session workspace, rather than redundantly on every single command execution. This reduces disk I/O and improves performance for long-running sessions.
• Windows:
  • Updated tests to pass pre-existing parent directories to policy.allowedPaths instead of non-existent target files, satisfying the Windows Sandbox requirement that granular access can only be granted to existing filesystem objects.
  • Refactored the native C# helper compilation (ensureHelperCompiled) to be a globally static initialization, ensuring it only compiles once per Node process.

Related Issues

Fixes https://github.com/google-gemini/gemini-cli/issues/24932.

How to Validate

Windows, Linux, macOS

Run integration tests:

npm run test -w @google/gemini-cli-core -- src/services/sandboxManager.integration.test.ts

Linux

Verify unit tests:

npm run test -w @google/gemini-cli-core -- src/sandbox/linux/bwrapArgsBuilder.test.ts

Changed files

• packages/core/src/sandbox/linux/LinuxSandboxManager.ts (modified, +22/-8)
• packages/core/src/sandbox/linux/bwrapArgsBuilder.test.ts (modified, +23/-3)
• packages/core/src/sandbox/linux/bwrapArgsBuilder.ts (modified, +8/-5)
• packages/core/src/sandbox/macos/MacOsSandboxManager.test.ts (modified, +1/-23)
• packages/core/src/sandbox/windows/WindowsSandboxManager.ts (modified, +46/-35)
• packages/core/src/services/sandboxManager.integration.test.ts (modified, +641/-377)