feat: add enterprise plugin system for ggshield

Author: clement-tourriere

.importlinter

@@ -7,35 +7,36 @@ include_external_packages = True
 [importlinter:contract:ggshield-layers]
 name = ggshield-layers
 type = layers
-layers = 
+layers =
 	ggshield.__main__
-	ggshield.cmd.auth | ggshield.cmd.config | ggshield.cmd.hmsl | ggshield.cmd.honeytoken | ggshield.cmd.install | ggshield.cmd.quota | ggshield.cmd.secret | ggshield.cmd.status | ggshield.cmd.utils
+	ggshield.cmd.auth | ggshield.cmd.config | ggshield.cmd.hmsl | ggshield.cmd.honeytoken | ggshield.cmd.install | ggshield.cmd.plugin | ggshield.cmd.quota | ggshield.cmd.secret | ggshield.cmd.status | ggshield.cmd.utils
 	ggshield.verticals.auth | ggshield.verticals.hmsl | ggshield.verticals.secret
 	ggshield.core
 	click | ggshield.utils | pygitguardian
-ignore_imports = 
+ignore_imports =
 	ggshield.cmd.** -> ggshield.cmd.utils.*
 	ggshield.utils.click.** -> click
 unmatched_ignore_imports_alerting = warn
 
 [importlinter:contract:verticals-cmd-transversals]
 name = verticals-cmd-transversals
 type = forbidden
-source_modules = 
+source_modules =
 	ggshield.cmd.auth
 	ggshield.cmd.config
 	ggshield.cmd.hmsl
 	ggshield.cmd.honeytoken
 	ggshield.cmd.install
+	ggshield.cmd.plugin
 	ggshield.cmd.quota
 	ggshield.cmd.secret
 	ggshield.cmd.status
 	ggshield.cmd.utils
-forbidden_modules = 
+forbidden_modules =
 	ggshield.verticals.auth
 	ggshield.verticals.hmsl
 	ggshield.verticals.secret
-ignore_imports = 
+ignore_imports =
 	ggshield.cmd.auth.** -> ggshield.verticals.auth
 	ggshield.cmd.auth.** -> ggshield.verticals.auth.**
 	ggshield.cmd.auth.** -> ggshield.verticals.hmsl.**
@@ -47,6 +48,8 @@ ignore_imports =
 	ggshield.cmd.honeytoken.** -> ggshield.verticals.honeytoken.**
 	ggshield.cmd.install.** -> ggshield.verticals.install
 	ggshield.cmd.install.** -> ggshield.verticals.install.**
+	ggshield.cmd.plugin.** -> ggshield.verticals.plugin
+	ggshield.cmd.plugin.** -> ggshield.verticals.plugin.**
 	ggshield.cmd.quota.** -> ggshield.verticals.quota
 	ggshield.cmd.quota.** -> ggshield.verticals.quota.**
 	ggshield.cmd.secret.** -> ggshield.verticals.secret

changelog.d/20260126_100000_clement.tourriere_enterprise_plugin_system.md

@@ -0,0 +1,42 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+
+### Added
+
+- Add enterprise plugin system for ggshield, allowing organizations to install and manage plugins from GitGuardian.
+
+<!--
+### Changed
+
+- A bullet item for the Changed category.
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->

ggshield/__main__.py

@@ -15,6 +15,7 @@
 from ggshield.cmd.hmsl import hmsl_group
 from ggshield.cmd.honeytoken import honeytoken_group
 from ggshield.cmd.install import install_cmd
+from ggshield.cmd.plugin import plugin_group
 from ggshield.cmd.quota import quota_cmd
 from ggshield.cmd.secret import secret_group
 from ggshield.cmd.secret.scan import scan_group
@@ -25,8 +26,11 @@
 from ggshield.core import check_updates, ui
 from ggshield.core.cache import Cache
 from ggshield.core.config import Config
+from ggshield.core.config.enterprise_config import EnterpriseConfig
 from ggshield.core.env_utils import load_dot_env
 from ggshield.core.errors import ExitCode
