xsoar-cli 1.0.9__py3-none-any.whl

xsoar_cli/manifest/commands.py

@@ -0,0 +1,271 @@
+import json
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from xsoar_cli.utilities import load_config
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+
+def load_manifest(manifest: str):  # noqa: ANN201
+    """Calls json.load() on the manifest and returns a dict."""
+    filepath = Path(manifest)
+    try:
+        return json.load(filepath.open("r"))
+    except json.JSONDecodeError:
+        msg = f"Failed to decode JSON in {filepath}"
+        click.echo(msg)
+        sys.exit(1)
+    except FileNotFoundError:
+        print(f"File not found: {filepath}")
+        sys.exit(1)
+
+
+def write_manifest(manifest: str, data: Any) -> None:  # noqa: ANN401
+    """Writes the xsoar_conf.json manifest using json.dumps()"""
+    manifest_path = Path(manifest)
+    with manifest_path.open("w") as f:
+        f.write(json.dumps(data, indent=4))
+        f.write("\n")
+    click.echo(f"Written updated manifest to '{manifest_path}'")
+
+
+@click.group()
+def manifest() -> None:
+    """Various commands to interact/update/deploy content packs defined in the xsoar_config.json manifest."""
+
+
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.argument("manifest_path", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def generate(ctx: click.Context, environment: str | None, manifest_path: str) -> None:
+    """Generate a new xsoar_config.json manifest from installed content packs.
+
+    This command assumes that you do not have any custom content packs uploaded to XSOAR.
+    All packs will be added as "marketplace_packs" in the manifest.
+    """
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    installed_packs = xsoar_client.get_installed_packs()
+    manifest_data = {
+        "marketplace_packs": [],
+    }
+    for item in installed_packs:
+        tmpobj = {
+            "id": item["id"],
+            "version": item["currentVersion"],
+        }
+        manifest_data["marketplace_packs"].append(tmpobj)
+    write_manifest(manifest_path, manifest_data)
+
+
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.argument("manifest", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def update(ctx: click.Context, environment: str | None, manifest: str) -> None:
+    """Update manifest on disk with latest available content pack versions."""
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    manifest_data = load_manifest(manifest)
+    click.echo("Fetching outdated packs from XSOAR server. This may take a minute...", nl=False)
+    results = xsoar_client.get_outdated_packs()
+    click.echo("done.")
+    if not results:
+        click.echo("No packs eligible for upgrade.")
+        sys.exit(0)
+
+    item1 = "Pack ID"
+    item2 = "Installed version"
+    item3 = "Latest available version"
+    header = f"{item1:50}{item2:20}{item3:20}"
+    click.echo(header)
+    for pack in results:
+        click.echo(f"{pack['id']:50}{pack['currentVersion']:20}{pack['latest']:20}")
+    click.echo(f"Total number of outdated content packs: {len(results)}")
+
+    for pack in results:
+        key = "custom_packs" if pack["author"] in ctx.obj["custom_pack_authors"] else "marketplace_packs"
+        index = next((i for i, item in enumerate(manifest_data[key]) if item["id"] == pack["id"]), None)
+        if index is None:
+            msg = f"Pack {pack['id']} not found in manifest."
+            click.echo(msg)
+            sys.exit(1)
+        comment = manifest_data[key][index].get("_comment", None)
+        if comment is not None:
+            print(f"WARNING: comment found in manifest for {pack['id']}: {comment}")
+        msg = f"Upgrade {pack['id']} from {pack['currentVersion']} to {pack['latest']}?"
+        should_upgrade = click.confirm(msg, default=True)
+        if should_upgrade:
+            manifest_data[key][index]["version"] = pack["latest"]
+    write_manifest(manifest, manifest_data)
+
+
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.option("--mode", type=click.Choice(["full", "diff"]), default="diff", help="Validate the full manifest, or only the definitions that diff with installed versions")
+@click.argument("manifest", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def validate(ctx: click.Context, environment: str | None, mode: str, manifest: str) -> None:
+    """Validate manifest JSON and content pack availability by doing HTTP CONNECT to the appropriate artifacts repository.
+    Custom pack availability is implementation dependant."""
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+
+    manifest_data = load_manifest(manifest)
+    click.echo("Manifest is valid JSON")
+    keys = ["custom_packs", "marketplace_packs"]
+
+
+    def found_in_local_filesystem() -> bool:
+        # If we are in a merge request and the merge request contains a new pack as well
+        # as a updated xsoar_config.json manifest, then the pack is not available in S3
+        # before the MR is merged. Check if we can find the appropriate pack version locally
+        # If so, we can ignore this error because the pack will become available after merge.
+        manifest_arg = Path(manifest)
+        manifest_path = manifest_arg.resolve()
+        repo_path = manifest_path.parent
+        pack_metadata_path = Path(f"{repo_path}/Packs/{pack['id']}/pack_metadata.json")
+        with Path.open(pack_metadata_path, encoding="utf-8") as f:
+            pack_metadata = json.load(f)
+        if pack_metadata["currentVersion"] == pack["version"]:
+            return True
+        # The relevant Pack locally does not have the requested version.
+        return False
+
+    if mode == "full":
+        for key in keys:
+            custom = key == "custom_packs"
+            click.echo(f"Checking {key} availability ", nl=False)
+            for pack in manifest_data[key]:
+                available = xsoar_client.is_pack_available(pack_id=pack["id"], version=pack["version"], custom=custom)
+                # We check if a pack is found in local filesystem regardless of whether it's an upstream pack or not.
+                # This should cause any significantly negative performance penalties.
+                if not available and not found_in_local_filesystem():
+                    click.echo(f"\nFailed to reach pack {pack['id']} version {pack['version']}")
+                    sys.exit(1)
+                click.echo(".", nl=False)
+            print()
+        click.echo("Manifest is valid JSON and all packs are reachable")
+        return
+    elif mode == "diff":
+        installed_packs = xsoar_client.get_installed_packs()
+        for key in keys:
+            found_diff = False
+            custom = key == "custom_packs"
+            click.echo(f"Checking {key} availability ", nl=False)
+            for pack in manifest_data[key]:
+                installed = next((item for item in installed_packs if item["id"] == pack["id"]), {})
+                if not installed or installed["currentVersion"] != pack["version"]:
+                    available = xsoar_client.is_pack_available(pack_id=pack["id"], version=pack["version"], custom=custom)
+                    # We check if a pack is found in local filesystem regardless of whether it's an upstream pack or not.
+                    # This should cause any significantly negative performance penalties.
+                    if not available and not found_in_local_filesystem():
+                        click.echo(f"\nFailed to reach pack {pack['id']} version {pack['version']}")
+                        sys.exit(1)
+                    click.echo(".", nl=False)
+                    found_diff = True
+            if not found_diff:
+                click.echo("- no diff from installed versions found in manifest.")
+            else:
+                print()
+
+        click.echo("Manifest is valid JSON and all packs are reachable.")
+        return
+    else:
+        msg = "Invalid value for --mode detected. This should never happen"
+        raise RuntimeError(msg)
+
+
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.argument("manifest", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def diff(ctx: click.Context, manifest: str, environment: str | None) -> None:
+    """Prints out the differences (if any) between what is defined in the xsoar_config.json manifest and what is actually
+    installed on the XSOAR server."""
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    manifest_data = load_manifest(manifest)
+    installed_packs = xsoar_client.get_installed_packs()
+    all_good = True
+    for key in manifest_data:
+        for pack in manifest_data[key]:
+            installed = next((item for item in installed_packs if item["id"] == pack["id"]), {})
+            if not installed:
+                click.echo(f"Pack {pack['id']} is not installed")
+                all_good = False
+            elif installed["currentVersion"] != pack["version"]:
+                msg = f"Manifest states {pack['id']} version {pack['version']} but version {installed['currentVersion']} is installed"
+                click.echo(msg)
+                all_good = False
+    if all_good:
+        click.echo("All packs up to date.")
+
+
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.option("--verbose", is_flag=True, default=False)
+@click.option("--yes", is_flag=True, default=False)
+@click.command()
+@click.argument("manifest", type=str)
+@click.pass_context
+@load_config
+def deploy(ctx: click.Context, environment: str | None, manifest: str, verbose: bool, yes: bool) -> None:  # noqa: FBT001
+    """
+    Deploys content packs to the XSOAR server as defined in the xsoar_config.json manifest.
+    The PATH argument expects the full or relative path to xsoar_config.json
+
+    \b
+    Prompts for confirmation prior to pack installation.
+    """
+    should_continue = True
+    if not yes:
+        should_continue = click.confirm(
+            f"WARNING: this operation will attempt to deploy all packs defined in the manifest to XSOAR {environment} environment. Continue?",
+        )
+    if not should_continue:
+        ctx.exit()
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    manifest_data = load_manifest(manifest)
+    click.echo("Fetching installed packs...", err=True)
+    installed_packs = xsoar_client.get_installed_packs()
+    click.echo("done.")
+    none_installed = True
+    for key in manifest_data:
+        custom = key == "custom_packs"
+        for pack in manifest_data[key]:
+            installed = next((item for item in installed_packs if item["id"] == pack["id"]), {})
+            if not installed or installed["currentVersion"] != pack["version"]:
+                # Install pack
+                click.echo(f"Installing {pack['id']} version {pack['version']}...", nl=False)
+                xsoar_client.deploy_pack(pack_id=pack["id"], pack_version=pack["version"], custom=custom)
+                click.echo("OK.")
+                none_installed = False
+            elif verbose:
+                click.echo(f"Not installing {pack['id']} version {pack['version']}. Already installed.")
+                # Print message that install is skipped
+
+    if none_installed:
+        click.echo("No packs to install. All packs and versions in manifest is already installed on XSOAR server.")
+
+
+manifest.add_command(deploy)
+manifest.add_command(diff)
+manifest.add_command(update)
+manifest.add_command(validate)
+manifest.add_command(generate)

xsoar_cli/pack/README.md

@@ -0,0 +1,36 @@
+# Pack
+
+Content pack management commands for XSOAR.
+
+## Delete
+
+Delete a content pack from the XSOAR server. Verifies the pack is installed before attempting deletion.
+
+**Syntax:** `xsoar-cli pack delete [OPTIONS] PACK_ID`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Arguments:**
+- `PACK_ID` - The ID of the content pack to delete
+
+**Examples:**
+```
+xsoar-cli pack delete MyCustomPack
+xsoar-cli pack delete --environment prod CommonScripts
+```
+
+## Get Outdated
+
+Display a list of outdated content packs showing current and latest available versions in table format.
+
+**Syntax:** `xsoar-cli pack get-outdated [OPTIONS]`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Examples:**
+```
+xsoar-cli pack get-outdated
+xsoar-cli pack get-outdated --environment staging
+```

xsoar_cli/pack/commands.py

@@ -0,0 +1,59 @@
+import sys
+from typing import TYPE_CHECKING
+
+import click
+
+from xsoar_cli.utilities import load_config
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+
+@click.group()
+@click.pass_context
+def pack(ctx: click.Context) -> None:
+    """Various content pack related commands."""
+
+
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.command()
+@click.argument("pack_id", type=str)
+@click.pass_context
+@load_config
+def delete(ctx: click.Context, environment: str | None, pack_id: str) -> None:
+    """Deletes a content pack from the XSOAR server."""
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    if not xsoar_client.is_installed(pack_id=pack_id):
+        click.echo(f"Pack ID {pack_id} is not installed. Cannot delete.")
+        sys.exit(1)
+    xsoar_client.delete(pack_id=pack_id)
+    click.echo(f"Deleted pack {pack_id} from XSOAR {environment}")
+
+
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.command()
+@click.pass_context
+@load_config
+def get_outdated(ctx: click.Context, environment: str | None) -> None:
+    """Prints out a list of outdated content packs."""
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    click.echo("Fetching outdated packs. This may take a little while...", err=True)
+    outdated_packs = xsoar_client.get_outdated_packs()
+    if not outdated_packs:
+        click.echo("No outdated packs found")
+        sys.exit(0)
+    id_header = "Pack ID"
+    installed_header = "Installed version"
+    latest_header = "Latest version"
+    click.echo(f"{id_header:<50}{installed_header:>17}{latest_header:>17}")
+    for pack in outdated_packs:
+        msg = f"{pack['id']:<50}{pack['currentVersion']:>17}{pack['latest']:>17}"
+        click.echo(msg)
+
+
+pack.add_command(delete)
+pack.add_command(get_outdated)

xsoar_cli/playbook/README.md

@@ -0,0 +1,43 @@
+# Playbook
+
+Playbook management commands for XSOAR development workflows.
+
+## Download
+
+Download a playbook from XSOAR, format it with demisto-sdk, and re-attach it to the server. Designed for content repository development workflows.
+
+**Syntax:** `xsoar-cli playbook download [OPTIONS] NAME`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Arguments:**
+- `NAME` - The name of the playbook to download
+
+**Examples:**
+```
+xsoar-cli playbook download "My Awesome Playbook"
+xsoar-cli playbook download --environment dev "Security Investigation"
+```
+
+## Requirements
+
+- Must be run from the root of a content repository with proper directory structure
+- Target directory `Packs/<PackID>/Playbooks/` must exist
+- `demisto-sdk` must be installed and available in PATH
+
+## Behavior
+
+1. Downloads the specified playbook from XSOAR
+2. Detects the content pack ID from playbook metadata
+3. Saves to `$(cwd)/Packs/<PackID>/Playbooks/<playbook_name>.yml`
+4. Runs `demisto-sdk format --assume-yes --no-validate --no-graph` on the file
+5. Re-attaches the formatted playbook to XSOAR
+6. Replaces whitespace characters in filenames with underscores
+
+## Limitations
+
+- Only supports playbooks that are already part of a content pack
+- Requires existing content repository directory structure
+- Attempting to download non-existing playbooks results in server errors
+- Does not support completely new playbooks (not yet implemented)

xsoar_cli/playbook/commands.py

@@ -0,0 +1,84 @@
+import pathlib
+import subprocess
+import sys
+from io import StringIO
+from typing import TYPE_CHECKING
+
+import click
+import yaml
+
+from xsoar_cli.utilities import load_config
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+
+@click.group()
+@click.pass_context
+def playbook(ctx: click.Context) -> None:
+    """Download/attach/detach playbooks"""
+
+
+@click.option(
+    "--environment", default=None, help="Default environment set in config file."
+)
+@click.command()
+@click.argument("name", type=str)
+@click.pass_context
+@load_config
+def download(ctx: click.Context, environment: str | None, name: str) -> None:
+    """Download and reattach playbook.
+
+    We try to detect output path to $(cwd)/Packs/<Pack ID>/Playbooks/<name>.yml
+    Whitespace in Pack ID and playbook filename will be replaced with underscores. After the playbook is downloaded,
+    then demisto-sdk format --assume-yes --no-validate --no-graph is done on the downloaded playbook before the item
+    is re-attached in XSOAR.
+    """
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    # Maybe we should search for the playbook before attempting download in
+    # case user specifies a cutsom playbook and not a system playbook
+    try:
+        click.echo("Downloading playbook...", nl=False)
+        playbook = xsoar_client.download_item(item_type="playbook", item_id=name)
+        click.echo("ok.")
+    except Exception as ex:  # noqa: BLE001
+        click.echo(f"FAILED: {ex!s}")
+        sys.exit(1)
+    playbook_bytes_data = StringIO(playbook.decode("utf-8"))
+    playbook_data = yaml.safe_load(playbook_bytes_data)
+    pack_id = playbook_data["contentitemexportablefields"]["contentitemfields"][
+        "packID"
+    ]
+    cwd = pathlib.Path().cwd()
+    target_dir = pathlib.Path(cwd / "Packs" / pack_id / "Playbooks")
+    if not target_dir.is_dir():
+        msg = f"Cannot find target directory: {target_dir}\nMaybe you're not running xsoar-cli from the root of a content repository?"
+        click.echo(msg)
+        sys.exit(1)
+    filepath = pathlib.Path(
+        cwd / "Packs" / pack_id / "Playbooks" / f"{playbook_data['id']}.yml"
+    )
+    filepath = pathlib.Path(str(filepath).replace(" ", "_"))
+    with filepath.open("w") as f:
+        yaml.dump(playbook_data, f, default_flow_style=False)
+    click.echo(f"Written playbook to: {filepath}")
+    click.echo("Running demisto-sdk format on newly downloaded playbook")
+    subprocess.run(
+        [
+            "demisto-sdk",
+            "format",
+            "--assume-yes",
+            "--no-validate",
+            "--no-graph",
+            str(filepath),
+        ],
+        check=False,
+    )  # noqa: S603, S607
+    click.echo("Re-attaching playbook in XSOAR...", nl=False)
+    xsoar_client.attach_item(item_type="playbook", item_id=name)
+    click.echo("done.")
+
+
+playbook.add_command(download)

xsoar_cli/plugins/README.md

@@ -0,0 +1,85 @@
+# XSOAR CLI Plugin System
+
+The XSOAR CLI plugin system allows you to extend the CLI with custom commands. Plugins are Python files placed in `~/.local/xsoar-cli/plugins/` that are automatically discovered and loaded.
+
+## Quick Start
+
+1. **Create the plugins directory**:
+   ```bash
+   mkdir -p ~/.local/xsoar-cli/plugins
+   ```
+
+2. **Create a plugin file** (`~/.local/xsoar-cli/plugins/hello_plugin.py`):
+   ```python
+   import click
+
+   class HelloPlugin(XSOARPlugin):
+       @property
+       def name(self) -> str:
+           return "hello"
+
+       @property
+       def version(self) -> str:
+           return "1.0.0"
+
+       def get_command(self) -> click.Command:
+           @click.command(help="Say hello")
+           @click.option("--name", default="World", help="Name to greet")
+           def hello(name: str):
+               click.echo(f"Hello, {name}!")
+           return hello
+   ```
+
+3. **Use your plugin**:
+   ```bash
+   xsoar-cli hello --name "Alice"
+   ```
+
+## Plugin Structure
+
+A plugin must:
+- Be a Python class that inherits from `XSOARPlugin`
+- Implement the `name`, `version`, and `get_command()` methods
+- The `get_command()` method must return a Click command
+
+### Required Methods
+
+- `name` - Unique identifier for your plugin
+- `version` - Version string
+- `get_command()` - Returns the Click command to register
+
+### Optional Methods
+
+- `description` - Plugin description
+- `initialize()` - Called when plugin loads
+- `cleanup()` - Called when plugin unloads
+
+## Plugin Management
+
+```bash
+# List all plugins
+xsoar-cli plugins list
+
+# Show plugin details
+xsoar-cli plugins info hello
+
+# Validate plugins
+xsoar-cli plugins validate
+
+# Reload a plugin after changes
+xsoar-cli plugins reload hello
+```
+
+## Command Conflicts
+
+Plugin commands cannot use the same names as core CLI commands:
+- `case`, `config`, `graph`, `manifest`, `pack`, `playbook`, `plugins`
+
+If conflicts occur, use a different command name or create a command group.
+
+## Notes
+
+- The `XSOARPlugin` class is automatically available in plugin files
+- Plugin files are discovered automatically from `~/.local/xsoar-cli/plugins/`
+- Plugins are loaded when the CLI starts
+- No special imports are needed for `XSOARPlugin`

xsoar_cli/plugins/__init__.py

@@ -0,0 +1,68 @@
+"""
+XSOAR CLI Plugin System
+
+This module provides the infrastructure for creating and loading plugins
+for the xsoar-cli application. Plugins can extend the CLI with custom
+commands and functionality.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import click
+
+
+class XSOARPlugin(ABC):
+    """
+    Abstract base class for XSOAR CLI plugins.
+
+    All plugins should inherit from this class and implement the required methods.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the plugin name."""
+
+    @property
+    @abstractmethod
+    def version(self) -> str:
+        """Return the plugin version."""
+
+    @property
+    def description(self) -> Optional[str]:
+        """Return an optional description of the plugin."""
+        return None
+
+    @abstractmethod
+    def get_command(self) -> click.Command:
+        """
+        Return the Click command or command group that this plugin provides.
+
+        Returns:
+            click.Command: The command to be registered with the CLI
+        """
+
+    def initialize(self) -> None:
+        """
+        Initialize the plugin. Called once when the plugin is loaded.
+        Override this method if your plugin needs initialization.
+        """
+
+    def cleanup(self) -> None:
+        """
+        Cleanup plugin resources. Called when the application shuts down.
+        Override this method if your plugin needs cleanup.
+        """
+
+
+class PluginError(Exception):
+    """Exception raised when there's an error with plugin loading or execution."""
+
+
+class PluginLoadError(PluginError):
+    """Exception raised when a plugin fails to load."""
+
+
+class PluginRegistrationError(PluginError):
+    """Exception raised when a plugin fails to register."""