Feature: only accept reusable workflow pinned by version

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

However:

Pinned by hash makes it pretty hard to retrieve the branch during verification.
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.

@laurentsimon

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

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?

@laurentsimon

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

@asraa

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

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

+1, good summary.

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

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?

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?

Yeah, we should enable that so that it's not a risk for folks who are simply contributors. I just added a tag rule for all tags ("*").

I just integrated the generator into a project that is also using Renovate with the pinning rule enforced. Manual overwrite for slsa generator package would look like this:

  "packageRules": [
    {
      "matchManagers": ["github-actions"],
      "matchPackageNames": ["slsa-framework/slsa-github-generator"],
      "pinDigests": false
    }
  ]

Would it be helpful to document this somewhere for users of the generator? Any recommendations for a location? Seems a bit too much detail for the README.

@datosh

Great idea @datosh

How about linking to your renovatebot config in the generator repo in this section https://github.com/slsa-framework/slsa-github-generator#referencing-slsa-builders-and-generators?

We can create a RENOVATEBOT.md to link to in the same repo? Wdut?

@laurentsimon

Thanks for the quick response @laurentsimon. I put together a quick PR. What do you think?

How about linking to your renovatebot config in the generator repo

Do you mean linking to the repository where I actually use slsa generator to show a live working example? I can add the link, just wasn't sure if that's what you mean.

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

Pinning by hash does not appear to be functional, hence one can only depend on released tags. As mentioned before in this thread that doesn't seem ideal for defense in depth.

It's also an issue for bug fixes though! In our case provenance generation was blocked by a breaking bug (slsa-framework/slsa-github-generator#3571). The fix is merged, but we are unable to use them, since it's not yet included in a release tag.

Supporting pinning by hash would solve that problem (slsa-framework/slsa-github-generator#3573).

@ramonpetgrave64

@ramonpetgrave64 let's work on a relaese

Enforce unique subject names (#15)

chore: Do not pin slsa-github-generator

chore: Do not pin slsa-github-generator (#22)

fix: BCR workflows require semver tags

Without pinning by hash, OpenSSF Scorecard's Pinned-Dependency for GitHub actions will give warnings.

Is there a reason why the workflow can't check GitHub for a tag/release (maybe error of there are multiple) on the pinned hash and use that to retrieve the required artifacts? Or if the action was in a separate repo to the verifier this wouldn't even be an issue.

feat: support SHA hash pinning for trusted builder workflows

ci: pin GitHub Actions to SHAs and add Dependabot with auto-merge (#1193

fix(ci): the SLSA generator must be tag-referenced, not SHA-pinned (#354

Navigation Menu

Repository navigation

Feature: only accept reusable workflow pinned by version #12

2 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Feature: only accept reusable workflow pinned by version #12

Description

Activity

naveensrinivasan commented on Apr 9, 2022

laurentsimon commented on Apr 11, 2022

MarkLodato commented on Apr 11, 2022

laurentsimon commented on Apr 11, 2022

MarkLodato commented on Apr 14, 2022

laurentsimon commented on Apr 14, 2022

laurentsimon commented on May 26, 2022

joshuagl commented on Jul 5, 2022

ianlewis commented on Jul 5, 2022

datosh commented on Oct 17, 2022

laurentsimon commented on Oct 18, 2022

datosh commented on Oct 18, 2022

2 remaining items

jul-sh commented on Apr 17, 2024

laurentsimon commented on Apr 17, 2024

scottschreckengaust commented on Aug 5, 2025

stevehipwell commented on Aug 6, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions