SLSA Specification

SLSA is a set of standards and technical controls you can adopt to improve artifact integrity, and build towards completely resilient systems. It’s not a single tool, but a step-by-step outline to prevent artifacts being tampered with and tampered artifacts from being used, and at the higher levels, hardening up the platforms that make up a supply chain. These requirements are explained below, along with the rest of the essential specifications.

SLSA 101

Supply chain threats

Protecting against key threats

Supply chain attacks are an ever-present threat, exploiting weakpoints to interfere with software. The SLSA framework establishes three trust boundaries encouraging the right standards, attestation and technical controls, so you can harden a system from these threats and risks.

This means automatic capability to analyse artifacts, guarantee the original source code, protect against interference that can happen in the build and distribution processes, isolate any hidden vulnerabilities and knowing with certainty which system components might be affected.

Real world examples

High profile attacks like SolarWinds, Codecov or Linux hypocrite commits exploit the kind of supply chain integrity vulnerabilities which may go unnoticed or be underdeveloped, and quickly become extremely public, disruptive and costly in today’s environment.

Attacks can occur at every link in a typical software supply chain, which puts an extra burden on anyone involved in complex critical systems. SLSA's designed with these examples in mind to make sure they’re common knowledge, and easier to protect against.

How it fits into the security ecosystem

There’s more to security than just protection against tampering. From vulnerability management and fuzzing to testing and developer trust, many of these require solutions where effort’s focused on the source. That’s where SLSA complements your wider security efforts, giving you confidence that the code you run is the code you analyzed.

Security levels

A ladder to the ideal state

SLSA’s requirements look at the three general main areas involved in a software artifact’s creation, and where vulnerabilities target - the build, the source, and the dependencies. As the levels scale up, they show that work’s been done to assure there’s more integrity in each area, which can be helpful in scenario planning.

Build integrity

SLSA starts at the build, the last step before an artifact’s released. This makes sure software’s built from the correct sources and dependencies, and hasn’t been modified. More resilient build integrity means protection from modifying code after source control, compromised build platforms or bypassing CI/CD.

Source integrity

Requirements can then focus on the source. All source code should reflect the intent of the software producer, that code and change history stay available for investigation. More resilient source integrity means better protection from bad code submitted without review or compromised source control systems.

Dependencies

Any other software artifacts fetched during the build process. Once the earlier security checks have been put into place, applying SLSA checks recursively to any dependencies in the system can then be followed up, which helps protect potentially massive attack surfaces against dependency confusion attacks.

Basic security steps

Level 1 means the supply chain is documented, there’s infrastructure to generate provenance, and systems are prepared for higher SLSA levels.

After the build

Level 2 shows more trustworthiness in the build, builders are source-aware, and signatures are used to prevent provenance being tampered with.

Back to source

Level 3 shows that a system’s builds are fully trustworthy, build definitions come from the source and a system has more hardened CI.

Across the chain

Level 4 means the build environment is fully accounted for, dependencies are tracked in provenance and insider threats are ruled out.

Introduction

SLSA is a set of standards and technical controls you can adopt to improve artifact integrity, and build towards completely resilient systems. It’s not a single tool, but a step-by-step outline to prevent artifacts being tampered with and tampered artifacts from being used, and at the higher levels, hardening up the platforms that make up a supply chain. These requirements are explained below, along with the rest of the essential specifications.

SLSA 101

Supply chain threats

Protecting against key threats

Supply chain attacks are an ever-present threat, exploiting weakpoints to interfere with software. The SLSA framework establishes three trust boundaries encouraging the right standards, attestation and technical controls, so you can harden a system from these threats and risks.

This means automatic capability to analyse artifacts, guarantee the original source code, protect against interference that can happen in the build and distribution processes, isolate any hidden vulnerabilities and knowing with certainty which system components might be affected.

Real world examples

High profile attacks like SolarWinds, Codecov or Linux hypocrite commits exploit the kind of supply chain integrity vulnerabilities which may go unnoticed or be underdeveloped, and quickly become extremely public, disruptive and costly in today’s environment.

