Techcle Wiki

Cascadeguard

4 min read

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:

KeyDescription
defaults.registryDefault container registry (e.g. ghcr.io/cascadeguard)
defaults.repositoryDefault repository prefix
defaults.local.dirDefault 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/:

FileTriggerPurpose
build-image.yamlworkflow_callReusable single-image build, scan (Grype + Trivy), SBOM, and Cosign signing
ci.yamlpush to main, pull_requestMatrix build of all images; pushes and signs on merge to main
scheduled-scan.yamlNightly cron + workflow_dispatchRe-scans all published images; opens a GitHub Issue on new CVEs
release.yamlTag 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 licensing@cascadeguard.com.

Repository Structure

.
├── app/                    # Python analysis tool for Dockerfile parsing and state generation
├── cdk8s/                  # CDK8s application for generating kubernetes resources
│   ├── lib/                # Reusable CDK8s constructs
│   ├── imports/            # Generated CRD imports
│   └── main.py             # Main CDK8s application
├── tests/                  # Integration and acceptance tests
│   └── integration/        # Integration test suite
├── Dockerfile              # Builds the CascadeGuard Docker image
├── Taskfile.docker.yaml    # Internal Taskfile (baked into Docker image)
├── Taskfile.shared.yaml    # Shared tasks for state repos (docker run wrappers)
└── Taskfile.yaml           # Developer tasks for this repo

Development

See Contributing for branch naming, PR process, and coding standards.

For local development setup (Python environments, testing, Docker builds), see the Development Guide.

Image Types

Base Images

Foundational container images that application images build upon. CascadeGuard monitors these for updates and triggers rebuilds of dependent images.

Managed Images

Built by your CI/CD pipeline. CascadeGuard discovers their Dockerfile dependencies and monitors the base images they use.

External Images

Third-party images tracked directly. CascadeGuard monitors these for new versions.

0 items under this folder.