[docs][byob] docs for tool writers

[asraa]

Is your feature request related to a problem? Please describe. Start docs aimed towards tool writers to create their own SLSA 3 builder.

Some notable items and example we should provide:

• An example of a composite tool action of an existing action hosted in their repo (this should be referenced as a local action in order to ensure that the action is called at the correct reference)
• Passing write permissions through a github.token for various permissions: packages, contents
• Passing secret(s)
• An example tool that produces multiple attestations
• An example TRW that publishes outside of the tool action
• An Example PW which calls in parallel multiple TRW
• The output builder ID referencing their tool reusable workflow
• Verification with slsa-verifier
• Performing authentication (e.g. docker registry, GCP) inside a tool action
• TRW Action outputs of different types: array, json, string
• Private project repositories

All of these will need corresponding e2e tests, maybe under example-byob or some other name?

cc @laurentsimon

[laurentsimon]

• only certain triggers are supported https://github.com/slsa-framework/slsa-github-generator/issues/1583
• debug mode during development https://github.com/slsa-framework/slsa-github-generator/issues/1583
• secrets don't support defaults in reusable workflows. Need to show how to use use defaults github.token
• inputs need a type
• secrets should only be used for high-entropy random values. Other sensitive values need to be omitted thru option https://github.com/slsa-framework/slsa-github-generator/issues/1575
• TRW Action output
• How to upload attestation in TRW
• Need to provide arekor-log-public option for TRW
• Need to provide a realse-tag-name option for TRW
• Concurrent calls
• how to set up e2e pre-submits (and daily schedule tests ?)
• how to do e2e pre-release tests. Must be in same repo for verification to work. Must set SLSA_VERIFIER_XXX env variable.
• wrapped Action needs to declare its outputs https://github.com/laurentsimon/sbom-action/blob/feat/slsa-trw/internal/sbom-wrapper/action.yml#L5-L24 Unexpected input(s) 'slsa-workflow-inputs', 'slsa-layout-file', 'slsa-workflow-secret1', 'slsa-workflow-secret2', valid inputs are ['']
• explain what each step (slsa-setup, slsa-run, slsa-verification) in TRW
• expected output for each step
• support for matrix (TRW and project maintainers)
• TRWs should return the attestation name + sha256 (coming from SRW) in case the project maintainer wants to download it, see https://github.com/slsa-framework/slsa-github-generator/issues/1637#issuecomment-1428418486
• TRW MUST randomize the name of any artifact they want to share to support concurrent runs (see https://github.com/slsa-framework/slsa-github-generator/pull/1787/files#diff-2478ac6d1b1fe04ba1b7d2876f808b106fc958c2d1631d692020841fdaad70be) for nodejs. Alternatively (better!), they can call our secure-upload-folder.
• TRW must have tests for concurrent runs
• TRWs must securely download provenance and verify download artifacts before using them
• TRW writers should use booleans for bool inputs. Here's an example which does not respect that https://github.com/laurentsimon/sbom-action/blob/v0.0.1/.github/workflows/slsa3.yml#L80-L83. (TODO: verify that it does not break the wrapper Action)

[laurentsimon]

note: I'm doing a Syft PoC at https://github.com/laurentsimon/sbom-action/blob/feat/slsa-trw/.github/workflows/slsa3.yml

[ianlewis]

Related to #1552

I started a template example repo at https://github.com/ianlewis/slsa-byob-template

@asraa @laurentsimon We can maybe move the repo under the SLSA org and start iterating on docs there. wdut?

[ianlewis]

With all the docs we might have to write, maybe we should start thinking about setting up a proper website with rendered HTML docs...

[laurentsimon]

Do you think GitHub pages would be a good start? Do you think we could host the doc in this repo under a different branch with no branch protection enabled? Or doing it on another repo is simpler?

Shall we brainstorm the high-level sections we have in mind?

0. Intro
   • Terminology
   • Supported triggers
1. Getting started
   • I want to wrap an existing Action
   • I want to create a compliant builder from scratch
2. Maintenance
   • Use X
   • Use Y
3. Improve my security
   • Generate provenance for my binaries
   • Verify them in Action
   • Follow Scorecard best practice
4. Let your users know
   • Update your README
   • Opt in the compliance program
5. FAQs / Common pitfalls
   • Error msg "bla"
6. Examples
   • Passing secrets
   • Using GH token
   • Upload provenance to release asset
   • ...

I'm just making this up :)

[laurentsimon]

/cc @olivekl if you have any insight / advice

[ianlewis]

I think gh pages would be great. We don't have a lot of collective bandwidth and expertise for docs so I think we'll want to use something with low friction.

The slsa website uses netlify so that might be another option to look at.

[laurentsimon]

OK. I propose starting with .md files. Hopefully GH pages will allow us to turn it into a website with a pre-defined theme with little effort if we want to polish it. Wdut?

[ianlewis]

OK. I propose starting with .md files. Hopefully GH pages will allow us to turn it into a website with a pre-defined theme with little effort if we want to polish it. Wdut?

Yeah, it should be easy to do. Definitely something we have to lead with. We can defer decisions until we need to polish and organize. the docs

[ianlewis]

Related to #892

[laurentsimon]

Closing this as completed, see https://github.com/slsa-framework/slsa-github-generator/blob/main/BYOB.md. We will iterate and update the README to mention BYOB in follow-up PR