ImageValidatingPolicy
The Kyverno ImageValidatingPolicy type is a Kyverno policy type designed for verifying container image signatures and attestations.
Additional Fields
The ImageValidatingPolicy extends the Kyverno ValidatingPolicy with the following additional fields for image verification features. A complete reference is provided in the API specification
images
When Kubernetes resources are evaluated images for pods and pod templates are automatically extracted for processing. For custom resources, or for JSON payloads, the images field can be used to declare CEL expressions that extract images from the payload.
For example, this policy declaration will process the image specified in the imageReference field:
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: sample
5spec:
6 evaluation:
7 mode: JSON
8 images:
9 - name: imagerefs
10 expression: "[object.imageReference]"
11 ...
matchImageReferences
The spec.matchImageReferences field defines rules for matching container images. It allows specifying glob patterns or CEL expressions that specify which images the policy should match.
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: check-images
5spec:
6 matchImageReferences: # At least one sub-field is required
7 - glob: "ghcr.io/kyverno/*" # Match images using glob pattern
8 - expression: "image.registry == 'ghcr.io'" # Match using CEL expression
9 ...
attestors
The attestors field declares trusted signing authorities, such as keys or certificates.
Cosign attestors: These use public keys, keyless signing, transparency logs, certificates, or TUF-based metadata for image validation.
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: check-images
5spec:
6 matchConstraints:
7 resourceRules:
8 - apiGroups: [""]
9 apiVersions: ["v1"]
10 operations: ["CREATE"]
11 resources: ["pods"]
12 variables:
13 - name: cm
14 expression: >-
15 resource.Get("v1", "configmaps", object.metadata.namespace, "keys")
16 attestors:
17 - name: cosign # A unique name to identify this attestor
18 cosign:
19 key: # Public key-based verification and At least one sub-field is required
20 expression: variables.cm.data.pubKey # CEL expression that resolves to the public key
21 kms: "gcpkms://..." # KMS URI for key verification (e.g., GCP KMS, AWS KMS)
22 hashAlgorithm: "sha256" # Optional hash algorithm used with the key
23 data: | # Direct inline public key data (optional if secretRef or kms is used)
24 -----BEGIN PUBLIC KEY-----
25 ...
26 -----END PUBLIC KEY-----
27
28 keyless: # Keyless signing verification (OIDC-based)
29 identities: # List of accepted signing identities
30 - subject: "https://github.com/myorg/myrepo/.github/workflows/deploy.yaml@refs/heads/main"
31 issuer: "https://token.actions.githubusercontent.com"
32 subjectRegExp: ".*github\\.com/.*/.*/.github/workflows/.*" # Optional regex for subject matching
33 issuerRegExp: "https://token\\.actions\\.githubusercontent\\.com" # Optional regex for issuer matching
34 root: | # Roots is an optional set of PEM encoded trusted root certificates. If not provided, the system roots are used.
35 -----BEGIN CERTIFICATE-----
36 ...
37 -----END CERTIFICATE-----
38
39 ctlog: # Transparency log settings (e.g., Rekor)
40 url: "https://rekor.sigstore.dev"
41 rekorPubKey: | # Public key for verifying Rekor entries
42 -----BEGIN PUBLIC KEY-----
43 ...
44 -----END PUBLIC KEY-----
45 ctLogPubKey: | # Public key for verifying CT log entries (optional)
46 -----BEGIN PUBLIC KEY-----
47 ...
48 -----END PUBLIC KEY-----
49 tsaCertChain: | # Certificate chain for Time Stamp Authority (optional)
50 -----BEGIN CERTIFICATE-----
51 ...
52 -----END CERTIFICATE-----
53 insecureIgnoreTlog: false # Skip TLog verification (for testing only)
54 insecureIgnoreSCT: false # Skip Signed Certificate Timestamp (for testing only)
55
56 certificate: # Certificate-based verification and At least one sub-field is required
57 cert:
58 value: | # Inline signing certificate
59 -----BEGIN CERTIFICATE-----
60 ...
61 -----END CERTIFICATE-----
62 expression: variables.cm.data.cert # CEL expression resolving to certificate
63 certChain: # At least one sub-field is required
64 value: | # Certificate chain associated with the signer o
65 -----BEGIN CERTIFICATE-----
66 ...
67 -----END CERTIFICATE-----
68 expression: variables.cm.data.certChain # CEL expression resolving to certificate
69
70 source: # Optional metadata to constrain image source (optional)
71 repository: "ghcr.io/myorg/myimage" # Limit to specific image repo
72 pullSecrets: # Kubernetes secrets used to access the registry
73 - name: my-registry-secret
74 tagPrefix: "v1." # Restrict verification to images starting with this tag
75
76 tuf:
77 root:
78 path: "/var/run/tuf/root.json" # Local path to TUF root metadata (optional)
79 data: | # Optional base64-encoded TUF root metadata (optional)
80 eyJzaWduZWQiOiB7Li4ufSwgInNpZ25hdHVyZXMiOiBbLi4uXX0=
81 mirror: "https://tuf.example.org" # Sigstore TUF mirror URL (optional)
82
83 ...
Notary attestors: These use certificates and optional Time Stamp Authority (TSA) certificates for image signature verification.
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: check-images
5spec:
6 matchConstraints:
7 resourceRules:
8 - apiGroups: [""]
9 apiVersions: ["v1"]
10 operations: ["CREATE"]
11 resources: ["pods"]
12 variables:
13 - name: cm
14 expression: >-
15 resource.Get("v1", "configmaps", object.metadata.namespace, "keys")
16 expression:
17 - name:
18 expression:
19 matchImageReferences:
20 - glob: ghcr.io/*
21 attestors:
22 - name: notary # Unique identifier for this attestor
23 notary:
24 certs: # At least one sub-field is required
25 value: | # Certificate(s) used to verify the signature or CEL expression resolving to certificate(s)
26 -----BEGIN CERTIFICATE-----
27 MIIBjTCCATOgAwIBAgIUdMiN3gC...
28 -----END CERTIFICATE-----
29
30 expression: variables.cm.data.cert # CEL expression resolving to certificate(s)
31
32 tsaCerts: # At least one sub-field is required
33 value: | # Optional: Time Stamp Authority (TSA) certificates
34 -----BEGIN CERTIFICATE-----
35 MIIC4jCCAcqgAwIBAgIQAm3T2tWk...
36 -----END CERTIFICATE-----
37
38 expression: variables.cm.data.tsaCert # Optional: CEL expression resolving to TSA certificate(s)
39
40
attestations
The attestations field specifies additional metadata to validate.
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: check-images
5spec:
6 matchConstraints:
7 resourceRules:
8 - apiGroups: [""]
9 apiVersions: ["v1"]
10 operations: ["CREATE"]
11 resources: ["pods"]
12 matchImageReferences:
13 - glob: ghcr.io/*
14 attestors:
15 - name: notary
16 notary:
17 certs:
18 value: |-
19 -----BEGIN CERTIFICATE-----
20 MIIBjTCCATOgAwIBAgIUdMiN3gC...
21 -----END CERTIFICATE-----
22 attestations:
23 - name: sbom # Logical name for this attestation
24 referrer: # Uses OCI artifact type for verification
25 type: sbom/cyclone-dx
26
27 - name: toto # Another attestation named `toto`
28 intoto:
29 type: https://example.com/attestations/slsa-provenance/v0.2 # Predicate type URI for in-toto format
validationConfigurations
The validationConfigurations field defines settings for mutating image tags to digests, verifying that images are using digests, and enforcing image validation requirements across policies.
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: check-images
5spec:
6 matchImageReferences:
7 - glob: ghcr.io/*
8 validationConfigurations:
9 mutateDigest: true # Mutates image tags to digests (recommended to avoid mutable tags).
10 required: true # Enforces that images must be validated according to policies.
11 verifyDigest: true # Ensures that images are verified with a digest instead of tags.
credentials
Credentials specify the authentication information required to securely access and interact with a registry.
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: check-images
5spec:
6 matchImageReferences:
7 - glob: ghcr.io/*
8 credentials:
9 allowInsecureRegistry: false # Deny insecure access to registries
10 providers: # specifies whose authentication providers are provided
11 - "default"
12 - "google"
13 - "azure"
14 - "amazon"
15 - "github"
16
17 secrets:
18 - "my-registry-secret" # Secrets specifies a list of secrets that are provided for credentials. Secrets must live in the Kyverno namespace.
Kyverno CEL Libraries
Kyverno enhances Kubernetes’ CEL environment with libraries enabling complex policy logic and advanced features for image validation. In addition to common Kyverno CEL Libraries the following additional libraries are supported for ImageValidatingPolicy types.
Image Verification Library
Kyverno provides specialized functions for verifying image signatures and attestations:
| CEL Expression | Purpose |
|---|---|
images.containers | Retrieves all container images in the resource |
verifyImageSignatures(image, [attestors.notary]) | Verify image signatures using specified attestors |
verifyAttestationSignatures(image, attestations.sbom, [attestors.notary]) | Verify attestation signatures for specific metadata |
extractPayload(image, attestations.sbom).bomFormat == 'CycloneDX' | Extract the in-toto payload |
The following policy demonstrates the use of these functions:
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: check-images
5spec:
6 matchConstraints:
7 resourceRules:
8 - apiGroups: [""]
9 apiVersions: ["v1"]
10 operations: ["CREATE"]
11 resources: ["pods"]
12 matchImageReferences:
13 - glob: ghcr.io/*
14 attestors:
15 - name: notary
16 notary:
17 certs:
18 value: |-
19 -----BEGIN CERTIFICATE-----
20 ...
21 -----END CERTIFICATE-----
22 attestations:
23 - name: sbom
24 referrer:
25 type: sbom/cyclone-dx
26 validations:
27 - expression: >-
28 images.containers.map(image, verifyImageSignatures(image, [attestors.notary])).all(e, e > 0)
29 message: failed to verify image with notary cert
30 - expression: >-
31 images.containers.map(image, verifyAttestationSignatures(image,
32 attestations.sbom, [attestors.notary])).all(e, e > 0)
33 message: failed to verify attestation with notary cert
34 - expression: >-
35 images.containers.map(image, extractPayload(image, attestations.sbom).bomFormat == 'CycloneDX').all(e, e)
36 message: sbom is not a cyclone dx sbom
This policy ensures that:
- All images are signed by the specified notary attestor
- All images have valid SBOM attestations
- All SBOMs are in CycloneDX format
Note: extractPayload() requires prior attestation verification via verifyAttestationSignatures(). If not verified, it will return an error.
Cosign Keyless Signature and Attestation Verification
This sample policy demonstrates how to verify container image signatures using Cosign keyless signing and validate the presence of a vulnerability scan attestation.
Kyverno supports the use of regular expressions in identities.subjectRegExp and identities.issuerRegExp fields when configuring keyless attestors
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: require-vulnerability-scan
5spec:
6 validationActions: [Audit]
7 webhookConfiguration:
8 timeoutSeconds: 15
9 failurePolicy: Fail
10 matchConstraints:
11 resourceRules:
12 - apiGroups: [""]
13 apiVersions: ["v1"]
14 resources: ["pods"]
15 operations: ["CREATE", "UPDATE"]
16 matchImageReferences:
17 - glob: "ghcr.io/myorg/myrepo:*"
18 attestors:
19 - name: cosign
20 cosign:
21 keyless:
22 identities:
23 - subject: "https://github.com/myorg/myrepo/.github/workflows/*"
24 issuer: "https://token.actions.githubusercontent.com"
25 ctlog:
26 url: "https://rekor.sigstore.dev"
27 attestations:
28 - name: cosign-attes
29 intoto:
30 type: cosign.sigstore.dev/attestation/vuln/v1
31 validations:
32 - expression: >-
33 images.containers.map(image, verifyImageSignatures(image, [attestors.cosign])).all(e, e > 0)
34 message: "Failed image signature verification"
35 - expression: >-
36 images.containers.map(image, verifyAttestationSignatures(image, [attestations.cosign-attes], [attestors.cosign])).all(e, e > 0)
37 message: "Failed to verify vulnerability scan attestation with Cosign keyless"
Cosign Public Key Signature Verification
This policy ensures that container images are signed with a specified Cosign public key before being admitted.
1apiVersion: policies.kyverno.io/v1alpha1
2kind: ImageValidatingPolicy
3metadata:
4 name: verify-image-ivpol
5spec:
6 webhookConfiguration:
7 timeoutSeconds: 15
8 evaluation:
9 background:
10 enabled: false
11 validationActions: [Deny]
12 matchConstraints:
13 resourceRules:
14 - apiGroups: [""]
15 apiVersions: ["v1"]
16 operations: ["CREATE", "UPDATE"]
17 resources: ["pods"]
18 matchImageReferences:
19 - glob : "docker.io/kyverno/kyverno*"
20 attestors:
21 - name: cosign
22 cosign:
23 key:
24 data: |
25 -----BEGIN PUBLIC KEY-----
26 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE6QsNef3SKYhJVYSVj+ZfbPwJd0pv
27 DLYNHXITZkhIzfE+apcxDjCCkDPcJ3A3zvhPATYOIsCxYPch7Q2JdJLsDQ==
28 -----END PUBLIC KEY-----
29 validations:
30 - expression: >-
31 images.containers.map(image, verifyImageSignatures(image, [attestors.cosign])).all(e ,e > 0)
32 message: >-
33 failed the image Signature verification
Note: To learn how to sign container images using Cosign with keyless signing, refer to the official Cosign documentation.
Policies are applied cluster-wide to help secure your cluster. However, there may be times when teams or users need to test specific tools or resources. In such cases, users can use PolicyException to bypass policies without modifying or tweaking the policies themselves. This ensures that your policies remain secure while providing the flexibility to bypass them when needed.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.