Skip to content

docs: correct Docker image verification instructions for cosign 3 - #4555

Merged
stevenvegt merged 2 commits into
masterfrom
docs/cosign-v3-verification
Sep 17, 2026
Merged

stevenvegt merged 2 commits into
masterfrom
docs/cosign-v3-verification

Conversation

@stevenvegt

@stevenvegt stevenvegt commented Sep 17, 2026 •

Copy link
Copy Markdown
Member

Since #4451 images are signed by the CI pipeline, but the verification guide in docs/pages/deployment/docker.rst describes the cosign 2 world. The pipeline installs cosign-installer v4.1.2, which is cosign 3, and cosign 3 stores a signature as a Sigstore bundle attached through the OCI referrers API instead of the sha256-<digest>.sig tag. Following the docs as written does not get you a verified image.

What was wrong, and how it was checked

  • "Install cosign (version 2 or later)". The published nutsfoundation/nuts-node:master image has no .sig tag (registry returns 404) and one OCI referrer with artifactType: application/vnd.dev.sigstore.bundle.v0.3+json. cosign 2.6.1 with the documented flags fails with Error: no signatures found; cosign 3.1.3 verifies it. The docs now ask for cosign 3.0 or later and explain the format, since the same mismatch bites every other verifier.
  • The Kyverno policy could never have admitted a Nuts node image. Kyverno's verifyImages defaults to type: Cosign, which reads the .sig tag. Only type: SigstoreBundle takes the path that reads referrers and filters on the application/vnd.dev.sigstore.bundle artifact type prefix (pkg/image/verifiers/cpol/cosign/sigstore.go). That type exists since Kyverno 1.13. The example now sets it.
  • rekor.url in the example is ignored on that path: the trust root comes from Sigstore TUF, and transparency log verification is done from the bundle. Removed, and the extra egress the cluster needs (tuf-repo-cdn.sigstore.dev) is now mentioned.
  • spec.validationFailureAction is deprecated in favour of the per-rule failureAction, which the image verification rule has had since 1.13. Switched.
  • policy-controller needs signatureFormat: bundle on the authority (field present since 0.14), otherwise it hits the same problem. Mentioned.
  • AKS Image Integrity was left as an open question ("see their docs for the formats it supports"). Microsoft's page states Notation is the only supported verifier, Audit the only supported effect, and that the preview should not be used for production, so it cannot check a cosign signature at all. Said plainly now.
  • Azure DevOps snippet downloaded releases/latest. Pinned to a cosign 3 version instead.

Things that were already correct and are unchanged: the --certificate-identity-regexp / --certificate-oidc-issuer flags, the jq '.[0].critical.image."docker-manifest-digest"' extraction (cosign 3 still prints that payload shape, verified), and the docker buildx imagetools inspect provenance and SBOM commands (both run fine against the published image).

Limits of the verification

The cosign commands were run for real against the published image. The Kyverno, policy-controller and Azure DevOps parts were checked against those projects' source and documentation, not executed in a cluster or pipeline. The second commit says so in the docs as well, so readers treat the enforcement examples as a starting point rather than a guarantee.

Note for reviewers: signing lands in 6.2.12 and 5.4.39, which are not tagged yet, so no released image carries a signature today. The master tag does, and that is what the cosign runs above were done against. The dev image is built by a separate step whose digest never reaches the sign job, so it is not signed; happy to fix that separately if you want it signed too.

The signing job runs cosign 3, which stores a signature as a Sigstore
bundle attached through the OCI referrers API instead of the
sha256-<digest>.sig tag. The verification guide still described the
cosign 2 layout: it said cosign 2 was enough (it reports "no signatures
found"), and the Kyverno example used the default Cosign type, which
reads the tag and would reject every published image.

Also switch the Kyverno example to the per-rule failureAction, drop the
rekor URL the bundle path ignores, mention the Sigstore TUF egress the
cluster needs, pin cosign in the Azure DevOps example, and replace the
open question about AKS Image Integrity with what it actually supports:
Notation signatures, Audit only, preview.

Assisted-by: AI
The Kyverno, policy-controller and Azure DevOps snippets were checked
against the projects' source and docs, not run in a real cluster or
pipeline, so say so instead of presenting them as ready to deploy.

Also name the releases that introduced signing, 6.2.12 and 5.4.39, so
readers of an older version's documentation know where they stand.

Assisted-by: AI
@stevenvegt
stevenvegt force-pushed the docs/cosign-v3-verification branch from 08f4060 to 5324140 Compare September 17, 2026 08:38
@stevenvegt
stevenvegt merged commit c315ea6 into master Sep 17, 2026
13 checks passed
@stevenvegt
stevenvegt deleted the docs/cosign-v3-verification branch September 17, 2026 08:43
stevenvegt added a commit that referenced this pull request Sep 18, 2026
…ckport #4555 to V6.2) (#4556)

* docs(deployment): correct image verification for cosign 3

The signing job runs cosign 3, which stores a signature as a Sigstore
bundle attached through the OCI referrers API instead of the
sha256-<digest>.sig tag. The verification guide still described the
cosign 2 layout: it said cosign 2 was enough (it reports "no signatures
found"), and the Kyverno example used the default Cosign type, which
reads the tag and would reject every published image.

Also switch the Kyverno example to the per-rule failureAction, drop the
rekor URL the bundle path ignores, mention the Sigstore TUF egress the
cluster needs, pin cosign in the Azure DevOps example, and replace the
open question about AKS Image Integrity with what it actually supports:
Notation signatures, Audit only, preview.

Assisted-by: AI

* docs(deployment): say the enforcement examples are a starting point

The Kyverno, policy-controller and Azure DevOps snippets were checked
against the projects' source and docs, not run in a real cluster or
pipeline, so say so instead of presenting them as ready to deploy.

Also name the releases that introduced signing, 6.2.12 and 5.4.39, so
readers of an older version's documentation know where they stand.

Assisted-by: AI
stevenvegt added a commit that referenced this pull request Sep 18, 2026
…ckport #4555 to V5.4) (#4557)

* docs(deployment): correct image verification for cosign 3

The signing job runs cosign 3, which stores a signature as a Sigstore
bundle attached through the OCI referrers API instead of the
sha256-<digest>.sig tag. The verification guide still described the
cosign 2 layout: it said cosign 2 was enough (it reports "no signatures
found"), and the Kyverno example used the default Cosign type, which
reads the tag and would reject every published image.

Also switch the Kyverno example to the per-rule failureAction, drop the
rekor URL the bundle path ignores, mention the Sigstore TUF egress the
cluster needs, pin cosign in the Azure DevOps example, and replace the
open question about AKS Image Integrity with what it actually supports:
Notation signatures, Audit only, preview.

Backport of #4555.

Assisted-by: AI

* docs(deployment): say the enforcement examples are a starting point

The Kyverno, policy-controller and Azure DevOps snippets were checked
against the projects' source and docs, not run in a real cluster or
pipeline, so say so instead of presenting them as ready to deploy.

Also name the releases that introduced signing, 6.2.12 and 5.4.39, so
readers of an older version's documentation know where they stand.

Backport of #4555.

Assisted-by: AI
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants