Chainguard Images

Imagens de contêiner mínimas com zero CVE construídas no Wolfi Linux para cadeias de suprimento de software seguras.

Primeiros Passos

Baixando Imagens

Comando	Descrição
`docker pull cgr.dev/chainguard/static:latest`	Baixar imagem base estática mínima
`docker pull cgr.dev/chainguard/busybox:latest`	Baixar imagem busybox para depuração
`docker pull cgr.dev/chainguard/wolfi-base:latest`	Baixar imagem base Wolfi com shell
`docker pull cgr.dev/chainguard/python:latest`	Baixar imagem runtime Python
`docker pull cgr.dev/chainguard/node:latest`	Baixar imagem runtime Node.js
`docker pull cgr.dev/chainguard/go:latest`	Baixar imagem de build Go
`docker pull cgr.dev/chainguard/nginx:latest`	Baixar imagem do servidor web nginx
`docker pull cgr.dev/chainguard/git:latest`	Baixar imagem git mínima
`docker pull cgr.dev/chainguard/jdk:latest`	Baixar imagem Java JDK
`docker pull cgr.dev/chainguard/rust:latest`	Baixar imagem de build Rust
`docker pull cgr.dev/chainguard/redis:latest`	Baixar imagem do servidor Redis
`docker pull cgr.dev/chainguard/postgres:latest`	Baixar imagem PostgreSQL
`docker pull cgr.dev/chainguard/curl:latest`	Baixar imagem curl mínima

Tags de Imagem

Comando	Descrição
tag `:latest`	Build mais recente, pronto para produção
tag `:latest-dev`	Variante de desenvolvimento com shell e gerenciador de pacotes
`:latest` em imagens `-dev`	Inclui apk, shell e ferramentas de depuração
`cgr.dev/chainguard-private/IMAGE`	Registro de imagens privado/empresarial
Fixação por digest `@sha256:abc123...`	Fixar ao build exato da imagem para reprodutibilidade

Uso de Imagens

Uso Básico

Comando	Descrição
`FROM cgr.dev/chainguard/static:latest`	Usar imagem estática no Dockerfile
`FROM cgr.dev/chainguard/python:latest-dev`	Usar variante dev com pip e shell
`FROM cgr.dev/chainguard/node:latest AS build`	Usar como estágio de build
`FROM cgr.dev/chainguard/go:latest AS builder`	Usar imagem Go para compilação
`docker run --rm cgr.dev/chainguard/wolfi-base sh`	Executar shell interativo
`docker run --rm -p 8080:8080 cgr.dev/chainguard/nginx`	Executar servidor nginx
`docker run --rm cgr.dev/chainguard/python -- python -c "print('hello')"`	Executar one-liner Python

Build Go Multi-Estágio

# Estágio de 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

# Estágio de runtime - distroless, sem shell, sem gerenciador de pacotes
FROM cgr.dev/chainguard/static:latest
COPY --from=builder /server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

Build Python Multi-Estágio

# Estágio de build com pip disponível
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 . .

# Estágio de runtime - Python mínimo, sem pip, sem 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 Node.js Multi-Estágio

# Estágio de 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

# Estágio de 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 Java Multi-Estágio

# Estágio de build
FROM cgr.dev/chainguard/jdk:latest-dev AS builder
WORKDIR /app
COPY . .
RUN ./gradlew build --no-daemon -x test

# Estágio de 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"]

Descoberta

Operações Chainctl

Comando	Descrição
`chainctl auth login`	Autenticar com Chainguard
`chainctl auth login --headless`	Login em ambientes headless
`chainctl auth configure-docker`	Configurar Docker para usar o registro Chainguard
`chainctl images list`	Listar imagens Chainguard disponíveis
`chainctl images repos list --group=GROUP_ID`	Listar repos de imagens de um grupo
`chainctl images diff IMAGE1 IMAGE2`	Comparar duas versões de imagem
`chainctl images history cgr.dev/chainguard/python`	Mostrar histórico de versões da imagem
Navegar em `images.chainguard.dev`	Catálogo web de todas as imagens

Inspeção de Imagens

Comando	Descrição
`crane ls cgr.dev/chainguard/python`	Listar tags disponíveis para uma imagem
`crane manifest cgr.dev/chainguard/python:latest`	Visualizar manifesto da imagem
`crane config cgr.dev/chainguard/python:latest`	Visualizar configuração da imagem
`docker inspect cgr.dev/chainguard/python:latest`	Inspecionar metadados da imagem
`docker history cgr.dev/chainguard/python:latest`	Visualizar camadas da imagem
`dive cgr.dev/chainguard/python:latest`	Explorar camadas da imagem interativamente

Verificação

Verificação de Assinatura

Comando	Descrição
`cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity-regexp='chainguard' cgr.dev/chainguard/python`	Verificar assinatura da imagem
`cosign verify-attestation --type spdx cgr.dev/chainguard/python`	Verificar atestado SBOM
`cosign verify-attestation --type vuln cgr.dev/chainguard/python`	Verificar atestado de vulnerabilidade
`cosign tree cgr.dev/chainguard/python`	Visualizar artefatos da cadeia de suprimentos
`cosign verify-attestation --type slsaprovenance cgr.dev/chainguard/python`	Verificar proveniência SLSA

Exemplo de Verificação Cosign

# Verificar a assinatura de uma imagem Chainguard
cosign verify \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest

