From 89bae2f9d52c7739f089ba9b0fb487708d21b0ab Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Tue, 30 Jul 2024 11:35:33 -0700 Subject: [PATCH 01/10] Add build environment track * Draft levels Environment L0-L2 * Add build environment model Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 235 +++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 docs/spec/draft/attested-build-env-levels.md diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md new file mode 100644 index 000000000..a9300bc5c --- /dev/null +++ b/docs/spec/draft/attested-build-env-levels.md @@ -0,0 +1,235 @@ +--- +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. +--- + + +## Track overview + +The SLSA Build Environment track describes increasing levels of integrity and +trustworthiness of the provenance of a build's execution context. +In this track, provenance describes how the [hosted] build platform built the +base [build image], what build environment they deployed, and the hardware +platform they used. + +| Track/Level | Requirements | Focus | +| ------------- | ------------ | ----- | +| [Environment L0] | (none) | (n/a) | +| [Environment L1] | Signed build image provenance exists | Tampering during build image distribution | +| [Environment L2] | Attested build environment deployment | Tampering via the build platform's control plane | +| [Environment L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface | +| [Environment L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build | + +> [!IMPORTANT] +> The Environment track currently requires a [hosted] build platform. +> A future version of this track may generalize requirements to cover local +> build environments (e.g., developer laptop). + +### Build environment model + +

Model Build Environment

+ +The Build Environment track expands upon the [build model] by explicitily +separating the *build image* and *compute platform* from the abstract build environment +and build platform. + +A typical build environment will go through the following lifecycle: + +1. *Build image creation*: A hosted build platform creates different build + images through a separate build process. For the SLSA HABE Track, the + hosted build platform outputs SLSA provenance describing this process. +2. *Build environment deployment*: The hosted build platform calls into the + *host interface* to deploy a new build environment from a given build image + on the underlying compute platform. + For the SLSA HABE Track, the build platform attests to the *measurement* + of the environment's *boot process*. +3. *Build dispatch*: When the tenant dispatches a new build, the hosted + build platform assigns the build to a deployed build environment. For + the SLSA HABE Track, the build platform attests to the binding between + a build environment and *build ID*. +4. *Build execution*: Finally, the *build executor* running within the + environment executes the tenant's build definition. + +| 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 a cryptographic key or other unique and immutable identfier (e.g., a UUID) associated with the build execution. +| Build image | The template for a build runtime environment, such as a VM or container image. Individual components of a build image are provided by the hosted build platform, and include the bootable storage volume containing the build executor, a dedicated build platform client, and platform-provided pre-installed guest OS and packages. +| Build executor | The platform-provided program dedicated to executing the tenant’s build definition, i.e., running the build, within the build image. The build executor must be included in the build image's measurement. +| 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, 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 environmenton the build platform. +| 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., image, build job, build runner) + +## Environment levels + +The lowest level only requires SLSA Build L2 (or higher) Provenance to exist +for the build image, while higher levels provide increasing auditability of +the build environment's properties and integrity of the generated provenance +attestations. The highest levels introduce further requirements for hardware- +assisted hardening aimed at reducing the trusted computing base of a build. + +The primary purpose of the Environment track is to enable [auditing] that a +build was run in the expected compute environment. The build platform and +producers can check attestations generated by the build platform against the +expected properties for a given build environment. This enables any party to +detect several classes of supply chain threats originating in the build +environment [TODO: Link here]. + +As in the Build track, the exact implementation of this track is determined +by the build platform provider, whether they are a commercial CI/CD service, +or enterprise organization. While this track describes +general [TODO: minimum requirements], this track does not dictate the +following implementation-specific details: the type of build environment +environment, accepted attestation formats, the type of technologies used to +meet L3/4 requirements, what SLSA [Build] level the *built artifacts* meet, +how attestations are distributed, how build environments are identified, and +what happens on failure. + +
+ +### Environment L0: No guarantees + +
+
Summary
+ +No requirements---L0 represents the lack of any sort of build environment provenance. + +
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 + +
+
+ +
+ +### Environment L1: Signed build image provenance exists + +
+
Summary
+ +The build image (i.e., VM or container image) used to instantiate the build +environment has SLSA provenance showing how the image was built. + +
Intended for
+ +Build platforms and organizations wanting to ensure a baseline level of +integrity for build environments at the time of build image generation. + +
Software Producer Requirements
+ +- MUST run builds using a build image that was built by a hosted build + platform that meets Environment L1 requirements. + +- SHOULD verify the build image's SLSA Build provenance for the selected + build image, and distribute evidence of the verification to consumers + (e.g., using a [VSA]) + +
Build Platform Requirements
+ +- MUST automatially generate and distribute SLSA [Build L1] or higher + Provenance for its supplied build images (i.e., VM or container images). + +- The initial state of the build environment's root storage volume + MUST be integrity measured and signed. + +- MUST execute builds on infrastructure that meets SLSA [Build L2]. + +
Benefits
+ +- Provides evidence that a build image provided by a hosted build platform + was built from the advertised source and build process. + +
+ +
+
+ +### Environment L2: Attested build environment instantiation + +
+
Summary
+ +The deployed build environment is integrity measured and authenticated +prior to giving access to the tenant, attesting to the initial state of the +environment. + +
Intended for
+ +Organizations wanting to ensure that a specific build is running +in the expected build environment. + +All of [Environment L1], plus: + +
Software Producer Requirements
+ +- MUST run builds in a build environment on a hosted build platform that + meets Environment L2 requirements. + +- SHOULD verify the build image's Build SLSA provenance for the selected + build image, and distribute evidence of the verification to consumers + (e.g., using a [VSA]) + +
Build Platform Requirements
+ +- MUST automatially generate and distribute SLSA [Build L2] or higher + Provenance for its supplied build images (i.e., VM or container images). + +- The boot process of each build environment MUST be cryptographically measured + and signed. + +- MUST distribute the boot and root storage attestations to allow for + independent verification. + +- MUST uniquely bind a build image to a build environment instance. + +- MUST uniquely and immutably bind an instance of a build to its build + environment. + +- MUST execute builds in an environment that meets SLSA [Build L3]. + +
Benefits
+ +- Provides evidence that a build environment deployed by a hosted build + platform was initialized from the expected build image. + +
+ +
+
+ +### Environment L3: Hardware-authenticated build environment +TODO + +
+
+ +### Environment L4: Encrypted build environment + +TODO + +
+ + + +[Build L1]: levels.md#build-l1 +[Build L2]: levels.md#build-l2 +[Build L3]: levels.md#build-l3 +[Environment L0]: #environment-l0 +[Environment L1]: #environment-l1 +[Environment L2]: #environment-l2 +[Environment L3]: #environment-l3 +[Environment L4]: #environment-l4 +[future versions]: future-directions.md +[hosted]: requirements.md#isolation-strength From aab225932dc5967dbfac9a7e6f621cc9f1b90f7e Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Fri, 16 Aug 2024 15:19:56 -0700 Subject: [PATCH 02/10] Fix link Co-authored-by: Tom Hennen Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index a9300bc5c..89f94f8f8 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -231,5 +231,6 @@ TODO [Environment L2]: #environment-l2 [Environment L3]: #environment-l3 [Environment L4]: #environment-l4 +[VSA]: verification_summary.md [future versions]: future-directions.md [hosted]: requirements.md#isolation-strength From 578ba50decea0fc7eb69b56934c83ef298b56d10 Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Fri, 16 Aug 2024 15:21:16 -0700 Subject: [PATCH 03/10] Make linter happy Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index 89f94f8f8..fe406e4b9 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -12,13 +12,13 @@ In this track, provenance describes how the [hosted] build platform built the base [build image], what build environment they deployed, and the hardware platform they used. -| Track/Level | Requirements | Focus | -| ------------- | ------------ | ----- | -| [Environment L0] | (none) | (n/a) | -| [Environment L1] | Signed build image provenance exists | Tampering during build image distribution | -| [Environment L2] | Attested build environment deployment | Tampering via the build platform's control plane | -| [Environment L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface | -| [Environment L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build | +| Track/Level | Requirements | Focus +| ------------- | ------------ | ----- +| [Environment L0] | (none) | (n/a) +| [Environment L1] | Signed build image provenance exists | Tampering during build image distribution +| [Environment L2] | Attested build environment deployment | Tampering via the build platform's control plane +| [Environment L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface +| [Environment L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build > [!IMPORTANT] > The Environment track currently requires a [hosted] build platform. @@ -210,6 +210,7 @@ All of [Environment L1], plus:
### Environment L3: Hardware-authenticated build environment + TODO
From d2119cc0e468b50f897b6859fc4a5282f1a37020 Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Wed, 21 Aug 2024 12:21:57 -0700 Subject: [PATCH 04/10] Refine L1 and L2, add rationale Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 191 +++++++++++-------- 1 file changed, 114 insertions(+), 77 deletions(-) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index fe406e4b9..db99a6a06 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -3,22 +3,39 @@ 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. --- +## Rationale + +Today's hosted build platforms play a central role in an artifact's supply +chain. Whether it's a cloud-hosted service like GitHub Actions or an internal +enterprise CI/CD system, the build platform has a privileged level of access +to artifacts and sensitive operations during a build (e.g., access to +producer secrets, provenance signing). + +This central and privileged role makes hosted build platforms an attractive +target for supply chain attackers. But even with strong economic and +reputational incentives to mitigate these risks, it's very challenging to +implement fully secure build platforms because they are made up of many +layers of interconnected components and subsystems. + +The SLSA Build Environment track aims to address these issues by making it +possible to validate the integrity and trace the provenance of core build +platform components. ## Track overview The SLSA Build Environment track describes increasing levels of integrity and trustworthiness of the provenance of a build's execution context. -In this track, provenance describes how the [hosted] build platform built the -base [build image], what build environment they deployed, and the hardware -platform they used. +In this track, provenance describes how a [build image] was created, how the +[hosted] build platform deployed a build image in its environment, +and the compute platform they used. | Track/Level | Requirements | Focus | ------------- | ------------ | ----- -| [Environment L0] | (none) | (n/a) -| [Environment L1] | Signed build image provenance exists | Tampering during build image distribution -| [Environment L2] | Attested build environment deployment | Tampering via the build platform's control plane -| [Environment L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface -| [Environment L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build +| [Environment L0] | (none) | (n/a) +| [Environment L1] | Build image provenance exists | Tampering during build image distribution +| [Environment L2] | Attested build environment deployment | Tampering via the build platform's control plane +| [Environment L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface +| [Environment L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build > [!IMPORTANT] > The Environment track currently requires a [hosted] build platform. @@ -30,52 +47,66 @@ platform they used.

