Merge pull request #74 from MarkLodato/merged-reqs

Merge all requirements docs into one.

README.md

@@ -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
 

_config.yml

@@ -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

build-requirements.md → requirements.md

@@ -1,20 +1,22 @@
-# 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.