Generalize Fulcio OIDs, clarify guidance for providers about fulcio HOT 5 OPEN

cc @trevrosen @feelepxyz @laurentsimon who might also be interested

from fulcio.

@marshall007 thanks for writing this up!

Fulcio OIDs are loosely based on the assumption that providers can reliably produce immutable references to "job"-level configuration

This was not my intention when writing the initial proposal on these extensions and we should look to clarify this in the docs! I agree that we should primarily reference the "pipeline"/workflow-level/ invocations and their source config.

I'm keen to see if we can make this work with the current extensions and/or new ones without changing existing extensions to reducing any breaking changes and churn.

Checking your list:

• Run Invocation URI (required): uniquely identifies pipeline/workflow execution (typically a human-readable summary page)
  • ✅ The current GitLab and GitHub implementations seem correct to me
• Run Config URI/Digest (required): actual workflow/pipeline configuration ref
  • For GitHub we put this info in the Build Config URI/Digest, so this is a ref to the workflow config.
  • For GitLab Build Config URI is currently set to the job URI and Build Config Digest is unset. Could we change the Build Config URI be to something like https:/gitlab.com/user/project/.gitlab-ci.yml or similar ref to the config? If a config is used from the source repo, could the Build Config Digest be set to the same as Source Repository Digest?
• Run Trigger: workflow/pipeline trigger/dispatch event
  • Not sure it's wort changing the name here from the existing Build Trigger but maybe the split between run/build is a bit confusing and could be clarified
• Build Invocation URI: uniquely identifies job execution (typically a human-readable summary page)
  • For GitLab I imagine this would point to something like: https://gitlab.com/wlynch/npm-provenance-example/-/jobs/4276586778?
  • The GitHub equivalent is https://github.com/sigstore/sigstore-js/actions/runs/4992584824/jobs/8940485186 but we don't include this anywhere atm
  • I'd argue we don't really need this if we have the "pipeline"/workflow level summary that links to the job. Could we put this in the SLSA predicate as metadata instead?
• Build Config URI/Digest: actual build/job configuration ref
  • I'd argue we should not try and link to the job level config and keep them as is and point them to the pipeline/workflow config
• Build Signer URI/Digest
  • This should point to the resource that I need to trust in order to trust the integrity of the provenance and or build
  • In the default case, I think this should just be the same as Build Config URI/Digest but if the system provides a way to run a job in an isolated environment from the triggering pipeline/workflow it should point to that resource so I can write policies against it
  • For GitHub actions this points to the reusable workflow ref if the provenance was signed inside it, if not, it points to the workflow level config
  • I believe GCP has some similar capability and TektonCD also has some way of running things in isolated pipelines

from fulcio.

• For GitLab Build Config URI is currently set to the job URI and Build Config Digest is unset.

Ahh I see this was changed here for GitLab: https://github.com/sigstore/fulcio/pull/1183/files

It sounds like Build Config URI will be updated to pipeline_ref and Build Config Digest to pipeline_sha which sounds in line with the above assumptions.

from fulcio.

@marshall007 if using a external pipeline config in gitlab, e.g. http://example.com/generate/ci/config.yml - is this not the config that also contains the instructions to mint OIDC tokens and actually run the provenance generation as part of a step? Wondering if it would make sense to also update Build Signer URI/Digest to pipeline_ref/pipeline_sha to make it clear what config you would need to vet in order to trust what happened during the build/provenance generation?

from fulcio.

@feelepxyz I agree with your suggestions on the claims we (GitLab) should use to populate the OIDs. I think I am primarily hung up on the naming of things. For example, as I understand it, Run Invocation, Build Trigger, and Build Config URI/Digest should all be defined in terms of the top-level execution. I think this would be more clearly stated if they all used the same terminology (like "Run").

I found the Build Signer vs Build Config terminology a bit confusing as well. The descriptions clarify, but we were tempted to populate Build Signer URI with a URI ref that did not point to build config instructions, and just uniquely identified the job instead.

If all top-level execution is referred to as Run *, I was suggesting that Build Signer * could just be called Build * (and just for consistency, support all the same OIDs as Run *).

I don't have super strong opinions here, this is just my anecdotal feedback. I always have to go back and cross-reference with the OID mapping table to remember what the intent is/was. I felt like more descriptive/consistent naming might help with that.

from fulcio.