Cosign Cheat Sheet¶

Installazione¶

Piattaforma	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`
## Comandi di Base

Comando	Descrizione
`cosign version`	Visualizza le informazioni sulla versione di cosign
`cosign help`	Mostra tutti i comandi e le opzioni disponibili
`cosign generate-key-pair`	Genera una nuova coppia di chiavi (cosign.key e cosign.pub)
`cosign generate-key-pair --output-key-prefix mykey`	Genera coppia di chiavi con prefisso personalizzato
`cosign sign --key cosign.key IMAGE_URI`	Firma un'immagine container con chiave privata
`cosign sign IMAGE_URI`	Firma immagine utilizzando modalità senza chiave (OIDC)
`cosign verify --key cosign.pub IMAGE_URI`	Verifica firma immagine con chiave pubblica
`cosign verify IMAGE_URI`	Verificare firma digitale senza chiave
`cosign sign --key cosign.key -a key=value IMAGE_URI`	Firma immagine con annotazioni personalizzate
`cosign verify --key cosign.pub -a key=value IMAGE_URI`	Verifica firma e controlla annotazioni
`cosign triangulate IMAGE_URI`	Trova la posizione della firma per un'immagine
`cosign download signature IMAGE_URI`	Scarica firma per un'immagine
`cosign download attestation IMAGE_URI`	Scarica attestazioni per un'immagine
`cosign copy SOURCE_IMAGE DEST_IMAGE`	Copia immagine con firme in una nuova posizione
`cosign sign --key cosign.key IMAGE1 IMAGE2 IMAGE3`	Firma più immagini contemporaneamente
`cosign verify --key cosign.pub IMAGE_URI --output json`	Restituisci i risultati di verifica come JSON
`cosign sign --key cosign.key gcr.io/project/image@sha256:abc123...`	Firma digest immagine specifico
`cosign public-key --key cosign.key`	Estrai la chiave pubblica dalla chiave privata
`cosign initialize`	Inizializza cosign con root of trust
`cosign tree IMAGE_URI`	Visualizza albero di firma e attestazione per immagine
## Utilizzo Avanzato

Comando	Descrizione
`cosign generate-key-pair --kms gcpkms://projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY`	Genera coppia di chiavi in Google Cloud KMS
`cosign generate-key-pair --kms awskms://arn:aws:kms:region:account:key/key-id`	Genera coppia di chiavi in AWS KMS
`cosign generate-key-pair --kms azurekms://vault.vault.azure.net/keys/keyname/version`	Genera coppia di chiavi in Azure Key Vault
`cosign generate-key-pair --kms hashivault://transit/keys/cosign`	Genera coppia di chiavi in HashiCorp Vault
`cosign attest --key cosign.key --predicate predicate.json IMAGE_URI`	Allega attestazione all'immagine
`cosign attest --key cosign.key --type slsaprovenance --predicate provenance.json IMAGE_URI`	Allega attestazione di provenienza SLSA
`cosign attest --key cosign.key --type vuln --predicate scan-results.json IMAGE_URI`	Allegare attestazione scansione vulnerabilità
`cosign attest --key cosign.key --type spdx --predicate sbom.spdx.json IMAGE_URI`	Allega attestazione SBOM
`cosign verify-attestation --key cosign.pub IMAGE_URI`	Verificare attestazioni sull'immagine
`cosign verify-attestation --key cosign.pub --type slsaprovenance IMAGE_URI`	Verificare il tipo specifico di attestazione
`cosign verify-attestation --key cosign.pub --policy policy.cue IMAGE_URI`	Verifica attestazione rispetto alla policy CUE
`cosign sign-blob --key cosign.key --output-signature file.sig file.txt`	Firma file arbitrario (non-container)
`cosign verify-blob --key cosign.pub --signature file.sig file.txt`	Verifica firma blob
`cosign sign --key cosign.key --timestamp-server-url http://timestamp.server IMAGE_URI`	Firma con timestamp RFC3161
`cosign verify --certificate-identity user@example.com --certificate-oidc-issuer https://accounts.google.com IMAGE_URI`	Verifica firma digitale senza chiave con identità
`cosign verify --key cosign.pub --rekor-url https://rekor.sigstore.dev IMAGE_URI`	Verifica con il registro di trasparenza Rekor personalizzato
`cosign verify --key cosign.pub --insecure-ignore-tlog IMAGE_URI`	Verifica senza controllare il transparency log
`cosign copy --platform linux/amd64 SOURCE_IMAGE DEST_IMAGE`	Copia immagine per piattaforma specifica
`cosign copy --sig-only SOURCE_IMAGE DEST_IMAGE`	Copia solo le firme (non l'immagine)
`cosign manifest verify --key cosign.pub IMAGE_URI`	Verificare la firma del manifesto dell'immagine
`cosign upload blob --signature file.sig --payload file.txt`	Carica firma nel log di trasparenza Rekor
`cosign sign --key cosign.key -r gcr.io/myproject/myimage`	Firma tutti i tag ricorsivamente
`cosign verify --key cosign.pub --certificate-chain chain.pem IMAGE_URI`	Verifica con catena di certificati
`cosign attach signature --signature sig.json IMAGE_URI`	Allegare manualmente la firma all'immagine
`cosign attach attestation --attestation att.json IMAGE_URI`	Allegare manualmente l'attestazione all'immagine
## Configurazione

Variabili di 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

Esempio di File di Policy 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/"
    }
  }
}

