Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generalize Fulcio OIDs, clarify guidance for providers #1182

Open
marshall007 opened this issue May 24, 2023 · 5 comments
Open

Generalize Fulcio OIDs, clarify guidance for providers #1182

marshall007 opened this issue May 24, 2023 · 5 comments
Labels
enhancement New feature or request

Comments

@marshall007
Copy link
Contributor

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

@marshall007 marshall007 added the enhancement New feature or request label May 24, 2023
@haydentherapper
Copy link
Contributor

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

@feelepxyz
Copy link
Member

@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)
  • 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
Copy link
Member

feelepxyz commented May 25, 2023

  • 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
Copy link
Member

@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
Copy link
Contributor Author

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

marshall007 added a commit to marshall007/fulcio that referenced this issue Jun 2, 2023
Assigns new `pipeline_ref/sha` claims to `Build Config` and
`Build Signer` related OIDs.

Depends on https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121597

Related to sigstore#1182
marshall007 added a commit to marshall007/fulcio that referenced this issue Jun 2, 2023
Assigns new `pipeline_ref/sha` claims to `Build Config` and
`Build Signer` related OIDs.

Depends on https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121597

Related to sigstore#1182

Signed-off-by: marshall007 <[email protected]>
haydentherapper pushed a commit that referenced this issue Jul 10, 2023
* Update GitLab claim mappings for build configs

Assigns new `pipeline_ref/sha` claims to `Build Config` and
`Build Signer` related OIDs.

Depends on https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121597

Related to #1182

Signed-off-by: marshall007 <[email protected]>

* update docs to reflect GitLab claim mappings

Signed-off-by: marshall007 <[email protected]>

* updates to match new claim names

Signed-off-by: marshall007 <[email protected]>

* fix issuer test

Signed-off-by: marshall007 <[email protected]>

* address PR feedback

Signed-off-by: marshall007 <[email protected]>

* fix failing grpc server tests

Signed-off-by: marshall007 <[email protected]>

* fix lint error

Signed-off-by: marshall007 <[email protected]>

---------

Signed-off-by: marshall007 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants