Bundle inspection and generation utilities

[haydentherapper]

Description

Inspired by @codysoyland's https://github.com/codysoyland/sigstore-bundle-upgrade and building on the upcoming bundle support (#3139), it would be great to have utilities to work with or create bundles outside of signing and verification workflows. This could include:

cosign bundle upgrade --version 0.3 --in-place foo.sigstore.json
cosign bundle synthesize --certificate foo.crt --signature foo.sig --attestation foo.json --out foo.sigstore.json
~~cosign bundle verify --identity foo foo.sigstore.json~~
cosign bundle inspect foo.sigstore.json
cosign bundle export --format protobuf --output foo.sigstore.pb foo.sigstore.json
cosign bundle export-certificate --output foo.crt foo.sigstore.json

In order:

• Upgrading a bundle version, resolving new requirements
• Merging detached verification material into a bundle
• Verifying that a bundle contains a specified identity (@codysoyland, did you have something else in mind for this? If this is effectively verify-blob without artifact verification, I'd skip this one, or at least rename)
• Provide user-readable bundle output (machine readable should just do cat foo.sigstore.json | jq)
• Export json bundle as protobuf (and should support proto -> json as well)
• Decompose bundle into detached verification material

Discussion: https://sigstore.slack.com/archives/C0440BFT43H/p1721088432507969

[codysoyland]

(re: cosign bundle verify)

@codysoyland, did you have something else in mind for this? If this is effectively verify-blob without artifact verification, I'd skip this one, or at least rename

Yeah, this one is probably redundant with existing verify commands, so it can be omitted.

[steiza]

Okay, so merging in the content from #3855, what about if we start with:

cosign bundle create

Assembles a protobuf ("new") bundle. Has flags similar to `verify-blob` and
`verify-blob-attestation`. Includes whatever information is not empty
strings.

    --attestations='':
        path to attestation FILE. Conflicts with --signature.

    --bundle='':
	path to old bundle FILE to convert to new bundle

    --certificate='':
	path to the public certificate. The certificate will be verified
	against the Fulcio roots.

    --out='':
	path to bundle FILE to output

    --rfc3161-timestamp='':
	path to RFC3161 timestamp FILE

    --sct='':
	path to a detached Signed Certificate Timestamp, formatted as a
	RFC6962 AddChainResponse struct. If a certificate contains an SCT,
	verification will check both the detached and embedded SCTs.

    --signature='':
	signature content or path or remote URL. Conflicts with
        --attestation.

Can we just assume this will only output new protobuf bundles? I think that's okay - I'm not sure why someone would be looking to take detached materials and create an old bundle. Or do we need a --new-bundle-format flag?

Then for trusted roots we can do something like:

cosign trusted-root create

Defaults to output PGI trusted root, obtained via TUF. Has flags similar to
`verify-blob` and `verify-blob-attestation`. Includes whatever information
is not empty strings (e.g. if you don't want a timestamp authority in your
trusted root, leave off `--timestamp-certificate-chain`). 

    --ca-intermediates='':
	path to a file of intermediate CA certificates in PEM format which
	will be needed when building the certificate chains for the signing
	certificate. The flag is optional and must be used together with
	--ca-roots, conflicts with --certificate-chain.

    --ca-roots='':
	path to a bundle file of CA certificates in PEM format which will be
	needed when building the certificate chains for the signing
	certificate. Conflicts with --certificate-chain.

    --certificate-chain='':
	path to a list of CA certificates in PEM format which will be needed
	when building the certificate chain for the signing certificate. Must
	start with the parent intermediate CA certificate of the signing
	certificate and end with the root certificate. Conflicts with
	--ca-roots and --ca-intermediates.

    --key='':
	path to the public key file, KMS URI or Kubernetes Secret

    --out='':
	path to trusted root FILE to output

    --rekor-url='https://rekor.sigstore.dev':
	address of rekor STL server

    --timestamp-certificate-chain='':
	path to PEM-encoded certificate chain file for the RFC3161 timestamp
	authority. Must contain the root CA certificate. Optionally may
	contain intermediate CA certificates, and may contain the leaf TSA
	certificate if not present in the timestamp

If this interface looks reasonable, I can start implementing!

[haydentherapper]

LGTM! A few details:

--sct can be dropped, we are deprecating detached SCTs (sigstore/fulcio#1499). For --bundle, we should note this is how an inclusion proof/SET is provided. One open question is do we want to fetch an inclusion proof is one is not present, for this and/or the cosign bundle upgrade case? If we're removing get-proof-by-hash, then I'd lean towards no.

Can we just assume this will only output new protobuf bundles?

Yes!

For cosign trusted-root create, we need to take in the Rekor public key too. I wouldn't rely on rekor-url providing you the public key (we should remove that functionality from the log). You also might need a few more details like signature algorithm and URLs for the CA and timestamp authority.

[woodruffw]

To tack on: another useful set of subcommand(s) here would be for interacting with PEP 740 attestation and provenance objects, which are semantically compatible with Sigstore bundles but have their own structure (to make them mesh with Python packaging land).

As a rough sketch, some things that would be useful:

# maybe this could be another `bundle synthesize` variant?
# convert an entire provenance object into >=1 sigstore bundles
cosign bundle convert-pep740 --provenance foo-1.2.3.tar.gz.provenance

# convert a single attestation object into its corresponding bundle
cosign bundle convert-pep740 --attestation foo-1.2.3.tar.gz.publish.attestation

The inverse (bundle to PEP 740) might also be useful, although this is already covered within standard uploading/signing flows.