cascadeguard 0.1.0

Guardian of the container cascade — event-driven image lifecycle management

CascadeGuard

Guardian of the container cascade. Event-driven image & tooling lifecycle management that integrates with your build & deployment tooling to eliminate vulnerability to supply chain attacks.

Quick Start

# Install (macOS / Linux)
curl -sSL https://raw.githubusercontent.com/cascadeguard/cascadeguard/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/cascadeguard/cascadeguard/main/install.ps1 | iex

Then in your state repository:

cg images init                   # Scaffold from seed repo (includes workflows)
cg images validate               # Validate images.yaml
cg images check                  # Discover base images, check drift and upstream tags

Requires Python 3.11+. Both cg and cascadeguard are installed as aliases.

How It Works

1. Image Enrollment: Images are defined in images.yaml in a state repository
2. State Files: Detailed configuration for each image in base-images/ and images/ directories
3. Kubernetes Manifest Generation: Uses CDK8s under the hood to generate manifests for popular kubernetes based tools like Kargo, ArgoCD, etc

Using CascadeGuard

1. Install

# macOS / Linux
curl -sSL https://raw.githubusercontent.com/cascadeguard/cascadeguard/main/install.sh | sh

2. Set up your state repository

Scaffold a new state repository from the seed repo:

mkdir my-images && cd my-images && git init
cg images init

Or create an images.yaml and .cascadeguard.yaml manually:

# .cascadeguard.yaml
defaults:
  registry: ghcr.io/myorg
  local:
    dir: images        # folder containing per-image Dockerfiles

ci:
  platform: github

# images.yaml — managed images inherit registry from .cascadeguard.yaml
- name: nginx
  dockerfile: images/nginx/Dockerfile
  image: nginx
  tag: stable-alpine-slim

# Upstream-tracked images (CVE monitoring only, no build)
- name: memcached
  enabled: false
  namespace: library

3. Validate, generate, and build

# Validate images.yaml (applies config defaults before checking)
cg images validate

# Enrol a new image
cg images enrol --name myapp --registry ghcr.io --repository org/myapp

# Check for base image drift and new upstream tags
cg images check
cg images check --format json    # JSON output for CI consumption
cg images check --image myapp    # Scope to a single image

# Generate CI/CD pipeline files (GitHub Actions)
cg build generate

# Generate CI with explicit platform or dry-run
cg build generate --platform github --dry-run

See cascadeguard-exemplar for a complete working example.

Config Inheritance

Common fields can be set once in .cascadeguard.yaml under defaults instead of repeating them on every image:

Key	Description
defaults.registry	Default container registry (e.g. ghcr.io/cascadeguard)
defaults.repository	Default repository prefix
defaults.local.dir	Default folder containing per-image Dockerfiles

Per-image values in images.yaml always override the defaults.

Generating CI/CD Pipelines

cg build generate reads images.yaml and emits four GitHub Actions workflow files under .github/workflows/:

File	Trigger	Purpose
build-image.yaml	workflow_call	Reusable single-image build, scan (Grype + Trivy), SBOM, and Cosign signing
ci.yaml	push to main, pull_request	Matrix build of all images; pushes and signs on merge to main
scheduled-scan.yaml	Nightly cron + workflow_dispatch	Re-scans all published images; opens a GitHub Issue on new CVEs
release.yaml	Tag push (v*)	Builds, signs, and pushes all images; creates a GitHub Release with changelog

cg build generate
cg build generate --dry-run    # preview without writing

Commit the generated files. Adding a new image to images.yaml and re-running cg build generate will automatically include it in every pipeline.

Overview

CascadeGuard automates the process of monitoring base images and shared build steps (github action workflows & steps, Gitlab pipelines, etc), discovering Dockerfile dependencies, package vulnerabilities and orchestrating intelligent pinning & container image rebuilds.

Licensing

CascadeGuard is licensed under the Business Source License 1.1 (BUSL-1.1).

You are free to use, copy, modify, and distribute CascadeGuard for non-production purposes. Production use is permitted provided you are not offering CascadeGuard to third parties as a commercial container image lifecycle management service or a managed image rebuild service.

Each version of CascadeGuard automatically converts to the Apache License 2.0 four years after its first public release.

For commercial licensing enquiries, contact [e-mail].