k8wiz
All graphs

Kyverno graph

Cosign: keyless image signing, attestations and verification with Kyverno

How a CI job signs an image with cosign and no long-lived key: an OIDC token, a 10-minute Fulcio certificate, a Rekor log entry and a Sigstore bundle attached to the image. Kyverno checks all of it before a Pod may run.

Cosign signs container images and other OCI artifacts. In keyless mode, the usual one in CI, there is no private key to store or rotate. The job proves who it is with an OIDC token, Sigstore's Fulcio CA turns that identity into a certificate that is valid for 10 minutes, and the Rekor transparency log records that the signature existed while the certificate was valid.

Cosign 3 stores the signature, the certificate and the log proof together in one Sigstore bundle, attached to the image through the OCI referrers API, so the image digest never changes. A Kyverno ImageValidatingPolicy reads those referrers at admission and admits a Pod only if a trusted identity signed its image.

Interactive graph

Click a resource to see what it does, or follow the setup step by step.

Outside the clusterMade by a toolYou write itComes with an add-onCreated by a controllercreatestrafficreferences

How it works

All 12 resources and what they do

CI job release workflow
Builds and pushes the image, then signs the digest it pushed with cosign sign --yes. id-token: write lets the job request an OIDC token from GitHub. The job's identity is the workflow file and the ref it ran from.
OIDC provider token.actions.githubusercontent.com
Issues the job a short-lived ID token. Its sub and job_workflow_ref claims name the repository, workflow and ref, which become the identity in the certificate. The issuer URL is the second half of every keyless trust rule.
Certificate authority Fulcio
Checks the ID token, then issues a code-signing certificate for the public half of a key pair cosign generated in memory. The certificate binds that key to the workflow identity and the issuer, and it expires after 10 minutes. The private key is thrown away after signing.
Transparency log Rekor
An append-only public log. Cosign records the signature and certificate there and gets back a signed entry with a timestamp. That entry proves the signature was made while the 10-minute certificate was valid, so it still verifies years later. Anyone can search the log for signatures made with their identity.
Trust root Sigstore TUF root
Distributes, through TUF, the Fulcio root certificates and the Rekor public keys that verifiers trust, plus the service URLs cosign 3 uses when signing. cosign and Kyverno fetch and cache it, so a key rotation doesn't need a new release.
Image index ghcr.io/acme/shop@sha256:5e1a…
What gets signed: the digest, not the tag. A tag can be moved to other content after signing; the digest is the hash of the exact bytes. Signing never changes this manifest, so the digest stays the same.
Signature Sigstore bundle
Pushed by cosign sign. One manifest whose single layer is the bundle: the signature over the image digest, the Fulcio certificate and the Rekor entry with its inclusion proof. Its subject points at the image, so GET /v2/acme/shop/referrers/sha256:5e1a… lists it.
Attestation SBOM (SPDX)
Pushed by cosign attest --type spdxjson --predicate sbom.spdx.json. An in-toto statement says "this SBOM describes image sha256:5e1a…" and is signed the same keyless way. It's another referrer of the image, so it travels with the image to every registry that copies it with its referrers.
ImageValidatingPolicy require-signed-shoppolicies.kyverno.io/v1
Matches images under ghcr.io/acme/* and trusts exactly one identity: the release workflow on main, as vouched for by GitHub's issuer. mutateDigest rewrites tags to the verified digest, so the node runs what was checked.
Admission controller kyverno-admission-controller
Kyverno's webhook. For each matching image it resolves the tag to a digest, lists the image's referrers, and checks each bundle: the certificate chains to Fulcio, the identity and issuer match an attestor, the Rekor entry is valid, and the signature covers this digest. It needs registry credentials for private images.
Deployment shopapps/v1
Refers to the image by tag, as most manifests do. The policy checks the Pods its ReplicaSet creates.
Pod shop-7d9c…v1
Admitted only after verification. With mutateDigest, its image reads ghcr.io/acme/shop:4f2c8e1@sha256:5e1a…, so a tag moved after admission can't change what the kubelet pulls.

Common mistakes

  • Trusting any identity from an issuer, such as subject: "*" with GitHub's issuer, trusts every repository on GitHub. Pin the repository, the workflow file and the ref.
  • Signing a tag (cosign sign ghcr.io/acme/shop:latest) signs whatever the tag points at when cosign resolves it. Use the digest from the build step's output.
  • Cosign 3 attaches bundles through the referrers API. A verifier, mirror or registry-copying tool that only knows the old sha256-….sig tags won't find them. Copy referrers along with images, and check that every verifier in the path reads bundles.
  • Private registries: Kyverno needs pull credentials to read referrers. Without them verification fails even though the kubelet, which has its own pull secret, could pull the image.
  • A policy that matches only Pods lets an unsigned Deployment through, and its ReplicaSet then fails to create Pods. kubectl describe rs shows the denial in FailedCreate events.
  • Kyverno's webhook only checks new requests. Pods that were running before the policy existed keep running until they are recreated; policy reports list them.

The manifests you write

Everything above that is marked "You write it", in one file. The rest comes from add-ons and controllers.

apiVersion: policies.kyverno.io/v1
kind: ImageValidatingPolicy
metadata:
  name: require-signed-shop
spec:
  validationActions: [Deny]
  matchConstraints:
    resourceRules:
      - apiGroups: [""]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["pods"]
  matchImageReferences:
    - glob: "ghcr.io/acme/*"
  attestors:
    - name: release
      cosign:
        keyless:
          identities:
            - issuer: https://token.actions.githubusercontent.com
              subject: https://github.com/acme/shop/.github/workflows/release.yaml@refs/heads/main
  validationConfigurations:
    mutateDigest: true
    verifyDigest: true
    required: true
  validations:
    - expression: >-
        images.containers.map(image, verifyImageSignatures(image, [attestors.release])).all(e, e > 0)
      message: shop images must be signed by the release workflow on main
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop
  namespace: shop
spec:
  replicas: 2
  selector:
    matchLabels:
      app: shop
  template:
    metadata:
      labels:
        app: shop
    spec:
      containers:
        - name: shop
          image: ghcr.io/acme/shop:4f2c8e1

Keep going

More graphs