Updating cosign signing docs by steiza · Pull Request #419 · sigstore/docs

steiza · 2026-03-06T19:32:50Z

Summary

Making progress on #418

Release Note

Updated cosign signing documentation to reflect Cosign v3 commands

Documentation

N/A

Signed-off-by: Zach Steindler <steiza@github.com>

netlify · 2026-03-06T19:32:57Z

✅ Deploy Preview for docssigstore ready!

Name	Link
🔨 Latest commit	`6194ae3`
🔍 Latest deploy log	https://app.netlify.com/projects/docssigstore/deploys/69b1612d54356a0008eb1fb4
😎 Deploy Preview	https://deploy-preview-419--docssigstore.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Signed-off-by: Zach Steindler <steiza@github.com>

Hayden-IO

This looks great, thank you for cleaning this up!

Any updates we need to make to https://github.com/sigstore/docs/blob/main/content/en/quickstart/quickstart-cosign.md? You made an update here to not use ttl.sh, should we make the same change in the quickstart guide?

content/en/cosign/signing/signing_with_containers.md

Signed-off-by: Zach Steindler <steiza@github.com>

cmurphy · 2026-03-09T20:03:31Z

content/en/cosign/signing/overview.md

+```shell
+$ cosign signing-config create \
+    --fulcio="url=https://fulcio.example.com,api-version=1,start-time=2024-01-01T00:00:00Z,operator=example.com" \
+    --rekor="url=https://rekor.example.com,api-version=2,start-time=2024-01-01T00:00:00Z,operator=example.com" \


Should also have a --tsa=... if the example is using Rekor v2.

cmurphy · 2026-03-09T20:23:59Z

content/en/cosign/signing/overview.md

+Then sign an image with your custom signing config:
+
+```shell
+$ cosign sign --signing-config custom.signingconfig.json \


Currently (this might change with one in-flight refactoring PR) I think this also needs --trusted-root if there is a CT log involved.

I ran this command as-is on main and it seemed to work for me.

cmurphy · 2026-03-09T20:39:03Z

content/en/cosign/signing/other_types.md

 ## SBOMs (Software Bill Of Materials)

-SBOMs can also be stored in an OCI registry, using this [specification](https://github.com/sigstore/cosign/blob/main/specs/SBOM_SPEC.md).
+There's a couple of different approaches SBOMs, depending on if you're working with container images or not.


Suggested change

There's a couple of different approaches SBOMs, depending on if you're working with container images or not.

SBOMs can be treated as either standalone OCI objects, or as container image attestations.

What I wanted to get across here (and maybe you can help me wordsmith) is that you can use SBOMs with Cosign both if you're working with container images (sign, attest), as well as if you're using files on disk (sign-blob, attest-blob).

Oh I got it, how about just that:

You can use SBOMs with Cosign both if you're working with container images (sign, attest), as well as if you're using files on disk (sign-blob, attest-blob).

cmurphy · 2026-03-09T20:39:43Z

content/en/cosign/signing/other_types.md

-SBOMs can also be stored in an OCI registry, using this [specification](https://github.com/sigstore/cosign/blob/main/specs/SBOM_SPEC.md).
+There's a couple of different approaches SBOMs, depending on if you're working with container images or not.

-Cosign can attach these using the `cosign attach sbom` command. In the following example, we'll be generating an SBOM for our sample container image by using the [syft](https://github.com/anchore/syft) tool created by Anchore community, then we'll be storing it in an OCI registry, once we store it, then we'll be signing the image tag that includes the SBOM itself, and verifying it.


I didn't know about syft, if it's still a useful tool then I think it would be nice to keep some reference to it.

I couldn't get syft to work to create an attested SBOM 😞 Their usage of Cosign is also quite out of date (v1.12.0).

cmurphy · 2026-03-09T20:40:26Z

content/en/cosign/signing/other_types.md

 ```

-Note that, attaching SBOMs this way does not sign them. If you want to sign the SBOM, you can use the following command:
+Another option is to use `cosign attest` when signing your container image to include information about the SBOM:


This is mostly what cosign is useful for, I think? Maybe move this option to the top?

Again, maybe you can help me wordsmith here. What I'm trying to get across is that if you're signing something, and are thinking "I'd like to add some metadata to this signature" you should really consider doing attest instead of sign.

I'm sort of torn on which approach is "better". I think for container images, you might be better off signing the SBOM separately, instead of including it as metadata in the container image signature. But that's not a strongly held belief, and this is certainly one of the issues folks are having with Cosign today - they are looking for more prescriptive guidance on how to use it with container images and SBOMs.

Hmm I don't think I have useful input here, I don't mind leaving it as-is

cmurphy · 2026-03-09T20:46:48Z

content/en/cosign/signing/other_types.md

 {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef"},"Type":"cosign container image signature"},"Optional":null}
 ```

-## Tag signing


Why did we want these sections removed?

For tag signing the use case doesn't make a lot of sense to me. I think today if you want the release name to digest mapping to have integrity you'd use something like https://github.com/in-toto/attestation/blob/main/spec/predicates/release.md, which leads to a second point that I think if you find yourself doing cosign sign -a what you really should be doing is cosign attest --predicate, especially since now a Cosign OCI signature is an attestation (with predicate type https://sigstore.dev/cosign/sign/v1).

For base image signing there's no reason you couldn't do that, but I don't think it needs special mention - you would sign the base image URI. You definitely would not sign each layer - how the heck would you verify that? This is sort of typical of early Cosign "sign everything now, figure out verification later" approach.

Countersigning I was more on the fence. There's no reason why you can't cosign sign targeting a protobuf bundle in the registry, but I don't think that's a use-case we necessarily want to encourage. If you want to do it, and you know what you're doing, go ahead, but I'm not sure it needs to be part of our documentation.

cmurphy · 2026-03-09T20:49:44Z

content/en/cosign/signing/signing_with_blobs.md

-
-```shell
-$ echo "my first artifact" > artifact
-$ cosign upload blob -f artifact gcr.io/user/demo/artifact


Is there an equivalent crane or oras command to help people with this use case?

Yeah, I sort of struggle with what's in scope for Cosign (or not), especially when it comes to OCI. I think if you want to upload blobs into a container registry, we can't stop you, but that's really between you and your container registry, not something Cosign needs to walk you through in its documentation. 🤷

cmurphy · 2026-03-09T20:51:40Z

content/en/cosign/signing/signing_with_containers.md

 $ cosign sign $IMAGE
 ```

-## Add annotations with a signature


It doesn't look like annotations are deprecated, why don't we want to include examples of it?

I mentioned this above, but I think it's difficult to answer "when should I use cosign sign -a vs when should I use cosign attest --predicate. I personally would strongly recommend people use cosign attest --predicate.

I might be wrong but I think one difference is people can verify that individual annotations are present, but for attestations you have to have more complex policy files to verify their contents. I lean slightly more on the side of keeping documentation and explaining the difference versus letting people discover it in the command line help and not have a good base for understanding it.

cmurphy · 2026-03-09T21:43:05Z

content/en/cosign/signing/other_types.md

-  }
-}
+$ echo '{"sbom_path": "example.com/...", "sbom_hash": "sha256:0a1b2c..."}' > sbom.predicate.json
+$ cosign attest --type custom --predicate sbom.predicate.json $IMAGE


