Chainguard Images

Immagini container minimali a zero CVE costruite su Wolfi Linux per catene di fornitura software sicure.

Per Iniziare

Download delle Immagini

Comando	Descrizione
`docker pull cgr.dev/chainguard/static:latest`	Scarica immagine base statica minimale
`docker pull cgr.dev/chainguard/busybox:latest`	Scarica immagine busybox per debug
`docker pull cgr.dev/chainguard/wolfi-base:latest`	Scarica immagine base Wolfi con shell
`docker pull cgr.dev/chainguard/python:latest`	Scarica immagine runtime Python
`docker pull cgr.dev/chainguard/node:latest`	Scarica immagine runtime Node.js
`docker pull cgr.dev/chainguard/go:latest`	Scarica immagine di build Go
`docker pull cgr.dev/chainguard/nginx:latest`	Scarica immagine web server nginx
`docker pull cgr.dev/chainguard/git:latest`	Scarica immagine git minimale
`docker pull cgr.dev/chainguard/jdk:latest`	Scarica immagine Java JDK
`docker pull cgr.dev/chainguard/rust:latest`	Scarica immagine di build Rust
`docker pull cgr.dev/chainguard/redis:latest`	Scarica immagine server Redis
`docker pull cgr.dev/chainguard/postgres:latest`	Scarica immagine PostgreSQL
`docker pull cgr.dev/chainguard/curl:latest`	Scarica immagine curl minimale

Tag delle Immagini

Comando	Descrizione
Tag `:latest`	Build piu recente, pronta per la produzione
Tag `:latest-dev`	Variante di sviluppo con shell e gestore pacchetti
`:latest` sulle immagini `-dev`	Include apk, shell e strumenti di debug
`cgr.dev/chainguard-private/IMAGE`	Registro immagini privato/enterprise
Pinning del digest `@sha256:abc123...`	Fissa a una build esatta dell’immagine per la riproducibilita

Utilizzo delle Immagini

Utilizzo Base

Comando	Descrizione
`FROM cgr.dev/chainguard/static:latest`	Usa immagine statica nel Dockerfile
`FROM cgr.dev/chainguard/python:latest-dev`	Usa variante dev con pip e shell
`FROM cgr.dev/chainguard/node:latest AS build`	Usa come fase di build
`FROM cgr.dev/chainguard/go:latest AS builder`	Usa immagine Go per la compilazione
`docker run --rm cgr.dev/chainguard/wolfi-base sh`	Esegui shell interattiva
`docker run --rm -p 8080:8080 cgr.dev/chainguard/nginx`	Esegui server nginx
`docker run --rm cgr.dev/chainguard/python -- python -c "print('hello')"`	Esegui one-liner Python

Build Multi-Stage Go

# Fase di build
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

# Fase runtime - distroless, senza shell, senza gestore pacchetti
FROM cgr.dev/chainguard/static:latest
COPY --from=builder /server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

Build Multi-Stage Python

# Fase di build con pip disponibile
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 . .

# Fase runtime - Python minimale, senza pip, senza shell
FROM cgr.dev/chainguard/python:latest
COPY --from=builder /install /usr/local
COPY --from=builder /app /app
WORKDIR /app
ENTRYPOINT ["python", "-m", "myapp"]

Build Multi-Stage Node.js

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

# Fase runtime
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"]

Build Multi-Stage Java

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

# Fase runtime
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"]

Scoperta

Operazioni Chainctl

Comando	Descrizione
`chainctl auth login`	Autenticati con Chainguard
`chainctl auth login --headless`	Login in ambienti headless
`chainctl auth configure-docker`	Configura Docker per usare il registro Chainguard
`chainctl images list`	Elenca le immagini Chainguard disponibili
`chainctl images repos list --group=GROUP_ID`	Elenca i repo immagini per un gruppo
`chainctl images diff IMAGE1 IMAGE2`	Confronta due versioni di immagine
`chainctl images history cgr.dev/chainguard/python`	Mostra la cronologia delle versioni dell’immagine
Naviga su `images.chainguard.dev`	Catalogo web di tutte le immagini

Ispezione delle Immagini

Comando	Descrizione
`crane ls cgr.dev/chainguard/python`	Elenca i tag disponibili per un’immagine
`crane manifest cgr.dev/chainguard/python:latest`	Visualizza il manifest dell’immagine
`crane config cgr.dev/chainguard/python:latest`	Visualizza la configurazione dell’immagine
`docker inspect cgr.dev/chainguard/python:latest`	Ispeziona i metadati dell’immagine
`docker history cgr.dev/chainguard/python:latest`	Visualizza i layer dell’immagine
`dive cgr.dev/chainguard/python:latest`	Esplora i layer dell’immagine interattivamente

Verifica

Verifica delle Firme

Comando	Descrizione
`cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity-regexp='chainguard' cgr.dev/chainguard/python`	Verifica la firma dell’immagine
`cosign verify-attestation --type spdx cgr.dev/chainguard/python`	Verifica attestazione SBOM
`cosign verify-attestation --type vuln cgr.dev/chainguard/python`	Verifica attestazione vulnerabilita
`cosign tree cgr.dev/chainguard/python`	Visualizza artefatti della supply chain
`cosign verify-attestation --type slsaprovenance cgr.dev/chainguard/python`	Verifica provenienza SLSA

Esempio di Verifica Cosign

# Verifica la firma di un'immagine Chainguard
cosign verify \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest

# Verifica attestazione SBOM e visualizza l'output
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 .

# Verifica attestazione di scansione vulnerabilita
cosign verify-attestation \
  --type vuln \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest

Scansione delle Vulnerabilita

Comando	Descrizione
`grype cgr.dev/chainguard/python`	Scansiona immagine per vulnerabilita con Grype
`grype cgr.dev/chainguard/python --only-fixed`	Mostra solo vulnerabilita risolvibili
`trivy image cgr.dev/chainguard/python`	Scansiona con scanner Trivy
`trivy image --severity HIGH,CRITICAL cgr.dev/chainguard/python`	Scansiona solo per alta/critica
`docker scout cves cgr.dev/chainguard/python`	Scansiona con Docker Scout
`chainctl images vulns cgr.dev/chainguard/python`	Visualizza vulnerabilita note tramite chainctl

Gestione Pacchetti APK Wolfi

Operazioni sui Pacchetti

Comando	Descrizione
`apk update`	Aggiorna l’indice dei pacchetti (nelle immagini dev)
`apk add curl`	Installa un pacchetto
`apk add --no-cache python3 py3-pip`	Installa senza cache dell’indice
`apk add --virtual .build-deps gcc musl-dev`	Installa dipendenze di build virtuali
`apk del .build-deps`	Rimuovi gruppo di pacchetti virtuali
`apk del curl`	Rimuovi un pacchetto
`apk list --installed`	Elenca pacchetti installati
`apk search nginx`	Cerca pacchetti disponibili
`apk info python3`	Mostra dettagli del pacchetto
`apk info -L python3`	Elenca file in un pacchetto

Costruzione di Immagini Personalizzate

Build di Pacchetti con Melange

Comando	Descrizione
`melange keygen`	Genera chiavi di firma per i pacchetti
`melange build recipe.yaml --signing-key melange.rsa`	Build pacchetto APK dalla ricetta
`melange build recipe.yaml --arch x86_64,aarch64`	Build per architetture multiple
`melange bump recipe.yaml 1.2.3`	Aggiorna versione nella ricetta

Esempio di Ricetta Melange

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

Build di Immagini con Apko

Comando	Descrizione
`apko build config.yaml tag output.tar`	Build immagine OCI da configurazione YAML
`apko publish config.yaml tag`	Build e push dell’immagine nel registro
`apko build config.yaml tag output.tar --arch x86_64,aarch64`	Build immagine multi-architettura
`docker load < output.tar`	Carica immagine costruita in Docker

Esempio di Configurazione Apko

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 e Provenienza

Artefatti della Supply Chain

Comando	Descrizione
`cosign download sbom cgr.dev/chainguard/python`	Scarica SBOM dell’immagine
`syft cgr.dev/chainguard/python`	Genera SBOM con Syft
`syft cgr.dev/chainguard/python -o spdx-json`	Genera SBOM in formato SPDX
`syft cgr.dev/chainguard/python -o cyclonedx-json`	Genera SBOM in formato CycloneDX
`cosign download attestation cgr.dev/chainguard/python`	Scarica tutte le attestazioni
`cosign verify-attestation --type slsaprovenance cgr.dev/chainguard/python`	Verifica provenienza SLSA
`chainctl images vulns cgr.dev/chainguard/python`	Visualizza vulnerabilita note

Applicazione delle Policy

Policy di Ammissione Kubernetes

# Sigstore Policy Controller - richiedi firme Chainguard
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

Esempio di Policy Kyverno

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/*"

Pipeline di Verifica CI/CD

# GitHub Actions - verifica e scansiona prima della distribuzione
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

Buone Pratiche

Usa build multi-stage — compila nelle immagini -dev (che hanno compilatori e gestori di pacchetti) e copia solo l’artefatto finale nell’immagine runtime minimale.
Fissa le immagini per digest — usa i digest @sha256:... invece dei tag per le distribuzioni in produzione per garantire la riproducibilita.
Scegli l’immagine base giusta — usa static per binari compilati senza dipendenze dal sistema operativo, wolfi-base quando hai bisogno di una shell, e immagini specifiche per linguaggio per i linguaggi interpretati.
Verifica le firme nella CI/CD — verifica sempre le firme delle immagini Chainguard con cosign prima di compilare o distribuire.
Scansiona anche le immagini a zero CVE — esegui scansioni di vulnerabilita come passaggio di validazione; le immagini Chainguard dovrebbero restituire zero risultati, confermando che la tua pipeline usa immagini genuine.
Usa le varianti -dev solo nelle fasi di build — non distribuire mai immagini -dev in produzione; includono strumenti che aumentano la superficie di attacco.
Esegui come nonroot — le immagini Chainguard usano l’utente nonroot per impostazione predefinita; mantieni questo nei tuoi Dockerfile non passando a root.
Applica policy sulle immagini — usa Kyverno, OPA Gatekeeper o Sigstore Policy Controller per limitare i registri container nei tuoi cluster.
Genera e archivia gli SBOM — usa Syft o cosign per scaricare gli SBOM per conformita e tracce di audit.
Mantieni le immagini aggiornate — Chainguard ricostruisce le immagini frequentemente; aggiorna i tuoi digest regolarmente per ottenere le ultime patch di sicurezza.