Skip to content

v1.17.5

Choose a tag to compare

View all tags
@simonsigre simonsigre released this 23 Dec 01:12
· 14 commits to main since this release
v1.17.5
4d90d84

GoCortex Spellbook

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

Commands

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

Version 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 --major

Git 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

Assets 2
Loading