Bundle inspection and generation utilities

haydentherapper commented 1 month ago

Description

Inspired by @codysoyland's https://github.com/codysoyland/sigstore-bundle-upgrade and building on the upcoming bundle support (https://github.com/sigstore/cosign/issues/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 commented 1 month ago

(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 commented 1 week ago

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 commented 1 week ago

LGTM! A few details:

--sct can be dropped, we are deprecating detached SCTs (https://github.com/sigstore/fulcio/issues/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.

sigstore / cosign

Bundle inspection and generation utilities #3794