Cosign Cheat Sheet

Instalação

Plataforma	Comando
Ubuntu/Debian	`wget https://github.com/sigstore/cosign/releases/latest/download/cosign_amd64.deb && sudo dpkg -i cosign_amd64.deb`
RHEL/Fedora/CentOS	`wget https://github.com/sigstore/cosign/releases/latest/download/cosign-amd64.rpm && sudo rpm -ivh cosign-amd64.rpm`
macOS (Homebrew)	`brew install cosign`
macOS (Binary)	`curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-darwin-amd64 && sudo mv cosign-darwin-amd64 /usr/local/bin/cosign && sudo chmod +x /usr/local/bin/cosign`
macOS (Apple Silicon)	`curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-darwin-arm64 && sudo mv cosign-darwin-arm64 /usr/local/bin/cosign && sudo chmod +x /usr/local/bin/cosign`
Windows (Scoop)	`scoop install cosign`
Windows (Chocolatey)	`choco install cosign`
Windows (winget)	`winget install sigstore.cosign`
Linux (Generic Binary)	`curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 && sudo mv cosign-linux-amd64 /usr/local/bin/cosign && sudo chmod +x /usr/local/bin/cosign`
Arch Linux	`yay -S cosign`
Container	`docker run --rm gcr.io/projectsigstore/cosign:latest version`
Verify Installation	`cosign version`

Comandos Básicos

Comando	Descrição
`cosign version`	Exibir informações da versão do cosign
`cosign help`	Mostrar todos os comandos e opções disponíveis
`cosign generate-key-pair`	Gere um novo par de chaves (cosign.key e cosign.pub)
`cosign generate-key-pair --output-key-prefix mykey`	Gerar par de chaves com prefixo personalizado
`cosign sign --key cosign.key IMAGE_URI`	Assinar uma imagem de container com chave privada
`cosign sign IMAGE_URI`	Assinar imagem usando modo sem chave (OIDC)
`cosign verify --key cosign.pub IMAGE_URI`	Verificar assinatura de imagem com chave pública
`cosign verify IMAGE_URI`	Verificar assinatura sem chave
`cosign sign --key cosign.key -a key=value IMAGE_URI`	Assinar imagem com anotações personalizadas
`cosign verify --key cosign.pub -a key=value IMAGE_URI`	Verificar assinatura e verificar anotações
`cosign triangulate IMAGE_URI`	Localizar localização da assinatura para uma imagem
`cosign download signature IMAGE_URI`	Baixar assinatura para uma imagem
`cosign download attestation IMAGE_URI`	Baixar atestados para uma imagem
`cosign copy SOURCE_IMAGE DEST_IMAGE`	Copiar imagem com assinaturas para novo local
`cosign sign --key cosign.key IMAGE1 IMAGE2 IMAGE3`	Assinar múltiplas imagens de uma vez
`cosign verify --key cosign.pub IMAGE_URI --output json`	Resultados de verificação de saída como JSON
`cosign sign --key cosign.key gcr.io/project/image@sha256:abc123...`	Assinar digest específico de imagem
`cosign public-key --key cosign.key`	Extrair chave pública a partir da chave privada
`cosign initialize`	Inicialize o cosign com raiz de confiança
`cosign tree IMAGE_URI`	Exibir árvore de assinatura e atestação para imagem

Uso Avançado

