feat(doc): #901 provenance reqs

.github/workflows/scorecards-analysis.yaml

@@ -6,7 +6,7 @@ on:
     # Weekly on Saturdays.
     - cron: 30 1 * * 6
   push:
-    branches: [main, master]
+    branches: [main]
 
 permissions: read-all
 
@@ -27,21 +27,21 @@ jobs:
           persist-credentials: false
 
       - name: Run analysis
-        uses: ossf/scorecard-action@c1aec4ac820532bab364f02a81873c555a0ba3a1  # v1.0.4
+        uses: ossf/scorecard-action@c1aec4ac820532bab364f02a81873c555a0ba3a1 # v1.0.4
         with:
           results_file: results.sarif
           results_format: sarif
           repo_token: ${{ secrets.SCORECARD_READ_TOKEN }}
           publish_results: true
 
       - name: Upload artifact
-        uses: actions/upload-artifact@82c141cc518b40d92cc801eee768e7aafc9c2fa2  # v2.3.1
+        uses: actions/upload-artifact@82c141cc518b40d92cc801eee768e7aafc9c2fa2 # v2.3.1
         with:
           name: SARIF file
           path: results.sarif
           retention-days: 5
 
       - name: Upload to code-scanning
-        uses: github/codeql-action/upload-sarif@5f532563584d71fdef14ee64d17bafb34f751ce5  # v1.0.26
+        uses: github/codeql-action/upload-sarif@5f532563584d71fdef14ee64d17bafb34f751ce5 # v1.0.26
         with:
           sarif_file: results.sarif

docs/src/security/slsa.md

@@ -17,23 +17,28 @@ Our current SLSA level is 2.
 The following is a detail of the levels achieved
 on each of the requirements:
 
-| Requirement                    | Level |
-| :----------------------------- | :---: |
-| Source - Version Controlled    |   4   |
-| Source - Verified History      |   4   |
-| Source - Retained Indefinitely |   4   |
-| Source - Two Person Reviewed   |   3   |
-| Build - Scripted Build         |   4   |
-| Build - Build Service          |   4   |
-| Build - Build As Code          |   4   |
-| Build - Ephemeral Environment  |   4   |
-| Build - Isolated               |   2   |
-| Build - Parameter-less         |   4   |
-| Build - Hermetic               |   4   |
-| Build - Reproducible           |   4   |
-| Common - Security              |   4   |
-| Common - Access                |   4   |
-| Common - Superusers            |   3   |
+| Requirement                        | Level |
+| :--------------------------------- | :---: |
+| Source - Version Controlled        |   4   |
+| Source - Verified History          |   4   |
+| Source - Retained Indefinitely     |   4   |
+| Source - Two Person Reviewed       |   3   |
+| Build - Scripted Build             |   4   |
+| Build - Build Service              |   4   |
+| Build - Build As Code              |   4   |
+| Build - Ephemeral Environment      |   4   |
+| Build - Isolated                   |   2   |
+| Build - Parameter-less             |   4   |
+| Build - Hermetic                   |   4   |
+| Build - Reproducible               |   4   |
+| Provenance - Available             |   4   |
+| Provenance - Authenticated         |   4   |
+| Provenance - Service Generated     |   4   |
+| Provenance - Non-Falsifiable       |   4   |
+| Provenance - Dependencies Complete |   4   |
+| Common - Security                  |   4   |
+| Common - Access                    |   4   |
+| Common - Superusers                |   3   |
 
 For clarity,
 this is how SLSA definitions map into our infrastructure:
@@ -263,6 +268,78 @@ All of our build scripts are intended to be reproducible.
 The reproducibility guarantees of our build scripts
 are that of the [Nix package manager][nix].
 
+## Provenance Requirements
+
+### Available
+
+Provenance is produced by Makes,
+and exposed by the build service
+as a JSON document
+together with the artifacts produced by the build.
+
+Only builds that produce artifacts generate provenance,
+because if a build does not produce artifacts,
+then there wouldn't be something to verify the provenance of.
+
+### Authenticated
+
+The authenticity of the provenance
+comes from the fact
+that it can be downloaded
+from the build service itself,
+and therefore the authenticity claim
+is as strong as the _Build and Source Requirements_ are secure.
+
+The integrity of the provenance
+is displayed in the logs
+and generated by Makes.
+
+### Service Generated
+
+The data in the provenance
+is exposed by the build service,
+and is generated by Makes.
+
+Regular users of the service
+are not able to inject
+or alter the contents
+because a build is fully determined
+and automated by its configuration,
+and the configuration comes directly from the source.
+
+### Non-Falsifiable
+
+The provenance
+cannot be falsified by the build service's users:
+
+- There is no secret material
+  to demonstrate the non-falsifiable nature of the provenance
+  (see _Provenance - Authenticated_).
+- Even if such secret material existed,
+  builds are run in an hermetic environment,
+  and therefore they wouldn't be available to the build steps
+  (see _Build - Hermetic_).
+- Every field in the provenance is generated
+  by the build service in a trusted control plane,
+  which is fully defined by the build configuration,
+  which comes directly from the Source,
+  and therefore is as secure as the Source is
+  (see _Source - Verified History_).
+
+### Dependencies Complete
+
+The provenance contains all of dependencies
+that were available while running the build steps.
+
+This is guaranteed by the fact
+that builds are hermetic
+(see _Build - Hermetic_).
+So for a build to succeed,
+all of its dependencies must be declared,
+and therefore the build tool (Makes and Nix)
+who fetched them at build time,
+have strong knowledge of their existence.
+
 ## Common Requirements
 
 ### Security