diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 93068bb56..e3374fad8 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -50,6 +50,10 @@ MD047: true MD048: style: "backtick" +# MD055/table-pipe-style - Table pipe style +MD055: + style: "leading_only" + # Disable checks that currently have bugs: MD051: false # https://github.com/DavidAnson/markdownlint/issues/538 MD053: false # https://github.com/DavidAnson/markdownlint/issues/537 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c02f13b41..32014fc7f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -99,15 +99,15 @@ multiple apply. If you are not sure which type to use, take a guess and a maintainer will update if needed. See [review and approval] for the meaning of "waiting period" and "# approvers". -| Type | Meaning | Waiting period | # Approvers | -|---|---|---|---| -| `content` | A change to the meaning of the specification. Must include a [changelog entry]. | 72h | 3 | -| `editorial` | A clarification to the specification that does not change its meaning, beyond a simple `fix`. | 24h | 2 | -| `nonspec` | A change to a non-specification, non-blog page, beyond a simple `fix`. | 24h | 2 | -| `blog` | A new or updated blog post. (Do not mix with categories above.) | 24h | 2 | -| `fix` | A fix for obvious typos, broken links, and similar. | 0h | 1 | -| `style` | A user-visible style or layout change. No content changes. | 0h | 1 | -| `impl` | A user-invisible change, such as editing a README or the repo configuration. | 0h | 1 | +| Type | Meaning | Waiting period | # Approvers +|---|---|---|--- +| `content` | A change to the meaning of the specification. Must include a [changelog entry]. | 72h | 3 +| `editorial` | A clarification to the specification that does not change its meaning, beyond a simple `fix`. | 24h | 2 +| `nonspec` | A change to a non-specification, non-blog page, beyond a simple `fix`. | 24h | 2 +| `blog` | A new or updated blog post. (Do not mix with categories above.) | 24h | 2 +| `fix` | A fix for obvious typos, broken links, and similar. | 0h | 1 +| `style` | A user-visible style or layout change. No content changes. | 0h | 1 +| `impl` | A user-invisible change, such as editing a README or the repo configuration. | 0h | 1 Note 1: PR authors with write access to the repo count as second or third approvers for their own PRs. For example, if the author of a PR with the diff --git a/MAINTAINERS.md b/MAINTAINERS.md index e80a37be1..2ec7c1327 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -13,14 +13,14 @@ permissions in this repository. -| Name | Email | OpenSSF Slack | GitHub | Affiliation | -| --- | --- | --- | --- | --- | -| Andrew McNamara | arewm@redhat.com | @arewm | [arewm](https://github.com/arewm) | Red Hat | -| Arnaud Le Hors | lehors@us.ibm.com | @Arnaud Le Hors | [lehors](https://github.com/lehors) | IBM | -| Joshua Lock | joshuagloe@gmail.com | @Joshua Lock | [joshuagl](https://github.com/joshuagl) | Verizon | -| Kris K | kkris@google.com | @Kris K | [kpk47](https://github.com/kpk47) | Google | -| Mark Lodato | lodato@google.com | @Mark Lodato | [MarkLodato](https://github.com/MarkLodato) | Google | -| Michael Lieberman | mlieberman85@gmail.com | @Michael Lieberman | [mlieberman85](https://github.com/mlieberman85) | Kusari | +| Name | Email | OpenSSF Slack | GitHub | Affiliation +| --- | --- | --- | --- | --- +| Andrew McNamara | arewm@redhat.com | @arewm | [arewm](https://github.com/arewm) | Red Hat +| Arnaud Le Hors | lehors@us.ibm.com | @Arnaud Le Hors | [lehors](https://github.com/lehors) | IBM +| Joshua Lock | joshuagloe@gmail.com | @Joshua Lock | [joshuagl](https://github.com/joshuagl) | Verizon +| Kris K | kkris@google.com | @Kris K | [kpk47](https://github.com/kpk47) | Google +| Mark Lodato | lodato@google.com | @Mark Lodato | [MarkLodato](https://github.com/MarkLodato) | Google +| Michael Lieberman | mlieberman85@gmail.com | @Michael Lieberman | [mlieberman85](https://github.com/mlieberman85) | Kusari ### Becoming a Maintainer @@ -47,8 +47,8 @@ candidate to the [Specification Maintainers] GitHub team. -| Name | Email | OpenSSF Slack | GitHub | Affiliation | -| --- | --- | --- | --- | --- | +| Name | Email | OpenSSF Slack | GitHub | Affiliation +| --- | --- | --- | --- | --- ### Removing a Maintainer diff --git a/README.md b/README.md index d403e673c..46c40d6db 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,12 @@ See https://slsa.dev/community for ways to get involved in SLSA development. ## Active workstreams -| Workstream | [Shepherd] | -| ---------- | ---------- | -| [Build Level 4] | David A Wheeler (@david-a-wheeler) | -| [Hardware Attested Platforms] | Marcela Melara (@marcelamelara), Chad Kimes (@chkimes) | -| [Source Track] | Kris K (@kpk47) | -| [Version 1.1 release] | Joshua Lock (@joshuagl) | +| Workstream | [Shepherd] +| ---------- | ---------- +| [Build Level 4] | David A Wheeler (@david-a-wheeler) +| [Hardware Attested Platforms] | Marcela Melara (@marcelamelara), Chad Kimes (@chkimes) +| [Source Track] | Kris K (@kpk47) +| [Version 1.1 release] | Joshua Lock (@joshuagl) [Shepherd]: CONTRIBUTING.md#workstream-lifecycle [Build Level 4]: https://github.com/slsa-framework/slsa/issues/977 diff --git a/controls/survey.md b/controls/survey.md index e9daf42f3..14069ef08 100644 --- a/controls/survey.md +++ b/controls/survey.md @@ -30,21 +30,21 @@ model. Subsequent sections analyze each layer. [in-toto v1]: https://github.com/in-toto/docs/blob/master/in-toto-spec.md [in-toto v2]: https://github.com/in-toto/attestation -Project | Envelope | Statement | Predicate | Storage | Generation | Policy | Status ----------------------- | -------- | --------- | --------- | ------- | ---------- | ------ | ------ -Raw signing | ✓ | ✓ | ✗ | | | | (varies) -[JSS] | ✓ | | | | | | Abandoned -[JWS] | ✓ | | | | | | IETF Standard -[JWT] | ✓ | | | | | | IETF Standard -[OpenPGP] | ✓ | | | | | | IETF Standard -[PASETO] | ✓ | | | | | | Stable -[DSSE] | ✓ | | | | | | In development -[in-toto v1] | ✓ | ✓ | ✓ | | ✓ | ✓ | Stable -[Notary v2] | ~ | ✓ | ✗ | ✓ | | ✓ | In development -[Simple Signing] | ~ | ✓ | | | | | Stable -[in-toto v2] | ~ | ✓ | | | | | In development -[SPDX] | | | ✓ | | | | Stable -[Binary Authorization] | ~ | ~ | ✗ | ~ | | ✓ | Stable +| Project | Envelope | Statement | Predicate | Storage | Generation | Policy | Status +| ---------------------- | -------- | --------- | --------- | ------- | ---------- | ------ | ------ +| Raw signing | ✓ | ✓ | ✗ | | | | (varies) +| [JSS] | ✓ | | | | | | Abandoned +| [JWS] | ✓ | | | | | | IETF Standard +| [JWT] | ✓ | | | | | | IETF Standard +| [OpenPGP] | ✓ | | | | | | IETF Standard +| [PASETO] | ✓ | | | | | | Stable +| [DSSE] | ✓ | | | | | | In development +| [in-toto v1] | ✓ | ✓ | ✓ | | ✓ | ✓ | Stable +| [Notary v2] | ~ | ✓ | ✗ | ✓ | | ✓ | In development +| [Simple Signing] | ~ | ✓ | | | | | Stable +| [in-toto v2] | ~ | ✓ | | | | | In development +| [SPDX] | | | ✓ | | | | Stable +| [Binary Authorization] | ~ | ~ | ✗ | ~ | | ✓ | Stable Legend: @@ -66,15 +66,15 @@ Columns: ## Envelope Layer (not specific to Attestations) -Property | [DSSE] | [OpenPGP] | [JWS] | [JWT] | [PASETO] | [in-toto v1] | [JSS] ------------------------ | -------------- | --------- | ----- | ----- | -------- | ------------ | ----- -Authenticated Purpose | ✓ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ -Arbitrary Message Type | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ -Simple | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ -Avoids Canonicalization | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ -Pluggable Crypto | ✓ | ✗ | ✓ | ✓ | ✗ | ✓ | ✓ -Efficient Encoding | ✓ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ -Widely Adopted | ✗ (not yet!) | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ +| Property | [DSSE] | [OpenPGP] | [JWS] | [JWT] | [PASETO] | [in-toto v1] | [JSS] +| ----------------------- | -------------- | --------- | ----- | ----- | -------- | ------------ | ----- +| Authenticated Purpose | ✓ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ +| Arbitrary Message Type | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ +| Simple | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ +| Avoids Canonicalization | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ +| Pluggable Crypto | ✓ | ✗ | ✓ | ✓ | ✗ | ✓ | ✓ +| Efficient Encoding | ✓ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ +| Widely Adopted | ✗ (not yet!) | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ Properties: @@ -107,17 +107,17 @@ Properties: ## Statement Layer -Property | [in-toto v2] | [in-toto v1] | [Simple Signing] | [Notary v2] | Raw Signing ---------------------- | ------------ | ------------ | ---------------- | ----------- | ----------- -Recommended Envelope | DSSE | in-toto v1 | OpenPGP | JWT | (various) -Subject: Clear | ✓ | ✗ | ✓ | ✓ | ✓ -Subject: Any Type | ✓ | ✓ | ✗ | ✓ | (depends) -Subject: Multi-Digest | ✓ | ✓ | ✗ | ✗ | (depends) -Predicate: Supported | ✓ | ✓ | ✓ | ✗ | ✗ -Predicate: Flexible | ✓ | ✗ (*) | ✓ | (n/a) | (n/a) -Predicate: Typed | ✓ | ✗ | ✗ | (n/a) | (n/a) -Layered | ✓ | ✗ | ✓ | (n/a) | (n/a) -Evolvable | ✓ | ✓ | ✗ | ✓ | ✗ +| Property | [in-toto v2] | [in-toto v1] | [Simple Signing] | [Notary v2] | Raw Signing +| --------------------- | ------------ | ------------ | ---------------- | ----------- | ----------- +| Recommended Envelope | DSSE | in-toto v1 | OpenPGP | JWT | (various) +| Subject: Clear | ✓ | ✗ | ✓ | ✓ | ✓ +| Subject: Any Type | ✓ | ✓ | ✗ | ✓ | (depends) +| Subject: Multi-Digest | ✓ | ✓ | ✗ | ✗ | (depends) +| Predicate: Supported | ✓ | ✓ | ✓ | ✗ | ✗ +| Predicate: Flexible | ✓ | ✗ (*) | ✓ | (n/a) | (n/a) +| Predicate: Typed | ✓ | ✗ | ✗ | (n/a) | (n/a) +| Layered | ✓ | ✗ | ✓ | (n/a) | (n/a) +| Evolvable | ✓ | ✓ | ✗ | ✓ | ✗ Properties: diff --git a/docs/attestation-model.md b/docs/attestation-model.md index 4181523c6..d8bb754a0 100644 --- a/docs/attestation-model.md +++ b/docs/attestation-model.md @@ -136,13 +136,13 @@ and have desirable security properties. Our hope is to align the industry around this particular suite because it makes everything easier. That said, we recognize that other choices MAY be necessary in various cases. -| Component | Recommendation | -| --- | --- | -| Envelope | **[DSSE]** (ECDSA over NIST P-256 (or stronger) and SHA-256.) | -| Statement | **[in-toto attestations]** | -| Predicate | Choose as appropriate, i.e.; [Provenance], [SPDX], [other predicates defined by third-parties]. If none are a good fit, invent a new one | -| Bundle | **[JSON Lines]**, see [attestation bundle] | -| Storage/Lookup | **TBD** | +| Component | Recommendation +| --- | --- +| Envelope | **[DSSE]** (ECDSA over NIST P-256 (or stronger) and SHA-256.) +| Statement | **[in-toto attestations]** +| Predicate | Choose as appropriate, i.e.; [Provenance], [SPDX], [other predicates defined by third-parties]. If none are a good fit, invent a new one +| Bundle | **[JSON Lines]**, see [attestation bundle] +| Storage/Lookup | **TBD** [attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md [Binary Authorization]: https://cloud.google.com/binary-authorization diff --git a/docs/get-started.md b/docs/get-started.md index be1508e16..4751ec112 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -106,9 +106,9 @@ The following table shows known build software packages and the potential SLSA l Note that this list is provided "as is". OpenSSF makes no claim as to the reliability of this information. A certification program is under development to provide a more definitive list. -| Builder | Potential SLSA Level | -|--------------------------|:--------------------:| -| FRSCA | 2 | -| GitHub Actions | 3 | -| Google Cloud Build | 3 | -| No Hosted Build Platform | 1 | +| Builder | Potential SLSA Level +|--------------------------|:--------------------: +| FRSCA | 2 +| GitHub Actions | 3 +| Google Cloud Build | 3 +| No Hosted Build Platform | 1 diff --git a/docs/notes/index.md b/docs/notes/index.md index 74efdc2c7..e106ef8d3 100644 --- a/docs/notes/index.md +++ b/docs/notes/index.md @@ -8,9 +8,9 @@ docs. This way you can type, for example, `https://slsa.dev/notes/community` instead of finding the Google docs URL. Each notes document also has the time, meeting link, etc. at the top. -URL | Alias | Meeting ------------------------------- | ------------ | --------------------------- -[community](community) | | General community meeting -[positioning](positioning) | | Positioning SIG -[specification](specification) | [spec](spec) | Specification SIG -[tooling](tooling) | | Tooling SIG +| URL | Alias | Meeting +| ------------------------------ | ------------ | --------------------------- +| [community](community) | | General community meeting +| [positioning](positioning) | | Positioning SIG +| [specification](specification) | [spec](spec) | Specification SIG +| [tooling](tooling) | | Tooling SIG diff --git a/docs/spec/v0.1/levels.md b/docs/spec/v0.1/levels.md index f6dec312c..23268c786 100644 --- a/docs/spec/v0.1/levels.md +++ b/docs/spec/v0.1/levels.md @@ -25,24 +25,24 @@ corresponding integrity guarantees. ## Summary of levels -| Level | Description | Example | -| :---- | :-------------------------------------------- | :---------------------------------------------------- | -| 1 | Documentation of the build process | Unsigned provenance | -| 2 | Tamper resistance of the build service | Hosted source/build, signed provenance | -| 3 | Extra resistance to specific threats | Security controls on host, non-falsifiable provenance | -| 4 | Highest levels of confidence and trust | Two-party review + hermetic builds | +| Level | Description | Example +| :---- | :-------------------------------------------- | :---------------------------------------------------- +| 1 | Documentation of the build process | Unsigned provenance +| 2 | Tamper resistance of the build service | Hosted source/build, signed provenance +| 3 | Extra resistance to specific threats | Security controls on host, non-falsifiable provenance +| 4 | Highest levels of confidence and trust | Two-party review + hermetic builds It can take years to achieve the ideal security state - intermediate milestones are important. SLSA guides you through gradually improving the security of your software. Artifacts used in critical infrastructure or vital business operations may want to attain a higher level of security, whereas software that poses a low risk can stop when they're comfortable. ## Detailed explanation -| Level | Requirements | -| ----- | ------------ | -| 0 | **No guarantees.** SLSA 0 represents the lack of any SLSA level. | -| 1 | **The build process must be fully scripted/automated and generate provenance.** Provenance is metadata about how an artifact was built, including the build process, top-level source, and dependencies. Knowing the provenance allows software consumers to make risk-based security decisions. Provenance at SLSA 1 does not protect against tampering, but it offers a basic level of code source identification and can aid in vulnerability management. | -| 2 | **Requires using version control and a hosted build service that generates authenticated provenance.** These additional requirements give the software consumer greater confidence in the origin of the software. At this level, the provenance prevents tampering to the extent that the build service is trusted. SLSA 2 also provides an easy upgrade path to SLSA 3. | -| 3 | **The source and build platforms meet specific standards to guarantee the auditability of the source and the integrity of the provenance respectively.** We envision an accreditation process whereby auditors certify that platforms meet the requirements, which consumers can then rely on. SLSA 3 provides much stronger protections against tampering than earlier levels by preventing specific classes of threats, such as cross-build contamination. | -| 4 | **Requires two-person review of all changes and a hermetic, reproducible build process.** Two-person review is an industry best practice for catching mistakes and deterring bad behavior. Hermetic builds guarantee that the provenance’s list of dependencies is complete. Reproducible builds, though not strictly required, provide many auditability and reliability benefits. Overall, SLSA 4 gives the consumer a high degree of confidence that the software has not been tampered with. | +| Level | Requirements +| ----- | ------------ +| 0 | **No guarantees.** SLSA 0 represents the lack of any SLSA level. +| 1 | **The build process must be fully scripted/automated and generate provenance.** Provenance is metadata about how an artifact was built, including the build process, top-level source, and dependencies. Knowing the provenance allows software consumers to make risk-based security decisions. Provenance at SLSA 1 does not protect against tampering, but it offers a basic level of code source identification and can aid in vulnerability management. +| 2 | **Requires using version control and a hosted build service that generates authenticated provenance.** These additional requirements give the software consumer greater confidence in the origin of the software. At this level, the provenance prevents tampering to the extent that the build service is trusted. SLSA 2 also provides an easy upgrade path to SLSA 3. +| 3 | **The source and build platforms meet specific standards to guarantee the auditability of the source and the integrity of the provenance respectively.** We envision an accreditation process whereby auditors certify that platforms meet the requirements, which consumers can then rely on. SLSA 3 provides much stronger protections against tampering than earlier levels by preventing specific classes of threats, such as cross-build contamination. +| 4 | **Requires two-person review of all changes and a hermetic, reproducible build process.** Two-person review is an industry best practice for catching mistakes and deterring bad behavior. Hermetic builds guarantee that the provenance’s list of dependencies is complete. Reproducible builds, though not strictly required, provide many auditability and reliability benefits. Overall, SLSA 4 gives the consumer a high degree of confidence that the software has not been tampered with. The SLSA level is not transitive ([see our FAQs](faq.md)). This makes each artifact’s SLSA rating independent from one another, allowing parallel progress and prioritization based on risk. The level describes the integrity protections of an artifact’s build process and top-level source, but nothing about the artifact’s dependencies. Dependencies have their own SLSA ratings, and it is possible for a SLSA 4 artifact to be built from SLSA 0 dependencies. diff --git a/docs/spec/v0.1/requirements.md b/docs/spec/v0.1/requirements.md index 03bbb6655..3ffae66e0 100644 --- a/docs/spec/v0.1/requirements.md +++ b/docs/spec/v0.1/requirements.md @@ -13,28 +13,28 @@ To better understand the reasoning behind the requirements, see ## Summary table -| Requirement | SLSA 1 | SLSA 2 | SLSA 3 | SLSA 4 | -| ------------------------------------ | ------ | ------ | ------ | ------ | -| Source - [Version controlled] | | ✓ | ✓ | ✓ | -| Source - [Verified history] | | | ✓ | ✓ | -| Source - [Retained indefinitely] | | | 18 mo. | ✓ | -| Source - [Two-person reviewed] | | | | ✓ | -| Build - [Scripted build] | ✓ | ✓ | ✓ | ✓ | -| Build - [Build service] | | ✓ | ✓ | ✓ | -| Build - [Build as code] | | | ✓ | ✓ | -| Build - [Ephemeral environment] | | | ✓ | ✓ | -| Build - [Isolated] | | | ✓ | ✓ | -| Build - [Parameterless] | | | | ✓ | -| Build - [Hermetic] | | | | ✓ | -| Build - [Reproducible] | | | | ○ | -| Provenance - [Available] | ✓ | ✓ | ✓ | ✓ | -| Provenance - [Authenticated] | | ✓ | ✓ | ✓ | -| Provenance - [Service generated] | | ✓ | ✓ | ✓ | -| Provenance - [Non-falsifiable] | | | ✓ | ✓ | -| Provenance - [Dependencies complete] | | | | ✓ | -| Common - [Security] | | | | ✓ | -| Common - [Access] | | | | ✓ | -| Common - [Superusers] | | | | ✓ | +| Requirement | SLSA 1 | SLSA 2 | SLSA 3 | SLSA 4 +| ------------------------------------ | ------ | ------ | ------ | ------ +| Source - [Version controlled] | | ✓ | ✓ | ✓ +| Source - [Verified history] | | | ✓ | ✓ +| Source - [Retained indefinitely] | | | 18 mo. | ✓ +| Source - [Two-person reviewed] | | | | ✓ +| Build - [Scripted build] | ✓ | ✓ | ✓ | ✓ +| Build - [Build service] | | ✓ | ✓ | ✓ +| Build - [Build as code] | | | ✓ | ✓ +| Build - [Ephemeral environment] | | | ✓ | ✓ +| Build - [Isolated] | | | ✓ | ✓ +| Build - [Parameterless] | | | | ✓ +| Build - [Hermetic] | | | | ✓ +| Build - [Reproducible] | | | | ○ +| Provenance - [Available] | ✓ | ✓ | ✓ | ✓ +| Provenance - [Authenticated] | | ✓ | ✓ | ✓ +| Provenance - [Service generated] | | ✓ | ✓ | ✓ +| Provenance - [Non-falsifiable] | | | ✓ | ✓ +| Provenance - [Dependencies complete] | | | | ✓ +| Common - [Security] | | | | ✓ +| Common - [Access] | | | | ✓ +| Common - [Superusers] | | | | ✓ _○ = REQUIRED unless there is a justification_ diff --git a/docs/spec/v0.1/terminology.md b/docs/spec/v0.1/terminology.md index 5b79481d5..4beb6571b 100644 --- a/docs/spec/v0.1/terminology.md +++ b/docs/spec/v0.1/terminology.md @@ -17,13 +17,13 @@ supply chains plus its own sources and builds. ![Software Supply Chain Model](../../images/supply-chain-model.svg) -| Term | Description | Example | -| --- | --- | --- | -| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. | -| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). | -| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). | -| Package | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. | -| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). | +| Term | Description | Example +| --- | --- | --- +| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. +| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). +| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). +| Package | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. +| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). [build]: #build-model @@ -39,31 +39,31 @@ one or more artifacts.

Model Build

-| Term | Description | -| --- | --- | -| Platform | System that allows tenants to run build. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. | -| Service | A platform that is hosted, not a developer's machine. (Term used in [requirements](requirements.md).) | -| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single environment. | -| Steps | The set of actions that comprise a build, defined by the tenant. | -| Environment | Machine, container, VM, or similar in which the build runs, initialized by the platform. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. | -| Trigger | External event or request causing the platform to run the build. | -| Source | Top-level input artifact required by the build. | -| Dependencies | Additional input artifacts required by the build. | -| Outputs | Collection of artifacts produced by the build. | -| Admin | Person with administrative access to the platform, potentially allowing them to tamper with the build process or access secret material. | +| Term | Description +| --- | --- +| Platform | System that allows tenants to run build. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. +| Service | A platform that is hosted, not a developer's machine. (Term used in [requirements](requirements.md).) +| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single environment. +| Steps | The set of actions that comprise a build, defined by the tenant. +| Environment | Machine, container, VM, or similar in which the build runs, initialized by the platform. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. +| Trigger | External event or request causing the platform to run the build. +| Source | Top-level input artifact required by the build. +| Dependencies | Additional input artifacts required by the build. +| Outputs | Collection of artifacts produced by the build. +| Admin | Person with administrative access to the platform, potentially allowing them to tamper with the build process or access secret material.
Example: GitHub Actions -| Term | Example | -| ------------ | ------- | -| Platform | [GitHub Actions] + runner + runner's dependent services | -| Build | Workflow or job (either would be OK) | -| Steps | [`steps`] | -| Environment | [`runs-on`] | -| Trigger | [workflow trigger] | -| Source | git commit defining the workflow | -| Dependencies | any other artifacts fetched during execution | -| Admin | GitHub personnel | +| Term | Example +| ------------ | ------- +| Platform | [GitHub Actions] + runner + runner's dependent services +| Build | Workflow or job (either would be OK) +| Steps | [`steps`] +| Environment | [`runs-on`] +| Trigger | [workflow trigger] +| Source | git commit defining the workflow +| Dependencies | any other artifacts fetched during execution +| Admin | GitHub personnel [GitHub Actions]: https://docs.github.com/en/actions [`runs-on`]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on @@ -91,13 +91,13 @@ runner environment plus the remote execution environment. The model can still work for the case of a developer building on their local workstation, though this does not meet SLSA 2+. -| Term | Example | -| ------------ | ------- | -| Platform | developer's workstation | -| Build | whatever they ran | -| Steps | whatever they ran | -| Environment | developer's workstation | -| Trigger | commands that the developer ran | -| Admin | developer | +| Term | Example +| ------------ | ------- +| Platform | developer's workstation +| Build | whatever they ran +| Steps | whatever they ran +| Environment | developer's workstation +| Trigger | commands that the developer ran +| Admin | developer
diff --git a/docs/spec/v1.0-rc1/index.md b/docs/spec/v1.0-rc1/index.md index e93797977..dd77ad5a0 100644 --- a/docs/spec/v1.0-rc1/index.md +++ b/docs/spec/v1.0-rc1/index.md @@ -28,15 +28,15 @@ Known issues: ## Table of contents -| Page | Description | -| ---- | --- | -| [What's new in v1.0](whats-new.md) | What's new in SLSA Version 1.0. | -| [Security levels](levels.md) | Overview of SLSA, intended for all audiences. If you read one page, read this. | -| [Guiding principles](principles.md) | Background on the guiding principles behind SLSA. | -| [Terminology](terminology.md) | Terminology and model used by SLSA. | -| [Producing artifacts](requirements.md) | Detailed technical requirements for producing software artifacts, intended for system implementers. | -| [Verifying build systems](verifying-systems.md) | Guidelines for securing SLSA Build L3+ builders, intended for system implementers. | -| [Verifying artifacts](verifying-artifacts.md) | Guidance for verifying software artifacts and their SLSA provenance, intended for system implementers and software consumers. | -| [Threats & mitigations](threats.md) | Specific supply chain attacks and how SLSA helps. | -| [FAQ](faq.md) | Questions and more information. | -| [Future directions](future-directions.md) | Additions and changes being considered for future SLSA versions. | +| Page | Description +| ---- | --- +| [What's new in v1.0](whats-new.md) | What's new in SLSA Version 1.0. +| [Security levels](levels.md) | Overview of SLSA, intended for all audiences. If you read one page, read this. +| [Guiding principles](principles.md) | Background on the guiding principles behind SLSA. +| [Terminology](terminology.md) | Terminology and model used by SLSA. +| [Producing artifacts](requirements.md) | Detailed technical requirements for producing software artifacts, intended for system implementers. +| [Verifying build systems](verifying-systems.md) | Guidelines for securing SLSA Build L3+ builders, intended for system implementers. +| [Verifying artifacts](verifying-artifacts.md) | Guidance for verifying software artifacts and their SLSA provenance, intended for system implementers and software consumers. +| [Threats & mitigations](threats.md) | Specific supply chain attacks and how SLSA helps. +| [FAQ](faq.md) | Questions and more information. +| [Future directions](future-directions.md) | Additions and changes being considered for future SLSA versions. diff --git a/docs/spec/v1.0-rc1/levels.md b/docs/spec/v1.0-rc1/levels.md index 9b25e0f3d..02d6705eb 100644 --- a/docs/spec/v1.0-rc1/levels.md +++ b/docs/spec/v1.0-rc1/levels.md @@ -67,12 +67,12 @@ to recognize progress made in one aspect of security without blocking on an unrelated aspect. Tracks also allow the SLSA spec to evolve: we can add more tracks without invalidating previous levels. -| Track/Level | Requirements | Benefits | -| ----------- | ------------ | -------- | -| [Build L0] | (none) | (n/a) | -| [Build L1] | Attestation showing that the package was built as expected | Documentation, mistake prevention, inventorying | -| [Build L2] | Signed attestation, generated by a hosted build service | Reduced attack surface, weak tamper protection | -| [Build L3] | Hardened build service | Strong tamper protection | +| Track/Level | Requirements | Benefits +| ----------- | ------------ | -------- +| [Build L0] | (none) | (n/a) +| [Build L1] | Attestation showing that the package was built as expected | Documentation, mistake prevention, inventorying +| [Build L2] | Signed attestation, generated by a hosted build service | Reduced attack surface, weak tamper protection +| [Build L3] | Hardened build service | Strong tamper protection > Note: The [previous version] of the specification used a single unnamed track, > SLSA 1–4. For version 1.0 the Source aspects were removed to focus on the diff --git a/docs/spec/v1.0-rc1/provenance.md b/docs/spec/v1.0-rc1/provenance.md index 5666c0fea..eee483dca 100644 --- a/docs/spec/v1.0-rc1/provenance.md +++ b/docs/spec/v1.0-rc1/provenance.md @@ -596,11 +596,11 @@ other security-relevant external parameters. The expectations SHOULD cover the following: -| What | Why | -| ---- | --- | -| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended system | -| `buildType` | To ensure that `externalParameters` are interpreted as intended | -| `externalParameters` | To prevent an adversary from injecting unofficial behavior | +| What | Why +| ---- | --- +| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended system +| `buildType` | To ensure that `externalParameters` are interpreted as intended +| `externalParameters` | To prevent an adversary from injecting unofficial behavior Verifiers SHOULD reject unrecognized fields in `externalParameters` to err on the side of caution. It is acceptable to allow a parameter to have a range of diff --git a/docs/spec/v1.0-rc1/terminology.md b/docs/spec/v1.0-rc1/terminology.md index 878bf2565..bb17a9682 100644 --- a/docs/spec/v1.0-rc1/terminology.md +++ b/docs/spec/v1.0-rc1/terminology.md @@ -24,14 +24,14 @@ supply chains plus its own sources and builds. ![Software Supply Chain Model](../../images/supply-chain-model.svg) -| Term | Description | Example | -| --- | --- | --- | -| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. | -| Attestation | An authenticated statement (metadata) about a software artifact or collection of software artifacts. | A signed [SLSA Provenance] file. | -| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). | -| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). | -| Package | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. | -| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). | +| Term | Description | Example +| --- | --- | --- +| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. +| Attestation | An authenticated statement (metadata) about a software artifact or collection of software artifacts. | A signed [SLSA Provenance] file. +| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). +| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). +| Package | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. +| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). [build]: #build-model [SLSA Provenance]: /provenance/v1-rc1 @@ -50,16 +50,16 @@ describing this whole process.

