From e7e964953b343d622407e6bab0023fa68b6ae1f8 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Mon, 10 Oct 2022 14:35:27 -0400 Subject: [PATCH 1/6] Implement style to format `
` as a table No visible changes. This just adds a new (as yet unused) class and defines a new color value (`$lightest-green`) to avoid copy/pasting the value. Signed-off-by: Mark Lodato --- docs/_sass/dl-as-table.scss | 55 ++++++++++++++++++++++++++++++++++ docs/_sass/minima.scss | 2 ++ docs/_sass/minima/_base.scss | 2 +- docs/_sass/minima/_custom.scss | 7 +++-- 4 files changed, 62 insertions(+), 4 deletions(-) create mode 100644 docs/_sass/dl-as-table.scss diff --git a/docs/_sass/dl-as-table.scss b/docs/_sass/dl-as-table.scss new file mode 100644 index 000000000..03a369177 --- /dev/null +++ b/docs/_sass/dl-as-table.scss @@ -0,0 +1,55 @@ +// Format definition lists as tables. This allows us to use Markdown instead of +// HTML, and also allows us to have a responsive design that works on mobile. +// +// TODO: Do not render as a table on mobile. + +dl.as-table { + + // Turn dl into a table + & { + display: grid; + grid-template-columns: max-content auto; + } + > dt { + grid-column-start: 1; + } + > dd { + grid-column-start: 2; + } + + // Remove extra whitespace from top and bottom of each box. + > dd > :first-child, + > dd > ul:first-child > li:first-child, + > dd > ul:first-child > li:first-child > p:first-child { + margin-top: 0; + } + > dd > :last-child, + > dd > ul:last-child > li:last-child, + > dd > ul:last-child > li:last-child > p:last-child { + margin-bottom: 0; + } + + // Format similar to the table from minima/_base.scss. + & { + border-top: 1px solid $grey-color-light; + border-left: 1px solid $grey-color-light; + border-collapse: collapse; + margin: 1rem 0 2.5rem 0; + line-height: 1.4; + } + > dd, > dt { + border-right: 1px solid $grey-color-light; + border-bottom: 1px solid $grey-color-light; + padding: $spacer-l ($spacer-xl / 2); + } + > dt { + text-align: left; + font-weight: 500; + color: $dark-green; + background-color: $lightest-green; + + // Vertically center the definition term + display: flex; + align-items: center; + } +} diff --git a/docs/_sass/minima.scss b/docs/_sass/minima.scss index bb1a9fc8d..bfb4c483e 100644 --- a/docs/_sass/minima.scss +++ b/docs/_sass/minima.scss @@ -21,6 +21,7 @@ $light-green: #58DA95; $green-darkest: #102B2D; $pastel-green: #ECF8F2; $button-green: #23907E; +$lightest-green: #F7FAF9; // font variables @@ -104,3 +105,4 @@ $on-laptop: 1180px !default; // Import partials. @import "minima/base", "minima/layout", "minima/syntax-highlighting", "minima/custom"; +@import "dl-as-table"; diff --git a/docs/_sass/minima/_base.scss b/docs/_sass/minima/_base.scss index 68ae470d4..8bc168df7 100644 --- a/docs/_sass/minima/_base.scss +++ b/docs/_sass/minima/_base.scss @@ -217,7 +217,7 @@ table { border: 1px solid $grey-color-light; tr { &:nth-child(even) { - background-color: #F7FAF9; + background-color: $lightest-green; } } th, diff --git a/docs/_sass/minima/_custom.scss b/docs/_sass/minima/_custom.scss index e46a97d35..33d436649 100644 --- a/docs/_sass/minima/_custom.scss +++ b/docs/_sass/minima/_custom.scss @@ -302,7 +302,7 @@ h5, .h5 { border: 1px solid #CECECE; border-radius: 20px; th { - background-color: #F7FAF9; + background-color: $lightest-green; } } blockquote { @@ -313,7 +313,7 @@ h5, .h5 { /* Green - Lightest */ border: none; - background: #F7FAF9; + background: $lightest-green; border-radius: $radius; margin-bottom: 30px; letter-spacing: normal; @@ -483,7 +483,8 @@ details { // This is a hack to fix paragraph spacing. Really the theme should be fixed. // See https://github.com/slsa-framework/slsa/issues/335. -.fix-paragraph-spacing { +.fix-paragraph-spacing, +dl.as-table { p, ul, ol { margin-bottom: 12px; &:last-child { From a917c17594e4524d7b2f85b78c57be0fee7adef2 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Mon, 10 Oct 2022 20:28:27 -0400 Subject: [PATCH 2/6] SLSA v1.0: replace limitations section (levels.md) Replace the outdated limitations section at the bottom of levels.md with a more useful paragraph at the top explaining that SLSA is intended to be a primitive in a broader determination of risk. Also link to the Terminology page at the top. Signed-off-by: Mark Lodato --- docs/spec/v1.0/levels.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/spec/v1.0/levels.md b/docs/spec/v1.0/levels.md index 810a7d36d..2d1b786ea 100644 --- a/docs/spec/v1.0/levels.md +++ b/docs/spec/v1.0/levels.md @@ -12,7 +12,8 @@ source. This page is an informative overview of the SLSA levels, describing their purpose and guarantees. For the normative requirements at each level, see -[Requirements](requirements.md). +[Requirements](requirements.md). For a background, see +[Terminology](terminology.md). ## What is SLSA? @@ -25,6 +26,16 @@ and actionable, and to protect against specific integrity attacks. SLSA 4 represents the ideal end state, and the lower levels represent milestones with corresponding integrity guarantees. +Importantly, SLSA is intended to be a primitive in a broader determination of a +software's risk. SLSA measures specific aspects of supply chain security, +particularly those that can be fully automated; other aspects, such as developer +trust and code quality, are out of scope. Furthermore, each link in the software +supply chain has its own, independent SLSA level ([FAQ](../faq.md)). The benefit +of this approach is to break up the large supply chain security problem into +tractable subproblems that can be prioritized based on risk and tackled in +parallel. But this does mean that SLSA alone is not sufficient to determine if +an artifact is "safe". + ## Summary of levels | Level | Description | Example | @@ -47,14 +58,3 @@ It can take years to achieve the ideal security state - intermediate milestones | 4 | **Requires two-person review of all changes and a hermetic, reproducible build process.** Two-person review is an industry best practice for catching mistakes and deterring bad behavior. Hermetic builds guarantee that the provenance’s list of dependencies is complete. Reproducible builds, though not strictly required, provide many auditability and reliability benefits. Overall, SLSA 4 gives the consumer a high degree of confidence that the software has not been tampered with. | The SLSA level is not transitive ([see our FAQs](../faq.md)). This makes each artifact’s SLSA rating independent from one another, allowing parallel progress and prioritization based on risk. The level describes the integrity protections of an artifact’s build process and top-level source, but nothing about the artifact’s dependencies. Dependencies have their own SLSA ratings, and it is possible for a SLSA 4 artifact to be built from SLSA 0 dependencies. - -## Limitations - -SLSA can help reduce supply chain threats in a software artifact, but there are limitations. - -- There are a significant number of dependencies in the supply chain for many artifacts. The full graph of dependencies could be intractably large. -- In practice, a team working on security will need to identify and focus on the important components in a supply chain. This can be performed manually, but the effort could be significant. -- An artifact’s SLSA level is not transitive ([see our FAQs](../faq.md)) and dependencies have their own SLSA ratings. This means that it is possible for a SLSA 4 artifact to be built from SLSA 0 dependencies. So, while the main artifact has strong security, risks may still exist elsewhere. The aggregate of these risks will help software consumers understand how and where to use the SLSA 4 artifact. -- While automation of these tasks will help, it isn’t practical for every software consumer to fully vet the entire graph of every artifact. To close this gap, auditors and accreditation bodies could verify and assert that something meets the SLSA requirements. This could be particularly valuable for closed source software. - -As part of our roadmap, we’ll explore how to identify important components, how to determine aggregate risk throughout a supply chain, and the role of accreditation. From 1d4bab5a1cb0d273ec1176d706b13c42b3b2fd17 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Mon, 10 Oct 2022 20:33:28 -0400 Subject: [PATCH 3/6] SLSA v1.0: rewrite, split build vs source, undef L4 (levels.md) This is a complete rewrite of the levels.md page as per the SLSA v1.0 Proposal: - Split into Build vs Source levels, now called "tracks". - Undefine Build L4 and the Source levels. - Better explain the summary, purpose, and requirements of each level. Otherwise, no changes to the meaning of each level. Also add placeholders for missing terminology and implementation guidelines in other pages that are linked from this new content. Signed-off-by: Mark Lodato --- docs/spec/v1.0/levels.md | 282 +++++++++++++++++++++++++++++---- docs/spec/v1.0/requirements.md | 14 ++ docs/spec/v1.0/terminology.md | 9 ++ 3 files changed, 277 insertions(+), 28 deletions(-) diff --git a/docs/spec/v1.0/levels.md b/docs/spec/v1.0/levels.md index 2d1b786ea..2fda00ec8 100644 --- a/docs/spec/v1.0/levels.md +++ b/docs/spec/v1.0/levels.md @@ -1,12 +1,10 @@ ---- -title: Security levels ---- +# Security levels +
-SLSA is organized into a series of levels that provide increasing -[integrity](terminology.md) guarantees. This gives you confidence that -software hasn’t been tampered with and can be securely traced back to its -source. +SLSA is organized into a series of levels that provide increasing supply chain +security guarantees. This gives you confidence that software hasn’t been +tampered with and can be securely traced back to its source.
@@ -21,10 +19,10 @@ SLSA is a set of incrementally adoptable security guidelines, established by industry consensus. The standards set by SLSA are guiding principles for both software producers and consumers: producers can follow the guidelines to make their software more secure, and consumers can make decisions based on a software -package's security posture. SLSA's four levels are designed to be incremental -and actionable, and to protect against specific integrity attacks. SLSA 4 -represents the ideal end state, and the lower levels represent milestones with -corresponding integrity guarantees. +package's security posture. SLSA's levels are designed to be incremental +and actionable, and to protect against specific classes of supply chain attacks. +The highest level in each track represents an ideal end state, and the lower +levels represent intermediate milestones with commensurate security guarantees. Importantly, SLSA is intended to be a primitive in a broader determination of a software's risk. SLSA measures specific aspects of supply chain security, @@ -36,25 +34,253 @@ tractable subproblems that can be prioritized based on risk and tackled in parallel. But this does mean that SLSA alone is not sufficient to determine if an artifact is "safe". -## Summary of levels +> **TODO:** SLSA is in the eye of the beholder: software consumers make their +> own SLSA determinations, though in practice they may delegate to some +> authority. + +## Levels and tracks + +SLSA levels are split into *tracks*. Each track has own set of levels that +measure a particular aspect of supply chain security. The purpose of tracks is +to recognize progress made in one aspect of security without blocking on an +unrelated aspect. Tracks also allow the SLSA spec to evolve: we can add more +tracks without invaliding previous levels. + +| Track/Level | Requirements | Benefits | +| ----------- | ------------ | -------- | +| [Build L0] | (none) | (n/a) | +| [Build L1] | Attestation showing how the package was built | Documentation, inventorying | +| [Build L2] | Signed attestation, generated by a hosted build service | Reduced attack surface, weak tamper protection | +| [Build L3] | Hardened build service | Strong tamper protection | +| [Build L4] | (not yet defined) | | +| [Source] | (not yet defined) | | + +> Note: The [previous version] of the specification used a single unnamed track, +> SLSA 1–4, roughly corresponding to the equivalently numbered Build + Source +> levels. + +## Build track + +The SLSA build track describes the level of protection against tampering +during or after the build, and the trustworthiness of provenance metadata. +Higher SLSA build levels provide increased confidence that a package truly came +from the correct sources, without unauthorized modification or influence. + +> **TODO:** Add a diagram visualizing the following. + +Summary of the build track: + +- Generate a **provenance attestation** automatically during each build. +- Build on **hardened services** that have been manually audited. + +Exactly how this is implemented is up to the packaging ecosystem (for open +source) or organization (for closed source), including: what provenance format +is accepted, whether reproducible builds are used, and how provenance is +distributed. Guidelines for implementers can be found in the +[requirements](requirements.md). + +
+ +### Build L0: No guarantees + +
+
Summary
+ +No requirements---L0 represents the lack of SLSA. + +
Intended for
+ +Software that does not need SLSA, such as: + +- Binaries built and executed on the same machine, including continuous + integration tests. +- Software that is never distributed to customers or used in environments with + sensitive access. + +
Requirements
+ +n/a + +
Benefits
+ +n/a + +
+
+
+ +### Build L1: Provenance + +
+
Summary
+ +Package has a provenance attestation showing how it was built, though without +tamper protection. + +
Intended for
+ +Projects and organizations wanting to easily and quickly gain some benefits of +SLSA other than tamper protection, while waiting to achieve higher levels. + +
Requirements
+ +- Up front, the package maintainer defines some sort of "build script" that + automates how the package is supposed to be built. + +- On each build, the release process automatically generates and distributes a + [provenance attestation] describing how the artifact was *actually* built, + including: who built the package (person or system), what process/command + was used, and what the input artifacts were. + +
Benefits
+ +For consumers: + +- Allows the consumer to known what the exact source code was for a given + artifact so that they can audit it or make decisions based on it. +- Makes it easier for consumers to build the software themselves, by knowing + what the official process and sources were. + +For large organizations and enterprises: + +- Aids in creating an inventory of first-party software and build systems + across many teams. +- Provides audit trail to narrow the scope of incident investigations. + +
Notes
+ +- Provenance may be incomplete and/or unsigned at L1. Higher levels require + more complete and trustworthy provenance. + +
+ +
+
+ +### Build L2: Build service + +
+
Summary
+ +Builds run on a hosted service that generates and signs the provenance, reducing +attack surface and offering some tamper protection. + +
Intended for
+ +Projects and organizations waiting for their build service to implement Build L3. + +
Requirements
+ +All of [Build L1], plus: + +- Builds run on a hosted build service that generates and signs the + provenance itself, outside the control of the users of the build service. + +
Benefits
+ +For package maintainers: + +- Prevents tampering of the artifact after the build. +- In some cases, reduces impact of compromised package upload credentials. + +For consumers: + +- Strongly identifies what build service was used. + +For large organizations and enterprises: + +- Allows large-scale migration of teams to supported build services early + while further hardening work ([Build L3]) is done in parallel. + +
+
+
+ +### Build L3: Hardened builds + +
+
Summary
+ +Builds run on a hardened build service that offers strong tamper protection. + +
Intended for
+ +Most software releases. + +
Requirements
+ +All of [Build L2], plus: + +- Build service implements strong controls to prevent runs from influencing + one another, even within the same project. + +> **TODO:** Add requirement about survey and audit as per the v1.0 proposal. + +
Benefits
+ +For package maintainers: + +- Prevents tampering of the artifact during or after the build. +- Reduces impact of compromised upload credentials. + +For consumers: + +- Greatly increases confidence that the package was built from the declared + source. + +For large organizations and enterprises: + +- Reduces risk that a compromised credential or rogue maintainer bypassed the + official change management system. + +
+
+
+ +### Build L4: (not yet defined) + +Build L4 is not yet defined. For reference, [previous version] of SLSA defined a +"SLSA 4" that included the following requirements, which *may or may not* be +part of a future Build L4: + +- Pinned dependencies, which guarantee that each build runs on exactly the + same set of inputs. +- Hermetic builds, which guarantee that no extraneous dependencies are used. +- All dependencies listed in the provenance, which enables downstream systems + to recursively apply SLSA to dependencies. +- Reproducible builds, which enable other systems to corroborate the + provenance. + +
+
+ +## Source track (not yet defined) + +The Source track is not yet defined but is expected to measure protection +against tampering of the source code. It will be defined in a future version of +the specification. -| Level | Description | Example | -| :---- | :-------------------------------------------- | :---------------------------------------------------- | -| 1 | Documentation of the build process | Unsigned provenance | -| 2 | Tamper resistance of the build service | Hosted source/build, signed provenance | -| 3 | Extra resistance to specific threats | Security controls on host, non-falsifiable provenance | -| 4 | Highest levels of confidence and trust | Two-party review + hermetic builds | +For reference, the [previous version] of SLSA included the following +requirements, which *may or may not* be part of a future Source track: -It can take years to achieve the ideal security state - intermediate milestones are important. SLSA guides you through gradually improving the security of your software. Artifacts used in critical infrastructure or vital business operations may want to attain a higher level of security, whereas software that poses a low risk can stop when they're comfortable. +- Strong authentication of author and reviewer identities to resist account + and credential compromise, such as 2-factor authentication using a hardware + security key. +- Retention of the source code to allow for after-the-fact inspection and + future rebuilds. +- Mandatory two-person review of all changes to the source to prevent a single + compromised actor or account from introducing malicious changes. -## Detailed explanation +
-| Level | Requirements | -| ----- | ------------ | -| 0 | **No guarantees.** SLSA 0 represents the lack of any SLSA level. | -| 1 | **The build process must be fully scripted/automated and generate provenance.** Provenance is metadata about how an artifact was built, including the build process, top-level source, and dependencies. Knowing the provenance allows software consumers to make risk-based security decisions. Provenance at SLSA 1 does not protect against tampering, but it offers a basic level of code source identification and can aid in vulnerability management. | -| 2 | **Requires using version control and a hosted build service that generates authenticated provenance.** These additional requirements give the software consumer greater confidence in the origin of the software. At this level, the provenance prevents tampering to the extent that the build service is trusted. SLSA 2 also provides an easy upgrade path to SLSA 3. | -| 3 | **The source and build platforms meet specific standards to guarantee the auditability of the source and the integrity of the provenance respectively.** We envision an accreditation process whereby auditors certify that platforms meet the requirements, which consumers can then rely on. SLSA 3 provides much stronger protections against tampering than earlier levels by preventing specific classes of threats, such as cross-build contamination. | -| 4 | **Requires two-person review of all changes and a hermetic, reproducible build process.** Two-person review is an industry best practice for catching mistakes and deterring bad behavior. Hermetic builds guarantee that the provenance’s list of dependencies is complete. Reproducible builds, though not strictly required, provide many auditability and reliability benefits. Overall, SLSA 4 gives the consumer a high degree of confidence that the software has not been tampered with. | + -The SLSA level is not transitive ([see our FAQs](../faq.md)). This makes each artifact’s SLSA rating independent from one another, allowing parallel progress and prioritization based on risk. The level describes the integrity protections of an artifact’s build process and top-level source, but nothing about the artifact’s dependencies. Dependencies have their own SLSA ratings, and it is possible for a SLSA 4 artifact to be built from SLSA 0 dependencies. +[build l0]: #build-l0 +[build l1]: #build-l1 +[build l2]: #build-l2 +[build l3]: #build-l3 +[build l4]: #build-l4 +[build]: #build-track +[previous version]: ../v0.1/levels.md +[provenance attestation]: terminology.md +[source]: #source-track diff --git a/docs/spec/v1.0/requirements.md b/docs/spec/v1.0/requirements.md index 7bf7c2e0f..df129582e 100644 --- a/docs/spec/v1.0/requirements.md +++ b/docs/spec/v1.0/requirements.md @@ -14,6 +14,20 @@ To better understand the reasoning behind the requirements, see > Reminder: SLSA is in `alpha`. The definitions below are not yet finalized and subject to change, particularly SLSA 3-4. +## TODO + +**TODO:** Update the requirements to provide guidelines for how to implement, +showing what the options are: + +- How to define expectations: explicit vs implicit +- What provenance format to use: recommend [SLSA Provenance](../../provenance) +- Whether provenance is generated during the initial build and/or + after-the-fact using reproducible builds +- How provenance is distributed +- When verification happens: during upload, during download, and/or continuous + monitoring +- What happens on failure: blocking, warning, and/or asynchronous notification + ## Summary table | Requirement | SLSA 1 | SLSA 2 | SLSA 3 | SLSA 4 | diff --git a/docs/spec/v1.0/terminology.md b/docs/spec/v1.0/terminology.md index ad3b5a02b..80121c534 100644 --- a/docs/spec/v1.0/terminology.md +++ b/docs/spec/v1.0/terminology.md @@ -8,6 +8,15 @@ of terminology and models to describe what we're protecting. +## TODO: Terms we still need to define + +> **TODO:** Define these terms before the v1.0 release. + +- Ecosystem +- Project +- Attestation +- Provenance + ## Software supply chain SLSA's framework addresses every step of the software supply chain - the From 112702912bba1213c479c25d94b4332c00fbda70 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Wed, 12 Oct 2022 16:15:28 -0400 Subject: [PATCH 4/6] SLSA v1.0: address feedback on levels.md - Add "Who is SLSA for?" section. - Simplify the benefits for each level. - Clarify what L0 is intended for. Signed-off-by: Mark Lodato --- docs/spec/v1.0/levels.md | 73 +++++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 35 deletions(-) diff --git a/docs/spec/v1.0/levels.md b/docs/spec/v1.0/levels.md index 2fda00ec8..230aedc66 100644 --- a/docs/spec/v1.0/levels.md +++ b/docs/spec/v1.0/levels.md @@ -38,6 +38,24 @@ an artifact is "safe". > own SLSA determinations, though in practice they may delegate to some > authority. +## Who is SLSA for? + +There are three main audiences for SLSA: + +- **Project maintainers,** who are often small teams that know their build + process and trust their teammates. Their primary goal is protection against + compromise with as low overhead as possible. They may also benefit from + easier maintenance and increased consumer confidence. + +- **Consumers,** who use a variety of software and do not know the maintainers + or their build processes. Their primary goal is confidence that the software + is authentic and has not been tampered with. They are concerned about rogue + maintainers, compromised credentials, and compromised infrastructure. + +- **Organizations,** who are both producers and consumers of software. In + addition to the goals above, organizations also want to broadly understand + and reduce risk across the organization. + ## Levels and tracks SLSA levels are split into *tracks*. Each track has own set of levels that @@ -90,12 +108,8 @@ No requirements---L0 represents the lack of SLSA.
Intended for
-Software that does not need SLSA, such as: - -- Binaries built and executed on the same machine, including continuous - integration tests. -- Software that is never distributed to customers or used in environments with - sensitive access. +Development or test builds of software that are built and run on the same +machine, such as unit tests.
Requirements
@@ -134,18 +148,12 @@ SLSA other than tamper protection, while waiting to achieve higher levels.
Benefits
-For consumers: - -- Allows the consumer to known what the exact source code was for a given - artifact so that they can audit it or make decisions based on it. -- Makes it easier for consumers to build the software themselves, by knowing - what the official process and sources were. +- Makes it easier for both maintainers and consumers to debug, patch, rebuild, + and/or analyze the software by knowing its precise source version and build + process. -For large organizations and enterprises: - -- Aids in creating an inventory of first-party software and build systems - across many teams. -- Provides audit trail to narrow the scope of incident investigations. +- Aids organizations in creating an inventory of software and build systems + used across a variety of teams.
Notes
@@ -178,16 +186,15 @@ All of [Build L1], plus:
Benefits
-For package maintainers: - -- Prevents tampering of the artifact after the build. -- In some cases, reduces impact of compromised package upload credentials. +All of [Build L1], plus: -For consumers: +- Prevents tampering after the build through digital signatures. -- Strongly identifies what build service was used. +- Moderately reduces the impact of compromised package upload credentials by + requiring attacker to also exploit the build process. -For large organizations and enterprises: +- Reduces attack surface by limiting builds to specific build services that + can be audited and hardened. - Allows large-scale migration of teams to supported build services early while further hardening work ([Build L3]) is done in parallel. @@ -218,20 +225,16 @@ All of [Build L2], plus:
Benefits
-For package maintainers: - -- Prevents tampering of the artifact during or after the build. -- Reduces impact of compromised upload credentials. - -For consumers: +All of [Build L2], plus: -- Greatly increases confidence that the package was built from the declared - source. +- Prevents tampering during the build---by maintainers, compromised + credentials, or other tenants. -For large organizations and enterprises: +- Greatly reduces the impact of compromised package upload credentials by + requiring attacker to perform a difficult exploit of the build process. -- Reduces risk that a compromised credential or rogue maintainer bypassed the - official change management system. +- Provides strong confidence that the package was built from the official + source and build process.
From f1d893bfbea18dc6627254a99adc01ea573120d1 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Wed, 12 Oct 2022 16:44:33 -0400 Subject: [PATCH 5/6] SLSA v1.0: better explain intention of each level Signed-off-by: Mark Lodato --- docs/spec/v1.0/levels.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/spec/v1.0/levels.md b/docs/spec/v1.0/levels.md index 230aedc66..3081fbdfa 100644 --- a/docs/spec/v1.0/levels.md +++ b/docs/spec/v1.0/levels.md @@ -128,13 +128,13 @@ n/a
Summary
-Package has a provenance attestation showing how it was built, though without -tamper protection. +Package has a provenance attestation showing how it was built, but the +provenance is trivial to forge.
Intended for
Projects and organizations wanting to easily and quickly gain some benefits of -SLSA other than tamper protection, while waiting to achieve higher levels. +SLSA---other than tamper protection---without changing their build workflows.
Requirements
@@ -171,11 +171,13 @@ SLSA other than tamper protection, while waiting to achieve higher levels.
Summary
Builds run on a hosted service that generates and signs the provenance, reducing -attack surface and offering some tamper protection. +attack surface and increasing the difficulty to forge the provenance.
Intended for
-Projects and organizations waiting for their build service to implement Build L3. +Projects and organizations wanting to gain moderate security benefits of SLSA by +switching to a hosted build service, while waiting changes to the build service +itself required by [Build L3].
Requirements
@@ -208,11 +210,13 @@ All of [Build L1], plus:
Summary
-Builds run on a hardened build service that offers strong tamper protection. +Builds run on a hardened build service that offers strong tamper protection. The +provenance is very difficult to exploit even for a determined adversary.
Intended for
-Most software releases. +Most software releases. Build L3 usually requires significant changes to +existing build services.
Requirements
From e09898bc5dd973db235c8ac36c378f639c6402b9 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Thu, 13 Oct 2022 17:01:41 -0400 Subject: [PATCH 6/6] SLSA v1.0: address more feedback on levels.md - Use consistent terminolgoy around "transitive" and link directly to the specific FAQ entry. - Add infrastructure providers to "Who is SLSA for?" - Fix typos and improve wording. - Add TODO about avoiding the term "signing". Signed-off-by: Mark Lodato --- docs/spec/v1.0/levels.md | 40 ++++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/spec/v1.0/levels.md b/docs/spec/v1.0/levels.md index 3081fbdfa..6c4c6e898 100644 --- a/docs/spec/v1.0/levels.md +++ b/docs/spec/v1.0/levels.md @@ -28,11 +28,12 @@ Importantly, SLSA is intended to be a primitive in a broader determination of a software's risk. SLSA measures specific aspects of supply chain security, particularly those that can be fully automated; other aspects, such as developer trust and code quality, are out of scope. Furthermore, each link in the software -supply chain has its own, independent SLSA level ([FAQ](../faq.md)). The benefit -of this approach is to break up the large supply chain security problem into -tractable subproblems that can be prioritized based on risk and tackled in -parallel. But this does mean that SLSA alone is not sufficient to determine if -an artifact is "safe". +supply chain has its own, independent SLSA level---in other words, it is not +transitive ([FAQ](../faq.md#q-why-is-slsa-not-transitive)). The benefit of this +approach is to break up the large supply chain security problem into tractable +subproblems that can be prioritized based on risk and tackled in parallel. But +this does mean that SLSA alone is not sufficient to determine if an artifact is +"safe". > **TODO:** SLSA is in the eye of the beholder: software consumers make their > own SLSA determinations, though in practice they may delegate to some @@ -40,7 +41,7 @@ an artifact is "safe". ## Who is SLSA for? -There are three main audiences for SLSA: +SLSA is intended to serve multiple populations: - **Project maintainers,** who are often small teams that know their build process and trust their teammates. Their primary goal is protection against @@ -56,13 +57,18 @@ There are three main audiences for SLSA: addition to the goals above, organizations also want to broadly understand and reduce risk across the organization. +- **Infrastructure providers,** such as build services and packaging + ecosystems, who are critical to achieving SLSA. While not the primary + beneficiary of SLSA, they may benefit from increased security and user + trust. + ## Levels and tracks SLSA levels are split into *tracks*. Each track has own set of levels that measure a particular aspect of supply chain security. The purpose of tracks is to recognize progress made in one aspect of security without blocking on an unrelated aspect. Tracks also allow the SLSA spec to evolve: we can add more -tracks without invaliding previous levels. +tracks without invalidating previous levels. | Track/Level | Requirements | Benefits | | ----------- | ------------ | -------- | @@ -71,7 +77,7 @@ tracks without invaliding previous levels. | [Build L2] | Signed attestation, generated by a hosted build service | Reduced attack surface, weak tamper protection | | [Build L3] | Hardened build service | Strong tamper protection | | [Build L4] | (not yet defined) | | -| [Source] | (not yet defined) | | +| [Source L…] | (not yet defined) | | > Note: The [previous version] of the specification used a single unnamed track, > SLSA 1–4, roughly corresponding to the equivalently numbered Build + Source @@ -176,8 +182,8 @@ attack surface and increasing the difficulty to forge the provenance.
Intended for
Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build service, while waiting changes to the build service -itself required by [Build L3]. +switching to a hosted build service, while waiting for changes to the build +service itself required by [Build L3].
Requirements
@@ -205,6 +211,8 @@ All of [Build L1], plus:
+> **TODO:** If possible, avoid being overly specific about "signing". + ### Build L3: Hardened builds
@@ -247,7 +255,7 @@ All of [Build L2], plus: ### Build L4: (not yet defined) Build L4 is not yet defined. For reference, [previous version] of SLSA defined a -"SLSA 4" that included the following requirements, which *may or may not* be +"SLSA 4" that included the following requirements, which **may or may not** be part of a future Build L4: - Pinned dependencies, which guarantee that each build runs on exactly the @@ -268,11 +276,11 @@ against tampering of the source code. It will be defined in a future version of the specification. For reference, the [previous version] of SLSA included the following -requirements, which *may or may not* be part of a future Source track: +requirements, which **may or may not** be part of a future Source track: -- Strong authentication of author and reviewer identities to resist account - and credential compromise, such as 2-factor authentication using a hardware - security key. +- Strong authentication of author and reviewer identities, such as 2-factor + authentication using a hardware security key, to resist account and + credential compromise. - Retention of the source code to allow for after-the-fact inspection and future rebuilds. - Mandatory two-person review of all changes to the source to prevent a single @@ -290,4 +298,4 @@ requirements, which *may or may not* be part of a future Source track: [build]: #build-track [previous version]: ../v0.1/levels.md [provenance attestation]: terminology.md -[source]: #source-track +[source l…]: #source-track