Attacks can occur at every link in a typical software supply chain, which puts an extra burden on anyone involved in complex critical systems. SLSA's designed with these examples in mind to make sure they’re common knowledge, and easier to protect against.

How it fits into the security ecosystem

There’s more to security than just protection against tampering. From vulnerability management and fuzzing to testing and developer trust, many of these require solutions where effort’s focused on the source. That’s where SLSA complements your wider security efforts, giving you confidence that the code you run is the code you analyzed.

Security levels

A ladder to the ideal state

SLSA’s requirements look at the three general main areas involved in a software artifact’s creation, and where vulnerabilities target - the build, the source, and the dependencies. As the levels scale up, they show that work’s been done to assure there’s more integrity in each area, which can be helpful in scenario planning.

Build integrity

SLSA starts at the build, the last step before an artifact’s released. This makes sure software’s built from the correct sources and dependencies, and hasn’t been modified. More resilient build integrity means protection from modifying code after source control, compromised build platforms or bypassing CI/CD.

Source integrity

Requirements can then focus on the source. All source code should reflect the intent of the software producer, that code and change history stay available for investigation. More resilient source integrity means better protection from bad code submitted without review or compromised source control systems.

Dependencies

Any other software artifacts fetched during the build process. Once the earlier security checks have been put into place, applying SLSA checks recursively to any dependencies in the system can then be followed up, which helps protect potentially massive attack surfaces against dependency confusion attacks.

Basic security steps

Level 1 means the supply chain is documented, there’s infrastructure to generate provenance, and systems are prepared for higher SLSA levels.

After the build

Level 2 shows more trustworthiness in the build, builders are source-aware, and signatures are used to prevent provenance being tampered with.

Back to source

Level 3 shows that a system’s builds are fully trustworthy, build definitions come from the source and a system has more hardened CI.

Across the chain

Level 4 means the build environment is fully accounted for, dependencies are tracked in provenance and insider threats are ruled out.

Terminology

Before diving into the SLSA Levels, we need to establish a core set of terminology and models to describe what we’re protecting.

Software supply chain

SLSA’s framework addresses every step of the software supply chain - the sequence of steps resulting in the creation of an artifact. We represent a supply chain as a directed acyclic graph of sources, builds, dependencies, and packages. One artifact’s supply chain is a combination of its dependencies’ supply chains plus its own sources and builds.

Build model

We model a build as running on a multi-tenant platform, where each execution is independent. A tenant defines the build, including the input source artifact and the steps to execute. In response to an external trigger, the platform runs the build by initializing the environment, fetching the source and possibly some dependencies, and then starting execution inside the environment. The build then performs arbitrary steps, possibly fetching additional dependencies, and outputs one or more artifacts.

Use cases

SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Below describe the three main use cases for SLSA.

Security levels

SLSA is organized into a series of levels that provide increasing integrity guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source.

This section is an informative overview of the SLSA levels, describing their purpose and guarantees. For the normative requirements at each level, see Requirements.

What is SLSA?

SLSA is a set of incrementally adoptable security guidelines, established by industry consensus. The standards set by SLSA are guiding principles for both software producers and consumers: producers can follow the guidelines to make their software more secure, and consumers can make decisions based on a software package’s security posture. SLSA’s four levels are designed to be incremental and actionable, and to protect against specific integrity attacks. SLSA 4 represents the ideal end state, and the lower levels represent milestones with corresponding integrity guarantees.

Summary of levels

It can take years to achieve the ideal security state - intermediate milestones are important. SLSA guides you through gradually improving the security of your software. Artifacts used in critical infrastructure or vital business operations may want to attain a higher level of security, whereas software that poses a low risk can stop when they’re comfortable.

Detailed explanation

The SLSA level is not transitive (see our FAQs). This makes each artifact’s SLSA rating independent from one another, allowing parallel progress and prioritization based on risk. The level describes the integrity protections of an artifact’s build process and top-level source, but nothing about the artifact’s dependencies. Dependencies have their own SLSA ratings, and it is possible for a SLSA 4 artifact to be built from SLSA 0 dependencies.

Limitations

SLSA can help reduce supply chain threats in a software artifact, but there are limitations.

• There are a significant number of dependencies in the supply chain for many artifacts. The full graph of dependencies could be intractably large.
• In practice, a team working on security will need to identify and focus on the important components in a supply chain. This can be performed manually, but the effort could be significant.
• An artifact’s SLSA level is not transitive (see our FAQs) and dependencies have their own SLSA ratings. This means that it is possible for a SLSA 4 artifact to be built from SLSA 0 dependencies. So, while the main artifact has strong security, risks may still exist elsewhere. The aggregate of these risks will help software consumers understand how and where to use the SLSA 4 artifact.
• While automation of these tasks will help, it isn’t practical for every software consumer to fully vet the entire graph of every artifact. To close this gap, auditors and accreditation bodies could verify and assert that something meets the SLSA requirements. This could be particularly valuable for closed source software.

As part of our roadmap, we’ll explore how to identify important components, how to determine aggregate risk throughout a supply chain, and the role of accreditation.

Requirements

This section covers all of the technical requirements for an artifact to meet the SLSA Levels.

For background, see Introduction and Terminology. To better understand the reasoning behind the requirements, see Threats and mitigations.

Reminder: SLSA is in alpha. The definitions below are not yet finalized and subject to change, particularly SLSA 3-4.

Summary table

○ = REQUIRED unless there is a justification

Definitions

See also Terminology for general SLSA concepts. The definitions below are only used in this document.

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.

Immutable reference: An identifier that is guaranteed to always point to the same, immutable artifact. This MUST allow the consumer to locate the artifact and SHOULD include a cryptographic hash of the artifact’s contents to ensure integrity. Examples: git URL + branch/tag/ref + commit ID; cloud storage bucket ID + SHA-256 hash; Subversion URL (no hash).

Provenance: Metadata about how an artifact was produced.

Revision: An immutable, coherent state of a source. In Git, for example, a revision is a commit in the history reachable from a specific branch in a specific repository. Different revisions within one repo MAY have different levels. Example: the most recent revision on a branch meets SLSA 4 but very old historical revisions before the cutoff do not.

Strong authentication: Authentication that maps back to a specific person using an authentication mechanism which is resistant to account and credential compromise. For example, 2-factor authentication (2FA) where one factor is a hardware security key (i.e. YubiKey).

Trusted persons: Set of persons who are granted the authority to maintain a software project. For example, https://github.com/MarkLodato/dotfiles has just one trusted person (MarkLodato), while https://hg.mozilla.org/mozilla-central has a set of trusted persons with write access to the mozilla-central repository.

Source requirements

Build requirements

Requirements on build process:

Provenance requirements

Requirements on the process by which provenance is generated and consumed:

Requirements on the contents of the provenance:

Common requirements

Common requirements for every trusted system involved in the supply chain (source, build, distribution, etc.)

Threats and mitigations

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.

SLSA’s levels are designed to mitigate the risk of these attacks. This section enumerates possible attacks throughout the supply chain and shows how SLSA can help. For a background, see Terminology.

Summary

SLSA’s primary focus is supply chain integrity, with a secondary focus on availability. Integrity means protection against tampering or unauthorized modification at any stage of the software lifecycle. Within SLSA, we divide integrity into source integrity vs build integrity.

Source integrity: Ensure that all changes to the source code reflect the intent of the software producer. Intent of an organization is difficult to define, so SLSA approximates this as approval from two authorized representatives.

Build integrity: Ensure that the package is built from the correct, unmodified sources and dependencies according to the build recipe defined by the software producer, and that artifacts are not modified as they pass between development stages.

Availability: Ensure that the package can continue to be built and maintained in the future, and that all code and change history is available for investigations and incident response.

Real-world examples