Model Build

-| Primary Term | Description | -| --- | --- | -| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. | -| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single environment on a platform. | -| Steps | The set of actions that comprise a build, defined by the tenant. | -| Environment | Machine, container, VM, or similar in which the build runs, initialized by the platform. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. | -| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the platform to initialize the build. | -| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. | -| Outputs | Collection of artifacts produced by the build. | -| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters. | +| Primary Term | Description +| --- | --- +| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. +| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single environment on a platform. +| Steps | The set of actions that comprise a build, defined by the tenant. +| Environment | Machine, container, VM, or similar in which the build runs, initialized by the platform. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. +| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the platform to initialize the build. +| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. +| Outputs | Collection of artifacts produced by the build. +| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters. Notably, there is no formal notion of "source" in the build model, just parameters and dependencies. Most build platforms have an explicit "source" @@ -84,31 +84,31 @@ build system the package was built. ![Verification Model](verification-model.svg) -| Term | Description | -|--------------|---- | -| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. | -| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. | -| Build system certification | [Build systems are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. | +| Term | Description +|--------------|---- +| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. +| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. +| Build system certification | [Build systems are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. The examples below suggest some ways that expectations and verification may be implemented for different, broadly defined, package ecosystems.
Example: Small software team -| Term | Example | -| ---- | ------- | -| Expectations | Defined by the producer's security personnel and stored in a database. | -| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. | -| Build system certification | The build system implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements. | +| Term | Example +| ---- | ------- +| Expectations | Defined by the producer's security personnel and stored in a database. +| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. +| Build system certification | The build system implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements.
Example: Open source language distribution -| Term | Example | -| ---- | ------- | -| Expectations | Defined separately for each package and stored in the package registry. | -| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. | -| Build system certification | Performed by the language ecosystem packaging authority. | +| Term | Example +| ---- | ------- +| Expectations | Defined separately for each package and stored in the package registry. +| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. +| Build system certification | Performed by the language ecosystem packaging authority.
diff --git a/docs/spec/v1.0-rc2/index.md b/docs/spec/v1.0-rc2/index.md index dd58e34f5..705fe7b74 100644 --- a/docs/spec/v1.0-rc2/index.md +++ b/docs/spec/v1.0-rc2/index.md @@ -19,10 +19,10 @@ levels and recommended attestation formats, including provenance. -| Page | Description | -| ---- | ----------- | +| Page | Description +| ---- | ----------- {%- for child in section.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} | +| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} {%- endfor %} diff --git a/docs/spec/v1.0-rc2/levels.md b/docs/spec/v1.0-rc2/levels.md index 50fa7eb98..230cf19ef 100644 --- a/docs/spec/v1.0-rc2/levels.md +++ b/docs/spec/v1.0-rc2/levels.md @@ -20,12 +20,12 @@ to recognize progress made in one aspect of security without blocking on an unrelated aspect. Tracks also allow the SLSA spec to evolve: we can add more tracks without invalidating previous levels. -| Track/Level | Requirements | Focus | -| ----------- | ------------ | ----- | -| [Build L0] | (none) | (n/a) | -| [Build L1] | Provenance showing how the package was built | Mistakes, documentation | -| [Build L2] | Signed provenance, generated by a hosted build service | Tampering after the build | -| [Build L3] | Hardened build service | Tampering during the build | +| Track/Level | Requirements | Focus +| ----------- | ------------ | ----- +| [Build L0] | (none) | (n/a) +| [Build L1] | Provenance showing how the package was built | Mistakes, documentation +| [Build L2] | Signed provenance, generated by a hosted build service | Tampering after the build +| [Build L3] | Hardened build service | Tampering during the build diff --git a/docs/spec/v1.0-rc2/terminology.md b/docs/spec/v1.0-rc2/terminology.md index 8a3b5a763..18cb6a72d 100644 --- a/docs/spec/v1.0-rc2/terminology.md +++ b/docs/spec/v1.0-rc2/terminology.md @@ -28,14 +28,14 @@ supply chains plus its own sources and builds. ![Software Supply Chain Model](../../images/supply-chain-model.svg) -| Term | Description | Example | -| --- | --- | --- | -| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. | -| Attestation | An authenticated statement (metadata) about a software artifact or collection of software artifacts. | A signed [SLSA Provenance] file. | -| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). | -| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). | -| [Package] | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. | -| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). | +| Term | Description | Example +| --- | --- | --- +| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. +| Attestation | An authenticated statement (metadata) about a software artifact or collection of software artifacts. | A signed [SLSA Provenance] file. +| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). +| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). +| [Package] | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. +| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). [build]: #build-model [package]: #package-model @@ -49,12 +49,12 @@ be filled by more than one person or an organization. Similarly, a person or organization may act as more than one role in a particular software supply chain. -| Role | Description | Examples | -| --- | --- | --- | -| Producer | A party who creates software and provides it to others. Producers are often also consumers. | An open source project's maintainers. A software vendor. | -| Verifier | A party who inspect an artifact's provenance to determine the artifact's authenticity. | A business's software ingestion system. A programming language ecosystem's package registry. | -| Consumer | A party who uses software provided by a producer. The consumer may verify provenance for software they consume or delegate that responsibility to a separate verifier. | A developer who uses open source software distributions. A business that uses a point of sale system. | -| Infrastructure provider | A party who provides software or services to other roles. | A package registry's maintainers. A build system's maintainers. | +| Role | Description | Examples +| --- | --- | --- +| Producer | A party who creates software and provides it to others. Producers are often also consumers. | An open source project's maintainers. A software vendor. +| Verifier | A party who inspect an artifact's provenance to determine the artifact's authenticity. | A business's software ingestion system. A programming language ecosystem's package registry. +| Consumer | A party who uses software provided by a producer. The consumer may verify provenance for software they consume or delegate that responsibility to a separate verifier. | A developer who uses open source software distributions. A business that uses a point of sale system. +| Infrastructure provider | A party who provides software or services to other roles. | A package registry's maintainers. A build system's maintainers. ### Build model @@ -70,19 +70,19 @@ describing this whole process.

