From aa087adbcce573600e2ab2f6e17cebfcc14cc47f Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Wed, 10 Jul 2024 14:25:56 +0000 Subject: [PATCH 01/36] Initial draft of a 'source attestation'. 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 #1071 Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 58 ++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 347b99839..6611d94e8 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -129,3 +129,61 @@ Trusted robots MAY be exempted from the code review process. It is RECOMMENDED t **[Different persons]** The organization strives to ensure that no two user accounts correspond to the same person. Should the organization discover that it issued multiple accounts to the same person, it MUST act to rectify the situation. For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that person's accounts are the author and/or code reviewer(s). Benefits: A compromise of a single human or account does not result in compromise of the project, since all changes require review from two humans. + +## Source Attestations + +There are two uses for source attestations within the source track: + +1. Assertions: Communicate to downstream users what high level security properties a given source revision meets. +2. Evidence: Provide trustworthy metadata which can be used to determine what high level security properties a given source revision meets. + +To provide interoperability and ensure ease of use, it's essential that the 'assertions' are applicabile 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 'evidence' attestations. To that end SLSA leaves 'evidence' attestations undefined and up to the SCPs to determine +what works best in their environment. + +### Source Level Assertions + +Source level assertions are issued by the SCP or some other authority that has sufficient evidence to make the determination of a given +revision's source level. + +These assertions are communicated in [Verification Summary Attestations (VSAs)](./verification_summary.md) as follows: + +1. `subject.uri` SHOULD be set to a human readable URI of the revision. +1. `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]. +1. `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) and SHOULD +provide the branch or refs. E.g. `git+https://github.com/foo/hello-world@refs/heads/main`. +1. `verifiedLevels` MUST include the SLSA source track level the issuer asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. +1. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. + +Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system, but SHOULD prefer to issue assertions based on Source Level Evidence appropriate to their SCP. + +#### Example + +``` +"_type": "https://in-toto.io/Statement/v1", +"subject": [{ + "uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a" + "digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"} +}], + +// Predicate +"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@refs/heads/main", + "policy": { + "uri": "https://example.com/slsa_source.policy", + }, + "verificationResult": "PASSED", + "verifiedLevels": ["SLSA_SOURCE_LEVEL_3"], +} +``` + +[^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms. + + From 6ebf74991a2c6e37f235c0c098b18c61f4be0280 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Wed, 10 Jul 2024 18:06:53 +0000 Subject: [PATCH 02/36] fix spelling Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 6611d94e8..ea0b3b614 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -137,7 +137,7 @@ There are two uses for source attestations within the source track: 1. Assertions: Communicate to downstream users what high level security properties a given source revision meets. 2. Evidence: Provide trustworthy metadata which can be used to determine what high level security properties a given source revision meets. -To provide interoperability and ensure ease of use, it's essential that the 'assertions' are applicabile across all Source Control Platforms. +To provide interoperability and ensure ease of use, it's essential that the 'assertions' 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 'evidence' attestations. To that end SLSA leaves 'evidence' attestations undefined and up to the SCPs to determine what works best in their environment. From 2b076ab8c189d76a478613af2f94af205f365b24 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Wed, 10 Jul 2024 18:09:19 +0000 Subject: [PATCH 03/36] make linter happy Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index ea0b3b614..e0026e661 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -134,8 +134,8 @@ Benefits: A compromise of a single human or account does not result in compromis There are two uses for source attestations within the source track: -1. Assertions: Communicate to downstream users what high level security properties a given source revision meets. -2. Evidence: Provide trustworthy metadata which can be used to determine what high level security properties a given source revision meets. +1. Assertions: Communicate to downstream users what high level security properties a given source revision meets. +2. Evidence: Provide trustworthy metadata which can be used to determine what high level security properties a given source revision meets. To provide interoperability and ensure ease of use, it's essential that the 'assertions' 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 @@ -149,26 +149,25 @@ revision's source level. These assertions are communicated in [Verification Summary Attestations (VSAs)](./verification_summary.md) as follows: -1. `subject.uri` SHOULD be set to a human readable URI of the revision. -1. `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...). +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]. -1. `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) and SHOULD +3. `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) and SHOULD provide the branch or refs. E.g. `git+https://github.com/foo/hello-world@refs/heads/main`. -1. `verifiedLevels` MUST include the SLSA source track level the issuer asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. -1. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. +4. `verifiedLevels` MUST include the SLSA source track level the issuer asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. +5. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system, but SHOULD prefer to issue assertions based on Source Level Evidence appropriate to their SCP. #### Example -``` +```json "_type": "https://in-toto.io/Statement/v1", "subject": [{ "uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a" "digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"} }], -// Predicate "predicateType": "https://slsa.dev/verification_summary/v1", "predicate": { "verifier": { @@ -185,5 +184,3 @@ Source Level Assertion issuers MAY issue assertions based on their understanding ``` [^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms. - - From 48f5301f9649fe1f25115b4d51fc6d723e2337ed Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Wed, 10 Jul 2024 18:13:16 +0000 Subject: [PATCH 04/36] We need a list of branches that pointed to the revision. --- docs/spec/draft/source-requirements.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index e0026e661..733ae4cb1 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -152,10 +152,11 @@ These assertions are communicated in [Verification Summary Attestations (VSAs)]( 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. `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) and SHOULD -provide the branch or refs. E.g. `git+https://github.com/foo/hello-world@refs/heads/main`. -4. `verifiedLevels` MUST include the SLSA source track level the issuer asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. -5. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. +3. `subject.annotations.source_branches` SHOULD be set to a list of branches that pointed to this revision at any point in their history. +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 issuer asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. +6. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system, but SHOULD prefer to issue assertions based on Source Level Evidence appropriate to their SCP. @@ -164,8 +165,9 @@ Source Level Assertion issuers MAY issue assertions based on their understanding ```json "_type": "https://in-toto.io/Statement/v1", "subject": [{ - "uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a" - "digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"} + "uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a", + "digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"}, + "annotations": {"source_branches": ["main", "release_1.0"]} }], "predicateType": "https://slsa.dev/verification_summary/v1", From d0281781606b613059225250c792857f51e3fc3c Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Wed, 10 Jul 2024 18:19:40 +0000 Subject: [PATCH 05/36] make linter happy Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 733ae4cb1..a2e241ee6 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -153,7 +153,7 @@ These assertions are communicated in [Verification Summary Attestations (VSAs)]( 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. -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). +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 issuer asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. 6. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. From da726cde797b7b39dbc81772854341688884503a Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Wed, 10 Jul 2024 18:20:41 +0000 Subject: [PATCH 06/36] allow other properties in verifiedLevels Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index a2e241ee6..771c84e99 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -156,6 +156,7 @@ SCPs that do not use cryptographic digests MUST define a canonical type that is 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 issuer 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 issuer. 6. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system, but SHOULD prefer to issue assertions based on Source Level Evidence appropriate to their SCP. From 0c2d8affbe8f7a54d2a2e9a04bae146a0562b7b0 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Wed, 10 Jul 2024 18:21:17 +0000 Subject: [PATCH 07/36] resourceUri does not need refs anymore Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 771c84e99..ffc8362c9 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -177,7 +177,7 @@ Source Level Assertion issuers MAY issue assertions based on their understanding "id": "https://example.com/source_verifier", }, "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "git+https://github.com/foo/hello-world@refs/heads/main", + "resourceUri": "git+https://github.com/foo/hello-world", "policy": { "uri": "https://example.com/slsa_source.policy", }, From a310289759906450cd360a5cdb4e6eb555ce28a3 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 12 Jul 2024 14:38:04 +0000 Subject: [PATCH 08/36] fully qualify git branches Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index ffc8362c9..fed53b919 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -153,6 +153,7 @@ These assertions are communicated in [Verification Summary Attestations (VSAs)]( 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 issuer asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. @@ -168,7 +169,7 @@ Source Level Assertion issuers MAY issue assertions based on their understanding "subject": [{ "uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a", "digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"}, - "annotations": {"source_branches": ["main", "release_1.0"]} + "annotations": {"source_branches": ["refs/heads/main", "refs/heads/release_1.0"]} }], "predicateType": "https://slsa.dev/verification_summary/v1", From 1c5136432b0591e82ae6308b118a8450db613466 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 12 Jul 2024 14:40:58 +0000 Subject: [PATCH 09/36] make linter happy Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index fed53b919..790e65841 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -153,7 +153,7 @@ These assertions are communicated in [Verification Summary Attestations (VSAs)]( 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. + - 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 issuer asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. From 9b05f90da49033e1baae2459b77c69dc1bb71147 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 12 Jul 2024 15:31:44 +0000 Subject: [PATCH 10/36] add instructions on how to verify Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 790e65841..d59081763 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -157,7 +157,7 @@ SCPs that do not use cryptographic digests MUST define a canonical type that is 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 issuer 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 issuer. +MAY include additional properties as asserted by the issuer. The issuer 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. Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system, but SHOULD prefer to issue assertions based on Source Level Evidence appropriate to their SCP. @@ -187,4 +187,11 @@ Source Level Assertion issuers MAY issue assertions based on their understanding } ``` +#### 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`. + [^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms. From 62d9375843d3741f9aee2aee37867f4b5dc2d1fa Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 12 Jul 2024 15:35:01 +0000 Subject: [PATCH 11/36] make linter happy Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index d59081763..27559a8be 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -189,9 +189,9 @@ Source Level Assertion issuers MAY issue assertions based on their understanding #### 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`. +- 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`. [^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms. From 9c1b891f51216ebec1bc52d8fa0f4f3254bac150 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 25 Jul 2024 10:32:31 -0400 Subject: [PATCH 12/36] Update docs/spec/draft/source-requirements.md Co-authored-by: Zachariah Cox Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 27559a8be..e270efb9b 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -144,7 +144,7 @@ what works best in their environment. ### Source Level Assertions -Source level assertions are issued by the SCP or some other authority that has sufficient evidence to make the determination of a given +Source level assertions are issued by some authority that has sufficient evidence to make the determination of a given revision's source level. These assertions are communicated in [Verification Summary Attestations (VSAs)](./verification_summary.md) as follows: From a5407091e45aafae4d1c294f34924fae8b3b1305 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 25 Jul 2024 14:33:37 +0000 Subject: [PATCH 13/36] clarify tamper-proof properties, start section on evidence Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 27559a8be..34e55cfd7 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -135,7 +135,7 @@ Benefits: A compromise of a single human or account does not result in compromis There are two uses for source attestations within the source track: 1. Assertions: Communicate to downstream users what high level security properties a given source revision meets. -2. Evidence: Provide trustworthy metadata which can be used to determine what high level security properties a given source revision meets. +2. Evidence: Provide trustworthy, tamper-proof, metadata which can be used to determine what high level security properties a given source revision meets. To provide interoperability and ensure ease of use, it's essential that the 'assertions' 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 @@ -160,7 +160,8 @@ E.g. `git+https://github.com/foo/hello-world`. MAY include additional properties as asserted by the issuer. The issuer 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. -Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system, but SHOULD prefer to issue assertions based on Source Level Evidence appropriate to their SCP. +Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system (e.g. based on design docs, security reviews, etc...), +but SHOULD prefer to issue assertions based on tamper-proof Source Level Evidence appropriate to their SCP. #### Example @@ -194,4 +195,7 @@ Source Level Assertion issuers MAY issue assertions based on their understanding - Users SHOULD check that the expected `SLSA_SOURCE_LEVEL_` is listed within `verifiedLevels`. - Users MUST ignore any unrecognized values in `verifiedLevels`. +### Source Level Evidence + + [^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms. From fd051aa7a0df80eeb239795e52a969a2f1e9866f Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 25 Jul 2024 14:49:00 +0000 Subject: [PATCH 14/36] flesh out Source Level Evidence Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 8c3a46bb7..6daf68eea 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -161,7 +161,7 @@ MAY include additional properties as asserted by the issuer. The issuer MUST in 6. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system (e.g. based on design docs, security reviews, etc...), -but SHOULD prefer to issue assertions based on tamper-proof Source Level Evidence appropriate to their SCP. +but SHOULD prefer to issue assertions based on tamper-proof [Source Level Evidence](#source-level-evidence) appropriate to their SCP. #### Example @@ -197,5 +197,17 @@ but SHOULD prefer to issue assertions based on tamper-proof Source Level Evidenc ### Source Level Evidence +Source level evidence is the tamper-proof (ideally signed in-toto attestations) that can be used to determine what SLSA Source Level a given revision meets. +This evidence can be used by an authority as the basis for issuing a [Source Level Assertion](#source-level-assertion). + +SCPs and VCSes may have different methods of operating that necessetate 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. + +Examples of evidence +* 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. + +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. From c7e6fd7706f71e6704ad48d7cdc6b9ddfc92c1aa Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 25 Jul 2024 15:03:02 +0000 Subject: [PATCH 15/36] make linter happy Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 6daf68eea..7070a1d43 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -203,11 +203,11 @@ This evidence can be used by an authority as the basis for issuing a [Source Lev SCPs and VCSes may have different methods of operating that necessetate 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. -Examples of evidence -* 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. +Examples of evidence: -TODO: Can we define or recommend any canonical formats? +- 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. +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. From 88f4fbc5fb7ade3da68ca3aecdc90c43fe6b3a3e Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Wed, 14 Aug 2024 18:30:48 +0000 Subject: [PATCH 16/36] Use standardized language for the source attestations Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 27 +++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 7070a1d43..49e1e0d1f 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -132,22 +132,22 @@ Benefits: A compromise of a single human or account does not result in compromis ## Source Attestations -There are two uses for source attestations within the source track: +There are two broad categories of source attestations within the source track: -1. Assertions: Communicate to downstream users what high level security properties a given source revision meets. -2. Evidence: Provide trustworthy, tamper-proof, metadata which can be used to determine what high level security properties a given source revision meets. +1. Summary attestations: Used to communicate to downstream users what high level security properties a given source revision meets. +2. Detailed attestations: Provide trustworthy, tamper-proof, metadata which can be used to determine what high level security properties a given source revision meets. -To provide interoperability and ensure ease of use, it's essential that the 'assertions' are applicable across all Source Control Platforms. +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 'evidence' attestations. To that end SLSA leaves 'evidence' attestations undefined and up to the SCPs to determine +allow for flexibility with the detailed attestations. To that end SLSA leaves detailed attestations undefined and up to the SCPs to determine what works best in their environment. -### Source Level Assertions +### Summary attestation -Source level assertions are issued by some authority that has sufficient evidence to make the determination of a given +Summary attestations are issued by some authority that has sufficient evidence to make the determination of a given revision's source level. -These assertions are communicated in [Verification Summary Attestations (VSAs)](./verification_summary.md) as follows: +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...). @@ -160,8 +160,8 @@ E.g. `git+https://github.com/foo/hello-world`. MAY include additional properties as asserted by the issuer. The issuer 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. -Source Level Assertion issuers MAY issue assertions based on their understanding of the underlying system (e.g. based on design docs, security reviews, etc...), -but SHOULD prefer to issue assertions based on tamper-proof [Source Level Evidence](#source-level-evidence) appropriate to their SCP. +Issuers 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 [detailed attestations](#detailed-attestations) appropriate to their SCP when making the assessment. #### Example @@ -195,13 +195,14 @@ but SHOULD prefer to issue assertions based on tamper-proof [Source Level Eviden - Users SHOULD check that the expected `SLSA_SOURCE_LEVEL_` is listed within `verifiedLevels`. - Users MUST ignore any unrecognized values in `verifiedLevels`. -### Source Level Evidence +### Detailed attestations Source level evidence is the tamper-proof (ideally signed in-toto attestations) that can be used to determine what SLSA Source Level a given revision meets. -This evidence can be used by an authority as the basis for issuing a [Source Level Assertion](#source-level-assertion). +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 necessetate 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. +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. Examples of evidence: From c54d16b98a20f54280a60dbe31fa9f867fd43793 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 15 Aug 2024 17:11:22 +0000 Subject: [PATCH 17/36] clarify attestations are about revisions (for the most part) Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index d07b3024e..d98a00b7b 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -248,6 +248,7 @@ 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: @@ -262,7 +263,8 @@ 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. +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: From f8b87a4b9c54cd652ff4e4962d825a12660fd0fa Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 15 Aug 2024 17:30:02 +0000 Subject: [PATCH 18/36] issuer -> verifier Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index d98a00b7b..b924225d9 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -275,11 +275,11 @@ SCPs that do not use cryptographic digests MUST define a canonical type that is - 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 issuer 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 issuer. The issuer MUST include _only_ the highest SLSA source level met by the revision. +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. -Issuers MAY issue these attestations based on their understanding of the underlying system (e.g. based on design docs, security reviews, etc...), +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 [detailed attestations](#detailed-attestations) appropriate to their SCP when making the assessment. #### Example From be652863b250f2055f580e8fd79d8717c6467d3e Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 16 Aug 2024 16:15:42 +0000 Subject: [PATCH 19/36] clarify source level evidence Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index b924225d9..17f725a66 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -316,7 +316,8 @@ but at SLSA Source Level 3 MUST used tamper-proof [detailed attestations](#detai ### Detailed attestations -Source level evidence is the tamper-proof (ideally signed in-toto attestations) that can be used to determine what SLSA Source Level a given revision meets. +Detailed attestations provide tamper-proof evidence (ideally signed in-toto attestations) 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 necessetate different forms of evidence. From 55b71089c131e2063fb8a04121c4e157285e65dc Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 16 Aug 2024 16:17:46 +0000 Subject: [PATCH 20/36] detailed -> full Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 17f725a66..30956f464 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -253,11 +253,11 @@ These attestations either refer to a source revision itself or provide context n 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. Detailed attestations: Provide trustworthy, tamper-proof, metadata which can be used to determine 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 detailed attestations. To that end SLSA leaves detailed attestations undefined and up to the SCPs to determine +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 @@ -280,7 +280,7 @@ MAY include additional properties as asserted by the verifier. The verifier MUS 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 [detailed attestations](#detailed-attestations) appropriate to their SCP when making the assessment. +but at SLSA Source Level 3 MUST used tamper-proof [full attestations](#full-attestations) appropriate to their SCP when making the assessment. #### Example @@ -314,9 +314,9 @@ but at SLSA Source Level 3 MUST used tamper-proof [detailed attestations](#detai - Users SHOULD check that the expected `SLSA_SOURCE_LEVEL_` is listed within `verifiedLevels`. - Users MUST ignore any unrecognized values in `verifiedLevels`. -### Detailed attestations +### Full attestations -Detailed attestations provide tamper-proof evidence (ideally signed in-toto attestations) that can be used to determine +Full attestations provide tamper-proof evidence (ideally signed in-toto attestations) 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). From 7916e37d7688f406e3fe9f068b456a6f5292e7d7 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 16 Aug 2024 16:19:50 +0000 Subject: [PATCH 21/36] fix typo Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 30956f464..fc37af63e 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -320,7 +320,7 @@ Full attestations provide tamper-proof evidence (ideally signed in-toto attestat 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 necessetate different forms of evidence. +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. From 21cadb04cb3f310c1473b5c495b26ffe642a7981 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 16 Aug 2024 16:31:32 +0000 Subject: [PATCH 22/36] more evidence examples Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index fc37af63e..5b4582ce2 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -326,8 +326,15 @@ operate over Subversion repositories. 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. TODO: Can we define or recommend any canonical formats? From 858d37f39fe86c50a3698aa6cca15070cafedbd2 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 16 Aug 2024 16:35:05 +0000 Subject: [PATCH 23/36] clarify that the source track may define new types of tags Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 5b4582ce2..314c3f451 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -282,6 +282,9 @@ MAY include additional properties as asserted by the verifier. The verifier MUS 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 From 72d3163e3c62bb427080cc4c8cebf7c0fd95f93d Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Tue, 20 Aug 2024 17:48:40 +0000 Subject: [PATCH 24/36] clarify who the attestors are Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 314c3f451..7bf90547e 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -319,14 +319,20 @@ to other properties of a revision (e.g. if it was code reviewed). All SLSA sour ### Full attestations -Full attestations provide tamper-proof evidence (ideally signed in-toto attestations) that can be used to determine -what SLSA Source Level or other high level properties a given revision meets +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. From 7f2ad75f21e2f600672e9f141a541df107dbdaab Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Mon, 9 Sep 2024 14:33:00 +0000 Subject: [PATCH 25/36] Add SCAI as example evidence Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 7bf90547e..826f7132f 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -344,6 +344,8 @@ Examples of evidence: 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? From 3e502cffe2946eb34a6166c45309183c15e96c9d Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Mon, 9 Sep 2024 14:52:30 +0000 Subject: [PATCH 26/36] Add TODOs Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 826f7132f..4ab6916e9 100644 --- a/docs/spec/draft/source-requirements.md +++ b/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 From ef1eb829ba6f95114c0f0a994738d35c4d02a964 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Mon, 9 Sep 2024 18:06:34 +0000 Subject: [PATCH 27/36] 'full attestation' -> 'provenance attestation' Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 4ab6916e9..88137bac6 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -255,7 +255,7 @@ These attestations either refer to a source revision itself or provide context n 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. +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 @@ -319,9 +319,9 @@ to other properties of a revision (e.g. if it was code reviewed). All SLSA sour - Users SHOULD check that the expected `SLSA_SOURCE_LEVEL_` is listed within `verifiedLevels`. - Users MUST ignore any unrecognized values in `verifiedLevels`. -### Full attestations +### Provenance attestations -Full attestations provide tamper-proof evidence (ideally signed [in-toto attestations](https://github.com/in-toto/attestation/blob/main/README.md)) +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). @@ -335,7 +335,10 @@ may vary. The authority that issues [summary-attestations](#summary-attestation which entity should issue each full attestation type and ensure the full attestations come from the appropriate attestor. -Examples of evidence: +'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. From 63d5c488bcee8b182957760923950d0e16a73d1d Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Mon, 9 Sep 2024 18:24:44 +0000 Subject: [PATCH 28/36] clarify when source_branches get set Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 88137bac6..aaa8758ac 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -287,6 +287,16 @@ but at SLSA Source Level 3 MUST used tamper-proof [full attestations](#full-atte 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. +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 From 85a6c7f2dc9598f73f6f89036f95c48e79a78451 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 19 Sep 2024 09:09:49 +0200 Subject: [PATCH 29/36] Update docs/spec/draft/source-requirements.md Co-authored-by: Zachariah Cox Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index ee0ba2b73..cc534d476 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -325,7 +325,7 @@ Example implementations: ### 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 +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. From 2de9531dbee82cb3081efbc4bc468fd37a942afa Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 19 Sep 2024 09:10:01 +0200 Subject: [PATCH 30/36] Update docs/spec/draft/source-requirements.md Co-authored-by: Zachariah Cox Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index cc534d476..186547bdb 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -329,7 +329,7 @@ that can be used to determine what SLSA Source Level or other high level propert 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 +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 From 7955011453691338117cc8d74da28bebb03ccfc6 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 19 Sep 2024 07:18:35 +0000 Subject: [PATCH 31/36] attestor->issuer and full->provenance Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 186547bdb..5f01f74a7 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -332,11 +332,11 @@ SCPs and VCSes may have different methods of operating that necessitate differen 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. +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 +[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. From fb001a4f2adafad311be58b19ef1fb7ef8316ba2 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 20 Sep 2024 15:00:38 +0200 Subject: [PATCH 32/36] Update docs/spec/draft/source-requirements.md Co-authored-by: Aditya Sirish <8928778+adityasaky@users.noreply.github.com> Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 5f01f74a7..9176aed75 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -252,7 +252,7 @@ There are two broad categories of source attestations within the source track: 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 +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. ### Summary attestation From 01a55cdb0d53ab596203c6d458706121648509f9 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 20 Sep 2024 15:00:55 +0200 Subject: [PATCH 33/36] Update docs/spec/draft/source-requirements.md Co-authored-by: Aditya Sirish <8928778+adityasaky@users.noreply.github.com> Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 9176aed75..b0b818e97 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -275,7 +275,7 @@ MAY include additional properties as asserted by the verifier. The verifier MUS 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. +but at SLSA Source Level 3 MUST used tamper-proof [provenance attestations](#provenance-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_`. From 074187766e7ddc2f812ede1220bf916f482c7071 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Fri, 20 Sep 2024 13:04:53 +0000 Subject: [PATCH 34/36] remove old TODO Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index b0b818e97..0be72810c 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -355,6 +355,4 @@ Example source provenance attestations: - 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. From bd719049567ad117533d8772203fdef2b2c4b89d Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Mon, 23 Sep 2024 10:50:46 -0400 Subject: [PATCH 35/36] Update docs/spec/draft/source-requirements.md Co-authored-by: Marcela Melara Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 0be72810c..e73bad7a2 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -275,7 +275,7 @@ MAY include additional properties as asserted by the verifier. The verifier MUS 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. +but at SLSA Source Level 3 MUST use tamper-proof [provenance attestations](#provenance-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_`. From b197be7638e7e48ed63fce51cadd18b6e96b9eaa Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Mon, 23 Sep 2024 10:51:05 -0400 Subject: [PATCH 36/36] Update docs/spec/draft/source-requirements.md Co-authored-by: Marcela Melara Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index e73bad7a2..c092b9e75 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -282,7 +282,7 @@ to other properties of a revision (e.g. if it was code reviewed). All SLSA sour #### Populating source_branches -The summary attestation issuer may chose to populate `source_branches` in any way they wish. +The summary attestation issuer may choose to populate `source_branches` in any way they wish. Downstream users are expected to be familiar with the method used by the issuer. Example implementations: