diff --git a/docs/_data/nav/main.yml b/docs/_data/nav/main.yml
index f67c7dde4..361b44988 100644
--- a/docs/_data/nav/main.yml
+++ b/docs/_data/nav/main.yml
@@ -8,9 +8,9 @@
url: /current-activities
description: What the SLSA community is currently working on
-- title: SLSA Specification 1.1 Draft
+- title: SLSA 1.1 Draft
description: >
- These pages describe SLSA's security levels and requirements for each track.
+ This section describes SLSA's security levels and requirements for each track.
If you want to achieve SLSA a particular level, these are the requirements
you'll need to meet.
url: /spec/v1.1/
@@ -18,7 +18,7 @@
- title: Understanding SLSA
description: >
- These pages provide an overview of SLSA, how it helps protect against common
+ This section provides an overview of SLSA, how it helps protect against common
supply chain attacks, and common use cases. If you're new to SLSA or
supply chain security, start here.
children:
@@ -53,7 +53,7 @@
- title: Core specification
description: >
- These pages describe SLSA's security levels and requirements for each track.
+ This section describes SLSA's security levels and requirements for each track.
If you want to achieve SLSA a particular level, these are the requirements
you'll need to meet.
children:
@@ -88,7 +88,7 @@
- title: Attestation formats
description: >
- These pages include the concrete schemas for SLSA attestations. The
+ This section includes the concrete schemas for SLSA attestations. The
Provenance and VSA formats are recommended, but not required by the
specification.
children:
@@ -109,9 +109,9 @@
url: /spec/v1.1/onepage
skip_next_prev: true # don't show as a next/prev link
-- title: SLSA Specification 1.0
+- title: SLSA 1.0
description: >
- These pages describe SLSA's security levels and requirements for each track.
+ This section describes SLSA's security levels and requirements for each track.
If you want to achieve SLSA a particular level, these are the requirements
you'll need to meet.
url: /spec/v1.0/
@@ -119,7 +119,7 @@
- title: Understanding SLSA
description: >
- These pages provide an overview of SLSA, how it helps protect against common
+ This section provides an overview of SLSA, how it helps protect against common
supply chain attacks, and common use cases. If you're new to SLSA or
supply chain security, start here.
children:
@@ -154,7 +154,7 @@
- title: Core specification
description: >
- These pages describe SLSA's security levels and requirements for each track.
+ This section describes SLSA's security levels and requirements for each track.
If you want to achieve SLSA a particular level, these are the requirements
you'll need to meet.
children:
@@ -189,7 +189,7 @@
- title: Attestation formats
description: >
- These pages include the concrete schemas for SLSA attestations. The
+ This section includes the concrete schemas for SLSA attestations. The
Provenance and VSA formats are recommended, but not required by the
specification.
children:
@@ -210,13 +210,13 @@
url: /spec/v1.0/onepage
skip_next_prev: true # don't show as a next/prev link
-- title: SLSA Working Draft
+- title: SLSA Draft
url: /spec/draft/
children:
- title: Understanding SLSA
description: >
- These pages provide an overview of SLSA, how it helps protect against common
+ This section provides an overview of SLSA, how it helps protect against common
supply chain attacks, and common use cases. If you're new to SLSA or
supply chain security, start here.
children:
@@ -251,8 +251,8 @@
- title: Core specification
description: >
- These pages describe SLSA's security levels and requirements for each track.
- If you want to achieve SLSA a particular level, these are the requirements
+ This section describes SLSA's security levels and requirements for each track.
+ If you want to achieve a particular SLSA level, these are the requirements
you'll need to meet.
children:
@@ -260,41 +260,16 @@
url: /spec/draft/terminology
description: Terminology and model used by SLSA
- - title: Security levels
+ - title: Security levels and tracks
url: /spec/draft/levels
description: Overview of SLSA's tracks and levels, intended for all audiences
-
- - title: Producing artifacts
- url: /spec/draft/requirements
- description: Detailed technical requirements for producing software artifacts, intended for platform implementers
-
- - title: Distributing provenance
- url: /spec/draft/distributing-provenance
- description: Detailed technical requirements for distributing provenance, intended for platform implementers and software distributors
-
- - title: Verifying artifacts
- url: /spec/draft/verifying-artifacts
- description: Guidance for verifying software artifacts and their SLSA provenance, intended for platform implementers and software consumers
-
- - title: Verifying build platforms
- url: /spec/draft/verifying-systems
- description: Guidelines for securing SLSA Build L3+ builders, intended for platform implementers
-
- - title: Integrity levels for attested build environments
- url: /spec/draft/attested-build-env-levels
- description: Overview of SLSA's Attested Build Environment track, intended for all audiences
-
- title: Threats & mitigations
url: /spec/draft/threats
description: Detailed information about specific supply chain attacks and how SLSA helps
- - title: Securing Source Code
- url: /spec/draft/source-requirements
- description: Overview of the Source track
-
- title: Attestation formats
description: >
- These pages include the concrete schemas for SLSA attestations. The
+ This section includes the concrete schemas for SLSA attestations. The
Provenance and VSA formats are recommended, but not required by the
specification.
children:
@@ -315,6 +290,48 @@
url: /spec/draft/onepage
skip_next_prev: true # don't show as a next/prev link
+- title: Build Track 1.0
+ url: /build/v1.0/
+ children:
+
+ - title: Terminology
+ url: /build/v1.0/terminology
+ description: Terminology and model used by SLSA
+
+ - title: Security levels
+ url: /build/v1.0/levels
+ description: Overview of SLSA Build track levels, intended for all audiences
+ - title: Producing artifacts
+ url: /build/v1.0/requirements
+ description: Detailed technical requirements for producing software artifacts, intended for platform implementers
+
+ - title: Distributing provenance
+ url: /build/v1.0/distributing-provenance
+ description: Detailed technical requirements for distributing provenance, intended for platform implementers and software distributors
+
+ - title: Verifying artifacts
+ url: /build/v1.0/verifying-artifacts
+ description: Guidance for verifying software artifacts and their SLSA provenance, intended for platform implementers and software consumers
+
+ - title: Verifying build platforms
+ url: /build/v1.0/verifying-systems
+ description: Guidelines for securing SLSA Build L3+ builders, intended for platform implementers
+
+- title: Source Track Draft
+ url: /source/draft/
+ children:
+
+ - title: Securing Source Code
+ url: /source/draft/source-requirements
+ description: Source track requirements
+
+ - title: Verifying source
+ url: /source/draft/verifying-source
+ description: Guidance for verifying properties of source revisions using SLSA source provenance attestations
+
+- title: Build Env. Track Draft
+ url: /build-env/draft/
+
- title: How to SLSA
description: >
These instructions tell you how to apply the core SLSA specification to use
diff --git a/docs/_redirects b/docs/_redirects
index ee192b337..e7ca209ae 100644
--- a/docs/_redirects
+++ b/docs/_redirects
@@ -55,9 +55,11 @@
/provenance/v1.1 /spec/v1.1/provenance 301
/provenance/draft /spec/draft/provenance 301
-/spec /spec/v1.0 302
-/spec/faq /spec/v1.0/faq 302
-/spec/v1/* /spec/v1.0/:splat 302
+/spec /spec/v1.0 302
+/spec/faq /spec/v1.0/faq 302
+/spec/v1/* /spec/v1.0/:splat 302
+/spec/current-activities /current-activities 301 # permanent
+/spec/v1.1/current-activities /current-activities 301 # permanent
# Note: Versions prior to v1.0 stay in /verification_summary.
/verification_summary /spec/v1.0/verification_summary 302 # floating
diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/build-env/draft/index.md
similarity index 86%
rename from docs/spec/draft/attested-build-env-levels.md
rename to docs/build-env/draft/index.md
index 36c898974..d432a1f26 100644
--- a/docs/spec/draft/attested-build-env-levels.md
+++ b/docs/build-env/draft/index.md
@@ -1,8 +1,17 @@
---
-title: Build Environment track
-description: This page gives an overview of the SLSA Build Environment track and its levels, describing their security objectives and general requirements.
+title: Build Environment Track
+description: The SLSA Build Environment track specification.
+layout: specifications
---
+{{ page.description }}
+
+SLSA is organized into a series of levels and tracks that provide increasing
+supply chain security guarantees on various aspects of the supply chain
+security. This specification defines the different security levels of the *SLSA
+Build Environment track*. For a general overview see the different [tracks and
+levels].
+
## Rationale
Today's hosted [build platforms] play a central role in an artifact's supply
@@ -36,14 +45,14 @@ environment, and the compute platform they used.
| [BuildEnv L2] | Attested build environment instantiation | Tampering via the build platform's control plane | The compute platform's host interface
| [BuildEnv L3] | Hardware-attested build environment | Tampering via the compute platform's host interface | The compute platform's hardware
-> :warning:
-> The Build Environment track L1+ currently requires a [hosted] build platform.
-> A future version of this track may generalize requirements to cover bare-metal
-> build environments.
+**Warning**:
+The Build Environment track L1+ currently requires a [hosted] build platform.
+A future version of this track may generalize requirements to cover bare-metal
+build environments.
-> :grey_exclamation:
-> We may consider the addition of an L4 to the Build Environment track, which
-> covers hardware-attested runtime integrity checking during a build.
+**Note**:
+We may consider the addition of an L4 to the Build Environment track, which
+covers hardware-attested runtime integrity checking during a build.
### Build environment threats
@@ -285,9 +294,10 @@ TODO
-[Build L1]: levels.md#build-l1
-[Build L2]: levels.md#build-l2
-[Build L3]: levels.md#build-l3
+[tracks and levels]: ../../spec/draft/levels
+[Build L1]: ../../build/v1.0/levels#build-l1
+[Build L2]: ../../build/v1.0/levels#build-l2
+[Build L3]: ../../build/v1.0/levels#build-l3
[BuildEnv L0]: #buildenv-l0
[BuildEnv L1]: #buildenv-l1
[BuildEnv L2]: #buildenv-l2
@@ -295,22 +305,22 @@ TODO
[Release Attestation]: https://github.com/in-toto/attestation/blob/main/spec/predicates/release.md
[SCAI]: https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md
[Secure Boot]: https://wiki.debian.org/SecureBoot#What_is_UEFI_Secure_Boot.3F
-[SLSA Build Provenance]: provenance.md
+[SLSA Build Provenance]: ../../spec/draft/provenance.md
[TPM]: https://trustedcomputinggroup.org/resource/tpm-library-specification/
-[VSA]: verification_summary.md
-[build image]: terminology.md#build-image
+[VSA]: ../../spec/draft/verification_summary.md
+[build image]: ../../build/v1.0/terminology#build-image
[confidential computing]: https://confidentialcomputing.io/wp-content/uploads/sites/10/2023/03/Common-Terminology-for-Confidential-Computing.pdf
-[execution context]: terminology.md#build-environment
-[hosted]: requirements.md#isolation-strength
-[boot process]: terminology.md#boot-process
-[build agent]: terminology.md#build-agent
-[build image producer]: terminology.md#build-image-producer
-[build platforms]: terminology.md#platform
-[compute platform]: terminology.md#compute-platform
-[host interface]: terminology.md#host-interface
-[measurement]: terminology.md#measurement
-[provenance]: terminology.md#provenance
-[quote]: terminology.md#quote
-[reference values]: terminology.md#reference-value
+[execution context]: ../../build/v1.0/terminology#build-environment
+[hosted]: ../../build/v1.0/requirements#isolation-strength
+[boot process]: ../../build/v1.0/terminology#boot-process
+[build agent]: ../../build/v1.0/terminology#build-agent
+[build image producer]: ../../build/v1.0/terminology#build-image-producer
+[build platforms]: ../../build/v1.0/terminology#platform
+[compute platform]: ../../build/v1.0/terminology#compute-platform
+[host interface]: ../../build/v1.0/terminology#host-interface
+[measurement]: ../../build/v1.0/terminology#measurement
+[provenance]: ../../build/v1.0/terminology#provenance
+[quote]: ../../build/v1.0/terminology#quote
+[reference values]: ../../build/v1.0/terminology#reference-value
[several classes]: #build-environment-threats
[vTPM]: https://trustedcomputinggroup.org/about/what-is-a-virtual-trusted-platform-module-vtpm/
diff --git a/docs/spec/draft/distributing-provenance.md b/docs/build/v1.0/distributing-provenance.md
similarity index 99%
rename from docs/spec/draft/distributing-provenance.md
rename to docs/build/v1.0/distributing-provenance.md
index 11f01f4a2..2ab0cadf2 100644
--- a/docs/spec/draft/distributing-provenance.md
+++ b/docs/build/v1.0/distributing-provenance.md
@@ -1,6 +1,7 @@
---
title: Distributing provenance
description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is platform implementers and software distributors.
+layout: specifications
---
In order to make provenance for artifacts available after generation
diff --git a/docs/spec/draft/images/build-env-model.svg b/docs/build/v1.0/images/build-env-model.svg
similarity index 100%
rename from docs/spec/draft/images/build-env-model.svg
rename to docs/build/v1.0/images/build-env-model.svg
diff --git a/docs/spec/draft/images/build-model.svg b/docs/build/v1.0/images/build-model.svg
similarity index 100%
rename from docs/spec/draft/images/build-model.svg
rename to docs/build/v1.0/images/build-model.svg
diff --git a/docs/spec/draft/images/supply-chain-threats-build-verification.svg b/docs/build/v1.0/images/supply-chain-threats-build-verification.svg
similarity index 100%
rename from docs/spec/draft/images/supply-chain-threats-build-verification.svg
rename to docs/build/v1.0/images/supply-chain-threats-build-verification.svg
diff --git a/docs/spec/draft/images/verification-model.svg b/docs/build/v1.0/images/verification-model.svg
similarity index 100%
rename from docs/spec/draft/images/verification-model.svg
rename to docs/build/v1.0/images/verification-model.svg
diff --git a/docs/build/v1.0/index.md b/docs/build/v1.0/index.md
new file mode 100644
index 000000000..df5f2613f
--- /dev/null
+++ b/docs/build/v1.0/index.md
@@ -0,0 +1,33 @@
+---
+title: Build Track
+description: The SLSA Build track specification version 1.0.
+layout: specifications
+---
+
+{{ page.description }}
+
+SLSA is organized into a series of levels and tracks that provide increasing
+supply chain security guarantees on various aspects of the supply chain
+security. This specification defines the different security levels of the *SLSA
+Build track*. For a general overview see the different [tracks and levels].
+
+{%- for section in site.data.nav.main %}
+{%- if section.url == page.url and section.children %}
+
+{{ section.description }}
+
+
+
+| Page | Description
+| ---- | -----------
+{%- for child in section.children %}
+| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}}
+{%- endfor %}
+
+
+{%- endif %}
+{%- endfor %}
+
+
+
+[tracks and levels]: ../../spec/draft/levels
diff --git a/docs/build/v1.0/levels.md b/docs/build/v1.0/levels.md
new file mode 100644
index 000000000..ec22f69ef
--- /dev/null
+++ b/docs/build/v1.0/levels.md
@@ -0,0 +1,235 @@
+---
+title: Security levels
+description: This page is a descriptive overview of the SLSA levels of the Build track, describing their intent.
+layout: specifications
+---
+
+This page is a descriptive overview of the SLSA levels of the Build track, describing
+their intent. For the prescriptive requirements for each level, see
+[Requirements](requirements.md).
+
+## Build track
+
+The SLSA build track describes increasing levels of trustworthiness and
+completeness in a package artifact's provenance. Provenance describes
+what entity built the artifact, what process they used, and what the inputs
+were. The lowest level only requires the provenance to exist, while higher
+levels provide increasing protection against tampering of the build, the
+provenance, or the artifact.
+
+The primary purpose of the build track is to enable [verification] that the
+artifact was built as expected. Consumers have some way of knowing what the
+expected provenance should look like for a given package and then compare each
+package artifact's actual provenance to those expectations. Doing so prevents
+several classes of [supply chain threats].
+
+Each ecosystem (for open source) or organization (for closed source) defines
+exactly how this is implemented, including: means of defining expectations, what
+provenance format is accepted, whether reproducible builds are used, how
+provenance is distributed, when verification happens, and what happens on
+failure. Guidelines for implementers can be found in the
+[requirements](requirements.md).
+
+## Build track levels
+
+| Track/Level | Requirements | Focus
+| ----------- | ------------ | -----
+| [Build L0] | (none) | (n/a)
+| [Build L1] | Provenance showing how the package was built | Mistakes, documentation
+| [Build L2] | Signed provenance, generated by a hosted build platform | Tampering after the build
+| [Build L3] | Hardened build platform | Tampering during the build
+
+
+
+> Note: The [previous version] of the specification used a single unnamed track,
+> SLSA 1–4. For version 1.0 the Source aspects were removed to focus on the
+> Build track. A Source track may be added in [future versions].
+
+
+
+### Build L0: No guarantees
+
+
+- Summary
-
+
+No requirements---L0 represents the lack of SLSA.
+
+
- Intended for
-
+
+Development or test builds of software that are built and run on the same
+machine, such as unit tests.
+
+
- Requirements
-
+
+n/a
+
+
- Benefits
-
+
+n/a
+
+
+
+
+
+### Build L1: Provenance exists
+
+
+- Summary
-
+
+Package has provenance showing how it was built. Can be used to prevent mistakes
+but is trivial to bypass or forge.
+
+
- Intended for
-
+
+Projects and organizations wanting to easily and quickly gain some benefits of
+SLSA---other than tamper protection---without changing their build workflows.
+
+
- Requirements
-
+
+- Software Producer:
+ - Follow a consistent build process so that others can form
+ expectations about what a "correct" build looks like.
+ - Run builds on a build platform that meets Build L1 requirements.
+ - Distribute provenance to consumers, preferably using a convention
+ determined by the package ecosystem.
+- Build platform:
+ - Automatically generate [provenance] describing how the artifact was
+ built, including: what entity built the package, what build process
+ they used, and what the top-level input to the build were.
+
+
- Benefits
-
+
+- Makes it easier for both producers and consumers to debug, patch, rebuild,
+ and/or analyze the software by knowing its precise source version and build
+ process.
+
+- With [verification], prevents mistakes during the release process, such as
+ building from a commit that is not present in the upstream repo.
+
+- Aids organizations in creating an inventory of software and build platforms
+ used across a variety of teams.
+
+
- Notes
-
+
+- Provenance may be incomplete and/or unsigned at L1. Higher levels require
+ more complete and trustworthy provenance.
+
+
+
+
+
+
+### Build L2: Hosted build platform
+
+
+- Summary
-
+
+Forging the provenance or evading verification requires an explicit "attack",
+though this may be easy to perform. Deters unsophisticated adversaries or those
+who face legal or financial risk.
+
+In practice, this means that builds run on a hosted platform that generates and
+signs[^sign] the provenance.
+
+
- Intended for
-
+
+Projects and organizations wanting to gain moderate security benefits of SLSA by
+switching to a hosted build platform, while waiting for changes to the build
+platform itself required by [Build L3].
+
+
- Requirements
-
+
+All of [Build L1], plus:
+
+- Software producer:
+ - Run builds on a [hosted] build platform that meets Build L2
+ requirements.
+- Build platform:
+ - Generate and sign[^sign] the provenance itself. This may be done
+ during the original build, an after-the-fact reproducible build, or
+ some equivalent system that ensures the trustworthiness of the
+ provenance.
+- Consumer:
+ - Validate the authenticity of the provenance.
+
+
- Benefits
-
+
+All of [Build L1], plus:
+
+- Prevents tampering after the build through digital signatures[^sign].
+
+- Deters adversaries who face legal or financial risk by evading security
+ controls, such as employees who face risk of getting fired.
+
+- Reduces attack surface by limiting builds to specific build platforms that
+ can be audited and hardened.
+
+- Allows large-scale migration of teams to supported build platforms early
+ while further hardening work ([Build L3]) is done in parallel.
+
+
+
+
+
+[^sign]: Alternate means of verifying the authenticity of the provenance are
+ also acceptable.
+
+### Build L3: Hardened builds
+
+
+- Summary
-
+
+Forging the provenance or evading verification requires exploiting a
+vulnerability that is beyond the capabilities of most adversaries.
+
+In practice, this means that builds run on a hardened build platform that offers
+strong tamper protection.
+
+
- Intended for
-
+
+Most software releases. Build L3 usually requires significant changes to
+existing build platforms.
+
+
- Requirements
-
+
+All of [Build L2], plus:
+
+- Software producer:
+ - Run builds on a hosted build platform that meets Build L3
+ requirements.
+- Build platform:
+ - Implement strong controls to:
+ - prevent runs from influencing one another, even within the same
+ project.
+ - prevent secret material used to sign the provenance from being
+ accessible to the user-defined build steps.
+
+
- Benefits
-
+
+All of [Build L2], plus:
+
+- Prevents tampering during the build---by insider threats, compromised
+ credentials, or other tenants.
+
+- Greatly reduces the impact of compromised package upload credentials by
+ requiring attacker to perform a difficult exploit of the build process.
+
+- Provides strong confidence that the package was built from the official
+ source and build process.
+
+
+
+
+
+
+[build l0]: #build-l0
+[build l1]: #build-l1
+[build l2]: #build-l2
+[build l3]: #build-l3
+[future versions]: /spec/v1.0/future-directions
+[hosted]: requirements.md#isolation-strength
+[previous version]: /spec/v0.1/levels
+[provenance]: /spec/v1.0/terminology
+[verification]: verifying-artifacts.md
+[suppy chain threats]: /spec/v1.0/threats
diff --git a/docs/spec/draft/requirements.md b/docs/build/v1.0/requirements.md
similarity index 93%
rename from docs/spec/draft/requirements.md
rename to docs/build/v1.0/requirements.md
index 63f0e6b2b..688f8210d 100644
--- a/docs/spec/draft/requirements.md
+++ b/docs/build/v1.0/requirements.md
@@ -1,6 +1,7 @@
---
title: Producing artifacts
description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers.
+layout: specifications
---
@@ -9,9 +10,9 @@ each SLSA level. The intended audience is platform implementers and security
engineers.
For an informative description of the levels intended for all audiences, see
-[Levels](levels.md). For background, see [Terminology](terminology.md). To
+[Security Levels](levels.md). For background, see [Terminology](terminology.md). To
better understand the reasoning behind the requirements, see
-[Threats and mitigations](threats.md).
+[Threats and mitigations].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
@@ -85,10 +86,10 @@ software. It might be an open-source project, a company, a team within a
company, or even an individual.
NOTE: There were more requirements for producers in the initial
-[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted
+[draft version (v0.1)](../v0.1/requirements#scripted-build) which impacted
how a package can be built. These were removed in the v1.0 specification and
will be reassessed and re-added as indicated in the
-[future directions](future-directions.md).
+[future directions].
### Choose an appropriate build platform
@@ -130,7 +131,7 @@ build platform is often a hosted, multi-tenant build service, but it could be a
system of multiple independent rebuilders, a special-purpose build platform used
by a single software project, or even an individual's workstation. Ideally, one
build platform is used by many different software packages so that consumers can
-[minimize the number of trusted platforms](principles.md). For more background,
+[minimize the number of trusted platforms]. For more background,
see [Build Model](terminology.md#build-model).
The build platform is responsible for providing two things: [provenance
@@ -179,7 +180,7 @@ Provenance.
- *Authenticity:* No requirements.
- *Accuracy:* No requirements.
-[SLSA Provenance]: provenance.md
+[SLSA Provenance]: ../../spec/v1.0/provenance.md
[associated suite]: ../../attestation-model#recommended-suite
✓ | ✓ | ✓
@@ -220,8 +221,7 @@ build platform (i.e. outside the trust boundary), except as noted below.
- Exceptions for fields that MAY be generated by a tenant of the build platform:
- The names and cryptographic digests of the output artifacts, i.e.
`subject` in [SLSA Provenance]. See [forge output digest of the
- provenance](threats#forged-digest) for explanation of why this is
- acceptable.
+ provenance] for explanation of why this is acceptable.
- Any field that is not marked as REQUIRED for Build L2. For example,
`resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at
Build L2. Builders SHOULD document any such cases of tenant-generated
@@ -256,7 +256,7 @@ build platform (i.e. outside the trust boundary), except as noted below.
- Completeness of resolved dependencies is best effort.
Note: This requirement was called "non-falsifiable" in the initial
-[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable).
+[draft version (v0.1)](../../spec/v0.1/requirements#non-falsifiable).
| | | ✓
@@ -323,16 +323,21 @@ out to a remote execution service or a "self-hosted runner" that is outside the
trust boundary of the build platform.
NOTE: This requirement was split into "Isolated" and "Ephemeral Environment"
-in the initial [draft version (v0.1)](../v0.1/requirements.md).
+in the initial [draft version (v0.1)].
NOTE: This requirement is not to be confused with "Hermetic", which roughly
means that the build ran with no network access. Such a requirement requires
substantial changes to both the build platform and each individual build, and is
-considered in the [future directions](future-directions.md).
+considered in the [future directions].
| | | ✓
-[external parameters]: provenance.md#externalParameters
-[identified in the provenance]: provenance.md#model
+[external parameters]: ../../spec/v1.0/provenance.md#externalParameters
+[identified in the provenance]: ../../spec/v1.0/provenance.md#model
[package ecosystem]: verifying-artifacts.md#package-ecosystem
+[draft version (v0.1)]: ../../spec/v0.1/requirements.md
+[future directions]: ../../spec/v1.0/future-directions.md
+[Threats and mitigations]: ../../spec/v1.0/threats.md
+[forge output digest of the provenance]: ../../spec/v1.0/threats#forged-digest
+[minimize the number of trusted platforms]: ../../spec/v1.0/principles.md
diff --git a/docs/build/v1.0/terminology.md b/docs/build/v1.0/terminology.md
new file mode 100644
index 000000000..5921f9500
--- /dev/null
+++ b/docs/build/v1.0/terminology.md
@@ -0,0 +1,186 @@
+---
+title: Terminology
+description: Before diving into the SLSA Build track specification, we need to establish a core set of terminology and models to describe what we're protecting.
+layout: specifications
+---
+
+
+Before diving into the [Build track levels](levels.md), we need to establish a
+core set of terminology and models to describe what we're protecting. This
+extends the [general terminology].
+
+## Software supply chain
+
+### Build model
+
+ 
+
+We model a build as running on a multi-tenant *build platform*, where each
+execution is independent.
+
+1. A tenant invokes the build by specifying *external parameters* through an
+ *interface*, either directly or via some trigger. Usually, at least one of
+ these external parameters is a reference to a *dependency*. (External
+ parameters are literal values while dependencies are artifacts.)
+2. The build platform's *control plane* interprets these external parameters,
+ fetches an initial set of dependencies, initializes a *build environment*,
+ and then starts the execution within that environment.
+3. The build then performs arbitrary steps, which might include fetching
+ additional dependencies, and then produces one or more *output* artifacts.
+ The steps within the build environment are under the tenant's control.
+ The build platform isolates build environments from one another to some
+ degree (which is measured by the SLSA Build Level).
+4. Finally, for SLSA Build L2+, the control plane outputs *provenance*
+ describing this whole process.
+
+Notably, there is no formal notion of "source" in the build model, just external
+parameters and dependencies. Most build platforms have an explicit "source"
+artifact to build from, which is often a git repository; in the build model, the
+reference to this artifact is an external parameter while the artifact itself is
+a dependency.
+
+For examples of how this model applies to real-world build platforms, see [index
+of build types](/provenance/v1#index-of-build-types).
+
+| Primary Term | Description
+| --- | ---
+| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations.
+| Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane.
+| Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters.
+| Control plane | Build platform component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control.
+| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform.
+| Steps | The set of actions that comprise a build, defined by the tenant.
+| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps.
+| Build caches | An intermediate artifact storage managed by the platform that maps intermediate artifacts to their explicit inputs. A build may share build caches with any subsequent build running on the platform.
+| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build.
+| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools.
+| Outputs | Collection of artifacts produced by the build.
+| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters.
+
+Ambiguous terms to avoid
+
+- *Build recipe:* Could mean *external parameters,* but may include concrete
+ steps of how to perform a build. To avoid implementation details, we don't
+ define this term, but always use "external parameters" which is the
+ interface to a build platform. Similar terms are *build configuration
+ source* and *build definition*.
+- *Builder:* Usually means *build platform*, but might be used for *build
+ environment*, the user who invoked the build, or a build tool from
+ *dependencies*. To avoid confusion, we always use "build platform". The only
+ exception is in the [provenance](/provenance/v1), where `builder` is used as
+ a more concise field name.
+
+
+
+The Build Environment (BuildEnv) track expands upon the
+[build model](#build-model) by explicitily separating the
+[build image](#build-image) and [compute platform](#compute-platform) from the
+abstract [build environment](#build-environment) and [build platform](#platform).
+Specifically, the BuildEnv track defines the following roles, components, and concepts:
+
+| Primary Term | Description
+| --- | ---
+| Build ID | An immutable identifier assigned uniquely to a specific execution of a tenant's build. In practice, the build ID may be an identifier, such as a UUID, associated with the build execution.
+| Build image | The template for a build environment, such as a VM or container image. Individual components of a build image include the root filesystem, pre-installed guest OS and packages, the build executor, and the build agent.
+| Build image producer | The party that creates and distributes build images. In practice, the build image producer may be the hosted build platform or a third party in a bring-your-own (BYO) build image setting.
+| Build agent | A build platform-provided program that interfaces with the build platform's control plane from within a running build environment. The build agent is also responsible for executing the tenant’s build definition, i.e., running the build. In practice, the build agent may be loaded into the build environment after instantiation, and may consist of multiple components. All build agent components must be measured along with the build image.
+| Build dispatch | The process of assigning a tenant's build to a pre-deployed build environment on a hosted build platform.
+| Compute platform | The compute system and infrastructure underlying a build platform, i.e., the host system (hypervisor and/or OS) and hardware. In practice, the compute platform and the build platform may be managed by the same or distinct organizations.
+| Host interface | The component in the compute platform that the hosted build platform uses to request resources for deploying new build environments, i.e., the VMM/hypervisor or container orchestrator.
+| Boot process | In the context of builds, the process of loading and executing the layers of firmware and/or software needed to start up a build environment on the host compute platform.
+| Measurement | The cryptographic hash of some component or system state in the build environment, including software binaries, configuration, or initialized run-time data.
+| Quote | (Virtual) hardware-signed data that contains one or more (virtual) hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata. (Based on the definition in [section 9.5.3.1](https://trustedcomputinggroup.org/wp-content/uploads/TPM-2.0-1.83-Part-1-Architecture.pdf) of the TPM 2.0 spec)
+| Reference value | A specific measurement used as the good known value for a given build environment component or state.
+
+**TODO:** Disambiguate similar terms (e.g., image, build job, build executor/runner)
+
+#### Build environment lifecycle
+
+A typical build environment will go through the following lifecycle:
+
+1. *Build image creation*: A [build image producer](#build-image-producer)
+ creates different [build images](#build-image) through a dedicated build
+ process. For the SLSA BuildEnv track, the build image producer outputs
+ [provenance](#provenance) describing this process.
+2. *Build environment instantiation*: The [hosted build platform](#platform)
+ calls into the [host interface](#host-interface) to create a new instance
+ of a build environment from a given build image. The
+ [build agent](#build-agent) begins to wait for an incoming
+ [build dispatch](#build-dispatch).
+ For the SLSA BuildEnv track, the host interface in the compute platform
+ attests to the integrity of the environment's initial state during its
+ [boot process](#boot-process).
+3. *Build dispatch*: When the tenant dispatches a new build, the hosted
+ build platform assigns the build to a created build environment.
+ For the SLSA BuildEnv track, the build platform attests to the binding
+ between a build environment and [build ID](#build-id).
+4. *Build execution*: Finally, the build agent within the environment executes
+ the tenant's build definition.
+
+### Verification model
+
+Verification in SLSA is performed in two ways. Firstly, the build platform is
+certified to ensure conformance with the requirements at the level claimed by
+the build platform. This certification should happen on a recurring cadence with
+the outcomes published by the platform operator for their users to review and
+make informed decisions about which builders to trust.
+
+Secondly, artifacts are verified to ensure they meet the producer defined
+expectations of where the package source code was retrieved from and on what
+build platform the package was built.
+
+
+
+| Term | Description
+|--------------|----
+| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly.
+| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used.
+| Build platform certification | [Build platforms are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level.
+
+The examples below suggest some ways that expectations and verification may be
+implemented for different, broadly defined, package ecosystems.
+
+Example: Small software team
+
+| Term | Example
+| ---- | -------
+| Expectations | Defined by the producer's security personnel and stored in a database.
+| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database.
+| Build platform certification | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements.
+
+Example: Open source language distribution
+
+| Term | Example
+| ---- | -------
+| Expectations | Defined separately for each package and stored in the package registry.
+| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages.
+| Build platform certification | Performed by the language ecosystem packaging authority.
+
+
-- Summary
-
-
-No requirements---L0 represents the lack of SLSA.
-
-
- Intended for
-
-
-Development or test builds of software that are built and run on the same
-machine, such as unit tests.
-
-
- Requirements
-
-
-n/a
-
-
- Benefits
-
-
-n/a
-
-
-
-
-
-### Build L1: Provenance exists
-
-
-- Summary
-
-
-Package has provenance showing how it was built. Can be used to prevent mistakes
-but is trivial to bypass or forge.
-
-
- Intended for
-
-
-Projects and organizations wanting to easily and quickly gain some benefits of
-SLSA---other than tamper protection---without changing their build workflows.
-
-
- Requirements
-
-
-- Software Producer:
- - Follow a consistent build process so that others can form
- expectations about what a "correct" build looks like.
- - Run builds on a build platform that meets Build L1 requirements.
- - Distribute provenance to consumers, preferably using a convention
- determined by the package ecosystem.
-- Build platform:
- - Automatically generate [provenance] describing how the artifact was
- built, including: what entity built the package, what build process
- they used, and what the top-level input to the build were.
-
-
- Benefits
-
-
-- Makes it easier for both producers and consumers to debug, patch, rebuild,
- and/or analyze the software by knowing its precise source version and build
- process.
-
-- With [verification], prevents mistakes during the release process, such as
- building from a commit that is not present in the upstream repo.
-
-- Aids organizations in creating an inventory of software and build platforms
- used across a variety of teams.
-
-
- Notes
-
-
-- Provenance may be incomplete and/or unsigned at L1. Higher levels require
- more complete and trustworthy provenance.
-
-
+For more information see the [Build track] specification.
-
-
+## Source track levels
-### Build L2: Hosted build platform
-
-
-- Summary
-
-
-Forging the provenance or evading verification requires an explicit "attack",
-though this may be easy to perform. Deters unsophisticated adversaries or those
-who face legal or financial risk.
-
-In practice, this means that builds run on a hosted platform that generates and
-signs[^sign] the provenance.
-
-
- Intended for
-
-
-Projects and organizations wanting to gain moderate security benefits of SLSA by
-switching to a hosted build platform, while waiting for changes to the build
-platform itself required by [Build L3].
-
-
- Requirements
-
-
-All of [Build L1], plus:
-
-- Software producer:
- - Run builds on a [hosted] build platform that meets Build L2
- requirements.
-- Build platform:
- - Generate and sign[^sign] the provenance itself. This may be done
- during the original build, an after-the-fact reproducible build, or
- some equivalent system that ensures the trustworthiness of the
- provenance.
-- Consumer:
- - Validate the authenticity of the provenance.
-
-
- Benefits
-
-
-All of [Build L1], plus:
-
-- Prevents tampering after the build through digital signatures[^sign].
-
-- Deters adversaries who face legal or financial risk by evading security
- controls, such as employees who face risk of getting fired.
-
-- Reduces attack surface by limiting builds to specific build platforms that
- can be audited and hardened.
-
-- Allows large-scale migration of teams to supported build platforms early
- while further hardening work ([Build L3]) is done in parallel.
-
-
-
-
-
-[^sign]: Alternate means of verifying the authenticity of the provenance are
- also acceptable.
-
-### Build L3: Hardened builds
-
-
-- Summary
-
-
-Forging the provenance or evading verification requires exploiting a
-vulnerability that is beyond the capabilities of most adversaries.
-
-In practice, this means that builds run on a hardened build platform that offers
-strong tamper protection.
-
-
- Intended for
-
-
-Most software releases. Build L3 usually requires significant changes to
-existing build platforms.
-
-
- Requirements
-
-
-All of [Build L2], plus:
-
-- Software producer:
- - Run builds on a hosted build platform that meets Build L3
- requirements.
-- Build platform:
- - Implement strong controls to:
- - prevent runs from influencing one another, even within the same
- project.
- - prevent secret material used to sign the provenance from being
- accessible to the user-defined build steps.
-
-
- Benefits
-
-
-All of [Build L2], plus:
+| Track/Level | Requirements | Focus
+| ----------- | ------------ | -----
+| [Source L0] | (none) | (n/a)
+| [Source L1] | Version controlled | Change tracking
+| [Source L2] | Branch history | Tampering of source versioning
+| [Source L3] | Authenticatable and Auditable Provenance | Tampering within the SCS's storage systems.
-- Prevents tampering during the build---by insider threats, compromised
- credentials, or other tenants.
+For more information see the [Source track] specification.
-- Greatly reduces the impact of compromised package upload credentials by
- requiring attacker to perform a difficult exploit of the build process.
+## Build Environment track levels
-- Provides strong confidence that the package was built from the official
- source and build process.
+| Track/Level | Requirements | Focus | Trust Root
+| ------------- | ------------ | ----- | ----------
+| [BuildEnv L0] | (none) | (n/a) | (n/a)
+| [BuildEnv L1] | Signed build image provenance exists | Tampering during build image distribution | Signed build image provenance
+| [BuildEnv L2] | Attested build environment instantiation | Tampering via the build platform's control plane | The compute platform's host interface
+| [BuildEnv L3] | Hardware-attested build environment | Tampering via the compute platform's host interface | The compute platform's hardware
-
-
+For more information see the [Build Environment track] specification.
-[build l0]: #build-l0
-[build l1]: #build-l1
-[build l2]: #build-l2
-[build l3]: #build-l3
-[future versions]: future-directions.md
-[hosted]: requirements.md#isolation-strength
-[previous version]: ../v0.1/levels.md
-[provenance]: terminology.md
-[verification]: verifying-artifacts.md
+[Build track]: ../../build/v1.0
+[Source track]: ../../source/draft
+[Build Environment track]: ../../build-env/draft
+[previous version]: ../v0.1/levels
diff --git a/docs/spec/draft/provenance.md b/docs/spec/draft/provenance.md
index bccb8e863..d660d6bf1 100644
--- a/docs/spec/draft/provenance.md
+++ b/docs/spec/draft/provenance.md
@@ -35,7 +35,7 @@ Describe how an artifact or set of artifacts was produced so that:
- Others can rebuild the artifact, if desired.
This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance
-requirements](requirements#provenance-generation).
+requirements].
## Model
@@ -85,7 +85,7 @@ The model is as follows:
- During execution, the build process might communicate with the build
platform's control plane and/or build caches. This communication is not
captured directly in the provenance, but is instead implied by `builder.id`
- and subject to [SLSA Requirements](requirements.md). Such
+ and subject to [SLSA Build Requirements](../../build/v1.0/requirements.md). Such
communication SHOULD NOT influence the definition of the build; if it does,
it SHOULD go in `resolvedDependencies` instead.
@@ -347,7 +347,7 @@ REQUIRED for SLSA Build L1: `id`
| string (TypeURI) |
URI indicating the transitive closure of the trusted build platform. This is
-[intended](verifying-artifacts#step-1-check-slsa-build-level)
+[intended](../../build/v1.0/verifying-artifacts#step-1-check-slsa-build-level)
to be the sole determiner of the SLSA Build level.
If a build platform has multiple modes of operations that have differing
@@ -384,7 +384,7 @@ the build and record the provenance. This includes not only the software but the
hardware and people involved in running the service. For example, a particular
instance of [Tekton](https://tekton.dev/) could be a build platform, while
Tekton itself is not. For more info, see [Build
-model](terminology#build-model).
+model](../../build/v1.0/terminology#build-model).
The `id` MUST reflect the trust base that consumers care about. How detailed to
be is a judgement call. For example, GitHub Actions supports both GitHub-hosted
@@ -454,7 +454,7 @@ information that is not captured in a standard field. Guidelines:
## Verification
-[Verification]: verifying-artifacts
+[Verification]: ../../build/v1.0/verifying-artifacts
Please see [Verifying Artifacts][Verification] for a detailed discussion of
provenance verification.
@@ -597,3 +597,4 @@ Initial version, named "in-toto.io/Provenance"
[purl]: https://github.com/package-url/purl-spec
[threats]: threats
[trusted]: principles#trust-systems-verify-artifacts
+[provenance requirements]: ../../build/v1.0/requirements#provenance-generation
diff --git a/docs/spec/draft/terminology.md b/docs/spec/draft/terminology.md
index cc760eca2..70e1c2871 100644
--- a/docs/spec/draft/terminology.md
+++ b/docs/spec/draft/terminology.md
@@ -1,6 +1,7 @@
---
title: Terminology
description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting.
+layout: specifications
---
-[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively
+[apply SLSA recursively]: ../../build/v1.0/verifying-artifacts#step-3-optional-check-dependencies-recursively
### Build dependency
@@ -886,7 +886,7 @@ output artifact.
including OS images, as any other artifact to be verified prior to use.
The threats described in this document apply recursively to build tooling
as do the mitigations and examples. A future
-[Build Environment track](current-activities#build-environment-track) may
+[Build Environment track](/current-activities#build-environment-track) may
provide more comprehensive guidance on how to address more specfiic
aspects of this threat.
@@ -1063,12 +1063,15 @@ collision resistance.
-[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively
-[authentic]: requirements.md#provenance-authentic
-[exists]: requirements.md#provenance-exists
-[isolated]: requirements.md#isolated
-[unforgeable]: requirements.md#provenance-unforgeable
+[apply SLSA recursively]: ../../build/v1.0/verifying-artifacts#step-3-optional-check-dependencies-recursively
+[authentic]: ../../build/v1.0/requirements#provenance-authentic
+[exists]: ../../build/v1.0/requirementsrequirements.md#provenance-exists
+[isolated]: ../../build/v1.0/requirementsrequirements.md#isolated
+[unforgeable]: ../../build/v1.0/requirementsrequirements.md#provenance-unforgeable
[secure-by-design]: https://www.cisa.gov/securebydesign
[supply chain threats]: threats-overview
[vsa]: verification_summary
[vsa_verification]: verification_summary#how-to-verify
+[Terminology]: ../../build/v1.0/terminology.md
+[requirements]: ../../build/v1.0/requirements.md
+[verifies artifacts]: ../../build/v1.0/verifying-artifacts.md
diff --git a/docs/spec/draft/whats-new.md b/docs/spec/draft/whats-new.md
index 92b92fe32..82855648a 100644
--- a/docs/spec/draft/whats-new.md
+++ b/docs/spec/draft/whats-new.md
@@ -16,9 +16,11 @@ Draft relative to the prior release, [v1.0].
- It is now recommended that the `digest` field of `ResourceDescriptor` is
set in a Verification Summary Attestation's (VSA) `policy` object.
- Further refine the [threat model](threats).
-- Add draft of [SLSA Source Track](source-requirements.md).
+- Add draft of [SLSA Source Track].
+- Add draft of [SLSA Build Environment Track].
[in-toto attestation]: https://github.com/in-toto/attestation
[v1.0]: /spec/v1.0/
+[SLSA Source Track]: ../../source/draft
diff --git a/docs/spec/v1.1/threats.md b/docs/spec/v1.1/threats.md
index 807445dce..18c26c797 100644
--- a/docs/spec/v1.1/threats.md
+++ b/docs/spec/v1.1/threats.md
@@ -64,7 +64,7 @@ This includes the threat of an authorized individual introducing an unauthorized
change---in other words, an insider threat.
SLSA v1.0 does not address source threats, but we anticipate doing so in a
-[future version](current-activities.md#source-track). In the meantime, the
+[future version](current-activities#source-track). In the meantime, the
threats and potential mitigations listed here show how SLSA v1.0 can fit into a
broader supply chain security program.
|