Model Build

-| Primary Term | Description | -| --- | --- | -| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations. | -| Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane. | -| Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters. | -| Control plane | Build system component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control. | -| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform. | -| Steps | The set of actions that comprise a build, defined by the tenant. | -| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. | -| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build. | -| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. | -| Outputs | Collection of artifacts produced by the build. | -| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters. | +| Primary Term | Description +| --- | --- +| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations. +| Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane. +| Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters. +| Control plane | Build system component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control. +| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform. +| Steps | The set of actions that comprise a build, defined by the tenant. +| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. +| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build. +| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. +| Outputs | Collection of artifacts produced by the build. +| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters. Notably, there is no formal notion of "source" in the build model, just parameters and dependencies. Most build platforms have an explicit "source" @@ -121,15 +121,15 @@ It is the primary identifier to which consumers attach expectations. [^label]: This resolution might include a version number, label, or some other selector in addition to the package name, but that is not important to SLSA. -| Term | Description | -| ---- | ----------- | -| Package | An identifiable unit of software intended for distribution, ambiguously meaning either an "artifact" or a "package name". Only use this term when the ambiguity is acceptable or desirable. | -| Package artifact | A file or other immutable object that is intended for distribution. | -| Package ecosystem | A set of rules and conventions governing how packages are distributed, including how clients resolve a package name into one or more specific artifacts. | -| Package manager client | Client-side tooling to interact with a package ecosystem. | -| Package name |

