📖doc tweaks (slsa-framework#199)

* 📖 add missing image used in SPECIFICATION.md

This was omitted when docs were copied from the slsa-github-generator-go
repository.

Signed-off-by: Joshua Lock <[email protected]>

* 📖 move verification steps to top-level README

* Move verification steps to top-level README, these are not ecosystem
  specific
* Make 'Provenance format' a child of 'Technical design'
* Make 'Generation of provenance' a second-level section

Signed-off-by: Joshua Lock <[email protected]>

* 📖 update README to clarify which requirements are met

Emphasise that the generator and builders can be used to meet the Build
and Provenance requirements only, Source requirements must be met with
other tools.

Signed-off-by: Joshua Lock <[email protected]>

Author: joshuagl

README.md

@@ -1,32 +1,53 @@
 # Generation of SLSA3+ provenance for native GitHub projects
 
-This repository contains the implementation for generating non-forgeable [SLSA provenance](https://slsa.dev/) that meets the requirement for the [SLSA level 3 and above](https://slsa.dev/spec/v0.1/levels). The SLSA generation makes use of a [Github Actions reusable workflow](https://docs.github.com/en/actions/using-workflows/reusing-workflows).
+This repository contains tools for generating non-forgeable [SLSA provenance](https://slsa.dev/) on GitHub that meets the [build](https://slsa.dev/spec/v0.1/requirements#build-requirements) and [provenance](https://slsa.dev/spec/v0.1/requirements#provenance-requirements) requirements for [SLSA level 3 and above](https://slsa.dev/spec/v0.1/levels).
 
-This repository contains the code, examples and technical design for the blog post on [Non forgeable SLSA provenance using GitHub workflows](https://security.googleblog.com/2022/04/improving-software-supply-chain.html).
+Use of the provided [Github Actions reusable workflow](https://docs.github.com/en/actions/using-workflows/reusing-workflows)s only is not sufficient to meet all of the requirements at SLSA level 3. Specifically, the [source requirements](https://slsa.dev/spec/v0.1/requirements#source-requirements) are not covered by these workflows and must be handled explicitly to meet all requirements at SLSA level 3+.
+
+This repository contains the code, examples and technical design for system described in the blog post on [Non forgeable SLSA provenance using GitHub workflows](https://security.googleblog.com/2022/04/improving-software-supply-chain.html).
 
 ---
 
-- [Golang projects](#golang-projects)
-- [Other projects](#other-projects)
-- [Provenance format](#provenance-format)
+- [Generation of provenance](#generation-of-provenance)
+  - [Golang projects](#golang-projects)
+  - [Other projects](#other-projects)
+- [Verification of provenance](#verification-of-provenance)
+  - [Installation](#installation)
+  - [Inputs](#inputs)
+  - [Command line examples](#command-line-examples)
 - [Technical design](#technical-design)
   - [Blog post](#blog-post)
   - [Specifications](#specifications)
+  - [Provenance format](#provenance-format)
 
 ---
 
-## Golang projects
+## Generation of provenance
+
+### Golang projects
 
 To generate SLSA provenance for your Golang project, follow [internal/builders/go/README.md](internal/builders/go/README.md).
 
-## Other projects
+### Other projects
 
 To generate SLSA provenance for other programming languages, follow [internal/builders/generic/README.md](internal/builders/generic/README.md).
 This is a pre-release only and we will have the official release in July 2022.
 
-## Provenance format
+## Verification of provenance
 
-The format of the provenance is available in [PROVENANCE_FORMAT.md](./PROVENANCE_FORMAT.md).
+To verify the provenance, use the [github.com/slsa-framework/slsa-verifier](https://github.com/slsa-framework/slsa-verifier) project.
+
+### Installation
+
+To install the verifier, see [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation).
+
+### Inputs
+
+The inputs of the verifier are described in [slsa-framework/slsa-verifier#available-options](https://github.com/slsa-framework/slsa-verifier#available-options).
+
+### Command line examples
+
+A command line example is provided in [slsa-framework/slsa-verifier#example](https://github.com/slsa-framework/slsa-verifier#example).
 
 ## Technical design
 
@@ -38,5 +59,7 @@ Find our blog post series [here](https://security.googleblog.com/2022/04/improvi
 
 For a more in-depth technical dive, read the [SPECIFICATIONS.md](./SPECIFICATIONS.md).
 
+### Provenance format
 
+The format of the provenance is available in [PROVENANCE_FORMAT.md](./PROVENANCE_FORMAT.md).
 

images/cert.svg

@@ -14,12 +14,6 @@ This document explains how to use the builder for Golang projects.
 - [Example provenance](#example-provenance)
 - [BuildConfig format](#buildconfig-format)
 
-[Verification of provenance](#verification-of-provenance)
-
-- [Installation](#installation)
-- [Inputs](#inputs)
-- [Command line examples](#command-line-examples)
-
 ---
 
 ## Generation
@@ -277,19 +271,3 @@ The `BuildConfig` contains the following fields:
 ```json
   "workingDir": "/home/runner/work/ianlewis/actions-test"
 ```
-
-## Verification of provenance
-
-To verify the provenance, use the [github.com/slsa-framework/slsa-verifier](https://github.com/slsa-framework/slsa-verifier) project.
-
-### Installation
-
-To install the verifier, see [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation).
-
-### Inputs
-
-The inputs of the verifier are described in [slsa-framework/slsa-verifier#available-options](https://github.com/slsa-framework/slsa-verifier#available-options).
-
-### Command line examples
-
-A command line example is provided in [slsa-framework/slsa-verifier#example](https://github.com/slsa-framework/slsa-verifier#example).