Image signing — Cosign, Sigstore, and verification · Docker & Containers

Image signing proves that an image is exactly what you think it is — which is a sentence that sounds much stronger than what a signature actually says. Start with the precise version, because every mistake in this area comes from the imprecise one.

What a signature attests

A Cosign signature over an image asserts exactly this:

Some holder of this signing key — or, for keyless signing, some holder of a certificate binding a public key to this OIDC identity — performed a signing operation over this manifest digest.

That is the whole statement. Everything else is inference from surrounding context, and the inferences people make are:

People assume the signature says	It actually says
The image is safe to run	Nothing about the contents
The code was reviewed	Nothing about the source
The build was not tampered with	Nothing about the build (that is provenance)
The publisher endorses it for production	Only that a signing operation happened
The image is current	Nothing; a signature does not expire with the image

The last row deserves emphasis. A signature over a two-year-old image riddled with known vulnerabilities verifies perfectly. Signing and scanning are orthogonal controls and neither substitutes for the other.

What signing does give you is enormous and specific: the registry stops being a trusted party. Without a signature, “this image came from our registry” is a claim the registry makes about itself. With one, a consumer verifies against a publisher identity, and an attacker who fully controls the registry still cannot make you accept an image your publisher did not sign.

Signing with a key

Configuration changegenerate a keypair and sign— Sign the digest, never the tag. A tag is a pointer somebody else can move; the digest is the artefact.

DIGEST=sha256:REPLACE_ME
IMG="registry.example.com/myorg/myapp@${DIGEST}"

cosign generate-key-pair
cosign sign --key cosign.key "$IMG"

Read-only / Safeverify with the public key— Exit status is the answer. A non-zero exit is the control; the printed payload is for humans.

DIGEST=sha256:REPLACE_ME
IMG="registry.example.com/myorg/myapp@${DIGEST}"

cosign verify --key cosign.pub "$IMG"

Cosign also accepts a KMS reference in place of a file — --key <provider>://<key> for AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault, OpenBao and Kubernetes secrets. That is the right answer when you keep long-lived keys: the private key never leaves the KMS, and every signing operation is logged by an auditable service you already operate.

The long-lived signing key on the build server

The default key-based setup puts cosign.key somewhere the CI job can read it. That file is now the single most valuable object in your supply chain, and it lives on the machine that runs arbitrary code from every pull request.

The failure is not subtle when it happens: anyone who exfiltrates that key can sign anything, and every verifier in your estate will accept it. Because signatures do not expire, they will keep accepting it after you rotate — you have to actively remove the old public key from every trust store, and finding every trust store is the hard part.

The mitigations, in order:

Do not have a long-lived key. Keyless signing, below, removes the object entirely.
If you must, put it in a KMS, so the key material never lands on the build host and every use is logged.
Never let a shared runner see it. A dedicated, minimal signing step with no access to build inputs.

The version of this that catches people out is a key committed to a repository “temporarily” during setup. Treat that as a full compromise of everything signed with it.

Keyless signing

For CI, the right answer is usually to have no key at all.

Configuration changekeyless signing in CI— No --key means keyless. Cosign obtains an OIDC token from the CI environment and requests a short-lived certificate.

DIGEST=sha256:REPLACE_ME
IMG="registry.example.com/myorg/myapp@${DIGEST}"

cosign sign "$IMG"

In current Cosign releases, keyless is simply the path taken when no --key is supplied. Older material wraps this in COSIGN_EXPERIMENTAL=1; that was required by Cosign 1.x and is not part of the current documented invocation.

What Fulcio and Rekor actually do

Keyless signing does not mean “signing without cryptography”. It means the key exists for about a minute and then ceases to exist.

1. Ephemeral keypair. Cosign generates a keypair in memory.

2. OIDC identity. It obtains an identity token from the environment — for GitHub Actions, a workflow token whose claims include the repository, the workflow file and the ref that triggered it. Nobody typed a password; the CI platform asserts the identity.

3. Fulcio. Cosign presents the token and the ephemeral public key to Fulcio, a certificate authority that issues a short-lived X.509 certificate binding that public key to the identity in the token. The certificate is valid for minutes.

4. Sign. Cosign signs the image digest with the ephemeral private key, then discards it. There is now no key to steal, rotate or leak.

5. Rekor. The signature, the certificate and the digest are recorded in Rekor, an append-only transparency log. Rekor returns a signed timestamp and an inclusion proof.

Step 5 is what makes step 4 verifiable later. The certificate expired minutes after it was issued, so a verifier reading it next year cannot simply check “is this certificate valid now” — it never will be again. Instead the verifier checks that the Rekor entry proves the signature existed while the certificate was valid. The transparency log substitutes for certificate validity, and it does something a conventional PKI cannot: it makes signing events public, so a publisher can detect signatures issued in their name that they did not make.

The trade is a dependency. Verification consults Fulcio’s roots and, by default, Rekor. Cosign v3 defaults to storing signatures in bundles that carry the material needed for verification, which reduces how much must be fetched at verify time — but keyless verification remains a richer operation than checking one public key, and air-gapped environments need deliberate planning for it.

Verification, and the one that accepts anything

This is the part that goes wrong.

Read-only / Safekeyless verification, constrained— The identity and issuer constraints are the control. Without them there is no policy, only a cryptographic formality.

DIGEST=sha256:REPLACE_ME
IMG="registry.example.com/myorg/myapp@${DIGEST}"

cosign verify \
--certificate-identity-regexp '^https://github\.com/myorg/myapp/\.github/workflows/release\.yml@refs/heads/main$' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
"$IMG"

For keyless flows, either --certificate-identity or --certificate-identity-regexp must be set — Cosign will not run without one. There is an equivalent pair for the issuer: --certificate-oidc-issuer and --certificate-oidc-issuer-regexp.

--certificate-identity-regexp '.*' accepts every Sigstore user on earth

Cosign requires an identity constraint. It does not require a useful one, and the shortest way past the requirement is a wildcard.

cosign verify "$IMG" \
  --certificate-identity-regexp '.*' \
  --certificate-oidc-issuer-regexp '.*'

That command exits zero for any image anybody has ever signed with Sigstore. An attacker signs their own image with their own GitHub account, and this verification passes. It is not a weaker control than a good policy — it is no control, wearing the costume of one, and it appears in CI logs as a green “signature verified” line.

The variants that reach production:

--certificate-identity-regexp '.*' added to unblock a pipeline during an incident and never narrowed.
A regexp anchored at neither end, so 'https://github.com/myorg/' matches https://github.com/myorg-evil/... on some patterns, or matches a substring anywhere in a longer identity.
No --certificate-oidc-issuer, so an identity string from a different, attacker-chosen IdP satisfies the identity check.

Anchor your regexps with ^ and $. Pin the issuer exactly. Review the identity constraint as carefully as you would review a firewall rule, because it is one.

Verifying a tag verifies whatever the tag points at now

cosign verify myorg/myapp:1.4.0 resolves the tag first and then verifies the digest it resolved to. If the tag has moved, you have verified a signature over the new image — which is correct behaviour and is not what the operator intended.

The safe pattern is to resolve once, verify that digest, and deploy that same digest:

DIGEST=$(docker buildx imagetools inspect registry.example.com/myorg/myapp:1.4.0 \
  | awk '/^Digest:/ {print $2; exit}')
REF="registry.example.com/myorg/myapp@${DIGEST}"

cosign verify --key cosign.pub "$REF"
docker pull "$REF"

Verifying the tag and then deploying the tag leaves a window in which the tag can move between the two operations. It is a small window and it is entirely avoidable.

Enforcement

A verification nobody enforces is a log line. Where you enforce depends on what runs your containers, and the honest summary is uneven:

Kubernetes. An admission controller is the strong answer, because it sits in the path of every workload creation and cannot be bypassed by a person with kubectl.

Configuration changeKyverno keyless verification policy— verifyImages is the mechanism. Checking for an annotation is not — annotations are attacker-controlled and prove nothing.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: check-image-keyless
spec:
webhookConfiguration:
  timeoutSeconds: 30
rules:
  - name: check-image-keyless
    match:
      any:
        - resources:
            kinds:
              - Pod
    verifyImages:
      - imageReferences:
          - 'registry.example.com/myorg/*'
        failureAction: Enforce
        attestors:
          - entries:
              - keyless:
                  subject: 'https://github.com/myorg/*'
                  issuer: 'https://token.actions.githubusercontent.com'
                  rekor:
                    url: https://rekor.sigstore.dev