Many recent high-profile attacks were consequences of supply-chain integrity vulnerabilities, and could have been prevented by SLSA’s framework. For example:

A SLSA level helps give consumers confidence that software has not been tampered with and can be securely traced back to source—something that is difficult, if not impossible, to do with most software today.

Threats in detail

IMPORTANT: This is a work in progress.

What follows is a comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. The goals are to:

• Explain the reasons for each of the SLSA requirements.
• Increase confidence that the SLSA requirements are sufficient to achieve the desired level of integrity protection.
• Help implementers better understand what they are protecting against so that they can better design and implement controls.

Frequently Asked Questions

Q: Why is SLSA not transitive?

SLSA is not transitive in order to make the problem tractable. If SLSA 4 required dependencies to be SLSA 4, then reaching SLSA 4 would require starting at the very beginning of the supply chain and working forward. This is backwards, forcing us to work on the least risky component first and blocking any progress further downstream. By making each artifact’s SLSA rating independent from one another, it allows parallel progress and prioritization based on risk. (This is a lesson we learned when deploying other security controls at scale throughout Google.) We expect SLSA ratings to be composed to describe a supply chain’s overall security stance, as described in the case study vision.

Q: What about reproducible builds?

When talking about reproducible builds, there are two related but distinct concepts: “reproducible” and “verified reproducible.”

“Reproducible” means that repeating the build with the same inputs results in bit-for-bit identical output. This property provides many benefits, including easier debugging, more confident cherry-pick releases, better build caching and storage efficiency, and accurate dependency tracking.

For these reasons, SLSA 4 requires reproducible builds unless there is a justification why the build cannot be made reproducible. Example justifications include profile-guided optimizations or code signing that invalidates hashes. Note that there is no actual reproduction, just a claim that reproduction is possible.

“Verified reproducible” means using two or more independent build systems to corroborate the provenance of a build. In this way, one can create an overall system that is more trustworthy than any of the individual components. This is often suggested as a solution to supply chain integrity. Indeed, this is one option to secure build steps of a supply chain. When designed correctly, such a system can satisfy all of the SLSA build requirements.

That said, verified reproducible builds are not a complete solution to supply chain integrity, nor are they practical in all cases:

• Reproducible builds do not address source, dependency, or distribution threats.
• Reproducers must truly be independent, lest they all be susceptible to the same attack. For example, if all rebuilders run the same pipeline software, and that software has a vulnerability that can be triggered by sending a build request, then an attacker can compromise all rebuilders, violating the assumption above.
• Some builds cannot easily be made reproducible, as noted above.
• Closed-source reproducible builds require the code owner to either grant source access to multiple independent rebuilders, which is unacceptable in many cases, or develop multiple, independent in-house rebuilders, which is likely prohibitively expensive.

Therefore, SLSA does not require verified reproducible builds directly. Instead, verified reproducible builds are one option for implementing the requirements.

For more on reproducibility, see Hermetic, Reproducible, or Verifiable?

Q: How does SLSA relate to in-toto?

in-toto is a framework to secure software supply chains hosted at the Cloud Native Computing Foundation. The in-toto specification provides a generalized workflow to secure different steps in a software supply chain. The SLSA specification recommends in-toto attestations as the vehicle to express Provenance and other attributes of software supply chains. Thus, in-toto can be thought of as the unopinionated layer to express information pertaining to a software supply chain, and SLSA as the opinionated layer specifying exactly what information must be captured in in-toto metadata to achieve the guarantees of a particular level.

in-toto’s official implementations written in Go, Java, and Rust include support for generating SLSA Provenance metadata. These APIs are used in other tools generating SLSA Provenance such as Sigstore’s cosign, the SLSA GitHub Generator, and the in-toto Jenkins plugin.

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.

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/v0.1"

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 how an artifact or set of artifacts was produced.

This predicate is the recommended way to satisfy the SLSA provenance requirements.

Model

