Merge pull request #17 from MarkLodato/source-reqs

Add detailed source requirements.

README.md

@@ -365,25 +365,25 @@ effort, so intermediate milestones are important.
 
 _○ = required unless there is a justification_
 
-Note: The actual requirements will necessarily be much more detailed and
-nuanced. We only provide a brief summary here for clarity.
+The following is a summary. For details, see corresponding
+[Source][source-reqs], [Build/Provenance][build-reqs], and [Common][common-reqs]
+documents.
 
-**[Source]** Requirements for the artifact's top-level source (i.e. the one
-containing the build script):
+**[\[Source\]][source-reqs]** Requirements for the artifact's top-level source,
+meaning the one containing the build script:
 
 *   **[Version Controlled]** Every change to the source is tracked in a version
     control system that identifies who made the change, what the change was, and
     when that change occurred.
-*   **[Verified History]** The version control history indicates which actor
-    identities (author, uploader, reviewer, etc.) and timestamps were strongly
-    authenticated. For example, GitHub-generated merge commits for pull requests
-    meet this requirement.
+*   **[Verified History]** Every change in the history has at least one strongly
+    authenticated actor identity (author, uploader, reviewer, etc.) and
+    timestamp.
 *   **[Retained Indefinitely]** The artifact and its change history are retained
     indefinitely and cannot be deleted.
 *   **[Two-Person Review]** At least two trusted persons agreed to every change
     in the history.
 
-**[Build]** Requirements for the artifact's build process:
+**[\[Build\]][build-reqs]** Requirements for the artifact's build process:
 
 *   **[Scripted]** All build steps were fully defined in some sort of "build
     script". The only manual command, if any, was to invoke the build script.
@@ -403,7 +403,7 @@ containing the build script):
     results in bit-for-bit identical output. (Builds that cannot meet this must
     provide a justification.)
 
-**[Provenance]** Requirements for the artifact's provenance:
+**[\[Provenance\]][build-reqs]** Requirements for the artifact's provenance:
 
 *   **[Available]** Provenance is available to the consumer of the artifact, or
     to whomever is verifying the policy, and it identifies at least the
@@ -419,8 +419,8 @@ containing the build script):
     meaning every artifact that was available to the build script. This includes
     the initial state of the machine, VM, or container of the build worker.
 
-**[Common]** Common requirements for every trusted system involved in the supply
-chain (source, build, distribution, etc.):
+**[\[Common\]][common-reqs]** Common requirements for every trusted system
+involved in the supply chain (source, build, distribution, etc.):
 
 *   **[Security]** The system meets some TBD baseline security standard to
     prevent compromise. (Patching, vulnerability scanning, user isolation,
@@ -638,7 +638,10 @@ Other takes on provenance and CI/CD:
 
 [Binary Authorization for Borg]: https://cloud.google.com/security/binary-authorization-for-borg
 [Threats, Risks, and Mitigations in the Open Source Ecosystem]: https://github.com/Open-Source-Security-Coalition/Open-Source-Security-Coalition/blob/master/publications/threats-risks-mitigations/v1.1/Threats%2C%20Risks%2C%20and%20Mitigations%20in%20the%20Open%20Source%20Ecosystem%20-%20v1.1.pdf
+[build-reqs]: build-requirements.md
+[common-reqs]: common-requirements.md
 [curl-dev]: https://pkgs.alpinelinux.org/package/edge/main/x86/curl-dev
 [curlimages/curl]: https://hub.docker.com/r/curlimages/curl
 [feedback form]: https://forms.gle/93QRfUqF7YY2mJDi9
 [mailing list]: https://groups.google.com/g/slsa-discussion
+[source-reqs]: source-requirements.md

build-requirements.md

+# SLSA Build and Provenance Requirements
+
+TODO

common-requirements.md

+# SLSA Common Platform Requirements
+
+TODO

source-requirements.md

+# 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 3 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 1.5
+
+A revision meets SLSA 1.5 if all of the following are true:
+
+*   **[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 2
+
+_NOTE: The SLSA 2 requirements are subject to change._
+
+A revision meets SLSA 2 if all of the following are true:
+
+-   The revision meets [SLSA 1.5](#slsa-15).
+
+-   **[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 2/3 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.
+
+-   **[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 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).
+
+-   **[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.