The verifyImages rule also offers mutateDigest, which rewrites a tag reference to the digest that was verified, and verifyDigest, which refuses tag references outright. Both close the verify-then-deploy window described above, at the cluster level.

Plain Docker hosts. There is no daemon-level signature enforcement to rely on. Docker Content Trust is being retired — the Notary v1 service at notary.docker.io shuts down on 8 December 2026 — and it was never a Cosign mechanism anyway.

So on a standalone host, enforcement is your deploy tooling. Make it a gate that fails closed:

Configuration changedeploy gate on a standalone host— Verification runs before the pull, and the script exits non-zero if it fails. set -e is doing real work here.

set -euo pipefail

REPO=registry.example.com/myorg/myapp
TAG=1.4.0
IDENTITY='^https://github\.com/myorg/myapp/\.github/workflows/release\.yml@refs/heads/main$'
ISSUER='https://token.actions.githubusercontent.com'

DIGEST=$(docker buildx imagetools inspect "${REPO}:${TAG}" \
| awk '/^Digest:/ {print $2; exit}')
REF="${REPO}@${DIGEST}"

cosign verify \
--certificate-identity-regexp "$IDENTITY" \
--certificate-oidc-issuer "$ISSUER" \
"$REF" > /dev/null

echo "verified: $REF"
docker pull "$REF"

verified: registry.example.com/myorg/myapp@sha256:4f2a...c19d
sha256:4f2a...c19d: Pulling from myorg/myapp

Illustrative output

BuildKit and Compose. Neither verifies signatures. Do not assume a docker compose pull checks anything; it does not.

Rotation

Sign new releases with the new key while the old public key is still in every trust store.
Optionally re-sign current releases with the new key — the registry holds multiple signatures for one digest happily, and this lets verifiers move independently.
Distribute the new public key to every verifier: CI, admission policies, deploy scripts, other teams.
Confirm every verifier accepts the new key before removing anything.
Remove the old public key from the trust stores. This is the step that actually revokes it.

Step 5 is the whole rotation. Signatures do not expire, so a compromised key keeps producing valid signatures until every verifier stops trusting it. “We rotated” means nothing until you can enumerate the trust stores you updated — which is a strong practical argument for keyless, where there is no long-lived key to rotate and revocation is expressed by narrowing the identity policy instead.

What if verification fails during a production deploy at 02:00?

The correct action is to stop, and the pressure will be to override. Work through it in this order.

1. Determine which check failed. The failure modes look similar in a pipeline log and mean very different things:

No signature found — the publishing pipeline did not sign, or signed a different digest, or the signature was garbage-collected from the registry. Most often this is an operational gap, not an attack.
Identity mismatch — a signature exists but from an identity your policy does not accept. Frequently a legitimate change (the release workflow was renamed, the branch changed) and occasionally not.
Signature does not verify against the digest — the serious one. The content does not match what was signed.
Transparency log or Fulcio unreachable — an availability problem in the verification path, not a statement about the image.

2. Check the digest against your build records. Did your pipeline produce this digest? If the answer is no, you are in an incident and the deploy is over.

3. Do not disable the check to get the deploy out. The override that “we will re-enable tomorrow” is how every one of these ends up permanently off. If you genuinely must ship, deploy the previous known good digest, which verifies, rather than bypassing verification for the new one.

4. If the cause is verifier-side availability, the design question is whether your gate should fail open or fail closed on an infrastructure error — and that decision belongs in a design review on a calm afternoon, written down, not improvised at 02:00 by whoever is holding the pager.

Rehearse this. A signature gate that has never failed in a drill will be turned off the first time it fails for real.

Why this matters

Signing is what removes the registry from your trusted computing base. That is a genuinely large change: without it, every statement about what you deploy ultimately rests on the registry being honest and uncompromised, and the registry is a service with push credentials scattered across your estate.

The failure modes are not cryptographic. Nobody breaks the signature. They verify a tag instead of a digest, or accept any identity because the regexp was widened during an incident, or check for an annotation that proves nothing, or verify in CI while nothing enforces at deploy. Every one of those produces a green line in a log.

Read your own verification command as though you were trying to defeat it. If a stranger with a GitHub account could sign an image that passes, it is not a control.