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

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

Merged
merged 40 commits into from
Sep 23, 2024
Merged
Changes from 38 commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
aa087ad
Initial draft of a 'source attestation'.
TomHennen Jul 10, 2024
6ebf749
fix spelling
TomHennen Jul 10, 2024
2b076ab
make linter happy
TomHennen Jul 10, 2024
48f5301
We need a list of branches that pointed to the revision.
TomHennen Jul 10, 2024
d028178
make linter happy
TomHennen Jul 10, 2024
da726cd
allow other properties in verifiedLevels
TomHennen Jul 10, 2024
0c2d8af
resourceUri does not need refs anymore
TomHennen Jul 10, 2024
a310289
fully qualify git branches
TomHennen Jul 12, 2024
1c51364
make linter happy
TomHennen Jul 12, 2024
9b05f90
add instructions on how to verify
TomHennen Jul 12, 2024
62d9375
make linter happy
TomHennen Jul 12, 2024
9c1b891
Update docs/spec/draft/source-requirements.md
TomHennen Jul 25, 2024
a540709
clarify tamper-proof properties, start section on evidence
TomHennen Jul 25, 2024
d310507
Merge branch 'source_attestation' of github.com:TomHennen/slsa into s…
TomHennen Jul 25, 2024
fd051aa
flesh out Source Level Evidence
TomHennen Jul 25, 2024
c7e6fd7
make linter happy
TomHennen Jul 25, 2024
88f4fbc
Use standardized language for the source attestations
TomHennen Aug 14, 2024
a50bfb5
merge
TomHennen Aug 15, 2024
c54d16b
clarify attestations are about revisions (for the most part)
TomHennen Aug 15, 2024
f8b87a4
issuer -> verifier
TomHennen Aug 15, 2024
be65286
clarify source level evidence
TomHennen Aug 16, 2024
55b7108
detailed -> full
TomHennen Aug 16, 2024
7916e37
fix typo
TomHennen Aug 16, 2024
21cadb0
more evidence examples
TomHennen Aug 16, 2024
858d37f
clarify that the source track may define new types of tags
TomHennen Aug 16, 2024
72d3163
clarify who the attestors are
TomHennen Aug 20, 2024
7f2ad75
Add SCAI as example evidence
TomHennen Sep 9, 2024
3e502cf
Add TODOs
TomHennen Sep 9, 2024
ef1eb82
'full attestation' -> 'provenance attestation'
TomHennen Sep 9, 2024
63d5c48
clarify when source_branches get set
TomHennen Sep 9, 2024
c5ab4a9
Merge branch 'main' of github.com:slsa-framework/slsa into source_att…
TomHennen Sep 13, 2024
2844f59
Merge branch 'main' into source_attestation
TomHennen Sep 17, 2024
85a6c7f
Update docs/spec/draft/source-requirements.md
TomHennen Sep 19, 2024
2de9531
Update docs/spec/draft/source-requirements.md
TomHennen Sep 19, 2024
7955011
attestor->issuer and full->provenance
TomHennen Sep 19, 2024
fb001a4
Update docs/spec/draft/source-requirements.md
TomHennen Sep 20, 2024
01a55cd
Update docs/spec/draft/source-requirements.md
TomHennen Sep 20, 2024
0741877
remove old TODO
TomHennen Sep 20, 2024
bd71904
Update docs/spec/draft/source-requirements.md
TomHennen Sep 23, 2024
b197be7
Update docs/spec/draft/source-requirements.md
TomHennen Sep 23, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 119 additions & 0 deletions docs/spec/draft/source-requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Open issues are tracked with the [source-track](https://github.com/slsa-framewor
- [] [How to communicate SLSA source track metadata?](https://github.com/slsa-framework/slsa/issues/1071)
- [] [Create guidance for consumers on how to evaluate the source platform](https://github.com/slsa-framework/slsa/issues/1078)
- [] [Clarify what must be retained during source migrations](https://github.com/slsa-framework/slsa/issues/1079)
- [] [Define source control 'system'](https://github.com/slsa-framework/slsa/issues/1128)
- [] [Define where source attestations are stored](https://github.com/slsa-framework/slsa/issues/1129)

## Objective

Expand Down Expand Up @@ -237,3 +239,120 @@ Branches may have differing security postures, and a change can be approved for

The change management tool MUST record timestamps for all contributions and review-related activities.
User-provided timestamps MUST NOT be used.

## Communicating source levels

SLSA source level details are communicated using attestations.
These attestations either refer to a source revision itself or provide context needed to evaluate an attestation that _does_ refer to a revision.

There are two broad categories of source attestations within the source track:
TomHennen marked this conversation as resolved.
Show resolved Hide resolved

1. Summary attestations: Used to communicate to downstream users what high level security properties a given source revision meets.
2. Provenance attestations: Provide trustworthy, tamper-proof, metadata with the necessary information to determine what high level security properties a given source revision has.

To provide interoperability and ensure ease of use, it's essential that the summary attestations are applicable across all Source Control Platforms.
Due to the significant differences in how SCPs operate and how they may chose to meet the Source Track requirements it is preferable to
allow for flexibility with the full attestations. To that end SLSA leaves provenance attestations undefined and up to the SCPs to determine
what works best in their environment.
TomHennen marked this conversation as resolved.
Show resolved Hide resolved

### Summary attestation

Summary attestations are issued by some authority that has sufficient evidence to make the determination of a given
revision's source level. Summary attestations convey properties about the revision as a whole and summarize properties computed over all
the changes that contributed to that revision over its history.

The source track issues summary attestations using [Verification Summary Attestations (VSAs)](./verification_summary.md) as follows:
TomHennen marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

- git branches MUST be fully qualified (e.g. `refs/head/main`) to reduce the likelyhood of confusing downstream tooling.
4. `resourceUri` MUST be set to the URI of the repository, preferably using [SPDX Download Location](https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field).
E.g. `git+https://github.com/foo/hello-world`.
5. `verifiedLevels` MUST include the SLSA source track level the verifier asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`.
MAY include additional properties as asserted by the verifier. The verifier MUST include _only_ the highest SLSA source level met by the revision.
6. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain.

Verifiers MAY issue these attestations based on their understanding of the underlying system (e.g. based on design docs, security reviews, etc...),
but at SLSA Source Level 3 MUST used tamper-proof [provenance attestations](#provenance-attestations) appropriate to their SCP when making the assessment.
TomHennen marked this conversation as resolved.
Show resolved Hide resolved

The SLSA source track MAY create additional tags to include in `verifiedLevels` which attest
to other properties of a revision (e.g. if it was code reviewed). All SLSA source tags will start with `SLSA_SOURCE_`.

#### Populating source_branches

The summary attestation issuer may chose to populate `source_branches` in any way they wish.
TomHennen marked this conversation as resolved.
Show resolved Hide resolved
Downstream users are expected to be familiar with the method used by the issuer.

Example implementations:

- Issue a new VSA for each merged Pull Request and add the destination branch to `source_branches`.
- Issue a new VSA each time a 'consumable branch' is updated to point to a new revision.

#### Example

```json
"_type": "https://in-toto.io/Statement/v1",
"subject": [{
"uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a",
"digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"},
"annotations": {"source_branches": ["refs/heads/main", "refs/heads/release_1.0"]}
TomHennen marked this conversation as resolved.
Show resolved Hide resolved
}],

"predicateType": "https://slsa.dev/verification_summary/v1",
"predicate": {
"verifier": {
TomHennen marked this conversation as resolved.
Show resolved Hide resolved
"id": "https://example.com/source_verifier",
},
"timeVerified": "1985-04-12T23:20:50.52Z",
"resourceUri": "git+https://github.com/foo/hello-world",
"policy": {
"uri": "https://example.com/slsa_source.policy",
},
"verificationResult": "PASSED",
"verifiedLevels": ["SLSA_SOURCE_LEVEL_3"],
}
```

#### How to verify

- VSAs for source revisions MUST follow [the standard method of VSA verification](./verification_summary.md#how-to-verify).
- Users SHOULD check that an allowed branch is listed in `subject.annotations.source_branches` to ensure the revision is from an appropriate context within the repository.
TomHennen marked this conversation as resolved.
Show resolved Hide resolved
- Users SHOULD check that the expected `SLSA_SOURCE_LEVEL_` is listed within `verifiedLevels`.
- Users MUST ignore any unrecognized values in `verifiedLevels`.

### Provenance attestations

Source provenance attestations provide tamper-proof evidence (ideally signed [in-toto attestations](https://github.com/in-toto/attestation/blob/main/README.md))
that can be used to determine what SLSA Source Level or other high level properties a given revision meets.
This evidence can be used by an authority as the basis for issuing a [Summary Attestation](#summary-attestation).

SCPs and VCSes may have different methods of operating that necessitate different forms of evidence.
E.g. GitHub-based workflows may need different evidence than Gerrit-based workflows, which would both likely be different from workflows that
operate over Subversion repositories.

These differences also mean that depending on the SCP and the repo's configuration the issuers of
provenance attestations may vary from implementation to implementation, often because entities with
the knowledge to issue them may vary. The authority that issues
TomHennen marked this conversation as resolved.
Show resolved Hide resolved
[summary-attestations](#summary-attestation) MUST understand which entity should issue each provenance
attestation type and ensure the full attestations come from the appropriate issuer.

'Source provenance attestations' is a generic term used to refer to any type of attestation that provides
evidence the process used to create a revision.

Example source provenance attestations:

- A TBD attestation which describes the revision's parents and the actors involved in creating this revision.
- A "code review" attestation which describes the basics of any code review that took place.
- An "authentication" attestation which describes how the actors involved in any revision were authenticated.
TomHennen marked this conversation as resolved.
Show resolved Hide resolved
- A [Vuln Scan attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/vuln.md)
which describes the results of a vulnerability scan over the contents of the revision.
- A [Test Results attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/test-result.md)
which describes the results of any tests run on the revision.
- An [SPDX attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md)
which provides a software bill of materials for the revision.
- A [SCAI attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md) used to
describe which source quality tools were run on the revision.

[^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms.