Commit f7bdd1d8 authored by Mark Lodato's avatar Mark Lodato
Browse files

Merge all requirements docs into one.

This allows us to add a link to the top of the website, and it also
makes it easier to see all requirements on one page.

NOTE: In a future change, I will reformat the source and common
requirements into table form, to match the build requirements.
parent d017a426
......@@ -250,8 +250,8 @@ mean the lack of a SLSA level.
### Level requirements
The following is a summary. For details, see corresponding [Source],
[Build/Provenance], and [Common] documents.
The following is a summary. For details, click the links in the table for
corresponding [requirements](requirements.md).
Requirement | SLSA 1 | SLSA 2 | SLSA 3 | SLSA 4
------------------------------------ | ------ | ------ | ------ | ------
......@@ -277,28 +277,25 @@ Common - [Superusers] | | | | ✓
_○ = required unless there is a justification_
[Access]: common-requirements.md#access
[Authenticated]: build-requirements.md#authenticated
[Available]: build-requirements.md#available
[Build Service]: build-requirements.md#build-service
[Build/Provenance]: build-requirements.md
[Common]: common-requirements.md
[Dependencies Complete]: build-requirements.md#dependencies-complete
[Ephemeral Environment]: build-requirements.md#ephemeral-environment
[Hermetic]: build-requirements.md#hermetic
[Isolated]: build-requirements.md#isolated
[Non-Falsifiable]: build-requirements.md#non-falsifiable
[Parameterless]: build-requirements.md#parameterless
[Reproducible]: build-requirements.md#reproducible
[Retained Indefinitely]: source-requirements.md#retained-indefinitely
[Scripted Build]: build-requirements.md#scripted-build
[Security]: common-requirements.md#security
[Service Generated]: build-requirements.md#service-generated
[Source]: source-requirements.md
[Superusers]: common-requirements.md#superusers
[Two-Person Reviewed]: source-requirements.md#two-person-reviewed
[Verified History]: source-requirements.md#verified-history
[Version Controlled]: source-requirements.md#version-controlled
[Access]: requirements.md#access
[Authenticated]: requirements.md#authenticated
[Available]: requirements.md#available
[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
## Scope of SLSA
......
......@@ -3,6 +3,7 @@ description: Supply-chain Levels for Software Artifacts
copyright_html: Copyright 2021 The Linux Foundation<br>under the terms of the <a href="https://github.com/slsa-framework/slsa/blob/main/LICENSE">Apache License 2.0</a>
repository: slsa-framework/slsa
header_pages:
- requirements.md
- walkthrough.md
theme: minima
......
# SLSA Common Platform Requirements
TODO: Write this document.
Common requirements for every trusted system involved in the supply chain
(source, build, distribution, etc.)
* <a id="security"></a>**[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](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-53r5.pdf)
or a subset thereof.)
* <a id="access"></a>**[Access]** All physical and remote access must be
rare, logged, and gated behind multi-party approval.
* <a id="superusers"></a>**[Superusers]** Only a small number of platform admins
may override the guarantees listed here. Doing so MUST require approval of a
second platform admin.
# SLSA Build and Provenance Requirements
# Requirements
TODO: Add an introduction, diagram, threat model, and high-level description of
each level.
Table of Contents:
* [Definitions](#definitions)
* [Source Requirements](#source-requirements)
* [Build Requirements](#build-requirements)
* [Provenance Requirements](#provenance-requirements)
* [Common Requirements](#common-requirements)
_Reminder: The definitions below are not yet finalized and subject to change,
particularly SLSA 3-4._
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).
This document enumerates all of the detailed requirements for an artifact to
meet SLSA. For a broader overview, including basic terminology and threat model,
see the [main page](README.md).
## Definitions
**Provenance**: Metadata about how an artifact was produced.
<a id="immutable-reference"></a>**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
......@@ -24,9 +26,137 @@ commit ID; cloud storage bucket ID + SHA-256 hash; Subversion URL (no hash).
[immutable reference]: #immutable-reference
[immutable references]: #immutable-reference
## Requirements
**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](https://hg.mozilla.org).
### Build Requirements
**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.
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).
## Source requirements
### SLSA 1
There are no source requirements at SLSA 1.
### SLSA 2
A revision meets SLSA 2 if all of the following are true:
* <a id="version-controlled"></a>**[Version Controlled]** Every change to the
source is tracked in a version control system that meets the following
requriements.
- **[Change History]** There exists a record of the history of changes
that went into the revision. Each change must contain: the identities of
the uploader and reviewers (if any), timestamps of the reviews (if any)
and submission, the change description / justification, the content of
the change, and the parent revisions.
- **[Immutable Reference]** There exists a way to indefinitely reference
this particular, immutable revision. In git, this is the {repo URL +
branch/tag/ref + commit ID}.
Most popular version control system meet this requirement, such as git,
Mercurial, Subversion, or Perforce.
NOTE: This does NOT require that the code, uploader/reviewer identities, or
change history be made public. Rather, some organization must attest to the fact
that these requirements are met, and it is up to the consumer whether this
attestation is sufficient.
### SLSA 3
_NOTE: The SLSA 3 requirements are subject to change._
A revision meets SLSA 3 if all of the following are true:
- The revision meets [SLSA 2](#slsa-2).
- <a id="verified-history"></a>**[Verified History]** Every change in the
revision's history has at least one strongly authenticated actor identities
(author, uploader, reviewer, etc.) and timestamp. It must be clear which
identities were verified, and those identities must use
[two-step verification](https://www.google.com/landing/2step/) or similar.
(Exceptions noted below.)
- **[First-Parent History]** In the case of a non-linear version control
system, where a revision can have more than one parent, only the "first
parent history" is in scope. In other words, when a feature branch is
merged back into the main branch, only the merge itself is in scope.
- **[Historical Cutoff]** There is some TBD exception to allow existing
projects to meet SLSA 3/4 even if historical revisions were present in
the history. Current thinking is that this could be either last N months
or a platform attestation guaranteeing that future changes in the next N
months will meet the requirements.
- <a id="retained-indefinitely"></a>**[Retained Indefinitely]** The revision
and its change history are preserved indefinitely and cannot be deleted,
except when subject to an established and transparent policy for
obliteration, such as a legal or policy requirement.
- **[Immutable History]** It must not be possible for persons to delete or
modify the history, even with multi-party approval, except by trusted
platform admins with two-party approval following the obliterate policy.
- **[Limited Retention for SLSA 2]** At SLSA 2 (but not 3), it is
acceptable for the retention to be limited to 18 months, as attested by
the source control platform.
- Example: If a commit is made on 2020-04-05 and then a retention
attestation is generated on 2021-01-01, the commit must be retained
until at least 2022-07-01.
### SLSA 4
_NOTE: The SLSA 4 requirements are subject to change._
A revision meets SLSA 4 if all of the following are true:
- The revision meets [SLSA 3](#slsa-3).
- <a id="two-person-reviewed"></a>**[Two-Person Reviewed]** Every change in
the revision's history was agreed to by two trusted persons prior to
submission, and both of these trusted persons were strongly authenticated.
(Exceptions from [Verified History] apply here as well.)
- The following combinations are acceptable:
- Uploader and reviewer are two different trusted persons.
- Two different reviewers are trusted persons.
- **[Different Persons]** The platform ensures that no person can use
alternate identities to bypass the two-person review requirement.
- Example: if a person uploads with identity X then reviews with alias
Y, the platform understands that this is the same person and does
not consider the review requirement satisfied.
- **[Informed Review]** The reviewer is able and encouraged to make an
informed decision about what they're approving. The reviewer should be
presented with a full, meaningful content diff between the proposed
revision and the previously reviewed revision. For example, it is not
sufficient to just indicate that file changed without showing the
contents.
- **[Context-specific Approvals]** Approvals are for a specific context,
such as a repo + branch in git. Moving fully reviewed content from one
context to another still requires review. (Exact definition of "context"
depends on the project, and this does not preclude well-understood
automatic or reviewless merges, such as cutting a release branch.)
- Git example: If a fully reviewed commit in one repo is merged into a
different repo, or a commit in one branch is merged into a different
branch, then the merge still requires review.
## Build Requirements
Requirements on build process:
......@@ -152,7 +282,7 @@ Requirements on build process:
</tr>
</table>
### Provenance Requirements
## Provenance Requirements
Requirements on the process by which provenance is generated and consumed:
......@@ -316,3 +446,24 @@ Requirements on the contents of the provenance:
<td><td><td><td>
</tr>
</table>
## Common requirements
TODO: Write this section
Common requirements for every trusted system involved in the supply chain
(source, build, distribution, etc.)
* <a id="security"></a>**[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](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-53r5.pdf)
or a subset thereof.)
* <a id="access"></a>**[Access]** All physical and remote access must be rare,
logged, and gated behind multi-party approval.
* <a id="superusers"></a>**[Superusers]** Only a small number of platform
admins may override the guarantees listed here. Doing so MUST require
approval of a second platform admin.
# SLSA Source Requirements
This document enumerates all of the detailed requirements for a source to meet
[SLSA](README.md).
## Definitions
A source **revision** is an immutable, coherent state of the 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.
A source repository has a set of "trusted persons" who own the project and a
"platform" that runs the infrastructure. For example, for
https://github.com/MarkLodato/dotfiles, there is just one "trusted person" (Mark
Lodato) and the platform is GitHub, while for
https://hg.mozilla.org/mozilla-central the set of "trusted persons" are those
with write access to the mozilla-central repository and the platform is
Mozilla's mercurial hosting.
## SLSA 1
There are no source requirements at SLSA 1.
## SLSA 2
A revision meets SLSA 2 if all of the following are true:
* <a id="version-controlled"></a>**[Version Controlled]** Every change to the
source is tracked in a version control system that meets the following
requriements.
- **[Change History]** There exists a record of the history of changes
that went into the revision. Each change must contain: the identities of
the uploader and reviewers (if any), timestamps of the reviews (if any)
and submission, the change description / justification, the content of
the change, and the parent revisions.
- **[Immutable Reference]** There exists a way to indefinitely reference
this particular, immutable revision. In git, this is the {repo URL +
branch/tag/ref + commit ID}.
Most popular version control system meet this requirement, such as git,
Mercurial, Subversion, or Perforce.
NOTE: This does NOT require that the code, uploader/reviewer identities, or
change history be made public. Rather, some organization must attest to the fact
that these requirements are met, and it is up to the consumer whether this
attestation is sufficient.
## SLSA 3
_NOTE: The SLSA 3 requirements are subject to change._
A revision meets SLSA 3 if all of the following are true:
- The revision meets [SLSA 2](#slsa-2).
- <a id="verified-history"></a>**[Verified History]** Every change in the
revision's history has at least one strongly authenticated actor identities
(author, uploader, reviewer, etc.) and timestamp. It must be clear which
identities were verified, and those identities must use
[two-step verification](https://www.google.com/landing/2step/) or similar.
(Exceptions noted below.)
- **[First-Parent History]** In the case of a non-linear version control
system, where a revision can have more than one parent, only the "first
parent history" is in scope. In other words, when a feature branch is
merged back into the main branch, only the merge itself is in scope.
- **[Historical Cutoff]** There is some TBD exception to allow existing
projects to meet SLSA 3/4 even if historical revisions were present in
the history. Current thinking is that this could be either last N months
or a platform attestation guaranteeing that future changes in the next N
months will meet the requirements.
- <a id="retained-indefinitely"></a>**[Retained Indefinitely]** The revision
and its change history are preserved indefinitely and cannot be deleted,
except when subject to an established and transparent policy for
obliteration, such as a legal or policy requirement.
- **[Immutable History]** It must not be possible for persons to delete or
modify the history, even with multi-party approval, except by trusted
platform admins with two-party approval following the obliterate policy.
- **[Limited Retention for SLSA 2]** At SLSA 2 (but not 3), it is
acceptable for the retention to be limited to 18 months, as attested by
the source control platform.
- Example: If a commit is made on 2020-04-05 and then a retention
attestation is generated on 2021-01-01, the commit must be retained
until at least 2022-07-01.
## SLSA 4
_NOTE: The SLSA 4 requirements are subject to change._
A revision meets SLSA 4 if all of the following are true:
- The revision meets [SLSA 3](#slsa-3).
- <a id="two-person-reviewed"></a>**[Two-Person Reviewed]** Every change in
the revision's history was agreed to by two trusted persons prior to
submission, and both of these trusted persons were strongly authenticated.
(Exceptions from [Verified History] apply here as well.)
- The following combinations are acceptable:
- Uploader and reviewer are two different trusted persons.
- Two different reviewers are trusted persons.
- **[Different Persons]** The platform ensures that no person can use
alternate identities to bypass the two-person review requirement.
- Example: if a person uploads with identity X then reviews with alias
Y, the platform understands that this is the same person and does
not consider the review requirement satisfied.
- **[Informed Review]** The reviewer is able and encouraged to make an
informed decision about what they're approving. The reviewer should be
presented with a full, meaningful content diff between the proposed
revision and the previously reviewed revision. For example, it is not
sufficient to just indicate that file changed without showing the
contents.
- **[Context-specific Approvals]** Approvals are for a specific context,
such as a repo + branch in git. Moving fully reviewed content from one
context to another still requires review. (Exact definition of "context"
depends on the project, and this does not preclude well-understood
automatic or reviewless merges, such as cutting a release branch.)
- Git example: If a fully reviewed commit in one repo is merged into a
different repo, or a commit in one branch is merged into a different
branch, then the merge still requires review.
# Detailed Example
# Example
## Motivating example
......@@ -140,9 +140,9 @@ highly skilled adversaries are likely able to forge it.
![slsa4](images/slsa-4.svg)
SLSA 4 [requires](#level-requirements) 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 3.
SLSA 4 [requires](requirements.md) 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 3.
In the updated diagram, the provenance now attests to its hermeticity and
includes the `cacert.pem` dependency, which was absent before.
......
Supports Markdown
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