From d021501662a19ac4558dd0b37ec8efa77538c9fd Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Tue, 23 Dec 2025 03:22:45 -0800 Subject: [PATCH 1/3] need new file for real-world stuff --- docs/spec/draft/real-world-examples.md | 207 +++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 docs/spec/draft/real-world-examples.md diff --git a/docs/spec/draft/real-world-examples.md b/docs/spec/draft/real-world-examples.md new file mode 100644 index 000000000..0771f468a --- /dev/null +++ b/docs/spec/draft/real-world-examples.md @@ -0,0 +1,207 @@ +## Mapping to real-world ecosystems + +Most real-world ecosystems fit the package model above but use different terms. +The table below attempts to document how various ecosystems map to the SLSA +Package model. There are likely mistakes and omissions; corrections and +additions are welcome! + + + + + + + + + + + + + + + + + + + + + + + + + + +
Package ecosystem + Package registry + Package name + Package artifact +
Languages +
Cargo (Rust) + Registry + Crate name + Artifact +
CPAN (Perl) + PAUSE + Distribution + Release (or Distribution) +
Go + Module proxy + Module path + Module +
Maven (Java) + Repository + Group ID + Artifact ID + Artifact +
npm (JavaScript) + Registry + Package Name + Package +
NuGet (C#) + Host + Project + Package +
PyPA (Python) + Index + Project Name + Distribution +
Operating systems +
Dpkg (e.g. Debian) + ? + Package name + Package +
Flatpak + Repository + Application + Bundle +
Homebrew (e.g. Mac) + Repository (Tap) + Package name (Formula) + Binary package (Bottle) +
Pacman (e.g. Arch) + Repository + Package name + Package +
RPM (e.g. Red Hat) + Repository + Package name + Package +
Nix (e.g. NixOS) + Repository (e.g. Nixpkgs) or binary cache + Derivation name + Derivation or store object +
Storage systems +
GCS + n/a + Object name + Object +
OCI/Docker + Registry + Repository + Object +
Meta +
deps.dev: System + Packaging authority + Package + n/a +
purl: type + Namespace + Name + n/a +
+ +Notes: + +- [Go](https://go.dev) (golang) uses a significantly different distribution model than other ecosystems. + In Go, the package name is a source repository URL. While clients can fetch + directly from that URL---in which case there is no "package" or + "registry"---they usually fetch a zip file from a *module proxy*. The module + proxy acts as both a builder (by constructing the package artifact from + source) and a registry (by mapping package name to package artifact). People + trust the module proxy because builds are independently reproducible, and a + *checksum database* guarantees that all clients receive the same artifact + for a given URL. + +### Real-world supply chain examples + +Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: + + + + + + + + + + + + + + + +
+Threats from +Known example +How SLSA could help +
A +Producer +SpySheriff: Software producer purports to offer anti-spyware software, but that software is actually malicious. +SLSA does not directly address this threat but could make it easier to discover malicious behavior in open source software, by forcing it into the publicly available source code. +For closed source software SLSA does not provide any solutions for malicious producers. +
B +Authoring & reviewing +SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. +Two-person review could have caught the unauthorized change. +
C +Source code management +PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. +A better-protected source code system would have been a much harder target for the attackers. +
D +External build parameters +The Great Suspender: Attacker published software that was not built from the purported sources. +A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. +
E +Build process +SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. +Higher SLSA Build levels have stronger security requirements for the build platform, making it more difficult for an attacker to forge the SLSA provenance and gain persistence. +
F +Artifact publication +CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. +Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. +
G +Distribution channel +Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. +Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. +
H +Package selection +Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. +SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. +
I +Usage +Default credentials: Attacker could leverage default credentials to access sensitive data. +SLSA does not address this threat. +
N/A +Dependency threats (i.e. A-H, recursively) +event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code. +Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source. +
+ + + + + + +
+Availability threat +Known example +How SLSA could help +
N/A +Dependency becomes unavailable +Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. +SLSA does not directly address this threat. +
+ +A SLSA level helps give consumers confidence that software has not been tampered +with and can be securely traced back to source—something that is difficult, if +not impossible, to do with most software today. + + \ No newline at end of file From 3695034f6a07e5c28c09a559b5869de90ed87a79 Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Thu, 22 Jan 2026 20:46:13 -0800 Subject: [PATCH 2/3] renaming files for consistency, no content changes --- docs/spec/draft/build-track-assessment.md | 254 +++++++++++++++ docs/spec/draft/build-track-basics.md | 188 ++++++++++- docs/spec/draft/build-track-provenance.md | 188 +++++++++++ docs/spec/draft/build-track-requirements.md | 344 ++++++++++++++++++++ docs/spec/draft/build-track-verification.md | 316 ++++++++++++++++++ 5 files changed, 1283 insertions(+), 7 deletions(-) create mode 100644 docs/spec/draft/build-track-assessment.md create mode 100644 docs/spec/draft/build-track-provenance.md create mode 100644 docs/spec/draft/build-track-requirements.md create mode 100644 docs/spec/draft/build-track-verification.md diff --git a/docs/spec/draft/build-track-assessment.md b/docs/spec/draft/build-track-assessment.md new file mode 100644 index 000000000..b862124ce --- /dev/null +++ b/docs/spec/draft/build-track-assessment.md @@ -0,0 +1,254 @@ +--- +title: "Build: Assessing build platforms" +description: This page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. +--- + +# {Build Track: Assessing Build Platforms} + +**About this page:** the *Build Track: Accessing Build Platforms* page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. + +**Intended audience:** {add appropriate audience} + +**Topics covered:** adversary behavior, sample prompts to access build platform security + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) + +>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). + +**For more information see:** [Threats & mitigations](threats.md) and the [build model](build-track-basics.md#build-model). + +## Overview + +One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify +artifacts". However, consumers cannot trust platforms to produce Build L3 +artifacts and provenance unless they have proof that the provenance is +[unforgeable](build-requirements.md#provenance-unforgeable) and the builds are +[isolated](build-requirements.md#isolated). This document provides sample prompts consumers can use to assess a build platform and measure its security level. + +## Threats + +SLSA's purpose is to help people defend against adversaries that threaten the software supply chain. By understanding adversary goals and profiles, you can assess your build platform more easily. + +### The adversary's goals + +The SLSA Build track defends against an adversary whose primary goal is to +inject unofficial behavior into a package artifact while avoiding detection. +Remember that [verifiers](verifying-artifacts.md) only accept artifacts whose +provenance matches expectations. To bypass this, the adversary tries to either +(a) tamper with a legitimate build whose provenance already matches +expectations, or (b) tamper with an illegitimate build's provenance to make it +match expectations. + +More formally, if a build with external parameters P would produce an artifact +with binary hash X and a build with external parameters P' would produce an +artifact with binary hash Y, they wish to produce provenance indicating a build +with external parameters P produced an artifact with binary hash Y. + +See threats [D], [E], [F], and [G] for examples of specific threats. + +**Note:** Platform abuse (e.g. running non-build workloads) and attacks against +builder availability are out of scope of this document. + +### Adversary profiles + +Consumers SHOULD also evaluate the build platform's ability to defend against the +following types of adversaries. + +1. Project contributors, who can: + - Create builds on the build platform. These are the adversary's controlled + builds. + - Modify one or more controlled builds' external parameters. + - Modify one or more controlled builds' environments and run arbitrary + code inside those environments. + - Read the target build's source repo. + - Fork the target build's source repo. + - Modify a fork of the target build's source repo and build from it. +2. Project maintainer, who can: + - Do everything listed under "project contributors". + - Create new builds under the target build's project or identity. + - Modify the target build's source repo and build from it. + - Modify the target build's configuration. +3. Build platform administrators, who can: + - Do everything listed under "project contributors" and "project + maintainers". + - Run arbitrary code on the build platform. + - Read and modify network traffic. + - Access the control plane's cryptographic secrets. + - Remotely access build environments (e.g. via SSH). + +[D]: threats.md#d-external-build-parameters +[E]: threats.md#e-build-process +[F]: threats.md#f-artifact-publication +[G]: threats.md#g-distribution-channel + +## Build platform components to assess + +Consumers SHOULD consider at least these five elements of the +[build model](terminology.md#build-model) when assessing build platforms for SLSA +conformance: external parameters, control plane, build environments, caches, +and outputs. + +![image](images/build-model.svg) + +The following sections detail these elements of the build model and give prompts +for assessing a build platform's ability to produce SLSA Build L3 provenance. +The assessment SHOULD take into account the security model used to identify the +transitive closure of the `builder.id` for the +[provenance model](build-provenance.md#model), specifically around the +platform's boundaries, actors, and interfaces. + +### External parameter of the build process + +External parameters are the external interface to the builder and include all +inputs to the build process. Examples include the source to be built, the build +definition/script to be executed, user-provided instructions to the +control plane for how to create the build environment (e.g. which operating +system to use), and any additional user-provided strings. + +#### Sample prompts for assessing external parameters + +- How does the control plane process user-provided external parameters? + Examples: sanitizing, parsing, not at all +- Which external parameters are processed by the control plane and which are + processed by the build environment? +- What sort of external parameters does the control plane accept for + build environment configuration? +- How do you ensure that all external parameters are represented in the + provenance? +- How will you ensure that future design changes will not add additional + external parameters without representing them in the provenance? + +### Control plane component + +The control plane is the build platform component that orchestrates each +independent build execution. It is responsible for setting up each build and +cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs +provenance for each build performed on the build platform. The control plane is +operated by one or more administrators, who have privileges to modify the +control plane. + +#### Sample prompts for assessing the control plane + +- Administration + - What are the ways an employee can use privileged access to influence a + build or provenance generation? Examples: physical access, terminal + access, access to cryptographic secrets + - What controls are in place to detect or prevent the employee from + abusing such access? Examples: two-person approvals, audit logging, + workload identities + - Roughly how many employees have such access? + - How are privileged accounts protected? Examples: two-factor + authentication, client device security policies + - What plans do you have for recovering from security incidents and platform + outages? Are they tested? How frequently? + +- Provenance generation + - How does the control plane observe the build to ensure the provenance's + accuracy? + - Are there situations in which the control plane will not generate + provenance for a completed build? What are they? + +- Development practices + - How do you track the control plane's software and configuration? + Example: version control + - How do you build confidence in the control plane's software supply + chain? Example: SLSA L3+ provenance, build from source + - How do you secure communications between builder components? Example: + TLS with certificate transparency. + - Are you able to perform forensic analysis on compromised build + environments? How? Example: retain base images indefinitely + +- Creating build environments + - How does the control plane share data with build environments? Example: + mounting a shared file system partition + - How does the control plane protect its integrity from build + environments? Example: not mount its own file system partitions on + build environments + - How does the control plane prevent build environments from accessing its + cryptographic secrets? Examples: dedicated secret storage, not mounting + its own file system partitions to build environments, hardware security + modules + +- Managing cryptographic secrets + - How do you store the control plane's cryptographic secrets? + - Which parts of the organization have access to the control plane's + cryptographic secrets? + - What controls are in place to detect or prevent employees abusing such + access? Examples: two-person approvals, audit logging + - How are secrets protected in memory? Examples: secrets are stored in + hardware security modules and backed up in secure cold storage + - How frequently are cryptographic secrets rotated? Describe the rotation + process. + - What is your plan for remediating cryptographic secret compromise? How + frequently is this plan tested? + +### Build environment execution context + +The build environment is the independent execution context where the build +takes place. In the case of a distributed build, the build environment is the +collection of all execution contexts that run build steps. Each build +environment must be isolated from the control plane and from all other build +environments, including those running builds from the same tenant or project. +Tenants are free to modify the build environment arbitrarily. Build +environments must have a means to fetch input artifacts (source, dependencies, +etc). + +#### Sample prompts for assessing build environments + +- Isolation technologies + - How are build environments isolated from the control plane and each + other? Examples: VMs, containers, sandboxed processes + - How is separation achieved between trusted and untrusted processes? + - How have you hardened your build environments against malicious tenants? + Examples: configuration hardening, limiting attack surface + - How frequently do you update your isolation software? + - What is your process for responding to vulnerability disclosures? What + about vulnerabilities in your dependencies? + - What prevents a malicious build from gaining persistence and influencing + subsequent builds? + +- Creation and destruction + - What operating system and utilities are available in build environments + on creation? How were these elements chosen? Examples: A minimal Linux + distribution with its package manager, OSX with HomeBrew + - How long could a compromised build environment remain active in the + build platform? + +- Network access + - Are build environments able to call out to remote execution? If so, how + do you prevent them from tampering with the control plane or other build + environments over the network? + - Are build environments able to open services on the network? If so, how + do you prevent remote interference through these services? + +### Cache issues + +Builders may have zero or more caches to store frequently used dependencies. +Build environments may have either read-only or read-write access to caches. + +#### Sample prompts for assessing caches + +- What sorts of caches are available to build environments? +- How are those caches populated? +- How are cache contents validated before use? + +### Output storage types + +Output Storage holds built artifacts and their provenance. Storage may either be +shared between build projects or allocated separately per-project. + +#### Sample prompts for assessing output storage + +- How do you prevent builds from reading or overwriting files that belong to + another build? Example: authorization on storage +- What processing, if any, does the control plane do on output artifacts? + +## Builder evaluation procedures + +Organizations can either self-attest to their answers or seek certification from +a third-party auditor. Evidence for self-attestation should be published on +the internet and can include information such as the security model defined as +part of the provenance. Evidence submitted for third-party certification need not +be published. diff --git a/docs/spec/draft/build-track-basics.md b/docs/spec/draft/build-track-basics.md index eccbc36b6..30c2512c5 100644 --- a/docs/spec/draft/build-track-basics.md +++ b/docs/spec/draft/build-track-basics.md @@ -1,7 +1,181 @@ --- -title: "Build: Track Basics" -description: The SLSA build track is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This page is a descriptive overview of the SLSA build track levels, describing their intent. ---- +title: "Build Track: Basics" +description: This page introduces the SLSA build track part of the supply chain and the levels it uses to create software artifacts and and their security requirements. +--- + +# {Build Track: Basics} + +**About this page:** the *Build Track: Basics* page introduces the SLSA build track part of the supply chain and the levels it uses to create software artifacts and their security requirements. + +**Intended audience:** everyone + +**Topics covered:** build track terminology, concept models, track levels + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} + +>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). + +**For more information, see:** {optional} + +## Overview + +The SLSA build track consists of a series of provenance levels that provide increasing supply chain security guarantees. The amount of security you want to apply is called a level. The levels go from Level 0 (none) to Level 3 (most). A high level of provenance gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. + +## Build Terminology + +These terms apply to SLSA Build track. See the general terminology [list](terms-generic.md) for terms used throughout the SLSA specification. + +| Term | Definition | +| --- | --- | +| Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane. | +| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform. | +| Build caches | An intermediate artifact storage managed by the platform that maps intermediate artifacts to their explicit inputs. A build may share build caches with any subsequent build running on the platform. | +| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. | +| Control plane | Build platform component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control. | +| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. | +| Distribution platform | An entity responsible for mapping package names to immutable package artifacts. | +| Expectations | Defined by the producer's security personnel and stored in a database. | +| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build. | +| Outputs | Collection of artifacts produced by the build. | +| Package | An identifiable unit of software intended for distribution, ambiguously meaning either an "artifact" or a "package name". Only use this term when the ambiguity is acceptable or desirable. | +| Package artifact | A file or other immutable object that is intended for distribution. | +| Package ecosystem | A set of rules and conventions governing how packages are distributed, including how clients resolve a package name into one or more specific artifacts. | +| Package manager client | Client-side tooling to interact with a package ecosystem. | +| Package name |

The primary identifier for a mutable collection of artifacts that all represent different versions of the same software. This is the primary identifier that consumers use to obtain the software.

A package name is specific to an ecosystem + registry, has a maintainer, is more general than a specific hash or version, and has a "correct" source location. A package ecosystem may group package names into some sort of hierarchy, such as the Group ID in Maven, though SLSA does not have a special term for this. | +| Package registry | A specific type of "distribution platform" used within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. | +| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations. | +| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters. | +| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. | +| Publish [a package] | Make an artifact available for use by registering it with the package registry. In technical terms, this means associating an artifact to a package name. This does not necessarily mean making the artifact fully public; an artifact may be published for only a subset of users, such as internal testing or a closed beta. | +| Steps | The set of actions that comprise a build, defined by the tenant. | +| Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters. | + +### Build track terms to avoid + +These terms can be ambiguous and should be avoided. + +| Term | Reason to avoid | +| --- | --- | +| Build recipe | Could mean external parameters, but may include concrete steps of how to perform a build. To avoid implementation details, we don't define this term, but always use "external parameters" which is the interface to a build platform. Similar terms are build configuration source and build definition. | +| Builder | Usually means build platform, but might be used for build environment, the user who invoked the build, or a build tool from dependencies. To avoid confusion, we always use "build platform". The only exception is in the provenance, where builder is used as a more concise field name. | + +## Build track concept models + +This section introduces software manufacturing models that SLSA uses to define the production of software artifacts, the distribution of artifact provenance, and the verification process. + +### Build production process model + +When SLSA's build model defines the production process of software artifacts, the build runs on a multi-tenant *build platform*, where each execution is independent. + +The diagram below shows the build model workflow. + +

Model Build

+ +#### Build workflow steps + +1. A tenant invokes the build by specifying *external parameters* through an + *interface*, either directly or via a trigger. Typically, at least one of + these external parameters is a reference to a *dependency*. External + parameters are literal values while dependencies are artifacts. +2. The build platform's *control plane* interprets these external parameters, + fetches an initial set of dependencies, initializes a *build environment*, + and then starts the execution within that environment. +3. The build then performs arbitrary steps (which might include fetching + additional dependencies) and produces one or more *output* artifacts. + Because the steps within the build environment are under the tenant's control, + the build platform isolates build environments from each other in accordance with the SLSA Build Level. +4. Finally, for SLSA Build L2+, the control plane outputs *provenance* information, + describing the whole process. + +**Note:** there is no formal definition of "source" in the build model, just external +parameters and dependencies. Most build platforms have an explicit "source" +artifact to fetch, which is often a Git repository. The +reference to the artifact is an external parameter, but the artifact itself is +a dependency. + +For examples of how this model applies to real-world build platforms, see [provenance](provenance.md). + +### Distribution of the artifact provenance model + +SLSA's distribution model generates artifact provenance to guarantee the integrity of the distribution of software packages, once they are manufactured. These packages are created according to the rules and conventions of standard package ecosystems. +Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), +[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and +[OCI](https://github.com/opencontainers/distribution-spec), while examples of +informal ecosystems include links to files on a website or distribution of +first-party software within a company. + +As an example, a consumer locates software within an ecosystem by asking a +distribution platform, such as a package registry, to resolve a +mutable package name into an immutable package artifact. + +To publish a package artifact, the software producer asks +the registry to update a mapping to resolve to the new artifact. The registry +represents the entity or entities with the power to alter what artifacts are +accepted by consumers for a given package name. For example, if consumers only +accept packages signed by a particular public key, then the access to the +public key serves as the registry. + +The package name is the primary security boundary within a package ecosystem. +Different package names represent separate pieces of +software, such as different owners, behaviors, security properties, and so on. +As a result, *the package name is the primary unit being protected in SLSA*. +It is the primary identifier to which consumers attach expectations. + +**Note:** This resolution might include a version number, label, or some other + selector in addition to the package name, but that is not important to SLSA. + +### Verification of the artifact provenance model + +SLSA verifies artifact provenance in two ways: + +- **Build platform certification** ensures conformance to the level requirements specified by +the build platform. This certification should happen on a recurring cadence, with +the outcomes published by the platform operator for their users to review and +make informed decisions about which builders to trust. +- **Artifact verification** ensures that artifacts meet the producer-defined +expectations of where the package source code was retrieved and on what +build platform the package was built. + +The diagram below shows how SLSA verifies artifact provenance. + +![Verification Model](images/verification-model.svg) + +#### Verification diagram terminology + +| Term | Description +| ---- | ---- +| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, either explicitly or implicitly. +| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. +| Build platform assessment | [Build platforms are assessed](assessing-build-platforms.md) for their ability to meet SLSA requirements at the stated level. + +The examples below suggest ways that expectations and verification can be +implemented for different and broadly-defined package ecosystems. + +
Example: Small software team + +| Term | Example +| ---- | ------- +| Expectations | Defined by the producer's security personnel and stored in a database. +| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. +| Build platform assessment | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their adherence to SLSA requirements. + +
+ +
Example: Open source language distribution + +| Term | Example +| ---- | ------- +| Expectations | Defined separately for each package and stored in the package registry. +| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. +| Build platform assessment | Performed by the language ecosystem packaging authority. + +
+ +## Build Track Levels + +Provenance describes how the artifact was created. Levels define the type of provenance. Each type gives you a different kind of security, with the zero being the lowest level and 3 providing the most security. | Track/Level | Requirements | Focus | ----------- | ------------ | ----- @@ -20,7 +194,7 @@ hermeticity or completeness of provenance -->
-## Build L0: No guarantees +### Build L0: No guarantees
Summary
@@ -44,7 +218,7 @@ n/a
-## Build L1: Provenance exists +### Build L1: Provenance exists
Summary
@@ -92,7 +266,7 @@ SLSA---other than tamper protection---without changing their build workflows.
-## Build L2: Hosted build platform +### Build L2: Hosted build platform
Summary
@@ -147,7 +321,7 @@ All of [Build L1], plus: [^sign]: Alternate means of verifying the authenticity of the provenance are also acceptable. -## Build L3: Hardened builds +### Build L3: Hardened builds
Summary
diff --git a/docs/spec/draft/build-track-provenance.md b/docs/spec/draft/build-track-provenance.md new file mode 100644 index 000000000..a297822b1 --- /dev/null +++ b/docs/spec/draft/build-track-provenance.md @@ -0,0 +1,188 @@ +--- +title: "Build: Distributing provenance" +description: This document provides specifications for distributing provenance and the +relationship between build artifacts and provenance. +--- + +# { Build Track: Distributing Provenance} + +**About this page:** the *Build Track Distributing Provenance* page provides specifications for distributing provenance and the +relationship between build artifacts and provenance. + +**Intended audience:** platform implementers and software distributors + +**Topics covered:** build provenance attestations + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) + +>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). + +**For more information, see:** {optional} + +## Overview + +In order to make provenance for artifacts available after generation +for verification, SLSA requires the distribution and verification of provenance +metadata in the form of SLSA attestations. + +This document focuses on artifacts for ecosystems that distribute build +artifacts, but some attention is also paid to ecosystems that distribute +container images or only distribute source artifacts, as many of the same +principles generally apply to any artifact or group of artifacts. + +In addition, this document is primarily for the benefit of artifact +distributors, to understand how they can adopt the distribution of SLSA +provenance. It is primarily concerned with the means of distributing +attestations and the relationship of attestations to build artifacts, and not +with the specific format of the attestation itself. + +## Build provenance attestations + +The process of creating and distributing build attestations requires addressing the following issues: + +### Maintainer responsibilities + +The [package ecosystem]'s maintainers are responsible for reliably +redistributing artifacts and provenance, making the producers' expectations +available to consumers, and providing tools to enable safe artifact consumption +(e.g., whether an artifact meets its producer's expectations). + +### Relationship between releases and attestations + +Attestations SHOULD be bound to artifacts, not releases. + +A single "release" of a project, package, or library might include multiple +artifacts. These artifacts result from builds on different platforms, +architectures, or environments. The builds need not happen at roughly the same +point in time and might even span multiple days. + +It is often difficult or impossible to determine when a release is 'finished' +because many ecosystems allow adding new artifacts to old releases when adding +support for new platforms or architectures. Therefore, the set of attestations +for a given release MAY grow over time as additional builds and attestations +are created. + +Thus, package ecosystems SHOULD support multiple individual attestations per +release. At the time of a given build, the relevant provenance for that build +can be added to the release, depending on the relationship to the given +artifacts. + +### Relationship between artifacts and attestations + +Package ecosystems SHOULD support a one-to-many relationship from build +artifacts to attestations to ensure that anyone is free to produce and publish +any attestation they might need. However, while there are lots of possible +attestations that can have a relationship to a given artifact, in this context +SLSA is primarily concerned with build attestations, i.e., provenance, and as +such, this specification only considers build attestations, produced by the +same maintainers as the artifacts themselves. + +By providing provenance alongside an artifact in the manner specified by a +given ecosystem, maintainers are considered to be 'elevating' these build +attestations above all other possible attestations that could be provided by +third parties for a given artifact. The ultimate goal is for maintainers to +provide the provenance necessary for a repository to be able to verify some +potential policy that requires a certain SLSA level for publication, not +support the publication of arbitrary attestations by third parties. + +As a result, this provenance SHOULD accompany the artifact at publish time, and +package ecosystems SHOULD provide a way to map a given artifact to its +corresponding attestations. The mappings can be either implicit (e.g., require a +custom filename schema that uniquely identifies the provenance over other +attestation types) or explicit (e.g., it could happen as a de-facto standard +based on where the attestation is published). + +The provenance SHOULD have a filename that is directly related to the build +artifact filename. For example, for an artifact `.`, the +attestation is `.attestation` or some similar extension (for example +[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`). + +### Where attestations are published + +There are a number of opportunities and venues to publish attestations during +and after the build process. Producers MUST publish attestations in at least +one place, and SHOULD publish attestations in more than one place: + +- **Publish attestations alongside the source repository releases**: If the + source repository hosting provider offers an artifact "release" feature, + such as [GitHub + releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) + or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), + producers SHOULD include provenance as part of such releases. This option + has the benefit of requiring no changes to the package registry to support + provenance formats, but has the disadvantage of putting the source + repository hosting provider in the critical path for installers that want to + verify policy at build-time. +- **Publish attestations alongside the artifact in the package registry**: + Many software repositories already support some variety of publishing 1:1 + related files alongside an artifact, sometimes known as “sidecar files”. + For example, PyPI supports publishing `.asc` files representing the PGP + signature for an artifact with the same filename (but different extension). + This option requires the mapping between artifact and attestation (or + attestation vessel) to be 1:1. +- **Publish attestations elsewhere, record their existence in a transparency + log**: Once an attestation has been generated and published for a build, a + hash of the attestation and a pointer to where it is indexed SHOULD be + published to a third-party transparency log that exists outside the source + repository and package registry. Not only are transparency logs such as + [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed + to be immutable, but they typically also make monitoring easier. + Requiring the presence of the attestation in a monitored transparency log + during verification helps ensure the attestation is trustworthy. + +Combining these options gives us a process for bootstrapping SLSA adoption +within an ecosystem, even if the package registry doesn't support publishing +attestations. First, interested projects modify their release process to +produce SLSA provenance. Then, they publish that provenance to their source +repository. Finally, they publish the provenance to the package registry, if +and when the registry supports it. + +Long-term, package registries SHOULD support uploading and distributing +provenance alongside the artifact. This model is preferred for two reasons: + +- trust: clients already trust the package registry as the source of their + artifacts, and don't need to trust an additional service; +- reliability: clients already depend on the package registry as part of + their critical path, so distributing provenance via the registry avoids + adding an additional point of failure. + +Short term, consumers of build artifacts can bootstrap a manual policy by using +the source repository only for projects that publish all artifacts and +attestations to the source repository, and later extend this to all artifacts +published to the package registry via the canonical installation tools once +a given ecosystem supports them. + +### Immutability of attestations + +Attestations SHOULD be immutable. Once an attestation is published as it +corresponds to a given artifact, that attestation is immutable and cannot be +overwritten later with a different attestation that refers to the same +artifact. Instead, a new release (and new artifacts) SHOULD be created. + +### Format of the attestation + +The provenance is available to the consumer in a format that the consumer +accepts. The format SHOULD be in-toto +[SLSA Build Provenance](/build-provenance), but another format MAY be used if +both producer and consumer agree and it meets all the other requirements. + +### Considerations for source-based ecosystems + +Some ecosystems have support for installing directly from source repositories +(an option for Python/`pip`, Go, etc.). In these cases, there is no need to +publish or verify provenance because there is no "build" step that translates +between a source repository and an artifact that is being installed. + +However, for ecosystems that install from source repositories _via_ some +intermediary (e.g., [Homebrew installing from GitHub release artifacts generated +from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go +installing through the Go module proxy](https://proxy.golang.org/)), these +ecosystems distribute "source archives" that are not the bit-for-bit identical +form from version control. These intermediaries are transforming the original +source repository in some way that constitutes a "build" and as a result SHOULD +be providing build provenance for this "package", and the recommendations +outlined here apply. + +[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/draft/build-track-requirements.md b/docs/spec/draft/build-track-requirements.md new file mode 100644 index 000000000..47e71785e --- /dev/null +++ b/docs/spec/draft/build-track-requirements.md @@ -0,0 +1,344 @@ +--- +title: "Build: Requirements for producing artifacts" +description: This page covers the technical requirements for producing artifacts at each SLSA level. +--- + +# {Build Track: Requirements for producing artifacts} + +**About this page:** the *Build Track Requirements for producing artifacts* page covers the technical requirements for producing artifacts at each SLSA level. + +**Intended audience:** platform implementers and security engineers + +**Topics covered:** build levels, producer and build platform responsibility sharing + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), [CIS Critical Security Controls](https://www.cisecurity.org/controls/cis-controls-list) + +>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). + +**For more information, see:** {optional} + +## Overview + +In order to produce artifacts with a specific build level, responsibility for meeting requirements is split between the [producer](#producer-responsibilities) and the [platform](#build-platform-responsibilities). 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. + +## Build provenance levels + +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 + L1L2L3 +
Producer + Choose an appropriate build platform + ✓✓✓ +
Follow a consistent build process + ✓✓✓ +
Distribute provenance + ✓✓✓ +
Build platform + Provenance generation + Exists + ✓✓✓ +
Authentic + ✓✓ +
Unforgeable + ✓ +
Isolation strength + Hosted + ✓✓ +
Isolated + ✓ +
+ +### Security best practices for creating build levels + +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). + +## Responsibilities and Requirements for Producers and Build Platforms + +### Producer responsibilities and requirements + +[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 responsibilities and requirements + +[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](build-track-basics) 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? + + +
RequirementDescriptionL1L2L3 + +
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). + + ✓ +
+ +#### Build platform 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 +[Assessing build platforms](assessing-build-platforms.md). + + + + +
RequirementDescriptionL1L2L3 + +
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). + + ✓ +
+ +[external parameters]: provenance.md#externalParameters +[identified in the provenance]: provenance.md#model +[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/draft/build-track-verification.md b/docs/spec/draft/build-track-verification.md new file mode 100644 index 000000000..47a36e13f --- /dev/null +++ b/docs/spec/draft/build-track-verification.md @@ -0,0 +1,316 @@ +--- +title: "Build Track: Verifying artifacts" +description: This page describes how to verify artifacts and their SLSA provenance. +--- + +# {Build Track: Verifying Artifacts} + +**About this page:** the *Build Track Verifying Artifacts* page describes how to verify artifacts and their SLSA provenance. + +**Intended audience:** platform implementers, security engineers, and software consumers + +**Topics covered:** verification procedures, expectation models, provenance, architecture options for provenance verification + +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) + +>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). + +**For more information, see:** {optional} + +## Overview + +SLSA uses provenance to indicate whether an artifact is authentic or not, but +provenance doesn't do anything unless somebody inspects it. SLSA calls that +inspection verification. + +This document explains the process for verifying an artifact and its provenance against a set of expectations. It also shows how to form the expectations used to verify provenance and discusses architecture choices for where provenance verification can happen. + +## How to verify SLSA artifacts + +Verification SHOULD include the following steps. These steps link more detailed procedures in the [Verification Steps](#verification-steps.md) section below. + +- [Step 1:](step-1:-check-slsa-build-level) Ensure that the builder identity is in the map of trusted builder id's to SLSA level. +- [Step 2:](step-2:-check-expectations) Verify the signature on the provenance envelope. +- [Step 3:]((optional)-check-dependencies-recursively) Make sure that the values for `buildType` and `externalParameters` in the + provenance match the expected values. The package ecosystem MAY allow + an approved list of `externalParameters` to be ignored during verification. + Any unrecognized `externalParameters` SHOULD cause verification to fail. + +![Threats covered by each step](images/supply-chain-threats-build-verification.svg) + +See [Build Track Terminology](build-track-basics.md#terminology) for build track terms and +[Threats & mitigations](threats.md) for a detailed explanation of each threat. + +**Note:** This section assumes that the provenance is in the recommended +[provenance format](provenance.md). If it is not, then the verifier SHOULD +perform equivalent checks on provenance fields that correspond to the ones +referenced here. + +## Verification Steps + +### Step 1: Check SLSA Build level + +[Step 1]: #step-1-check-slsa-build-level + +First, check the SLSA Build level by comparing the artifact to its provenance +and the provenance to a preconfigured root of trust. The goal is to ensure that +the provenance actually applies to the artifact in question and to assess the +trustworthiness of the provenance. This mitigates some or all of [threats] "E", +"F", "G", and "H", depending on SLSA Build level and where verification happens. + +Once, when bootstrapping the verifier: + +- Configure the verifier's roots of trust, meaning the recognized builder + identities and the maximum SLSA Build level each builder is trusted up to. + Different verifiers might use different roots of trust, but usually a + verifier uses the same roots of trust for all packages. This configuration + is likely in the form of a map from (builder public key identity, + `builder.id`) to (SLSA Build level). + +
+ Example root of trust configuration + + The following snippet shows conceptually how a verifier's roots of trust + might be configured using made-up syntax. + + ```jsonc + "slsaRootsOfTrust": [ + // A builder trusted at SLSA Build L3, using a fixed public key. + { + "publicKey": "HKJEwI...", + "builderId": "https://somebuilder.example.com/slsa/l3", + "slsaBuildLevel": 3 + }, + // A different builder that claims to be SLSA Build L3, + // but this verifier only trusts it to L2. + { + "publicKey": "tLykq9...", + "builderId": "https://differentbuilder.example.com/slsa/l3", + "slsaBuildLevel": 2 + }, + // A builder that uses Sigstore for authentication. + { + "sigstore": { + "root": "global", // identifies fulcio/rekor roots + "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" + } + "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", + "slsaBuildLevel": 3, + } + ... + ], + ``` + +
+ +Given an artifact and its provenance: + +1. [Verify][validation-model] the envelope's signature using the roots of + trust, resulting in a list of recognized public keys (or equivalent). +2. [Verify][validation-model] that statement's `subject` matches the digest of + the artifact in question. +3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1`. +4. Look up the SLSA Build Level in the roots of trust, using the recognized + public keys and the `builder.id`, defaulting to SLSA Build L1. + +Resulting threat mitigation: + +- [Threat "E"]: SLSA Build L3 requires protection against compromise of the + build process and provenance generation by an external adversary, such as + persistence between builds or theft of the provenance signing key. In other + words, SLSA Build L3 establishes that the provenance is accurate and + trustworthy, assuming you trust the build platform. + - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build + platform itself, such as by a malicious insider. Instead, verifiers + SHOULD carefully consider which build platforms are added to the roots + of trust. For advice on establishing trust in build platforms, see + [Assessing build platforms](assessing-build-platforms.md). +- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance + after the build. This is accomplished by verifying the `subject` and + signature in the steps above. +- [Threat "G"]: Verification by the consumer or otherwise outside of the + package registry covers compromise of the registry itself. (Verifying within + the registry at publication time is also valuable, but does not cover Threat + "G" or "I".) +- [Threat "I"]: Verification by the consumer covers compromise of the package + in transit. (Many ecosystems also address this threat using package + signatures or checksums.) + - NOTE: SLSA does not yet cover adversaries tricking a consumer to use an + unintended package, such as through typosquatting. Those threats are + discussed in more detail under [Threat "H"]. + +[Threat "E"]: threats#e-build-process +[Threat "F"]: threats#f-artifact-publication +[Threat "G"]: threats#g-distribution-channel +[Threat "H"]: threats#h-package-selection +[Threat "I"]: threats#i-usage + +[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model + +### Step 2: Check expectations + +[verify-step-2]: #check-expectations + +Next, check that the package's provenance meets your expectations for that +package in order to mitigate [threat "D"]. + +In our threat model, the adversary has the ability to invoke a build and to publish +to the registry. The adversary is not able to write to the source repository, nor do +they have insider access to any trusted systems. Your expectations SHOULD be +sufficient to detect or prevent this adversary from injecting unofficial +behavior into the package. + +You SHOULD compare the provenance against expected values for at least the +following fields: + +| What | Why +| ---- | --- +| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended platform +| Canonical source repository | To prevent an adversary from building from an unofficial fork (or other disallowed source) +| `buildType` | To ensure that `externalParameters` are interpreted as intended +| `externalParameters` | To prevent an adversary from injecting unofficial behavior + +Verification tools SHOULD reject unrecognized fields in `externalParameters` to +err on the side of caution. It is acceptable to allow a parameter to have a +range of values (possibly any value) if it is known that any value in the range +is safe. JSON comparison is sufficient for verifying parameters. + +TIP: Difficulty in forming meaningful expectations about `externalParameters` can +be a sign that the `buildType`'s level of abstraction is too low. For example, +`externalParameters` that record a list of commands to run is likely impractical +to verify because the commands change on every build. Instead, consider a +`buildType` that defines the list of commands in a configuration file in a +source repository, then put only the source repository in +`externalParameters`. Such a design is easier to verify because the source +repository is constant across builds. + +[Threat "D"]: threats#d-external-build-parameters + +### Step 3: (Optional) Check dependencies recursively + +[verify-step-3]: #step-3-optional-check-dependencies-recursively + +Finally, recursively check the `resolvedDependencies` as available and to the +extent desired. Note that SLSA v1.0 does not have any requirements on the +completeness or verification of `resolvedDependencies`. However, one might wish +to verify dependencies in order to mitigate [dependency threats] and protect against +threats further up the supply chain. If `resolvedDependencies` is incomplete, +these checks can be done on a best-effort basis. + +A [Verification Summary Attestation (VSA)][VSA] can make dependency verification +more efficient by recording the result of prior verifications. A trimming +heuristic or exception mechanism is almost always necessary when verifying +dependencies because there will be transitive dependencies that are SLSA Build +L0. (For example, consider the compiler's compiler's compiler's ... compiler.) + +[dependency threats]: threats#dependency-threats +[VSA]: /verification_summary +[threats]: threats + +## Expectation Models + +Expectations are known provenance values that indicate the +corresponding artifact is authentic. For example, a package ecosystem may +maintain a mapping between package names and their canonical source +repositories. That mapping constitutes a set of expectations. + +Possible models for forming expectations include: + +- **Trust on first use:** Accept the first version of the package as-is. On + each version update, compare the old provenance to the new provenance and + alert on any differences. This can be augmented by having rules about what + changes are benign, such as a parameter known to be safe or a heuristic + about safe git branches or tags. + +- **Defined by producer:** The package producer tells the verifier what their + expectations ought to be. In this model, the verifier SHOULD provide an + authenticated communication mechanism for the producer to set the package's + expectations, and there SHOULD be some protection against an adversary + unilaterally modifying them. For example, modifications might require + two-party control, or consumers might have to accept each policy change + (another form of trust on first use). + +- **Defined in source:** The source repository tells the verifier what their + expectations ought to be. In this model, the package name is immutably bound + to a source repository and all other external parameters are defined in the + source repository. This is how the Go ecosystem works, for example, since + the package name *is* the source repository location. + +>**Note:** that expectations are tied to a *package name*, whereas +provenance is tied to an *artifact*. Different versions of the same package name +will likely have different artifacts and therefore different provenance. Similarly, an +artifact might have different names in different package ecosystems but use the same +provenance file. + +## Architecture options for provenance verification + +There are several options (non-mutually exclusive) for where provenance verification +can happen: the package ecosystem at upload time, the consumers at download time, or +via a continuous monitoring system. Each option comes with its own set of +considerations, but all are valid and at least one SHOULD be used. + +More than one component can verify provenance. For example, even if a package +ecosystem verifies provenance, consumers who get artifacts from that package +ecosystem might wish to verify provenance themselves for defense in depth. They +can do so using either client-side verification tooling or by polling a +monitor. + + + +### Package ecosystem + +[Package ecosystem]: #package-ecosystem + +A package ecosystem is a set of rules and conventions governing +how packages are distributed. Every package artifact has an ecosystem, whether it is +formal or ad-hoc. Some ecosystems are formal, such as language distribution +(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. +[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact +distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). +Other ecosystems are informal, such as a convention used within a company. Even +ad-hoc distribution of software, such as through a link on a website, is +considered an "ecosystem". For more background, see +[Package Model](terminology.md#package-model). + +During package upload, a package ecosystem can ensure that the artifact's +provenance matches the expected values for that package name's provenance before +accepting it into the package registry. This option is RECOMMENDED whenever +possible because doing so benefits all of the package ecosystem's clients. + +The package ecosystem is responsible for making its expectations available to +consumers, reliably redistributing artifacts and provenance, and providing tools +to enable safe artifact consumption (e.g. whether an artifact meets +expectations). + +### Consumer + +[Consumer]: #consumer + +A package artifact's consumer is the organization or individual that uses the +package artifact. + +Consumers can form their own expectations for artifacts or use the default +expectations provided by the package producer and/or package ecosystem. +When forming their own expectations, the consumer uses client-side verification tooling to ensure +that the artifact's provenance matches their expectations for that package +before use (e.g. during installation or deployment). Client-side verification +tooling can be either standalone, such as +[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into +the package ecosystem client. + +### Monitor + +[Monitor]: #monitor + +A monitor is a service that verifies provenance for a set +of packages and publishes the result of that verification. The set of +packages verified by a monitor is arbitrary, though it MAY mimic the set +of packages published through one or more package ecosystems. The monitor +SHOULD publish its expectations for all the packages it verifies. + +Consumers can continuously poll a monitor to detect artifacts that +do not meet the monitor's expectations. Detecting artifacts that fail +verification is of limited benefit unless a human or automated system takes +action in response to the failed verification. From 5a8a56e9f574d579546dc5be6d13af03037f074d Mon Sep 17 00:00:00 2001 From: Seth McEvoy Date: Sun, 25 Jan 2026 22:25:49 -0800 Subject: [PATCH 3/3] build track ready for pull request --- docs/spec/draft/build-track-assessment.md | 10 +++++----- docs/spec/draft/build-track-basics.md | 2 +- docs/spec/draft/build-track-provenance.md | 13 ++++++------- docs/spec/draft/build-track-requirements.md | 10 +++++----- docs/spec/draft/build-track-verification.md | 10 +++++----- 5 files changed, 22 insertions(+), 23 deletions(-) diff --git a/docs/spec/draft/build-track-assessment.md b/docs/spec/draft/build-track-assessment.md index b862124ce..c8788aa2e 100644 --- a/docs/spec/draft/build-track-assessment.md +++ b/docs/spec/draft/build-track-assessment.md @@ -1,17 +1,17 @@ --- -title: "Build: Assessing build platforms" +title: "Build Track: Assessment" description: This page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. --- -# {Build Track: Assessing Build Platforms} +# {Build Track: Assessment} -**About this page:** the *Build Track: Accessing Build Platforms* page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. +**About this page:** the *Build Track: Assessment* page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. **Intended audience:** {add appropriate audience} -**Topics covered:** adversary behavior, sample prompts to access build platform security +**Topics covered:** adversary behavior, sample prompts to assess build platform security -**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} >The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be diff --git a/docs/spec/draft/build-track-basics.md b/docs/spec/draft/build-track-basics.md index 30c2512c5..49e2b0a54 100644 --- a/docs/spec/draft/build-track-basics.md +++ b/docs/spec/draft/build-track-basics.md @@ -17,7 +17,7 @@ description: This page introduces the SLSA build track part of the supply chain "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). -**For more information, see:** {optional} +**For more information, see:** {optional} ## Overview diff --git a/docs/spec/draft/build-track-provenance.md b/docs/spec/draft/build-track-provenance.md index a297822b1..402810289 100644 --- a/docs/spec/draft/build-track-provenance.md +++ b/docs/spec/draft/build-track-provenance.md @@ -1,24 +1,23 @@ --- -title: "Build: Distributing provenance" +title: "Build Track: Provenance" description: This document provides specifications for distributing provenance and the relationship between build artifacts and provenance. --- -# { Build Track: Distributing Provenance} +# { Build Track: Provenance} -**About this page:** the *Build Track Distributing Provenance* page provides specifications for distributing provenance and the +**About this page:** the *Build Track: Provenance* page provides specifications for distributing provenance and the relationship between build artifacts and provenance. **Intended audience:** platform implementers and software distributors -**Topics covered:** build provenance attestations +**Topics covered:** build provenance metadata and attestation formats -**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} >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). - +interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) **For more information, see:** {optional} ## Overview diff --git a/docs/spec/draft/build-track-requirements.md b/docs/spec/draft/build-track-requirements.md index 47e71785e..08e6eec00 100644 --- a/docs/spec/draft/build-track-requirements.md +++ b/docs/spec/draft/build-track-requirements.md @@ -1,17 +1,17 @@ --- -title: "Build: Requirements for producing artifacts" +title: "Build: Requirements" description: This page covers the technical requirements for producing artifacts at each SLSA level. --- -# {Build Track: Requirements for producing artifacts} +# {Build Track: Requirements} -**About this page:** the *Build Track Requirements for producing artifacts* page covers the technical requirements for producing artifacts at each SLSA level. +**About this page:** the *Build Track: Requirements* page covers the technical requirements for producing artifacts at each SLSA level. **Intended audience:** platform implementers and security engineers -**Topics covered:** build levels, producer and build platform responsibility sharing +**Topics covered:** build levels, responsibilities and requirements -**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), [CIS Critical Security Controls](https://www.cisecurity.org/controls/cis-controls-list) +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), [CIS Critical Security Controls](https://www.cisecurity.org/controls/cis-controls-list), {other standards as required} >The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be diff --git a/docs/spec/draft/build-track-verification.md b/docs/spec/draft/build-track-verification.md index 47a36e13f..b8949cc49 100644 --- a/docs/spec/draft/build-track-verification.md +++ b/docs/spec/draft/build-track-verification.md @@ -1,17 +1,17 @@ --- -title: "Build Track: Verifying artifacts" +title: "Build Track: Verification" description: This page describes how to verify artifacts and their SLSA provenance. --- -# {Build Track: Verifying Artifacts} +# {Build Track: Verification} -**About this page:** the *Build Track Verifying Artifacts* page describes how to verify artifacts and their SLSA provenance. +**About this page:** the *Build Track: Verification* page describes how to verify artifacts and their SLSA provenance. **Intended audience:** platform implementers, security engineers, and software consumers -**Topics covered:** verification procedures, expectation models, provenance, architecture options for provenance verification +**Topics covered:** verification procedures, expectation models, architecture options for provenance verification -**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) +**Internet standards:** [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), {other standards as required} >The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be