1- # SLSA Build and Provenance Requirements
1+ # Requirements
22
3- TODO: Add an introduction, diagram, threat model, and high-level description of
4- each level.
3+ Table of Contents:
4+
5+ * [ Definitions] ( #definitions )
6+ * [ Source Requirements] ( #source-requirements )
7+ * [ Build Requirements] ( #build-requirements )
8+ * [ Provenance Requirements] ( #provenance-requirements )
9+ * [ Common Requirements] ( #common-requirements )
510
611_ Reminder: The definitions below are not yet finalized and subject to change,
712particularly SLSA 3-4._
813
9- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
10- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
11- interpreted as described in
12- [ RFC 2119] ( https://www.rfc-editor.org/rfc/rfc2119 ) .
14+ This document enumerates all of the detailed requirements for an artifact to
15+ meet SLSA. For a broader overview, including basic terminology and threat model,
16+ see the [ main page] ( README.md ) .
1317
1418## Definitions
1519
16- ** Provenance** : Metadata about how an artifact was produced.
17-
1820<a id =" immutable-reference " ></a >** Immutable reference:** An identifier that is
1921guaranteed to always point to the same, immutable artifact. This MUST allow the
2022consumer 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).
2426[ immutable reference ] : #immutable-reference
2527[ immutable references ] : #immutable-reference
2628
27- ## Requirements
29+ ** Platform:** Infrastructure or service that hosts the source, build, or
30+ distribution of software. Examples: GitHub, Google Cloud Build, Travis CI,
31+ [ Mozilla's self-hosted Mercurial server] ( https://hg.mozilla.org ) .
2832
29- ### Build Requirements
33+ ** Provenance** : Metadata about how an artifact was produced.
34+
35+ ** Revision:** An immutable, coherent state of a source. In Git, for example, a
36+ revision is a commit in the history reachable from a specific branch in a
37+ specific repository. Different revisions within one repo MAY have different
38+ levels. Example: the most recent revision on a branch meets SLSA 4 but very old
39+ historical revisions before the cutoff do not.
40+
41+ ** Trusted persons:** Set of persons who are granted the authority to maintain a
42+ software project. For example, https://github.com/MarkLodato/dotfiles has just
43+ one trusted person (MarkLodato), while https://hg.mozilla.org/mozilla-central
44+ has a set of trusted persons with write access to the mozilla-central
45+ repository.
46+
47+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
48+ "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
49+ interpreted as described in [ RFC 2119] ( https://www.rfc-editor.org/rfc/rfc2119 ) .
50+
51+ ## Source requirements
52+
53+ ### SLSA 1
54+
55+ There are no source requirements at SLSA 1.
56+
57+ ### SLSA 2
58+
59+ A revision meets SLSA 2 if all of the following are true:
60+
61+ * <a id =" version-controlled " ></a >** [ Version Controlled] ** Every change to the
62+ source is tracked in a version control system that meets the following
63+ requriements.
64+
65+ - ** [ Change History] ** There exists a record of the history of changes
66+ that went into the revision. Each change must contain: the identities of
67+ the uploader and reviewers (if any), timestamps of the reviews (if any)
68+ and submission, the change description / justification, the content of
69+ the change, and the parent revisions.
70+
71+ - ** [ Immutable Reference] ** There exists a way to indefinitely reference
72+ this particular, immutable revision. In git, this is the {repo URL +
73+ branch/tag/ref + commit ID}.
74+
75+ Most popular version control system meet this requirement, such as git,
76+ Mercurial, Subversion, or Perforce.
77+
78+ NOTE: This does NOT require that the code, uploader/reviewer identities, or
79+ change history be made public. Rather, some organization must attest to the fact
80+ that these requirements are met, and it is up to the consumer whether this
81+ attestation is sufficient.
82+
83+ ### SLSA 3
84+
85+ _ NOTE: The SLSA 3 requirements are subject to change._
86+
87+ A revision meets SLSA 3 if all of the following are true:
88+
89+ - The revision meets [ SLSA 2] ( #slsa-2 ) .
90+
91+ - <a id =" verified-history " ></a >** [ Verified History] ** Every change in the
92+ revision's history has at least one strongly authenticated actor identities
93+ (author, uploader, reviewer, etc.) and timestamp. It must be clear which
94+ identities were verified, and those identities must use
95+ [ two-step verification] ( https://www.google.com/landing/2step/ ) or similar.
96+ (Exceptions noted below.)
97+
98+ - ** [ First-Parent History] ** In the case of a non-linear version control
99+ system, where a revision can have more than one parent, only the "first
100+ parent history" is in scope. In other words, when a feature branch is
101+ merged back into the main branch, only the merge itself is in scope.
102+ - ** [ Historical Cutoff] ** There is some TBD exception to allow existing
103+ projects to meet SLSA 3/4 even if historical revisions were present in
104+ the history. Current thinking is that this could be either last N months
105+ or a platform attestation guaranteeing that future changes in the next N
106+ months will meet the requirements.
107+
108+ - <a id =" retained-indefinitely " ></a >** [ Retained Indefinitely] ** The revision
109+ and its change history are preserved indefinitely and cannot be deleted,
110+ except when subject to an established and transparent policy for
111+ obliteration, such as a legal or policy requirement.
112+
113+ - ** [ Immutable History] ** It must not be possible for persons to delete or
114+ modify the history, even with multi-party approval, except by trusted
115+ platform admins with two-party approval following the obliterate policy.
116+ - ** [ Limited Retention for SLSA 2] ** At SLSA 2 (but not 3), it is
117+ acceptable for the retention to be limited to 18 months, as attested by
118+ the source control platform.
119+ - Example: If a commit is made on 2020-04-05 and then a retention
120+ attestation is generated on 2021-01-01, the commit must be retained
121+ until at least 2022-07-01.
122+
123+ ### SLSA 4
124+
125+ _ NOTE: The SLSA 4 requirements are subject to change._
126+
127+ A revision meets SLSA 4 if all of the following are true:
128+
129+ - The revision meets [ SLSA 3] ( #slsa-3 ) .
130+
131+ - <a id =" two-person-reviewed " ></a >** [ Two-Person Reviewed] ** Every change in
132+ the revision's history was agreed to by two trusted persons prior to
133+ submission, and both of these trusted persons were strongly authenticated.
134+ (Exceptions from [ Verified History] apply here as well.)
135+
136+ - The following combinations are acceptable:
137+ - Uploader and reviewer are two different trusted persons.
138+ - Two different reviewers are trusted persons.
139+ - ** [ Different Persons] ** The platform ensures that no person can use
140+ alternate identities to bypass the two-person review requirement.
141+ - Example: if a person uploads with identity X then reviews with alias
142+ Y, the platform understands that this is the same person and does
143+ not consider the review requirement satisfied.
144+ - ** [ Informed Review] ** The reviewer is able and encouraged to make an
145+ informed decision about what they're approving. The reviewer should be
146+ presented with a full, meaningful content diff between the proposed
147+ revision and the previously reviewed revision. For example, it is not
148+ sufficient to just indicate that file changed without showing the
149+ contents.
150+ - ** [ Context-specific Approvals] ** Approvals are for a specific context,
151+ such as a repo + branch in git. Moving fully reviewed content from one
152+ context to another still requires review. (Exact definition of "context"
153+ depends on the project, and this does not preclude well-understood
154+ automatic or reviewless merges, such as cutting a release branch.)
155+ - Git example: If a fully reviewed commit in one repo is merged into a
156+ different repo, or a commit in one branch is merged into a different
157+ branch, then the merge still requires review.
158+
159+ ## Build Requirements
30160
31161Requirements on build process:
32162
@@ -152,7 +282,7 @@ Requirements on build process:
152282 </tr >
153283</table >
154284
155- ### Provenance Requirements
285+ ## Provenance Requirements
156286
157287Requirements on the process by which provenance is generated and consumed:
158288
@@ -316,3 +446,24 @@ Requirements on the contents of the provenance:
316446 <td >○<td >○<td >○<td >○
317447 </tr >
318448</table >
449+
450+ ## Common requirements
451+
452+ TODO: Write this section
453+
454+ Common requirements for every trusted system involved in the supply chain
455+ (source, build, distribution, etc.)
456+
457+ * <a id =" security " ></a >** [ Security] ** The system meets some TBD baseline
458+ security standard to prevent compromise. (Patching, vulnerability scanning,
459+ user isolation, transport security, secure boot, machine identity, etc.
460+ Perhaps
461+ [ NIST 800-53] ( https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-53r5.pdf )
462+ or a subset thereof.)
463+
464+ * <a id =" access " ></a >** [ Access] ** All physical and remote access must be rare,
465+ logged, and gated behind multi-party approval.
466+
467+ * <a id =" superusers " ></a >** [ Superusers] ** Only a small number of platform
468+ admins may override the guarantees listed here. Doing so MUST require
469+ approval of a second platform admin.
0 commit comments