Metadata-Version: 2.4
Name: cascadeguard
Version: 0.1.0
Summary: Guardian of the container cascade — event-driven image lifecycle management
Author-email: CascadeGuard <hello@cascadeguard.com>
License-Expression: BUSL-1.1
Project-URL: Homepage, https://cascadeguard.com
Project-URL: Documentation, https://docs.cascadeguard.com
Project-URL: Repository, https://github.com/cascadeguard/cascadeguard
Project-URL: Issues, https://github.com/cascadeguard/cascadeguard/issues
Keywords: containers,docker,image-lifecycle,kargo,argocd,gitops,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# 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

```bash
# 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:

```bash
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

```bash
# 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:

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

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

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

ci:
  platform: github
```

```yaml
# 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

```bash
# 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](https://github.com/cascadeguard/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 |

```bash
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](LICENSE) (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](https://www.apache.org/licenses/LICENSE-2.0) four years after its first public release.

For commercial licensing enquiries, contact [licensing@cascadeguard.com](mailto:licensing@cascadeguard.com).
