Hoja de Referencia de Cosign

Instalación

Platform	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	Descripción
`cosign version`	Mostrar información de versión de cosign
`cosign help`	Mostrar todos los comandos y opciones disponibles
`cosign generate-key-pair`	Generar un nuevo par de claves (cosign.key y cosign.pub)
`cosign generate-key-pair --output-key-prefix mykey`	Generar par de claves con prefijo personalizado
`cosign sign --key cosign.key IMAGE_URI`	Firmar una imagen de contenedor con clave privada
`cosign sign IMAGE_URI`	Firmar imagen usando modo sin clave (OIDC)
`cosign verify --key cosign.pub IMAGE_URI`	Verificar firma de imagen con clave pública
`cosign verify IMAGE_URI`	Verificar firma sin clave
`cosign sign --key cosign.key -a key=value IMAGE_URI`	Firmar imagen con anotaciones personalizadas
`cosign verify --key cosign.pub -a key=value IMAGE_URI`	Verificar firma y revisar anotaciones
`cosign triangulate IMAGE_URI`	Encontrar ubicación de firma para una imagen
`cosign download signature IMAGE_URI`	Descargar firma para una imagen
`cosign download attestation IMAGE_URI`	Descargar atestaciones para una imagen
`cosign copy SOURCE_IMAGE DEST_IMAGE`	Copiar imagen con firmas a nueva ubicación
`cosign sign --key cosign.key IMAGE1 IMAGE2 IMAGE3`	Firmar varios imágenes a la vez
`cosign verify --key cosign.pub IMAGE_URI --output json`	Generar resultados de verificación como JSON
`cosign sign --key cosign.key gcr.io/project/image@sha256:abc123...`	Firmar hash de imagen específico
`cosign public-key --key cosign.key`	Extraer clave pública de clave privada
`cosign initialize`	Inicializar cosign con raíz de confianza
`cosign tree IMAGE_URI`	Mostrar árbol de firma y atestación para imagen

Uso Avanzado

Comando	Descripción
`cosign generate-key-pair --kms gcpkms://projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY`	Generar par de claves en Google Cloud KMS
`cosign generate-key-pair --kms awskms://arn:aws:kms:region:account:key/key-id`	Generar par de claves en AWS KMS
`cosign generate-key-pair --kms azurekms://vault.vault.azure.net/keys/keyname/version`	Generar par de claves en Azure Key Vault
`cosign generate-key-pair --kms hashivault://transit/keys/cosign`	Generar par de claves en HashiCorp Vault
`cosign attest --key cosign.key --predicate predicate.json IMAGE_URI`	Adjuntar atestación a imagen
`cosign attest --key cosign.key --type slsaprovenance --predicate provenance.json IMAGE_URI`	Adjuntar atestación de procedencia SLSA
`cosign attest --key cosign.key --type vuln --predicate scan-results.json IMAGE_URI`	Adjuntar atestación de escaneo de vulnerabilidades
`cosign attest --key cosign.key --type spdx --predicate sbom.spdx.json IMAGE_URI`	Adjuntar atestación SBOM
`cosign verify-attestation --key cosign.pub IMAGE_URI`	Verificar atestaciones en imagen
`cosign verify-attestation --key cosign.pub --type slsaprovenance IMAGE_URI`	Verificar tipo de atestación específico
`cosign verify-attestation --key cosign.pub --policy policy.cue IMAGE_URI`	Verificar atestación contra política CUE
`cosign sign-blob --key cosign.key --output-signature file.sig file.txt`	Firmar archivo arbitrario (no contenedor)
`cosign verify-blob --key cosign.pub --signature file.sig file.txt`	Verificar firma de blob
`cosign sign --key cosign.key --timestamp-server-url http://timestamp.server IMAGE_URI`	Firmar con marca de tiempo RFC3161
`cosign verify --certificate-identity user@example.com --certificate-oidc-issuer https://accounts.google.com IMAGE_URI`	Verificar firma sin clave con identidad
`cosign verify --key cosign.pub --rekor-url https://rekor.sigstore.dev IMAGE_URI`	Verificar con registro de transparencia Rekor personalizado
`cosign verify --key cosign.pub --insecure-ignore-tlog IMAGE_URI`	Verificar sin consultar el registro de transparencia
`cosign copy --platform linux/amd64 SOURCE_IMAGE DEST_IMAGE`	Copiar imagen para plataforma específica
`cosign copy --sig-only SOURCE_IMAGE DEST_IMAGE`	Copiar solo firmas (no imagen)
`cosign manifest verify --key cosign.pub IMAGE_URI`	Verificar firma de manifiesto de imagen
`cosign upload blob --signature file.sig --payload file.txt`	Cargar firma en el registro de transparencia Rekor
`cosign sign --key cosign.key -r gcr.io/myproject/myimage`	Firmar todas las etiquetas recursivamente
`cosign verify --key cosign.pub --certificate-chain chain.pem IMAGE_URI`	Verificar con cadena de certificados
`cosign attach signature --signature sig.json IMAGE_URI`	Adjuntar manualmente la firma a la imagen
`cosign attach attestation --attestation att.json IMAGE_URI`	Adjuntar manualmente la atestación a la imagen

