From 31662a9f380e5cb45dc3103abf6b29c41db165b4 Mon Sep 17 00:00:00 2001 From: arewm Date: Fri, 13 Oct 2023 15:44:37 -0400 Subject: [PATCH 1/6] editorial: Clarify the requirements for self-hosted runners on provenance Resolves: #966 Some CI systems allow for users to configure self-hosted runner environments for perform builds and CI analysis. While both the build platform and the self-hosted runners have the ability to affect the build for the resulting artifact, the SLSA Build requirements do not need to be imposed on both systems. This addition to the FAQ is a clarification of the requirements as they relate to the generation of the provenance. Signed-off-by: arewm --- docs/spec/v1.0/faq.md | 27 +++++++++++++++++++++++++++ docs/spec/v1.1/faq.md | 27 +++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/docs/spec/v1.0/faq.md b/docs/spec/v1.0/faq.md index 9766dd382..b63909fea 100644 --- a/docs/spec/v1.0/faq.md +++ b/docs/spec/v1.0/faq.md @@ -150,6 +150,33 @@ describes our understanding of the intersection efforts today. We do not know how things will evolve over the coming months and years, but we look forward to the collaboration and improved software supply chain security. +## Q: How to SLSA with a self-hosted runner + +Some CI systems allow producers to provide their own self-hosted runners as a build +environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage +these, classifying the SLSA build level for the resulting artifact can be confusing. + +Since the SLSA Build track describes increasing levels of trustworthiness and +completeness in a package artifact's provenance, interpretation of the +specification hinges on the platform entities involved in the provenance generation. +The SLSA build level requirements (secure key storage, isolation, etc.) should be +imposed on the transitive closure of the systems which are responsible for informing +the provenance generated. + +Some common situations may include: + +- The platform generates the provenance and just calls a runner for individual items. + In this situation, the provenance is only affected by the platform so there would be + no requirements imposed on the runner. +- The runner generates the provenance. In this situation, the orchestrating platform + is irrelevant and all requirements are imposed on the runner. +- The platform provides the runner with some credentials for generating the provenance + or both the platform and the runner provide information for the provenance.Trust is + shared between the platform and the runner so the requirements are imposed on both. + +Requirements on the self-hosted runners may increase with Build levels greater than L3. + +[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners [Software Bill of Materials (SBOM)]: https://ntia.gov/sbom [SLSA Provenance]: provenance.md [Build track]: levels.md#build-track diff --git a/docs/spec/v1.1/faq.md b/docs/spec/v1.1/faq.md index 9766dd382..b63909fea 100644 --- a/docs/spec/v1.1/faq.md +++ b/docs/spec/v1.1/faq.md @@ -150,6 +150,33 @@ describes our understanding of the intersection efforts today. We do not know how things will evolve over the coming months and years, but we look forward to the collaboration and improved software supply chain security. +## Q: How to SLSA with a self-hosted runner + +Some CI systems allow producers to provide their own self-hosted runners as a build +environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage +these, classifying the SLSA build level for the resulting artifact can be confusing. + +Since the SLSA Build track describes increasing levels of trustworthiness and +completeness in a package artifact's provenance, interpretation of the +specification hinges on the platform entities involved in the provenance generation. +The SLSA build level requirements (secure key storage, isolation, etc.) should be +imposed on the transitive closure of the systems which are responsible for informing +the provenance generated. + +Some common situations may include: + +- The platform generates the provenance and just calls a runner for individual items. + In this situation, the provenance is only affected by the platform so there would be + no requirements imposed on the runner. +- The runner generates the provenance. In this situation, the orchestrating platform + is irrelevant and all requirements are imposed on the runner. +- The platform provides the runner with some credentials for generating the provenance + or both the platform and the runner provide information for the provenance.Trust is + shared between the platform and the runner so the requirements are imposed on both. + +Requirements on the self-hosted runners may increase with Build levels greater than L3. + +[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners [Software Bill of Materials (SBOM)]: https://ntia.gov/sbom [SLSA Provenance]: provenance.md [Build track]: levels.md#build-track From f92baffd95dfa106e9ef8709ab1465628199646c Mon Sep 17 00:00:00 2001 From: arewm Date: Tue, 24 Oct 2023 09:18:48 -0400 Subject: [PATCH 2/6] address review comments Signed-off-by: arewm --- docs/spec/v1.0/faq.md | 5 +++-- docs/spec/v1.1/faq.md | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/spec/v1.0/faq.md b/docs/spec/v1.0/faq.md index b63909fea..290f487be 100644 --- a/docs/spec/v1.0/faq.md +++ b/docs/spec/v1.0/faq.md @@ -159,7 +159,7 @@ these, classifying the SLSA build level for the resulting artifact can be confus Since the SLSA Build track describes increasing levels of trustworthiness and completeness in a package artifact's provenance, interpretation of the specification hinges on the platform entities involved in the provenance generation. -The SLSA build level requirements (secure key storage, isolation, etc.) should be +The SLSA [build level requirements] (secure key storage, isolation, etc.) should be imposed on the transitive closure of the systems which are responsible for informing the provenance generated. @@ -171,11 +171,12 @@ Some common situations may include: - The runner generates the provenance. In this situation, the orchestrating platform is irrelevant and all requirements are imposed on the runner. - The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance.Trust is + or both the platform and the runner provide information for the provenance. Trust is shared between the platform and the runner so the requirements are imposed on both. Requirements on the self-hosted runners may increase with Build levels greater than L3. +[build level requirements]: requirements.md [GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners [Software Bill of Materials (SBOM)]: https://ntia.gov/sbom [SLSA Provenance]: provenance.md diff --git a/docs/spec/v1.1/faq.md b/docs/spec/v1.1/faq.md index b63909fea..290f487be 100644 --- a/docs/spec/v1.1/faq.md +++ b/docs/spec/v1.1/faq.md @@ -159,7 +159,7 @@ these, classifying the SLSA build level for the resulting artifact can be confus Since the SLSA Build track describes increasing levels of trustworthiness and completeness in a package artifact's provenance, interpretation of the specification hinges on the platform entities involved in the provenance generation. -The SLSA build level requirements (secure key storage, isolation, etc.) should be +The SLSA [build level requirements] (secure key storage, isolation, etc.) should be imposed on the transitive closure of the systems which are responsible for informing the provenance generated. @@ -171,11 +171,12 @@ Some common situations may include: - The runner generates the provenance. In this situation, the orchestrating platform is irrelevant and all requirements are imposed on the runner. - The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance.Trust is + or both the platform and the runner provide information for the provenance. Trust is shared between the platform and the runner so the requirements are imposed on both. Requirements on the self-hosted runners may increase with Build levels greater than L3. +[build level requirements]: requirements.md [GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners [Software Bill of Materials (SBOM)]: https://ntia.gov/sbom [SLSA Provenance]: provenance.md From 0653003f1b0b709ea18687d4e22322f7446934f0 Mon Sep 17 00:00:00 2001 From: Michael Lieberman Date: Mon, 13 Nov 2023 12:58:03 -0500 Subject: [PATCH 3/6] Update docs/spec/v1.0/faq.md Co-authored-by: Andrew McNamara Signed-off-by: Michael Lieberman --- docs/spec/v1.0/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/v1.0/faq.md b/docs/spec/v1.0/faq.md index 290f487be..6d96c97f7 100644 --- a/docs/spec/v1.0/faq.md +++ b/docs/spec/v1.0/faq.md @@ -165,7 +165,7 @@ the provenance generated. Some common situations may include: -- The platform generates the provenance and just calls a runner for individual items. +- The platform generates the provenance and just calls a runner for individual build steps. In this situation, the provenance is only affected by the platform so there would be no requirements imposed on the runner. - The runner generates the provenance. In this situation, the orchestrating platform From 86cdeafabf533837d118185c3a0a7918e54b5595 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Fri, 17 Nov 2023 15:00:04 -0500 Subject: [PATCH 4/6] Update docs/spec/v1.0/faq.md Co-authored-by: Arnaud J Le Hors Signed-off-by: Mark Lodato --- docs/spec/v1.0/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/v1.0/faq.md b/docs/spec/v1.0/faq.md index 6d96c97f7..7512aa700 100644 --- a/docs/spec/v1.0/faq.md +++ b/docs/spec/v1.0/faq.md @@ -174,7 +174,7 @@ Some common situations may include: or both the platform and the runner provide information for the provenance. Trust is shared between the platform and the runner so the requirements are imposed on both. -Requirements on the self-hosted runners may increase with Build levels greater than L3. +Additional requirements on the self-hosted runners may be added to Build levels greater than L3 when such levels get defined. [build level requirements]: requirements.md [GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners From 3e3ff36e4864f7fe0611a4e5467d6d39631c9307 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Fri, 17 Nov 2023 15:00:50 -0500 Subject: [PATCH 5/6] Update docs/spec/v1.1/faq.md Signed-off-by: Mark Lodato --- docs/spec/v1.1/faq.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/spec/v1.1/faq.md b/docs/spec/v1.1/faq.md index 290f487be..f14497708 100644 --- a/docs/spec/v1.1/faq.md +++ b/docs/spec/v1.1/faq.md @@ -174,7 +174,8 @@ Some common situations may include: or both the platform and the runner provide information for the provenance. Trust is shared between the platform and the runner so the requirements are imposed on both. -Requirements on the self-hosted runners may increase with Build levels greater than L3. +Additional requirements on the self-hosted runners may be added to Build levels greater than +L3 when such levels get defined. [build level requirements]: requirements.md [GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners From a6a02b1b672374bb8f28701a63d21389e9f38a69 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Fri, 17 Nov 2023 15:07:47 -0500 Subject: [PATCH 6/6] wrap to 80 cols Signed-off-by: Mark Lodato --- docs/spec/v1.0/faq.md | 3 ++- docs/spec/v1.1/faq.md | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/spec/v1.0/faq.md b/docs/spec/v1.0/faq.md index 7512aa700..ad0bd577c 100644 --- a/docs/spec/v1.0/faq.md +++ b/docs/spec/v1.0/faq.md @@ -174,7 +174,8 @@ Some common situations may include: or both the platform and the runner provide information for the provenance. Trust is shared between the platform and the runner so the requirements are imposed on both. -Additional requirements on the self-hosted runners may be added to Build levels greater than L3 when such levels get defined. +Additional requirements on the self-hosted runners may be added to Build levels +greater than L3 when such levels get defined. [build level requirements]: requirements.md [GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners diff --git a/docs/spec/v1.1/faq.md b/docs/spec/v1.1/faq.md index f14497708..90ed7bb8c 100644 --- a/docs/spec/v1.1/faq.md +++ b/docs/spec/v1.1/faq.md @@ -174,8 +174,8 @@ Some common situations may include: or both the platform and the runner provide information for the provenance. Trust is shared between the platform and the runner so the requirements are imposed on both. -Additional requirements on the self-hosted runners may be added to Build levels greater than -L3 when such levels get defined. +Additional requirements on the self-hosted runners may be added to Build levels +greater than L3 when such levels get defined. [build level requirements]: requirements.md [GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners