Feature: only accept reusable workflow pinned by version

[laurentsimon]

The reusable workflow can be pinned by hash, version or tag in general.

However:

1. Pinned by hash makes it pretty hard to retrieve the branch during verification.
2. Pinned by branch (like main) should be discouraged.

The OIDC token (which we use to retrieve the workflow identity/pin) currently does not report the version/branch used. So for now we will only accept version/tag pinning during verification. Once GitHub adds support, we can accept hash pins.

[naveensrinivasan]

Pinned by hash makes it pretty hard to retrieve the branch during verification.

@laurentsimon Can you please explain why so? A specific example would be helpful to understand. Thanks

[laurentsimon]

Well, sort of what I described. The OIDC currently does not contain all the information we'd like and only contains trusted-workflow.yml@XXX where XXX is how the user pinned the trusted builder.
If users use a hash, the verifier would need to use GitHub API to match it to a branch and verify it's the main branch.
If they use a branch... well.. they should not use the main branch directly because we may be breaking things at head.
So the only viable solution today is to ask users to pin by version: we, the maintainers, should be only releasing branches from the main branch, so if they trust us this works.

Later when GitHub adds support in the OIDC token to indicate the branch and hash of the trusted builder, we'll be able to let users pin by hash and we'll be able to verify the hash corresponds to the main branch via the information in the certificate (see https://github.com/slsa-framework/slsa-github-generator-go/blob/main/images/cert.svg) which is a mere copy of the information in the OIDC token.

Does this help?

[MarkLodato]

@laurentsimon The verifier could have a list of acceptable hashes, either hard-coded or via some signed mechanism (TUF? attestation?) This avoids the need for us to trust the protection of tags on our repo.

[laurentsimon]

You're right, we could do that. There are going to be quite a few generators though, and we'll have to be sure to add new hashes after each release. This is do-able, just a little more error prone for us. Some builders may be "out of our control", for example pipy seem interested in owning their builder.

It may become useful to have a builder's version, since new versions may have new features or breaking changes. (We can map each tag to a version, though).

Using version/tag pinning seems simpler to start with (due to the OIDC token limitation). We could later introduce support for hashes. If we introduce hashes right now, it may be harder to take it way from users if it becomes untenable to maintain.

I'm not against doing it, mostly trying to weigh the pros and cons.

Wdut?

/cc @asraa

[MarkLodato]

I think we have the following considerations:

• Ease of implementation on our side:
  • Branch: easy, just check for main
  • Tag: easy, just check for some pattern, e.g. v*
  • Hash: hard, need to maintain a hardcoded allowlist OR have some infrastructure to keep the list of "trusted" hashes up-to-date (signing, TUF, etc.)
• Ease of use on caller's side:
  • Branch: easy, stays updated
  • Tag: medium-to-easy, dependabot keeps it up-to-date
  • Hash: medium, dependabot keeps it up-to-date, but it's less readable
• Stability for the caller:
  • Branch: poor, API can change underneath the user, breaking a build
  • Tag: medium-to-good (tags are mutable, but we shouldn't modify them)
  • Hash: good (immutable)
• Insider risk of someone with slsa-framework write access pushing a bad release:
  • branch: medium, branch protection w/ two party review mostly covers this, but still a risk of two people pushing a bad commit that gets auto-accepted everywhere
  • tag: poor, anyone with correct permissions can push arbitrary things to the tag and mutate/delete tags, with no logs
  • hash: good, immutable - this is what GitHub recommends for security reasons

[laurentsimon]

+1, good summary.

[laurentsimon]

Enforcing pinning by version is done in #63
Keeping this issue open for now.

[joshuagl]

I just discovered that GitHub now supports tag protection rules:

Only users with admin or maintain permissions in the repository will be able to create protected tags, and only users with admin permissions in the repository will be able to delete protected tags.

It's not clear from the docs what permissions are required to mutate/overwrite a tag, but this may mitigate some of the insider risk of tags?