Configuración

Variables de Entorno

# 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

Ejemplo de Archivo 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 Atestación para Escaneos 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
  }
}

Integración con 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 Comunes

Caso de Uso 1: Firmar y Verificar Imagen de Contenedor con Par de Claves

# 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: Firma Sin Clave con 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: Adjuntar y 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: Firmar con 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: Verificación Basada en Políticas con Atestaciones

# 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

Mejores Prácticas

Siempre usar hashes de imagen específicos: Firmar y verificar usando @sha256:...hashes en lugar de etiquetas para prevenir ataques de mutación de etiquetas. Las etiquetas pueden moverse, pero los hashes son inmutables.
Almacenar claves privadas de forma segura: Usar cloud KMS (AWS KMS, Google Cloud KMS, Azure Key Vault) o módulos de seguridad de hardware (HSM) en lugar de almacenar claves en disco. Nunca confirmar claves en control de versiones.
Preferir firma sin clave para CI/CD: Usar firma sin clave basada en OIDC en tuberías automatizadas para evitar administrar credenciales de larga duración. Esto aprovecha certificados de corta duración vinculados a su proveedor de identidad.
Implementar cumplimiento de políticas en tiempo de ejecución: Integrar verificación de cosign con controladores de admisión de Kubernetes (como Kyverno u OPA Gatekeeper) para prevenir la ejecución de imágenes no firmadas o no verificadas.
Adjuntar atestaciones completas: Incluir SBOM, escaneos de vulnerabilidades y atestaciones de procedencia SLSA para proporcionar transparencia completa de la cadena de suministro. Esto permite registros de auditoría e informes de cumplimiento.
Usar registros de transparencia: Siempre verificar contra el registro de transparencia de Rekor en producción para detectar antedatación de firmas o compromiso de claves. Solo omitir con --insecure-ignore-tlogen entornos aislados.
Rotar claves regularmente: Establecer un calendario de rotación de claves (por ejemplo, cada 90 días) y mantener un proceso de revocación de claves. Conservar claves públicas antiguas para verificar firmas históricas.
Verificar identidad en modo sin clave: Siempre especificar --certificate-identityy --certificate-oidc-issueral verificar firmas sin clave para evitar aceptar firmas de identidades inesperadas.
Probar verificación en entorno de pruebas: Siempre probar las políticas de verificación en entornos no productivos antes de aplicarlas en producción para evitar fallos de implementación.
Documentar flujo de trabajo de firma: Mantener documentación clara de quién puede firmar imágenes, qué atestaciones son requeridas y cómo verificar firmas para respuesta a incidentes y auditoría.

Resolución de Problemas

Problema	Solución
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.