containerd/docs/image-verification.md

Image Verification

The following covers the default "bindir" ImageVerifier plugin implementation.

To enable image verification, add a stanza like the following to the containerd config:

[plugins]
  [plugins."io.containerd.image-verifier.v1.bindir"]
    bin_dir = "/opt/containerd/image-verifier/bin"
    max_verifiers = 10
    per_verifier_timeout = "10s"

All files in bin_dir, if it exists, must be verifier executables which conform to the following API.

Image Verifier Binary API

CLI Arguments

• -name: The given reference to the image that may be pulled.
• -digest: The resolved digest of the image that may be pulled.
• -stdin-media-type: The media type of the JSON data passed to stdin.

Standard Input

A JSON encoded payload is passed to the verifier binary's standard input. The media type of this payload is specified by the -stdin-media-type CLI argument, and may change in future versions of containerd. Currently, the payload has a media type of application/vnd.oci.descriptor.v1+json and represents the OCI Content Descriptor of the image that may be pulled. See the OCI specification for more details.

Image Pull Judgement

Print to standard output a reason for the image pull judgement.

Return an exit code of 0 to allow the image to be pulled and any other exit code to block the image from being pulled.

Image Verifier Caller Contract

• If bin_dir does not exist or contains no files, the image verifier does not block image pulls.
• An image is pulled only if all verifiers that are called return an "ok" judgement (exit with status code 0). In other words, image pull judgements are combined with an AND operator.
• If any verifiers exceeds the per_verifier_timeout or fails to exec, the verification fails with an error and a nil judgement is returned.
• If max_verifiers < 0, there is no imposed limit on the number of image verifiers called.
• If max_verifiers >= 0, there is a limit imposed on the number of image verifiers called. The entries in bin_dir are lexicographically sorted by name, and the first n = max_verifiers of the verifiers will be called, and the rest will be skipped.
• There is no guarantee for the order of execution of verifier binaries.
• Standard error output of verifier binaries is logged at debug level by containerd, subject to truncation.
• Standard output of verifier binaries (the "reason" for the judgement) is subject to truncation.
• System resources used by verifier binaries are currently accounted for in and constrained by containerd's own cgroup, but this is subject to change.