Metadata-Version: 2.4
Name: xsoar-cli
Version: 2.0.1
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 :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: azure-identity>=1.25.1
Requires-Dist: azure-storage-blob>=12.28.0
Requires-Dist: boto3>=1.36.17
Requires-Dist: click==8.1.8
Requires-Dist: demisto-py>=3.2.22
Requires-Dist: packaging
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.8.0
Requires-Dist: xsoar-dependency-graph>=0.2.1
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
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](https://docs.astral.sh/uv/) for installation

### Additional Requirements
- **demisto-sdk** - Required by `xsoar-cli playbook download`. Should be installed separately.


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

```bash
uv tool install xsoar-cli
```

Alternatively, using pip:

```bash
pip install xsoar-cli
```

## Upgrading

```bash
uv tool upgrade xsoar-cli
```

Or with pip:

```bash
pip install --upgrade xsoar-cli
```

## Uninstalling

```bash
uv tool uninstall xsoar-cli
```

Or with pip:

```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
```

### 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:

```json
{
    "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
```json
{
    "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 
```json
{
    "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:

```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/commands/case/README.md)** - Retrieve case details and clone cases between environments
- **[content](src/xsoar_cli/commands/content/README.md)** - Inspect and manage content items on your XSOAR server
- **[config](src/xsoar_cli/commands/config/README.md)** - Create, validate, and manage CLI configuration files
- **[graph](src/xsoar_cli/commands/graph/README.md)** - Generate visual dependency graphs for content packs
- **[integration](src/xsoar_cli/commands/integration/README.md)** - Save and load integration instance configuration
- **[manifest](src/xsoar_cli/commands/manifest/README.md)** - Validate and deploy content using declarative manifests
- **[pack](src/xsoar_cli/commands/pack/README.md)** - Manage content pack operations and information
- **[playbook](src/xsoar_cli/commands/playbook/README.md)** - Download playbooks for local editing and development
- **[plugins](src/xsoar_cli/commands/plugins/README.md)** - Extend CLI functionality with custom commands
- **[rbac](src/xsoar_cli/commands/rbac/README.md)** - 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](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.10 or later

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