xsoar-cli 1.0.9__py3-none-any.whl

xsoar_cli/plugins/commands.py

@@ -0,0 +1,273 @@
+"""
+Plugin management commands for XSOAR CLI
+
+This module provides CLI commands for managing plugins, including
+listing, loading, reloading, and creating example plugins.
+"""
+
+import logging
+
+import click
+
+from .manager import PluginManager
+
+logger = logging.getLogger(__name__)
+
+
+@click.group(help="Manage XSOAR CLI plugins")
+def plugins():
+    """Plugin management commands."""
+
+
+@click.command(help="List all available and loaded plugins")
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed information")
+@click.pass_context
+def list_plugins(ctx: click.Context, verbose: bool):
+    """List all plugins in the plugins directory."""
+    plugin_manager = PluginManager()
+
+    # Discover all plugins
+    discovered = plugin_manager.discover_plugins()
+
+    # Load all plugins to get their info
+    plugin_manager.load_all_plugins(ignore_errors=True)
+
+    loaded_info = plugin_manager.get_plugin_info()
+    failed_info = plugin_manager.get_failed_plugins()
+
+    if not discovered:
+        return
+
+    click.echo(f"Plugins directory: {plugin_manager.plugins_dir}")
+    click.echo(f"Discovered {len(discovered)} plugin files\n")
+
+    # Show loaded plugins
+    if loaded_info:
+        click.echo("Loaded Plugins:")
+        for plugin_name, info in loaded_info.items():
+            if verbose:
+                click.echo(f"  {plugin_name}")
+                click.echo(f"    Name: {info['name']}")
+                click.echo(f"    Version: {info['version']}")
+                click.echo(f"    Description: {info['description']}")
+            else:
+                click.echo(f"  {plugin_name} (v{info['version']})")
+        click.echo()
+
+    # Show failed plugins
+    if failed_info:
+        click.echo("Failed Plugins:")
+        for plugin_name, error in failed_info.items():
+            if verbose:
+                click.echo(f"  {plugin_name}: {error}")
+            else:
+                click.echo(f"  {plugin_name}")
+        click.echo()
+
+    # Show unloaded plugins (discovered but not loaded and not failed)
+    unloaded = set(discovered) - set(loaded_info.keys()) - set(failed_info.keys())
+    if unloaded:
+        click.echo("Unloaded Plugins:")
+        for plugin_name in unloaded:
+            click.echo(f"  {plugin_name}")
+
+    # Show command conflicts
+    conflicts = plugin_manager.get_command_conflicts()
+    if conflicts:
+        click.echo()
+        click.echo("Command Conflicts:")
+        for conflict in conflicts:
+            click.echo(f"  Plugin '{conflict['plugin_name']}' command '{conflict['command_name']}' conflicts with core command")
+            click.echo(f"    Plugin version: {conflict['plugin_version']}")
+            click.echo("    Solution: Rename the command in your plugin or use a command group")
+
+
+@click.command(help="Reload a specific plugin")
+@click.argument("plugin_name", type=str)
+def reload(plugin_name: str):
+    """Reload a specific plugin."""
+    plugin_manager = PluginManager()
+
+    try:
+        click.echo(f"Reloading plugin: {plugin_name}...")
+        plugin = plugin_manager.reload_plugin(plugin_name)
+
+        if plugin:
+            click.echo(f"Successfully reloaded plugin: {plugin_name}")
+            click.echo(f"   Name: {plugin.name}")
+            click.echo(f"   Version: {plugin.version}")
+        else:
+            click.echo(f"Failed to reload plugin: {plugin_name}")
+
+    except Exception as e:
+        click.echo(f"Error reloading plugin {plugin_name}: {e}")
+
+
+@click.command(help="Show information about a specific plugin")
+@click.argument("plugin_name", type=str)
+def info(plugin_name: str):
+    """Show detailed information about a plugin."""
+    plugin_manager = PluginManager()
+
+    try:
+        plugin = plugin_manager.load_plugin(plugin_name)
+
+        if plugin:
+            click.echo("Plugin Information:")
+            click.echo(f"  File: {plugin_manager.plugins_dir / plugin_name}.py")
+            click.echo(f"  Name: {plugin.name}")
+            click.echo(f"  Version: {plugin.version}")
+            click.echo(f"  Description: {plugin.description or 'No description provided'}")
+
+            # Try to get command info
+            try:
+                command = plugin.get_command()
+                click.echo(f"  Command: {command.name}")
+                if hasattr(command, "commands"):
+                    subcommands = list(command.commands.keys())
+                    if subcommands:
+                        click.echo(f"  Subcommands: {', '.join(subcommands)}")
+            except Exception as e:
+                click.echo(f"  Command: Error loading command ({e})")
+        else:
+            click.echo(f"Plugin not found or failed to load: {plugin_name}")
+
+    except Exception as e:
+        click.echo(f"Error loading plugin {plugin_name}: {e}")
+
+
+@click.command(help="Validate all plugins")
+def validate():
+    """Validate all plugins in the plugins directory."""
+    plugin_manager = PluginManager()
+
+    discovered = plugin_manager.discover_plugins()
+
+    if not discovered:
+        click.echo(f"No plugins found in {plugin_manager.plugins_dir}")
+        return
+
+    click.echo(f"Validating {len(discovered)} plugins...\n")
+
+    all_valid = True
+
+    for plugin_name in discovered:
+        try:
+            plugin = plugin_manager.load_plugin(plugin_name)
+            if plugin:
+                # Test that the plugin can provide a command
+                command = plugin.get_command()
+                if not isinstance(command, (click.Command, click.Group)):
+                    raise ValueError("get_command() must return a Click Command or Group")
+
+                click.echo(f"{plugin_name}: Valid")
+            else:
+                click.echo(f"{plugin_name}: Failed to load")
+                all_valid = False
+
+        except Exception as e:
+            click.echo(f"{plugin_name}: {e}")
+            all_valid = False
+
+    # Check for command conflicts by attempting registration
+    try:
+        from xsoar_cli.cli import cli
+
+        temp_plugin_manager = PluginManager()
+        temp_plugin_manager.load_all_plugins(ignore_errors=True)
+        temp_plugin_manager.register_plugin_commands(cli)
+
+        conflicts = temp_plugin_manager.get_command_conflicts()
+        if conflicts:
+            click.echo("\nCommand Conflicts Detected:")
+            for conflict in conflicts:
+                click.echo(f"  Plugin '{conflict['plugin_name']}' command '{conflict['command_name']}' conflicts with core command")
+                click.echo("    Solution: Rename the command or use a command group")
+            all_valid = False
+    except Exception as e:
+        click.echo(f"\nCould not check for command conflicts: {e}")
+
+    click.echo()
+    if all_valid:
+        click.echo("All plugins are valid!")
+    else:
+        click.echo("Some plugins have validation errors.")
+
+
+@click.command(help="Open the plugins directory")
+def open_dir():
+    """Open the plugins directory in the system file manager."""
+    plugin_manager = PluginManager()
+    plugins_dir = plugin_manager.plugins_dir
+
+    click.echo(f"Plugins directory: {plugins_dir}")
+
+    # Try to open the directory
+    import subprocess
+    import sys
+
+    try:
+        if sys.platform == "win32":
+            subprocess.run(["explorer", str(plugins_dir)], check=True)
+        elif sys.platform == "darwin":
+            subprocess.run(["open", str(plugins_dir)], check=True)
+        else:
+            subprocess.run(["xdg-open", str(plugins_dir)], check=True)
+
+        click.echo("Opened plugins directory in file manager.")
+
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        click.echo("Could not open directory automatically.")
+        click.echo(f"Please navigate to: {plugins_dir}")
+
+
+# Add all commands to the plugins group
+@click.command(help="Check for command conflicts with core CLI")
+def check_conflicts():
+    """Check for command conflicts between plugins and core CLI."""
+    plugin_manager = PluginManager()
+
+    # Load all plugins
+    plugin_manager.load_all_plugins(ignore_errors=True)
+
+    # Check conflicts by attempting registration with a temporary CLI group
+    import click
+
+    temp_cli = click.Group()
+
+    # Add core commands to temp CLI to simulate real conflicts
+    core_commands = ["case", "config", "graph", "manifest", "pack", "playbook", "plugins"]
+    for cmd_name in core_commands:
+        temp_cli.add_command(click.Command(cmd_name, callback=lambda: None))
+
+    # Attempt to register plugin commands
+    plugin_manager.register_plugin_commands(temp_cli)
+
+    conflicts = plugin_manager.get_command_conflicts()
+
+    if not conflicts:
+        click.echo("No command conflicts detected!")
+        click.echo("All plugin commands have unique names.")
+        return
+
+    click.echo(f"Found {len(conflicts)} command conflict(s):")
+    click.echo()
+
+    for conflict in conflicts:
+        click.echo(f"Plugin: {conflict['plugin_name']} (v{conflict['plugin_version']})")
+        click.echo(f"   Command: '{conflict['command_name']}'")
+        click.echo("   Conflicts with: Core CLI command")
+        click.echo()
+
+    click.echo("Solutions:")
+    click.echo("  Rename the conflicting command in your plugin")
+    click.echo("  Use a command group to namespace your commands")
+    click.echo("  Example: Instead of 'case', use 'mycase' or 'myplugin case'")
+
+
+plugins.add_command(list_plugins, name="list")
+plugins.add_command(reload)
+plugins.add_command(info)
+plugins.add_command(validate)
+plugins.add_command(check_conflicts, name="check-conflicts")
+plugins.add_command(open_dir, name="open")

