Add support for policy engine in extensions

[chrstnb]

Summary

Add support for extensions to contribute policy rules and safety checkers to the policy engine. It establishes a secure framework for extensions to provide guardrails while preventing them from bypassing user confirmation or security modes.

Details

1. Core policy engine enhancements

• Shared policy tier: Reverted to a 4-tier system where extensions contribute to the Workspace Tier (Tier 2), placing them alongside workspace-defined policies.
  • Default: 1
  • Workspace/Extension: 2
  • User: 3
  • Admin: 4
• Source-based management: Added removeRulesBySource and removeCheckersBySource to PolicyEngine to allow surgical removal of extension-contributed rules when an extension is deactivated.

2. Extension configuration and manifest

• Manifest update: The policies property has been removed from gemini-extension.json.
• Interface updates: Enhanced the GeminiCLIExtension interface to carry parsed rules and checkers through the system lifecycle.

3. Security mandates (critical)

To prevent extensions from compromising system security, the following restrictions are enforced during policy loading:

• Ignored allow rules: Any rule contributing an ALLOW decision is strictly ignored. Extensions can only use DENY or ASK_USER decisions.
• Ignored yolo mode: Extensions are prohibited from contributing rules or checkers for yolo mode.
• Logging: Warnings are logged to the debug console when an extension attempts to contribute disallowed rules, identifying the extension and the specific tool involved.

4. Lifecycle automation

• Auto-registration: ExtensionLoader now automatically registers policy rules and checkers when an extension starts.
• Auto-unregistration: Extension rules are automatically removed when the extension is stopped, using the namespaced source field to avoid affecting other extensions or system policies.

5. Documentation and examples

• Updated docs/extensions/reference.md with:
  • Documentation reflecting the new directory-based policy loading approach (i.e., policies/ directory).
  • A dedicated section on contributing to the Policy Engine.
  • Security warnings regarding the ignored allow and yolo configurations.
• New example extension: Added packages/cli/src/commands/extensions/examples/policies, which provides a hands-on example of contributing rules and safety checkers via the new policies/ directory.

6. Verification and quality

• Added unit and integration tests for extension policy loading and security enforcement.
• Updated all existing policy tests to reflect the new tier numbering.
• Verified full project integrity with npm run build and npm run lint.

Related Issues

Fixes https://github.com/google-gemini/maintainers-gemini-cli/issues/1407
Fixes #19702

How to Validate

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

[gemini-code-assist]

Summary of Changes

Hello @chrstnb, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Gemini CLI's extensibility by allowing extensions to securely integrate with the core policy engine. It introduces a dedicated policy tier for extensions, ensuring their rules are applied appropriately within the existing hierarchy. The changes include robust security measures to prevent extensions from undermining user control or system safety, alongside automated management of policy registration and unregistration. This enables extensions to provide valuable guardrails and custom security checks, making the CLI more adaptable and secure.

Highlights

• Policy Engine Integration for Extensions: Extensions can now contribute policy rules and safety checkers to the Gemini CLI Policy Engine, enabling them to define guardrails for tool usage.
• New Policy Tier Introduced: An EXTENSION_POLICY_TIER (Tier 2) has been added, positioning extension policies with higher priority than default rules but lower than workspace, user, or admin policies. Existing tiers have been renumbered accordingly.
• Secure Policy Contribution: To maintain security, extension-contributed policies are restricted: ALLOW decisions and yolo mode configurations are strictly ignored, preventing extensions from bypassing user confirmation or security measures.
• Automated Policy Lifecycle Management: The ExtensionLoader now automatically registers policy rules and safety checkers when an extension starts and unregisters them when an extension stops, ensuring dynamic and clean management of extension policies.
• Manifest and Interface Updates: The gemini-extension.json manifest now includes a policies property to specify a TOML file for policy definitions, and the GeminiCLIExtension interface has been enhanced to carry parsed rules and checkers.
• Policy Engine Cleanup Methods: New methods removeRulesBySource and removeCheckersBySource have been added to the PolicyEngine to allow for surgical removal of policies contributed by specific sources, such as deactivated extensions.
• Comprehensive Documentation and Example: Updated documentation provides guidance on contributing to the Policy Engine, including security warnings, and a new example extension demonstrates how to define and use extension policies.

Changelog

• docs/extensions/reference.md
  • Updated documentation to include the new policies property in gemini-extension.json.
  • Added a new section detailing how extensions can contribute to the Policy Engine.
  • Included security warnings regarding allow decisions and yolo mode for extension policies in the documentation.
