Releases: gocortexio/spellbook
v1.22.0-beta.3
GoCortex Spellbook v1.22.0-beta.3 - Hear Here Be Dragons + Summon the Templates!
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
Notes:
- v1.22.0-beta.3 will not be be marked as the LATEST image in either DockerHub or GitHub Container Registry during the beta testing.
Beta Improvements:
- Refresh intel_retrohunt XQL query with %%INDICATOR_TYPE%% / %%SOURCE_FIELDS%% tokens and inline guidance
- Add Jobs template support with Job JSON linked to Playbook (id/playbookId) (not working yet)
- Update SDK pin to v1.38.23
- Standardise Job scheduling (default cadence; cron 02:00; no prompts; LOOKBACK-derived fallback)
- Introduce @@token@@ for auto-derived tokens; hide from users
- Align Playbook and Job naming to prevent collisions and ensure consistent filename derivation
- Fix marketplace upload behaviour (--platform support; resolve Jobs being dropped on --xsiam)
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:1.22.0-beta.3
# Create a content instance
docker run --rm \
-v $(pwd):/content \
-v ~/.gitconfig:/home/spellbook/.gitconfig:ro \
ghcr.io/gocortexio/spellbook:1.22.0-beta.3 init my-content --author "Your Organisation" --no-ci
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"Licence
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full licence text.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
Contributors
Assets 2
v1.22.0-beta.2
GoCortex Spellbook v1.22.0-beta.2 - Hear Here Be Dragons + Summon the Templates!
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
Notes:
- v1.22.0-beta.2 will not be be marked as the LATEST image in either DockerHub or GitHub Container Registry during the beta testing.
Beta Improvements:
- Overhaul intel_retrohunt XQL template from PANW-specific query to universal threat intel hunt supporting IP, Domain, File Hash, Username, and URL hunt types
- Add %%SOURCE_FIELDS%% token for user-defined field selection replacing hardcoded field list
- Add %%INDICATOR_TYPE%% token to threat intel join filter replacing hardcoded "IP" type
- Add null-defaulted field mapping section for standardised intermediary names aligned to XDM paths
- Fix IPv4 vs IPv6 filter logic in data quality section
- Fix indicator type placeholder in threat intel join filter
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:1.22.0-beta.2
# Create a content instance
docker run --rm \
-v $(pwd):/content \
-v ~/.gitconfig:/home/spellbook/.gitconfig:ro \
ghcr.io/gocortexio/spellbook:1.22.0-beta.2 init my-content --author "Your Organisation" --no-ci
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"Licence
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full licence text.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
v1.22.0-beta.1
GoCortex Spellbook v1.22.0-beta.1 - Here Be Dragons + Summon the Templates!
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
Notes:
- v1.22.0-beta.1 will not be be marked as the LATEST image in either DockerHub or GitHub Container Registry during the beta testing.
Beta Features:
- Add summon template command for generating content pack artefacts from self-describing templates with %%TOKEN%% placeholders and interactive/non-interactive modes
- Add built-in intel_retrohunt template shipped with the tool and copied to instance-level templates/ directory during init for user customisation
- Add XSIAM validation engine (xsiam_validator.py) with rules for invalid INGEST fields, simple_schedule in correlation rules, parentheses in rule names, and problematic filename characters
- Add --message (-m) flag to bump-version and set-version for writing commit messages directly into release notes files instead of the placeholder scaffold
- Add automatic version history section in pack README.md using HTML comment markers, updated on --tag with the commit message (newest first)
- Add set-version command now creates release notes files (previously only bump-version did)
Beta Improvements:
- Add non-blocking XSIAM validation as a pre-step in build, upload, bump-version, and set-version (skippable with --no-validate / --skip-validation)
- Conditionally preserve user_defined_severity and user_defined_category in correlation imports only when the corresponding field is set to "User Defined"
- Add error handling for UnicodeDecodeError during template rendering with user-friendly messages
- Update demisto-sdk pinned version from 1.38.18 to 1.38.20 across Dockerfile, pyproject.toml, and CLI
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:1.22.0-beta.1
# Create a content instance
docker run --rm \
-v $(pwd):/content \
-v ~/.gitconfig:/home/spellbook/.gitconfig:ro \
ghcr.io/gocortexio/spellbook:1.22.0-beta.1 init my-content --author "Your Organisation" --no-ci
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"Licence
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full licence text.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
v1.20.2
GoCortex Spellbook v1.20.2
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
Features:
- Add summon correlation command for importing correlation rules from Cortex Platform JSON exports,
- Add --message (-m) flag for custom commit messages when using --tag supporting CI/CD integration (e.g. auto-closing issues)
- Add Git repository check before tag creation to prevent errors in uninitialised repositories
- Add trigger playbook template
Improvements:
- Standardise all CLI output to grepable format with status tags at column 0 ([OK], [ERROR], [WARN], [INFO], [PASS], [FAIL], [MISSING])
- Add gitconfig volume mount to all Docker examples in Windows README
Disabled:
- Temporarily disable rename-content command pending further review
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:latest
# Or build locally from source
docker build -t ghcr.io/gocortexio/spellbook .
# Create a content instance
docker run --rm \
-v $(pwd):/content \
-v ~/.gitconfig:/home/spellbook/.gitconfig:ro \
ghcr.io/gocortexio/spellbook init my-content --author "Your Organisation" --no-ci
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"Licence
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full licence text.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
v1.20.1
GoCortex Spellbook v1.20.1
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
Features:
- Add summon correlation command for importing correlation rules from Cortex Platform JSON exports,
- Add --message (-m) flag for custom commit messages when using --tag supporting CI/CD integration (e.g. auto-closing issues)
- Add Git repository check before tag creation to prevent errors in uninitialised repositories
- Add trigger playbook template
Improvements:
- Standardise all CLI output to grepable format with status tags at column 0 ([OK], [ERROR], [WARN], [INFO], [PASS], [FAIL], [MISSING])
- Add gitconfig volume mount to all Docker examples in Windows README
Disabled:
- Temporarily disable rename-content command pending further review
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:latest
# Or build locally from source
docker build -t ghcr.io/gocortexio/spellbook .
# Create a content instance
docker run --rm \
-v $(pwd):/content \
-v ~/.gitconfig:/home/spellbook/.gitconfig:ro \
ghcr.io/gocortexio/spellbook init my-content --author "Your Organisation" --no-ci
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"Licence
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full licence text.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
v1.20.0
GoCortex Spellbook v1.20
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
Features:
- Add summon correlation command for importing correlation rules from Cortex Platform JSON exports,
- Add --message (-m) flag for custom commit messages when using --tag supporting CI/CD integration (e.g. auto-closing issues)
- Add Git repository check before tag creation to prevent errors in uninitialised repositories
- Add trigger playbook template
Improvements:
- Standardise all CLI output to grepable format with status tags at column 0 ([OK], [ERROR], [WARN], [INFO], [PASS], [FAIL], [MISSING])
- Add gitconfig volume mount to all Docker examples in Windows README
Disabled:
- Temporarily disable rename-content command pending further review
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:latest
# Or build locally from source
docker build -t ghcr.io/gocortexio/spellbook .
# Create a content instance
docker run --rm \
-v $(pwd):/content \
-v ~/.gitconfig:/home/spellbook/.gitconfig:ro \
ghcr.io/gocortexio/spellbook init my-content --author "Your Organisation" --no-ci
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"Licence
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full licence text.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
v1.19.0
GoCortex Spellbook v1.19.0
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
FEATURES:
- Git tag support added for version management via set-version command using the --tag flag
- Single operation now stages all pack files, commits changes, and creates a Git tag
- New XSIAMDashboard and XSIAMReport example content types added
- Pinned Demisto SDK to v1.38.18 instead of using the latest version
FIXES:
- Linting removed from validate and build commands to resolve demisto-sdk issues
- Validation now limited to schema and structural checks
- Unnecessary Docker configuration file removed
- Ensure 'list-packs' and 'validate-all' now skip SamplePack created as part of init
DOCUMENTATION:
- Command reference tables updated with init, check-init, list-instances, and upload
- check-init and upload documented to require -e flags for DEMISTO_BASE_URL, DEMISTO_API_KEY, and XSIAM_AUTH_ID
- Added README_LOCAL-DOCKER-WINDOWS.md for Windows users needing local Docker setup
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:latest
# Or build locally from source
docker build -t ghcr.io/gocortexio/spellbook .
# Create a content instance
docker run --rm \
-v $(pwd):/content \
-v ~/.gitconfig:/home/spellbook/.gitconfig:ro \
ghcr.io/gocortexio/spellbook init my-content --author "Your Organisation" --no-ci
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"Licence
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full licence text.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
v1.18.10
GoCortex Spellbook v1.18.10
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
- New template example for Scheduled Correlation rules
- XSIAMDashboards folder now included in template structure
- GitLab CI/CD support with .gitlab-ci.yml template and Package Registry publishing
- check-init command to validate instance environment and configuration
- All Docker commands in documentation now include the gitconfig mount requirement: -v ~/.gitconfig:/home/spellbook/.gitconfig:ro
- Zip filename format changed from PackName-1.0.0.zip to PackName-v1.0.0.zip to match Git tag format used in CI/CD pipelines
- Upload command accepts pack directories only; pre-built zip upload removed
Features
- Instance initialisation with optional GitHub Actions templates
- Multi-pack support within a single content instance
- Content renaming to fix naming mismatches after copying packs
- Validation and linting using demisto-sdk
- Automated packaging into distributable zip files
- Direct upload to Cortex Platform instances
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:latest
# Or build locally from source
docker build -t ghcr.io/gocortexio/spellbook .
# Create a content instance
docker run --rm -v $(pwd):/content ghcr.io/gocortexio/spellbook init my-content --author "My Organisation"
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"
# Build all packs
docker run --rm -v $(pwd):/content ghcr.io/gocortexio/spellbook build --allCommands
| Command | Description |
|---|---|
| init | Create a new content instance with starter pack |
| create | Create a new pack from template |
| rename-content | Rename content items to match pack name |
| list-packs | List all discovered packs |
| validate | Validate a pack using demisto-sdk |
| validate-all | Validate all packs |
| lint | Lint a pack using demisto-sdk pre-commit |
| build | Build and package packs |
| upload | Upload a pack to Cortex Platform |
| version | Show version information for a pack |
| set-version | Set a specific version for a pack |
| bump-version | Automatically increment pack version |
Instance Structure
After running init, your instance has this structure:
my-content/
|-- .github/workflows/ # CI/CD pipelines (if enabled)
| |-- build.yml # Builds packs on version tags
| +-- validate.yml # Validates packs on PRs
|-- Packs/
| +-- SamplePack/ # Starter pack with examples
| |-- pack_metadata.json
| |-- README.md
| |-- CorrelationRules/
| |-- ParsingRules/
| +-- ModelingRules/
|-- artifacts/ # Built zip files (gitignored)
+-- spellbook.yaml # Build configuration
Configuration
Each instance has a spellbook.yaml file:
packs_directory: Packs
artifacts_directory: artifacts
defaults:
support: community
author: "Your Organisation"
marketplaces:
- xsoar
- marketplacev2
exclude_packs: []
validation:
enabled: true
allow_warnings: true
packaging:
create_zip: trueVersion Management
Pack versions are stored in pack_metadata.json within each pack. Use these commands to manage versions:
# Show current version
gocortex-spellbook version SamplePack
# Set a specific version
gocortex-spellbook set-version SamplePack 2.0.0
# Increment revision (1.0.0 -> 1.0.1) - default behaviour
gocortex-spellbook bump-version SamplePack
# Increment revision explicitly (1.0.0 -> 1.0.1)
gocortex-spellbook bump-version SamplePack --revision
# Increment minor version (1.0.0 -> 1.1.0)
gocortex-spellbook bump-version SamplePack --minor
# Increment major version (1.0.0 -> 2.0.0)
gocortex-spellbook bump-version SamplePack --majorGit tags (format: PackName-v1.0.0) can be used to trigger CI/CD builds but are not required for local development.
Licence
This project is available under the MIT Licence.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
v1.18.0
GoCortex Spellbook v1.18.0
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release
- Add GitLab CI/CD support (.gitlab-ci.yml) with validate, build, and release stages
- Add bump-version --tag auto-commit: now commits version changes before creating Git tag
- Add upload command documentation with environment variable examples (-e and --env-file)
- Enhanced .gitignore template to exclude sensitive files: .env, .env., *.key, *.pem, *.p12, *.pfx, *.log, Desktop.ini
Features
- Instance initialisation with optional GitHub Actions templates
- Multi-pack support within a single content instance
- Content renaming to fix naming mismatches after copying packs
- Validation and linting using demisto-sdk
- Automated packaging into distributable zip files
- Direct upload to Cortex Platform instances
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:latest
# Or build locally from source
docker build -t ghcr.io/gocortexio/spellbook .
# Create a content instance
docker run --rm -v $(pwd):/content ghcr.io/gocortexio/spellbook init my-content --author "My Organisation"
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"
# Build all packs
docker run --rm -v $(pwd):/content ghcr.io/gocortexio/spellbook build --allCommands
| Command | Description |
|---|---|
| init | Create a new content instance with starter pack |
| create | Create a new pack from template |
| rename-content | Rename content items to match pack name |
| list-packs | List all discovered packs |
| validate | Validate a pack using demisto-sdk |
| validate-all | Validate all packs |
| lint | Lint a pack using demisto-sdk pre-commit |
| build | Build and package packs |
| upload | Upload a pack to Cortex Platform |
| version | Show version information for a pack |
| set-version | Set a specific version for a pack |
| bump-version | Automatically increment pack version |
Instance Structure
After running init, your instance has this structure:
my-content/
|-- .github/workflows/ # CI/CD pipelines (if enabled)
| |-- build.yml # Builds packs on version tags
| +-- validate.yml # Validates packs on PRs
|-- Packs/
| +-- SamplePack/ # Starter pack with examples
| |-- pack_metadata.json
| |-- README.md
| |-- CorrelationRules/
| |-- ParsingRules/
| +-- ModelingRules/
|-- artifacts/ # Built zip files (gitignored)
+-- spellbook.yaml # Build configuration
Configuration
Each instance has a spellbook.yaml file:
packs_directory: Packs
artifacts_directory: artifacts
defaults:
support: community
author: "Your Organisation"
marketplaces:
- xsoar
- marketplacev2
exclude_packs: []
validation:
enabled: true
allow_warnings: true
packaging:
create_zip: trueVersion Management
Pack versions are stored in pack_metadata.json within each pack. Use these commands to manage versions:
# Show current version
gocortex-spellbook version SamplePack
# Set a specific version
gocortex-spellbook set-version SamplePack 2.0.0
# Increment revision (1.0.0 -> 1.0.1) - default behaviour
gocortex-spellbook bump-version SamplePack
# Increment revision explicitly (1.0.0 -> 1.0.1)
gocortex-spellbook bump-version SamplePack --revision
# Increment minor version (1.0.0 -> 1.1.0)
gocortex-spellbook bump-version SamplePack --minor
# Increment major version (1.0.0 -> 2.0.0)
gocortex-spellbook bump-version SamplePack --majorGit tags (format: PackName-v1.0.0) can be used to trigger CI/CD builds but are not required for local development.
Licence
This project is available under the MIT Licence.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide
v1.17.5
GoCortex Spellbook v1.17.5
A Python toolset for building, validating, and packaging Cortex Platform content packs.
Overview
GoCortex Spellbook is a toolset for building, validating, and packaging Cortex Platform content packs. It solves the problem of creating compliant content packs without needing to understand the intricacies of the demisto-sdk and Cortex Platform schema requirements.
- Creates new content pack instances with correct structure
- Generates XSIAM content templates (CorrelationRules, ParsingRules, ModelingRules)
- Validates content against Cortex Platform schemas using demisto-sdk
- Packages content into uploadable zip files
- Uploads content directly to Cortex Platform instances
The demisto-sdk is powerful but complex. Spellbook wraps it in a simpler interface and provides working templates that have been verified to upload successfully.
New In This Release (should have been in 1.17.0!)
Container Security:
- Add non-root spellbook user (UID/GID 1000) to Dockerfile to stop Snyk complaining
- Configure proper ownership for /app and /content directories
Build Workflow:
- Rename build.yml to conjure.yml because I think its more fun
- Fixed pesky permissions issue that prevented the write
Features
- Instance initialisation with optional GitHub Actions templates
- Multi-pack support within a single content instance
- Content renaming to fix naming mismatches after copying packs
- Validation and linting using demisto-sdk
- Automated packaging into distributable zip files
- Direct upload to Cortex Platform instances
Workflow Guides
Choose your preferred method and follow the corresponding guide:
| Method | Best For | Guide |
|---|---|---|
| Docker (Local) | Most users. No Python setup required. | README_LOCAL-DOCKER.md |
| Source (Local) | Developers who want to modify Spellbook. | README_SOURCE.md |
| CI/CD | Automated builds triggered by Git tags. | README_CICD.md |
Quick Start (Docker)
# Pull from GitHub Container Registry (preferred)
docker pull ghcr.io/gocortexio/spellbook:latest
# Or build locally from source
docker build -t ghcr.io/gocortexio/spellbook .
# Create a content instance
docker run --rm -v $(pwd):/content ghcr.io/gocortexio/spellbook init my-content --author "My Organisation"
# Initialise Git (required for validation)
cd my-content
git init
git add .
git commit -s -m "Initial commit"
# Build all packs
docker run --rm -v $(pwd):/content ghcr.io/gocortexio/spellbook build --allCommands
| Command | Description |
|---|---|
| init | Create a new content instance with starter pack |
| create | Create a new pack from template |
| rename-content | Rename content items to match pack name |
| list-packs | List all discovered packs |
| validate | Validate a pack using demisto-sdk |
| validate-all | Validate all packs |
| lint | Lint a pack using demisto-sdk pre-commit |
| build | Build and package packs |
| upload | Upload a pack to Cortex Platform |
| version | Show version information for a pack |
| set-version | Set a specific version for a pack |
| bump-version | Automatically increment pack version |
Instance Structure
After running init, your instance has this structure:
my-content/
|-- .github/workflows/ # CI/CD pipelines (if enabled)
| |-- build.yml # Builds packs on version tags
| +-- validate.yml # Validates packs on PRs
|-- Packs/
| +-- SamplePack/ # Starter pack with examples
| |-- pack_metadata.json
| |-- README.md
| |-- CorrelationRules/
| |-- ParsingRules/
| +-- ModelingRules/
|-- artifacts/ # Built zip files (gitignored)
+-- spellbook.yaml # Build configuration
Configuration
Each instance has a spellbook.yaml file:
packs_directory: Packs
artifacts_directory: artifacts
defaults:
support: community
author: "Your Organisation"
marketplaces:
- xsoar
- marketplacev2
exclude_packs: []
validation:
enabled: true
allow_warnings: true
packaging:
create_zip: trueVersion Management
Pack versions are stored in pack_metadata.json within each pack. Use these commands to manage versions:
# Show current version
gocortex-spellbook version SamplePack
# Set a specific version
gocortex-spellbook set-version SamplePack 2.0.0
# Increment revision (1.0.0 -> 1.0.1) - default behaviour
gocortex-spellbook bump-version SamplePack
# Increment revision explicitly (1.0.0 -> 1.0.1)
gocortex-spellbook bump-version SamplePack --revision
# Increment minor version (1.0.0 -> 1.1.0)
gocortex-spellbook bump-version SamplePack --minor
# Increment major version (1.0.0 -> 2.0.0)
gocortex-spellbook bump-version SamplePack --majorGit tags (format: PackName-v1.0.0) can be used to trigger CI/CD builds but are not required for local development.
Licence
This project is available under the MIT Licence.
References
- Cortex Platform Content Pack Format: https://xsoar.pan.dev/docs/packs/packs-format
- Demisto SDK Documentation: https://docs-cortex.paloaltonetworks.com/r/1/Demisto-SDK-Guide