diff --git a/docs/spec/v1.1/levels.md b/docs/spec/v1.1/levels.md
index 98bce5869..c075f00ff 100644
--- a/docs/spec/v1.1/levels.md
+++ b/docs/spec/v1.1/levels.md
@@ -26,6 +26,7 @@ tracks without invalidating previous levels.
| [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
+| [Build L4] | Attested build environment | Tampering during the build via the build environment
@@ -231,14 +232,74 @@ All of [Build L2], plus:
+
+
+### Build L4: Attested build environment
+
+
+- Summary
-
+
+Compromising a build requires exploiting a vulnerability in the build
+platform's supply chain or physical access to the underlying compute
+platform.
+
+In practice, this means that builds are configured to run on a build platform
+that supports hardware capabilities for attesting to the state of the
+compute environment executing builds.
+
+
- Intended for
-
+
+Software releases needing assurances about the integrity of the environment
+used to create the release (e.g., specific compute platform, pre-build
+tamper detection).
+Build L4 usually requires significant changes to existing build platforms.
+
+
- Requirements
-
+
+All of [Build L3], plus:
+
+- Software producer:
+ - MUST run builds on a hosted build platform that meets Build L4
+ requirements.
+ - SHOULD verify the [build environment attestations] at the start of a
+ build and produce a [verification summary] about the check.
+
+- Build platform:
+ - MUST generate and distribute attestations to good known integrity
+ measurements of the entire initial state of the build environment
+ (i.e., VM/container image, boot process and filesystem). All
+ attestations MUST be authenticated by a hardware root of trust.
+ - MUST capture all of the inputs to the build in the Provenance.
+ - MUST verify the build environment integrity against the build
+ environment attestations prior to passing control of the build to
+ the tenant.
+
+
- Benefits
-
+
+All of [Build L3], plus:
+
+- Greatly reduces trust in a hosted build platform by increasing
+ observability into the level of integrity of the build environment.
+- Provides machine-checkable, cryptographic, hardware-rooted evidence
+ about:
+ - The initial state of the build environment executing a build, such
+ as its VM/container image, boot process, kernel and filesystem.
+ - The specific build environment that executed a build.
+
+
+
+
[build l0]: #build-l0
[build l1]: #build-l1
[build l2]: #build-l2
[build l3]: #build-l3
+[build l4]: #build-l4
+[build environment attestations]: requirements.md#hardware-attested
[future versions]: future-directions.md
[hosted]: requirements.md#isolation-strength
[previous version]: ../v0.1/levels.md
[provenance]: terminology.md
[verification]: verifying-artifacts.md
+[verification summary]: verification_summary.md
diff --git a/docs/spec/v1.1/requirements.md b/docs/spec/v1.1/requirements.md
index 63f0e6b2b..9736a57ad 100644
--- a/docs/spec/v1.1/requirements.md
+++ b/docs/spec/v1.1/requirements.md
@@ -32,35 +32,38 @@ build level, implementing any controls as specified by the chosen platform.
+ Hardware-Attested
+ | | | | ✓
### Security Best Practices
@@ -153,7 +156,7 @@ minimum requirements on its:
the build process?
-Requirement | Description | L1 | L2 | L3
+ |
---|
Requirement | Description | L1 | L2 | L3 | L4
|
---|
Provenance Exists |
@@ -182,7 +185,7 @@ Provenance.
[SLSA Provenance]: provenance.md
[associated suite]: ../../attestation-model#recommended-suite
- | ✓ | ✓ | ✓
+ | ✓ | ✓ | ✓ | ✓
| Provenance is Authentic |
*Authenticity:* Consumers MUST be able to validate the authenticity of the
@@ -233,7 +236,7 @@ build platform (i.e. outside the trust boundary), except as noted below.
the provenance.
- Completeness of resolved dependencies is best effort.
- | | ✓ | ✓
+ | | ✓ | ✓ | ✓
| Provenance is Unforgeable |
*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants.
@@ -258,9 +261,11 @@ build platform (i.e. outside the trust boundary), except as noted below.
Note: This requirement was called "non-falsifiable" in the initial
[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable).
- | | | ✓
+ | | | ✓ | ✓
|
+TODO: Add completeness of resolved dependencies
+
### Isolation strength
[Isolation strength]: #isolation-strength
@@ -270,12 +275,12 @@ The build platform is responsible for isolating between builds, even within the
same tenant project. In other words, how strong of a guarantee do we have that
the build really executed correctly, without external influence?
-The SLSA Build level describes the minimum bar for isolation strength. For more
-information on assessing a build platform's isolation strength, see
-[Verifying build platforms](verifying-systems.md).
+The SLSA Build level describes the minimum bar for isolation strength.
+For more information on assessing a build platform's isolation strength,
+see [Verifying build platforms](verifying-systems.md).
-Requirement | Description | L1 | L2 | L3
+ |
---|
Requirement | Description | L1 | L2 | L3 | L4
|
---|
Hosted
@@ -286,7 +291,7 @@ infrastructure, not on an individual's workstation.
Examples: GitHub Actions, Google Cloud Build, Travis CI.
- | | ✓ | ✓
+ | | ✓ | ✓ | ✓
|
Isolated
|
@@ -330,9 +335,77 @@ 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).
- | | | ✓
+ | | | ✓ | ✓
+ |
+Hardware-Attested
+ |
+
+The build platform generated an authenticated attestation to the integrity
+of the entire initial state of the build environment (i.e., VM/container
+image, kernel, and filesystem) was generated at creation time and verified
+at deployment time. The build platform also attested to the build request.
+In other words, tampering with the initial state of the build environment
+MUST be detectable by the platform itself and the build.
+
+The build platform MUST guarantee the following:
+
+- When creating a new build environment:
+ - The integrity of the build image (i.e., VM or container) MUST be
+ authenticated and verifiable. That is, SLSA Build L3+ Provenance for
+ the build image MUST be generated and distributed to allow for
+ independent verification.
+ - The boot process of each build environment MUST be measured and
+ attested using a [TCG-compliant measured boot] mechanism. In
+ addition, the initial state of the build environment's disk image
+ MUST be integrity measured and attested. The boot and disk
+ attestations MUST be distributed to allow for independent
+ verification.
+- When deploying a new build environment:
+ - The build image's SLSA Provenance MUST be verified to ensure the
+ VM/container image has not been tampered with.
+ - The boot process and state of disk image attestations MUST be
+ verified to ensure the guest kernel and filesystem have not been
+ tampered with.
+ - A unique immutable build environment identifier (e.g.,
+ cryptographic keypair) MUST be generated and cryptographically bound
+ to the build environment via attestation. This *deploy-time
+ attestation* MUST be generated only after build image, boot process
+ and disk image integrity have been verified, and distributed to
+ allow for independent verification.
+- When accepting a new build request (e.g., GHA build job):
+ - The build environment's deploy-time attestation and uniqueness of its
+ immutable identifier MUST be verified to ensure the initial state
+ of the build environment has not been tampered with.
+ - A unique immutable build identifier (e.g., GHA build job
+ ID) MUST be generated and cryptographically bound to the build
+ environment via attestation. This *request-time attestation*
+ MUST be generated only after the deploy-time attestation has been
+ verified, and distributed to allow for independent verification.
+ - Run-time changes to the build environment's disk image SHOULD be
+ observable at run-time by the executing build. These changes NEED NOT
+ be attested.
+- Boot, disk, deploy- and request-time attestations MUST be authenticated
+ by a hardware root of trust (e.g., [TPM] or [trusted execution
+ environment]). In addition, these attestations MUST be distributed in a
+ consistent format that follows the SLSA [attestation model], such as
+ [SCAI].
+
+NOTE: Virtual hardware (e.g., vTPM) MAY be used to meet this requirement.
+
+NOTE: A [confidential computing] technology MAY be used to meet this
+requirement. Such technologies SHOULD be chosen for builds with a need for
+additional data and code confidentiality, and tamper-evidence properties
+during build execution.
+
+ | | | | ✓
|
+[attestation model]: attestation-model.md#model-and-terminology
+[confidential computing]: https://confidentialcomputing.io/wp-content/uploads/sites/10/2023/03/Common-Terminology-for-Confidential-Computing.pdf
[external parameters]: provenance.md#externalParameters
[identified in the provenance]: provenance.md#model
[package ecosystem]: verifying-artifacts.md#package-ecosystem
+[SCAI]: https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md
+[TCG-compliant measured boot]: https://trustedcomputinggroup.org/resource/tcg-efi-platform-specification/
+[TPM]: https://trustedcomputinggroup.org/resource/tpm-library-specification/
+[trusted execution environment]: https://csrc.nist.gov/glossary/term/trusted_execution_environment
diff --git a/docs/spec/v1.1/terminology.md b/docs/spec/v1.1/terminology.md
index 3047e0774..26174d5b5 100644
--- a/docs/spec/v1.1/terminology.md
+++ b/docs/spec/v1.1/terminology.md
@@ -125,6 +125,39 @@ of build types](/provenance/v1#index-of-build-types).
+### Build environment model
+
+Following the [build model](#build-model), we model a *build environment*
+as a single instance of an execution context that runs a tenant's build
+on a hosted build platform. Specifically, a build environment comprises
+resources from the *compute platform* and a *build image*.
+
+A typical build environment will go through the following lifecycle:
+
+1. A hosted build platform creates different build images through a separate
+ build process. For SLSA Build L4, the build platform outputs provenance
+ describing this process.
+2. The hosted build platform deploys a build image on a compute platform to
+ provision a new build environment. For SLSA Build L4, the
+ build platform validates the *measurement* of the environment's
+ *boot process*.
+3. When a new *build request* is made, the platform assigns the request to
+ a deployed build environment. For SLSA Build L4, the tenant may validate
+ the measurement of the build environment.
+4. Finally, the *build executior* running within the environment executes
+ the tenant's build steps.
+
+| Primary Term | Description
+| --- | ---
+| Build image | The run-time context within a build environment, such as the VM or container image. Individual components of a build image are provided by both the hosted build platform and tenant, and include the build executor, platform-provided pre-installed guest OS and packages, and the tenant’s build steps and external parameters.
+| Build executor | The platform-provided program dedicated to executing the tenant’s build definition, i.e., running the build, within the build image.
+| Build request | The process of assigning a build to a pre-provisioned build environment on a hosted build process.
+| Compute platform | The compute system and infrastructure, i.e., the host system (hypervisor and/or OS) and hardware, underlying a build platform. In practice, the compute platform and the build platform may be managed by the same or distinct organizations.
+| Boot process | In the context of builds, the process of loading and executing the layers of firmware and software needed to start up a build environment.
+| Measurement | The cryptographic hash of some system state in the build environment, including software binaries, configuration, or initialized run-time data. Software layers that are commonly measured include the bootloader, kernel, and kernel cmdline.
+
+TODO: Disambiguate similar terms (e.g., build job, build runner)
+
### Package model
Software is distributed in identifiable units called packages
|