xsoar-cli 1.0.1__tar.gz → 1.0.3__tar.gz

xsoar_cli-1.0.3/.github/workflows/pull-request-open.yml

@@ -0,0 +1,34 @@
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Create and activate virtual environment
+        run: |
+          python3.12 -m venv venv
+          source venv/bin/activate
+
+      - name: Install requirements
+        run: |
+          pip install -r requirements.txt
+          pip install -r requirements_dev.txt
+
+      - name: Install xsoar-cli
+        run: pip install -e .
+
+      - name: Create example plugin
+        run: xsoar-cli plugins create-example
+
+      - name: Run unit tests
+        run: pytest

xsoar_cli-1.0.3/CONTRIBUTING.md

@@ -0,0 +1,197 @@
+# Contributing to xsoar-cli
+
+We welcome contributions of all kinds! Whether you're fixing bugs, adding features, improving documentation, or sharing ideas, your help makes this project better.
+
+## Ways to Contribute
+
+### Documentation (just as valuable as code!)
+- Fix typos or unclear explanations
+- Add examples and use cases
+- Improve command documentation
+- Translate documentation
+- Write tutorials or blog posts
+
+### Code Contributions
+- Bug fixes and performance improvements
+- New features and command enhancements
+- Plugin examples and templates
+- Test coverage improvements
+
+### Issue Reports
+- Bug reports with clear reproduction steps
+- Feature requests with use case descriptions
+- Documentation gaps or confusion points
+
+## Getting Started
+
+### 1. Fork and Clone
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/xsoar-cli.git
+   cd xsoar-cli
+   ```
+
+### 2. Set Up Development Environment
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install development dependencies
+pip install -r requirements_dev.txt
+
+# Install the package in development mode
+pip install -e .
+```
+
+### 3. Verify Setup
+```bash
+# Run tests to ensure everything works
+pytest
+
+# Check code style
+black --check src/ tests/
+
+# Run the CLI to verify installation
+xsoar-cli --help
+```
+
+## Development Workflow
+
+### Making Changes
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** (code, docs, tests)
+
+3. **Run quality checks**:
+   ```bash
+   # Run tests
+   pytest
+   
+   # Format code
+   black src/ tests/
+   
+   # Check for any issues
+   python -m pytest --cov=src/xsoar_cli
+   ```
+
+4. **Commit with clear messages**:
+   ```bash
+   git add .
+   git commit -m "Add feature: brief description of what you added"
+   ```
+
+5. **Push and create Pull Request**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+### Code Style
+- We use [Black](https://github.com/psf/black) for code formatting
+- Run `black src/ tests/` before committing
+- Follow existing code patterns and conventions
+- Add type hints where appropriate
+- Write docstrings for new functions and classes
+
+### Testing
+- Add tests for new features
+- Ensure existing tests still pass
+- Aim for good test coverage
+- Test commands work with both XSOAR v6 and v8 when applicable
+
+## Documentation Contributions
+
+Documentation improvements are especially welcome! You can contribute to documentation in several ways:
+
+### Quick Edits
+- **Edit files directly on GitHub** (great for small fixes like typos)
+- Click the "Edit" button on any file in the GitHub interface
+- Make your changes and create a pull request
+
+### Larger Documentation Changes
+- Use the full development setup described above
+- Focus on clarity - assume readers are new to the tool
+- Include practical examples where helpful
+- Test any code examples you include
+
+### Types of Documentation Contributions
+- **README improvements**: Better explanations, more examples
+- **Command documentation**: Individual command READMEs in `src/xsoar_cli/*/README.md`
+- **Plugin documentation**: Examples and guides for plugin development
+- **Troubleshooting**: Common issues and solutions
+- **Tutorials**: Step-by-step guides for specific workflows
+
+## Submitting Pull Requests
+
+### Before Submitting
+- [ ] Tests pass (`pytest`)
+- [ ] Code is formatted (`black src/ tests/`)
+- [ ] Documentation is updated if needed
+- [ ] Commit messages are clear and descriptive
+
+### Pull Request Guidelines
+- **Describe your changes** clearly in the PR description
+- **Reference any related issues** (e.g., "Fixes #123")
+- **Include testing instructions** if applicable
+- **Be responsive to feedback** during code review
+
+### What to Expect
+- We'll review your PR as soon as possible
+- We may suggest changes or improvements
+- Once approved, we'll merge your contribution
+- Your contribution will be included in the next release
+
+## Reporting Issues
+
+### Bug Reports
+Please include:
+- **Clear description** of the problem
+- **Steps to reproduce** the issue
+- **Expected vs actual behavior**
+- **Environment details** (Python version, XSOAR version, OS)
+- **Error messages** and stack traces if applicable
+
+### Feature Requests
+Please include:
+- **Use case description** - what problem does this solve?
+- **Proposed solution** or implementation ideas
+- **Examples** of how the feature would be used
+
+## Development Tips
+
+### Working with XSOAR Environments
+- Test against both XSOAR v6 and v8 when possible
+- Use the configuration examples in the README as reference
+- Consider how features work with different authentication methods
+
+### Plugin Development
+- Look at examples in the `examples/` directory
+- Follow the plugin architecture in `src/xsoar_cli/plugins/`
+- Test plugin loading and command registration
+
+### Command Development
+- Follow the existing command structure
+- Use Click decorators consistently
+- Include proper help text and examples
+- Consider error handling and user feedback
+
+## Questions or Ideas?
+
+- **Open an issue** for discussion
+- **Check existing issues** for similar topics
+- **Feel free to ask questions** - we're here to help!
+- **Join discussions** on existing PRs and issues
+
+## Code of Conduct
+
+Be respectful and constructive in all interactions. We want this to be a welcoming space for contributors of all backgrounds and experience levels.
+
+## Recognition
+
+Contributors are recognized in release notes and we appreciate all contributions, no matter how small!
+
+Thank you for contributing!

xsoar_cli-1.0.3/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: xsoar-cli
+Version: 1.0.3
+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.