Image Verification CEL Path (IVP CEL)#

Kyverno has two distinct image-verification execution paths:

The IVP CEL path is implemented in pkg/cel/policies/ivpol/engine/engine.go and uses a two-phase admission webhook design — a mutating webhook followed by a validating webhook — rather than a single-phase handler. 1

Key Structural Difference from the Legacy Path#

The legacy path runs signature/attestation verification inside the mutating webhook via imageVerifier.Verify and emits JSON Patch operations to pin tags to digests and record ImageVerificationMetadata. The IVP CEL path separates these concerns: mutation is for digest-pinning only; actual image verification is performed exclusively in the validating phase 2.

Two-Phase Webhook Architecture#

Four HTTP routes are registered in pkg/webhooks/server.go for the IVP CEL path 1:

The policy name is embedded in the URL, so each webhook call targets only the matching policy subset.

Phase 1 — HandleMutating#

HandleMutating is the entry point for the mutating webhook. Its current implementation extracts the resource from the admission request and returns it unchanged with no patches and no policy results 3. The code comment documents this explicitly: performing signature/attestation verification here would duplicate registry calls and — critically — previously relied on the kyverno.io/image-verification-outcomes annotation to hand results to the validating webhook, an annotation that a caller could forge (see issue #16336).

The mutating phase is reserved for true mutation (e.g., tag-to-digest pinning), none of which is implemented for ImageValidatingPolicy yet.

Phase 2 — HandleValidating#

HandleValidating performs actual image verification: it fetches compiled policies, matches resources, compiles CEL expressions, and calls cosign/notary signature/attestation verification via pkg/cel/libs/imageverify/impl.go. Results are mapped to pass, fail, skip, or error 1.

Enforcement depends on ValidationAction: Deny rejects on Fail/Error; Warn emits warnings instead.

mutateDigest and verifyDigest Fields#

In the Legacy Path (ClusterPolicy)#

For ClusterPolicy/Policy, MutateDigest and VerifyDigest are boolean fields on ImageVerification, defaulting to true. When MutateDigest is true, handleMutateDigest fetches the image descriptor and emits a JSON Patch to replace the image tag with a digest. This mutation happens inside the same engine call that performs verification.

In the IVP CEL Path (ImageValidatingPolicy)#

MutateDigest and VerifyDigest are pointer-typed fields on spec.validationConfigurations. Both default to true when unset. The webhook controller's ivpolsNeedingMutation function uses these fields to determine which ImageValidatingPolicy/NamespacedImageValidatingPolicy resources need a mutating webhook registered:

mutateDigest := spec.ValidationConfigurations.MutateDigest == nil || *spec.ValidationConfigurations.MutateDigest
verifyDigest := spec.ValidationConfigurations.VerifyDigest == nil || *spec.ValidationConfigurations.VerifyDigest
// Policy gets a mutating webhook only if mutateDigest || verifyDigest

4

Tag-to-digest pinning gap: Even though mutateDigest defaults to true, the current HandleMutating implementation returns no patches 5. This means tag-to-digest pinning is not yet implemented for ImageValidatingPolicy. The mutating webhook is registered when mutateDigest or verifyDigest is enabled, but it presently does nothing. Pinning is a planned mutation responsibility of the mutating phase once implemented 2.

Setting both to false: Policies with both mutateDigest: false and verifyDigest: false are excluded from mutating webhook registration entirely 6.

Security Context: The Annotation Bypass (Issue #16336)#

The original IVP CEL design ran image verification in the mutating webhook and serialized outcomes into the kyverno.io/image-verification-outcomes annotation, which the validating webhook then read to enforce policy. This created a bypass:

• If the mutating webhook was skipped (e.g., failurePolicy: Ignore + registry timeout), a user-supplied forged annotation could be trusted by the validating webhook, admitting an unverified image 7.
• Mixed Ignore (mutate) + Fail (validate) configurations were particularly vulnerable.

The fix — decided by the Kyverno maintainers — was to move verification into the validating webhook so there is no annotation to forge 7. The current HandleMutating reflects this: it is intentionally a no-op for verification and the comment in the source explicitly references issue #16336 as the rationale 2.

The fix also calls for adding a verification cache for ImageValidatingPolicy, since verification now runs on every admission request. The existing imageVerifyCacheEnabled cache is wired only into the legacy ClusterPolicy engine 7.

Background scan is unaffected: it re-verifies independently rather than trusting the annotation 7.

Key Source Files#