Comando	Descrição
`cosign generate-key-pair --kms gcpkms://projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY`	Gerar par de chaves no Google Cloud KMS
`cosign generate-key-pair --kms awskms://arn:aws:kms:region:account:key/key-id`	Gerar par de chaves no AWS KMS
`cosign generate-key-pair --kms azurekms://vault.vault.azure.net/keys/keyname/version`	Gerar par de chaves no Azure Key Vault
`cosign generate-key-pair --kms hashivault://transit/keys/cosign`	Gerar par de chaves no HashiCorp Vault
`cosign attest --key cosign.key --predicate predicate.json IMAGE_URI`	Anexar atestado à imagem
`cosign attest --key cosign.key --type slsaprovenance --predicate provenance.json IMAGE_URI`	Anexar atestado de proveniência SLSA
`cosign attest --key cosign.key --type vuln --predicate scan-results.json IMAGE_URI`	Anexar atestado de varredura de vulnerabilidade
`cosign attest --key cosign.key --type spdx --predicate sbom.spdx.json IMAGE_URI`	Anexar atestado de SBOM
`cosign verify-attestation --key cosign.pub IMAGE_URI`	Verificar atestados na imagem
`cosign verify-attestation --key cosign.pub --type slsaprovenance IMAGE_URI`	Verificar tipo de atestação específico
`cosign verify-attestation --key cosign.pub --policy policy.cue IMAGE_URI`	Verificar atestação em relação à política CUE
`cosign sign-blob --key cosign.key --output-signature file.sig file.txt`	Assinar arquivo arbitrário (não-container)
`cosign verify-blob --key cosign.pub --signature file.sig file.txt`	Verificar assinatura do blob
`cosign sign --key cosign.key --timestamp-server-url http://timestamp.server IMAGE_URI`	Assinar com timestamp RFC3161
`cosign verify --certificate-identity user@example.com --certificate-oidc-issuer https://accounts.google.com IMAGE_URI`	Verificar assinatura sem chave com identidade
`cosign verify --key cosign.pub --rekor-url https://rekor.sigstore.dev IMAGE_URI`	Verifique com o log de transparência personalizado do Rekor
`cosign verify --key cosign.pub --insecure-ignore-tlog IMAGE_URI`	Verificar sem verificar log de transparência
`cosign copy --platform linux/amd64 SOURCE_IMAGE DEST_IMAGE`	Copiar imagem para plataforma específica
`cosign copy --sig-only SOURCE_IMAGE DEST_IMAGE`	Copiar apenas assinaturas (não imagem)
`cosign manifest verify --key cosign.pub IMAGE_URI`	Verificar assinatura do manifesto de imagem
`cosign upload blob --signature file.sig --payload file.txt`	Carregar assinatura para o log de transparência do Rekor
`cosign sign --key cosign.key -r gcr.io/myproject/myimage`	Assinar todas as tags recursivamente
`cosign verify --key cosign.pub --certificate-chain chain.pem IMAGE_URI`	Verificar com cadeia de certificados
`cosign attach signature --signature sig.json IMAGE_URI`	Anexar manualmente assinatura à imagem
`cosign attach attestation --attestation att.json IMAGE_URI`	Anexar manualmente atestado à imagem

Configuração

Variáveis de Ambiente

# Enable experimental features (keyless signing)
export COSIGN_EXPERIMENTAL=1

# Set custom Rekor transparency log URL
export REKOR_URL=https://rekor.sigstore.dev

# Set custom Fulcio certificate authority URL
export FULCIO_URL=https://fulcio.sigstore.dev

# Set custom OIDC issuer for keyless signing
export COSIGN_OIDC_ISSUER=https://oauth2.sigstore.dev/auth

# Set custom OIDC client ID
export COSIGN_OIDC_CLIENT_ID=sigstore

# Set Docker registry credentials
export COSIGN_REPOSITORY=registry.example.com/signatures

# Set password for private key (CI/CD use)
export COSIGN_PASSWORD=your-password-here

# Skip TUF root verification (not recommended for production)
export COSIGN_EXPERIMENTAL_SKIP_TUF=1

# Set custom Docker config location
export DOCKER_CONFIG=/path/to/.docker

Exemplo de Arquivo de Política CUE

// policy.cue - Example attestation policy
predicateType: "https://slsa.dev/provenance/v0.2"

predicate: {
  buildType: "https://cloudbuild.googleapis.com/CloudBuildYaml@v1"
  builder: id: =~"^https://cloudbuild.googleapis.com/"
  
  invocation: {
    configSource: {
      repository: =~"^https://github.com/myorg/"
    }
  }
}

Política de Atestação para Varreduras de Vulnerabilidades

// vuln-policy.cue - Require no critical vulnerabilities
predicateType: "https://cosign.sigstore.dev/attestation/vuln/v1"

predicate: {
  scanner: {
    name: "trivy"
  }
  
  metadata: {
    scanFinishedOn: string
  }
  
  // No critical vulnerabilities allowed
  scanner: result: {
    criticalCount: 0
  }
}

Integração com GitHub Actions

# .github/workflows/sign.yml
name: Sign Container Image
on: [push]

