Dosu LogoDosu Logo
Ask
Join our Discord
kyvernoPublic
Nirmata
Documentskyverno
OCI Referrers API Fallback
OCI Referrers API Fallback
Type
Topic
Status
Published
Created
Jul 21, 2026
Updated
Jul 21, 2026
Created by
Dosu Bot
Updated by
Dosu Bot

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 :

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 :

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 .

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():

VerifierArtifactType filterCode
Cosign / SigstoreBundle (cpol)strings.HasPrefix(manifestDesc.ArtifactType, "application/vnd.dev.sigstore.bundle")
Notary (cpol, attestations)ref.ArtifactType == expectedArtifactType (caller passes opts.Type)
Notary (cpol, signatures)d.ArtifactType == notationregistry.ArtifactTypeNotation

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

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


Key Source Files#

FilePurpose
pkg/image/verifiers/cpol/cosign/cosign.goBuilds cosign.CheckOpts; sets ExperimentalOCI11
pkg/image/verifiers/cpol/cosign/sigstore.goCalls remote.Referrers(), filters by artifactType, fetches & parses bundles
pkg/image/verifiers/ivpol/cosign/verifier.goAuto-detects cosign v3 bundle format; falls back to legacy verification
pkg/image/verifiers/cpol/notary/notary.goNotary: fetches referrers, filters by artifactType, extracts statements
pkg/image/verifiers/cpol/notary/repository.goNotary: ListSignatures filters for application/vnd.cncf.notary.signature only
api/kyverno/v1/image_verification_types.goDefines CosignOCI11 policy field
Documents
Background Controller Trigger Validation
Background Controller UpdateRequest Processing
Background Mutation Engine
Background Scan Report Reconciliation
CEL Context Injection
CEL Policy Exception Handling
CLI Policy Result Processing
CLI Policy Testing
CLI Resource Resolution
CLI Worker Pool Management
Concurrency Safety
Engine Context Propagation
Generate Policy UpdateRequest Lifecycle
GeneratingPolicy Downstream Cleanup
GeneratingPolicy Synchronization and Reconciliation
Image Verification CEL Path
ImageValidatingPolicy Webhook Architecture
JMESPath Type Safety
JSON Patch Mutation
MutatingPolicy Resource Targeting
NamespaceSelector Policy Enforcement
OCI Referrers API Fallback
Policy Controller Reconciliation
Projected Service Account Token
Prometheus Metrics Integration
Report Controller Goroutine Lifecycle
Sigstore & TUF Integration
TTL Controller Lifecycle
ValidatingPolicy Autogen
ValidatingPolicy Engine
ValidatingPolicy Status Management
Webhook Generation
Webhook Lifecycle Management
Webhook Selector Grouping