Generalize Fulcio OIDs, clarify guidance for providers

[marshall007]

Description

All build systems have some concept of a "pipeline", which is typically composed of multiple "jobs". Some providers support reusable/identifiable "job" definitions or even composing reusable "steps" together to form "jobs", but this is a less common/consistent abstraction.

Most (probably all) build systems can easily generate URI references to "pipeline"-level invocations and their source config, but "job"-level metadata is highly dependent on how "pipeline" configuration is defined. This is challenging to do if pipeline configurations can be composed dynamically at runtime, for example.

Fulcio OIDs are loosely based on the assumption that providers can reliably produce immutable references to "job"-level configuration. When that is not possible, the guidance is not very clear. I think we should consider standardizing OIDs that map more cleanly to both "pipeline" and "job" abstractions to:

1. improve the consistency of how these claims are interpreted across providers
2. make incremental adoption easier for providers that cannot easily generate immutable "job"-level refs

I propose something along the lines of:

• Run Invocation URI (required): uniquely identifies pipeline/workflow execution (typically a human-readable summary page)
• Run Config URI/Digest (required): actual workflow/pipeline configuration ref
• Run Trigger: workflow/pipeline trigger/dispatch event
• Build Invocation URI: uniquely identifies job execution (typically a human-readable summary page)
• Build Config URI/Digest: actual build/job configuration ref
• Build Signer URI/Digest: no longer necessary. the same as Run/Build Config. Build is preferred, but Run is acceptable if that's all the provider can support

Note the current intent behind Run Invocation URI is to uniquely identify the run, in practice it is typically represented by a "summary page" for human users to view directly. I think we should embrace this Invocation URI terminology and definition as this ends up being quite useful for UI implementations (like "view build summary" links in the npm registry UI).

/cc @wlynch

[haydentherapper]

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

[feelepxyz]

@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

[feelepxyz]

• 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.

[feelepxyz]

@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?

[marshall007]

@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.