Cosign Cheat Sheet¶

Installation¶

Plattform	Befehl
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`

Grundlegende Befehle¶

Befehl	Beschreibung
`cosign version`	Zeige cosign Versionsinformationen
`cosign help`	Zeige alle verfügbaren Befehle und Optionen
`cosign generate-key-pair`	Generieren Sie ein neues Schlüsselpaar (cosign.key und cosign.pub)
`cosign generate-key-pair --output-key-prefix mykey`	Generiere Schlüsselpaar mit benutzerdefiniertem Präfix
`cosign sign --key cosign.key IMAGE_URI`	Ein Container-Image mit einem privaten Schlüssel signieren
`cosign sign IMAGE_URI`	Bild mit keyless-Modus signieren (OIDC)
`cosign verify --key cosign.pub IMAGE_URI`	Image-Signatur mit öffentlichem Schlüssel verifizieren
`cosign verify IMAGE_URI`	Keyless-Signatur überprüfen
`cosign sign --key cosign.key -a key=value IMAGE_URI`	Bild mit benutzerdefinierten Anmerkungen signieren
`cosign verify --key cosign.pub -a key=value IMAGE_URI`	Signatur überprüfen und Anmerkungen prüfen
`cosign triangulate IMAGE_URI`	Signaturposition für ein Bild finden
`cosign download signature IMAGE_URI`	Signatur für ein Image herunterladen
`cosign download attestation IMAGE_URI`	Download-Atteste für ein Bild
`cosign copy SOURCE_IMAGE DEST_IMAGE`	Bild mit Signaturen an neuen Speicherort kopieren
`cosign sign --key cosign.key IMAGE1 IMAGE2 IMAGE3`	Mehrere Images gleichzeitig signieren
`cosign verify --key cosign.pub IMAGE_URI --output json`	Ausgabeverifikationsergebnisse als JSON
`cosign sign --key cosign.key gcr.io/project/image@sha256:abc123...`	Signiere spezifischen Image-Digest
`cosign public-key --key cosign.key`	Öffentlichen Schlüssel aus privatem Schlüssel extrahieren
`cosign initialize`	Initialisiere cosign mit Root of Trust
`cosign tree IMAGE_URI`	Signatur und Attestationsbaum für Image anzeigen

Erweiterte Nutzung¶

Befehl	Beschreibung
`cosign generate-key-pair --kms gcpkms://projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY`	Schlüsselpaar in Google Cloud KMS generieren
`cosign generate-key-pair --kms awskms://arn:aws:kms:region:account:key/key-id`	Schlüsselpaar in AWS KMS generieren
`cosign generate-key-pair --kms azurekms://vault.vault.azure.net/keys/keyname/version`	Generieren eines Schlüsselpaars in Azure Key Vault
`cosign generate-key-pair --kms hashivault://transit/keys/cosign`	Schlüsselpaar in HashiCorp Vault generieren
`cosign attest --key cosign.key --predicate predicate.json IMAGE_URI`	Attestation an Bild anhängen
`cosign attest --key cosign.key --type slsaprovenance --predicate provenance.json IMAGE_URI`	SLSA-Herkunftsnachweis anhängen
`cosign attest --key cosign.key --type vuln --predicate scan-results.json IMAGE_URI`	Vulnerability-Scan-Bescheinigung anhängen
`cosign attest --key cosign.key --type spdx --predicate sbom.spdx.json IMAGE_URI`	SBOM-Attestierung anhängen
`cosign verify-attestation --key cosign.pub IMAGE_URI`	Attestierungen auf Bild überprüfen
`cosign verify-attestation --key cosign.pub --type slsaprovenance IMAGE_URI`	Bestätige spezifischen Attestationstyp
`cosign verify-attestation --key cosign.pub --policy policy.cue IMAGE_URI`	Überprüfe Attestation gegen CUE-Richtlinie
`cosign sign-blob --key cosign.key --output-signature file.sig file.txt`	Beliebige Datei signieren (Nicht-Container)
`cosign verify-blob --key cosign.pub --signature file.sig file.txt`	Blob-Signatur überprüfen
`cosign sign --key cosign.key --timestamp-server-url http://timestamp.server IMAGE_URI`	Mit RFC3161-Zeitstempel signieren
`cosign verify --certificate-identity user@example.com --certificate-oidc-issuer https://accounts.google.com IMAGE_URI`	Schlüssellosen Signatur mit Identität überprüfen
`cosign verify --key cosign.pub --rekor-url https://rekor.sigstore.dev IMAGE_URI`	Mit benutzerdefiniertem Rekor Transparency Log verifizieren
`cosign verify --key cosign.pub --insecure-ignore-tlog IMAGE_URI`	Verifizieren ohne Transparenz-Log zu prüfen
`cosign copy --platform linux/amd64 SOURCE_IMAGE DEST_IMAGE`	Bild für spezifische Plattform kopieren
`cosign copy --sig-only SOURCE_IMAGE DEST_IMAGE`	Kopiere nur Signaturen (nicht Bild)
`cosign manifest verify --key cosign.pub IMAGE_URI`	Überprüfe Signatur des Image-Manifests
`cosign upload blob --signature file.sig --payload file.txt`	Signatur zu Rekor-Transparenzprotokoll hochladen
`cosign sign --key cosign.key -r gcr.io/myproject/myimage`	Alle Tags rekursiv signieren
`cosign verify --key cosign.pub --certificate-chain chain.pem IMAGE_URI`	Mit Zertifikatskette verifizieren
`cosign attach signature --signature sig.json IMAGE_URI`	Signatur manuell an Bild anhängen
`cosign attach attestation --attestation att.json IMAGE_URI`	Attestation manuell an Bild anhängen

