adds top-level slsa-attestations page and updates links

Author: paulsavoie

docs/_data/menus/documentation.yml

@@ -62,9 +62,12 @@
 
 - text: Origin Verification
   path: origin-verification
+
+- text: SLSA Attestations
+  path: slsa-attestations
   items:
-    - text: SLSA Attestations
-      path: slsa-attestations
+    - text: Definitions
+      path: definitions
 
 - separator: true
 

…origin-verification/slsa-attestations.md docs/slsa-attestations/definitions.mddocs/origin-verification/slsa-attestations.md renamed to docs/slsa-attestations/definitions.md docs/origin-verification/slsa-attestations.md renamed to docs/slsa-attestations/definitions.md

@@ -1,39 +1,13 @@
 ---
-header: SLSA Build Levels
+header: Definitions
 layout: resources
 toc: true
 show_toc: 3
 description: Describes SignPath SLSA build levels
 ---
 
-## SLSA attestations by SignPath
-
 This page contains the definitions for SignPath build types and builders for SLSA provenance files.
 
-SignPath creates SLSA attestation in three distinct steps:
-
-<!-- TODO: product names should be explained somewhere -->
-1. SignPath Pipeline Integrity gathers and verifies relevant information from a supported _origin_ CI/CD system 
-2. SignPath DeepSign creates SLSA provenance build based on that information (along with other code signing operations)
-3. SignPath Attest signs the provenance 
-
-{:.panel.info} 
-> **Attestation trust explained**
->
-> In order to be able to trust an attestation issued by SignPath, clients need to:
-> 
-> * Verify the signature on the attestation: it must be signed by an official SignPath certificate
-> * Trust SignPath to evaluate the attested properties 
->   * SignPath evaluates and continuously monitors the services and APIs it uses from supported CI/CD systems. We do extensive research based on official vendor documentation and perform our own tests to ensure that attested properties reflect the actual configuration and build execution. 
-> * Trust all hosted CI/CD system supported by SignPath or verify that the _origin_ system is one that you trust.
->   * SignPath cannot guarantee that the CI/CD system is actually operated in a safe way and safe from manipulation.
-> 
-> Clients do _not_ need to trust the publisher for these security properties, as they are evaluated on the _control plane_ without relying on the provider's configuration. However, SignPath can only make technical evaluations and enforce technical policies. The quality of the source code (including build scripts) and code reviews is still up to the publisher.
-> 
-> SignPath cannot attest builds from customer-operated CI/CD systems. However, SignPath provides features for customers to self-attest builds from centrally operated CI/CD systems for individual teams.
-
-For details how to create SLSA attestations with SignPath, see the respective [artifact configuration directives](/artifact-configuration/reference#create-provenance-file).
-
 ## Build type and builder identifier
 
 SignPath identifies build types and builders using the following URIs:
@@ -178,3 +152,7 @@ Guarantee: If the provenance is signed by SignPath, the build was executed on a
 | GitHub Actions | The build was executed on a GitHub-hosted runner which does not provide the ability to remotely connect, unless explicitly specified in the build definition (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network)) 
 
 <!--| GitLab CI/CD   | The build was executed on a GitLab-hosted runner wich does not allow remote connections (see [the official documentation](https://docs.gitlab.com/ci/runners/hosted_runners/))-->
+
+## The `resource-uri` field
+
+A Verification Summary Attestation (VSA) document defines a `resource-uri` field, with the intention to communicate an URI where the software artifact can be retrieved. This information is rarely known ahead of time for all artifacts that are published outside an e.g. app store or package manager repository. SignPath instead provides, in accordance with the SLSA specifications, information identifying the software publisher.

docs/slsa-attestations/index.md

@@ -0,0 +1,64 @@
+---
+header: SLSA Attestations
+layout: resources
+toc: true
+show_toc: 3
+description: SLSA Attestations in SignPath
+---
+
+## Overview
+
+The [SLSA framework](https://slsa.dev) was originally introduced by Google in 2021 and is now maintained under the Open Source Security Foundation (OpenSSF). It defines a set of incremental security properties for build systems - a maturity model with levels that describe increasing degrees of assurance.
+
+### Key concepts
+
+- A **Provenance** is a machine- and human-readable file describing *where*, *when*, and *how* a software artifact was produced - typically including the source code repository and revision, the build definition, and information about the build system.
+- An **Attestation** is a digitally signed provenance.
+- A **Verification Summary Attestation (VSA)** confirms that an artifact was built compliant with the attested SLSA build level. It omits technical details about the build process and can therefore be more easily shared and validated.
+
+### Build Levels
+
+SLSA defines [three incremental levels](https://slsa.dev/spec/v1.2/build-track-basics) for build security:
+
+#### Build L1 - Provenance exists
+
+A provenance document exists, though its contents are not yet considered fully trustworthy or complete. 
+
+
+#### Build L2 - Hosted build platform
+
+The build ran on a hosted build system (not a developer's local machine), the provenance was generated by a trusted system (such as SignPath), and it is signed - making it a proper attestation.
+
+#### Build L3 - Hardened builds
+
+The build ran in an isolated, ephemeral environment - free from caches, remote sessions, and interference from other builds. A fresh environment is provisioned for every build.
+
+## SLSA attestations by SignPath
+
+SignPath creates SLSA attestation in three distinct steps:
+
+<!-- TODO: product names should be explained somewhere -->
+1. SignPath Pipeline Integrity gathers and verifies relevant information from a supported _origin_ CI/CD system 
+2. SignPath DeepSign creates SLSA provenance build based on that information (along with other code signing operations)
+3. SignPath Attest signs the provenance 
+
+For details see the respective [artifact configuration directives](/artifact-configuration/reference#create-provenance-file).
+
+{:.panel.info} 
+> **Attestation trust explained**
+>
+> In order to be able to trust an attestation issued by SignPath, clients need to:
+> 
+> * Verify the signature on the attestation: it must be signed by an official SignPath certificate
+> * Trust SignPath to evaluate the attested properties 
+>   * SignPath evaluates and continuously monitors the services and APIs it uses from supported CI/CD systems. We do extensive research based on official vendor documentation and perform our own tests to ensure that attested properties reflect the actual configuration and build execution. 
+> * Trust all hosted CI/CD system supported by SignPath or verify that the _origin_ system is one that you trust.
+>   * SignPath cannot guarantee that the CI/CD system is actually operated in a safe way and safe from manipulation.
+> 
+> Clients do _not_ need to trust the publisher for these security properties, as they are evaluated on the _control plane_ without relying on the provider's configuration. However, SignPath can only make technical evaluations and enforce technical policies. The quality of the source code (including build scripts) and code reviews is still up to the publisher.
+> 
+> SignPath cannot attest builds from customer-operated CI/CD systems. However, SignPath provides features for customers to self-attest builds from centrally operated CI/CD systems for individual teams.
+>
+> A step-by-step guide on how to validate a Verification Summary Attestation is [provided here](/artifact-configuration/reference#slsa-vsa-verification).
+
+Specific information about each supported build system and the underlying guarantees can be found in the [SLSA Attestation definitions](/slsa-attestations/definitions).

docs/specs/slsa/builder/azure-devops/build-l1/slsa-1.1/v1.md

@@ -1,3 +1,3 @@
 ---
-redirect_to: /origin-verification/slsa-attestations
+redirect_to: /slsa-attestations/definitions
 ---

docs/specs/slsa/builder/azure-devops/build-l2/slsa-1.1/v1.md

@@ -1,3 +1,3 @@
 ---
-redirect_to: /origin-verification/slsa-attestations
+redirect_to: /slsa-attestations/definitions
 ---

docs/specs/slsa/builder/azure-devops/build-l3/slsa-1.1/v1.md

@@ -1,3 +1,3 @@
 ---
-redirect_to: /origin-verification/slsa-attestations
+redirect_to: /slsa-attestations/definitions
 ---

docs/specs/slsa/builder/github/build-l1/slsa-1.1/v1.md

@@ -1,3 +1,3 @@
 ---
-redirect_to: /origin-verification/slsa-attestations
+redirect_to: /slsa-attestations/definitions
 ---

docs/specs/slsa/builder/github/build-l2/slsa-1.1/v1.md

@@ -1,3 +1,3 @@
 ---
-redirect_to: /origin-verification/slsa-attestations
+redirect_to: /slsa-attestations/definitions
 ---

docs/specs/slsa/builder/github/build-l3/slsa-1.1/v1.md

@@ -1,3 +1,3 @@
 ---
-redirect_to: /origin-verification/slsa-attestations
+redirect_to: /slsa-attestations/definitions
 ---

docs/specs/slsa/builder/gitlab/build-l1/slsa-1.1/v1.md

@@ -1,3 +1,3 @@
 ---
-redirect_to: /origin-verification/slsa-attestations
+redirect_to: /slsa-attestations/definitions
 ---