# Verificar atestado SBOM e exibi-lo
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 .

# Verificar atestado de varredura de vulnerabilidade
cosign verify-attestation \
  --type vuln \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="chainguard" \
  cgr.dev/chainguard/python:latest

Varredura de Vulnerabilidades

Comando	Descrição
`grype cgr.dev/chainguard/python`	Varrer imagem para vulnerabilidades com Grype
`grype cgr.dev/chainguard/python --only-fixed`	Mostrar apenas vulnerabilidades corrigíveis
`trivy image cgr.dev/chainguard/python`	Varrer com scanner Trivy
`trivy image --severity HIGH,CRITICAL cgr.dev/chainguard/python`	Varrer apenas alta/crítica
`docker scout cves cgr.dev/chainguard/python`	Varrer com Docker Scout
`chainctl images vulns cgr.dev/chainguard/python`	Ver vulnerabilidades conhecidas via chainctl

Gerenciamento APK Wolfi

Operações de Pacotes

Comando	Descrição
`apk update`	Atualizar índice de pacotes (em imagens dev)
`apk add curl`	Instalar um pacote
`apk add --no-cache python3 py3-pip`	Instalar sem cache de índice
`apk add --virtual .build-deps gcc musl-dev`	Instalar dependências de build virtuais
`apk del .build-deps`	Remover grupo de pacotes virtuais
`apk del curl`	Remover um pacote
`apk list --installed`	Listar pacotes instalados
`apk search nginx`	Buscar pacotes disponíveis
`apk info python3`	Mostrar detalhes do pacote
`apk info -L python3`	Listar arquivos de um pacote

Construindo Imagens Personalizadas

Build de Pacotes Melange

Comando	Descrição
`melange keygen`	Gerar chaves de assinatura para pacotes
`melange build recipe.yaml --signing-key melange.rsa`	Construir pacote APK a partir de receita
`melange build recipe.yaml --arch x86_64,aarch64`	Construir para múltiplas arquiteturas
`melange bump recipe.yaml 1.2.3`	Incrementar versão na receita

Exemplo de Receita Melange

package:
  name: myapp
  version: 1.0.0
  epoch: 0
  description: Aplicação personalizada
  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 de Imagens Apko

Comando	Descrição
`apko build config.yaml tag output.tar`	Construir imagem OCI a partir de config YAML
`apko publish config.yaml tag`	Construir e enviar imagem para registro
`apko build config.yaml tag output.tar --arch x86_64,aarch64`	Construir imagem multi-arquitetura
`docker load < output.tar`	Carregar imagem construída no Docker

Exemplo de Configuração 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 Proveniência

Artefatos da Cadeia de Suprimentos

Comando	Descrição
`cosign download sbom cgr.dev/chainguard/python`	Baixar SBOM da imagem
`syft cgr.dev/chainguard/python`	Gerar SBOM com Syft
`syft cgr.dev/chainguard/python -o spdx-json`	Gerar SBOM SPDX
`syft cgr.dev/chainguard/python -o cyclonedx-json`	Gerar SBOM CycloneDX
`cosign download attestation cgr.dev/chainguard/python`	Baixar todos os atestados
`cosign verify-attestation --type slsaprovenance cgr.dev/chainguard/python`	Verificar proveniência SLSA
`chainctl images vulns cgr.dev/chainguard/python`	Ver vulnerabilidades conhecidas

Aplicação de Políticas

Política de Admissão Kubernetes

# Sigstore Policy Controller - exigir assinaturas 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

Exemplo de Política 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: "Apenas imagens Chainguard de cgr.dev são permitidas."
        pattern:
          spec:
            containers:
              - image: "cgr.dev/chainguard/*"
            initContainers:
              - image: "cgr.dev/chainguard/*"

Pipeline de Verificação CI/CD

# GitHub Actions - verificar e varrer antes da implantação
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

Melhores Práticas

Usar builds multi-estágio — construir em imagens -dev (que possuem compiladores e gerenciadores de pacotes) e copiar apenas o artefato final para a imagem runtime mínima.
Fixar imagens por digest — usar digests @sha256:... em vez de tags para implantações em produção para garantir reprodutibilidade.
Escolher a imagem base correta — usar static para binários compilados sem dependências de SO, wolfi-base quando precisar de shell, e imagens específicas de linguagem para linguagens interpretadas.
Verificar assinaturas no CI/CD — sempre verificar assinaturas de imagens Chainguard com cosign antes de construir ou implantar.
Varrer mesmo imagens zero-CVE — executar varreduras de vulnerabilidade como etapa de validação; imagens Chainguard devem retornar zero resultados, confirmando que seu pipeline está usando imagens genuínas.
Usar variantes -dev apenas em estágios de build — nunca envie imagens -dev para produção; elas incluem ferramentas que aumentam a superfície de ataque.
Executar como nonroot — imagens Chainguard usam por padrão o usuário nonroot; mantenha isso em seus Dockerfiles não alternando para root.
Aplicar políticas de imagem — usar Kyverno, OPA Gatekeeper ou Sigstore Policy Controller para restringir registros de contêiner em seus clusters.
Gerar e armazenar SBOMs — usar Syft ou cosign para baixar SBOMs para conformidade e trilhas de auditoria.
Manter imagens atualizadas — Chainguard reconstrói imagens frequentemente; atualize seus digests regularmente para obter os patches de segurança mais recentes.