ImageTrustPolicy

​

What it needs

• supplychain.signatureDiscovery.enabled: true: the supplychain component checks who signed every running digest (keyless identity, a configured key, unsigned, invalid, or unknown). See Signature endpoints.
• The evaluator (on by default). evaluator.imageTrust.enabled follows signature discovery unless set.
• The CRDs in charts/kguardian/crds/. Helm installs that directory on first install only; on an upgrade apply them yourself: kubectl apply -f charts/kguardian/crds/. Without them the evaluator logs once and evaluates nothing.

​

Example

apiVersion: kguardian.dev/v1alpha1
kind: ImageTrustPolicy
metadata:
  name: release-signed
  namespace: shop
spec:
  images:
    - ghcr.io/example/**        # "*" = one path segment, "**" = any
  authorities:
    - name: ci
      keyless:
        issuer: https://token.actions.githubusercontent.com
        subjectRegExp: https://github\.com/example/.+/\.github/workflows/release\.yaml@refs/tags/v.+
    - name: legacy-key
      key:
        publicKey: |
          -----BEGIN PUBLIC KEY-----
          ...
          -----END PUBLIC KEY-----
  attestations:
    - predicateType: https://slsa.dev/provenance/v1
      sourceRepoRegExp: https://github\.com/example/.+

• An image is trusted when a signature from any authority verified, and every listed attestation is attached, verified and signed by one of them.
• keyless needs an issuer and a subject, each exact or a regular expression. Regular expressions must match the whole value.
• key takes the PEM or its fingerprint (sha256 of the DER public key, as kguardian reports it). kguardian’s supplychain component must hold the same key (supplychain.signatureDiscovery.publicKeys) to verify those signatures; otherwise they read as key-not-verified.
• images is matched against the image repository (docker.io/library/nginx). Empty matches every image.

​

Status

$ kubectl get itp -n shop
NAME             STATE        CONTAINERS   WOULD-DENY   UNKNOWN   LAST-EVALUATED   AGE
release-signed   evaluated    12           2            1         4m               3d

​

Generating policies

• A repository is covered only when every running digest of it verified. Unsigned, invalid, unchecked, unknown, and key-signed images whose key kguardian does not hold are listed in the header as not covered, never given a guessed signer.
• The authorities are the signers seen. A GitHub Actions subject pinned to a tag (.../release.yaml@refs/tags/v1.2.3) is widened to any tag of the same workflow, or the next release would fail; other subjects stay exact. Regular expressions are anchored.
• SLSA provenance is required when every digest of the repository has it, verified and signed by one of the authorities. policy-controller checks only attestations for an authority that lists them, so the requirement is a second ClusterImagePolicy next to the signature one.
• Image globs follow each engine. Kyverno matches the image as the pod spec writes it, so every spelling is listed, bare, with a tag and with a digest: for Docker Hub nginx, library/nginx, docker.io/nginx, docker.io/library/nginx and index.docker.io/.... policy-controller matches the normalised name (index.docker.io/library/nginx:**).
• The header lists every identity the policy trusts, with the images and digests it was seen verifying, under “review every identity before applying”: they were observed on running images, not vetted. If a rogue signer signed an image you run, it is in that list.
• A pod whose image reference was malformed when reported (a control character, line separator or over-long value) is kept in the inventory as malformed_reference and listed as not covered, never dropped. The broker counts these in kguardian_image_inventory_malformed_total{field}.
• policy-controller only checks namespaces labelled policy.sigstore.dev/include=true.

​

How it works