Provenance is a claim that some entity (builder) produced one or more software artifacts (Statement’s subject) by executing some recipe, using some other artifacts as input (materials). The builder is trusted to have faithfully recorded the provenance; there is no option but to trust the builder. However, the builder may have performed this operation at the request of some external, possibly untrusted entity. These untrusted parameters are captured in the recipe’s entryPoint, arguments, and some of the materials. Finally, the build may have depended on various environmental parameters (environment) that are needed for reproducing the build but that are not under external control.

See Example for a concrete example.

Schema

{
  // Standard attestation fields:
  "_type": "https://in-toto.io/Statement/v0.1",
  "subject": [{ ... }],
// Predicate:
“predicateType”: “https://slsa.dev/provenance/v0.1”,
“predicate”: {
“builder”: {
“id”: ”<URI>”
},
“recipe”: {
“type”: ”<URI>”,
“definedInMaterial”: /* integer /,
“entryPoint”: ”<STRING>”,
“arguments”: { / object / },
“environment”: { / object / }
},
“metadata”: {
“buildInvocationId”: ”<STRING>”,
“buildStartedOn”: ”<TIMESTAMP>”,
“buildFinishedOn”: ”<TIMESTAMP>”,
“completeness”: {
“arguments”: true/false,
“environment”: true/false,
“materials”: true/false
},
“reproducible”: true/false
},
“materials”: [
{
“uri”: ”<URI>”,
“digest”: { / DigestSet */ }
}
]
}
}

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.

builder object, required

Identifies the entity that executed the recipe, which is trusted to have correctly performed the operation and populated this provenance.

The identity 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, the “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 because one signer may generate 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.

builder.id string (TypeURI), required

URI indicating the builder’s identity.

recipe object, optional

Identifies the configuration used for the build. When combined with materials, this SHOULD fully describe the build, such that re-running this recipe results in bit-for-bit identical output (if the build is reproducible).

MAY be unset/null if unknown, but this is DISCOURAGED.

recipe.type string (TypeURI), required

URI indicating what type of recipe was performed. It determines the meaning of recipe.entryPoint, recipe.arguments, recipe.environment, and materials.

recipe.definedInMaterial integer, optional

Index in materials containing the recipe steps that are not implied by recipe.type. For example, if the recipe type were “make”, then this would point to the source containing the Makefile, not the make program itself.

Omit this field (or use null) if the recipe doesn’t come from a material.

TODO: What if there is more than one material?

recipe.entryPoint string, optional

String identifying the entry point into the build. This is often a path to a configuration file and/or a target label within that file. The syntax and meaning are defined by recipe.type. For example, if the recipe type were “make”, then this would reference the directory in which to run make as well as which target to use.

Consumers SHOULD accept only specific recipe.entryPoint values. For example, a policy might only allow the “release” entry point but not the “debug” entry point.

MAY be omitted if the recipe type specifies a default value.

Design rationale: The entryPoint is distinct from arguments to make it easier to write secure policies without having to parse arguments.

recipe.arguments object, optional

Collection of all external inputs that influenced the build on top of recipe.definedInMaterial and recipe.entryPoint. For example, if the recipe type were “make”, then this might be the flags passed to make aside from the target, which is captured in recipe.entryPoint.

Consumers SHOULD accept only “safe” recipe.arguments. The simplest and safest way to achieve this is to disallow any arguments altogether.

This is an arbitrary JSON object with a schema is defined by recipe.type.

This is considered to be incomplete unless metadata.completeness.arguments is true. Unset or null is equivalent to empty.

recipe.environment object, optional

Any other builder-controlled inputs necessary for correctly evaluating the recipe. Usually only needed for reproducing the build but not evaluated as part of policy.

This SHOULD be minimized to only include things that are part of the public API, that cannot be recomputed from other values in the provenance, and that actually affect the evaluation of the recipe. For example, this might include variables that are referenced in the workflow definition, but it SHOULD NOT include a dump of all environment variables or include things like the hostname (assuming hostname is not part of the public API).

This is an arbitrary JSON object with a schema is defined by recipe.type.