The primary identifier for a mutable collection of artifacts that all represent different versions of the same software. This is the primary identifier that consumers use to obtain the software.

A package name is specific to an ecosystem + registry, has a maintainer, is more general than a specific hash or version, and has a "correct" source location. A package ecosystem may group package names into some sort of hierarchy, such as the Group ID in Maven, though SLSA does not have a special term for this. | -| Package registry | An entity responsible for mapping package names to artifacts within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. | -| Publish [a package] | Make an artifact available for use by registering it with the package registry. In technical terms, this means associating an artifact to a package name. This does not necessarily mean making the artifact fully public; an artifact may be published for only a subset of users, such as internal testing or a closed beta. | +| Term | Description +| ---- | ----------- +| Package | An identifiable unit of software intended for distribution, ambiguously meaning either an "artifact" or a "package name". Only use this term when the ambiguity is acceptable or desirable. +| Package artifact | A file or other immutable object that is intended for distribution. +| Package ecosystem | A set of rules and conventions governing how packages are distributed, including how clients resolve a package name into one or more specific artifacts. +| Package manager client | Client-side tooling to interact with a package ecosystem. +| Package name |

The primary identifier for a mutable collection of artifacts that all represent different versions of the same software. This is the primary identifier that consumers use to obtain the software.

A package name is specific to an ecosystem + registry, has a maintainer, is more general than a specific hash or version, and has a "correct" source location. A package ecosystem may group package names into some sort of hierarchy, such as the Group ID in Maven, though SLSA does not have a special term for this. +| Package registry | An entity responsible for mapping package names to artifacts within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. +| Publish [a package] | Make an artifact available for use by registering it with the package registry. In technical terms, this means associating an artifact to a package name. This does not necessarily mean making the artifact fully public; an artifact may be published for only a subset of users, such as internal testing or a closed beta. Ambiguous terms to avoid: @@ -275,31 +275,31 @@ build system the package was built. ![Verification Model](verification-model.svg) -| Term | Description | -|--------------|---- | -| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. | -| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. | -| Build system certification | [Build systems are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. | +| Term | Description +|--------------|---- +| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. +| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. +| Build system certification | [Build systems are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. The examples below suggest some ways that expectations and verification may be implemented for different, broadly defined, package ecosystems.

Example: Small software team -| Term | Example | -| ---- | ------- | -| Expectations | Defined by the producer's security personnel and stored in a database. | -| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. | -| Build system certification | The build system implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements. | +| Term | Example +| ---- | ------- +| Expectations | Defined by the producer's security personnel and stored in a database. +| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. +| Build system certification | The build system implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements.
Example: Open source language distribution -| Term | Example | -| ---- | ------- | -| Expectations | Defined separately for each package and stored in the package registry. | -| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. | -| Build system certification | Performed by the language ecosystem packaging authority. | +| Term | Example +| ---- | ------- +| Expectations | Defined separately for each package and stored in the package registry. +| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. +| Build system certification | Performed by the language ecosystem packaging authority.
diff --git a/docs/spec/v1.0-rc2/verifying-artifacts.md b/docs/spec/v1.0-rc2/verifying-artifacts.md index 1ca529b56..ea220665c 100644 --- a/docs/spec/v1.0-rc2/verifying-artifacts.md +++ b/docs/spec/v1.0-rc2/verifying-artifacts.md @@ -147,12 +147,12 @@ behavior into the package. You SHOULD compare the provenance against expected values for at least the following fields: -| What | Why | -| ---- | --- | -| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended system | -| Canonical source repository | To prevent an adversary from building from an unofficial fork (or other disallowed source) | -| `buildType` | To ensure that `externalParameters` are interpreted as intended | -| `externalParameters` | To prevent an adversary from injecting unofficial behavior | +| What | Why +| ---- | --- +| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended system +| Canonical source repository | To prevent an adversary from building from an unofficial fork (or other disallowed source) +| `buildType` | To ensure that `externalParameters` are interpreted as intended +| `externalParameters` | To prevent an adversary from injecting unofficial behavior Verification tools SHOULD reject unrecognized fields in `externalParameters` to err on the side of caution. It is acceptable to allow a parameter to have a diff --git a/docs/spec/v1.0/index.md b/docs/spec/v1.0/index.md index 53eed0106..26c0e3cab 100644 --- a/docs/spec/v1.0/index.md +++ b/docs/spec/v1.0/index.md @@ -19,10 +19,10 @@ levels and recommended attestation formats, including provenance. -| Page | Description | -| ---- | ----------- | +| Page | Description +| ---- | ----------- {%- for child in section.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} | +| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} {%- endfor %} diff --git a/docs/spec/v1.0/levels.md b/docs/spec/v1.0/levels.md index 028e4882a..11b384b10 100644 --- a/docs/spec/v1.0/levels.md +++ b/docs/spec/v1.0/levels.md @@ -20,12 +20,12 @@ to recognize progress made in one aspect of security without blocking on an unrelated aspect. Tracks also allow the SLSA spec to evolve: we can add more tracks without invalidating previous levels. -| Track/Level | Requirements | Focus | -| ----------- | ------------ | ----- | -| [Build L0] | (none) | (n/a) | -| [Build L1] | Provenance showing how the package was built | Mistakes, documentation | -| [Build L2] | Signed provenance, generated by a hosted build platform | Tampering after the build | -| [Build L3] | Hardened build platform | Tampering during the build | +| Track/Level | Requirements | Focus +| ----------- | ------------ | ----- +| [Build L0] | (none) | (n/a) +| [Build L1] | Provenance showing how the package was built | Mistakes, documentation +| [Build L2] | Signed provenance, generated by a hosted build platform | Tampering after the build +| [Build L3] | Hardened build platform | Tampering during the build diff --git a/docs/spec/v1.0/terminology.md b/docs/spec/v1.0/terminology.md index 49bac91e5..3047e0774 100644 --- a/docs/spec/v1.0/terminology.md +++ b/docs/spec/v1.0/terminology.md @@ -36,14 +36,14 @@ supply chains plus its own sources and builds. ![Software Supply Chain Model](images/supply-chain-model.svg) -| Term | Description | Example | -| --- | --- | --- | -| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. | -| Attestation | An authenticated statement (metadata) about a software artifact or collection of software artifacts. | A signed [SLSA Provenance] file. | -| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). | -| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). | -| [Package] | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. | -| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). | +| Term | Description | Example +| --- | --- | --- +| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. +| Attestation | An authenticated statement (metadata) about a software artifact or collection of software artifacts. | A signed [SLSA Provenance] file. +| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). +| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). +| [Package] | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. +| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). [build]: #build-model [package]: #package-model @@ -57,12 +57,12 @@ be filled by more than one person or an organization. Similarly, a person or organization may act as more than one role in a particular software supply chain. -| Role | Description | Examples | -| --- | --- | --- | -| Producer | A party who creates software and provides it to others. Producers are often also consumers. | An open source project's maintainers. A software vendor. | -| Verifier | A party who inspect an artifact's provenance to determine the artifact's authenticity. | A business's software ingestion system. A programming language ecosystem's package registry. | -| Consumer | A party who uses software provided by a producer. The consumer may verify provenance for software they consume or delegate that responsibility to a separate verifier. | A developer who uses open source software distributions. A business that uses a point of sale system. | -| Infrastructure provider | A party who provides software or services to other roles. | A package registry's maintainers. A build platform's maintainers. | +| Role | Description | Examples +| --- | --- | --- +| Producer | A party who creates software and provides it to others. Producers are often also consumers. | An open source project's maintainers. A software vendor. +| Verifier | A party who inspect an artifact's provenance to determine the artifact's authenticity. | A business's software ingestion system. A programming language ecosystem's package registry. +| Consumer | A party who uses software provided by a producer. The consumer may verify provenance for software they consume or delegate that responsibility to a separate verifier. | A developer who uses open source software distributions. A business that uses a point of sale system. +| Infrastructure provider | A party who provides software or services to other roles. | A package registry's maintainers. A build platform's maintainers. ### Build model @@ -95,20 +95,20 @@ a dependency. For examples of how this model applies to real-world build platforms, see [index of build types](/provenance/v1#index-of-build-types). -| Primary Term | Description | -| --- | --- | -| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations. | -| Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane. | -| Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters. | -| Control plane | Build platform component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control. | -| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform. | -| Steps | The set of actions that comprise a build, defined by the tenant. | -| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. | -| Build caches | An intermediate artifact storage managed by the platform that maps intermediate artifacts to their explicit inputs. A build may share build caches with any subsequent build running on the platform. | -| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build. | -| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. | -| Outputs | Collection of artifacts produced by the build. | -| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters. | +| Primary Term | Description +| --- | --- +| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations. +| Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane. +| Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters. +| Control plane | Build platform component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control. +| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform. +| Steps | The set of actions that comprise a build, defined by the tenant. +| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. +| Build caches | An intermediate artifact storage managed by the platform that maps intermediate artifacts to their explicit inputs. A build may share build caches with any subsequent build running on the platform. +| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build. +| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. +| Outputs | Collection of artifacts produced by the build. +| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters.
Ambiguous terms to avoid @@ -153,15 +153,15 @@ It is the primary identifier to which consumers attach expectations. [^label]: This resolution might include a version number, label, or some other selector in addition to the package name, but that is not important to SLSA. -| Term | Description | -| ---- | ----------- | -| Package | An identifiable unit of software intended for distribution, ambiguously meaning either an "artifact" or a "package name". Only use this term when the ambiguity is acceptable or desirable. | -| Package artifact | A file or other immutable object that is intended for distribution. | -| Package ecosystem | A set of rules and conventions governing how packages are distributed, including how clients resolve a package name into one or more specific artifacts. | -| Package manager client | Client-side tooling to interact with a package ecosystem. | -| Package name |