xsoar_cli/plugins/manager.py

@@ -0,0 +1,328 @@
+"""
+Plugin Manager for XSOAR CLI
+
+This module handles the discovery, loading, and management of plugins
+for the xsoar-cli application from a local directory.
+"""
+
+import importlib.util
+import logging
+import sys
+import types
+from pathlib import Path
+
+import click
+
+from . import PluginLoadError, PluginRegistrationError, XSOARPlugin
+
+logger = logging.getLogger(__name__)
+
+
+class PluginManager:
+    """
+    Manages the discovery, loading, and registration of XSOAR CLI plugins
+    from the ~/.local/xsoar-cli/plugins directory.
+    """
+
+    def __init__(self, plugins_dir: Path | None = None) -> None:
+        """
+        Initialize the plugin manager.
+
+        Args:
+            plugins_dir: Custom plugins directory. If None, uses ~/.local/xsoar-cli/plugins
+        """
+        if plugins_dir is None:
+            self.plugins_dir = Path.home() / ".local" / "xsoar-cli" / "plugins"
+        else:
+            self.plugins_dir = plugins_dir
+
+        self.loaded_plugins: dict[str, XSOARPlugin] = {}
+        self.failed_plugins: dict[str, Exception] = {}
+        self.command_conflicts: list[dict[str, str]] = []
+
+        # Ensure plugins directory exists
+        self.plugins_dir.mkdir(parents=True, exist_ok=True)
+
+        # Add plugins directory to Python path if not already there
+        plugins_dir_str = str(self.plugins_dir)
+        if plugins_dir_str not in sys.path:
+            sys.path.insert(0, plugins_dir_str)
+
+    def discover_plugins(self) -> list[str]:
+        """
+        Discover available plugins by scanning the plugins directory for Python files.
+
+        Returns:
+            List of plugin module names found
+        """
+        plugin_names = []
+
+        if not self.plugins_dir.exists():
+            logger.info(f"Plugins directory does not exist: {self.plugins_dir}")
+            return plugin_names
+
+        for file_path in self.plugins_dir.glob("*.py"):
+            if file_path.name.startswith("__"):
+                continue  # Skip __init__.py, __pycache__, etc.
+
+            module_name = file_path.stem
+            plugin_names.append(module_name)
+
+        logger.info(f"Discovered {len(plugin_names)} plugin files: {plugin_names}")
+        return plugin_names
+
+    def _load_module_from_file(self, module_name: str, file_path: Path) -> types.ModuleType:
+        """
+        Load a Python module from a file path.
+
+        Args:
+            module_name: Name to give the module
+            file_path: Path to the Python file
+
+        Returns:
+            The loaded module
+        """
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if spec is None or spec.loader is None:
+            raise PluginLoadError(f"Could not load module spec for {file_path}")
+
+        module = importlib.util.module_from_spec(spec)
+
+        # Inject XSOARPlugin class into the module's namespace
+        # This allows plugins to use XSOARPlugin without complex imports
+        from . import XSOARPlugin
+
+        module.XSOARPlugin = XSOARPlugin
+
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        return module
+
+    def _find_plugin_classes(self, module: types.ModuleType) -> list[type[XSOARPlugin]]:
+        """
+        Find all XSOARPlugin classes in a module.
+
+        Args:
+            module: The module to search
+
+        Returns:
+            List of plugin classes found
+        """
+        plugin_classes = []
+
+        for attr_name in dir(module):
+            attr = getattr(module, attr_name)
+
+            # Check if it's a class that inherits from XSOARPlugin
+            if isinstance(attr, type) and issubclass(attr, XSOARPlugin) and attr is not XSOARPlugin:
+                plugin_classes.append(attr)
+
+        return plugin_classes
+
+    def load_plugin(self, plugin_name: str) -> XSOARPlugin | None:
+        """
+        Load a single plugin by name.
+
+        Args:
+            plugin_name: Name of the plugin module to load
+
+        Returns:
+            The loaded plugin instance, or None if loading failed
+
+        Raises:
+            PluginLoadError: If the plugin fails to load
+        """
+        if plugin_name in self.loaded_plugins:
+            return self.loaded_plugins[plugin_name]
+
+        try:
+            file_path = self.plugins_dir / f"{plugin_name}.py"
+            if not file_path.exists():
+                raise PluginLoadError(f"Plugin file not found: {file_path}")
+
+            # Load the module
+            module = self._load_module_from_file(plugin_name, file_path)
+
+            # Find plugin classes in the module
+            plugin_classes = self._find_plugin_classes(module)
+
+            if not plugin_classes:
+                raise PluginLoadError(
+                    f"No XSOARPlugin classes found in {plugin_name}.py",
+                )
+
+            if len(plugin_classes) > 1:
+                logger.warning(
+                    f"Multiple plugin classes found in {plugin_name}.py, using the first one",
+                )
+
+            # Instantiate the first plugin class found
+            plugin_class = plugin_classes[0]
+            plugin_instance = plugin_class()
+
+            # Initialize the plugin
+            try:
+                plugin_instance.initialize()
+            except Exception as e:
+                raise PluginLoadError(f"Plugin '{plugin_name}' initialization failed: {e}")
+
+            # Store the loaded plugin
+            self.loaded_plugins[plugin_name] = plugin_instance
+            logger.info(f"Successfully loaded plugin: {plugin_name}")
+
+            return plugin_instance
+
+        except Exception as e:
+            self.failed_plugins[plugin_name] = e
+            logger.error(f"Failed to load plugin '{plugin_name}': {e}")
+            raise PluginLoadError(f"Failed to load plugin '{plugin_name}': {e}")
+
+    def load_all_plugins(self, *, ignore_errors: bool = True) -> dict[str, XSOARPlugin]:
+        """
+        Load all discovered plugins.
+
+        Args:
+            ignore_errors: If True, continue loading other plugins when one fails
+
+        Returns:
+            Dictionary of successfully loaded plugins
+
+        Raises:
+            PluginLoadError: If ignore_errors is False and any plugin fails to load
+        """
+        discovered_plugins = self.discover_plugins()
+
+        for plugin_name in discovered_plugins:
+            try:
+                self.load_plugin(plugin_name)
+            except PluginLoadError as e:
+                if not ignore_errors:
+                    raise
+                logger.warning(f"Skipping failed plugin: {e}")
+
+        return self.loaded_plugins.copy()
+
+    def register_plugin_commands(self, cli_group: click.Group) -> None:
+        """
+        Register all loaded plugin commands with the CLI group.
+
+        Args:
+            cli_group: The Click group to register commands with
+
+        Raises:
+            PluginRegistrationError: If a plugin command fails to register
+        """
+        conflicts = []
+
+        for plugin_name, plugin in self.loaded_plugins.items():
+            try:
+                command = plugin.get_command()
+                if not isinstance(command, (click.Command, click.Group)):
+                    raise PluginRegistrationError(
+                        f"Plugin '{plugin_name}' get_command() must return a Click Command or Group",
+                    )
+
+                # Ensure the command name doesn't conflict with existing commands
+                if command.name in cli_group.commands:
+                    conflict_info = {
+                        "plugin_name": plugin_name,
+                        "command_name": command.name,
+                        "plugin_version": plugin.version,
+                    }
+                    conflicts.append(conflict_info)
+                    logger.warning(
+                        f"Plugin '{plugin_name}' command '{command.name}' conflicts with existing command",
+                    )
+                    continue
+
+                cli_group.add_command(command)
+                logger.info(f"Registered command '{command.name}' from plugin '{plugin_name}'")
+
+            except Exception as e:
+                error_msg = f"Failed to register plugin '{plugin_name}': {e}"
+                logger.error(error_msg)
+                raise PluginRegistrationError(error_msg)
+
+        # Store conflicts for later reporting
+        self.command_conflicts = conflicts
+
+    def unload_plugin(self, plugin_name: str) -> None:
+        """
+        Unload a plugin and call its cleanup method.
+
+        Args:
+            plugin_name: Name of the plugin to unload
+        """
+        if plugin_name in self.loaded_plugins:
+            plugin = self.loaded_plugins[plugin_name]
+            try:
+                plugin.cleanup()
+            except Exception as e:
+                logger.warning(f"Plugin '{plugin_name}' cleanup failed: {e}")
+            del self.loaded_plugins[plugin_name]
+            logger.info(f"Unloaded plugin: {plugin_name}")
+
+    def unload_all_plugins(self) -> None:
+        """Unload all plugins and call their cleanup methods."""
+        plugin_names = list(self.loaded_plugins.keys())
+        for plugin_name in plugin_names:
+            self.unload_plugin(plugin_name)
+
+    def get_plugin_info(self) -> dict[str, dict[str, str]]:
+        """
+        Get information about all loaded plugins.
+
+        Returns:
+            Dictionary with plugin information
+        """
+        info = {}
+        for plugin_name, plugin in self.loaded_plugins.items():
+            info[plugin_name] = {
+                "name": plugin.name,
+                "version": plugin.version,
+                "description": plugin.description or "No description provided",
+            }
+        return info
+
+    def get_failed_plugins(self) -> dict[str, str]:
+        """
+        Get information about plugins that failed to load.
+
+        Returns:
+            Dictionary with plugin names and error messages
+        """
+        return {name: str(error) for name, error in self.failed_plugins.items()}
+
+    def get_command_conflicts(self) -> list[dict[str, str]]:
+        """
+        Get information about command conflicts.
+
+        Returns:
+            List of dictionaries with conflict information
+        """
+        return self.command_conflicts.copy()
+
+    def reload_plugin(self, plugin_name: str) -> XSOARPlugin | None:
+        """
+        Reload a plugin by unloading and loading it again.
+
+        Args:
+            plugin_name: Name of the plugin to reload
+
+        Returns:
+            The reloaded plugin instance, or None if reloading failed
+        """
+        # Unload if already loaded
+        if plugin_name in self.loaded_plugins:
+            self.unload_plugin(plugin_name)
+
+        # Remove from failed plugins if it was there
+        if plugin_name in self.failed_plugins:
+            del self.failed_plugins[plugin_name]
+
+        # Remove from sys.modules to force reload
+        if plugin_name in sys.modules:
+            del sys.modules[plugin_name]
+
+        # Load again
+        return self.load_plugin(plugin_name)