xsoar-cli 1.0.9__py3-none-any.whl

xsoar_cli/utilities.py

@@ -0,0 +1,159 @@
+import contextlib
+import json
+from collections.abc import Callable
+from functools import update_wrapper
+from pathlib import Path
+
+import click
+from xsoar_client.artifact_providers.azure import AzureArtifactProvider
+from xsoar_client.artifact_providers.s3 import S3ArtifactProvider
+from xsoar_client.config import ClientConfig
+from xsoar_client.xsoar_client import Client
+
+
+def parse_string_to_dict(input_string: str | None, delimiter: str) -> dict:
+    if not input_string:
+        return {}
+    # Parse a string into a python dictionary
+    pairs = [pair.split("=", 1) for pair in input_string.split(delimiter)]
+    # Filter pairs that have exactly 2 parts (key and value) after splitting by "="
+    valid_pairs = [pair for pair in pairs if len(pair) == 2]  # noqa: PLR2004
+    return {key.strip(): value.strip() for key, value in valid_pairs}
+
+
+def get_config_file_template_contents() -> dict:
+    return {
+        "default_environment": "dev",
+        "default_new_case_type": "",
+        "custom_pack_authors": ["SOMEONE"],
+        "server_config": {
+            "dev": {
+                "base_url": "https://xsoar.example.com",
+                "api_token": "YOUR API TOKEN HERE",
+                "artifacts_location": "S3",
+                "s3_bucket_name": "xsoar-cicd",
+                "verify_ssl": "/path/to/your/CA_bundle.pem",
+                "server_version": 6,
+            },
+            "prod": {
+                "base_url": "https://api-xsoar-v8.example.com",
+                "api_token": "YOUR API TOKEN HERE",
+                "artifacts_location": "S3",
+                "s3_bucket_name": "xsoar-cicd-prod",
+                "verify_ssl": False,
+                "server_version": 8,
+                "xsiam_auth_id": 123,
+            },
+        },
+    }
+
+
+def validate_environments(*args, **kwargs) -> bool:  # noqa: ANN002, ANN003
+    return all(env in kwargs["ctx"].obj["server_envs"] for env in args)
+
+
+def get_config_file_path() -> Path:
+    homedir = Path.home()
+    config_file_path = homedir / ".config/xsoar-cli"
+    config_file_name = "config.json"
+    return Path(config_file_path / config_file_name)
+
+
+def get_config_file_contents(filepath: Path):  # noqa: ANN201
+    return json.load(filepath.open("r"))
+
+
+def load_config(f: Callable) -> Callable:
+    """
+    This function is only to be used as a decorator for various xsoar-cli subcommands. Loads and parses the config file if
+    exists, or prompts the user to create one otherwise.
+    If an illegal environment is provided by the user, i.e by invoking "xsoar-cli command --environment illegal subcommand",
+    then prints out helpful error message and returns non-zero exit value.
+    """
+
+    @click.pass_context
+    def wrapper(ctx: click.Context, *args, **kwargs) -> Callable:  # noqa: ANN002, ANN003
+        config_file_path = get_config_file_path()
+        if not config_file_path.is_file():
+            click.echo(
+                'Config file not found. Please create a template config file using "xsoar-cli config create" and replace placeholder values before retrying.',
+            )
+            ctx.exit(1)
+        config = get_config_file_contents(config_file_path)
+        parse_config(config, ctx)
+        if (
+            "environment" in ctx.params
+            and ctx.params["environment"] not in ctx.obj["server_envs"]
+            and ctx.params["environment"] is not None
+        ):
+            click.echo(f"Invalid environment: {ctx.params['environment']}")
+            click.echo(f"Available environments as defined in config file are: {list(ctx.obj['server_envs'])}")
+            ctx.exit(1)
+        return ctx.invoke(f, *args, **kwargs)
+
+    return update_wrapper(wrapper, f)
+
+
+def fail_if_no_artifacts_provider(f: Callable) -> Callable:
+    """
+    This function is only to be used as a decorator for various xsoar-cli subcommands, and only AFTER the load_config decorator has been called.
+    The intention is to fail gracefully if any subcommand is executed which requires an artifacts provider."
+    """
+
+    @click.pass_context
+    def wrapper(ctx: click.Context, *args, **kwargs) -> Callable:  # noqa: ANN002, ANN003
+        if "environment" in ctx.params:  # noqa: SIM108
+            key = ctx.params["environment"]
+        else:
+            key = ctx.obj["default_environment"]
+
+        with contextlib.suppress(KeyError):
+            location = ctx.obj["server_envs"][key].get("artifacts_location", None)
+            if not location:
+                click.echo("Command requires artifacts repository, but no artifacts_location defined in config.")
+                ctx.exit(1)
+        return ctx.invoke(f, *args, **kwargs)
+
+    return update_wrapper(wrapper, f)
+
+
+def parse_config(config: dict, ctx: click.Context) -> None:
+    # Set the two XSOAR client objects in Click Context for use in later functions
+    ctx.obj = {}
+    ctx.obj["default_environment"] = config["default_environment"]
+    ctx.obj["custom_pack_authors"] = config["custom_pack_authors"]
+    ctx.obj["default_new_case_type"] = config["default_new_case_type"]
+    ctx.obj["server_envs"] = {}
+    for key in config["server_config"]:
+        ctx.obj["server_envs"][key] = {}
+        server_version = config["server_config"][key]["server_version"]
+        custom_pack_authors = config["custom_pack_authors"]
+
+        server_url = config["server_config"][key]["base_url"]
+        api_token = config["server_config"][key]["api_token"]
+        verify_ssl = config["server_config"][key]["verify_ssl"]
+        xsiam_auth_id = config["server_config"][key].get("xsiam_auth_id", "")
+
+        xsoar_client_config = ClientConfig(
+            server_version=server_version,
+            custom_pack_authors=custom_pack_authors,
+            api_token=api_token,
+            server_url=server_url,
+            xsiam_auth_id=xsiam_auth_id,
+            verify_ssl=verify_ssl,
+        )
+
+        artifacts_location = config["server_config"][key].get("artifacts_location", None)
+        if artifacts_location == "S3":
+            bucket_name = config["server_config"][key].get("s3_bucket_name", None)
+            artifact_provider = S3ArtifactProvider(bucket_name=bucket_name)
+        elif artifacts_location == "Azure":
+            url = config["server_config"][key]["azure_blobstore_url"]
+            container_name = config["server_config"][key]["azure_container_name"]
+            access_token = config["server_config"][key].get("azure_storage_access_token", "")
+            artifact_provider = AzureArtifactProvider(storage_account_url=url, container_name=container_name, access_token=access_token)
+        else:
+            artifact_provider = None
+        xsoar_client = Client(config=xsoar_client_config, artifact_provider=artifact_provider)
+
+        ctx.obj["server_envs"][key]["xsoar_client"] = xsoar_client

