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. Implementer Requirement Degree - L1L2L3 + L1L2L3L4 Producer Choose an appropriate build platform - ✓✓✓ + ✓✓✓✓ Follow a consistent build process - ✓✓✓ + ✓✓✓✓ Distribute provenance - ✓✓✓ + ✓✓✓✓ - Build platform + Build platform Provenance generation Exists - ✓✓✓ + ✓✓✓✓ Authentic - ✓✓ + ✓✓✓ Unforgeable - ✓ + ✓✓ - Isolation strength + Isolation strength Hosted - ✓✓ + ✓✓✓ Isolated - ✓ + ✓✓ + + Hardware-Attested + ✓ ### Security Best Practices @@ -153,7 +156,7 @@ minimum requirements on its: the build process? -
RequirementDescriptionL1L2L3 +
RequirementDescriptionL1L2L3L4
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). - +
RequirementDescriptionL1L2L3 +
RequirementDescriptionL1L2L3L4
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