Skip to content

GitLab

Unverified Commit 3af201ab authored by Mark Lodato's avatar Mark Lodato Committed by GitHub
Browse files

Merge pull request #275 from MarkLodato/reorg 

Add terminology page and reshuffle content
parents bd5a1d5a c967745c
Expand all Hide whitespace changes
Inline Side-by-side
docs/_data/nav.yml
View file @ 3af201ab
......@@ -8,7 +8,10 @@
- title: Introduction
url: /spec/v0.1/index
- title: Security levels
- title: Terminology
url: /spec/v0.1/terminology
- title: Levels
url: /spec/v0.1/levels
- title: Requirements
......
docs/_spec/v0.1/index.md
View file @ 3af201ab
......@@ -32,15 +32,19 @@ levels:
badge: /images/SLSA-Badge-full-level4.svg
subpages:
- title: Terminology
description: Start here to understand how we model supply chains
relative_url: terminology
- title: Security levels
description: Start here for the level breakdowns
description: Ladder of increasing security guarantees
relative_url: levels
- title: Requirements
description: The checks and measures for each level
description: Technical requirements to reach each level
relative_url: requirements
- title: Threats
- title: Threats & mitigations
description: Specific supply chain attacks and how SLSA helps
relative_url: threats
......
docs/_spec/v0.1/levels.md
View file @ 3af201ab
......@@ -5,10 +5,30 @@ layout: specifications
---
<span class="subtitle">
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.
SLSA is organized into a series of levels that provide increasing
[integrity](terminology.md) guarantees. This gives you confidence that that
software hasn’t been tampered with and can be securely traced back to its
source.
</span>
This page is an informative overview of the SLSA levels, describing their
purpose and guarantees. For the normative requirements at each level, see
[Requirements](requirements.md).
## 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
| Level | Description | Example |
| :---- | :-------------------------------------------- | :---------------------------------------------------- |
| 1 | Documentation of the build process | Unsigned provenance |
......@@ -30,89 +50,6 @@ It can take years to achieve the ideal security state - intermediate milestones
The SLSA level is not transitive ([see our FAQs](../faq.md)). 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.
## Level requirements
The following table provides a summary of the [requirements](requirements.md) 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 - [Build as code] | | | ✓ | ✓ |
| 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] | | | | ✓ |
<!-- markdownlint-disable MD036 -->
_○ = required unless there is a justification_
[access]: requirements.md#access
[authenticated]: requirements.md#authenticated
[available]: requirements.md#available
[build as code]: requirements.md#build-as-code
[build service]: requirements.md#build-service
[dependencies complete]: requirements.md#dependencies-complete
[ephemeral environment]: requirements.md#ephemeral-environment
[hermetic]: requirements.md#hermetic
[isolated]: requirements.md#isolated
[non-falsifiable]: requirements.md#non-falsifiable
[parameterless]: requirements.md#parameterless
[reproducible]: requirements.md#reproducible
[retained indefinitely]: requirements.md#retained-indefinitely
[scripted build]: requirements.md#scripted-build
[security]: requirements.md#security
[service generated]: requirements.md#service-generated
[superusers]: requirements.md#superusers
[two-person reviewed]: requirements.md#two-person-reviewed
[verified history]: requirements.md#verified-history
[version controlled]: requirements.md#version-controlled
## <a name="threats"></a>Supply chain threats
Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive and costly in today’s environment. In developing SLSA, the requirements for each level are designed to specifically mitigate the risk of such known examples. For a much deeper technical analysis of the risks and how SLSA mitigates them, see [Threats and mitigations](threats.md).
![Supply Chain Threats](../../images/supply-chain-threats.svg)
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](requirements.md#build-requirements), 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. |
[linux hypocrite commits]: https://lore.kernel.org/lkml/202105051005.49BFABCE@keescook/
[php]: https://news-web.php.net/php.internals/113838
[webmin]: https://www.webmin.com/exploit.html
[solarwinds]: https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/
[event-stream]: https://schneider.dev/blog/event-stream-vulnerability-explained/
[codecov]: https://about.codecov.io/apr-2021-post-mortem/
[attacks on package mirrors]: https://theupdateframework.io/papers/attacks-on-package-managers-ccs2008.pdf
[browserify typosquatting]: https://blog.sonatype.com/damaging-linux-mac-malware-bundled-within-browserify-npm-brandjack-attempt
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.
## Limitations
SLSA can help reduce supply chain threats in a software artifact, but there are limitations.
......
docs/_spec/v0.1/requirements.md
View file @ 3af201ab
......@@ -5,32 +5,71 @@ layout: specifications
---
<span class="subtitle">
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 the [overview](index.md).
This page covers all of the technical requirements for an artifact to meet the
[SLSA Levels](levels.md).
</span>
> Reminder: SLSA is in `alpha`. The definitions below are not yet finalized and subject to change, particularly SLSA 3-4.
## 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](levels.md) 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.
### Terminology
For background, see [Introduction](index.md) and [Terminology](terminology.md).
To better understand the reasoning behind the requirements, see
[Threats and mitigations](threats.md).
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](https://en.wikipedia.org/wiki/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.
![Software Supply Chain Model](../../images/supply-chain-model.svg)
> Reminder: SLSA is in `alpha`. The definitions below are not yet finalized and subject to change, particularly SLSA 3-4.
| 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). |
## Summary table
| 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 - [Build as code] | | | ✓ | ✓ |
| 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] | | | | ✓ |
<!-- markdownlint-disable MD036 -->
_○ = required unless there is a justification_
[access]: #access
[authenticated]: #authenticated
[available]: #available
[build as code]: #build-as-code
[build service]: #build-service
[dependencies complete]: #dependencies-complete
[ephemeral environment]: #ephemeral-environment
[hermetic]: #hermetic
[isolated]: #isolated
[non-falsifiable]: #non-falsifiable
[parameterless]: #parameterless
[reproducible]: #reproducible
[retained indefinitely]: #retained-indefinitely
[scripted build]: #scripted-build
[security]: #security
[service generated]: #service-generated
[superusers]: #superusers
[two-person reviewed]: #two-person-reviewed
[verified history]: #verified-history
[version controlled]: #version-controlled
## Definitions
> See also [Terminology](terminology.md) for general SLSA concepts. The
> defintions 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](https://www.rfc-editor.org/rfc/rfc2119).
......
docs/_spec/v0.1/terminology.md 0 → 100644
View file @ 3af201ab
---
title: Terminology
version: 0.1
layout: specifications
---
<div class="subtitle">
Before diving into the [SLSA Levels](levels.md), we need to establish a core set
of terminology and models to describe what we're protecting.
</div>
## 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.
[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph
![Software Supply Chain Model](../../images/supply-chain-model.svg)
| 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). |
## Supply chain integrity
SLSA is focused on supply chain integrity. This means protection against
tampering or unauthorized modification at any stage of the software lifecycle.
Within SLSA, we divide integrity into two main areas:
**Source Integrity and Availability:** Ensure that all changes to the source
code reflect the intent of the software producer, and that the code and change
history remain available for investigations and incident response. Intent of an
organization is difficult to define, so we approximate this as approval from two
authorized representatives.
**Build Integrity:** Ensure that packages are 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.
> For a detailed look at integrity, see [Threats and mitigations](threats.md).
![Supply Chain Threats](../../images/supply-chain-threats-no-labels.svg)
docs/_spec/v0.1/threats.md
View file @ 3af201ab
---
title: Threats
title: Threats and mitigations
version: 0.1
layout: specifications
---
<!-- markdownlint disable required to avoid list sub-items appearing in table of contents -->
<!-- markdownlint-disable MD001 -->
<div class="subtitle">
> **IMPORTANT:** This is a work in progress.
This document is a comprehensive technical analysis of supply chain integrity
threats and their corresponding mitigations in SLSA. For a higher level overview
of threats and mitigations, please see
[Supply chain threats](levels.md#threats).
Attacks can occur at every link in a typical software supply chain, and these
kinds of attacks are increasingly public, disruptive, and costly in today's
environment.
The goals of this document are to:
</div>
- 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.
SLSA's [levels](levels.md) are designed to mitigate the risk of these attacks.
This page enumerates possible attacks throughout the supply chain and shows how
SLSA can help.
## Definition of integrity
## Supply chain threats
![Supply Chain Threats](../../images/supply-chain-threats.svg)
Our goal is to provide software supply chain integrity, but we first need to
define "integrity." Within SLSA, we divide integrity into two main areas:
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](requirements.md#build-requirements), 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. |
[linux hypocrite commits]: https://lore.kernel.org/lkml/202105051005.49BFABCE@keescook/
[php]: https://news-web.php.net/php.internals/113838
[webmin]: https://www.webmin.com/exploit.html
[solarwinds]: https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/
[event-stream]: https://schneider.dev/blog/event-stream-vulnerability-explained/
[codecov]: https://about.codecov.io/apr-2021-post-mortem/
[attacks on package mirrors]: https://theupdateframework.io/papers/attacks-on-package-managers-ccs2008.pdf
[browserify typosquatting]: https://blog.sonatype.com/damaging-linux-mac-malware-bundled-within-browserify-npm-brandjack-attempt
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
**Source Integrity and Availability:** Ensure that all changes to the source
code reflect the intent of the software producer, and that the code and change
history remain available for investigations and incident response. Intent of an
organization is difficult to define, so we approximate this as approval from two
authorized representatives.
> **IMPORTANT:** This is a work in progress.
**Build Integrity:** Ensure that packages are 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.
What follows is a comprehensive technical analysis of supply chain integrity
threats and their corresponding mitigations in SLSA. For definitions, see
[Terminology](terminology.md).
The goals of this section are to:
- Explain the reasons for each of the SLSA [requirements](requirements.md).
- Increase confidence that the SLSA requirements are sufficient to achieve the
desired [level](levels.md) of integrity protection.
- Help implementers better understand what they are protecting against so that
they can better design and implement controls.
## Source integrity and availability
### Source integrity and availability
<article class="threats">
......@@ -296,7 +318,7 @@ management system to bypass controls.
</details>
## Build integrity
### Build integrity
#### (C) Modify code after source control
......@@ -557,7 +579,7 @@ ad-hoc analysis, and can complement source-based typosquatting solutions.
</details>
## Things that don't fit well in current picture
### Things that don't fit well in current picture
<details><summary>Tamper with policy <span>(TBD)</span></summary>
......
docs/images/supply-chain-threats-no-labels.svg 0 → 100644
View file @ 3af201ab
This diff is collapsed.
docs/terminology.md 0 → 100644
View file @ 3af201ab
---
layout: redirect
redirect_to_url: spec/v0.1/terminology # WARNING: This is brittle and will not update as per {{ site.current_spec_version }}
sitemap: false
---
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment