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

docs/spec/draft/source-requirements.md

@@ -15,6 +15,8 @@ Open issues are tracked with the [source-track](https://github.com/slsa-framewor
 -   [] [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)
 -   [] [Refine requirements/guidance for trusted robots](https://github.com/slsa-framework/slsa/issues/1080)
+-   [] [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
 
@@ -244,3 +246,109 @@ 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:
+
+1.  Summary attestations: Used to communicate to downstream users what high level security properties a given source revision meets.
+2.  Full 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 full attestations undefined and up to the SCPs to determine
+what works best in their environment.
+
+### 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:
+
+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.
+    -   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 [full attestations](#full-attestations) appropriate to their SCP when making the assessment.
+
+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_`.
+
+#### 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"]}
+}],
+
+"predicateType": "https://slsa.dev/verification_summary/v1",
+"predicate": {
+  "verifier": {
+    "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.
+-   Users SHOULD check that the expected `SLSA_SOURCE_LEVEL_` is listed within `verifiedLevels`.
+-   Users MUST ignore any unrecognized values in `verifiedLevels`.
+
+### Full attestations
+
+Full 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 attestor may
+vary from implementation to implementation, often because entities with the knowledge to issue them
+may vary.  The authority that issues [summary-attestations](#summary-attestation) MUST understand
+which entity should issue each full attestation type and ensure the full attestations come from the
+appropriate attestor.
+
+Examples of evidence:
+
+-   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.
+-   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.
+
+TODO: Can we define or recommend any canonical formats?
+
+[^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms.