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 the Working Draft of what the next version of the SLSA
specification might be. It defines several SLSA levels and tracks, as
well as recommended attestation formats, including provenance.
This is Version 1.2 of the SLSA specification, which defines the SLSA Build
and Source tracks.
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.
Provides an overview of each track and links to more specific information.
Build Track
These sections describe the build track’s security levels and requirements. If you want to achieve a particular level of the SLSA build track these are the requirements you’ll need to meet.
The SLSA build track is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This section is a descriptive overview of the SLSA build track levels, describing their intent.
Guidelines for securing SLSA Build L3+ builders, intended for platform implementers
Build Environment Track
These sections describe the build environment track’s security levels and requirements. If you want to achieve a particular level of the SLSA build environment track these are the requirements you’ll need to meet.
Overview of SLSA’s Attested Build Environment track, intended for all audiences
Dependency Track
This sections describes the dependency track’s security levels and requirements. If you want to achieve a particular level of the SLSA dependency track these are the requirements you’ll need to meet.
These sections describe the source track’s security levels and requirements. If you want to achieve a particular level of the SLSA source track these are the requirements you’ll need to meet.
SLSA allows a common way to express verified properties that may not fit within a SLSA track.
Attestation formats
These sections include the concrete schemas for SLSA attestations. The Provenance and VSA formats are recommended, but not required by the specification.
This document describes the major changes brought by this Working
Draft relative to the prior release, v1.1.
Summary of changes
Addition of the Source Track which helps
organizations secure their source code development process and consumers
establish trust in that source.
Updated the threat model to account for the threats mitigated by
the Source Track.
Improved the structure of the spec to accomodate multiple tracks.
Addition of SLSA Verified Properties that allows
software supply chain controls that don’t fit neatly within existing SLSA
levels or that do exist within SLSA levels but where their is utility in
recognizing the specific control while the software might not meet all the
other requirements of that level.
About SLSA
This section is an introduction to SLSA and its concepts. If you’re new
to SLSA, start here!
What is SLSA?
Supply-chain Levels for Software Artifacts, or SLSA (“salsa”), 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
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 of May 12th, 2021.
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 platform (by marking
artifacts with a factory “stamp” that shows which build platform created it)
Threats against the build platform (by providing “manufacturing facility”
best practices for build platform services)
In short: everyone involved in producing and consuming software, or providing
infrastructure for software.
Software producers, such as an open source project, a software vendor, or a
team writing first-party code for use within the same company. SLSA gives you
protection against tampering along the supply chain to your consumers, both
reducing insider risk and 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 platform. 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.
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.
Producer trust: SLSA does not address organizations that intentionally
produce malicious software, but it can reduce insider risks within an
organization you trust.
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 threat overview
{The Supply Chain Problem}
Introduction to Supply Chain Attacks
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 outlines possible attacks throughout the supply chain and how
SLSA can help.
Threats can be mitigated because SLSA’s primary focus is supply chain integrity. 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: Ensures that the source revision represents the intent of the producer, that all expected processes were followed and that the revision was not modified after being accepted.
Build integrity: Ensures 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.
SLSA can provide additional mitigation because its secondary focus is on availablity:
Availability: Ensures 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.
SLSA 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.
Supply chain threat model
This supply chain threat model diagram shows where threats can occur in the supply chain sequence of events. The letters (A) through (I) represent different threats and are explained in the real-world example table below. For more technical details on supply chain threats, see Threats & mitigations.
Note: SLSA does not currently address all of the threats presented in the diagram.
Real-world examples of Supply Chain threats
Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA’s framework.
The table below outlines a set of real world supply chain threat problems and explains how SLSA can mitigate them. Each threat in this table has a label of (A) through (I). These labels coincide with the red triangle threat locations in the diagram above. See the Threats & Mitigations section for in-depth details on threat problems and SLSA solutions.
Threats from
Known example
How SLSA could help
A
Producer
SpySheriff: Software producer purports to offer anti-spyware software, but that software is actually malicious.
SLSA does not directly address this threat but could make it easier to discover malicious behavior in open source software, by forcing it into the publicly available source code.
For closed source software SLSA does not provide any solutions for malicious producers.
B
Authoring & reviewing
SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself.
Two-person review could have caught the unauthorized change.
C
Source code management
PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits.
A better-protected source code system would have been a much harder target for the attackers.
D
External build parameters
The Great Suspender: Attacker published software that was not built from the purported sources.
A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering.
E
Build process
SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build.
CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly.
Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo.
G
Distribution channel
Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages.
Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo.
H
Package selection
Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original.
SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions.
I
Usage
Default credentials: Attacker could leverage default credentials to access sensitive data.
SLSA does not address this threat.
N/A
Dependency threats (i.e. A-H, recursively)
event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code.
Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source.
Availability threat
Known example
How SLSA could help
N/A
Dependency becomes unavailable
Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily.
SLSA does not directly address this threat.
{Applying SLSA}
The sections in this subsection provide information on general concepts of how and where to put SLSA into practice. They define SLSA use cases and guiding principles.
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. This section defines the three most common settings where supply chain problems threaten the security of different types of software producing organizations. They include: first party organizations,
oopen source software producers, and vendor services.
First party organizations
How SLSA can be used here: 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 of 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 registry.
How SLSA can be used here: 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 platforms rather than the many thousands of developers with upload
permissions across various packages.
Example of 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.
How SLSA can be used here: Reducing risk from consuming vendor provided software and services.
SLSA can also 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 the trustworthiness of claims made
by the vendor.
Example of 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 by a trusted third-party auditor.
Hypothetical example
For a look at how SLSA might be applied to open source in the future, see the
hypothetical curl example.
Guiding principles
Best practices for implementing the slsa specification are outlined on this section. They include
advice on how to achieve the best outcomes through:
simplicity, trust and verify, minimize platforms, using attestations, anonymous contributors.
Simple levels with clear outcomes
Use levels to communicate security state and to
encourage a large population to improve its security stance over time. When
necessary, split levels into separate tracks to recognize progress in unrelated
security areas.
Reasoning: Levels simplify how to think about security by boiling a complex
topic into an easy-to-understand number. It is clear that level N is better than
level N-1, even to someone with passing familiarity. This provides a convenient
way to describe the current security state as well as a natural path to improvement.
Guidelines:
Define levels in terms of concrete security outcomes. Each level should
have clear and meaningful security value, such as stopping a particular
class of threats. Levels should represent security milestones, not just
incremental progress. Give each level an easy-to-remember mnemonic, such as
“Provenance exists.”
Balance level granularity. Too many levels makes SLSA hard to understand
and remember; too few makes each level hard to achieve. Collapse levels
until each step requires a non-trivial but manageable amount of work to
implement. Separate levels if they require significant work from multiple
distinct parties, such as infrastructure work plus user behavior changes, so
long as the intermediate level still has some security value (prior bullet).
Use tracks sparingly. Additional tracks add extra complexity to SLSA, so
a new track should be seen as a last resort. Each track should have a clear,
distinct purpose with a crisply defined objective, such as trustworthy
provenance for the Build track. As a rule of thumb, a
new track may be warranted if it addresses threats unrelated to another
track. Try to avoid tracks that sound confusingly similar in either name or
objective.
Trust platforms, verify artifacts
Establish trust in a small number of platforms and systems—such as change management, build,
and packaging platforms—and then automatically verify the many artifacts
produced by those platforms.
Reasoning: Trusted computing bases are unavoidable—there’s no choice but
to trust some platforms. Hardening and verifying platforms is difficult and
expensive manual work, and each trusted platform expands the attack surface of the
supply chain. Verifying that an artifact is produced by a trusted platform,
though, is easy to automate.
To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited
number of platforms and then automate verification of the artifacts produced by those platforms.
The attack surface and work to establish trust do not scale with the number of artifacts produced,
as happens when artifacts each use a different trusted platform.
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
platform to ensure that it meets the SLSA Build Track requirements. Following the
analysis, the public keys used by the build platform to sign provenance are
“trusted” up to the given SLSA level. Downstream platforms verify the provenance
signed by the public key to automatically determine that an artifact meets the
SLSA level.
Corollary: Minimize the number of trusted platforms
A corollary to this principle is to minimize the size of the trusted computing
base. Every platform 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 platform, use a
shared build platform. 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 platforms.
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. Individuals, 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 platform’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 platform pulls only
from the proper source, package registry allows access only to the CI/CD platform,
and so on. We might infer that we can trust artifacts produced by these platforms
based on the platform’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 platform 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 platforms from the trust base and ensures that
individuals who are accidentally granted access do not have sufficient permission to tamper with the package.
Support anonymous and pseudonymous contributions
SLSA supports anonymous and pseudonymous ‘identities’ within the software supply chain.
While organizations that implement SLSA may choose otherwise, SLSA itself does not require,
or encourage, participants to be mapped to their legal identities.
Nothing in this specification should be taken to mean that SLSA requires participants to
reveal their legal identity.
Reasoning: SLSA uses identities for multiple purposes: as a trust anchor for attestations
(i.e. who or what is making this claim and do I trust it to do so) or for attributing actions
to an actor. Choice of identification technology is left to the organization and technical
stacks implementing the SLSA standards.
When identities are strongly authenticated and used consistently they can often be leveraged
for both of these purposes without requiring them to be mapped to legal identities.
This reflects how identities are often used in open source where legal name means much less
to projects than the history and behavior of a given handle over time does. Meanwhile, some
organizations may choose to levy additional requirements on identities. They are free to do
so, but SLSA itself does not require it.
Benefits: By not requiring legal identities SLSA lowers the barriers to its adoption,
enabling all of its other benefits and maintaining support for anonymous and pseudonymous
contribution as has been practiced in the software industry for decades.
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
providesmanybenefits,
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 platforms to
corroborate the provenance of a build. In this way, one can create an overall
platform 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 platform 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.
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.
Q. What is the difference between a build platform, system, and service?
Build platform and build system have been used interchangeably in the past. With
the v1.0 specification, however, there has been a unification around the term
platform as indicated in the Terminology. The use of the word
system still exists related to software and services within the build platform
and to systems outside of a build platform like change management systems.
A build service is a hosted build platform that is often run on shared infrastructure
instead of individuals’ machines and workstations. Its use has also been replaced outside
of the requirements as it relates to the build platform.
Q: Is SLSA the same as TACOS?
No.
Trusted Attestation and Compliance for Open Source (TACOS)
is a framework authored by Tidelift.
Per their website, TACOS is a framework
“for assessing the development practices of open source projects
against a set of secure development standards specified by the (US)
NIST Secure Software Development Framework (SSDF) V1.1” which
“vendors can use to provide self-attestation for the open source components
they rely on.”
In contrast, SLSA is a community-developed framework—including
adoptable guidelines for securing a software supply chain and
mechanism to evaluate the trustworthiness of artifacts you consume—that
is part of the Open Source Security Foundation (OpenSSF).
Q: How does SLSA and SLSA Provenance relate to SBOM?
Software Bill of Materials (SBOM) are a frequently recommended tool for
increased software supply chain rigor. An SBOM is typically focused on
understanding software in order to evaluate risk through known vulnerabilities
and license compliance. These use-cases require fine-grained and timely data
which can be refined to improve signal-to-noise ratio.
SLSA Provenance and the Build track are focused on trustworthiness of the
build process. To improve trustworthiness, Provenance is generated in the build
platform’s trusted control plane, which in practice results in it being coarse
grained. For example, in Provenance metadata completeness of
resolvedDependencies information is on a best-effort basis. Further, the
ResourceDescriptor type does not require version and license information or
even a URI to the dependency’s original location.
While they likely include similar data, SBOMs and SLSA Provenance operate at
different levels of abstraction. The fine-grained data in an SBOM typically
describes the components present in a produced artifact, whereas SLSA
Provenance more coarsely describes parameters of a build which are external to
the build platform.
The granularity and expressiveness of the two use-cases differs enough that
current SBOM formats were deemed not a good fit for the requirements of
the Build track. Yet SBOMs are a good practice and may form part of a future
SLSA Vulnerabilities track. Further, SLSA Provenance can increase the
trustworthiness of an SBOM by describing how the SBOM was created.
SLSA Provenance, the wider in-toto Attestation Framework in which the
recommended format sits, and the various SBOM standards, are all rapidly
evolving spaces. There is ongoing investigation into linking between the
different formats and exploration of alignment on common models. This FAQ entry
describes our understanding of the intersection efforts today. We do not know
how things will evolve over the coming months and years, but we look forward to
the collaboration and improved software supply chain security.
Q: How to SLSA with a self-hosted runner
Some CI systems allow producers to provide their own self-hosted runners as a build
environment (e.g. GitHub Actions). While there are many valid reasons to leverage
these, classifying the SLSA build level for the resulting artifact can be confusing.
Since the SLSA Build track describes increasing levels of trustworthiness and
completeness in a package artifact’s provenance, interpretation of the
specification hinges on the platform entities involved in the provenance generation.
The SLSA build level requirements (secure key storage, isolation, etc.) should be
imposed on the transitive closure of the systems which are responsible for informing
the provenance generated.
Some common situations may include:
The platform generates the provenance and just calls a runner for individual items.
In this situation, the provenance is only affected by the platform so there would be
no requirements imposed on the runner.
The runner generates the provenance. In this situation, the orchestrating platform
is irrelevant and all requirements are imposed on the runner.
The platform provides the runner with some credentials for generating the provenance
or both the platform and the runner provide information for the provenance. Trust is
shared between the platform and the runner so the requirements are imposed on both.
Additional requirements on the self-hosted runners may be added to Build levels
greater than L3 when such levels get defined.
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 platform and enabling
corroboration 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 verifiers
to recursively apply SLSA to dependencies.
Reproducible builds, which enable other build platforms to corroborate the
provenance.
Platform Operations track
A Platform Operations track could provide assurances around the hardening of
platforms (e.g. build or source platforms) as they are operated.
Controls for approval, logging, and auditing of all physical and remote
access to platform infrastructure, cryptographic secrets, and privileged
debugging interfaces.
Conformance to security best practices to minimize the risk of compromise.
Protection of cryptographic secrets used by the build platform.
Tracks
SLSA is composed of multiple tracks which are each
composed of multiple levels. Each track addresses different threats
and has its own set of requirements and patterns of use.
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.
The SLSA source track provides producers and consumers with increasing levels of
trust in the source code they produce and consume. It describes increasing
levels of trustworthiness and completeness of how a source revision was created.
The expected process for creating a new revision is determined solely by that
repository’s owner (the organization) who also determines the intent of the
software in the repository and administers technical controls to enforce the
process.
Consumers can review attestations to verify whether a particular revision meets
their standards.
The goal of a Build Environment track is to enable the detection of tampering
with core components of the compute environment executing builds. The track
describes increasing levels of integrity for different components of the
build platform and its underlying compute platform.
At a general level, implementers of this track will generate SLSA Build
Provenance for build images, validate the integrity of a build’s environment
at boot time against good known values, and at L3 deploy the build system on
compute that supports system state measurement and attestation capabilities at
the hardware level.
The goal of Dependency Track is to enable a software producer to measure, control and reduce risk introduced from third party dependencies.
The Dependency Track is primarily aimed at enterprises/organizations, with medium to large-sized organizations benefiting the most from adoption of the dependency track levels. Organizations include enterprises, but also large open source projects that want to manage third party dependency risk.
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. In 1.2 the Source Track reintroduces
coverage of source code.
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:
Follow a consistent build process so that others can form
expectations about what a “correct” build looks like.
Run builds on a build platform that meets Build L1 requirements.
Distribute provenance to consumers, preferably using a convention
determined by the package ecosystem.
Build platform:
Automatically generate 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.
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 platforms
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: Hosted build platform
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 platform that generates and
signs1 the provenance.
Intended for
Projects and organizations wanting to gain moderate security benefits of SLSA by
switching to a hosted build platform, while waiting for changes to the build
platform itself required by Build L3.
Run builds on a hosted build platform that meets Build L2
requirements.
Build platform:
Generate and sign1 the provenance itself. This may be done
during the original build, an after-the-fact reproducible build, or
some equivalent system that ensures the trustworthiness of the
provenance.
Prevents tampering during the build—by insider threats, compromised
credentials, or other tenants.
Greatly reduces the impact of compromised package upload credentials by
requiring the 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.
Alternate means of verifying the authenticity of the provenance are
also acceptable. ↩
Build: Terminology
Before diving into the Build Track, 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.
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.
The channel through which artifacts are “published” for use by others.
A registry like DockerHub or npm. Artifacts may also be distributed via physical media (e.g., a USB drive).
Package
Artifact that is distributed. 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 (distribution). 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 platform’s maintainers.
Build model
We model a build as running on a multi-tenant build platform, where each
execution is independent.
A tenant invokes the build by specifying external parameters through an
interface, either directly or via some trigger. Usually, at least one of
these external parameters is a reference to a dependency. (External
parameters are literal values while dependencies are artifacts.)
The build platform’s control plane interprets these external parameters,
fetches an initial set of dependencies, initializes a build environment,
and then starts the execution within that environment.
The build then performs arbitrary steps, which might include fetching
additional dependencies, and then produces one or more output artifacts.
The steps within the build environment are under the tenant’s control.
The build platform isolates build environments from one another to some
degree (which is measured by the SLSA Build Level).
Finally, for SLSA Build L2+, the control plane outputs provenance
describing this whole process.
Notably, there is no formal notion of “source” in the build model, just external
parameters and dependencies. Most build platforms have an explicit “source”
artifact to build from, which is often a git repository; in the build model, the
reference to this artifact is an external parameter while the artifact itself is
a dependency.
For examples of how this model applies to real-world build platforms, see index
of build types.
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 platform component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant’s control.
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.
Build caches
An intermediate artifact storage managed by the platform that maps intermediate artifacts to their explicit inputs. A build may share build caches with any subsequent build running on the platform.
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.
Ambiguous terms to avoid
Build recipe: Could mean external parameters, but may include concrete
steps of how to perform a build. To avoid implementation details, we don’t
define this term, but always use “external parameters” which is the
interface to a build platform. Similar terms are build configuration
source and build definition.
Builder: Usually means build platform, but might be used for build
environment, the user who invoked the build, or a build tool from
dependencies. To avoid confusion, we always use “build platform”. The only
exception is in the provenance, where builder is used as
a more concise field name.
Distribution model
Software is distributed in identifiable units called packages
according to 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
distribution platform, such as a package registry, to resolve a
mutable package name into an immutable package artifact.
1 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
Distribution platform
An entity responsible for mapping package names to immutable package artifacts.
Package
An identifiable unit of software intended for distribution, ambiguously meaning either an “artifact” or a “package name”. Only use this term when the ambiguity is acceptable or desirable.
Package artifact
A file or other immutable object that is intended for distribution.
Package ecosystem
A set of rules and conventions governing how packages are distributed, including how clients resolve a package name into one or more specific artifacts.
Package manager client
Client-side tooling to interact with a package ecosystem.
Package name
The primary identifier for a mutable collection of artifacts that all represent different versions of the same software. This is the primary identifier that consumers use to obtain the software.
A package name is specific to an ecosystem + registry, has a maintainer, is more general than a specific hash or version, and has a “correct” source location. A package ecosystem may group package names into some sort of hierarchy, such as the Group ID in Maven, though SLSA does not have a special term for this.
Package registry
A specific type of “distribution platform” used within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries.
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!
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 platform is
certified to ensure conformance with the requirements at the level claimed by
the build platform. This certification should happen on a recurring cadence, with
the outcomes published by the platform operator for their users to review and
make informed decisions about which builders to trust.
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 platform 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.
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 platform assessment
The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their adherence to SLSA requirements.
Example: Open source language distribution
Term
Example
Expectations
Defined separately for each package and stored in the package registry.
Provenance verification
The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages.
Build platform assessment
Performed by the language ecosystem packaging authority.
Build: Requirements for producing artifacts
This section covers the detailed technical requirements for producing artifacts at
each SLSA level. The intended audience is platform implementers and security
engineers.
For an informative description of the levels intended for all audiences, see
Build Track Basics. 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 platform. The build platform MUST
strengthen the security controls in order to achieve a specific level while the
producer MUST choose and adopt a build platform capable of achieving a desired
build level, implementing any controls as specified by the chosen platform.
While the exact definition of what constitutes a secure platform is beyond the
scope of this specification, all implementations MUST use industry security
best practices to be conformant to this specification. This includes, but is
not limited to, using proper access controls, securing communications,
implementing proper management of cryptographic secrets, doing frequent updates,
and promptly fixing known vulnerabilities.
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 platform
The producer MUST select a build platform that is capable of reaching their
desired SLSA Build Level.
For example, if a producer wishes to produce a Build Level 3 artifact, they MUST
choose a builder capable of producing Build Level 3 provenance.
Follow a consistent build process
The producer MUST build their artifact in a consistent
manner such that verifiers can form expectations about the build process. In
some implementations, the producer MAY provide explicit metadata to a verifier
about their build process. In others, the verifier will form their expectations
implicitly (e.g. trust on first use).
If a producer wishes to distribute their artifact through a package ecosystem
that requires explicit metadata about the build process in the form of a
configuration file, the producer MUST complete the configuration file and keep
it up to date. This metadata might include information related to the artifact’s
source repository and build parameters.
Distribute provenance
The producer MUST distribute provenance to artifact consumers. The producer
MAY delegate this responsibility to the
package ecosystem, provided that the package ecosystem is capable of
distributing provenance.
Build Platform
A package’s build platform is the infrastructure used to transform the
software from source to package. This includes the transitive closure of all
hardware, software, persons, and organizations that can influence the build. A
build platform is often a hosted, multi-tenant build service, but it could be a
system of multiple independent rebuilders, a special-purpose build platform used
by a single software project, or even an individual’s workstation. Ideally, one
build platform is used by many different software packages so that consumers can
minimize the number of trusted platforms. For more background,
see Build Model.
The build platform is responsible for generating provenance describing how the
package was produced.
The SLSA Build level describes the overall provenance integrity according to
minimum requirements on its:
Completeness: What information is contained in the provenance?
Authenticity: How strongly can the provenance be tied back to the builder?
Accuracy: How resistant is the provenance generation to tampering within
the build process?
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 platform and other entities that are
necessary to trust in order to trust the artifact they produced.
This SHOULD be through a digital signature from a private key accessible only
to the build platform component that generated the provenance attestation.
While many constraints affect choice of signing methodologies, it is
RECOMMENDED that build platforms use signing methodologies which improve the
ability to detect and remediate key compromise, such as methods which rely on
transparency logs or, when transparency isn’t appropriate, time stamping
services.
Authenticity allows the consumer to trust the contents of the provenance
attestation, such as the identity of the build platform.
Accuracy: The provenance MUST be generated by the control plane (i.e. within
the trust boundary identified in the provenance) and not by a tenant of the
build platform (i.e. outside the trust boundary), except as noted below.
The data in the provenance MUST be obtained from the build platform, either
because the generator is the build platform or because the provenance
generator reads the data directly from the build platform.
The build platform MUST have some security control to prevent tenants from
tampering with the provenance. However, there is no minimum bound on the
strength. The purpose is to deter adversaries who might face legal or
financial risk from evading controls.
Exceptions for fields that MAY be generated by a tenant of the build platform:
Any field that is not marked as REQUIRED for Build L2. For example,
resolvedDependencies in SLSA Provenance MAY be tenant-generated at
Build L2. Builders SHOULD document any such cases of tenant-generated
fields.
Completeness: SHOULD be complete.
There MAY be external parameters that are not sufficiently captured in
the provenance.
Completeness of resolved dependencies is best effort.
✓
✓
Provenance is Unforgeable
Accuracy: Provenance MUST be strongly resistant to forgery by tenants.
Any secret material used for authenticating the provenance, for example the
signing key used to generate a digital signature, MUST be stored in a secure
management system appropriate for such material and accessible only to the
build service account.
Such secret material MUST NOT be accessible to the environment running
the user-defined build steps.
Every field in the provenance MUST be generated or verified by the build
platform in a trusted control plane. The user-controlled build steps MUST
NOT be able to inject or alter the contents, except as noted in Provenance
is Authentic. (Build L3 does not require additional
fields beyond those of L2.)
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 platform is responsible for isolating between builds, even within the
same tenant project. In other words, how strong of a guarantee do we have that
the build really executed correctly, without external influence?
The SLSA Build level describes the minimum bar for isolation strength. For more
information on assessing a build platform’s isolation strength, see
Assessing build platforms.
Requirement
Description
L1
L2
L3
Hosted
All build steps ran using a hosted build platform on shared or dedicated
infrastructure, not on an individual’s workstation.
Examples: GitHub Actions, Google Cloud Build, Travis CI.
✓
✓
Isolated
The build platform ensured that the build steps ran in an isolated environment,
free of unintended external influence. In other words, any external influence on
the build was specifically requested by the build itself. This MUST hold true
even between builds within the same tenant project.
The build platform MUST guarantee the following:
It MUST NOT be possible for a build to access any secrets of the build
platform, such as the provenance signing key, because doing so would
compromise the authenticity of the provenance.
It MUST NOT be possible for two builds that overlap in time to influence one
another, such as by altering the memory of a different build process running
on the same machine.
It MUST NOT be possible for one build to persist or influence the build
environment of a subsequent build. In other words, an ephemeral build
environment MUST be provisioned for each build.
It MUST NOT be possible for one build to inject false entries into a build
cache used by another build, also known as “cache poisoning”. In other
words, the output of the build MUST be identical whether or not the cache is
used.
The build platform MUST NOT open services that allow for remote influence
unless all such interactions are captured as externalParameters in the
provenance.
There are no sub-requirements on the build itself. Build L3 is limited to
ensuring that a well-intentioned build runs securely. It does not require that
a build platform prevents a producer from performing a risky or insecure build. In
particular, the “Isolated” requirement does not prohibit a build from calling
out to a remote execution service or a “self-hosted runner” that is outside the
trust boundary of the build platform.
NOTE: This requirement was split into “Isolated” and “Ephemeral Environment”
in the initial draft version (v0.1).
NOTE: This requirement is not to be confused with “Hermetic”, which roughly
means that the build ran with no network access. Such a requirement requires
substantial changes to both the build platform and each individual build, and is
considered in the future directions.
✓
Build: 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 provider in the critical path for installers that want to
verify policy at build-time.
Publish attestations alongside the artifact in the package registry:
Many software repositories already support some variety of publishing 1:1
related files alongside an artifact, sometimes known as “sidecar files”.
For example, PyPI supports publishing .asc files representing the PGP
signature for an artifact with the same filename (but different extension).
This option requires the mapping between artifact and attestation (or
attestation vessel) to be 1:1.
Publish attestations elsewhere, record their existence in a transparency
log: Once an attestation has been generated and published for a build, a
hash of the attestation and a pointer to where it is indexed SHOULD be
published to a third-party transparency log that exists outside the source
repository and package registry. Not only are transparency logs such as
Rekor from Sigstore guaranteed
to be immutable, but they typically also make monitoring easier.
Requiring the presence of the attestation in a monitored transparency log
during verification helps ensure the attestation is trustworthy.
Combining these options gives us a process for bootstrapping SLSA adoption
within an ecosystem, even if the package registry doesn’t support publishing
attestations. First, interested projects modify their release process to
produce SLSA provenance. Then, they publish that provenance to their source
repository. Finally, they publish the provenance to the package registry, if
and when the registry supports it.
Long-term, package registries SHOULD support uploading and distributing
provenance alongside the artifact. This model is preferred for two reasons:
trust: clients already trust the package registry as the source of their
artifacts, and don’t need to trust an additional service;
reliability: clients already depend on the package registry as part of
their critical path, so distributing provenance via the registry avoids
adding an additional point of failure.
Short term, consumers of build artifacts can bootstrap a manual policy by using
the source repository only for projects that publish all artifacts and
attestations to the source repository, and later extend this to all artifacts
published to the package registry via the canonical installation tools once
a given ecosystem supports them.
Immutability of attestations
Attestations SHOULD be immutable. Once an attestation is published as it
corresponds to a given artifact, that attestation is immutable and cannot be
overwritten later with a different attestation that refers to the same
artifact. Instead, a new release (and new artifacts) SHOULD be created.
Format of the attestation
The provenance is available to the consumer in a format that the consumer
accepts. The format SHOULD be in-toto
SLSA Build Provenance, 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.
Build: 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.
See Terminology for an explanation of the supply chain model and
Threats & mitigations for a detailed explanation of each threat.
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).
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.
Look up the SLSA Build Level in the roots of trust, using the recognized
public keys and the builder.id, defaulting to SLSA Build L1.
Resulting threat mitigation:
Threat “E”: SLSA Build L3 requires protection against compromise of the
build process and provenance generation by an external adversary, such as
persistence between builds or theft of the provenance signing key. In other
words, SLSA Build L3 establishes that the provenance is accurate and
trustworthy, assuming you trust the build platform.
IMPORTANT: SLSA Build L3 does not cover compromise of the build
platform itself, such as by a malicious insider. Instead, verifiers
SHOULD carefully consider which build platforms are added to the roots
of trust. For advice on establishing trust in build platforms, see
Assessing build platforms.
Threat “F”: SLSA Build L2 covers tampering of the artifact or provenance
after the build. This is accomplished by verifying the subject and
signature in the steps above.
Threat “G”: Verification by the consumer or otherwise outside of the
package registry covers compromise of the registry itself. (Verifying within
the registry at publication time is also valuable, but does not cover Threat
“G” or “I”.)
Threat “I”: Verification by the consumer covers compromise of the package
in transit. (Many ecosystems also address this threat using package
signatures or checksums.)
NOTE: SLSA does not yet cover adversaries tricking a consumer to use an
unintended package, such as through typosquatting. Those threats are
discussed in more detail under Threat “H”.
Step 2: Check expectations
Next, check that the package’s provenance meets your expectations for that
package in order to mitigate threat “D”.
In our threat model, the adversary has the ability to invoke a build and to publish
to the registry. The adversary is not able to write to the source repository, nor do
they have insider access to any trusted systems. Your expectations SHOULD be
sufficient to detect or prevent this adversary from injecting unofficial
behavior into the package.
You SHOULD compare the provenance against expected values for at least the
following fields:
To prevent an adversary from building the correct code on an unintended platform
Canonical source repository
To prevent an adversary from building from an unofficial fork (or other disallowed source)
buildType
To ensure that externalParameters are interpreted as intended
externalParameters
To prevent an adversary from injecting unofficial behavior
Verification tools SHOULD reject unrecognized fields in externalParameters to
err on the side of caution. It is acceptable to allow a parameter to have a
range of values (possibly any value) if it is known that any value in the range
is safe. JSON comparison is sufficient for verifying parameters.
TIP: Difficulty in forming meaningful expectations about externalParameters can
be a sign that the buildType’s level of abstraction is too low. For example,
externalParameters that record a list of commands to run is likely impractical
to verify because the commands change on every build. Instead, consider a
buildType that defines the list of commands in a configuration file in a
source repository, then put only the source repository in
externalParameters. Such a design is easier to verify because the source
repository is constant across builds.
Step 3: (Optional) Check dependencies recursively
Finally, recursively check the resolvedDependencies as available and to the
extent desired. Note that SLSA v1.0 does not have any requirements on the
completeness or verification of resolvedDependencies. However, one might wish
to verify dependencies in order to mitigate dependency threats and protect against
threats further up the supply chain. If resolvedDependencies is incomplete,
these checks can be done on a best-effort basis.
A Verification Summary Attestation (VSA) 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.)
Forming Expectations
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
There are several options (non-mutually exclusive) for where provenance verification
can happen: the package ecosystem at upload time, the consumers at download time, or
via a continuous monitoring system. Each option comes with its own set of
considerations, but all are valid and at least one SHOULD be used.
More than one component can verify provenance. For example, even if a package
ecosystem verifies provenance, consumers who get artifacts from that package
ecosystem might wish to verify provenance themselves for defense in depth. They
can do so using either client-side verification tooling or by polling a
monitor.
Package ecosystem
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. This option is RECOMMENDED whenever
possible because doing so benefits all of the package ecosystem’s clients.
The package ecosystem is responsible for making its expectations available to
consumers, reliably redistributing artifacts and provenance, and providing tools
to enable safe artifact consumption (e.g. whether an artifact meets
expectations).
Consumer
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 automated system takes
action in response to the failed verification.
Build: Assessing build platforms
One of SLSA’s guiding principles is to “trust platforms, verify
artifacts”. However, consumers cannot trust platforms 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 platform that consumers SHOULD assess
and provides sample questions consumers can ask when assessing a build platform.
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 D, E, F, and G for examples of specific threats.
Note: Platform abuse (e.g. running non-build workloads) and attacks against
builder availability are out of scope of this document.
Adversary profiles
Consumers SHOULD also evaluate the build platform’s ability to defend against the
following types of adversaries.
Project contributors, who can:
Create builds on the build platform. These are the adversary’s controlled
builds.
Modify one or more controlled builds’ external parameters.
Modify one or more controlled builds’ environments and run arbitrary
code inside those environments.
Read the target build’s source repo.
Fork the target build’s source repo.
Modify a fork of the target build’s source repo and build from it.
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 platform administrators, who can:
Do everything listed under “project contributors” and “project
maintainers”.
Run arbitrary code on the build platform.
Read and modify network traffic.
Access the control plane’s cryptographic secrets.
Remotely access build environments (e.g. via SSH).
Build platform components
Consumers SHOULD consider at least these five elements of the
build model when assessing build platforms 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 platform’s ability to produce SLSA Build L3 provenance.
The assessment SHOULD take into account the security model used to identify the
transitive closure of the builder.id for the
provenance model, specifically around the
platform’s boundaries, actors, and interfaces.
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 platform component that orchestrates each
independent build execution. It is responsible for setting up each build and
cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs
provenance for each build performed on the build platform. The control plane is
operated by one or more administrators, who have privileges to modify the
control plane.
Prompts for assessing the control plane
Administration
What are the ways an employee can use privileged access to influence a
build or provenance generation? Examples: physical access, terminal
access, access to cryptographic secrets
What controls are in place to detect or prevent the employee from
abusing such access? Examples: two-person approvals, audit logging,
workload identities
Roughly how many employees have such access?
How are privileged accounts protected? Examples: two-factor
authentication, client device security policies
What plans do you have for recovering from security incidents and platform
outages? Are they tested? How frequently?
Provenance generation
How does the control plane observe the build to ensure the provenance’s
accuracy?
Are there situations in which the control plane will not generate
provenance for a completed build? What are they?
Development practices
How do you track the control plane’s software and configuration?
Example: version control
How do you build confidence in the control plane’s software supply
chain? Example: SLSA L3+ provenance, build from source
How do you secure communications between builder components? Example:
TLS with certificate transparency.
Are you able to perform forensic analysis on compromised build
environments? How? Example: retain base images indefinitely
Creating build environments
How does the control plane share data with build environments? Example:
mounting a shared file system partition
How does the control plane protect its integrity from build
environments? Example: not mount its own file system partitions on
build environments
How does the control plane prevent build environments from accessing its
cryptographic secrets? Examples: dedicated secret storage, not mounting
its own file system partitions to build environments, hardware security
modules
Managing cryptographic secrets
How do you store the control plane’s cryptographic secrets?
Which parts of the organization have access to the control plane’s
cryptographic secrets?
What controls are in place to detect or prevent employees abusing such
access? Examples: two-person approvals, audit logging
How are secrets protected in memory? Examples: secrets are stored in
hardware security modules and backed up in secure cold storage
How frequently are cryptographic secrets rotated? Describe the rotation
process.
What is your plan for remediating cryptographic secret compromise? How
frequently is this plan tested?
Build environment
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 is separation achieved between trusted and untrusted processes?
How have you hardened your build environments against malicious tenants?
Examples: configuration hardening, limiting attack surface
How frequently do you update your isolation software?
What is your process for responding to vulnerability disclosures? What
about vulnerabilities in your dependencies?
What prevents a malicious build from gaining persistence and influencing
subsequent builds?
Creation and destruction
What operating system and utilities are available in build environments
on creation? How were these elements chosen? Examples: A minimal Linux
distribution with its package manager, OSX with HomeBrew
How long could a compromised build environment remain active in the
build platform?
Network access
Are build environments able to call out to remote execution? If so, how
do you prevent them from tampering with the control plane or other build
environments over the network?
Are build environments able to open services on the network? If so, how
do you prevent remote interference through these services?
Cache
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 and can include information such as the security model defined as
part of the provenance. Evidence submitted for third-party certification need not
be published.
Build Environment track
Rationale
Today’s hosted build platforms play a central role in an artifact’s supply
chain. Whether it’s a cloud-hosted service like GitHub Actions or an internal
enterprise CI/CD system, the build platform has a privileged level of access
to artifacts and sensitive operations during a build (e.g., access to
producer secrets, provenance signing).
This central and privileged role makes hosted build platforms an attractive
target for supply chain attackers. But even with strong economic and
reputational incentives to mitigate these risks, it’s very challenging to
implement and operate fully secure build platforms because they are made up
of many layers of interconnected components and subsystems.
The SLSA Build Environment track aims to address these issues by making it
possible to validate the integrity and trace the provenance of core build
platform components.
Track overview
The SLSA Build Environment (BuildEnv) track describes increasing levels of
integrity and trustworthiness of the provenance of a build’s
execution context. In this track, provenance describes how a build image
was created, how the hosted build platform deployed a build image in its
environment, and the compute platform they used.
Tampering via the compute platform’s host interface
The compute platform’s hardware
:warning:
The Build Environment track L1+ currently requires a hosted build platform.
A future version of this track may generalize requirements to cover bare-metal
build environments.
:grey_exclamation:
We may consider the addition of an L4 to the Build Environment track, which
covers hardware-attested runtime integrity checking during a build.
An immutable identifier assigned uniquely to a specific execution of a tenant’s build. In practice, the build ID may be an identifier, such as a UUID, associated with the build execution.
Build image
The template for a build environment, such as a VM or container image. Individual components of a build image include the root filesystem, pre-installed guest OS and packages, the build executor, and the build agent.
Build image producer
The party that creates and distributes build images. In practice, the build image producer may be the hosted build platform or a third party in a bring-your-own (BYO) build image setting.
Build agent
A build platform-provided program that interfaces with the build platform’s control plane from within a running build environment. The build agent is also responsible for executing the tenant’s build definition, i.e., running the build. In practice, the build agent may be loaded into the build environment after instantiation, and may consist of multiple components. All build agent components must be measured along with the build image.
Build dispatch
The process of assigning a tenant’s build to a pre-deployed build environment on a hosted build platform.
Compute platform
The compute system and infrastructure underlying a build platform, i.e., the host system (hypervisor and/or OS) and hardware. In practice, the compute platform and the build platform may be managed by the same or distinct organizations.
Host interface
The component in the compute platform that the hosted build platform uses to request resources for deploying new build environments, i.e., the VMM/hypervisor or container orchestrator.
Boot process
In the context of builds, the process of loading and executing the layers of firmware and/or software needed to start up a build environment on the host compute platform.
Measurement
The cryptographic hash of some component or system state in the build environment, including software binaries, configuration, or initialized run-time data.
Quote
(Virtual) hardware-signed data that contains one or more (virtual) hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata. (Based on the definition in section 9.5.3.1 of the TPM 2.0 spec)
Reference value
A specific measurement used as the good known value for a given build environment component or state.
TODO: Disambiguate similar terms (e.g., image, build job, build executor/runner)
Build environment lifecycle
A typical build environment will go through the following lifecycle:
Build image creation: A build image producer
creates different build images through a dedicated build
process. For the SLSA BuildEnv track, the build image producer outputs
provenance describing this process.
Build environment instantiation: The hosted build platform
calls into the host interface to create a new instance
of a build environment from a given build image. The
build agent begins to wait for an incoming
build dispatch.
For the SLSA BuildEnv track, the host interface in the compute platform
attests to the integrity of the environment’s initial state during its
boot process.
Build dispatch: When the tenant dispatches a new build, the hosted
build platform assigns the build to a created build environment.
For the SLSA BuildEnv track, the build platform attests to the binding
between a build environment and build ID.
Build execution: Finally, the build agent within the environment executes
the tenant’s build definition.
Build environment threats
The SLSA Build track defines requirements for the provenance that is produced for the build artifacts.
Trustworthiness of the build process largely depends on the trustworthiness of the build environment the build runs in.
The Build track assumes full trust into the Build Platform, and provides no requirements to verify integrity of the build environment.
BuildEnv track intends to close this gap.
Build environment is bootstrapped from a build image, which is expected to be an artifact of a SLSA build pipeline.
Build platform verifies image security properties including provenance upon starting up the environment and makes evidence of the verification available to tenants or other auditors.
BuildEnv track assumes full trust in the software that comes with the build image or is installed at runtime.
Malicious software having privileged access within the build environment might be able to circumvent protections provided by the BuildEnv track.
Image providers should manage vulnerabilities in the image components to reduce the risks of such attacks, e.g. by using SLSA Dependency track and hardening images with mandatory access control (MAC) policies.
Control Plane may perform additional analysis of the image SBOM as it bootstraps the build environment.
Bootstrapping the build environment is a complex process, especially at higher SLSA levels.
Build L3 usually requires significant changes to existing build platforms to maintain ephemeral build environments.
It is not uncommon for the build platforms to rely on public cloud providers to manage the compute resources that power build environments.
This in turn significantly expands the attack surface because added build platform dependencies become part of the TCB.
Cloud providers are big companies with complex infrastructure that often provide limited abilities to scope the context of trust and continuously validate it over time when using their services.
The BuildEnv track addresses build TCB size concerns at BuildEnv L2 and BuildEnv L3 levels.
BuildEnv L1 level assumes full trust into the Build Platform including underlying Compute Platform (e.g., public cloud provider).
BuildEnv L2 level adds capabilities for verifying the Compute Platform providing evidence that the build environment is bootstrapped from the expected image with the expected early boot components (e.g. UEFI firmware) provided by the Compute Platform.
In essence L2 provides evidence of the boot time integrity of a build environment.
L2 also addresses malicious access to the build environment using compromised Build Platform Admin credentials assuming that image has Compute Platform maintenance agents disabled in it, which are typically used for providing remote access to the virtual machine using Compute Platform APIs.
It is the responsibility of the Image provider to disable/uninstall those agents.
Control Plane should verify that maintenance agents are disabled in the image upon consuming it.
BuildEnv L3 level reduces the Compute Platform attack surface through the use of trusted execution environments (TEEs) addressing runtime infrastructure threats that could be coming from compromised Compute Platform admin credentials (that would allow direct access to the host interface) or malicious software within the Compute Platform.
The SEV-SNP/TDX threat model describes this level of trust reduction through the use of memory encryption, integrity protection, and remote attestation with cryptographic keys that are certified by the hardware manufacturer.
L3 provides evidence of continuous integrity of the build environment for the whole lifetime.
TEE technologies are not infallible, so physical human access to hardware and side channel attacks are still a risk that is accepted at L3.
This diagram outlines the lifetime of a build image between its creation and use in bootstrapping a build environment.
A Build Image could be compromised at any stage of its lifetime.
Higher SLSA BuildEnv levels secure the build environment from larger classes of threats.
BuildEnv L1 protects from threats that happened during the build image distribution, i.e. in between image creation and consumption (e.g., pulling image from a shared registry) by the Build Platform.
This covers the case of unauthorized modifications to the image as it is distributed (potentially via untrusted channels).
BuildEnv L2 delivers boot time integrity providing cryptographic evidence that the build environment has been bootstrapped to an expected state.
The Compute platform is fully trusted at this level as it provides a virtual TPM device that performs boot measurements.
BuildEnv L3 extends boot time integrity into the run time all the way until the Build Environment is terminated.
L3 addresses threats coming from malicious actors (e.g., software agents or compromised admin credentials) in the Compute Platform host interface (see SEV-SNP/TDX threat model for the list of threats).
Vulnerabilities in the software that is legitimally included in the Build Image are out of scope.
Physical and side-channel attacks are out of scope too but may be considered in the additional future levels of this track.
Practically, achieving L3 requires the build running in a confidential VM using technologies like AMD SEV-SNP and Intel TDX.
Compute Platform footprint in TCB is reduced but may not be eliminated completely if a confidential VM uses custom virtualization components running within it (e.g., paravisor).
NOTE: Control Plane is considered trusted at L2 and L3 because it verifies the remote attestation of the build environment.
Build platforms MAY provide capabilities that let tenants perform remote attestation using a third-party verifier.
However, for the Control Plane to be considered untrusted it should have no back-door access to the build environment (e.g. via SSH).
Besides, Control Plane provides input data to the build environment (i.e. build request message) and security risks associated with compromising inputs have to be considered as well.
For the example threats refer to the Build Threats subsection.
BuildEnv levels
The primary purpose of the Build Environment (BuildEnv) track is to enable
auditing that a build was run in the expected execution context.
The lowest level only requires SLSA Build L2 Provenance to
exist for the build image, while higher levels provide increasing
auditability of the build environment’s properties and integrity of the
generated provenance attestations. The highest levels introduce further
requirements for hardware-assisted hardening of the compute platform
aimed at reducing the trusted computing base of a build.
Software producers and third-party auditors can check attestations generated
by the build image producer and build platform against the expected
properties for a given build environment. This enables any party to detect
several classes of supply chain threats originating in the build
environment.
As in the Build track, the exact implementation of this track is determined
by the build platform implementer, whether they are a commercial CI/CD service
or enterprise organization. While this track describes general minimum
requirements, this track does not dictate the following
implementation-specific details: the type of build environment, accepted
attestation formats, the type of technologies used to meet L3 requirements,
how attestations are distributed, how build environments are identified, and
what happens on failure.
BuildEnv L0: No guarantees
Summary
No requirements—L0 represents the lack of any sort of build environment
provenance.
Intended for
Development or test builds of software that are built and run on a local
machine, such as unit tests.
Requirements
n/a
Benefits
n/a
BuildEnv L1: Signed build image provenance exists
Summary
The build image (i.e., VM or container image) used to instantiate the build
environment has SLSA Build Provenance showing how the image was built.
Intended for
Build platforms and organizations wanting to ensure a baseline level of
integrity for build environments at the time of build image distribution.
Requirements
Build Image Producer:
MUST automatically generate SLSA Build L2 or higher
Provenance for created build images (i.e., VM or container images).
MUST allow independent automatic verification of a build image’s SLSA
Build Provenance. If the build image artifact cannot be published, for
example due to intellectual property concerns, an attestation asserting the
expected hash value of the build image MUST be generated and distributed
instead (e.g., using SCAI or a Release Attestation). If the full Build
Provenance document cannot be disclosed, a VSA asserting the build
image’s SLSA Provenance MUST be distributed instead.
Prior to the instantiation of a new build environment, the SLSA
Provenance for the selected build image MUST be automatically verified.
A signed attestation to the result of the SLSA Provenance verification
MUST be generated and distributed (e.g., via a VSA).
Benefits
Provides evidence that a build image was built from the advertised
source and build process.
The build environment is measured and authenticated by the compute platform
upon instantiation, attesting to the integrity of the initial state
of the environment prior to executing a build.
Intended for
Organizations wanting to ensure that their build started from
a clean, known good state.
Build images MUST be created via a SLSA Build L3 or higher build
process.
MUST automatically generate and distribute signed reference values
for the following build image components: bootloader or equivalent,
guest kernel, build agent, and root filesystem (e.g., via the image’s
SLSA Provenance, or SCAI).
Additional build image components whose initial state is to be checked
MAY be also measured.
The build agent MUST be capable of:
Upon completion of the boot process: Automatically interfacing
with the host interface to obtain and transmit a signed quote for the
build environment’s system state.
Upon build dispatch: Automatically generating and distributing
a signed attestation that binds its boot process quote to the
assigned build ID (e.g., using SCAI).
Prior to dispatching a tenant’s build to an instantiated environment,
a signed quote MUST be automatically requested from the build agent,
and the contained [measurements] verified against their boot process
reference values. A signed attestation to the result of the verification
MUST be generated and distributed (e.g., via a VSA).
Compute Platform Requirements:
The host interface MUST be capable of generating signed quotes for
the build environment’s system state.
In a VM-based environment, this MUST be achieved by enabling a feature
like vTPM, or equivalent, in the hypervisor.
For container-based environments, the container orchestrator MAY need
modifications to produce these attestations.
The host interface MUST validate the measurements of the build image
components against their signed references values during the build
environment’s boot process.
In a VM-based environment, this MUST be achieved by enabling a process
like Secure Boot, or equivalent, in the hypervisor.
For container-based environments, the container orchestrator MAY need
modifications to perform these checks.1
Prior to instantiating a new build environment, the host interface
MUST automatically verify the SLSA Provenance for the selected build
image. A signed attestation to the verification of the build image’s
SLSA Provenance MUST be automatically generated and distributed (e.g.,
via a VSA).
Benefits
Provides evidence that a build environment deployed by a hosted build
platform was instantiated from the expected build image and is at the
expected initial state, even in the face of a build platform-level
adversary.
BuildEnv L3: Hardware-attested build environment
Summary
The initial state of the build’s host environment is measured
and authenticated by trusted hardware, attesting to the integrity
of the build environment’s underlying compute stack prior to executing
a build.
Intended for
Organizations wanting strong assurances that their build ran on a good
known host environment.
Upon completion of the boot process: The build agent MUST be capable
of automatically interfacing with the trusted hardware component to
obtain a signed quote for the host interface’s boot process and
the environment’s system state.
Upon build dispatch: The generated dispatch attestation MUST include
the host interface’s boot process quote.
Build Platform Requirements:
Prior to dispatching a tenant’s build to an instantiated environment,
the measurements in the host interface’s boot process quote MUST be
automatically verified against their reference values.
A signed attestation to the result of the verification MUST be generated
and distributed (e.g., via a VSA).
Compute Platform Requirements:
MUST have trusted hardware capabilities, i.e., built-in physical
hardware features for generating measurements and quotes for its system
state. This SHOULD be achieved using a feature like TPM,
confidential computing, or equivalent.
MUST enable validation of the host interface’s boot process against
its reference values. This MUST be achieved by enabling a process
like Secure Boot, or equivalent, in the host platform.
Benefits
Provides hardware-authenticated evidence that a build ran in the expected
host environment, even in the face of a compromised host interface
(hypervisor/container orchestrator).
Considerations for Distributed Builds
TODO
Since containers are executed as processes on the host platform they do not contain a traditional bootloader that starts up the execution context. ↩
Source: Requirements for producing source
Objective
The primary purpose of the SLSA Source track is to provide producers and consumers with increasing levels of trust in the source code they produce and consume.
It describes increasing levels of trustworthiness and completeness of how a source revision was created.
The expected process for creating a new revision is determined solely by that repository’s owner (the organization) who also determines the intent of the software in the repository and administers technical controls to enforce the process.
Consumers can review attestations to verify whether a particular revision meets their standards.
Definitions
A Version Control System (VCS) is a system of software and protocols for
managing the version history of a set of files. Git, Mercurial, and Subversion
are all examples of version control systems.
The following terms apply to Version Control Systems:
Term
Description
Source Repository (Repo)
A self-contained unit that holds the content and revision history for a set of files, along with related metadata like Branches and Tags.
Source Revision
A specific, logically immutable snapshot of the repository’s tracked files. It is uniquely identified by a revision identifier, such as a cryptographic hash like a Git commit SHA or a path-qualified sequential number like 25@trunk/ in SVN. A Source Revision includes both the content (the files) and its associated version control metadata, such as the author, timestamp, and parent revision(s). Note: Path qualification is needed for version control systems that represent Branches and Tags using paths, such as Subversion and Perforce.
Named Reference
A user-friendly name for a specific source revision, such as main or v1.2.3.
Change
A modification to the state of the Source Repository, such as creation of a new Source Revision based on a previous Source Revision, or creation, deletion, or modification of a Named Reference.
Change History
A record of the history of Source Revisions that preceded a specific revision.
Branch
A Named Reference that moves to track the Change History of a cohesive line of development within a Source Repository. E.g. main, develop, feature-x
Tag
A Named Reference that is intended to be immutable. Once created, it is not moved to point to a different revision. E.g. v1.2.3, release-20250722
NOTE: The ‘branch’ and ‘tag’ features within version control systems may
not always align with the ‘Branch’ and ‘Tag’ definitions provided in this
specification. For example, in git and other version control systems, the UX may
allow ‘tags’ to be moved. Patterns like latest and nightly tags rely on this.
For the purposes of this specification these would be classified as ‘Named References’ and not as ‘Tags’.
A Source Control System (SCS) is a platform or combination of services
(self-hosted or SaaS) that hosts a Source Repository and provides a trusted
foundation for managing source revisions by enforcing policies for
authentication, authorization, and change management, such as mandatory code
reviews or passing status checks.
The following terms apply to Source Control Systems:
Term
Description
Organization
A set of people who collectively create Source Revisions within a Source Repository. Examples of organizations include open-source projects, a company, or a team within a company. The organization defines the goals of a Source Repository and the methods used to produce new Source Revisions.
Proposed Change
A proposal to make a Change in a Source Repository.
Source Provenance
Information about how a Source Revision came to exist, where it was hosted, when it was generated, what process was used, who the contributors were, and which parent revisions preceded it.
Source Roles
Role
Description
Administrator
A human who can perform privileged operations on one or more projects. Privileged actions include, but are not limited to, modifying the change history and modifying project- or organization-wide security policies.
Trusted person
A human who is authorized by the organization to propose and approve changes to the source.
Trusted robot
Automation authorized by the organization to act in explicitly defined contexts. The robot’s identity and codebase cannot be unilaterally influenced.
Untrusted person
A human who has limited access to the project. They MAY be able to read the source. They MAY be able to propose or review changes to the source. They MAY NOT approve changes to the source or perform any privileged actions on the project.
Onboarding
When onboarding a branch to the SLSA Source Track or increasing the level of
that branch, organizations are making claims about how the branch is managed
from that revision forward. This establishes continuity.
No claims are made for prior revisions.
Basics
NOTE: This table presents a simplified view of the requirements. See the
Requirements subsection for the full list of requirements for each
level.
Improved code quality and resistance to insider threats.
Level 1: Version controlled
Summary
The source is stored and managed through a modern version control system.
Intended for
Organizations currently storing source in non-standard ways who want to quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem with minimal impact to their current workflows.
Benefits
Migrating to the appropriate tools is an important first step on the road to operational maturity.
Level 2: History & Provenance
Summary
Branch history is continuous, immutable, and retained, and the
SCS issues Source Provenance Attestations for each new Source Revision.
The attestations provide contemporaneous, tamper-resistant evidence of when
changes were made, who made them, and which technical controls were enforced.
Intended for
All organizations of any size producing software of any kind.
Benefits
Reliable history allows organizations and consumers to track changes to software
over time, enabling attribution of those changes to the actors that made them.
Source Provenance provides strong, tamper-resistant evidence of the process that
was followed to produce a Source Revision.
Level 3: Continuous technical controls
Summary
The SCS is configured to enforce the Organization’s technical controls for specific Named References within the Source Repository.
Intended for
Organizations that want to show evidence of their additional technical controls.
Benefits
A verifier can use this published data to ensure that a given Source Revision
was created in the correct way by verifying the Source Provenance or VSA.
Provides verifiers strong evidence of all technical controls enforced during the update of a Named Reference.
Level 4: Two-party review
Summary
The SCS requires two trusted persons to review all changes to protected
branches.
Intended for
Organizations that want strong guarantees that the software they produce is not
subject to unilateral changes that would subvert their intent.
Benefits
Makes it harder for an actor to introduce malicious changes into the software
and makes it more likely that the source reflects the intent of the
organization.
Requirements
Many examples in this document use the
git version control system, but use of git is not a
requirement to meet any level on the SLSA source track.
An organization producing Source Revisions MUST select an SCS capable of reaching
their desired SLSA Source Level.
For example, if an organization wishes to produce revisions at Source Level 3,
they MUST choose a Source Control System capable of producing Source Level 3
attestations.
✓
✓
✓
✓
Configure the SCS to control access and enforce history 🔗
The organization MUST configure access controls to restrict sensitive operations
on the Source Repository. These controls MUST be implemented using the
SCS-provided Identity Management capability.
For example, an organization may configure the SCS to assign users to a
maintainers role and only allow users in maintainers to make updates to
main.
The SCS MUST be configured to produce a reliable Change History for
its consumable Source Revisions.
If the SCS provides this capability by design, no additional controls are needed.
Otherwise the organization MUST provide evidence of continuous enforcement.
If the SCS supports Tags, the SCS MUST be configured to prevent them
from being moved or deleted.
For example, if a git tag release1 is used to indicate a release revision
with ID abc123, controls must be configured to prevent that tag from being
updated to any other revision in the future.
Evidence of these controls (and their continuity) will appear in the Source
Provenance documents for revision abc123.
SCSs MAY allow the organization to expunge (remove) content from a repository
and its change history without leaving a public record of the removed content,
but the organization MUST only allow these changes in order to meet legal or
privacy compliance requirements. Content changed under this process includes
changing files, history, references, or any other metadata stored by the SCS.
Warning
Removing a revision from a repository is similar to deleting a package version
from a registry: it’s almost impossible to estimate the amount of downstream
supply chain impact.
For example, in Git, each revision ID is based on the ones before it.
When you remove a revision, you must generate new revisions (and new revision IDs)
for any revisions that were built on top of it. Consumers who took a dependency
on the old revisions may now be unable to refer to the revision they’ve already
integrated into their products.
It may be the case that the specific set of changes targeted by a legal takedown
can be expunged in ways that do not impact consumed revisions, which can mitigate
these problems.
It is also the case that removing content from a repository won’t necessarily
remove it everywhere.
The content may still exist in other copies of the repository, either in backups
or on developer machines.
Process
An organization MUST document the Safe Expunging Process and describe how
requests and actions are tracked and SHOULD log the fact that content was
removed. Different organizations and tech stacks may have different approaches
to the problem.
SCSs SHOULD have technical mechanisms in place which require an Administrator
plus at least one additional ‘trusted person’ to trigger any expunging
(removals) made under this process.
The application of the Safe Expunging Process and the resulting logs MAY be
private to prevent calling attention to potentially sensitive data or to comply
with local laws and regulations. Organizations SHOULD prefer to make logs public
if possible.
The organization MUST provide evidence of continuous enforcement via technical
controls for any claims made in the Source Provenance attestations or VSAs (see
control continuity).
The organization MUST document the meaning of their enforced technical controls.
For example, if an organization implements a technical control via a custom
tool (such as required GitHub Actions workflow), it must indicate the name of
this tool, what it accomplishes, and how to find its evidence in the provenance
attestation.
For another example, if the organization claims that all consumable Source
Revisions on the main branch were tested prior to acceptance, this MUST be
explicitly enforced in the SCS.
The repository ID is defined by the SCS and MUST be uniquely identifiable within
the context of the SCS with a stable locator, such as a URI.
✓
✓
✓
✓
Revisions are immutable and uniquely identifiable 🔗
The revision ID is defined by the SCS and MUST be uniquely identifiable within the context of the repository.
When the revision ID is a digest of the content of the revision (as in git) nothing more is needed.
When the revision ID is a number or otherwise not a digest, then the SCS MUST document how the immutability of the revision is established.
The same revision ID MAY be present in multiple repositories.
The SCS MUST provide tooling to display Changes between one Source Revision and
another in a human readable form (e.g. ‘diffs’) for all plain-text changes and
SHOULD provide mechanisms to provide human understandable interpretations of
non-plain-text changes (e.g. render images, verify and display provenance for
binaries, etc.).
If a consumer is authorized to access a revision, they MUST be able to fetch the
corresponding Source VSA.
If the SCS DOES NOT generate a VSA for a revision, the revision has Source Level
0.
At Source Levels 1 and 2 the SCS MAY issue these attestations based on its
understanding of the underlying system (e.g. based on design docs, security
reviews, etc.), but at Level 2+ the SCS MUST use the SCS-issued
source provenance when issuing the VSAs.
How does the current revision relate to previous revisions?
To answer these questions, the SCS MUST record all changes to Named References,
including when they occurred, who made them, and the new Source Revision ID.
If Source Revisions have ancestry relationships in the VCS, the SCS MUST ensure
that a Branch can only be updated to point to revisions that descend from the
current revision.
In git, this requires a technical control to prohibit git push --force.
This requirement captures evidence that the organization intended to make the
changes captured by the new revision.
For example, if a branch currently points to revision a, it may only be
moved to a new revision b if a is an ancestor of b.
Technical Controls are only effective if they are used continuously in the
history of a Branch.
‘Control continuity’ reflects an organization’s ongoing commitment to a
technical control.
For each technical control claimed in a VSA, continuity MUST be established and
tracked from a specific start revision.
If there is a lapse in continuity for a specific control, continuity of that
control MUST be re-established from a new revision.
For example, the main branch currently points to revision a when a new
technical control t is configured.
The next revision on the main branch, b will be the first revision that was
protected by t and b is the first revision in the “continuity” of t.
Any revisions added to main while t is disabled will reset the continuity of t.
The SCS MUST provide an identity management system or some other means of
identifying and authenticating actors.
The SCS MUST allow organizations to specify which actors and roles are allowed
to perform sensitive actions within a repository (e.g. creation or updates of
branches, approval of changes).
Depending on the SCS, identity management may be provided by source control
services (e.g., GitHub, GitLab), implemented using cryptographic signatures
(e.g., using gittuf to manage public keys for actors), or extending existing
authentication systems used by the organization (e.g., Active Directory, Okta,
etc.).
The SCS MUST document how actors are identified for the purposes of attribution.
Activities conducted on the SCS SHOULD be attributed to authenticated
identities.
Source Provenance are attestations that
contain information about how a specific revision was created and how it came to
exist on a protected branch or how a tag came to point at it. They are
associated with the revision identifier delivered to consumers and are a
statement of fact from the perspective of the SCS. The SCS MUST document the
format and intent of all Source Provenance attestations it produces.
Source Provenance MUST be created contemporaneously with the branch being
updated such that they provide a credible, auditable, record of changes.
If a consumer is authorized to access a revision, they MUST be able to access the
corresponding Source Provenance documents for that revision.
It is possible that an SCS can make no claims about a particular revision.
For example, this would happen if the revision was created on another SCS,
on an unprotected branch (such as a topic branch), or if the revision was not
the result of the expected process.
The SCS MUST provide the ability for an organization to enforce customized technical controls for Named References.
The SCS MUST provide a mechanism for organizations to indicate which Named
References should be protected by technical controls.
For example, the organization may instruct the SCS to protect main and
refs/heads/releases/*, but not refs/heads/experimental/* using branch
protection rules (e.g. GitHub,
GitLab)
or via the application and verification of gittuf
policies.
For another example, the organization may instruct the SCS to prevent the deletion of
all refs/tags/releases/* using tag protection rules
(e.g. GitHub,
GitLab)
or via the application and verification of gittuf
policies.
The SCS MUST
Record technical controls enforced on Named References in contemporaneously
produced attestations associated with the corresponding Source Revisions.
Allow organizations to distribute additional attestations related to their
technical controls to consumers authorized to access the corresponding Source
Revision.
Prevent organization-specified properties from beginning with any value
other than ORG_SOURCE_.
Changes in protected branches MUST be agreed to by two or more trusted persons prior to submission.
The following combinations are acceptable:
Uploader and reviewer are two different trusted persons.
Two different reviewers are trusted persons.
Reviews SHOULD cover, at least, security relevant properties of the code.
[Final revision approved] This requirement applies to the final revision
submitted. I.e., if additional changes are made during the review process, those changes MUST
be reviewed as well.
[Context-specific approvals] Approvals are for a specific context, such as a
repo + branch in git. Moving fully reviewed content from one context to another
still requires review. The exact definition of “context” depends on the project,
and this does not preclude well-understood automatic merges, such as cutting a release branch.
[Informed Review] The SCS MUST present reviewers with a clear representation of the result of accepting the proposed change. See Human Readable Changes.
[Trusted Robot Contributions] An organization MAY choose to grant a Trusted
Robot a perpetual exception to a policy (e.g. a bot may be able to merge a change
that has not been reviewed by two parties).
Examples:
Import and migration bots that move code from one repo to another.
Dependabot
✓
Communicating source levels
SLSA source level details are communicated using attestations.
These attestations either refer to a source revision itself or provide context needed to evaluate an attestation that does refer to a revision.
There are two broad categories of source attestations within the source track:
Source verification summary attestations (Source VSAs): Used to communicate to downstream users what high level security properties a given source revision meets.
Source provenance attestations: Provide trustworthy, tamper-proof, metadata with the necessary information to determine what high level security properties a given source revision has.
To provide interoperability and ensure ease of use, it’s essential that the Source VSAs are applicable across all Source Control Systems.
However, due to the significant differences in how SCSs operate and how they may choose to meet the Source Track requirements, it is preferable to
allow for flexibility with the full source provenance attestations. To that end, SLSA leaves source provenance attestations undefined and up to the SCSs to determine
what works best in their environment.
Source verification summary attestation
Source verification summary attestations (Source VSAs) are issued by some authority that has sufficient evidence to make the determination of a given
revision’s source level. Source VSAs convey properties about the revision as a whole and summarize properties computed over all
the changes that contributed to that revision over its history.
subject.uri SHOULD be set to a URI where a human can find details about
the revision. This field is not intended for policy decisions. Instead, it
is only intended to direct a human investigating verification failures.
For example: https://github.com/slsa-framework/slsa/commit/6ff3cd75c8c9e0fcedc62bd6a79cf006f185cedb
subject.digest MUST include the revision identifier (e.g. gitCommit) and MAY include other digests over the contents of the revision (e.g. gitTree, dirHash, etc.).
SCSs that do not use cryptographic digests MUST define a canonical type that is used to identify immutable revisions and MUST include the repository within the type2.
For example: svn_revision_id: svn+https://svn.myproject.org/svn/MyProject/trunk@2019
subject.annotations.sourceRefs SHOULD be set to a list of references that pointed to this revision when the attestation was created. The list MAY be non-exhaustive.
git references MUST be fully qualified (e.g. refs/heads/main or refs/tags/v1.0) to reduce the likelihood of confusing downstream tooling.
resourceUri MUST be set to the URI of the repository, preferably using SPDX Download Location.
E.g. git+https://github.com/foo/hello-world.
verifiedLevels MUST include the SLSA source track level the SCS asserts the revision meets. One of SLSA_SOURCE_LEVEL_0, SLSA_SOURCE_LEVEL_1, SLSA_SOURCE_LEVEL_2, SLSA_SOURCE_LEVEL_3.
MAY include additional properties as asserted by the SCS. The SCS MUST include only the highest SLSA source level met by the revision.
dependencyLevels MAY be empty as source revisions are typically terminal nodes in a supply chain. For example, this could be used to indicate the source level of any git submodules present in the revision.
Additional properties
The SLSA source track MAY create additional properties to include in
verifiedLevels which attest to other claims concerning a revision.
The SCS MAY embed additional properties within verifiedLevels provided by the
organization as long as they are prefixed by ORG_SOURCE_ to distinguish them
from other properties the SCS may wish to use. The SCS MUST enforce the use of
this prefix for such properties. An organization MAY further differentiate
properties using:
ORG_SOURCE_ to indicate a property that is meant for consumption by
external consumers.
ORG_SOURCE_INTERNAL_ to indicate a property that is not meant for
consumption by external consumers.
The meaning of the properties is left entirely to the organization.
Populating sourceRefs
The Source VSA issuer may choose to populate sourceRefs in any way they wish.
Downstream users are expected to be familiar with the method used by the issuer.
Example implementations:
Issue a new VSA for each merged Pull Request and add the destination branch to sourceRefs.
Issue a new VSA each time a Named Reference is updated to point to a new revision.
See Verifying Source for instructions how to verify
VSAs for Source Revisions.
Source provenance attestations
Source provenance attestations provide tamper-proof evidence (attestation model)
that can be used to determine what SLSA Source Level or other high-level properties a given revision meets.
This evidence can be used by:
an authority as the basis for issuing a Source VSA
a consumer to cross-check a Source VSA they received for a revision
a consumer to enforce a more detailed policy than the organization’s own process
SCSs may have different methods of operating that necessitate different forms of evidence.
E.g. GitHub-based workflows may need different evidence than Gerrit-based workflows, which would both likely be different from workflows that
operate over Subversion repositories.
These differences also mean that, depending on the configuration, the issuers of provenance attestations may vary from implementation to implementation, often because entities with the knowledge to issue them may vary.
The authority that issues Source VSAs MUST understand which entity should issue each provenance attestation type, and ensure all source provenance attestations come from their expected issuers.
‘Source provenance attestations’ is a generic term used to refer to any type of attestation that provides evidence of the process used to create a revision.
Example source provenance attestations:
A TBD attestation which describes the revision’s parents and the actors involved in creating this revision.
A “code review” attestation which describes the basics of any code review that took place.
An “authentication” attestation which describes how the actors involved in any revision were authenticated.
A Vuln Scan attestation
which describes the results of a vulnerability scan over the contents of the revision.
An SPDX attestation
which provides a software bill of materials for the revision.
A SCAI attestation used to
describe which source quality tools were run on the revision.
Irrespective of the types of provenance attestations generated by an SCS and
their implementations, the SCS MUST document provenance
formats, and how each provenance attestation can be used to reason about the
revision’s properties recorded in the summary attestation.
Future Considerations
Authentication
Better protection against phishing by forbidding second factors that are not
phishing resistant.
Protect against authentication token theft by forbidding bearer tokens
(e.g. PATs).
Including length of continuity in the VSAs
Source: Verifying source
SLSA uses attestations to indicate security claims associated with a repository
revision, but attestations don’t do anything unless somebody inspects them. SLSA
calls that inspection verification, and this section describes how to verify
properties of source revisions using
the attestations associated
with those revisions.
At Source L3+, Source Control Systems (SCSs) issue detailed
provenance attestations of
the process that was used to create specific revisions of a repository. These
provenance attestations are issued in bespoke formats and may be too burdensome
to use in some use cases.
Source Verification Summary Attestations
(Source VSAs) address this, making verification more efficient and ergonomic by
recording the result of prior verifications. Source VSAs may be issued by a VSA
provider to make a SLSA source level determination based on the content of those
attestations.
How to verify a source revision
The source consumer checks:
If they trust the SCS that issued the VSA and if the VSA applies to the
revision they’ve fetched.
If the claims made in the VSA match their expectations for how the source
should be managed.
(Optional): If the evidence presented in the source provenance matches the
claims made in the VSA.
Step 1: Check the SCS
First, check the SLSA Source level by comparing the artifact to its VSA and the
VSA to a preconfigured root of trust. The goal is to ensure that the VSA
actually applies to the artifact in question and to assess the trustworthiness
of the VSA. This mitigates threats within “B” and “C”, depending on SLSA Source
level.
Once, when bootstrapping the verifier:
Configure the verifier’s roots of trust, meaning the recognized SCS
identities and the maximum SLSA Source level each SCS is trusted up to.
Different verifiers MAY use different roots of trust for repositories. The
root of trust configuration is likely in the form of a map from (SCS public
key identity, VSA verifier.id) to (SLSA Source level).
Example root of trust configuration
The following snippet shows conceptually how a verifier’s roots of trust
might be configured using made-up syntax.
"slsaSourceRootsOfTrust":[// A SCS trusted at SLSA Source L3, using a fixed public key.{"publicKey":"HKJEwI...","scsId":"https://somescs.example.com/slsa/l3","slsaSourceLevel":3},// A different SCS that claims to be SLSA Source L3,// but this verifier only trusts it to L2.{"publicKey":"tLykq9...","scsId":"https://differentscs.example.com/slsa/l3","slsaSourceLevel":2},// A SCS that uses Sigstore for authentication.{"sigstore":{"root":"global",// identifies fulcio/rekor roots"subjectAlternativeNamePattern":"https://github.com/slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@refs/tags/v*.*.*"},"scsId":"https://github.com/slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@refs/tags/v*.*.*","slsaSourceLevel":3,}...],
Given a revision and its VSA follow the
VSA verification instructions and the
validation-model using the revision identifier to perform subject matching and
checking the verifier.id against the root-of-trust described above.
Step 2: Check Expectations
Next, check that the revision’s VSA meets your expectations in order to mitigate
threat “B”.
In our threat model, the adversary has the ability to create revisions within
the repository and get consumers to fetch that revision. The adversary is not
able to subvert controls implemented by the Producer and enforced by the SCS.
Your expectations SHOULD be sufficient to detect an un-official revision and
SHOULD make it more difficult for an adversary to create a malicious official
revision.
You SHOULD compare the VSA against expected values for at least the following
fields:
To prevent an adversary from substituting a VSA from another revision.
verificationResult
To prevent an adversary from providing a VSA for a revision that failed some aspect of the organization’s expectations.
predicate.resourceUri
To prevent an adversary from substituting a VSA for the intended repository (e.g. git+https://github.com/IntendedOrg/hello-world) for another (e.g. git+https://github.com/AdversaryOrg/hello-world)
subject.annotations.sourceRefs
To prevent an adversary from substituting the intended revision from one branch (e.g. release) with another (e.g. experimental_auth).
verifiedLevels
To ensure the expected controls were in place for the creation of the revision. E.g. SLSA_SOURCE_LEVEL_3, ORG_SOURCE_STATIC_ANALYSIS, etc…
Step 3: Verify Evidence using Source Provenance [optional]
As the format and implementation of source provenance attestations are left to
the SCS, you SHOULD form expectations about the claims in source provenance
attestations and how they map to a revision’s properties claimed in its VSA in
conjunction with the SCS and the producer.
Forming Expectations
Expectations are known values that indicate the corresponding
revision is authentic. For example, an SCS may maintain a mapping between
repository branches & tags and the controls they claim to implement. That
mapping constitutes a set of expectations.
Possible models for forming expectations include:
Trust on first use: Accept the first version of the revision as-is. On
each update, compare the old VSA to the new VSA and alert on any
differences.
Defined by producer: The revision 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 revision’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).
It is important to note that expectations are tied to a repository branch or
tag, whereas a VSA is tied to an revision. Different revisions will have
different VSAs and the claims made by those VSAs may differ.
Architecture options
There are several options (non-mutually exclusive) for where VSA verification
can happen: the build system at source fetch time, the package ecosystem at
build artifact upload time, the consumers at download time, or
via a continuous monitoring system. Each option comes with its own set of
considerations, but all are valid and at least one SHOULD be used.
More than one component can verify VSAs. For example, even if a builder verifies
source VSAs, package ecosystems may wish to verify the source VSAs for the
artifacts they host that claim to be built from that source (as indicated by the
build provenance).
Source: Assessing source control systems
One of SLSA’s guiding principles is to “trust platforms, verify
artifacts”. However, consumers cannot trust source control systems (SCSs) unless
they have some proof that an SCS meets its
requirements.
This section describes the parts of an SCS that consumers SHOULD assess and
provides sample questions consumers can ask when assessing a SCS. See also
Threats & mitigations.
Threats
Adversary goal
The SLSA Source track defends against an adversary whose primary goal is to
inject unofficial behavior into protected source code while avoiding detection.
Organizations typically establish change management processes to prevent this
unofficial behavior from being introduced. The adversary’s goal is to bypass the
change management process.
Adversary profiles
Consumers SHOULD also evaluate the source control systems’ ability to defend
against the following types of adversaries.
Project contributors, who can:
Propose changes to protected branches of the source repo.
Upload new content to the source repo.
Project maintainer, who can:
Do everything listed under “project contributors”.
Define the purpose of the source repo.
Add or remove contributors to the source repo.
Add or remove permissions granted to contributors of the source repo.
Modify security controls within the source repo.
Modify controls used to enforce the change management process on the
source repo.
Source control system administrators, who can:
Do everything listed under “project contributors” and “project
maintainers”.
Modify the source repo while bypassing the project maintainer’s controls.
Modify the behavior of the Source Control System itself.
Access the control plane’s cryptographic secrets.
Source Control System components
Consumers SHOULD consider at least these elements when assessing a Source
Control System for SLSA conformance: control configuration, change management
interface, control plane, verifier, storage.
The following subsection details these elements.
Change management interface
The change management interface is the user interface for proposing and
approving changes to protected branches within a source repository. During
normal operation all such changes go through this interface.
Control configuration
Control configuration is how organizations establish technical controls in a
given source repository. If done well the configuration will reflect the intent
of the organization.
Technical controls
Technical controls are the organization configured settings that are used to
determine if a revision can be introduced into storage within any particular
context and who has access to those revisions.
The technical controls component is responsible for the storage of these
settings while the control plane is responsible for enforcing
the configured controls.
They include:
Read/write ACLs,
If approvals are required to introduce changes within a given context
The control plane is the SCS component that orchestrates the introduction and
creation of new revisions into a source repository. It is responsible for
enforcing technical controls and, at SLSA Source L3+,
generating and signing source provenance for each revision. The control plane is
operated by one or more administrators, who have privileges to modify the
control plane.
Verifier
The verifier is the SCS component that evaluates source provenance and generates
and signs a
verification summary attestation
(VSA).
Storage
Storage holds source revisions and their provenance and summary attestations.
Assessing components
The following are prompts for assessing a Source Control System’s ability to
meet the SLSA requirements.
Prompts for assessing the change management interface
How does the SCS manage which actors are permitted to approve changes?
What types of non-plain-text changes can the change management interface
render? How well does the SCS render those changes?
What controls does the change management interface provide for enabling
Trusted Robot Contributions? Example: SLSA Build L3+ provenance, built from
SLSA Source L4+ source.
Prompts for assessing control configuration & technical controls
How does the SCS prevent regression in control configurations?
Examples: built-in controls that cannot change, notifying project
maintainers when controls change, requiring public declaration of control
changes.
How does the SCS prevent individual project maintainers from tampering with
controls configured by the project?
How does the SCS prevent SCS administrators from tampering with a project’s
configured technical controls?
Prompts for assessing the control plane & verifier
NOTE The control plane and verifier perform related roles within the SCS and
should typically be assessed together.
Administration
What are the ways an SCS administrator can use privileged access to
influence a revision creation, provenance generation, or VSA generation?
Examples: physical access, terminal access, access to cryptographic
secrets
What controls are in place to detect or prevent an SCS administrator
from abusing such access? Examples: two-person approvals, audit logging,
workload identities
Roughly how many SCS maintainers have such access?
How are privileged accounts protected? Examples: two-factor
authentication, client device security policies
What plans do you have for recovering from security incidents and
platform outages? Are they tested? How frequently?
Control effectiveness
How does the SCS ensure the control plane is enforcing the
technical controls are working as intended?
Source provenance generation
How does the control plane observe the revision creation to ensure the
provenance’s accuracy?
Are there situations in which the control plane will not generate
source provenance? What are they?
What details are included in the source provenance? Are they sufficient
to mitigate tampering with other SCS components?
VSA generation
How does the verifier determine what source level a revision meets?
How does the verifier determine the organization’s control expectations
and if they are met?
Development practices
How do you track the control plane and verifier’s software and
configuration?
Example: version control.
How do you build confidence in the control plane’s software supply
chain? Example: SLSA Build L3+ provenance, built from SLSA Source L4+
source.
How do you secure communications between components? Example: TLS with
certificate transparency.
Managing cryptographic secrets
How do you store the control plane and verifier’s cryptographic secrets?
Which parts of the organization have access to the control plane and
verifier’s cryptographic secrets?
What controls are in place to detect or prevent SCS administrators from
abusing such access? Examples: two-person approvals, audit logging
How are secrets protected in memory? Examples: secrets are stored in
hardware security modules and backed up in secure cold storage
How frequently are cryptographic secrets rotated? Describe the rotation
process.
What is your plan for remediating cryptographic secret compromise? How
frequently is this plan tested?
Prompts for assessing output storage
How do you prevent tampering with storage directly?
How do you prevent one project’s revisions from affecting another project?
Source control system 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 and can include information such as the security model used in the
evaluation. Evidence submitted for third-party certification need not be
published.
Threats & mitigations
{Threats & Mitigations}
This section supplies a comprehensive technical analysis of supply chain threat problems and
their corresponding mitigations with SLSA. It expands on the diagram first presented in the Introduction to supply chain attacks section and provides additional examples with detailed descriptions of different types of supply chain threats. They cover threats to the integrity of source, build, usage, dependency, availability, and verification portions of the software supply chain. Each example of a threat problem includes a SLSA mitigation that explains the reasons for the SLSA build and source requirements.
Having more information on threats and mitigation can increase confidence that the SLSA requirements are sufficient to achieve the desired level of integrity protection and help implementers understand what they are protecting against so that they can better design and implement controls.
Supply chain threat model
The threat model above that was first shown in the Introduction to supply chain attacks section, shows the software supply chain process of how software is produced and consumed, and where threats can occur. This Threats & Mitigation section adds additional details that describe cluster threats based
on where in the software development pipeline those threats occur. The threat locations are labeled (A)
through (I) in the diagram and all the examples.
This detailed threat information is important because priorities and mitigations mostly cluster
along those same lines. Dependencies are
highly recursive, and each dependency in these examples has its own threats
(A) through (I), and the same for their dependencies, and so on. Recursion problems cause producers and consumers to face aggregate risk across all of the
software they produce and consume. Due to the size and scope of software development organizations, it’s not practical to rely on every individual team to do
the right thing. For this reason, SLSA prioritizes mitigations that can be
broadly adopted in an automated fashion, minimizing the chance of mistakes.
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 modification of the source data at rest as well as insider threats,
when an authorized individual introduces an unauthorized change.
The SLSA Source track mitigates these threats when the consumer
verifies source against expectations, confirming
that the revision they received was created in the expected manner.
(A) Producer
The producer of the software intentionally produces code that harms the
consumer, or the producer otherwise uses practices that are not deserving of the
consumer’s trust.
Software producer intentionally creates a malicious revision of the source
Threat: A producer intentionally creates a malicious revision with the intent of harming their consumers.
Mitigation:
This kind of attack cannot be directly mitigated through SLSA controls.
Consumers must establish some basis to trust the organizations from which they consume software.
That basis may be:
The repo is open source with an active user-base. High numbers of engaged users may increase the likelihood that bad code is detected during code review and reduce the time-to-detection when bad revisions are accepted.
The organization has sufficient legal or reputational incentives to dissuade it from making malicious changes.
Ultimately this is a judgement call with no straightforward answer.
Example: A producer with an otherwise good reputation decides suddenly to produce a malicious artifact with the intent to harm their consumers.
(B) Modifying the source
An adversary without any special administrator privileges attempts to introduce a change counter to the declared intent of the source by following the producer’s official source control process.
Threats in this category can be mitigated by following source control management best practices.
(B1) Submit change without review
Directly submit without review(Source L4)
Threat: Malicious code submitted to the source repository.
Mitigation: Require approval of all changes before they are accepted.
Example: Adversary directly pushes a change to a git repo’s main branch.
Solution: The Source Control System is configured to require two party review for
contributions to the main branch.
Single actor controls multiple accounts
Threat: An actor is able to control multiple account and effectively approve their own code changes.
Mitigation: The producer must ensure that no actor is able to control or influence multiple accounts with review privileges.
Example: Adversary creates a pull request using a secondary account and approves it using their primary account.
Solution: The producer must track all actors who have both explicit review permissions and the independent ability to control
a privileged bot. A common vector for this attack is to influence a robot account with the permission to review or contribute
code. Control of the robot account and an actor’s own personal account is enough to exploit this vulnerability. A common
solution to this flow is to deny bot accounts from contributing or reviewing code, or to require more human reviews in those
cases.
Use a robot account to submit change
Threat: Exploit a robot account that has the ability to submit changes without
two-person review.
Mitigation: All changes require review by two people, even changes authored by
robots.
Example: A file within the source repository is automatically generated by a
robot, which is allowed to submit without review.
Adversary compromises the robot and submits a malicious change.
Solution: Require two-person review for such changes, ignoring the robot.
Abuse of rule exceptions
Threat: Rule exceptions provide vector for abuse.
Mitigation: Remove rule exceptions.
Example: A producer intends to require two-person review on “all changes except for documentation changes,” defined as those only modifying .md files.
Adversary submits a malicious executable masquerading as a documentation file, help.md.
This avoids the two-person review rule due to the exception.
In the future, a user (or another workflow) can be induced to executehelp.md and become compromised.
Technically the malicious code change met all defined policies yet the intent of the organization was defeated.
Solution: The producer adjusts the rules to prohibit such exceptions.
Highly-permissioned actor bypasses or disables controls(verification)
Threat: Trusted actor with “admin” privileges in a repository submits code by disabling existing controls.
Mitigation: The Source Control System must have controls in place to prevent
and detect abusive behavior from administrators (e.g. two-person approvals,
audit logging).
Example: GitHub repository-level admin removes a branch protection requirement, pushes
their change, then re-enables the requirement to cover their tracks.
Solution: Consumers do not accept claims from the Source Control System unless
they trust sufficient controls are in place to prevent repo admins from
abusing privileges.
(B2) Evade change management process
Alter change history(Source L2+)
Threat: Adversary alters branch history to hide malicious activity.
Mitigation: The Source Control System prevents branch history from being
altered.
Example: Adversary submits a malicious commit X to the main branch. A
release is built and published from X. The adversary then “force pushes”
to main erasing the record of the malicious commit. Solution: The Source
Control System is configured to prevent force pushes to main.
Replace tagged content with malicious content(Source L2+)
Threat: Adversary alters a tag to point at malicious content.
Mitigation: The Source Control System does not allow protected tags to be updated.
Example: Adversary crafts a malicious commit X on a development branch which
does enforce any controls. They then update the release_1.2 tag to point to
X. Consumers of release_1.2 will get the malicious revision. Solution: The
Source Control System does not allow protected tags to be updated.
Skip required checks(Source L3+)
Threat: Code is submitted without following the producers documented
development process, introducing unintended behavior.
Mitigation: The producer uses the Source Control System to implement technical
controls ensuring adherence to the development process.
Example: An engineer submits a new feature that has a critical flaw on an
untested code path, in violation of the producer’s documented process of having
high test coverage. Solution: The producer implements a technical control in the
SCS that requires 95%+ test coverage.
Modify code after review(Source L4)
Threat: Modify the code after it has been reviewed but before submission.
Mitigation: The Source Control System invalidates approvals whenever the proposed change is modified.
Example: Source repository requires two-person review on all changes.
Adversary sends an initial “good” pull request to a peer, who approves it.
Adversary then modifies their proposal to contain “bad” code.
Solution: Configure the code review rules to require review of the most recent revision before submission.
Submit a change that is unreviewable(Source L4)
Threat: Adversary crafts a change that looks benign to a reviewer but is actually malicious.
Mitigation: Code review system ensures that all reviews are informed and
meaningful to the extent possible. For example the system could show
& resolve symlinks, render images, or verify & display provenance.
Example: A proposed change updates a JPEG file to include a malicious
message, but the reviewer is only presented with a diff of the binary
file contents. The reviewer is unable to parse the contents themselves
so they do not have enough context to provide a meaningful review.
Solution: the code review system should present the reviewer with a
rendering of the image and the embedded
metadata, allowing them to make an
informed decision.
Copy a reviewed change to another context(Source L4)
Threat: Get a change reviewed in one context and then transfer it to a
different context.
Mitigation: Approvals are context-specific.
Example: MyPackage’s source repository requires two-person review. Adversary
forks the repo, submits a change in the fork with review from a colluding
colleague (who is not trusted by MyPackage), then proposes the change to
the upstream repo.
Solution: The proposed change still requires two-person review in the upstream
context even though it received two-person review in another context.
Commit graph attacks
Threat: A malicious commit can be included in a sequence of commits such that it does not appear malicious in the net change presented to reviewers.
Mitigation: The producer ensures that all revisions in the protected context followed the same contribution process.
Example: Adversary sends a pull request containing malicious commit X and a commit Y that undoes X.
The combined change of X + Y displays zero lines of malicious code and the reviewer cannot tell that X is malicious unless they review it individually.
If X is allowed to become reachable from the protected branch, the content may become available in secured environments such as developer machines.
Solution: Each revision in the protected context must have followed the intended process.
Ultimately, this means that either each code review results in at most a single new commit or that the full process is followed for each constituent commit in a proposed sequence.
(B3) Render code review ineffective
Collude with another trusted person
Threat: Two trusted persons collude to author and approve a bad change.
Mitigation: This threat is not currently addressed by SLSA, but the producer can arbitrarily increase friction of their policies to reduce risk, such as requiring additional, or more senior reviewers.
The goal of policy here is to ensure that the approved changes match the intention of the producer for the source.
Increasing the friction of the policies may make it harder to circumvent, but doing so has diminishing returns.
Ultimately the producer will need to land upon a balanced risk profile that makes sense for their security posture.
Trick reviewer into approving bad code
Threat: Construct a change that looks benign but is actually malicious, a.k.a.
“bugdoor.”
Mitigation: This threat is not currently addressed by SLSA.
Reviewer blindly approves changes
Threat: Reviewer approves changes without actually reviewing, a.k.a. “rubber
stamping.”
Mitigation: This threat is not currently addressed by SLSA.
(B4) Render change metadata ineffective
Forge change metadata(Source L2+)
Threat: Forge the change metadata to alter attribution, timestamp, or
discoverability of a change.
Mitigation: The Source Control System only attributes changes to authenticated
identities and records contemporaneous evidence of changes in signed source
provenance attestations.
Example: Adversary ‘X’ creates a commit with unauthenticated metadata claiming
it was authored by ‘Y’. Solution: The Source Control System records the identity
of ‘X’ when ‘X’ submits the commit to the repository.
(C) Source code management
An adversary introduces a change to the source control repository through an
administrative interface, or through a compromise of the underlying
infrastructure.
Platform admin abuses privileges(verification)
Threat: Platform administrator abuses their privileges to bypass controls or
to push a malicious version of the software.
Mitigation: The source platform must have controls in place to prevent and
detect abusive behavior from administrators (e.g. two-person approvals for
changes to the infrastructure, audit logging). A future Platform
Operations Track may provide
more specific guidance on how to secure the underlying platform.
Example 1: GitHostingService employee uses an internal tool to push changes to
the MyPackage source repo.
Example 2: GitHostingService employee uses an internal tool to push a
malicious version of the server to serve malicious versions of MyPackage sources
to a specific CI/CD client but the regular version to everyone else, in order to
hide tracks.
Example 3: GitHostingService employee uses an internal tool to push a
malicious version of the server that includes a backdoor allowing specific users
to bypass branch protections. Adversary then uses this backdoor to submit a
change to MyPackage without review.
Solution: Consumers do not accept claims from the Source Control System unless
they trust sufficient controls are in place to prevent repo admins from
abusing privileges.
Exploit vulnerability in SCM
Threat: Exploit a vulnerability in the implementation of the source code
management system to bypass controls.
Mitigation: This threat is not currently addressed by SLSA.
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.
(D) External build parameters
An adversary builds from a version of the source code that does not match the
official source control repository, or changes the build parameters to inject
behavior that was not intended by the official source.
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 platform 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.
(E) Build process
An adversary introduces an unauthorized change to a build output through
tampering of the build image, build environment or build process; or introduces false information into the
provenance.
These threats are directly addressed by the SLSA Build and BuildEnv tracks.
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
platform 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.3 (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 owner of the “mypackage” project. Awesome Builder allows
owners to debug the build environment via SSH. An adversary uses this feature
to alter a build in progress. Solution: Build L3 requires the external parameters
to be complete in the provenance. The attackers access and/or actions within the
SSH connection would be enumerated within the external parameters. The updated
external parameters will not match the declared expectations causing verification
to fail.
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 platform 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 platform 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 platform.
Mitigation: Builds are isolated from the trusted build platform 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 (example).
Mitigation: Build caches must be isolated between builds to prevent
such cache poisoning attacks. In particular, the cache SHOULD be keyed by the
transitive closure of all inputs to the cached artifact, and the cache must
either be only writable by the trusted control plane or have SLSA Build L3
provenance for each cache entry.
Example 1: The cache key does not fully cover the transitive closure of all
inputs and instead only uses the digest of the source file itself. Adversary runs
a build over auth.cc with command line flags to gcc that define a marco
replacing CheckAuth(ctx) with true. When subsequent builds build auth.cc
they will get the attacker’s poisoned instance that does not call CheckAuth.
Solution: Build cache is keyed by digest of auth.cc, command line, and digest of
gcc so changing the command line flags results in a different cache entry.
Example 2: The tenant controlled build process has full write access to the
cache. Adversary observes a legitimate build of auth.cc which covers the
transitive closure of all inputs and notes the digest used for caching. The
adversary builds a malicious version of auth.o and directly writes it to the
build cache using the observed digest. Subsequent legitimate builds will use
the malicious version of auth.o. Solution: Each cache entry is keyed by the
transitive closure of the inputs, and the cache entry is itself a SLSA Build L3
build with its own provenance that corresponds to the key.
Compromise build platform admin (BuildEnv L2)
Threat: An adversary gains admin permissions for the artifact’s build platform.
Admin may potentially access the build environment directly (e.g., using Compute Platform APIs for the remote access).
Mitigation: Compute Platform-provided agents that power remote access APIs are disabled in the build image.
Control Plane attests build environment before the build is started in it and produces a VSA providing evidence that build environment has no outside-in access and runs with the expected image and early boot components (e.g., firmware)
Example: MyPackage is built on Awesome Builder. Awesome Builder uses images that have Compute Platform infrastructure agents enabled in them (including those that allow remote access, provisioning new users and resetting credentials of the existing ones). An adversary uses these capabilities to remotely access the build environment and modify a build in progress.
Solution: Consumers do not accept provenance from the Build platform unless they can validate that the build environment was bootstrapped from the expected image that has Compute Platform agents disabled in it (which is a responsibility of the Build Image provider).
Compromise build image during the distribution (in transit)(BuildEnv L1+)
Threat: An adversary injects malicious code into the build image after the image has been generated and before it is consumed by the Build Platform.
Mitigation: The build image is produced by a pipeline having SLSA Build L2+ level and comes with SLSA Build Provenance.
The Control Plane verifies the build image upon the initial consumption (e.g., as it is being pulled from the build image registry into a local cache).
Example: MyPackage is built on Awesome Builder. Awesome Builder uses images provided by a Fancy Image partner.
An adversary was able to hijack the supply channel between Fancy Image and Awesome Builder and install malicious tools into the image.
Local compromise of build image (at rest)(BuildEnv L2+)
Threat: An adversary injects malicious code into the build image after it was accepted by the Build Platform and passed initial verification.
Mitigation: Build Environment is bootstrapped using Secure Boot with boot measurements performed by vTPM.
Control Plane performs remote attestation of the Build Environment prior to scheduling the build on it.
Example: Awesome Builder uses images provided by a Fancy Image partner.
Adversary was able to get unauthorized access to the Awesome Builder persistent storage and modify the image after it was received from Fancy Image and persisted locally.
Image size is large enough to make SLSA provenance verification prohibitively expensive to perform prior to every Build Environment instantiation.
Integrity of the root file system is protected by the mechanisms that delay verification until the actual usage of the underlying blocks (e.g., [dm-veryity], IMA or similar).
Compromise build environment in use(BuildEnv L3)
Threat 1: Malware having elevated privileges to the host interface in the Compute Platform was able to compromise Build Environment state data while it’s running.
Threat 2: Compute Platform admin credentials were compromised allowing an adversary to get access and modify Build Environment state while it’s running via privileged hypervisor APIs or direct VM memory manipulation.
Mitigation: Virtualized build environments run in the trusted execution environment (TEE) using technologies like AMD SEV-SNP and Intel TDX that provide isolation for the VM from the privileged software running on the host machine.
Control Plane attests build environment before the build is started in it and produces a VSA providing evidence that build environment has no outside-in access and runs in the TEE with the expected image and early boot components (e.g., firmware).
Root file system integrity is protected by cryptographic mechanisms like dm-verity, IMA or similar.
Temporary file system is overlaid over the root file system and is encrypted to protect integrity of intermediate files by an ephemeral key that is provisioned inside TEE upon bootstrapping the environment.
Example: Awesome Builder uses Cloudy Sky compute provider for provisioning virtual machines.
An adversary got unauthorized access to Cloudy Sky infrastructure using the compromised admin credentials and was able to get privileged access to the host machines.
Adversary was able then to modify virtual machine state while it’s running on the host.
(F) Artifact publication
An adversary uploads a package artifact that does not reflect the intent of the
package’s official source control repository.
This is the most direct threat because it is the easiest to pull off. If there
are no mitigations for this threat, then (D) and (E) are often indistinguishable
from this threat.
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 SomeOtherBuildPlatform, which is only
trusted up to Build L2, and then exploits SomeOtherBuildPlatform 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) Distribution channel
An adversary modifies the package on the package registry using an
administrative interface or through a compromise of the infrastructure
including modification of the package in transit to the consumer.
The distribution channel threats and mitigations look very similar to the
Artifact Publication (F) threats and mitigations with the main difference
being that these threats are mitigated by having the consumer perform
verification.
The consumer’s actions may be simplified if (F) produces a VSA.
In this case the consumer may replace provenance verification with
VSA verification.
Build with untrusted CI/CD (expectations)
Threat: Replace the package with one built 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 or a VSA for corresponding resourceUri.
Example: MyPackage is expected to be built on Google Cloud Build, which is
trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only
trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject
malicious behavior. Adversary then replaces the original package within the
repository with the malicious package. Solution: Verifier rejects because
builder is not as expected.
Issue VSA from untrusted intermediary (expectations)
Threat: Have an unofficial intermediary issue a VSA for a malicious package.
Mitigation: Verifier requires VSAs to be issued by a trusted intermediary.
Example: Verifier expects VSAs to be issued by TheRepository. Adversary
builds a malicious package and then issues a VSA of their own for the malicious
package. Solution: Verifier rejects because they only accept VSAs from
TheRepository which the adversary cannot issue since they do not have the
corresponding signing key.
Upload package without provenance or VSA (Build L1)
Threat: Replace the original package with a malicious one without provenance.
Mitigation: Verifier requires provenance or a VSA before accepting the package.
Example: Adversary replaces MyPackage with a malicious version of MyPackage
on the package repository and deletes existing provenance. Solution: Verifier
rejects because provenance is missing.
Replace package and VSA with another (expectations)
Threat: Replace a package and its VSA with a malicious package and its valid VSA.
Mitigation: Consumer ensures that the VSA matches the package they’ve requested (not just the package they received) by following the verification process.
Example: Adversary uploads a malicious package to repo/evil-package,
getting a valid VSA for repo/evil-package. Adversary then replaces
repo/my-package and its VSA with repo/evil-package and its VSA.
Solution: Verifier rejects because the VSA resourceUri field lists
repo/evil-package and not the expected repo/my-package.
Tamper with artifact after upload (Build L1)
Threat: Take a benign version of the package, modify it in some way, then
replace it while retaining the original provenance or VSA.
Mitigation: Verifier checks that the provenance or VSA’s subject matches
the hash of the package.
Example: Adversary performs a proper build, modifies the artifact, then
replaces the modified version of the package in the repository and retains the
original provenance. Solution: Verifier rejects because the hash of the
artifact does not match the subject found within the provenance.
Tamper with provenance or VSA (Build L2)
Threat: Perform a build that would not meet expectations, then modify the
provenance or VSA to make the expectations checks pass.
Mitigation: Verifier only accepts provenance or VSA with a valid cryptographic
signature or equivalent proving that the provenance came from an
acceptable builder or the VSA came from an expected verifier.
Example 1: 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.
Example 2: Verifier expects VSAs to be issued by TheRepository. Adversary
builds a malicious package and then modifies the original VSA’s subject
field to match the digest of the malicious package. Solution: Verifier rejects
because the cryptographic signature is no longer valid.
Usage threats
A usage threat is a potential for an adversary to exploit behavior of the
consumer.
(H) Package selection
The consumer requests a package that it did not intend.
Dependency confusion
Threat: Register a package name in a public registry that shadows a name used
on the victim’s internal registry, and wait for a misconfigured victim to fetch
from the public registry instead of the internal one.
Mitigation: The mitigation is for the software producer to build internal
packages on a SLSA Level 2+ compliant build system and define expectations for
build provenance. Expectations must be verified on installation of the internal
packages. If a misconfigured victim attempts to install attacker’s package with
an internal name but from the public registry, then verification against
expectations will fail.
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: This threat is not currently addressed by 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.
(I) Usage
The consumer uses a package in an unsafe manner.
Improper usage
Threat: The software can be used in an insecure manner, allowing an
adversary to compromise the consumer.
Mitigation: This threat is not addressed by SLSA, but may be addressed by
efforts like Secure by Design.
Dependency threats
A dependency threat is a potential for an adversary to introduce unintended
behavior in one artifact by compromising some other artifact that the former
depends on at build time. (Runtime dependencies are excluded from the model, as
noted below.)
Unlike other threat categories, dependency threats develop recursively through
the supply chain and can only be exploited indirectly. For example, if
application A includes library B as part of its build process, then a build
or source threat to B is also a dependency threat to A. Furthermore, if
library B uses build tool C, then a source or build threat to C is also a
dependency threat to both A and B.
This version of SLSA does not explicitly address dependency threats, but we
expect that a future version will. In the meantime, you can apply SLSA
recursively to your dependencies in order to reduce the risk of dependency
threats.
Build dependency
An adversary compromises the target artifact through one of its build
dependencies. Any artifact that is present in the build environment and has the
ability to influence the output is considered a build dependency.
Include a vulnerable dependency (library, base image, bundled file, etc.)
Threat: Statically link, bundle, or otherwise include an artifact that is
compromised or has some vulnerability, causing the output artifact to have the
same vulnerability.
Example: The C++ program MyPackage statically links libDep at build time. A
contributor accidentally introduces a security vulnerability into libDep. The
next time MyPackage is built, it picks up and includes the vulnerable version of
libDep, resulting in MyPackage also having the security vulnerability.
Mitigation: A future
Dependency track may
provide more comprehensive guidance on how to address more specfiic
aspects of this threat.
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.)
Threat: Use a compromised tool or other software artifact during the build
process, which alters the build process and injects unintended behavior into the
output artifact.
Mitigation: This can be partially mitigated by treating build tooling,
including OS images, as any other artifact to be verified prior to use.
The threats described in this document apply recursively to build tooling
as do the mitigations and examples. A future
Build Environment track may
provide more comprehensive guidance on how to address more specfiic
aspects of this threat.
Example: MyPackage is a tarball containing an ELF executable, created by
running /usr/bin/tar during its build process. An adversary compromises the
tar OS package such that /usr/bin/tar injects a backdoor into every ELF
executable it writes. The next time MyPackage is built, the build picks up the
vulnerable tar package, which injects the backdoor into the resulting
MyPackage artifact. Solution: apply SLSA recursively to all build tools
prior to the build. The build platform verifies the disk image,
or the individual components on the disk image, against the associated
provenance or VSAs prior to running a build. Depending on where the initial
compromise took place (i.e. before/during vs after the build of the build tool itself), the modified /usr/bin/tar will fail this verification.
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.)
Threat: During the build process, use a compromised runtime dependency (such
as during testing or dynamic linking), which alters the build process and
injects unwanted behavior into the output.
NOTE: This is technically the same case as Use a compromised build
tool. We call it out to remind the reader that
runtime dependencies can become build dependencies if they are
loaded during the build.
Example: MyPackage has a runtime dependency on package Dep, meaning that Dep
is not included in MyPackage but required to be installed on the user’s machine
at the time MyPackage is run. However, Dep is also loaded during the build
process of MyPackage as part of a test. An adversary compromises Dep such that,
when run during a build, it injects a backdoor into the output artifact. The
next time MyPackage is built, it picks up and loads Dep during the build
process. The malicious code then injects the backdoor into the new MyPackage
artifact.
Mitigation: In addition to all the mitigations for build tools, you can often
avoid runtime dependencies becoming build dependencies by isolating tests to a
separate environment that does not have write access to the output artifact.
Related threats
The following threats are related to “dependencies” but are not modeled as
“dependency threats”.
Use a compromised dependency at runtime (modeled separately)
Threat: Load a compromised artifact at runtime, thereby compromising the user
or environment where the software ran.
Example: MyPackage lists package Dep as a runtime dependency. Adversary
publishes a compromised version of Dep that runs malicious code on the user’s
machine when Dep is loaded at runtime. An end user installs MyPackage, which in
turn installs the compromised version of Dep. When the user runs MyPackage, it
loads and executes the malicious code from Dep.
Mitigation: N/A - SLSA’s
threat model does not explicitly model runtime dependencies. Instead, each
runtime dependency is considered a distinct artifact with its own threats.
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 does not currently address availability threats, though future versions might.
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: This threat is not currently addressed by SLSA.
A dependency becomes temporarily or permanently unavailable to the build process
Threat: Unable to perform a build with the intended dependencies.
Mitigation: This threat is not currently addressed by SLSA. That said, some
solutions to support hermetic and reproducible builds may also reduce the
impact of this threat.
De-list artifact
Threat: The package registry stops serving the artifact.
Mitigation: This threat is not currently addressed by SLSA.
De-list provenance
Threat: The package registry stops serving the provenance.
Mitigation: This threat is not currently addressed by SLSA.
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.
Exploit cryptographic hash collisions
Threat: Exploit a cryptographic hash collision weakness to bypass one of the
other controls.
Mitigation: Choose secure algorithms when using cryptographic digests, such
as SHA-256.
Examples: Attacker crafts a malicious file with the same MD5 hash as a target
benign file. Attacker replaces the benign file with the malicious file.
Solution: Only accept cryptographic hashes with strong collision resistance.
SLSA Verified Properties
While SLSA is typically focused on expressing the security state of an artifact
with levels, levels may not be
appropriate in all cases. Some software supply chain controls don’t fit neatly
within existing SLSA levels or that do may exist with others that users are not
yet able to meet. SLSA Verified Properties allows a common way to express those
properties (and their requirements) without needing to fit them into existing
levels or introduce new tracks.
These properties MAY be included in the verifiedLevels field of
verification_summaries (VSAs) when the VSA issuer
determines the requirements have been met.
SLSA_SOURCE_TWO_PARTY_REVIEWED
Indicates the source code associated with this artifact has been reviewed by
two trusted persons. This property MUST only be issued in accordance with the
Source Track’s
two-party-review requirements.
The property MAY be added at any source level in which an SCS can make this
claim.
SLSA_BUILD_REPRODUCED
Indicates the referenced artifact has been reproduced by two or more builders.
This property MUST only be issued if the referenced artifact has
build provenance from two or more independently
operated Build Platforms which are
trusted by the VSA issuer.
Software attestations
A software attestation is an authenticated statement (metadata) about a
software artifact or collection of software artifacts.
The primary intended use case is to feed into automated policy engines, such as
in-toto and Binary Authorization.
This section provides a high-level overview of the attestation model, including
standardized terminology, data model, layers, conventions for software
attestations, and formats for different use cases.
Overview
A software attestation, not to be confused with a remote attestation in
the trusted computing world, is an authenticated statement (metadata) about a
software artifact or collection of software artifacts. Software attestations
are a generalization of raw artifact/code signing.
With raw signing, a signature is directly over the artifact (or a hash of the
artifact) and implies a single bit of metadata about the artifact, based on
the public key. The exact meaning MUST be negotiated between signer and
verifier, and a new keyset MUST be provisioned for each bit of information. For
example, a signature might denote who produced an artifact, or it might denote
fitness for some purpose, or something else entirely.
With an attestation, the metadata is explicit and the signature only denotes
who created the attestation (authenticity). A single keyset can express an
arbitrary amount of information, including things that are not possible with
raw signing. For example, an attestation might state exactly how an artifact
was produced, including the build command that was run and all of its
dependencies (as in the case of SLSA Provenance).
Formats
This subsection explains how to choose the attestation format that’s best suited
for your situation by considering factors such as intended use and who will be
consuming the attestation.
First party
Producers of first-party code might consider the following questions:
Will SLSA be used only within our organization?
Is SLSA’s primary use case to manage insider risk?
Are we developing entirely in a closed-source environment?
If these are the main considerations, the organization can choose any format
for internal use. To make an external claim of meeting a SLSA level, however,
there needs to be a way for external users to consume and verify your provenance.
Currently, SLSA recommends using the SLSA Provenance format for SLSA
attestations since it is easy to verify using the Generic SLSA Verifier.
Open source
Producers of open-source code might consider these questions:
Is SLSA’s primary use case to convey trust in how your code was developed?
Do you develop software with standard open-source licenses?
Will the code be consumed by others?
In these situations, we encourage you to use the SLSA Provenance format. The SLSA
Provenance format offers a path towards interoperability and cohesion across the open
source ecosystem. Users can verify any provenance statement in this format
using the Generic SLSA Verifier.
Closed source, third party
Producers of closed-source code that is consumed by others might consider
the following questions:
Is my code produced for the sole purpose of specific third-party consumers?
Is SLSA’s primary use case to create trust in our organization or to comply with
audits and legal requirements?
In these situations, you might not want to make all the details of your
provenance available externally. Consider using Verification Summary
Attestations (VSAs) to summarize provenance information in a sanitized way
that’s safe for external consumption. For more about VSAs, see the Verification
Summary Attestation section.
Model and Terminology
We define the following model to represent any software attestations, regardless
of format. Not all formats will have all fields or all layers, but to be called
a “software attestation” it MUST fit this general model.
The key words MUST, SHOULD, and MAY are to be interpreted as described in
RFC 2119.
An example of an attestation in English follows with the components of the
attestation mapped to the component names (and colors from the model diagram above):
Components:
Artifact: Immutable blob of data described by an attestation, usually
identified by cryptographic content hash. Examples: file content, git
commit, container digest. MAY also include a mutable locator, such as
a package name or URI.
Attestation: Authenticated, machine-readable metadata about one or more
software artifacts. An attestation MUST contain at least:
Envelope: Authenticates the message. At a minimum, it MUST contain:
Message: Content (statement) of the attestation. The message
type SHOULD be authenticated and unambiguous to avoid confusion
attacks.
Signature: Denotes the attester who created the attestation.
Statement: Binds the attestation to a particular set of artifacts.
This is a separate layer to allow for predicate-agnostic processing
and storage/lookup. MUST contain at least:
Subject: Identifies which artifacts the predicate applies to.
Predicate: Metadata about the subject. The predicate type SHOULD
be explicit to avoid misinterpretation.
Predicate: Arbitrary metadata in a predicate-specific schema. MAY
contain:
Link:(repeated) Reference to a related artifact, such as
build dependency. Effectively forms a hypergraph where the
nodes are artifacts and the hyperedges are attestations. It is
helpful for the link to be standardized to allow predicate-agnostic
graph processing.
Bundle: A collection of Attestations, which are usually but not
necessarily related.
Storage/Lookup: Convention for where attesters place attestations and
how verifiers find attestations for a given artifact.
Recommended Suite
We recommend a single suite of formats and conventions that work well together
and have desirable security properties. Our hope is to align the industry around
this particular suite because it makes everything easier. That said, we
recognize that other choices MAY be necessary in various cases.
Component
Recommendation
Envelope
DSSE (ECDSA over NIST P-256 (or stronger) and SHA-256.)
In SLSA ‘provenance’ refers to verifiable information that can be used to track
an artifact back, through all the moving parts in a complex supply chain, to
where it came from. It’s the verifiable information about software artifacts
describing where, when, and how something was produced.
The different SLSA tracks may have their own, more specific, implementations of
provenance to account for their unique needs.
Build provenance - tracks the output of a build process
back to the source code used to produce that output.
Source provenance - tracks the
creation of source code revisions and the change management processes
that were in place during their creation.
Build: 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"
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.
Provenance is an attestation that a particular build platform produced a set of
software artifacts through execution of the buildDefinition.
NOTE: This diagram depicts how the SLSA Provenance format is structured. It
elaborates on the SLSA Build Model but only applies
to the SLSA Provenance format specifically and not to builds in general.
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 platforms.)
The build platform implementer SHOULD define a security model for the build
platform in order to clearly identify the platform’s boundaries, actors,
and interfaces. This model SHOULD then be used to identify the transitive
closure of the trusted build platform for the builder.id as well as the
trusted control plane.
The build process is defined by a parameterized template, identified by
buildType. This encapsulates the process that ran, regardless of what
platform 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.
internalParameters: 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.
#ResourceDescriptor:{”uri”:string,”digest”:{”sha256”:string,”sha512”:string,”gitCommit”:string,[string]:string,},”name”:string,”downloadLocation”:string,”mediaType”:string,”content”:bytes,// base64-encoded”annotations”:{[string]:_// any JSON type}}
NOTE: This protobuf definition prioritizes being a human-readable summary
of the schema for readers of the specification. A version of the protobuf
definition useful for code generation is maintained in the
in-toto attestation repository.
// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the// provenance is always serialized using JSON with lowerCamelCase. Protobuf// tooling performs this case conversion automatically.
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
internalParameters; 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 platform. They MUST be complete at SLSA Build L3, meaning 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 platform 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.
internalParameters
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 platform is already trusted, and in many cases it is
not practical to do so.
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 internalParameters 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 internalParameters.
The parameters SHOULD only contain the actual values passed in through the
interface to the build platform. 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:
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 platform 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 platform to read configuration
directly from version control, recording the server-verified URI in
externalParameters and the digest in resolvedDependencies.
Record the digest in the provenance1 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”.
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.
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.
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.
BuildMetadata
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.
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 a 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,},"internalParameters":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
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 platforms,
align with reproducible builds, and make verification easier.
Grouped fields into buildDefinition vs runDetails.
Renamed:
parameters -> externalParameters (slight change in semantics)
environment -> internalParameters (slight change in semantics)
materials -> resolvedDependencies (slight change in semantics)
buildInvocationId -> invocationId
buildStartedOn -> startedOn
buildFinishedOn -> 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
Changed naming convention for extension fields (in RC2).
Renamed localName (RC1) -> name (RC2).
Added annotations and content (in RC2).
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”
The externalParameters SHOULD reflect reality. If clients
send the evaluated configuration object directly to the build server, record
the digest directly in externalParameters. If clients upload the
configuration object to a temporary storage location and send that location
to the build server, record the location in externalParameters as a URI
and record the uri and digest in resolvedDependencies. ↩
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:
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","predicate":{"verifier":{"id":"<URI>","version":{"<COMPONENT>":"<VERSION>",...}},"timeVerified":<TIMESTAMP>,"resourceUri":<artifact-URI-in-request>,"policy":{"uri":"<URI>","digest":{<digest-of-policy-data>}}"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.
verifierobject, 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.
URI that identifies the resource associated with the artifact being verified.
The resourceUri SHOULD be set to the URI from which the producer expects the
consumer to fetch the artifact for verification. This enables the consumer to
easily determine the expected value when verifying. If the
resourceUri is set to some other value, the producer MUST communicate the
expected value, or how to determine the expected value, to consumers through
an out-of-band channel.
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.
verificationResultstring, required
Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification.
Indicates the highest level of each track verified for the artifact (and not
its dependencies) and any verified properties verified
for the artifact 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.
dependencyLevelsobject, 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.
A set but empty dependencyLevels object means that the artifact has no
dependency at all, while an unset or null dependencyLevels means that the
verifier makes no claims about the artifact’s dependencies.
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.
slsaVersionstring, 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.
VSA consumers use VSAs to accomplish goals based on delegated trust. We call the
process of establishing a VSA’s authenticity and determining whether it meets
the consumer’s goals ‘verification’. Goals differ, as do levels of confidence
in VSA producers, so the verification procedure changes to suit its context.
However, there are certain steps that most verification procedures have in
common.
Verification MUST include the following steps:
Verify the signature on the VSA envelope using the preconfigured roots of
trust. This step ensures that the VSA was produced by a trusted producer
and that it hasn’t been tampered with.
Verify the statement’s subject matches the digest of the artifact in
question. This step ensures that the VSA pertains to the intended artifact.
Verify that the predicateType is
https://slsa.dev/verification_summary/v1. This step ensures that the
in-toto predicate is using this version of the VSA format.
Verify that the verifier matches the public key (or equivalent) used to
verify the signature in step 1. This step identifies the VSA producer in
cases where their identity is not implicitly revealed in step 1.
Verify that the value for resourceUri in the VSA matches the expected
value. This step ensures that the consumer is using the VSA for the
producer’s intended purpose.
Verify that the value for verificationResult is PASSED. This step
ensures the artifact is suitable for the consumer’s purposes.
Verify that verifiedLevels contains the expected value. This step ensures
that the artifact is suitable for the consumer’s purposes.
Verification MAY additionally contain the following step:
(Optional) Verify additional fields required to determine whether the VSA
meets your goal.
Verification mitigates different threats depending on the VSA’s contents and the
verification procedure.
IMPORTANT: A VSA does not protect against compromise of the verifier, such as by
a malicious insider. Instead, VSA consumers SHOULD carefully consider which
verifiers they add to their roots of trust.
Examples
Suppose consumer C wants to delegate to verifier V the decision for whether
to accept artifact A as resource R. Consumer C verifies that:
The signature on the VSA envelope using V’s public signing key from their
preconfigured root of trust.
subject is A.
predicateType is https://slsa.dev/verification_summary/v1.
Note: This example is analogous to traditional code signing. The expected
value for verifiedLevels is arbitrary but prenegotiated by the producer and
the consumer. The consumer does not need to check additional fields, as C
fully delegates the decision to V.
Suppose consumer C wants to enforce the rule “Artifact A at resource R must
have a passing VSA from verifier V showing it meets SLSA Build Level 2+.”
Consumer C verifies that:
The signature on the VSA envelope using V’s public signing key from their
preconfigured root of trust.
subject is A.
predicateType is https://slsa.dev/verification_summary/v1.
verifier.id is V.
resourceUri is R.
slsaResult is PASSED.
verifiedLevels is SLSA_BUILD_LEVEL_2 or SLSA_BUILD_LEVEL_3.
Note: In this example, verifying the VSA mitigates the same threats as
verifying the artifact’s SLSA provenance. See
Verifying artifacts for details about which
threats are addressed by verifying each SLSA level.
SlsaResult (String)
The result of evaluating an artifact (or set of artifacts) against SLSA.
SHOULD be
The SLSA Track level the referenced artifact qualifies for as
SLSA_<TRACK_NAME>_LEVEL_<LEVEL_NUMBER>, or
SLSA_<TRACK NAME>_LEVEL_UNEVALUATED if the VSA issuer does not want to
make a claim about the track level an artifact meets, or
Note that each SLSA level implies the levels below it in the same track.
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.2:
Update SlsaResult definition to discuss how to refer to new tracks and
link to verified properties for additional SLSA
endorsed values.
1.1:
Changed the policy object to recommend that the digest field of
the ResourceDescriptor is set.
Added optional verifier.version field to record verification tools.
Added Verification subsection with examples.
Made timeVerified optional.
1.0:
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.
This resolution might include a version number, label, or some other
selector in addition to the package name, but that is not important to SLSA. ↩
Technically this requires the artifact to be known to the
adversary. If they only know the digest but not the actual contents, they
cannot actually build the artifact without a preimage attack on the digest
algorithm. However, even still there are no known concerns where this is a
problem. ↩