I'm curious why use a custom type with an arbitrary predicate instead of keeping the SPDX example for SBOMs?

I really want folks to move away from things like https://github.com/in-toto/attestation/blob/main/spec/predicates/cyclonedx.md and https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx2.md.

SBOMs range from 1 - 100 MBs, and if you stuff the entire SBOM into the Sigstore protobuf bundle (using those predicates) then your Sigstore bundle can be 100 MBs. Not only does this cause problems with Rekor (mostly v1 I think), this also means that anytime you want to verify the container image signature you might have to download 100 MBs of data.

Instead, I think folks should use https://github.com/in-toto/attestation/blob/main/spec/predicates/reference.md, and indeed, this is what we at GitHub are moving things like https://github.com/actions/attest-sbom to. Unfortunately, cosign attest today doesn't let you reference arbitrary predicate types.

Oh, I got it, that makes a lot of sense and I wasn't aware we were trying to move people off of the individual predicate types.

Should we be more explicit about why we're recommending using the custom predicate type and a hash instead of the whole SBOM? Or is there a place we could talk about the advantages (searchability) and disadvantages (size) of using the more explicit predicates?

steiza

Lots of great questions! I added some opinionated answers on my current perspective.

steiza · 2026-03-10T20:23:31Z

content/en/cosign/signing/other_types.md

 ## SBOMs (Software Bill Of Materials)

