Chainguard Images

Minimal zero-CVE container images built on Wolfi Linux for secure software supply chains.

Getting Started

Pulling Images

Command	Description
docker pull cgr.dev/chainguard/static:latest	Pull minimal static base image
docker pull cgr.dev/chainguard/busybox:latest	Pull busybox image for debugging
docker pull cgr.dev/chainguard/wolfi-base:latest	Pull Wolfi base image with shell
docker pull cgr.dev/chainguard/python:latest	Pull Python runtime image
docker pull cgr.dev/chainguard/node:latest	Pull Node.js runtime image
docker pull cgr.dev/chainguard/go:latest	Pull Go build image
docker pull cgr.dev/chainguard/nginx:latest	Pull nginx web server image
docker pull cgr.dev/chainguard/git:latest	Pull minimal git image
docker pull cgr.dev/chainguard/jdk:latest	Pull Java JDK image
docker pull cgr.dev/chainguard/rust:latest	Pull Rust build image
docker pull cgr.dev/chainguard/redis:latest	Pull Redis server image
docker pull cgr.dev/chainguard/postgres:latest	Pull PostgreSQL image
docker pull cgr.dev/chainguard/curl:latest	Pull minimal curl image

Image Tags

Command	Description
:latest tag	Most recent build, production-ready
:latest-dev tag	Development variant with shell and package manager
:latest on -dev images	Includes apk, shell, and debugging tools
cgr.dev/chainguard-private/IMAGE	Private/enterprise image registry
Digest pinning @sha256:abc123...	Pin to exact image build for reproducibility

Image Usage

Basic Usage

Command	Description
FROM cgr.dev/chainguard/static:latest	Use static image in Dockerfile
FROM cgr.dev/chainguard/python:latest-dev	Use dev variant with pip and shell
FROM cgr.dev/chainguard/node:latest AS build	Use as build stage
FROM cgr.dev/chainguard/go:latest AS builder	Use Go image for compilation
docker run --rm cgr.dev/chainguard/wolfi-base sh	Run interactive shell
docker run --rm -p 8080:8080 cgr.dev/chainguard/nginx	Run nginx server
docker run --rm cgr.dev/chainguard/python -- python -c "print('hello')"	Run Python one-liner

Go Multi-Stage Build

# Build stage
FROM cgr.dev/chainguard/go:latest AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /server ./cmd/server

# Runtime stage - distroless, no shell, no package manager
FROM cgr.dev/chainguard/static:latest
COPY --from=builder /server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

Python Multi-Stage Build

# Build stage with pip available
FROM cgr.dev/chainguard/python:latest-dev AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
COPY . .

# Runtime stage - minimal Python, no pip, no shell
FROM cgr.dev/chainguard/python:latest
COPY --from=builder /install /usr/local
COPY --from=builder /app /app
WORKDIR /app
ENTRYPOINT ["python", "-m", "myapp"]

Node.js Multi-Stage Build

# Build stage
FROM cgr.dev/chainguard/node:latest-dev AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# Runtime stage
FROM cgr.dev/chainguard/node:latest
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
EXPOSE 3000
ENTRYPOINT ["node", "dist/index.js"]

Java Multi-Stage Build

# Build stage
FROM cgr.dev/chainguard/jdk:latest-dev AS builder
WORKDIR /app
COPY . .
RUN ./gradlew build --no-daemon -x test

# Runtime stage
FROM cgr.dev/chainguard/jre:latest
COPY --from=builder /app/build/libs/app.jar /app/app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

Discovery

Chainctl Operations

Command	Description
chainctl auth login	Authenticate with Chainguard
chainctl auth login --headless	Login in headless environments
chainctl auth configure-docker	Configure Docker to use Chainguard registry
chainctl images list	List available Chainguard images
chainctl images repos list --group=GROUP_ID	List image repos for a group
chainctl images diff IMAGE1 IMAGE2	Compare two image versions
chainctl images history cgr.dev/chainguard/python	Show image version history
Browse images.chainguard.dev	Web catalog of all images

Image Inspection

Command	Description
crane ls cgr.dev/chainguard/python	List available tags for an image
crane manifest cgr.dev/chainguard/python:latest	View image manifest
crane config cgr.dev/chainguard/python:latest	View image config
docker inspect cgr.dev/chainguard/python:latest	Inspect image metadata
docker history cgr.dev/chainguard/python:latest	View image layers
dive cgr.dev/chainguard/python:latest	Explore image layers interactively

Verification

Signature Verification

Command	Description
cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity-regexp='chainguard' cgr.dev/chainguard/python	Verify image signature
cosign verify-attestation --type spdx cgr.dev/chainguard/python	Verify SBOM attestation
cosign verify-attestation --type vuln cgr.dev/chainguard/python	Verify vulnerability attestation
cosign tree cgr.dev/chainguard/python	View supply chain artifacts
cosign verify-attestation --type slsaprovenance cgr.dev/chainguard/python	Verify SLSA provenance

Cosign Verification Example

# Verify the signature of a Chainguard image
cosign verify \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest

# Verify SBOM attestation and output it
cosign verify-attestation \
  --type spdx \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest | jq -r '.payload' | base64 -d | jq .

# Verify vulnerability scan attestation
cosign verify-attestation \
  --type vuln \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest

Vulnerability Scanning

Command	Description
grype cgr.dev/chainguard/python	Scan image for vulnerabilities with Grype
grype cgr.dev/chainguard/python --only-fixed	Show only fixable vulnerabilities
trivy image cgr.dev/chainguard/python	Scan with Trivy scanner
trivy image --severity HIGH,CRITICAL cgr.dev/chainguard/python	Scan for high/critical only
docker scout cves cgr.dev/chainguard/python	Scan with Docker Scout
chainctl images vulns cgr.dev/chainguard/python	View known vulnerabilities via chainctl