The primary identifier for a mutable collection of artifacts that all represent different versions of the same software. This is the primary identifier that consumers use to obtain the software.

A package name is specific to an ecosystem + registry, has a maintainer, is more general than a specific hash or version, and has a "correct" source location. A package ecosystem may group package names into some sort of hierarchy, such as the Group ID in Maven, though SLSA does not have a special term for this. | -| Package registry | An entity responsible for mapping package names to artifacts within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. | -| Publish [a package] | Make an artifact available for use by registering it with the package registry. In technical terms, this means associating an artifact to a package name. This does not necessarily mean making the artifact fully public; an artifact may be published for only a subset of users, such as internal testing or a closed beta. | +| Term | Description +| ---- | ----------- +| Package | An identifiable unit of software intended for distribution, ambiguously meaning either an "artifact" or a "package name". Only use this term when the ambiguity is acceptable or desirable. +| Package artifact | A file or other immutable object that is intended for distribution. +| Package ecosystem | A set of rules and conventions governing how packages are distributed, including how clients resolve a package name into one or more specific artifacts. +| Package manager client | Client-side tooling to interact with a package ecosystem. +| Package name |

The primary identifier for a mutable collection of artifacts that all represent different versions of the same software. This is the primary identifier that consumers use to obtain the software.

A package name is specific to an ecosystem + registry, has a maintainer, is more general than a specific hash or version, and has a "correct" source location. A package ecosystem may group package names into some sort of hierarchy, such as the Group ID in Maven, though SLSA does not have a special term for this. +| Package registry | An entity responsible for mapping package names to artifacts within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. +| Publish [a package] | Make an artifact available for use by registering it with the package registry. In technical terms, this means associating an artifact to a package name. This does not necessarily mean making the artifact fully public; an artifact may be published for only a subset of users, such as internal testing or a closed beta.