-SBOMs can also be stored in an OCI registry, using this [specification](https://github.com/sigstore/cosign/blob/main/specs/SBOM_SPEC.md).
+There's a couple of different approaches SBOMs, depending on if you're working with container images or not.


What I wanted to get across here (and maybe you can help me wordsmith) is that you can use SBOMs with Cosign both if you're working with container images (sign, attest), as well as if you're using files on disk (sign-blob, attest-blob).

steiza · 2026-03-10T20:26:21Z

content/en/cosign/signing/other_types.md

 ```

-Note that, attaching SBOMs this way does not sign them. If you want to sign the SBOM, you can use the following command:
+Another option is to use `cosign attest` when signing your container image to include information about the SBOM:


Again, maybe you can help me wordsmith here. What I'm trying to get across is that if you're signing something, and are thinking "I'd like to add some metadata to this signature" you should really consider doing attest instead of sign.

I'm sort of torn on which approach is "better". I think for container images, you might be better off signing the SBOM separately, instead of including it as metadata in the container image signature. But that's not a strongly held belief, and this is certainly one of the issues folks are having with Cosign today - they are looking for more prescriptive guidance on how to use it with container images and SBOMs.

steiza · 2026-03-10T20:31:43Z

content/en/cosign/signing/other_types.md

-  }
-}
+$ echo '{"sbom_path": "example.com/...", "sbom_hash": "sha256:0a1b2c..."}' > sbom.predicate.json
+$ cosign attest --type custom --predicate sbom.predicate.json $IMAGE


I really want folks to move away from things like https://github.com/in-toto/attestation/blob/main/spec/predicates/cyclonedx.md and https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx2.md.

SBOMs range from 1 - 100 MBs, and if you stuff the entire SBOM into the Sigstore protobuf bundle (using those predicates) then your Sigstore bundle can be 100 MBs. Not only does this cause problems with Rekor (mostly v1 I think), this also means that anytime you want to verify the container image signature you might have to download 100 MBs of data.

Instead, I think folks should use https://github.com/in-toto/attestation/blob/main/spec/predicates/reference.md, and indeed, this is what we at GitHub are moving things like https://github.com/actions/attest-sbom to. Unfortunately, cosign attest today doesn't let you reference arbitrary predicate types.

steiza · 2026-03-10T20:43:01Z

content/en/cosign/signing/other_types.md

 {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef"},"Type":"cosign container image signature"},"Optional":null}
 ```

-## Tag signing


For tag signing the use case doesn't make a lot of sense to me. I think today if you want the release name to digest mapping to have integrity you'd use something like https://github.com/in-toto/attestation/blob/main/spec/predicates/release.md, which leads to a second point that I think if you find yourself doing cosign sign -a what you really should be doing is cosign attest --predicate, especially since now a Cosign OCI signature is an attestation (with predicate type https://sigstore.dev/cosign/sign/v1).

For base image signing there's no reason you couldn't do that, but I don't think it needs special mention - you would sign the base image URI. You definitely would not sign each layer - how the heck would you verify that? This is sort of typical of early Cosign "sign everything now, figure out verification later" approach.

Countersigning I was more on the fence. There's no reason why you can't cosign sign targeting a protobuf bundle in the registry, but I don't think that's a use-case we necessarily want to encourage. If you want to do it, and you know what you're doing, go ahead, but I'm not sure it needs to be part of our documentation.

steiza · 2026-03-10T20:44:43Z

content/en/cosign/signing/signing_with_blobs.md

-
-```shell
-$ echo "my first artifact" > artifact
-$ cosign upload blob -f artifact gcr.io/user/demo/artifact


Yeah, I sort of struggle with what's in scope for Cosign (or not), especially when it comes to OCI. I think if you want to upload blobs into a container registry, we can't stop you, but that's really between you and your container registry, not something Cosign needs to walk you through in its documentation. 🤷

steiza · 2026-03-10T20:46:41Z

content/en/cosign/signing/signing_with_containers.md

 $ cosign sign $IMAGE
 ```

-## Add annotations with a signature


I mentioned this above, but I think it's difficult to answer "when should I use cosign sign -a vs when should I use cosign attest --predicate. I personally would strongly recommend people use cosign attest --predicate.

Signed-off-by: Zach Steindler <steiza@github.com>

Updating cosign signing docs

af9961c

Signed-off-by: Zach Steindler <steiza@github.com>

Remove additional reference to gitsign

95c9755

Signed-off-by: Zach Steindler <steiza@github.com>

Hayden-IO reviewed Mar 9, 2026

View reviewed changes

content/en/cosign/signing/signing_with_containers.md Outdated Show resolved Hide resolved

Hayden-IO requested a review from cmurphy March 9, 2026 18:18

Add ko link; update Cosign quickstart to be consistent

7c4d7a9

Signed-off-by: Zach Steindler <steiza@github.com>

Hayden-IO previously approved these changes Mar 9, 2026

View reviewed changes

cmurphy reviewed Mar 9, 2026

View reviewed changes

steiza commented Mar 10, 2026

View reviewed changes

Add TSA to signing-config example

6194ae3

Signed-off-by: Zach Steindler <steiza@github.com>

steiza dismissed Hayden-IO’s stale review via 6194ae3 March 11, 2026 12:33

	There's a couple of different approaches SBOMs, depending on if you're working with container images or not.
	SBOMs can be treated as either standalone OCI objects, or as container image attestations.

Conversation

steiza commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Release Note

Documentation

Uh oh!

netlify bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docssigstore ready!

Uh oh!

Hayden-IO left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

steiza left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

steiza commented Mar 6, 2026 •

edited

Loading

netlify bot commented Mar 6, 2026 •

edited

Loading