Model Build Environment

The Build Environment track expands upon the [build model] by explicitily -separating the *build image* and *compute platform* from the abstract build environment -and build platform. +separating the *build image* and *compute platform* from the abstract build +environment and build platform. A typical build environment will go through the following lifecycle: -1. *Build image creation*: A hosted build platform creates different build - images through a separate build process. For the SLSA HABE Track, the - hosted build platform outputs SLSA provenance describing this process. +1. *Build image creation*: A build image producer creates different build + images through dedicated build process. For the SLSA Environment track, + the build image producer outputs provenance describing this process. 2. *Build environment deployment*: The hosted build platform calls into the - *host interface* to deploy a new build environment from a given build image - on the underlying compute platform. - For the SLSA HABE Track, the build platform attests to the *measurement* - of the environment's *boot process*. + *host interface* to deploy a new build environment from a given build + image on the underlying compute platform. + For the SLSA Environment track, the hosted build platform attests to the + *measurement* of the environment's *initial state* during its boot + process. 3. *Build dispatch*: When the tenant dispatches a new build, the hosted build platform assigns the build to a deployed build environment. For - the SLSA HABE Track, the build platform attests to the binding between - a build environment and *build ID*. + the SLSA Environment track, the build platform attests to the binding + between a build environment and *build ID*. 4. *Build execution*: Finally, the *build executor* running within the - environment executes the tenant's build definition. +environment executes the tenant's build definition. + +### Definitions + +The Build Environment track specifies the following supply chain components +and roles: | 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 a cryptographic key or other unique and immutable identfier (e.g., a UUID) associated with the build execution. -| Build image | The template for a build runtime environment, such as a VM or container image. Individual components of a build image are provided by the hosted build platform, and include the bootable storage volume containing the build executor, a dedicated build platform client, and platform-provided pre-installed guest OS and packages. -| Build executor | The platform-provided program dedicated to executing the tenant’s build definition, i.e., running the build, within the build image. The build executor must be included in the build image's measurement. +| Build image | The template for a build environment, such as a VM or container image. Individual components of a build image include the bootable storage volume containing the build executor, a dedicated build platform client, and pre-installed guest OS and packages. +| 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 BYO build image setting. +| Build executor | A platform-provided program dedicated to executing the tenant’s build definition, i.e., running the build, within the build environment. The build executor must be included in the build image's measurement. +| Build platform client | A platform-provided program that interfaces with the hosted build platform's control plane from within a running build environment. The build platform client must be included in the build image's measurement. | 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, 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 environmenton the 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 build platform. | 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., image, build job, build runner) +### Build environment threats + +TODO + ## Environment levels -The lowest level only requires SLSA Build L2 (or higher) Provenance to exist +The primary purpose of the Environment track is to enable [auditing] that a +build was run in the expected compute environment. + +The lowest level only requires SLSA Build L1 (or higher) Provenance to exist for the build image, while higher levels provide increasing auditability of the build environment's properties and integrity of the generated provenance attestations. The highest levels introduce further requirements for hardware- assisted hardening aimed at reducing the trusted computing base of a build. -The primary purpose of the Environment track is to enable [auditing] that a -build was run in the expected compute environment. The build platform and -producers can check attestations generated by the build platform against the -expected properties for a given build environment. This enables any party to -detect several classes of supply chain threats originating in the build -environment [TODO: Link here]. +Software producers and third-party auditors can check attestations generated +by the build image producer and build platform against the expected +properties for a given build environment. This enables any party to detect +[several classes] of supply chain threats originating the build environment. As in the Build track, the exact implementation of this track is determined by the build platform provider, whether they are a commercial CI/CD service, @@ -127,29 +158,25 @@ environment has SLSA provenance showing how the image was built. Build platforms and organizations wanting to ensure a baseline level of integrity for build environments at the time of build image generation. -
Software Producer Requirements
- -- MUST run builds using a build image that was built by a hosted build - platform that meets Environment L1 requirements. - -- SHOULD verify the build image's SLSA Build provenance for the selected - build image, and distribute evidence of the verification to consumers - (e.g., using a [VSA]) - -
Build Platform Requirements
- -- MUST automatially generate and distribute SLSA [Build L1] or higher - Provenance for its supplied build images (i.e., VM or container images). +
Requirements
-- The initial state of the build environment's root storage volume - MUST be integrity measured and signed. +- Build Image Producer: + - MUST automatially generate SLSA [Build L1] or higher + Provenance for created build images (i.e., VM or container images). + - MUST allow independent automatic verification of a build image's SLSA + Provenance. If the full Provenance document cannot be distributed, for + example due to intellectual property concerns, a [VSA] asserting the + build image's SLSA Provenance MUST be distributed instead. -- MUST execute builds on infrastructure that meets SLSA [Build L2]. +- Build Platform: + - MUST meet SLSA [Build L2] requirements. + - Prior to deployment of a new build environment, the SLSA Provenance + for the selected build image MUST be automatically verified.
Benefits
-- Provides evidence that a build image provided by a hosted build platform - was built from the advertised source and build process. +- Provides evidence that a build image was built from the advertised + source and build process. @@ -170,45 +197,51 @@ environment. Organizations wanting to ensure that a specific build is running in the expected build environment. -All of [Environment L1], plus: - -
Software Producer Requirements
- -- MUST run builds in a build environment on a hosted build platform that - meets Environment L2 requirements. - -- SHOULD verify the build image's Build SLSA provenance for the selected - build image, and distribute evidence of the verification to consumers - (e.g., using a [VSA]) - -
Build Platform Requirements
- -- MUST automatially generate and distribute SLSA [Build L2] or higher - Provenance for its supplied build images (i.e., VM or container images). - -- The boot process of each build environment MUST be cryptographically measured - and signed. - -- MUST distribute the boot and root storage attestations to allow for - independent verification. - -- MUST uniquely bind a build image to a build environment instance. +
Requirements
-- MUST uniquely and immutably bind an instance of a build to its build - environment. +All of [Environment L1], plus: -- MUST execute builds in an environment that meets SLSA [Build L3]. +- Build Image Producer: + - Build images MUST be created via a SLSA [Build L2] or higher build + process. + - MUST add support in the build image for: + - Automatically checking the initial state of build image + components against known good measurements during the boot process. + In VM-based images, this can be achieved by enabling [trusted boot]. + In container-based build images, a dedicated program MUST be used to + perform these checks.[^1] + - Automatically generating and distributing signed attestations + that a given build environment instance was booted from a build image + with verified measurements and SLSA Provenance (e.g., using [SCAI] + or a [VSA]). + - MUST automatically generate and distribute signed measurements + of the following build image components: bootloader (or equivalent), + guest kernel, build platform client, build executor, and root filesystem. + Additional build image components whose initial state is to be checked + MAY be also measured. + +- Build Platform Requirements: + - MUST meet SLSA [Build L3] requirements. + - Prior to deployment of a new build environment, a signed attestation + to the verification of the build image's SLSA Provenance MUST be + automatically generated and distributed (e.g., via a [VSA]). + - Prior to dispatching a tenant's build to a deployed build + environment, its initial state attestations MUST be automatically + verified.
Benefits
- Provides evidence that a build environment deployed by a hosted build - platform was initialized from the expected build image. + platform was instantiated from a known good build image and is at the + expected initial state.
+[^1]: Since containers are executed as processes on the host platform they do not contain a traditional bootloader that starts up the execution context. + ### Environment L3: Hardware-authenticated build environment TODO @@ -232,6 +265,10 @@ TODO [Environment L2]: #environment-l2 [Environment L3]: #environment-l3 [Environment L4]: #environment-l4 +[SCAI]: https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md [VSA]: verification_summary.md -[future versions]: future-directions.md +[build image]: #definitions +[build model]: terminology.md#build-model [hosted]: requirements.md#isolation-strength +[several classes]: #build-environment-threats +[trusted boot]: https://csrc.nist.gov/glossary/term/trusted_boot From db0edfc5a2e5a0da2771d728f2243ffd00c9ecbf Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Wed, 21 Aug 2024 12:42:19 -0700 Subject: [PATCH 05/10] Change abbrev. for track Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 70 ++++++++++---------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index db99a6a06..c67d0f661 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -23,19 +23,19 @@ platform components. ## Track overview -The SLSA Build Environment track describes increasing levels of integrity and -trustworthiness of the provenance of a build's execution context. -In this track, provenance describes how a [build image] was created, how the -[hosted] build platform deployed a build image in its environment, -and the compute platform they used. +The SLSA Build Environment (BuildEnv) track describes increasing levels of +integrity and trustworthiness of the provenance of a build's +execution context. In this track, provenance describes how a [build image] +was created, how the [hosted] build platform deployed a build image in its +environment, and the compute platform they used. | Track/Level | Requirements | Focus | ------------- | ------------ | ----- -| [Environment L0] | (none) | (n/a) -| [Environment L1] | Build image provenance exists | Tampering during build image distribution -| [Environment L2] | Attested build environment deployment | Tampering via the build platform's control plane -| [Environment L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface -| [Environment L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build +| [BuildEnv L0] | (none) | (n/a) +| [BuildEnv L1] | Build image provenance exists | Tampering during build image distribution +| [BuildEnv L2] | Attested build environment deployment | Tampering via the build platform's control plane +| [BuildEnv L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface +| [BuildEnv L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build > [!IMPORTANT] > The Environment track currently requires a [hosted] build platform. @@ -92,12 +92,12 @@ TODO: Disambiguate similar terms (e.g., image, build job, build runner) TODO -## Environment levels +## Build Environment (BuildEnv) levels -The primary purpose of the Environment track is to enable [auditing] that a -build was run in the expected compute environment. +The primary purpose of the Build Environment (BuildEnv) track is to enable +[auditing] that a build was run in the expected execution context. -The lowest level only requires SLSA Build L1 (or higher) Provenance to exist +The lowest level only requires SLSA [Build L1] (or higher) Provenance to exist for the build image, while higher levels provide increasing auditability of the build environment's properties and integrity of the generated provenance attestations. The highest levels introduce further requirements for hardware- @@ -120,7 +120,7 @@ what happens on failure.
-### Environment L0: No guarantees +### BuildEnv L0: No guarantees
Summary
@@ -143,9 +143,9 @@ n/a
-
+
-### Environment L1: Signed build image provenance exists +### BuildEnv L1: Build image provenance exists
Summary
@@ -175,15 +175,15 @@ integrity for build environments at the time of build image generation.
Benefits
-- Provides evidence that a build image was built from the advertised - source and build process. +Provides evidence that a build image was built from the advertised +source and build process.
-
+
-### Environment L2: Attested build environment instantiation +### BuildEnv L2: Attested build environment instantiation
Summary
@@ -194,12 +194,12 @@ environment.
Intended for
-Organizations wanting to ensure that a specific build is running +FIXME: Organizations wanting to ensure that a specific build is running in the expected build environment.
Requirements
-All of [Environment L1], plus: +All of [BuildEnv L1], plus: - Build Image Producer: - Build images MUST be created via a SLSA [Build L2] or higher build @@ -231,25 +231,25 @@ All of [Environment L1], plus:
Benefits
-- Provides evidence that a build environment deployed by a hosted build - platform was instantiated from a known good build image and is at the - expected initial state. +Provides evidence that a build environment deployed by a hosted build +platform was instantiated from a known good build image and is at the +expected initial state.
-
+
[^1]: Since containers are executed as processes on the host platform they do not contain a traditional bootloader that starts up the execution context. -### Environment L3: Hardware-authenticated build environment +### BuildEnv L3: Hardware-authenticated build environment TODO
-
+
-### Environment L4: Encrypted build environment +### BuildEnv L4: Encrypted build environment TODO @@ -260,11 +260,11 @@ TODO [Build L1]: levels.md#build-l1 [Build L2]: levels.md#build-l2 [Build L3]: levels.md#build-l3 -[Environment L0]: #environment-l0 -[Environment L1]: #environment-l1 -[Environment L2]: #environment-l2 -[Environment L3]: #environment-l3 -[Environment L4]: #environment-l4 +[BuildEnv L0]: #buildenv-l0 +[BuildEnv L1]: #buildenv-l1 +[BuildEnv L2]: #buildenv-l2 +[BuildEnv L3]: #buildenv-l3 +[BuildEnv L4]: #buildenv-l4 [SCAI]: https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md [VSA]: verification_summary.md [build image]: #definitions From a80650de20c60b887287c14af12c0480cc2d4560 Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Wed, 21 Aug 2024 17:18:59 -0700 Subject: [PATCH 06/10] Add L3 Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 126 +++++++++++++------ 1 file changed, 86 insertions(+), 40 deletions(-) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index c67d0f661..0cce4701c 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -84,7 +84,8 @@ and roles: | 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 build platform. -| 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. +| Measurement | The cryptographic hash of some component or system state in the build environment, including software binaries, configuration, or initialized run-time data. +| 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 runner) @@ -92,16 +93,17 @@ TODO: Disambiguate similar terms (e.g., image, build job, build runner) TODO -## Build Environment (BuildEnv) levels +## BuildEnv levels The primary purpose of the Build Environment (BuildEnv) track is to enable [auditing] that a build was run in the expected execution context. -The lowest level only requires SLSA [Build L1] (or higher) Provenance to exist -for the build image, while higher levels provide increasing auditability of -the build environment's properties and integrity of the generated provenance -attestations. The highest levels introduce further requirements for hardware- -assisted hardening aimed at reducing the trusted computing base of a build. +The lowest level only requires SLSA [Build L1] (or higher) Provenance to +exist for the build image, while higher levels provide increasing +auditability of the build environment's properties and integrity of the +generated provenance attestations. The highest levels introduce further +requirements for hardware-assisted hardening aimed at reducing the trusted +computing base of a build. Software producers and third-party auditors can check attestations generated by the build image producer and build platform against the expected @@ -110,11 +112,10 @@ properties for a given build environment. This enables any party to detect As in the Build track, the exact implementation of this track is determined by the build platform provider, whether they are a commercial CI/CD service, -or enterprise organization. While this track describes -general [TODO: minimum requirements], this track does not dictate the -following implementation-specific details: the type of build environment -environment, accepted attestation formats, the type of technologies used to -meet L3/4 requirements, what SLSA [Build] level the *built artifacts* meet, +or enterprise organization. While this track describes general minimum +requirements, this track does not dictate the following +implementation-specific details: the type of build environment, accepted +attestation formats, the type of technologies used to meet L3/4 requirements, how attestations are distributed, how build environments are identified, and what happens on failure. @@ -125,11 +126,12 @@ what happens on failure.
Summary
-No requirements---L0 represents the lack of any sort of build environment provenance. +No requirements---L0 represents the lack of any sort of build environment +provenance.
Intended for
-Development or test builds of software that are built and run on the same +Development or test builds of software that are built and run on a local machine, such as unit tests.
Requirements
@@ -156,7 +158,7 @@ environment has SLSA provenance showing how the image was built.
Intended for
Build platforms and organizations wanting to ensure a baseline level of -integrity for build environments at the time of build image generation. +integrity for build environments at the time of build image distrbution.
Requirements
@@ -188,14 +190,14 @@ source and build process.
Summary
-The deployed build environment is integrity measured and authenticated -prior to giving access to the tenant, attesting to the initial state of the -environment. +The build environment is measured and authenticated prior to dispatching +any builds, attesting to the integrity of initial state of the environment +when it's deployed by the build paltform.
Intended for
-FIXME: Organizations wanting to ensure that a specific build is running -in the expected build environment. +Organizations wanting to ensure that their build started from +a clean, known good state.
Requirements
@@ -204,18 +206,18 @@ All of [BuildEnv L1], plus: - Build Image Producer: - Build images MUST be created via a SLSA [Build L2] or higher build process. - - MUST add support in the build image for: - - Automatically checking the initial state of build image - components against known good measurements during the boot process. - In VM-based images, this can be achieved by enabling [trusted boot]. - In container-based build images, a dedicated program MUST be used to - perform these checks.[^1] - - Automatically generating and distributing signed attestations - that a given build environment instance was booted from a build image - with verified measurements and SLSA Provenance (e.g., using [SCAI] - or a [VSA]). - - MUST automatically generate and distribute signed measurements - of the following build image components: bootloader (or equivalent), + - MUST add support in the build image to: + - Automatically check build image components against their + reference values during build environment startup. + In VM-based images, this can be achieved by enabling a [trusted boot] + process. In container-based build images, a dedicated program MUST be + used to perform these checks.[^1] + - Automatically generate and distribute a signed attestation that + the initial state of a given build environment instance has been + verified against the corresponding build image, incl. its SLSA + Provenance (e.g., using [SCAI] or a [VSA]). + - MUST automatically generate and distribute signed reference values + for the following build image components: bootloader or equivalent, guest kernel, build platform client, build executor, and root filesystem. Additional build image components whose initial state is to be checked MAY be also measured. @@ -225,26 +227,66 @@ All of [BuildEnv L1], plus: - Prior to deployment of a new build environment, a signed attestation to the verification of the build image's SLSA Provenance MUST be automatically generated and distributed (e.g., via a [VSA]). - - Prior to dispatching a tenant's build to a deployed build - environment, its initial state attestations MUST be automatically - verified. + - Prior to dispatching a tenant's build to a deployed environment, its + initial state attestation MUST be automatically verified.
Benefits
Provides evidence that a build environment deployed by a hosted build -platform was instantiated from a known good build image and is at the -expected initial state. +platform was instantiated from the expected build image and is at the +expected initial state, even in the face of a build platform-level +adversary.
-[^1]: Since containers are executed as processes on the host platform they do not contain a traditional bootloader that starts up the execution context. - ### BuildEnv L3: Hardware-authenticated build environment -TODO +
+
Summary
+ +The initial state of the build environment is measured and autenticated by +trusted hardware, and the build ID is verifiably bound to the +deployed build environment, attesting to the integrity of the environment +when a tenant's build is first dispatched. + +
Intended for
+ +Organizations wanting strong assurances that their build was dispatched in +a known good environment. + +
Requirements
+ +All of [BuildEnv L2], plus: + +- Build Image Producer: + - Build images MUST be created via a SLSA [Build L3] or higher build + process. + - MUST add support in the build image to: + - Use trusted hardware to check build image component reference + values and integrity of the build environment startup. + - Automatically generate and distribute a signed attestation + that a given build ID was dispatched in the corresponding build + environment instance, incl. its initial state attestation (e.g., + using [SCAI] or a [VSA]). + - Use trusted hardware to sign all build image-generated + attestations. + +- Build Platform Requirements: + - MUST meet SLSA [Build L3] requirements. + - Prior to assigning a build ID to tenant's build, a signed attestation + to the verification of the selected build environment initial state + attestations MUST be generated and distributed. + +
Benefits
+ +Provides hardware-authenticated evidence that a build running on a hosted +build platform was dispatched in the expected build environment, even in the +face of a compromised host interface (hypervisor/container orchestrator). + +
@@ -255,6 +297,10 @@ TODO
+ + +[^1]: Since containers are executed as processes on the host platform they do not contain a traditional bootloader that starts up the execution context. + [Build L1]: levels.md#build-l1 From 8b952e2efe61e1fad9c802fe72fb0411656195d5 Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Thu, 29 Aug 2024 15:58:42 -0700 Subject: [PATCH 07/10] Update L1 and L2 per review comments Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 52 +++++++++++--------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index 0cce4701c..95eacd875 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -32,7 +32,7 @@ environment, and the compute platform they used. | Track/Level | Requirements | Focus | ------------- | ------------ | ----- | [BuildEnv L0] | (none) | (n/a) -| [BuildEnv L1] | Build image provenance exists | Tampering during build image distribution +| [BuildEnv L1] | Signed build image provenance exists | Tampering during build image distribution | [BuildEnv L2] | Attested build environment deployment | Tampering via the build platform's control plane | [BuildEnv L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface | [BuildEnv L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build @@ -66,7 +66,7 @@ A typical build environment will go through the following lifecycle: the SLSA Environment track, the build platform attests to the binding between a build environment and *build ID*. 4. *Build execution*: Finally, the *build executor* running within the -environment executes the tenant's build definition. + environment executes the tenant's build definition. ### Definitions @@ -85,6 +85,7 @@ and roles: | 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 build 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 | Hardware-signed data that contains one or more hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata. | 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 runner) @@ -98,7 +99,7 @@ TODO The primary purpose of the Build Environment (BuildEnv) track is to enable [auditing] that a build was run in the expected execution context. -The lowest level only requires SLSA [Build L1] (or higher) Provenance to +The lowest level only requires SLSA [Build L2] Provenance to exist for the build image, while higher levels provide increasing auditability of the build environment's properties and integrity of the generated provenance attestations. The highest levels introduce further @@ -108,7 +109,8 @@ computing base of a build. Software producers and third-party auditors can check attestations generated by the build image producer and build platform against the expected properties for a given build environment. This enables any party to detect -[several classes] of supply chain threats originating the build environment. +[several classes] of supply chain threats originating in the build +environment. As in the Build track, the exact implementation of this track is determined by the build platform provider, whether they are a commercial CI/CD service, @@ -147,7 +149,7 @@ n/a
-### BuildEnv L1: Build image provenance exists +### BuildEnv L1: Signed build image provenance exists
Summary
@@ -163,17 +165,20 @@ integrity for build environments at the time of build image distrbution.
Requirements
- Build Image Producer: - - MUST automatially generate SLSA [Build L1] or higher + - MUST automatially generate SLSA [Build L2] or higher Provenance for created build images (i.e., VM or container images). - MUST allow independent automatic verification of a build image's SLSA - Provenance. If the full Provenance document cannot be distributed, for - example due to intellectual property concerns, a [VSA] asserting the - build image's SLSA Provenance MUST be distributed instead. + Provenance. If the build image artifact cannot be published, for example + due to intellectual property concerns, an attestation asserting the + expected hash value of the build image MUST be generated and distributed + instead (e.g., using [SCAI] or a [Release Attestation]). If the full + Provenance document cannot be disclosed, a [VSA] asserting the build + image's SLSA Provenance MUST be distributed instead. - Build Platform: - MUST meet SLSA [Build L2] requirements. - Prior to deployment of a new build environment, the SLSA Provenance - for the selected build image MUST be automatically verified. + for the selected build image SHOULD be automatically verified.
Benefits
@@ -192,7 +197,7 @@ source and build process. The build environment is measured and authenticated prior to dispatching any builds, attesting to the integrity of initial state of the environment -when it's deployed by the build paltform. +when it's deployed by the build platform.
Intended for
@@ -204,7 +209,7 @@ a clean, known good state. All of [BuildEnv L1], plus: - Build Image Producer: - - Build images MUST be created via a SLSA [Build L2] or higher build + - Build images MUST be created via a SLSA [Build L3] or higher build process. - MUST add support in the build image to: - Automatically check build image components against their @@ -224,11 +229,14 @@ All of [BuildEnv L1], plus: - Build Platform Requirements: - MUST meet SLSA [Build L3] requirements. - - Prior to deployment of a new build environment, a signed attestation - to the verification of the build image's SLSA Provenance MUST be - automatically generated and distributed (e.g., via a [VSA]). + - Prior to deployment of a new build environment, the SLSA Provenance + for the selected build image MUST be automatically verified. A signed + attestation to the verification of the build image's SLSA Provenance + MUST be automatically generated and distributed (e.g., via a [VSA]). - Prior to dispatching a tenant's build to a deployed environment, its - initial state attestation MUST be automatically verified. + initial state attestation MUST be automatically verified. A signed + attestation binding the tenant's build ID to the verified initial state + of the selected build environment MUST be generated and distributed.
Benefits
@@ -261,9 +269,9 @@ a known good environment. All of [BuildEnv L2], plus: +**TODO:** These requirements need to be re-formulated. + - Build Image Producer: - - Build images MUST be created via a SLSA [Build L3] or higher build - process. - MUST add support in the build image to: - Use trusted hardware to check build image component reference values and integrity of the build environment startup. @@ -274,11 +282,9 @@ All of [BuildEnv L2], plus: - Use trusted hardware to sign all build image-generated attestations. -- Build Platform Requirements: - - MUST meet SLSA [Build L3] requirements. - - Prior to assigning a build ID to tenant's build, a signed attestation - to the verification of the selected build environment initial state - attestations MUST be generated and distributed. +- Build Platform Requirements: TODO + +- Compute Platform Requirements: TODO
Benefits
From 0d99fc9f0d06e858beedf183762396b1826d5f00 Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Fri, 6 Sep 2024 17:55:46 -0700 Subject: [PATCH 08/10] High-level updates to level focus, terminology changes Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 37 ++++++++++---------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index 95eacd875..99ea338d7 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -33,9 +33,9 @@ environment, and the compute platform they used. | ------------- | ------------ | ----- | [BuildEnv L0] | (none) | (n/a) | [BuildEnv L1] | Signed build image provenance exists | Tampering during build image distribution -| [BuildEnv L2] | Attested build environment deployment | Tampering via the build platform's control plane +| [BuildEnv L2] | Attested build environment instantiation | Tampering via the build platform's control plane | [BuildEnv L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface -| [BuildEnv L4] | Encrypted build environment | Tampering and data leaks by the build platform or compute platform during the build +| [BuildEnv L4] | Runtime monitored build environment | Tampering by the build platform or compute platform during the build > [!IMPORTANT] > The Environment track currently requires a [hosted] build platform. @@ -55,16 +55,17 @@ A typical build environment will go through the following lifecycle: 1. *Build image creation*: A build image producer creates different build images through dedicated build process. For the SLSA Environment track, the build image producer outputs provenance describing this process. -2. *Build environment deployment*: The hosted build platform calls into the - *host interface* to deploy a new build environment from a given build - image on the underlying compute platform. - For the SLSA Environment track, the hosted build platform attests to the - *measurement* of the environment's *initial state* during its boot - process. + 2. *Build environment instantiation*: The hosted build platform calls + into the *host interface* to create a new build environment from a given + build image. The *build agent* begins to wait for an incoming build + dispatch. + **[TODO: revise]** For the SLSA Environment track, the hosted build + platform attests to the *measurement* of the environment's *initial + state* during its boot process. 3. *Build dispatch*: When the tenant dispatches a new build, the hosted - build platform assigns the build to a deployed build environment. For - the SLSA Environment track, the build platform attests to the binding - between a build environment and *build ID*. + build platform assigns the build to a created build environment. + **[TODO: revise]** For the SLSA Environment track, the build platform + attests to the binding between a build environment and *build ID*. 4. *Build execution*: Finally, the *build executor* running within the environment executes the tenant's build definition. @@ -76,10 +77,10 @@ and roles: | 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 a cryptographic key or other unique and immutable identfier (e.g., 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 bootable storage volume containing the build executor, a dedicated build platform client, and pre-installed guest OS and packages. +| Build image | The template for a build environment, such as a VM or container image. Individual components of a build image include the bootable storage volume containing the build executor, a dedicated build agent, and pre-installed guest OS and packages. | 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 BYO build image setting. | Build executor | A platform-provided program dedicated to executing the tenant’s build definition, i.e., running the build, within the build environment. The build executor must be included in the build image's measurement. -| Build platform client | A platform-provided program that interfaces with the hosted build platform's control plane from within a running build environment. The build platform client must be included in the build image's measurement. +| Build agent | A program that interacts with the hosted build platform's control plane from within a running build environment. The build agent must be included in the build image's measurement. | 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. @@ -211,7 +212,7 @@ All of [BuildEnv L1], plus: - Build Image Producer: - Build images MUST be created via a SLSA [Build L3] or higher build process. - - MUST add support in the build image to: + - **[TODO: revise]** MUST add support in the build image to: - Automatically check build image components against their reference values during build environment startup. In VM-based images, this can be achieved by enabling a [trusted boot] @@ -223,11 +224,11 @@ All of [BuildEnv L1], plus: Provenance (e.g., using [SCAI] or a [VSA]). - MUST automatically generate and distribute signed reference values for the following build image components: bootloader or equivalent, - guest kernel, build platform client, build executor, and root filesystem. + guest kernel, build agent, build executor, and root filesystem. Additional build image components whose initial state is to be checked MAY be also measured. -- Build Platform Requirements: +- **[TODO: revise]** Build Platform Requirements: - MUST meet SLSA [Build L3] requirements. - Prior to deployment of a new build environment, the SLSA Provenance for the selected build image MUST be automatically verified. A signed @@ -269,7 +270,7 @@ a known good environment. All of [BuildEnv L2], plus: -**TODO:** These requirements need to be re-formulated. +**[TODO: These requirements need to be re-formulated.]** - Build Image Producer: - MUST add support in the build image to: @@ -297,7 +298,7 @@ face of a compromised host interface (hypervisor/container orchestrator).
-### BuildEnv L4: Encrypted build environment +### BuildEnv L4: Runtime monitored build environment TODO From 08b92e867f2ce643ced933f94ed4cbb37748033c Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Tue, 17 Sep 2024 17:35:37 -0700 Subject: [PATCH 09/10] Finalize first draft of L2, L3, remove L4 Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 177 +++++++++++-------- 1 file changed, 99 insertions(+), 78 deletions(-) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index 99ea338d7..1a9f51fa6 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -29,18 +29,21 @@ execution context. In this track, provenance describes how a [build image] was created, how the [hosted] build platform deployed a build image in its environment, and the compute platform they used. -| Track/Level | Requirements | Focus -| ------------- | ------------ | ----- -| [BuildEnv L0] | (none) | (n/a) -| [BuildEnv L1] | Signed build image provenance exists | Tampering during build image distribution -| [BuildEnv L2] | Attested build environment instantiation | Tampering via the build platform's control plane -| [BuildEnv L3] | Hardware-authenticated build environment | Tampering via the compute platform's host interface -| [BuildEnv L4] | Runtime monitored build environment | Tampering by the build platform or compute platform during the build - -> [!IMPORTANT] -> The Environment track currently requires a [hosted] build platform. -> A future version of this track may generalize requirements to cover local -> build environments (e.g., developer laptop). +| 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 + +> :warning: +> The Build Environment track 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. ### Build environment model @@ -55,16 +58,15 @@ A typical build environment will go through the following lifecycle: 1. *Build image creation*: A build image producer creates different build images through dedicated build process. For the SLSA Environment track, the build image producer outputs provenance describing this process. - 2. *Build environment instantiation*: The hosted build platform calls - into the *host interface* to create a new build environment from a given - build image. The *build agent* begins to wait for an incoming build - dispatch. - **[TODO: revise]** For the SLSA Environment track, the hosted build - platform attests to the *measurement* of the environment's *initial +2. *Build environment instantiation*: The hosted build platform calls + into the *host interface* to create a new instance of a build environment + from a given build image. The *build agent* begins to wait for an incoming + build dispatch. For the SLSA Environment track, the host interface in the + compute platform attests to the integrity of the environment's *initial state* during its boot process. 3. *Build dispatch*: When the tenant dispatches a new build, the hosted build platform assigns the build to a created build environment. - **[TODO: revise]** For the SLSA Environment track, the build platform + For the SLSA Environment track, the build platform attests to the binding between a build environment and *build ID*. 4. *Build execution*: Finally, the *build executor* running within the environment executes the tenant's build definition. @@ -84,9 +86,9 @@ and roles: | 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 build platform. +| 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 | Hardware-signed data that contains one or more hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata. +| 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. | 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 runner) @@ -178,8 +180,10 @@ integrity for build environments at the time of build image distrbution. - Build Platform: - MUST meet SLSA [Build L2] requirements. - - Prior to deployment of a new build environment, the SLSA Provenance - for the selected build image SHOULD be automatically verified. + - Prior to the instantiation of a new build environment, the SLSA Provenance + for the selected build image MUST be automatically verified. + A signed attestation to the result of the SLSA Provenance verification MUST + be generated and distributed (e.g., via a [VSA]).
Benefits
@@ -196,9 +200,9 @@ source and build process.
Summary
-The build environment is measured and authenticated prior to dispatching -any builds, attesting to the integrity of initial state of the environment -when it's deployed by the build platform. +The build environment is measured and authenticated by the compute platform +upon instantiation, attesting to the integrity of the initial state +of the environment prior to executing a build.
Intended for
@@ -212,32 +216,46 @@ All of [BuildEnv L1], plus: - Build Image Producer: - Build images MUST be created via a SLSA [Build L3] or higher build process. - - **[TODO: revise]** MUST add support in the build image to: - - Automatically check build image components against their - reference values during build environment startup. - In VM-based images, this can be achieved by enabling a [trusted boot] - process. In container-based build images, a dedicated program MUST be - used to perform these checks.[^1] - - Automatically generate and distribute a signed attestation that - the initial state of a given build environment instance has been - verified against the corresponding build image, incl. its SLSA - Provenance (e.g., using [SCAI] or a [VSA]). - MUST automatically generate and distribute signed reference values for the following build image components: bootloader or equivalent, - guest kernel, build agent, build executor, and root filesystem. + guest kernel, build agent, build executor, and root filesystem (e.g., + via the image's SLSA Provenance, or [SCAI]). Additional build image components whose initial state is to be checked MAY be also measured. - -- **[TODO: revise]** Build Platform Requirements: + - The running build environment MUST be capable of: + - Upon completion of the boot process: Automatically interfacing + with the host interface to obtain a signed quote for the + environment's initial state. + - Upon build dispatch: Automatically generating and distributing + a signed attestation that binds its boot process quote to the + assigned build ID (e.g., using [SCAI]). + +- Build Platform Requirements: - MUST meet SLSA [Build L3] requirements. - - Prior to deployment of a new build environment, the SLSA Provenance - for the selected build image MUST be automatically verified. A signed - attestation to the verification of the build image's SLSA Provenance - MUST be automatically generated and distributed (e.g., via a [VSA]). - - Prior to dispatching a tenant's build to a deployed environment, its - initial state attestation MUST be automatically verified. A signed - attestation binding the tenant's build ID to the verified initial state - of the selected build environment MUST be generated and distributed. + - Prior to dispatching a tenant's build to an instantiated environment, + its boot process quote MUST be automatically verified. A signed + attestation to the result of the verification MUST be generated and + distributed (e.g., via a [VSA]). + +- Compute Platform Requirements: + - The host interface MUST be capable of generating signed quotes for + the build environment's system state. + In a VM-based environment, this MUST be achieved by enabling a feature + like [vTPM], or equivalent, in the hypervisor. + For container-based environments, the container orchestrator MAY need + modifications to produce these attestations. + - The host interface MUST validate the measurements of the build image + components against their references values during the build environment's + boot process. + In a VM-based environment, this MUST be achieved by enabling a process + like [Secure Boot], or equivalent, in the hypervisor. + For container-based environments, the container orchestrator MAY need + modifications to perform these checks.[^1] + - Prior to instantiating a new build environment, the host interface + MUST automatically verify the SLSA Provenance for the selected build + image. A signed attestation to the verification of the build image's + SLSA Provenance MUST be automatically generated and distributed (e.g., + via a [VSA]).
Benefits
@@ -251,59 +269,62 @@ adversary.
-### BuildEnv L3: Hardware-authenticated build environment +### BuildEnv L3: Hardware-attested build environment
Summary
-The initial state of the build environment is measured and autenticated by -trusted hardware, and the build ID is verifiably bound to the -deployed build environment, attesting to the integrity of the environment -when a tenant's build is first dispatched. +The initial state of the build's host environment is measured +and autenticated by trusted hardware, attesting to the integrity +of the build environment's underlying compute stack prior to executing +a build.
Intended for
-Organizations wanting strong assurances that their build was dispatched in -a known good environment. +Organizations wanting strong assurances that their build ran on a good +known host environment.
Requirements
All of [BuildEnv L2], plus: -**[TODO: These requirements need to be re-formulated.]** - - Build Image Producer: - - MUST add support in the build image to: - - Use trusted hardware to check build image component reference - values and integrity of the build environment startup. - - Automatically generate and distribute a signed attestation - that a given build ID was dispatched in the corresponding build - environment instance, incl. its initial state attestation (e.g., - using [SCAI] or a [VSA]). - - Use trusted hardware to sign all build image-generated - attestations. - -- Build Platform Requirements: TODO - -- Compute Platform Requirements: TODO + - Upon completion of the boot process: The running build environment + MUST be capable of automatically interfacing with the *trusted hardware* + component to obtain a signed quote for the host interface's boot process + quote and the environment's initial state. + - Upon build dispatch: The generated dispatch attestation MUST include + the host interface's boot process quote. + +- Build Platform Requirements: + - Prior to dispatching a tenant's build to an instantiated environment, + the *host interface's* boot process quote MUST be automatically verified. + A signed attestation to the result of the verification MUST be generated + and distributed (e.g., via a [VSA]). + +- Compute Platform Requirements: + - MUST have trusted hardware capabilities, i.e., built-in physical + hardware features for generating measurements and quotes for its system + state. This SHOULD be achieved using a feature like [TPM], + [confidential computing], or equivalent. + - MUST enable validation of the host interface's boot process against + its reference values. This MUST be achieved by enabling a process + like [Secure Boot], or equivalent, in the host platform.
Benefits
-Provides hardware-authenticated evidence that a build running on a hosted -build platform was dispatched in the expected build environment, even in the -face of a compromised host interface (hypervisor/container orchestrator). +Provides hardware-authenticated evidence that a build ran in the expected host +environment, even in the face of a compromised host interface +(hypervisor/container orchestrator).
-
-### BuildEnv L4: Runtime monitored build environment +## Considerations for Distributed Builds TODO -
- [^1]: Since containers are executed as processes on the host platform they do not contain a traditional bootloader that starts up the execution context. @@ -317,11 +338,11 @@ TODO [BuildEnv L1]: #buildenv-l1 [BuildEnv L2]: #buildenv-l2 [BuildEnv L3]: #buildenv-l3 -[BuildEnv L4]: #buildenv-l4 [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 [VSA]: verification_summary.md [build image]: #definitions [build model]: terminology.md#build-model [hosted]: requirements.md#isolation-strength [several classes]: #build-environment-threats -[trusted boot]: https://csrc.nist.gov/glossary/term/trusted_boot +[vTPM]: https://trustedcomputinggroup.org/about/what-is-a-virtual-trusted-platform-module-vtpm/ From 6f64be6cdfb9522f6d33833410b5554c7493e8a5 Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Wed, 18 Sep 2024 09:26:34 -0700 Subject: [PATCH 10/10] Fix typo Signed-off-by: Marcela Melara --- docs/spec/draft/attested-build-env-levels.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/attested-build-env-levels.md b/docs/spec/draft/attested-build-env-levels.md index 1a9f51fa6..7fb0cb33a 100644 --- a/docs/spec/draft/attested-build-env-levels.md +++ b/docs/spec/draft/attested-build-env-levels.md @@ -168,7 +168,7 @@ integrity for build environments at the time of build image distrbution.
Requirements
- Build Image Producer: - - MUST automatially generate SLSA [Build L2] or higher + - MUST automatically generate SLSA [Build L2] or higher Provenance for created build images (i.e., VM or container images). - MUST allow independent automatic verification of a build image's SLSA Provenance. If the build image artifact cannot be published, for example