Ambiguous terms to avoid @@ -309,31 +309,31 @@ build platform the package was built. ![Verification Model](images/verification-model.svg) -| Term | Description | -|--------------|---- | -| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. | -| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. | -| Build platform certification | [Build platforms are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. | +| Term | Description +|--------------|---- +| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. +| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. +| Build platform certification | [Build platforms are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. The examples below suggest some ways that expectations and verification may be implemented for different, broadly defined, package ecosystems.
Example: Small software team -| Term | Example | -| ---- | ------- | -| Expectations | Defined by the producer's security personnel and stored in a database. | -| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. | -| Build platform certification | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements. | +| Term | Example +| ---- | ------- +| Expectations | Defined by the producer's security personnel and stored in a database. +| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. +| Build platform certification | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements.
Example: Open source language distribution -| Term | Example | -| ---- | ------- | -| Expectations | Defined separately for each package and stored in the package registry. | -| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. | -| Build platform certification | Performed by the language ecosystem packaging authority. | +| Term | Example +| ---- | ------- +| Expectations | Defined separately for each package and stored in the package registry. +| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. +| Build platform certification | Performed by the language ecosystem packaging authority.
diff --git a/docs/spec/v1.0/verifying-artifacts.md b/docs/spec/v1.0/verifying-artifacts.md index 826de5507..2e6e7045d 100644 --- a/docs/spec/v1.0/verifying-artifacts.md +++ b/docs/spec/v1.0/verifying-artifacts.md @@ -150,12 +150,12 @@ behavior into the package. You SHOULD compare the provenance against expected values for at least the following fields: -| What | Why | -| ---- | --- | -| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended platform | -| Canonical source repository | To prevent an adversary from building from an unofficial fork (or other disallowed source) | -| `buildType` | To ensure that `externalParameters` are interpreted as intended | -| `externalParameters` | To prevent an adversary from injecting unofficial behavior | +| What | Why +| ---- | --- +| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended platform +| Canonical source repository | To prevent an adversary from building from an unofficial fork (or other disallowed source) +| `buildType` | To ensure that `externalParameters` are interpreted as intended +| `externalParameters` | To prevent an adversary from injecting unofficial behavior Verification tools SHOULD reject unrecognized fields in `externalParameters` to err on the side of caution. It is acceptable to allow a parameter to have a diff --git a/docs/spec/v1.1/index.md b/docs/spec/v1.1/index.md index 9f0783ff8..21b920718 100644 --- a/docs/spec/v1.1/index.md +++ b/docs/spec/v1.1/index.md @@ -19,10 +19,10 @@ levels and recommended attestation formats, including provenance. -| Page | Description | -| ---- | ----------- | +| Page | Description +| ---- | ----------- {%- for child in section.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} | +| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} {%- endfor %} diff --git a/docs/spec/v1.1/levels.md b/docs/spec/v1.1/levels.md index b95f3aed2..93adf66ef 100644 --- a/docs/spec/v1.1/levels.md +++ b/docs/spec/v1.1/levels.md @@ -20,12 +20,12 @@ to recognize progress made in one aspect of security without blocking on an unrelated aspect. Tracks also allow the SLSA spec to evolve: we can add more tracks without invalidating previous levels. -| Track/Level | Requirements | Focus | -| ----------- | ------------ | ----- | -| [Build L0] | (none) | (n/a) | -| [Build L1] | Provenance showing how the package was built | Mistakes, documentation | -| [Build L2] | Signed provenance, generated by a hosted build platform | Tampering after the build | -| [Build L3] | Hardened build platform | Tampering during the build | +| Track/Level | Requirements | Focus +| ----------- | ------------ | ----- +| [Build L0] | (none) | (n/a) +| [Build L1] | Provenance showing how the package was built | Mistakes, documentation +| [Build L2] | Signed provenance, generated by a hosted build platform | Tampering after the build +| [Build L3] | Hardened build platform | Tampering during the build diff --git a/docs/spec/v1.1/terminology.md b/docs/spec/v1.1/terminology.md index 49bac91e5..3047e0774 100644 --- a/docs/spec/v1.1/terminology.md +++ b/docs/spec/v1.1/terminology.md @@ -36,14 +36,14 @@ supply chains plus its own sources and builds. ![Software Supply Chain Model](images/supply-chain-model.svg) -| Term | Description | Example | -| --- | --- | --- | -| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. | -| Attestation | An authenticated statement (metadata) about a software artifact or collection of software artifacts. | A signed [SLSA Provenance] file. | -| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). | -| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). | -| [Package] | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. | -| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). | +| Term | Description | Example +| --- | --- | --- +| Artifact | An immutable blob of data; primarily refers to software, but SLSA can be used for any artifact. | A file, a git commit, a directory of files (serialized in some way), a container image, a firmware image. +| Attestation | An authenticated statement (metadata) about a software artifact or collection of software artifacts. | A signed [SLSA Provenance] file. +| Source | Artifact that was directly authored or reviewed by persons, without modification. It is the beginning of the supply chain; we do not trace the provenance back any further. | Git commit (source) hosted on GitHub (platform). +| [Build] | Process that transforms a set of input artifacts into a set of output artifacts. The inputs may be sources, dependencies, or ephemeral build outputs. | .travis.yml (process) run by Travis CI (platform). +| [Package] | Artifact that is "published" for use by others. In the model, it is always the output of a build process, though that build process can be a no-op. | Docker image (package) distributed on DockerHub (platform). A ZIP file containing source code is a package, not a source, because it is built from some other source, such as a git commit. +| Dependency | Artifact that is an input to a build process but that is not a source. In the model, it is always a package. | Alpine package (package) distributed on Alpine Linux (platform). [build]: #build-model [package]: #package-model @@ -57,12 +57,12 @@ be filled by more than one person or an organization. Similarly, a person or organization may act as more than one role in a particular software supply chain. -| Role | Description | Examples | -| --- | --- | --- | -| Producer | A party who creates software and provides it to others. Producers are often also consumers. | An open source project's maintainers. A software vendor. | -| Verifier | A party who inspect an artifact's provenance to determine the artifact's authenticity. | A business's software ingestion system. A programming language ecosystem's package registry. | -| Consumer | A party who uses software provided by a producer. The consumer may verify provenance for software they consume or delegate that responsibility to a separate verifier. | A developer who uses open source software distributions. A business that uses a point of sale system. | -| Infrastructure provider | A party who provides software or services to other roles. | A package registry's maintainers. A build platform's maintainers. | +| Role | Description | Examples +| --- | --- | --- +| Producer | A party who creates software and provides it to others. Producers are often also consumers. | An open source project's maintainers. A software vendor. +| Verifier | A party who inspect an artifact's provenance to determine the artifact's authenticity. | A business's software ingestion system. A programming language ecosystem's package registry. +| Consumer | A party who uses software provided by a producer. The consumer may verify provenance for software they consume or delegate that responsibility to a separate verifier. | A developer who uses open source software distributions. A business that uses a point of sale system. +| Infrastructure provider | A party who provides software or services to other roles. | A package registry's maintainers. A build platform's maintainers. ### Build model @@ -95,20 +95,20 @@ a dependency. For examples of how this model applies to real-world build platforms, see [index of build types](/provenance/v1#index-of-build-types). -| Primary Term | Description | -| --- | --- | -| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations. | -| Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane. | -| Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters. | -| Control plane | Build platform component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control. | -| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform. | -| Steps | The set of actions that comprise a build, defined by the tenant. | -| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. | -| Build caches | An intermediate artifact storage managed by the platform that maps intermediate artifacts to their explicit inputs. A build may share build caches with any subsequent build running on the platform. | -| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build. | -| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. | -| Outputs | Collection of artifacts produced by the build. | -| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters. | +| Primary Term | Description +| --- | --- +| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations. +| Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane. +| Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters. +| Control plane | Build platform component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control. +| Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform. +| Steps | The set of actions that comprise a build, defined by the tenant. +| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps. +| Build caches | An intermediate artifact storage managed by the platform that maps intermediate artifacts to their explicit inputs. A build may share build caches with any subsequent build running on the platform. +| External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build. +| Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools. +| Outputs | Collection of artifacts produced by the build. +| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters.
Ambiguous terms to avoid @@ -153,15 +153,15 @@ It is the primary identifier to which consumers attach expectations. [^label]: This resolution might include a version number, label, or some other selector in addition to the package name, but that is not important to SLSA. -| Term | Description | -| ---- | ----------- | -| Package | An identifiable unit of software intended for distribution, ambiguously meaning either an "artifact" or a "package name". Only use this term when the ambiguity is acceptable or desirable. | -| Package artifact | A file or other immutable object that is intended for distribution. | -| Package ecosystem | A set of rules and conventions governing how packages are distributed, including how clients resolve a package name into one or more specific artifacts. | -| Package manager client | Client-side tooling to interact with a package ecosystem. | -| Package name |