This is considered to be incomplete unless metadata.completeness.environment is true. Unset or null is equivalent to empty.

metadata object, optional

Other properties of the build.

metadata.buildInvocationId string, optional

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.

metadata.buildStartedOn string (Timestamp), optional

The timestamp of when the build started.

metadata.buildFinishedOn string (Timestamp), optional

The timestamp of when the build completed.

metadata.completeness object, optional

Indicates that the builder claims certain fields in this message to be complete.

metadata.completeness.arguments boolean, optional

If true, the builder claims that recipe.arguments is complete, meaning that all external inputs are properly captured in recipe.

metadata.completeness.environment boolean, optional

If true, the builder claims that recipe.environment is claimed to be complete.

metadata.completeness.materials boolean, optional

If true, the builder claims that materials is complete, usually through some controls to prevent network access. Sometimes called “hermetic”.

metadata.reproducible boolean, optional

If true, the builder claims that running recipe on materials will produce bit-for-bit identical output.

materials array of objects, optional

The collection of artifacts that influenced the build including sources, dependencies, build tools, base images, and so on.

This is considered to be incomplete unless metadata.completeness.materials is true. Unset or null is equivalent to empty.

materials[*].uri string (ResourceURI), optional

The method by which this artifact was referenced during the build.

TODO: Should we differentiate between the “referenced” URI and the “resolved” URI, e.g. “latest” vs “3.4.1”?

TODO: Should wrap in a locator object to allow for extensibility, in case we add other types of URIs or other non-URI locators?

materials[*].digest object (DigestSet), optional

Collection of cryptographic digests for the contents of this artifact.

Example

WARNING: This is just for demonstration purposes.

Suppose the builder downloaded example-1.2.3.tar.gz, extracted it, and ran make -C src foo CFLAGS=-O3, resulting in a file with hash 5678.... Then the provenance might look like this:

{
  "_type": "https://in-toto.io/Statement/v0.1",
  // Output file; name is "_" to indicate "not important".
  "subject": [{"name": "_", "digest": {"sha256": "5678..."}}],
  "predicateType": "https://slsa.dev/provenance/v0.1",
  "predicate": {
    "builder": { "id": "mailto:person@example.com" },
    "recipe": {
      "type": "https://example.com/Makefile",
      "definedInMaterial": 0,                 // material containing the Makefile
      "entryPoint": "src:foo",                // target "foo" in directory "src"
      "arguments": {"CFLAGS": "-O3"}          // extra args to `make`
    },
    "materials": [{
      "uri": "https://example.com/example-1.2.3.tar.gz",
      "digest": {"sha256": "1234..."}
    }]
  }
}

More examples

GitHub Actions

WARNING: This is only for demonstration purposes. The GitHub Actions team has not yet reviewed or approved this design, and it is not yet implemented. Details are subject to change!

If GitHub is the one to generate provenance, and the runner is GitHub-hosted, then the builder would be as follows:

"builder": {
  "id": "https://github.com/Attestations/GitHubHostedActions@v1"
}

Self-hosted runner: Not yet supported. We need to figure out a URI scheme that represents what system hosted the runner, or perhaps add additional properties in builder.

GitHub Actions Workflow

"recipe": {
  // Build steps were defined in a GitHub Actions Workflow file ...
  "type": "https://github.com/Attestations/GitHubActionsWorkflow@v1",
  // ... in the git repo described by `materials[0]` ...
  "definedInMaterial": 0,
  // ... at the path .github/workflows/build.yaml, using the job "build".
  "entryPoint": "build.yaml:build",
  // The only possible user-defined parameters that can affect the build are the
  // "inputs" to a workflow_dispatch event. This is unset/null for all other
  // events.
  "arguments": {
    "inputs": { ... }
  },
  // Other variables that are required to reproduce the build and that cannot be
  // recomputed using existing information. (Documentation would explain how to
  // recompute the rest of the fields.)
  "environment": {
    // The architecture of the runner.
    "arch": "amd64",
    // Environment variables. These are always set because it is not possible
    // to know whether they were referenced or not.
    "env": {
      "GITHUB_RUN_ID": "1234",
      "GITHUB_RUN_NUMBER": "5678",
      "GITHUB_EVENT_NAME": "push"
    },
    // The context values that were referenced in the workflow definition.
    // Secrets are set to the empty string.
    "context": {
      "github": {
        "run_id": "abcd1234"
      },
      "runner": {
        "os": "Linux",
        "temp": "/tmp/tmp.iizj8l0XhS",
      }
    }
  }
}
"materials": [{
  // The git repo that contains the build.yaml referenced above.
  "uri": "git+https://github.com/foo/bar.git",
  // The resolved git commit hash reflecting the version of the repo used
  // for this build.
  "digest": {"sha1": "abc..."}
}]