permissions:
  contents: read
  id-token: write  # Required for keyless signing
  packages: write

jobs:
  sign:
    runs-on: ubuntu-latest
    steps:
      - name: Install Cosign
        uses: sigstore/cosign-installer@v3
        
      - name: Login to Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
          
      - name: Build Image
        run: docker build -t ghcr.io/${{ github.repository }}:latest .
        
      - name: Push Image
        run: docker push ghcr.io/${{ github.repository }}:latest
        
      - name: Sign Image (Keyless)
        run: |
          cosign sign --yes ghcr.io/${{ github.repository }}:latest

Casos de Uso Comuns

Caso de Uso 1: Assinar e Verificar Imagem de Contêiner com Par de Chaves

# Generate key pair (will prompt for password)
cosign generate-key-pair

# Build your container image
docker build -t myregistry.io/myapp:v1.0 .

# Push image to registry
docker push myregistry.io/myapp:v1.0

# Sign the image
cosign sign --key cosign.key myregistry.io/myapp:v1.0

# Verify the signature
cosign verify --key cosign.pub myregistry.io/myapp:v1.0

# Verify and extract payload
cosign verify --key cosign.pub myregistry.io/myapp:v1.0 | jq .

Caso de Uso 2: Assinatura Sem Chave com GitHub Actions

# Enable experimental mode for keyless signing
export COSIGN_EXPERIMENTAL=1

# Sign image (will open browser for OIDC authentication)
cosign sign myregistry.io/myapp:v1.0

# In CI/CD (GitHub Actions), use --yes flag
cosign sign --yes myregistry.io/myapp:v1.0

# Verify keyless signature with identity
cosign verify \
  --certificate-identity user@example.com \
  --certificate-oidc-issuer https://github.com/login/oauth \
  myregistry.io/myapp:v1.0

# Verify in GitHub Actions workflow
cosign verify \
  --certificate-identity https://github.com/myorg/myrepo/.github/workflows/build.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  myregistry.io/myapp:v1.0

Caso de Uso 3: Anexar e Verificar SBOM

# Generate SBOM using syft
syft myregistry.io/myapp:v1.0 -o spdx-json > sbom.spdx.json

# Attach SBOM as attestation
cosign attest --key cosign.key \
  --type spdx \
  --predicate sbom.spdx.json \
  myregistry.io/myapp:v1.0

# Verify attestation
cosign verify-attestation --key cosign.pub \
  --type spdx \
  myregistry.io/myapp:v1.0

# Download and view SBOM
cosign verify-attestation --key cosign.pub \
  --type spdx \
  myregistry.io/myapp:v1.0 | jq -r '.payload' | base64 -d | jq .

Caso de Uso 4: Assinar com Cloud KMS

# Generate key in Google Cloud KMS
cosign generate-key-pair --kms gcpkms://projects/my-project/locations/us-central1/keyRings/cosign/cryptoKeys/signing-key

# Sign image using KMS key
cosign sign --key gcpkms://projects/my-project/locations/us-central1/keyRings/cosign/cryptoKeys/signing-key \
  myregistry.io/myapp:v1.0

# Get public key from KMS
cosign public-key --key gcpkms://projects/my-project/locations/us-central1/keyRings/cosign/cryptoKeys/signing-key > cosign.pub

# Verify using public key
cosign verify --key cosign.pub myregistry.io/myapp:v1.0

# AWS KMS example
cosign sign --key awskms://arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012 \
  myregistry.io/myapp:v1.0

Caso de Uso 5: Verificação Baseada em Política com Atestações

# Create vulnerability scan
trivy image --format json --output scan-results.json myregistry.io/myapp:v1.0

# Attach scan results as attestation
cosign attest --key cosign.key \
  --type vuln \
  --predicate scan-results.json \
  myregistry.io/myapp:v1.0

# Create policy file
cat > vuln-policy.cue <<EOF
predicateType: "https://cosign.sigstore.dev/attestation/vuln/v1"
predicate: {
  scanner: {
    name: "trivy"
  }
}
EOF

# Verify against policy
cosign verify-attestation --key cosign.pub \
  --type vuln \
  --policy vuln-policy.cue \
  myregistry.io/myapp:v1.0

# If policy passes, deploy image
kubectl set image deployment/myapp myapp=myregistry.io/myapp:v1.0

Melhores Práticas

Sempre use resumos de imagens específicos: Assine e verifique usando @sha256:...resumos em vez de tags para prevenir ataques de mutação de tags. Tags podem ser movidas, mas resumos são imutáveis.
Armazene chaves privadas com segurança: Use cloud KMS (AWS KMS, Google Cloud KMS, Azure Key Vault) ou módulos de segurança de hardware (HSM) em vez de armazenar chaves em disco. Nunca faça commit de chaves no controle de versão.
Prefira assinatura sem chave para CI/CD: Use assinatura sem chave baseada em OIDC em pipelines automatizados para evitar gerenciar credenciais de longa duração. Isso aproveita certificados de curta duração vinculados ao seu provedor de identidade.
Implemente imposição de política em tempo de execução: Integre verificação do cosign com controladores de admissão do Kubernetes (como Kyverno ou OPA Gatekeeper) para impedir a execução de imagens não assinadas ou não verificadas.
Anexe atestações abrangentes: Inclua atestações de SBOM, varreduras de vulnerabilidades e proveniência SLSA para fornecer transparência completa da cadeia de suprimentos. Isso permite trilhas de auditoria e relatórios de conformidade.
Use registros de transparência: Sempre verifique em relação ao registro de transparência Rekor em produção para detectar backdating de assinatura ou comprometimento de chave. Pule apenas com --insecure-ignore-tlogem ambientes isolados.
Gire chaves regularmente: Estabeleça um cronograma de rotação de chaves (por exemplo, a cada 90 dias) e mantenha um processo de revogação de chaves. Mantenha chaves públicas antigas para verificar assinaturas históricas.
Verifique a identidade no modo sem chave: Sempre especifique --certificate-identitye --certificate-oidc-issuerao verificar assinaturas sem chave para evitar aceitar assinaturas de identidades inesperadas.
Teste verificação em staging: Sempre teste suas políticas de verificação em ambientes de não produção antes de aplicar em produção para evitar falhas de implantação.
Documente seu fluxo de assinatura: Mantenha documentação clara de quem pode assinar imagens, quais atestações são necessárias e como verificar assinaturas para resposta a incidentes e auditoria.

Solução de Problemas

Problema	Solução
Error: “private key password incorrect”	Ensure you’re using the correct password for your private key. Set `COSIGN_PASSWORD` environment variable for non-interactive use: `export COSIGN_PASSWORD=your-password`
Error: “no matching signatures”	The image may not be signed, or you’re using the wrong public key. Verify with `cosign triangulate IMAGE_URI` to check if signatures exist, and ensure you’re using the correct public key.
Error: “UNAUTHORIZED: authentication required”	You need to authenticate to the registry first. Run `docker login` or use `cosign login` with appropriate credentials before signing or verifying.
Keyless signing fails with “no provider found”	Enable experimental mode with `export COSIGN_EXPERIMENTAL=1` and ensure you have internet access to reach Fulcio and Rekor services.
Error: “failed to verify certificate identity”	When verifying keyless signatures, you must specify both `--certificate-identity` and `--certificate-oidc-issuer` flags matching the signer’s identity.
Signatures not found after copying image	Use `cosign copy` instead of `docker tag` or `crane copy` to ensure signatures are copied along with the image. Regular Docker commands don’t copy OCI artifacts.
Error: “tlog entry not found”	The signature may not have been uploaded to Rekor transparency log. Use `--insecure-ignore-tlog` flag only in air-gapped environments or re-sign the image.
Verification fails in air-gapped environment	Initialize cosign with TUF root: `cosign initialize --mirror https://your-mirror --root root.json`, or use `--insecure-ignore-tlog` and `--insecure-ignore-sct` flags (not recommended for production).
Error: “image is a manifest list”	Sign the specific platform image instead of the manifest list, or use `cosign sign --recursive` to sign all images in the manifest list.
Attestation verification fails with policy	Check your CUE policy syntax with `cue vet policy.cue`. Ensure the predicateType matches exactly. Use `cosign verify-attestation --output json` to inspect actual attestation structure.
Error: “failed to get public key from KMS”	Verify your cloud credentials are configured (`gcloud auth`, `aws configure`, `az login`) and you have permissions to access the KMS key. Check the KMS key URI format is correct.