From e5058717ba3f0c1320d505b3d963178c8aa11058 Mon Sep 17 00:00:00 2001 From: Marcela Melara Date: Tue, 30 Jul 2024 11:35:33 -0700 Subject: [PATCH] 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 ++++++++++ .../draft/attested-build-env-requirements.md | 411 ++++++++++++++++++ 2 files changed, 646 insertions(+) create mode 100644 docs/spec/draft/attested-build-env-levels.md create mode 100644 docs/spec/draft/attested-build-env-requirements.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 diff --git a/docs/spec/draft/attested-build-env-requirements.md b/docs/spec/draft/attested-build-env-requirements.md new file mode 100644 index 000000000..9736a57ad --- /dev/null +++ b/docs/spec/draft/attested-build-env-requirements.md @@ -0,0 +1,411 @@ +--- +title: Producing artifacts +description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers. +--- + + +This page covers the detailed technical requirements for producing artifacts at +each SLSA level. The intended audience is platform implementers and security +engineers. + +For an informative description of the levels intended for all audiences, see +[Levels](levels.md). For background, see [Terminology](terminology.md). To +better understand the reasoning behind the requirements, see +[Threats and mitigations](threats.md). + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +## Overview + +### Build levels + +In order to produce artifacts with a specific build level, responsibility is +split between the [Producer] and [Build platform]. The build platform MUST +strengthen the security controls in order to achieve a specific level while the +producer MUST choose and adopt a build platform capable of achieving a desired +build level, implementing any controls as specified by the chosen platform. + + + + + + + + + + + + +
Implementer + Requirement + Degree + L1L2L3L4 +
Producer + Choose an appropriate build platform + ✓✓✓✓ +
Follow a consistent build process + ✓✓✓✓ +
Distribute provenance + ✓✓✓✓ +
Build platform + Provenance generation + Exists + ✓✓✓✓ +
Authentic + ✓✓✓ +
Unforgeable + ✓✓ +
Isolation strength + Hosted + ✓✓✓ +
Isolated + ✓✓ +
Hardware-Attested + ✓ +
+ +### Security Best Practices + +While the exact definition of what constitutes a secure platform is beyond the +scope of this specification, all implementations MUST use industry security +best practices to be conformant to this specification. This includes, but is +not limited to, using proper access controls, securing communications, +implementing proper management of cryptographic secrets, doing frequent updates, +and promptly fixing known vulnerabilities. + +Various relevant standards and guides can be consulted for that matter such as +the [CIS Critical Security +Controls](https://www.cisecurity.org/controls/cis-controls-list). + +## Producer + +[Producer]: #producer + +A package's producer is the organization that owns and releases the +software. It might be an open-source project, a company, a team within a +company, or even an individual. + +NOTE: There were more requirements for producers in the initial +[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted +how a package can be built. These were removed in the v1.0 specification and +will be reassessed and re-added as indicated in the +[future directions](future-directions.md). + +### Choose an appropriate build platform + +The producer MUST select a build platform that is capable of reaching their +desired SLSA Build Level. + +For example, if a producer wishes to produce a Build Level 3 artifact, they MUST +choose a builder capable of producing Build Level 3 provenance. + +### Follow a consistent build process + +The producer MUST build their artifact in a consistent +manner such that verifiers can form expectations about the build process. In +some implementations, the producer MAY provide explicit metadata to a verifier +about their build process. In others, the verifier will form their expectations +implicitly (e.g. trust on first use). + +If a producer wishes to distribute their artifact through a [package ecosystem] +that requires explicit metadata about the build process in the form of a +configuration file, the producer MUST complete the configuration file and keep +it up to date. This metadata might include information related to the artifact's +source repository and build parameters. + +### Distribute provenance + +The producer MUST distribute provenance to artifact consumers. The producer +MAY delegate this responsibility to the +[package ecosystem], provided that the package ecosystem is capable of +distributing provenance. + +## Build Platform + +[Build platform]: #build-platform + +A package's build platform is the infrastructure used to transform the +software from source to package. This includes the transitive closure of all +hardware, software, persons, and organizations that can influence the build. A +build platform is often a hosted, multi-tenant build service, but it could be a +system of multiple independent rebuilders, a special-purpose build platform used +by a single software project, or even an individual's workstation. Ideally, one +build platform is used by many different software packages so that consumers can +[minimize the number of trusted platforms](principles.md). For more background, +see [Build Model](terminology.md#build-model). + +The build platform is responsible for providing two things: [provenance +generation] and [isolation between builds]. The [Build level](levels.md#build-track) describes +the degree to which each of these properties is met. + +### Provenance generation + +[Provenance generation]: #provenance-generation + +The build platform is responsible for generating provenance describing how the +package was produced. + +The SLSA Build level describes the overall provenance integrity according to +minimum requirements on its: + +- *Completeness:* What information is contained in the provenance? +- *Authenticity:* How strongly can the provenance be tied back to the builder? +- *Accuracy:* How resistant is the provenance generation to tampering within + the build process? + + +
RequirementDescriptionL1L2L3L4 + +
Provenance Exists + +The build process MUST generate provenance that unambiguously identifies the +output package by cryptographic digest and describes how that package was +produced. The format MUST be acceptable to the [package ecosystem] and/or +[consumer](verifying-artifacts.md#consumer). + +It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] +because it is designed to be interoperable, universal, and unambiguous when +used for SLSA. See that format's documentation for requirements and +implementation guidelines. + +If using an alternate format, it MUST contain the equivalent information as SLSA +Provenance at each level and SHOULD be bi-directionally translatable to SLSA +Provenance. + +- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient + information to catch mistakes and simulate the user experience at higher + levels in the absence of tampering. In other words, the contents of the + provenance SHOULD be the same at all Build levels, but a few fields MAY be + absent at L1 if they are prohibitively expensive to implement. +- *Authenticity:* No requirements. +- *Accuracy:* No requirements. + +[SLSA Provenance]: provenance.md +[associated suite]: ../../attestation-model#recommended-suite + +✓✓✓✓ +
Provenance is Authentic + +*Authenticity:* Consumers MUST be able to validate the authenticity of the +provenance attestation in order to: + +- *Ensure integrity:* Verify that the digital signature of the provenance + attestation is valid and the provenance was not tampered with after the + build. +- *Define trust:* Identify the build platform and other entities that are + necessary to trust in order to trust the artifact they produced. + +This SHOULD be through a digital signature from a private key accessible only +to the build platform component that generated the provenance attestation. + +While many constraints affect choice of signing methodologies, it is +RECOMMENDED that build platforms use signing methodologies which improve the +ability to detect and remediate key compromise, such as methods which rely on +transparency logs or, when transparency isn't appropriate, time stamping +services. + +Authenticity allows the consumer to trust the contents of the provenance +attestation, such as the identity of the build platform. + +*Accuracy:* The provenance MUST be generated by the control plane (i.e. within +the trust boundary [identified in the provenance]) and not by a tenant of the +build platform (i.e. outside the trust boundary), except as noted below. + +- The data in the provenance MUST be obtained from the build platform, either + because the generator *is* the build platform or because the provenance + generator reads the data directly from the build platform. +- The build platform MUST have some security control to prevent tenants from + tampering with the provenance. However, there is no minimum bound on the + strength. The purpose is to deter adversaries who might face legal or + financial risk from evading controls. +- Exceptions for fields that MAY be generated by a tenant of the build platform: + - The names and cryptographic digests of the output artifacts, i.e. + `subject` in [SLSA Provenance]. See [forge output digest of the + provenance](threats#forged-digest) for explanation of why this is + acceptable. + - Any field that is not marked as REQUIRED for Build L2. For example, + `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at + Build L2. Builders SHOULD document any such cases of tenant-generated + fields. + +*Completeness:* SHOULD be complete. + +- There MAY be [external parameters] that are not sufficiently captured in + the provenance. +- Completeness of resolved dependencies is best effort. + + ✓✓✓ +
Provenance is Unforgeable + +*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. + +- Any secret material used for authenticating the provenance, for example the + signing key used to generate a digital signature, MUST be stored in a secure + management system appropriate for such material and accessible only to the + build service account. +- Such secret material MUST NOT be accessible to the environment running + the user-defined build steps. +- Every field in the provenance MUST be generated or verified by the build + platform in a trusted control plane. The user-controlled build steps MUST + NOT be able to inject or alter the contents, except as noted in [Provenance + is Authentic](#provenance-authentic). (Build L3 does not require additional + fields beyond those of L2.) + +*Completeness:* SHOULD be complete. + +- [External parameters] MUST be fully enumerated. +- Completeness of resolved dependencies is best effort. + +Note: This requirement was called "non-falsifiable" in the initial +[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). + + ✓✓ +
+ +TODO: Add completeness of resolved dependencies + +### Isolation strength + +[Isolation strength]: #isolation-strength +[Isolation between builds]: #isolation-strength + +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). + + + + + +
RequirementDescriptionL1L2L3L4 + +
Hosted + + +All build steps ran using a hosted build platform on shared or dedicated +infrastructure, not on an individual's workstation. + +Examples: GitHub Actions, Google Cloud Build, Travis CI. + + ✓✓✓ +
Isolated + + +The build platform ensured that the build steps ran in an isolated environment, +free of unintended external influence. In other words, any external influence on +the build was specifically requested by the build itself. This MUST hold true +even between builds within the same tenant project. + +The build platform MUST guarantee the following: + +- It MUST NOT be possible for a build to access any secrets of the build + platform, such as the provenance signing key, because doing so would + compromise the authenticity of the provenance. +- It MUST NOT be possible for two builds that overlap in time to influence one + another, such as by altering the memory of a different build process running + on the same machine. +- It MUST NOT be possible for one build to persist or influence the build + environment of a subsequent build. In other words, an ephemeral build + environment MUST be provisioned for each build. +- It MUST NOT be possible for one build to inject false entries into a build + cache used by another build, also known as "cache poisoning". In other + words, the output of the build MUST be identical whether or not the cache is + used. +- The build platform MUST NOT open services that allow for remote influence + unless all such interactions are captured as `externalParameters` in the + provenance. + +There are no sub-requirements on the build itself. Build L3 is limited to +ensuring that a well-intentioned build runs securely. It does not require that +a build platform prevents a producer from performing a risky or insecure build. In +particular, the "Isolated" requirement does not prohibit a build from calling +out to a remote execution service or a "self-hosted runner" that is outside the +trust boundary of the build platform. + +NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" +in the initial [draft version (v0.1)](../v0.1/requirements.md). + +NOTE: This requirement is not to be confused with "Hermetic", which roughly +means that the build ran with no network access. Such a requirement requires +substantial changes to both the build platform and each individual build, and is +considered in the [future directions](future-directions.md). + + ✓✓ +
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