Merge pull request #503 from MarkLodato/v1-expectations

SLSA v1.0: shift emphasis to expectations + verification in levels.md

docs/spec/v1.0/levels.md

@@ -73,7 +73,7 @@ tracks without invalidating previous levels.
 | Track/Level | Requirements | Benefits |
 | ----------- | ------------ | -------- |
 | [Build L0]  | (none)       | (n/a)    |
-| [Build L1]  | Attestation showing how the package was built | Documentation, inventorying |
+| [Build L1]  | Attestation showing that the package was built as expected | Documentation, mistake prevention, inventorying |
 | [Build L2]  | Signed attestation, generated by a hosted build service | Reduced attack surface, weak tamper protection |
 | [Build L3]  | Hardened build service | Strong tamper protection |
 | [Build L4]  | (not yet defined) | |
@@ -94,13 +94,17 @@ from the correct sources, without unauthorized modification or influence.
 
 Summary of the build track:
 
+-   Set **project-specific expectations** for how the package should be built.
 -   Generate a **provenance attestation** automatically during each build.
 -   Build on **hardened services** that have been manually audited.
+-   **Automatically verify** that each package's provenance meets expectations
+    before allowing its publication and/or consumption.
 
 Exactly how this is implemented is up to the packaging ecosystem (for open
-source) or organization (for closed source), including: what provenance format
-is accepted, whether reproducible builds are used, and how provenance is
-distributed. Guidelines for implementers can be found in the
+source) or organization (for closed source), including: means of defining
+expectations, what provenance format is accepted, whether reproducible builds
+are used, how provenance is distributed, when verification happens, and what
+happens on failure. Guidelines for implementers can be found in the
 [requirements](requirements.md).
 
 <section id="build-l0">
@@ -134,8 +138,8 @@ n/a
 <dl class="as-table">
 <dt>Summary<dd>
 
-Package has a provenance attestation showing how it was built, but the
-provenance is trivial to forge.
+Package has a provenance attestation showing that it was built as expected, but
+the provenance is trivial to forge.
 
 <dt>Intended for<dd>
 
@@ -144,20 +148,26 @@ SLSA---other than tamper protection---without changing their build workflows.
 
 <dt>Requirements<dd>
 
--   Up front, the package maintainer defines some sort of "build script" that
-    automates how the package is supposed to be built.
+-   Up front, the package maintainer defines how the package is *expected* to be
+    built, including the canonical source repository and build command.
 
 -   On each build, the release process automatically generates and distributes a
     [provenance attestation] describing how the artifact was *actually* built,
     including: who built the package (person or system), what process/command
     was used, and what the input artifacts were.
 
+-   Downstream tooling automatically verifies that the artifact's provenance
+    exists and matches the expectation.
+
 <dt>Benefits<dd>
 
 -   Makes it easier for both maintainers and consumers to debug, patch, rebuild,
     and/or analyze the software by knowing its precise source version and build
     process.
 
+-   Prevents mistakes during the release process, such as building from a client
+    with local modifications.
+
 -   Aids organizations in creating an inventory of software and build systems
     used across a variety of teams.
 
@@ -168,6 +178,10 @@ SLSA---other than tamper protection---without changing their build workflows.
 
 </dl>
 
+> **TODO:** Add "Scripted Build" if decided in
+> [#498](https://github.com/slsa-framework/slsa/issues/498): "Build process is
+> fully scripted/automated, with no manual steps."
+
 </section>
 <section id="build-l2">
 
@@ -192,6 +206,9 @@ All of [Build L1], plus:
 -   Builds run on a hosted build service that generates and signs the
     provenance itself, outside the control of the users of the build service.
 
+-   Downstream verification of provenance includes authenticating the
+    provenance.
+
 <dt>Benefits<dd>
 
 All of [Build L1], plus: