diff --git a/docs/spec/v1.0/levels.md b/docs/spec/v1.0/levels.md index 6c4c6e898..3fd33f52f 100644 --- a/docs/spec/v1.0/levels.md +++ b/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).
@@ -134,8 +138,8 @@ n/a
Summary
-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.
Intended for
@@ -144,20 +148,26 @@ SLSA---other than tamper protection---without changing their build workflows.
Requirements
-- 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. +
Benefits
- 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.
+> **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." +
@@ -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. +
Benefits
All of [Build L1], plus: