Add rationale and examples for all of the requirements

[MarkLodato]

It helps to explain not just what a system must do to meet SLSA N, but also why along with examples showing common scenarios.

Thanks @david-a-wheeler for the suggestion.

[MarkLodato]

Prior art: https://bestpractices.coreinfrastructure.org/en/criteria

[david-a-wheeler]

An easy way to do this would be to use HTML <details> ...rationale... </details>

[david-a-wheeler]

E.g., Requirement "Scripted build" says:

All build steps were fully defined in some sort of “build script”. The only manual command, if any, was to invoke the build script.

Examples:

• Build script is Makefile, invoked via make all.
• Build script is .github/workflows/build.yaml, invoked by GitHub Actions.

I think we need to document the rationale, something like this:

Rationale: If the only way to rebuild the software is to manually enter special commands, over time rebuilders are likely to forget/omit steps, leading to subtly wrong builds. In addition, an automated script is necessary to implement automated pipelines to rebuild and test built artifacts. Note that it's fine for rebuilding scripts to support options (e.g., via parameters and environment variables) so users can instruct an automated build for a specific purpose while still having an automated script.

[david-a-wheeler]

Here's a tweaked rationale for "Scripted build" - I think every rationale needs to explain why it's relevant to security/integrity. I also add a reference to the best practices badge requirement for the same thing if there's a build step available. I chose "scripted build" because I figured it shouldn't be hard to write a rationale for it :-).

Rationale: If rebuilding the software requires manual steps, rebuilders are likely to forget/omit steps or execute them incorrectly in some cases, leading to subtly wrong builds. Wrong builds can have latent vulnerabilities. In addition, an automated script is necessary to implement automated pipelines to rebuild and test built artifacts, and automated testing is vital for early detection of vulnerabilities (preferably before the software is released for use). Note that it's fine for rebuilding scripts to support options (e.g., via parameters and environment variables) so users can instruct an automated build for a specific purpose while still having an automated script. This requirement is not applicable if there are no build steps, however, note that building a package for distribution is still a build step, even if it's for an interpreted library. This is also required by the OpenSSF Best Practices badge "build" requirement.

FYI, here's the full text of the OpenSSF Best Practices badge requirement "build":

If the software produced by the project requires building for use, the project MUST provide a working build system that can automatically rebuild the software from source code. {N/A allowed} [build]

[abacchi]

@david-a-wheeler I am happy to be the "hater" to spot check these and help write some