fix(security): enforce strict policy directory permissions (#17353)

Co-authored-by: Yuna Seol <yunaseol@google.com>

Author: yunaseoul

docs/core/policy-engine.md

@@ -146,6 +146,38 @@ A rule matches a tool call if all of its conditions are met:
 Policies are defined in `.toml` files. The CLI loads these files from Default,
 User, and (if configured) Admin directories.
 
+### Policy locations
+
+| Tier      | Type   | Location                    |
+| :-------- | :----- | :-------------------------- |
+| **User**  | Custom | `~/.gemini/policies/*.toml` |
+| **Admin** | System | _See below (OS specific)_   |
+
+#### System-wide policies (Admin)
+
+Administrators can enforce system-wide policies (Tier 3) that override all user
+and default settings. These policies must be placed in specific, secure
+directories:
+
+| OS          | Policy Directory Path                             |
+| :---------- | :------------------------------------------------ |
+| **Linux**   | `/etc/gemini-cli/policies`                        |
+| **macOS**   | `/Library/Application Support/GeminiCli/policies` |
+| **Windows** | `C:\ProgramData\gemini-cli\policies`              |
+
+**Security Requirements:**
+
+To prevent privilege escalation, the CLI enforces strict security checks on
+admin directories. If checks fail, system policies are **ignored**.
+
+- **Linux / macOS:** Must be owned by `root` (UID 0) and NOT writable by group
+  or others (e.g., `chmod 755`).
+- **Windows:** Must be in `C:\ProgramData`. Standard users (`Users`, `Everyone`)
+  must NOT have `Write`, `Modify`, or `Full Control` permissions. _Tip: If you
+  see a security warning, use the folder properties to remove write permissions
+  for non-admin groups. You may need to "Disable inheritance" in Advanced
+  Security Settings._
+
 ### TOML rule schema
 
 Here is a breakdown of the fields available in a TOML policy rule:

packages/core/src/config/storage.test.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
@@ -85,3 +85,55 @@ describe('Storage – additional helpers', () => {
     expect(storage.getProjectTempPlansDir()).toBe(expected);
   });
 });
+
+describe('Storage - System Paths', () => {
+  const originalEnv = process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'];
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'] = originalEnv;
+    } else {
+      delete process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'];
+    }
+  });
+
+  it('getSystemSettingsPath returns correct path based on platform (default)', () => {
+    delete process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'];
+
+    const platform = os.platform();
+    const result = Storage.getSystemSettingsPath();
+
+    if (platform === 'darwin') {
+      expect(result).toBe(
+        '/Library/Application Support/GeminiCli/settings.json',
+      );
+    } else if (platform === 'win32') {
+      expect(result).toBe('C:\\ProgramData\\gemini-cli\\settings.json');
+    } else {
+      expect(result).toBe('/etc/gemini-cli/settings.json');
+    }
+  });
+
+  it('getSystemSettingsPath follows GEMINI_CLI_SYSTEM_SETTINGS_PATH if set', () => {
+    const customPath = '/custom/path/settings.json';
+    process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'] = customPath;
+    expect(Storage.getSystemSettingsPath()).toBe(customPath);
+  });
+
+  it('getSystemPoliciesDir returns correct path based on platform and ignores env var', () => {
+    process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'] =
+      '/custom/path/settings.json';
+    const platform = os.platform();
+    const result = Storage.getSystemPoliciesDir();
+
+    expect(result).not.toContain('/custom/path');
+
+    if (platform === 'darwin') {
+      expect(result).toBe('/Library/Application Support/GeminiCli/policies');
+    } else if (platform === 'win32') {
+      expect(result).toBe('C:\\ProgramData\\gemini-cli\\policies');
+    } else {
+      expect(result).toBe('/etc/gemini-cli/policies');
+    }
+  });
+});

packages/core/src/config/storage.ts

@@ -74,21 +74,25 @@ export class Storage {
     );
   }
 
