Container Image Verification: Digests, Signatures, and Provenance

Container image signature verification should support a specific release decision: these are the intended image bytes, the signer is authorized, and the build evidence meets the deployment policy. A digest identifies content. A signature connects signed content to an identity under a trust model. Provenance supplies statements about the build. Each answers a different question; none should silently stand in for the others.

Start with one application, one proposed release and one deployment destination. Write down what you expect before reading the image’s attached evidence. Then compare the observed artifact, identity and provenance against those expectations, and verify that the intended deployment boundary applies the policy.

This guide proposes a review worksheet and an authorized verification plan. It does not report tests against a registry or cluster. Documentation was reviewed on October 30, 2026; check syntax, supported formats and admission behavior against your installed versions. Qualified technical review remains pending.

Set release expectations before inspecting the artifact

Ask the application owner and platform owner to identify the release they intend to admit. Record the registry and repository, release identifier, expected digest, deployment environment and supported architecture. Establish who may authorize the signing identity, trusted builder and policy changes.

Keep those expectations in a controlled release record. Copying the signer identity or builder value from an unfamiliar attestation into an allowlist makes the submitted evidence define its own acceptance criteria. Sigstore’s verification guidance calls for prior knowledge of the expected signer, published somewhere trusted people control.

For an initial review, agree on five decisions:

• Which exact artifact and architecture scope are being approved?
• Which trust configuration and signer identity may establish authenticity?
• Which builder, source and build inputs are acceptable for this application?
• Where must the deployment policy apply, and what evidence demonstrates that scope?
• Who owns a failed or inconclusive check, and who can approve an exception?

Supplier procurement remains a separate job. Use the software supply chain security and SBOM buyer guide for supplier evidence and purchasing questions. An SBOM request does not replace the release-specific trust decision described here.

Fix the image reference and digest scope

A familiar tag can point somewhere new. Kubernetes documents image digests as immutable content identifiers, while tags can move. Record a digest-qualified reference and ensure the proposed deployment refers to the artifact you evaluated. Verifying a tag today and deploying that tag later leaves an unresolved identity question if it changes.

Also identify what the digest names. A multi-architecture image index references platform-specific manifests. An index digest and a selected platform manifest digest describe different objects. Their values need not be identical.

Add two worksheet fields: verified object type and target platform. If your release approves an index, record the relationship to the manifest selected for the deployment platform. If it approves a platform manifest directly, identify that scope explicitly. Confirm that the signature and provenance checks cover the intended object; do not treat any different digest as an automatic attack or an automatic equivalent.

Retain the original tag as a human-readable release label, alongside the resolved reference and resolution time. When comparing evidence, use the recorded digest and object scope rather than the label alone. If the registry view, release record and deployment specification disagree, pause the decision and reconcile them before proceeding.

Verify the approved signer and issuer

For identity-based verification, the Cosign verification reference documents --certificate-identity and --certificate-oidc-issuer. For Cosign container signature payloads, the image digest binding is checked by default. Preserve that check; the presence of a signature file is insufficient evidence.

The following PowerShell example illustrates the documented command shape. It has not been executed. Replace every placeholder using an independently approved release record, and confirm compatibility with your installed Cosign version and trust configuration.

$image = 'registry.example.org/team/app@sha256:REPLACE_WITH_FULL_DIGEST'
$identity = 'REPLACE_WITH_APPROVED_SIGNER_IDENTITY'
$issuer = 'REPLACE_WITH_APPROVED_OIDC_ISSUER'
cosign verify $image --certificate-identity $identity --certificate-oidc-issuer $issuer

Record the actual verifier version, trust-root configuration, command, time, exit status and relevant verification diagnostics when an authorized operator performs the check. Protect registry credentials and unrelated private data when retaining evidence. A successful command is an observation about that invocation, not permission to deploy.

Be precise about GitHub context. The generic verification reference lists the human GitHub OAuth issuer https://github.com/login/oauth. The Sigstore CI quickstart uses https://token.actions.githubusercontent.com for GitHub Actions workload signing, together with a workflow-specific identity. These values are not interchangeable defaults. Approve the pair for the actual signing workflow.

For the related cloud-credential problem, see the GitHub Actions OIDC migration guide. Cloud-role trust and artifact signing authorization require their own decisions.

Check provenance against trusted build expectations

An image signature check and a provenance policy check are distinct operations. Do not infer that a successful cosign verify evaluated every build field. Verify the provenance envelope and its relationship to the artifact before using its contents in the decision.

The SLSA v1.2 verification guidance covers envelope authenticity, the subject digest, the expected predicate type, trusted builder identity and expected build values. The verifier needs trusted expectations; a builder’s self-description does not establish the level of trust your organization assigns it.

For the SLSA provenance v1 format, distinguish the outer statement from its predicate:

• subject binds the statement to the artifact digest.
• predicateType identifies the provenance format, including https://slsa.dev/provenance/v1.
• predicate.runDetails.builder.id identifies the asserted build platform.
• predicate.buildDefinition.buildType explains how to interpret the build definition.
• predicate.buildDefinition.externalParameters contains externally controlled build inputs to compare with approved expectations.

Source and workflow details must be interpreted according to that build type’s documented schema. Avoid a universal JSON path for every builder’s source repository. Similarly, a policy written for SLSA v0.2 fields needs review before use with a v1 predicate.

List the expected repository, permitted build configuration and relevant parameters in the release policy. Route unknown fields or unexpected values for review instead of dropping them to obtain a pass.

Combine the checks in a verification decision record

Use one record to connect evidence to the deployment decision. The following is a proposed operational worksheet, not a Sigstore or SLSA mandated form. Link to retained evidence rather than copying large logs into every field.

Keep expected and observed values in separate columns or fields. A release record filled entirely with expected values can look complete while containing no verification evidence. Mark unavailable observations as pending or inconclusive, with an owner and next action.

Use a shared artifact reference across the command evidence, provenance evaluation and policy decision. This makes a later review easier: the reviewer should not have to guess whether three screenshots concern the same image.

Walk through a fictional release decision

Consider a fictional payments application with an approved release digest and a policy requiring its designated release workflow and trusted builder. The example contains no real artifact, command output or observed deployment result.

Suppose an authorized reviewer obtains a valid signature for the recorded digest, but the verified identity names an experimental workflow. The digest comparison and cryptographic verification can succeed while the signer-authorization requirement fails. The proposed disposition is hold, with the release owner asked to reconcile the unexpected workflow. Editing the allowlist to mirror the unfamiliar identity would change the policy rather than explain the discrepancy.

Now suppose the signer matches but required provenance cannot be retrieved. Record the signature result and missing provenance separately. The missing evidence is unresolved; it is not evidence of an acceptable build. Assign investigation to the evidence owner, preserving the exact artifact reference and diagnostic context.

If the owner later supplies corrected evidence, evaluate it against the same approved expectations. If the build or image changes, start a new artifact decision rather than attaching a new result to the old digest. If expectations legitimately change, retain the policy change’s authorization and version so another reviewer can explain why the disposition changed.

Verify the actual deployment boundary

A local check does not demonstrate that a deployment will be blocked when evidence fails. Review the destination’s admission configuration separately. The Sigstore policy-controller overview describes enforcement using verifiable supply-chain metadata, with configured namespace and policy scope. It also explains that warning mode permits a noncompliant admission while issuing a warning.

Ask the platform owner to identify included namespaces, matched images and resource types, behavior for unmatched images, effective enforcement mode and relevant webhook configuration. Compare those answers with the intended release destination. An installed controller or an old policy screenshot does not establish current coverage.

Keep this review specific to the deployed controller version. The upstream overview is under active development and includes examples with different API versions. Use its concepts to identify questions; have the platform owner validate the actual configuration and supported schema before proposing changes.

Record any difference between the intended policy and its current scope. Track configuration drift through the security misconfiguration checklist. The artifact decision should state that an enforcement gap remains open rather than presenting a local verification success as closure.

Plan positive and negative verification cases

Before an authorized test, write the expected result for an approved release and for selected failures. Keep local verification and admission observations distinct. The diagram above is a planning aid; every observed result remains pending until a reviewer collects it.

Choose cases that answer real policy questions:

• An approved artifact with all required evidence should satisfy the intended policy.
• An unauthorized signer or issuer should fail its identity requirement.
• Provenance referring to a different subject digest should fail artifact binding.
• An unapproved builder, source or external parameter should fail the relevant expectation.
• Missing required evidence should follow the documented failure disposition.
• A deployment in each intended scope should receive the configured admission decision.

Arrange these checks with platform and application owners in an authorized environment. Agree on recovery criteria before changing production enforcement. Record the input, policy version, expected outcome, actual outcome, time and evidence location. If an unexpected case is admitted, investigate the matching and enforcement path before marking the control effective.

Successful admission also leaves other security work open. Vulnerability assessment, application behavior and runtime permissions require separate evidence. The Kubernetes service-account RBAC review addresses workload permissions after the artifact trust question.

Handle failures and exceptions without erasing uncertainty

Separate a policy mismatch from an unavailable verification dependency. Both may prevent a normal approval, but their investigation owners and evidence differ. Preserve the actual diagnostic rather than summarizing every failure as “bad signature.”

For a mismatch, compare the expected and verified values, then ask the appropriate release or platform owner to explain the difference. For unavailable evidence, record what could not be retrieved or evaluated and what remains unknown. Avoid weakening identity or digest checks to turn either condition into a success.

If the organization permits exceptions, use its existing approval process. Record the exact artifact digest, environment and deployment scope; reason; approving owner; compensating measures actually authorized; expiry; and recheck trigger. An exception accepts a documented limitation. It does not transform missing evidence into verified evidence.

Assign follow-up before closing the record. Builder migrations, signing-workflow changes, trust-root changes and policy revisions should trigger a fresh comparison with approved expectations. Keep earlier decisions available so the next reviewer can distinguish a deliberate change from unexplained drift.

Make a decision another reviewer can explain

Choose one release and complete its decision record before broadening the rollout. A useful result identifies the artifact, explains which identity and build evidence were accepted, names the applicable policy and shows what was actually observed.

The Sigstore security model describes identity, trust roots and compromise limitations. Treat the absence of a code-safety guarantee as a limit of this evidence: a signature or provenance statement alone cannot establish that an application contains no malicious behavior or vulnerabilities.

Allow the release only through the organization’s authorized decision process. Otherwise, record a hold or a separately approved exception with an owner and next check. The practical goal is a defensible artifact trust decision with visible limits and a clear path for resolving what remains unknown.