Revised build track files #1536
Conversation
✅ Deploy Preview for slsa ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| --- | ||
| title: "Build: Assessing build platforms" | ||
| description: Guidelines for assessing build platform security. | ||
| description: This page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. |
There was a problem hiding this comment.
nit: I think this might need to be in quotes or else that ' will cause some problems.
| description: This page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. | ||
| --- | ||
|
|
||
| # {Build Track: Assessing Build Platforms} |
There was a problem hiding this comment.
FYI this is redundant. The title on line 1 is going to show up when this is rendered. With this line we wind up with two titles, one of which is in {}.
You can see the preview by clicking on this link in any of the PRs you send.
|
|
||
| # {Build Track: Assessing Build Platforms} | ||
|
|
||
| **About this page:** the *Build Track: Accessing Build Platforms* page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. |
There was a problem hiding this comment.
| **About this page:** the *Build Track: Accessing Build Platforms* page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. | |
| **About this page:** the *Build Track: Accessing Build Platforms* page describes the how to assess the build platform in order to verify an artifact's security. |
This page should be describing the whole process of assessing, not just the various components.
NOTE: I see you're just moving existing language around, but we might as well fix this while were in here.
|
|
||
| **About this page:** the *Build Track: Accessing Build Platforms* page describes the parts of a build platform that consumers SHOULD assess in order to verify an artifact's security. | ||
|
|
||
| **Intended audience:** {add appropriate audience} |
There was a problem hiding this comment.
Who do you think this would be?
Looking at this now I'm somewhat skeptical of these new headings vs just using the overview but I'd be interested to see what other folks think.
| ### Adversary goal | ||
| SLSA's purpose is to help people defend against adversaries that threaten the software supply chain. By understanding adversary goals and profiles, you can assess your build platform more easily. | ||
|
|
||
| ### The adversary's goals |
There was a problem hiding this comment.
Changing headings is OK, but that will also change the links to these sections. Did you happen to check if anyone is linking here or is that something we'll have to check before submitting?
There was a problem hiding this comment.
I see this file was deleted, was it moved elsewhere?
| description: This page covers the technical requirements for producing artifacts at each SLSA level. | ||
| --- | ||
|
|
||
| # {Build Track: Requirements for producing artifacts} |
There was a problem hiding this comment.
As noted elsewhere the title on line 2 will be rendered so we don't need this one.
| ## Overview | ||
|
|
||
| ### Build levels | ||
| In order to produce artifacts with a specific build level, responsibility for meeting requirements is split between the [producer](#producer-responsibilities) and the [platform](#build-platform-responsibilities). The build platform MUST strengthen the security controls in order to achieve a specific level while the |
There was a problem hiding this comment.
nit: we try to keep line lengths around 80 characters.
There was a problem hiding this comment.
I see that we're moving a lot of content into this 'basics' page here (e.g. terminology, etc). That seems fine, but I don't see a similar pattern for the other tracks. It also takes the page beyond the "Just tell me what the levels are" purpose that it had served previously.
It looks like the existing terminology.md page is still hanging around even though its content seems to be here too?
It would be nice to get a consistent recommendation for what pages each track should have and what content should go on those pages. Some tracks might have additional pages, but there definitely seems to be some commonality.
2 participants
Build Track Files:
build-track-basics.md
build-requirements.md
distributing-providence.md
verifying-artifacts.md
assessing-build-platforms.md
These track files have a new header block structure to provide a consistent table of contents to help users improve navigation and easily identify key details for each page. This will also help spec writers ensure that their information is complete and organized.
Additional edits have been made to headings and content to increase the logic flow and add clarity to each page.
DO NOT MERGE