The primary identifier for a mutable collection of artifacts that all represent different versions of the same software. This is the primary identifier that consumers use to obtain the software.

A package name is specific to an ecosystem + registry, has a maintainer, is more general than a specific hash or version, and has a "correct" source location. A package ecosystem may group package names into some sort of hierarchy, such as the Group ID in Maven, though SLSA does not have a special term for this. | -| Package registry | An entity responsible for mapping package names to artifacts within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. | -| Publish [a package] | Make an artifact available for use by registering it with the package registry. In technical terms, this means associating an artifact to a package name. This does not necessarily mean making the artifact fully public; an artifact may be published for only a subset of users, such as internal testing or a closed beta. | +| Term | Description +| ---- | ----------- +| Package | An identifiable unit of software intended for distribution, ambiguously meaning either an "artifact" or a "package name". Only use this term when the ambiguity is acceptable or desirable. +| Package artifact | A file or other immutable object that is intended for distribution. +| Package ecosystem | A set of rules and conventions governing how packages are distributed, including how clients resolve a package name into one or more specific artifacts. +| Package manager client | Client-side tooling to interact with a package ecosystem. +| Package name |

The primary identifier for a mutable collection of artifacts that all represent different versions of the same software. This is the primary identifier that consumers use to obtain the software.

A package name is specific to an ecosystem + registry, has a maintainer, is more general than a specific hash or version, and has a "correct" source location. A package ecosystem may group package names into some sort of hierarchy, such as the Group ID in Maven, though SLSA does not have a special term for this. +| Package registry | An entity responsible for mapping package names to artifacts within a packaging ecosystem. Most ecosystems support multiple registries, usually a single global registry and multiple private registries. +| Publish [a package] | Make an artifact available for use by registering it with the package registry. In technical terms, this means associating an artifact to a package name. This does not necessarily mean making the artifact fully public; an artifact may be published for only a subset of users, such as internal testing or a closed beta.

Ambiguous terms to avoid @@ -309,31 +309,31 @@ build platform the package was built. ![Verification Model](images/verification-model.svg) -| Term | Description | -|--------------|---- | -| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. | -| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. | -| Build platform certification | [Build platforms are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. | +| Term | Description +|--------------|---- +| Expectations | A set of constraints on the package's provenance metadata. The package producer sets expectations for a package, whether explicitly or implicitly. +| Provenance verification | Artifacts are verified by the package ecosystem to ensure that the package's expectations are met before the package is used. +| Build platform certification | [Build platforms are certified](verifying-systems.md) for their conformance to the SLSA requirements at the stated level. The examples below suggest some ways that expectations and verification may be implemented for different, broadly defined, package ecosystems.
Example: Small software team -| Term | Example | -| ---- | ------- | -| Expectations | Defined by the producer's security personnel and stored in a database. | -| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. | -| Build platform certification | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements. | +| Term | Example +| ---- | ------- +| Expectations | Defined by the producer's security personnel and stored in a database. +| Provenance verification | Performed automatically on cluster nodes before execution by querying the expectations database. +| Build platform certification | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their conformance to SLSA requirements.
Example: Open source language distribution -| Term | Example | -| ---- | ------- | -| Expectations | Defined separately for each package and stored in the package registry. | -| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. | -| Build platform certification | Performed by the language ecosystem packaging authority. | +| Term | Example +| ---- | ------- +| Expectations | Defined separately for each package and stored in the package registry. +| Provenance verification | The language distribution registry verifies newly uploaded packages meet expectations before publishing them. Further, the package manager client also verifies expectations prior to installing packages. +| Build platform certification | Performed by the language ecosystem packaging authority.
diff --git a/docs/spec/v1.1/verifying-artifacts.md b/docs/spec/v1.1/verifying-artifacts.md index 826de5507..2e6e7045d 100644 --- a/docs/spec/v1.1/verifying-artifacts.md +++ b/docs/spec/v1.1/verifying-artifacts.md @@ -150,12 +150,12 @@ behavior into the package. You SHOULD compare the provenance against expected values for at least the following fields: -| What | Why | -| ---- | --- | -| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended platform | -| Canonical source repository | To prevent an adversary from building from an unofficial fork (or other disallowed source) | -| `buildType` | To ensure that `externalParameters` are interpreted as intended | -| `externalParameters` | To prevent an adversary from injecting unofficial behavior | +| What | Why +| ---- | --- +| Builder identity from [Step 1] | To prevent an adversary from building the correct code on an unintended platform +| Canonical source repository | To prevent an adversary from building from an unofficial fork (or other disallowed source) +| `buildType` | To ensure that `externalParameters` are interpreted as intended +| `externalParameters` | To prevent an adversary from injecting unofficial behavior Verification tools SHOULD reject unrecognized fields in `externalParameters` to err on the side of caution. It is acceptable to allow a parameter to have a