Policy di Attestazione per Scansioni di Vulnerabilità¶

// 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
  }
}

Integrazione 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

Casi d'Uso Comuni¶

Caso d'Uso 1: Firmare e Verificare Immagine Container con Coppia di Chiavi¶

# 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 d'Uso 2: Firma Keyless 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 d'Uso 3: Allegare e Verificare 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 d'Uso 4: Firmare 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 d'Uso 5: Verifica Basata su Policy con Attestazioni¶

# 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

Best Practice¶

Utilizzare sempre digest specifici delle immagini: Firmare e verificare utilizzando @sha256:...digest invece di tag per prevenire attacchi di mutazione dei tag. I tag possono essere spostati, ma i digest sono immutabili.
Archiviare le chiavi private in modo sicuro: Utilizzare cloud KMS (AWS KMS, Google Cloud KMS, Azure Key Vault) o moduli di sicurezza hardware (HSM) invece di archiviare le chiavi su disco. Non committare mai le chiavi nel controllo versione.
Preferire la firma keyless per CI/CD: Utilizzare la firma keyless basata su OIDC nelle pipeline automatizzate per evitare la gestione di credenziali a lungo termine. Questo sfrutta certificati a breve termine legati al proprio provider di identità.
Implementare l'applicazione delle policy a runtime: Integrare la verifica cosign con controller di ammissione Kubernetes (come Kyverno o OPA Gatekeeper) per impedire l'esecuzione di immagini non firmate o non verificate.
Allegare attestazioni complete: Includere attestazioni SBOM, scansioni di vulnerabilità e attestazioni di provenienza SLSA per fornire piena trasparenza della supply chain. Questo abilita audit trail e report di conformità.
Utilizzare log di trasparenza: Verificare sempre rispetto al log di trasparenza Rekor in produzione per rilevare backdating delle firme o compromissione delle chiavi. Saltare solo con --insecure-ignore-tlogin ambienti air-gapped.
Ruotare le chiavi regolarmente: Stabilire una pianificazione di rotazione delle chiavi (es. ogni 90 giorni) e mantenere un processo di revoca delle chiavi. Conservare vecchie chiavi pubbliche per verificare firme storiche.
Verificare l'identità in modalità keyless: Specificare sempre --certificate-identitye --certificate-oidc-issuerdurante la verifica di firme keyless per impedire l'accettazione di firme da identità inattese.
Testare la verifica in staging: Testare sempre le proprie policy di verifica in ambienti non di produzione prima di applicarle in produzione per evitare guasti di distribuzione.
Documentare il workflow di firma: Mantenere documentazione chiara su chi può firmare immagini, quali attestazioni sono richieste e come verificare le firme per incident response e audit.

Risoluzione dei Problemi¶

Problema	Soluzione
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.