Konfiguration¶

Umgebungsvariablen¶

# 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

CUE Policy Datei Beispiel¶

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

Attestations-Richtlinie für Sicherheitsschwachstellen-Scans¶

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

GitHub Actions Integration¶

# .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

Häufige Anwendungsfälle¶

Anwendungsfall 1: Container-Image mit Schlüsselpaar signieren und verifizieren¶

# 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 .

Anwendungsfall 2: Schlüsselloses Signieren mit 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

Anwendungsfall 3: SBOM anhängen und verifizieren¶

# 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 .

Anwendungsfall 4: Mit Cloud KMS signieren¶

# 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

Anwendungsfall 5: Richtlinienbasierte Verifizierung mit Attestationen¶

# 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 Practices¶

Verwenden Sie immer spezifische Image-Digests: Signieren und verifizieren Sie mithilfe von @sha256:...Digests anstelle von Tags, um Angriffe durch Tag-Mutation zu verhindern. Tags können verschoben werden, aber Digests sind unveränderlich.
Speichern Sie private Schlüssel sicher: Verwenden Sie Cloud KMS (AWS KMS, Google Cloud KMS, Azure Key Vault) oder Hardware-Sicherheitsmodule (HSM) anstatt Schlüssel auf der Festplatte zu speichern. Committen Sie niemals Schlüssel in die Versionskontrolle.
Bevorzugen Sie schlüsselloses Signieren für CI/CD: Verwenden Sie OIDC-basiertes schlüsselloses Signieren in automatisierten Pipelines, um die Verwaltung langlebiger Anmeldeinformationen zu vermeiden. Dies nutzt kurzlebige Zertifikate, die an Ihren Identitätsanbieter gebunden sind.
Implementieren Sie Richtlinienerzwingung zur Laufzeit: Integrieren Sie die Cosign-Verifizierung mit Kubernetes-Admission-Controllern (wie Kyverno oder OPA Gatekeeper), um das Ausführen unsignierter oder unverifizierbarer Images zu verhindern.
Hängen Sie umfassende Attestationen an: Fügen Sie SBOM, Sicherheitsschwachstellen-Scans und SLSA-Provenance-Attestationen hinzu, um vollständige Lieferkettentransparenz zu bieten. Dies ermöglicht Prüfpfade und Compliance-Berichterstattung.
Verwenden Sie Transparenz-Logs: Verifizieren Sie immer gegen das Rekor-Transparenz-Log in der Produktion, um Signatur-Backdating oder Schlüsselkompromittierung zu erkennen. Überspringen Sie dies nur mit --insecure-ignore-tlogin luftabgeschirmten Umgebungen.
Rotieren Sie Schlüssel regelmäßig: Etablieren Sie einen Schlüsselrotationszeitplan (z.B. alle 90 Tage) und pflegen Sie einen Schlüsselwiderrufsprozess. Behalten Sie alte öffentliche Schlüssel zur Verifizierung historischer Signaturen bei.
Verifizieren Sie die Identität im schlüssellosen Modus: Geben Sie immer --certificate-identityund --certificate-oidc-issuerbei der Verifizierung schlüsselloser Signaturen an, um das Akzeptieren von Signaturen unerwarteter Identitäten zu verhindern.
Testen Sie die Verifizierung im Staging: Testen Sie Ihre Verifizierungsrichtlinien immer in Nicht-Produktionsumgebungen, bevor Sie sie in der Produktion erzwingen, um Bereitstellungsfehler zu vermeiden.
Dokumentieren Sie Ihren Signierworkflow: Pflegen Sie eine klare Dokumentation darüber, wer Images signieren darf, welche Attestationen erforderlich sind und wie Signaturen für Incident Response und Auditing verifiziert werden.

Fehlerbehebung¶

Problem	Lösung
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.