• package-lock.json
  • Updated various package dependencies by adding the peer: true flag.
  • Added a new dependency strip-json-comments.
• packages/cli/src/commands/extensions/examples/policies/README.md
  • Added a new README file for the policy engine example extension.
• packages/cli/src/commands/extensions/examples/policies/gemini-extension.json
  • Added a new extension manifest file for the policy engine example, including a policies entry.
• packages/cli/src/commands/extensions/examples/policies/policies.toml
  • Added a new TOML file defining example policy rules and safety checkers for the example extension.
• packages/cli/src/config/extension-manager.ts
  • Imported policy-related types and constants from @google/gemini-cli-core.
  • Implemented logic to load policy rules and safety checkers from extension policy files.
  • Added security checks to filter out ALLOW decisions and YOLO mode rules/checkers from extensions.
  • Prefixed policy rule and checker sources with the extension name to prevent collisions.
• packages/cli/src/config/extension.ts
  • Added an optional policies property to the ExtensionConfig interface to specify a policy TOML file path.
• packages/cli/src/config/policy-engine.integration.test.ts
  • Updated expected priority values in integration tests to align with the newly introduced EXTENSION_POLICY_TIER and renumbered tiers.
• packages/cli/src/test-utils/createExtension.ts
  • Added a policies parameter to the createExtension utility function for testing purposes.
• packages/core/src/config/config.ts
  • Imported PolicyRule and SafetyCheckerRule types.
  • Added optional rules and checkers properties to the GeminiCLIExtension interface to hold extension-contributed policies.
• packages/core/src/policy/config.ts
  • Introduced EXTENSION_POLICY_TIER as Tier 2.
  • Shifted WORKSPACE_POLICY_TIER, USER_POLICY_TIER, and ADMIN_POLICY_TIER to higher numerical values.
  • Adjusted the ALWAYS_ALLOW_PRIORITY calculation to reflect the new tier numbering.
• packages/core/src/policy/policy-engine.ts
  • Added removeRulesBySource method to remove policy rules based on their source identifier.
  • Added removeCheckersBySource method to remove safety checkers based on their source identifier.
• packages/core/src/policy/toml-loader.test.ts
  • Updated test cases to reflect the new policy tier numbering and source naming conventions.
• packages/core/src/policy/toml-loader.ts
  • Updated the PolicyFileError interface to include the new extension tier type.
  • Modified the getTierName function to correctly map the new policy tier numbers to their corresponding names.
• packages/core/src/utils/extensionLoader.test.ts
  • Added mock implementations for PolicyEngine methods (addRule, addChecker, removeRulesBySource, removeCheckersBySource).
  • Updated the mock activeExtension to include example policy rules and checkers.
  • Added new tests to verify that policies are correctly registered when an extension starts and unregistered when it stops.
• packages/core/src/utils/extensionLoader.ts
  • Implemented automatic registration of extension-defined policy rules and safety checkers with the PolicyEngine upon extension activation.
  • Implemented automatic unregistration of extension-defined policy rules and safety checkers from the PolicyEngine upon extension deactivation, using their source identifiers.

Activity

• No human activity (comments, reviews) was provided in the context for this pull request.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a well-designed feature enabling extensions to contribute to the policy engine, including a new policy tier and security restrictions to prevent extensions from bypassing user confirmations. While the security architecture is generally well-thought-out, a critical Path Traversal vulnerability was identified in the extension policy loading logic. The policies path from the manifest is not validated to remain within the extension's directory, which could lead to unauthorized file access and must be addressed. Additionally, an issue was found where a safety checker's source is modified twice, which would break the unregistration logic.

[github-actions]

Size Change: +4.15 kB (+0.02%)

Total Size: 25.7 MB

Filename	Size	Change
./bundle/gemini.js	25.2 MB	+4.15 kB (+0.02%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[chrstnb]

Build failed: Build process failed with link errors:

18:08:32 [ERROR] ✗ Found 1 invalid link in 1 file.
18:08:32   └─ /docs/admin/policy-engine - invalid link
18:08:32 [ERROR] [starlight-links-validator-integration] An unhandled error occurred while running the "astro:build:done" hook

[chrstnb]

Build failed: Build process failed with link errors:

22:14:41 [ERROR] ✗ Found 1 invalid link in 1 file.
22:14:41   └─ /docs/admin/policy-engine - invalid link
22:14:41 [ERROR] [starlight-links-validator-integration] An unhandled error occurred while running the "astro:build:done" hook

[Abhijit-2592]

LGTM with minor cosmetic comments