xsoar-cli 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

xsoar_cli/__about__.py

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

xsoar_cli/case/commands.py

@@ -20,7 +20,7 @@ def case() -> None:
 @click.pass_context
 @load_config
 def get(ctx: click.Context, casenumber: int, environment: str) -> None:
-    xsoar_client: Client = ctx.obj["server_envs"][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}")
@@ -40,7 +40,7 @@ def clone(ctx: click.Context, casenumber: int, source: str, dest: str) -> None:
     if not valid_envs:
         click.echo(f"Error: cannot find environments {source} and/or {dest} in config")
         ctx.exit(1)
-    xsoar_source_client: Client = ctx.obj["server_envs"][source]
+    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.
@@ -57,7 +57,7 @@ def clone(ctx: click.Context, casenumber: int, source: str, dest: str) -> None:
     # Ensure that playbooks run immediately when the case is created
     data["createInvestigation"] = True
 
-    xsoar_dest_client: Client = ctx.obj["server_envs"][dest]
+    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))
 
@@ -71,7 +71,7 @@ def clone(ctx: click.Context, casenumber: int, source: str, dest: str) -> None:
 @load_config
 def create(ctx: click.Context, environment: str, casetype: str, name: 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."""
-    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    xsoar_client: Client = ctx.obj["server_envs"][environment]["xsoar_client"]
     if not casetype:
         casetype = ctx.obj["default_new_case_type"]
     data = {

xsoar_cli/config/commands.py

@@ -8,7 +8,13 @@ if TYPE_CHECKING:
 
 import contextlib
 
-from xsoar_cli.utilities import get_config_file_contents, get_config_file_path, get_config_file_template_contents, load_config
+from xsoar_cli.utilities import (
+    fail_if_no_artifacts_provider,
+    get_config_file_contents,
+    get_config_file_path,
+    get_config_file_template_contents,
+    load_config,
+)
 
 
 @click.group(help="Create/validate etc")
@@ -35,6 +41,7 @@ def show(ctx: click.Context, masked: bool) -> None:
 @click.option("--only-test-environment", default=None, show_default=True, help="Environment as defined in config file")
 @click.pass_context
 @load_config
+@fail_if_no_artifacts_provider
 def validate(ctx: click.Context, only_test_environment: str) -> None:
     """Validates that the configuration file is JSON and tests connectivity for each XSOAR Client environment defined."""
     return_code = 0
@@ -44,7 +51,7 @@ def validate(ctx: click.Context, only_test_environment: str) -> None:
             # 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: Client = ctx.obj["server_envs"][server_env]["xsoar_client"]
         try:
             xsoar_client.test_connectivity()
         except ConnectionError as ex:
@@ -53,6 +60,9 @@ def validate(ctx: click.Context, only_test_environment: str) -> None:
             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)
 
 

xsoar_cli/manifest/README.md

@@ -1,23 +1,269 @@
-# Manifest
+# Manifest Commands
 
-## Validate
-Verifies that the xsoar_config.json manifest is valid JSON. Does a HTTP HEAD calls to every upstream content pack defined. Checks
-custom content pack availability in AWS S3 artefact repository.
+The manifest commands help you manage XSOAR content pack deployments using a declarative configuration file (`xsoar_config.json`). This file defines which content packs should be installed on your XSOAR server and their specific versions.
+
+## Prerequisites
+
+- Valid XSOAR CLI configuration file (`~/.config/xsoar-cli/config.json`)
+- Access to XSOAR server API
+- For custom packs: AWS S3 credentials configured (AWS S3 is currently the only supported artifacts repository provider)
+- Content repository with proper directory structure
+
+## Manifest File Structure
+
+The `xsoar_config.json` file contains two main sections:
+
+```json
+{
+    "custom_packs": [
+        {
+            "id": "MyCustomPack",
+            "version": "1.0.0",
+            "_comment": "Optional comment for documentation"
+        }
+    ],
+    "marketplace_packs": [
+        {
+            "id": "CommonScripts", 
+            "version": "1.20.0"
+        }
+    ]
+}
+```
+
+- **custom_packs**: Content packs developed by your organization, stored in AWS S3 (currently the only supported artifacts repository provider; pull requests for new providers are welcome!)
+- **marketplace_packs**: Official Palo Alto Networks content packs from the marketplace
+- **_comment**: Optional field for documentation/notes about specific pack versions
+
+## Commands
+
+### validate
+Validates the manifest file and verifies all specified content packs are available.
+
+**Usage:**
+```bash
+xsoar-cli manifest validate [OPTIONS] MANIFEST_PATH
+```
+
+**Options:**
+- `--environment TEXT`: Environment name from config file (default: dev)
+
+**Examples:**
+```bash
+# Validate manifest in current directory
+xsoar-cli manifest validate ./xsoar_config.json
+
+# Validate with specific environment
+xsoar-cli manifest validate --environment prod ./xsoar_config.json
+```
+
+**What it checks:**
+- JSON syntax validity
+- Custom pack availability in S3 artifact repository
+- Marketplace pack availability via HTTP connectivity
+- Local pack metadata consistency for new packs in development
+
+**Sample output:**
 ```
-xsoar-cli manifest validate /my/full/path/to/xsoar_config.json
-xsoar-cli manifest validate relative/path/to/xsoar_config.json
+Manifest is valid JSON
+Checking custom_packs availability ........................done.
+Checking marketplace_packs availability ........................done.
+Manifest is valid JSON and all packs are reachable.
 ```
 
-## Update
-Updates and prompts the user to write the xsoar_config.json manifest with the latest available content packs. Both upstream and custom content packs are checked.
+### update
+Compares installed packs against available versions and updates the manifest with latest versions.
+
+**Usage:**
+```bash
+xsoar-cli manifest update [OPTIONS] MANIFEST_PATH
 ```
-xsoar-cli manifest update /my/full/path/to/xsoar_config.json
-xsoar-cli manifest update relative/path/to/xsoar_config.json
+
+**Options:**
+- `--environment TEXT`: Environment name from config file (default: dev)
+
+**Examples:**
+```bash
+# Update manifest with latest versions
+xsoar-cli manifest update ./xsoar_config.json
+
+# Interactive prompts for each pack upgrade
+xsoar-cli manifest update --environment staging ./xsoar_config.json
 ```
 
-## Diff
-Queries the XSOAR server for installed packages and compares them to what is defined in the manifest. Prints out the diff.
+**Behavior:**
+- Queries XSOAR server for outdated packs
+- Displays upgrade candidates in tabular format
+- Prompts for confirmation on each upgrade
+- Preserves `_comment` fields but shows warnings
+- Updates manifest file on disk
+
+**Sample output:**
 ```
-xsoar-cli manifest diff /my/full/path/to/xsoar_config.json
-xsoar-cli manifest diff relative/path/to/xsoar_config.json
+Fetching outdated packs from XSOAR server. This may take a minute...done.
+Pack ID                                           Installed version   Latest available version
+CommonScripts                                     1.19.0              1.20.0              
+Base                                              1.40.14             1.41.14             
+Total number of outdated content packs: 2
+Upgrade CommonScripts from 1.19.0 to 1.20.0? [Y/n]: y
+Upgrade Base from 1.40.14 to 1.41.14? [Y/n]: y
+Written updated manifest to './xsoar_config.json'
 ```
+
+### diff
+Compares the manifest definition against what's actually installed on the XSOAR server.
+
+**Usage:**
+```bash
+xsoar-cli manifest diff [OPTIONS] MANIFEST_PATH
+```
+
+**Options:**
+- `--environment TEXT`: Environment name from config file (default: dev)
+
+**Examples:**
+```bash
+# Show differences between manifest and server
+xsoar-cli manifest diff ./xsoar_config.json
+
+# Check production environment
+xsoar-cli manifest diff --environment prod ./xsoar_config.json
+```
+
+**Output shows:**
+- Packs defined in manifest but not installed
+- Version mismatches between manifest and installed packs
+- Summary message when everything is up to date
+
+**Sample output:**
+```
+Pack MyCustomPack is not installed
+Manifest states CommonScripts version 1.20.0 but version 1.19.0 is installed
+```
+
+### deploy
+Installs or updates content packs on the XSOAR server according to the manifest.
+
+**Usage:**
+```bash
+xsoar-cli manifest deploy [OPTIONS] MANIFEST_PATH
+```
+
+**Options:**
+- `--environment TEXT`: Environment name from config file (default: dev)
+- `--verbose`: Show detailed information about skipped packs
+- `--yes`: Skip confirmation prompt
+
+**Examples:**
+```bash
+# Deploy with confirmation prompt
+xsoar-cli manifest deploy ./xsoar_config.json
+
+# Deploy to production without prompts
+xsoar-cli manifest deploy --environment prod --yes ./xsoar_config.json
+
+# Deploy with verbose output
+xsoar-cli manifest deploy --verbose ./xsoar_config.json
+```
+
+**Behavior:**
+- Prompts for confirmation before deployment (unless --yes used)
+- Only installs/updates packs that differ from current installation
+- Shows progress for each pack installation
+- Skips packs already at correct version
+
+**Sample output:**
+```
+WARNING: this operation will attempt to deploy all packs defined in the manifest to XSOAR dev environment. Continue? [y/N]: y
+Fetching installed packs...done.
+Installing MyCustomPack version 1.0.0...OK.
+Installing CommonScripts version 1.20.0...OK.
+Not installing Base version 1.41.14. Already installed.
+```
+
+## Common Workflows
+
+### Initial Setup
+1. Create manifest: `xsoar-cli manifest validate ./xsoar_config.json` (validates structure)
+2. Deploy: `xsoar-cli manifest deploy ./xsoar_config.json`
+
+### Regular Updates
+1. Check for updates: `xsoar-cli manifest update ./xsoar_config.json`
+2. Review changes in manifest file
+3. Deploy updates: `xsoar-cli manifest deploy ./xsoar_config.json`
+
+### Environment Consistency
+1. Check differences: `xsoar-cli manifest diff --environment prod ./xsoar_config.json`
+2. Deploy if needed: `xsoar-cli manifest deploy --environment prod ./xsoar_config.json`
+
+### CI/CD Pipeline Integration
+```bash
+# Typical CI/CD workflow
+xsoar-cli manifest validate ./xsoar_config.json    # Fail fast on invalid manifest
+xsoar-cli manifest diff --environment dev ./xsoar_config.json  # Show what will change
+xsoar-cli manifest deploy --yes --environment dev ./xsoar_config.json  # Deploy changes
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"Failed to decode JSON in {filepath}"**
+- Check JSON syntax in manifest file
+- Ensure no trailing commas or missing quotes
+- Use a JSON validator to identify syntax errors
+
+**"Failed to reach pack {pack_id} version {version}"**
+- **For custom packs**: Check AWS S3 credentials and bucket access
+- **For marketplace packs**: Verify internet connectivity to Palo Alto Networks CDN
+- Ensure pack version exists in the artifact repository
+- Check if pack is in development locally (may not be uploaded yet)
+
+**"Pack {pack_id} not found in manifest"**
+- Verify pack ID matches exactly (case-sensitive)
+- Check that pack is in correct section (`custom_packs` vs `marketplace_packs`)
+- Ensure pack ID in manifest matches the ID in pack metadata
+
+**"Environment not found"**
+- Check config file exists: `~/.config/xsoar-cli/config.json`
+- Verify environment name matches configuration exactly
+- Run `xsoar-cli config create` if configuration is missing
+- Check server connectivity and API credentials
+
+**"WARNING: comment found in manifest for {pack_id}: {comment}"**
+- This is informational only - comments are preserved during updates
+- Review the comment to understand why the version was pinned
+- Decide whether to accept or decline the upgrade based on the comment
+
+### Performance Considerations
+
+- **Large manifests**: Commands may take several minutes with 100+ packs
+- **Network timeouts**: Custom pack validation requires S3 connectivity
+- **Rate limiting**: XSOAR API calls are rate-limited; large deployments may be slower
+
+### Best Practices
+
+1. **Version Control**: Keep `xsoar_config.json` in version control
+2. **Comments**: Use `_comment` field to document version pin reasons
+3. **Testing**: Always validate before deploying to production
+4. **Environment Separation**: Consider different manifests for dev/staging/prod
+5. **Backup**: Run `diff` before `deploy` to understand changes
+6. **Incremental Updates**: Update and deploy frequently rather than large batch updates
+7. **Monitoring**: Check deployment results and verify pack functionality after updates
+
+### Development Workflow
+
+When developing new custom packs:
+
+1. Add pack to manifest with new version
+2. Run `xsoar-cli manifest validate` - may show pack not available (expected)
+3. The validation will pass if local pack metadata matches manifest version
+4. Deploy pack artifacts to S3 repository
+5. Run `xsoar-cli manifest deploy` to install on XSOAR server
+
+### Security Notes
+
+- AWS credentials should be configured securely (IAM roles, not hardcoded keys)
+- XSOAR API keys should be stored in the configuration file with appropriate permissions
+- Consider using different credentials for different environments
+- Review pack sources and content before deploying to production systems

xsoar_cli/manifest/commands.py

@@ -46,7 +46,7 @@ def manifest() -> None:
 @load_config
 def update(ctx: click.Context, environment: str, manifest: str) -> None:
     """Update manifest on disk with latest available content pack versions."""
-    xsoar_client: Client = ctx.obj["server_envs"][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()
@@ -89,7 +89,7 @@ def update(ctx: click.Context, environment: str, manifest: str) -> None:
 def validate(ctx: click.Context, environment: str, manifest: str) -> None:
     """Validate manifest JSON and all pack availability. Validates upstream pack availability by doing HTTP CONNECT.
     Custom pack availability is implementation dependant."""
-    xsoar_client: Client = ctx.obj["server_envs"][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"]
@@ -129,7 +129,7 @@ def validate(ctx: click.Context, environment: str, manifest: str) -> None:
 def diff(ctx: click.Context, manifest: str, environment: str) -> 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."""
-    xsoar_client: Client = ctx.obj["server_envs"][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
@@ -170,7 +170,7 @@ def deploy(ctx: click.Context, environment: str, manifest: str, verbose: bool, y
     if not should_continue:
         ctx.exit()
 
-    xsoar_client: Client = ctx.obj["server_envs"][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()
@@ -191,7 +191,7 @@ def deploy(ctx: click.Context, environment: str, manifest: str, verbose: bool, y
                 # Print message that install is skipped
 
     if none_installed:
-        click.echo("No packs to install. XSOAR server is up to date with manifest.")
+        click.echo("No packs to install. All packs and versions in manifest is already installed on XSOAR server.")
 
 
 manifest.add_command(deploy)

xsoar_cli/pack/commands.py

@@ -22,7 +22,7 @@ def pack(ctx: click.Context) -> None:
 @load_config
 def delete(ctx: click.Context, environment: str, pack_id: str) -> None:
     """Deletes a content pack from the XSOAR server."""
-    xsoar_client: Client = ctx.obj["server_envs"][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)
@@ -36,7 +36,7 @@ def delete(ctx: click.Context, environment: str, pack_id: str) -> None:
 @load_config
 def get_outdated(ctx: click.Context, environment: str) -> None:
     """Prints out a list of outdated content packs."""
-    xsoar_client: Client = ctx.obj["server_envs"][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:

xsoar_cli/plugins/README.md

@@ -40,20 +40,20 @@ class MyPlugin(XSOARPlugin):
     @property
     def name(self) -> str:
         return "myplugin"
-    
-    @property 
+
+    @property
     def version(self) -> str:
         return "1.0.0"
-    
+
     @property
     def description(self) -> str:
         return "My custom plugin"
-    
+
     def get_command(self) -> click.Command:
         @click.command(help="My custom command")
         def mycommand():
             click.echo("Hello from my plugin!")
-        
+
         return mycommand
 ```
 
@@ -75,23 +75,23 @@ class MyCustomPlugin(XSOARPlugin):
     @property
     def name(self) -> str:
         return "mycustom"
-    
+
     @property
     def version(self) -> str:
         return "1.0.0"
-    
+
     @property
     def description(self) -> str:
         return "A custom plugin with multiple commands"
-    
+
     def get_command(self) -> click.Command:
         """Return the main command group for this plugin."""
-        
+
         @click.group(help="My custom commands")
         def mycustom():
             """Main command group for my custom plugin."""
             pass
-        
+
         @click.command(help="Greet someone")
         @click.option("--name", default="World", help="Name to greet")
         @click.option("--times", default=1, help="Number of times to greet")
@@ -99,7 +99,7 @@ class MyCustomPlugin(XSOARPlugin):
             """Greet someone multiple times."""
             for i in range(times):
                 click.echo(f"Hello, {name}!")
-        
+
         @click.command(help="Show current status")
         @click.option("--verbose", "-v", is_flag=True, help="Verbose output")
         def status(verbose: bool):
@@ -108,7 +108,7 @@ class MyCustomPlugin(XSOARPlugin):
             if verbose:
                 click.echo(f"Description: {self.description}")
                 click.echo("Status: Active")
-        
+
         @click.command(help="Process a file")
         @click.argument("filename", type=click.Path(exists=True))
         @click.option("--output", "-o", help="Output file")
@@ -118,18 +118,18 @@ class MyCustomPlugin(XSOARPlugin):
             if output:
                 click.echo(f"Output will be saved to: {output}")
             # Your processing logic here
-        
+
         # Add commands to the group
         mycustom.add_command(greet)
         mycustom.add_command(status)
         mycustom.add_command(process)
-        
+
         return mycustom
-    
+
     def initialize(self):
         """Initialize the plugin."""
         click.echo("My custom plugin initialized!")
-    
+
     def cleanup(self):
         """Cleanup when the plugin is unloaded."""
         pass
@@ -176,7 +176,7 @@ from xsoar_cli.utilities import load_config
 @load_config
 def my_command(ctx: click.Context):
     # Access XSOAR client
-    xsoar_client = ctx.obj["server_envs"]["dev"]
+    xsoar_client = ctx.obj["server_envs"]["dev"]["xsoar_client"]
     # Use the client...
 ```
 
@@ -284,11 +284,11 @@ class MyPlugin(XSOARPlugin):
         @click.group()
         def myplugin():
             pass
-        
+
         @click.command()
         def case():  # ✅ Namespaced as 'myplugin case'
             click.echo("My case command")
-        
+
         myplugin.add_command(case)
         return myplugin
 ```
@@ -297,7 +297,7 @@ class MyPlugin(XSOARPlugin):
 
 These command names are reserved by the core CLI:
 - `case` - Case/incident management
-- `config` - Configuration management  
+- `config` - Configuration management
 - `graph` - Dependency graphs
 - `manifest` - Manifest operations
 - `pack` - Content pack operations
@@ -330,7 +330,7 @@ def get_command(self) -> click.Command:
         except Exception as e:
             click.echo(f"Error: {e}", err=True)
             raise click.Abort()
-    
+
     return mycommand
 ```
 
@@ -430,4 +430,4 @@ except ImportError:
 
 You can share plugins by simply sharing the Python file. Users can place it in their plugins directory and it will be automatically discovered.
 
-For more complex plugins, consider packaging them as proper Python packages that install the plugin file automatically.
+For more complex plugins, consider packaging them as proper Python packages that install the plugin file automatically.

xsoar_cli/utilities.py

@@ -1,7 +1,8 @@
+import contextlib
 import json
+from collections.abc import Callable
 from functools import update_wrapper
 from pathlib import Path
-from typing import Callable
 
 import click
 from xsoar_client.xsoar_client import Client
@@ -75,6 +76,29 @@ def load_config(f: Callable) -> Callable:
     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 = {}
@@ -83,13 +107,15 @@ def parse_config(config: dict, ctx: click.Context) -> None:
     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] = Client(
+        ctx.obj["server_envs"][key] = {}
+        ctx.obj["server_envs"][key]["xsoar_client"] = Client(
             api_token=config["server_config"][key]["api_token"],
             server_url=config["server_config"][key]["base_url"],
             verify_ssl=config["server_config"][key]["verify_ssl"],
             custom_pack_authors=config["custom_pack_authors"],
             xsiam_auth_id=config["server_config"][key].get("xsiam_auth_id", ""),
             server_version=config["server_config"][key]["server_version"],
-            artifacts_location=config["server_config"][key]["artifacts_location"],
-            s3_bucket_name=config["server_config"][key]["s3_bucket_name"],
+            artifacts_location=config["server_config"][key].get("artifacts_location", None),
+            s3_bucket_name=config["server_config"][key].get("s3_bucket_name", None),
         )
+        ctx.obj["server_envs"][key]["artifacts_location"] = config["server_config"][key].get("artifacts_location", None)

xsoar_cli-1.0.4.dist-info/METADATA

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: xsoar-cli
+Version: 1.0.4
+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.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.12
+Requires-Dist: click==8.1.8
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: xsoar-client>=1.0.0
+Requires-Dist: xsoar-dependency-graph>=0.0.3
+Description-Content-Type: text/markdown
+
+# xsoar-cli
+
+[![PyPI version](https://badge.fury.io/py/xsoar-cli.svg)](https://badge.fury.io/py/xsoar-cli) [![Python](https://img.shields.io/pypi/pyversions/xsoar-cli.svg)](https://pypi.org/project/xsoar-cli/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![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 (depending on usage)
+- **AWS SDK for Python (Boto3)** - Only required when working with custom content packs stored in S3. You can use marketplace packs and other functionality without AWS setup.
+
+**Note:** AWS S3 is currently the only available artifacts repository provider for custom packs. Pull requests for new providers are welcome!
+
+## 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": "S3",
+            "s3_bucket_name": "xsoar-cicd-prod",
+            "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 (currently only "S3" is supported)
+  - **s3_bucket_name**: S3 bucket where your custom content packs are stored
+  - **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. Plugins are Python files that you place in `~/.local/xsoar-cli/plugins/` and they're automatically discovered and loaded.
+
+### Quick Start with Plugins
+
+1. **Create an example plugin**:
+   ```bash
+   xsoar-cli plugins create-example
+   ```
+
+2. **List available plugins**:
+   ```bash
+   xsoar-cli plugins list
+   ```
+
+3. **Test the example plugin**:
+   ```bash
+   xsoar-cli example hello --name "World"
+   ```
+
+### Plugin Management Commands
+
+- `xsoar-cli plugins list` - List all plugins
+- `xsoar-cli plugins info <plugin>` - Show plugin information
+- `xsoar-cli plugins validate` - Validate all plugins
+- `xsoar-cli plugins reload <plugin>` - Reload a specific plugin
+- `xsoar-cli plugins create-example` - Create an example plugin
+- `xsoar-cli plugins open` - Open the plugins directory
+
+### Creating Your Own Plugins
+
+Create a Python file in `~/.local/xsoar-cli/plugins/` that inherits from `XSOARPlugin`:
+
+```python
+import click
+from xsoar_cli.plugins import XSOARPlugin
+
+class MyPlugin(XSOARPlugin):
+    @property
+    def name(self) -> str:
+        return "myplugin"
+
+    @property
+    def version(self) -> str:
+        return "1.0.0"
+
+    def get_command(self) -> click.Command:
+        @click.command(help="My custom command")
+        def mycommand():
+            click.echo("Hello from my plugin!")
+        return mycommand
+```
+
+For detailed documentation, 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.2.dist-info → xsoar_cli-1.0.4.dist-info}/RECORD

@@ -1,31 +1,31 @@
-xsoar_cli/__about__.py,sha256=cwkA9vKz4-QApCiApwquYub4oxcNxa_UUZycn3J1BsI,127
+xsoar_cli/__about__.py,sha256=ppSrh4dfP4K0nr9jdlBQ1YkT9cD5CyaRnZQz5wDhG94,127
 xsoar_cli/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 xsoar_cli/cli.py,sha256=iAlSeZe2iR6ciTVrJYLt-CDZk7b5I-hzHFXbYoXhupA,1342
-xsoar_cli/utilities.py,sha256=nmvb7aclp1Uil6gVtSBTy6wa-GfRLAWOsV_0a8Nc3Vk,3931
+xsoar_cli/utilities.py,sha256=aW0lmPAf06YyGlq0ayQg0h2uCmvqgIHSuLdpCTJQN_0,5150
 xsoar_cli/case/README.md,sha256=MTfgVeW3qJXRPNFo8CkZvulm2vwbN8sgiW86V-qXRFw,1342
 xsoar_cli/case/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xsoar_cli/case/commands.py,sha256=EWFld2BfLPgBhPJs5QqWsddlzrUvNIWmlKG4HwnpukU,3511
+xsoar_cli/case/commands.py,sha256=UXXOrE3qmYF4z8mtKRkIP7onatib5x55fwprtbNxTBA,3575
 xsoar_cli/config/README.md,sha256=pcO858PDL9c0qtwj3_a6B8q2CGvcka3dwclVnwi2vlA,516
 xsoar_cli/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xsoar_cli/config/commands.py,sha256=SJqIBUBq4tHmnXusycXuIOkmHhyc-vKvQwFMjIHh3Cc,3884
+xsoar_cli/config/commands.py,sha256=i6lWaR0LjAzMpNVPZyCsDPaT0GMVqTUXdau6Id0iOrs,4193
 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=Ha84Ozlj7KwSj9FsK42sSZVYoWllmPKsjtkB-53Anpg,913
+xsoar_cli/manifest/README.md,sha256=0oiA6rZEAUQMOYM7VmtUBtW3PRo7-exfkjw5JLt_whU,9282
 xsoar_cli/manifest/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xsoar_cli/manifest/commands.py,sha256=jShmi0s7GOSXJt9DQbEoFSu4ZsC0Givv1vJj7qfwI2g,8697
+xsoar_cli/manifest/commands.py,sha256=6IU9k-UFCeZUnM9CHNqafaouiTOrK3OXtWxsr3LTCV4,8792
 xsoar_cli/pack/README.md,sha256=CA7jAEphHxK0gh58rLRKL-u3wx29QgNAXojd_tGBXnY,46
 xsoar_cli/pack/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xsoar_cli/pack/commands.py,sha256=bLbKCC_TROqqysEfmk6G9qqKJuXkt0nqwUHoP_LauD8,1899
+xsoar_cli/pack/commands.py,sha256=A1CYdzvdXNAy63rPVoBOAXddRzl8PRmuSCQOSDeRlRk,1931
 xsoar_cli/playbook/README.md,sha256=8y_YhvZtLP7KzYG83jiVBF-wBAEh8UTJcgmTOTynmbc,977
 xsoar_cli/playbook/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xsoar_cli/playbook/commands.py,sha256=mFmXJ3D8plvrUC9ylMlkrAa2T1yhydByEBhrBVbaZec,2729
-xsoar_cli/plugins/README.md,sha256=qQ_shzxcJcJKHuWfuN_cTVhtaew4BEGBEjn9wxaZG5c,11314
+xsoar_cli/plugins/README.md,sha256=19AAhaYi2Rk6h95MkDGoh8n73KB-BcbaznQ0nfW2rpc,11220
 xsoar_cli/plugins/__init__.py,sha256=81IZsMbZsqrLdB6TjA9t6s3yS8FkuihliBFX4xZUpTo,1753
 xsoar_cli/plugins/commands.py,sha256=HC0sWu149uQG9Ztag4t2CNPKXTM4WJbEdLSvFMEjw80,10660
 xsoar_cli/plugins/manager.py,sha256=7RPk3lAYDifGMLOU-hFOqyPxTVk8ibBVzBqH7R8wy4g,13012
-xsoar_cli-1.0.2.dist-info/METADATA,sha256=Oqf719w5HhWZgyYifNZXktW90EyVk_L_tE6uErKj_2M,4659
-xsoar_cli-1.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-xsoar_cli-1.0.2.dist-info/entry_points.txt,sha256=s6Klu4QRekXsmZaBxMyFlE4Q-4_jIA9uijk4qIYUPvE,48
-xsoar_cli-1.0.2.dist-info/licenses/LICENSE.txt,sha256=l6xnqWKshqwwTXt6ayO6MX8Uvygq0YnkUuFTNnR3ba4,1097
-xsoar_cli-1.0.2.dist-info/RECORD,,
+xsoar_cli-1.0.4.dist-info/METADATA,sha256=cKIkFA52ep6NsbFDXtpcZLatvMtKs473AAAP2bfF-o0,9110
+xsoar_cli-1.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+xsoar_cli-1.0.4.dist-info/entry_points.txt,sha256=s6Klu4QRekXsmZaBxMyFlE4Q-4_jIA9uijk4qIYUPvE,48
+xsoar_cli-1.0.4.dist-info/licenses/LICENSE.txt,sha256=l6xnqWKshqwwTXt6ayO6MX8Uvygq0YnkUuFTNnR3ba4,1097
+xsoar_cli-1.0.4.dist-info/RECORD,,

xsoar_cli-1.0.2.dist-info/METADATA

@@ -1,136 +0,0 @@
-Metadata-Version: 2.4
-Name: xsoar-cli
-Version: 1.0.2
-Project-URL: Documentation, https://github.com/tlium/xsoar-cli#readme
-Project-URL: Issues, https://github.com/tliumb/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.8
-Classifier: Programming Language :: Python :: 3.9
-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.8
-Requires-Dist: click==8.1.8
-Requires-Dist: pyyaml>=6.0.2
-Requires-Dist: xsoar-client>=1.0.0
-Requires-Dist: xsoar-dependency-graph>=0.0.3
-Description-Content-Type: text/markdown
-
-# xsoar-cli
------
-This tool is made to help provide a smoother workflow for developers, but also for power users to get useful information out of XSOAR from
-the terminal. It is mostly useful if you are using a CICD workflow to deploy your XSOAR content, and most of the functionality assumest that
-you have your content stored in a [content repository](https://github.com/demisto/content-ci-cd-template).
-
-Pull Requests are very welcome and appreciated!
-
-
-*IMPORTANT NOTE*
-This CLI tools is made to be run from the root of a content repository. Some commands depends on files located in your
-content repository or expects a certain directory structure to be available from your currently working directory.
-
-## Installation
-```
-pip install xsoar-cli
-```
-## Upgrading
-```
-pip install --upgrade 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
-```
-xsoar-cli config create
-```
-Open up the newly created configuration file and add values that correspond with your environment.
-
-*IMPORTANT NOTES* 
-- The configuration key `"custom_pack_authors": ["SOMEONE"]` is needed in order for `xsoar-cli` to be able to determine which content packs 
-are your own custom content packs and which are supplied from Palo Alto upstream. Use whatever values you may have set in pack_metadata.json
- in the content packs in your content repository.
-
-## 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
-1. [case](src/xsoar_cli/case/README.md)
-2. [config](src/xsoar_cli/config/README.md)
-3. [graph](src/xsoar_cli/graph/README.md)
-4. [manifest](src/xsoar_cli/manifest/README.md)
-5. [pack](src/xsoar_cli/pack/README.md)
-6. [playbook](src/xsoar_cli/playbook/README.md)
-7. [plugins](src/xsoar_cli/plugins/README.md)
-
-## Plugin System
-
-xsoar-cli supports a plugin system that allows you to extend the CLI with custom commands. Plugins are Python files that you place in `~/.local/xsoar-cli/plugins/` and they're automatically discovered and loaded.
-
-### Quick Start with Plugins
-
-1. **Create an example plugin**:
-   ```bash
-   xsoar-cli plugins create-example
-   ```
-
-2. **List available plugins**:
-   ```bash
-   xsoar-cli plugins list
-   ```
-
-3. **Test the example plugin**:
-   ```bash
-   xsoar-cli example hello --name "World"
-   ```
-
-### Plugin Management Commands
-
-- `xsoar-cli plugins list` - List all plugins
-- `xsoar-cli plugins info <plugin>` - Show plugin information
-- `xsoar-cli plugins validate` - Validate all plugins
-- `xsoar-cli plugins reload <plugin>` - Reload a specific plugin
-- `xsoar-cli plugins create-example` - Create an example plugin
-- `xsoar-cli plugins open` - Open the plugins directory
-
-### Creating Your Own Plugins
-
-Create a Python file in `~/.local/xsoar-cli/plugins/` that inherits from `XSOARPlugin`:
-
-```python
-import click
-from xsoar_cli.plugins import XSOARPlugin
-
-class MyPlugin(XSOARPlugin):
-    @property
-    def name(self) -> str:
-        return "myplugin"
-
-    @property
-    def version(self) -> str:
-        return "1.0.0"
-
-    def get_command(self) -> click.Command:
-        @click.command(help="My custom command")
-        def mycommand():
-            click.echo("Hello from my plugin!")
-        return mycommand
-```
-
-For detailed documentation, see [Plugin System Documentation](src/xsoar_cli/plugins/README.md).
-
-## License
-
-`xsoar-cli` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.