Google Cloud Build

WARNING: This is only for demonstration purposes. The Google Cloud Build team has not yet reviewed or approved this design, and it is not yet implemented. Details are subject to change!

If Google is the one to generate provenance, and the worker is Google-hosted, then the builder would be as follows:

"builder": {
  "id": "https://cloudbuild.googleapis.com/GoogleHostedWorker@v1"
}

Custom worker: Not yet supported. We need to figure out a URI scheme that represents what system hosted the worker, or perhaps add additional properties in builder.

Cloud Build config-as-code

Here entryPoint references the filename from the CloudBuild BuildTrigger.

"recipe": {
  // Build steps were defined in a cloudbuild.yaml file ...
  "type": "https://cloudbuild.googleapis.com/CloudBuildYaml@v1",
  // ... in the git repo described by `materials[0]` ...
  "definedInMaterial": 0,
  // ... at the path path/to/cloudbuild.yaml.
  "entryPoint": "path/to/cloudbuild.yaml",
  // The only possible user-defined parameters that can affect a BuildTrigger
  // are the substitutions in the BuildTrigger.
  "arguments": {
    "substitutions": {...}
  }
}
"materials": [{
  // The git repo that contains the cloudbuild.yaml referenced above.
  "uri": "git+https://source.developers.google.com/p/foo/r/bar",
  // The resolved git commit hash reflecting the version of the repo used
  // for this build.
  "digest": {"sha1": "abc..."}
}]

Cloud Build RPC

Here we list the steps defined in a trigger or over RPC:

"recipe": {
  // Build steps were provided as an argument. No `definedInMaterial` or
  // `entryPoint`.
  "type": "https://cloudbuild.googleapis.com/CloudBuildSteps@v1",
  "arguments": {
    // The steps that were performed. (Format TBD.)
    "steps": [...],
    // The substitutions in the build trigger.
    "substitutions": {...}
    // TODO: Any other arguments?
  }
}

Explicitly run commands

WARNING: This is just a proof-of-concept. It is not yet standardized.

Execution of arbitrary commands:

"recipe": {
  // There was no entry point, and the commands were run in an ad-hoc fashion.
  // There is no `definedInMaterial` or `entryPoint`.
  "type": "https://example.com/ManuallyRunCommands@v1",
  "arguments": {
    // The list of commands that were executed.
    "commands": [
      "tar xvf foo-1.2.3.tar.gz",
      "cd foo-1.2.3",
      "./configure --enable-some-feature",
      "make foo.zip"
    ],
    // Indicates how to parse the strings in `commands`.
    "shell": "bash"
  }
}

Change history

• Renamed to “slsa.dev/provenance”.
• 0.1.1: Added metadata.buildInvocationId.
• 0.1: Initial version, named “in-toto.io/Provenance”

Verification Summary Attestation (VSA)

Verification summary attestations communicate that an artifact has been verified at a specific SLSA level and details about that verification.

This document defines the following predicate type within the in-toto attestation framework:

