Proposed SLSA spec TOC reorganization

[mcevoy-building7]

Tom wanted me to create a GitHub issue to present my new TOC ideas to the team. I've been working to develop a simple set of TOC categories for the SLSA specification so new readers can learn and use SLSA as efficiently as possible. Having a simple TOC will also help provide contributors with clear categories for inserting their additions and making changes.

I've been working a lot to clarify confusing content and headings, add transitions to enhance the logic flow, make general English edits where language is ambiguous, overly dense, or incorrect. As I've been pulling together all the PR versions into an updated TOC layout, I noticed there were a lot of problems putting things into clear categories, so it was easy to follow. At the last minute I hit on a new idea that would help combine all of the existing pages into a simple set of "like with like" categories. My new design should provide consistency and clarity that will make it easier to dig through all the different SLSA pages without getting lost and confused.

I am proposing the TOC consists of four categories of SLSA material. The four concepts are:

1. Introductory content to get started
2. The problems of supply chain security
3. Technical details of how SLSA can solve those problems
4. Assorted resource topics

Here's the complete breakdown of my new TOC strategy:

===================

INTRODUCTION TO SLSA

• What is SLSA?
• About this specification
  • Who are we?
  • Licenses & Sponsors
  • What's in this document?
  • What's new?
  • Future directions
  • Specification stages
  • Version history
• Applying SLSA
  • Use cases
  • SLSA Guiding Principles
• {is there other getting started info needed?}

THE SUPPLY CHAIN PROBLEM

• Real world examples of Supply Chain threats
• Threats & mitigations

THE SLSA SOLUTION

• Introduction to Tracks
  • Tracks overview
  • Terminology
• Build Track
  • Buld Track: Basics
  • Build Track: Requirements for producing artifacts
  • Build Track: Distributing provenance
  • Build Track: Verifying artifacts
  • Build Track: Assessing build platforms
• Build Environment Track
  • Build Environment Track: Basics
• Dependency Track
  • Dependency Track: Consuming dependencies
• Source Track
  • Source Track: Consuming source
  • Source Track: Verifying source
  • Source Track: Assessing source control systems
  • Source Track: Example controls
• Attestation Formats
  • Attestation formats: General model
  • Attestation formats: Provenance
  • Attestation formats: Build Provenance
  • Attestation formats: Verification Summary Attestation (VSA)
• Verified properties

RESOURCES

• FAQ
• Blog
• Community
• Contributor guide
• {More?}

===================

Here's some notes on the TOC details:

• About this specification: This would be a good category to put all the structural information about what is the spec? who's involved? what are the plans? technical details about stages and versions people need to know?

  • I'll write up a list of content needed for this section, but the team will need to fill in all the nitty-gritty details.

• The Supply Chain problem and the SLSA solution - these two categories separate the Supply Chain threats and mitigation information in a stand-alone place so people can refer to it easily. The Supply Chain problem outlines the many, many threats and the SLSA Solution section combines all the specification standards and requirement pages into one place. Most of this is complete and all the tracks received new headers to help add consistency to the openings of each page. Attestations are still coming.

  • I chose these unique titles for these two TOC categories to help enhance the core SLSA issues because it consists of two parts: (1) the problem of supply chain threats to the software industry and (2) the SLSA solution to that problem.

• Resources - this category can be a catch-all for any and all extra pages.

My hope is by reframing how we describe the threats and tracks, it might help communicate the idea that there's a huge security problem and SLSA is the solution.

I appreciate any and all feedback.

[TomHennen]

Thanks Seth.

It would be nice to see a bit more standardization between the tracks. What pages should be common between them? What should be on those pages? E.g. the Build Track has "Basics" but in the recent PR it actually has a lot more than it used to discussed here.

I know the Build Environment and Dependency track don't have all their content yet, but what should they have?

E.g. should each track have a 'Basics' page that discusses the concepts needed to understand the requirements (including track specific terminology)? Should they then have a separate "requirements" page that covers the actual nitty gritty details the implementors need to work out? Should they each have an "assessment" page that details how consumers can verify if an implementor did it right? Should they all have a page that helps consumers verify if a given aritfact meets the requirements or not? Where should tracks put a summary of their various levels? E.g. the source track has it's in this basics section, which differs from what the Build Track is doing.

I'm guessing the "Terminology" page will be for "common" terminology.

I'm wondering if clear guidance for how we should organize the content (including descriptions of what goes on each of these pages) would be the most impactful work right now.

Does anyone else have thoughts?

[lehors]

I agree that we should have some kind of standard structure that is followed for every track. There may be exceptions of course, a particular track may want to touch on some unique aspect that is worth addressing in a different section that just doesn't exist for other tracks but otherwise it'd be nice to get some regularity across the tracks.