-  static getSystemSettingsPath(): string {
-    if (process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH']) {
-      return process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'];
-    }
+  private static getSystemConfigDir(): string {
     if (os.platform() === 'darwin') {
-      return '/Library/Application Support/GeminiCli/settings.json';
+      return '/Library/Application Support/GeminiCli';
     } else if (os.platform() === 'win32') {
-      return 'C:\\ProgramData\\gemini-cli\\settings.json';
+      return 'C:\\ProgramData\\gemini-cli';
     } else {
-      return '/etc/gemini-cli/settings.json';
+      return '/etc/gemini-cli';
+    }
+  }
+
+  static getSystemSettingsPath(): string {
+    if (process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH']) {
+      return process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'];
     }
+    return path.join(Storage.getSystemConfigDir(), 'settings.json');
   }
 
   static getSystemPoliciesDir(): string {
-    return path.join(path.dirname(Storage.getSystemSettingsPath()), 'policies');
+    return path.join(Storage.getSystemConfigDir(), 'policies');
   }
 
   static getGlobalTempDir(): string {

packages/core/src/policy/config.test.ts

@@ -10,6 +10,11 @@ import nodePath from 'node:path';
 
 import type { PolicySettings } from './types.js';
 import { ApprovalMode, PolicyDecision, InProcessCheckerType } from './types.js';
+import { isDirectorySecure } from '../utils/security.js';
+
+vi.mock('../utils/security.js', () => ({
+  isDirectorySecure: vi.fn().mockResolvedValue({ secure: true }),
+}));
 
 afterEach(() => {
   vi.clearAllMocks();
@@ -28,7 +33,53 @@ describe('createPolicyEngineConfig', () => {
     vi.spyOn(Storage, 'getSystemPoliciesDir').mockReturnValue(
       '/non/existent/system/policies',
     );
+    // Reset security check to default secure
+    vi.mocked(isDirectorySecure).mockResolvedValue({ secure: true });
+  });
+
+  it('should filter out insecure system policy directories', async () => {
+    const { Storage } = await import('../config/storage.js');
+    const systemPolicyDir = '/insecure/system/policies';
+    vi.spyOn(Storage, 'getSystemPoliciesDir').mockReturnValue(systemPolicyDir);
+
+    vi.mocked(isDirectorySecure).mockImplementation(async (path: string) => {
+      if (nodePath.resolve(path) === nodePath.resolve(systemPolicyDir)) {
+        return { secure: false, reason: 'Insecure directory' };
+      }
+      return { secure: true };
+    });
+
+    // We need to spy on loadPoliciesFromToml to verify which directories were passed
+    // But it is not exported from config.js, it is imported.
+    // We can spy on the module it comes from.
+    const tomlLoader = await import('./toml-loader.js');
+    const loadPoliciesSpy = vi.spyOn(tomlLoader, 'loadPoliciesFromToml');
+    loadPoliciesSpy.mockResolvedValue({
+      rules: [],
+      checkers: [],
+      errors: [],
+    });
+
+    const { createPolicyEngineConfig } = await import('./config.js');
+    const settings: PolicySettings = {};
+
+    await createPolicyEngineConfig(
+      settings,
+      ApprovalMode.DEFAULT,
+      '/tmp/mock/default/policies',
+    );
+
+    // Verify loadPoliciesFromToml was called
+    expect(loadPoliciesSpy).toHaveBeenCalled();
+    const calledDirs = loadPoliciesSpy.mock.calls[0][0];
+
+    // The system directory should NOT be in the list
+    expect(calledDirs).not.toContain(systemPolicyDir);
+    // But other directories (user, default) should be there
+    expect(calledDirs).toContain('/non/existent/user/policies');
+    expect(calledDirs).toContain('/tmp/mock/default/policies');
   });
+
   it('should return ASK_USER for write tools and ALLOW for read-only tools by default', async () => {
     const actualFs =
       await vi.importActual<typeof import('node:fs/promises')>(

packages/core/src/policy/config.ts

@@ -29,6 +29,8 @@ import { debugLogger } from '../utils/debugLogger.js';
 import { SHELL_TOOL_NAMES } from '../utils/shell-utils.js';
 import { SHELL_TOOL_NAME } from '../tools/tool-names.js';
 
+import { isDirectorySecure } from '../utils/security.js';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export const DEFAULT_CORE_POLICIES_DIR = path.join(__dirname, 'policies');
@@ -112,19 +114,47 @@ export function formatPolicyError(error: PolicyFileError): string {
   return message;
 }
 
+/**
+ * Filters out insecure policy directories (specifically the system policy directory).
+ * Emits warnings if insecure directories are found.
+ */
+async function filterSecurePolicyDirectories(
+  dirs: string[],
+): Promise<string[]> {
+  const systemPoliciesDir = path.resolve(Storage.getSystemPoliciesDir());
+
+  const results = await Promise.all(
+    dirs.map(async (dir) => {
+      // Only check security for system policies
+      if (path.resolve(dir) === systemPoliciesDir) {
+        const { secure, reason } = await isDirectorySecure(dir);
+        if (!secure) {
+          const msg = `Security Warning: Skipping system policies from ${dir}: ${reason}`;
+          coreEvents.emitFeedback('warning', msg);
+          return null;
+        }
+      }
+      return dir;
+    }),
+  );
+
+  return results.filter((dir): dir is string => dir !== null);
+}
+
 export async function createPolicyEngineConfig(
   settings: PolicySettings,
   approvalMode: ApprovalMode,
   defaultPoliciesDir?: string,
 ): Promise<PolicyEngineConfig> {
   const policyDirs = getPolicyDirectories(defaultPoliciesDir);
+  const securePolicyDirs = await filterSecurePolicyDirectories(policyDirs);
 
   // Load policies from TOML files
   const {
     rules: tomlRules,
     checkers: tomlCheckers,
     errors,
-  } = await loadPoliciesFromToml(policyDirs, (dir) =>
+  } = await loadPoliciesFromToml(securePolicyDirs, (dir) =>
     getPolicyTier(dir, defaultPoliciesDir),
   );