SLSA (pronounced “salsa”) is security framework from source to service, giving anyone working with software a common language for increasing levels of software security and supply chain integrity.
The best way to read about SLSA is to visit slsa.dev.
What’s in this repo?
The primary content of this repo is the docs/ directory, which contains the core SLSA specification and sources to the slsa.dev website.
You can read SLSA’s documentation here:
- Levels (Defining the framework)
Requirements (How to attain compliance)
Example of use
Our roadmap
Security Levels
Each level provides an increasing degree of confidence, a way to say that software hasn’t been tampered with and can be securely traced back to its source.
| Level | Description | Example |
|---|---|---|
| 1 | Documentation of the build process | Unsigned provenance |
| 2 | Tamper resistance of the build service | Hosted source/build, signed provenance |
| 3 | Prevents extra resistance to specific threats | Security controls on host, non-falsifiable provenance |
| 4 | Highest levels of confidence and trust | Two-party review + hermetic builds |
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.
| Level | Requirements |
|---|---|
| 0 | No guarantees. SLSA 0 represents the lack of any SLSA level. |
| 1 | The build process must be fully scripted/automated and generate provenance. Provenance is metadata about how an artifact was built, including the build process, top-level source, and dependencies. Knowing the provenance allows software consumers to make risk-based security decisions. Provenance at SLSA 1 does not protect against tampering, but it offers a basic level of code source identification and can aid in vulnerability management. |
| 2 | Requires using version control and a hosted build service that generates authenticated provenance. These additional requirements give the software consumer greater confidence in the origin of the software. At this level, the provenance prevents tampering to the extent that the build service is trusted. SLSA 2 also provides an easy upgrade path to SLSA 3. |
| 3 | The source and build platforms meet specific standards to guarantee the auditability of the source and the integrity of the provenance respectively. We envision an accreditation process whereby auditors certify that platforms meet the requirements, which consumers can then rely on. SLSA 3 provides much stronger protections against tampering than earlier levels by preventing specific classes of threats, such as cross-build contamination. |
| 4 | Requires two-person review of all changes and a hermetic, reproducible build process. Two-person review is an industry best practice for catching mistakes and deterring bad behavior. Hermetic builds guarantee that the provenance’s list of dependencies is complete. Reproducible builds, though not strictly required, provide many auditability and reliability benefits. Overall, SLSA 4 gives the consumer a high degree of confidence that the software has not been tampered with. |
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.
The following table provides a summary of the requirements for each level.
| Requirement | SLSA 1 | SLSA 2 | SLSA 3 | SLSA 4 |
|---|---|---|---|---|
| Source – Version controlled | ✓ | ✓ | ✓ | |
| Source – Verified history | ✓ | ✓ | ||
| Source – Retained indefinitely | 18 mo. | ✓ | ||
| Source – Two-person reviewed | ✓ | |||
| Build – Scripted build | ✓ | ✓ | ✓ | ✓ |
| Build – Build service | ✓ | ✓ | ✓ | |
| Build – Ephemeral environment | ✓ | ✓ | ||
| Build – Isolated | ✓ | ✓ | ||
| Build – Parameterless | ✓ | |||
| Build – Hermetic | ✓ | |||
| Build – Reproducible | ○ | |||
| Provenance – Available | ✓ | ✓ | ✓ | ✓ |
| Provenance – Authenticated | ✓ | ✓ | ✓ | |
| Provenance – Service generated | ✓ | ✓ | ✓ | |
| Provenance – Non-falsifiable | ✓ | ✓ | ||
| Provenance – Dependencies complete | ✓ | |||
| Common – Security | ✓ | |||
| Common – Access | ✓ | |||
| Common – Superusers | ✓ |
○ = required unless there is a justification
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. In developing SLSA, the requirements for each level are there to specifically mitigate the risk of such known examples.
Many recent high-profile attacks were consequences of supply-chain integrity vulnerabilities, and could have been prevented by SLSA’s framework. For example:
| Threat | Known example | How SLSA can help | |
|---|---|---|---|
| A | Submit bad code to the source repository | Linux hypocrite commits: Researcher attempted to intentionally introduce vulnerabilities into the Linux kernel via patches on the mailing list. | Two-person review caught most, but not all, of the vulnerabilities. |
| B | Compromise source control platform | PHP: Attacker compromised PHP’s self-hosted git server and injected two malicious commits. | A better-protected source code platform would have been a much harder target for the attackers. |
| C | Build with official process but from code not matching source control | Webmin: Attacker modified the build infrastructure to use source files not matching source control. | A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. |
| D | Compromise build platform | SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. | Higher SLSA levels require stronger security controls for the build platform, making it more difficult to compromise and gain persistence. |
| E | Use bad dependency (i.e. A-H, recursively) | event-stream: Attacker added an innocuous dependency and then later updated the dependency to add malicious behavior. The update did not match the code submitted to GitHub (i.e. attack F). | Applying SLSA recursively to all dependencies would have prevented this particular vector, because the provenance would have indicated that it either wasn’t built from a proper builder or that the source did not come from GitHub. |
| F | Upload an artifact that was not built by the CI/CD system | CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. | Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. |
| G | Compromise package repository | Attacks on Package Mirrors: Researcher ran mirrors for several popular package repositories, which could have been used to serve malicious packages. | Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. |
| H | Trick consumer into using bad package | Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. | SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. |
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.
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 mant 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 document covers all of the detailed requirements for an artifact to meet SLSA. For a broader overview, including basic terminology and threat model, see overview.
Reminder: SLSA is in alpha. The definitions below are not yet finalized and subject to change, particularly SLSA 3-4.
- What is SLSA?
- Definitions
- Source requirements
- Build requirements
- Provenance requirements
- Common requirements
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.
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. |
| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). |
| Build | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). |
| Package | Artifact that is “published” for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. |
| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). |
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).
Platform: Infrastructure or service that hosts the source, build, or distribution of software. Examples: GitHub, Google Cloud Build, Travis CI, Mozilla’s self-hosted Mercurial server.
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.
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.
Requirements on build process:
Requirements on the process by which provenance is generated and consumed:
| Requirement | Description | L1 | L2 | L3 | L4 |
|---|---|---|---|---|---|
| Available | The provenance is available to the consumer in a format that the consumer accepts. The format SHOULD be in-toto SLSA Provenance, but another format MAY be used if both producer and consumer agree and it meets all the other requirements. | ✓ | ✓ | ✓ | ✓ |
| Authenticated | The provenance’s authenticity and integrity can be verified by the consumer. This SHOULD be through a digital signature from a private key accessible only to the service generating the provenance. | ✓ | ✓ | ✓ | |
| Service generated | The data in the provenance MUST be obtained from the build service (either because the generator is the build service or because the provenance generator reads the data directly from the build service).Regular users of the service MUST NOT be able to inject or alter the contents, except as noted below. The following provenance fields MAY be generated by the user-controlled build steps: The output artifact hash from Identifies Artifact. Reasoning: This only allows a “bad” build to falsely claim that it produced a “good” artifact. This is not a security problem because the consumer MUST accept only “good” builds and reject “bad” builds. The “reproducible” boolean and justification from Reproducible. | ✓ | ✓ | ✓ | |
| Non-falsifiable | Provenance cannot be falsified by the build service’s users. NOTE: This requirement is a stricter version of Service Generated.The provenance signing key MUST be stored in a secure key management system accessible only to the build service account. The provenance signing key MUST NOT be accessible to the environment running the user-defined build steps. Every field in the provenance MUST be generated or verified by the build service in a trusted control plane. The user-controlled build steps MUST NOT be able to inject or alter the contents, except as noted below.The following provenance fields MAY be generated by the user-controlled build steps without the build service verifying their correctness: The output artifact hash from Identifies Artifact. Reasoning: This only allows a “bad” build to falsely claim that it produced a “good” artifact. This is not a security problem because the consumer MUST accept only “good” builds and reject “bad” builds. The “reproducible” boolean and justification from Reproducible. | ✓ | ✓ | ||
| Dependencies complete | Provenance records all build dependencies that were available while running the build steps. This includes the initial state of the machine, VM, or container of the build worker.MUST include all user-specified build steps, sources, dependencies.SHOULD include all service-provided artifacts. | ✓ |
Requirements on the contents of the provenance:
Common requirements for every trusted system involved in the supply chain (source, build, distribution, etc.)
| Requirement | Description | L1 | L2 | L3 | L4 |
|---|---|---|---|---|---|
| Security | The system meets some TBD baseline security standard to prevent compromise. (Patching, vulnerability scanning, user isolation, transport security, secure boot, machine identity, etc. Perhaps NIST 800-53 or a subset thereof.) | ✓ | |||
| Access | All physical and remote access must be rare, logged, and gated behind multi-party approval. | ✓ | |||
| Superusers | Only a small number of platform admins may override the guarantees listed here. Doing so MUST require approval of a second platform admin. | ✓ |
Example
Consider the example of using curl through its official docker image. What threats are we exposed to in the software supply chain? (We choose curl simply because it is a popular open-source package, not to single it out.)
The first problem is figuring out the actual supply chain. This requires significant manual effort, guesswork, and blind trust. Working backwards:
- The “latest” tag in Docker Hub points to 7.72.0.
- It claims to have come from a Docker file in the curl/curl-docker GitHub repository.
- That Docker file reads the following artifacts, assuming there are no further fetches during build time:
- Docker Hub image: registry.hub.docker.com/library/alpine:3.11.5
- Alpine packages: libssh2 libssh2-dev libssh2-static auto conf auto make build-base groff open ssl curl-dev python3 python3-dev lib tool curl stunnel perl nghttp2
- File at URL: https://curl.haxx.se/ca/cacert.pem
- Each of the dependencies has its own supply chain, but let’s look at curl-dev, which contains the actual “curl” source code.
- The package, like all Alpine packages, has its build script defined in an APKBUILD in the Alpine git repo. There are several build dependencies:
- File at URL: https://curl.haxx.se/download/curl-7.72.0.tar.xz.
- The APKBUILD includes a sha256 hash of this file. It is not clear where that hash came from.
- Alpine packages: openssl-dev nghttp2-dev zlib-dev brotli-dev autoconf automake groff libtool perl
- File at URL: https://curl.haxx.se/download/curl-7.72.0.tar.xz.
- The source tarball was presumably built from the actual upstream GitHub repository curl/curl@curl-7_72_0, by running the commands
./buildconf && ./configure && make && ./maketgz 7.72.0. That command has a set of dependencies, but those are not well documented. - Finally, there are the systems that actually ran the builds above. We have no indication about their software, configuration, or runtime state whatsoever.
Suppose some developer’s machine is compromised. What attacks could potentially be performed unilaterally with only that developer’s credentials? (None of these are confirmed.)
- Directly upload a malicious image to Docker Hub.
- Point the CI/CD system to build from an unofficial Dockerfile.
- Upload a malicious Dockerfile (or other file) in the curl/curl-docker git repo.
- Upload a malicious https://curl.haxx.se/ca/cacert.pem.
- Upload a malicious APKBUILD in Alpine’s git repo.
- Upload a malicious curl-dev Alpine package to the Alpine repository. (Not sure if this is possible.)
- Upload a malicious https://curl.haxx.se/download/curl-7.72.0.tar.xz. (Won’t be detected by APKBUILD’s hash if the upload happens before the hash is computed.)
- Upload a malicious change to the curl/curl git repo.
- Attack any of the systems involved in the supply chain, as in the SolarWinds attack.
SLSA intends to cover all of these threats. When all artifacts in the supply chain have a sufficient SLSA level, consumers can gain confidence that most of these attacks are mitigated, first via self-certification and eventually through automated verification.
Finally, note that all of this is just for curl’s own first-party supply chain steps. The dependencies, namely the Alpine base image and packages, have their own similar threats. And they too have dependencies, which have other dependencies, and so on. Each dependency has its own SLSA level and the composition of SLSA levels describes the entire supply chain’s security.
For another look at Docker supply chain security, see Who’s at the Helm? For a much broader look at open source security, including these issues and many more, see Threats, Risks, and Mitigations in the Open Source Ecosystem.
Let’s consider how we might secure curlimages/curl from the motivating example using the SLSA framework.
Let’s start by incrementally applying the SLSA principles to the final Docker image.
Initially the Docker image is SLSA 0. There is no provenance. It is difficult to determine who built the artifact and what sources and dependencies were used.
The diagram shows that the (mutable) locator curlimages/curl:7.72.0 points to (immutable) artifact sha256:3c3ff….
SLSA 1: Provenance
We can reach SLSA 1 by scripting the build and generating provenance. The build script was already automated via make, so we use simple tooling to generate the provenance on every release. Provenance records the output artifact hash, the builder (in this case, our local machine), and the top-level source containing the build script.
In the updated diagram, the provenance attestation says that the artifact sha256:3c3ff… was built from curl/curl-docker@d6525….
At SLSA 1, the provenance does not protect against tampering or forging but may be useful for vulnerability management.
To reach SLSA 2 (and later SLSA 3), we must switch to a hosted build service that generates provenance for us. This updated provenance should also include dependencies on a best-effort basis. SLSA 3 additionally requires the source and build platforms to implement additional security controls, which might need to be enabled.
In the updated diagram, the provenance now lists some dependencies, such as the base image (alpine:3.11.5) and apk packages (e.g. curl-dev).
At SLSA 3, the provenance is significantly more trustworthy than before. Only highly skilled adversaries are likely able to forge it.
SLSA 4: Hermeticity and two-person review
SLSA 4 requires two-party source control and hermetic builds. Hermeticity in particular guarantees that the dependencies are complete. Once these controls are enabled, the Docker image will be SLSA 4.
In the updated diagram, the provenance now attests to its hermeticity and includes the cacert.pem dependency, which was absent before.
At SLSA 4, we have high confidence that the provenance is complete and trustworthy and that no single person can unilaterally change the top-level source.
We can recursively apply the same steps above to lock down dependencies. Each non-source dependency gets its own provenance, which in turns lists more dependencies, and so on.
The final diagram shows a subset of the graph, highlighting the path to the upstream source repository (curl/curl) and the certificate file (cacert.pem).
In reality, the graph is intractably large due to the fanout of dependencies. There will need to be some way to trim the graph to focus on the most important components. While this can reasonably be done by hand, we do not yet have a solid vision for how best to do this in an scalable, generic, automated way. One idea is to use ecosystem-specific heuristics. For example, Debian packages are built and organized in a very uniform way, which may allow Debian-specific heuristics.
An artifact’s SLSA level is not transitive, so some aggregate measure of security risk across the whole supply chain is necessary. In other words, each node in our graph has its own, independent SLSA level. Just because an artifact’s level is N does not imply anything about its dependencies’ levels.
In our example, suppose that the final curl images/curl Docker image were SLSA 4 but its curl-dev dependency were SLSA 0. Then this would imply a significant security risk: an adversary could potentially introduce malicious behavior into the final image by modifying the source code found in the curl-dev package. That said, even being able to identify that it has a SLSA 0 dependency has tremendous value because it can help focus efforts.
Formation of this aggregate risk measure is left for future work. It is perhaps too early to develop such a measure without real-world data. Once SLSA becomes more widely adopted, we expect patterns to emerge and the task to get a bit easier.
Accreditation and delegation will play a large role in the SLSA framework. It is not practical for every software consumer to fully vet every platform and fully walk the entire graph of every artifact. Auditors and/or accreditation bodies can verify and assert that a platform or vendor meets the SLSA requirements when configured in a certain way. Similarly, there may be some way to “trust” an artifact without analyzing its dependencies. This may be particularly valuable for closed source software.