xsoar_cli-1.0.9.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: xsoar-cli
+Version: 1.0.9
+Project-URL: Documentation, https://github.com/tlium/xsoar-cli#readme
+Project-URL: Issues, https://github.com/tlium/xsoar-cli/issues
+Project-URL: Source, https://github.com/tlium/xsoar-cli
+Author-email: Torbjørn Lium <torben@lium.org>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: <3.13,>=3.10
+Requires-Dist: click==8.1.8
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: xsoar-client>=2.0.0
+Requires-Dist: xsoar-dependency-graph>=0.0.3
+Description-Content-Type: text/markdown
+
+# xsoar-cli
+
+![PyPI - Version](https://img.shields.io/pypi/v/xsoar-cli) [![Python](https://img.shields.io/pypi/pyversions/xsoar-cli.svg)](https://pypi.org/project/xsoar-cli/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A command-line interface for managing Palo Alto Networks XSOAR (Cortex XSOAR) that streamlines content development and deployment workflows.
+
+**Key Features:**
+- **Content Management**: Validate and deploy content packs with declarative manifests
+- **Case Operations**: Retrieve case details and clone cases between environments
+- **Playbook Development**: Download playbooks for local editing and testing
+- **Dependency Analysis**: Generate visual graphs of content pack dependencies
+- **Plugin System**: Extend functionality with custom commands
+
+Perfect for DevOps teams using CI/CD pipelines to manage XSOAR content stored in [content repositories](https://github.com/demisto/content-ci-cd-template).
+
+Pull Requests are very welcome and appreciated! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Quick Start
+
+```bash
+# Install
+pip install xsoar-cli
+
+# Create configuration file
+xsoar-cli config create
+
+# Validate and deploy your content
+xsoar-cli manifest validate ./xsoar_config.json
+xsoar-cli manifest deploy ./xsoar_config.json
+
+# Get help on available commands
+xsoar-cli --help
+```
+
+## Important Notes
+
+This CLI tool is made to be run from the root of a content repository. Some commands depend on files located in your content repository or expects a certain directory structure to be available from your currently working directory.
+
+## Requirements
+
+### Core Requirements
+- XSOAR servers version 6 or 8
+- Python 3.9+ (only tested with Python 3.12, earlier versions may work but are not guaranteed)
+
+### Additional Requirements 
+- **AWS SDK for Python (Boto3)** - Only required when working with custom content packs stored in S3.
+- **Azure SDK for Python**
+
+
+## Installation
+
+```bash
+pip install xsoar-cli
+```
+
+## Upgrading
+
+```bash
+pip install --upgrade xsoar-cli
+```
+
+## Uninstalling
+
+```bash
+pip uninstall xsoar-cli
+```
+
+## Configuration
+
+The xsoar-cli config file is located in `~/.config/xsoar-cli/config.json`. To create a configuration file from template, please run:
+
+```bash
+xsoar-cli config create
+```
+
+### Configuration File Structure
+
+After creating the config file, edit it with your XSOAR server details:
+
+```json
+{
+    "default_environment": "xsoar6",
+    "default_new_case_type": "",
+    "custom_pack_authors": ["SOMEONE"],
+    "server_config": {
+        "xsoar6": {
+            "base_url": "https://xsoar-v6.example.com",
+            "api_token": "YOUR API TOKEN HERE",
+            "artifacts_location": "S3",
+            "s3_bucket_name": "xsoar-cicd",
+            "verify_ssl": "/path/to/your/CA_bundle.pem",
+            "server_version": 6
+        },
+        "xsoar8": {
+            "base_url": "https://xsoar-v8.example.com",
+            "api_token": "YOUR API TOKEN HERE",
+            "artifacts_location": "Azure",
+            "azure_blobstore_url": "https://some/url",
+            "azure_container_name": "some-container-name",
+            "verify_ssl": false,
+            "server_version": 8,
+            "xsiam_auth_id": 123
+        }
+    }
+}
+```
+
+### Configuration Options
+
+- **default_environment**: Which environment to use by default (e.g., "xsoar6")
+- **default_new_case_type**: Default case type when creating new cases
+- **custom_pack_authors**: List of author names used in your custom content packs. This helps xsoar-cli distinguish between your custom packs and marketplace packs. Use the same values you have in `pack_metadata.json` files.
+
+- **server_config**: Define multiple XSOAR environments (xsoar6, xsoar8, etc.)
+  - **base_url**: Your XSOAR server URL
+  - **api_token**: API token for authentication (see XSOAR documentation for creating API keys)
+  - **artifacts_location**: Where artifacts are stored ("Azure" and "S3" is currently supported)
+  - **s3_bucket_name**: S3 bucket where your custom content packs are stored (only applicable if using "S3" artifacts location)
+  - **azure_blobstore_url** URL to your Azure BlobStore location (only applicable if using "Azure" artifats location)
+  - **azure_container_name** Name of the container where blobs should be stored (only applicable if using "Azure" artifats location)
+  - **verify_ssl**: SSL certificate verification - use `false` for self-signed certificates, or path to CA bundle
+  - **server_version**: XSOAR server version (6 or 8)
+  - **xsiam_auth_id**: Required for XSOAR 8 (XSIAM) - the authentication ID for API access
+
+### Validation
+
+Test your configuration with:
+
+```bash
+xsoar-cli config validate
+```
+
+This will verify connectivity to all configured XSOAR environments.
+
+## Usage
+
+```bash
+xsoar-cli <command> <sub-command> <args>
+```
+
+For information about available commands, run `xsoar-cli` without arguments.
+
+For more information on a specific command execute `xsoar-cli <command> --help`.
+
+### Commands
+
+- **[case](src/xsoar_cli/case/README.md)** - Retrieve case details and clone cases between environments
+- **[config](src/xsoar_cli/config/README.md)** - Create, validate, and manage CLI configuration files
+- **[graph](src/xsoar_cli/graph/README.md)** - Generate visual dependency graphs for content packs
+- **[manifest](src/xsoar_cli/manifest/README.md)** - Validate and deploy content using declarative manifests
+- **[pack](src/xsoar_cli/pack/README.md)** - Manage content pack operations and information
+- **[playbook](src/xsoar_cli/playbook/README.md)** - Download playbooks for local editing and development
+- **[plugins](src/xsoar_cli/plugins/README.md)** - Extend CLI functionality with custom commands
+
+## Plugin System
+
+xsoar-cli supports a plugin system that allows you to extend the CLI with custom commands. For complete documentation, examples, and usage instructions, see [Plugin System Documentation](src/xsoar_cli/plugins/README.md).
+
+## Troubleshooting
+
+### Common Issues
+
+**"Config file not found"**
+- Run `xsoar-cli config create` to generate a template configuration file
+- Ensure the file exists at `~/.config/xsoar-cli/config.json`
+
+**"Failed to reach pack" or connection errors**
+- Verify your XSOAR server URL and API token in the config file
+- Check network connectivity to your XSOAR server
+- For custom packs: Ensure AWS credentials are configured and S3 bucket is accessible
+
+**"Invalid environment"**
+- Check that the environment name matches exactly what's defined in your config file
+- Use `xsoar-cli config validate` to verify your configuration
+
+**Python compatibility issues**
+- Ensure you're using Python 3.9 or later
+- Consider using Python 3.12 for best compatibility
+
+## Contributing
+
+We welcome all contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute to this project.
+
+## License
+
+`xsoar-cli` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

xsoar_cli-1.0.9.dist-info/RECORD

@@ -0,0 +1,31 @@
+xsoar_cli/__about__.py,sha256=cTSznV8o6zwE_gWFgbw2V8Fv6kDBG0hajt9f9FHdlzw,127
+xsoar_cli/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+xsoar_cli/cli.py,sha256=iAlSeZe2iR6ciTVrJYLt-CDZk7b5I-hzHFXbYoXhupA,1342
+xsoar_cli/utilities.py,sha256=fQGRD_FfltMuH282-61A_tIv_CdGxq3XPNK5eHLr110,6779
+xsoar_cli/case/README.md,sha256=Qpf-HUdkboYoHU5GDkQG1EsQpX2wF7LKsW0CKxmqG1M,1903
+xsoar_cli/case/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsoar_cli/case/commands.py,sha256=06UEPoSKutrBtAIbgpp_g6YzYXW2N9zx_KtRi16nPlg,5135
+xsoar_cli/config/README.md,sha256=v8xvmuTV-goDRDn48Ko7VG6YZRy89KajBsGx38Jfj_I,1718
+xsoar_cli/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsoar_cli/config/commands.py,sha256=6geg5FWufdKfv8mjZ9WYnhLu7ESv5ew7MYHcEg8y1aM,4476
+xsoar_cli/graph/README.md,sha256=kyWIGs2Sd-OdqAaCWJjyvGpAhXhFcuqQwVqFBgzgWzk,861
+xsoar_cli/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsoar_cli/graph/commands.py,sha256=LKOpUu8r6KThJ5HdyjZlhpwLKRgMcEu7btBOQXwDkMs,1069
+xsoar_cli/manifest/README.md,sha256=HfdhHlpyJFIm9fC37YaWAwXlG9arhGwpQf2aWO5OewY,3607
+xsoar_cli/manifest/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsoar_cli/manifest/commands.py,sha256=XF_IyfyDTSaXE8FXayec1l5a3Bim-Au67T5UeBuF1W4,12048
+xsoar_cli/pack/README.md,sha256=YYVBjxGT4aCQAu1CE16Yo5AnjdL_uh6T9bpAD2eSpl8,891
+xsoar_cli/pack/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsoar_cli/pack/commands.py,sha256=1vGF8_mMemZt75qCBTau_M3dihSr79vc2vea8xr5h_Y,2063
+xsoar_cli/playbook/README.md,sha256=00ohD9gH_Dt4vWlnPGJIpl_GwVHb274Xao8fR9SHAVc,1474
+xsoar_cli/playbook/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xsoar_cli/playbook/commands.py,sha256=nauCczvYvDsb2d2Wd71zADos-7vvSism6p2bDkgRJ5o,2950
+xsoar_cli/plugins/README.md,sha256=MHeEEqg9QWfAql2n1iX90DJpbz4j1G2_4mWb80vVQac,2209
+xsoar_cli/plugins/__init__.py,sha256=81IZsMbZsqrLdB6TjA9t6s3yS8FkuihliBFX4xZUpTo,1753
+xsoar_cli/plugins/commands.py,sha256=UuX-oHpEHZaDWz3JxD79o3vJkJ4jBdxCMAWDXr-5pAE,9513
+xsoar_cli/plugins/manager.py,sha256=qhLEeOmNDLsByRBztsADv2QLQjoBTmWxiKsB9pvy7DU,11024
+xsoar_cli-1.0.9.dist-info/METADATA,sha256=1Fmcz4E70F_k4qEP9U9RHFnE2we8BJqrmJRTw2eEtJ0,8089
+xsoar_cli-1.0.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+xsoar_cli-1.0.9.dist-info/entry_points.txt,sha256=s6Klu4QRekXsmZaBxMyFlE4Q-4_jIA9uijk4qIYUPvE,48
+xsoar_cli-1.0.9.dist-info/licenses/LICENSE.txt,sha256=l6xnqWKshqwwTXt6ayO6MX8Uvygq0YnkUuFTNnR3ba4,1097
+xsoar_cli-1.0.9.dist-info/RECORD,,

xsoar_cli-1.0.9.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

xsoar_cli-1.0.9.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+xsoar-cli = xsoar_cli.cli:cli

xsoar_cli-1.0.9.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025-present Torbjørn Lium <torben@lium.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.