xsoar-cli 0.0.3__tar.gz

xsoar_cli-0.0.3/.github/workflows/release.yml

@@ -0,0 +1,144 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+      - "[0-9]+.[0-9]+.[0-9]+a[0-9]+"
+      - "[0-9]+.[0-9]+.[0-9]+b[0-9]+"
+      - "[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+
+env:
+  PACKAGE_NAME: "xsoar-cli"
+  OWNER: "tlium"
+
+jobs:
+  details:
+    runs-on: ubuntu-latest
+    outputs:
+      new_version: ${{ steps.release.outputs.new_version }}
+      suffix: ${{ steps.release.outputs.suffix }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Extract tag and Details
+        id: release
+        run: |
+          if [ "${{ github.ref_type }}" = "tag" ]; then
+            TAG_NAME=${GITHUB_REF#refs/tags/}
+            NEW_VERSION=$(echo $TAG_NAME | awk -F'-' '{print $1}')
+            SUFFIX=$(echo $TAG_NAME | grep -oP '[a-z]+[0-9]+' || echo "")
+            echo "new_version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+            echo "suffix=$SUFFIX" >> "$GITHUB_OUTPUT"
+            echo "tag_name=$TAG_NAME" >> "$GITHUB_OUTPUT"
+            echo "Version is $NEW_VERSION"
+            echo "Suffix is $SUFFIX"
+            echo "Tag name is $TAG_NAME"
+          else
+            echo "No tag found"
+            exit 1
+          fi
+
+  check_pypi:
+    needs: details
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch information from PyPI
+        run: |
+          response=$(curl -s https://pypi.org/pypi/${{ env.PACKAGE_NAME }}/json || echo "{}")
+          latest_previous_version=$(echo $response | jq --raw-output "select(.releases != null) | .releases | keys_unsorted | last")
+          if [ -z "$latest_previous_version" ]; then
+            echo "Package not found on PyPI."
+            latest_previous_version="0.0.0"
+          fi
+          echo "Latest version on PyPI: $latest_previous_version"
+          echo "latest_previous_version=$latest_previous_version" >> $GITHUB_ENV
+
+      - name: Compare versions and exit if not newer
+        run: |
+          NEW_VERSION=${{ needs.details.outputs.new_version }}
+          LATEST_VERSION=$latest_previous_version
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$NEW_VERSION" | sort -rV | head -n 1)" != "$NEW_VERSION" ] || [ "$NEW_VERSION" == "$LATEST_VERSION" ]; then
+            echo "The new version $NEW_VERSION is not greater than the latest version $LATEST_VERSION on PyPI."
+            exit 1
+          else
+            echo "The new version $NEW_VERSION is greater than the latest version $LATEST_VERSION on PyPI."
+          fi
+
+  setup_and_build:
+    needs: [details, check_pypi]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install Hatch
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+
+      - name: Set project version with Hatch
+        run: |
+          hatch version ${{ needs.details.outputs.new_version }}
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Build source and wheel distribution
+        run: |
+          hatch build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi_publish:
+    name: Upload release to PyPI
+    needs: [setup_and_build, details]
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github_release:
+    name: Create GitHub Release
+    needs: [setup_and_build, details]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        id: create_release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create ${{ needs.details.outputs.tag_name }} dist/* --title ${{ needs.details.outputs.tag_name }} --generate-notes

xsoar_cli-0.0.3/.gitignore

@@ -0,0 +1,8 @@
+**/__pycache__
+dist
+build
+venv
+xsoar_config.json
+.venv
+.coverage
+.pytest_cache

xsoar_cli-0.0.3/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.

xsoar_cli-0.0.3/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: xsoar-cli
+Version: 0.0.3
+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. Merge 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 NOTE*: 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 whateve 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. [manifest](src/xsoar_cli/manifest/README.md)
+4. [pack](src/xsoar_cli/pack/README.md)
+5. [playbook](src/xsoar_cli/playbook/README.md)
+6. [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.

xsoar_cli-0.0.3/README.md

@@ -0,0 +1,103 @@
+# 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. Merge 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 NOTE*: 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 whateve 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. [manifest](src/xsoar_cli/manifest/README.md)
+4. [pack](src/xsoar_cli/pack/README.md)
+5. [playbook](src/xsoar_cli/playbook/README.md)
+6. [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.

xsoar_cli-0.0.3/examples/README.md

@@ -0,0 +1,161 @@
+# XSOAR CLI Plugin Examples
+
+This directory contains example plugins that demonstrate various features and capabilities of the XSOAR CLI plugin system.
+
+## Examples
+
+### advanced_plugin.py
+
+A comprehensive example plugin that demonstrates:
+
+- **Multiple command groups** - Organized commands into logical groups (`cases`, `utils`)
+- **XSOAR integration patterns** - Shows how to structure commands that would interact with XSOAR
+- **Rich CLI features** - Options, arguments, validation, prompts, confirmations
+- **File operations** - Reading/writing files, log analysis
+- **Error handling** - Proper exception handling and user feedback
+- **Code generation** - Dynamic template generation for new plugins
+
+#### Usage
+
+1. Copy the file to your plugins directory:
+   ```bash
+   cp examples/advanced_plugin.py ~/.local/xsoar-cli/plugins/
+   ```
+
+2. Verify the plugin is loaded:
+   ```bash
+   xsoar-cli plugins list
+   ```
+
+3. Use the plugin commands:
+   ```bash
+   # List cases
+   xsoar-cli advanced cases list --limit 5
+   
+   # Create a test case
+   xsoar-cli advanced cases create --name "Test Case" --severity High
+   
+   # Analyze a log file
+   xsoar-cli advanced utils analyze-log /path/to/logfile.log --pattern "error"
+   
+   # Generate a new plugin template
+   xsoar-cli advanced utils generate-template MyCustomPlugin
+   
+   # Show plugin statistics
+   xsoar-cli advanced stats --verbose
+   ```
+
+## Creating Your Own Plugins
+
+### Quick Start
+
+1. **Use the built-in example generator**:
+   ```bash
+   xsoar-cli plugins create-example
+   ```
+
+2. **Or generate a custom template**:
+   ```bash
+   xsoar-cli advanced utils generate-template YourPluginName
+   ```
+
+3. **Copy to plugins directory**:
+   ```bash
+   cp YourPluginName_plugin.py ~/.local/xsoar-cli/plugins/
+   ```
+
+### Plugin Structure
+
+Every plugin must inherit from `XSOARPlugin` and implement these required methods:
+
+```python
+import click
+
+class MyPlugin(XSOARPlugin):
+    @property
+    def name(self) -> str:
+        return "myplugin"
+    
+    @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 command")
+        def mycommand():
+            click.echo("Hello from my plugin!")
+        return mycommand
+```
+
+### Best Practices
+
+1. **Use descriptive names** - Choose clear, unique command names
+2. **Organize with groups** - Use `@click.group()` for multiple related commands
+3. **Handle errors gracefully** - Use try/catch and proper error messages
+4. **Validate inputs** - Use Click's built-in validation options
+5. **Provide helpful output** - Use colors, formatting, and clear messages
+6. **Document your commands** - Add help text and descriptions
+
+### XSOAR Integration
+
+To integrate with XSOAR in your plugins, use the configuration system:
+
+```python
+from xsoar_cli.utilities import load_config
+
+@click.command()
+@click.pass_context
+@load_config
+def my_xsoar_command(ctx: click.Context):
+    # Access XSOAR client
+    xsoar_client = ctx.obj["server_envs"]["dev"]
+    
+    # Use the client for XSOAR operations
+    cases = xsoar_client.get_cases()
+    # ... your logic here
+```
+
+## Testing Your Plugins
+
+1. **Validate syntax**:
+   ```bash
+   xsoar-cli plugins validate
+   ```
+
+2. **Check plugin info**:
+   ```bash
+   xsoar-cli plugins info your_plugin_name
+   ```
+
+3. **Test commands**:
+   ```bash
+   xsoar-cli your-command --help
+   xsoar-cli your-command test-args
+   ```
+
+4. **Reload during development**:
+   ```bash
+   xsoar-cli plugins reload your_plugin_name
+   ```
+
+## Sharing Plugins
+
+To share your plugins with others:
+
+1. **Simple sharing** - Share the `.py` file directly
+2. **Documentation** - Include usage examples and requirements
+3. **Dependencies** - List any external packages needed
+4. **Testing** - Provide test cases or examples
+
+## Getting Help
+
+- **Plugin documentation**: `src/xsoar_cli/plugins/README.md`
+- **List available plugins**: `xsoar-cli plugins list`
+- **Plugin commands help**: `xsoar-cli plugins --help`
+- **Command-specific help**: `xsoar-cli <plugin-command> --help`
+
+Happy plugin development! 🚀