"predicateType": "https://slsa.dev/verification_summary/v0.1"

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 publishers 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 materials of the artifact being verified (recursively) or b) matching the non-source dependency listed in materials (by subject.digest == materials.digest and, ideally, subject.name == materials.uri) to a VSA for that dependency and using vsa.policy_level and vsa.dependency_levels. Policy verifiers wishing to establish minimum requirements on dependencies SLSA levels may use vsa.dependency_levels to do so.

Schema

// Standard attestation fields:
"_type": "https://in-toto.io/Statement/v0.1",
"subject": [{
  "name": <artifact-URI-in-request>,
  "digest": { <digest-in-request> }
}],
// Predicate
“predicateType”: “https://slsa.dev/verification_summary/v0.1”,
“predicate”: {
// Required
“verifier”: {
“id”: ”<URI>”
},
“time_verified”: <TIMESTAMP>,
“policy”: {
“uri”: ”<URI>”,
“digest”: { /* DigestSet */ }
}
“verification_result”: ”<PASSED|FAILED>”,
“policy_level”: ”<SlsaResult>”,
“dependency_levels”: {
”<SlsaResult>”: <Int>,
”<SlsaResult>”: <Int>,
…
}
}

Parsing rules

This predicate follows the in-toto attestation parsing rules. Summary:

• Consumers MUST ignore unrecognized fields.
• The predicateType URI includes the major version number and will always change whenever there is a backwards incompatible change.
• Minor version changes are always backwards compatible and “monotonic.” Such changes do not update the predicateType.
• Producers MAY add extension fields using field names that are URIs.

Fields

NOTE: This subsection describes the fields within predicate. For a description of the other top-level fields, such as subject, see Statement.

verifier object, required

Identifies the entity that performed the verification.

The identity MUST reflect the trust base that consumers care about. How detailed to be is a judgment call.

Consumers MUST accept only specific (signer, verifier) pairs. For example, “GitHub” can sign provenance for the “GitHub Actions” verifier, and “Google” can sign provenance for the “Google Cloud Deploy” verifier, but “GitHub” cannot sign for the “Google Cloud Deploy” verifier.

The field is required, even if it is implicit from the signer, to aid readability and debugging. It is an object to allow additional fields in the future, in case one URI is not sufficient.

verifier.id string (TypeURI), required

URI indicating the verifier’s identity.

time_verified string (Timestamp), required

Timestamp indicating what time the verification occurred.

policy object, required

Describes the policy that was used to verify this artifact.

policy.uri string (ResourceURI), required

The URI of the policy used to perform verification.

policy.digest object (DigestSet), optional

Collection of cryptographic digests for the contents of the policy used to perform verification.

verification_result string, required

Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification.

policy_level string (SlsaResult), required

Indicates what SLSA level the artifact itself (and not its dependencies) was verified at or “FAILED” if policy verification failed.

dependency_levels object, required

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.

Example

WARNING: This is just for demonstration purposes.

"_type": "https://in-toto.io/Statement/v0.1",
"subject": [{
  "name": "https://example.com/example-1.2.3.tar.gz",
  "digest": {"sha256": "5678..."}
}],
// Predicate
“predicateType”: “https://slsa.dev/verification_summary/v0.1”,
“predicate”: {
“verifier”: {
“id”: “https://example.com/publication_verifier”
},
“time_verified”: “1985-04-12T23:20:50.52Z”,
“policy”: {
“uri”: “https://example.com/example_tarball.policy”,
“digest”: {“sha256”: “1234…”}
},
“verification_result”: “PASSED”,
“policy_level”: “SLSA_LEVEL_3”,
“dependency_levels”: {
“SLSA_LEVEL_4”: 1,
“SLSA_LEVEL_3”: 5,
“SLSA_LEVEL_2”: 7,
“SLSA_LEVEL_1”: 1,
}
}

The result of evaluating an artifact (or set of artifacts) against SLSA. Must be one of these values:

• SLSA_LEVEL_0
• SLSA_LEVEL_1
• SLSA_LEVEL_2
• SLSA_LEVEL_3
• SLSA_LEVEL_4
• FAILED (Indicates policy evaluation failed)

Change history

• 0.1: Initial version.