content: draft: define how downstream users can verify the SLSA source track level of revisions #1094

TomHennen · 2024-07-10T14:29:43Z

This PR modifies draft content of the SLSA spec.

Context

Google document requires [email protected] membership.

VSA for source

Define how downstream users can verify the SLSA source track level of revisions by using a VSAs produced by the Source Control Platform (SCP).

To use these VSAs users do not need to know the specifics of how any given SCP or Version Control System (VCS) meets the SLSA source requirements (which may vary greatly from implementation to implementation). Instead it is left to the SCP or another trusted 'authority' to make that determination for downstream users.

The question of how the authority ensures those claims to be true is left undefined in this change.

Future updates can include guidance for how to verify source level when combined with build provenance.

Example scenario

A user wants to verify 9a04d1e is SLSA source level 3.
The user 'trusts' GitHub as the authority for source revisions managed by GitHub.
The user requests a VSA for 9a04d1e from a TBD API
The user verifies the VSA following the standard instructions or using standard tooling and looking for SLSA_SOURCE_LEVEL_2 in the verifiedLevels field.

Just focusing on how to communicate levels to downstream users. Future updates can include guidance for how to verify. Open question: should this live here or someplace else? refs slsa-framework#1071 Signed-off-by: Tom Hennen <[email protected]>

netlify · 2024-07-10T14:30:00Z

✅ Deploy Preview for slsa ready!

Name	Link
🔨 Latest commit	`b197be7`
🔍 Latest deploy log	https://app.netlify.com/sites/slsa/deploys/66f1805b6eb953000805e881
😎 Deploy Preview	https://deploy-preview-1094--slsa.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

docs/spec/draft/source-requirements.md

Signed-off-by: Tom Hennen <[email protected]>

docs/spec/draft/source-requirements.md

Signed-off-by: Tom Hennen <[email protected]>

docs/spec/draft/source-requirements.md

zachariahcox · 2024-07-17T13:33:35Z

docs/spec/draft/source-requirements.md

+1.  `subject.uri` SHOULD be set to a human readable URI of the revision.
+2.  `subject.digest` MUST include the revision identifier (e.g. `gitCommit`) and MAY include other digests over the contents of the revision (e.g. `gitTree`, `dirHash`, etc...).
+SCPs that do not use cryptographic digests MUST define a canonical type that is used to identify immutable revisions (e.g. `svn_revision_id`)[^1].
+3.  `subject.annotations.source_branches` SHOULD be set to a list of branches that pointed to this revision at any point in their history.


at any point in their history

