xsoar-cli

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
• 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.

Pull Requests are very welcome and appreciated! See CONTRIBUTING.md for guidelines.

Quick Start

# Install
uv tool 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 expect a certain directory structure to be available from your current working directory.

Requirements

Core Requirements

• XSOAR servers version 6 or 8
• Python 3.10+ (tested with Python 3.10-3.14, earlier versions may work but are untested)
• uv for installation

Installation

Installing xsoar-cli as a uv tool is recommended. This gives it an isolated environment with its own dependencies, avoiding version conflicts with other Python tools such as demisto-sdk.

uv tool install xsoar-cli

Alternatively, using pip:

pip install xsoar-cli

Upgrading

uv tool upgrade xsoar-cli

Or with pip:

pip install --upgrade xsoar-cli

Uninstalling

uv tool uninstall xsoar-cli

Or with pip:

pip uninstall xsoar-cli

Shell Completion

xsoar-cli supports tab completion for Bash, Zsh, and Fish. Completion covers commands, subcommands, and options.

The easiest way to set up completions is with the built-in command:

xsoar-cli completions install

This auto-detects your shell and writes the completion script to the appropriate location. Use --shell to specify a shell explicitly. For Zsh, Oh My Zsh is detected automatically.

To remove completions:

xsoar-cli completions uninstall

Regenerate completions after upgrading xsoar-cli by running xsoar-cli completions install again.

For manual setup or details, see the completions command documentation.

Configuration

The xsoar-cli config file is located in ~/.config/xsoar-cli/config.json. To create a configuration file from template, please run:

xsoar-cli config create

Sample configuration file using AWS S3 as artifacts repository for custom content packs

After creating the config file, edit it with your XSOAR server details:

{
    "default_environment": "xsoar6",
    "default_new_case_type": "My case type",
    "log_level": "INFO",
    "custom_pack_authors": ["My_Org"],
    "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
        },
    }
}

Sample configuration file using Azure BlobStorage as artifacts repository for custom content packs

{
    "default_environment": "xsoar8",
    "default_new_case_type": "My case type",
    "custom_pack_authors": ["My_Org"],
    "server_config": {
        "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",
            "azure_storage_access_token": "my-access-token",
            "verify_ssl": false,
            "server_version": 8,
            "xsiam_auth_id": 123
        }
    }
}

Full configuration file with multiple environments

{
    "default_environment": "dev",
    "default_new_case_type": "My case type",
    "custom_pack_authors": ["My_Org"],
    "log_level": "DEBUG",
    "server_config": {
        "dev": {
            "base_url": "https://your.dev.domain",
            "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://your.prod.domain",
            "api_token": "YOUR API TOKEN HERE",
            "artifacts_location": "S3",
            "s3_bucket_name": "xsoar-cicd",
            "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.

• skip_version_check: Set to false to check PyPI for newer versions of xsoar-cli on each invocation. Defaults to true (no check). The check is also skipped for editable and non-index installs.

• 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). Set this to an empty string to use xsoar-cli without an artifacts repository.
  • 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" artifacts location)
  • azure_container_name Name of the container where blobs should be stored (only applicable if using "Azure" artifacts 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:

xsoar-cli config validate

This will verify connectivity to all configured XSOAR environments.

Usage

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 - Retrieve case details and clone cases between environments
• completions - Install and manage shell completion
• content - Inspect and manage content items on your XSOAR server
• config - Create, validate, and manage CLI configuration files
• graph - Generate visual dependency graphs for content packs
• integration - Save and load integration instance configuration
• manifest - Validate and deploy content using declarative manifests
• pack - Manage content pack operations and information
• plugins - Extend CLI functionality with custom commands
• rbac - Dump roles, users and user groups from XSOAR

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.

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.10 or later

Contributing

We welcome all contributions! Please see CONTRIBUTING.md for detailed guidelines on how to contribute to this project.

License

xsoar-cli is distributed under the terms of the MIT license.