content updates

Author: zachariahcox

docs/spec/draft/source-requirements.md

@@ -79,10 +79,10 @@ level.
 
 | Track/Level | Requirements | Focus
 | ----------- | ------------ | -----
-| [Source L1](#source-l1)  | Use a version control system | First steps towards operational maturity
-| [Source L2](#source-l2)  | History and controls for protected branches & tags | Preserve history and ensure the process has been followed
-| [Source L3](#source-l3)  | Signed provenance | Tampering by the source control system
-| [Source L4](#source-l4)  | Code review | Tampering by project contributors
+| [Source L1](#source-l1)  | Use a version control system. | Generation and use of discrete Source Revisions.
+| [Source L2](#source-l2)  | Preserve Change History and generate Source Provenance. | Reliable history through enforced controls and evidence. 
+| [Source L3](#source-l3)  | Enforce organizational intent with technical controls. | Consumer knowledge of consumable Source Revisions and their guaranteed technical controls.
+| [Source L4](#source-l4)  | Require code review. | Improved code quality and resistance to insider threats.
 
 <section id="source-l1">
 
@@ -105,45 +105,53 @@ Migrating to the appropriate tools is an important first step on the road to ope
 </section>
 <section id="source-l2">
 
-### Level 2: Controls
+### Level 2: History & Provenance
 
 <dl class="as-table">
 <dt>Summary<dd>
 
-Clarifies which branches and tags in a repo are consumable and guarantees that
-all changes to protected branches and tags are recorded and subject to the
-organization's technical controls.
+At least one branch’s history is continuous, immutable, and retained, and the
+SCS issues Source Provenance Attestations for each new Source Revision.
+The attestations provide contemporaneous, tamper‑resistant evidence of when
+changes were made, who made them, and which technical controls were enforced.
 
 <dt>Intended for<dd>
 
 All organizations of any size producing software of any kind.
 
 <dt>Benefits<dd>
 
-Allows organizations and source consumers the ability to ensure the change
-management process has been followed to track changes to the software over time
-and attribute those changes to the actors that made them.
+Reliable history allows organizations and consumers to track changes to software
+over time, enabling attribution of those changes to the actors that made them.
+Source Provenance provides strong, tamper-resistant evidence of the process that
+was followed to produce a Source Revision.
 
 </dl>
 </section>
 <section id="source-l3">
 
-### Level 3: Signed and Auditable Provenance
+### Level 3: Communication and Enforcement of Intent
 
 <dl class="as-table">
 <dt>Summary<dd>
 
-The SCS generates credible, tamper-resistant, and contemporaneous evidence of how a specific revision was created.
-It is provided to authorized users of the source repository in a documented format.
+The SCS is configured to enforce the Organization's intentions for the Source
+Repository using any necessary technical controls.
+
+The Organization clarifies which revisions and Named References in a repo are
+intended for consumption and defines which technical controls are guaranteed in
+those contexts.
 
 <dt>Intended for<dd>
 
-Organizations that want strong guarantees and auditability of their change management processes.
+Organizations with many Named References or who otherwise need to document
+which controls were in place as Source Revisions were created.
 
 <dt>Benefits<dd>
 
-Provides information to policy enforcement tools to reduce the risk of tampering
-within the SCS's storage systems.
+A verifier can use this published data to ensure that a given Source Revision
+was created in the correct way by verifying the Source Provenance or VSA
+for all expected claims and properties.
 
 </dl>
 </section>
@@ -193,47 +201,34 @@ attestations.
 
 <td>✓<td>✓<td>✓<td>✓
 
-<tr id="protect-consumable-branches-and-tags"><td>Protect consumable branches and tags <a href="#protect-consumable-branches-and-tags">🔗</a><td>
+<tr id="configure-controls"><td>Configure the SCS to enforce intent <a href="#configure-controls">🔗</a><td>
 
-An organization producing source revisions MUST implement a change management
-process to ensure changes to source matches the organization's intent.
+The organization MUST configure access controls that govern access to sensitive
+operations on the Source Repository.
+These controls MUST be implemented using the SCS-provided
+[Identity Management capability](#identity-management).
 
-The organization MUST specify which branches and tags are covered by the process
-and are intended for use in its own applications or services or those of
-downstream consumers of the software.
+> For example, an organization may configure the SCS to assign users to a
+`maintainers` role and only allow users in `maintainers` to make updates to `main`.
 
-> For example, if an organization has branches 'main' and 'experimental' and it
-intends for 'main' to be protected then it MUST indicate to the SCS that 'main'
-should be protected. From that point forward revisions on 'main' will be
-eligible for Source Level 2+ while revisions made solely on 'experimental' will
-not.
+The SCS MUST be configured to produce a reliable [Change History](#history) 
+for all consumable Source Revisions.
 
-The organization MUST use the SCS provided
-[Identity Management capability](#identity-management) to configure the actors
-and roles that are allowed to perform sensitive actions on protected branches
-and tags.
+> For example, if the organization intends for all new Source Revisions on the
+`main` branch to be unit tested prior to acceptance, this MUST be explicitly
+configured in the SCS, not a social contract.
 
-> For example, an organization may configure the SCS to assign users to a `maintainers` role and only allow users in `maintainers` to make updates to `main`.
+If the SCS supports "tags" (or other Named References that do not support
+continuity enforcement mechanisms or change management processes), the SCS MUST
+be configured to prevent tags from being moved or deleted.
 
-The organization MUST specify what technical controls consumers can expect to be
-enforced for revisions in each protected branch and tag using the
-[Enforced change management process](#enforced-change-management-process)
-and it MUST document the meaning of those controls.
-
-> For example, an organization may claim that revisions on `main` passed unit
-tests before being accepted.  The organization could then configure the SCS to
-enforce this requirement and store corresponding [test result attestations] for
-all affected revisions.  They may then embed the `ORG_SOURCE_UNIT_TESTED`
-property in the [Source VSA](#source-verification-summary-attestation). Consumers
-would then expect that future revisions on `main` have been united tested and
-determine if that expectation has been met by looking for the
-`ORG_SOURCE_UNIT_TESTED` property in the VSAs and, if desired, consult the
-[test result attestations] as well.
-
-[test result attestations]: https://github.com/in-toto/attestation/blob/main/spec/predicates/test-result.md
+> For example, if a git tag `release1` is used to indicate a release revision
+with ID `abc123`, controls must be configured to prevent that tag from being
+updated to any other revision in the future.
+Evidence of these controls (and their continuity) will appear in the Source
+Provenance documents for revision `abc123`.
 
 <td><td>✓<td>✓<td>✓
-
 <tr id="safe-expunging-process"><td>Safe Expunging Process <a href="#safe-expunging-process">🔗</a><td>
 
 SCSs MAY allow the organization to expunge (remove) content from a repository
@@ -281,6 +276,26 @@ to be kept private to the extent possible. Organizations SHOULD prefer to make
 logs public if possible.
 
 <td><td>✓<td>✓<td>✓
+<tr id="intent"><td>Declare which revisions are consumable <a href="#intent">🔗</a><td>
+
+The organization MUST specify which Source Revisions are intended for use and
+how to find them.
+
+> For example, if an organization has branches `main` and `experimental` and it
+intends for Source Revisions on `main` to be used, then it MUST document that
+revisions on `main` can be consumed. From that point forward, revisions on
+`main` will be considered consumable while revisions solely on `experimental`
+will not.
+
+The organization MUST specify what technical controls consumers can expect to be
+enforced on consumable Source Revisions and it MUST document the meaning of
+those controls.
+
+> For example, if an organization requires Static Application Security Testing
+on consumable revisions and implements it via a required GitHub Actions workflow,
+it must indicate the name of this workflow and what it accomplishes.
+
+<td><td><td>✓<td>✓
 
 </table>
 
@@ -332,92 +347,55 @@ the SCS-issued [source provenance](#source-provenance) when issuing
 the VSAs.
 
 <td>✓<td>✓<td>✓<td>✓
-<tr id="branches"><td>Protected Branches <a href="#branches">🔗</a><td>
-
-The SCS MUST provide a mechanism for organizations to indicate which branches
-should be protected by SLSA Source Level 2+ requirements.
-
-E.g. The organization may configure the SCS to protect `main` and
-`refs/heads/releases/*`, but not `refs/heads/playground/*`.
 
-<td><td>✓<td>✓<td>✓
 <tr id="history"><td>History <a href="#history">🔗</a><td>
 
-Revisions are created by applying specific code changes (a "diff" in git) on
-top of earlier revisions of a branch. This sequence of changes, the revisions
-they produced, and how they were introduced into a branch constitute the history
-of that branch.
-
-The SCS MUST record the sequence of changes, the revisions they created,
-the actors that introduced them and the context they were introduced into.
+The SCS MUST record the sequence of all Source Revisions ever referenced by a
+branch.
+This MUST include metadata capturing when each change occurred and the actor who
+made it.
 
 The SCS MUST prevent tampering with these records on protected branches.
 
 > For example, in systems like GitHub or GitLab, this can be accomplished by
 enabling branch protection rules that prevent force pushes and branch deletions.
 
-<td><td>✓<td>✓<td>✓
-<tr id="enforced-change-management-process"><td>Enforced change management process <a href="#enforced-change-management-process">🔗</a><td>
+If revisions have their own ancestries in the VCS, the SCS MUST ensure that all
+new revisions added to a branch are descendants of the previous revision of the branch.
 
-The SCS MUST
-
--   Ensure organization-defined technical controls are enforced for changes made
-   to protected branches.
--   Allow organizations to specify
-   [additional properties](#additional-properties) to be included in the
-   [Source VSA](#source-verification-summary-attestation) when the corresponding controls are
-   enforced.
--   Allow organizations to distribute additional attestations related to their
-   technical controls to consumers authorized to access the corresponding source
-   revision.
--   Prevent organization-specified properties from beginning with any value
-   other than `ORG_SOURCE_` unless the SCS endorses the veracity of the
-   corresponding claims.
-
-> For example: enforcement of the organization-defined technical controls could
-be accomplished by the configuration of branch protection rules (e.g.
-[GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets),
-[GitLab](https://docs.gitlab.com/ee/user/project/repository/branches/protected.html))
-which require additional checks to 'pass' (e.g. unit tests, linters) or the
-application and verification of [gittuf](https://github.com/gittuf/gittuf)
-policies.
+> For example, if `main` currently points to revision `a`, it may only be
+moved to a new revision, `b`, if `b` has `a` somewhere in its revision ancestry.
 
 <td><td>✓<td>✓<td>✓
 <tr id="continuity"><td>Continuity <a href="#continuity">🔗</a><td>
 
-In a source control system, each new revision is built on top of prior
-revisions. Controls (e.g. [history](#history) or
-[enforced change management process](#enforced-change-management-process)) are
-only effective if they are used continuously from one revision to another. If
-a control is disabled for the introduction of a new revision and then re-enabled
-it is difficult to reason about the effectiveness of the control. 'Continuity' is
-the concept of ensuring controls are enforced continuously from the time they
-were introduced, leading to a higher degree of trust in the revisions produced
-after their introduction.
-
-On [protected branches](#branches) continuity for [history](#history) and
-[enforced change management process](#enforced-change-management-process)
-controls MUST be established and tracked from a specific revision forward
-through each new revision created. If there is a lapse in continuity for a
-specific control, continuity of that control MUST be re-established from a new
-revision.
-
-Continuity exceptions are allowed via the [safe expunging process](#safe-expunging-process).
-
-<td><td>✓<td>✓<td>✓
-<tr id="protected-tags"><td>Protected Tags <a href="#protected-tags">🔗</a><td>
+In a Source Control System, each new revision is built on top of prior
+revisions. Technical Controls (e.g. [history](#history) or
+[branch protections](#branches)) are only effective if they are used
+continuously from one revision to another. If a control is disabled for the
+introduction of a new revision and then re-enabled it is difficult to reason
+about the effectiveness of the control. 'Continuity' is the concept of ensuring
+technical controls are enforced continuously along a branch, leading to a higher
+degree of trust in the revisions produced after their introduction.
 
-If the SCS supports tags (or other non-branch revision trackers), additional
-care must be taken to prevent unintentional changes.
-Unlike branches, tags have no built-in continuity enforcement mechanisms or
-change management processes.
+On [protected branches](#branches), continuity for controls MUST be established
+and tracked from a specific revision forward through each new revision created.
+If there is a lapse in continuity for a specific control, continuity of that
+control MUST be re-established from a new revision.
 
-The SCS MUST provide a mechanism for organizations to indicate which tags should
-be protected by SLSA Source Level 2+ requirements.
+Continuity exceptions are allowed via the [safe expunging process](#safe-expunging-process).
 
-The SCS MUST prevent protected tags from being moved or deleted.
+> For example, the main branch currently points to revision `a` and a new
+technical control `t` is configured.
+The next revision on the `main` branch, `b` will be the first revision that can
+claim to have been protected by `t` and `b` is the first revision in the
+"continuity" of `t`.
+If in the future, `t` is disabled, any revisions added to `main` while `t` is
+disabled cannot claim to have been protected by `t` and the "continuity" of `t`
+will be reset.
 
 <td><td>✓<td>✓<td>✓
+
 <tr id="identity-management"><td>Identity Management <a href="#identity-management">🔗</a><td>
 
 The SCS MUST provide an identity management system or some other means of
@@ -429,7 +407,7 @@ branches, approval of changes).
 
 Depending on the SCS, identity management may be provided by source control
 services (e.g., GitHub, GitLab), implemented using cryptographic signatures
-(e.g., using gittuf to manage public keys for actors), or extend existing
+(e.g., using gittuf to manage public keys for actors), or extending existing
 authentication systems used by the organization (e.g., Active Directory, Okta,
 etc.).
 
@@ -439,6 +417,7 @@ Activities conducted on the SCS SHOULD be attributed to authenticated
 identities.
 
 <td><td>✓<td>✓<td>✓
+
 <tr id="source-provenance"><td>Source Provenance <a href="#source-provenance">🔗</a><td>
 
 [Source Provenance](#source-provenance-attestations) are attestations that
@@ -448,17 +427,62 @@ associated with the revision identifier delivered to consumers and are a
 statement of fact from the perspective of the SCS. The SCS MUST document the
 format and intent of all Source Provenance attestations it produces.
 
-At Source Level 3, Source Provenance MUST be created contemporaneously with the
-branch being updated to use that revision such that they provide a credible,
-auditable, record of changes.
+Source Provenance MUST be created contemporaneously with the branch being
+updated such that they provide a credible, auditable, record of changes.
 
-If a consumer is authorized to access a revision, they MUST be able to fetch the
-corresponding source provenance documents for that revision.
+If a consumer is authorized to access a revision, they MUST be able to access the
+corresponding Source Provenance documents for that revision.
 
 It is possible that an SCS can make no claims about a particular revision.
 
 > For example, this would happen if the revision was created on another SCS,
-or if the revision was not the result of an accepted change management process.
+on a unprotected branch (such as a `topic` branch), or if the revision was not
+the result of the expected change management process.
+
+The SCS MUST
+
+-   Allow organizations to provide
+   [organization-specified properties](#additional-properties) to be included in the
+   [Source VSA](#source-verification-summary-attestation) when the corresponding controls are
+   enforced.
+-   Allow organizations to distribute additional attestations related to their
+   technical controls to consumers authorized to access the corresponding Source
+   Revision.
+-   Prevent organization-specified properties from beginning with any value
+   other than `ORG_SOURCE_` unless the SCS endorses the veracity of the
+   corresponding claims.
+
+<td><td>✓<td>✓<td>✓
+<tr id="branches"><td>Protected Branches <a href="#branches">🔗</a><td>
+
+The SCS MUST provide any technical controls needed to enforce the organization's
+intent for the repo.
+
+The SCS MUST provide a mechanism for organizations to indicate which branches
+should be protected by technical controls.
+
+> For example, the organization may instruct the SCS to protect `main` and
+`refs/heads/releases/*`, but not `refs/heads/experimental/*` using branch
+protection rules (e.g. [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets),
+[GitLab](https://docs.gitlab.com/ee/user/project/repository/branches/protected.html))
+or via the application and verification of [gittuf](https://github.com/gittuf/gittuf)
+policies.
+
+<td><td><td>✓<td>✓
+<tr id="protected-tags"><td>Protected Tags <a href="#protected-tags">🔗</a><td>
+
+The SCS MUST provide any technical controls needed to enforce the organization's
+intent for the repo.
+
+The SCS MUST provide a mechanism for organizations to indicate which tags
+should be protected by technical controls.
+
+> For example, the organization may instruct the SCS to prevent the deletion of
+all `refs/tags/*` using tag
+protection rules (e.g. [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets),
+[GitLab](https://docs.gitlab.com/user/project/protected_tags/))
+or via the application and verification of [gittuf](https://github.com/gittuf/gittuf)
+policies.
 
 <td><td><td>✓<td>✓
 <tr id="two-party-review"><td>Two-party review <a href="#two-party-review">🔗</a><td>