xsoar-cli 1.0.9__py3-none-any.whl

xsoar_cli/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present Torbjørn Lium <torben@lium.org>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "1.0.9"

xsoar_cli/__init__.py

@@ -0,0 +1 @@
+

xsoar_cli/case/README.md

@@ -0,0 +1,57 @@
+# Case
+
+Various case/incident related commands for XSOAR.
+
+## Get
+
+Retrieve basic information about a single case. Returns raw JSON formatted with 4-space indentation.
+
+**Syntax:** `xsoar-cli case get [OPTIONS] CASENUMBER`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Examples:**
+```
+xsoar-cli case get 312412
+xsoar-cli case get --environment prod 312412
+```
+
+## Clone
+
+Clone a case from one environment to another. Useful for copying production cases to development environment for testing.
+
+**Syntax:** `xsoar-cli case clone [OPTIONS] CASENUMBER`
+
+**Options:**
+- `--source TEXT` - Source environment (default: prod)
+- `--dest TEXT` - Destination environment (default: dev)
+
+**Examples:**
+```
+xsoar-cli case clone 312412                           # Clone from prod to dev (defaults)
+xsoar-cli case clone --source dev --dest prod 312412  # Clone from dev to prod
+```
+
+## Create
+
+Create a new case in XSOAR with optional custom fields and case type.
+
+**Syntax:** `xsoar-cli case create [OPTIONS] [NAME] [DETAILS]`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+- `--casetype TEXT` - Case type (default: uses default case type from config)
+- `--custom-fields TEXT` - Additional fields in format "field1=value1,field2=value2" (useful when XSOAR has mandatory custom case fields configured)
+- `--custom-fields-delimiter TEXT` - Delimiter for custom fields (default: ",")
+
+**Arguments:**
+- `NAME` - Case title (default: "Test case created from xsoar-cli")
+- `DETAILS` - Case description (default: "Placeholder case details")
+
+**Examples:**
+```
+xsoar-cli case create
+xsoar-cli case create "Security Incident" "Suspicious network activity detected"
+xsoar-cli case create --casetype "Phishing" --custom-fields "severity=High,source=Email" "Phishing Email" "Suspicious email received"
+```

xsoar_cli/case/commands.py

