OCI Referrers API Fallback#

Overview#

Kyverno uses the OCI Referrers API to discover signatures and attestations attached to an image digest. When verifying images, Kyverno calls remote.Referrers() from go-containerregistry to fetch the referrer index, then filters the resulting manifests by artifactType to identify what kind of artifact each referrer represents (signature, attestation, SBOM, etc.).

The key integration concern is: what happens when a registry does not support the OCI 1.1 Referrers API? Kyverno itself does not implement its own fallback — it delegates that concern to the upstream sigstore/cosign library via an explicit opt-in flag.

The cosignOCI11 Flag (ClusterPolicy / cpol)#

For the legacy ClusterPolicy (cpol) path, Kyverno exposes a cosignOCI11 boolean field on ImageVerification 1:

spec:
  rules:
    - verifyImages:
        - type: Cosign
          cosignOCI11: true
          ...

This flag defaults to false. When set to true, it is propagated through the verification stack to cosign's CheckOpts 2:

cosignOpts.ExperimentalOCI11 = opts.CosignOCI11

Setting ExperimentalOCI11 = true in cosign enables experimental OCI 1.1 behavior, which includes transparent fallback to the tag-based referrer scheme (e.g., sha256-<digest>.sig, sha256-<digest>.att) for registries that do not support the native Referrers API endpoint. The fallback itself is handled entirely within the sigstore/cosign library; Kyverno only passes the flag through.

Without cosignOCI11: true, attempting to verify an image that uses OCI 1.1 referrer storage (tag-based) will fail with no signatures found. This is demonstrated by the test TestCosignOCI11Experimental, which verifies ghcr.io/kyverno/test-verify-image:cosign-oci11 — it fails without the flag and passes with it.

Bundle Format Auto-Detection (ImageValidatingPolicy / ivpol)#

The newer ImageValidatingPolicy (ivpol) path uses a different mechanism: automatic cosign v3 bundle format detection via buildCheckOptsWithBundleDetection().

1. It enables cOpts.NewBundleFormat = true and calls cosign.GetBundles() to probe for cosign v3 bundles.
2. If no bundles are found (or an error occurs), it sets cOpts.NewBundleFormat = false and falls back to the traditional verification path (cosign.VerifyImageSignatures).
3. For attestations, the bundle path always uses cosign.VerifyImageAttestations with IntotoSubjectClaimVerifier 3.

This auto-detection is distinct from the cosignOCI11 flag: it handles the bundle format (cosign v3 .sigstore bundle vs. older OCI artifact format), not the registry's referrer API support.

ArtifactType Filtering#

All three verifier paths use artifactType to differentiate referrers in the index returned by remote.Referrers():

Referrers that do not match the expected artifactType are silently skipped 7. For in-toto attestations inside a sigstore bundle, a further predicate-type filter is applied inside the DSSE envelope 8.

A safety limit of 50 referrers is enforced in both the cosign/SigstoreBundle path 9 and the Notary path 10 to guard against compromised images with abnormally large referrer lists.

Key Source Files#