Getting Started

Getting Started with CascadeGuard Image Factory

Image Factory is the end-to-end image lifecycle process that CascadeGuard automates: detect upstream base image changes → rebuild your images via your existing CI/CD pipeline → roll out updated images to your deployments. It is implemented by the cg images command group.

CascadeGuard also provides cg tools — a separate set of supply chain utilities for your CI/CD tooling itself: pin GitHub Actions to verified commit SHAs, audit workflow files against a policy, and scaffold policy configuration. These work on any repository, not just image build repos.

---

New to CascadeGuard? Two ways to get value immediately:

I want to…	Start here
Automate image builds and keep base images up to date	This guide — Image Factory quick start
Pin and audit GitHub Actions in my CI pipelines	Supply Chain Automation guide
Drop in a hardened base image right now	CascadeGuard Secure Images
Understand how it all fits together	Security Model

---

CascadeGuard Image Factory automates container image lifecycle management. It monitors base images for updates, discovers Dockerfile dependencies, identifies vulnerabilities and orchestrates intelligent rebuilds through your existing build tools & processes.

Prerequisites

• Python 3.11+ (installed automatically via the install script)
• A repository to use as your state repository

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

This installs CascadeGuard to ~/.cascadeguard and adds it to your PATH as cascadeguard and cg.

Concepts

State Repository

CascadeGuard is driven by a state repository — a Git repo that declares which images you manage and tracks their current state. It contains:

• images.yaml — enrollment configuration for all managed images
• .cascadeguard.yaml — repo-level defaults and tool configuration
• base-images/ — tracked upstream base image state (generated)
• images/ — per-image state files (generated)
• .github/workflows/ — auto-generated CI pipelines (generated)

See cascadeguard-exemplar and cascadeguard-open-secure-images for complete working examples, and cascadeguard-seed for the seed repo thats used when cg images init is used.

Image Types

Type	Description
Base images	Foundational images your application images build from. CascadeGuard monitors these for updates and triggers rebuilds of dependents.
Managed images	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 for new versions.

Quick Start

1. Initialise your repo (optional)

cg images init

Init pulls the latest seed from cascadeguard-seed giving you a ready to go starting point, including:

• An example image you can build to see it working
• A PR Checker that validates images.yaml to prevent mistakes being merged to main
• A daily scheduled task to monitor the upstream image(s) of your images

You can set repo-level defaults so you don’t repeat common fields on every image:

# .cascadeguard.yaml
defaults:
  registry: ghcr.io/your-org       # applied to all images missing a registry
  local:
    dir: images                     # folder containing per-image Dockerfiles
 
ci:
  platform: github

2. Create images.yaml

This file is where the images CascadeGuard should monitor & manage are defined. Config from .cascadeguard.yaml defaults if not set per-image.

The content can be added to this file directly in the yaml:

# Managed images — CascadeGuard builds, scans, and signs these
- name: my-app
  dockerfile: images/my-app/Dockerfile
  image: my-app
  tag: latest
 
# Upstream-tracked images — CVE monitoring only, no build
- name: memcached
  enabled: false
  namespace: library

Or by using the images enrol method:

cg images enrol \
  --name my-new-service \
  --registry ghcr.io \
  --repository your-org/my-new-service

3. Validate your configuration

cg images validate

Verifies that the state in images.yaml and .cascadeguard.yaml is valid. This can be used in a PR check or similar.

5. Generate state files

cg images generate

This reads images.yaml, analyzes Dockerfiles to discover base image dependencies, and writes state files to base-images/ and images/.

6. Generate CI pipelines

cg tools generate

This emits the GitHub Actions workflow files under .github/workflows/ based on the cascadeguard-seed repository:

File	Trigger	Purpose
build-image.yaml	workflow_call	Reusable single-image build, scan, SBOM, and signing
ci.yaml	Push to main, pull requests	Matrix build of all images
check.yaml	Nightly cron	Re-scans all published images; opens issues on new CVEs
release.yaml	Tag push (v*)	Builds, signs, and pushes all images

Use --dry-run to preview without writing files:

cg tools generate --dry-run

7. Commit and push

git add images.yaml .cascadeguard.yaml .github/workflows/ .cascadeguard
git commit -m "Initial CascadeGuard state"
git push

Config Inheritance

.cascadeguard.yaml supports a defaults section. Any field set here is applied to every image in images.yaml that doesn’t already have that field:

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 always take precedence over defaults. Disabled images (enabled: false) only require a name field.

Checking image status

cg images status
cg images check

Next Steps

• GitHub Actions Integration Guide — how the generated CI pipelines work and how to customize them
• CLI Reference — full command reference
• images.yaml Reference — schema and options
• Security Model — how CascadeGuard handles scanning, SBOMs, and signing

How-to Guides

End-to-end walkthroughs for specific CI/CD combinations:

• GitHub CI + Cloudflare CD — GitHub Actions for image build/scan/sign, Cloudflare Pages/Workers for deployment (CascadeGuard’s own setup)
• GitLab CI + Argo CD — GitLab CI/CD pipelines with Argo CD and Kargo for Kubernetes deployment