@@ -0,0 +1,130 @@
+import json
+from typing import TYPE_CHECKING
+
+import click
+
+from xsoar_cli.utilities import load_config, parse_string_to_dict, validate_environments
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+
+@click.group(help="Add new or modify existing XSOAR case")
+def case() -> None:
+    pass
+
+
+@click.argument("casenumber", type=int)
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.command(help="Get basic information about a single case in XSOAR")
+@click.pass_context
+@load_config
+def get(ctx: click.Context, casenumber: int, environment: str | None) -> None:
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    response = xsoar_client.get_case(casenumber)
+    if response["total"] == 0 and not response["data"]:
+        click.echo(f"Cannot find case ID {casenumber}")
+        ctx.exit(1)
+    click.echo(json.dumps(response, indent=4))
+
+
+@click.argument("casenumber", type=int)
+@click.option("--source", default="prod", show_default=True, help="Source environment")
+@click.option("--dest", default="dev", show_default=True, help="Destination environment")
+@click.option(
+    "--custom-fields",
+    default=None,
+    help='Additional fields on the form "myfield=my_value,anotherfield=another value". Use machine name for field names, e.g mycustomfieldname.',
+)
+@click.option("--custom-fields-delimiter", default=",", help='Delimiter when specifying additional fields. Default is ","')
+@click.command()
+@click.pass_context
+@load_config
+def clone(  # noqa: PLR0913
+    ctx: click.Context,
+    casenumber: int,
+    source: str,
+    dest: str,
+    custom_fields: str | None,
+    custom_fields_delimiter: str,
+) -> None:
+    """Clones a case from source to destination environment."""
+    valid_envs = validate_environments(source, dest, ctx=ctx)
+    if not valid_envs:
+        click.echo(f"Error: cannot find environments {source} and/or {dest} in config")
+        ctx.exit(1)
+    if custom_fields and "=" not in custom_fields:
+        click.echo('Malformed custom fields. Must be on the form "myfield=myvalue"')
+        ctx.exit(1)
+    xsoar_source_client: Client = ctx.obj["server_envs"][source]["xsoar_client"]
+    results = xsoar_source_client.get_case(casenumber)
+    data = results["data"][0]
+    # Dbot mirror info is irrelevant. This will be added again if applicable by XSOAR after ticket creation in dev.
+    data.pop("dbotMirrorId")
+    data.pop("dbotMirrorInstance")
+    data.pop("dbotMirrorDirection")
+    data.pop("dbotDirtyFields")
+    data.pop("dbotCurrentDirtyFields")
+    data.pop("dbotMirrorTags")
+    data.pop("dbotMirrorLastSync")
+    data.pop("id")
+    data.pop("created")
+    data.pop("modified")
+    # Ensure that playbooks run immediately when the case is created
+    data["createInvestigation"] = True
+    if "CustomFields" in data:
+        data["CustomFields"] = data["CustomFields"] | parse_string_to_dict(custom_fields, custom_fields_delimiter)
+
+    xsoar_dest_client: Client = ctx.obj["server_envs"][dest]["xsoar_client"]
+    case_data = xsoar_dest_client.create_case(data=data)
+    click.echo(json.dumps(case_data, indent=4))
+
+
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.option("--casetype", default="", show_default=True, help="Create case of specified type. Default type set in config file.")
+@click.option(
+    "--custom-fields",
+    default=None,
+    help='Additional fields on the form "myfield=my_value,anotherfield=another value". Use machine name for field names, e.g mycustomfieldname.',
+)
+@click.option("--custom-fields-delimiter", default=",", help='Delimiter when specifying additional fields. Default is ","')
+@click.argument("details", type=str, default="Placeholder case details")
+@click.argument("name", type=str, default="Test case created from xsoar-cli")
+@click.command()
+@click.pass_context
+@load_config
+def create(  # noqa: PLR0913
+    ctx: click.Context,
+    environment: str | None,
+    casetype: str,
+    name: str,
+    custom_fields: str | None,
+    custom_fields_delimiter: str,
+    details: str,
+) -> None:
+    """Creates a new case in XSOAR. If invalid case type is specified as a command option, XSOAR will default to using Unclassified."""
+    if custom_fields and "=" not in custom_fields:
+        click.echo('Malformed custom fields. Must be on the form "myfield=myvalue"')
+        ctx.exit(1)
+    if not environment:
+        environment = ctx.obj["default_environment"]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
+    if not casetype:
+        casetype = ctx.obj["default_new_case_type"]
+    data = {
+        "createInvestigation": True,
+        "name": name,
+        "type": casetype,
+        "details": details,
+        "CustomFields": parse_string_to_dict(custom_fields, custom_fields_delimiter),
+    }
+    case_data = xsoar_client.create_case(data=data)
+    case_id = case_data["id"]
+    click.echo(f"Created XSOAR case {case_id}")
+
+
+case.add_command(get)
+case.add_command(clone)
+case.add_command(create)

xsoar_cli/cli.py

@@ -0,0 +1,41 @@
+import logging
+
+import click
+
+from .__about__ import __version__
+from .case import commands as case_commands
+from .config import commands as config_commands
+from .graph import commands as graph_commands
+from .manifest import commands as manifest_commands
+from .pack import commands as pack_commands
+from .playbook import commands as playbook_commands
+from .plugins import commands as plugin_commands
+from .plugins.manager import PluginManager
+
+
+@click.group()
+@click.pass_context
+@click.version_option(__version__)
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+def cli(ctx: click.Context, debug: bool) -> None:
+    """XSOAR CLI - Command line interface for XSOAR operations."""
+    if debug:
+        logging.basicConfig(level=logging.DEBUG)
+
+
+cli.add_command(config_commands.config)
+cli.add_command(case_commands.case)
+cli.add_command(pack_commands.pack)
+cli.add_command(manifest_commands.manifest)
+cli.add_command(playbook_commands.playbook)
+cli.add_command(graph_commands.graph)
+cli.add_command(plugin_commands.plugins)
+
+# Load and register plugins after all core commands are added
+plugin_manager = PluginManager()
+try:
+    plugin_manager.load_all_plugins(ignore_errors=True)
+    plugin_manager.register_plugin_commands(cli)
+except Exception:
+    # Silently ignore plugin loading errors to not break the CLI
+    pass