+from ggshield.core.plugin.loader import PluginLoader
+from ggshield.core.plugin.registry import PluginRegistry
 from ggshield.core.ui import ensure_level, log_utils
 from ggshield.core.ui.rich import RichGGShieldUI
 from ggshield.utils.click import RealPath
@@ -55,11 +59,36 @@ def exit_code(ctx: click.Context, exit_code: int, **kwargs: Any) -> int:
     return exit_code
 
 
+# Load plugins early so their commands can be discovered
+# This happens at module load time, before the CLI is invoked
+_plugin_registry: Optional[PluginRegistry] = None
+
+
+def _load_plugins() -> PluginRegistry:
+    """Load plugins at module level so commands are available."""
+    global _plugin_registry
+    if _plugin_registry is None:
+        try:
+            enterprise_config = EnterpriseConfig.load()
+            plugin_loader = PluginLoader(enterprise_config)
+            _plugin_registry = plugin_loader.load_enabled_plugins()
+        except Exception as e:
+            logger.debug("Failed to load plugins: %s", e)
+            _plugin_registry = PluginRegistry()
+
+        # Make registry available to hooks module
+        from ggshield.core.plugin.hooks import set_plugin_registry
+
+        set_plugin_registry(_plugin_registry)
+    return _plugin_registry
+
+
 @click.group(
     context_settings={"help_option_names": ["-h", "--help"]},
     commands={
         "auth": auth_group,
         "config": config_group,
+        "plugin": plugin_group,
         "secret": secret_group,
         "install": install_cmd,
         "quota": quota_cmd,
@@ -83,6 +112,7 @@ def cli(
     *,
     allow_self_signed: Optional[bool],
     insecure: Optional[bool],
+    instance: Optional[str],
     config_path: Optional[Path],
     **kwargs: Any,
 ) -> None:
@@ -104,11 +134,33 @@ def cli(
     if insecure or allow_self_signed:
         user_config.insecure = True
 
+    # Set the instance URL from command line if provided
+    if instance:
+        ctx_obj.config.cmdline_instance_name = instance
+
     ctx_obj.config._dotenv_vars = load_dot_env()
 
+    # Use pre-loaded plugin registry
+    ctx_obj.plugin_registry = _load_plugins()
+
     _set_color(ctx)
 
 
+# Register plugin commands at module load time
+# This must happen after the cli group is defined
+def _register_plugin_commands() -> None:
+    """Register plugin commands with the CLI."""
+    try:
+        registry = _load_plugins()
+        for cmd in registry.get_commands():
+            cli.add_command(cmd)
+    except Exception as e:
+        logger.debug("Failed to register plugin commands: %s", e)
+
+
+_register_plugin_commands()
+
+
 def _set_color(ctx: click.Context):
     """
     Helper function to override the default click default output color setting.

ggshield/cmd/plugin/__init__.py

@@ -0,0 +1,51 @@
+"""
+Plugin commands for managing ggshield plugins.
+"""
+
+from typing import Any
+
+import click
+
+from ggshield.cmd.plugin.install import install_cmd
+from ggshield.cmd.plugin.manage import disable_cmd, enable_cmd, uninstall_cmd
+from ggshield.cmd.plugin.plugin_list import list_cmd
+from ggshield.cmd.plugin.status import status_cmd
+from ggshield.cmd.plugin.update import update_cmd
+from ggshield.cmd.utils.common_options import add_common_options
+
+
+@click.group(
+    commands={
+        "install": install_cmd,
+        "list": list_cmd,
+        "status": status_cmd,
+        "enable": enable_cmd,
+        "disable": disable_cmd,
+        "uninstall": uninstall_cmd,
+        "update": update_cmd,
+    }
+)
+@add_common_options()
+def plugin_group(**kwargs: Any) -> None:
+    """
+    Manage ggshield plugins.
+
+    Plugins extend ggshield with additional capabilities like local secret
+    detection. Use 'ggshield plugin status' to see available plugins
+    for your GitGuardian account.
+
+    Examples:
+
+        # Check available plugins for your account
+        ggshield plugin status
+
+        # Install a plugin
+        ggshield plugin install tokenscanner
+
+        # List installed plugins
+        ggshield plugin list
+
+        # Check for updates
+        ggshield plugin update --check
+    """
+    pass

ggshield/cmd/plugin/install.py

@@ -0,0 +1,119 @@
+"""
+Plugin install command.
+"""
+
+from typing import Any, Optional
+
+import click
+
+from ggshield.cmd.utils.common_options import add_common_options
+from ggshield.cmd.utils.context_obj import ContextObj
+from ggshield.core import ui
+from ggshield.core.client import create_client_from_config
+from ggshield.core.config.enterprise_config import EnterpriseConfig
+from ggshield.core.errors import ExitCode
+from ggshield.core.plugin.downloader import DownloadError, PluginDownloader
+from ggshield.core.plugin.entitlements import (
+    EntitlementsClient,
+    EntitlementsError,
+    PluginNotAvailableError,
+)
+
+
+@click.command()
+@click.argument("plugin_name")
+@click.option(
+    "--version",
+    "version",
+    default=None,
+    help="Specific version to install (defaults to latest)",
+)
+@add_common_options()
+@click.pass_context
+def install_cmd(
+    ctx: click.Context,
+    plugin_name: str,
+    version: Optional[str],
+    **kwargs: Any,
+) -> None:
+    """
+    Download and install a plugin from GitGuardian.
+
+    Install a specific plugin:
+
+        ggshield plugin install tokenscanner
+
+    Install a specific version:
+
+        ggshield plugin install tokenscanner --version 0.1.0
+
+    Plugins are downloaded from GitGuardian and installed locally.
+    Requires authentication with a GitGuardian account.
+    """
+
+    ctx_obj = ContextObj.get(ctx)
+    config = ctx_obj.config
+
+    # Fetch entitlements
+    try:
+        client = create_client_from_config(config)
+        entitlements_client = EntitlementsClient(client)
+        entitlements = entitlements_client.get_entitlements()
+    except EntitlementsError as e:
+        ui.display_error(str(e))
+        ctx.exit(ExitCode.UNEXPECTED_ERROR)
+    except Exception as e:
+        ui.display_error(f"Failed to connect to GitGuardian: {e}")
+        ctx.exit(ExitCode.UNEXPECTED_ERROR)
+
+    # Check if plugin is available
+    available_plugins = {p.name: p for p in entitlements.plugins if p.available}
+
+    if plugin_name not in available_plugins:
+        # Check if plugin exists but is not available
+        unavailable = next(
+            (p for p in entitlements.plugins if p.name == plugin_name), None
+        )
+        if unavailable:
+            ui.display_error(
+                f"Plugin '{plugin_name}' is not available for your account"
+            )
+            if unavailable.reason:
+                ui.display_info(f"Reason: {unavailable.reason}")
+        else:
+            ui.display_error(f"Unknown plugin: {plugin_name}")
+            ui.display_info("Use 'ggshield plugin status' to see available plugins")
+        ctx.exit(ExitCode.USAGE_ERROR)
+
+    # Install the plugin
+    downloader = PluginDownloader()
+    enterprise_config = EnterpriseConfig.load()
+
+    ui.display_info(f"Installing {plugin_name}...")
+
+    try:
+        # Get download info
+        download_info = entitlements_client.get_plugin_download_info(
+            plugin_name, version=version
+        )
+
+        # Download and install
+        downloader.download_and_install(download_info, plugin_name)
+
+        # Enable in config
+        enterprise_config.enable_plugin(plugin_name, version=download_info.version)
+
+        # Save config
+        enterprise_config.save()
+
+        ui.display_info(f"Installed {plugin_name} v{download_info.version}")
+
+    except PluginNotAvailableError as e:
+        ui.display_error(f"Failed to install {plugin_name}: {e}")
+        ctx.exit(ExitCode.UNEXPECTED_ERROR)
+    except DownloadError as e:
+        ui.display_error(f"Failed to install {plugin_name}: {e}")
+        ctx.exit(ExitCode.UNEXPECTED_ERROR)
+    except Exception as e:
+        ui.display_error(f"Failed to install {plugin_name}: {e}")
+        ctx.exit(ExitCode.UNEXPECTED_ERROR)