fix: Apply fixes from PR 1319 and 1320 to draft (#1321)

Align the draft version of the spec with the latest v1.1-rc2.

Signed-off-by: Arnaud Le Hors <[email protected]>

Author: lehors

docs/spec/draft/about.md

@@ -1,6 +1,6 @@
 ---
 title: About SLSA
-description: With supply chain attacks on the rise, a shared vocabulary and universal framework is needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software.
+description: With supply chain attacks on the rise, a shared vocabulary and universal framework are needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software.
 ---
 
 This page is an introduction to SLSA and its concepts. If you're new
@@ -23,15 +23,15 @@ SLSA offers:
 
 ## Why SLSA is needed
 
-High profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply
+High-profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply
 chain integrity weaknesses that may go unnoticed, yet quickly become very
 public, disruptive, and costly in today's environment when exploited. They've
 also shown that there are inherent risks not just in code itself, but at
 multiple points in the complex process of getting that code into software
 systems—that is, in the **software supply chain**. Since these attacks are on
 the rise and show no sign of decreasing, a universal framework for hardening the
 software supply chain is needed, as affirmed by the U.S. Executive Order on
-Improving the Nation's Cybersecurity of May 12th 2021.
+Improving the Nation's Cybersecurity of May 12th, 2021.
 
 Security techniques for vulnerability detection and analysis of source code are
 essential, but are not enough on their own. Even after fuzzing or vulnerability

docs/spec/draft/attestation-model.md

@@ -42,11 +42,11 @@ consuming the attestation.
 
 ### First party
 
-Producers of first party code might consider the following questions:
+Producers of first-party code might consider the following questions:
 
 -   Will SLSA be used only within our organization?
 -   Is SLSA's primary use case to manage insider risk?
--   Are we developing entirely in a closed source environment?
+-   Are we developing entirely in a closed-source environment?
 
 If these are the main considerations, the organization can choose any format
 for internal use. To make an external claim of meeting a SLSA level, however,
@@ -56,10 +56,10 @@ attestations since it is easy to verify using the [Generic SLSA Verifier].
 
 ### Open source
 
-Producers of open source code might consider these questions:
+Producers of open-source code might consider these questions:
 
 -   Is SLSA's primary use case to convey trust in how your code was developed?
--   Do you develop software with standard open source licenses?
+-   Do you develop software with standard open-source licenses?
 -   Will the code be consumed by others?
 
 In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA
@@ -69,10 +69,10 @@ using the [Generic SLSA Verifier].
 
 ### Closed source, third party
 
-Producers of closed source code that is consumed by others might consider
+Producers of closed-source code that is consumed by others might consider
 the following questions:
 
--   Is my code produced for the sole purpose of specific third party consumers?
+-   Is my code produced for the sole purpose of specific third-party consumers?
 -   Is SLSA's primary use case to create trust in our organization or to comply with
 audits and legal requirements?
 

docs/spec/draft/distributing-provenance.md

@@ -7,7 +7,7 @@ In order to make provenance for artifacts available after generation
 for verification, SLSA requires the distribution and verification of provenance
 metadata in the form of SLSA attestations.
 
-This document provides specifications for distributing provenance, and the
+This document provides specifications for distributing provenance and the
 relationship between build artifacts and provenance (build attestations). It is
 primarily concerned with artifacts for ecosystems that distribute build
 artifacts, but some attention is also paid to ecosystems that distribute
@@ -29,15 +29,15 @@ interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
 The [package ecosystem]'s maintainers are responsible for reliably
 redistributing artifacts and provenance, making the producers' expectations
 available to consumers, and providing tools to enable safe artifact consumption
-(e.g. whether an artifact meets its producer's expectations).
+(e.g., whether an artifact meets its producer's expectations).
 
 ## Relationship between releases and attestations
 
 Attestations SHOULD be bound to artifacts, not releases.
 
 A single "release" of a project, package, or library might include multiple
 artifacts. These artifacts result from builds on different platforms,
-architectures or environments. The builds need not happen at roughly the same
+architectures, or environments. The builds need not happen at roughly the same
 point in time and might even span multiple days.
 
 It is often difficult or impossible to determine when a release is 'finished'
@@ -57,7 +57,7 @@ Package ecosystems SHOULD support a one-to-many relationship from build
 artifacts to attestations to ensure that anyone is free to produce and publish
 any attestation they might need. However, while there are lots of possible
 attestations that can have a relationship to a given artifact, in this context
-SLSA is primarily concerned with build attestations, i.e. provenance, and as
+SLSA is primarily concerned with build attestations, i.e., provenance, and as
 such, this specification only considers build attestations, produced by the
 same maintainers as the artifacts themselves.
 
@@ -71,15 +71,15 @@ support the publication of arbitrary attestations by third parties.
 
 As a result, this provenance SHOULD accompany the artifact at publish time, and
 package ecosystems SHOULD provide a way to map a given artifact to its
-corresponding attestations. The mappings can be either implicit (e.g. require a
+corresponding attestations. The mappings can be either implicit (e.g., require a
 custom filename schema that uniquely identifies the provenance over other
-attestation types) or explicit (e.g. it could happen as a de-facto standard
+attestation types) or explicit (e.g., it could happen as a de-facto standard
 based on where the attestation is published).
 
 The provenance SHOULD have a filename that is directly related to the build
 artifact filename. For example, for an artifact `<filename>.<extension>`, the
 attestation is `<filename>.attestation` or some similar extension (for example
-[in-toto](https://in-toto.io/) recommends `<filename>.intoto.jsonl`.)
+[in-toto](https://in-toto.io/) recommends `<filename>.intoto.jsonl`).
 
 ## Where attestations are published
 
@@ -95,7 +95,7 @@ one place, and SHOULD publish attestations in more than one place:
     producers SHOULD include provenance as part of such releases. This option
     has the benefit of requiring no changes to the package registry to support
     provenance formats, but has the disadvantage of putting the source
-    repository hosting providing in the critical path for installers that want to
+    repository hosting provider in the critical path for installers that want to
     verify policy at build-time.
 -   **Publish attestations alongside the artifact in the package registry**:
     Many software repositories already support some variety of publishing 1:1
@@ -153,12 +153,12 @@ the other requirements.
 ## Considerations for source-based ecosystems
 
 Some ecosystems have support for installing directly from source repositories
-(an option for Python/`pip`, Go, etc). In these cases, there is no need to
+(an option for Python/`pip`, Go, etc.). In these cases, there is no need to
 publish or verify provenance because there is no "build" step that translates
 between a source repository and an artifact that is being installed.
 
 However, for ecosystems that install from source repositories _via_ some
-intermediary (e.g. [Homebrew installing from GitHub release artifacts generated
+intermediary (e.g., [Homebrew installing from GitHub release artifacts generated
 from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go
 installing through the Go module proxy](https://proxy.golang.org/)), these
 ecosystems distribute "source archives" that are not the bit-for-bit identical

docs/spec/draft/future-directions.md

@@ -63,4 +63,4 @@ The Source track will be scoped to revisions of a single repository.
 The intent of each revision is determined by the [software producer](terminology.md#roles) who is also responsible for declaring which Source level should apply and administering technical controls to enforce that level.
 
 The primary purpose of the Source track will be to enable verification that the creation of a revision followed the producer's intended process.
-Consumers will be able to examine source provenance attestations to determine if a revision meet their requirements.
+Consumers will be able to examine source provenance attestations to determine if a revision meets their requirements.

docs/spec/draft/levels.md

@@ -31,7 +31,7 @@ tracks without invalidating previous levels.
 hermeticity or completeness of provenance -->
 
 > Note: The [previous version] of the specification used a single unnamed track,
-> SLSA 1–4. For version 1.0 the Source aspects were removed to focus on the
+> SLSA 1–4. For version 1.0, the Source aspects were removed to focus on the
 > Build track. A Source track may be added in [future versions].
 
 ## Build track
@@ -223,7 +223,7 @@ All of [Build L2], plus:
     credentials, or other tenants.
 
 -   Greatly reduces the impact of compromised package upload credentials by
-    requiring attacker to perform a difficult exploit of the build process.
+    requiring the attacker to perform a difficult exploit of the build process.
 
 -   Provides strong confidence that the package was built from the official
     source and build process.

docs/spec/draft/principles.md

@@ -15,15 +15,15 @@ levels into separate tracks to recognize progress in unrelated security areas.
 **Reasoning:** Levels simplify how to think about security by boiling a complex
 topic into an easy-to-understand number. It is clear that level N is better than
 level N-1, even to someone with passing familiarity. This provides a convenient
-way to describe current security state as well as a natural path to improvement.
+way to describe the current security state as well as a natural path to improvement.
 
 Guidelines:
 
 -   **Define levels in terms of concrete security outcomes.** Each level should
     have clear and meaningful security value, such as stopping a particular
     class of threats. Levels should represent security milestones, not just
     incremental progress. Give each level an easy-to-remember mnemonic, such as
-    "Provenance exists".
+    "Provenance exists."
 
 -   **Balance level granularity.** Too many levels makes SLSA hard to understand
     and remember; too few makes each level hard to achieve. Collapse levels
@@ -53,8 +53,8 @@ supply chain. Verifying that an artifact is produced by a trusted platform,
 though, is easy to automate.
 
 To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited
-numbers of platforms and then automate verification of the artifacts produced by those platforms.
-The attack surface and work to establish trust does not scale with the number of artifacts produced,
+number of platforms and then automate verification of the artifacts produced by those platforms.
+The attack surface and work to establish trust do not scale with the number of artifacts produced,
 as happens when artifacts each use a different trusted platform.
 
 **Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant
@@ -67,7 +67,7 @@ platform to ensure that it meets the SLSA Build Track requirements. Following th
 analysis, the public keys used by the build platform to sign provenance are
 "trusted" up to the given SLSA level. Downstream platforms verify the provenance
 signed by the public key to automatically determine that an artifact meets the
-SLSA level.  
+SLSA level.
 
 ### Corollary: Minimize the number of trusted platforms
 
@@ -122,7 +122,7 @@ While organizations that implement SLSA may choose otherwise, SLSA itself does n
 or encourage, participants to be mapped to their legal identities.
 
 **Nothing in this specification should be taken to mean that SLSA requires participants to
-to reveal their legal identity.**
+reveal their legal identity.**
 
 **Reasoning**: SLSA uses identities for multiple purposes: as a trust anchor for attestations
 (i.e. who or what is making this claim and do I trust it to do so) or for attributing actions
@@ -132,7 +132,7 @@ stacks implementing the SLSA standards.
 When identities are strongly authenticated and used consistently they can often be leveraged
 for both of these purposes without requiring them to be mapped to legal identities.
 This reflects how identities are often used in open source where legal name means much less
-to projects than the history and behavior of a given handle over time does. Meanwhile some
+to projects than the history and behavior of a given handle over time does. Meanwhile, some
 organizations may choose to levy additional requirements on identities. They are free to do
 so, but SLSA itself does not require it.
 

docs/spec/draft/provenance.md

@@ -5,7 +5,7 @@ layout: standard
 ---
 To trace software back to the source and define the moving parts in a complex
 supply chain, provenance needs to be there from the very beginning. It's the
-verifiable information about software artifacts describing where, when and how
+verifiable information about software artifacts describing where, when, and how
 something was produced. For higher SLSA levels and more resilient integrity
 guarantees, provenance requirements are stricter and need a deeper, more
 technical understanding of the predicate.
@@ -129,7 +129,7 @@ disagreement with the text description, the text is authoritative.*
 
 Link: [provenance.proto](schema/provenance.proto)
 
-*NOTE: This protobuf definition prioritises being a human-readable summary
+*NOTE: This protobuf definition prioritizes being a human-readable summary
 of the schema for readers of the specification. A version of the protobuf
 definition useful for code generation is maintained in the
 [in-toto attestation] repository.*
@@ -191,7 +191,7 @@ https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1
 
 The parameters that are under external control, such as those set by a user or
 tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that
-that there is no additional mechanism for an external party to influence the
+there is no additional mechanism for an external party to influence the
 build. (At lower SLSA Build levels, the completeness MAY be best effort.)
 
 The build platform SHOULD be designed to minimize the size and complexity of

docs/spec/draft/terminology.md

@@ -289,24 +289,24 @@ additions are welcome!
 Notes:
 
 -   Go uses a significantly different distribution model than other ecosystems.
-    In go, the package name is a source repository URL. While clients can fetch
+    In Go, the package name is a source repository URL. While clients can fetch
     directly from that URL---in which case there is no "package" or
     "registry"---they usually fetch a zip file from a *module proxy*. The module
     proxy acts as both a builder (by constructing the package artifact from
     source) and a registry (by mapping package name to package artifact). People
-    trust the module proxy because builds are independently reproducible and a
+    trust the module proxy because builds are independently reproducible, and a
     *checksum database* guarantees that all clients receive the same artifact
     for a given URL.
 
 ### Verification model
 
 Verification in SLSA is performed in two ways. Firstly, the build platform is
 certified to ensure conformance with the requirements at the level claimed by
-the build platform. This certification should happen on a recurring cadence with
+the build platform. This certification should happen on a recurring cadence, with
 the outcomes published by the platform operator for their users to review and
 make informed decisions about which builders to trust.
 
-Secondly, artifacts are verified to ensure they meet the producer defined
+Secondly, artifacts are verified to ensure they meet the producer-defined
 expectations of where the package source code was retrieved from and on what
 build platform the package was built.
 

docs/spec/draft/use-cases.md

@@ -40,7 +40,7 @@ Example ways an organization might use SLSA internally:
 -   A small company or team uses SLSA to ensure that the code being deployed to
     production in binary form is the same one that was tested and reviewed in
     source form.
--   A large company uses SLSA to require two person review for every production
+-   A large company uses SLSA to require two-person review for every production
     change, scalably across hundreds or thousands of employees/teams.
 -   An open source project uses SLSA to ensure that compromised credentials
     cannot be abused to release an unofficial package to a package registry.
@@ -96,16 +96,16 @@ Reducing risk from consuming vendor provided software and services
 </div>
 <div class="md:w-2/3">
 
-Finally, SLSA can be used to reduce risk for consumers of vendor provided
+Finally, SLSA can be used to reduce risk for consumers of vendor-provided
 software and services. Unlike open source, there is no canonical source
-repository to map to, so instead the focus is on trustworthiness of claims made
+repository to map to, so instead the focus is on the trustworthiness of claims made
 by the vendor.
 
-Example ways a consumer might use SLSA for vendor provided software:
+Example ways a consumer might use SLSA for vendor-provided software:
 
 -   Prefer vendors who make SLSA claims and back them up with credible evidence.
 -   Require a vendor to implement SLSA as part of a contract.
--   Require a vendor to be SLSA certified from a trusted third-party auditor.
+-   Require a vendor to be SLSA certified by a trusted third-party auditor.
 
 </div>
 </div>