xsoar_cli/config/README.md

@@ -0,0 +1,64 @@
+# Config
+
+Configuration management commands for XSOAR CLI.
+
+## Create
+
+Create a new configuration file based on a template. If the configuration file already exists, prompts for confirmation to overwrite.
+
+**Syntax:** `xsoar-cli config create`
+
+**Examples:**
+```
+xsoar-cli config create
+```
+
+## Show
+
+Display the current configuration file contents as formatted JSON. API keys are masked by default for security.
+
+**Syntax:** `xsoar-cli config show [OPTIONS]`
+
+**Options:**
+- `--unmask` - Show unmasked API keys in output
+
+**Examples:**
+```
+xsoar-cli config show
+xsoar-cli config show --unmask
+```
+
+## Validate
+
+Validate that the configuration file is properly formatted JSON and test connectivity to each XSOAR environment defined in the configuration.
+
+**Syntax:** `xsoar-cli config validate [OPTIONS]`
+
+**Options:**
+- `--only-test-environment TEXT` - Test connectivity for only the specified environment
+
+**Examples:**
+```
+xsoar-cli config validate
+xsoar-cli config validate --only-test-environment prod
+```
+
+## Set Credentials
+
+Update API credentials for a specific environment in the configuration file. Automatically sets server version based on whether a key ID is provided.
+
+**Syntax:** `xsoar-cli config set-credentials [OPTIONS] APITOKEN`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: dev)
+- `--key_id INTEGER` - API key ID for XSOAR 8 (sets server_version to 8, omit for XSOAR 6)
+
+**Arguments:**
+- `APITOKEN` - The API token to set for the environment
+
+**Examples:**
+```
+xsoar-cli config set-credentials your-api-token-here
+xsoar-cli config set-credentials --environment prod your-api-token-here
+xsoar-cli config set-credentials --environment prod --key_id 123 your-api-token-here
+```

xsoar_cli/config/commands.py

@@ -0,0 +1,112 @@
+import json
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+import contextlib
+
+from xsoar_cli.utilities import (
+    get_config_file_contents,
+    get_config_file_path,
+    get_config_file_template_contents,
+    load_config,
+)
+
+
+@click.group(help="Create/validate etc")
+def config() -> None:
+    pass
+
+
+@click.command()
+@click.option("--unmask", "masked", is_flag=True, default=False)
+@click.pass_context
+@load_config
+def show(ctx: click.Context, masked: bool) -> None:
+    """Prints out current config. API keys are masked."""
+    config_file = get_config_file_path()
+    config = get_config_file_contents(config_file)
+    if not masked:
+        for key in config["server_config"]:
+            config["server_config"][key]["api_token"] = "MASKED"  # noqa: S105
+            if "azure_storage_access_token" in config["server_config"][key]:
+                config["server_config"][key]["azure_storage_access_token"] = "*****"  # noqa: S105
+
+    print(json.dumps(config, indent=4))
+    ctx.exit()
+
+
+@click.command()
+@click.option("--only-test-environment", default=None, show_default=True, help="Environment as defined in config file")
+@click.option("--stacktrace", is_flag=True, default=False, help="Print full stack trace on config validation failure.")
+@click.pass_context
+@load_config
+def validate(ctx: click.Context, only_test_environment: str, stacktrace: bool) -> None:
+    """Validates that the configuration file is JSON and tests connectivity for each XSOAR Client environment defined."""
+    return_code = 0
+    for server_env in ctx.obj["server_envs"]:
+        if only_test_environment and server_env != only_test_environment:
+            # Ignore environment if --only-test-environment option is given and environment does not match
+            # what the user specified in option
+            continue
+        click.echo(f'Testing "{server_env}" environment...', nl=False)
+        xsoar_client: Client = ctx.obj["server_envs"][server_env]["xsoar_client"]
+        try:
+            xsoar_client.test_connectivity()
+        except ConnectionError as ex:
+            if stacktrace:
+                raise ConnectionError from ex
+            click.echo("FAILED")
+            return_code = 1
+            continue
+        click.echo("OK")
+    if ctx.obj["default_environment"] not in ctx.obj["server_envs"]:
+        click.echo(f'Error: default environment "{ctx.obj["default_environment"]}" not found in server config.')
+        return_code = 1
+    ctx.exit(return_code)
+
+
+@click.command()
+def create() -> None:
+    """Create a new configuration file based on a template."""
+    # if confdir does not exist, create it
+    # if conf file does not exist, create it
+    config_file = get_config_file_path()
+    if config_file.is_file():
+        click.confirm(f"WARNING: {config_file} already exists. Overwrite?", abort=True)
+    config_file.parent.mkdir(exist_ok=True, parents=True)
+    config_data = get_config_file_template_contents()
+    config_file.write_text(json.dumps(config_data, indent=4))
+    click.echo(f"Wrote template configuration file {config_file}")
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.option("--key_id", type=int, help="If set then server config for server_version will be set to 8.")
+@click.argument("apitoken", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def set_credentials(ctx: click.Context, environment: str, apitoken: str, key_id: int) -> None:  # noqa: ARG001
+    """Set individual credentials for an environment in the config file."""
+    config_file = get_config_file_path()
+    config_data = json.loads(config_file.read_text())
+    config_data["server_config"][environment]["api_token"] = apitoken
+    # If we are given an API key ID, then we know it's supposed to be used in XSOAR 8.
+    # Set or remove the xsiam_auth_id accordingly.
+    if key_id:
+        config_data["server_config"][environment]["xsiam_auth_id"] = key_id
+        config_data["server_config"][environment]["server_version"] = 8
+    else:
+        config_data["server_config"][environment]["server_version"] = 6
+        with contextlib.suppress(KeyError):
+            config_data["server_config"][environment].pop("xsiam_auth_id")
+    config_file.write_text(json.dumps(config_data, indent=4))
+
+
+config.add_command(create)
+config.add_command(validate)
+config.add_command(show)
+config.add_command(set_credentials)

xsoar_cli/graph/README.md

@@ -0,0 +1,17 @@
+# Graph
+BETA command. Under active development.
+
+## Generate
+Creates a graph representation of the entire content repository and plots connected components. The syntax is `xsoar-cli graph generate [OPTIONS] [PACKS]...`
+where the only required option is the path to the content repository. An optional PACKS argument can be specified with the paths of one or more content packs
+you want to be plotted.
+
+### Example invocations
+```
+# Plot the connected components from the graph of the entire content repository
+xsoar-cli graph generate -rp ./content_repo
+# Plot only the components found in MyFirstPack
+xsoar-cli graph generate -rp ./content_repo ./content_repo/Packs/MyFirstPack
+# Plot only connected components from MyFirstPack and MySecondPack
+xsoar-cli graph generate -rp ./content_repo ./content_repo/Packs/MyFirstPack ./content_repo/Packs/MySecondPack
+```

xsoar_cli/graph/commands.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import click
+from xsoar_dependency_graph.xsoar_dependency_graph import ContentGraph
+
+
+@click.group(help="(BETA) Create dependency graphs from one or more content packs")
+def graph() -> None:
+    pass
+
+
+@click.option("-rp", "--repo-path", required=True, type=click.Path(exists=True), help="Path to content repository")
+@click.argument("packs", nargs=-1, required=False, type=click.Path(exists=True))
+@click.command()
+def generate(packs: tuple[Path], repo_path: Path) -> None:
+    """BETA
+
+    Generates a XSOAR dependency graph for one or more content packs. If no packs are defined in the [PACKS] argument,
+    a dependency graph is created for all content packs in the content repository.
+
+    Usage examples:
+
+    xsoar-cli graph generate -rp . Packs/Pack_one Packs/Pack_two
+
+    xsoar-cli graph generate -rp ."""
+    cg: ContentGraph = ContentGraph(repo_path=Path(repo_path))
+    packs_list = [Path(item) for item in packs]
+    cg.create_content_graph(pack_paths=packs_list)
+    cg.plot_connected_components()
+
+
+graph.add_command(generate)

xsoar_cli/manifest/README.md

@@ -0,0 +1,122 @@
+# Manifest
+
+Content pack deployment management commands using a declarative configuration file (`xsoar_config.json`).
+
+## Generate
+
+Generate a new manifest file from currently installed content packs. Assumes all packs are marketplace packs (no custom packs).
+
+**Syntax:** `xsoar-cli manifest generate [OPTIONS] MANIFEST_PATH`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Arguments:**
+- `MANIFEST_PATH` - Path where the new manifest file will be created
+
+**Examples:**
+```
+xsoar-cli manifest generate ./xsoar_config.json
+xsoar-cli manifest generate --environment prod ./xsoar_config.json
+```
+
+## Validate
+
+Validate manifest JSON syntax and verify all specified content packs are available. Tests connectivity to pack sources and checks local pack metadata for development packs.
+
+**Syntax:** `xsoar-cli manifest validate [OPTIONS] MANIFEST_PATH`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Arguments:**
+- `MANIFEST_PATH` - Path to the manifest file to validate
+
+**Examples:**
+```
+xsoar-cli manifest validate ./xsoar_config.json
+xsoar-cli manifest validate --environment staging ./xsoar_config.json
+```
+
+## Update
+
+Compare installed packs against available versions and update the manifest file with latest versions. Prompts for confirmation on each upgrade.
+
+**Syntax:** `xsoar-cli manifest update [OPTIONS] MANIFEST_PATH`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Arguments:**
+- `MANIFEST_PATH` - Path to the manifest file to update
+
+**Examples:**
+```
+xsoar-cli manifest update ./xsoar_config.json
+xsoar-cli manifest update --environment dev ./xsoar_config.json
+```
+
+## Diff
+
+Compare the manifest definition against what is actually installed on the XSOAR server. Shows packs that are missing or have version mismatches.
+
+**Syntax:** `xsoar-cli manifest diff [OPTIONS] MANIFEST_PATH`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Arguments:**
+- `MANIFEST_PATH` - Path to the manifest file to compare
+
+**Examples:**
+```
+xsoar-cli manifest diff ./xsoar_config.json
+xsoar-cli manifest diff --environment prod ./xsoar_config.json
+```
+
+## Deploy
+
+Install or update content packs on the XSOAR server according to the manifest. Only deploys packs that differ from current installation.
+
+**Syntax:** `xsoar-cli manifest deploy [OPTIONS] MANIFEST_PATH`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+- `--verbose` - Show detailed information about skipped packs
+- `--yes` - Skip confirmation prompt
+
+**Arguments:**
+- `MANIFEST_PATH` - Path to the manifest file to deploy
+
+**Examples:**
+```
+xsoar-cli manifest deploy ./xsoar_config.json
+xsoar-cli manifest deploy --environment prod --yes ./xsoar_config.json
+xsoar-cli manifest deploy --verbose ./xsoar_config.json
+```
+
+## Manifest File Structure
+
+The `xsoar_config.json` file defines content packs to be installed:
+
+```json
+{
+    "custom_packs": [
+        {
+            "id": "MyCustomPack",
+            "version": "1.0.0",
+            "_comment": "Optional documentation comment"
+        }
+    ],
+    "marketplace_packs": [
+        {
+            "id": "CommonScripts",
+            "version": "1.20.0"
+        }
+    ]
+}
+```
+
+- **custom_packs**: Organization-developed packs stored in artifact repositories
+- **marketplace_packs**: Official Palo Alto Networks content packs
+- **_comment**: Optional field for documentation (preserved during updates)