Cosign Cheatsheet¶

Installation¶

Platform	Command
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`

Basic Commands¶

Command	Description
`cosign version`	Display cosign version information
`cosign help`	Show all available commands and options
`cosign generate-key-pair`	Generate a new key pair (cosign.key and cosign.pub)
`cosign generate-key-pair --output-key-prefix mykey`	Generate key pair with custom prefix
`cosign sign --key cosign.key IMAGE_URI`	Sign a container image with private key
`cosign sign IMAGE_URI`	Sign image using keyless mode (OIDC)
`cosign verify --key cosign.pub IMAGE_URI`	Verify image signature with public key
`cosign verify IMAGE_URI`	Verify keyless signature
`cosign sign --key cosign.key -a key=value IMAGE_URI`	Sign image with custom annotations
`cosign verify --key cosign.pub -a key=value IMAGE_URI`	Verify signature and check annotations
`cosign triangulate IMAGE_URI`	Find signature location for an image
`cosign download signature IMAGE_URI`	Download signature for an image
`cosign download attestation IMAGE_URI`	Download attestations for an image
`cosign copy SOURCE_IMAGE DEST_IMAGE`	Copy image with signatures to new location
`cosign sign --key cosign.key IMAGE1 IMAGE2 IMAGE3`	Sign multiple images at once
`cosign verify --key cosign.pub IMAGE_URI --output json`	Output verification results as JSON
`cosign sign --key cosign.key gcr.io/project/image@sha256:abc123...`	Sign specific image digest
`cosign public-key --key cosign.key`	Extract public key from private key
`cosign initialize`	Initialize cosign with root of trust
`cosign tree IMAGE_URI`	Display signature and attestation tree for image

Advanced Usage¶

Command	Description
`cosign generate-key-pair --kms gcpkms://projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY`	Generate key pair in Google Cloud KMS
`cosign generate-key-pair --kms awskms://arn:aws:kms:region:account:key/key-id`	Generate key pair in AWS KMS
`cosign generate-key-pair --kms azurekms://vault.vault.azure.net/keys/keyname/version`	Generate key pair in Azure Key Vault
`cosign generate-key-pair --kms hashivault://transit/keys/cosign`	Generate key pair in HashiCorp Vault
`cosign attest --key cosign.key --predicate predicate.json IMAGE_URI`	Attach attestation to image
`cosign attest --key cosign.key --type slsaprovenance --predicate provenance.json IMAGE_URI`	Attach SLSA provenance attestation
`cosign attest --key cosign.key --type vuln --predicate scan-results.json IMAGE_URI`	Attach vulnerability scan attestation
`cosign attest --key cosign.key --type spdx --predicate sbom.spdx.json IMAGE_URI`	Attach SBOM attestation
`cosign verify-attestation --key cosign.pub IMAGE_URI`	Verify attestations on image
`cosign verify-attestation --key cosign.pub --type slsaprovenance IMAGE_URI`	Verify specific attestation type
`cosign verify-attestation --key cosign.pub --policy policy.cue IMAGE_URI`	Verify attestation against CUE policy
`cosign sign-blob --key cosign.key --output-signature file.sig file.txt`	Sign arbitrary file (non-container)
`cosign verify-blob --key cosign.pub --signature file.sig file.txt`	Verify blob signature
`cosign sign --key cosign.key --timestamp-server-url http://timestamp.server IMAGE_URI`	Sign with RFC3161 timestamp
`cosign verify --certificate-identity user@example.com --certificate-oidc-issuer https://accounts.google.com IMAGE_URI`	Verify keyless signature with identity
`cosign verify --key cosign.pub --rekor-url https://rekor.sigstore.dev IMAGE_URI`	Verify with custom Rekor transparency log
`cosign verify --key cosign.pub --insecure-ignore-tlog IMAGE_URI`	Verify without checking transparency log
`cosign copy --platform linux/amd64 SOURCE_IMAGE DEST_IMAGE`	Copy image for specific platform
`cosign copy --sig-only SOURCE_IMAGE DEST_IMAGE`	Copy only signatures (not image)
`cosign manifest verify --key cosign.pub IMAGE_URI`	Verify image manifest signature
`cosign upload blob --signature file.sig --payload file.txt`	Upload signature to Rekor transparency log
`cosign sign --key cosign.key -r gcr.io/myproject/myimage`	Sign all tags recursively
`cosign verify --key cosign.pub --certificate-chain chain.pem IMAGE_URI`	Verify with certificate chain
`cosign attach signature --signature sig.json IMAGE_URI`	Manually attach signature to image
`cosign attach attestation --attestation att.json IMAGE_URI`	Manually attach attestation to image

Configuration¶

Environment Variables¶

# 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 File Example¶

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

Attestation Policy for Vulnerability 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

Common Use Cases¶

Use Case 1: Sign and Verify Container Image with Key Pair¶

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

Use Case 2: Keyless Signing with 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

Use Case 3: Attach and Verify 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 .

Use Case 4: Sign with 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

Use Case 5: Policy-Based Verification with Attestations¶

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

Always use specific image digests: Sign and verify using @sha256:... digests instead of tags to prevent tag mutation attacks. Tags can be moved, but digests are immutable.
Store private keys securely: Use cloud KMS (AWS KMS, Google Cloud KMS, Azure Key Vault) or hardware security modules (HSM) instead of storing keys on disk. Never commit keys to version control.
Prefer keyless signing for CI/CD: Use OIDC-based keyless signing in automated pipelines to avoid managing long-lived credentials. This leverages short-lived certificates tied to your identity provider.
Implement policy enforcement at runtime: Integrate cosign verification with Kubernetes admission controllers (like Kyverno or OPA Gatekeeper) to prevent unsigned or unverified images from running.
Attach comprehensive attestations: Include SBOM, vulnerability scans, and SLSA provenance attestations to provide full supply chain transparency. This enables audit trails and compliance reporting.
Use transparency logs: Always verify against Rekor transparency log in production to detect signature backdating or key compromise. Only skip with --insecure-ignore-tlog in air-gapped environments.
Rotate keys regularly: Establish a key rotation schedule (e.g., every 90 days) and maintain a key revocation process. Keep old public keys for verifying historical signatures.
Verify identity in keyless mode: Always specify --certificate-identity and --certificate-oidc-issuer when verifying keyless signatures to prevent accepting signatures from unexpected identities.
Test verification in staging: Always test your verification policies in non-production environments before enforcing in production to avoid deployment failures.
Document your signing workflow: Maintain clear documentation of who can sign images, what attestations are required, and how to verify signatures for incident response and auditing.

Troubleshooting¶

Issue	Solution
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.
Slow signature verification	Verification requires downloading signatures from registry. Use `--attachment-tag-prefix` to optimize lookup, or cache verification results in your deployment pipeline.