SLSA is a specification for describing and incrementally improving supply chain
security, established by industry consensus. It is organized into a series of
levels that describe increasing security guarantees.
This is version 1.0 RC2 of the SLSA specification, which defines the SLSA
levels and recommended attestation formats, including provenance.
Understanding SLSA
These sections provide an overview of SLSA, how it helps protect against common supply chain attacks, and common use cases. If you’re new to SLSA or supply chain security, start here.
Core specification
These sections describe SLSA’s security levels and requirements for each track. If you want to achieve SLSA a particular level, these are the requirements you’ll need to meet.
| Section |
Description |
| Terminology |
Terminology and model used by SLSA |
| Security levels |
Overview of SLSA’s tracks and levels, intended for all audiences |
| Producing artifacts |
Detailed technical requirements for producing software artifacts, intended for system implementers |
| Distributing provenance |
Detailed technical requirements for distributing provenance, intended for system implementers and software distributors |
| Verifying artifacts |
Guidance for verifying software artifacts and their SLSA provenance, intended for system implementers and software consumers |
| Verifying build systems |
Guidelines for securing SLSA Build L3+ builders, intended for system implementers |
| Threats & mitigations |
Detailed information about specific supply chain attacks and how SLSA helps |
These sections include the concrete schemas for SLSA attestations. The Provenance and VSA formats are recommended, but not required by the specification.
How to SLSA
These instructions tell you how to apply the core SLSA specification to use SLSA in your specific situation.
What's new in SLSA v1.0
SLSA v1.0 represents changes made in response to feedback from the SLSA
community and early adopters of SLSA v0.1. Overall, these changes
prioritize simplicity and practicality.
Check back here for a detailed v1.0 changelog with the official 1.0 release!
Until then, see the following for more information about what’s new:
About SLSA
This section is an introduction to SLSA and its concepts. If you’re new
to SLSA, start here!
What is SLSA?
SLSA is a set of incrementally adoptable guidelines for supply chain security,
established by industry consensus. The specification set by SLSA is useful for
both software producers and consumers: producers can follow SLSA’s guidelines to
make their software supply chain more secure, and consumers can use SLSA to make
decisions about whether to trust a software package.
SLSA offers:
- A common vocabulary to talk about software supply chain security
- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume
- An actionable checklist to improve your own software’s security
- A way to measure your efforts toward compliance with forthcoming
Executive Order standards in the Secure Software Development Framework (SSDF)
Why SLSA is needed
High profile attacks like those against SolarWinds or Codecov have exposed the kind of supply
chain integrity weaknesses that may go unnoticed, yet quickly become very
public, disruptive, and costly in today’s environment when exploited. They’ve
also shown that there are inherent risks not just in code itself, but at
multiple points in the complex process of getting that code into software
systems—that is, in the software supply chain. Since these attacks are on
the rise and show no sign of decreasing, a universal framework for hardening the
software supply chain is needed, as affirmed by the
U.S. Executive Order on Improving the Nation’s Cybersecurity.
Security techniques for vulnerability detection and analysis of source code are
essential, but are not enough on their own. Even after fuzzing or vulnerability
scanning is completed, changes to code can happen, whether unintentionally or
from insider threats or compromised accounts. Risk for code modification exists at
each link in a typical software supply chain, from source to build through
packaging and distribution. Any weaknesses in the supply chain undermine
confidence in whether the code that you run is actually the code that you
scanned.
SLSA is designed to support automation that tracks code handling from source
to binary, protecting against tampering regardless of the complexity
of the software supply chain. As a result, SLSA increases trust that the
analysis and review performed on source code can be assumed to still apply to
the binary consumed after the build and distribution process.
SLSA in layperson’s terms
There has been a lot of discussion about the need for “ingredient labels” for
software—a “software bill of materials” (SBOM) that tells users what is in their
software. Building off this analogy, SLSA can be thought of as all the food
safety handling guidelines that make an ingredient list credible. From standards
for clean factory environments so contaminants aren’t introduced in packaging
plants, to the requirement for tamper-proof seals on lids that ensure nobody
changes the contents of items sitting on grocery store shelves, the entire food
safety framework ensures that consumers can trust that the ingredient list
matches what’s actually in the package they buy.
Likewise, the SLSA framework provides this trust with guidelines and
tamper-resistant evidence for securing each step of the software production
process. That means you know not only that nothing unexpected was added to the
software product, but also that the ingredient label itself wasn’t tampered with
and accurately reflects the software contents. In this way, SLSA helps protect
against the risk of:
- Code modification (by adding a tamper-evident “seal” to code after
source control)
- Uploaded artifacts that were not built by the expected CI/CD system (by marking
artifacts with a factory “stamp” that shows which build service created it)
- Threats against the build system (by providing “manufacturing facility”
best practices for build system services)
For more exploration of this analogy, see the blog post
SLSA + SBOM: Accelerating SBOM success with the help of SLSA.
Who is SLSA for?
In short: everyone involved in producing and consuming software, or providing
infrastructure for software.
Software producers, such as a development team or open
source maintainers. SLSA gives you protection against insider risk and tampering
along the supply chain to your consumers, increasing confidence that the
software you produce reaches your consumers as you intended.
Software consumers, such as a development team using open source packages, a
government agency using vendored software, or a CISO judging organizational
risk. SLSA gives you a way to judge the security practices of the software you
rely on and be sure that what you receive is what you expected.
Infrastructure providers, who provide infrastructure such as an ecosystem
package manager, build platform, or CI/CD system. As the bridge between the
producers and consumers, your adoption of SLSA enables a secure software supply
chain between them.
How SLSA works
We talk about SLSA in terms of tracks and levels.
A SLSA track focuses on a particular aspect of a supply chain, such as the Build
Track. SLSA v1.0 consists of only a single track (Build), but future versions of
SLSA will add tracks that cover other parts of the software supply chain, such
as how source code is managed.
Within each track, ascending levels indicate increasingly hardened security
practices. Higher levels provide better guarantees against supply chain threats,
but come at higher implementation costs. Lower SLSA levels are designed to be
easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes
used to refer to software that doesn’t yet meet any SLSA level. Currently, the
SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels
to be possible in future revisions.
The combination of tracks and levels offers an easy way to discuss whether
software meets a specific set of requirements. By referring to an artifact as
meeting SLSA Build Level 3, for example, you’re indicating in one phrase that
the software artifact was built following a set of security practices that
industry leaders agree protect against particular supply chain compromises.
What SLSA doesn’t cover
SLSA is only one part of a thorough approach to supply chain security. There
are several areas outside SLSA’s current framework that are nevertheless
important to consider together with SLSA such as:
- Code quality: SLSA does not tell you whether the developers writing the
source code followed secure coding practices.
- Developer trust: SLSA cannot tell you whether a developer is
intentionally writing malicious code. If you trust a developer to write
code you want to consume, though, SLSA can guarantee that the code will
reach you without another party tampering with it.
- Transitive trust for dependencies: the SLSA level of an artifact is
independent of the level of its dependencies. You can use SLSA recursively to
also judge an artifact’s dependencies on their own, but there is
currently no single SLSA level that applies to both an artifact and its
transitive dependencies together. For a more detailed explanation of why,
see the FAQ.
Supply chain threats
Attacks can occur at every link in a typical software supply chain, and these
kinds of attacks are increasingly public, disruptive, and costly in today’s
environment.
This section is an introduction to possible attacks throughout the supply chain and how
SLSA can help. For a more technical discussion, see Threats & mitigations.
Summary
SLSA’s primary focus is supply chain integrity, with a secondary focus on
availability. Integrity means protection against tampering or unauthorized
modification at any stage of the software lifecycle. Within SLSA, we divide
integrity into source integrity vs build integrity.
Source integrity: Ensure that all changes to the source code reflect the
intent of the software producer. Intent of an organization is difficult to
define, so SLSA approximates this as approval from two authorized
representatives.
Build integrity: Ensure that the package is built from the correct,
unmodified sources and dependencies according to the build recipe defined by the
software producer, and that artifacts are not modified as they pass between
development stages.
Availability: Ensure that the package can continue to be built and
maintained in the future, and that all code and change history is available for
investigations and incident response.
Real-world examples
Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA’s framework. For example:
|
| Integrity threat
| Known example
| How SLSA can help
|
| A
| Submit unauthorized change (to source repo)
| SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself.
| Two-person review could have caught the unauthorized change.
|
| B
| Compromise source repo
| PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits.
| A better-protected source code platform would have been a much harder target for the attackers.
|
| C
| Build from modified source (not matching source repo)
| Webmin: Attacker modified the build infrastructure to use source files not matching source control.
| A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering.
|
| D
| Use compromised dependency (i.e. A-H, recursively)
| event-stream: Attacker added an innocuous dependency and then later updated the dependency to add malicious behavior. The update did not match the code submitted to GitHub (i.e. attack F).
| Applying SLSA recursively to all dependencies would have prevented this particular vector, because the provenance would have indicated that it either wasn't built from a proper builder or that the source did not come from GitHub.
|
| E
| Compromise build process
| SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build.
| Higher SLSA levels require stronger security controls for the build platform, making it more difficult to compromise and gain persistence.
|
| F
| Upload modified package (not matching build process)
| 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
| Compromise package repo
| Attacks on Package Mirrors: Researcher ran mirrors for several popular package repositories, 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
| Use compromised package
| 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.
|
|
| Availability threat
| Known example
| How SLSA can help
|
| D
| 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.
Use cases
SLSA protects against tampering during the software supply chain, but how?
The answer depends on the use case in which SLSA is applied. Below
describe the three main use cases for SLSA.
Applications of SLSA
First party
Reducing risk within an organization from insiders and compromised accounts
In its simplest form, SLSA can be used entirely within an organization to reduce
risk from internal sources. This is the easiest case in which to apply SLSA
because there is no need to transfer trust across organizational boundaries.
Example ways an organization might use SLSA internally:
- A small company or team uses SLSA to ensure that the code being deployed to
production in binary form is the same one that was tested and reviewed in
source form.
- A large company uses SLSA to require two person review for every production
change, scalably across hundreds or thousands of employees/teams.
- An open source project uses SLSA to ensure that compromised credentials
cannot be abused to release an unofficial package to a package repostory.
Case study: Google (Binary Authorization for Borg)
Open source
Reducing risk from consuming open source software
SLSA can also be used to reduce risk for consumers of open source software. The
focus here is to map built packages back to their canonical sources and
dependencies. In this way, consumers need only trust a small number of secure
build systems rather than the many thousands of developers with upload
permissions across various packages.
Example ways an open source ecosystem might use SLSA to protect users:
- At upload time, the package registry rejects the package if it was not built
from the canonical source repository.
- At download time, the packaging client rejects the package if it was not
built by a trusted builder.
Case study: SUSE
Vendors
Reducing risk from consuming vendor provided software and services
Finally, SLSA can be used to reduce risk for consumers of vendor provided
software and services. Unlike open source, there is no canonical source
repository to map to, so instead the focus is on trustworthiness of claims made
by the vendor.
Example ways a consumer might use SLSA for vendor provided software:
- Prefer vendors who make SLSA claims and back them up with credible evidence.
- Require a vendor to implement SLSA as part of a contract.
- Require a vendor to be SLSA certified from a trusted third-party auditor.
Guiding principles
This section is an introduction to the guiding principles behind SLSA’s design
decisions.
Trust systems, verify artifacts
Establish trust in a small number of systems—such as change management, build,
and packaging systems—and then automatically verify the many artifacts
produced by those systems.
Reasoning: Trusted computing bases are unavoidable—there’s no choice but
to trust some systems. Hardening and verifying systems is difficult and
expensive manual work, and each trusted system expands the attack surface of the
supply chain. Verifying that an artifact is produced by a trusted system,
though, is easy to automate.
To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited
numbers of systems and then automate verification of the artifacts produced by those systems.
The attack surface and work to establish trust does not scale with the number of artifacts produced,
as happens when artifacts each use a different trusted system.
Benefits: Allows SLSA to scale to entire ecosystems or organizations with a near-constant
amount of central work.
Example
A security engineer analyzes the architecture and implementation of a build
system to ensure that it meets the SLSA Build Track requirements. Following the
analysis, the public keys used by the build system to sign provenance are
“trusted” up to the given SLSA level. Downstream systems verify the provenance
signed by the public key to automatically determine that an artifact meets the
SLSA level.
Corollary: Minimize the number of trusted systems
A corollary to this principle is to minimize the size of the trusted computing
base. Every system we trust adds attack surface and increases the need for
manual security analysis. Where possible:
- Concentrate trust in shared infrastructure. For example, instead of each
team within an organization maintaining their own build system, use a
shared build system. Hardening work can be shared across all teams.
- Remove the need to trust components. For example, use end-to-end signing
to avoid the need to trust intermediate distribution systems.
Trust code, not individuals
Securely trace all software back to source code rather than trust individuals who have write access to package registries.
Reasoning: Code is static and analyzable. People, on the other hand, are prone to mistakes,
credential compromise, and sometimes malicious action.
Benefits: Removes the possibility for a trusted individual—or an
attacker abusing compromised credentials—to tamper with source code
after it has been committed.
Prefer attestations over inferences
Require explicit attestations about an artifact’s provenance; do not infer
security properties from a system’s configurations.
Reasoning: Theoretically, access control can be configured so that the only path from
source to release is through the official channels: the CI/CD system pulls only
from the proper source, package registry allows access only to the CI/CD system,
and so on. We might infer that we can trust artifacts produced by these systems
based on the system’s configuration.
In practice, though, these configurations are almost impossible to get right and
keep right. There are often over-provisioning, confused deputy problems, or
mistakes. Even if a system is configured properly at one moment, it might not
stay that way, and humans almost always end up getting in the access control
lists.
Access control is still important, but SLSA goes further to provide defense in depth: it requires proof in
the form of attestations that the package was built correctly.
Benefits: The attestation removes intermediate systems from the trust base and ensures that
individuals who are accidentally granted access do not have sufficient permission to tamper with the package.
Frequently asked questions
Q: Why is SLSA not transitive?
SLSA Build levels only cover the trustworthiness of a single build, with no
requirements about the build levels of transitive dependencies. The reason for
this is to make the problem tractable. If a SLSA Build level required
dependencies to be the same level, then reaching a level would require starting
at the very beginning of the supply chain and working forward. This is
backwards, forcing us to work on the least risky component first and blocking
any progress further downstream. By making each artifact’s SLSA rating
independent from one another, it allows parallel progress and prioritization
based on risk. (This is a lesson we learned when deploying other security
controls at scale throughout Google.) We expect SLSA ratings to be composed to
describe a supply chain’s overall security stance, as described in the case
study vision.
Q: What about reproducible builds?
When talking about reproducible builds, there
are two related but distinct concepts: “reproducible” and “verified
reproducible.”
“Reproducible” means that repeating the build with the same inputs results in
bit-for-bit identical output. This property
provides
many
benefits,
including easier debugging, more confident cherry-pick releases, better build
caching and storage efficiency, and accurate dependency tracking.
“Verified reproducible” means using two or more independent build systems to
corroborate the provenance of a build. In this way, one can create an overall
system that is more trustworthy than any of the individual components. This is
often
suggested
as a solution to supply chain integrity. Indeed, this is one option to secure
build steps of a supply chain. When designed correctly, such a system can
satisfy all of the SLSA Build level requirements.
That said, verified reproducible builds are not a complete solution to supply
chain integrity, nor are they practical in all cases:
- Reproducible builds do not address source, dependency, or distribution
threats.
- Reproducers must truly be independent, lest they all be susceptible to the
same attack. For example, if all rebuilders run the same pipeline software,
and that software has a vulnerability that can be triggered by sending a
build request, then an attacker can compromise all rebuilders, violating the
assumption above.
- Some builds cannot easily be made reproducible, as noted above.
- Closed-source reproducible builds require the code owner to either grant
source access to multiple independent rebuilders, which is unacceptable in
many cases, or develop multiple, independent in-house rebuilders, which is
likely prohibitively expensive.
Therefore, SLSA does not require verified reproducible builds directly. Instead,
verified reproducible builds are one option for implementing the requirements.
For more on reproducibility, see
Hermetic, Reproducible, or Verifiable?
Q: How does SLSA relate to in-toto?
in-toto is a framework to secure software supply chains
hosted at the Cloud Native Computing Foundation. The in-toto
specification provides a generalized workflow to secure different steps in a
software supply chain. The SLSA specification recommends
in-toto attestations as the vehicle to
express Provenance and other attributes of software supply chains. Thus, in-toto
can be thought of as the unopinionated layer to express information pertaining
to a software supply chain, and SLSA as the opinionated layer specifying exactly
what information must be captured in in-toto metadata to achieve the guarantees
of a particular level.
in-toto’s official implementations written in
Go,
Java, and
Rust include support for generating
SLSA Provenance metadata. These APIs are used in other tools generating SLSA
Provenance such as Sigstore’s cosign, the SLSA GitHub Generator, and the in-toto
Jenkins plugin.
Future directions
The initial draft version (v0.1) of SLSA had a larger scope including
protections against tampering with source code and a higher level of build
integrity (Build L4). This section collects some early thoughts on how SLSA
might evolve in future versions to re-introduce those notions and add other
additional aspects of automatable supply chain security.
Build track
Build L4
A build L4 could include further hardening of the build service and enabling
corraboration of the provenance, for example by providing complete knowledge of
the build inputs.
The initial draft version (v0.1) of SLSA defined a “SLSA 4” that included the
following requirements, which may or may not be part of a future Build L4:
- Pinned dependencies, which guarantee that each build runs on exactly the
same set of inputs.
- Hermetic builds, which guarantee that no extraneous dependencies are used.
- All dependencies listed in the provenance, which enables downstream systems
to recursively apply SLSA to dependencies.
- Reproducible builds, which enable other systems to corroborate the
provenance.
Source track
A Source track could provide protection against tampering of the source code
prior to the build.
The initial draft version (v0.1)
of SLSA included the following source requirements, which may or may not
form the basis for a future Source track:
- Strong authentication of author and reviewer identities, such as 2-factor
authentication using a hardware security key, to resist account and
credential compromise.
- Retention of the source code to allow for after-the-fact inspection and
future rebuilds.
- Mandatory two-person review of all changes to the source to prevent a single
compromised actor or account from introducing malicious changes.
Terminology
Before diving into the SLSA Levels, we need to establish a core set
of terminology and models to describe what we’re protecting.
Software supply chain
SLSA’s framework addresses every step of the software supply chain - the
sequence of steps resulting in the creation of an artifact. We represent a
supply chain as a directed acyclic graph of sources, builds, dependencies, and
packages. One artifact’s supply chain is a combination of its dependencies’
supply chains plus its own sources and builds.
| Term |
Description |
Example |
| Artifact |
An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. |
A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. |
| Attestation |
An authenticated statement (metadata) about a software artifact or collection of software artifacts. |
A signed SLSA Provenance file. |
| Source |
Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. |
Git commit (source) hosted on GitHub (platform). |
| Build |
Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. |
.travis.yml (process) run by Travis CI (platform). |
| Package |
Artifact that is “published” for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. |
Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. |
| Dependency |
Artifact that is an input to a build process but that is not a source. In the model, it is always a package. |
Alpine package (package) distributed on Alpine Linux (platform). |
Roles
Throughout the specification, you will see reference to the following roles
that take part in the software supply chain. Note that in practice a role may
be filled by more than one person or an organization. Similarly, a person or
organization may act as more than one role in a particular software supply
chain.
| Role |
Description |
Examples |
| Producer |
A party who creates software and provides it to others. Producers are often also consumers. |
An open source project’s maintainers. A software vendor. |
| Verifier |
A party who inspect an artifact’s provenance to determine the artifact’s authenticity. |
A business’s software ingestion system. A programming language ecosystem’s package registry. |
| Consumer |
A party who uses software provided by a producer. The consumer may verify provenance for software they consume or delegate that responsibility to a separate verifier. |
A developer who uses open source software distributions. A business that uses a point of sale system. |
| Infrastructure provider |
A party who provides software or services to other roles. |
A package registry’s maintainers. A build system’s maintainers. |
Build model
We model a build as running on a multi-tenant platform, where each execution is
independent. A tenant defines the build by specifying parameters through some
sort of external interface, often including a reference to a configuration file
in source control. The control plane then runs the build by interpreting the
parameters, fetching some initial set of dependencies, initializing the build
environment, and then starting execution. The build then performs arbitrary
steps, possibly fetching additional dependencies, and outputs one or more
artifacts. Finally, for SLSA Build L2+, the control plane outputs provenance
describing this whole process.
| Primary Term |
Description |
| 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. |
| Admin |
A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane. |
| Tenant |
An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters. |
| Control plane |
Build system 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. |
| 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. |
| Steps |
The set of actions that comprise a build, defined by the tenant. |
| 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. |
| 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. |
| Dependencies |
Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. |
| Outputs |
Collection of artifacts produced by the build. |
| Provenance |
Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters. |
Notably, there is no formal notion of “source” in the build model, just
parameters and dependencies. Most build platforms have an explicit “source”
artifact to be built, which is often a git repository; in the build model, the
reference to this artifact is a parameter while the artifact itself is a
dependency.
For examples on how this model applies to real-world build systems, see index
of build types.
Package model
Software is distributed in identifiable units called packages
according the the rules and conventions of a package ecosystem.
Examples of formal ecosystems include Python/PyPA,
Debian/Apt, and
OCI, while examples of
informal ecosystems include links to files on a website or distribution of
first-party software within a company.
Abstractly, a consumer locates software within an ecosystem by asking 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 this 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 it is access to that public key that serves as the registry.
The package name is the primary security boundary within a package ecosystem.
Different package names represent materially different pieces of
software—different owners, behaviors, security properties, and so on.
Therefore, the package name is the primary unit being protected in SLSA.
It is the primary identifier to which consumers attach expectations.
| Term |
Description |
| 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 |
An entity responsible for mapping package names to artifacts within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. |
| 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. |
Ambiguous terms to avoid:
- Package repository — Could mean either package registry or package name,
depending on the ecosystem. To avoid confusion, we always use “repository”
exclusively to mean “source repository”, where there is no ambiguity.
- Package manager (without “client”) — Could mean either package
ecosystem, package registry, or client-side tooling.
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!
Notes:
- Go 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.
Verification model
Verification in SLSA is performed in two ways. Firstly, the build system is
certified to ensure conformance with the requirements at the level claimed by
the build system. 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.
Secondly, artifacts are verified to ensure they meet the producer defined
expectations of where the package source code was retrieved from and on what
build system the package was built.
| Term |
Description |
| Expectations |
A set of constraints on the package’s provenance metadata. The package producer sets expectations for a package, whether 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 system certification |
Build systems are certified for their conformance to the SLSA requirements at the stated level. |
The examples below suggest some ways that expectations and verification may be
implemented for different, 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 system certification |
The build system implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance 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 system certification |
Performed by the language ecosystem packaging authority. |
Security levels
SLSA 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 section is a descriptive overview of the SLSA levels and tracks, describing
their intent. For the prescriptive requirements for each level, see
Requirements. For a general overview of SLSA, see
About SLSA.
Levels and tracks
SLSA levels are split into tracks. Each track has its own set of levels that
measure a particular aspect of supply chain security. The purpose of tracks is
to recognize progress made in one aspect of security without blocking on an
unrelated aspect. Tracks also allow the SLSA spec to evolve: we can add more
tracks without invalidating previous levels.
| Track/Level |
Requirements |
Focus |
| Build L0 |
(none) |
(n/a) |
| Build L1 |
Provenance showing how the package was built |
Mistakes, documentation |
| Build L2 |
Signed provenance, generated by a hosted build service |
Tampering after the build |
| Build L3 |
Hardened build service |
Tampering during the build |
Note: The previous version of the specification used a single unnamed track,
SLSA 1–4. For version 1.0 the Source aspects were removed to focus on the
Build track. A Source track may be added in future versions.
Build track
The SLSA build track describes increasing levels of trustworthiness and
completeness in a package artifact’s provenance. Provenance describes
what entity built the artifact, what process they used, and what the inputs
were. The lowest level only requires the provenance to exist, while higher
levels provide increasing protection against tampering of the build, the
provenance, or the artifact.
The primary purpose of the build track is to enable verification that the
artifact was built as expected. Consumers have some way of knowing what the
expected provenance should look like for a given package and then compare each
package artifact’s actual provenance to those expectations. Doing so prevents
several classes of supply chain threats.
Each ecosystem (for open source) or organization (for closed source) defines
exactly how this is implemented, including: means of defining expectations, what
provenance format is accepted, whether reproducible builds are used, how
provenance is distributed, when verification happens, and what happens on
failure. Guidelines for implementers can be found in the
requirements.
Build L0: No guarantees
- Summary
-
No requirements—L0 represents the lack of SLSA.
- 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
Build L1: Provenance exists
- Summary
-
Package has provenance showing how it was built. Can be used to prevent mistakes
but is trivial to bypass or forge.
- Intended for
-
Projects and organizations wanting to easily and quickly gain some benefits of
SLSA—other than tamper protection—without changing their build workflows.
- Requirements
-
-
Software producer follows a consistent build process so that others can form
expectations about what a “correct” build looks like.
-
Build system automatically generates provenance describing how the
artifact was built, including: what entity built the package, what build
process they used, and what the top-level input to the build were.
-
Software producer distributes provenance to consumers, preferably using a
convention determined by the package ecosystem.
- Benefits
-
-
Makes it easier for both producers and consumers to debug, patch, rebuild,
and/or analyze the software by knowing its precise source version and build
process.
-
With verification, prevents mistakes during the release process, such as
building from a commit that is not present in the upstream repo.
-
Aids organizations in creating an inventory of software and build systems
used across a variety of teams.
- Notes
-
- Provenance may be incomplete and/or unsigned at L1. Higher levels require
more complete and trustworthy provenance.
Build L2: Build service
- Summary
-
Forging the provenance or evading verification requires an explicit “attack”,
though this may be easy to perform. Deters unsophisticated adversaries or those
who face legal or financial risk.
In practice, this means that builds run on a hosted service that generates and
signs the provenance.
- Intended for
-
Projects and organizations wanting to gain moderate security benefits of SLSA by
switching to a hosted build service, while waiting for changes to the build
service itself required by Build L3.
- Requirements
-
All of Build L1, plus:
-
The build runs on a hosted build service that generates and signs the
provenance itself. This may be the original build, an after-the-fact
reproducible build, or some equivalent system that ensures the
trustworthiness of the provenance.
-
Downstream verification of provenance includes validating the authenticity
of the provenance.
- Benefits
-
All of Build L1, plus:
-
Prevents tampering after the build through digital signatures.
-
Deters adversaries who face legal or financial risk by evading security
controls, such as employees who face risk of getting fired.
-
Reduces attack surface by limiting builds to specific build services that
can be audited and hardened.
-
Allows large-scale migration of teams to supported build services early
while further hardening work (Build L3) is done in parallel.
Build L3: Hardened builds
- Summary
-
Forging the provenance or evading verification requires exploiting a
vulnerability that is beyond the capabilities of most adversaries.
In practice, this means that builds run on a hardened build service that offers
strong tamper protection.
- Intended for
-
Most software releases. Build L3 usually requires significant changes to
existing build services.
- Requirements
-
All of Build L2, plus:
- Benefits
-
All of Build L2, plus:
-
Prevents tampering during the build—by insider threats, compromised
credentials, or other tenants.
-
Greatly reduces the impact of compromised package upload credentials by
requiring attacker to perform a difficult exploit of the build process.
-
Provides strong confidence that the package was built from the official
source and build process.
Producing artifacts
This section covers the detailed technical requirements for producing artifacts at
each SLSA level. The intended audience is system implementers and security
engineers.
For an informative description of the levels intended for all audiences, see
Levels. For background, see Terminology. To
better understand the reasoning behind the requirements, see
Threats and mitigations.
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.
Overview
Build levels
In order to produce artifacts with a specific build level, responsibility is
split between the Producer and
Build system. The build system MUST strengthen the security controls in
order to achieve a specific level while the producer MUST choose and adopt a
build system capable of achieving a desired build level, implementing any
controls as specified by the chosen system.
Security Best Practices
While the exact definition of what constitutes a secure system 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.
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) 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.
Choose an appropriate build system
The producer MUST select a build system 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 system
A package’s build system 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 system is often a hosted, multi-tenant build service, but it could be a
system of multiple independent rebuilders, a special-purpose build system used
by a single software project, or even an individual’s workstation. Ideally, one
build system is used by many different software packages so that consumers can
minimize the number of trusted systems. For more background,
see Build Model.
The build system is responsible for providing two things: provenance
generation and isolation between builds. The Build level describes
the degree to which each of these properties is met.
Provenance generation
The build system 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?
| Requirement | Description | L1 | L2 | L3
|
|---|
| 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.
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.
| ✓ | ✓ | ✓
|
| 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 system 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 service that generated the provenance attestation.
This allows the consumer to trust the contents of the provenance attestation,
such as the identity of the build system.
Accuracy: The provenance MUST be generated by the build system (i.e. within
the trust boundary identified in the provenance) and not by a tenant of the
build system (i.e. outside the trust boundary), except as noted below.
- The data in the provenance MUST be obtained from the build service, either
because the generator is the build service or because the provenance
generator reads the data directly from the build service.
- The build system 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 system:
- The names and cryptographic digests of the output artifacts, i.e.
subject in SLSA Provenance. See forge output digest of the
provenance 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
service 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. (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).
| | | ✓
|
Isolation strength
The build system 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 system’s isolation strength, see
Verifying build systems.
| Requirement | Description | L1 | L2 | L3
|
|---|
| Build service
|
All build steps ran using some build service, not on an individual’s
workstation.
Examples: GitHub Actions, Google Cloud Build, Travis CI.
| | ✓ | ✓
|
| Isolated
|
The build service 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 system MUST guarantee the following:
- It MUST NOT be possible for a build to access any secrets of the build
service, 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 system 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
build systems prevent 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).
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 system and each individual build, and is
considered in the future directions.
| | | ✓
|
Distributing provenance
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 provides specifications for distributing provenance, and the
relationship between build artifacts and provenance (build attestations). It is
primarily concerned with 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.
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.
Background
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 <filename>.<extension>, the
attestation is <filename>.attestation or some similar extension (for example
in-toto recommends <filename>.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
or GitLab 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 providing 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 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.
The provenance is available to the consumer in a format that the consumer
accepts. The format SHOULD be in-toto SLSA 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, Go
installing through the Go module proxy), 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.
Verifying build systems
One of SLSA’s guiding principles is to “trust systems, verify
artifacts”. However, consumers cannot trust systems to produce Build L3
artifacts and provenance unless they have some proof that the provenance is
unforgeable and the builds are
isolated.
This section describes the parts of a build system that consumers SHOULD assess
and provides sample questions consumers can ask when assessing a build system.
See also Threats & mitigations and the
build model.
Threats
Adversary goal
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 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 C, D, E, and F 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 system’s ability to defend against the
following types of adversaries.
- Project contributors, who can:
- Create builds on the build service. 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.
- 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.
- Build service administrators, who can:
- Do everything listed under “project contributors” and “project
maintainers”.
- Run arbitrary code on the build service.
- Read and modify network traffic.
- Access the control plane’s cryptographic secrets.
- Remotely access build environments (e.g. via SSH).
Build system components
Consumers SHOULD consider at least these five elements of the
build model when assessing build systems for SLSA
conformance: external parameters, control plane, build environments, caches,
and outputs.
The following subsections detail these elements of the build model and give prompts
for assessing a build system’s ability to produce SLSA Build L3 provenance.
External parameters
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.
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
The control plane is the build system 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 service. The control plane is
operated by one or more administrators, who have privileges to modify the
control plane.
Prompts for assessing the control plane
Build environment
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).
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 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 system?
-
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
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.
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
Output Storage holds built artifacts and their provenance. Storage may either be
shared between build projects or allocated separately per-project.
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
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. Evidence submitted for third-party certification need not be
published.
Verifying artifacts
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, and this section describes recommendations for how to
verify artifacts and their SLSA provenance.
This section is divided into several subsections. The first describes the process
for verifying an artifact and its provenance against a set of expectations. The
second describes how to form the expectations used to verify provenance. The
third discusses architecture choices for where provenance verification can
happen.
How to verify
Verification SHOULD include the following steps:
- Ensuring that the builder identity is one of those in the map of trusted
builder id’s to SLSA level.
- Verifying the signature on the provenance envelope.
- Ensuring 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.
Note: This subsection assumes that the provenance is in the recommended
provenance format. If it is not, then the verifier SHOULD
perform equivalent checks on provenance fields that correspond to the ones
referenced here.
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) drawn from the SLSA Conformance
Program (coming soon).
Example root of trust configuration
The following snippet shows conceptually how a verifier’s roots of trust
might be configured using made-up syntax.
"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:
- Verify the envelope’s signature using the roots of
trust, resulting in a list of recognized public keys (or equivalent).
- Verify that statement’s
subject matches the digest of
the artifact in question.
- Verify that the
predicateType is https://slsa.dev/provenance/v1-rc2.
- 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
Verifying build systems.
- 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 “H”.)
- Threat “H”: 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 cover adversaries tricking a consumer to use an
unintended package, such as through typosquatting.
Step 2: Check expectations
Next, check that the package’s provenance meets your expectations for that
package in order to mitigate threat “C”.
In our threat model, the adversary has 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 system |
| 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.
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 threat “E” 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) 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.)
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.
It is important to 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
System implementers decide which part(s) of the system will verify provenance:
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. The options are not mutually exclusive, but
at least one part of a SLSA-conformant system SHOULD verify provenance.
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
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), operating system distribution (e.g.
Debian/Apt), or artifact
distribution (e.g. OCI).
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.
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. If possible, system implementers SHOULD
prefer this option 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
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, or built into
the package ecosystem client.
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 another part of the system
responds to the failed verification.
Threats & mitigations
What follows is a comprehensive technical analysis of supply chain threats and
their corresponding mitigations in SLSA. For an introduction to the
supply chain threats that SLSA protects against, see Supply chain threats.
The examples on this section are meant to:
- Explain the reasons for each of the SLSA requirements.
- Increase confidence that the SLSA requirements are sufficient to achieve the
desired level of integrity protection.
- Help implementers better understand what they are protecting against so that
they can better design and implement controls.
Source threats
A source integrity threat is a potential for an adversary to introduce a change
to the source code that does not reflect the intent of the software producer.
This includes the threat of an authorized individual introducing an unauthorized
change—in other words, an insider threat.
SLSA v1.0 does not address source threats, but we anticipate doing so in a
future version. In the meantime, the
threats and potential mitigations listed here show how SLSA v1.0 can fit into a
broader supply chain security program.
(A) Submit unauthorized change
An adversary introduces a change through the official source control management
interface without any special administrator privileges.
SLSA v1.0 does not address this threat, but it may be addressed in a future
version.
(B) Compromise source repo
An adversary introduces a change to the source control repository through an
administrative interface, or through a compromise of the underlying
infrastructure.
SLSA v1.0 does not address this threat, but it may be addressed in a future
version.
(C) Build from modified source
An adversary builds from a version of the source code that does not match the
official source control repository.
The mitigation here is to compare the provenance against expectations for the
package, which depends on SLSA Build L1 for provenance. (Threats against the
provenance itself are covered by (E) and (F).)
Build from unofficial fork of code (expectations)
Threat: Build using the expected CI/CD process but from an unofficial fork of
the code that may contain unauthorized changes.
Mitigation: Verifier requires the provenance’s source location to match an
expected value.
Example: MyPackage is supposed to be built from GitHub repo good/my-package.
Instead, it is built from evilfork/my-package. Solution: Verifier rejects
because the source location does not match.
Build from unofficial branch or tag (expectations)
Threat: Build using the expected CI/CD process and source location, but
checking out an “experimental” branch or similar that may contain code not
intended for release.
Mitigation: Verifier requires that the provenance’s source branch/tag matches
an expected value, or that the source revision is reachable from an expected
branch.
Example: MyPackage’s releases are tagged from the main branch, which has
branch protections. Adversary builds from the unprotected experimental branch
containing unofficial changes. Solution: Verifier rejects because the source
revision is not reachable from main.
Build from unofficial build steps (expectations)
Threat: Build the package using the proper CI/CD platform but with unofficial
build steps.
Mitigation: Verifier requires that the provenance’s build configuration source
matches an expected value.
Example: MyPackage is expected to be built by Google Cloud Build using the
build steps defined in the source’s cloudbuild.yaml file. Adversary builds
with Google Cloud Build, but using custom build steps provided over RPC.
Solution: Verifier rejects because the build steps did not come from the
expected source.
Build from unofficial parameters (expectations)
Threat: Build using the expected CI/CD process, source location, and
branch/tag, but using a parameter that injects unofficial behavior.
Mitigation: Verifier requires that the provenance’s external parameters all
match expected values.
Example 1: MyPackage is supposed to be built from the release.yml workflow.
Adversary builds from the debug.yml workflow. Solution: Verifier rejects
because the workflow parameter does not match the expected value.
Example 2: MyPackage’s GitHub Actions Workflow uses github.event.inputs to
allow users to specify custom compiler flags per invocation. Adversary sets a
compiler flag that overrides a macro to inject malicious behavior into the
output binary. Solution: Verifier rejects because the inputs parameter was not
expected.
Build from modified version of code modified after checkout (expectations)
Threat: Build from a version of the code that includes modifications after
checkout.
Mitigation: Build service pulls directly from the source repository and
accurately records the source location in provenance.
Example: Adversary fetches from MyPackage’s source repo, makes a local commit,
then requests a build from that local commit. Builder records the fact that it
did not pull from the official source repo. Solution: Verifier rejects because
the source repo does not match the expected value.
Dependency threats
A dependency threat is a vector for an adversary to introduce behavior to an
artifact through external software that the artifact requires to function.
SLSA mitigates dependency threats when you verify your dependencies’ SLSA
provenance.
(D) Use compromised dependency
Use a compromised build dependency
Threat: The adversary injects malicious code into software required to build
the artifact.
Mitigation: N/A - This threat is out of scope of SLSA v1.0, though the build
provenance may list build dependencies on a best-effort basis for forensic
analysis. You may be able to mitigate this threat by pinning your build
dependencies, preferably by digest rather than version number. Alternatively,
you can apply SLSA recursively,
but we have not yet standardized how to do so.
Example: The artifact uses libFoo and requires its source code to compile.
The adversary compromises libFoo‘s source repository and inserts malicious
code. When your artifact builds, it contains the adversary’s malicious code.
Use a compromised runtime dependency
Threat: The adversary injects malicious code into software required to run the
artifact.
Mitigation: N/A - This threat is out of scope of SLSA v1.0. However, you can
mitigate this threat by verifying SLSA provenance for all of your runtime
dependencies that provide provenance.
Example: The artifact dynamically links libBar and requires a binary version
to run. The adversary compromises libBar‘s build process and inserts malicious
code. When your artifact runs, it contains the adversary’s malicious code.
Build threats
A build integrity threat is a potential for an adversary to introduce behavior
to an artifact without changing its source code, or to build from a
source, dependency, and/or process that is not intended by the software
producer.
The SLSA Build track mitigates these threats when the consumer
verifies artifacts against expectations, confirming
that the artifact they received was built in the expected manner.
(E) Compromise build process
An adversary introduces an unauthorized change to a build output through
tampering of the build process; or introduces false information into the
provenance.
These threats are directly addressed by the SLSA Build track.
Forge values of the provenance (other than output digest) (Build L2+)
Threat: Generate false provenance and get the trusted control plane to sign
it.
Mitigation: At Build L2+, the trusted control plane generates all
information that goes in the provenance, except (optionally) the output artifact
hash. At Build L3+, this is hardened to prevent compromise even
by determined adversaries.
Example 1 (Build L2): Provenance is generated on the build worker, which the
adversary has control over. Adversary uses a malicious process to get the build
service to claim that it was built from source repo good/my-package when it
was really built from evil/my-package. Solution: Builder generates and signs
the provenance in the trusted control plane; the worker reports the output
artifacts but otherwise has no influence over the provenance.
Example 2 (Build L3): Provenance is generated in the trusted control plane,
but workers can break out of the container to access the signing material.
Solution: Builder is hardened to provide strong isolation against tenant
projects.
Forge output digest of the provenance (n/a)
Threat: The tenant-controlled build process sets output artifact digest
(subject in SLSA Provenance) without the trusted control plane verifying that
such an artifact was actually produced.
Mitigation: None; this is not a problem. Any build claiming to produce a given
artifact could have actually produced it by copying it verbatim from input to
output. (Reminder: Provenance is only a claim that a particular
artifact was built, not that it was published to a particular registry.)
Example: A legitimate MyPackage artifact has digest abcdef and is built
from source repo good/my-package. A malicious build from source repo
evil/my-package claims that it built artifact abcdef when it did not.
Solution: Verifier rejects because the source location does not match; the
forged digest is irrelevant.
Compromise project owner (Build L2+)
Threat: An adversary gains owner permissions for the artifact’s build project.
Mitigation: The build project owner must not have the ability to influence the
build process or provenance generation.
Example: MyPackage is built on Awesome Builder under the project “mypackage”.
Adversary is an administrator of the “mypackage” project. Awesome Builder allows
administrators to debug build machines via SSH. An adversary uses this feature
to alter a build in progress.
Compromise other build (Build L3)
Threat: Perform a malicious build that alters the behavior of a benign
build running in parallel or subsequent environments.
Mitigation: Builds are isolated from one another, with no way for one to
affect the other or persist changes.
Example 1: A build service runs all builds for project MyPackage on
the same machine as the same Linux user. An adversary starts a malicious build
that listens for another build and swaps out source files, then starts a benign
build. The benign build uses the malicious build’s source files, but its
provenance says it used benign source files. Solution: The build platform
changes architecture to isolate each build in a separate VM or similar.
Example 2: A build service uses the same machine for subsequent
builds. An adversary first runs a build that replaces the make binary with a
malicious version, then subsequently runs an otherwise benign build. Solution:
The builder changes architecture to start each build with a clean machine image.
Steal cryptographic secrets (Build L3)
Threat: Use or exfiltrate the provenance signing key or some other
cryptographic secret that should only be available to the build service.
Mitigation: Builds are isolated from the trusted build service control
plane, and only the control plane has access to cryptographic
secrets.
Example: Provenance is signed on the build worker, which the adversary has
control over. Adversary uses a malicious process that generates false provenance
and signs it using the provenance signing key. Solution: Builder generates and
signs provenance in the trusted control plane; the worker has no access to the
key.
Poison the build cache (Build L3)
Threat: Add a malicious artifact to a build cache that is later picked up by a
benign build process.
Mitigation: Build caches must be isolate between builds to prevent
such cache poisoning attacks.
Example: Build system uses a build cache across builds, keyed by the hash of
the source file. Adversary runs a malicious build that creates a “poisoned”
cache entry with a falsified key, meaning that the value wasn’t really produced
from that source. A subsequent build then picks up that poisoned cache entry.
Compromise build platform admin (verification)
Threat: An adversary gains admin permissions for the artifact’s build platform.
Mitigation: The build platform must have controls in place to prevent and
detect abusive behavior from administrators (e.g. two-person approvals, audit
logging).
Example: MyPackage is built on Awesome Builder. Awesome Builder allows
engineers on-call to SSH into build machines to debug production issues. An
adversary uses this access to modify a build in progress. Solution: Consumers
do not accept provenance from the build platform unless they trust sufficient
controls are in place to prevent abusing admin privileges.
(F) Upload modified package
An adversary uploads a package not built from the proper build process.
Build with untrusted CI/CD (expectations)
Threat: Build using an unofficial CI/CD pipeline that does not build in the
correct way.
Mitigation: Verifier requires provenance showing that the builder matched an
expected value.
Example: MyPackage is expected to be built on Google Cloud Build, which is
trusted up to Build L3. Adversary builds on SomeOtherBuildService, which is only
trusted up to Build L2, and then exploits SomeOtherBuildService to inject
malicious behavior. Solution: Verifier rejects because builder is not as
expected.
Upload package without provenance (Build L1)
Threat: Upload a package without provenance.
Mitigation: Verifier requires provenance before accepting the package.
Example: Adversary uploads a malicious version of MyPackage to the package
repository without provenance. Solution: Verifier rejects because provenance is
missing.
Tamper with artifact after CI/CD (Build L1)
Threat: Take a benign version of the package, modify it in some way, then
re-upload it using the original provenance.
Mitigation: Verifier checks that the provenance’s subject matches the hash
of the package.
Example: Adversary performs a proper build, modifies the artifact, then
uploads the modified version of the package to the repository along with the
provenance. Solution: Verifier rejects because the hash of the artifact does not
match the subject found within the provenance.
Tamper with provenance (Build L2)
Threat: Perform a build that would not meet expectations, then modify the
provenance to make the expectations checks pass.
Mitigation: Verifier only accepts provenance with a valid cryptographic
signature or equivalent proving that the provenance came from an
acceptable builder.
Example: MyPackage is expected to be built by GitHub Actions from the
good/my-package repo. Adversary builds with GitHub Actions from the
evil/my-package repo and then modifies the provenance so that the source looks
like it came from good/my-package. Solution: Verifier rejects because the
cryptographic signature is no longer valid.
(G) Compromise package repo
An adversary modifies the package on the package repository using an
administrative interface or through a compromise of the infrastructure.
De-list artifact
Threat: The package repository stops serving the artifact.
Mitigation: N/A - This threat is out of scope of SLSA v1.0.
De-list provenance
Threat: The package repository stops serving the provenance.
Mitigation: N/A - This threat is out of scope of SLSA v1.0.
(H) Use compromised package
An adversary modifies the package after it has left the package repository, or
tricks the user into using an unintended package.
Typosquatting
Threat: Register a package name that is similar looking to a popular package
and get users to use your malicious package instead of the benign one.
Mitigation: Mostly outside the scope of SLSA. That said, the requirement
to make the source available can be a mild deterrent, can aid investigation or
ad-hoc analysis, and can complement source-based typosquatting solutions.
Availability threats
An availability threat is a potential for an adversary to deny someone from
reading a source and its associated change history, or from building a package.
SLSA v1.0 does not address availability threats, though future versions might.
(A)(B) Delete the code
Threat: Perform a build from a particular source revision and then delete that
revision or cause it to get garbage collected, preventing anyone from inspecting
the code.
Mitigation: Some system retains the revision and its version control history,
making it available for inspection indefinitely. Users cannot delete the
revision except as part of a transparent legal or privacy process.
Example: An adversary submits malicious code to the MyPackage GitHub repo,
builds from that revision, then does a force push to erase that revision from
history (or requests that GitHub delete the repo.) This would make the revision
unavailable for inspection. Solution: Verifier rejects the package because it
lacks a positive attestation showing that some system, such as GitHub, ensured
retention and availability of the source code.
(D) A dependency becomes temporarily or permanently unavailable to the build process
Threat: Unable to perform a build with the intended dependencies.
Mitigation: Outside the scope of SLSA. That said, some solutions to
support hermetic and reproducible builds may also reduce the impact of this
threat.
Verification threats
Threats that can compromise the ability to prevent or detect the supply chain
security threats above.
Tamper with recorded expectations
Threat: Modify the verifier’s recorded expectations, causing the verifier to
accept an unofficial package artifact.
Mitigation: Changes to recorded expectations requires some form of
authorization, such as two-party review.
Example: The package ecosystem records its expectations for a given package
name in a configuration file that is modifiable by that package’s producer. The
configuration for MyPackage expects the source repository to be
good/my-package. The adversary modifies the configuration to also accept
evil/my-package, and then builds from that repository and uploads a malicious
version of the package. Solution: Changes to the recorded expectations require
two-party review.
Forge change metadata
Threat: Forge the change metadata to alter attribution, timestamp, or
discoverability of a change.
Mitigation: Source control platform strongly authenticates actor identity,
timestamp, and parent revisions.
Example: Adversary submits a git commit with a falsified author and timestamp,
and then rewrites history with a non-fast-forward update to make it appear to
have been made long ago. Solution: Consumer detects this by seeing that such
changes are not strongly authenticated and thus not trustworthy.
Exploit cryptographic hash collisions
Threat: Exploit a cryptographic hash collision weakness to bypass one of the
other controls.
Mitigation: Require cryptographically secure hash functions for commit
checksums and provenance subjects, such as SHA-256.
Examples: Construct a benign file and a malicious file with the same SHA-1
hash. Get the benign file reviewed and then submit the malicious file.
Alternatively, get the benign file reviewed and submitted and then build from
the malicious file. Solution: Only accept cryptographic hashes with strong
collision resistance.
Provenance
To trace software back to the source and define the moving parts in a complex
supply chain, provenance needs to be there from the very beginning. It’s the
verifiable information about software artifacts describing where, when and how
something was produced. For higher SLSA levels and more resilient integrity
guarantees, provenance requirements are stricter and need a deeper, more
technical understanding of the predicate.
This document defines the following predicate type within the in-toto
attestation framework:
"predicateType": "https://slsa.dev/provenance/v1-rc2"
Important: Always use the above string for predicateType rather than what is
in the URL bar. The predicateType URI will always resolve to the latest
minor version of this specification. See parsing rules for
more information.
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.
Purpose
Describe how an artifact or set of artifacts was produced so that:
- Consumers of the provenance can verify that the artifact was built according
to expectations.
- Others can rebuild the artifact, if desired.
This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 provenance
requirements.
Model
Provenance is an attestation that a particular build platform produced a set of
software artifacts through execution of the buildDefinition.
The model is as follows:
-
Each build runs as an independent process on a multi-tenant build platform.
The builder.id identifies this platform, representing the transitive
closure of all entities that are trusted to faithfully run the build and
record the provenance. (Note: The same model can be used for platform-less
or single-tenant build systems.)
-
The build process is defined by a parameterized template, identified by
buildType. This encapsulates the process that ran, regardless of what
system ran it. Often the build type is specific to the build platform
because most build platforms have their own unique interfaces.
-
All top-level, independent inputs are captured by the parameters to the
template. There are two types of parameters:
-
externalParameters: the external interface to the build. In SLSA,
these values are untrusted; they MUST be included in the provenance and
MUST be verified downstream.
-
systemParameters: set internally by the platform. In SLSA, these
values are trusted because the platform is trusted; they are OPTIONAL
and need not be verified downstream. They MAY be included to enable
reproducible builds, debugging, or incident response.
-
All artifacts fetched during initialization or execution of the build
process are considered dependencies, including those referenced directly by
parameters. The resolvedDependencies captures these dependencies, if
known. For example, a build that takes a git repository URI as a parameter
might record the specific git commit that the URI resolved to as a
dependency.
-
During execution, the build process might communicate with the build
platform’s control plane and/or build caches. This communication is not
captured directly in the provenance, but is instead implied by builder.id
and subject to SLSA Requirements. Such
communication SHOULD NOT influence the definition of the build; if it does,
it SHOULD go in resolvedDependencies instead.
-
Finally, the build process outputs one or more artifacts, identified by
subject.
For concrete examples, see index of build types.
Parsing rules
This predicate follows the in-toto attestation parsing rules. Summary:
- Consumers MUST ignore unrecognized fields unless otherwise noted.
- The
predicateType URI includes the major version number and will always
change whenever there is a backwards incompatible change.
- Minor version changes are always backwards compatible and “monotonic.”
Such changes do not update the
predicateType.
- Unset, null, and empty field values MUST be interpreted equivalently.
Schema
NOTE: This subsection describes the fields within predicate. For a description
of the other top-level fields, such as subject, see Statement.
{% include_relative schema/provenance.cue %}
Protocol buffer schema
Link: provenance.proto
{% include_relative schema/provenance.proto %}
Provenance
REQUIRED for SLSA Build L1: buildDefinition, runDetails
| Field | Type | Description
|
|---|
buildDefinition
| BuildDefinition |
The input to the build. The accuracy and completeness are implied by
runDetails.builder.id.
|
runDetails
| RunDetails |
Details specific to this particular execution of the build.
|
BuildDefinition
REQUIRED for SLSA Build L1: buildType, externalParameters
| Field | Type | Description
|
|---|
buildType
| string (TypeURI) |
Identifies the template for how to perform the build and interpret the
parameters and dependencies.
The URI SHOULD resolve to a human-readable specification that includes: overall
description of the build type; schema for externalParameters and
systemParameters; unambiguous instructions for how to initiate the build given
this BuildDefinition, and a complete example. Example:
https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1
|
externalParameters
| object |
The parameters that are under external control, such as those set by a user or
tenant of the build system. They MUST be complete at SLSA Build L3, meaning that
that there is no additional mechanism for an external party to influence the
build. (At lower SLSA Build levels, the completeness MAY be best effort.)
The build system SHOULD be designed to minimize the size and complexity of
externalParameters, in order to reduce fragility and ease verification.
Consumers SHOULD have an expectation of what “good” looks like; the more
information that they need to check, the harder that task becomes.
Verifiers SHOULD reject unrecognized or unexpected fields within
externalParameters.
|
systemParameters
| object |
The parameters that are under the control of the entity represented by
builder.id. The primary intention of this field is for debugging, incident
response, and vulnerability management. The values here MAY be necessary for
reproducing the build. There is no need to verify these
parameters because the build system is already trusted, and in many cases it is
not practical to do so.
NOTE: This field is named internalParameters in v1 final.
|
resolvedDependencies
| array (ResourceDescriptor) |
Unordered collection of artifacts needed at build time. Completeness is best
effort, at least through SLSA Build L3. For example, if the build script
fetches and executes “example.com/foo.sh”, which in turn fetches
“example.com/bar.tar.gz”, then both “foo.sh” and “bar.tar.gz” SHOULD be
listed here.
|
The BuildDefinition describes all of the inputs to the build. It SHOULD contain
all the information necessary and sufficient to initialize the build and begin
execution.
The externalParameters and systemParameters are the top-level inputs to the
template, meaning inputs not derived from another input. Each is an arbitrary
JSON object, though it is RECOMMENDED to keep the structure simple with string
values to aid verification. The same field name SHOULD NOT be used for both
externalParameters and systemParameters.
The parameters SHOULD only contain the actual values passed in through the
interface to the build system. Metadata about those parameter values,
particularly digests of artifacts referenced by those parameters, SHOULD instead
go in resolvedDependencies. The documentation for buildType SHOULD explain
how to convert from a parameter to the dependency uri. For example:
"externalParameters": {
"repository": "https://github.com/octocat/hello-world",
"ref": "refs/heads/main"
},
"resolvedDependencies": [{
"uri": "git+https://github.com/octocat/hello-world@refs/heads/main",
"digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"}
}]
Guidelines:
-
Maximize the amount of information that is implicit from the meaning of
buildType. In particular, any value that is boilerplate and the same
for every build SHOULD be implicit.
-
Reduce parameters by moving configuration to input artifacts whenever
possible. For example, instead of passing in compiler flags via an external
parameter that has to be verified separately, require the
flags to live next to the source code or build configuration so that
verifying the latter automatically verifies the compiler flags.
-
In some cases, additional external parameters might exist that do not impact
the behavior of the build, such as a deadline or priority. These extra
parameters SHOULD be excluded from the provenance after careful analysis
that they indeed pose no security impact.
-
If possible, architect the build system to use this definition as its
sole top-level input, in order to guarantee that the information is
sufficient to run the build.
-
When build configuration is evaluated client-side before being sent to the
server, such as transforming version-controlled YAML into ephemeral JSON,
some solution is needed to make verification practical. Consumers need a
way to know what configuration is expected and the usual way to do that is
to map it back to version control, but that is not possible if the server
cannot verify the configuration’s origins. Possible solutions:
-
(RECOMMENDED) Rearchitect the build service to read configuration
directly from version control, recording the server-verified URI in
externalParameters and the digest in resolvedDependencies.
-
Record the digest in the provenance and use a separate
provenance attestation to link that digest back to version control. In
this solution, the client-side evaluation is considered a separate
“build” that SHOULD be independently secured using SLSA, though securing
it can be difficult since it usually runs on an untrusted workstation.
-
The purpose of resolvedDependencies is to facilitate recursive analysis of
the software supply chain. Where practical, it is valuable to record the
URI and digest of artifacts that, if compromised, could impact the build. At
SLSA Build L3, completeness is considered “best effort”.
RunDetails
REQUIRED for SLSA Build L1: builder
| Field | Type | Description
|
|---|
builder
| Builder |
Identifies the build platform that executed the invocation, which is trusted to
have correctly performed the operation and populated this provenance.
|
metadata
| BuildMetadata |
Metadata about this particular execution of the build.
|
byproducts
| array (ResourceDescriptor) |
Additional artifacts generated during the build that are not considered
the “output” of the build but that might be needed during debugging or
incident response. For example, this might reference logs generated during
the build and/or a digest of the fully evaluated build configuration.
In most cases, this SHOULD NOT contain all intermediate files generated during
the build. Instead, this SHOULD only contain files that are likely to be useful
later and that cannot be easily reproduced.
|
Builder
REQUIRED for SLSA Build L1: id
| Field | Type | Description
|
|---|
id
| string (TypeURI) |
URI indicating the transitive closure of the trusted build platform. This is
intended
to be the sole determiner of the SLSA Build level.
If a build platform has multiple modes of operations that have differing
security attributes or SLSA Build levels, each mode MUST have a different
builder.id and SHOULD have a different signer identity. This is to minimize
the risk that a less secure mode compromises a more secure one.
The builder.id URI SHOULD resolve to documentation explaining:
- The scope of what this ID represents.
- The claimed SLSA Build level.
- The accuracy and completeness guarantees of the fields in the provenance.
- Any fields that are generated by the tenant-controlled build process and not
verified by the trusted control plane, except for the
subject.
- The interpretation of any extension fields.
|
builderDependencies
| array (ResourceDescriptor) |
Dependencies used by the orchestrator that are not run within the workload
and that do not affect the build, but might affect the provenance generation
or security guarantees.
|
version
| map (string→string) |
Map of names of components of the build platform to their version.
|
The build platform, or builder for short, represents the transitive
closure of all the entities that are, by necessity, trusted to faithfully run
the build and record the provenance. This includes not only the software but the
hardware and people involved in running the service. For example, a particular
instance of Tekton could be a build platform, while
Tekton itself is not. For more info, see Build
model.
The id MUST reflect the trust base that consumers care about. How detailed to
be is a judgement call. For example, GitHub Actions supports both GitHub-hosted
runners and self-hosted runners. The GitHub-hosted runner might be a single
identity because it’s all GitHub from the consumer’s perspective. Meanwhile,
each self-hosted runner might have its own identity because not all runners are
trusted by all consumers.
Consumers MUST accept only specific signer-builder pairs. For example, “GitHub”
can sign provenance for the “GitHub Actions” builder, and “Google” can sign
provenance for the “Google Cloud Build” builder, but “GitHub” cannot sign for
the “Google Cloud Build” builder.
Design rationale: The builder is distinct from the signer in order to support
the case where one signer generates attestations for more than one builder, as
in the GitHub Actions example above. The field is REQUIRED, even if it is
implicit from the signer, to aid readability and debugging. It is an object to
allow additional fields in the future, in case one URI is not sufficient.
⚠ RFC: Do we want/need to identify the tenant of the build system,
separately from the build system itself? If so, a single id
that combines both (e.g.
https://builder.example/tenants/company1.example/project1) or two separate
fields (e.g. {"id": "https://builder.example", "tenant": "https://company1.example/project1"})? What would the use case be for this?
How does verification work?
REQUIRED: (none)
| Field | Type | Description
|
|---|
invocationId
| string |
Identifies this particular build invocation, which can be useful for finding
associated logs or other ad-hoc analysis. The exact meaning and format is
defined by builder.id; by default it is treated as opaque and case-sensitive.
The value SHOULD be globally unique.
|
startedOn
| string (Timestamp) |
The timestamp of when the build started.
|
finishedOn
| string (Timestamp) |
The timestamp of when the build completed.
|
Extension fields
Implementations MAY add extension fields to any JSON object to describe
information that is not captured in a standard field. Guidelines:
- Extension fields SHOULD use names of the form
<vendor>_<fieldname>, e.g.
examplebuilder_isCodeReviewed. This practice avoids field name collisions
by namespacing each vendor. Non-extension field names never contain an
underscore.
- Extension fields MUST NOT alter the meaning of any other field. In other
words, an attestation with an absent extension field MUST be interpreted
identically to an attestation with an unrecognized (and thus ignored)
extension field.
- Extension fields SHOULD follow the monotonic principle,
meaning that deleting or ignoring the extension SHOULD NOT turn a DENY
decision into an ALLOW.
Verification
Please see Verifying Artifacts for a detailed discussion of
provenance verification.
Index of build types
The following is an partial index of build type definitions. Each contains a
complete example predicate.
To add an entry here, please send a pull request on GitHub.
Migrating from 0.2
To migrate from version 0.2 (old), use the following
pseudocode. The meaning of each field is unchanged unless otherwise noted.
{
"buildDefinition": {
// The `buildType` MUST be updated for v1.0 to describe how to
// interpret `inputArtifacts`.
"buildType": /* updated version of */ old.buildType,
"externalParameters":
old.invocation.parameters + {
// It is RECOMMENDED to rename "entryPoint" to something more
// descriptive.
"entryPoint": old.invocation.configSource.entryPoint,
// It is OPTIONAL to rename "source" to something more descriptive,
// especially if "source" is ambiguous or confusing.
"source": old.invocation.configSource.uri,
},
"systemParameters": old.invocation.environment,
"resolvedDependencies":
old.materials + [
{
"uri": old.invocation.configSource.uri,
"digest": old.invocation.configSource.digest,
}
]
},
"runDetails": {
"builder": {
"id": old.builder.id,
"builderDependencies": null, // not in v0.2
"version": null, // not in v0.2
},
"metadata": {
"invocationId": old.metadata.buildInvocationId,
"startedOn": old.metadata.buildStartedOn,
"finishedOn": old.metadata.buildFinishedOn,
},
"byproducts": null, // not in v0.2
},
}
The following fields from v0.2 are no longer present in v1.0:
entryPoint: Use externalParameters[<name>] instead.buildConfig: No longer inlined into the provenance. Instead, either:
- If the configuration is a top-level input, record its digest in
externalParameters["config"].
- Else if there is a known use case for knowing the exact resolved
build configuration, record its digest in
byproducts. An example use
case might be someone who wishes to parse the configuration to look for
bad patterns, such as curl | bash.
- Else omit it.
metadata.completeness: Now implicit from builder.id.metadata.reproducible: Now implicit from builder.id.
Change history
v1.0 RC2
Major refactor to reduce misinterpretation, including a minor change in model.
- Significantly expanded all documentation.
- Altered the model slightly to better align with real-world build systems,
align with reproducible builds, and make verification easier.
- Grouped fields into
buildDefinition vs runDetails.
- Renamed:
parameters -> externalParameters (slight change in semantics)environment -> systemParameters (slight change in semantics)materials -> resolvedDependencies (slight change in semantics)buildInvocationId -> invocationIdbuildStartedOn -> startedOnbuildFinishedOn -> finishedOn
- Removed:
configSource: No longer special-cased. Now represented as
externalParameters + resolvedDependencies.buildConfig: No longer inlined into the provenance. Can be replaced
with a reference in externalParameters or byproducts, depending on
the semantics, or omitted if not needed.completeness and reproducible: Now implied by builder.id.
- Added:
- ResourceDescriptor:
annotations, content, downloadLocation,
mediaType, name
- Builder:
builderDependencies and version
byproducts
- Changed naming convention for extension fields.
v0.2
Refactored to aid clarity and added buildConfig. The model is unchanged.
- Replaced
definedInMaterial and entryPoint with configSource.
- Renamed
recipe to invocation.
- Moved
invocation.type to top-level buildType.
- Renamed
arguments to parameters.
- Added
buildConfig, which can be used as an alternative to configSource
to validate the configuration.
rename: slsa.dev/provenance
Renamed to “slsa.dev/provenance”.
v0.1.1
- Added
metadata.buildInvocationId.
v0.1
Initial version, named “in-toto.io/Provenance”
Verification Summary Attestation (VSA)
Verification summary attestations communicate that an artifact has been verified
at a specific SLSA level and details about that verification.
This document defines the following predicate type within the in-toto
attestation framework:
"predicateType": "https://slsa.dev/verification_summary/v1-rc2"
Important: Always use the above string for predicateType rather than what is
in the URL bar. The predicateType URI will always resolve to the latest
minor version of this specification. See parsing rules for
more information.
Purpose
Describe what SLSA level an artifact or set of artifacts was verified at
and other details about the verification process including what SLSA level
the dependencies were verified at.
This allows software consumers to make a decision about the validity of an
artifact without needing to have access to all of the attestations about the
artifact or all of its transitive dependencies. They can use it to delegate
complex policy decisions to some trusted party and then simply trust that
party’s decision regarding the artifact.
It also allows software producers to keep the details of their build pipeline
confidential while still communicating that some verification has taken place.
This might be necessary for legal reasons (keeping a software supplier
confidential) or for security reasons (not revealing that an embargoed patch has
been included).
Model
A Verification Summary Attestation (VSA) is an attestation that some entity
(verifier) verified one or more software artifacts (the subject of an
in-toto attestation Statement) by evaluating the artifact and a bundle
of attestations against some policy. Users who trust the verifier may
assume that the artifacts met the indicated SLSA level without themselves
needing to evaluate the artifact or to have access to the attestations the
verifier used to make its determination.
The VSA also allows consumers to determine the verified levels of
all of an artifact’s transitive dependencies. The verifier does this by
either a) verifying the provenance of each non-source dependency listed in
the resolvedDependencies of the artifact
being verified (recursively) or b) matching the non-source dependency
listed in resolvedDependencies (subject.digest ==
resolvedDependencies.digest and, ideally, vsa.resourceUri ==
resolvedDependencies.uri) to a VSA for that dependency and using
vsa.verifiedLevels and vsa.dependencyLevels. Policy verifiers wishing
to establish minimum requirements on dependencies SLSA levels may use
vsa.dependencyLevels to do so.
Schema
// Standard attestation fields:
"_type": "https://in-toto.io/Statement/v1",
"subject": [{
"name": <NAME>,
"digest": { <digest-in-request> }
}],
// Predicate
"predicateType": "https://slsa.dev/verification_summary/v1-rc2",
"predicate": {
// Required
"verifier": {
"id": "<URI>"
},
"timeVerified": <TIMESTAMP>,
"resourceUri": <artifact-URI-in-request>,
"policy": {
"uri": "<URI>",
"digest": { /* DigestSet */ }
}
"inputAttestations": [
{
"uri": "<URI>",
"digest": { <digest-of-attestation-data> }
},
...
],
"verificationResult": "<PASSED|FAILED>",
"verifiedLevels": ["<SlsaResult>"],
"dependencyLevels": {
"<SlsaResult>": <Int>,
"<SlsaResult>": <Int>,
...
},
"slsaVersion": "<MAJOR>.<MINOR>",
}
Parsing rules
This predicate follows the in-toto attestation parsing rules. Summary:
- Consumers MUST ignore unrecognized fields.
- The
predicateType URI includes the major version number and will always
change whenever there is a backwards incompatible change.
- Minor version changes are always backwards compatible and “monotonic.” Such
changes do not update the
predicateType.
- Producers MAY add extension fields using field names that are URIs.
Fields
NOTE: This subsection describes the fields within predicate. For a description
of the other top-level fields, such as subject, see Statement.
verifier object, required
Identifies the entity that performed the verification.
The identity MUST reflect the trust base that consumers care about. How
detailed to be is a judgment call.
Consumers MUST accept only specific (signer, verifier) pairs. For example,
“GitHub” can sign provenance for the “GitHub Actions” verifier, and “Google”
can sign provenance for the “Google Cloud Deploy” verifier, but “GitHub” cannot
sign for the “Google Cloud Deploy” verifier.
The field is required, even if it is implicit from the signer, to aid readability and
debugging. It is an object to allow additional fields in the future, in case one
URI is not sufficient.
verifier.id string (TypeURI), required
URI indicating the verifier’s identity.
timeVerified string (Timestamp), required
Timestamp indicating what time the verification occurred.
resourceUri string (ResourceURI), required
URI that identifies the resource associated with the artifact being verified.
policy object (ResourceDescriptor), required
Describes the policy that the subject was verified against.
The entry MUST contain a uri.
inputAttestations array (ResourceDescriptor), optional
The collection of attestations that were used to perform verification.
Conceptually similar to the resolvedDependencies field in SLSA Provenance.
This field MAY be absent if the verifier does not support this feature.
If non-empty, this field MUST contain information on all the attestations
used to perform verification.
Each entry MUST contain a digest of the attestation and SHOULD contains a
uri that can be used to fetch the attestation.
verificationResult string, required
Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification.
verifiedLevels array (SlsaResult), required
Indicates the highest level of each track verified for the artifact (and not
its dependencies), or “FAILED” if policy verification failed.
Users MUST NOT include more than one level per SLSA track. Note that each SLSA
level implies all levels below it (e.g. SLSA_BUILD_LEVEL_3 implies
SLSA_BUILD_LEVEL_2 and SLSA_BUILD_LEVEL_1), so there is no need to
include more than one level per track.
dependencyLevels object, optional
A count of the dependencies at each SLSA level.
Map from SlsaResult to the number of the artifact’s transitive dependencies
that were verified at the indicated level. Absence of a given level of
SlsaResult MUST be interpreted as reporting 0 dependencies at that level.
Users MUST count each dependency only once per SLSA track, at the highest
level verified. For example, if a dependency meets SLSA_BUILD_LEVEL_2,
you include it with the count for SLSA_BUILD_LEVEL_2 but not the count for
SLSA_BUILD_LEVEL_1.
slsaVersion string, optional
Indicates the version of the SLSA specification that the verifier used, in the
form <MAJOR>.<MINOR>. Example: 1.0. If unset, the default is an
unspecified minor version of 1.x.
Example
WARNING: This is just for demonstration purposes.
"_type": "https://in-toto.io/Statement/v1",
"subject": [{
"name": "out/example-1.2.3.tar.gz",
"digest": {"sha256": "5678..."}
}],
// Predicate
"predicateType": "https://slsa.dev/verification_summary/v1-rc2",
"predicate": {
"verifier": {
"id": "https://example.com/publication_verifier"
},
"timeVerified": "1985-04-12T23:20:50.52Z",
"resourceUri": "https://example.com/example-1.2.3.tar.gz",
"policy": {
"uri": "https://example.com/example_tarball.policy",
"digest": {"sha256": "1234..."}
},
"inputAttestations": [
{
"uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl",
"digest": {"sha256": "abcd..."}
}
],
"verificationResult": "PASSED",
"verifiedLevels": ["SLSA_LEVEL_3"],
"dependencyLevels": {
"SLSA_BUILD_LEVEL_3": 5,
"SLSA_BUILD_LEVEL_2": 7,
"SLSA_BUILD_LEVEL_1": 1,
},
"slsaVersion": "1.0"
}
SlsaResult (String)
The result of evaluating an artifact (or set of artifacts) against SLSA.
SHOULD be one of these values:
- SLSA_BUILD_LEVEL_0
- SLSA_BUILD_LEVEL_1
- SLSA_BUILD_LEVEL_2
- SLSA_BUILD_LEVEL_3
- FAILED (Indicates policy evaluation failed)
Note that each SLSA level implies the levels below it. For example,
SLSA_BUILD_LEVEL_3 means (SLSA_BUILD_LEVEL_1 + SLSA_BUILD_LEVEL_2 +
SLSA_BUILD_LEVEL_3).
Users MAY use custom values here but MUST NOT use custom values starting with
SLSA_.
Change history
- 1:
- Replaced
materials with resolvedDependencies.
- Relaxed
SlsaResult to allow other values.
- Converted to lowerCamelCase for consistency with SLSA Provenance.
- Added
slsaVersion field.
- 0.2:
- Added
resource_uri field.
- Added optional
input_attestations field.
- 0.1: Initial version.
