Container Image Digests, Signatures and Provenance: Keep the Verified Artifact Through Deployment
CONTAINER SECURITY
A digest keeps content identity stable. A signature and build provenance answer other questions. A release can pass one check and still fail the next.
By Hossam
KEY FINDINGS
- Keep the verified digest through deployment instead of resolving a movable tag again.
- An index digest identifies a multi-platform object. Record which platform manifest the assessment covers.
- A valid signature is not automatically from an accepted signer. Provenance must also match your expected source and build.
- The release-review example below is fictional. No registry, signing service or cluster was tested.
The same name can lead to a different image
A team reviews an image tagged release-7, approves it and deploys release-7 later. The names match. That does not necessarily mean the content matches: a tag can be moved to another image. If the review and deployment resolve the tag at different times, they can refer to different artifacts.
A digest addresses that identity problem. Docker and Kubernetes documentation distinguish movable tags from content-addressed digests. Pinning the intended digest helps keep the artifact you select stable. It does not, on its own, answer who produced it, whether the build followed your policy or whether the software contains vulnerabilities.
Those are separate questions. Treating one successful check as an answer to all of them creates false confidence.
Documentation: Image digests, Images.
Content identity is not producer identity
A digest identifies content through a cryptographic hash. In the container image structure, manifests reference configuration and layers through digests. A changed artifact has a different content identity. The digest is useful when promoting a reviewed artifact between environments or investigating which image a workload used.
But an attacker can publish harmful content with a perfectly valid digest. A hash does not label a producer as trustworthy. Your decision still needs an expected source and a policy for what is acceptable. Recording a digest after accepting an untrusted image only gives you a precise record of the untrusted artifact.
Keep availability separate as well. Pinning a digest does not promise that a registry will retain it forever or that credentials and network access will remain valid. Store deployment and recovery evidence according to your retention policy rather than assuming a content identifier is a backup.
Documentation: Image digests, Images.
Know whether you selected an index or a platform image
A multi-platform image can have an image index that points to platform-specific manifests. Docker's documentation distinguishes an index digest from the digest of an individual platform image. The distinction matters when interpreting evidence: two machines can select different platform artifacts from the same multi-platform index.
Record the platform alongside the artifact identity relevant to your review. If a vulnerability assessment describes one platform build, do not assume it automatically covers every other platform under the same published tag. The required scope depends on what was actually assessed.
This does not make a multi-platform index unreliable. It means that a precise identifier is only useful when you understand what it identifies.
Keep two identifiers when your review needs them: the index selected for distribution and the platform manifest actually assessed. An index signature can authenticate that index without turning an assessment of one child manifest into an assessment of every child. Which object a verification tool checks is an implementation question. Inspect its documented behavior instead of assuming every tool follows the same chain.
Documentation: Image digests, Prove where your container image came from.
A signature answers a different question
A signature binds a signed claim to a key or identity under a verification system. The important checks include which artifact digest the claim names and which signer your policy accepts. A valid signature from an unexpected signer is not approval from your intended producer.
Docker's signing guide recommends verifying by digest and deploying the digest that was verified. Otherwise, verifying a movable tag and later deploying that tag leaves a gap in which the reference can change. Keep the reviewed identity through the handoff instead of resolving the friendly name again.
Signature validity is not a vulnerability scan. A producer can correctly sign an artifact that contains a bug, an outdated dependency or unwanted behavior. Signing improves evidence about origin or approval under a defined trust model; it does not replace evaluation of the software.
The Docker signing guide is an interactive simulation, not a test performed for this article. Its key example also exposes a limit: if a signing key is stolen, an attacker can produce a signature that verifies against that key. Cryptographic validity and your decision to keep trusting a signer are separate. The accepted identity and key-management policy are part of the check, not an optional label added afterward.
Documentation: Prove where your container image came from, Build: Verifying artifacts, SLSA v1.2.
Provenance needs expectations, not merely existence
Build provenance adds claims about how an artifact was produced. SLSA's verification guidance separates checking the provenance's authenticity from checking whether it meets the consumer's expectations. Relevant checks include the statement's subject digest, builder identity, source repository, build type and external parameters.
The practical question is not simply whether an attestation exists. It is whether an authenticated statement refers to this artifact and describes a build your policy permits. An authentic record of an unexpected source repository should not pass merely because it is well formed.
Trust also has limits. SLSA explicitly notes that trust in the build platform matters and that its build assurances do not cover every possible compromise. Provenance, signatures, component inventories and vulnerability assessments contribute different evidence. None should be described as a universal safety certificate.
Metadata existence is not authenticated provenance
Docker documents BuildKit provenance as build metadata attached to an image index, with individual attestation manifests referring to a platform image. Finding that metadata is a useful starting point. It is not, by itself, evidence that you verified a trusted signer or met a particular SLSA Build level.
There is a version boundary too. Docker currently documents provenance schema v0.2 as its default, with v1 available as an option. SLSA v1.2 verification guidance describes checks against the v1 provenance format, or equivalent checks for another format. Do not paste one format's field names into a different format and call the result verified. Likewise, Docker's min and max modes describe the detail recorded in provenance, not SLSA assurance levels.
More metadata can also disclose more. Docker warns that max mode exposes build-argument values. Treat provenance distribution as a data-handling decision; do not assume that every build record is suitable for unrestricted sharing. This article does not recommend a build command or a blanket mode setting.
Documentation: Build: Verifying artifacts, SLSA v1.2.
A release-review checklist
Before promoting an image, record the intended repository, tag used for discovery, selected digest and platform scope. Check the relevant signature or provenance against the identities and build expectations your organization actually trusts. Then associate vulnerability and policy assessments with that same artifact. This is an editorial checklist, not a complete security standard.
If an identity or provenance check fails, stop promotion and investigate. Do not disable the check just to make the release pass. If the artifact passes origin checks but contains an unresolved vulnerability, route that to the appropriate risk decision rather than calling the signature a fix.
For Kubernetes, do not confuse image selection with pull behavior. Its image pull policy controls when the runtime attempts a pull; cached layers can still be reused. Setting Always is not the same thing as choosing an immutable artifact, and it does not certify a publisher. The current Kubernetes documentation explains these behaviors separately.
A fictional promotion review
Imagine a team reviewing a service called Cedar. The tag release-7 initially resolves to index A, which contains an amd64 manifest B and an arm64 manifest C. These letters are symbolic identifiers, not valid digest strings or output from a real registry. The team checks B, but production includes both amd64 and arm64 nodes.
- Tag drift: release-7 later resolves to index D. Approval of A does not approve D. Preserve the reviewed reference instead of relying on the unchanged tag text.
- Platform gap: the deployed index is still A, but the vulnerability review covers only B. The identity check can pass while coverage for C remains unresolved.
- Signer gap: a signature on A verifies, but the signer is a developer key rather than the release identity required by policy. Do not silently widen the accepted-signer list.
- Source gap: authentic provenance names an unexpected source repository. The record can be genuine and still fail the release expectations.
- Operational gap: A is approved, but the workload configuration still names D. Evidence about A does not demonstrate what the deployment is using.
These are separate review outcomes. One green result should not overwrite a red or unresolved result elsewhere. The example is a reasoning aid, not evidence that a particular admission controller implements these checks.
Documentation: Images, Build: Verifying artifacts, SLSA v1.2.
The boundary to preserve
Use a digest to keep the selected artifact's identity stable. Use signatures and provenance to assess claims about its origin and build against a trust policy. Use component and vulnerability evidence to evaluate other risks. Finally, confirm that the deployed workload actually uses the intended artifact and configuration.
A precise digest is valuable because it narrows the question. It should not be stretched into an answer about authorship, security, runtime behavior or recovery that it was never designed to provide.
Documentation: Image digests, Images, Build: Verifying artifacts, SLSA v1.2.
Connect identity to vulnerability assessment
Once the artifact is identified, you still need to decide what its components and vulnerabilities mean. Our SBOM versus VEX release-review guide separates inventory matches from scoped vulnerability assessments. Use that distinction after matching the relevant artifact and platform. A digest cannot supply a missing inventory; a signature cannot turn an unresolved assessment into a not-affected verdict.
Sources & Provenance
- Image digests, Docker
- Prove where your container image came from, Docker Learn
- Images, Kubernetes project
- Build: Verifying artifacts, SLSA v1.2, SLSA
- Build attestations, Docker
- Provenance attestations, Docker
Documentation-based explanation, checked 20 November 2026. No registry, signing service or Kubernetes deployment was tested. This is a decision guide, not a copy-and-run deployment tutorial. The Cedar example and review outcomes are fictional editorial guidance. No copied command sequence, vendor screenshot, benchmark, image or test output is included.
Comments
Post a Comment