I think this is supposed to help consumers who only want releases/* refs?

They would be able to see if this revision was reachable from any release ref when this attestation was minted.

For a single revision / subject, a normal git late branching flow would keep reminting these things when important branches point to it.
I'd be nice not to have to do that.

I think this is supposed to help consumers who only want releases/* refs?

Something like that yes.

For a single revision / subject, a normal git late branching flow would keep reminting these things when important branches point to it.
I'd be nice not to have to do that.

Could they be minted on-demand?

If not, do you have any other thoughts about how to capture this information (or perhaps we should see if we can make it inconsequential?)

Could they be minted on-demand?

that sounds tricky! like, do you include forks? user branches? etc. Probably we need to avoid needing it.

I think the intent is to say: I can deploy this revision because X, where X is the set of rules required to land in the /refs/heads/release/ refspec on this date.

Ideally, you'd be able to reverify the qualifications for X and not need to use the refname as a place holder.
If you do need the refname, I think we'd pretty much always need to explain why so we can know if any mapping is required when the ref rules change over time.

Oh so we typically use the branch name to convey semantic between the folks managing the code and the folks writing the individual policies.

The automated rules that get applied to a 'experimental' and 'release' branch might very well be the same, but the code you put in them would be different. Being able to convey downstream if something was good enough for the 'release' branch is very helpful! These names will likely differ from team to team as they set up their branches and development flows differently.

So I suppose I view the refname(?) as orthogonal to the actual rules the SCP is enforcing at any point in time.

Does that explanation help explain why we'd want such a thing? (Even if we do decide it's too hard to actually implement)

In our last discussion I think we agreed that having some way to reference the branch names is useful, so I think this can be resolved?

we can definitely reference the branch names in the revision-creation claims -- it's not likely to be feasible to mint attestations on demand or on every ref update, but potentially on every closed pull request?
@TomHennen maybe we can focus the discussion just on that part going forward?

Sure, let me make a proposal on how this happens. Might be worth merging with other language that @zachariahcox added (?) about which branches on 'consumable'. I'll have to go look for the specifics. (suggestion per @adityasaky ).

Another suggestion: don't define how it's done here but instead leave it up to the implementing systems to define when they set these things. However I think it's probably helpful to have some minimum path that a system like GitHub could use (as a sort of 'existence proof').

WDYT @zachariahcox ?

Ok, I've made a concrete proposal. PTAL?

Signed-off-by: Tom Hennen <[email protected]>

TomHennen · 2024-09-19T07:27:14Z

Thanks for the updates! My main high-level suggestion is that the source track ought to make the roles and requirements of the VCS vs. SCP vs. producer clearer. In the Build track, the distinction between what the hosted build platform vs the producer is responsible for is called out. In the current source track spec, I feel like there are a lot of assumptions/expectations about the SCP, the producer and the VCS that we aren't including right now. So it might be helpful to draw a clearer separation between who is responsible for achieving which requirements.

Good feedback, added to #1128 (comment) to be sure we address it before we release.

TomHennen · 2024-09-19T07:46:37Z

Ok, I think all outstanding comments have been addressed or turned into tracking issues.

Can we get one more approval and merge this draft?

adityasaky

Some nits, but I think we can merge this! Thanks @TomHennen!

docs/spec/draft/source-requirements.md

Co-authored-by: Aditya Sirish <[email protected]> Signed-off-by: Tom Hennen <[email protected]>

Signed-off-by: Tom Hennen <[email protected]>

marcelamelara

Thanks @TomHennen ! I only have minor comments at this point; they can either be resolved quickly or in a future PR.

docs/spec/draft/source-requirements.md

Co-authored-by: Marcela Melara <[email protected]> Signed-off-by: Tom Hennen <[email protected]>

…e track level of revisions (slsa-framework#1094) fixes slsa-framework#1071 fixes slsa-framework#1042 refs slsa-framework#241 This PR modifies _draft_ content of the SLSA spec. See [discussions here](https://docs.google.com/document/d/13Xt8mA_2b00McGX2vkyhu4GQdFAqtXPu7YXE8ZA6ISE/edit?resourcekey=0-EqfHF79tUWAKp4PzsE3z1A&tab=t.0#heading=h.fhg4lsemfpz2) [and here](https://docs.google.com/document/d/1PwhekVB1iDpcgCQRNVN_aesoVdOiTruoebCs896aGxw/edit#bookmark=id.oqoqjt4urxm). Google document requires [[email protected]](mailto:[email protected]) membership. Define how downstream users can verify the SLSA source track level of revisions by using a [VSAs](http://slsa.dev/verification_summary) produced by the Source Control Platform (SCP). To use these VSAs users do not need to know the specifics of how any given SCP or Version Control System (VCS) meets the SLSA source requirements (which may vary greatly from implementation to implementation). Instead it is left to the SCP or another trusted 'authority' to make that determination for downstream users. The question of _how_ the authority ensures those claims to be true is left undefined in this change. Future updates can include guidance for how to verify source level when combined with [build provenance](https://slsa.dev/provenance). 1. A user wants to verify slsa-framework@9a04d1e is SLSA source level 3. 2. The user 'trusts' GitHub as the authority for source revisions managed by GitHub. 3. The user requests a VSA for slsa-framework@9a04d1e from a TBD API 4. The user verifies the VSA following [the standard instructions](https://slsa.dev/spec/draft/verification_summary#how-to-verify) or using [standard tooling](https://github.com/slsa-framework/slsa-verifier?tab=readme-ov-file#verification-summary-attestations-vsa) and looking for `SLSA_SOURCE_LEVEL_2` in the `verifiedLevels` field. --------- Signed-off-by: Tom Hennen <[email protected]> Signed-off-by: Tom Hennen <[email protected]> Co-authored-by: Zachariah Cox <[email protected]> Co-authored-by: Aditya Sirish <[email protected]> Co-authored-by: Marcela Melara <[email protected]>

Initial draft of a 'source attestation'.

aa087ad

Just focusing on how to communicate levels to downstream users. Future updates can include guidance for how to verify. Open question: should this live here or someplace else? refs slsa-framework#1071 Signed-off-by: Tom Hennen <[email protected]>

zachariahcox reviewed Jul 10, 2024

View reviewed changes

docs/spec/draft/source-requirements.md Outdated Show resolved Hide resolved