Wolfi APK Management

Package Operations

Command	Description
apk update	Update package index (in dev images)
apk add curl	Install a package
apk add --no-cache python3 py3-pip	Install without caching index
apk add --virtual .build-deps gcc musl-dev	Install virtual build dependencies
apk del .build-deps	Remove virtual package group
apk del curl	Remove a package
apk list --installed	List installed packages
apk search nginx	Search for available packages
apk info python3	Show package details
apk info -L python3	List files in a package

Building Custom Images

Melange Package Building

Command	Description
melange keygen	Generate signing keys for packages
melange build recipe.yaml --signing-key melange.rsa	Build APK package from recipe
melange build recipe.yaml --arch x86_64,aarch64	Build for multiple architectures
melange bump recipe.yaml 1.2.3	Bump version in recipe

Melange Recipe Example

package:
  name: myapp
  version: 1.0.0
  epoch: 0
  description: My custom application
  copyright:
    - license: Apache-2.0

environment:
  contents:
    packages:
      - build-base
      - go
      - ca-certificates-bundle

pipeline:
  - uses: git-checkout
    with:
      repository: https://github.com/org/myapp
      tag: v${{package.version}}

  - uses: go/build
    with:
      packages: ./cmd/myapp
      output: myapp
      ldflags: -s -w

  - uses: strip

Apko Image Building

Command	Description
apko build config.yaml tag output.tar	Build OCI image from YAML config
apko publish config.yaml tag	Build and push image to registry
apko build config.yaml tag output.tar --arch x86_64,aarch64	Build multi-arch image
docker load < output.tar	Load built image into Docker

Apko Config Example

contents:
  packages:
    - ca-certificates-bundle
    - wolfi-baselayout
    - myapp
  repositories:
    - https://packages.wolfi.dev/os
    - /path/to/local/packages

accounts:
  groups:
    - groupname: nonroot
      gid: 65532
  users:
    - username: nonroot
      uid: 65532
      gid: 65532
  run-as: 65532

entrypoint:
  command: /usr/bin/myapp

archs:
  - x86_64
  - aarch64

environment:
  APP_ENV: production
  PORT: "8080"

SBOM & Provenance

Supply Chain Artifacts

Command	Description
cosign download sbom cgr.dev/chainguard/python	Download image SBOM
syft cgr.dev/chainguard/python	Generate SBOM with Syft
syft cgr.dev/chainguard/python -o spdx-json	Generate SPDX SBOM
syft cgr.dev/chainguard/python -o cyclonedx-json	Generate CycloneDX SBOM
cosign download attestation cgr.dev/chainguard/python	Download all attestations
cosign verify-attestation --type slsaprovenance cgr.dev/chainguard/python	Verify SLSA provenance
chainctl images vulns cgr.dev/chainguard/python	View known vulnerabilities

Policy Enforcement

Kubernetes Admission Policy

# Sigstore Policy Controller - require Chainguard signatures
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: require-chainguard-signatures
spec:
  images:
    - glob: "cgr.dev/chainguard/**"
    - glob: "cgr.dev/chainguard-private/**"
  authorities:
    - keyless:
        url: https://fulcio.sigstore.dev
        identities:
          - issuerRegExp: ".*"
            subjectRegExp: ".*chainguard.*"
        ctlog:
          url: https://rekor.sigstore.dev

Kyverno Policy Example

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-chainguard-images
spec:
  validationFailureAction: Enforce
  background: true
  rules:
    - name: check-image-registry
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "Only Chainguard images from cgr.dev are allowed."
        pattern:
          spec:
            containers:
              - image: "cgr.dev/chainguard/*"
            initContainers:
              - image: "cgr.dev/chainguard/*"

CI/CD Verification Pipeline

# GitHub Actions - verify and scan before deployment
name: Image Verification
on:
  push:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - name: Install cosign
        uses: sigstore/cosign-installer@v3

      - name: Verify image signature
        run: |
          cosign verify \
            --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
            --certificate-identity-regexp="chainguard" \
            cgr.dev/chainguard/python:latest

      - name: Scan for vulnerabilities
        uses: anchore/grype-action@v0
        with:
          image: cgr.dev/chainguard/python:latest
          fail-on: high

Best Practices

1. Use multi-stage builds — build in -dev images (which have compilers and package managers) and copy only the final artifact into the minimal runtime image.

2. Pin images by digest — use @sha256:... digests instead of tags for production deployments to guarantee reproducibility.

3. Choose the right base image — use static for compiled binaries with no OS dependencies, wolfi-base when you need a shell, and language-specific images for interpreted languages.

4. Verify signatures in CI/CD — always verify Chainguard image signatures with cosign before building or deploying.

5. Scan even zero-CVE images — run vulnerability scans as a validation step; Chainguard images should return zero findings, confirming your pipeline is using genuine images.

6. Use -dev variants only in build stages — never ship -dev images to production; they include tools that increase attack surface.

7. Run as nonroot — Chainguard images default to nonroot user; maintain this in your Dockerfiles by not switching to root.

8. Enforce image policies — use Kyverno, OPA Gatekeeper, or Sigstore Policy Controller to restrict container registries in your clusters.

9. Generate and store SBOMs — use Syft or cosign to download SBOMs for compliance and audit trails.

10. Keep images up to date — Chainguard rebuilds images frequently; update your digests regularly to pick up the latest security patches.