diff --git a/.github/workflows/publish-spec.yml b/.github/workflows/publish-spec.yml new file mode 100644 index 000000000..7024f0d67 --- /dev/null +++ b/.github/workflows/publish-spec.yml @@ -0,0 +1,50 @@ +# This workflow publishes the SLSA specification as a GitHub Release when a commit is pushed to a release branch. +# It creates a zip archive of the spec, generates a build provenance attestation, and attaches both to the release. +name: Publish Spec as Release + +on: + push: + branches: + - 'releases/v*.*.*' + +jobs: + publish-spec: + permissions: + attestations: write # Needed to generate and upload build provenance attestations + packages: write # Required for provenance and artifact publishing features + contents: write # Allows creating, deleting, and updating releases and release assets + id-token: write # Grants access to the OIDC token for secure provenance attestation + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Create source artifact + run: | + cd docs + zip -r spec.zip spec + + - name: Set up GitHub CLI + uses: cli/gh-action@v2 + + - name: Generate build provenance attestation + run: | + gh attestation generate build-provenance \ + --repo "$GITHUB_REPOSITORY" \ + --subject-path docs/spec.zip \ + --output docs/spec.attestation.json + + - name: Create or recreate GitHub Release and upload assets + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Determine the release version from the Git ref + VERSION=${GITHUB_REF##*/} + # If a release with this version already exists, delete it to avoid errors + if gh release view "$VERSION" > /dev/null 2>&1; then + gh release delete "$VERSION" --yes + fi + # Create a new release and upload the spec artifact and attestation + gh release create "$VERSION" docs/spec.zip docs/spec.attestation.json \ + --title "Release $VERSION" \ + --notes "This is the release of the spec. The source artifact and attestation are attached." \ No newline at end of file diff --git a/.gitignore b/.gitignore index aa6407894..950527ee3 100644 --- a/.gitignore +++ b/.gitignore @@ -3,9 +3,10 @@ .jekyll-cache .jekyll-metadata .sass-cache -_site node_modules -/docs/vendor/bundle +/www/vendor/bundle +/www/spec +_site # Ignore the following files markdownlint that are already tracked by git (thus # uanffected by gitignore). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 818e6303d..959cf612e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,29 +81,29 @@ VS Code will build the container and configure the development environment autom Once done, you can open a Terminal and launch the development server in the DevContainer with the following command: ```shell -cd docs +cd www +../tools/combine-versions.sh +bundle exec jekyll serve netlify dev -c 'bundle exec jekyll serve --livereload --incremental' ``` ### Deploying the site locally -SLSA.dev is hosted on [Netlify](https://www.netlify.com/), and you can run a local development server using the Netlify CLI. +For detailed instructions on building and testing the site locally, see [www/README.md](www/README.md#building-and-testing-locally). -1. Install the Netlify CLI globally if you haven't already: +Quick start (from the repository root): - ```shell - npm install -g netlify-cli # this will be pre-installed in the DevContainer - ``` +```shell +cd www +../tools/combine-versions.sh +netlify dev +``` -2. `cd` into the `docs` directory -3. Run the following command to start the local development server: +Then browse to http://localhost:8888 to view the site locally. - ```shell - netlify dev - ``` +### Deploying the site in production -4. Open the browser and navigate to http://localhost:8888 -5. Verify that the site is running locally +For detailed instructions on deploying the site in production, see [www/README.md](www/README.md#production). ### Markdown style @@ -192,7 +192,7 @@ approvers for their own PRs. For example, if the author of a PR with the two additional approvers before merging. However, a PR with the `impl` type always requires one reviewer, even if the author has write access. -Note 2: If the PR only touches files in the [Draft](docs/spec-stages.md) +Note 2: If the PR only touches files in the [Draft](www/spec-stages.md) specification stage, then the "waiting period" and "# reviewers" are relaxed and up to Maintainer discretion (including the PR author if they're a maintainer). Note that a relaxed number of reviewers and waiting period may result in more back @@ -303,34 +303,32 @@ in your git config. ## SLSA versions management -The main working draft is located in the `spec/draft` folder while the various versions are in specific folders: +The main working draft is located in the `spec` folder with the various versions in branches a la "releases/v0.1", "releases/v1.0", etc. + +`spec` is where all new work should take place. To publish a new version of the SLSA specification, create a new branch (e.g., `releases/v1.1`) and make the necessary changes to the spec folder on that branch: it is possible for instance that not all that is in the draft should be included in which case you will need to remove that content, and several config and navigation files need to be updated such as: ```none -spec/draft -spec/v0.1 -spec/v0.2 -spec/v1.0 -spec/v1.0-rc1 -spec/v1.0-rc2 -spec/v1.1 +www/_data/nav/config.yml +www/_data/nav/v1.1.yml (corresponding to the version you are creating) +www/_data/versions.yml +www/_redirects ``` -`spec/draft` is where all new work should take place. To publish a new version of the SLSA specification, copy the draft folder to a version specific folder (e.g., `spec/v1.1`) and make the necessary changes to that folder: it is possible for instance that not all that is in the draft should be included in which case you will need to remove that content, and several config and navigation files need to be updated such as: +To patch a specific version of the specification, the changes should be made to both the corresponding branch as well as, if applicable, all the later versions and the draft on the main branch. -```none -_data/nav/config.yml -_data/nav/v1.1.yml (corresponding to the version you are creating) -_data/versions.yml -_redirects -``` +To compare the changes between two versions you may find it handy to use the [diff site script](https://github.com/slsa-framework/slsa/tree/main/www#comparing-built-versions). + +**Note**: When publishing new versions of the SLSA specification, make sure to follow the [Specification stages and versions documentation](www/spec-stages.md) and the [Specification Development Process](https://github.com/slsa-framework/governance/blob/main/5._Governance.md#4-specification-development-process) to ensure compliance with the [Community Specification License](https://github.com/slsa-framework/governance/blob/main/1._Community_Specification_License-v1.md). + +## Netlify and Jekylll -To patch a specific version of the specification, the changes should be made to both the corresponding folder as well as, if applicable, to all later versions including the draft folder. +The website https://slsa.dev is built with Jekyll and served by Netlify where we have an account managed by the Steering Committee. Netlify is setup to monitor the GitHub repository and automatically deploy updates when a PR is merged on main. -Unfortunately we've not figured out a better way to handle the different versions with Jekyll. If you do, please let us know! +The netlify configuration is in the `/netlify.toml` file. This file overrides settings defined on the Netlify admin control panel where we need to say little more than which repository and branch to monitor. -To compare the changes between two versions you may find it handy to use the [diff site script](https://github.com/slsa-framework/slsa/tree/main/docs#comparing-built-versions). +At deployment time, the website is built in several steps. First, we take all the different versions of the spec from the branches and copy them into corresponding `www/spec/` folders. Then, the jekyll build is run to generate the website files in `www/_site` which is then deployed by netlify. -**Note**: When publishing new versions of the SLSA specification, make sure to follow the [Specification stages and versions documentation](docs/spec-stages.md) and the [Specification Development Process](https://github.com/slsa-framework/governance/blob/main/5._Governance.md#4-specification-development-process) to ensure compliance with the [Community Specification License](https://github.com/slsa-framework/governance/blob/main/1._Community_Specification_License-v1.md). +For more information see the [www/README.md](www/README.md) file. ## Workstream lifecycle diff --git a/README.md b/README.md index 2c6212123..b70787071 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # SLSA ("salsa") is Supply-chain Levels for Software Artifacts -The OpenSSF mascot, a goose in armor, strikes a pose wearing a red salsa dress +The OpenSSF mascot, a goose in armor, strikes a pose wearing a red salsa dress SLSA (pronounced ["salsa"](https://www.google.com/search?q=how+to+pronounce+salsa)) is a security framework from source to service, giving anyone working with software a common language for increasing levels of software security and supply chain integrity. It’s how you get from safe enough to being as resilient as possible, at any link in the chain. @@ -10,7 +10,7 @@ See https://slsa.dev to learn about SLSA. ## What's in this repo? -The primary content of this repo is the [docs/](docs/) directory, which contains +The primary content of this repo is the [www/](www/) directory, which contains the core SLSA specification and sources to the [slsa.dev] website. See the README.md in that directory for instructions on how to build the site. @@ -40,7 +40,7 @@ See https://slsa.dev/community for ways to get involved in SLSA development. ## URL Aliases -We have several [redirect](docs/_redirects) configured on slsa.dev for +We have several [redirect](www/_redirects) configured on slsa.dev for convenience of the team: - https://slsa.dev/gh ⇒ SLSA GitHub repo diff --git a/docs/spec/v0.1/attestation-model.md b/docs/spec/v0.1/attestation-model.md deleted file mode 100644 index 7cb104f8c..000000000 --- a/docs/spec/v0.1/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v0.1/faq.md b/docs/spec/v0.1/faq.md deleted file mode 100644 index 313b4c30a..000000000 --- a/docs/spec/v0.1/faq.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Frequently Asked Questions -description: Questions and more information. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA is not transitive in order to make the problem tractable. If SLSA 4 -required dependencies to be SLSA 4, then reaching SLSA 4 would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -For these reasons, SLSA 4 [requires](levels.md#detailed-explanation) reproducible builds -unless there is a justification why the build cannot be made reproducible. -[Example](https://lists.reproducible-builds.org/pipermail/rb-general/2021-January/002177.html) -justifications include profile-guided optimizations or code signing that -invalidates hashes. Note that there is no actual reproduction, just a claim that -reproduction is possible. - -"Verified reproducible" means using two or more independent build systems to -corroborate the provenance of a build. In this way, one can create an overall -system that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a system can -satisfy all of the SLSA build requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. diff --git a/docs/spec/v0.1/images/provenance.dot b/docs/spec/v0.1/images/provenance.dot deleted file mode 100644 index 88d6987ed..000000000 --- a/docs/spec/v0.1/images/provenance.dot +++ /dev/null @@ -1,17 +0,0 @@ -digraph { - node [shape=rect]; - subgraph cluster_external { - label="External Inputs"; - materials; - entryPoint; - arguments; - } - subgraph cluster_system { - label="System Inputs"; - environment; - type; - } - BuildExecution [shape=oval]; - {type, entryPoint, arguments, materials} -> recipe; - {recipe, materials, environment} -> BuildExecution -> subject; -} diff --git a/docs/spec/v0.1/images/provenance.svg b/docs/spec/v0.1/images/provenance.svg deleted file mode 100644 index 2d71cf6da..000000000 --- a/docs/spec/v0.1/images/provenance.svg +++ /dev/null @@ -1,118 +0,0 @@ - - - - - - - - -cluster_external - -External Inputs - - -cluster_system - -System Inputs - - - -materials - -materials - - - -BuildExecution - -BuildExecution - - - -materials->BuildExecution - - - - - -recipe - -recipe - - - -materials->recipe - - - - - -entryPoint - -entryPoint - - - -entryPoint->recipe - - - - - -arguments - -arguments - - - -arguments->recipe - - - - - -environment - -environment - - - -environment->BuildExecution - - - - - -type - -type - - - -type->recipe - - - - - -subject - -subject - - - -BuildExecution->subject - - - - - -recipe->BuildExecution - - - - - diff --git a/docs/spec/v0.1/index.md b/docs/spec/v0.1/index.md deleted file mode 100644 index 10a598079..000000000 --- a/docs/spec/v0.1/index.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Introduction -description: Overview of the SLSA standards and technical controls to improve artifact integrity. -layout: standard -stages: - - 1: - title: Build integrity - text: SLSA starts at the build, the last step before an artifact’s released. This makes sure software’s built from the correct sources and dependencies, and hasn’t been modified. More resilient build integrity means protection from modifying code after source control, compromised build platforms or bypassing CI/CD. - - 2: - title: Source integrity - text: Requirements can then focus on the source. All source code should reflect the intent of the software producer, that code and change history stay available for investigation. More resilient source integrity means better protection from bad code submitted without review or compromised source control systems. - - 3: - title: Dependencies - text: Any other software artifacts fetched during the build process. Once the earlier security checks have been put into place, applying SLSA checks recursively to any dependencies in the system can then be followed up, which helps protect potentially massive attack surfaces against dependency confusion attacks. -levels: - - 1: - title: Basic security steps - text: Level 1 means the supply chain is documented, there’s infrastructure to generate provenance, and systems are prepared for higher SLSA levels. - badge: /images/SLSA-Badge-full-level1.svg - - 2: - title: After the build - text: Level 2 shows more trustworthiness in the build, builders are source-aware, and signatures are used to prevent provenance being tampered with. - badge: /images/SLSA-Badge-full-level2.svg - - 3: - title: Back to source - text: Level 3 shows that a system’s builds are fully trustworthy, build definitions come from the source and a system has more hardened CI. - badge: /images/SLSA-Badge-full-level3.svg - - 4: - title: Across the chain - text: Level 4 means the build environment is fully accounted for, dependencies are tracked in provenance and insider threats are ruled out. - badge: /images/SLSA-Badge-full-level4.svg - -subpages: - - title: Terminology - description: Start here to understand how we model supply chains - relative_url: terminology - - - title: Security levels - description: Ladder of increasing security guarantees - relative_url: levels - - - title: Requirements - description: Technical requirements to reach each level - relative_url: requirements - - - title: Threats & mitigations - description: Specific supply chain attacks and how SLSA helps - relative_url: threats - - - title: FAQs - description: Questions and more information - relative_url: faq ---- - -SLSA is a set of standards and technical controls you can adopt to improve -artifact integrity, and build towards completely resilient systems. It's not a -single tool, but a step-by-step outline to prevent artifacts being tampered with -and tampered artifacts from being used, and at the higher levels, hardening up -the platforms that make up a supply chain. These requirements are explained -below, along with the rest of the essential specifications. - -
- -
-
- -## SLSA 101 - -
-
-
-
-
- -## Supply chain threats - -
-

- Protecting against key threats - -

-
-
-

Supply chain attacks are an ever-present threat, exploiting weakpoints to interfere with software. The SLSA framework establishes three trust boundaries encouraging the right standards, attestation and technical controls, so you can harden a system from these threats and risks.

-
-
-

This means automatic capability to analyse artifacts, guarantee the original source code, protect against interference that can happen in the build and distribution processes, isolate any hidden vulnerabilities and knowing with certainty which system components might be affected.

-
-
-
- supply chain full threats image -
-
-
-
-

- Real world examples -

-
-
-
-

High profile attacks like SolarWinds, Codecov or Linux hypocrite commits exploit the kind of supply chain integrity vulnerabilities which may go unnoticed or be underdeveloped, and quickly become extremely public, disruptive and costly in today’s environment.

-
-
-

Attacks can occur at every link in a typical software supply chain, which puts an extra burden on anyone involved in complex critical systems. SLSA's designed with these examples in mind to make sure they’re common knowledge, and easier to protect against.

-
-
-
-
-
- -
-

Read about threats in detail

-
- -
-
-
-
-

- How it fits into the security ecosystem -

-
-
-
-

There’s more to security than just protection against tampering. From vulnerability management and fuzzing to testing and developer trust, many of these require solutions where effort’s focused on the source. That’s where SLSA complements your wider security efforts, giving you confidence that the code you run is the code you analyzed.

-
-
- How it fits into the security ecosystem image -
-
-
-
- -
- -
-
- -## Security levels - -
-
-
-
-
-

A ladder to the ideal state

-

SLSA’s requirements look at the three general main areas involved in a software artifact’s creation, and where vulnerabilities target - the build, the source, and the dependencies. As the levels scale up, they show that work’s been done to assure there’s more integrity in each area, which can be helpful in scenario planning.

-
-
- SLSA levels badge -
-
-
- {%- for stage in page.stages -%} - {%- assign stage_content = stage | map: stage -%} -
-
-

{{ stage[forloop.index].title}}

-

{{ stage[forloop.index].text}}

-
-
- {%- endfor -%} -
-
- {%- for level in page.levels -%} - {%- assign level_content = level | map: level -%} -
-
-
- {{level[forloop.index].title}} Badge -
-
-

{{level[forloop.index].title}}

-

{{level[forloop.index].text}}

-
-
-
- {%- endfor -%} -
-
-
-
- -
-

Read the level specifications

-
- -
-
-
-
- -
-
- -## Specifications - -
- - -{% include specifications-versions.html %} -
- -
- {%- include specifications-list.html subpages=page.subpages -%} -
-
-
-
diff --git a/docs/spec/v0.1/levels.md b/docs/spec/v0.1/levels.md deleted file mode 100644 index 23268c786..000000000 --- a/docs/spec/v0.1/levels.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Security levels -description: Ladder of increasing security guarantees. ---- - -SLSA is organized into a series of levels that provide increasing -[integrity](terminology.md) guarantees. This gives you confidence that -software hasn’t been tampered with and can be securely traced back to its -source. - -This page is an informative overview of the SLSA levels, describing their -purpose and guarantees. For the normative requirements at each level, see -[Requirements](requirements.md). - -## What is SLSA? - -SLSA is a set of incrementally adoptable security guidelines, established by -industry consensus. The standards set by SLSA are guiding principles for both -software producers and consumers: producers can follow the guidelines to make -their software more secure, and consumers can make decisions based on a software -package's security posture. SLSA's four levels are designed to be incremental -and actionable, and to protect against specific integrity attacks. SLSA 4 -represents the ideal end state, and the lower levels represent milestones with -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 - -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. - -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. - -## Limitations - -SLSA can help reduce supply chain threats in a software artifact, but there are limitations. - -- There are a significant number of dependencies in the supply chain for many artifacts. The full graph of dependencies could be intractably large. -- In practice, a team working on security will need to identify and focus on the important components in a supply chain. This can be performed manually, but the effort could be significant. -- An artifact’s SLSA level is not transitive ([see our FAQs](faq.md)) and dependencies have their own SLSA ratings. This means that it is possible for a SLSA 4 artifact to be built from SLSA 0 dependencies. So, while the main artifact has strong security, risks may still exist elsewhere. The aggregate of these risks will help software consumers understand how and where to use the SLSA 4 artifact. -- While automation of these tasks will help, it isn’t practical for every software consumer to fully vet the entire graph of every artifact. To close this gap, auditors and accreditation bodies could verify and assert that something meets the SLSA requirements. This could be particularly valuable for closed source software. - -As part of our roadmap, we’ll explore how to identify important components, how to determine aggregate risk throughout a supply chain, and the role of accreditation. diff --git a/docs/spec/v0.1/onepage.md b/docs/spec/v0.1/onepage.md deleted file mode 100644 index 83eea0968..000000000 --- a/docs/spec/v0.1/onepage.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: SLSA Specification -description: Description of the SLSA standards and technical controls to improve artifact integrity. -layout: standard -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v0.1/" %} -{% assign filenames = "terminology,levels,requirements,threats,faq" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v0.1/provenance.md b/docs/spec/v0.1/provenance.md deleted file mode 100644 index 56bc6c5cf..000000000 --- a/docs/spec/v0.1/provenance.md +++ /dev/null @@ -1,505 +0,0 @@ ---- -title: Provenance -description: Description of SLSA provenance specification for verifying where, when, and how something was produced. -layout: standard ---- - -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v0.1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe how an artifact or set of artifacts was produced. - -This predicate is the recommended way to satisfy the SLSA [provenance -requirements]. - -## Model - -Provenance is a claim that some entity (`builder`) produced one or more software -artifacts ([Statement]'s `subject`) by executing some `recipe`, using some other -artifacts as input (`materials`). The builder is trusted to have faithfully -recorded the provenance; there is no option but to trust the builder. However, -the builder may have performed this operation at the request of some external, -possibly untrusted entity. These untrusted parameters are captured in the -recipe's `entryPoint`, `arguments`, and some of the `materials`. Finally, the -build may have depended on various environmental parameters (`environment`) that -are needed for [reproducing][reproducible] the build but that are not under -external control. - -See [Example](#example) for a concrete example. - -![Model Diagram](images/provenance.svg) - -## Schema - -```jsonc -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v0.1", - "subject": [{ ... }], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v0.1", - "predicate": { - "builder": { - "id": "" - }, - "recipe": { - "type": "", - "definedInMaterial": /* integer */, - "entryPoint": "", - "arguments": { /* object */ }, - "environment": { /* object */ } - }, - "metadata": { - "buildInvocationId": "", - "buildStartedOn": "", - "buildFinishedOn": "", - "completeness": { - "arguments": true/false, - "environment": true/false, - "materials": true/false - }, - "reproducible": true/false - }, - "materials": [ - { - "uri": "", - "digest": { /* DigestSet */ } - } - ] - } -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`builder` _object, required_ - -> Identifies the entity that executed the recipe, which is trusted to have -> correctly performed the operation and populated this provenance. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgement call. For example, [GitHub Actions] supports -> both GitHub-hosted runners and self-hosted runners. The GitHub-hosted runner -> might be a single identity because, it's all GitHub from the consumer's -> perspective. Meanwhile, each self-hosted runner might have its own identity -> because not all runners are trusted by all consumers. -> -> Consumers MUST accept only specific (signer, builder) pairs. For example, the -> "GitHub" can sign provenance for the "GitHub Actions" builder, and "Google" -> can sign provenance for the "Google Cloud Build" builder, but "GitHub" cannot -> sign for the "Google Cloud Build" builder. -> -> Design rationale: The builder is distinct from the signer because one signer -> may generate attestations for more than one builder, as in the GitHub Actions -> example above. The field is required, even if it is implicit from the signer, -> to aid readability and debugging. It is an object to allow additional fields -> in the future, in case one URI is not sufficient. - - -`builder.id` _string ([TypeURI]), required_ - -> URI indicating the builder's identity. - - -`recipe` _object, optional_ - -> Identifies the configuration used for the build. When combined with -> `materials`, this SHOULD fully describe the build, such that re-running this -> recipe results in bit-for-bit identical output (if the build is -> [reproducible]). -> -> MAY be unset/null if unknown, but this is DISCOURAGED. - - -`recipe.type` _string ([TypeURI]), required_ - -> URI indicating what type of recipe was performed. It determines the meaning of -> `recipe.entryPoint`, `recipe.arguments`, `recipe.environment`, and -> `materials`. - - -`recipe.definedInMaterial` _integer, optional_ - -> Index in `materials` containing the recipe steps that are not implied by -> `recipe.type`. For example, if the recipe type were "make", then this would -> point to the source containing the Makefile, not the `make` program itself. -> -> Omit this field (or use null) if the recipe doesn't come from a material. -> -> TODO: What if there is more than one material? - - -`recipe.entryPoint` _string, optional_ - -> String identifying the entry point into the build. This is often a path to a -> configuration file and/or a target label within that file. The syntax and -> meaning are defined by `recipe.type`. For example, if the recipe type were -> "make", then this would reference the directory in which to run `make` as well -> as which target to use. -> -> Consumers SHOULD accept only specific `recipe.entryPoint` values. For example, -> a policy might only allow the "release" entry point but not the "debug" entry -> point. -> -> MAY be omitted if the recipe type specifies a default value. -> -> Design rationale: The `entryPoint` is distinct from `arguments` to make it -> easier to write secure policies without having to parse `arguments`. - - -`recipe.arguments` _object, optional_ - -> Collection of all external inputs that influenced the build on top of -> `recipe.definedInMaterial` and `recipe.entryPoint`. For example, if the recipe -> type were "make", then this might be the flags passed to `make` aside from the -> target, which is captured in `recipe.entryPoint`. -> -> Consumers SHOULD accept only "safe" `recipe.arguments`. The simplest and -> safest way to achieve this is to disallow any `arguments` altogether. -> -> This is an arbitrary JSON object with a schema is defined by `recipe.type`. -> -> This is considered to be incomplete unless `metadata.completeness.arguments` -> is true. Unset or null is equivalent to empty. - - -`recipe.environment` _object, optional_ - -> Any other builder-controlled inputs necessary for correctly evaluating the -> recipe. Usually only needed for [reproducing][reproducible] the build but not -> evaluated as part of policy. -> -> This SHOULD be minimized to only include things that are part of the public -> API, that cannot be recomputed from other values in the provenance, and that -> actually affect the evaluation of the recipe. For example, this might include -> variables that are referenced in the workflow definition, but it SHOULD NOT -> include a dump of all environment variables or include things like the -> hostname (assuming hostname is not part of the public API). -> -> This is an arbitrary JSON object with a schema is defined by `recipe.type`. -> -> This is considered to be incomplete unless `metadata.completeness.environment` -> is true. Unset or null is equivalent to empty. - - -`metadata` _object, optional_ - -> Other properties of the build. - - -`metadata.buildInvocationId` _string, optional_ - -> Identifies this particular build invocation, which can be useful for finding -> associated logs or other ad-hoc analysis. The exact meaning and format is -> defined by `builder.id`; by default it is treated as opaque and -> case-sensitive. The value SHOULD be globally unique. - - -`metadata.buildStartedOn` _string ([Timestamp]), optional_ - -> The timestamp of when the build started. - - -`metadata.buildFinishedOn` _string ([Timestamp]), optional_ - -> The timestamp of when the build completed. - - -`metadata.completeness` _object, optional_ - -> Indicates that the `builder` claims certain fields in this message to be -> complete. - - -`metadata.completeness.arguments` _boolean, optional_ - -> If true, the `builder` claims that `recipe.arguments` is complete, meaning -> that all external inputs are properly captured in `recipe`. - - -`metadata.completeness.environment` _boolean, optional_ - -> If true, the `builder` claims that `recipe.environment` is claimed to be -> complete. - - -`metadata.completeness.materials` _boolean, optional_ - -> If true, the `builder` claims that `materials` is complete, usually through -> some controls to prevent network access. Sometimes called "hermetic". - - -`metadata.reproducible` _boolean, optional_ - -> If true, the `builder` claims that running `recipe` on `materials` will -> produce bit-for-bit identical output. - - -`materials` _array of objects, optional_ - -> The collection of artifacts that influenced the build including sources, -> dependencies, build tools, base images, and so on. -> -> This is considered to be incomplete unless `metadata.completeness.materials` -> is true. Unset or null is equivalent to empty. - - -`materials[*].uri` _string ([ResourceURI]), optional_ - -> The method by which this artifact was referenced during the build. -> -> TODO: Should we differentiate between the "referenced" URI and the "resolved" -> URI, e.g. "latest" vs "3.4.1"? -> -> TODO: Should wrap in a `locator` object to allow for extensibility, in case we -> add other types of URIs or other non-URI locators? - - -`materials[*].digest` _object ([DigestSet]), optional_ - -> Collection of cryptographic digests for the contents of this artifact. - -## Example - -WARNING: This is just for demonstration purposes. - -Suppose the builder downloaded `example-1.2.3.tar.gz`, extracted it, and ran -`make -C src foo CFLAGS=-O3`, resulting in a file with hash `5678...`. Then the -provenance might look like this: - -```jsonc -{ - "_type": "https://in-toto.io/Statement/v0.1", - // Output file; name is "_" to indicate "not important". - "subject": [{"name": "_", "digest": {"sha256": "5678..."}}], - "predicateType": "https://slsa.dev/provenance/v0.1", - "predicate": { - "builder": { "id": "mailto:person@example.com" }, - "recipe": { - "type": "https://example.com/Makefile", - "definedInMaterial": 0, // material containing the Makefile - "entryPoint": "src:foo", // target "foo" in directory "src" - "arguments": {"CFLAGS": "-O3"} // extra args to `make` - }, - "materials": [{ - "uri": "https://example.com/example-1.2.3.tar.gz", - "digest": {"sha256": "1234..."} - }] - } -} -``` - -## More examples - -### GitHub Actions - -WARNING: This is only for demonstration purposes. The GitHub Actions team has -not yet reviewed or approved this design, and it is not yet implemented. Details -are subject to change! - -If GitHub is the one to generate provenance, and the runner is GitHub-hosted, -then the builder would be as follows: - -```json -"builder": { - "id": "https://github.com/Attestations/GitHubHostedActions@v1" -} -``` - -Self-hosted runner: Not yet supported. We need to figure out a URI scheme that -represents what system hosted the runner, or perhaps add additional properties -in `builder`. - -#### GitHub Actions Workflow - -```jsonc -"recipe": { - // Build steps were defined in a GitHub Actions Workflow file ... - "type": "https://github.com/Attestations/GitHubActionsWorkflow@v1", - // ... in the git repo described by `materials[0]` ... - "definedInMaterial": 0, - // ... at the path .github/workflows/build.yaml, using the job "build". - "entryPoint": "build.yaml:build", - // The only possible user-defined parameters that can affect the build are the - // "inputs" to a workflow_dispatch event. This is unset/null for all other - // events. - "arguments": { - "inputs": { ... } - }, - // Other variables that are required to reproduce the build and that cannot be - // recomputed using existing information. (Documentation would explain how to - // recompute the rest of the fields.) - "environment": { - // The architecture of the runner. - "arch": "amd64", - // Environment variables. These are always set because it is not possible - // to know whether they were referenced or not. - "env": { - "GITHUB_RUN_ID": "1234", - "GITHUB_RUN_NUMBER": "5678", - "GITHUB_EVENT_NAME": "push" - }, - // The context values that were referenced in the workflow definition. - // Secrets are set to the empty string. - "context": { - "github": { - "run_id": "abcd1234" - }, - "runner": { - "os": "Linux", - "temp": "/tmp/tmp.iizj8l0XhS", - } - } - } -} -"materials": [{ - // The git repo that contains the build.yaml referenced above. - "uri": "git+https://github.com/foo/bar.git", - // The resolved git commit hash reflecting the version of the repo used - // for this build. - "digest": {"sha1": "abc..."} -}] -``` - -### Google Cloud Build - -WARNING: This is only for demonstration purposes. The Google Cloud Build team -has not yet reviewed or approved this design, and it is not yet implemented. -Details are subject to change! - -If Google is the one to generate provenance, and the worker is Google-hosted, -then the builder would be as follows: - -```json -"builder": { - "id": "https://cloudbuild.googleapis.com/GoogleHostedWorker@v1" -} -``` - -Custom worker: Not yet supported. We need to figure out a URI scheme that -represents what system hosted the worker, or perhaps add additional properties -in `builder`. - -#### Cloud Build config-as-code - -Here `entryPoint` references the `filename` from the CloudBuild -[BuildTrigger](https://cloud.google.com/build/docs/api/reference/rest/v1/projects.triggers). - -```jsonc -"recipe": { - // Build steps were defined in a cloudbuild.yaml file ... - "type": "https://cloudbuild.googleapis.com/CloudBuildYaml@v1", - // ... in the git repo described by `materials[0]` ... - "definedInMaterial": 0, - // ... at the path path/to/cloudbuild.yaml. - "entryPoint": "path/to/cloudbuild.yaml", - // The only possible user-defined parameters that can affect a BuildTrigger - // are the substitutions in the BuildTrigger. - "arguments": { - "substitutions": {...} - } -} -"materials": [{ - // The git repo that contains the cloudbuild.yaml referenced above. - "uri": "git+https://source.developers.google.com/p/foo/r/bar", - // The resolved git commit hash reflecting the version of the repo used - // for this build. - "digest": {"sha1": "abc..."} -}] -``` - -#### Cloud Build RPC - -Here we list the steps defined in a trigger or over RPC: - -```jsonc -"recipe": { - // Build steps were provided as an argument. No `definedInMaterial` or - // `entryPoint`. - "type": "https://cloudbuild.googleapis.com/CloudBuildSteps@v1", - "arguments": { - // The steps that were performed. (Format TBD.) - "steps": [...], - // The substitutions in the build trigger. - "substitutions": {...} - // TODO: Any other arguments? - } -} -``` - -### Explicitly run commands - -WARNING: This is just a proof-of-concept. It is not yet standardized. - -Execution of arbitrary commands: - -```jsonc -"recipe": { - // There was no entry point, and the commands were run in an ad-hoc fashion. - // There is no `definedInMaterial` or `entryPoint`. - "type": "https://example.com/ManuallyRunCommands@v1", - "arguments": { - // The list of commands that were executed. - "commands": [ - "tar xvf foo-1.2.3.tar.gz", - "cd foo-1.2.3", - "./configure --enable-some-feature", - "make foo.zip" - ], - // Indicates how to parse the strings in `commands`. - "shell": "bash" - } -} -``` - -## Change history - -- Renamed to "slsa.dev/provenance". -- 0.1.1: Added `metadata.buildInvocationId`. -- 0.1: Initial version, named "in-toto.io/Provenance" - -[0.2]: v0.2.md -[DigestSet]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#DigestSet -[GitHub Actions]: #github-actions -[Reproducible]: https://reproducible-builds.org -[ResourceURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#ResourceURI -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#statement -[Timestamp]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#Timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#parsing-rules -[provenance requirements]: requirements#provenance-requirements diff --git a/docs/spec/v0.1/requirements.md b/docs/spec/v0.1/requirements.md deleted file mode 100644 index 4aebdd3b3..000000000 --- a/docs/spec/v0.1/requirements.md +++ /dev/null @@ -1,586 +0,0 @@ ---- -title: Requirements -description: Technical requirements to reach each level. ---- -This page covers all of the technical requirements for an artifact to meet the -[SLSA Levels](levels.md). - -For background, see [Introduction](index.md) and [Terminology](terminology.md). -To better understand the reasoning behind the requirements, see -[Threats and mitigations](threats.md). - -> Reminder: SLSA is in `alpha`. The definitions below are not yet finalized and subject to change, particularly SLSA 3-4. - -## 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] | | | | ✓ - - -_○ = REQUIRED unless there is a justification_ - -[access]: #access -[authenticated]: #authenticated -[available]: #available -[build as code]: #build-as-code -[build service]: #build-service -[dependencies complete]: #dependencies-complete -[ephemeral environment]: #ephemeral-environment -[hermetic]: #hermetic -[isolated]: #isolated -[non-falsifiable]: #non-falsifiable -[parameterless]: #parameterless -[reproducible]: #reproducible -[retained indefinitely]: #retained-indefinitely -[scripted build]: #scripted-build -[security]: #security -[service generated]: #service-generated -[superusers]: #superusers -[two-person reviewed]: #two-person-reviewed -[verified history]: #verified-history -[version controlled]: #version-controlled - -## Definitions - -> See also [Terminology](terminology.md) for general SLSA concepts. The -> definitions below are only used in this document. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -**Immutable reference:** An identifier that is -guaranteed to always point to the same, immutable artifact. This MUST allow the -consumer to locate the artifact and SHOULD include a cryptographic hash of the -artifact's contents to ensure integrity. Examples: git URL + branch/tag/ref \+ -commit ID; cloud storage bucket ID + SHA-256 hash; Subversion URL (no hash). - -[immutable reference]: #immutable-reference -[immutable references]: #immutable-reference - -**Provenance**: Metadata about how an artifact was produced. - -**Revision:** An immutable, coherent state of a source. In Git, for example, a -revision is a commit in the history reachable from a specific branch in a -specific repository. Different revisions within one repo MAY have different -levels. Example: the most recent revision on a branch meets SLSA 4 but very old -historical revisions before the cutoff do not. - -**Strong authentication:** Authentication that maps back to a specific person -using an authentication mechanism which is resistant to account and credential -compromise. For example, 2-factor authentication (2FA) where one factor is a -hardware security key (i.e. YubiKey). - -**Trusted persons:** Set of persons who are granted the authority to maintain a -software project. For example, https://github.com/MarkLodato/dotfiles has just -one trusted person (MarkLodato), while https://hg.mozilla.org/mozilla-central -has a set of trusted persons with write access to the mozilla-central -repository. - -## Source requirements - - - - - - -
RequirementDescriptionL1L2L3L4 -
Version controlled - - -Every change to the source is tracked in a version control system that meets the -following requirements: - -- **[Change history]** There exists a record of the history of changes - that went into the revision. Each change MUST contain: the identities of - the uploader and reviewers (if any), timestamps of the reviews (if any) - and submission, the change description/justification, the content of - the change, and the parent revisions. - -- **\[Immutable reference]** There exists a way to indefinitely reference - this particular, immutable revision. In git, this is the {repo URL + - branch/tag/ref + commit ID}. - -Most popular version control system meet this requirement, such as git, -Mercurial, Subversion, or Perforce. - -NOTE: This does NOT require that the code, uploader/reviewer identities, or -change history be made public. Rather, some organization MUST attest to the fact -that these requirements are met, and it is up to the consumer whether this -attestation is sufficient. - -"○" = RECOMMENDED. - -○✓✓✓ -
Verified history - - -Every change in the revision's history has at least one strongly authenticated -actor identity (author, uploader, reviewer, etc.) and timestamp. It MUST be -clear which identities were verified, and those identities MUST use [two-step -verification](https://www.google.com/landing/2step/) or similar. (Exceptions -noted below.) - -- **[First-parent history]** In the case of a non-linear version control - system, where a revision can have more than one parent, only the "first - parent history" is in scope. In other words, when a feature branch is merged - back into the main branch, only the merge itself is in scope. -- **[Historical cutoff]** There is some TBD exception to allow existing - projects to meet SLSA 3/4 even if historical revisions were present in the - history. Current thinking is that this could be either last N months or a - platform attestation guaranteeing that future changes in the next N months - will meet the requirements. - - ✓✓ -
Retained indefinitely - - -The revision and its change history are preserved indefinitely and cannot be -deleted, except when subject to an established and transparent policy for -obliteration, such as a legal or policy requirement. - -- **[Immutable history]** It MUST NOT be possible for persons to delete or - modify the history, even with multi-party approval, except by trusted - platform admins with two-party approval following the obliterate policy. -- **[Limited retention for SLSA 3]** At SLSA 3 (but not 4), it is acceptable - for the retention to be limited to 18 months, as attested by the source - control platform. - - Example: If a commit is made on 2020-04-05 and then a retention - attestation is generated on 2021-01-01, the commit MUST be retained - until at least 2022-07-01. - - 18 mo.✓ -
Two-person reviewed - - -Every change in the revision's history was agreed to by two trusted persons -prior to submission, and both of these trusted persons were strongly -authenticated. (Exceptions from [Verified History](#verified-history) apply here -as well.) - -- The following combinations are acceptable: - - Uploader and reviewer are two different trusted persons. - - Two different reviewers are trusted persons. -- **[Different persons]** The platform ensures that no person can use - alternate identities to bypass the two-person review requirement. - - Example: if a person uploads with identity X then reviews with alias Y, - the platform understands that this is the same person and does not - consider the review requirement satisfied. -- **[Informed review]** The reviewer is able and encouraged to make an - informed decision about what they're approving. The reviewer SHOULD be - presented with a full, meaningful content diff between the proposed revision - and the previously reviewed revision. For example, it is not sufficient to - just indicate that file changed without showing the contents. -- **[Context-specific approvals]** Approvals are for a specific context, such - as a repo + branch in git. Moving fully reviewed content from one context to - another still requires review. (Exact definition of "context" depends on the - project, and this does not preclude well-understood automatic or reviewless - merges, such as cutting a release branch.) - - Git example: If a fully reviewed commit in one repo is merged into a - different repo, or a commit in one branch is merged into a different - branch, then the merge still requires review. - - ✓ -
- -## Build requirements - -Requirements on build process: - - - - - - - - - - -
RequirementDescriptionL1L2L3L4 -
Scripted build - - -All build steps were fully defined in some sort of "build script". The -only manual command, if any, was to invoke the build script. - -Examples: - -- Build script is Makefile, invoked via `make all`. -- Build script is .github/workflows/build.yaml, invoked by GitHub Actions. - -✓✓✓✓ -
Build service - - -All build steps ran using some build service, not on a developer's -workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓✓ -
Build as code - - -The build definition and configuration executed by the build service is -verifiably derived from text file definitions stored in a version control -system. - -Verifiably derived can mean either fetched directly through a trusted channel, -or that the derived definition has some trustworthy provenance chain linking -back to version control. - -Examples: - -- .github/workflows/build.yaml stored in git -- Tekton bundles generated from text files by a SLSA compliant build process - and stored in an OCI registry with SLSA provenance metadata available. - - ✓✓ -
Ephemeral environment - - -The build service ensured that the build steps ran in an ephemeral environment, -such as a container or VM, provisioned solely for this build, and not reused -from a prior build. - - ✓✓ -
Isolated - - -The build service ensured that the build steps ran in an isolated environment -free of influence from other build instances, whether prior or concurrent. - -- It MUST NOT be possible for a build to access any secrets of the build service, such as the provenance signing key. -- It MUST NOT be possible for two builds that overlap in time to influence one another. -- It MUST NOT be possible for one build to persist or influence the build environment of a subsequent build. -- Build caches, if used, MUST be purely content-addressable to prevent tampering. - - ✓✓ -
Parameterless - - -The build output cannot be affected by user parameters other than the build -entry point and the top-level source location. In other words, the build is -fully defined through the build script and nothing else. - -Examples: - -- GitHub Actions - [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) - `inputs` MUST be empty. -- Google Cloud Build - [user-defined substitutions](https://cloud.google.com/build/docs/configuring-builds/substitute-variable-values) - MUST be empty. (Default substitutions, whose values are defined by the - server, are acceptable.) - - ✓ -
Hermetic - - -All transitive build steps, sources, and dependencies were fully declared up -front with [immutable references], and the build steps ran with no network -access. - -The user-defined build script: - -- MUST declare all dependencies, including sources and other build steps, - using [immutable references] in a format that the build service understands. - -The build service: - -- MUST fetch all artifacts in a trusted control plane. -- MUST NOT allow mutable references. -- MUST verify the integrity of each artifact. - - If the [immutable reference] includes a cryptographic hash, the service - MUST verify the hash and reject the fetch if the verification fails. - - Otherwise, the service MUST fetch the artifact over a channel that - ensures transport integrity, such as TLS or code signing. -- MUST prevent network access while running the build steps. - - This requirement is "best effort." It SHOULD deter a reasonable team - from having a non-hermetic build, but it need not stop a determined - adversary. For example, using a container to prevent network access is - sufficient. - - ✓ -
Reproducible - - -Re-running the build steps with identical input artifacts results in bit-for-bit -identical output. Builds that cannot meet this MUST provide a justification why -the build cannot be made reproducible. - -"○" means that this requirement is "best effort". The user-provided build script -SHOULD declare whether the build is intended to be reproducible or a -justification why not. The build service MAY blindly propagate this intent -without verifying reproducibility. A consumer MAY reject the build if it does -not reproduce. - - ○ -
- -## Provenance requirements - -Requirements on the process by which provenance is generated and consumed: - - - - - - - -
RequirementDescriptionL1L2L3L4 -
Available - - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto [SLSA Provenance], -but another format MAY be used if both producer and consumer agree and it meets -all the other requirements. - -[SLSA Provenance]: ../../provenance - -✓✓✓✓ -
Authenticated - - -The provenance's authenticity and integrity can be verified by the consumer. -This SHOULD be through a digital signature from a private key accessible only to -the service generating the provenance. - - ✓✓✓ -
Service generated - - -The data in the provenance MUST be obtained from the build service (either because -the generator _is_ the build service or because the provenance generator reads the -data directly from the build service). - -Regular users of the service MUST NOT be -able to inject or alter the contents, except as noted below. - -The following provenance fields MAY be generated by the user-controlled build -steps: - -- The output artifact hash from [Identifies Artifact](#identifies-artifact). - - Reasoning: This only allows a "bad" build to falsely claim that it - produced a "good" artifact. This is not a security problem because the - consumer MUST accept only "good" builds and reject "bad" builds. -- The "reproducible" boolean and justification from - [Reproducible](#reproducible). - - ✓✓✓ -
Non-falsifiable - - -Provenance cannot be falsified by the build service's users. - -NOTE: This requirement is a stricter version of [Service Generated](#service-generated). - -- Any secret material used to demonstrate the non-falsifiable nature of - the provenance, for example the signing key used to generate a digital - signature, MUST be stored in a secure management system appropriate for - such material and accessible only to the build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - service in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted below. - -The following provenance fields MAY be generated by the user-controlled build -steps without the build service verifying their correctness: - -- The output artifact hash from [Identifies Artifact](#identifies-artifact). - - Reasoning: This only allows a "bad" build to falsely claim that it - produced a "good" artifact. This is not a security problem because the - consumer MUST accept only "good" builds and reject "bad" builds. -- The "reproducible" boolean and justification from - [Reproducible](#reproducible). - - ✓✓ -
Dependencies complete - - -Provenance records all build dependencies that were available while running the -build steps. This includes the initial state of the machine, VM, or container of -the build worker. - -- MUST include all user-specified build steps, sources, dependencies. -- SHOULD include all service-provided artifacts. - - ✓ -
- -Requirements on the contents of the provenance: - - - - - - - - - - - -
RequirementDescriptionL1L2L3L4 -
Identifies artifact - - -The provenance MUST identify the output artifact via at least one -cryptographic hash. The provenance MAY provide multiple identifying -cryptographic hashes using different algorithms. When only one hash is -provided, the RECOMMENDED algorithm is SHA-256 for cross-system -compatibility. If another algorithm is used, it SHOULD be resistant to -collisions and second preimages. - -✓✓✓✓ -
Identifies builder - - -The provenance identifies the entity that performed the build and generated the -provenance. This represents the entity that the consumer MUST trust. Examples: -"GitHub Actions with a GitHub-hosted worker", "`jdoe@example.com`'s machine". - -✓✓✓✓ -
Identifies build instructions - - -The provenance identifies the top-level instructions used to execute the build. - -The identified instructions SHOULD be at the highest level available to the build -(e.g. if the build is told to run build.sh it SHOULD list build.sh and NOT the -individual instructions in build.sh). - -If build-as-code is used, this SHOULD be the -source repo and entry point of the build config (as in -[the GitHub Actions example](/provenance/v0.2#github-actions)). - -If the build isn't defined in code it MAY list the details of what it was -asked to do (as in -[the Google Cloud Build RPC example](/provenance/v0.2#cloud-build-rpc) -or -[the Explicitly Run Commands example](/provenance/v0.2#explicitly-run-commands)). - -✓✓✓✓ -
Identifies source code - - -The provenance identifies the repository origin(s) for the source code used in -the build. - -The identified repositories SHOULD only include source used directly in the build. -The source of dependencies SHOULD NOT be included. - -At level 2 this information MAY come from users and DOES NOT need to be -authenticated by the builder. - -At level 3+ this information MUST be authenticated by the builder (i.e. the -builder either needs to have fetched the source itself or _observed_ the fetch). - -At level 4 this information MUST be complete (i.e. all source repositories used -in the build are listed). - -✓✓ (Authenticated)✓ (Complete) -
Identifies entry point - - -The provenance identifies the "entry point" of the build definition -(see build-as-code) used to drive the build -including what source repo the configuration was read from. - -Example: - -- source repo: git URL + branch/tag/ref + commit ID -- entrypoint: path to config file(s) (e.g. ./.zuul.yaml) + job name within config (e.g. envoy-build-arm64) - -✓✓ -
Includes all build parameters - - -The provenance includes all build parameters under a user's control. See -[Parameterless](#parameterless) for details. (At L3, the parameters MUST be -listed; at L4, they MUST be empty.) - - ✓✓ -
Includes all transitive dependencies - - -The provenance includes all transitive dependencies listed in -[Dependencies Complete](#dependencies-complete). - - ✓ -
Includes reproducible info - - -The provenance includes a boolean indicating whether build is intended to be -reproducible and, if so, all information necessary to reproduce the build. See -[Reproducible](#reproducible) for more details. - - ✓ -
Includes metadata - - -The provenance includes metadata to aid debugging and investigations. This -SHOULD at least include start and end timestamps and a unique identifier to -allow finding detailed debug logs. - -"○" = RECOMMENDED. - -○○○○ -
- -## Common requirements - -Common requirements for every trusted system involved in the supply chain -(source, build, distribution, etc.) - - - - - -
RequirementDescriptionL1L2L3L4 -
Security - - -The system meets some TBD baseline security standard to prevent compromise. -(Patching, vulnerability scanning, user isolation, transport security, secure -boot, machine identity, etc. Perhaps -[NIST 800-53](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-53r5.pdf) -or a subset thereof.) - - ✓ -
Access - - -All physical and remote access MUST be rare, logged, and gated behind -multi-party approval. - - ✓ -
Superusers - - -Only a small number of platform admins MAY override the guarantees listed here. -Doing so MUST require approval of a second platform admin. - - ✓ -
diff --git a/docs/spec/v0.1/terminology.md b/docs/spec/v0.1/terminology.md deleted file mode 100644 index 4beb6571b..000000000 --- a/docs/spec/v0.1/terminology.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Terminology -description: Start here to understand how we model supply chains. ---- -Before diving into the [SLSA Levels](levels.md), we need to establish a core set -of terminology and models to describe what we're protecting. - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). - -[build]: #build-model - -### Build model - -We model a build as running on a multi-tenant platform, where each execution is -independent. A tenant defines the build, including the input source artifact and -the steps to execute. In response to an external trigger, the platform runs the -build by initializing the environment, fetching the source and possibly some -dependencies, and then starting execution inside the environment. The build then -performs arbitrary steps, possibly fetching additional dependencies, and outputs -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. - -
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 - -[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 -[`steps`]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps -[workflow trigger]: https://docs.github.com/en/actions/using-workflows/triggering-a-workflow - -
- -
Example: Distributed Bazel Builds - -Suppose a [Bazel] build runs on GitHub Actions using Bazel's [remote execution] -feature. Some steps (namely `bazel` itself) run on a GitHub Actions runner while -other steps (Bazel actions) run on a remote execution service. - -In this case, the build's **environment** is the union of the GitHub Actions -runner environment plus the remote execution environment. - -[Bazel]: https://bazel.build -[remote execution]: https://bazel.build/docs/remote-execution - -
- -
Example: Local Builds - -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 - -
diff --git a/docs/spec/v0.1/threats.md b/docs/spec/v0.1/threats.md deleted file mode 100644 index 96e675056..000000000 --- a/docs/spec/v0.1/threats.md +++ /dev/null @@ -1,788 +0,0 @@ ---- -title: Threats and mitigations -description: Specific supply chain attacks and how SLSA helps. ---- -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -SLSA's [levels](levels.md) are designed to mitigate the risk of these attacks. -This page enumerates possible attacks throughout the supply chain and shows how -SLSA can help. For a background, see [Terminology](terminology.md). - -## Summary - -![Supply Chain Threats](../../images/supply-chain-threats.svg) - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that all changes to the source code reflect the -intent of the software producer. Intent of an organization is difficult to -define, so SLSA approximates this as approval from two authorized -representatives. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply-chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - -
-Integrity threat -Known example -How SLSA can help -
A -Submit unauthorized change (to source repo) -Linux hypocrite commits: Researcher attempted to intentionally introduce vulnerabilities into the Linux kernel via patches on the mailing list. -Two-person review caught most, but not all, of the vulnerabilities. -
B -Compromise source repo -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code platform would have been a much harder target for the attackers. -
C -Build from modified source (not matching source repo) -Webmin: Attacker modified the build infrastructure to use source files not matching source control. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
D -Compromise build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA levels require stronger security controls for the build platform, making it more difficult to compromise and gain persistence. -
E -Use compromised dependency (i.e. A-H, recursively) -event-stream: Attacker added an innocuous dependency and then later updated the dependency to add malicious behavior. The update did not match the code submitted to GitHub (i.e. attack F). -Applying SLSA recursively to all dependencies would have prevented this particular vector, because the provenance would have indicated that it either wasn't built from a proper builder or that the source did not come from GitHub. -
F -Upload modified package (not matching build process) -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Compromise package repo -Attacks on Package Mirrors: Researcher ran mirrors for several popular package repositories, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Use compromised package -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
- - - - - - -
-Availability threat -Known example -How SLSA can help -
E -Dependency becomes unavailable -Mimemagic: Maintainer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. - -## Threats in detail - -> **IMPORTANT:** This is a work in progress. - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations in SLSA. The goals are to: - -- Explain the reasons for each of the SLSA [requirements](requirements.md). -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](levels.md) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - -
- -## Source integrity threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes the threat of an authorized developer introducing an unauthorized -change—in other words, an insider threat. - -### (A) Submit unauthorized change - -An adversary introduces a change through the official source control management -interface without any special administrator privileges. - -#### (A1) Submit change without review - -
Directly submit without review (SLSA 4) - -*Threat:* Submit bad code to the source repository without another person -reviewing. - -*Mitigation:* Source repository requires two-person approval for all changes. -[[Two-person reviewed] @ SLSA 4] - -*Example:* Adversary directly pushes a change to a GitHub repo's `main` branch. -Solution: Configure GitHub's "branch protection" feature to require pull request -reviews on the `main` branch. - -
-
Review own change through a sock puppet account (SLSA 4) - -*Threat:* Propose a change using one account and then approve it using another -account. - -*Mitigation:* Source repository requires approval from two different, trusted -persons. If the proposer is trusted, only one approval is needed; otherwise two -approvals are needed. The software producer maps accounts to trusted persons. -[[Two-person reviewed] → Different persons @ SLSA 4] - -*Example:* Adversary creates a pull request using a secondary account and then -approves and merges the pull request using their primary account. Solution: -Configure branch protection to require two approvals and ensure that all -repository contributors and owners map to unique persons. - -
-
Use a robot account to submit change (SLSA 4) - -*Threat:* Exploit a robot account that has the ability to submit changes without -two-person review. - -*Mitigation:* All changes require two-person review, even changes authored by -robots. [[Two-person reviewed] @ SLSA 4] - -*Example:* A file within the source repository is automatically generated by a -robot, which is allowed to submit without review. Adversary compromises the -robot and submits a malicious change without review. Solution: Require human -review for these changes. - -> TODO([#196](https://github.com/slsa-framework/slsa/issues/196)) This solution -> may not be practical. Should there be an exception for locked down robot -> accounts? - -
-
Abuse review exceptions(SLSA 4) - -*Threat:* Exploit a review exception to submit a bad change without review. - -*Mitigation:* All changes require two-person review without exception. -[[Two-person reviewed] @ SLSA 4] - -*Example:* Source repository requires two-person review on all changes except -for "documentation changes," defined as only touching files ending with `.md` or -`.html`. Adversary submits a malicious executable named `evil.md` without review -using this exception, and then builds a malicious package containing this -executable. This would pass the policy because the source repository is correct, -and the source repository does require two-person review. Solution: Do not allow -such exceptions. - -> TODO This solution may not be practical in all circumstances. Are there any -> valid exceptions? If so, how do we ensure they cannot be exploited? - -
- -#### (A2) Evade code review requirements - -
Modify code after review (not required) - -*Threat:* Modify the code after it has been reviewed but before submission. - -*Mitigation:* Source control platform invalidates approvals whenever the -proposed change is modified. [NOT REQUIRED FOR SLSA] - -*Example:* Source repository requires two-person review on all changes. -Adversary sends a "good" pull request to a peer, who approves it. Adversary then -modifies it to contain "bad" code before submitting. Solution: Configure branch -protection to dismiss stale approvals when new changes are pushed. - -> Note: This is not currently a SLSA requirement because the productivity hit is -> considered too great to outweigh the security benefit. The cost of code review -> is already too high for most projects, given current code review tooling, so -> making code review even costlier would not further our goals. However, this -> should be considered for future SLSA revisions once the state-of-the-art for -> code review has improved and the cost can be minimized. - -
-
Submit a change that is unreviewable (SLSA 4) - -*Threat:* Send a change that is meaningless for a human to review that looks -benign but is actually malicious. - -*Mitigation:* Code review system ensures that all reviews are informed and -meaningful. [[Two-person reviewed] → Informed review @ SLSA 4] - -*Example:* A proposed change updates a file, but the reviewer is only presented -with a diff of the cryptographic hash, not of the file contents. Thus, the -reviewer does not have enough context to provide a meaningful review. Solution: -the code review system should present the reviewer with a content diff or some -other information to make an informed decision. - -
-
Copy a reviewed change to another context (SLSA 4) - -*Threat:* Get a change reviewed in one context and then transfer it to a -different context. - -*Mitigation:* Approvals are context-specific. [[Two-person reviewed] -> -Context-specific approvals @ SLSA 4] - -*Example:* MyPackage's source repository requires two-person review. Adversary -forks the repo, submits a change in the fork with review from a colluding -colleague (who is not trusted by MyPackage), then merges the change back into -the upstream repo. Solution: The merge should still require review, even though -the fork was reviewed. - -
-
Compromise another account (SLSA 3) - -*Threat:* Compromise one or more trusted accounts and use those to submit and -review own changes. - -*Mitigation:* Source control platform verifies two-factor authentication, which -increases the difficulty of compromising accounts. [[Verified history] → -strong authentication @ SLSA 3] - -*Example:* Trusted person uses a weak password on GitHub. Adversary guesses the -weak password, logs in, and pushes changes to a GitHub repo. Solution: Configure -GitHub organization to requires 2FA for all trusted persons. This would increase -the difficulty of using the compromised password to log in to GitHub. - -
-
Hide bad change behind good one (SLSA 4) - -*Threat:* Request review for a series of two commits, X and Y, where X is bad -and Y is good. Reviewer thinks they are approving only the final Y state whereas -they are also implicitly approving X. - -*Mitigation:* Only the version that is actually reviewed is the one that is -approved. Any intermediate revisions don't count as being reviewed. -[[Two-person reviewed] @ SLSA 4] - -*Example:* Adversary sends a pull request containing malicious commit X and -benign commit Y that undoes X. In the pull request UI, reviewer only reviews and -approves "changes from all commits", which is a delta from HEAD to Y; they don't -see X. Adversary then builds from the malicious revision X. Solution: Policy -does not accept this because the version X is not considered reviewed. - -> TODO This is implicit but not clearly spelled out in the requirements. We -> should consider clarifying if there is confusion or incorrect implementations. - -
- -#### (A3) Code review bypasses that are out of scope of SLSA - -
Software producer intentionally submits bad code (out of scope) - -*Threat:* Software producer intentionally submits "bad" code, following all -proper processes. - -*Mitigation:* **Outside the scope of SLSA.** Trust of the software producer is -an important but separate property from integrity. - -*Example:* A popular extension author sells the rights to a new owner, who then -modifies the code to secretly mine bitcoin at the users' expense. SLSA does not -protect against this, though if the extension were open source, regular auditing -may discourage this from happening. - -
-
Collude with another trusted person (out of scope) - -*Threat:* Two trusted persons collude to author and approve a bad change. - -*Mitigation:* **Outside the scope of SLSA.** We use "two trusted persons" as a -proxy for "intent of the software producer". - -
-
Trick reviewer into approving bad code (out of scope) - -*Threat:* Construct a change that looks benign but is actually malicious, a.k.a. -"bugdoor." - -*Mitigation:* **Outside the scope of SLSA.** - -
-
Reviewer blindly approves changes (out of scope) - -*Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber -stamping." - -*Mitigation:* **Outside the scope of SLSA.** - -
- -### (B) Compromise source repo - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -
Project owner bypasses or disables controls (SLSA 4) - -*Threat:* Trusted person with "admin" privileges in a repository submits "bad" -code bypassing existing controls. - -*Mitigation:* All persons are subject to same controls, whether or not they have -administrator privileges. Disabling the controls requires two-person review (and -maybe notifies other trusted persons?) [[Two-person reviewed] @ SLSA -4] - -*Example 1:* GitHub project owner pushes a change without review, even though -GitHub branch protection is enabled. Solution: Enable the "Include -Administrators" option for the branch protection. - -*Example 2:* GitHub project owner disables "Include Administrators", pushes a -change without review, then re-enables "Include Administrators". This currently -has no solution on GitHub. - -> TODO This is implicit but not clearly spelled out in the requirements. We -> should consider clarifying since most if not all existing platforms do not -> properly address this threat. - -
-
Platform admin abuses privileges (SLSA 4) - -*Threat:* Platform administrator abuses their privileges to bypass controls or -to push a malicious version of the software. - -*Mitigation:* TBD [[Common requirements] @ SLSA 4] - -*Example 1:* GitHostingService employee uses an internal tool to push changes to -the MyPackage source repo. - -*Example 2:* GitHostingService employee uses an internal tool to push a -malicious version of the server to serve malicious versions of MyPackage sources -to a specific CI/CD client but the regular version to everyone else, in order to -hide tracks. - -*Example 3:* GitHostingService employee uses an internal tool to push a -malicious version of the server that includes a backdoor allowing specific users -to bypass branch protections. Adversary then uses this backdoor to submit a -change to MyPackage without review. - -
-
Exploit vulnerability in SCM (out of scope) - -*Threat:* Exploit a vulnerability in the implementation of the source code -management system to bypass controls. - -*Mitigation:* **Outside the scope of SLSA.** - -
- -## Build integrity threats - -A build integrity threat is a potential for an adversary to introduce behavior -to a package that is not reflected in the source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -### (C) Build from modified source - -An adversary builds from a version of the source code that does not match the -official source control repository. - -
Build from unofficial fork of code (TBD) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Policy requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Policy rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (TBD) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Policy requires that the provenance's source branch/tag matches an -expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Policy rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (TBD) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Policy requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Policy rejects because the build steps did not come from the expected -source. - -
-
Build from unofficial entry point (TBD) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a target or entry point that is not intended for release. - -*Mitigation:* Policy requires that the provenance's build entry point matches an -expected value. - -*Example:* MyPackage is supposed to be built from the `release` workflow. -Adversary builds from the `debug` workflow. Solution: Policy rejects because the -entry point does not match. - -
-
Build from modified version of code modified after checkout (SLSA 3) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build service pulls directly from the source repository and -accurately records the source location in provenance. [[Identifies source -code] @ SLSA 3] - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Policy rejects because the -source repo is not as expected. - -
- -### (D) Compromise build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -
Use build parameter to inject behavior (SLSA 4) - -*Threat:* Build using the expected CI/CD process, source location, branch/tag, -and entry point, but adding a build parameter that injects bad behavior into the -output. - -*Mitigation:* Policy only allows known-safe parameters. At SLSA 4, no parameters -are allowed. [[Parameterless] @ SLSA 4] - -*Example:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Policy rejects because it does not allow any `inputs`. - -
-
Compromise build environment of subsequent build (SLSA 3) - -*Threat:* Perform a "bad" build that persists a change in the build environment, -then run a subsequent "good" build using that environment. - -*Mitigation:* Builder ensures that each build environment is ephemeral, with no -way to persist changes between subsequent builds. [[Ephemeral environment] -@ SLSA 3] - -*Example:* Build service uses the same machine for subsequent builds. Adversary -first runs a build that replaces the `make` binary with a malicious version, -then runs a subsequent build that otherwise would pass the policy. Solution: -Builder changes architecture to start each build with a clean machine image. - -
-
Compromise parallel build (SLSA 3) - -*Threat:* Perform a "bad" build that alters the behavior of another "good" build -running in parallel. - -*Mitigation:* Builds are isolated from one another, with no way for one to -affect the other. [[Isolated] @ SLSA 3] - -*Example:* Build service runs all builds for project MyPackage on the same -machine as the same Linux user. Adversary starts a "bad" build that listens for -the "good" build and swaps out source files, then starts a "good" build that -would otherwise pass the policy. Solution: Builder changes architecture to -isolate each build in a separate VM or similar. - -
-
Steal cryptographic secrets (SLSA 3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build service. - -*Mitigation:* Builds are isolated from the trusted build service control plane, -and only the control plane has access to cryptographic secrets. [[Isolated] -@ SLSA 3] - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Set values of the provenance (SLSA 2) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* Trusted control plane generates all information that goes in the -provenance, except (optionally) the output artifact hash. -[[Service generated] @ SLSA 2] - -*Example:* Provenance is generated on the build worker, which the adversary has -control over. Adversary uses a malicious process to get the build service to -claim that it was built from source repo `good/my-package` when it was really -built from `evil/my-package`. Solution: Builder generates and signs the -provenance in the trusted control plane; the worker reports the output artifacts -but otherwise has no influence over the provenance. - -
-
Poison the build cache (TBD) - -*Threat:* Add a "bad" artifact to a build cache that is later picked up by a -"good" build process. - -*Mitigation:* **TBD** - -*Example:* Build system uses a build cache across builds, keyed by the hash of -the source file. Adversary runs a malicious build that creates a "poisoned" -cache entry with a falsified key, meaning that the value wasn't really produced -from that source. A subsequent build then picks up that poisoned cache entry. - -
-
Project owner (TBD) - -**TODO:** similar to Source (do the same threats apply here?) - -
-
Platform admin (TBD) - -**TODO:** similar to Source - -
- -### (E) Use compromised dependency - -> **TODO:** What exactly is this about? Is it about compromising the build -> process through a bad build tool, and/or is it about compromising the output -> package through a bad library? Does it involve all upstream threats to the -> dependency, or is it just about this particular use of the package (e.g. -> tampering on input, or choosing a bad dependency)? - - - -> **TODO:** Fill this out to give more examples of threats from compromised -> dependencies. - -### (F) Upload modified package - -An adversary uploads a package not built from the proper build process. - -
Build with untrusted CI/CD (TBD) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Policy requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to SLSA 4. Adversary builds on SomeOtherBuildService, which is only -trusted up to SLSA 2, and then exploits SomeOtherBuildService to inject bad -behavior. Solution: Policy rejects because builder is not as expected. - -
-
Upload package without provenance (SLSA 1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Policy requires provenance showing that the package came from the -expected CI/CD pipeline. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Policy rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (SLSA 1) - -*Threat:* Take a good version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Policy requires provenance with a `subject` matching the hash of -the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Policy rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (SLSA 2) - -*Threat:* Perform a build that would not otherwise pass the policy, then modify -the provenance to make the policy checks pass. - -*Mitigation:* Policy only accepts provenance that was cryptographically signed -by the public key corresponding to an acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Policy rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Compromise package repo - -An adversary modifies the package on the package repository using an -administrative interface or through a compromise of the infrastructure. - -**TODO:** fill this out - -### (H) Use compromised package - -An adversary modifies the package after it has left the package repository, or -tricks the user into using an unintended package. - -
Typosquatting (out of scope) - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* **Mostly outside the scope of SLSA.** That said, the requirement -to make the source available can be a mild deterrent, can aid investigation or -ad-hoc analysis, and can complement source-based typosquatting solutions. -[[Verified history] and [Retained indefinitely] @ SLSA 3] - -
- -## Availability threats - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -
(A)(B) Delete the code (SLSA 3) - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* Some system retains the revision and its version control history, -making it available for inspection indefinitely. Users cannot delete the -revision except as part of a transparent legal or privacy process. -[[Retained indefinitely] @ SLSA 3-4] - -*Example:* Adversary submits bad code to the MyPackage GitHub repo, builds from -that revision, then does a force push to erase that revision from history (or -requests GitHub to delete the repo.) This would make the revision unavailable -for inspection. Solution: Policy prevents this by requiring a positive -attestation showing that some system, such as GitHub, ensures retention and -availability. - -
-
(E) A dependency becomes temporarily or permanently unavailable to the build process (out of scope) - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* **Outside the scope of SLSA.** That said, some solutions to support Hermetic and Reproducible builds may also reduce the impact of this threat. -[[Hermetic] [Reproducible] @ SLSA 4] - -
- -## Other threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above but that do not fall cleanly into any one category. - -
Tamper with policy (TBD) - -*Threat:* Modify the policy to accept something that would not otherwise be -accepted. - -*Mitigation:* Policies themselves must meet SLSA 4, including two-party review. - -*Example:* Policy for MyPackage only allows source repo `good/my-package`. -Adversary modifies the policy to also accept `evil/my-package`, then builds from -that repo and uploads a bad version of the package. Solution: Policy changes -require two-party review. - -
-
Forge change metadata (SLSA 3) - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* Source control platform strongly authenticates actor identity, -timestamp, and parent revisions. [[Verified history] @ SLSA 3] - -*Example:* Adversary submits a git commit with a falsified author and timestamp, -and then rewrites history with a non-fast-forward update to make it appear to -have been made long ago. Solution: Consumer detects this by seeing that such -changes are not strongly authenticated and thus not trustworthy. - -
-
Exploit cryptographic hash collisions (TBD) - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Require cryptographically secure hash functions for code review -and provenance, such as SHA-256. - -*Examples:* Construct a "good" file and a "bad" file with the same SHA-1 hash. -Get the "good" file reviewed and then submit the "bad" file, or get the "good" -file reviewed and submitted and then build from the "bad" file. Solution: Only -accept cryptographic hashes with strong collision resistance. - -
- -
- - - -[Access]: requirements.md#access -[Authenticated]: requirements.md#authenticated -[Available]: requirements.md#available -[Build as code]: requirements.md#build-as-code -[Build service]: requirements.md#build-service -[Common requirements]: requirements.md#common-requirements -[Dependencies complete]: requirements.md#dependencies-complete -[Ephemeral environment]: requirements.md#ephemeral-environment -[Hermetic]: requirements.md#hermetic -[Identifies source code]: requirements.md#identifies-source-code -[Isolated]: requirements.md#isolated -[Non-falsifiable]: requirements.md#non-falsifiable -[Parameterless]: requirements.md#parameterless -[Reproducible]: requirements.md#reproducible -[Retained indefinitely]: requirements.md#retained-indefinitely -[Scripted build]: requirements.md#scripted-build -[Security]: requirements.md#security -[Service generated]: requirements.md#service-generated -[Superusers]: requirements.md#superusers -[Two-person reviewed]: requirements.md#two-person-reviewed -[Verified history]: requirements.md#verified-history -[Version controlled]: requirements.md#version-controlled diff --git a/docs/spec/v0.1/use-cases.md b/docs/spec/v0.1/use-cases.md deleted file mode 100644 index d9908ea6d..000000000 --- a/docs/spec/v0.1/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package repository. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build systems rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified from a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v0.1/verification_summary.md b/docs/spec/v0.1/verification_summary.md deleted file mode 100644 index 98964d1f7..000000000 --- a/docs/spec/v0.1/verification_summary.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v0.1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software publishers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [materials](/provenance/v0.2#materials) of the artifact -being verified (recursively) or b) matching the non-source dependency -listed in `materials` (by subject.digest == materials.digest and, ideally, -subject.name == materials.uri) to a VSA _for that dependency_ and using -`vsa.policy_level` and `vsa.dependency_levels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependency_levels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v0.1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v0.1", -"predicate": { - // Required - "verifier": { - "id": "" - }, - "time_verified": , - "policy": { - "uri": "", - "digest": { /* DigestSet */ } - } - "verification_result": "", - "policy_level": "", - "dependency_levels": { - "": , - "": , - ... - } -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`time_verified` _string ([Timestamp]), required_ - -> Timestamp indicating what time the verification occurred. - - -`policy` _object, required_ - -> Describes the policy that was used to verify this artifact. - - -`policy.uri` _string ([ResourceURI]), required_ - -> The URI of the policy used to perform verification. - - -`policy.digest` _object ([DigestSet]), optional_ - -> Collection of cryptographic digests for the contents of the policy used to perform verification. - - -`verification_result` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`policy_level` _string ([SlsaResult]), required_ - -> Indicates what SLSA level the artifact itself (and not its dependencies) was verified at or "FAILED" if policy verification failed. - - -`dependency_levels` _object, required_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v0.1", -"subject": [{ - "name": "https://example.com/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v0.1", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier" - }, - "time_verified": "1985-04-12T23:20:50.52Z", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "verification_result": "PASSED", - "policy_level": "SLSA_LEVEL_3", - "dependency_levels": { - "SLSA_LEVEL_4": 1, - "SLSA_LEVEL_3": 5, - "SLSA_LEVEL_2": 7, - "SLSA_LEVEL_1": 1, - } -} -``` - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -Must be one of these values: - -- SLSA_LEVEL_0 -- SLSA_LEVEL_1 -- SLSA_LEVEL_2 -- SLSA_LEVEL_3 -- SLSA_LEVEL_4 -- FAILED (Indicates policy evaluation failed) - -## Change history - -- 0.1: Initial version. - -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#DigestSet -[ResourceURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#ResourceURI -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#statement -[Timestamp]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#Timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#parsing-rules diff --git a/docs/spec/v0.2/attestation-model.md b/docs/spec/v0.2/attestation-model.md deleted file mode 100644 index 7cb104f8c..000000000 --- a/docs/spec/v0.2/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v0.2/images/provenance.dot b/docs/spec/v0.2/images/provenance.dot deleted file mode 100644 index f1c10d3dc..000000000 --- a/docs/spec/v0.2/images/provenance.dot +++ /dev/null @@ -1,35 +0,0 @@ -digraph { - newrank=true; - { - node [shape=plaintext]; - "External Inputs"; - "System Inputs"; - Evaluate; - Execute; - } - subgraph cluster_invocation { - label="invocation"; - fontname="Courier"; - node [shape=rect, fontname="Courier"]; - configSource; - parameters; - environment; - } - { - rank=same; - node [shape=rect, fontname="Courier"]; - materials; - configSource; - parameters; - environment; - } - { - node [shape=rect, fontname="Courier"]; - buildConfig; - subject; - } - "External Inputs" -> {materials, configSource, parameters} [style=dashed]; - "System Inputs" -> {environment} [style=dashed]; - configSource -> Evaluate -> buildConfig; - {materials, buildConfig, parameters, environment}-> Execute -> subject; -} diff --git a/docs/spec/v0.2/images/provenance.svg b/docs/spec/v0.2/images/provenance.svg deleted file mode 100644 index 3046f4f5a..000000000 --- a/docs/spec/v0.2/images/provenance.svg +++ /dev/null @@ -1,139 +0,0 @@ - - - - - - - - -cluster_invocation - -invocation - - - -External Inputs -External Inputs - - - -configSource - -configSource - - - -External Inputs->configSource - - - - - -parameters - -parameters - - - -External Inputs->parameters - - - - - -materials - -materials - - - -External Inputs->materials - - - - - -System Inputs -System Inputs - - - -environment - -environment - - - -System Inputs->environment - - - - - -Evaluate -Evaluate - - - -buildConfig - -buildConfig - - - -Evaluate->buildConfig - - - - - -Execute -Execute - - - -subject - -subject - - - -Execute->subject - - - - - -configSource->Evaluate - - - - - -parameters->Execute - - - - - -environment->Execute - - - - - -materials->Execute - - - - - -buildConfig->Execute - - - - - diff --git a/docs/spec/v0.2/provenance.md b/docs/spec/v0.2/provenance.md deleted file mode 100644 index 080125314..000000000 --- a/docs/spec/v0.2/provenance.md +++ /dev/null @@ -1,645 +0,0 @@ ---- -title: Provenance -description: Description of SLSA provenance specification for verifying where, when, and how something was produced. -layout: standard ---- - -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v0.2" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe how an artifact or set of artifacts was produced. - -This predicate is the recommended way to satisfy the SLSA [provenance -requirements]. - -## Model - -Provenance is an attestation that some entity (`builder`) produced one or more -software artifacts (the `subject` of an in-toto attestation [Statement]) by -executing some `invocation`, using some other artifacts as input (`materials`). -The invocation in turn runs the `buildConfig`, which is a record of what was -executed. The builder is trusted to have faithfully recorded the provenance; -there is no option but to trust the builder. However, the builder may have -performed this operation at the request of some external, possibly untrusted -entity. These untrusted parameters are captured in the invocation's `parameters` -and some of the `materials`. Finally, the build may have depended on various -environmental parameters (`environment`) that are needed for -[reproducing][reproducible] the build but that are not under external control. - -See [Example](#example) for a concrete example. - -![Model Diagram](images/provenance.svg) - -## Schema - -```jsonc -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v0.1", - "subject": [{ ... }], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v0.2", - "predicate": { - "builder": { - "id": "" - }, - "buildType": "", - "invocation": { - "configSource": { - "uri": "", - "digest": { /* DigestSet */ }, - "entryPoint": "" - }, - "parameters": { /* object */ }, - "environment": { /* object */ } - }, - "buildConfig": { /* object */ }, - "metadata": { - "buildInvocationId": "", - "buildStartedOn": "", - "buildFinishedOn": "", - "completeness": { - "parameters": true/false, - "environment": true/false, - "materials": true/false - }, - "reproducible": true/false - }, - "materials": [ - { - "uri": "", - "digest": { /* DigestSet */ } - } - ] - } -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. -- Optional fields MAY be unset or null, and should be treated equivalently. - Both are equivalent to empty for _object_ or _array_ values. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`builder` _object, required_ - -> Identifies the entity that executed the invocation, which is trusted to have -> correctly performed the operation and populated this provenance. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgement call. For example, [GitHub Actions] supports -> both GitHub-hosted runners and self-hosted runners. The GitHub-hosted runner -> might be a single identity because it's all GitHub from the consumer's -> perspective. Meanwhile, each self-hosted runner might have its own identity -> because not all runners are trusted by all consumers. -> -> Consumers MUST accept only specific (signer, builder) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" builder, and "Google" -> can sign provenance for the "Google Cloud Build" builder, but "GitHub" cannot -> sign for the "Google Cloud Build" builder. -> -> Design rationale: The builder is distinct from the signer because one signer -> may generate attestations for more than one builder, as in the GitHub Actions -> example above. The field is required, even if it is implicit from the signer, -> to aid readability and debugging. It is an object to allow additional fields -> in the future, in case one URI is not sufficient. - - -`builder.id` _string ([TypeURI]), required_ - -> URI indicating the builder's identity. - - -`buildType` _string ([TypeURI]), required_ - -> URI indicating what type of build was performed. It determines the meaning of -> `invocation`, `buildConfig` and `materials`. - - -`invocation` _object, optional_ - -> Identifies the event that kicked off the build. When combined with -> `materials`, this SHOULD fully describe the build, such that re-running this -> invocation results in bit-for-bit identical output (if the build is -> [reproducible]). -> -> MAY be unset/null if unknown, but this is DISCOURAGED. - - -`invocation.configSource` _object, optional_ - -> Describes where the config file that kicked off the build came from. -> This is effectively a pointer to the source where `buildConfig` came from. - - -`invocation.configSource.uri` _string ([ResourceURI]), optional_ - -> URI indicating the identity of the source of the config. - - -`invocation.configSource.digest` _object ([DigestSet]), optional_ - -> Collection of cryptographic digests for the contents of the artifact -> specified by `invocation.configSource.uri`. - - -`invocation.configSource.entryPoint` _string, optional_ - -> String identifying the entry point into the build. This is often a path to a -> configuration file and/or a target label within that file. The syntax and -> meaning are defined by `buildType`. For example, if the `buildType` were -> "make", then this would reference the directory in which to run `make` as well -> as which target to use. -> -> Consumers SHOULD accept only specific `invocation.entryPoint` values. For example, -> a policy might only allow the "release" entry point but not the "debug" entry -> point. -> -> MAY be omitted if the `buildType` specifies a default value. -> -> Design rationale: The `entryPoint` is distinct from `parameters` to make it -> easier to write secure policies without having to parse `parameters`. - - -`invocation.parameters` _object, optional_ - -> Collection of all external inputs that influenced the build on top of -> `invocation.configSource`. For example, if the invocation -> type were "make", then this might be the flags passed to `make` aside from the -> target, which is captured in `invocation.configSource.entryPoint`. -> -> Consumers SHOULD accept only "safe" `invocation.parameters`. The simplest and -> safest way to achieve this is to disallow any `parameters` altogether. -> -> This is an arbitrary JSON object with a schema defined by `buildType`. -> -> This is considered to be incomplete unless `metadata.completeness.parameters` -> is true. - - -`invocation.environment` _object, optional_ - -> Any other builder-controlled inputs necessary for correctly evaluating the -> build. Usually only needed for [reproducing][reproducible] the build but not -> evaluated as part of policy. -> -> This SHOULD be minimized to only include things that are part of the public -> API, that cannot be recomputed from other values in the provenance, and that -> actually affect the evaluation of the build. For example, this might include -> variables that are referenced in the workflow definition, but it SHOULD NOT -> include a dump of all environment variables or include things like the -> hostname (assuming hostname is not part of the public API). -> -> This is an arbitrary JSON object with a schema defined by `buildType`. -> -> This is considered to be incomplete unless `metadata.completeness.environment` -> is true. - - -`metadata` _object, optional_ - -> Other properties of the build. - - -`metadata.buildInvocationId` _string, optional_ - -> Identifies this particular build invocation, which can be useful for finding -> associated logs or other ad-hoc analysis. The exact meaning and format is -> defined by `builder.id`; by default it is treated as opaque and -> case-sensitive. The value SHOULD be globally unique. - - -`metadata.buildStartedOn` _string ([Timestamp]), optional_ - -> The timestamp of when the build started. - - -`metadata.buildFinishedOn` _string ([Timestamp]), optional_ - -> The timestamp of when the build completed. - - -`metadata.completeness` _object, optional_ - -> Indicates that the `builder` claims certain fields in this message to be -> complete. - - -`metadata.completeness.parameters` _boolean, optional_ - -> If true, the `builder` claims that `invocation.parameters` is complete, meaning -> that all external inputs are properly captured in `invocation.parameters`. - - -`metadata.completeness.environment` _boolean, optional_ - -> If true, the `builder` claims that `invocation.environment` is complete. - - -`metadata.completeness.materials` _boolean, optional_ - -> If true, the `builder` claims that `materials` is complete, usually through -> some controls to prevent network access. Sometimes called "hermetic". - - -`metadata.reproducible` _boolean, optional_ - -> If true, the `builder` claims that running `invocation` on `materials` will -> produce bit-for-bit identical output. - - -`buildConfig` _object, optional_ - -> Lists the steps in the build. -> If `invocation.configSource` is not available, `buildConfig` can be used -> to verify information about the build. -> -> This is an arbitrary JSON object with a schema defined by `buildType`. - - -`materials` _array of objects, optional_ - -> The collection of artifacts that influenced the build including sources, -> dependencies, build tools, base images, and so on. -> -> This is considered to be incomplete unless `metadata.completeness.materials` -> is true. - - -`materials[*].uri` _string ([ResourceURI]), optional_ - -> The method by which this artifact was referenced during the build. -> -> TODO: Should we differentiate between the "referenced" URI and the "resolved" -> URI, e.g. "latest" vs "3.4.1"? -> -> TODO: Should wrap in a `locator` object to allow for extensibility, in case we -> add other types of URIs or other non-URI locators? - - -`materials[*].digest` _object ([DigestSet]), optional_ - -> Collection of cryptographic digests for the contents of this artifact. - -## Example - -WARNING: This is just for demonstration purposes. - -Suppose the builder downloaded `example-1.2.3.tar.gz`, extracted it, and ran -`make -C src foo CFLAGS=-O3`, resulting in a file with hash `5678...`. Then the -provenance might look like this: - -```jsonc -{ - "_type": "https://in-toto.io/Statement/v0.1", - // Output file; name is "_" to indicate "not important". - "subject": [{"name": "_", "digest": {"sha256": "5678..."}}], - "predicateType": "https://slsa.dev/provenance/v0.2", - "predicate": { - "buildType": "https://example.com/Makefile", - "builder": { "id": "mailto:person@example.com" }, - "invocation": { - "configSource": { - "uri": "https://example.com/example-1.2.3.tar.gz", - "digest": {"sha256": "1234..."}, - "entryPoint": "src:foo", // target "foo" in directory "src" - }, - "parameters": {"CFLAGS": "-O3"} // extra args to `make` - }, - "materials": [{ - "uri": "https://example.com/example-1.2.3.tar.gz", - "digest": {"sha256": "1234..."} - }] - } -} -``` - -## More examples - -### GitHub Actions - -WARNING: This is only for demonstration purposes. The GitHub Actions team has -not yet reviewed or approved this design, and it is not yet implemented. Details -are subject to change! - -If GitHub is the one to generate provenance, and the runner is GitHub-hosted, -then the builder would be as follows: - -```json -"builder": { - "id": "https://github.com/Attestations/GitHubHostedActions@v1" -} -``` - -Self-hosted runner: Not yet supported. We need to figure out a URI scheme that -represents what system hosted the runner, or perhaps add additional properties -in `builder`. - -#### GitHub Actions Workflow - -```jsonc -"buildType": "https://github.com/Attestations/GitHubActionsWorkflow@v1", -"invocation": { - "configSource": { - "entryPoint": "build.yaml:build", - // The git repo that contains the build.yaml referenced in the entrypoint. - "uri": "git+https://github.com/foo/bar.git", - // The resolved git commit hash reflecting the version of the repo used - // for this build. - "digest": {"sha1": "abc..."} - }, - // The only possible user-defined parameters that can affect the build are the - // "inputs" to a workflow_dispatch event. This is unset/null for all other - // events. - "parameters": { - "inputs": { ... } - }, - // Other variables that are required to reproduce the build and that cannot be - // recomputed using existing information. (Documentation would explain how to - // recompute the rest of the fields.) - "environment": { - // The architecture of the runner. - "arch": "amd64", - // Environment variables. These are always set because it is not possible - // to know whether they were referenced or not. - "env": { - "GITHUB_RUN_ID": "1234", - "GITHUB_RUN_NUMBER": "5678", - "GITHUB_EVENT_NAME": "push" - }, - // The context values that were referenced in the workflow definition. - // Secrets are set to the empty string. - "context": { - "github": { - "run_id": "abcd1234" - }, - "runner": { - "os": "Linux", - "temp": "/tmp/tmp.iizj8l0XhS", - } - } - } -} -"materials": [{ - // The git repo that contains the build.yaml referenced above. - "uri": "git+https://github.com/foo/bar.git", - // The resolved git commit hash reflecting the version of the repo used - // for this build. - "digest": {"sha1": "abc..."} -}] -``` - -### GitLab CI - -The GitLab CI team has implemented an [artifact attestation](https://docs.gitlab.com/ee/ci/runners/configure_runners.html#artifact-attestation) capability in their GitLab Runner 15.1 release. - -If GitLab is the one to generate provenance, and the runner is GitLab-hosted or self-hosted, -then the builder would be as follows: - -```jsonc -"builder": { - "id": "https://gitlab.com/foo/bar/-/runners/12345678" -} -``` - -#### GitLab CI Job - -```jsonc -"buildType": "https://gitlab.com/gitlab-org/gitlab-runner/-/blob/v15.1.0/PROVENANCE.md", -"invocation": { - "configSource": { - // the git repo that contains the GitLab CI job referenced in the entrypoint - "uri": "https://gitlab.com//foo/bar", - // The resolved git commit hash reflecting the version of the repo used - // for this build. - "digest": { - "sha256": "abc..." - }, - // the name of the CI job that triggered the build - "entryPoint": "build" - }, - // Other variables that are required to reproduce the build and that cannot be - // recomputed using existing information. (Documentation would explain how to - // recompute the rest of the fields.) - "environment": { - // Name of the GitLab runner - "name": "hosted-gitlab-runner", - // The runner executor - "executor": "kubernetes", - // The architecture on which the CI job is run - "architecture": "amd64" - }, - // Collection of all external inputs (CI variables) related to the job - "parameters": { - "CI_PIPELINE_ID": "", - "CI_PIPELINE_URL": "", - // All other CI variable names are listed here. Values are always represented as empty strings to avoid leaking secrets. - } -}, -"metadata": { - "buildStartedOn": "2022-06-17T00:47:27+03:00", - "buildFinishedOn": "2022-06-17T00:47:28+03:00", - "completeness": { - "parameters": true, - "environment": true, - "materials": false - }, - "reproducible": false -} -``` - -### Google Cloud Build - -WARNING: This is only for demonstration purposes. The Google Cloud Build team -has not yet reviewed or approved this design, and it is not yet implemented. -Details are subject to change! - -If Google is the one to generate provenance, and the worker is Google-hosted, -then the builder would be as follows: - -```json -"builder": { - "id": "https://cloudbuild.googleapis.com/GoogleHostedWorker@v1" -} -``` - -Custom worker: Not yet supported. We need to figure out a URI scheme that -represents what system hosted the worker, or perhaps add additional properties -in `builder`. - -#### Cloud Build config-as-code - -Here `entryPoint` references the `filename` from the CloudBuild -[BuildTrigger](https://cloud.google.com/build/docs/api/reference/rest/v1/projects.triggers). - -```jsonc -"buildType": "https://cloudbuild.googleapis.com/CloudBuildYaml@v1", -"invocation": { - // ... in the git repo described by `materials[0]` ... - "configSource": { - "entryPoint": "path/to/cloudbuild.yaml", - // The git repo that contains the cloudbuild.yaml referenced above. - "uri": "git+https://source.developers.google.com/p/foo/r/bar", - // The resolved git commit hash reflecting the version of the repo used - // for this build. - "digest": {"sha1": "abc..."} - }, - // The only possible user-defined parameters that can affect a BuildTrigger - // are the substitutions in the BuildTrigger. - "parameters": { - "substitutions": {...} - } -} -"buildConfig": { - // each step in the recipe corresponds to a step in the cloudbuild.yaml - // the format of this is determined by `buildType` - "steps": [ - { - "image": "pkg:docker/make@sha256:244fd47e07d1004f0aed9c", - "arguments": ["build"] - } - ] -} -"materials": [{ - // The git repo that contains the cloudbuild.yaml referenced above. - "uri": "git+https://source.developers.google.com/p/foo/r/bar", - // The resolved git commit hash reflecting the version of the repo used - // for this build. - "digest": {"sha1": "abc..."} -}] -``` - -#### Cloud Build RPC - -Here we list the steps defined in a trigger or over RPC: - -```jsonc -"buildType": "https://cloudbuild.googleapis.com/CloudBuildSteps@v1", -"invocation": { - // Build steps were provided as an argument. No `configSource` - "parameters": { - // The substitutions in the build trigger. - "substitutions": {...} - // TODO: Any other arguments? - } -} -"buildConfig": { - // The steps that were performed. (Format TBD.) - "steps": [...] -} -``` - -### Explicitly run commands - -WARNING: This is just a proof-of-concept. It is not yet standardized. - -Execution of arbitrary commands: - -```jsonc -"buildType": "https://example.com/ManuallyRunCommands@v1", -// There was no entry point, and the commands were run in an ad-hoc fashion. -// There is no `configSource`. -"invocation": null, -"buildConfig": { - // The list of commands that were executed. - "commands": [ - "tar xvf foo-1.2.3.tar.gz", - "cd foo-1.2.3", - "./configure --enable-some-feature", - "make foo.zip" - ], - // Indicates how to parse the strings in `commands`. - "shell": "bash" -} -``` - -## Migrating from 0.1 - -To migrate from [version 0.1][0.1] (`old`): - -```javascript -{ - "builder": old.builder, // (unchanged) - "buildType": old.recipe.type, - "invocation": { - "configSource": { - "uri": old.materials[old.recipe.definedInMaterial].uri, - "digest": old.materials[old.recipe.definedInMaterial].digest, - "entrypoint": old.recipe.entryPoint - }, - "parameters": old.recipe.arguments, - "environment": old.recipe.environment // (unchanged) - }, - "buildConfig": null, // no equivalent in 0.1 - "metadata": { - "buildInvocationId": old.metadata.buildInvocationId, // (unchanged) - "buildStartedOn": old.metadata.buildStartedOn, // (unchanged) - "buildFinishedOn": old.metadata.buildFinishedOn, // (unchanged) - "completeness": { - "parameters": old.metadata.completeness.arguments, - "environment": old.metadata.completeness.environment, // (unchanged) - "materials": old.metadata.completeness.materials, // (unchanged) - }, - "reproducible": old.metadata.reproducible // (unchanged) - }, - "materials": old.materials // optionally removing the configSource -} -``` - -## Change history - -- 0.2: Refactored to aid clarity and added `buildConfig`. The model is - unchanged. - - Replaced `definedInMaterial` and `entryPoint` with `configSource`. - - Renamed `recipe` to `invocation`. - - Moved `invocation.type` to top-level `buildType`. - - Renamed `arguments` to `parameters`. - - Added `buildConfig`, which can be used as an alternative to - `configSource` to validate the configuration. -- Renamed to "slsa.dev/provenance". -- 0.1.1: Added `metadata.buildInvocationId`. -- 0.1: Initial version, named "in-toto.io/Provenance" - -[0.1]: /provenance/v0.1 -[DigestSet]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#DigestSet -[GitHub Actions]: #github-actions -[Reproducible]: https://reproducible-builds.org -[ResourceURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#ResourceURI -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#statement -[Timestamp]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#Timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#parsing-rules -[provenance requirements]: ../v0.1/requirements#provenance-requirements diff --git a/docs/spec/v0.2/verification_summary.md b/docs/spec/v0.2/verification_summary.md deleted file mode 100644 index 1746022a5..000000000 --- a/docs/spec/v0.2/verification_summary.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v0.2" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software publishers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [materials](/provenance/v0.2#materials) of the artifact -being verified (recursively) or b) matching the non-source dependency -listed in `materials` (by `subject.digest` == `materials.digest` and, ideally, -`vsa.resource_uri` == `materials.uri`) to a VSA _for that dependency_ and using -`vsa.policy_level` and `vsa.dependency_levels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependency_levels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v0.1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v0.2", -"predicate": { - // Required - "verifier": { - "id": "" - }, - "time_verified": , - "resource_uri": , - "policy": { - "uri": "", - "digest": { /* DigestSet */ } - } - "input_attestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verification_result": "", - "policy_level": "", - "dependency_levels": { - "": , - "": , - ... - } -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`time_verified` _string ([Timestamp]), required_ - -> Timestamp indicating what time the verification occurred. - - -`resource_uri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. - - -`policy` _object, required_ - -> Describes the policy that was used to verify this artifact. - - -`policy.uri` _string ([ResourceURI]), required_ - -> The URI of the policy used to perform verification. - - -`policy.digest` _object ([DigestSet]), optional_ - -> Collection of cryptographic digests for the contents of the policy used to perform verification. - - -`input_attestations` _object, optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `materials` field in the [SLSA Provenance](/provenance). -> -> This field can be absent if the verifier does not support this feature; -> If present, this field must contain information on _all_ the attestations -> used to perform verification. -> An empty collection indicates the decision was made without attestations. - - -`input_attestations[*].uri` _string ([ResourceURI]), optional_ - -> A URI that can be used (provided the requester has read permission) to fetch -> the attestation. -> -> An absent field indicates the verifier does not know where to fetch the attestation -> (e.g. it was supplied by the verification requester). -> -> The data fetched from the URI may contain more than one attestation (e.g. an -> attestation bundle file). In that case, the attestation is identified by -> `digest` field values. - - -`input_attestations[*].digest` _object ([DigestSet]), required_ - -> Collection of cryptographic digests for this attestation. - - -`verification_result` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`policy_level` _string ([SlsaResult]), required_ - -> Indicates what SLSA level the artifact itself (and not its dependencies) was verified at or "FAILED" if policy verification failed. - - -`dependency_levels` _object, required_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v0.1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v0.2", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier" - }, - "time_verified": "1985-04-12T23:20:50.52Z", - "resource_uri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "input_attestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verification_result": "PASSED", - "policy_level": "SLSA_LEVEL_3", - "dependency_levels": { - "SLSA_LEVEL_4": 1, - "SLSA_LEVEL_3": 5, - "SLSA_LEVEL_2": 7, - "SLSA_LEVEL_1": 1, - } -} -``` - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -Must be one of these values: - -- SLSA_LEVEL_0 -- SLSA_LEVEL_1 -- SLSA_LEVEL_2 -- SLSA_LEVEL_3 -- SLSA_LEVEL_4 -- FAILED (Indicates policy evaluation failed) - -## Change history - -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#DigestSet -[ResourceURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#ResourceURI -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#statement -[Timestamp]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#Timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#parsing-rules diff --git a/docs/spec/v1.0-rc1/attestation-model.md b/docs/spec/v1.0-rc1/attestation-model.md deleted file mode 100644 index 7cb104f8c..000000000 --- a/docs/spec/v1.0-rc1/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.0-rc1/build-model.svg b/docs/spec/v1.0-rc1/build-model.svg deleted file mode 100644 index 2912c934c..000000000 --- a/docs/spec/v1.0-rc1/build-model.svg +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.0-rc1/faq.md b/docs/spec/v1.0-rc1/faq.md deleted file mode 100644 index f918bdfac..000000000 --- a/docs/spec/v1.0-rc1/faq.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Frequently Asked Questions -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build systems to -corroborate the provenance of a build. In this way, one can create an overall -system that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a system can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. diff --git a/docs/spec/v1.0-rc1/future-directions.md b/docs/spec/v1.0-rc1/future-directions.md deleted file mode 100644 index 83890ed0f..000000000 --- a/docs/spec/v1.0-rc1/future-directions.md +++ /dev/null @@ -1,53 +0,0 @@ -# Future directions - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future version to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build service and enabling -corraboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream systems - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other systems to corroborate the - provenance. - -
- -
- -## Source track - -A Source track could provide protection against tampering of the source code -prior to the build. - -The initial [draft version (v0.1)](../v0.1/requirements.md#source-requirements) -of SLSA included the following source requirements, which **may or may not** -form the basis for a future Source track: - -- Strong authentication of author and reviewer identities, such as 2-factor - authentication using a hardware security key, to resist account and - credential compromise. -- Retention of the source code to allow for after-the-fact inspection and - future rebuilds. -- Mandatory two-person review of all changes to the source to prevent a single - compromised actor or account from introducing malicious changes. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md diff --git a/docs/spec/v1.0-rc1/images/provenance-model.svg b/docs/spec/v1.0-rc1/images/provenance-model.svg deleted file mode 100644 index 0c3995328..000000000 --- a/docs/spec/v1.0-rc1/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.0-rc1/index.md b/docs/spec/v1.0-rc1/index.md deleted file mode 100644 index dd77ad5a0..000000000 --- a/docs/spec/v1.0-rc1/index.md +++ /dev/null @@ -1,42 +0,0 @@ -# SLSA Specification - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **version 1.0-rc1** of the SLSA specification, which defines the SLSA -levels. For other versions, use the chooser at the bottom of this page. For -the recommended attestation formats, including provenance, see "Specifications" -in the menu at the top. - -## About this release candidate - -This release candidate is a preview of version 1.0. It contains all -anticipated concepts and major changes for v1.0, but there are still outstanding -TODOs and cleanups. We expect to cover all TODOs and address feedback before the -1.0 final release. - -Known issues: - -- TODO: Use consistent terminology throughout the site: "publish" vs - "release", "publisher" vs "maintainer" vs "developer", "consumer" vs - "ecosystem" vs "downstream system", "build" vs "produce. - -- Verifying artifacts and setting expectations are still in flux. We would - like feedback on whether to move these parts out of the build track. - -## 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. diff --git a/docs/spec/v1.0-rc1/levels.md b/docs/spec/v1.0-rc1/levels.md deleted file mode 100644 index cdc3cb344..000000000 --- a/docs/spec/v1.0-rc1/levels.md +++ /dev/null @@ -1,286 +0,0 @@ -# Security levels - -SLSA is organized into a series of levels that provide increasing supply chain -security guarantees. This gives you confidence that software hasn’t been -tampered with and can be securely traced back to its source. - -This page is an informative overview of the SLSA levels, describing their -purpose and guarantees. For the normative requirements at each level, see -[Requirements](requirements.md). For a background, see -[Terminology](terminology.md). - -## What is SLSA? - -SLSA is a set of incrementally adoptable security guidelines, established by -industry consensus. The standards set by SLSA are guiding principles for both -software producers and consumers: producers can follow the guidelines to make -their software more secure, and consumers can make decisions based on a software -package's security posture. SLSA's levels are designed to be incremental -and actionable, and to protect against specific classes of supply chain attacks. -The highest level in each track represents an ideal end state, and the lower -levels represent intermediate milestones with commensurate security guarantees. - -Importantly, SLSA is intended to be a primitive in a broader determination of a -software's risk. SLSA measures specific aspects of supply chain security, -particularly those that can be fully automated; other aspects, such as developer -trust and code quality, are out of scope. Furthermore, each link in the software -supply chain has its own, independent SLSA level---in other words, it is not -transitive ([FAQ](faq.md#q-why-is-slsa-not-transitive)). The benefit of this -approach is to break up the large supply chain security problem into tractable -subproblems that can be prioritized based on risk and tackled in parallel. But -this does mean that SLSA alone is not sufficient to determine if an artifact is -"safe". - -Finally, SLSA is in the eye of the beholder: software consumers ultimately make -their own SLSA determinations, though in practice they may delegate to some -authority. For example, a build system may claim to conform to SLSA Build L3, -but it is up to a consumer whether to trust that claim. - -## Who is SLSA for? - -SLSA is intended to serve multiple populations: - -- **Project maintainers,** who are often small teams that know their build - process and trust their teammates. Their primary goal is protection against - compromise with as low overhead as possible. They may also benefit from - easier maintenance and increased consumer confidence. - -- **Consumers,** who use a variety of software and do not know the maintainers - or their build processes. Their primary goal is confidence that the software - has not been tampered with. They are concerned about rogue maintainers, - compromised credentials, and compromised infrastructure. - -- **Organizations,** who are both producers and consumers of software. In - addition to the goals above, organizations also want to broadly understand - and reduce risk across the organization. - -- **Infrastructure providers,** such as build services and package - ecosystems, who are critical to achieving SLSA. While not the primary - beneficiary of SLSA, they may benefit from increased security and user - trust. - -## Levels and tracks - -SLSA levels are split into *tracks*. Each track has its own set of levels that -measure a particular aspect of supply chain security. The purpose of tracks is -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 - -> 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 -> Build track. A Source track may be added in [future versions]. - -## Build track - -The SLSA build track describes the level of protection against tampering -during or after the build, and the trustworthiness of provenance metadata. -Higher SLSA build levels provide increased confidence that a package truly came -from the correct sources, without unauthorized modification or influence. - -> **TODO:** Add a diagram visualizing the following. - -Summary of the build track: - -- Set **project-specific expectations** for how the package should be built. -- Generate a **provenance attestation** automatically during each build. -- **Automatically verify** that each package's provenance meets expectations - before allowing its publication and/or consumption. - -What sets the levels apart is how much trust there is in the accuracy of the -provenance and the degree to which adversaries are detected or prevented from -tampering with the package. Higher levels require hardened builds and protection -against more sophisticated adversaries. - -Each ecosystem (for open source) or organization (for closed source) defines -exactly how this is implemented, including: means of defining expectations, what -provenance format is accepted, whether reproducible builds are used, how -provenance is distributed, when verification happens, and what happens on -failure. Guidelines for implementers can be found in the -[requirements](requirements.md). - -
- -### Build L0: No guarantees - -
-
Summary
- -No requirements---L0 represents the lack of SLSA. - -
Intended for
- -Development or test builds of software that are built and run on the same -machine, such as unit tests. - -
Requirements
- -n/a - -
Benefits
- -n/a - -
-
-
- -### Build L1: Provenance - -
-
Summary
- -Package has a provenance attestation showing how it was built, and a downstream -system automatically verifies that packages were built as expected. Prevents -mistakes but is trivial to bypass or forge. - -
Intended for
- -Projects and organizations wanting to easily and quickly gain some benefits of -SLSA---other than tamper protection---without changing their build workflows. - -
Requirements
- -- Up front, the package maintainer defines how the package is *expected* to be - built, including the canonical source repository and build command. - -- On each build, the release process automatically generates and distributes a - [provenance attestation] describing how the artifact was *actually* built, - including: who built the package (person or system), what process/command - was used, and what the input artifacts were. - -- Downstream tooling automatically verifies that the artifact's provenance - exists and matches the expectation. - -
Benefits
- -- Makes it easier for both maintainers and consumers to debug, patch, rebuild, - and/or analyze the software by knowing its precise source version and build - process. - -- Prevents mistakes during the release process, such as building from a commit - that is not present in the upstream repo. - -- Aids organizations in creating an inventory of software and build systems - used across a variety of teams. - -
Notes
- -- Provenance may be incomplete and/or unsigned at L1. Higher levels require - more complete and trustworthy provenance. - -
- -
-
- -### Build L2: Build service - -
-
Summary
- -Forging the provenance or evading verification requires an explicit "attack", -though this may be easy to perform. Deters unsophisticated adversaries or those -who face legal or financial risk. - -In practice, this means that builds run on a hosted service that generates and -signs[^sign] the provenance. - -
Intended for
- -Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build service, while waiting for changes to the build -service itself required by [Build L3]. - -
Requirements
- -All of [Build L1], plus: - -- The build runs on a hosted build service that generates and signs[^sign] the - provenance itself. This may be the original build, an after-the-fact - reproducible build, or some equivalent system that ensures the - trustworthiness of the provenance. - -- Downstream verification of provenance includes validating the authenticity - of the provenance attestation. - -
Benefits
- -All of [Build L1], plus: - -- Prevents tampering after the build through digital signatures[^sign]. - -- Deters adversaries who face legal or financial risk by evading security - controls, such as employees who face risk of getting fired. - -- Reduces attack surface by limiting builds to specific build services that - can be audited and hardened. - -- Allows large-scale migration of teams to supported build services early - while further hardening work ([Build L3]) is done in parallel. - -
-
-
- -[^sign]: Alternate means of verifying the authenticity of the provenance are - also acceptable. - -### Build L3: Hardened builds - -
-
Summary
- -Forging the provenance or evading verification requires exploiting a -vulnerability that is beyond the capabilities of most adversaries. - -In practice, this means that builds run on a hardened build service that offers -strong tamper protection. - -
Intended for
- -Most software releases. Build L3 usually requires significant changes to -existing build services. - -
Requirements
- -All of [Build L2], plus: - -- Build service implements strong controls to: - - - prevent runs from influencing one another, even within the same project. - - prevent secret material used to sign the provenance from being - accessible to the user-defined build steps. - -
Benefits
- -All of [Build L2], plus: - -- Prevents tampering during the build---by maintainers, compromised - credentials, or other tenants. - -- Greatly reduces the impact of compromised package upload credentials by - requiring attacker to perform a difficult exploit of the build process. - -- Provides strong confidence that the package was built from the official - source and build process. - -
-
- - - -[build l0]: #build-l0 -[build l1]: #build-l1 -[build l2]: #build-l2 -[build l3]: #build-l3 -[future versions]: future-directions.md -[previous version]: ../v0.1/levels.md -[provenance attestation]: terminology.md diff --git a/docs/spec/v1.0-rc1/onepage.md b/docs/spec/v1.0-rc1/onepage.md deleted file mode 100644 index e0eabfd74..000000000 --- a/docs/spec/v1.0-rc1/onepage.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: SLSA Specification -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.0-rc1/" %} -{% assign filenames = "levels,principles,terminology,requirements,verifying-systems,threats,faq,future-directions,provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.0-rc1/principles.md b/docs/spec/v1.0-rc1/principles.md deleted file mode 100644 index 5d4d72553..000000000 --- a/docs/spec/v1.0-rc1/principles.md +++ /dev/null @@ -1,76 +0,0 @@ -# Guiding principles - -This page provides a background on the guiding principles behind SLSA. It is -intended to help the reader better understand SLSA's design decisions. - -## Trust systems, verify artifacts - -One of the main ideas behind SLSA is to establish trust in a small number of -*systems* and then automatically verify the many *artifacts* produced by those -systems. In this way, SLSA is able to scale to support hundreds of thousands of -software projects with a near-constant amount of central work. - -We have no option but to manually analyze and reason about the behavior of some -number of trusted *systems*, such as change management, build, and packaging -systems. There will always be some trusted computing base on which we rely for -security. We need to analyze and reason about this computing base to convince -ourselves that it meets our security needs. Such analysis is difficult and -expensive. We cannot possibly harden and audit thousands of bespoke build -systems. We can, however, do this for a small number of general purpose systems. - -Once we have a set of trusted systems, we can verify the supply chain of -arbitrarily many *artifacts* by ensuring that artifacts were produced by trusted -systems. This allows SLSA to scale to entire ecosystems and organizations -regardless of size. - -For example, a security engineer may analyze the architecture and implementation -of a build system to ensure that it meets the SLSA build requirements. Once the -analysis is complete, the public keys used by the build system to sign -provenance can then be "trusted" up to a given SLSA level. Downstream systems -can then automatically determine that an artifact meets a given level by -verifying that it has provenance signed by that public key. - -### Corollary: Minimize the number of trusted systems - -A corollary to the previous principle is to minimize the size of the trusted -computing base. Every system we trust adds attack surface and increases the need -for manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team maintaining their own build system, use a shared build system. This way - hardening work can be shared across all teams. -- Remove the need to trust components whenever possible. For example, use - end-to-end signing to avoid the need to trust intermediate distribution - systems. - -## Anchor trust in code, not individuals - -Another idea behind SLSA is to anchor our trust in source code rather than -individual maintainers who have write access to package registries. Code is -static and analyzable. People, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. Therefore, SLSA aims to -securely trace all software back to source code, without the possibility for an -individual maintainer to tamper with it after it has been committed. - -## Prefer attestations over inferences - -SLSA places a strong emphasis on explicit attestations about security -properties, particularly an artifact's provenance, rather than inferring -security properties from how a system is configured. - -Theoretically one could configure access control such that the only path from -source to release is through the official channels: the CI/CD system only pulls -from the proper source, package registry only allows access to the CI/CD system, -and so on. In practice, that is almost impossible to get right and keep right. -There are often over-provisioning, confused deputy problems, or mistakes. Even -if it is configured properly at one moment, there is no guarantee that it will -continue to stay so. And humans almost always end up getting in the access -control lists. - -Instead, SLSA prefers explicit attestations about an artifact's provenance. -Access control is still important, but SLSA provides a defense in depth: it is -not sufficient to be granted access to publish a package; one must also have -proof in the form of attestations that a package was built correctly. This way, -the intermediate systems are taken out of the trust base and any individuals -that are accidentally granted access do not have sufficient permission to tamper -with the package. diff --git a/docs/spec/v1.0-rc1/provenance.md b/docs/spec/v1.0-rc1/provenance.md deleted file mode 100644 index eee483dca..000000000 --- a/docs/spec/v1.0-rc1/provenance.md +++ /dev/null @@ -1,790 +0,0 @@ ---- -title: Provenance -description: Description of SLSA provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1-rc1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](/spec/v1.0-rc1/requirements#provenance-generation). - -## Model - -Provenance is an attestation that the `builder` produced the `subject` software -artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant platform. The - `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build systems.) - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - system ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `systemParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](/spec/v1.0-rc1/requirements). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -Link: [provenance.proto](schema/provenance.proto) - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`systemParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build system. They MUST be complete at SLSA Build L3, meaning that -that there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build system SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
systemParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build system is already trusted, and in many cases it is -not practical to do so. - -***NOTE:** This field is named `internalParameters` in [v1](/provenance/v1) final.* - -
resolvedDependencies -array (ArtifactReference) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script fetches -and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be listed -here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `systemParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `systemParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build system. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"sha1": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build system to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build service to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -> ⚠ **RFC:** We are particularly looking for feedback on this schema from -> potential implementers. Does this model map cleanly to existing build systems? -> Is it natural to identify and express the external parameters? Is anything -> confusing or ambiguous? - -### ArtifactReference - -[ArtifactReference]: #artifactreference - -REQUIRED: at least one of `uri` or `digest` - - -
FieldTypeDescription - -
uri -string (URI) - -URI describing where this artifact came from. When possible, this SHOULD -be a universal and stable identifier, such as a source location or Package -URL ([purl]). - -
digest -DigestSet - -One or more cryptographic digests of the contents of this artifact. - -
localName -string - -The name for this artifact local to the build. - -
downloadLocation -string (URI) - -URI identifying the location that this artifact was downloaded from, if -different and not derivable from `uri`. - -
mediaType -string (MediaType) - -Media type (aka MIME type) of this artifact was interpreted. - -
- -Example: - -```json -{ - "uri": "pkg:pypi/pyyaml@6.0", - "digest": {"sha256": "5f0689d54944564971f2811f9788218bfafb21aa20f532e6490004377dfa648f"}, - "localName": "PyYAML-6.0.tar.gz", - "downloadLocation": "https://files.pythonhosted.org/packages/36/2b/61d51a2c4f25ef062ae3f74576b01638bebad5e045f747ff12643df63844/PyYAML-6.0.tar.gz", - "mediaType": "application/gzip" -} -``` - -> ⚠ **RFC:** Do we need all these fields? Is this adding too much complexity? - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the entity that executed the invocation, which is trusted to have -correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ArtifactReference) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or incident -response. For example, this might reference logs generated during the build -and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted builder. This is -[intended][Step 1] to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -
version -map (string→string) - -Version numbers of components of the builder. - -
builderDependencies -array (ArtifactReference) - -Dependencies used by the orchestrator that are not run within the workload and -that do not affect the build, but might affect the provenance generation or -security guarantees. - -
- -The builder represents the transitive closure of all the entities that are, by -necessity, [trusted] to faithfully run the build and record the provenance. - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -> ⚠ **RFC:** Do we need more explicit guidance on how to choose a URI? - -> ⚠ **RFC:** Would it be preferable to allow builders to set arbitrary -> properties, rather than calling out `version` and `builderDependencies`? We -> don't expect verifiers to use any of them, so maybe that's the simpler -> approach? Or have a `properties` that is an arbitrary object? (#319) - -> ⚠ **RFC:** Do we want/need to identify the tenant of the build system, -> separately from the build system itself? If so, a single `id` -> that combines both (e.g. -> `https://builder.example/tenants/company1.example/project1`) or two separate -> fields (e.g. `{"id": "https://builder.example", "tenant": -> "https://company1.example/project1"}`)? What would the use case be for this? -> How does [verification] work? - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -## Verification - -[Verification]: #verification - -Verification of provenance encompasses the following steps. - -![Threats covered by each step](../../images/supply-chain-threats-build-verification.svg) - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "D", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Up front: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This is likely in - the form of a map from (builder public key identity, `builder.id`) to - (SLSA Build level). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication, without a builder.id - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "", // empty for this particular builder - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. Verify the envelope's signature using the roots of trust, resulting in a - list of recognized public keys (or equivalent). -2. Verify that statement's `subject` matches the digest of the artifact in - question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1-rc1`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "D"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Verifying build systems](/spec/v1.0-rc1/verifying-systems). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "H".) -- [Threat "H"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. - -[Threat "D"]: /spec/v1.0-rc1/threats#d-compromise-build-process -[Threat "F"]: /spec/v1.0-rc1/threats#f-upload-modified-package -[Threat "G"]: /spec/v1.0-rc1/threats#g-compromise-package-repo -[Threat "H"]: /spec/v1.0-rc1/threats#h-use-compromised-package - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets expectations for that package in -order to mitigate [threat "C"]. - -In our threat model, the adversary has ability to invoke a build and to publish -to the registry but not to write to the source repository, nor do they have -insider access to any trusted systems. Expectations MUST be sufficient to detect -or prevent this adversary from injecting unofficial behavior into the package. -Example threats in this category include building from an unofficial fork or -abusing a build parameter to modify the build. Usually expectations identify the -canonical source repository (which is the entry in `externalParameters`) and any -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 - -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 -values (possibly any value) if it is known that any value in the range is safe. -Implementations need not special-case the `buildType` if JSON comparisons are -sufficient. - -Possible models for implementing expectation setting in package ecosystems (not -exhaustive): - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git refs. - -- **Explicit policy:** Package producer defines the expectations for the - package and distributes it to the verifier; the verifier uses these - expectations after verifying their authenticity. In this model, there MUST - be some protection against an adversary unilaterally modifying the policy. - For example, this might involve two-party control over policy modifications, - or having consumers accept each policy change (another form of trust on - first use). - -- **Immutable policy:** Expectations for a package cannot change. In this - model, the package name is immutably bound to a source repository and all - other expectations are defined in the source repository. This is how go - works, for example, since the package name *is* the source repository - location. - -TIP: Difficulty in setting meaningful expectations for `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then make put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "C"]: /spec/v1.0-rc1/threats#c-build-from-modified-source - -### Step 3: Check dependencies (recursively) - -[verify-step-3]: #step-3-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. This mitigates [threat "E"]. While SLSA v1.0 does not have any -requirements on the completeness or verification of `resolvedDependencies`, one -might wish to go beyond SLSA's minimum requirements in order to protect against -threats further up the supply chain. - -One possible approach is to recursively [verify][Verification] each entry in -`resolvedDependencies`. A [Verification Summary Attestation (VSA)][VSA] can make -this process more efficient by recording the result of prior verifications. A -trimming heuristic or exception mechanism will almost always be necessary -because there will always be some transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) -If `resolvedDependencies` is incomplete, this can be done on a best-effort -basis. - -[Threat "E"]: /spec/v1.0-rc1/threats#e-use-compromised-dependency -[VSA]: /verification_summary - -## Index of build types - -The following is an partial index of build type definitions. Each contains a -complete example predicate. - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) - -**TODO:** Before marking the spec stable, add at least 1-2 other build types to -validate that the design is general enough to apply to other builders. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "systemParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "version": null, // not in v0.2 - "builderDependencies": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.0 RC1 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build systems, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed, with slight changes in semantics: - - `parameters` -> `externalParameters` - - `environment` -> `systemParameters` - - `materials` -> `resolvedDependencies` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - `localName`, `downloadLocation`, and `mediaType` - - `builder.version` - - `byproducts` - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: /spec/v1.0-rc1/threats -[trusted]: /spec/v1.0-rc1/principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.0-rc1/requirements.md b/docs/spec/v1.0-rc1/requirements.md deleted file mode 100644 index b5ab45ba7..000000000 --- a/docs/spec/v1.0-rc1/requirements.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -title: Producing artifacts ---- - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is system implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Levels](levels.md). For background, see [Terminology](terminology.md). To -better understand the reasoning behind the requirements, see -[Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -Responsibility to implement SLSA is spread across the following parties. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build system - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build system - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Non-forgeable - ✓ -
Isolation strength - Build service - ✓✓ -
Ephemeral and isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure system is beyond the -scope of this specification, to be conformant all implementations MUST use -industry security best practices. This includes, but is not limited to, using -proper access controls, securing communications, implementing proper management -of cryptographic secrets, doing frequent updates, and promptly fixing known -vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -### Choose an appropriate build system - -The producer MUST select a build system that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -For example, if a producer wishes to distribute their artifact through a package -ecosystem that requires explicit metadata about the build process in the form of -a config file. That metadata includes the artifact's source repository and build -parameters that stay constant between builds. The producer MUST complete that -config file and keep it up to date. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the package ecosystem, provided that the -package ecosystem is capable of distributing provenance. - -## Build system - -[Build system]: #build-system - -A package's build system is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build system is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build system used -by a single software project, or even a developer's workstation. Ideally, one -build system is used by many different software packages so that consumers can -[minimize the number of trusted systems](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build system is responsible for providing two things: [provenance -generation] and [isolation between builds]. The [Build level](levels.md#build-track) describes -the degree to which each of these properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build system is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the minimum bound for: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package and describes how that package was produced. - -The format MUST be acceptable to the -[package ecosystem](verifying-artifacts.md#package-ecosystem) and/or -[consumer](verifying-artifacts.md#consumer). It -is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. If using an alternate format, it MUST contain the -equivalent information as SLSA Provenance at each level and SHOULD be -bi-directionally translatable to SLSA Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build system and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only to -the service that generated the provenance attestation. - -This allows the consumer to trust the contents of the provenance attestation, -such as the identity of the build system. - -*Accuracy:* The provenance MUST be generated by the build system (i.e. within -the trust boundary identified in the provenance) and not by a tenant of the -build system (i.e. outside the trust boundary). - -- The data in the provenance MUST be obtained from the build service, either - because the generator *is* the build service or because the provenance - generator reads the data directly from the build service. -- The build system MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. - -*Completeness:* SHOULD be complete, but there MAY be external parameters that -are not sufficiently captured in the provenance. - - ✓✓ -
Provenance is Non-forgeable - -*Accuracy:* Provenance MUST be strongly resistant to influence by tenants. - -- Any secret material used to demonstrate the non-forgeable nature of - the provenance, for example the signing key used to generate a digital - signature, MUST be stored in a secure management system appropriate for - such material and accessible only to the build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - service in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents. - -*Completeness:* MUST be complete. In particular, the external parameters MUST be -fully enumerated in the provenance. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build system is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build system's isolation strength, see -[Verifying build systems](verifying-systems.md). - - - - -
RequirementDescriptionL1L2L3 - -
Build service - - -All build steps ran using some build service, not on a maintainer's -workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Ephemeral and isolated - - -The build service ensured that the build steps ran in an ephemeral and isolated -environment provisioned solely for this build, free of influence from other -build instances, whether prior or concurrent. - -- It MUST NOT be possible for a build to access any secrets of the build service, such as the provenance signing key. -- It MUST NOT be possible for two builds that overlap in time to influence one another. -- It MUST NOT be possible for one build to persist or influence the build environment of a subsequent build. -- Build caches, if used, MUST be purely content-addressable to prevent tampering. -- The build SHOULD NOT call out to remote execution unless it's considered part of the "builder" within the trust boundary. -- The build SHOULD NOT open services that allow for remote influence. - -Note: This requirement was split into "Isolated" and "Ephemeral Environment" the -initial [draft version (v0.1)](../v0.1/requirements.md). - - ✓ -
diff --git a/docs/spec/v1.0-rc1/schema/provenance.cue b/docs/spec/v1.0-rc1/schema/provenance.cue deleted file mode 100644 index dabb48e01..000000000 --- a/docs/spec/v1.0-rc1/schema/provenance.cue +++ /dev/null @@ -1,45 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1-rc1", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "systemParameters": object, - "resolvedDependencies": [ ...#ArtifactReference ], - }, - "runDetails": { - "builder": { - "id": string, - "version": string, - "builderDependencies": [ ...#ArtifactReference ], - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ArtifactReference ], - } - } -} - -#ArtifactReference: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "sha1": string, - // TODO: list the other standard algorithms - [string]: string, - }, - "localName": string, - "downloadLocation": string, - "mediaType": string, -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.0-rc1/schema/provenance.proto b/docs/spec/v1.0-rc1/schema/provenance.proto deleted file mode 100644 index b727fa4df..000000000 --- a/docs/spec/v1.0-rc1/schema/provenance.proto +++ /dev/null @@ -1,48 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct system_parameters = 3; - repeated ArtifactReference resolved_dependencies = 4; -} - -message ArtifactReference { - string uri = 1; - map digest = 2; - string local_name = 3; - string download_location = 4; - string media_type = 5; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ArtifactReference byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ArtifactReference builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.0-rc1/slsa_attack.png b/docs/spec/v1.0-rc1/slsa_attack.png deleted file mode 100644 index a917ce36b..000000000 Binary files a/docs/spec/v1.0-rc1/slsa_attack.png and /dev/null differ diff --git a/docs/spec/v1.0-rc1/slsa_build_model.png b/docs/spec/v1.0-rc1/slsa_build_model.png deleted file mode 100644 index 539ec09b5..000000000 Binary files a/docs/spec/v1.0-rc1/slsa_build_model.png and /dev/null differ diff --git a/docs/spec/v1.0-rc1/terminology.md b/docs/spec/v1.0-rc1/terminology.md deleted file mode 100644 index 67a01c1c0..000000000 --- a/docs/spec/v1.0-rc1/terminology.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Terminology ---- - -Before diving into the [SLSA Levels](levels.md), we need to establish a core set -of terminology and models to describe what we're protecting. - -## TODO: Terms we still need to define - -> **TODO:** Define these terms before the v1.0 release. - -- Ecosystem -- Project - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). - -[build]: #build-model -[SLSA Provenance]: /provenance/v1-rc1 - -### Build model - -We model a build as running on a multi-tenant platform, where each execution is -independent. A tenant defines the build by specifying parameters through some -sort of external interface, often including a reference to a configuration file -in source control. The platform then runs the build by interpreting the -parameters, fetching some initial set of dependencies, initializing the build -environment, and then starting execution. The build then performs arbitrary -steps, possibly fetching additional dependencies, and outputs one or more -artifacts. Finally, for SLSA Build L2+, the platform outputs provenance -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. - -Notably, there is no formal notion of "source" in the build model, just -parameters and dependencies. Most build platforms have an explicit "source" -artifact to be built, which is often a git repository; in the build model, the -reference to this artifact is a parameter while the artifact itself is a -dependency. - -For examples on how this model applies to real-world build systems, see [index -of build types](/provenance/v1-rc1#index-of-build-types). - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build system is -certified to ensure conformance with the requirements at the level claimed by -the build system. This certification should happen on a recurring cadence with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer defined -expectations of where the package source code was retrieved from and on what -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. - -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. - -
- -
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. - -
diff --git a/docs/spec/v1.0-rc1/threats.md b/docs/spec/v1.0-rc1/threats.md deleted file mode 100644 index 84c2e73a4..000000000 --- a/docs/spec/v1.0-rc1/threats.md +++ /dev/null @@ -1,771 +0,0 @@ ---- -title: Threats and mitigations ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -SLSA's [levels](levels.md) are designed to mitigate the risk of these attacks. -This page enumerates possible attacks throughout the supply chain and shows how -SLSA can help. For a background, see [Terminology](terminology.md). - -## Summary - -![Supply Chain Threats](../../images/supply-chain-threats.svg) - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that all changes to the source code reflect the -intent of the software producer. Intent of an organization is difficult to -define, so SLSA approximates this as approval from two authorized -representatives. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -> **TODO:** Update this for v1.0. - -Many recent high-profile attacks were consequences of supply-chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - -
-Integrity threat -Known example -How SLSA can help -
A -Submit unauthorized change (to source repo) -Linux hypocrite commits: Researcher attempted to intentionally introduce vulnerabilities into the Linux kernel via patches on the mailing list. -Two-person review caught most, but not all, of the vulnerabilities. -
B -Compromise source repo -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code platform would have been a much harder target for the attackers. -
C -Build from modified source (not matching source repo) -Webmin: Attacker modified the build infrastructure to use source files not matching source control. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
D -Compromise build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA levels require stronger security controls for the build platform, making it more difficult to compromise and gain persistence. -
E -Use compromised dependency (i.e. A-H, recursively) -event-stream: Attacker added an innocuous dependency and then later updated the dependency to add malicious behavior. The update did not match the code submitted to GitHub (i.e. attack F). -Applying SLSA recursively to all dependencies would have prevented this particular vector, because the provenance would have indicated that it either wasn't built from a proper builder or that the source did not come from GitHub. -
F -Upload modified package (not matching build process) -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Compromise package repo -Attacks on Package Mirrors: Researcher ran mirrors for several popular package repositories, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Use compromised package -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
- - - - - - -
-Availability threat -Known example -How SLSA can help -
E -Dependency becomes unavailable -Mimemagic: Maintainer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. - -## Threats in detail - -> **IMPORTANT:** This is a work in progress. - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations in SLSA. The goals are to: - -- Explain the reasons for each of the SLSA [requirements](requirements.md). -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](levels.md) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - -
- -## Source integrity threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes the threat of an authorized developer introducing an unauthorized -change—in other words, an insider threat. - -SLSA v1.0 does not address source integrity, though we anticipate a [Source -track](future-directions#source-track) might do so in a future version. In -the meantime, the threats and potential mitigations listed here show how SLSA -v1.0 can fit into a broader supply chain security program. - -### (A) Submit unauthorized change - -An adversary introduces a change through the official source control management -interface without any special administrator privileges. - -#### (A1) Submit change without review - -
Directly submit without review - -*Threat:* Submit bad code to the source repository without another person -reviewing. - -*Mitigation:* Source repository requires two-person approval for all changes. - -*Example:* Adversary directly pushes a change to a GitHub repo's `main` branch. -Solution: Configure GitHub's "branch protection" feature to require pull request -reviews on the `main` branch. - -
-
Review own change through a sock puppet account - -*Threat:* Propose a change using one account and then approve it using another -account. - -*Mitigation:* Source repository requires approval from two different, trusted -persons. If the proposer is trusted, only one approval is needed; otherwise two -approvals are needed. The software producer maps accounts to trusted persons. - -*Example:* Adversary creates a pull request using a secondary account and then -approves and merges the pull request using their primary account. Solution: -Configure branch protection to require two approvals and ensure that all -repository contributors and owners map to unique persons. - -
-
Use a robot account to submit change - -*Threat:* Exploit a robot account that has the ability to submit changes without -two-person review. - -*Mitigation:* All changes require two-person review, even changes authored by -robots. - -*Example:* A file within the source repository is automatically generated by a -robot, which is allowed to submit without review. Adversary compromises the -robot and submits a malicious change without review. Solution: Require human -review for these changes. - -> RFC ([#196](https://github.com/slsa-framework/slsa/issues/196)): This solution -> may not be practical. Should there be an exception for locked down robot -> accounts? - -
-
Abuse review exceptions - -*Threat:* Exploit a review exception to submit a bad change without review. - -*Mitigation:* All changes require two-person review without exception. - -*Example:* Source repository requires two-person review on all changes except -for "documentation changes," defined as only touching files ending with `.md` or -`.html`. Adversary submits a malicious executable named `evil.md` without review -using this exception, and then builds a malicious package containing this -executable. This would pass expectations because the source repository is -correct, and the source repository does require two-person review. Solution: Do -not allow such exceptions. - -> RFC: This solution may not be practical in all circumstances. Are there any -> valid exceptions? If so, how do we ensure they cannot be exploited? - -
- -#### (A2) Evade code review requirements - -
Modify code after review - -*Threat:* Modify the code after it has been reviewed but before submission. - -*Mitigation:* Source control platform invalidates approvals whenever the -proposed change is modified. - -*Example:* Source repository requires two-person review on all changes. -Adversary sends a "good" pull request to a peer, who approves it. Adversary then -modifies it to contain "bad" code before submitting. Solution: Configure branch -protection to dismiss stale approvals when new changes are pushed. - -> RFC: How do we handle the productivity hit? The cost of code review is already -> high for most projects, given current code review tooling, so making code -> review even costlier might not be considered warranted. Are there alternative -> solutions? Better tooling? Another SLSA level to represent this? - -
-
Submit a change that is unreviewable - -*Threat:* Send a change that is meaningless for a human to review that looks -benign but is actually malicious. - -*Mitigation:* Code review system ensures that all reviews are informed and -meaningful. - -*Example:* A proposed change updates a file, but the reviewer is only presented -with a diff of the cryptographic hash, not of the file contents. Thus, the -reviewer does not have enough context to provide a meaningful review. Solution: -the code review system should present the reviewer with a content diff or some -other information to make an informed decision. - -
-
Copy a reviewed change to another context - -*Threat:* Get a change reviewed in one context and then transfer it to a -different context. - -*Mitigation:* Approvals are context-specific. - -*Example:* MyPackage's source repository requires two-person review. Adversary -forks the repo, submits a change in the fork with review from a colluding -colleague (who is not trusted by MyPackage), then merges the change back into -the upstream repo. Solution: The merge should still require review, even though -the fork was reviewed. - -
-
Compromise another account - -*Threat:* Compromise one or more trusted accounts and use those to submit and -review own changes. - -*Mitigation:* Source control platform verifies two-factor authentication, which -increases the difficulty of compromising accounts. - -*Example:* Trusted person uses a weak password on GitHub. Adversary guesses the -weak password, logs in, and pushes changes to a GitHub repo. Solution: Configure -GitHub organization to requires 2FA for all trusted persons. This would increase -the difficulty of using the compromised password to log in to GitHub. - -
-
Hide bad change behind good one - -*Threat:* Request review for a series of two commits, X and Y, where X is bad -and Y is good. Reviewer thinks they are approving only the final Y state whereas -they are also implicitly approving X. - -*Mitigation:* Only the version that is actually reviewed is the one that is -approved. Any intermediate revisions don't count as being reviewed. - -*Example:* Adversary sends a pull request containing malicious commit X and -benign commit Y that undoes X. In the pull request UI, reviewer only reviews and -approves "changes from all commits", which is a delta from HEAD to Y; they don't -see X. Adversary then builds from the malicious revision X. Solution: -Expectations do not accept this because the version X is not considered -reviewed. - -
- -#### (A3) Code review bypasses that are out of scope of SLSA - -
Software producer intentionally submits bad code - -*Threat:* Software producer intentionally submits "bad" code, following all -proper processes. - -*Mitigation:* **Outside the scope of SLSA.** Trust of the software producer is -an important but separate property from integrity. - -*Example:* A popular extension author sells the rights to a new owner, who then -modifies the code to secretly mine bitcoin at the users' expense. SLSA does not -protect against this, though if the extension were open source, regular auditing -may discourage this from happening. - -
-
Collude with another trusted person - -*Threat:* Two trusted persons collude to author and approve a bad change. - -*Mitigation:* **Outside the scope of SLSA.** We use "two trusted persons" as a -proxy for "intent of the software producer". - -
-
Trick reviewer into approving bad code - -*Threat:* Construct a change that looks benign but is actually malicious, a.k.a. -"bugdoor." - -*Mitigation:* **Outside the scope of SLSA.** - -
-
Reviewer blindly approves changes - -*Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber -stamping." - -*Mitigation:* **Outside the scope of SLSA.** - -
- -### (B) Compromise source repo - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -
Project owner bypasses or disables controls - -*Threat:* Trusted person with "admin" privileges in a repository submits "bad" -code bypassing existing controls. - -*Mitigation:* All persons are subject to same controls, whether or not they have -administrator privileges. Disabling the controls requires two-person review (and -maybe notifies other trusted persons?) - -*Example 1:* GitHub project owner pushes a change without review, even though -GitHub branch protection is enabled. Solution: Enable the "Include -Administrators" option for the branch protection. - -*Example 2:* GitHub project owner disables "Include Administrators", pushes a -change without review, then re-enables "Include Administrators". This currently -has no solution on GitHub. - -
-
Platform admin abuses privileges - -*Threat:* Platform administrator abuses their privileges to bypass controls or -to push a malicious version of the software. - -*Mitigation:* TBD - -*Example 1:* GitHostingService employee uses an internal tool to push changes to -the MyPackage source repo. - -*Example 2:* GitHostingService employee uses an internal tool to push a -malicious version of the server to serve malicious versions of MyPackage sources -to a specific CI/CD client but the regular version to everyone else, in order to -hide tracks. - -*Example 3:* GitHostingService employee uses an internal tool to push a -malicious version of the server that includes a backdoor allowing specific users -to bypass branch protections. Adversary then uses this backdoor to submit a -change to MyPackage without review. - -
-
Exploit vulnerability in SCM - -*Threat:* Exploit a vulnerability in the implementation of the source code -management system to bypass controls. - -*Mitigation:* **Outside the scope of SLSA.** - -
- -## Build integrity threats - -A build integrity threat is a potential for an adversary to introduce behavior -to a package that is not reflected in the source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track covers these threats when combined with verifying artifacts -against expectations. - -### (C) Build from modified source - -An adversary builds from a version of the source code that does not match the -official source control repository. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (D) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build service pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -### (D) Compromise build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Compromise build environment of subsequent build (Build L3) - -*Threat:* Perform a "bad" build that persists a change in the build environment, -then run a subsequent "good" build using that environment. - -*Mitigation:* Builder ensures that each build environment is [ephemeral], with -no way to persist changes between subsequent builds. - -*Example:* Build service uses the same machine for subsequent builds. Adversary -first runs a build that replaces the `make` binary with a malicious version, -then runs a subsequent build that otherwise would pass expectations. Solution: -Builder changes architecture to start each build with a clean machine image. - -
-
Compromise parallel build (Build L3) - -*Threat:* Perform a "bad" build that alters the behavior of another "good" build -running in parallel. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other. - -*Example:* Build service runs all builds for project MyPackage on the same -machine as the same Linux user. Adversary starts a "bad" build that listens for -the "good" build and swaps out source files, then starts a "good" build that -would otherwise pass expectations. Solution: Builder changes architecture to -isolate each build in a separate VM or similar. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build service. - -*Mitigation:* Builds are [isolated] from the trusted build service control -plane, and only the control plane has [access][non-forgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Set values of the provenance (Build L2-L3) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][non-forgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -service to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a "bad" artifact to a build cache that is later picked up by a -"good" build process. - -*Mitigation:* Build caches must be [isolate][isolated] between builds to prevent -such cache poisoning attacks. - -*Example:* Build system uses a build cache across builds, keyed by the hash of -the source file. Adversary runs a malicious build that creates a "poisoned" -cache entry with a falsified key, meaning that the value wasn't really produced -from that source. A subsequent build then picks up that poisoned cache entry. - -
-
Project owner (TBD) - -**TODO:** similar to Source (do the same threats apply here?) - -
-
Platform admin (TBD) - -**TODO:** similar to Source - -
- -### (E) Use compromised dependency - -> **TODO:** What exactly is this about? Is it about compromising the build -> process through a bad build tool, and/or is it about compromising the output -> package through a bad library? Does it involve all upstream threats to the -> dependency, or is it just about this particular use of the package (e.g. -> tampering on input, or choosing a bad dependency)? - - - -> **TODO:** Fill this out to give more examples of threats from compromised -> dependencies. - -### (F) Upload modified package - -An adversary uploads a package not built from the proper build process. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildService, which is only -trusted up to Build L2, and then exploits SomeOtherBuildService to inject bad -behavior. Solution: Verifier rejects because builder is not as expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a good version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not pass expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Compromise package repo - -An adversary modifies the package on the package repository using an -administrative interface or through a compromise of the infrastructure. - -**TODO:** fill this out - -### (H) Use compromised package - -An adversary modifies the package after it has left the package repository, or -tricks the user into using an unintended package. - -
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* **Mostly outside the scope of SLSA.** That said, the requirement -to make the source available can be a mild deterrent, can aid investigation or -ad-hoc analysis, and can complement source-based typosquatting solutions. - -
- -## Availability threats - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA v1.0 does not address availability threats, though future versions might. - -
(A)(B) Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* Some system retains the revision and its version control history, -making it available for inspection indefinitely. Users cannot delete the -revision except as part of a transparent legal or privacy process. - -*Example:* Adversary submits bad code to the MyPackage GitHub repo, builds from -that revision, then does a force push to erase that revision from history (or -requests GitHub to delete the repo.) This would make the revision unavailable -for inspection. Solution: Verifier rejects the package because it lacks a -positive attestation showing that some system, such as GitHub, ensured retention -and availability of the source code. - -
-
(E) A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* **Outside the scope of SLSA.** That said, some solutions to -support hermetic and reproducible builds may also reduce the impact of this -threat. - -
- -## Other threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above but that do not fall cleanly into any one category. - -
Tamper with expectations - -*Threat:* Modify the expectations to accept something that would not otherwise -be accepted. - -*Mitigation:* Changes to expectations require some form of authorization, such -as two-party review. - -*Example:* Expectations for MyPackage only allows source repo `good/my-package`. -Adversary modifies the expectations to also accept `evil/my-package`, then -builds from that repo and uploads a bad version of the package. Solution: -Expectation changes require two-party review. - -
-
Forge change metadata - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* Source control platform strongly authenticates actor identity, -timestamp, and parent revisions. - -*Example:* Adversary submits a git commit with a falsified author and timestamp, -and then rewrites history with a non-fast-forward update to make it appear to -have been made long ago. Solution: Consumer detects this by seeing that such -changes are not strongly authenticated and thus not trustworthy. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Require cryptographically secure hash functions for code review -and provenance, such as SHA-256. - -*Examples:* Construct a "good" file and a "bad" file with the same SHA-1 hash. -Get the "good" file reviewed and then submit the "bad" file, or get the "good" -file reviewed and submitted and then build from the "bad" file. Solution: Only -accept cryptographic hashes with strong collision resistance. - -
- -
- - - -[authentic]: requirements.md#provenance-authentic -[ephemeral]: requirements.md#ephemeral-isolated -[exists]: requirements.md#provenance-exists -[isolated]: requirements.md#ephemeral-isolated -[non-forgeable]: requirements.md#provenance-non-forgeable -[service]: requirements.md#build-service diff --git a/docs/spec/v1.0-rc1/use-cases.md b/docs/spec/v1.0-rc1/use-cases.md deleted file mode 100644 index d9908ea6d..000000000 --- a/docs/spec/v1.0-rc1/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package repository. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build systems rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified from a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.0-rc1/verification-model.svg b/docs/spec/v1.0-rc1/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.0-rc1/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.0-rc1/verifying-artifacts.md b/docs/spec/v1.0-rc1/verifying-artifacts.md deleted file mode 100644 index 47ddd9e28..000000000 --- a/docs/spec/v1.0-rc1/verifying-artifacts.md +++ /dev/null @@ -1,192 +0,0 @@ -# Verifying Artifacts - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection -verification, and this page describes how to verify artifacts and their SLSA -provenance. The intended audience is system implementers, security engineers, -and software consumers. - -## Overview - -Artifact verification is a process that consists of several stages that involves -the artifact distribution system ("package ecosystem") and artifact consumer. - -Package ecosystems verify an artifact's provenance against a set of expectations. -Those expectations are set by the package ecosystem, with optional input from the -artifact producer. Package ecosystems may choose to distribute only artifacts that -pass verification, or they may choose to require that consumers opt-in to -verification. - -Consumers can trust their package ecosystem or some other third party to verify -artifacts, or they can verify artifacts against their own set of expectations. - -## Package ecosystem - -[Package ecosystem]: #package-ecosystem - -> ⚠ **RFC:** Is there a better term that is more obvious to most readers? - -A package ecosystem is a set of conventions and tooling for package -distribution. Every package has an ecosystem, whether it is formal or ad-hoc. -Some ecosystems are formal, such as language distribution (e.g. -[Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". - -The package ecosystem's maintainers are responsible for reliably redistributing -artifacts and provenance, making the producers' expectations available to consumers, -and providing tools to enable safe artifact consumption (e.g. whether an artifact -meets its producer's expectations). - -### Setting Expectations - -Expectations are known provenance values that indicate the corresponding -artifact is authentic. For example, a producer can define the allowed values for -[`buildType`](/provenance/v1-rc1#buildType) and -[`externalParameters`](/provenance/v1-rc1#externalParameters) -for a given package (assuming it uses the SLSA provenance format) in order to address -the [build integrity threats](threats#build-integrity-threats). -> **TODO:** link to more concrete guidance once it's available. - -Expectations MUST be sufficient to detect -or prevent this adversary from injecting unofficial behavior into the package. -Example threats in this category include building from an unofficial fork or -abusing a build parameter to modify the build. Usually expectations identify -the canonical source repository (which is the main external parameter) and -any other security-relevant external parameters. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -may have different artifacts and therefore different provenance. Similarly, an -artifact may have different names in different package ecosystems but use the same -provenance file. - -Package ecosystems -using the [RECOMMENDED suite](attestation-model#recommended-suite) of attestation -formats SHOULD list the package name in the provenance attestation statement's -`subject` field, though the precise semantics for binding a package name to an -artifact are defined by the package ecosystem. - - - - -
RequirementDescriptionL1L2L3 - -
Expectations known - - -The package ecosystem MUST ensure that expectations are defined for the package before it is made available to package ecosystem users. - -There are several approaches a package ecosystem could take to setting expectations, for example: - -- Requiring the producer to set expectations when registering a new package - in the package ecosystem. -- Using the values from the package's provenance during its initial - publication (trust on first use). - -✓✓✓ -
Changes authorized - - -The package ecosystem MUST ensure that any changes to expectations are -authorized by the package's producer. This is to prevent a malicious actor -from updating the expectations to allow building and publishing from a fork -under the malicious actor's control. Some ways this could be achieved include: - -- Requiring two authorized individuals from the package producer to approve - the change. -- Requiring consumers to approve changes, in a similar fashion to how SSH - host fingerprint changes have to be approved by users. -- Disallowing changes altogether, for example by binding the package name to - the source repository. - -✓✓ -
- -### Verifying expectations for artifacts - -It is a critical responsibility of the package ecosystem to verify that the -provenance for a package matches the expectations defined for that package. -In our threat model, the adversary has the ability to invoke a build and to publish -to the registry but not to write to the source repository, nor do they have -insider access to any trusted systems. - -A package version is considered to meet a given SLSA level if and only if the -package ecosystem has verified its provenance against the package's -expectations. If expectations are defined for a package but no provenance -exists for the artifact, this MUST result in verification failure. -Conversely, if multiple provenance attestations exist, the system SHOULD accept -any combination that satisfies expectations. - -Verifying expectations could happen in multiple places within a package -ecosystem, for example by using one or more of the following approaches: - -- During package upload, the registry ensures that the package's provenance - matches the known expectations for that package before accepting it into - the registry. -- During client-side installation/deployment of a package, the package - ecosystem client ensures that the package's provenance matches the - known expectations for that package before use. -- Package ecosystem participants and/or the ecosystem operators perform - continuous monitoring of packages to detect any changes to packages which - do not match the known expectations. **TODO:** do we need to - emphasize that the value of monitoring without enforcement is lower? - -All package ecosystem verifiers will require a mapping from builder identity to -the SLSA level the builder is trusted to meet. How this map is defined, -distributed, and updated is package ecosystem specific. -> **TODO:** expand on this map model. Provide examples for ecosystems to follow, -perhaps in the use-cases, and link to certification. - -Verification MUST include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- [Verification of the provenance](/provenance/v1-rc1#verification) metadata. -- Ensuring that the values for `BuildType` and `ExternalParameters` in the - provenance match the known expectations. The package ecosystem MAY allow - an approved list of `ExternalParameters` to be ignored during verification. - Any unrecognized `ExternalParameters` SHOULD cause verification to fail. - -NOTE: The term *package ecosystem* MAY be interpreted loosely. For example, one -could implement a system which is external to the canonical package ecosystem -and perform SLSA verification for that package ecosystem's contents. This -combination can be considered a package ecosystem for the purposes of setting -and verifying expectations. - -**TODO:** Update the requirements to provide guidelines for how to implement, -showing what the options are: - -- Create a more concrete guide on how to do expectations -- Whether provenance is generated during the initial build and/or - after-the-fact using reproducible builds -- How provenance is distributed -- What happens on failure: blocking, warning, and/or asynchronous notification - -### Provenance Distribution - -The package ecosystems MUST distribute provenance for the artifacts they distribute -if provided by the producer. - -## Consumer - -[Consumer]: #consumer - -A package's consumer is the organization or individual that uses the -package. - -There are no requirements for how artifact consumers interact with SLSA, -but they will benefit from verifying an artifact's provenance and the build -system used to produce the artifact. If a consumer is unwilling or unable to verify -artifacts, they may still gain some benefit by relying on third-party verification -(e.g. a monitoring service that publicizes artifacts that violate their expectations). - -The consumer may have to opt-in to enable SLSA verification, depending on the -package ecosystem. - -Consumers may either audit the build systems -themselves using the prompts in [verifying systems](verifying-systems.md) or -rely on the SLSA certification program (coming soon). diff --git a/docs/spec/v1.0-rc1/verifying-systems.md b/docs/spec/v1.0-rc1/verifying-systems.md deleted file mode 100644 index 81381d714..000000000 --- a/docs/spec/v1.0-rc1/verifying-systems.md +++ /dev/null @@ -1,164 +0,0 @@ -# Verifying Build Systems - -The provenance consumer is responsible for deciding whether they trust a builder to produce SLSA Build L3 provenance. However, assessing Build L3 capabilities requires information about a builder's construction and operating procedures that the consumer cannot glean from the provenance itself. To aid with such assessments, we provide a common threat model and builder model for reasoning about builders' security. We also provide a questionnaire that organizations can use to describe their builders to consumers along with sample answers that do and do not satisfy the SLSA Build L3 requirements. - -## Threat Model - -### Attacker Goal - -The attacker's primary goal is to tamper with a build to create unexpected, vulnerable, or malicious behavior in the output artifact while avoiding detection. Their means of doing so is generating build provenance that does not faithfully represent the built artifact's origins or build process. - -More formally, if a build with external parameters P would produce an artifact with binary hash X and a build with external parameters P' would produce an artifact with binary hash Y, they wish to produce provenance indicating a build with external parameters P produced an artifact with binary hash Y. - -This diagram represents a successful attack: - -![image](slsa_attack.png) - -Note: Platform abuse (e.g. running non-build workloads) and attacks against builder availability are out of scope of this document. - -TODO: Align/cross-reference with SLSA Provenance Model. - -TODO: Redraw diagrams in the style used by the rest of the site. - -### Types of attackers - -We consider three attacker profiles differentiated by the attacker's capabilities and privileges as related to the build they wish to subvert (the "target build"). - -TODO: Tie attack profiles into the rest of this page. - -#### Project contributors - -Capabilities: - -- Create builds on the build service. These are the attacker's controlled builds. -- Modify one or more controlled builds' external parameters. -- Modify one or more controlled builds' environments and run arbitrary code inside those environments. -- Read the target build's source repo. -- Fork the target build's source repo. -- Modify a fork of the target build's source repo and build from it. - -#### Project maintainer - -Capabilities: - -- All listed under "low privilege". -- Create new builds under the target build's project or identity. -- Modify the target build's source repo and build from it. -- Modify the target build's configuration. - -#### Build service admin - -Capabilities: - -- All listed under "low privilege" and "medium privilege". -- Run arbitrary code on the build service. -- Read and modify network traffic. -- Access the control plane's cryptographic secrets. -- Remotely access build executors (e.g. via SSH). - -TODO: List other high-privilege capabilities. -TODO: Maybe differentiate between unilateral and non-unilateral privileges. - -## Build Model - -The build model consists of five components: parameters, the control plane, one or more build executors, a build cache, and output storage. The data flow between these components is shown in the diagram below. - -![image](slsa_build_model.png) - -TODO: Align with provenance and build models. - -The following sections detail each element of the build model and prompts for assessing its ability to produce SLSA Build L3 provenance. - -### External Parameters - -External parameters are the external interface to the builder and include all inputs to the build process. Examples include the source to be built, the build definition/script to be executed, user-provided instructions to the control plane for how to create the build executor (e.g. which operating system to use), and any additional user-provided strings. - -#### Prompts for Assessing External Parameters - -- How does the control plane process user-provided external parameters? Examples: sanitizing, parsing, not at all -- Which external parameters are processed by the control plane and which are processed by the executor? -- What sort of external parameters does the control plane accept for executor configuration? -- How do you ensure that all external parameters are represented in the provenance? -- How will you ensure that future design changes will not add additional external parameters without representing them in the provenance? - -### Control Plane - -The control plane is the build system component that orchestrates each independent build execution. It is responsible for setting up each build and cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs provenance for each build performed on the build service. The control plane is operated by one or more administrators, who have privileges to modify the control plane. - -#### Prompts for Assessing Control Planes - -- Administration - - What are the ways an employee can use privileged access to influence a build or provenance generation? Examples: physical access, terminal access, access to cryptographic secrets - - What controls are in place to detect or prevent the employee from abusing such access? Examples: two-person approvals, audit logging, workload identities - - Roughly how many employees have such access? - - How are privileged accounts protected? Examples: two-factor authentication, client device security policies - - What plans do you have for recovering from security incidents and system outages? Are they tested? How frequently? - -- Provenance generation - - How does the control plane observe the build to ensure the provenance's accuracy? - - Are there situations in which the control plane will not generate provenance for a completed build? What are they? - -- Development practices - - How do you track the control plane's software and configuration? Example: version control - - How do you build confidence in the control plane's software supply chain? Example: SLSA L3+ provenance, build from source - - How do you secure communications between builder components? Example: TLS with certificate transparency. - - Are you able to perform forensic analysis on compromised executors? How? Example: retain base images indefinitely - -- Creating executors - - How does the control plane share data with executors? Example: mounting a shared file system partition - - How does the control plane protect its integrity from executors? Example: not mount its own file system partitions on executors - - How does the control plane prevent executors from accessing its cryptographic secrets? Examples: dedicated secret storage, not mounting its own file system partitions on executors, hardware security modules - -- Managing cryptographic secrets - - How do you store the control plane's cryptographic secrets? - - Which parts of the organization have access to the control plane's cryptographic secrets? - - What controls are in place to detect or prevent employees abusing such access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation process. - - What is your plan for remediating cryptographic secret compromise? How frequently is this plan tested? - -### Executor - -The build executor is the independent execution environment where the build takes place. Each executor must be isolated from the control plane and from all other executors, including executors running builds from the same build user or project. Build users are free to modify the environment inside the executor arbitrarily. Build executors must have a means to fetch input artifacts (source, dependencies, etc). - -#### Prompts for Assessing Executors - -- Isolation technologies - - How are executors isolated from the control plane and each other? Examples: VMs, containers, sandboxed processes - - How have you hardened your executors against malicious tenants? Examples: configuration hardening, limiting attack surface - - How frequently do you update your isolation software? - - What is your process for responding to vulnerability disclosures? What about vulnerabilities in your dependencies? - - What prevents a malicious build from gaining persistence and influencing subsequent builds? - -- Creation and destruction - - What tools and environment are available in executors on creation? How were the elements of this environment chosen? Examples: A minimal Linux distribution with its package manager, OSX with HomeBrew - - How long could a compromised executor remain active in the build system? - -- Network access - - Are executors able to call out to remote execution? If so, how do you prevent them from tampering with the control plane or other executors over the network? - - Are executors able to open services on the network? If so, how do you prevent remote interference through these services? - -### Cache - -Builders may have zero or more caches to store frequently used dependencies. Build executors may have either read-only or read-write access to caches. - -#### Prompts for Assessing Caches - -- What sorts of caches are available to build executors? -- How are those caches populated? -- How are cache contents validated before use? - -### Output Storage - -Output Storage holds built artifacts and their provenance. Storage may either be shared between build projects or allocated separately per-project. - -#### Prompts for Assessing Output Storage - -- How do you prevent builds from reading or overwriting files that belong to another build? Example: authorization on storage -- What processing, if any, does the control plane do on output artifacts? - -## Builder Evaluation - -Organizations can either self-attest to their answers or seek an audit/certification from a third party. Questionnaires for self-attestation should be published on the internet. Questionnaires for third-party certification need not be published. All provenance generated by L3+ builders must contain a non-forgeable attestation of the builder's L3+ capabilities with a limited validity period. Any secret materials used to prove the non-forgeability of the attestation must belong to the attesting party. - -TODO: Add build system attestation spec diff --git a/docs/spec/v1.0-rc1/whats-new.md b/docs/spec/v1.0-rc1/whats-new.md deleted file mode 100644 index 842687c7a..000000000 --- a/docs/spec/v1.0-rc1/whats-new.md +++ /dev/null @@ -1,16 +0,0 @@ -# What's New in SLSA v1.0 - -SLSA v1.0 represents changes made in response to feedback from the SLSA -community and early adopters of SLSA v0.1. Overall, these changes -prioritize simplicity and practicality. - -Check back here for a detailed v1.0 changelog with the official 1.0 release! - -Until then, see the following for more information about what's new: - -- [Release candidate blog post](/blog/2023/02/slsa-v1-rc): describes the - addition of SLSA tracks, verification expectations, and changes to SLSA's - model, specification, and format - -- [Provenance changelog](/provenance/v1-rc1#v10-draft): a detailed summary of - changes to the provenance format diff --git a/docs/spec/v1.0-rc2/about.md b/docs/spec/v1.0-rc2/about.md deleted file mode 100644 index 76e21b8e0..000000000 --- a/docs/spec/v1.0-rc2/about.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: About SLSA -description: With supply chain attacks on the rise, a shared vocabulary and universal framework is needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software. ---- - -This page is an introduction to SLSA and its concepts. If you're new -to SLSA, start here! - -## What is SLSA? - -SLSA is a set of incrementally adoptable guidelines for supply chain security, -established by industry consensus. The specification set by SLSA is useful for -both software producers and consumers: producers can follow SLSA's guidelines to -make their software supply chain more secure, and consumers can use SLSA to make -decisions about whether to trust a software package. - -SLSA offers: - -- A common vocabulary to talk about software supply chain security -- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume -- An actionable checklist to improve your own software's security -- A way to measure your efforts toward compliance with forthcoming - Executive Order standards in the [Secure Software Development Framework (SSDF)](https://csrc.nist.gov/Projects/ssdf) - -## Why SLSA is needed - -High profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply -chain integrity weaknesses that may go unnoticed, yet quickly become very -public, disruptive, and costly in today's environment when exploited. They've -also shown that there are inherent risks not just in code itself, but at -multiple points in the complex process of getting that code into software -systems—that is, in the **software supply chain**. Since these attacks are on -the rise and show no sign of decreasing, a universal framework for hardening the -software supply chain is needed, as affirmed by the -[U.S. Executive Order on Improving the Nation's Cybersecurity](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/). - -Security techniques for vulnerability detection and analysis of source code are -essential, but are not enough on their own. Even after fuzzing or vulnerability -scanning is completed, changes to code can happen, whether unintentionally or -from insider threats or compromised accounts. Risk for code modification exists at -each link in a typical software supply chain, from source to build through -packaging and distribution. Any weaknesses in the supply chain undermine -confidence in whether the code that you run is actually the code that you -scanned. - -SLSA is designed to support automation that tracks code handling from source -to binary, protecting against tampering regardless of the complexity -of the software supply chain. As a result, SLSA increases trust that the -analysis and review performed on source code can be assumed to still apply to -the binary consumed after the build and distribution process. - -## SLSA in layperson's terms - -There has been a [lot of discussion](https://ntia.gov/page/software-bill-materials) about the need for "ingredient labels" for -software—a "software bill of materials" (SBOM) that tells users what is in their -software. Building off this analogy, SLSA can be thought of as all the food -safety handling guidelines that make an ingredient list credible. From standards -for clean factory environments so contaminants aren't introduced in packaging -plants, to the requirement for tamper-proof seals on lids that ensure nobody -changes the contents of items sitting on grocery store shelves, the entire food -safety framework ensures that consumers can trust that the ingredient list -matches what's actually in the package they buy. - -Likewise, the SLSA framework provides this trust with guidelines and -tamper-resistant evidence for securing each step of the software production -process. That means you know not only that nothing unexpected was added to the -software product, but also that the ingredient label itself wasn't tampered with -and accurately reflects the software contents. In this way, SLSA helps protect -against the risk of: - -- Code modification (by adding a tamper-evident "seal" to code after - source control) -- Uploaded artifacts that were not built by the expected CI/CD system (by marking - artifacts with a factory "stamp" that shows which build service created it) -- Threats against the build system (by providing "manufacturing facility" - best practices for build system services) - -For more exploration of this analogy, see the blog post -[SLSA + SBOM: Accelerating SBOM success with the help of SLSA](/blog/2022/05/slsa-sbom). - -## Who is SLSA for? - -In short: everyone involved in producing and consuming software, or providing -infrastructure for software. - -**Software producers**, such as a development team or open -source maintainers. SLSA gives you protection against insider risk and tampering -along the supply chain to your consumers, increasing confidence that the -software you produce reaches your consumers as you intended. - -**Software consumers**, such as a development team using open source packages, a -government agency using vendored software, or a CISO judging organizational -risk. SLSA gives you a way to judge the security practices of the software you -rely on and be sure that what you receive is what you expected. - -**Infrastructure providers**, who provide infrastructure such as an ecosystem -package manager, build platform, or CI/CD system. As the bridge between the -producers and consumers, your adoption of SLSA enables a secure software supply -chain between them. - -## How SLSA works - -We talk about SLSA in terms of [tracks and levels](levels.md). -A SLSA track focuses on a particular aspect of a supply chain, such as the Build -Track. SLSA v1.0 consists of only a single track ([Build](levels.md#build-track)), but future versions of -SLSA will add tracks that cover other parts of the software supply chain, such -as how source code is managed. - -Within each track, ascending levels indicate increasingly hardened security -practices. Higher levels provide better guarantees against supply chain threats, -but come at higher implementation costs. Lower SLSA levels are designed to be -easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes -used to refer to software that doesn't yet meet any SLSA level. Currently, the -SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels -to be possible in [future revisions](future-directions.md). - -The combination of tracks and levels offers an easy way to discuss whether -software meets a specific set of requirements. By referring to an artifact as -meeting SLSA Build Level 3, for example, you're indicating in one phrase that -the software artifact was built following a set of security practices that -industry leaders agree protect against particular supply chain compromises. - -## What SLSA doesn't cover - -SLSA is only one part of a thorough approach to supply chain security. There -are several areas outside SLSA's current framework that are nevertheless -important to consider together with SLSA such as: - -- Code quality: SLSA does not tell you whether the developers writing the - source code followed secure coding practices. -- Developer trust: SLSA cannot tell you whether a developer is - intentionally writing malicious code. If you trust a developer to write - code you want to consume, though, SLSA can guarantee that the code will - reach you without another party tampering with it. -- Transitive trust for dependencies: the SLSA level of an artifact is - independent of the level of its dependencies. You can use SLSA recursively to - also judge an artifact's dependencies on their own, but there is - currently no single SLSA level that applies to both an artifact and its - transitive dependencies together. For a more detailed explanation of why, - see the [FAQ](faq#q-why-is-slsa-not-transitive). diff --git a/docs/spec/v1.0-rc2/attestation-model.md b/docs/spec/v1.0-rc2/attestation-model.md deleted file mode 100644 index 7cb104f8c..000000000 --- a/docs/spec/v1.0-rc2/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.0-rc2/build-model.svg b/docs/spec/v1.0-rc2/build-model.svg deleted file mode 100644 index c5d5364be..000000000 --- a/docs/spec/v1.0-rc2/build-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.0-rc2/distributing-provenance.md b/docs/spec/v1.0-rc2/distributing-provenance.md deleted file mode 100644 index 99f9497d4..000000000 --- a/docs/spec/v1.0-rc2/distributing-provenance.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Distributing provenance -description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is system implementers and software distributors. ---- - -In order to make provenance for artifacts available after generation -for verification, SLSA requires the distribution and verification of provenance -metadata in the form of SLSA attestations. - -This document provides specifications for distributing provenance, and the -relationship between build artifacts and provenance (build attestations). It is -primarily concerned with artifacts for ecosystems that distribute build -artifacts, but some attention is also paid to ecosystems that distribute -container images or only distribute source artifacts, as many of the same -principles generally apply to any artifact or group of artifacts. - -In addition, this document is primarily for the benefit of artifact -distributors, to understand how they can adopt the distribution of SLSA -provenance. It is primarily concerned with the means of distributing -attestations and the relationship of attestations to build artifacts, and not -with the specific format of the attestation itself. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Background - -The [package ecosystem]'s maintainers are responsible for reliably -redistributing artifacts and provenance, making the producers' expectations -available to consumers, and providing tools to enable safe artifact consumption -(e.g. whether an artifact meets its producer's expectations). - -## Relationship between releases and attestations - -Attestations SHOULD be bound to artifacts, not releases. - -A single "release" of a project, package, or library might include multiple -artifacts. These artifacts result from builds on different platforms, -architectures or environments. The builds need not happen at roughly the same -point in time and might even span multiple days. - -It is often difficult or impossible to determine when a release is 'finished' -because many ecosystems allow adding new artifacts to old releases when adding -support for new platforms or architectures. Therefore, the set of attestations -for a given release MAY grow over time as additional builds and attestations -are created. - -Thus, package ecosystems SHOULD support multiple individual attestations per -release. At the time of a given build, the relevant provenance for that build -can be added to the release, depending on the relationship to the given -artifacts. - -## Relationship between artifacts and attestations - -Package ecosystems SHOULD support a one-to-many relationship from build -artifacts to attestations to ensure that anyone is free to produce and publish -any attestation they might need. However, while there are lots of possible -attestations that can have a relationship to a given artifact, in this context -SLSA is primarily concerned with build attestations, i.e. provenance, and as -such, this specification only considers build attestations, produced by the -same maintainers as the artifacts themselves. - -By providing provenance alongside an artifact in the manner specified by a -given ecosystem, maintainers are considered to be 'elevating' these build -attestations above all other possible attestations that could be provided by -third parties for a given artifact. The ultimate goal is for maintainers to -provide the provenance necessary for a repository to be able to verify some -potential policy that requires a certain SLSA level for publication, not -support the publication of arbitrary attestations by third parties. - -As a result, this provenance SHOULD accompany the artifact at publish time, and -package ecosystems SHOULD provide a way to map a given artifact to its -corresponding attestations. The mappings can be either implicit (e.g. require a -custom filename schema that uniquely identifies the provenance over other -attestation types) or explicit (e.g. it could happen as a de-facto standard -based on where the attestation is published). - -The provenance SHOULD have a filename that is directly related to the build -artifact filename. For example, for an artifact `.`, the -attestation is `.attestation` or some similar extension (for example -[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`.) - -## Where attestations are published - -There are a number of opportunities and venues to publish attestations during -and after the build process. Producers MUST publish attestations in at least -one place, and SHOULD publish attestations in more than one place: - -- **Publish attestations alongside the source repository releases**: If the - source repository hosting provider offers an artifact "release" feature, - such as [GitHub - releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), - producers SHOULD include provenance as part of such releases. This option - has the benefit of requiring no changes to the package registry to support - provenance formats, but has the disadvantage of putting the source - repository hosting providing in the critical path for installers that want to - verify policy at build-time. -- **Publish attestations alongside the artifact in the package registry**: - Many software repositories already support some variety of publishing 1:1 - related files alongside an artifact, sometimes known as “sidecar files”. - For example, PyPI supports publishing `.asc` files representing the PGP - signature for an artifact with the same filename (but different extension). - This option requires the mapping between artifact and attestation (or - attestation vessel) to be 1:1. -- **Publish attestations elsewhere, record their existence in a transparency - log**: Once an attestation has been generated and published for a build, a - hash of the attestation and a pointer to where it is indexed SHOULD be - published to a third-party transparency log that exists outside the source - repository and package registry. Not only are transparency logs such as - [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed - to be immutable, but they typically also make monitoring easier. - Requiring the presence of the attestation in a monitored transparency log - during verification helps ensure the attestation is trustworthy. - -Combining these options gives us a process for bootstrapping SLSA adoption -within an ecosystem, even if the package registry doesn't support publishing -attestations. First, interested projects modify their release process to -produce SLSA provenance. Then, they publish that provenance to their source -repository. Finally, they publish the provenance to the package registry, if -and when the registry supports it. - -Long-term, package registries SHOULD support uploading and distributing -provenance alongside the artifact. This model is preferred for two reasons: - -- trust: clients already trust the package registry as the source of their - artifacts, and don't need to trust an additional service; -- reliability: clients already depend on the package registry as part of - their critical path, so distributing provenance via the registry avoids - adding an additional point of failure. - -Short term, consumers of build artifacts can bootstrap a manual policy by using -the source repository only for projects that publish all artifacts and -attestations to the source repository, and later extend this to all artifacts -published to the package registry via the canonical installation tools once -a given ecosystem supports them. - -## Immutability of attestations - -Attestations SHOULD be immutable. Once an attestation is published as it -corresponds to a given artifact, that attestation is immutable and cannot be -overwritten later with a different attestation that refers to the same -artifact. Instead, a new release (and new artifacts) SHOULD be created. - -## Format of the attestation - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto [SLSA Provenance](/provenance), but -another format MAY be used if both producer and consumer agree and it meets all -the other requirements. - -## Considerations for source-based ecosystems - -Some ecosystems have support for installing directly from source repositories -(an option for Python/`pip`, Go, etc). In these cases, there is no need to -publish or verify provenance because there is no "build" step that translates -between a source repository and an artifact that is being installed. - -However, for ecosystems that install from source repositories _via_ some -intermediary (e.g. [Homebrew installing from GitHub release artifacts generated -from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go -installing through the Go module proxy](https://proxy.golang.org/)), these -ecosystems distribute "source archives" that are not the bit-for-bit identical -form from version control. These intermediaries are transforming the original -source repository in some way that constitutes a "build" and as a result SHOULD -be providing build provenance for this "package", and the recommendations -outlined here apply. - -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.0-rc2/faq.md b/docs/spec/v1.0-rc2/faq.md deleted file mode 100644 index 60c53b28e..000000000 --- a/docs/spec/v1.0-rc2/faq.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Frequently asked questions -description: Answers to questions frequently asked about SLSA. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build systems to -corroborate the provenance of a build. In this way, one can create an overall -system that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a system can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. diff --git a/docs/spec/v1.0-rc2/future-directions.md b/docs/spec/v1.0-rc2/future-directions.md deleted file mode 100644 index 05f200433..000000000 --- a/docs/spec/v1.0-rc2/future-directions.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Future directions -description: The initial draft version (v0.1) of SLSA had a larger scope including protections against tampering with source code and a higher level of build integrity (Build L4). This page collects some early thoughts on how SLSA **might** evolve in future versions to re-introduce these notions and add other additional aspects of automatable supply chain security. ---- - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future versions to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build service and enabling -corraboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream systems - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other systems to corroborate the - provenance. - -
- -
- -## Source track - -A Source track could provide protection against tampering of the source code -prior to the build. - -The initial [draft version (v0.1)](../v0.1/requirements.md#source-requirements) -of SLSA included the following source requirements, which **may or may not** -form the basis for a future Source track: - -- Strong authentication of author and reviewer identities, such as 2-factor - authentication using a hardware security key, to resist account and - credential compromise. -- Retention of the source code to allow for after-the-fact inspection and - future rebuilds. -- Mandatory two-person review of all changes to the source to prevent a single - compromised actor or account from introducing malicious changes. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md diff --git a/docs/spec/v1.0-rc2/images/provenance-model.svg b/docs/spec/v1.0-rc2/images/provenance-model.svg deleted file mode 100644 index 6a3296dde..000000000 --- a/docs/spec/v1.0-rc2/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.0-rc2/index.md b/docs/spec/v1.0-rc2/index.md deleted file mode 100644 index 705fe7b74..000000000 --- a/docs/spec/v1.0-rc2/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: SLSA specification -description: SLSA is a specification for describing and incrementally improving supply chain security, established by industry consensus. It is organized into a series of levels that describe increasing security guarantees. This is **version 1.0** of the SLSA specification, which defines the SLSA levels. ---- - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **version 1.0 RC2** of the SLSA specification, which defines the SLSA -levels and recommended attestation formats, including provenance. - -{%- for section in site.data.nav.v10-rc2 %} -{%- if section.children %} - -## {{ section.title }} - -{{ section.description }} - - - -| Page | Description -| ---- | ----------- -{%- for child in section.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} -{%- endfor %} - - -{%- endif %} -{%- endfor %} diff --git a/docs/spec/v1.0-rc2/levels.md b/docs/spec/v1.0-rc2/levels.md deleted file mode 100644 index 2182fd0de..000000000 --- a/docs/spec/v1.0-rc2/levels.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: Security levels -description: SLSA is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This page is a descriptive overview of the SLSA levels and tracks, describing their intent. ---- - -SLSA is organized into a series of levels that provide increasing supply chain -security guarantees. This gives you confidence that software hasn’t been -tampered with and can be securely traced back to its source. - -This page is a descriptive overview of the SLSA levels and tracks, describing -their intent. For the prescriptive requirements for each level, see -[Requirements](requirements.md). For a general overview of SLSA, see -[About SLSA](principles.md). - -## Levels and tracks - -SLSA levels are split into *tracks*. Each track has its own set of levels that -measure a particular aspect of supply chain security. The purpose of tracks is -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 - - - -> 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 -> Build track. A Source track may be added in [future versions]. - -## Build track - -The SLSA build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance. Provenance describes -what entity built the artifact, what process they used, and what the inputs -were. The lowest level only requires the provenance to exist, while higher -levels provide increasing protection against tampering of the build, the -provenance, or the artifact. - -The primary purpose of the build track is to enable [verification] that the -artifact was built as expected. Consumers have some way of knowing what the -expected provenance should look like for a given package and then compare each -package artifact's actual provenance to those expectations. Doing so prevents -several classes of [supply chain threats](threats.md). - -Each ecosystem (for open source) or organization (for closed source) defines -exactly how this is implemented, including: means of defining expectations, what -provenance format is accepted, whether reproducible builds are used, how -provenance is distributed, when verification happens, and what happens on -failure. Guidelines for implementers can be found in the -[requirements](requirements.md). - -
- -### Build L0: No guarantees - -
-
Summary
- -No requirements---L0 represents the lack of SLSA. - -
Intended for
- -Development or test builds of software that are built and run on the same -machine, such as unit tests. - -
Requirements
- -n/a - -
Benefits
- -n/a - -
-
-
- -### Build L1: Provenance exists - -
-
Summary
- -Package has provenance showing how it was built. Can be used to prevent mistakes -but is trivial to bypass or forge. - -
Intended for
- -Projects and organizations wanting to easily and quickly gain some benefits of -SLSA---other than tamper protection---without changing their build workflows. - -
Requirements
- -- Software producer follows a consistent build process so that others can form - expectations about what a "correct" build looks like. - -- Build system automatically generates [provenance] describing how the - artifact was built, including: what entity built the package, what build - process they used, and what the top-level input to the build were. - -- Software producer distributes provenance to consumers, preferably using a - convention determined by the package ecosystem. - -
Benefits
- -- Makes it easier for both producers and consumers to debug, patch, rebuild, - and/or analyze the software by knowing its precise source version and build - process. - -- With [verification], prevents mistakes during the release process, such as - building from a commit that is not present in the upstream repo. - -- Aids organizations in creating an inventory of software and build systems - used across a variety of teams. - -
Notes
- -- Provenance may be incomplete and/or unsigned at L1. Higher levels require - more complete and trustworthy provenance. - -
- -
-
- -### Build L2: Build service - -
-
Summary
- -Forging the provenance or evading verification requires an explicit "attack", -though this may be easy to perform. Deters unsophisticated adversaries or those -who face legal or financial risk. - -In practice, this means that builds run on a hosted service that generates and -signs[^sign] the provenance. - -
Intended for
- -Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build service, while waiting for changes to the build -service itself required by [Build L3]. - -
Requirements
- -All of [Build L1], plus: - -- The build runs on a hosted build service that generates and signs[^sign] the - provenance itself. This may be the original build, an after-the-fact - reproducible build, or some equivalent system that ensures the - trustworthiness of the provenance. - -- Downstream verification of provenance includes validating the authenticity - of the provenance. - -
Benefits
- -All of [Build L1], plus: - -- Prevents tampering after the build through digital signatures[^sign]. - -- Deters adversaries who face legal or financial risk by evading security - controls, such as employees who face risk of getting fired. - -- Reduces attack surface by limiting builds to specific build services that - can be audited and hardened. - -- Allows large-scale migration of teams to supported build services early - while further hardening work ([Build L3]) is done in parallel. - -
-
-
- -[^sign]: Alternate means of verifying the authenticity of the provenance are - also acceptable. - -### Build L3: Hardened builds - -
-
Summary
- -Forging the provenance or evading verification requires exploiting a -vulnerability that is beyond the capabilities of most adversaries. - -In practice, this means that builds run on a hardened build service that offers -strong tamper protection. - -
Intended for
- -Most software releases. Build L3 usually requires significant changes to -existing build services. - -
Requirements
- -All of [Build L2], plus: - -- Build service implements strong controls to: - - - prevent runs from influencing one another, even within the same project. - - prevent secret material used to sign the provenance from being - accessible to the user-defined build steps. - -
Benefits
- -All of [Build L2], plus: - -- Prevents tampering during the build---by insider threats, compromised - credentials, or other tenants. - -- Greatly reduces the impact of compromised package upload credentials by - requiring attacker to perform a difficult exploit of the build process. - -- Provides strong confidence that the package was built from the official - source and build process. - -
-
- - - -[build l0]: #build-l0 -[build l1]: #build-l1 -[build l2]: #build-l2 -[build l3]: #build-l3 -[future versions]: future-directions.md -[previous version]: ../v0.1/levels.md -[provenance]: terminology.md -[verification]: verifying-artifacts.md diff --git a/docs/spec/v1.0-rc2/onepage.md b/docs/spec/v1.0-rc2/onepage.md deleted file mode 100644 index abda9fd00..000000000 --- a/docs/spec/v1.0-rc2/onepage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SLSA Specification -description: A one-page rendering of all that is included in SLSA v1.0. -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.0-rc2/" %} -{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,terminology,levels,requirements,distributing-provenance,verifying-systems,verifying-artifacts,threats,provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.0-rc2/principles.md b/docs/spec/v1.0-rc2/principles.md deleted file mode 100644 index 407091d2f..000000000 --- a/docs/spec/v1.0-rc2/principles.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Guiding principles -description: An introduction to the guiding principles behind SLSA's design decisions. ---- - -This page is an introduction to the guiding principles behind SLSA's design -decisions. - -## Trust systems, verify artifacts - -Establish trust in a small number of systems---such as change management, build, -and packaging systems---and then automatically verify the many artifacts -produced by those systems. - -**Reasoning**: Trusted computing bases are unavoidable---there's no choice but -to trust some systems. Hardening and verifying systems is difficult and -expensive manual work, and each trusted system expands the attack surface of the -supply chain. Verifying that an artifact is produced by a trusted system, -though, is easy to automate. - -To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited -numbers of systems and then automate verification of the artifacts produced by those systems. -The attack surface and work to establish trust does not scale with the number of artifacts produced, -as happens when artifacts each use a different trusted system. - -**Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant -amount of central work. - -### Example - -A security engineer analyzes the architecture and implementation of a build -system to ensure that it meets the SLSA Build Track requirements. Following the -analysis, the public keys used by the build system to sign provenance are -"trusted" up to the given SLSA level. Downstream systems verify the provenance -signed by the public key to automatically determine that an artifact meets the -SLSA level. - -### Corollary: Minimize the number of trusted systems - -A corollary to this principle is to minimize the size of the trusted computing -base. Every system we trust adds attack surface and increases the need for -manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team within an organization maintaining their own build system, use a - shared build system. Hardening work can be shared across all teams. -- Remove the need to trust components. For example, use end-to-end signing - to avoid the need to trust intermediate distribution systems. - -## Trust code, not individuals - -Securely trace all software back to source code rather than trust individuals who have write access to package registries. - -**Reasoning**: Code is static and analyzable. People, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. - -**Benefits**: Removes the possibility for a trusted individual---or an -attacker abusing compromised credentials---to tamper with source code -after it has been committed. - -## Prefer attestations over inferences - -Require explicit attestations about an artifact's provenance; do not infer -security properties from a system's configurations. - -**Reasoning**: Theoretically, access control can be configured so that the only path from -source to release is through the official channels: the CI/CD system pulls only -from the proper source, package registry allows access only to the CI/CD system, -and so on. We might infer that we can trust artifacts produced by these systems -based on the system's configuration. - -In practice, though, these configurations are almost impossible to get right and -keep right. There are often over-provisioning, confused deputy problems, or -mistakes. Even if a system is configured properly at one moment, it might not -stay that way, and humans almost always end up getting in the access control -lists. - -Access control is still important, but SLSA goes further to provide defense in depth: it **requires proof in -the form of attestations that the package was built correctly**. - -**Benefits**: The attestation removes intermediate systems from the trust base and ensures that -individuals who are accidentally granted access do not have sufficient permission to tamper with the package. diff --git a/docs/spec/v1.0-rc2/provenance.md b/docs/spec/v1.0-rc2/provenance.md deleted file mode 100644 index d7a9403fa..000000000 --- a/docs/spec/v1.0-rc2/provenance.md +++ /dev/null @@ -1,583 +0,0 @@ ---- -title: Provenance -description: Description of SLSA provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1-rc2" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](/spec/v1.0-rc2/requirements#provenance-generation). - -## Model - -Provenance is an attestation that a particular build platform produced a set of -software artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant build platform. - The `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build systems.) - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - system ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `systemParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](/spec/v1.0-rc2/requirements). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." - Such changes do not update the `predicateType`. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -Link: [provenance.proto](schema/provenance.proto) - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`systemParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build system. They MUST be complete at SLSA Build L3, meaning that -that there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build system SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
systemParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build system is already trusted, and in many cases it is -not practical to do so. - -***NOTE:** This field is named `internalParameters` in [v1](/provenance/v1) final.* - -
resolvedDependencies -array (ResourceDescriptor) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script -fetches and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be -listed here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `systemParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `systemParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build system. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build system to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build service to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the build platform that executed the invocation, which is trusted to -have correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ResourceDescriptor) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or -incident response. For example, this might reference logs generated during -the build and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted build platform. This is -[intended](/spec/v1.0-rc2/verifying-artifacts#step-1-check-slsa-build-level) -to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -The `builder.id` URI SHOULD resolve to documentation explaining: - -- The scope of what this ID represents. -- The claimed SLSA Build level. -- The accuracy and completeness guarantees of the fields in the provenance. -- Any fields that are generated by the tenant-controlled build process and not - verified by the trusted control plane, except for the `subject`. -- The interpretation of any extension fields. - -
builderDependencies -array (ResourceDescriptor) - -Dependencies used by the orchestrator that are not run within the workload -and that do not affect the build, but might affect the provenance generation -or security guarantees. - -
version -map (string→string) - -Map of names of components of the build platform to their version. - -
- -The build platform, or builder for short, represents the transitive -closure of all the entities that are, by necessity, [trusted] to faithfully run -the build and record the provenance. This includes not only the software but the -hardware and people involved in running the service. For example, a particular -instance of [Tekton](https://tekton.dev/) could be a build platform, while -Tekton itself is not. For more info, see [Build -model](/spec/v1.0-rc2/terminology#build-model). - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -> ⚠ **RFC:** Do we want/need to identify the tenant of the build system, -> separately from the build system itself? If so, a single `id` -> that combines both (e.g. -> `https://builder.example/tenants/company1.example/project1`) or two separate -> fields (e.g. `{"id": "https://builder.example", "tenant": -> "https://company1.example/project1"}`)? What would the use case be for this? -> How does [verification] work? - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -### Extension fields - -[Extension fields]: #extension-fields - -Implementations MAY add extension fields to any JSON object to describe -information that is not captured in a standard field. Guidelines: - -- Extension fields SHOULD use names of the form `_`, e.g. - `examplebuilder_isCodeReviewed`. This practice avoids field name collisions - by namespacing each vendor. Non-extension field names never contain an - underscore. -- Extension fields MUST NOT alter the meaning of any other field. In other - words, an attestation with an absent extension field MUST be interpreted - identically to an attestation with an unrecognized (and thus ignored) - extension field. -- Extension fields SHOULD follow the [monotonic principle][parsing rules], - meaning that deleting or ignoring the extension SHOULD NOT turn a DENY - decision into an ALLOW. - -## Verification - -[Verification]: verifying-artifacts.md - -Please see [Verifying Artifacts][Verification] for a detailed discussion of -provenance verification. - -## Index of build types - -The following is an partial index of build type definitions. Each contains a -complete example predicate. - - - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) -- [Google Cloud Build (community-maintained)](https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1) - -To add an entry here, please send a pull request on GitHub. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "systemParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "builderDependencies": null, // not in v0.2 - "version": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.0 RC2 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build systems, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed: - - `parameters` -> `externalParameters` (slight change in semantics) - - `environment` -> `systemParameters` (slight change in semantics) - - `materials` -> `resolvedDependencies` (slight change in semantics) - - `buildInvocationId` -> `invocationId` - - `buildStartedOn` -> `startedOn` - - `buildFinishedOn` -> `finishedOn` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - ResourceDescriptor: `annotations`, `content`, `downloadLocation`, - `mediaType`, `name` - - Builder: `builderDependencies` and `version` - - `byproducts` -- Changed naming convention for extension fields. - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: /spec/v1.0-rc2/threats -[trusted]: /spec/v1.0-rc2/principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.0-rc2/requirements.md b/docs/spec/v1.0-rc2/requirements.md deleted file mode 100644 index 9971d2388..000000000 --- a/docs/spec/v1.0-rc2/requirements.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: Producing artifacts -description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is system implementers and security engineers. ---- - - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is system implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Levels](levels.md). For background, see [Terminology](terminology.md). To -better understand the reasoning behind the requirements, see -[Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -In order to produce artifacts with a specific build level, responsibility is -split between the Producer and -Build system. The build system MUST strengthen the security controls in -order to achieve a specific level while the producer MUST choose and adopt a -build system capable of achieving a desired build level, implementing any -controls as specified by the chosen system. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build system - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build system - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Unforgeable - ✓ -
Isolation strength - Build service - ✓✓ -
Isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure system is beyond the -scope of this specification, all implementations MUST use industry security -best practices to be conformant to this specification. This includes, but is -not limited to, using proper access controls, securing communications, -implementing proper management of cryptographic secrets, doing frequent updates, -and promptly fixing known vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -NOTE: There were more requirements for producers in the initial -[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted -how a package can be built. These were removed in the v1.0 specification and -will be reassessed and re-added as indicated in the -[future directions](future-directions.md). - -### Choose an appropriate build system - -The producer MUST select a build system that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -If a producer wishes to distribute their artifact through a [package ecosystem] -that requires explicit metadata about the build process in the form of a -configuration file, the producer MUST complete the configuration file and keep -it up to date. This metadata might include information related to the artifact's -source repository and build parameters. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the -[package ecosystem], provided that the package ecosystem is capable of -distributing provenance. - -## Build system - -[Build system]: #build-system - -A package's build system is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build system is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build system used -by a single software project, or even an individual's workstation. Ideally, one -build system is used by many different software packages so that consumers can -[minimize the number of trusted systems](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build system is responsible for providing two things: [provenance -generation] and [isolation between builds]. The [Build level](levels.md#build-track) describes -the degree to which each of these properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build system is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the overall provenance integrity according to -minimum requirements on its: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package by cryptographic digest and describes how that package was -produced. The format MUST be acceptable to the [package ecosystem] and/or -[consumer](verifying-artifacts.md#consumer). - -It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. - -If using an alternate format, it MUST contain the equivalent information as SLSA -Provenance at each level and SHOULD be bi-directionally translatable to SLSA -Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build system and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only to -the service that generated the provenance attestation. - -This allows the consumer to trust the contents of the provenance attestation, -such as the identity of the build system. - -*Accuracy:* The provenance MUST be generated by the build system (i.e. within -the trust boundary identified in the provenance) and not by a tenant of the -build system (i.e. outside the trust boundary), except as noted below. - -- The data in the provenance MUST be obtained from the build service, either - because the generator *is* the build service or because the provenance - generator reads the data directly from the build service. -- The build system MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. -- Exceptions for fields that MAY be generated by a tenant of the build system: - - The names and cryptographic digests of the output artifacts, i.e. - `subject` in [SLSA Provenance]. See [forge output digest of the - provenance](threats#forged-digest) for explanation of why this is - acceptable. - - Any field that is not marked as REQUIRED for Build L2. For example, - `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at - Build L2. Builders SHOULD document any such cases of tenant-generated - fields. - -*Completeness:* SHOULD be complete. - -- There MAY be [external parameters] that are not sufficiently captured in - the provenance. -- Completeness of resolved dependencies is best effort. - - ✓✓ -
Provenance is Unforgeable - -*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. - -- Any secret material used for authenticating the provenance, for example the - signing key used to generate a digital signature, MUST be stored in a secure - management system appropriate for such material and accessible only to the - build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - service in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted in [Provenance - is Authentic](#provenance-authentic). (Build L3 does not require additional - fields beyond those of L2.) - -*Completeness:* SHOULD be complete. - -- [External parameters] MUST be fully enumerated. -- Completeness of resolved dependencies is best effort. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build system is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build system's isolation strength, see -[Verifying build systems](verifying-systems.md). - - - - -
RequirementDescriptionL1L2L3 - -
Build service - - -All build steps ran using some build service, not on an individual's -workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Isolated - - -The build service ensured that the build steps ran in an isolated environment, -free of unintended external influence. In other words, any external influence on -the build was specifically requested by the build itself. This MUST hold true -even between builds within the same tenant project. - -The build system MUST guarantee the following: - -- It MUST NOT be possible for a build to access any secrets of the build - service, such as the provenance signing key, because doing so would - compromise the authenticity of the provenance. -- It MUST NOT be possible for two builds that overlap in time to influence one - another, such as by altering the memory of a different build process running - on the same machine. -- It MUST NOT be possible for one build to persist or influence the build - environment of a subsequent build. In other words, an ephemeral build - environment MUST be provisioned for each build. -- It MUST NOT be possible for one build to inject false entries into a build - cache used by another build, also known as "cache poisoning". In other - words, the output of the build MUST be identical whether or not the cache is - used. -- The build system MUST NOT open services that allow for remote influence - unless all such interactions are captured as `externalParameters` in the - provenance. - -There are no sub-requirements on the build itself. Build L3 is limited to -ensuring that a well-intentioned build runs securely. It does not require that -build systems prevent a producer from performing a risky or insecure build. In -particular, the "Isolated" requirement does not prohibit a build from calling -out to a remote execution service or a "self-hosted runner" that is outside the -trust boundary of the build platform. - -NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" -in the initial [draft version (v0.1)](../v0.1/requirements.md). - -NOTE: This requirement is not to be confused with "Hermetic", which roughly -means that the build ran with no network access. Such a requirement requires -substantial changes to both the build system and each individual build, and is -considered in the [future directions](future-directions.md). - - ✓ -
- -[external parameters]: provenance.md#externalParameters -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.0-rc2/schema/provenance.cue b/docs/spec/v1.0-rc2/schema/provenance.cue deleted file mode 100644 index 672e81328..000000000 --- a/docs/spec/v1.0-rc2/schema/provenance.cue +++ /dev/null @@ -1,46 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1-rc2", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "systemParameters": object, - "resolvedDependencies": [ ...#ResourceDescriptor ], - }, - "runDetails": { - "builder": { - "id": string, - "builderDependencies": [ ...#ResourceDescriptor ], - "version": { ...string }, - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ResourceDescriptor ], - } - } -} - -#ResourceDescriptor: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "gitCommit": string, - [string]: string, - }, - "name": string, - "downloadLocation": string, - "mediaType": string, - "content": bytes, // base64-encoded - "annotations": object, -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.0-rc2/schema/provenance.proto b/docs/spec/v1.0-rc2/schema/provenance.proto deleted file mode 100644 index 72b348fd7..000000000 --- a/docs/spec/v1.0-rc2/schema/provenance.proto +++ /dev/null @@ -1,50 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct system_parameters = 3; - repeated ResourceDescriptor resolved_dependencies = 4; -} - -message ResourceDescriptor { - string uri = 1; - map digest = 2; - string name = 3; - string download_location = 4; - string media_type = 5; - bytes content = 6; - google.protobuf.Struct annotations = 7; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ResourceDescriptor byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ResourceDescriptor builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.0-rc2/terminology.md b/docs/spec/v1.0-rc2/terminology.md deleted file mode 100644 index 4d795ab40..000000000 --- a/docs/spec/v1.0-rc2/terminology.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -title: Terminology -description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting. ---- - - -Before diving into the [SLSA Levels](levels.md), we need to establish a core set -of terminology and models to describe what we're protecting. - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). - -[build]: #build-model -[package]: #package-model -[SLSA Provenance]: /provenance/v1-rc2 - -### Roles - -Throughout the specification, you will see reference to the following roles -that take part in the software supply chain. Note that in practice a role may -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. - -### Build model - -We model a build as running on a multi-tenant platform, where each execution is -independent. A tenant defines the build by specifying parameters through some -sort of external interface, often including a reference to a configuration file -in source control. The control plane then runs the build by interpreting the -parameters, fetching some initial set of dependencies, initializing the build -environment, and then starting execution. The build then performs arbitrary -steps, possibly fetching additional dependencies, and outputs one or more -artifacts. Finally, for SLSA Build L2+, the control plane outputs provenance -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. - -Notably, there is no formal notion of "source" in the build model, just -parameters and dependencies. Most build platforms have an explicit "source" -artifact to be built, which is often a git repository; in the build model, the -reference to this artifact is a parameter while the artifact itself is a -dependency. - -For examples on how this model applies to real-world build systems, see [index -of build types](/provenance/v1-rc2#index-of-build-types). - -### Package model - -Software is distributed in identifiable units called packages -according the the rules and conventions of a package ecosystem. -Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and -[OCI](https://github.com/opencontainers/distribution-spec), while examples of -informal ecosystems include links to files on a website or distribution of -first-party software within a company. - -Abstractly, a consumer locates software within an ecosystem by asking a -package registry to resolve a mutable package name into an -immutable package artifact.[^label] To publish a package -artifact, the software producer asks the registry to update this mapping to -resolve to the new artifact. The registry represents the entity or entities with -the power to alter what artifacts are accepted by consumers for a given package -name. For example, if consumers only accept packages signed by a particular -public key, then it is access to that public key that serves as the registry. - -The package name is the primary security boundary within a package ecosystem. -Different package names represent materially different pieces of -software---different owners, behaviors, security properties, and so on. -Therefore, **the package name is the primary unit being protected in SLSA**. -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. - -Ambiguous terms to avoid: - -- *Package repository* --- Could mean either package registry or package name, - depending on the ecosystem. To avoid confusion, we always use "repository" - exclusively to mean "source repository", where there is no ambiguity. -- *Package manager* (without "client") --- Could mean either package - ecosystem, package registry, or client-side tooling. - -### Mapping to real-world ecosystems - -Most real-world ecosystems fit the package model above but use different terms. -The table below attempts to document how various ecosystems map to the SLSA -Package model. There are likely mistakes and omissions; corrections and -additions are welcome! - - - - - - - - - - - - - - - - - - - - - - - - - - -
Package ecosystem - Package registry - Package name - Package artifact -
Languages -
Cargo (Rust) - Registry - Crate name - Artifact -
CPAN (Perl) - Upload server - Distribution - Release (or Distribution) -
Go - Module proxy - Module path - Module -
Maven (Java) - Repository - Group ID + Artifact ID - Artifact -
npm (JavaScript) - Registry - Package Name - Package -
NuGet (C#) - Host - Project - Package -
PyPA (Python) - Index - Project Name - Distribution -
Operating systems -
Dpkg (e.g. Debian) - ? - Package name - Package -
Flatpak - Repository - Application - Bundle -
Homebrew (e.g. Mac) - Repository (Tap) - Package name (Formula) - Binary package (Bottle) -
Pacman (e.g. Arch) - Repository - Package name - Package -
RPM (e.g. Red Hat) - Repository - Package name - Package -
Nix (e.g. NixOS) - Repository (e.g. Nixpkgs) or binary cache - Derivation name - Derivation or store object -
Storage systems -
GCS - n/a - Object name - Object -
OCI/Docker - Registry - Repository - Object -
Meta -
deps.dev: System - Packaging authority - Package - n/a -
purl: type - Namespace - Name - n/a -
- -Notes: - -- Go uses a significantly different distribution model than other ecosystems. - In go, the package name is a source repository URL. While clients can fetch - directly from that URL---in which case there is no "package" or - "registry"---they usually fetch a zip file from a *module proxy*. The module - proxy acts as both a builder (by constructing the package artifact from - source) and a registry (by mapping package name to package artifact). People - trust the module proxy because builds are independently reproducible and a - *checksum database* guarantees that all clients receive the same artifact - for a given URL. - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build system is -certified to ensure conformance with the requirements at the level claimed by -the build system. This certification should happen on a recurring cadence with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer defined -expectations of where the package source code was retrieved from and on what -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. - -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. - -
- -
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. - -
diff --git a/docs/spec/v1.0-rc2/threats-overview.md b/docs/spec/v1.0-rc2/threats-overview.md deleted file mode 100644 index 8e0093a46..000000000 --- a/docs/spec/v1.0-rc2/threats-overview.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Supply chain threats -description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA can help. ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA can help. For a more technical discussion, see [Threats & mitigations](threats.md). - -## Summary - -![Supply Chain Threats](../../images/v1.0-rc2/supply-chain-threats.svg) - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that all changes to the source code reflect the -intent of the software producer. Intent of an organization is difficult to -define, so SLSA approximates this as approval from two authorized -representatives. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - -
-Integrity threat -Known example -How SLSA can help -
A -Submit unauthorized change (to source repo) -SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. -Two-person review could have caught the unauthorized change. -
B -Compromise source repo -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code platform would have been a much harder target for the attackers. -
C -Build from modified source (not matching source repo) -Webmin: Attacker modified the build infrastructure to use source files not matching source control. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
D -Use compromised dependency (i.e. A-H, recursively) -event-stream: Attacker added an innocuous dependency and then later updated the dependency to add malicious behavior. The update did not match the code submitted to GitHub (i.e. attack F). -Applying SLSA recursively to all dependencies would have prevented this particular vector, because the provenance would have indicated that it either wasn't built from a proper builder or that the source did not come from GitHub. -
E -Compromise build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA levels require stronger security controls for the build platform, making it more difficult to compromise and gain persistence. -
F -Upload modified package (not matching build process) -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Compromise package repo -Attacks on Package Mirrors: Researcher ran mirrors for several popular package repositories, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Use compromised package -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
- - - - - - -
-Availability threat -Known example -How SLSA can help -
D -Dependency becomes unavailable -Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. diff --git a/docs/spec/v1.0-rc2/threats.md b/docs/spec/v1.0-rc2/threats.md deleted file mode 100644 index 54c38f0cc..000000000 --- a/docs/spec/v1.0-rc2/threats.md +++ /dev/null @@ -1,523 +0,0 @@ ---- -title: Threats & mitigations -description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. ---- - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations in SLSA. For an introduction to the -supply chain threats that SLSA protects against, see [Supply chain threats]. - -The examples on this page are meant to: - -- Explain the reasons for each of the SLSA [requirements](requirements.md). -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](levels.md) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - -
- -![Supply Chain Threats](../../images/v1.0-rc2/supply-chain-threats.svg) - -## Source threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes the threat of an authorized individual introducing an unauthorized -change---in other words, an insider threat. - -SLSA v1.0 does not address source threats, but we anticipate doing so in a -[future version](future-directions.md#source-track). In the meantime, the -threats and potential mitigations listed here show how SLSA v1.0 can fit into a -broader supply chain security program. - -### (A) Submit unauthorized change - -An adversary introduces a change through the official source control management -interface without any special administrator privileges. - -SLSA v1.0 does not address this threat, but it may be addressed in a [future -version](future-directions). - -### (B) Compromise source repo - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -SLSA v1.0 does not address this threat, but it may be addressed in a [future -version](future-directions). - -### (C) Build from modified source - -An adversary builds from a version of the source code that does not match the -official source control repository. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (E) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build service pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -## Dependency threats - -A dependency threat is a vector for an adversary to introduce behavior to an -artifact through external software that the artifact requires to function. - -SLSA mitigates dependency threats when you verify your dependencies' SLSA -provenance. - -### (D) Use compromised dependency - -
Use a compromised build dependency - -*Threat:* The adversary injects malicious code into software required to build -the artifact. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0, though the build -provenance may list build dependencies on a best-effort basis for forensic -analysis. You may be able to mitigate this threat by pinning your build -dependencies, preferably by digest rather than version number. Alternatively, -you can [apply SLSA recursively](verifying-artifacts.md#step-3-optional-check-dependencies-recursively), -but we have not yet standardized how to do so. - -*Example:* The artifact uses `libFoo` and requires its source code to compile. -The adversary compromises `libFoo`'s source repository and inserts malicious -code. When your artifact builds, it contains the adversary's malicious code. - -
- -
Use a compromised runtime dependency - -*Threat:* The adversary injects malicious code into software required to run the -artifact. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. However, you can -mitigate this threat by verifying SLSA provenance for all of your runtime -dependencies that provide provenance. - -*Example:* The artifact dynamically links `libBar` and requires a binary version -to run. The adversary compromises `libBar`'s build process and inserts malicious -code. When your artifact runs, it contains the adversary's malicious code. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - -### (E) Compromise build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Forge values of the provenance (other than output digest) (Build L2+) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, the trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][unforgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -service to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Forge output digest of the provenance (n/a) - -*Threat:* The tenant-controlled build process sets output artifact digest -(`subject` in SLSA Provenance) without the trusted control plane verifying that -such an artifact was actually produced. - -*Mitigation:* None; this is not a problem. Any build claiming to produce a given -artifact could have actually produced it by copying it verbatim from input to -output.[^preimage] (Reminder: Provenance is only a claim that a particular -artifact was *built*, not that it was *published* to a particular registry.) - -*Example:* A legitimate MyPackage artifact has digest `abcdef` and is built -from source repo `good/my-package`. A malicious build from source repo -`evil/my-package` claims that it built artifact `abcdef` when it did not. -Solution: Verifier rejects because the source location does not match; the -forged digest is irrelevant. - -[^preimage]: Technically this requires the artifact to be known to the - adversary. If they only know the digest but not the actual contents, they - cannot actually build the artifact without a [preimage attack] on the digest - algorithm. However, even still there are no known concerns where this is a - problem. - -[preimage attack]: https://en.wikipedia.org/wiki/Preimage_attack - -
-
Compromise project owner (Build L2+) - -*Threat:* An adversary gains owner permissions for the artifact's build project. - -*Mitigation:* The build project owner must not have the ability to influence the -build process or provenance generation. - -*Example:* MyPackage is built on Awesome Builder under the project "mypackage". -Adversary is an administrator of the "mypackage" project. Awesome Builder allows -administrators to debug build machines via SSH. An adversary uses this feature -to alter a build in progress. - -
-
Compromise other build (Build L3) - -*Threat:* Perform a malicious build that alters the behavior of a benign -build running in parallel or subsequent environments. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other or persist changes. - -*Example 1:* A build service runs all builds for project MyPackage on -the same machine as the same Linux user. An adversary starts a malicious build -that listens for another build and swaps out source files, then starts a benign -build. The benign build uses the malicious build's source files, but its -provenance says it used benign source files. Solution: The build platform -changes architecture to isolate each build in a separate VM or similar. - -*Example 2:* A build service uses the same machine for subsequent -builds. An adversary first runs a build that replaces the `make` binary with a -malicious version, then subsequently runs an otherwise benign build. Solution: -The builder changes architecture to start each build with a clean machine image. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build service. - -*Mitigation:* Builds are [isolated] from the trusted build service control -plane, and only the control plane has [access][unforgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a malicious artifact to a build cache that is later picked up by a -benign build process. - -*Mitigation:* Build caches must be [isolate][isolated] between builds to prevent -such cache poisoning attacks. - -*Example:* Build system uses a build cache across builds, keyed by the hash of -the source file. Adversary runs a malicious build that creates a "poisoned" -cache entry with a falsified key, meaning that the value wasn't really produced -from that source. A subsequent build then picks up that poisoned cache entry. - -
-
Compromise build platform admin (verification) - -*Threat:* An adversary gains admin permissions for the artifact's build platform. - -*Mitigation:* The build platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals, audit -logging). - -*Example:* MyPackage is built on Awesome Builder. Awesome Builder allows -engineers on-call to SSH into build machines to debug production issues. An -adversary uses this access to modify a build in progress. Solution: Consumers -do not accept provenance from the build platform unless they trust sufficient -controls are in place to prevent abusing admin privileges. - -
- -### (F) Upload modified package - -An adversary uploads a package not built from the proper build process. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildService, which is only -trusted up to Build L2, and then exploits SomeOtherBuildService to inject -malicious behavior. Solution: Verifier rejects because builder is not as -expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Compromise package repo - -An adversary modifies the package on the package repository using an -administrative interface or through a compromise of the infrastructure. - -
De-list artifact - -*Threat:* The package repository stops serving the artifact. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. - -
- -
De-list provenance - -*Threat:* The package repository stops serving the provenance. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. - -
- -### (H) Use compromised package - -An adversary modifies the package after it has left the package repository, or -tricks the user into using an unintended package. - -
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* **Mostly outside the scope of SLSA.** That said, the requirement -to make the source available can be a mild deterrent, can aid investigation or -ad-hoc analysis, and can complement source-based typosquatting solutions. - -
- -## Availability threats - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA v1.0 does not address availability threats, though future versions might. - -
(A)(B) Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* Some system retains the revision and its version control history, -making it available for inspection indefinitely. Users cannot delete the -revision except as part of a transparent legal or privacy process. - -*Example:* An adversary submits malicious code to the MyPackage GitHub repo, -builds from that revision, then does a force push to erase that revision from -history (or requests that GitHub delete the repo.) This would make the revision -unavailable for inspection. Solution: Verifier rejects the package because it -lacks a positive attestation showing that some system, such as GitHub, ensured -retention and availability of the source code. - -
-
(D) A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* **Outside the scope of SLSA.** That said, some solutions to -support hermetic and reproducible builds may also reduce the impact of this -threat. - -
- -## Verification threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above. - -
Tamper with recorded expectations - -*Threat:* Modify the verifier's recorded expectations, causing the verifier to -accept an unofficial package artifact. - -*Mitigation:* Changes to recorded expectations requires some form of -authorization, such as two-party review. - -*Example:* The package ecosystem records its expectations for a given package -name in a configuration file that is modifiable by that package's producer. The -configuration for MyPackage expects the source repository to be -`good/my-package`. The adversary modifies the configuration to also accept -`evil/my-package`, and then builds from that repository and uploads a malicious -version of the package. Solution: Changes to the recorded expectations require -two-party review. - -
-
Forge change metadata - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* Source control platform strongly authenticates actor identity, -timestamp, and parent revisions. - -*Example:* Adversary submits a git commit with a falsified author and timestamp, -and then rewrites history with a non-fast-forward update to make it appear to -have been made long ago. Solution: Consumer detects this by seeing that such -changes are not strongly authenticated and thus not trustworthy. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Require cryptographically secure hash functions for commit -checksums and provenance subjects, such as SHA-256. - -*Examples:* Construct a benign file and a malicious file with the same SHA-1 -hash. Get the benign file reviewed and then submit the malicious file. -Alternatively, get the benign file reviewed and submitted and then build from -the malicious file. Solution: Only accept cryptographic hashes with strong -collision resistance. - -
- -
- - - -[authentic]: requirements.md#provenance-authentic -[exists]: requirements.md#provenance-exists -[isolated]: requirements.md#isolated -[unforgeable]: requirements.md#provenance-unforgeable -[service]: requirements.md#build-service -[supply chain threats]: threats-overview diff --git a/docs/spec/v1.0-rc2/use-cases.md b/docs/spec/v1.0-rc2/use-cases.md deleted file mode 100644 index d9908ea6d..000000000 --- a/docs/spec/v1.0-rc2/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package repository. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build systems rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified from a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.0-rc2/verification-model.svg b/docs/spec/v1.0-rc2/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.0-rc2/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.0-rc2/verification_summary.md b/docs/spec/v1.0-rc2/verification_summary.md deleted file mode 100644 index c2e08d254..000000000 --- a/docs/spec/v1.0-rc2/verification_summary.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v1-rc2" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software producers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [resolvedDependencies](/provenance/v1-rc2#resolvedDependencies) of the artifact -being verified (recursively) or b) matching the non-source dependency -listed in `resolvedDependencies` (`subject.digest` == -`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` == -`resolvedDependencies.uri`) to a VSA _for that dependency_ and using -`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependencyLevels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1-rc2", -"predicate": { - // Required - "verifier": { - "id": "" - }, - "timeVerified": , - "resourceUri": , - "policy": { - "uri": "", - "digest": { /* DigestSet */ } - } - "inputAttestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verificationResult": "", - "verifiedLevels": [""], - "dependencyLevels": { - "": , - "": , - ... - }, - "slsaVersion": ".", -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`timeVerified` _string ([Timestamp]), required_ - -> Timestamp indicating what time the verification occurred. - - -`resourceUri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. - - -`policy` _object ([ResourceDescriptor]), required_ - -> Describes the policy that the `subject` was verified against. -> -> The entry MUST contain a `uri`. - - -`inputAttestations` _array ([ResourceDescriptor]), optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `resolvedDependencies` field in [SLSA Provenance]. -> -> This field MAY be absent if the verifier does not support this feature. -> If non-empty, this field MUST contain information on _all_ the attestations -> used to perform verification. -> -> Each entry MUST contain a `digest` of the attestation and SHOULD contains a -> `uri` that can be used to fetch the attestation. - - -`verificationResult` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`verifiedLevels` _array ([SlsaResult]), required_ - -> Indicates the highest level of each track verified for the artifact (and not -> its dependencies), or "FAILED" if policy verification failed. -> -> Users MUST NOT include more than one level per SLSA track. Note that each SLSA -> level implies all levels below it (e.g. SLSA_BUILD_LEVEL_3 implies -> SLSA_BUILD_LEVEL_2 and SLSA_BUILD_LEVEL_1), so there is no need to -> include more than one level per track. - - -`dependencyLevels` _object, optional_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. -> -> Users MUST count each dependency only once per SLSA track, at the highest -> level verified. For example, if a dependency meets SLSA_BUILD_LEVEL_2, -> you include it with the count for SLSA_BUILD_LEVEL_2 but not the count for ->SLSA_BUILD_LEVEL_1. - - -`slsaVersion` _string, optional_ - -> Indicates the version of the SLSA specification that the verifier used, in the -> form `.`. Example: `1.0`. If unset, the default is an -> unspecified minor version of `1.x`. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1-rc2", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier" - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "inputAttestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_LEVEL_3"], - "dependencyLevels": { - "SLSA_BUILD_LEVEL_3": 5, - "SLSA_BUILD_LEVEL_2": 7, - "SLSA_BUILD_LEVEL_1": 1, - }, - "slsaVersion": "1.0" -} -``` - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -SHOULD be one of these values: - -- SLSA_BUILD_LEVEL_0 -- SLSA_BUILD_LEVEL_1 -- SLSA_BUILD_LEVEL_2 -- SLSA_BUILD_LEVEL_3 -- FAILED (Indicates policy evaluation failed) - -Note that each SLSA level implies the levels below it. For example, -SLSA_BUILD_LEVEL_3 means (SLSA_BUILD_LEVEL_1 + SLSA_BUILD_LEVEL_2 + -SLSA_BUILD_LEVEL_3). - -Users MAY use custom values here but MUST NOT use custom values starting with -`SLSA_`. - -## Change history - -- 1: - - Replaced `materials` with `resolvedDependencies`. - - Relaxed `SlsaResult` to allow other values. - - Converted to lowerCamelCase for consistency with [SLSA Provenance]. - - Added `slsaVersion` field. -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SLSA Provenance]: /provenance -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md -[ResourceURI]: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#ResourceURI -[ResourceDescriptor]: https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md -[Timestamp]: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#Timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v1/README.md#parsing-rules diff --git a/docs/spec/v1.0-rc2/verifying-artifacts.md b/docs/spec/v1.0-rc2/verifying-artifacts.md deleted file mode 100644 index ea220665c..000000000 --- a/docs/spec/v1.0-rc2/verifying-artifacts.md +++ /dev/null @@ -1,300 +0,0 @@ ---- -title: Verifying artifacts -description: SLSA uses provenance to indicate whether an artifact is authentic or not, but provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection verification, and this page describes how to verify artifacts and their SLSA provenenance. The intended audience is system implementers, security engineers, and software consumers. ---- - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that -inspection **verification**, and this page describes recommendations for how to -verify artifacts and their SLSA provenance. - -This page is divided into several sections. The first describes the process -for verifying an artifact and its provenance against a set of expectations. The -second describes how to form the expectations used to verify provenance. The -third discusses architecture choices for where provenance verification can -happen. - -## How to verify - -Verification SHOULD include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- Verifying the signature on the provenance envelope. -- Ensuring that the values for `buildType` and `externalParameters` in the - provenance match the expected values. The package ecosystem MAY allow - an approved list of `externalParameters` to be ignored during verification. - Any unrecognized `externalParameters` SHOULD cause verification to fail. - -![Threats covered by each step](/images/v1.0-rc2/supply-chain-threats-build-verification.svg) - -Note: This section assumes that the provenance is in the recommended -[provenance format](/provenance/v1-rc2). If it is not, then the verifier SHOULD -perform equivalent checks on provenance fields that correspond to the ones -referenced here. - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "E", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This configuration - is likely in the form of a map from (builder public key identity, - `builder.id`) to (SLSA Build level) drawn from the SLSA Conformance - Program (coming soon). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the artifact in question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1-rc2`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "E"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Verifying build systems](verifying-systems). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "H".) -- [Threat "H"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. - -[Threat "E"]: threats#e-compromise-build-process -[Threat "F"]: threats#f-upload-modified-package -[Threat "G"]: threats#g-compromise-package-repo -[Threat "H"]: threats#h-use-compromised-package - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets your expectations for that -package in order to mitigate [threat "C"]. - -In our threat model, the adversary has ability to invoke a build and to publish -to the registry. The adversary is not able to write to the source repository, nor do -they have insider access to any trusted systems. Your expectations SHOULD be -sufficient to detect or prevent this adversary from injecting unofficial -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 - -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 -range of values (possibly any value) if it is known that any value in the range -is safe. JSON comparison is sufficient for verifying parameters. - -TIP: Difficulty in forming meaningful expectations about `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "C"]: threats#c-build-from-modified-source - -### Step 3: (Optional) Check dependencies recursively - -[verify-step-3]: #step-3-optional-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. Note that SLSA v1.0 does not have any requirements on the -completeness or verification of `resolvedDependencies`. However, one might wish -to verify dependencies in order to mitigate [threat "E"] and protect against -threats further up the supply chain. If `resolvedDependencies` is incomplete, -these checks can be done on a best-effort basis. - -A [Verification Summary Attestation (VSA)][VSA] can make dependency verification -more efficient by recording the result of prior verifications. A trimming -heuristic or exception mechanism is almost always necessary when verifying -dependencies because there will be transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) - -[Threat "E"]: threats#e-use-compromised-dependency -[VSA]: /verification_summary -[threats]: threats - -## Forming Expectations - -Expectations are known provenance values that indicate the -corresponding artifact is authentic. For example, a package ecosystem may -maintain a mapping between package names and their canonical source -repositories. That mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git branches or tags. - -- **Defined by producer:** The package producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the package's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -- **Defined in source:** The source repository tells the verifier what their - expectations ought to be. In this model, the package name is immutably bound - to a source repository and all other external parameters are defined in the - source repository. This is how the Go ecosystem works, for example, since - the package name *is* the source repository location. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -will likely have different artifacts and therefore different provenance. Similarly, an -artifact might have different names in different package ecosystems but use the same -provenance file. - -## Architecture options - -System implementers decide which part(s) of the system will verify provenance: -the package ecosystem at upload time, the consumers at download time, or via a -continuous monitoring system. Each option comes with its own set of -considerations, but all are valid. The options are not mutually exclusive, but -at least one part of a SLSA-conformant system SHOULD verify provenance. - -More than one component can verify provenance. For example, even if a package -ecosystem verifies provenance, consumers who get artifacts from that package -ecosystem might wish to verify provenance themselves for defense in depth. They -can do so using either client-side verification tooling or by polling a -monitor. - - - -### Package ecosystem - -[Package ecosystem]: #package-ecosystem - -A package ecosystem is a set of rules and conventions governing -how packages are distributed. Every package artifact has an ecosystem, whether it is -formal or ad-hoc. Some ecosystems are formal, such as language distribution -(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". For more background, see -[Package Model](terminology.md#package-model). - -During package upload, a package ecosystem can ensure that the artifact's -provenance matches the expected values for that package name's provenance before -accepting it into the package registry. If possible, system implementers SHOULD -prefer this option because doing so benefits all of the package ecosystem's -clients. - -The package ecosystem is responsible for making its expectations available to -consumers, reliably redistributing artifacts and provenance, and providing tools -to enable safe artifact consumption (e.g. whether an artifact meets -expectations). - -### Consumer - -[Consumer]: #consumer - -A package artifact's consumer is the organization or individual that uses the -package artifact. - -Consumers can form their own expectations for artifacts or use the default -expectations provided by the package producer and/or package ecosystem. -When forming their own expectations, the consumer uses client-side verification tooling to ensure -that the artifact's provenance matches their expectations for that package -before use (e.g. during installation or deployment). Client-side verification -tooling can be either standalone, such as -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into -the package ecosystem client. - -### Monitor - -[Monitor]: #monitor - -A monitor is a service that verifies provenance for a set -of packages and publishes the result of that verification. The set of -packages verified by a monitor is arbitrary, though it MAY mimic the set -of packages published through one or more package ecosystems. The monitor -SHOULD publish its expectations for all the packages it verifies. - -Consumers can continuously poll a monitor to detect artifacts that -do not meet the monitor's expectations. Detecting artifacts that fail -verification is of limited benefit unless a human or another part of the system -responds to the failed verification. diff --git a/docs/spec/v1.0-rc2/verifying-systems.md b/docs/spec/v1.0-rc2/verifying-systems.md deleted file mode 100644 index 7c77a60fa..000000000 --- a/docs/spec/v1.0-rc2/verifying-systems.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: Verifying build systems -description: Guidelines for assessing build system security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust systems, verify -artifacts". However, consumers cannot trust systems to produce Build L3 -artifacts and provenance unless they have some proof that the provenance is -[unforgeable](requirements.md#provenance-unforgeable) and the builds are -[isolated](requirements.md#isolated). - -This page describes the parts of a build system that consumers SHOULD assess -and provides sample questions consumers can ask when assessing a build system. -See also [Threats & mitigations](threats.md) and the -[build model](terminology.md#build-model). - -## Threats - -### Adversary goal - -The SLSA Build track defends against an adversary whose primary goal is to -inject unofficial behavior into a package artifact while avoiding detection. -Remember that [verifiers](verifying-artifacts.md) only accept artifacts whose -provenance matches expectations. To bypass this, the adversary tries to either -(a) tamper with a legitimate build whose provenance already matches -expectations, or (b) tamper with an illegitimate build's provenance to make it -match expectations. - -More formally, if a build with external parameters P would produce an artifact -with binary hash X and a build with external parameters P' would produce an -artifact with binary hash Y, they wish to produce provenance indicating a build -with external parameters P produced an artifact with binary hash Y. - -See threats [C], [D], [E], and [F] for examples of specific threats. - -Note: Platform abuse (e.g. running non-build workloads) and attacks against -builder availability are out of scope of this document. - -### Adversary profiles - -Consumers SHOULD also evaluate the build system's ability to defend against the -following types of adversaries. - -1. Project contributors, who can: - - Create builds on the build service. These are the adversary's controlled - builds. - - Modify one or more controlled builds' external parameters. - - Modify one or more controlled builds' environments and run arbitrary - code inside those environments. - - Read the target build's source repo. - - Fork the target build's source repo. - - Modify a fork of the target build's source repo and build from it. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Create new builds under the target build's project or identity. - - Modify the target build's source repo and build from it. - - Modify the target build's configuration. -3. Build service administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Run arbitrary code on the build service. - - Read and modify network traffic. - - Access the control plane's cryptographic secrets. - - Remotely access build environments (e.g. via SSH). - -[C]: threats.md#c-build-from-modified-source -[D]: threats.md#d-use-compromised-dependency -[E]: threats.md#e-compromise-build-process -[F]: threats.md#f-upload-modified-package - -## Build system components - -Consumers SHOULD consider at least these five elements of the -[build model](terminology.md#build-model) when assessing build systems for SLSA -conformance: external parameters, control plane, build environments, caches, -and outputs. - -![image](build-model.svg) - -The following sections detail these elements of the build model and give prompts -for assessing a build system's ability to produce SLSA Build L3 provenance. - -### External parameters - -External parameters are the external interface to the builder and include all -inputs to the build process. Examples include the source to be built, the build -definition/script to be executed, user-provided instructions to the -control plane for how to create the build environment (e.g. which operating -system to use), and any additional user-provided strings. - -#### Prompts for assessing external parameters - -- How does the control plane process user-provided external parameters? - Examples: sanitizing, parsing, not at all -- Which external parameters are processed by the control plane and which are - processed by the build environment? -- What sort of external parameters does the control plane accept for - build environment configuration? -- How do you ensure that all external parameters are represented in the - provenance? -- How will you ensure that future design changes will not add additional - external parameters without representing them in the provenance? - -### Control plane - -The control plane is the build system component that orchestrates each -independent build execution. It is responsible for setting up each build and -cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs -provenance for each build performed on the build service. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -#### Prompts for assessing the control plane - -- Administration - - What are the ways an employee can use privileged access to influence a - build or provenance generation? Examples: physical access, terminal - access, access to cryptographic secrets - - What controls are in place to detect or prevent the employee from - abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many employees have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and system - outages? Are they tested? How frequently? - -- Provenance generation - - How does the control plane observe the build to ensure the provenance's - accuracy? - - Are there situations in which the control plane will not generate - provenance for a completed build? What are they? - -- Development practices - - How do you track the control plane's software and configuration? - Example: version control - - How do you build confidence in the control plane's software supply - chain? Example: SLSA L3+ provenance, build from source - - How do you secure communications between builder components? Example: - TLS with certificate transparency. - - Are you able to perform forensic analysis on compromised build - environments? How? Example: retain base images indefinitely - -- Creating build environments - - How does the control plane share data with build environments? Example: - mounting a shared file system partition - - How does the control plane protect its integrity from build - environments? Example: not mount its own file system partitions on - build environments - - How does the control plane prevent build environments from accessing its - cryptographic secrets? Examples: dedicated secret storage, not mounting - its own file system partitions to build environments, hardware security - modules - -- Managing cryptographic secrets - - How do you store the control plane's cryptographic secrets? - - Which parts of the organization have access to the control plane's - cryptographic secrets? - - What controls are in place to detect or prevent employees abusing such - access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Build environment - -The build environment is the independent execution context where the build -takes place. In the case of a distributed build, the build environment is the -collection of all execution contexts that run build steps. Each build -environment must be isolated from the control plane and from all other build -environments, including those running builds from the same tenant or project. -Tenants are free to modify the build environment arbitrarily. Build -environments must have a means to fetch input artifacts (source, dependencies, -etc). - -#### Prompts for assessing build environments - -- Isolation technologies - - How are build environments isolated from the control plane and each - other? Examples: VMs, containers, sandboxed processes - - How have you hardened your build environments against malicious tenants? - Examples: configuration hardening, limiting attack surface - - How frequently do you update your isolation software? - - What is your process for responding to vulnerability disclosures? What - about vulnerabilities in your dependencies? - - What prevents a malicious build from gaining persistence and influencing - subsequent builds? - -- Creation and destruction - - What operating system and utilities are available in build environments - on creation? How were these elements chosen? Examples: A minimal Linux - distribution with its package manager, OSX with HomeBrew - - How long could a compromised build environment remain active in the - build system? - -- Network access - - Are build environments able to call out to remote execution? If so, how - do you prevent them from tampering with the control plane or other build - environments over the network? - - Are build environments able to open services on the network? If so, how - do you prevent remote interference through these services? - -### Cache - -Builders may have zero or more caches to store frequently used dependencies. -Build environments may have either read-only or read-write access to caches. - -#### Prompts for assessing caches - -- What sorts of caches are available to build environments? -- How are those caches populated? -- How are cache contents validated before use? - -### Output storage - -Output Storage holds built artifacts and their provenance. Storage may either be -shared between build projects or allocated separately per-project. - -#### Prompts for assessing output storage - -- How do you prevent builds from reading or overwriting files that belong to - another build? Example: authorization on storage -- What processing, if any, does the control plane do on output artifacts? - -## Builder evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet. Evidence submitted for third-party certification need not be -published. diff --git a/docs/spec/v1.0-rc2/whats-new.md b/docs/spec/v1.0-rc2/whats-new.md deleted file mode 100644 index cf33ebe35..000000000 --- a/docs/spec/v1.0-rc2/whats-new.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: What's new in SLSA v1.0 -description: SLSA v1.0 represents changes made in response to feedback from the SLSA community and early adopters of SLSA v0.1. Overall, these changes prioritize simplicity and practicality. ---- - -SLSA v1.0 represents changes made in response to feedback from the SLSA -community and early adopters of SLSA v0.1. Overall, these changes -prioritize simplicity and practicality. - -Check back here for a detailed v1.0 changelog with the official 1.0 release! - -Until then, see the following for more information about what's new: - -- [Release candidate blog post](/blog/2023/02/slsa-v1-rc): describes the - addition of SLSA tracks, verification expectations, and changes to SLSA's - model, specification, and format - -- [Provenance changelog](/provenance/v1-rc2#change-history): a detailed - summary of changes to the provenance format diff --git a/docs/spec/v1.0/about.md b/docs/spec/v1.0/about.md deleted file mode 100644 index 0ad229800..000000000 --- a/docs/spec/v1.0/about.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: About SLSA -description: With supply chain attacks on the rise, a shared vocabulary and universal framework is needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software. ---- - -This page is an introduction to SLSA and its concepts. If you're new -to SLSA, start here! - -## What is SLSA? - -SLSA is a set of incrementally adoptable guidelines for supply chain security, -established by industry consensus. The specification set by SLSA is useful for -both software producers and consumers: producers can follow SLSA's guidelines to -make their software supply chain more secure, and consumers can use SLSA to make -decisions about whether to trust a software package. - -SLSA offers: - -- A common vocabulary to talk about software supply chain security -- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume -- An actionable checklist to improve your own software's security -- A way to measure your efforts toward compliance with forthcoming - Executive Order standards in the [Secure Software Development Framework (SSDF)](https://csrc.nist.gov/Projects/ssdf) - -## Why SLSA is needed - -High profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply -chain integrity weaknesses that may go unnoticed, yet quickly become very -public, disruptive, and costly in today's environment when exploited. They've -also shown that there are inherent risks not just in code itself, but at -multiple points in the complex process of getting that code into software -systems—that is, in the **software supply chain**. Since these attacks are on -the rise and show no sign of decreasing, a universal framework for hardening the -software supply chain is needed, as affirmed by the -[U.S. Executive Order on Improving the Nation's Cybersecurity](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/). - -Security techniques for vulnerability detection and analysis of source code are -essential, but are not enough on their own. Even after fuzzing or vulnerability -scanning is completed, changes to code can happen, whether unintentionally or -from insider threats or compromised accounts. Risk for code modification exists at -each link in a typical software supply chain, from source to build through -packaging and distribution. Any weaknesses in the supply chain undermine -confidence in whether the code that you run is actually the code that you -scanned. - -SLSA is designed to support automation that tracks code handling from source -to binary, protecting against tampering regardless of the complexity -of the software supply chain. As a result, SLSA increases trust that the -analysis and review performed on source code can be assumed to still apply to -the binary consumed after the build and distribution process. - -## SLSA in layperson's terms - -There has been a [lot of discussion](https://ntia.gov/page/software-bill-materials) about the need for "ingredient labels" for -software—a "software bill of materials" (SBOM) that tells users what is in their -software. Building off this analogy, SLSA can be thought of as all the food -safety handling guidelines that make an ingredient list credible. From standards -for clean factory environments so contaminants aren't introduced in packaging -plants, to the requirement for tamper-proof seals on lids that ensure nobody -changes the contents of items sitting on grocery store shelves, the entire food -safety framework ensures that consumers can trust that the ingredient list -matches what's actually in the package they buy. - -Likewise, the SLSA framework provides this trust with guidelines and -tamper-resistant evidence for securing each step of the software production -process. That means you know not only that nothing unexpected was added to the -software product, but also that the ingredient label itself wasn't tampered with -and accurately reflects the software contents. In this way, SLSA helps protect -against the risk of: - -- Code modification (by adding a tamper-evident "seal" to code after - source control) -- Uploaded artifacts that were not built by the expected CI/CD platform (by marking - artifacts with a factory "stamp" that shows which build platform created it) -- Threats against the build platform (by providing "manufacturing facility" - best practices for build platform services) - -For more exploration of this analogy, see the blog post -[SLSA + SBOM: Accelerating SBOM success with the help of SLSA](/blog/2022/05/slsa-sbom). - -## Who is SLSA for? - -In short: everyone involved in producing and consuming software, or providing -infrastructure for software. - -**Software producers**, such as an open source project, a software vendor, or a -team writing first-party code for use within the same company. SLSA gives you -protection against tampering along the supply chain to your consumers, both -reducing insider risk and increasing confidence that the software you produce -reaches your consumers as you intended. - -**Software consumers**, such as a development team using open source packages, a -government agency using vendored software, or a CISO judging organizational -risk. SLSA gives you a way to judge the security practices of the software you -rely on and be sure that what you receive is what you expected. - -**Infrastructure providers**, who provide infrastructure such as an ecosystem -package manager, build platform, or CI/CD platform. As the bridge between the -producers and consumers, your adoption of SLSA enables a secure software supply -chain between them. - -## How SLSA works - -We talk about SLSA in terms of [tracks and levels](levels.md). -A SLSA track focuses on a particular aspect of a supply chain, such as the Build -Track. SLSA v1.0 consists of only a single track ([Build](levels.md#build-track)), but future versions of -SLSA will add tracks that cover other parts of the software supply chain, such -as how source code is managed. - -Within each track, ascending levels indicate increasingly hardened security -practices. Higher levels provide better guarantees against supply chain threats, -but come at higher implementation costs. Lower SLSA levels are designed to be -easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes -used to refer to software that doesn't yet meet any SLSA level. Currently, the -SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels -to be possible in [future revisions](future-directions.md). - -The combination of tracks and levels offers an easy way to discuss whether -software meets a specific set of requirements. By referring to an artifact as -meeting SLSA Build Level 3, for example, you're indicating in one phrase that -the software artifact was built following a set of security practices that -industry leaders agree protect against particular supply chain compromises. - -## What SLSA doesn't cover - -SLSA is only one part of a thorough approach to supply chain security. There -are several areas outside SLSA's current framework that are nevertheless -important to consider together with SLSA such as: - -- Code quality: SLSA does not tell you whether the developers writing the - source code followed secure coding practices. -- Producer trust: SLSA does not address organizations that intentionally - produce malicious software, but it can reduce insider risks within an - organization you trust. SLSA's Build Track protects against tampering during - or after the build, and [future SLSA tracks](future-directions.md) intend to - protect against unauthorized modifications of source code and dependencies. -- Transitive trust for dependencies: the SLSA level of an artifact is - independent of the level of its dependencies. You can use SLSA recursively to - also judge an artifact's dependencies on their own, but there is - currently no single SLSA level that applies to both an artifact and its - transitive dependencies together. For a more detailed explanation of why, - see the [FAQ](faq#q-why-is-slsa-not-transitive). diff --git a/docs/spec/v1.0/attestation-model.md b/docs/spec/v1.0/attestation-model.md deleted file mode 100644 index 7cb104f8c..000000000 --- a/docs/spec/v1.0/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.0/distributing-provenance.md b/docs/spec/v1.0/distributing-provenance.md deleted file mode 100644 index 11f01f4a2..000000000 --- a/docs/spec/v1.0/distributing-provenance.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Distributing provenance -description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is platform implementers and software distributors. ---- - -In order to make provenance for artifacts available after generation -for verification, SLSA requires the distribution and verification of provenance -metadata in the form of SLSA attestations. - -This document provides specifications for distributing provenance, and the -relationship between build artifacts and provenance (build attestations). It is -primarily concerned with artifacts for ecosystems that distribute build -artifacts, but some attention is also paid to ecosystems that distribute -container images or only distribute source artifacts, as many of the same -principles generally apply to any artifact or group of artifacts. - -In addition, this document is primarily for the benefit of artifact -distributors, to understand how they can adopt the distribution of SLSA -provenance. It is primarily concerned with the means of distributing -attestations and the relationship of attestations to build artifacts, and not -with the specific format of the attestation itself. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Background - -The [package ecosystem]'s maintainers are responsible for reliably -redistributing artifacts and provenance, making the producers' expectations -available to consumers, and providing tools to enable safe artifact consumption -(e.g. whether an artifact meets its producer's expectations). - -## Relationship between releases and attestations - -Attestations SHOULD be bound to artifacts, not releases. - -A single "release" of a project, package, or library might include multiple -artifacts. These artifacts result from builds on different platforms, -architectures or environments. The builds need not happen at roughly the same -point in time and might even span multiple days. - -It is often difficult or impossible to determine when a release is 'finished' -because many ecosystems allow adding new artifacts to old releases when adding -support for new platforms or architectures. Therefore, the set of attestations -for a given release MAY grow over time as additional builds and attestations -are created. - -Thus, package ecosystems SHOULD support multiple individual attestations per -release. At the time of a given build, the relevant provenance for that build -can be added to the release, depending on the relationship to the given -artifacts. - -## Relationship between artifacts and attestations - -Package ecosystems SHOULD support a one-to-many relationship from build -artifacts to attestations to ensure that anyone is free to produce and publish -any attestation they might need. However, while there are lots of possible -attestations that can have a relationship to a given artifact, in this context -SLSA is primarily concerned with build attestations, i.e. provenance, and as -such, this specification only considers build attestations, produced by the -same maintainers as the artifacts themselves. - -By providing provenance alongside an artifact in the manner specified by a -given ecosystem, maintainers are considered to be 'elevating' these build -attestations above all other possible attestations that could be provided by -third parties for a given artifact. The ultimate goal is for maintainers to -provide the provenance necessary for a repository to be able to verify some -potential policy that requires a certain SLSA level for publication, not -support the publication of arbitrary attestations by third parties. - -As a result, this provenance SHOULD accompany the artifact at publish time, and -package ecosystems SHOULD provide a way to map a given artifact to its -corresponding attestations. The mappings can be either implicit (e.g. require a -custom filename schema that uniquely identifies the provenance over other -attestation types) or explicit (e.g. it could happen as a de-facto standard -based on where the attestation is published). - -The provenance SHOULD have a filename that is directly related to the build -artifact filename. For example, for an artifact `.`, the -attestation is `.attestation` or some similar extension (for example -[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`.) - -## Where attestations are published - -There are a number of opportunities and venues to publish attestations during -and after the build process. Producers MUST publish attestations in at least -one place, and SHOULD publish attestations in more than one place: - -- **Publish attestations alongside the source repository releases**: If the - source repository hosting provider offers an artifact "release" feature, - such as [GitHub - releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), - producers SHOULD include provenance as part of such releases. This option - has the benefit of requiring no changes to the package registry to support - provenance formats, but has the disadvantage of putting the source - repository hosting providing in the critical path for installers that want to - verify policy at build-time. -- **Publish attestations alongside the artifact in the package registry**: - Many software repositories already support some variety of publishing 1:1 - related files alongside an artifact, sometimes known as “sidecar files”. - For example, PyPI supports publishing `.asc` files representing the PGP - signature for an artifact with the same filename (but different extension). - This option requires the mapping between artifact and attestation (or - attestation vessel) to be 1:1. -- **Publish attestations elsewhere, record their existence in a transparency - log**: Once an attestation has been generated and published for a build, a - hash of the attestation and a pointer to where it is indexed SHOULD be - published to a third-party transparency log that exists outside the source - repository and package registry. Not only are transparency logs such as - [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed - to be immutable, but they typically also make monitoring easier. - Requiring the presence of the attestation in a monitored transparency log - during verification helps ensure the attestation is trustworthy. - -Combining these options gives us a process for bootstrapping SLSA adoption -within an ecosystem, even if the package registry doesn't support publishing -attestations. First, interested projects modify their release process to -produce SLSA provenance. Then, they publish that provenance to their source -repository. Finally, they publish the provenance to the package registry, if -and when the registry supports it. - -Long-term, package registries SHOULD support uploading and distributing -provenance alongside the artifact. This model is preferred for two reasons: - -- trust: clients already trust the package registry as the source of their - artifacts, and don't need to trust an additional service; -- reliability: clients already depend on the package registry as part of - their critical path, so distributing provenance via the registry avoids - adding an additional point of failure. - -Short term, consumers of build artifacts can bootstrap a manual policy by using -the source repository only for projects that publish all artifacts and -attestations to the source repository, and later extend this to all artifacts -published to the package registry via the canonical installation tools once -a given ecosystem supports them. - -## Immutability of attestations - -Attestations SHOULD be immutable. Once an attestation is published as it -corresponds to a given artifact, that attestation is immutable and cannot be -overwritten later with a different attestation that refers to the same -artifact. Instead, a new release (and new artifacts) SHOULD be created. - -## Format of the attestation - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto [SLSA Provenance](/provenance), but -another format MAY be used if both producer and consumer agree and it meets all -the other requirements. - -## Considerations for source-based ecosystems - -Some ecosystems have support for installing directly from source repositories -(an option for Python/`pip`, Go, etc). In these cases, there is no need to -publish or verify provenance because there is no "build" step that translates -between a source repository and an artifact that is being installed. - -However, for ecosystems that install from source repositories _via_ some -intermediary (e.g. [Homebrew installing from GitHub release artifacts generated -from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go -installing through the Go module proxy](https://proxy.golang.org/)), these -ecosystems distribute "source archives" that are not the bit-for-bit identical -form from version control. These intermediaries are transforming the original -source repository in some way that constitutes a "build" and as a result SHOULD -be providing build provenance for this "package", and the recommendations -outlined here apply. - -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.0/faq.md b/docs/spec/v1.0/faq.md deleted file mode 100644 index ad0bd577c..000000000 --- a/docs/spec/v1.0/faq.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Frequently asked questions -description: Answers to questions frequently asked about SLSA. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build platforms to -corroborate the provenance of a build. In this way, one can create an overall -platform that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a platform can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. - -## Q. What is the difference between a build platform, system, and service? - -Build platform and build system have been used interchangeably in the past. With -the v1.0 specification, however, there has been a unification around the term -platform as indicated in the [Terminology](terminology.md). The use of the word -`system` still exists related to software and services within the build platform -and to systems outside of a build platform like change management systems. - -A build service is a hosted build platform that is often run on shared infrastructure -instead of individuals' machines and workstations. Its use has also been replaced outside -of the requirements as it relates to the build platform. - -## Q: Is SLSA the same as TACOS? - -No. -[Trusted Attestation and Compliance for Open Source (TACOS)](https://github.com/tacosframework) -is a framework authored by Tidelift. -Per their website, TACOS is a framework -"for assessing the development practices of open source projects -against a set of secure development standards specified by the (US) -NIST Secure Software Development Framework (SSDF) V1.1" which -"vendors can use to provide self-attestation for the open source components -they rely on." - -In contrast, SLSA is a community-developed framework---including -adoptable guidelines for securing a software supply chain and -mechanism to evaluate the trustworthiness of artifacts you consume---that -is part of the Open Source Security Foundation (OpenSSF). - -## Q: How does SLSA and SLSA Provenance relate to SBOM? - -[Software Bill of Materials (SBOM)] are a frequently recommended tool for -increased software supply chain rigor. An SBOM is typically focused on -understanding software in order to evaluate risk through known vulnerabilities -and license compliance. These use-cases require fine-grained and timely data -which can be refined to improve signal-to-noise ratio. - -[SLSA Provenance] and the [Build track] are focused on trustworthiness of the -build process. To improve trustworthiness, Provenance is generated in the build -platform's trusted control plane, which in practice results in it being coarse -grained. For example, in Provenance metadata completeness of -`resolvedDependencies` information is on a best-effort basis. Further, the -`ResourceDescriptor` type does not require version and license information or -even a URI to the dependency's original location. - -While they likely include similar data, SBOMs and SLSA Provenance operate at -different levels of abstraction. The fine-grained data in an SBOM typically -describes the components present in a produced artifact, whereas SLSA -Provenance more coarsely describes parameters of a build which are external to -the build platform. - -The granularity and expressiveness of the two use-cases differs enough that -current SBOM formats were deemed not a good fit for the requirements of -the Build track. Yet SBOMs are a good practice and may form part of a future -SLSA Vulnerabilities track. Further, SLSA Provenance can increase the -trustworthiness of an SBOM by describing how the SBOM was created. - -SLSA Provenance, the wider [in-toto Attestation Framework] in which the -recommended format sits, and the various SBOM standards, are all rapidly -evolving spaces. There is ongoing investigation into linking between the -different formats and exploration of alignment on common models. This FAQ entry -describes our understanding of the intersection efforts today. We do not know -how things will evolve over the coming months and years, but we look forward to -the collaboration and improved software supply chain security. - -## Q: How to SLSA with a self-hosted runner - -Some CI systems allow producers to provide their own self-hosted runners as a build -environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage -these, classifying the SLSA build level for the resulting artifact can be confusing. - -Since the SLSA Build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance, interpretation of the -specification hinges on the platform entities involved in the provenance generation. -The SLSA [build level requirements] (secure key storage, isolation, etc.) should be -imposed on the transitive closure of the systems which are responsible for informing -the provenance generated. - -Some common situations may include: - -- The platform generates the provenance and just calls a runner for individual build steps. - In this situation, the provenance is only affected by the platform so there would be - no requirements imposed on the runner. -- The runner generates the provenance. In this situation, the orchestrating platform - is irrelevant and all requirements are imposed on the runner. -- The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance. Trust is - shared between the platform and the runner so the requirements are imposed on both. - -Additional requirements on the self-hosted runners may be added to Build levels -greater than L3 when such levels get defined. - -[build level requirements]: requirements.md -[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners -[Software Bill of Materials (SBOM)]: https://ntia.gov/sbom -[SLSA Provenance]: provenance.md -[Build track]: levels.md#build-track -[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/ diff --git a/docs/spec/v1.0/future-directions.md b/docs/spec/v1.0/future-directions.md deleted file mode 100644 index 699bf39df..000000000 --- a/docs/spec/v1.0/future-directions.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Future directions -description: The initial draft version (v0.1) of SLSA had a larger scope including protections against tampering with source code and a higher level of build integrity (Build L4). This page collects some early thoughts on how SLSA **might** evolve in future versions to re-introduce these notions and add other additional aspects of automatable supply chain security. ---- - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future versions to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build platform and enabling -corraboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream verifiers - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other build platforms to corroborate the - provenance. - -
- -
- -## Source track - -A Source track could provide protection against tampering of the source code -prior to the build. - -The initial [draft version (v0.1)](../v0.1/requirements.md#source-requirements) -of SLSA included the following source requirements, which **may or may not** -form the basis for a future Source track: - -- Strong authentication of author and reviewer identities, such as 2-factor - authentication using a hardware security key, to resist account and - credential compromise. -- Retention of the source code to allow for after-the-fact inspection and - future rebuilds. -- Mandatory two-person review of all changes to the source to prevent a single - compromised actor or account from introducing malicious changes. - -
- -
- -## Build Platform Operations track - -A Build Platform Operations track could provide assurances around the hardening -of build platforms as they are operated. - -The initial [draft version (v0.1)] of SLSA included a section on -[common requirements](../v0.1/requirements.md#common-requirements) that formed -the foundation of the guidance for -[verifying build systems](verifying-systems.md), which **may or may not** form -the basis for a future Build Platform Operations track: - -- Controls for approval, logging, and auditing of all physical and remote - access to platform infrastructure, cryptographic secrets, and privileged - debugging interfaces. -- Conformance to security best practices to minimize the risk of compromise. -- Protection of cryptographic secrets used by the build platform. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md diff --git a/docs/spec/v1.0/images/build-model.svg b/docs/spec/v1.0/images/build-model.svg deleted file mode 100644 index 9d6bed6ca..000000000 --- a/docs/spec/v1.0/images/build-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.0/images/provenance-model.svg b/docs/spec/v1.0/images/provenance-model.svg deleted file mode 100644 index 028dad49e..000000000 --- a/docs/spec/v1.0/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.0/images/supply-chain-model.svg b/docs/spec/v1.0/images/supply-chain-model.svg deleted file mode 100644 index d3efece68..000000000 --- a/docs/spec/v1.0/images/supply-chain-model.svg +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.0/images/supply-chain-threats-build-verification.svg b/docs/spec/v1.0/images/supply-chain-threats-build-verification.svg deleted file mode 100644 index 494f14519..000000000 --- a/docs/spec/v1.0/images/supply-chain-threats-build-verification.svg +++ /dev/null @@ -1,84 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.0/images/supply-chain-threats.svg b/docs/spec/v1.0/images/supply-chain-threats.svg deleted file mode 100644 index 8fc08b6b9..000000000 --- a/docs/spec/v1.0/images/supply-chain-threats.svg +++ /dev/null @@ -1,77 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.0/images/verification-model.svg b/docs/spec/v1.0/images/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.0/images/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.0/index.md b/docs/spec/v1.0/index.md deleted file mode 100644 index 39267bf2a..000000000 --- a/docs/spec/v1.0/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: SLSA specification -description: SLSA is a specification for describing and incrementally improving supply chain security, established by industry consensus. It is organized into a series of levels that describe increasing security guarantees. This is **version 1.0** of the SLSA specification, which defines the SLSA levels. ---- - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **version 1.0** of the SLSA specification, which defines the SLSA -levels and recommended attestation formats, including provenance. - -{%- for section in site.data.nav.main %} -{%- if section.url == page.url %} -{%- for subsection in section.children %} -{%- if subsection.children %} - -## {{ subsection.title }} - -{{ subsection.description }} - - - -| Page | Description -| ---- | ----------- -{%- for child in subsection.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} -{%- endfor %} - - -{%- endif %} -{%- endfor %} -{%- endif %} -{%- endfor %} diff --git a/docs/spec/v1.0/levels.md b/docs/spec/v1.0/levels.md deleted file mode 100644 index fdab66610..000000000 --- a/docs/spec/v1.0/levels.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: Security levels -description: SLSA is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This page is a descriptive overview of the SLSA levels and tracks, describing their intent. ---- - -SLSA is organized into a series of levels that provide increasing supply chain -security guarantees. This gives you confidence that software hasn’t been -tampered with and can be securely traced back to its source. - -This page is a descriptive overview of the SLSA levels and tracks, describing -their intent. For the prescriptive requirements for each level, see -[Requirements](requirements.md). For a general overview of SLSA, see -[About SLSA](principles.md). - -## Levels and tracks - -SLSA levels are split into *tracks*. Each track has its own set of levels that -measure a particular aspect of supply chain security. The purpose of tracks is -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 - - - -> 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 -> Build track. A Source track may be added in [future versions]. - -## Build track - -The SLSA build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance. Provenance describes -what entity built the artifact, what process they used, and what the inputs -were. The lowest level only requires the provenance to exist, while higher -levels provide increasing protection against tampering of the build, the -provenance, or the artifact. - -The primary purpose of the build track is to enable [verification] that the -artifact was built as expected. Consumers have some way of knowing what the -expected provenance should look like for a given package and then compare each -package artifact's actual provenance to those expectations. Doing so prevents -several classes of [supply chain threats](threats.md). - -Each ecosystem (for open source) or organization (for closed source) defines -exactly how this is implemented, including: means of defining expectations, what -provenance format is accepted, whether reproducible builds are used, how -provenance is distributed, when verification happens, and what happens on -failure. Guidelines for implementers can be found in the -[requirements](requirements.md). - -
- -### Build L0: No guarantees - -
-
Summary
- -No requirements---L0 represents the lack of SLSA. - -
Intended for
- -Development or test builds of software that are built and run on the same -machine, such as unit tests. - -
Requirements
- -n/a - -
Benefits
- -n/a - -
-
-
- -### Build L1: Provenance exists - -
-
Summary
- -Package has provenance showing how it was built. Can be used to prevent mistakes -but is trivial to bypass or forge. - -
Intended for
- -Projects and organizations wanting to easily and quickly gain some benefits of -SLSA---other than tamper protection---without changing their build workflows. - -
Requirements
- -- Software producer follows a consistent build process so that others can form - expectations about what a "correct" build looks like. - -- [Provenance] exists describing how the artifact was built, including the - build platform, build process, and top-level inputs. - -- Software producer distributes provenance to consumers, preferably using a - convention determined by the package ecosystem. - -
Benefits
- -- Makes it easier for both producers and consumers to debug, patch, rebuild, - and/or analyze the software by knowing its precise source version and build - process. - -- With [verification], prevents mistakes during the release process, such as - building from a commit that is not present in the upstream repo. - -- Aids organizations in creating an inventory of software and build platforms - used across a variety of teams. - -
Notes
- -- Provenance may be incomplete and/or unsigned at L1. Higher levels require - more complete and trustworthy provenance. - -
- -
-
- -### Build L2: Hosted build platform - -
-
Summary
- -Forging the provenance or evading verification requires an explicit "attack", -though this may be easy to perform. Deters unsophisticated adversaries or those -who face legal or financial risk. - -In practice, this means that builds run on a hosted platform that generates and -signs[^sign] the provenance. - -
Intended for
- -Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build platform, while waiting for changes to the build -platform itself required by [Build L3]. - -
Requirements
- -All of [Build L1], plus: - -- Build platform runs on dedicated infrastructure, not an individual's - workstation, and the provenance is tied to that infrastructure through - a digital signature[^sign]. - -- Downstream verification of provenance includes validating the authenticity - of the provenance. - -
Benefits
- -All of [Build L1], plus: - -- Prevents tampering after the build through digital signatures[^sign]. - -- Deters adversaries who face legal or financial risk by evading security - controls, such as employees who face risk of getting fired. - -- Reduces attack surface by limiting builds to specific build platforms that - can be audited and hardened. - -- Allows large-scale migration of teams to supported build platforms early - while further hardening work ([Build L3]) is done in parallel. - -
-
-
- -[^sign]: Usually this means that the provenance is signed by a key that is only - accessible to the build platform, but alternate means of verifying the - authenticity of the provenance are also acceptable. - -### Build L3: Hardened builds - -
-
Summary
- -Forging the provenance or evading verification requires exploiting a -vulnerability that is beyond the capabilities of most adversaries. - -In practice, this means that builds run on a hardened build platform that offers -strong tamper protection. - -
Intended for
- -Most software releases. Build L3 usually requires significant changes to -existing build platforms. - -
Requirements
- -All of [Build L2], plus: - -- Build platform implements strong controls to: - - - prevent runs from influencing one another, even within the same project. - - prevent secret material used to sign the provenance from being - accessible to the user-defined build steps. - -
Benefits
- -All of [Build L2], plus: - -- Prevents tampering during the build---by insider threats, compromised - credentials, or other tenants. - -- Greatly reduces the impact of compromised package upload credentials by - requiring attacker to perform a difficult exploit of the build process. - -- Provides strong confidence that the package was built from the official - source and build process. - -
-
- - - -[build l0]: #build-l0 -[build l1]: #build-l1 -[build l2]: #build-l2 -[build l3]: #build-l3 -[future versions]: future-directions.md -[previous version]: ../v0.1/levels.md -[provenance]: terminology.md -[verification]: verifying-artifacts.md diff --git a/docs/spec/v1.0/onepage.md b/docs/spec/v1.0/onepage.md deleted file mode 100644 index 997cc5bc6..000000000 --- a/docs/spec/v1.0/onepage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SLSA Specification -description: A one-page rendering of all that is included in SLSA v1.0. -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.0/" %} -{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,terminology,levels,requirements,distributing-provenance,verifying-artifacts,verifying-systems,threats,attestation-model,provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.0/principles.md b/docs/spec/v1.0/principles.md deleted file mode 100644 index 359dac788..000000000 --- a/docs/spec/v1.0/principles.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Guiding principles -description: An introduction to the guiding principles behind SLSA's design decisions. ---- - -This page is an introduction to the guiding principles behind SLSA's design -decisions. - -## Trust platforms, verify artifacts - -Establish trust in a small number of platforms and systems---such as change management, build, -and packaging platforms---and then automatically verify the many artifacts -produced by those platforms. - -**Reasoning**: Trusted computing bases are unavoidable---there's no choice but -to trust some platforms. Hardening and verifying platforms is difficult and -expensive manual work, and each trusted platform expands the attack surface of the -supply chain. Verifying that an artifact is produced by a trusted platform, -though, is easy to automate. - -To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited -numbers of platforms and then automate verification of the artifacts produced by those platforms. -The attack surface and work to establish trust does not scale with the number of artifacts produced, -as happens when artifacts each use a different trusted platform. - -**Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant -amount of central work. - -### Example - -A security engineer analyzes the architecture and implementation of a build -platform to ensure that it meets the SLSA Build Track requirements. Following the -analysis, the public keys used by the build platform to sign provenance are -"trusted" up to the given SLSA level. Downstream platforms verify the provenance -signed by the public key to automatically determine that an artifact meets the -SLSA level. - -### Corollary: Minimize the number of trusted platforms - -A corollary to this principle is to minimize the size of the trusted computing -base. Every platform we trust adds attack surface and increases the need for -manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team within an organization maintaining their own build platform, use a - shared build platform. Hardening work can be shared across all teams. -- Remove the need to trust components. For example, use end-to-end signing - to avoid the need to trust intermediate distribution platforms. - -## Trust code, not individuals - -Securely trace all software back to source code rather than trust individuals who have write access to package registries. - -**Reasoning**: Code is static and analyzable. People, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. - -**Benefits**: Removes the possibility for a trusted individual---or an -attacker abusing compromised credentials---to tamper with source code -after it has been committed. - -## Prefer attestations over inferences - -Require explicit attestations about an artifact's provenance; do not infer -security properties from a platform's configurations. - -**Reasoning**: Theoretically, access control can be configured so that the only path from -source to release is through the official channels: the CI/CD platform pulls only -from the proper source, package registry allows access only to the CI/CD platform, -and so on. We might infer that we can trust artifacts produced by these platforms -based on the platform's configuration. - -In practice, though, these configurations are almost impossible to get right and -keep right. There are often over-provisioning, confused deputy problems, or -mistakes. Even if a platform is configured properly at one moment, it might not -stay that way, and humans almost always end up getting in the access control -lists. - -Access control is still important, but SLSA goes further to provide defense in depth: it **requires proof in -the form of attestations that the package was built correctly**. - -**Benefits**: The attestation removes intermediate platforms from the trust base and ensures that -individuals who are accidentally granted access do not have sufficient permission to tamper with the package. diff --git a/docs/spec/v1.0/provenance.md b/docs/spec/v1.0/provenance.md deleted file mode 100644 index 1e7fe5238..000000000 --- a/docs/spec/v1.0/provenance.md +++ /dev/null @@ -1,586 +0,0 @@ ---- -title: Provenance -description: Description of SLSA provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](requirements#provenance-generation). - -## Model - -Provenance is an attestation that a particular build platform produced a set of -software artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant build platform. - The `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build platforms.) - - - The build platform implementer SHOULD define a security model for the build - platform in order to clearly identify the platform's boundaries, actors, - and interfaces. This model SHOULD then be used to identify the transitive - closure of the trusted build platform for the `builder.id` as well as the - trusted control plane. - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - platform ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `internalParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](requirements.md). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." - Such changes do not update the `predicateType`. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -Link: [provenance.proto](schema/provenance.proto) - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`internalParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that -that there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build platform SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
internalParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build platform is already trusted, and in many cases it is -not practical to do so. - -
resolvedDependencies -array (ResourceDescriptor) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script -fetches and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be -listed here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `internalParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `internalParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build platform. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build platform to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build platform to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the build platform that executed the invocation, which is trusted to -have correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ResourceDescriptor) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or -incident response. For example, this might reference logs generated during -the build and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted build platform. This is -[intended](/spec/v1.0/verifying-artifacts#step-1-check-slsa-build-level) -to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -The `builder.id` URI SHOULD resolve to documentation explaining: - -- The scope of what this ID represents. -- The claimed SLSA Build level. -- The accuracy and completeness guarantees of the fields in the provenance. -- Any fields that are generated by the tenant-controlled build process and not - verified by the trusted control plane, except for the `subject`. -- The interpretation of any extension fields. - -
builderDependencies -array (ResourceDescriptor) - -Dependencies used by the orchestrator that are not run within the workload -and that do not affect the build, but might affect the provenance generation -or security guarantees. - -
version -map (string→string) - -Map of names of components of the build platform to their version. - -
- -The build platform, or builder for short, represents the transitive -closure of all the entities that are, by necessity, [trusted] to faithfully run -the build and record the provenance. This includes not only the software but the -hardware and people involved in running the service. For example, a particular -instance of [Tekton](https://tekton.dev/) could be a build platform, while -Tekton itself is not. For more info, see [Build -model](/spec/v1.0/terminology#build-model). - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -### Extension fields - -[Extension fields]: #extension-fields - -Implementations MAY add extension fields to any JSON object to describe -information that is not captured in a standard field. Guidelines: - -- Extension fields SHOULD use names of the form `_`, e.g. - `examplebuilder_isCodeReviewed`. This practice avoids field name collisions - by namespacing each vendor. Non-extension field names never contain an - underscore. -- Extension fields MUST NOT alter the meaning of any other field. In other - words, an attestation with an absent extension field MUST be interpreted - identically to an attestation with an unrecognized (and thus ignored) - extension field. -- Extension fields SHOULD follow the [monotonic principle][parsing rules], - meaning that deleting or ignoring the extension SHOULD NOT turn a DENY - decision into an ALLOW. - -## Verification - -[Verification]: /spec/v1.0/verifying-artifacts - -Please see [Verifying Artifacts][Verification] for a detailed discussion of -provenance verification. - -## Index of build types - -The following is a partial index of build type definitions. Each contains a -complete example predicate. - - - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) -- [Google Cloud Build (community-maintained)](https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1) - -To add an entry here, please send a pull request on GitHub. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "internalParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "builderDependencies": null, // not in v0.2 - "version": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.0 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build platforms, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed: - - `parameters` -> `externalParameters` (slight change in semantics) - - `environment` -> `internalParameters` (slight change in semantics) - - `materials` -> `resolvedDependencies` (slight change in semantics) - - `buildInvocationId` -> `invocationId` - - `buildStartedOn` -> `startedOn` - - `buildFinishedOn` -> `finishedOn` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - ResourceDescriptor: `annotations`, `content`, `downloadLocation`, - `mediaType`, `name` - - Builder: `builderDependencies` and `version` - - `byproducts` -- Changed naming convention for extension fields. - -Differences from RC1 and RC2: - -- Renamed `systemParameters` (RC1 + RC2) -> `internalParameters` (final). -- Changed naming convention for extension fields (in RC2). -- Renamed `localName` (RC1) -> `name` (RC2). -- Added `annotations` and `content` (in RC2). - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: /spec/v1.0/threats -[trusted]: /spec/v1.0/principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.0/requirements.md b/docs/spec/v1.0/requirements.md deleted file mode 100644 index c0a72d931..000000000 --- a/docs/spec/v1.0/requirements.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -title: Producing artifacts -description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers. ---- - - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is platform implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Levels](levels.md). For background, see [Terminology](terminology.md). To -better understand the reasoning behind the requirements, see -[Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -In order to produce artifacts with a specific build level, responsibility is -split between the [Producer] and [Build platform]. The build platform MUST -strengthen the security controls in order to achieve a specific level while the -producer MUST choose and adopt a build platform capable of achieving a desired -build level, implementing any controls as specified by the chosen platform. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build platform - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build platform - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Unforgeable - ✓ -
Isolation strength - Hosted - ✓✓ -
Isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure platform is beyond the -scope of this specification, all implementations MUST use industry security -best practices to be conformant to this specification. This includes, but is -not limited to, using proper access controls, securing communications, -implementing proper management of cryptographic secrets, doing frequent updates, -and promptly fixing known vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -NOTE: There were more requirements for producers in the initial -[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted -how a package can be built. These were removed in the v1.0 specification and -will be reassessed and re-added as indicated in the -[future directions](future-directions.md). - -### Choose an appropriate build platform - -The producer MUST select a build platform that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -If a producer wishes to distribute their artifact through a [package ecosystem] -that requires explicit metadata about the build process in the form of a -configuration file, the producer MUST complete the configuration file and keep -it up to date. This metadata might include information related to the artifact's -source repository and build parameters. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the -[package ecosystem], provided that the package ecosystem is capable of -distributing provenance. - -## Build Platform - -[Build platform]: #build-platform - -A package's build platform is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build platform is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build platform used -by a single software project, or even an individual's workstation. Ideally, one -build platform is used by many different software packages so that consumers can -[minimize the number of trusted platforms](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build platform is responsible for providing two things: [provenance -generation] and [isolation between builds]. The [Build level](levels.md#build-track) describes -the degree to which each of these properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build platform is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the overall provenance integrity according to -minimum requirements on its: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package by cryptographic digest and describes how that package was -produced. The format MUST be acceptable to the [package ecosystem] and/or -[consumer](verifying-artifacts.md#consumer). - -It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. - -If using an alternate format, it MUST contain the equivalent information as SLSA -Provenance at each level and SHOULD be bi-directionally translatable to SLSA -Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build platform and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only -to the build platform component that generated the provenance attestation. - -While many constraints affect choice of signing methodologies, it is -RECOMMENDED that build platforms use signing methodologies which improve the -ability to detect and remediate key compromise, such as methods which rely on -transparency logs or, when transparency isn't appropriate, time stamping -services. - -Authenticity allows the consumer to trust the contents of the provenance -attestation, such as the identity of the build platform. - -*Accuracy:* The provenance MUST be generated by the control plane (i.e. within -the trust boundary [identified in the provenance]) and not by a tenant of the -build platform (i.e. outside the trust boundary), except as noted below. - -- The data in the provenance MUST be obtained from the build platform, either - because the generator *is* the build platform or because the provenance - generator reads the data directly from the build platform. -- The build platform MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. -- Exceptions for fields that MAY be generated by a tenant of the build platform: - - The names and cryptographic digests of the output artifacts, i.e. - `subject` in [SLSA Provenance]. See [forge output digest of the - provenance](threats#forged-digest) for explanation of why this is - acceptable. - - Any field that is not marked as REQUIRED for Build L2. For example, - `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at - Build L2. Builders SHOULD document any such cases of tenant-generated - fields. - -*Completeness:* SHOULD be complete. - -- There MAY be [external parameters] that are not sufficiently captured in - the provenance. -- Completeness of resolved dependencies is best effort. - - ✓✓ -
Provenance is Unforgeable - -*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. - -- Any secret material used for authenticating the provenance, for example the - signing key used to generate a digital signature, MUST be stored in a secure - management system appropriate for such material and accessible only to the - build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - platform in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted in [Provenance - is Authentic](#provenance-authentic). (Build L3 does not require additional - fields beyond those of L2.) - -*Completeness:* SHOULD be complete. - -- [External parameters] MUST be fully enumerated. -- Completeness of resolved dependencies is best effort. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build platform is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build platform's isolation strength, see -[Verifying build platforms](verifying-systems.md). - - - - -
RequirementDescriptionL1L2L3 - -
Hosted - - -All build steps ran using a hosted build platform on shared or dedicated -infrastructure, not on an individual's workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Isolated - - -The build platform ensured that the build steps ran in an isolated environment, -free of unintended external influence. In other words, any external influence on -the build was specifically requested by the build itself. This MUST hold true -even between builds within the same tenant project. - -The build platform MUST guarantee the following: - -- It MUST NOT be possible for a build to access any secrets of the build - platform, such as the provenance signing key, because doing so would - compromise the authenticity of the provenance. -- It MUST NOT be possible for two builds that overlap in time to influence one - another, such as by altering the memory of a different build process running - on the same machine. -- It MUST NOT be possible for one build to persist or influence the build - environment of a subsequent build. In other words, an ephemeral build - environment MUST be provisioned for each build. -- It MUST NOT be possible for one build to inject false entries into a build - cache used by another build, also known as "cache poisoning". In other - words, the output of the build MUST be identical whether or not the cache is - used. -- The build platform MUST NOT open services that allow for remote influence - unless all such interactions are captured as `externalParameters` in the - provenance. - -There are no sub-requirements on the build itself. Build L3 is limited to -ensuring that a well-intentioned build runs securely. It does not require that -a build platform prevents a producer from performing a risky or insecure build. In -particular, the "Isolated" requirement does not prohibit a build from calling -out to a remote execution service or a "self-hosted runner" that is outside the -trust boundary of the build platform. - -NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" -in the initial [draft version (v0.1)](../v0.1/requirements.md). - -NOTE: This requirement is not to be confused with "Hermetic", which roughly -means that the build ran with no network access. Such a requirement requires -substantial changes to both the build platform and each individual build, and is -considered in the [future directions](future-directions.md). - - ✓ -
- -[external parameters]: provenance.md#externalParameters -[identified in the provenance]: provenance.md#model -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.0/schema/provenance.cue b/docs/spec/v1.0/schema/provenance.cue deleted file mode 100644 index c4e308628..000000000 --- a/docs/spec/v1.0/schema/provenance.cue +++ /dev/null @@ -1,46 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "internalParameters": object, - "resolvedDependencies": [ ...#ResourceDescriptor ], - }, - "runDetails": { - "builder": { - "id": string, - "builderDependencies": [ ...#ResourceDescriptor ], - "version": { ...string }, - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ResourceDescriptor ], - } - } -} - -#ResourceDescriptor: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "gitCommit": string, - [string]: string, - }, - "name": string, - "downloadLocation": string, - "mediaType": string, - "content": bytes, // base64-encoded - "annotations": object, -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.0/schema/provenance.proto b/docs/spec/v1.0/schema/provenance.proto deleted file mode 100644 index 231702598..000000000 --- a/docs/spec/v1.0/schema/provenance.proto +++ /dev/null @@ -1,50 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct internal_parameters = 3; - repeated ResourceDescriptor resolved_dependencies = 4; -} - -message ResourceDescriptor { - string uri = 1; - map digest = 2; - string name = 3; - string download_location = 4; - string media_type = 5; - bytes content = 6; - google.protobuf.Struct annotations = 7; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ResourceDescriptor byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ResourceDescriptor builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.0/terminology.md b/docs/spec/v1.0/terminology.md deleted file mode 100644 index 365adbd7b..000000000 --- a/docs/spec/v1.0/terminology.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -title: Terminology -description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting. ---- - - -Before diving into the [SLSA Levels](levels.md), we need to establish a core set -of terminology and models to describe what we're protecting. - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). - -[build]: #build-model -[package]: #package-model -[SLSA Provenance]: /provenance/v1 - -### Roles - -Throughout the specification, you will see reference to the following roles -that take part in the software supply chain. Note that in practice a role may -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. - -### Build model - -

Model Build

- -We model a build as running on a multi-tenant *build platform*, where each -execution is independent. - -1. A tenant invokes the build by specifying *external parameters* through an - *interface*, either directly or via some trigger. Usually, at least one of - these external parameters is a reference to a *dependency*. (External - parameters are literal values while dependencies are artifacts.) -2. The build platform's *control plane* interprets these external parameters, - fetches an initial set of dependencies, initializes a *build environment*, - and then starts the execution within that environment. -3. The build then performs arbitrary steps, which might include fetching - additional dependencies, and then produces one or more *output* artifacts. - The steps within the build environment are under the tenant's control. - The build platform isolates build environments from one another to some - degree (which is measured by the SLSA Build Level). -4. Finally, for SLSA Build L2+, the control plane outputs *provenance* - describing this whole process. - -Notably, there is no formal notion of "source" in the build model, just external -parameters and dependencies. Most build platforms have an explicit "source" -artifact to build from, which is often a git repository; in the build model, the -reference to this artifact is an external parameter while the artifact itself is -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. - -
Ambiguous terms to avoid - -- *Build recipe:* Could mean *external parameters,* but may include concrete - steps of how to perform a build. To avoid implementation details, we don't - define this term, but always use "external parameters" which is the - interface to a build platform. Similar terms are *build configuration - source* and *build definition*. -- *Builder:* Usually means *build platform*, but might be used for *build - environment*, the user who invoked the build, or a build tool from - *dependencies*. To avoid confusion, we always use "build platform". The only - exception is in the [provenance](/provenance/v1), where `builder` is used as - a more concise field name. - -
- -### Package model - -Software is distributed in identifiable units called packages -according to the rules and conventions of a package ecosystem. -Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and -[OCI](https://github.com/opencontainers/distribution-spec), while examples of -informal ecosystems include links to files on a website or distribution of -first-party software within a company. - -Abstractly, a consumer locates software within an ecosystem by asking a -package registry to resolve a mutable package name into an -immutable package artifact.[^label] To publish a package -artifact, the software producer asks the registry to update this mapping to -resolve to the new artifact. The registry represents the entity or entities with -the power to alter what artifacts are accepted by consumers for a given package -name. For example, if consumers only accept packages signed by a particular -public key, then it is access to that public key that serves as the registry. - -The package name is the primary security boundary within a package ecosystem. -Different package names represent materially different pieces of -software---different owners, behaviors, security properties, and so on. -Therefore, **the package name is the primary unit being protected in SLSA**. -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. - -

Ambiguous terms to avoid - -- *Package repository:* Could mean either package registry or package name, - depending on the ecosystem. To avoid confusion, we always use "repository" - exclusively to mean "source repository", where there is no ambiguity. -- *Package manager* (without "client"): Could mean either package ecosystem, - package registry, or client-side tooling. - -
- -### Mapping to real-world ecosystems - -Most real-world ecosystems fit the package model above but use different terms. -The table below attempts to document how various ecosystems map to the SLSA -Package model. There are likely mistakes and omissions; corrections and -additions are welcome! - - - - - - - - - - - - - - - - - - - - - - - - - - -
Package ecosystem - Package registry - Package name - Package artifact -
Languages -
Cargo (Rust) - Registry - Crate name - Artifact -
CPAN (Perl) - Upload server - Distribution - Release (or Distribution) -
Go - Module proxy - Module path - Module -
Maven (Java) - Repository - Group ID + Artifact ID - Artifact -
npm (JavaScript) - Registry - Package Name - Package -
NuGet (C#) - Host - Project - Package -
PyPA (Python) - Index - Project Name - Distribution -
Operating systems -
Dpkg (e.g. Debian) - ? - Package name - Package -
Flatpak - Repository - Application - Bundle -
Homebrew (e.g. Mac) - Repository (Tap) - Package name (Formula) - Binary package (Bottle) -
Pacman (e.g. Arch) - Repository - Package name - Package -
RPM (e.g. Red Hat) - Repository - Package name - Package -
Nix (e.g. NixOS) - Repository (e.g. Nixpkgs) or binary cache - Derivation name - Derivation or store object -
Storage systems -
GCS - n/a - Object name - Object -
OCI/Docker - Registry - Repository - Object -
Meta -
deps.dev: System - Packaging authority - Package - n/a -
purl: type - Namespace - Name - n/a -
- -Notes: - -- Go uses a significantly different distribution model than other ecosystems. - In go, the package name is a source repository URL. While clients can fetch - directly from that URL---in which case there is no "package" or - "registry"---they usually fetch a zip file from a *module proxy*. The module - proxy acts as both a builder (by constructing the package artifact from - source) and a registry (by mapping package name to package artifact). People - trust the module proxy because builds are independently reproducible and a - *checksum database* guarantees that all clients receive the same artifact - for a given URL. - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build platform is -certified to ensure conformance with the requirements at the level claimed by -the build platform. This certification should happen on a recurring cadence with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer defined -expectations of where the package source code was retrieved from and on what -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. - -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. - -
- -
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. - -
diff --git a/docs/spec/v1.0/threats-overview.md b/docs/spec/v1.0/threats-overview.md deleted file mode 100644 index 5aeb409da..000000000 --- a/docs/spec/v1.0/threats-overview.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Supply chain threats -description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA could help. ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA could help. For a more technical discussion, see [Threats & mitigations](threats.md). - -## Summary - -![Supply Chain Threats](images/supply-chain-threats.svg) - -**Note that SLSA does not currently address all of the threats presented here.** -See [Threats & mitigations](threats.md) for what is currently addressed and -[Terminology](terminology.md) for an explanation of the supply chain model. - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that all changes to the source code reflect the -intent of the software producer. Intent of an organization is difficult to -define, so SLSA is expected to approximate this as approval from two authorized -representatives. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - -
-Integrity threat -Known example -How SLSA could help -
A -Submit unauthorized change (to source repo) -SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. -Two-person review could have caught the unauthorized change. -
B -Compromise source repo -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code platform would have been a much harder target for the attackers. -
C -Build from modified source (not matching source repo) -Webmin: Attacker modified the build infrastructure to use source files not matching source control. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
D -Use compromised dependency (i.e. A-H, recursively) -event-stream: Attacker added an innocuous dependency and then later updated the dependency to add malicious behavior. The update did not match the code submitted to GitHub (i.e. attack F). -Applying SLSA recursively to all dependencies would have prevented this particular vector, because the provenance would have indicated that it either wasn't built from a proper builder or that the source did not come from GitHub. -
E -Compromise build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA levels require stronger security controls for the build platform, making it more difficult to compromise and gain persistence. -
F -Upload modified package (not matching build process) -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Compromise package registry -Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Use compromised package -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
- - - - - - -
-Availability threat -Known example -How SLSA could help -
D -Dependency becomes unavailable -Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. diff --git a/docs/spec/v1.0/threats.md b/docs/spec/v1.0/threats.md deleted file mode 100644 index 8a912a82e..000000000 --- a/docs/spec/v1.0/threats.md +++ /dev/null @@ -1,524 +0,0 @@ ---- -title: Threats & mitigations -description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. ---- - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations in SLSA. For an introduction to the -supply chain threats that SLSA is aiming to protect against, see [Supply chain threats]. - -The examples on this page are meant to: - -- Explain the reasons for each of the SLSA [requirements](requirements.md). -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](levels.md) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - -
- -![Supply Chain Threats](images/supply-chain-threats.svg) - -See [Terminology](terminology.md) for an explanation of supply chain model. - -## Source threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes the threat of an authorized individual introducing an unauthorized -change---in other words, an insider threat. - -SLSA v1.0 does not address source threats, but we anticipate doing so in a -[future version](future-directions.md#source-track). In the meantime, the -threats and potential mitigations listed here show how SLSA v1.0 can fit into a -broader supply chain security program. - -### (A) Submit unauthorized change - -An adversary introduces a change through the official source control management -interface without any special administrator privileges. - -SLSA v1.0 does not address this threat, but it may be addressed in a [future -version](future-directions). - -### (B) Compromise source repo - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -SLSA v1.0 does not address this threat, but it may be addressed in a [future -version](future-directions). - -### (C) Build from modified source - -An adversary builds from a version of the source code that does not match the -official source control repository. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (E) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build platform pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -## Dependency threats - -A dependency threat is a vector for an adversary to introduce behavior to an -artifact through external software that the artifact requires to function. - -SLSA mitigates dependency threats when you verify your dependencies' SLSA -provenance. - -### (D) Use compromised dependency - -
Use a compromised build dependency - -*Threat:* The adversary injects malicious code into software required to build -the artifact. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0, though the build -provenance may list build dependencies on a best-effort basis for forensic -analysis. You may be able to mitigate this threat by pinning your build -dependencies, preferably by digest rather than version number. Alternatively, -you can [apply SLSA recursively](verifying-artifacts.md#step-3-optional-check-dependencies-recursively), -but we have not yet standardized how to do so. - -*Example:* The artifact uses `libFoo` and requires its source code to compile. -The adversary compromises `libFoo`'s source repository and inserts malicious -code. When your artifact builds, it contains the adversary's malicious code. - -
- -
Use a compromised runtime dependency - -*Threat:* The adversary injects malicious code into software required to run the -artifact. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. However, you can -mitigate this threat by verifying SLSA provenance for all of your runtime -dependencies that provide provenance. - -*Example:* The artifact dynamically links `libBar` and requires a binary version -to run. The adversary compromises `libBar`'s build process and inserts malicious -code. When your artifact runs, it contains the adversary's malicious code. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - -### (E) Compromise build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Forge values of the provenance (other than output digest) (Build L2+) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, the trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][unforgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -platform to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Forge output digest of the provenance (n/a) - -*Threat:* The tenant-controlled build process sets output artifact digest -(`subject` in SLSA Provenance) without the trusted control plane verifying that -such an artifact was actually produced. - -*Mitigation:* None; this is not a problem. Any build claiming to produce a given -artifact could have actually produced it by copying it verbatim from input to -output.[^preimage] (Reminder: Provenance is only a claim that a particular -artifact was *built*, not that it was *published* to a particular registry.) - -*Example:* A legitimate MyPackage artifact has digest `abcdef` and is built -from source repo `good/my-package`. A malicious build from source repo -`evil/my-package` claims that it built artifact `abcdef` when it did not. -Solution: Verifier rejects because the source location does not match; the -forged digest is irrelevant. - -[^preimage]: Technically this requires the artifact to be known to the - adversary. If they only know the digest but not the actual contents, they - cannot actually build the artifact without a [preimage attack] on the digest - algorithm. However, even still there are no known concerns where this is a - problem. - -[preimage attack]: https://en.wikipedia.org/wiki/Preimage_attack - -
-
Compromise project owner (Build L2+) - -*Threat:* An adversary gains owner permissions for the artifact's build project. - -*Mitigation:* The build project owner must not have the ability to influence the -build process or provenance generation. - -*Example:* MyPackage is built on Awesome Builder under the project "mypackage". -Adversary is an administrator of the "mypackage" project. Awesome Builder allows -administrators to debug build machines via SSH. An adversary uses this feature -to alter a build in progress. - -
-
Compromise other build (Build L3) - -*Threat:* Perform a malicious build that alters the behavior of a benign -build running in parallel or subsequent environments. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other or persist changes. - -*Example 1:* A build platform runs all builds for project MyPackage on -the same machine as the same Linux user. An adversary starts a malicious build -that listens for another build and swaps out source files, then starts a benign -build. The benign build uses the malicious build's source files, but its -provenance says it used benign source files. Solution: The build platform -changes architecture to isolate each build in a separate VM or similar. - -*Example 2:* A build platform uses the same machine for subsequent -builds. An adversary first runs a build that replaces the `make` binary with a -malicious version, then subsequently runs an otherwise benign build. Solution: -The builder changes architecture to start each build with a clean machine image. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build platform. - -*Mitigation:* Builds are [isolated] from the trusted build platform control -plane, and only the control plane has [access][unforgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a malicious artifact to a build cache that is later picked up by a -benign build process. - -*Mitigation:* Build caches must be [isolate][isolated] between builds to prevent -such cache poisoning attacks. - -*Example:* Build platform uses a build cache across builds, keyed by the hash of -the source file. Adversary runs a malicious build that creates a "poisoned" -cache entry with a falsified key, meaning that the value wasn't really produced -from that source. A subsequent build then picks up that poisoned cache entry. - -
-
Compromise build platform admin (verification) - -*Threat:* An adversary gains admin permissions for the artifact's build platform. - -*Mitigation:* The build platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals, audit -logging). - -*Example:* MyPackage is built on Awesome Builder. Awesome Builder allows -engineers on-call to SSH into build machines to debug production issues. An -adversary uses this access to modify a build in progress. Solution: Consumers -do not accept provenance from the build platform unless they trust sufficient -controls are in place to prevent abusing admin privileges. - -
- -### (F) Upload modified package - -An adversary uploads a package not built from the proper build process. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Solution: Verifier rejects because builder is not as -expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Compromise package registry - -An adversary modifies the package on the package registry using an -administrative interface or through a compromise of the infrastructure. - -
De-list artifact - -*Threat:* The package registry stops serving the artifact. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. - -
- -
De-list provenance - -*Threat:* The package registry stops serving the provenance. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. - -
- -### (H) Use compromised package - -An adversary modifies the package after it has left the package registry, or -tricks the user into using an unintended package. - -
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* **Mostly outside the scope of SLSA.** That said, the requirement -to make the source available can be a mild deterrent, can aid investigation or -ad-hoc analysis, and can complement source-based typosquatting solutions. - -
- -## Availability threats - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA v1.0 does not address availability threats, though future versions might. - -
(A)(B) Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* Some system retains the revision and its version control history, -making it available for inspection indefinitely. Users cannot delete the -revision except as part of a transparent legal or privacy process. - -*Example:* An adversary submits malicious code to the MyPackage GitHub repo, -builds from that revision, then does a force push to erase that revision from -history (or requests that GitHub delete the repo.) This would make the revision -unavailable for inspection. Solution: Verifier rejects the package because it -lacks a positive attestation showing that some system, such as GitHub, ensured -retention and availability of the source code. - -
-
(D) A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* **Outside the scope of SLSA.** That said, some solutions to -support hermetic and reproducible builds may also reduce the impact of this -threat. - -
- -## Verification threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above. - -
Tamper with recorded expectations - -*Threat:* Modify the verifier's recorded expectations, causing the verifier to -accept an unofficial package artifact. - -*Mitigation:* Changes to recorded expectations requires some form of -authorization, such as two-party review. - -*Example:* The package ecosystem records its expectations for a given package -name in a configuration file that is modifiable by that package's producer. The -configuration for MyPackage expects the source repository to be -`good/my-package`. The adversary modifies the configuration to also accept -`evil/my-package`, and then builds from that repository and uploads a malicious -version of the package. Solution: Changes to the recorded expectations require -two-party review. - -
-
Forge change metadata - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* Source control platform strongly authenticates actor identity, -timestamp, and parent revisions. - -*Example:* Adversary submits a git commit with a falsified author and timestamp, -and then rewrites history with a non-fast-forward update to make it appear to -have been made long ago. Solution: Consumer detects this by seeing that such -changes are not strongly authenticated and thus not trustworthy. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Require cryptographically secure hash functions for commit -checksums and provenance subjects, such as SHA-256. - -*Examples:* Construct a benign file and a malicious file with the same SHA-1 -hash. Get the benign file reviewed and then submit the malicious file. -Alternatively, get the benign file reviewed and submitted and then build from -the malicious file. Solution: Only accept cryptographic hashes with strong -collision resistance. - -
- -
- - - -[authentic]: requirements.md#provenance-authentic -[exists]: requirements.md#provenance-exists -[isolated]: requirements.md#isolated -[unforgeable]: requirements.md#provenance-unforgeable -[supply chain threats]: threats-overview diff --git a/docs/spec/v1.0/use-cases.md b/docs/spec/v1.0/use-cases.md deleted file mode 100644 index 9e92d2b46..000000000 --- a/docs/spec/v1.0/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package registry. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build platforms rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified from a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.0/verification_summary.md b/docs/spec/v1.0/verification_summary.md deleted file mode 100644 index ef0a1d760..000000000 --- a/docs/spec/v1.0/verification_summary.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software producers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [resolvedDependencies](/provenance/v1#resolvedDependencies) of the artifact -being verified (recursively) or b) matching the non-source dependency -listed in `resolvedDependencies` (`subject.digest` == -`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` == -`resolvedDependencies.uri`) to a VSA _for that dependency_ and using -`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependencyLevels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - // Required - "verifier": { - "id": "" - }, - "timeVerified": , - "resourceUri": , - "policy": { - "uri": "", - "digest": { /* DigestSet */ } - } - "inputAttestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verificationResult": "", - "verifiedLevels": [""], - "dependencyLevels": { - "": , - "": , - ... - }, - "slsaVersion": ".", -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`timeVerified` _string ([Timestamp]), required_ - -> Timestamp indicating what time the verification occurred. - - -`resourceUri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. - - -`policy` _object ([ResourceDescriptor]), required_ - -> Describes the policy that the `subject` was verified against. -> -> The entry MUST contain a `uri`. - - -`inputAttestations` _array ([ResourceDescriptor]), optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `resolvedDependencies` field in [SLSA Provenance]. -> -> This field MAY be absent if the verifier does not support this feature. -> If non-empty, this field MUST contain information on _all_ the attestations -> used to perform verification. -> -> Each entry MUST contain a `digest` of the attestation and SHOULD contains a -> `uri` that can be used to fetch the attestation. - - -`verificationResult` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`verifiedLevels` _array ([SlsaResult]), required_ - -> Indicates the highest level of each track verified for the artifact (and not -> its dependencies), or "FAILED" if policy verification failed. -> -> Users MUST NOT include more than one level per SLSA track. Note that each SLSA -> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies -> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to -> include more than one level per track. - - -`dependencyLevels` _object, optional_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. -> A set but empty `dependencyLevels` object means that the artifact has **no** -> dependency at all, while an unset or null `dependencyLevels` means that the -> verifier makes no claims about the artifact's dependencies. -> -> Users MUST count each dependency only once per SLSA track, at the highest -> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`, -> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for -> `SLSA_BUILD_LEVEL_1`. - - -`slsaVersion` _string, optional_ - -> Indicates the version of the SLSA specification that the verifier used, in the -> form `.`. Example: `1.0`. If unset, the default is an -> unspecified minor version of `1.x`. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier" - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "inputAttestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_BUILD_LEVEL_3"], - "dependencyLevels": { - "SLSA_BUILD_LEVEL_3": 5, - "SLSA_BUILD_LEVEL_2": 7, - "SLSA_BUILD_LEVEL_1": 1, - }, - "slsaVersion": "1.0" -} -``` - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -SHOULD be one of these values: - -- `SLSA_BUILD_LEVEL_0` -- `SLSA_BUILD_LEVEL_1` -- `SLSA_BUILD_LEVEL_2` -- `SLSA_BUILD_LEVEL_3` -- `FAILED` (Indicates policy evaluation failed) - -Note that each SLSA level implies the levels below it in the same track. -For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` + -`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`). - -Users MAY use custom values here but MUST NOT use custom values starting with -`SLSA_`. - -## Change history - -- 1: - - Replaced `materials` with `resolvedDependencies`. - - Relaxed `SlsaResult` to allow other values. - - Converted to lowerCamelCase for consistency with [SLSA Provenance]. - - Added `slsaVersion` field. -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SLSA Provenance]: /provenance -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md -[ResourceURI]: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#ResourceURI -[ResourceDescriptor]: https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md -[Statement]: https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md -[Timestamp]: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#Timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v1/README.md#parsing-rules diff --git a/docs/spec/v1.0/verifying-artifacts.md b/docs/spec/v1.0/verifying-artifacts.md deleted file mode 100644 index 2e6e7045d..000000000 --- a/docs/spec/v1.0/verifying-artifacts.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Verifying artifacts -description: SLSA uses provenance to indicate whether an artifact is authentic or not, but provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection verification, and this page describes how to verify artifacts and their SLSA provenenance. The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that -inspection **verification**, and this page describes recommendations for how to -verify artifacts and their SLSA provenance. - -This page is divided into several sections. The first describes the process -for verifying an artifact and its provenance against a set of expectations. The -second describes how to form the expectations used to verify provenance. The -third discusses architecture choices for where provenance verification can -happen. - -## How to verify - -Verification SHOULD include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- Verifying the signature on the provenance envelope. -- Ensuring that the values for `buildType` and `externalParameters` in the - provenance match the expected values. The package ecosystem MAY allow - an approved list of `externalParameters` to be ignored during verification. - Any unrecognized `externalParameters` SHOULD cause verification to fail. - -![Threats covered by each step](images/supply-chain-threats-build-verification.svg) - -See [Terminology](terminology.md) for an explanation of supply chain model and -[Threats & mitigations](threats.md) for a detailed explanation of each threat. - -**Note:** This section assumes that the provenance is in the recommended -[provenance format](/provenance/v1). If it is not, then the verifier SHOULD -perform equivalent checks on provenance fields that correspond to the ones -referenced here. - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "E", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This configuration - is likely in the form of a map from (builder public key identity, - `builder.id`) to (SLSA Build level) drawn from the SLSA Conformance - Program (coming soon). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the artifact in question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "E"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Verifying build platforms](verifying-systems). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "H".) -- [Threat "H"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. - -[Threat "E"]: threats#e-compromise-build-process -[Threat "F"]: threats#f-upload-modified-package -[Threat "G"]: threats#g-compromise-package-repo -[Threat "H"]: threats#h-use-compromised-package - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets your expectations for that -package in order to mitigate [threat "C"]. - -In our threat model, the adversary has ability to invoke a build and to publish -to the registry. The adversary is not able to write to the source repository, nor do -they have insider access to any trusted systems. Your expectations SHOULD be -sufficient to detect or prevent this adversary from injecting unofficial -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 - -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 -range of values (possibly any value) if it is known that any value in the range -is safe. JSON comparison is sufficient for verifying parameters. - -TIP: Difficulty in forming meaningful expectations about `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "C"]: threats#c-build-from-modified-source - -### Step 3: (Optional) Check dependencies recursively - -[verify-step-3]: #step-3-optional-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. Note that SLSA v1.0 does not have any requirements on the -completeness or verification of `resolvedDependencies`. However, one might wish -to verify dependencies in order to mitigate [threat "E"] and protect against -threats further up the supply chain. If `resolvedDependencies` is incomplete, -these checks can be done on a best-effort basis. - -A [Verification Summary Attestation (VSA)][VSA] can make dependency verification -more efficient by recording the result of prior verifications. A trimming -heuristic or exception mechanism is almost always necessary when verifying -dependencies because there will be transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) - -[Threat "E"]: threats#e-use-compromised-dependency -[VSA]: /verification_summary -[threats]: threats - -## Forming Expectations - -Expectations are known provenance values that indicate the -corresponding artifact is authentic. For example, a package ecosystem may -maintain a mapping between package names and their canonical source -repositories. That mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git branches or tags. - -- **Defined by producer:** The package producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the package's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -- **Defined in source:** The source repository tells the verifier what their - expectations ought to be. In this model, the package name is immutably bound - to a source repository and all other external parameters are defined in the - source repository. This is how the Go ecosystem works, for example, since - the package name *is* the source repository location. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -will likely have different artifacts and therefore different provenance. Similarly, an -artifact might have different names in different package ecosystems but use the same -provenance file. - -## Architecture options - -There are several options (non-mutually exclusive) for where provenance verification -can happen: the package ecosystem at upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify provenance. For example, even if a package -ecosystem verifies provenance, consumers who get artifacts from that package -ecosystem might wish to verify provenance themselves for defense in depth. They -can do so using either client-side verification tooling or by polling a -monitor. - - - -### Package ecosystem - -[Package ecosystem]: #package-ecosystem - -A package ecosystem is a set of rules and conventions governing -how packages are distributed. Every package artifact has an ecosystem, whether it is -formal or ad-hoc. Some ecosystems are formal, such as language distribution -(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". For more background, see -[Package Model](terminology.md#package-model). - -During package upload, a package ecosystem can ensure that the artifact's -provenance matches the expected values for that package name's provenance before -accepting it into the package registry. This option is RECOMMENDED whenever -possible because doing so benefits all of the package ecosystem's clients. - -The package ecosystem is responsible for making its expectations available to -consumers, reliably redistributing artifacts and provenance, and providing tools -to enable safe artifact consumption (e.g. whether an artifact meets -expectations). - -### Consumer - -[Consumer]: #consumer - -A package artifact's consumer is the organization or individual that uses the -package artifact. - -Consumers can form their own expectations for artifacts or use the default -expectations provided by the package producer and/or package ecosystem. -When forming their own expectations, the consumer uses client-side verification tooling to ensure -that the artifact's provenance matches their expectations for that package -before use (e.g. during installation or deployment). Client-side verification -tooling can be either standalone, such as -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into -the package ecosystem client. - -### Monitor - -[Monitor]: #monitor - -A monitor is a service that verifies provenance for a set -of packages and publishes the result of that verification. The set of -packages verified by a monitor is arbitrary, though it MAY mimic the set -of packages published through one or more package ecosystems. The monitor -SHOULD publish its expectations for all the packages it verifies. - -Consumers can continuously poll a monitor to detect artifacts that -do not meet the monitor's expectations. Detecting artifacts that fail -verification is of limited benefit unless a human or automated system takes -action in response to the failed verification. diff --git a/docs/spec/v1.0/verifying-systems.md b/docs/spec/v1.0/verifying-systems.md deleted file mode 100644 index 7c0ef2896..000000000 --- a/docs/spec/v1.0/verifying-systems.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Verifying build platforms -description: Guidelines for assessing build platform security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust platforms to produce Build L3 -artifacts and provenance unless they have some proof that the provenance is -[unforgeable](requirements.md#provenance-unforgeable) and the builds are -[isolated](requirements.md#isolated). - -This page describes the parts of a build platform that consumers SHOULD assess -and provides sample questions consumers can ask when assessing a build platform. -See also [Threats & mitigations](threats.md) and the -[build model](terminology.md#build-model). - -## Threats - -### Adversary goal - -The SLSA Build track defends against an adversary whose primary goal is to -inject unofficial behavior into a package artifact while avoiding detection. -Remember that [verifiers](verifying-artifacts.md) only accept artifacts whose -provenance matches expectations. To bypass this, the adversary tries to either -(a) tamper with a legitimate build whose provenance already matches -expectations, or (b) tamper with an illegitimate build's provenance to make it -match expectations. - -More formally, if a build with external parameters P would produce an artifact -with binary hash X and a build with external parameters P' would produce an -artifact with binary hash Y, they wish to produce provenance indicating a build -with external parameters P produced an artifact with binary hash Y. - -See threats [C], [D], [E], and [F] for examples of specific threats. - -Note: Platform abuse (e.g. running non-build workloads) and attacks against -builder availability are out of scope of this document. - -### Adversary profiles - -Consumers SHOULD also evaluate the build platform's ability to defend against the -following types of adversaries. - -1. Project contributors, who can: - - Create builds on the build platform. These are the adversary's controlled - builds. - - Modify one or more controlled builds' external parameters. - - Modify one or more controlled builds' environments and run arbitrary - code inside those environments. - - Read the target build's source repo. - - Fork the target build's source repo. - - Modify a fork of the target build's source repo and build from it. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Create new builds under the target build's project or identity. - - Modify the target build's source repo and build from it. - - Modify the target build's configuration. -3. Build platform administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Run arbitrary code on the build platform. - - Read and modify network traffic. - - Access the control plane's cryptographic secrets. - - Remotely access build environments (e.g. via SSH). - -[C]: threats.md#c-build-from-modified-source -[D]: threats.md#d-use-compromised-dependency -[E]: threats.md#e-compromise-build-process -[F]: threats.md#f-upload-modified-package - -## Build platform components - -Consumers SHOULD consider at least these five elements of the -[build model](terminology.md#build-model) when assessing build platforms for SLSA -conformance: external parameters, control plane, build environments, caches, -and outputs. - -![image](images/build-model.svg) - -The following sections detail these elements of the build model and give prompts -for assessing a build platform's ability to produce SLSA Build L3 provenance. The -assessment SHOULD take into account the security model used to identify the -transitive closure of the `builder.id` for the [provenance model](provenance.md#model), specifically -around the platform's boundaries, actors, and interfaces. - -### External parameters - -External parameters are the external interface to the builder and include all -inputs to the build process. Examples include the source to be built, the build -definition/script to be executed, user-provided instructions to the -control plane for how to create the build environment (e.g. which operating -system to use), and any additional user-provided strings. - -#### Prompts for assessing external parameters - -- How does the control plane process user-provided external parameters? - Examples: sanitizing, parsing, not at all -- Which external parameters are processed by the control plane and which are - processed by the build environment? -- What sort of external parameters does the control plane accept for - build environment configuration? -- How do you ensure that all external parameters are represented in the - provenance? -- How will you ensure that future design changes will not add additional - external parameters without representing them in the provenance? - -### Control plane - -The control plane is the build platform component that orchestrates each -independent build execution. It is responsible for setting up each build and -cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs -provenance for each build performed on the build platform. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -#### Prompts for assessing the control plane - -- Administration - - What are the ways an employee can use privileged access to influence a - build or provenance generation? Examples: physical access, terminal - access, access to cryptographic secrets - - What controls are in place to detect or prevent the employee from - abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many employees have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and platform - outages? Are they tested? How frequently? - -- Provenance generation - - How does the control plane observe the build to ensure the provenance's - accuracy? - - Are there situations in which the control plane will not generate - provenance for a completed build? What are they? - -- Development practices - - How do you track the control plane's software and configuration? - Example: version control - - How do you build confidence in the control plane's software supply - chain? Example: SLSA L3+ provenance, build from source - - How do you secure communications between builder components? Example: - TLS with certificate transparency. - - Are you able to perform forensic analysis on compromised build - environments? How? Example: retain base images indefinitely - -- Creating build environments - - How does the control plane share data with build environments? Example: - mounting a shared file system partition - - How does the control plane protect its integrity from build - environments? Example: not mount its own file system partitions on - build environments - - How does the control plane prevent build environments from accessing its - cryptographic secrets? Examples: dedicated secret storage, not mounting - its own file system partitions to build environments, hardware security - modules - -- Managing cryptographic secrets - - How do you store the control plane's cryptographic secrets? - - Which parts of the organization have access to the control plane's - cryptographic secrets? - - What controls are in place to detect or prevent employees abusing such - access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Build environment - -The build environment is the independent execution context where the build -takes place. In the case of a distributed build, the build environment is the -collection of all execution contexts that run build steps. Each build -environment must be isolated from the control plane and from all other build -environments, including those running builds from the same tenant or project. -Tenants are free to modify the build environment arbitrarily. Build -environments must have a means to fetch input artifacts (source, dependencies, -etc). - -#### Prompts for assessing build environments - -- Isolation technologies - - How are build environments isolated from the control plane and each - other? Examples: VMs, containers, sandboxed processes - - How is separation achieved between trusted and untrusted processes? - - How have you hardened your build environments against malicious tenants? - Examples: configuration hardening, limiting attack surface - - How frequently do you update your isolation software? - - What is your process for responding to vulnerability disclosures? What - about vulnerabilities in your dependencies? - - What prevents a malicious build from gaining persistence and influencing - subsequent builds? - -- Creation and destruction - - What operating system and utilities are available in build environments - on creation? How were these elements chosen? Examples: A minimal Linux - distribution with its package manager, OSX with HomeBrew - - How long could a compromised build environment remain active in the - build platform? - -- Network access - - Are build environments able to call out to remote execution? If so, how - do you prevent them from tampering with the control plane or other build - environments over the network? - - Are build environments able to open services on the network? If so, how - do you prevent remote interference through these services? - -### Cache - -Builders may have zero or more caches to store frequently used dependencies. -Build environments may have either read-only or read-write access to caches. - -#### Prompts for assessing caches - -- What sorts of caches are available to build environments? -- How are those caches populated? -- How are cache contents validated before use? - -### Output storage - -Output Storage holds built artifacts and their provenance. Storage may either be -shared between build projects or allocated separately per-project. - -#### Prompts for assessing output storage - -- How do you prevent builds from reading or overwriting files that belong to - another build? Example: authorization on storage -- What processing, if any, does the control plane do on output artifacts? - -## Builder evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model defined as -part of the provenance. Evidence submitted for third-party certification need not -be published. diff --git a/docs/spec/v1.0/whats-new.md b/docs/spec/v1.0/whats-new.md deleted file mode 100644 index 7ef772722..000000000 --- a/docs/spec/v1.0/whats-new.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: What's new in SLSA v1.0 -description: SLSA v1.0 is the first stable release of SLSA. This document describes what has changed since v0.1. ---- - -SLSA v1.0 is the first stable release of SLSA, creating a solid foundation on -which future versions can expand. This document describes the major changes in -v1.0 relative to the prior release, [v0.1]. - -## Summary of changes - -SLSA v1.0 is a significant rework of the specification in response to ongoing -feedback, filed issues, suggestions for course corrections, and other input from -the SLSA community and early adopters. Overall, the changes prioritize -simplicity, practicality, and stability. - -Overall, SLSA v1.0 is more stable and better defined than v0.1, but less -ambitious. It corresponds roughly to the build and provenance requirements of -the prior version's SLSA Levels 1 through 3, deferring SLSA Level 4 and the -source and common requirements to a future version. The rationale is explained -[below][stability]. - -Other significant changes: - -- [Division of the levels into multiple tracks][tracks], which are separate - sets of levels that measure different aspects of software supply chain - security -- [Reorganization and simplification of the core specification][core-spec] to - make it easier to understand and to provide better guidance -- [New guidance on verification][verification] of artifacts and build systems -- [Updated provenance and VSA schemas][provenance-spec], with a clearer build - model - -## Stability and scope - -[stability]: #stability-and-scope - -The v1.0 release marks the first stable version of SLSA. We are confident that -the specification represents broad consensus and will not change significantly -in the future. Having a stable foundation enables organizations and ecosystems -to begin implementing and adopting SLSA with minimal risk of future breaking -changes. - -That said, some concepts from v0.1 had to be deferred to a [future -version][future] in order to allow us to release v1.0 in a reasonable time -frame. The deferred concepts---source requirements, hermetic builds (SLSA L4), -and common requirements---were at significant risk of breaking changes in the -future to address concerns from v0.1. We believed it was more valuable to -release a small but stable base now while we work towards solidifying those -concepts in a future version. - -Going forward, we commit to a consistent [versioning](/spec-stages#versioning) -scheme based on semantic versioning. Backwards-incompatible changes will result -in a major version increase (v2.0, v3.0, etc.); significant backwards-compatible -changes will result in a minor version increase (v1.1, v1.2, etc.), while -editorial changes may be made without a version increase. - -For further explanation of the decisions behind v1.0, see the [SLSA v1.0 -Proposal][proposal]. - -## Tracks - -[Tracks]: #tracks - -A significant conceptual change from v0.1 is the division of SLSA's level -requirements into multiple tracks. Previously, each SLSA level encompassed -requirements across multiple software supply chain aspects: there were source, -build, provenance, and common requirements. To reach a particular level, -adopters needed to meet [all requirements in each of the four areas][v0.1-reqs]. -Organizing the specification in that way made adoption cumbersome, since -requirements were split across unrelated domains—improvements in one area were -not recognized until improvements were made in all areas. - -Now, the requirements are divided into SLSA tracks that each focus on one area -of the software supply chain. We anticipate this division will make SLSA -adoption easier for users. Division into tracks also benefits the SLSA -community: developers contributing to SLSA can parallelize work on multiple -tracks without blocking each other, and members of the community can contribute -specifically to their areas of expertise. - -SLSA v1.0 defines the SLSA Build track to begin this separation of -requirements, with other tracks to come in future versions. The new -[SLSA Build track Levels 1-3](levels#build-track) roughly -correspond to [Levels 1-3 of v0.1](requirements#build-requirements), -minus the source requirements. We anticipate future versions of the -specification to continue building on requirements without changing the existing -requirements defined in v1.0. The specification will likely expand to -incorporate both new tracks and additional levels for existing tracks. We -currently have [plans][future] for Build Level 4 and a Source track. - -The v1.0 also defines the [principles](principles) behind SLSA track -requirements, which will guide future track additions. For more information -about the rationale for tracks, see the [proposal]. - -## Improvements to core specification - -[core-spec]: #improvements-to-core-specification - -We've simplified and reorganized the specification to make it easier to -understand and apply. We've also split the requirements into multiple pages to -better reflect the division of labor across the software supply chain: producing -artifacts, distributing provenance, verifying artifacts, and verifying build -platforms. - -[Terminology](terminology) has been expanded to fully define all necessary -concepts and to be consistent across the specification. - -[Security levels](levels) has been completely rewritten to provide a high -level overview of the SLSA [tracks] and levels. Importantly, it explains the -benefits provided by each level. - -[Producing artifacts](requirements) explains requirements for the software -producer and the build platform. While the requirements are largely the same as -before---aside from those [deferred][stability] to a future version---there are -some minor changes to make SLSA easier to adopt. These changes include: -renaming, simplifying, and merging some requirements; removing the redundant -"scripted build" and "config as code" requirements; merging of the provenance -requirements into the recommended [provenance format][provenance-spec]; and -splitting the requirements between those for the Producer and the Build -platform. - -[Distributing provenance](distributing-provenance) *(new for v1.0)* provides -guidance to software producers and package ecosystems on how to distribute -provenance alongside artifacts. We hope this brings consistency across open -source package ecosystems as they adopt SLSA. - -[Verifying artifacts](verifying-artifacts) *(new for v1.0)* provides guidance to -package ecosystems and consumers for how to verify provenance and compare it to -expectations. It is discussed more in the following section. - -[Verifying build platforms](verifying-systems) *(new for v1.0)* provides a list -of prompts for evaluating a build platform's SLSA conformance. It covers similar -ground as v0.1's common requirements, but in a different form. It is also -discussed in the following section. - -[Threats & mitigations](threats) has been updated for v1.0, filling out parts -that were missing in v0.1. Note that labels D and E have swapped positions from -v0.1 to align with the grouping of Source (A-C), Dependency (D), and Build (E-H) -threats. - -## Verification - -[verification]: #verification - -Another significant change in the v1.0 is documenting the need for provenance -verification. - -SLSA v0.1 specified guidance for how to produce provenance but not how to verify -it. This left a large gap as most threats targeted by SLSA are only mitigated by -verifying provenance and comparing it to expectations. - -SLSA v1.0 addresses this gap by providing more explicit guidance on how to -verify provenance. This is split between establishing -[trust in build platforms](verifying-systems) themselves versus establishing -[trust in artifacts](verifying-artifacts) produced by those build platforms. -Build platforms implement the requirements around isolation and provenance -generation, and consumers choose whether to trust those build platforms. Once -that trust is established, consumers or package managers can verify artifacts by -comparing the provenance to expectations for the package in question. - -Ecosystems are already creating verification tooling, such as [npm's forthcoming -SLSA support](https://github.com/github/roadmap/issues/612). Tooling for -organizations that need to protect first-party software is also available, such -as [slsa-verifier](https://github.com/slsa-framework/slsa-verifier). - -## Provenance and VSA formats - -[provenance-spec]: #provenance-and-vsa-formats - -SLSA v1.0 simplifies SLSA's build model and recommended provenance format to -make it easier to understand and apply to arbitrary build platforms. - -A major source of confusion for SLSA v0.1 was how to model a build and represent -it in provenance. The v0.1 spec and v0.x provenance formats were overly rigid -about a build's inputs, differentiating between "source", "build config", "entry -point", and so on. Many implementers found that their build platforms did not -clearly fit into this model, and the intent of each field was not clear. -Furthermore, provenance requirements were described both abstractly in the SLSA -specification and concretely in the provenance format, using different language. -Implementers needed to jump back and forth and mentally map one concept to -another. - -SLSA v1.0 and the recommended [provenance v1 format](/provenance/v1) attempt to -address this confusion by simplifying the model and aligning terminology between -the two. The main change is to represent all "external parameters" that are -exposed to the build platform's users, instead of differentiating between -various inputs. Now, you can represent arbitrary parameters, as long as it is -possible to compare these parameters to expectations. Other parts of the -provenance format were renamed, though most concepts translate from the old -format to the new format. For a detailed list of changes, see -[provenance change history](/provenance/v1#change-history). - -In addition, the recommended -[verification summary attestation (VSA)](/verification_summary/v1) has been -updated to v1.0. - - - -[future]: future-directions -[proposal]: https://github.com/slsa-framework/slsa-proposals/blob/main/0003/README.md -[v0.1-reqs]: /spec/v0.1/requirements -[v0.1]: /spec/v0.1/ diff --git a/docs/spec/v1.1-rc1/about.md b/docs/spec/v1.1-rc1/about.md deleted file mode 100644 index dc1bfade4..000000000 --- a/docs/spec/v1.1-rc1/about.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: About SLSA -description: With supply chain attacks on the rise, a shared vocabulary and universal framework is needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software. ---- - -This page is an introduction to SLSA and its concepts. If you're new -to SLSA, start here! - -## What is SLSA? - -Supply-chain Levels for Software Artifacts, or SLSA ("salsa"), is a set of incrementally adoptable guidelines for supply chain security, -established by industry consensus. The specification set by SLSA is useful for -both software producers and consumers: producers can follow SLSA's guidelines to -make their software supply chain more secure, and consumers can use SLSA to make -decisions about whether to trust a software package. - -SLSA offers: - -- A common vocabulary to talk about software supply chain security -- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume -- An actionable checklist to improve your own software's security -- A way to measure your efforts toward compliance with forthcoming - Executive Order standards in the [Secure Software Development Framework (SSDF)](https://csrc.nist.gov/Projects/ssdf) - -## Why SLSA is needed - -High profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply -chain integrity weaknesses that may go unnoticed, yet quickly become very -public, disruptive, and costly in today's environment when exploited. They've -also shown that there are inherent risks not just in code itself, but at -multiple points in the complex process of getting that code into software -systems—that is, in the **software supply chain**. Since these attacks are on -the rise and show no sign of decreasing, a universal framework for hardening the -software supply chain is needed, as affirmed by the -[U.S. Executive Order on Improving the Nation's Cybersecurity](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/). - -Security techniques for vulnerability detection and analysis of source code are -essential, but are not enough on their own. Even after fuzzing or vulnerability -scanning is completed, changes to code can happen, whether unintentionally or -from insider threats or compromised accounts. Risk for code modification exists at -each link in a typical software supply chain, from source to build through -packaging and distribution. Any weaknesses in the supply chain undermine -confidence in whether the code that you run is actually the code that you -scanned. - -SLSA is designed to support automation that tracks code handling from source -to binary, protecting against tampering regardless of the complexity -of the software supply chain. As a result, SLSA increases trust that the -analysis and review performed on source code can be assumed to still apply to -the binary consumed after the build and distribution process. - -## SLSA in layperson's terms - -There has been a [lot of discussion](https://ntia.gov/page/software-bill-materials) about the need for "ingredient labels" for -software—a "software bill of materials" (SBOM) that tells users what is in their -software. Building off this analogy, SLSA can be thought of as all the food -safety handling guidelines that make an ingredient list credible. From standards -for clean factory environments so contaminants aren't introduced in packaging -plants, to the requirement for tamper-proof seals on lids that ensure nobody -changes the contents of items sitting on grocery store shelves, the entire food -safety framework ensures that consumers can trust that the ingredient list -matches what's actually in the package they buy. - -Likewise, the SLSA framework provides this trust with guidelines and -tamper-resistant evidence for securing each step of the software production -process. That means you know not only that nothing unexpected was added to the -software product, but also that the ingredient label itself wasn't tampered with -and accurately reflects the software contents. In this way, SLSA helps protect -against the risk of: - -- Code modification (by adding a tamper-evident "seal" to code after - source control) -- Uploaded artifacts that were not built by the expected CI/CD platform (by marking - artifacts with a factory "stamp" that shows which build platform created it) -- Threats against the build platform (by providing "manufacturing facility" - best practices for build platform services) - -For more exploration of this analogy, see the blog post -[SLSA + SBOM: Accelerating SBOM success with the help of SLSA](/blog/2022/05/slsa-sbom). - -## Who is SLSA for? - -In short: everyone involved in producing and consuming software, or providing -infrastructure for software. - -**Software producers**, such as an open source project, a software vendor, or a -team writing first-party code for use within the same company. SLSA gives you -protection against tampering along the supply chain to your consumers, both -reducing insider risk and increasing confidence that the software you produce -reaches your consumers as you intended. - -**Software consumers**, such as a development team using open source packages, a -government agency using vendored software, or a CISO judging organizational -risk. SLSA gives you a way to judge the security practices of the software you -rely on and be sure that what you receive is what you expected. - -**Infrastructure providers**, who provide infrastructure such as an ecosystem -package manager, build platform, or CI/CD platform. As the bridge between the -producers and consumers, your adoption of SLSA enables a secure software supply -chain between them. - -## How SLSA works - -We talk about SLSA in terms of [tracks and levels](levels.md). -A SLSA track focuses on a particular aspect of a supply chain, such as the Build -Track. SLSA v1.0 consists of only a single track ([Build](levels.md#build-track)), but future versions of -SLSA will add tracks that cover other parts of the software supply chain, such -as how source code is managed. - -Within each track, ascending levels indicate increasingly hardened security -practices. Higher levels provide better guarantees against supply chain threats, -but come at higher implementation costs. Lower SLSA levels are designed to be -easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes -used to refer to software that doesn't yet meet any SLSA level. Currently, the -SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels -to be possible in [future revisions](future-directions.md). - -The combination of tracks and levels offers an easy way to discuss whether -software meets a specific set of requirements. By referring to an artifact as -meeting SLSA Build Level 3, for example, you're indicating in one phrase that -the software artifact was built following a set of security practices that -industry leaders agree protect against particular supply chain compromises. - -## What SLSA doesn't cover - -SLSA is only one part of a thorough approach to supply chain security. There -are several areas outside SLSA's current framework that are nevertheless -important to consider together with SLSA such as: - -- Code quality: SLSA does not tell you whether the developers writing the - source code followed secure coding practices. -- Producer trust: SLSA does not address organizations that intentionally - produce malicious software, but it can reduce insider risks within an - organization you trust. SLSA's Build Track protects against tampering during - or after the build, and [future SLSA tracks](future-directions.md) intend to - protect against unauthorized modifications of source code and dependencies. -- Transitive trust for dependencies: the SLSA level of an artifact is - independent of the level of its dependencies. You can use SLSA recursively to - also judge an artifact's dependencies on their own, but there is - currently no single SLSA level that applies to both an artifact and its - transitive dependencies together. For a more detailed explanation of why, - see the [FAQ](faq#q-why-is-slsa-not-transitive). diff --git a/docs/spec/v1.1-rc1/attestation-model.md b/docs/spec/v1.1-rc1/attestation-model.md deleted file mode 100644 index 7cb104f8c..000000000 --- a/docs/spec/v1.1-rc1/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.1-rc1/distributing-provenance.md b/docs/spec/v1.1-rc1/distributing-provenance.md deleted file mode 100644 index 11f01f4a2..000000000 --- a/docs/spec/v1.1-rc1/distributing-provenance.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Distributing provenance -description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is platform implementers and software distributors. ---- - -In order to make provenance for artifacts available after generation -for verification, SLSA requires the distribution and verification of provenance -metadata in the form of SLSA attestations. - -This document provides specifications for distributing provenance, and the -relationship between build artifacts and provenance (build attestations). It is -primarily concerned with artifacts for ecosystems that distribute build -artifacts, but some attention is also paid to ecosystems that distribute -container images or only distribute source artifacts, as many of the same -principles generally apply to any artifact or group of artifacts. - -In addition, this document is primarily for the benefit of artifact -distributors, to understand how they can adopt the distribution of SLSA -provenance. It is primarily concerned with the means of distributing -attestations and the relationship of attestations to build artifacts, and not -with the specific format of the attestation itself. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Background - -The [package ecosystem]'s maintainers are responsible for reliably -redistributing artifacts and provenance, making the producers' expectations -available to consumers, and providing tools to enable safe artifact consumption -(e.g. whether an artifact meets its producer's expectations). - -## Relationship between releases and attestations - -Attestations SHOULD be bound to artifacts, not releases. - -A single "release" of a project, package, or library might include multiple -artifacts. These artifacts result from builds on different platforms, -architectures or environments. The builds need not happen at roughly the same -point in time and might even span multiple days. - -It is often difficult or impossible to determine when a release is 'finished' -because many ecosystems allow adding new artifacts to old releases when adding -support for new platforms or architectures. Therefore, the set of attestations -for a given release MAY grow over time as additional builds and attestations -are created. - -Thus, package ecosystems SHOULD support multiple individual attestations per -release. At the time of a given build, the relevant provenance for that build -can be added to the release, depending on the relationship to the given -artifacts. - -## Relationship between artifacts and attestations - -Package ecosystems SHOULD support a one-to-many relationship from build -artifacts to attestations to ensure that anyone is free to produce and publish -any attestation they might need. However, while there are lots of possible -attestations that can have a relationship to a given artifact, in this context -SLSA is primarily concerned with build attestations, i.e. provenance, and as -such, this specification only considers build attestations, produced by the -same maintainers as the artifacts themselves. - -By providing provenance alongside an artifact in the manner specified by a -given ecosystem, maintainers are considered to be 'elevating' these build -attestations above all other possible attestations that could be provided by -third parties for a given artifact. The ultimate goal is for maintainers to -provide the provenance necessary for a repository to be able to verify some -potential policy that requires a certain SLSA level for publication, not -support the publication of arbitrary attestations by third parties. - -As a result, this provenance SHOULD accompany the artifact at publish time, and -package ecosystems SHOULD provide a way to map a given artifact to its -corresponding attestations. The mappings can be either implicit (e.g. require a -custom filename schema that uniquely identifies the provenance over other -attestation types) or explicit (e.g. it could happen as a de-facto standard -based on where the attestation is published). - -The provenance SHOULD have a filename that is directly related to the build -artifact filename. For example, for an artifact `.`, the -attestation is `.attestation` or some similar extension (for example -[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`.) - -## Where attestations are published - -There are a number of opportunities and venues to publish attestations during -and after the build process. Producers MUST publish attestations in at least -one place, and SHOULD publish attestations in more than one place: - -- **Publish attestations alongside the source repository releases**: If the - source repository hosting provider offers an artifact "release" feature, - such as [GitHub - releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), - producers SHOULD include provenance as part of such releases. This option - has the benefit of requiring no changes to the package registry to support - provenance formats, but has the disadvantage of putting the source - repository hosting providing in the critical path for installers that want to - verify policy at build-time. -- **Publish attestations alongside the artifact in the package registry**: - Many software repositories already support some variety of publishing 1:1 - related files alongside an artifact, sometimes known as “sidecar files”. - For example, PyPI supports publishing `.asc` files representing the PGP - signature for an artifact with the same filename (but different extension). - This option requires the mapping between artifact and attestation (or - attestation vessel) to be 1:1. -- **Publish attestations elsewhere, record their existence in a transparency - log**: Once an attestation has been generated and published for a build, a - hash of the attestation and a pointer to where it is indexed SHOULD be - published to a third-party transparency log that exists outside the source - repository and package registry. Not only are transparency logs such as - [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed - to be immutable, but they typically also make monitoring easier. - Requiring the presence of the attestation in a monitored transparency log - during verification helps ensure the attestation is trustworthy. - -Combining these options gives us a process for bootstrapping SLSA adoption -within an ecosystem, even if the package registry doesn't support publishing -attestations. First, interested projects modify their release process to -produce SLSA provenance. Then, they publish that provenance to their source -repository. Finally, they publish the provenance to the package registry, if -and when the registry supports it. - -Long-term, package registries SHOULD support uploading and distributing -provenance alongside the artifact. This model is preferred for two reasons: - -- trust: clients already trust the package registry as the source of their - artifacts, and don't need to trust an additional service; -- reliability: clients already depend on the package registry as part of - their critical path, so distributing provenance via the registry avoids - adding an additional point of failure. - -Short term, consumers of build artifacts can bootstrap a manual policy by using -the source repository only for projects that publish all artifacts and -attestations to the source repository, and later extend this to all artifacts -published to the package registry via the canonical installation tools once -a given ecosystem supports them. - -## Immutability of attestations - -Attestations SHOULD be immutable. Once an attestation is published as it -corresponds to a given artifact, that attestation is immutable and cannot be -overwritten later with a different attestation that refers to the same -artifact. Instead, a new release (and new artifacts) SHOULD be created. - -## Format of the attestation - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto [SLSA Provenance](/provenance), but -another format MAY be used if both producer and consumer agree and it meets all -the other requirements. - -## Considerations for source-based ecosystems - -Some ecosystems have support for installing directly from source repositories -(an option for Python/`pip`, Go, etc). In these cases, there is no need to -publish or verify provenance because there is no "build" step that translates -between a source repository and an artifact that is being installed. - -However, for ecosystems that install from source repositories _via_ some -intermediary (e.g. [Homebrew installing from GitHub release artifacts generated -from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go -installing through the Go module proxy](https://proxy.golang.org/)), these -ecosystems distribute "source archives" that are not the bit-for-bit identical -form from version control. These intermediaries are transforming the original -source repository in some way that constitutes a "build" and as a result SHOULD -be providing build provenance for this "package", and the recommendations -outlined here apply. - -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.1-rc1/faq.md b/docs/spec/v1.1-rc1/faq.md deleted file mode 100644 index 90ed7bb8c..000000000 --- a/docs/spec/v1.1-rc1/faq.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Frequently asked questions -description: Answers to questions frequently asked about SLSA. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build platforms to -corroborate the provenance of a build. In this way, one can create an overall -platform that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a platform can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. - -## Q. What is the difference between a build platform, system, and service? - -Build platform and build system have been used interchangeably in the past. With -the v1.0 specification, however, there has been a unification around the term -platform as indicated in the [Terminology](terminology.md). The use of the word -`system` still exists related to software and services within the build platform -and to systems outside of a build platform like change management systems. - -A build service is a hosted build platform that is often run on shared infrastructure -instead of individuals' machines and workstations. Its use has also been replaced outside -of the requirements as it relates to the build platform. - -## Q: Is SLSA the same as TACOS? - -No. -[Trusted Attestation and Compliance for Open Source (TACOS)](https://github.com/tacosframework) -is a framework authored by Tidelift. -Per their website, TACOS is a framework -"for assessing the development practices of open source projects -against a set of secure development standards specified by the (US) -NIST Secure Software Development Framework (SSDF) V1.1" which -"vendors can use to provide self-attestation for the open source components -they rely on." - -In contrast, SLSA is a community-developed framework---including -adoptable guidelines for securing a software supply chain and -mechanism to evaluate the trustworthiness of artifacts you consume---that -is part of the Open Source Security Foundation (OpenSSF). - -## Q: How does SLSA and SLSA Provenance relate to SBOM? - -[Software Bill of Materials (SBOM)] are a frequently recommended tool for -increased software supply chain rigor. An SBOM is typically focused on -understanding software in order to evaluate risk through known vulnerabilities -and license compliance. These use-cases require fine-grained and timely data -which can be refined to improve signal-to-noise ratio. - -[SLSA Provenance] and the [Build track] are focused on trustworthiness of the -build process. To improve trustworthiness, Provenance is generated in the build -platform's trusted control plane, which in practice results in it being coarse -grained. For example, in Provenance metadata completeness of -`resolvedDependencies` information is on a best-effort basis. Further, the -`ResourceDescriptor` type does not require version and license information or -even a URI to the dependency's original location. - -While they likely include similar data, SBOMs and SLSA Provenance operate at -different levels of abstraction. The fine-grained data in an SBOM typically -describes the components present in a produced artifact, whereas SLSA -Provenance more coarsely describes parameters of a build which are external to -the build platform. - -The granularity and expressiveness of the two use-cases differs enough that -current SBOM formats were deemed not a good fit for the requirements of -the Build track. Yet SBOMs are a good practice and may form part of a future -SLSA Vulnerabilities track. Further, SLSA Provenance can increase the -trustworthiness of an SBOM by describing how the SBOM was created. - -SLSA Provenance, the wider [in-toto Attestation Framework] in which the -recommended format sits, and the various SBOM standards, are all rapidly -evolving spaces. There is ongoing investigation into linking between the -different formats and exploration of alignment on common models. This FAQ entry -describes our understanding of the intersection efforts today. We do not know -how things will evolve over the coming months and years, but we look forward to -the collaboration and improved software supply chain security. - -## Q: How to SLSA with a self-hosted runner - -Some CI systems allow producers to provide their own self-hosted runners as a build -environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage -these, classifying the SLSA build level for the resulting artifact can be confusing. - -Since the SLSA Build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance, interpretation of the -specification hinges on the platform entities involved in the provenance generation. -The SLSA [build level requirements] (secure key storage, isolation, etc.) should be -imposed on the transitive closure of the systems which are responsible for informing -the provenance generated. - -Some common situations may include: - -- The platform generates the provenance and just calls a runner for individual items. - In this situation, the provenance is only affected by the platform so there would be - no requirements imposed on the runner. -- The runner generates the provenance. In this situation, the orchestrating platform - is irrelevant and all requirements are imposed on the runner. -- The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance. Trust is - shared between the platform and the runner so the requirements are imposed on both. - -Additional requirements on the self-hosted runners may be added to Build levels -greater than L3 when such levels get defined. - -[build level requirements]: requirements.md -[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners -[Software Bill of Materials (SBOM)]: https://ntia.gov/sbom -[SLSA Provenance]: provenance.md -[Build track]: levels.md#build-track -[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/ diff --git a/docs/spec/v1.1-rc1/future-directions.md b/docs/spec/v1.1-rc1/future-directions.md deleted file mode 100644 index 21be81619..000000000 --- a/docs/spec/v1.1-rc1/future-directions.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Future directions -description: The initial draft version (v0.1) of SLSA had a larger scope including protections against tampering with source code and a higher level of build integrity (Build L4). This page collects some early thoughts on how SLSA **might** evolve in future versions to re-introduce these notions and add other additional aspects of automatable supply chain security. ---- - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future versions to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build platform and enabling -corraboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream verifiers - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other build platforms to corroborate the - provenance. - -
- -
- -## Build Platform Operations track - -A Build Platform Operations track could provide assurances around the hardening -of build platforms as they are operated. - -The initial [draft version (v0.1)] of SLSA included a section on -[common requirements](../v0.1/requirements.md#common-requirements) that formed -the foundation of the guidance for -[verifying build systems](verifying-systems.md), which **may or may not** form -the basis for a future Build Platform Operations track: - -- Controls for approval, logging, and auditing of all physical and remote - access to platform infrastructure, cryptographic secrets, and privileged - debugging interfaces. -- Conformance to security best practices to minimize the risk of compromise. -- Protection of cryptographic secrets used by the build platform. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md diff --git a/docs/spec/v1.1-rc1/images/build-model.svg b/docs/spec/v1.1-rc1/images/build-model.svg deleted file mode 100644 index 9d6bed6ca..000000000 --- a/docs/spec/v1.1-rc1/images/build-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1-rc1/images/provenance-model.svg b/docs/spec/v1.1-rc1/images/provenance-model.svg deleted file mode 100644 index 028dad49e..000000000 --- a/docs/spec/v1.1-rc1/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1-rc1/images/supply-chain-model.svg b/docs/spec/v1.1-rc1/images/supply-chain-model.svg deleted file mode 100644 index 6a37ffa05..000000000 --- a/docs/spec/v1.1-rc1/images/supply-chain-model.svg +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1-rc1/images/supply-chain-threats-build-verification.svg b/docs/spec/v1.1-rc1/images/supply-chain-threats-build-verification.svg deleted file mode 100644 index 2888f6215..000000000 --- a/docs/spec/v1.1-rc1/images/supply-chain-threats-build-verification.svg +++ /dev/null @@ -1,88 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1-rc1/images/supply-chain-threats.svg b/docs/spec/v1.1-rc1/images/supply-chain-threats.svg deleted file mode 100644 index 38421111d..000000000 --- a/docs/spec/v1.1-rc1/images/supply-chain-threats.svg +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1-rc1/images/verification-model.svg b/docs/spec/v1.1-rc1/images/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.1-rc1/images/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1-rc1/index.md b/docs/spec/v1.1-rc1/index.md deleted file mode 100644 index b993f9e2a..000000000 --- a/docs/spec/v1.1-rc1/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SLSA specification -description: SLSA is a specification for describing and incrementally improving supply chain security, established by industry consensus. It is organized into a series of levels that describe increasing security guarantees. This is **version 1.1 RC1** of the SLSA specification, which defines the SLSA levels. ---- - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **Version 1.1 Release Candidate 1 (RC1)** of the SLSA -specification, which defines the SLSA levels and recommended attestation -formats, including provenance. This version has been superseded by -[Version 1.0 RC2](../v1.1-rc2/). - -{%- for section in site.data.nav.main %} -{%- if section.url == page.url %} -{%- for subsection in section.children %} -{%- if subsection.children %} - -## {{ subsection.title }} - -{{ subsection.description }} - - - -| Page | Description -| ---- | ----------- -{%- for child in subsection.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} -{%- endfor %} - - -{%- endif %} -{%- endfor %} -{%- endif %} -{%- endfor %} diff --git a/docs/spec/v1.1-rc1/levels.md b/docs/spec/v1.1-rc1/levels.md deleted file mode 100644 index b0e751453..000000000 --- a/docs/spec/v1.1-rc1/levels.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: Security levels -description: SLSA is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This page is a descriptive overview of the SLSA levels and tracks, describing their intent. ---- - -SLSA is organized into a series of levels that provide increasing supply chain -security guarantees. This gives you confidence that software hasn’t been -tampered with and can be securely traced back to its source. - -This page is a descriptive overview of the SLSA levels and tracks, describing -their intent. For the prescriptive requirements for each level, see -[Requirements](requirements.md). For a general overview of SLSA, see -[About SLSA](principles.md). - -## Levels and tracks - -SLSA levels are split into *tracks*. Each track has its own set of levels that -measure a particular aspect of supply chain security. The purpose of tracks is -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 - - - -> 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 -> Build track. A Source track may be added in [future versions]. - -## Build track - -The SLSA build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance. Provenance describes -what entity built the artifact, what process they used, and what the inputs -were. The lowest level only requires the provenance to exist, while higher -levels provide increasing protection against tampering of the build, the -provenance, or the artifact. - -The primary purpose of the build track is to enable [verification] that the -artifact was built as expected. Consumers have some way of knowing what the -expected provenance should look like for a given package and then compare each -package artifact's actual provenance to those expectations. Doing so prevents -several classes of [supply chain threats](threats.md). - -Each ecosystem (for open source) or organization (for closed source) defines -exactly how this is implemented, including: means of defining expectations, what -provenance format is accepted, whether reproducible builds are used, how -provenance is distributed, when verification happens, and what happens on -failure. Guidelines for implementers can be found in the -[requirements](requirements.md). - -
- -### Build L0: No guarantees - -
-
Summary
- -No requirements---L0 represents the lack of SLSA. - -
Intended for
- -Development or test builds of software that are built and run on the same -machine, such as unit tests. - -
Requirements
- -n/a - -
Benefits
- -n/a - -
-
-
- -### Build L1: Provenance exists - -
-
Summary
- -Package has provenance showing how it was built. Can be used to prevent mistakes -but is trivial to bypass or forge. - -
Intended for
- -Projects and organizations wanting to easily and quickly gain some benefits of -SLSA---other than tamper protection---without changing their build workflows. - -
Requirements
- -- Software Producer: - - Follow a consistent build process so that others can form - expectations about what a "correct" build looks like. - - Run builds on a build platform that meets Build L1 requirements. - - Distribute provenance to consumers, preferably using a convention - determined by the package ecosystem. -- Build platform: - - Automatically generate [provenance] describing how the artifact was - built, including: what entity built the package, what build process - they used, and what the top-level input to the build were. - -
Benefits
- -- Makes it easier for both producers and consumers to debug, patch, rebuild, - and/or analyze the software by knowing its precise source version and build - process. - -- With [verification], prevents mistakes during the release process, such as - building from a commit that is not present in the upstream repo. - -- Aids organizations in creating an inventory of software and build platforms - used across a variety of teams. - -
Notes
- -- Provenance may be incomplete and/or unsigned at L1. Higher levels require - more complete and trustworthy provenance. - -
- -
-
- -### Build L2: Hosted build platform - -
-
Summary
- -Forging the provenance or evading verification requires an explicit "attack", -though this may be easy to perform. Deters unsophisticated adversaries or those -who face legal or financial risk. - -In practice, this means that builds run on a hosted platform that generates and -signs[^sign] the provenance. - -
Intended for
- -Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build platform, while waiting for changes to the build -platform itself required by [Build L3]. - -
Requirements
- -All of [Build L1], plus: - -- Software producer: - - Run builds on a [hosted] build platform that meets Build L2 - requirements. -- Build platform: - - Generate and sign[^sign] the provenance itself. This may be done - during the original build, an after-the-fact reproducible build, or - some equivalent system that ensures the trustworthiness of the - provenance. -- Consumer: - - Validate the authenticity of the provenance. - -
Benefits
- -All of [Build L1], plus: - -- Prevents tampering after the build through digital signatures[^sign]. - -- Deters adversaries who face legal or financial risk by evading security - controls, such as employees who face risk of getting fired. - -- Reduces attack surface by limiting builds to specific build platforms that - can be audited and hardened. - -- Allows large-scale migration of teams to supported build platforms early - while further hardening work ([Build L3]) is done in parallel. - -
-
-
- -[^sign]: Alternate means of verifying the authenticity of the provenance are - also acceptable. - -### Build L3: Hardened builds - -
-
Summary
- -Forging the provenance or evading verification requires exploiting a -vulnerability that is beyond the capabilities of most adversaries. - -In practice, this means that builds run on a hardened build platform that offers -strong tamper protection. - -
Intended for
- -Most software releases. Build L3 usually requires significant changes to -existing build platforms. - -
Requirements
- -All of [Build L2], plus: - -- Software producer: - - Run builds on a hosted build platform that meets Build L3 - requirements. -- Build platform: - - Implement strong controls to: - - prevent runs from influencing one another, even within the same - project. - - prevent secret material used to sign the provenance from being - accessible to the user-defined build steps. - -
Benefits
- -All of [Build L2], plus: - -- Prevents tampering during the build---by insider threats, compromised - credentials, or other tenants. - -- Greatly reduces the impact of compromised package upload credentials by - requiring attacker to perform a difficult exploit of the build process. - -- Provides strong confidence that the package was built from the official - source and build process. - -
-
- - - -[build l0]: #build-l0 -[build l1]: #build-l1 -[build l2]: #build-l2 -[build l3]: #build-l3 -[future versions]: future-directions.md -[hosted]: requirements.md#isolation-strength -[previous version]: ../v0.1/levels.md -[provenance]: terminology.md -[verification]: verifying-artifacts.md diff --git a/docs/spec/v1.1-rc1/onepage.md b/docs/spec/v1.1-rc1/onepage.md deleted file mode 100644 index 697bdd029..000000000 --- a/docs/spec/v1.1-rc1/onepage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SLSA specification -description: A one-page rendering of all that is included in SLSA v1.1 RC1. -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.1-rc1/" %} -{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,terminology,levels,requirements,distributing-provenance,verifying-artifacts,verifying-systems,threats,attestation-model,provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.1-rc1/principles.md b/docs/spec/v1.1-rc1/principles.md deleted file mode 100644 index d82fcc319..000000000 --- a/docs/spec/v1.1-rc1/principles.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Guiding principles -description: An introduction to the guiding principles behind SLSA's design decisions. ---- - -This page is an introduction to the guiding principles behind SLSA's design -decisions. - -## Simple levels with clear outcomes - -Use [levels](levels) to communicate security state and to encourage a large -population to improve its security stance over time. When necessary, split -levels into separate tracks to recognize progress in unrelated security areas. - -**Reasoning:** Levels simplify how to think about security by boiling a complex -topic into an easy-to-understand number. It is clear that level N is better than -level N-1, even to someone with passing familiarity. This provides a convenient -way to describe current security state as well as a natural path to improvement. - -Guidelines: - -- **Define levels in terms of concrete security outcomes.** Each level should - have clear and meaningful security value, such as stopping a particular - class of threats. Levels should represent security milestones, not just - incremental progress. Give each level an easy-to-remember mnemonic, such as - "Provenance exists". - -- **Balance level granularity.** Too many levels makes SLSA hard to understand - and remember; too few makes each level hard to achieve. Collapse levels - until each step requires a non-trivial but manageable amount of work to - implement. Separate levels if they require significant work from multiple - distinct parties, such as infrastructure work plus user behavior changes, so - long as the intermediate level still has some security value (prior bullet). - -- **Use tracks sparingly.** Additional tracks add extra complexity to SLSA, so - a new track should be seen as a last resort. Each track should have a clear, - distinct purpose with a crisply defined objective, such as trustworthy - provenance for the [Build track](levels#build-track). As a rule of thumb, a - new track may be warranted if it addresses threats unrelated to another - track. Try to avoid tracks that sound confusingly similar in either name or - objective. - -## Trust platforms, verify artifacts - -Establish trust in a small number of platforms and systems---such as change management, build, -and packaging platforms---and then automatically verify the many artifacts -produced by those platforms. - -**Reasoning**: Trusted computing bases are unavoidable---there's no choice but -to trust some platforms. Hardening and verifying platforms is difficult and -expensive manual work, and each trusted platform expands the attack surface of the -supply chain. Verifying that an artifact is produced by a trusted platform, -though, is easy to automate. - -To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited -numbers of platforms and then automate verification of the artifacts produced by those platforms. -The attack surface and work to establish trust does not scale with the number of artifacts produced, -as happens when artifacts each use a different trusted platform. - -**Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant -amount of central work. - -### Example - -A security engineer analyzes the architecture and implementation of a build -platform to ensure that it meets the SLSA Build Track requirements. Following the -analysis, the public keys used by the build platform to sign provenance are -"trusted" up to the given SLSA level. Downstream platforms verify the provenance -signed by the public key to automatically determine that an artifact meets the -SLSA level. - -### Corollary: Minimize the number of trusted platforms - -A corollary to this principle is to minimize the size of the trusted computing -base. Every platform we trust adds attack surface and increases the need for -manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team within an organization maintaining their own build platform, use a - shared build platform. Hardening work can be shared across all teams. -- Remove the need to trust components. For example, use end-to-end signing - to avoid the need to trust intermediate distribution platforms. - -## Trust code, not individuals - -Securely trace all software back to source code rather than trust individuals who have write access to package registries. - -**Reasoning**: Code is static and analyzable. People, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. - -**Benefits**: Removes the possibility for a trusted individual---or an -attacker abusing compromised credentials---to tamper with source code -after it has been committed. - -## Prefer attestations over inferences - -Require explicit attestations about an artifact's provenance; do not infer -security properties from a platform's configurations. - -**Reasoning**: Theoretically, access control can be configured so that the only path from -source to release is through the official channels: the CI/CD platform pulls only -from the proper source, package registry allows access only to the CI/CD platform, -and so on. We might infer that we can trust artifacts produced by these platforms -based on the platform's configuration. - -In practice, though, these configurations are almost impossible to get right and -keep right. There are often over-provisioning, confused deputy problems, or -mistakes. Even if a platform is configured properly at one moment, it might not -stay that way, and humans almost always end up getting in the access control -lists. - -Access control is still important, but SLSA goes further to provide defense in depth: it **requires proof in -the form of attestations that the package was built correctly**. - -**Benefits**: The attestation removes intermediate platforms from the trust base and ensures that -individuals who are accidentally granted access do not have sufficient permission to tamper with the package. diff --git a/docs/spec/v1.1-rc1/provenance.md b/docs/spec/v1.1-rc1/provenance.md deleted file mode 100644 index bccb8e863..000000000 --- a/docs/spec/v1.1-rc1/provenance.md +++ /dev/null @@ -1,599 +0,0 @@ ---- -title: Provenance -description: Description of SLSA provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](requirements#provenance-generation). - -## Model - -Provenance is an attestation that a particular build platform produced a set of -software artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant build platform. - The `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build platforms.) - - - The build platform implementer SHOULD define a security model for the build - platform in order to clearly identify the platform's boundaries, actors, - and interfaces. This model SHOULD then be used to identify the transitive - closure of the trusted build platform for the `builder.id` as well as the - trusted control plane. - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - platform ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `internalParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](requirements.md). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." - Such changes do not update the `predicateType`. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -### Summary - -*NOTE: This summary (in cue) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -*NOTE: This summary (in protobuf) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - -Link: [provenance.proto](schema/provenance.proto) - -*NOTE: This protobuf definition prioritises being a human-readable summary -of the schema for readers of the specification. A version of the protobuf -definition useful for code generation is maintained in the -[in-toto attestation] repository.* - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`internalParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that -that there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build platform SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
internalParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build platform is already trusted, and in many cases it is -not practical to do so. - -
resolvedDependencies -array (ResourceDescriptor) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script -fetches and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be -listed here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `internalParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `internalParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build platform. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build platform to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build platform to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the build platform that executed the invocation, which is trusted to -have correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ResourceDescriptor) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or -incident response. For example, this might reference logs generated during -the build and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted build platform. This is -[intended](verifying-artifacts#step-1-check-slsa-build-level) -to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -The `builder.id` URI SHOULD resolve to documentation explaining: - -- The scope of what this ID represents. -- The claimed SLSA Build level. -- The accuracy and completeness guarantees of the fields in the provenance. -- Any fields that are generated by the tenant-controlled build process and not - verified by the trusted control plane, except for the `subject`. -- The interpretation of any extension fields. - -
builderDependencies -array (ResourceDescriptor) - -Dependencies used by the orchestrator that are not run within the workload -and that do not affect the build, but might affect the provenance generation -or security guarantees. - -
version -map (string→string) - -Map of names of components of the build platform to their version. - -
- -The build platform, or builder for short, represents the transitive -closure of all the entities that are, by necessity, [trusted] to faithfully run -the build and record the provenance. This includes not only the software but the -hardware and people involved in running the service. For example, a particular -instance of [Tekton](https://tekton.dev/) could be a build platform, while -Tekton itself is not. For more info, see [Build -model](terminology#build-model). - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -### Extension fields - -[Extension fields]: #extension-fields - -Implementations MAY add extension fields to any JSON object to describe -information that is not captured in a standard field. Guidelines: - -- Extension fields SHOULD use names of the form `_`, e.g. - `examplebuilder_isCodeReviewed`. This practice avoids field name collisions - by namespacing each vendor. Non-extension field names never contain an - underscore. -- Extension fields MUST NOT alter the meaning of any other field. In other - words, an attestation with an absent extension field MUST be interpreted - identically to an attestation with an unrecognized (and thus ignored) - extension field. -- Extension fields SHOULD follow the [monotonic principle][parsing rules], - meaning that deleting or ignoring the extension SHOULD NOT turn a DENY - decision into an ALLOW. - -## Verification - -[Verification]: verifying-artifacts - -Please see [Verifying Artifacts][Verification] for a detailed discussion of -provenance verification. - -## Index of build types - -The following is a partial index of build type definitions. Each contains a -complete example predicate. - - - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) -- [Google Cloud Build (community-maintained)](https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1) - -To add an entry here, please send a pull request on GitHub. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "internalParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "builderDependencies": null, // not in v0.2 - "version": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.0 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build platforms, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed: - - `parameters` -> `externalParameters` (slight change in semantics) - - `environment` -> `internalParameters` (slight change in semantics) - - `materials` -> `resolvedDependencies` (slight change in semantics) - - `buildInvocationId` -> `invocationId` - - `buildStartedOn` -> `startedOn` - - `buildFinishedOn` -> `finishedOn` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - ResourceDescriptor: `annotations`, `content`, `downloadLocation`, - `mediaType`, `name` - - Builder: `builderDependencies` and `version` - - `byproducts` -- Changed naming convention for extension fields. - -Differences from RC1 and RC2: - -- Renamed `systemParameters` (RC1 + RC2) -> `internalParameters` (final). -- Changed naming convention for extension fields (in RC2). -- Renamed `localName` (RC1) -> `name` (RC2). -- Added `annotations` and `content` (in RC2). - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: threats -[trusted]: principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.1-rc1/requirements.md b/docs/spec/v1.1-rc1/requirements.md deleted file mode 100644 index c0a72d931..000000000 --- a/docs/spec/v1.1-rc1/requirements.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -title: Producing artifacts -description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers. ---- - - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is platform implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Levels](levels.md). For background, see [Terminology](terminology.md). To -better understand the reasoning behind the requirements, see -[Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -In order to produce artifacts with a specific build level, responsibility is -split between the [Producer] and [Build platform]. The build platform MUST -strengthen the security controls in order to achieve a specific level while the -producer MUST choose and adopt a build platform capable of achieving a desired -build level, implementing any controls as specified by the chosen platform. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build platform - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build platform - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Unforgeable - ✓ -
Isolation strength - Hosted - ✓✓ -
Isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure platform is beyond the -scope of this specification, all implementations MUST use industry security -best practices to be conformant to this specification. This includes, but is -not limited to, using proper access controls, securing communications, -implementing proper management of cryptographic secrets, doing frequent updates, -and promptly fixing known vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -NOTE: There were more requirements for producers in the initial -[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted -how a package can be built. These were removed in the v1.0 specification and -will be reassessed and re-added as indicated in the -[future directions](future-directions.md). - -### Choose an appropriate build platform - -The producer MUST select a build platform that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -If a producer wishes to distribute their artifact through a [package ecosystem] -that requires explicit metadata about the build process in the form of a -configuration file, the producer MUST complete the configuration file and keep -it up to date. This metadata might include information related to the artifact's -source repository and build parameters. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the -[package ecosystem], provided that the package ecosystem is capable of -distributing provenance. - -## Build Platform - -[Build platform]: #build-platform - -A package's build platform is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build platform is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build platform used -by a single software project, or even an individual's workstation. Ideally, one -build platform is used by many different software packages so that consumers can -[minimize the number of trusted platforms](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build platform is responsible for providing two things: [provenance -generation] and [isolation between builds]. The [Build level](levels.md#build-track) describes -the degree to which each of these properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build platform is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the overall provenance integrity according to -minimum requirements on its: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package by cryptographic digest and describes how that package was -produced. The format MUST be acceptable to the [package ecosystem] and/or -[consumer](verifying-artifacts.md#consumer). - -It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. - -If using an alternate format, it MUST contain the equivalent information as SLSA -Provenance at each level and SHOULD be bi-directionally translatable to SLSA -Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build platform and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only -to the build platform component that generated the provenance attestation. - -While many constraints affect choice of signing methodologies, it is -RECOMMENDED that build platforms use signing methodologies which improve the -ability to detect and remediate key compromise, such as methods which rely on -transparency logs or, when transparency isn't appropriate, time stamping -services. - -Authenticity allows the consumer to trust the contents of the provenance -attestation, such as the identity of the build platform. - -*Accuracy:* The provenance MUST be generated by the control plane (i.e. within -the trust boundary [identified in the provenance]) and not by a tenant of the -build platform (i.e. outside the trust boundary), except as noted below. - -- The data in the provenance MUST be obtained from the build platform, either - because the generator *is* the build platform or because the provenance - generator reads the data directly from the build platform. -- The build platform MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. -- Exceptions for fields that MAY be generated by a tenant of the build platform: - - The names and cryptographic digests of the output artifacts, i.e. - `subject` in [SLSA Provenance]. See [forge output digest of the - provenance](threats#forged-digest) for explanation of why this is - acceptable. - - Any field that is not marked as REQUIRED for Build L2. For example, - `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at - Build L2. Builders SHOULD document any such cases of tenant-generated - fields. - -*Completeness:* SHOULD be complete. - -- There MAY be [external parameters] that are not sufficiently captured in - the provenance. -- Completeness of resolved dependencies is best effort. - - ✓✓ -
Provenance is Unforgeable - -*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. - -- Any secret material used for authenticating the provenance, for example the - signing key used to generate a digital signature, MUST be stored in a secure - management system appropriate for such material and accessible only to the - build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - platform in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted in [Provenance - is Authentic](#provenance-authentic). (Build L3 does not require additional - fields beyond those of L2.) - -*Completeness:* SHOULD be complete. - -- [External parameters] MUST be fully enumerated. -- Completeness of resolved dependencies is best effort. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build platform is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build platform's isolation strength, see -[Verifying build platforms](verifying-systems.md). - - - - -
RequirementDescriptionL1L2L3 - -
Hosted - - -All build steps ran using a hosted build platform on shared or dedicated -infrastructure, not on an individual's workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Isolated - - -The build platform ensured that the build steps ran in an isolated environment, -free of unintended external influence. In other words, any external influence on -the build was specifically requested by the build itself. This MUST hold true -even between builds within the same tenant project. - -The build platform MUST guarantee the following: - -- It MUST NOT be possible for a build to access any secrets of the build - platform, such as the provenance signing key, because doing so would - compromise the authenticity of the provenance. -- It MUST NOT be possible for two builds that overlap in time to influence one - another, such as by altering the memory of a different build process running - on the same machine. -- It MUST NOT be possible for one build to persist or influence the build - environment of a subsequent build. In other words, an ephemeral build - environment MUST be provisioned for each build. -- It MUST NOT be possible for one build to inject false entries into a build - cache used by another build, also known as "cache poisoning". In other - words, the output of the build MUST be identical whether or not the cache is - used. -- The build platform MUST NOT open services that allow for remote influence - unless all such interactions are captured as `externalParameters` in the - provenance. - -There are no sub-requirements on the build itself. Build L3 is limited to -ensuring that a well-intentioned build runs securely. It does not require that -a build platform prevents a producer from performing a risky or insecure build. In -particular, the "Isolated" requirement does not prohibit a build from calling -out to a remote execution service or a "self-hosted runner" that is outside the -trust boundary of the build platform. - -NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" -in the initial [draft version (v0.1)](../v0.1/requirements.md). - -NOTE: This requirement is not to be confused with "Hermetic", which roughly -means that the build ran with no network access. Such a requirement requires -substantial changes to both the build platform and each individual build, and is -considered in the [future directions](future-directions.md). - - ✓ -
- -[external parameters]: provenance.md#externalParameters -[identified in the provenance]: provenance.md#model -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.1-rc1/schema/provenance.cue b/docs/spec/v1.1-rc1/schema/provenance.cue deleted file mode 100644 index 22bc5e0d8..000000000 --- a/docs/spec/v1.1-rc1/schema/provenance.cue +++ /dev/null @@ -1,48 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "internalParameters": object, - "resolvedDependencies": [ ...#ResourceDescriptor ], - }, - "runDetails": { - "builder": { - "id": string, - "builderDependencies": [ ...#ResourceDescriptor ], - "version": { ...string }, - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ResourceDescriptor ], - } - } -} - -#ResourceDescriptor: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "gitCommit": string, - [string]: string, - }, - "name": string, - "downloadLocation": string, - "mediaType": string, - "content": bytes, // base64-encoded - "annotations": { - [string]: _ // any JSON type - } -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.1-rc1/schema/provenance.proto b/docs/spec/v1.1-rc1/schema/provenance.proto deleted file mode 100644 index ae0a71ee1..000000000 --- a/docs/spec/v1.1-rc1/schema/provenance.proto +++ /dev/null @@ -1,50 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct internal_parameters = 3; - repeated ResourceDescriptor resolved_dependencies = 4; -} - -message ResourceDescriptor { - string uri = 1; - map digest = 2; - string name = 3; - string download_location = 4; - string media_type = 5; - bytes content = 6; - map annotations = 7; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ResourceDescriptor byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ResourceDescriptor builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.1-rc1/terminology.md b/docs/spec/v1.1-rc1/terminology.md deleted file mode 100644 index 95c5678e1..000000000 --- a/docs/spec/v1.1-rc1/terminology.md +++ /dev/null @@ -1,341 +0,0 @@ ---- -title: Terminology -description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting. ---- - - -Before diving into the [SLSA Levels](levels.md), we need to establish a core set -of terminology and models to describe what we're protecting. - -## Software supply chain - -**TODO:** Update the text to match the new diagram. - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). - -[build]: #build-model -[package]: #package-model -[SLSA Provenance]: /provenance/v1 - -### Roles - -Throughout the specification, you will see reference to the following roles -that take part in the software supply chain. Note that in practice a role may -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. - -### Build model - -

Model Build

- -We model a build as running on a multi-tenant *build platform*, where each -execution is independent. - -1. A tenant invokes the build by specifying *external parameters* through an - *interface*, either directly or via some trigger. Usually, at least one of - these external parameters is a reference to a *dependency*. (External - parameters are literal values while dependencies are artifacts.) -2. The build platform's *control plane* interprets these external parameters, - fetches an initial set of dependencies, initializes a *build environment*, - and then starts the execution within that environment. -3. The build then performs arbitrary steps, which might include fetching - additional dependencies, and then produces one or more *output* artifacts. - The steps within the build environment are under the tenant's control. - The build platform isolates build environments from one another to some - degree (which is measured by the SLSA Build Level). -4. Finally, for SLSA Build L2+, the control plane outputs *provenance* - describing this whole process. - -Notably, there is no formal notion of "source" in the build model, just external -parameters and dependencies. Most build platforms have an explicit "source" -artifact to build from, which is often a git repository; in the build model, the -reference to this artifact is an external parameter while the artifact itself is -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. - -
Ambiguous terms to avoid - -- *Build recipe:* Could mean *external parameters,* but may include concrete - steps of how to perform a build. To avoid implementation details, we don't - define this term, but always use "external parameters" which is the - interface to a build platform. Similar terms are *build configuration - source* and *build definition*. -- *Builder:* Usually means *build platform*, but might be used for *build - environment*, the user who invoked the build, or a build tool from - *dependencies*. To avoid confusion, we always use "build platform". The only - exception is in the [provenance](/provenance/v1), where `builder` is used as - a more concise field name. - -
- -### Package model - -Software is distributed in identifiable units called packages -according to the rules and conventions of a package ecosystem. -Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and -[OCI](https://github.com/opencontainers/distribution-spec), while examples of -informal ecosystems include links to files on a website or distribution of -first-party software within a company. - -Abstractly, a consumer locates software within an ecosystem by asking a -package registry to resolve a mutable package name into an -immutable package artifact.[^label] To publish a package -artifact, the software producer asks the registry to update this mapping to -resolve to the new artifact. The registry represents the entity or entities with -the power to alter what artifacts are accepted by consumers for a given package -name. For example, if consumers only accept packages signed by a particular -public key, then it is access to that public key that serves as the registry. - -The package name is the primary security boundary within a package ecosystem. -Different package names represent materially different pieces of -software---different owners, behaviors, security properties, and so on. -Therefore, **the package name is the primary unit being protected in SLSA**. -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. - -

Ambiguous terms to avoid - -- *Package repository:* Could mean either package registry or package name, - depending on the ecosystem. To avoid confusion, we always use "repository" - exclusively to mean "source repository", where there is no ambiguity. -- *Package manager* (without "client"): Could mean either package ecosystem, - package registry, or client-side tooling. - -
- -### Mapping to real-world ecosystems - -Most real-world ecosystems fit the package model above but use different terms. -The table below attempts to document how various ecosystems map to the SLSA -Package model. There are likely mistakes and omissions; corrections and -additions are welcome! - - - - - - - - - - - - - - - - - - - - - - - - - - -
Package ecosystem - Package registry - Package name - Package artifact -
Languages -
Cargo (Rust) - Registry - Crate name - Artifact -
CPAN (Perl) - PAUSE - Distribution - Release (or Distribution) -
Go - Module proxy - Module path - Module -
Maven (Java) - Repository - Group ID + Artifact ID - Artifact -
npm (JavaScript) - Registry - Package Name - Package -
NuGet (C#) - Host - Project - Package -
PyPA (Python) - Index - Project Name - Distribution -
Operating systems -
Dpkg (e.g. Debian) - ? - Package name - Package -
Flatpak - Repository - Application - Bundle -
Homebrew (e.g. Mac) - Repository (Tap) - Package name (Formula) - Binary package (Bottle) -
Pacman (e.g. Arch) - Repository - Package name - Package -
RPM (e.g. Red Hat) - Repository - Package name - Package -
Nix (e.g. NixOS) - Repository (e.g. Nixpkgs) or binary cache - Derivation name - Derivation or store object -
Storage systems -
GCS - n/a - Object name - Object -
OCI/Docker - Registry - Repository - Object -
Meta -
deps.dev: System - Packaging authority - Package - n/a -
purl: type - Namespace - Name - n/a -
- -Notes: - -- Go uses a significantly different distribution model than other ecosystems. - In go, the package name is a source repository URL. While clients can fetch - directly from that URL---in which case there is no "package" or - "registry"---they usually fetch a zip file from a *module proxy*. The module - proxy acts as both a builder (by constructing the package artifact from - source) and a registry (by mapping package name to package artifact). People - trust the module proxy because builds are independently reproducible and a - *checksum database* guarantees that all clients receive the same artifact - for a given URL. - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build platform is -certified to ensure conformance with the requirements at the level claimed by -the build platform. This certification should happen on a recurring cadence with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer defined -expectations of where the package source code was retrieved from and on what -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. - -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. - -
- -
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. - -
diff --git a/docs/spec/v1.1-rc1/threats-overview.md b/docs/spec/v1.1-rc1/threats-overview.md deleted file mode 100644 index 1245cd975..000000000 --- a/docs/spec/v1.1-rc1/threats-overview.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Supply chain threats -description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA could help. ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA could help. For a more technical discussion, see [Threats & mitigations](threats.md). - -## Summary - -![Supply Chain Threats](images/supply-chain-threats.svg) - -**Note that SLSA does not currently address all of the threats presented here.** -See [Threats & mitigations](threats.md) for what is currently addressed and -[Terminology](terminology.md) for an explanation of the supply chain model. - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that all changes to the source code reflect the -intent of the software producer. Intent of an organization is difficult to -define, so SLSA is expected to approximate this as approval from two authorized -representatives. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - -
-Integrity threat -Known example -How SLSA could help -
A -Submit unauthorized change (to source repo) -SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. -Two-person review could have caught the unauthorized change. -
B -Compromise source repo -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code platform would have been a much harder target for the attackers. -
C -Build from modified source (not matching source repo) -Webmin: Attacker modified the build infrastructure to use source files not matching source control. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
D -Use compromised dependency (i.e. A-H, recursively) -event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code. -Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source. -
E -Compromise build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA levels require stronger security controls for the build platform, making it more difficult to compromise and gain persistence. -
F -Upload modified package (not matching build process) -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Compromise package registry -Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Use compromised package -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
- - - - - - -
-Availability threat -Known example -How SLSA could help -
D -Dependency becomes unavailable -Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. diff --git a/docs/spec/v1.1-rc1/threats.md b/docs/spec/v1.1-rc1/threats.md deleted file mode 100644 index 807445dce..000000000 --- a/docs/spec/v1.1-rc1/threats.md +++ /dev/null @@ -1,932 +0,0 @@ ---- -title: Threats & mitigations -description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. ---- - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations in SLSA. For an introduction to the -supply chain threats that SLSA is aiming to protect against, see [Supply chain threats]. - -The examples on this page are meant to: - -- Explain the reasons for each of the SLSA [requirements](requirements.md). -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](levels.md) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - -**TODO:** Update the ordering to match the diagram. We're currently in the -middle of refactoring, with a jumble of new and old. - -**TODO:** Expand this threat model to also cover "unknowns". Not sure if that is -a "threat" or a "risk". Example: If libFoo is compromised, how do you know if -you are compromised? At a first level, if you don't even know whether you -include libFoo or not, that's a big risk. But even then, it might be that you -don't use libFoo in a way that makes your product vulnerable. We should capture -that somehow. This isn't specific to dependencies - it applies to the entire -diagram. -([discussion](https://github.com/slsa-framework/slsa/pull/1046/files/ebf34a8f9e874b219f152bad62673eae0b3ba2c3#r1585440922)) - -**TODO:** Revisit and possibly update any item that says "out of scope", since -we want to really expand SLSA's scope to include all of these threats. A more -nuanced answer would be that the current version does not define a specific -mitigation, but it's in scope for the project overall. We can also list specific -mitigations even if they're not listed as a level requirement. - -
- -## Overview - -![Supply Chain Threats](images/supply-chain-threats.svg) - -This threat model covers the *software supply chain*, meaning the process by -which software is produced and consumed. We describe and cluster threats based -on where in the software development pipeline those threats occur, labeled (A) -through (I). This is useful because priorities and mitigations mostly cluster -along those same lines. Keep in mind that dependencies are -[highly recursive](#dependency-threats), so each dependency has its own threats -(A) through (I), and the same for *their* dependencies, and so on. For a more -detailed explanation of the supply chain model, see -[Terminology](terminology.md). - -Importantly, producers and consumers face *aggregate* risk across all of the -software they produce and consume, respectively. Many organizations produce -and/or consume thousands of software packages, both first- and third-party, and -it is not practical to rely on every individual team in the organization to do -the right thing. For this reason, SLSA prioritizes mitigations that can be -broadly adopted in an automated fashion, minimizing the chance of mistakes. - -## Source threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes the threat of an authorized individual introducing an unauthorized -change---in other words, an insider threat. - -SLSA v1.0 does not address source threats, but we anticipate doing so in a -[future version](current-activities.md#source-track). In the meantime, the -threats and potential mitigations listed here show how SLSA v1.0 can fit into a -broader supply chain security program. - -### (A) Producer - -The producer of the software intentionally produces code that harms the -consumer, or the producer otherwise uses practices that are not deserving of the -consumer's trust. - -Threats in this category likely *cannot* be mitigated through controls placed -during the authoring/reviewing process, in contrast with (B). - -**TODO:** The difference between (A) and (B) is still a bit fuzzy, which would -be nice to resolve. For example, compromised developer credentials - is that (A) -or (B)? - -
Software producer intentionally submits bad code - -*Threat:* Software producer intentionally submits "bad" code, following all -proper processes. - -*Mitigation:* **TODO** - -*Example:* A popular extension author sells the rights to a new owner, who then -modifies the code to secretly mine cryptocurrency at the users' expense. SLSA -does not protect against this, though if the extension were open source, regular -auditing may discourage this from happening. - -
- -**TODO:** More producer threats? Perhaps the attack to xz where a malicious -contributor gained enhanced privileges through social engineering? - -### (B) Authoring & reviewing - -An adversary introduces a change through the official source control management -interface without any special administrator privileges. - -Threats in this category *can* be mitigated by code review or some other -controls during the authoring/reviewing process, at least in theory. Contrast -this with (A), where such controls are likely ineffective. - -#### (B1) Submit change without review - -
Directly submit without review - -*Threat:* Submit bad code to the source repository without another person -reviewing. - -*Mitigation:* Source repository requires two-person approval for all changes. - -*Example:* Adversary directly pushes a change to a GitHub repo's `main` branch. -Solution: Configure GitHub's "branch protection" feature to require pull request -reviews on the `main` branch. - -
-
Review own change through a sock puppet account - -*Threat:* Propose a change using one account and then approve it using another -account. - -*Mitigation:* Source repository requires approval from two different, trusted -persons. If the proposer is trusted, only one approval is needed; otherwise two -approvals are needed. The software producer maps accounts to trusted persons. - -*Example:* Adversary creates a pull request using a secondary account and then -approves and merges the pull request using their primary account. Solution: -Configure branch protection to require two approvals and ensure that all -repository contributors and owners map to unique persons. - -
-
Use a robot account to submit change - -*Threat:* Exploit a robot account that has the ability to submit changes without -two-person review. - -*Mitigation:* All changes require two-person review, even changes authored by -robots. - -*Example:* A file within the source repository is automatically generated by a -robot, which is allowed to submit without review. Adversary compromises the -robot and submits a malicious change without review. Solution: Require human -review for these changes. - -> TODO([#196](https://github.com/slsa-framework/slsa/issues/196)) This solution -> may not be practical. Should there be an exception for locked down robot -> accounts? - -
-
Abuse review exceptions - -*Threat:* Exploit a review exception to submit a bad change without review. - -*Mitigation:* All changes require two-person review without exception. - -*Example:* Source repository requires two-person review on all changes except -for "documentation changes," defined as only touching files ending with `.md` or -`.html`. Adversary submits a malicious executable named `evil.md` without review -using this exception, and then builds a malicious package containing this -executable. This would pass the policy because the source repository is correct, -and the source repository does require two-person review. Solution: Do not allow -such exceptions. - -> TODO This solution may not be practical in all circumstances. Are there any -> valid exceptions? If so, how do we ensure they cannot be exploited? - -
- -#### (B2) Evade code review requirements - -
Modify code after review - -*Threat:* Modify the code after it has been reviewed but before submission. - -*Mitigation:* Source control platform invalidates approvals whenever the -proposed change is modified. - -*Example:* Source repository requires two-person review on all changes. -Adversary sends a "good" pull request to a peer, who approves it. Adversary then -modifies it to contain "bad" code before submitting. Solution: Configure branch -protection to dismiss stale approvals when new changes are pushed. - -> Note: This is not currently a SLSA requirement because the productivity hit is -> considered too great to outweigh the security benefit. The cost of code review -> is already too high for most projects, given current code review tooling, so -> making code review even costlier would not further our goals. However, this -> should be considered for future SLSA revisions once the state-of-the-art for -> code review has improved and the cost can be minimized. - -
-
Submit a change that is unreviewable - -*Threat:* Send a change that is meaningless for a human to review that looks -benign but is actually malicious. - -*Mitigation:* Code review system ensures that all reviews are informed and -meaningful. - -*Example:* A proposed change updates a file, but the reviewer is only presented -with a diff of the cryptographic hash, not of the file contents. Thus, the -reviewer does not have enough context to provide a meaningful review. Solution: -the code review system should present the reviewer with a content diff or some -other information to make an informed decision. - -
-
Copy a reviewed change to another context - -*Threat:* Get a change reviewed in one context and then transfer it to a -different context. - -*Mitigation:* Approvals are context-specific. - -*Example:* MyPackage's source repository requires two-person review. Adversary -forks the repo, submits a change in the fork with review from a colluding -colleague (who is not trusted by MyPackage), then merges the change back into -the upstream repo. Solution: The merge should still require review, even though -the fork was reviewed. - -
-
Compromise another account - -*Threat:* Compromise one or more trusted accounts and use those to submit and -review own changes. - -*Mitigation:* Source control platform verifies two-factor authentication, which -increases the difficulty of compromising accounts. - -*Example:* Trusted person uses a weak password on GitHub. Adversary guesses the -weak password, logs in, and pushes changes to a GitHub repo. Solution: Configure -GitHub organization to requires 2FA for all trusted persons. This would increase -the difficulty of using the compromised password to log in to GitHub. - -
-
Hide bad change behind good one - -*Threat:* Request review for a series of two commits, X and Y, where X is bad -and Y is good. Reviewer thinks they are approving only the final Y state whereas -they are also implicitly approving X. - -*Mitigation:* Only the version that is actually reviewed is the one that is -approved. Any intermediate revisions don't count as being reviewed. - -*Example:* Adversary sends a pull request containing malicious commit X and -benign commit Y that undoes X. In the pull request UI, reviewer only reviews and -approves "changes from all commits", which is a delta from HEAD to Y; they don't -see X. Adversary then builds from the malicious revision X. Solution: Policy -does not accept this because the version X is not considered reviewed. - -> TODO This is implicit but not clearly spelled out in the requirements. We -> should consider clarifying if there is confusion or incorrect implementations. - -
- -#### (B3) Render code review ineffective - -
Collude with another trusted person - -*Threat:* Two trusted persons collude to author and approve a bad change. - -*Mitigation:* **Outside the scope of SLSA.** We use "two trusted persons" as a -proxy for "intent of the software producer". - -
-
Trick reviewer into approving bad code - -*Threat:* Construct a change that looks benign but is actually malicious, a.k.a. -"bugdoor." - -*Mitigation:* **Outside the scope of SLSA.** - -
-
Reviewer blindly approves changes - -*Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber -stamping." - -*Mitigation:* **Outside the scope of SLSA.** - -
- -### (C) Source code management - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -
Project owner bypasses or disables controls - -*Threat:* Trusted person with "admin" privileges in a repository submits "bad" -code bypassing existing controls. - -*Mitigation:* All persons are subject to same controls, whether or not they have -administrator privileges. Disabling the controls requires two-person review (and -maybe notifies other trusted persons?) - -*Example 1:* GitHub project owner pushes a change without review, even though -GitHub branch protection is enabled. Solution: Enable the "Include -Administrators" option for the branch protection. - -*Example 2:* GitHub project owner disables "Include Administrators", pushes a -change without review, then re-enables "Include Administrators". This currently -has no solution on GitHub. - -> TODO This is implicit but not clearly spelled out in the requirements. We -> should consider clarifying since most if not all existing platforms do not -> properly address this threat. - -
-
Platform admin abuses privileges - -*Threat:* Platform administrator abuses their privileges to bypass controls or -to push a malicious version of the software. - -*Mitigation:* TODO - -*Example 1:* GitHostingService employee uses an internal tool to push changes to -the MyPackage source repo. - -*Example 2:* GitHostingService employee uses an internal tool to push a -malicious version of the server to serve malicious versions of MyPackage sources -to a specific CI/CD client but the regular version to everyone else, in order to -hide tracks. - -*Example 3:* GitHostingService employee uses an internal tool to push a -malicious version of the server that includes a backdoor allowing specific users -to bypass branch protections. Adversary then uses this backdoor to submit a -change to MyPackage without review. - -
-
Exploit vulnerability in SCM - -*Threat:* Exploit a vulnerability in the implementation of the source code -management system to bypass controls. - -*Mitigation:* **Outside the scope of SLSA.** - -
- -### (D) External build parameters - -**TODO:** Move under "Build threats". - -An adversary builds from a version of the source code that does not match the -official source control repository, or changes the build parameters to inject -behavior that was not intended by the official source. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (E) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build platform pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -## Dependency threats - -**TODO:** Move after Usage Threats. - -A dependency threat is a potential for an adversary to introduce unintended -behavior in one artifact by compromising some other artifact that the former -depends on at build time. (Runtime dependencies are excluded from the model, as -[noted below](#runtime-dep).) - -Unlike other threat categories, dependency threats develop recursively through -the supply chain and can only be exploited indirectly. For example, if -application *A* includes library *B* as part of its build process, then a build -or source threat to *B* is also a dependency threat to *A*. Furthermore, if -library *B* uses build tool *C*, then a source or build threat to *C* is also a -dependency threat to both *A* and *B*. - -This version of SLSA does not explicitly address dependency threats, but we -expect that a future version will. In the meantime, you can [apply SLSA -recursively] to your dependencies in order to reduce the risk of dependency -threats. - -- **TODO:** Should we distinguish 1P vs 3P boundaries in the diagram, or - otherwise visualize 1P/3P? -- **TODO:** Expand to cover typosquatting, dependency confusion, and other - "dependency" threats. -- **TODO:** The word "compromised" is a bit too restrictive. If the publisher - intends to do harm, either because they tricked you into using a dependency - (typosquatting or dependency confusion), or because they were good and now - do something bad, that's not really "compromised" per se. -- **TODO:** Should we expand this to cover "transitive SLSA verification"? -- **TODO:** Update the Terminology page to show "build time" vs "runtime", - since the latter term results in confusion. Also consider the term "deploy - time" as an alternative. - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively - -### Build dependency - -An adversary compromises the target artifact through one of its build -dependencies. Any artifact that is present in the build environment and has the -ability to influence the output is considered a build dependency. - -
Include a vulnerable dependency (library, base image, bundled file, etc.) - -*Threat:* Statically link, bundle, or otherwise include an artifact that is -compromised or has some vulnerability, causing the output artifact to have the -same vulnerability. - -*Example:* The C++ program MyPackage statically links libDep at build time. A -contributor accidentally introduces a security vulnerability into libDep. The -next time MyPackage is built, it picks up and includes the vulnerable version of -libDep, resulting in MyPackage also having the security vulnerability. - -*Mitigation:* **TODO** - -
-
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.) - -*Threat:* Use a compromised tool or other software artifact during the build -process, which alters the build process and injects unintended behavior into the -output artifact. - -*Example:* MyPackage is a tarball containing an ELF executable, created by -running `/usr/bin/tar` during its build process. An adversary compromises the -`tar` OS package such that `/usr/bin/tar` injects a backdoor into every ELF -executable it writes. The next time MyPackage is built, the build picks up the -vulnerable `tar` package, which injects the backdoor into the resulting -MyPackage artifact. - -*Mitigation:* **TODO** - -
- -Reminder: dependencies that look like [runtime dependencies](#runtime-dep) -actually become build dependencies if they get loaded at build time. - -
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.) - -*Threat:* During the build process, use a compromised runtime dependency (such -as during testing or dynamic linking), which alters the build process and -injects unwanted behavior into the output. - -**NOTE:** This is technically the same case as [Use a compromised build -tool](#build-tool). We call it out to remind the reader that -[runtime dependencies](#runtime-dep) can become build dependencies if they are -loaded during the build. - -*Example:* MyPackage has a runtime dependency on package Dep, meaning that Dep -is not included in MyPackage but required to be installed on the user's machine -at the time MyPackage is run. However, Dep is also loaded during the build -process of MyPackage as part of a test. An adversary compromises Dep such that, -when run during a build, it injects a backdoor into the output artifact. The -next time MyPackage is built, it picks up and loads Dep during the build -process. The malicious code then injects the backdoor into the new MyPackage -artifact. - -*Mitigation:* In addition to all the mitigations for build tools, you can often -avoid runtime dependencies becoming build dependencies by isolating tests to a -separate environment that does not have write access to the output artifact. - -
- -### Related threats - -The following threats are related to "dependencies" but are not modeled as -"dependency threats". - -
Use a compromised dependency at runtime (modeled separately) - -*Threat:* Load a compromised artifact at runtime, thereby compromising the user -or environment where the software ran. - -*Example:* MyPackage lists package Dep as a runtime dependency. Adversary -publishes a compromised version of Dep that runs malicious code on the user's -machine when Dep is loaded at runtime. An end user installs MyPackage, which in -turn installs the compromised version of Dep. When the user runs MyPackage, it -loads and executes the malicious code from Dep. - -*Mitigation:* N/A - This threat is out of scope of SLSA. SLSA's threat model -does not explicitly model runtime dependencies. Instead, each runtime dependency -is considered a distinct artifact with its own threats. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - -### (E) Build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Forge values of the provenance (other than output digest) (Build L2+) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, the trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][unforgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -platform to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Forge output digest of the provenance (n/a) - -*Threat:* The tenant-controlled build process sets output artifact digest -(`subject` in SLSA Provenance) without the trusted control plane verifying that -such an artifact was actually produced. - -*Mitigation:* None; this is not a problem. Any build claiming to produce a given -artifact could have actually produced it by copying it verbatim from input to -output.[^preimage] (Reminder: Provenance is only a claim that a particular -artifact was *built*, not that it was *published* to a particular registry.) - -*Example:* A legitimate MyPackage artifact has digest `abcdef` and is built -from source repo `good/my-package`. A malicious build from source repo -`evil/my-package` claims that it built artifact `abcdef` when it did not. -Solution: Verifier rejects because the source location does not match; the -forged digest is irrelevant. - -[^preimage]: Technically this requires the artifact to be known to the - adversary. If they only know the digest but not the actual contents, they - cannot actually build the artifact without a [preimage attack] on the digest - algorithm. However, even still there are no known concerns where this is a - problem. - -[preimage attack]: https://en.wikipedia.org/wiki/Preimage_attack - -
-
Compromise project owner (Build L2+) - -*Threat:* An adversary gains owner permissions for the artifact's build project. - -*Mitigation:* The build project owner must not have the ability to influence the -build process or provenance generation. - -*Example:* MyPackage is built on Awesome Builder under the project "mypackage". -Adversary is an administrator of the "mypackage" project. Awesome Builder allows -administrators to debug build machines via SSH. An adversary uses this feature -to alter a build in progress. - -
-
Compromise other build (Build L3) - -*Threat:* Perform a malicious build that alters the behavior of a benign -build running in parallel or subsequent environments. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other or persist changes. - -*Example 1:* A build platform runs all builds for project MyPackage on -the same machine as the same Linux user. An adversary starts a malicious build -that listens for another build and swaps out source files, then starts a benign -build. The benign build uses the malicious build's source files, but its -provenance says it used benign source files. Solution: The build platform -changes architecture to isolate each build in a separate VM or similar. - -*Example 2:* A build platform uses the same machine for subsequent -builds. An adversary first runs a build that replaces the `make` binary with a -malicious version, then subsequently runs an otherwise benign build. Solution: -The builder changes architecture to start each build with a clean machine image. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build platform. - -*Mitigation:* Builds are [isolated] from the trusted build platform control -plane, and only the control plane has [access][unforgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a malicious artifact to a build cache that is later picked up by a -benign build process. - -*Mitigation:* Build caches must be [isolate][isolated] between builds to prevent -such cache poisoning attacks. - -*Example:* Build platform uses a build cache across builds, keyed by the hash of -the source file. Adversary runs a malicious build that creates a "poisoned" -cache entry with a falsified key, meaning that the value wasn't really produced -from that source. A subsequent build then picks up that poisoned cache entry. - -
-
Compromise build platform admin (verification) - -*Threat:* An adversary gains admin permissions for the artifact's build platform. - -*Mitigation:* The build platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals, audit -logging). - -*Example:* MyPackage is built on Awesome Builder. Awesome Builder allows -engineers on-call to SSH into build machines to debug production issues. An -adversary uses this access to modify a build in progress. Solution: Consumers -do not accept provenance from the build platform unless they trust sufficient -controls are in place to prevent abusing admin privileges. - -
- -### (F) Artifact publication - -An adversary uploads a package artifact that does not reflect the intent of the -package's official source control repository. - -This is the most direct threat because it is the easiest to pull off. If there -are no mitigations for this threat, then (D) and (E) are often indistinguishable -from this threat. - -**TODO:** We need to define "official source control repository". Its meaning is -not obvious. The gist is that each package theoretically has some "official" or -"canonical" repository from which it "should" be built, and the attack here is -that you either build from a different source repository or otherwise do -something that doesn't reflect that source repository. But we need to nail down -this concept. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Solution: Verifier rejects because builder is not as -expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Distribution channel - -An adversary modifies the package on the package registry using an -administrative interface or through a compromise of the infrastructure. - -**TODO:** - -## Usage threats - -A usage threat is a potential for an adversary to exploit behavior of the -consumer. - -### (H) Package selection - -The consumer requests a package that it did not intend. - -
Dependency confusion - -*Threat:* Register a package name in a public registry that shadows a name used -on the victim's internal registry, and wait for a misconfigured victim to fetch -from the public registry instead of the internal one. - -**TODO:** fill out the rest of this section - -
-
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* **Mostly outside the scope of SLSA.** That said, the requirement -to make the source available can be a mild deterrent, can aid investigation or -ad-hoc analysis, and can complement source-based typosquatting solutions. - -
- -### (I) Usage - -**TODO:** What should we put here? - -## Availability threats - -**TODO:** Merge into the list above rather than having a separate section. - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA v1.0 does not address availability threats, though future versions might. - -
(A)(B) Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* Some system retains the revision and its version control history, -making it available for inspection indefinitely. Users cannot delete the -revision except as part of a transparent legal or privacy process. - -*Example:* An adversary submits malicious code to the MyPackage GitHub repo, -builds from that revision, then does a force push to erase that revision from -history (or requests that GitHub delete the repo.) This would make the revision -unavailable for inspection. Solution: Verifier rejects the package because it -lacks a positive attestation showing that some system, such as GitHub, ensured -retention and availability of the source code. - -
-
A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* **Outside the scope of SLSA.** That said, some solutions to -support hermetic and reproducible builds may also reduce the impact of this -threat. - -
-
De-list artifact - -*Threat:* The package registry stops serving the artifact. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. - -
-
De-list provenance - -*Threat:* The package registry stops serving the provenance. - -*Mitigation:* N/A - This threat is out of scope of SLSA v1.0. - -
- -## Verification threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above. - -
Tamper with recorded expectations - -*Threat:* Modify the verifier's recorded expectations, causing the verifier to -accept an unofficial package artifact. - -*Mitigation:* Changes to recorded expectations requires some form of -authorization, such as two-party review. - -*Example:* The package ecosystem records its expectations for a given package -name in a configuration file that is modifiable by that package's producer. The -configuration for MyPackage expects the source repository to be -`good/my-package`. The adversary modifies the configuration to also accept -`evil/my-package`, and then builds from that repository and uploads a malicious -version of the package. Solution: Changes to the recorded expectations require -two-party review. - -
-
Forge change metadata - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* Source control platform strongly authenticates actor identity, -timestamp, and parent revisions. - -*Example:* Adversary submits a git commit with a falsified author and timestamp, -and then rewrites history with a non-fast-forward update to make it appear to -have been made long ago. Solution: Consumer detects this by seeing that such -changes are not strongly authenticated and thus not trustworthy. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Require cryptographically secure hash functions for commit -checksums and provenance subjects, such as SHA-256. - -*Examples:* Construct a benign file and a malicious file with the same SHA-1 -hash. Get the benign file reviewed and then submit the malicious file. -Alternatively, get the benign file reviewed and submitted and then build from -the malicious file. Solution: Only accept cryptographic hashes with strong -collision resistance. - -
- -
- - - -[authentic]: requirements.md#provenance-authentic -[exists]: requirements.md#provenance-exists -[isolated]: requirements.md#isolated -[unforgeable]: requirements.md#provenance-unforgeable -[supply chain threats]: threats-overview diff --git a/docs/spec/v1.1-rc1/use-cases.md b/docs/spec/v1.1-rc1/use-cases.md deleted file mode 100644 index 9e92d2b46..000000000 --- a/docs/spec/v1.1-rc1/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package registry. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build platforms rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified from a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.1-rc1/verification_summary.md b/docs/spec/v1.1-rc1/verification_summary.md deleted file mode 100644 index 31021e559..000000000 --- a/docs/spec/v1.1-rc1/verification_summary.md +++ /dev/null @@ -1,411 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software producers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [resolvedDependencies](/provenance/v1#resolvedDependencies) of the artifact -being verified (recursively) or b) matching the non-source dependency -listed in `resolvedDependencies` (`subject.digest` == -`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` == -`resolvedDependencies.uri`) to a VSA _for that dependency_ and using -`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependencyLevels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "", - "version": { - "": "", - ... - } - }, - "timeVerified": , - "resourceUri": , - "policy": { - "uri": "", - "digest": { } - } - "inputAttestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verificationResult": "", - "verifiedLevels": [""], - "dependencyLevels": { - "": , - "": , - ... - }, - "slsaVersion": ".", -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`verifier.version` _map (string->string), optional_ - -> Map of names of components of the verification platform to their version. - - -`timeVerified` _string ([Timestamp]), optional_ - -> Timestamp indicating what time the verification occurred. - - -`resourceUri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. - - -`policy` _object ([ResourceDescriptor]), required_ - -> Describes the policy that the `subject` was verified against. -> -> The entry MUST contain a `uri` identifying which policy was applied and -> SHOULD contain a `digest` to indicate the exact version of that policy. - - -`inputAttestations` _array ([ResourceDescriptor]), optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `resolvedDependencies` field in [SLSA Provenance]. -> -> This field MAY be absent if the verifier does not support this feature. -> If non-empty, this field MUST contain information on _all_ the attestations -> used to perform verification. -> -> Each entry MUST contain a `digest` of the attestation and SHOULD contains a -> `uri` that can be used to fetch the attestation. - - -`verificationResult` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`verifiedLevels` _array ([SlsaResult]), required_ - -> Indicates the highest level of each track verified for the artifact (and not -> its dependencies), or "FAILED" if policy verification failed. -> -> Users MUST NOT include more than one level per SLSA track. Note that each SLSA -> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies -> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to -> include more than one level per track. - - -`dependencyLevels` _object, optional_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. -> A set but empty `dependencyLevels` object means that the artifact has **no** -> dependency at all, while an unset or null `dependencyLevels` means that the -> verifier makes no claims about the artifact's dependencies. -> -> Users MUST count each dependency only once per SLSA track, at the highest -> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`, -> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for -> `SLSA_BUILD_LEVEL_1`. - - -`slsaVersion` _string, optional_ - -> Indicates the version of the SLSA specification that the verifier used, in the -> form `.`. Example: `1.0`. If unset, the default is an -> unspecified minor version of `1.x`. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier", - "version": { - "slsa-verifier-linux-amd64": "v2.3.0", - "slsa-framework/slsa-verifier/actions/installer": "v2.3.0" - } - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "inputAttestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_BUILD_LEVEL_3"], - "dependencyLevels": { - "SLSA_BUILD_LEVEL_3": 5, - "SLSA_BUILD_LEVEL_2": 7, - "SLSA_BUILD_LEVEL_1": 1, - }, - "slsaVersion": "1.0" -} -``` - -## How to verify - -VSA consumers use VSAs to accomplish goals based on delegated trust. We call the -process of establishing a VSA's authenticity and determining whether it meets -the consumer's goals 'verification'. Goals differ, as do levels of confidence -in VSA producers, so the verification procedure changes to suit its context. -However, there are certain steps that most verification procedures have in -common. - -Verification MUST include the following steps: - -1. Verify the signature on the VSA envelope using the preconfigured roots of - trust. This step ensures that the VSA was produced by a trusted producer - and that it hasn't been tampered with. - -2. Verify the statement's `subject` matches the digest of the artifact in - question. This step ensures that the VSA pertains to the intended artifact. - -3. Verify that the `predicateType` is - `https://slsa.dev/verification_summary/v1`. This step ensures that the - in-toto predicate is using this version of the VSA format. - -4. Verify that the `verifier` matches the public key (or equivalent) used to - verify the signature in step 1. This step identifies the VSA producer in - cases where their identity is not implicitly revealed in step 1. - -5. Verify that the value for `resourceUri` in the VSA matches the expected - value. This step ensures that the consumer is using the VSA for the - producer's intended purpose. - -6. Verify that the value for `slsaResult` is `PASSED`. This step ensures the - artifact is suitable for the consumer's purposes. - -7. Verify that `verifiedLevels` contains the expected value. This step ensures - that the artifact is suitable for the consumer's purposes. - -Verification MAY additionally contain the following step: - -1. (Optional) Verify additional fields required to determine whether the VSA - meets your goal. - -Verification mitigates different threats depending on the VSA's contents and the -verification procedure. - -IMPORTANT: A VSA does not protect against compromise of the verifier, such as by -a malicious insider. Instead, VSA consumers SHOULD carefully consider which -verifiers they add to their roots of trust. - -### Examples - -1. Suppose consumer C wants to delegate to verifier V the decision for whether - to accept artifact A as resource R. Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` contains `SLSA_BUILD_LEVEL_UNEVALUATED`. - - Note: This example is analogous to traditional code signing. The expected - value for `verifiedLevels` is arbitrary but prenegotiated by the producer and - the consumer. The consumer does not need to check additional fields, as C - fully delegates the decision to V. - -2. Suppose consumer C wants to enforce the rule "Artifact A at resource R must - have a passing VSA from verifier V showing it meets SLSA Build Level 2+." - Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` is `SLSA_BUILD_LEVEL_2` or `SLSA_BUILD_LEVEL_3`. - - Note: In this example, verifying the VSA mitigates the same threats as - verifying the artifact's SLSA provenance. See - [Verifying artifacts](/spec/v1.0/verifying-artifacts) for details about which - threats are addressed by verifying each SLSA level. - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -SHOULD be one of these values: - -- `SLSA_BUILD_LEVEL_UNEVALUATED` -- `SLSA_BUILD_LEVEL_0` -- `SLSA_BUILD_LEVEL_1` -- `SLSA_BUILD_LEVEL_2` -- `SLSA_BUILD_LEVEL_3` -- `FAILED` (Indicates policy evaluation failed) - -Note that each SLSA level implies the levels below it in the same track. -For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` + -`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`). - -Users MAY use custom values here but MUST NOT use custom values starting with -`SLSA_`. - -## Change history - -- 1.1: - - Changed the `policy` object to recommend that the `digest` field of - the `ResourceDescriptor` is set. - - Added optional `verifier.version` field to record verification tools. - - Added Verification section with examples. - - Made `timeVerified` optional. -- 1.0: - - Replaced `materials` with `resolvedDependencies`. - - Relaxed `SlsaResult` to allow other values. - - Converted to lowerCamelCase for consistency with [SLSA Provenance]. - - Added `slsaVersion` field. -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SLSA Provenance]: /provenance -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/digest_set.md -[ResourceURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#resourceuri -[ResourceDescriptor]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/resource_descriptor.md -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[Timestamp]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules diff --git a/docs/spec/v1.1-rc1/verifying-artifacts.md b/docs/spec/v1.1-rc1/verifying-artifacts.md deleted file mode 100644 index 2e6e7045d..000000000 --- a/docs/spec/v1.1-rc1/verifying-artifacts.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Verifying artifacts -description: SLSA uses provenance to indicate whether an artifact is authentic or not, but provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection verification, and this page describes how to verify artifacts and their SLSA provenenance. The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that -inspection **verification**, and this page describes recommendations for how to -verify artifacts and their SLSA provenance. - -This page is divided into several sections. The first describes the process -for verifying an artifact and its provenance against a set of expectations. The -second describes how to form the expectations used to verify provenance. The -third discusses architecture choices for where provenance verification can -happen. - -## How to verify - -Verification SHOULD include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- Verifying the signature on the provenance envelope. -- Ensuring that the values for `buildType` and `externalParameters` in the - provenance match the expected values. The package ecosystem MAY allow - an approved list of `externalParameters` to be ignored during verification. - Any unrecognized `externalParameters` SHOULD cause verification to fail. - -![Threats covered by each step](images/supply-chain-threats-build-verification.svg) - -See [Terminology](terminology.md) for an explanation of supply chain model and -[Threats & mitigations](threats.md) for a detailed explanation of each threat. - -**Note:** This section assumes that the provenance is in the recommended -[provenance format](/provenance/v1). If it is not, then the verifier SHOULD -perform equivalent checks on provenance fields that correspond to the ones -referenced here. - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "E", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This configuration - is likely in the form of a map from (builder public key identity, - `builder.id`) to (SLSA Build level) drawn from the SLSA Conformance - Program (coming soon). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the artifact in question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "E"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Verifying build platforms](verifying-systems). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "H".) -- [Threat "H"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. - -[Threat "E"]: threats#e-compromise-build-process -[Threat "F"]: threats#f-upload-modified-package -[Threat "G"]: threats#g-compromise-package-repo -[Threat "H"]: threats#h-use-compromised-package - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets your expectations for that -package in order to mitigate [threat "C"]. - -In our threat model, the adversary has ability to invoke a build and to publish -to the registry. The adversary is not able to write to the source repository, nor do -they have insider access to any trusted systems. Your expectations SHOULD be -sufficient to detect or prevent this adversary from injecting unofficial -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 - -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 -range of values (possibly any value) if it is known that any value in the range -is safe. JSON comparison is sufficient for verifying parameters. - -TIP: Difficulty in forming meaningful expectations about `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "C"]: threats#c-build-from-modified-source - -### Step 3: (Optional) Check dependencies recursively - -[verify-step-3]: #step-3-optional-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. Note that SLSA v1.0 does not have any requirements on the -completeness or verification of `resolvedDependencies`. However, one might wish -to verify dependencies in order to mitigate [threat "E"] and protect against -threats further up the supply chain. If `resolvedDependencies` is incomplete, -these checks can be done on a best-effort basis. - -A [Verification Summary Attestation (VSA)][VSA] can make dependency verification -more efficient by recording the result of prior verifications. A trimming -heuristic or exception mechanism is almost always necessary when verifying -dependencies because there will be transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) - -[Threat "E"]: threats#e-use-compromised-dependency -[VSA]: /verification_summary -[threats]: threats - -## Forming Expectations - -Expectations are known provenance values that indicate the -corresponding artifact is authentic. For example, a package ecosystem may -maintain a mapping between package names and their canonical source -repositories. That mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git branches or tags. - -- **Defined by producer:** The package producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the package's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -- **Defined in source:** The source repository tells the verifier what their - expectations ought to be. In this model, the package name is immutably bound - to a source repository and all other external parameters are defined in the - source repository. This is how the Go ecosystem works, for example, since - the package name *is* the source repository location. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -will likely have different artifacts and therefore different provenance. Similarly, an -artifact might have different names in different package ecosystems but use the same -provenance file. - -## Architecture options - -There are several options (non-mutually exclusive) for where provenance verification -can happen: the package ecosystem at upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify provenance. For example, even if a package -ecosystem verifies provenance, consumers who get artifacts from that package -ecosystem might wish to verify provenance themselves for defense in depth. They -can do so using either client-side verification tooling or by polling a -monitor. - - - -### Package ecosystem - -[Package ecosystem]: #package-ecosystem - -A package ecosystem is a set of rules and conventions governing -how packages are distributed. Every package artifact has an ecosystem, whether it is -formal or ad-hoc. Some ecosystems are formal, such as language distribution -(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". For more background, see -[Package Model](terminology.md#package-model). - -During package upload, a package ecosystem can ensure that the artifact's -provenance matches the expected values for that package name's provenance before -accepting it into the package registry. This option is RECOMMENDED whenever -possible because doing so benefits all of the package ecosystem's clients. - -The package ecosystem is responsible for making its expectations available to -consumers, reliably redistributing artifacts and provenance, and providing tools -to enable safe artifact consumption (e.g. whether an artifact meets -expectations). - -### Consumer - -[Consumer]: #consumer - -A package artifact's consumer is the organization or individual that uses the -package artifact. - -Consumers can form their own expectations for artifacts or use the default -expectations provided by the package producer and/or package ecosystem. -When forming their own expectations, the consumer uses client-side verification tooling to ensure -that the artifact's provenance matches their expectations for that package -before use (e.g. during installation or deployment). Client-side verification -tooling can be either standalone, such as -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into -the package ecosystem client. - -### Monitor - -[Monitor]: #monitor - -A monitor is a service that verifies provenance for a set -of packages and publishes the result of that verification. The set of -packages verified by a monitor is arbitrary, though it MAY mimic the set -of packages published through one or more package ecosystems. The monitor -SHOULD publish its expectations for all the packages it verifies. - -Consumers can continuously poll a monitor to detect artifacts that -do not meet the monitor's expectations. Detecting artifacts that fail -verification is of limited benefit unless a human or automated system takes -action in response to the failed verification. diff --git a/docs/spec/v1.1-rc1/verifying-systems.md b/docs/spec/v1.1-rc1/verifying-systems.md deleted file mode 100644 index 7c0ef2896..000000000 --- a/docs/spec/v1.1-rc1/verifying-systems.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Verifying build platforms -description: Guidelines for assessing build platform security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust platforms to produce Build L3 -artifacts and provenance unless they have some proof that the provenance is -[unforgeable](requirements.md#provenance-unforgeable) and the builds are -[isolated](requirements.md#isolated). - -This page describes the parts of a build platform that consumers SHOULD assess -and provides sample questions consumers can ask when assessing a build platform. -See also [Threats & mitigations](threats.md) and the -[build model](terminology.md#build-model). - -## Threats - -### Adversary goal - -The SLSA Build track defends against an adversary whose primary goal is to -inject unofficial behavior into a package artifact while avoiding detection. -Remember that [verifiers](verifying-artifacts.md) only accept artifacts whose -provenance matches expectations. To bypass this, the adversary tries to either -(a) tamper with a legitimate build whose provenance already matches -expectations, or (b) tamper with an illegitimate build's provenance to make it -match expectations. - -More formally, if a build with external parameters P would produce an artifact -with binary hash X and a build with external parameters P' would produce an -artifact with binary hash Y, they wish to produce provenance indicating a build -with external parameters P produced an artifact with binary hash Y. - -See threats [C], [D], [E], and [F] for examples of specific threats. - -Note: Platform abuse (e.g. running non-build workloads) and attacks against -builder availability are out of scope of this document. - -### Adversary profiles - -Consumers SHOULD also evaluate the build platform's ability to defend against the -following types of adversaries. - -1. Project contributors, who can: - - Create builds on the build platform. These are the adversary's controlled - builds. - - Modify one or more controlled builds' external parameters. - - Modify one or more controlled builds' environments and run arbitrary - code inside those environments. - - Read the target build's source repo. - - Fork the target build's source repo. - - Modify a fork of the target build's source repo and build from it. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Create new builds under the target build's project or identity. - - Modify the target build's source repo and build from it. - - Modify the target build's configuration. -3. Build platform administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Run arbitrary code on the build platform. - - Read and modify network traffic. - - Access the control plane's cryptographic secrets. - - Remotely access build environments (e.g. via SSH). - -[C]: threats.md#c-build-from-modified-source -[D]: threats.md#d-use-compromised-dependency -[E]: threats.md#e-compromise-build-process -[F]: threats.md#f-upload-modified-package - -## Build platform components - -Consumers SHOULD consider at least these five elements of the -[build model](terminology.md#build-model) when assessing build platforms for SLSA -conformance: external parameters, control plane, build environments, caches, -and outputs. - -![image](images/build-model.svg) - -The following sections detail these elements of the build model and give prompts -for assessing a build platform's ability to produce SLSA Build L3 provenance. The -assessment SHOULD take into account the security model used to identify the -transitive closure of the `builder.id` for the [provenance model](provenance.md#model), specifically -around the platform's boundaries, actors, and interfaces. - -### External parameters - -External parameters are the external interface to the builder and include all -inputs to the build process. Examples include the source to be built, the build -definition/script to be executed, user-provided instructions to the -control plane for how to create the build environment (e.g. which operating -system to use), and any additional user-provided strings. - -#### Prompts for assessing external parameters - -- How does the control plane process user-provided external parameters? - Examples: sanitizing, parsing, not at all -- Which external parameters are processed by the control plane and which are - processed by the build environment? -- What sort of external parameters does the control plane accept for - build environment configuration? -- How do you ensure that all external parameters are represented in the - provenance? -- How will you ensure that future design changes will not add additional - external parameters without representing them in the provenance? - -### Control plane - -The control plane is the build platform component that orchestrates each -independent build execution. It is responsible for setting up each build and -cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs -provenance for each build performed on the build platform. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -#### Prompts for assessing the control plane - -- Administration - - What are the ways an employee can use privileged access to influence a - build or provenance generation? Examples: physical access, terminal - access, access to cryptographic secrets - - What controls are in place to detect or prevent the employee from - abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many employees have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and platform - outages? Are they tested? How frequently? - -- Provenance generation - - How does the control plane observe the build to ensure the provenance's - accuracy? - - Are there situations in which the control plane will not generate - provenance for a completed build? What are they? - -- Development practices - - How do you track the control plane's software and configuration? - Example: version control - - How do you build confidence in the control plane's software supply - chain? Example: SLSA L3+ provenance, build from source - - How do you secure communications between builder components? Example: - TLS with certificate transparency. - - Are you able to perform forensic analysis on compromised build - environments? How? Example: retain base images indefinitely - -- Creating build environments - - How does the control plane share data with build environments? Example: - mounting a shared file system partition - - How does the control plane protect its integrity from build - environments? Example: not mount its own file system partitions on - build environments - - How does the control plane prevent build environments from accessing its - cryptographic secrets? Examples: dedicated secret storage, not mounting - its own file system partitions to build environments, hardware security - modules - -- Managing cryptographic secrets - - How do you store the control plane's cryptographic secrets? - - Which parts of the organization have access to the control plane's - cryptographic secrets? - - What controls are in place to detect or prevent employees abusing such - access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Build environment - -The build environment is the independent execution context where the build -takes place. In the case of a distributed build, the build environment is the -collection of all execution contexts that run build steps. Each build -environment must be isolated from the control plane and from all other build -environments, including those running builds from the same tenant or project. -Tenants are free to modify the build environment arbitrarily. Build -environments must have a means to fetch input artifacts (source, dependencies, -etc). - -#### Prompts for assessing build environments - -- Isolation technologies - - How are build environments isolated from the control plane and each - other? Examples: VMs, containers, sandboxed processes - - How is separation achieved between trusted and untrusted processes? - - How have you hardened your build environments against malicious tenants? - Examples: configuration hardening, limiting attack surface - - How frequently do you update your isolation software? - - What is your process for responding to vulnerability disclosures? What - about vulnerabilities in your dependencies? - - What prevents a malicious build from gaining persistence and influencing - subsequent builds? - -- Creation and destruction - - What operating system and utilities are available in build environments - on creation? How were these elements chosen? Examples: A minimal Linux - distribution with its package manager, OSX with HomeBrew - - How long could a compromised build environment remain active in the - build platform? - -- Network access - - Are build environments able to call out to remote execution? If so, how - do you prevent them from tampering with the control plane or other build - environments over the network? - - Are build environments able to open services on the network? If so, how - do you prevent remote interference through these services? - -### Cache - -Builders may have zero or more caches to store frequently used dependencies. -Build environments may have either read-only or read-write access to caches. - -#### Prompts for assessing caches - -- What sorts of caches are available to build environments? -- How are those caches populated? -- How are cache contents validated before use? - -### Output storage - -Output Storage holds built artifacts and their provenance. Storage may either be -shared between build projects or allocated separately per-project. - -#### Prompts for assessing output storage - -- How do you prevent builds from reading or overwriting files that belong to - another build? Example: authorization on storage -- What processing, if any, does the control plane do on output artifacts? - -## Builder evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model defined as -part of the provenance. Evidence submitted for third-party certification need not -be published. diff --git a/docs/spec/v1.1-rc1/whats-new.md b/docs/spec/v1.1-rc1/whats-new.md deleted file mode 100644 index c4cc6ca53..000000000 --- a/docs/spec/v1.1-rc1/whats-new.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: What's new in SLSA v1.1 -description: SLSA v1.1 is a minor release of SLSA. That is, all changes are intended to be backwards compatible. This document describes what has changed since v1.0. ---- - -SLSA v1.1 is a minor release of SLSA v1 which brings clarifications and -additional content without changing the meaning of the specification. This -document describes the main changes in v1.1 relative to the prior release, -[v1.0]. - -## Summary of changes - -- Clarify that attestation format schema are informative and the - specification texts (SLSA and [in-toto attestation]) are the canonical - source of definitions. -- Add procedure for verifying VSAs. -- Add verifier metadata to VSA format. -- It is now recommended that the `digest` field of `ResourceDescriptor` is - set in a Verification Summary Attestation's (VSA) `policy` object. -- Further refine the [threat model](threats). - - - -[in-toto attestation]: https://github.com/in-toto/attestation -[v1.0]: /spec/v1.0/ diff --git a/docs/spec/v1.1-rc2/about.md b/docs/spec/v1.1-rc2/about.md deleted file mode 100644 index fcf183c6a..000000000 --- a/docs/spec/v1.1-rc2/about.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: About SLSA -description: With supply chain attacks on the rise, a shared vocabulary and universal framework are needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software. ---- - -This page is an introduction to SLSA and its concepts. If you're new -to SLSA, start here! - -## What is SLSA? - -Supply-chain Levels for Software Artifacts, or SLSA ("salsa"), is a set of incrementally adoptable guidelines for supply chain security, -established by industry consensus. The specification set by SLSA is useful for -both software producers and consumers: producers can follow SLSA's guidelines to -make their software supply chain more secure, and consumers can use SLSA to make -decisions about whether to trust a software package. - -SLSA offers: - -- A common vocabulary to talk about software supply chain security -- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume -- An actionable checklist to improve your own software's security -- A way to measure your efforts toward compliance with the [Secure Software Development Framework (SSDF)](https://csrc.nist.gov/Projects/ssdf) - -## Why SLSA is needed - -High-profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply -chain integrity weaknesses that may go unnoticed, yet quickly become very -public, disruptive, and costly in today's environment when exploited. They've -also shown that there are inherent risks not just in code itself, but at -multiple points in the complex process of getting that code into software -systems—that is, in the **software supply chain**. Since these attacks are on -the rise and show no sign of decreasing, a universal framework for hardening the -software supply chain is needed, as affirmed by the U.S. Executive Order on -Improving the Nation's Cybersecurity of May 12th, 2021. - -Security techniques for vulnerability detection and analysis of source code are -essential, but are not enough on their own. Even after fuzzing or vulnerability -scanning is completed, changes to code can happen, whether unintentionally or -from insider threats or compromised accounts. Risk for code modification exists at -each link in a typical software supply chain, from source to build through -packaging and distribution. Any weaknesses in the supply chain undermine -confidence in whether the code that you run is actually the code that you -scanned. - -SLSA is designed to support automation that tracks code handling from source -to binary, protecting against tampering regardless of the complexity -of the software supply chain. As a result, SLSA increases trust that the -analysis and review performed on source code can be assumed to still apply to -the binary consumed after the build and distribution process. - -## SLSA in layperson's terms - -There has been a [lot of discussion](https://ntia.gov/page/software-bill-materials) about the need for "ingredient labels" for -software—a "software bill of materials" (SBOM) that tells users what is in their -software. Building off this analogy, SLSA can be thought of as all the food -safety handling guidelines that make an ingredient list credible. From standards -for clean factory environments so contaminants aren't introduced in packaging -plants, to the requirement for tamper-proof seals on lids that ensure nobody -changes the contents of items sitting on grocery store shelves, the entire food -safety framework ensures that consumers can trust that the ingredient list -matches what's actually in the package they buy. - -Likewise, the SLSA framework provides this trust with guidelines and -tamper-resistant evidence for securing each step of the software production -process. That means you know not only that nothing unexpected was added to the -software product, but also that the ingredient label itself wasn't tampered with -and accurately reflects the software contents. In this way, SLSA helps protect -against the risk of: - -- Code modification (by adding a tamper-evident "seal" to code after - source control) -- Uploaded artifacts that were not built by the expected CI/CD platform (by marking - artifacts with a factory "stamp" that shows which build platform created it) -- Threats against the build platform (by providing "manufacturing facility" - best practices for build platform services) - -For more exploration of this analogy, see the blog post -[SLSA + SBOM: Accelerating SBOM success with the help of SLSA](/blog/2022/05/slsa-sbom). - -## Who is SLSA for? - -In short: everyone involved in producing and consuming software, or providing -infrastructure for software. - -**Software producers**, such as an open source project, a software vendor, or a -team writing first-party code for use within the same company. SLSA gives you -protection against tampering along the supply chain to your consumers, both -reducing insider risk and increasing confidence that the software you produce -reaches your consumers as you intended. - -**Software consumers**, such as a development team using open source packages, a -government agency using vendored software, or a CISO judging organizational -risk. SLSA gives you a way to judge the security practices of the software you -rely on and be sure that what you receive is what you expected. - -**Infrastructure providers**, who provide infrastructure such as an ecosystem -package manager, build platform, or CI/CD platform. As the bridge between the -producers and consumers, your adoption of SLSA enables a secure software supply -chain between them. - -## How SLSA works - -We talk about SLSA in terms of [tracks and levels](levels.md). -A SLSA track focuses on a particular aspect of a supply chain, such as the Build -Track. SLSA v1.1 consists of only a single track ([Build](levels.md#build-track)), but future versions of -SLSA will add tracks that cover other parts of the software supply chain, such -as how source code is managed. - -Within each track, ascending levels indicate increasingly hardened security -practices. Higher levels provide better guarantees against supply chain threats, -but come at higher implementation costs. Lower SLSA levels are designed to be -easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes -used to refer to software that doesn't yet meet any SLSA level. Currently, the -SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels -to be possible in [future revisions](future-directions.md). - -The combination of tracks and levels offers an easy way to discuss whether -software meets a specific set of requirements. By referring to an artifact as -meeting SLSA Build Level 3, for example, you're indicating in one phrase that -the software artifact was built following a set of security practices that -industry leaders agree protect against particular supply chain compromises. - -## What SLSA doesn't cover - -SLSA is only one part of a thorough approach to supply chain security. There -are several areas outside SLSA's current framework that are nevertheless -important to consider together with SLSA such as: - -- Code quality: SLSA does not tell you whether the developers writing the - source code followed secure coding practices. -- Producer trust: SLSA does not address organizations that intentionally - produce malicious software, but it can reduce insider risks within an - organization you trust. SLSA's Build Track protects against tampering during - or after the build, and [future SLSA tracks](future-directions.md) intend to - protect against unauthorized modifications of source code and dependencies. -- Transitive trust for dependencies: the SLSA level of an artifact is - independent of the level of its dependencies. You can use SLSA recursively to - also judge an artifact's dependencies on their own, but there is - currently no single SLSA level that applies to both an artifact and its - transitive dependencies together. For a more detailed explanation of why, - see the [FAQ](faq#q-why-is-slsa-not-transitive). diff --git a/docs/spec/v1.1-rc2/attestation-model.md b/docs/spec/v1.1-rc2/attestation-model.md deleted file mode 100644 index 380907029..000000000 --- a/docs/spec/v1.1-rc2/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first-party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed-source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open-source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open-source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed-source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third-party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.1-rc2/distributing-provenance.md b/docs/spec/v1.1-rc2/distributing-provenance.md deleted file mode 100644 index dadf4db94..000000000 --- a/docs/spec/v1.1-rc2/distributing-provenance.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Distributing provenance -description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is platform implementers and software distributors. ---- - -In order to make provenance for artifacts available after generation -for verification, SLSA requires the distribution and verification of provenance -metadata in the form of SLSA attestations. - -This document provides specifications for distributing provenance and the -relationship between build artifacts and provenance (build attestations). It is -primarily concerned with artifacts for ecosystems that distribute build -artifacts, but some attention is also paid to ecosystems that distribute -container images or only distribute source artifacts, as many of the same -principles generally apply to any artifact or group of artifacts. - -In addition, this document is primarily for the benefit of artifact -distributors, to understand how they can adopt the distribution of SLSA -provenance. It is primarily concerned with the means of distributing -attestations and the relationship of attestations to build artifacts, and not -with the specific format of the attestation itself. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Background - -The [package ecosystem]'s maintainers are responsible for reliably -redistributing artifacts and provenance, making the producers' expectations -available to consumers, and providing tools to enable safe artifact consumption -(e.g., whether an artifact meets its producer's expectations). - -## Relationship between releases and attestations - -Attestations SHOULD be bound to artifacts, not releases. - -A single "release" of a project, package, or library might include multiple -artifacts. These artifacts result from builds on different platforms, -architectures, or environments. The builds need not happen at roughly the same -point in time and might even span multiple days. - -It is often difficult or impossible to determine when a release is 'finished' -because many ecosystems allow adding new artifacts to old releases when adding -support for new platforms or architectures. Therefore, the set of attestations -for a given release MAY grow over time as additional builds and attestations -are created. - -Thus, package ecosystems SHOULD support multiple individual attestations per -release. At the time of a given build, the relevant provenance for that build -can be added to the release, depending on the relationship to the given -artifacts. - -## Relationship between artifacts and attestations - -Package ecosystems SHOULD support a one-to-many relationship from build -artifacts to attestations to ensure that anyone is free to produce and publish -any attestation they might need. However, while there are lots of possible -attestations that can have a relationship to a given artifact, in this context -SLSA is primarily concerned with build attestations, i.e., provenance, and as -such, this specification only considers build attestations, produced by the -same maintainers as the artifacts themselves. - -By providing provenance alongside an artifact in the manner specified by a -given ecosystem, maintainers are considered to be 'elevating' these build -attestations above all other possible attestations that could be provided by -third parties for a given artifact. The ultimate goal is for maintainers to -provide the provenance necessary for a repository to be able to verify some -potential policy that requires a certain SLSA level for publication, not -support the publication of arbitrary attestations by third parties. - -As a result, this provenance SHOULD accompany the artifact at publish time, and -package ecosystems SHOULD provide a way to map a given artifact to its -corresponding attestations. The mappings can be either implicit (e.g., require a -custom filename schema that uniquely identifies the provenance over other -attestation types) or explicit (e.g., it could happen as a de-facto standard -based on where the attestation is published). - -The provenance SHOULD have a filename that is directly related to the build -artifact filename. For example, for an artifact `.`, the -attestation is `.attestation` or some similar extension (for example -[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`). - -## Where attestations are published - -There are a number of opportunities and venues to publish attestations during -and after the build process. Producers MUST publish attestations in at least -one place, and SHOULD publish attestations in more than one place: - -- **Publish attestations alongside the source repository releases**: If the - source repository hosting provider offers an artifact "release" feature, - such as [GitHub - releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), - producers SHOULD include provenance as part of such releases. This option - has the benefit of requiring no changes to the package registry to support - provenance formats, but has the disadvantage of putting the source - repository hosting provider in the critical path for installers that want to - verify policy at build-time. -- **Publish attestations alongside the artifact in the package registry**: - Many software repositories already support some variety of publishing 1:1 - related files alongside an artifact, sometimes known as “sidecar files”. - For example, PyPI supports publishing `.asc` files representing the PGP - signature for an artifact with the same filename (but different extension). - This option requires the mapping between artifact and attestation (or - attestation vessel) to be 1:1. -- **Publish attestations elsewhere, record their existence in a transparency - log**: Once an attestation has been generated and published for a build, a - hash of the attestation and a pointer to where it is indexed SHOULD be - published to a third-party transparency log that exists outside the source - repository and package registry. Not only are transparency logs such as - [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed - to be immutable, but they typically also make monitoring easier. - Requiring the presence of the attestation in a monitored transparency log - during verification helps ensure the attestation is trustworthy. - -Combining these options gives us a process for bootstrapping SLSA adoption -within an ecosystem, even if the package registry doesn't support publishing -attestations. First, interested projects modify their release process to -produce SLSA provenance. Then, they publish that provenance to their source -repository. Finally, they publish the provenance to the package registry, if -and when the registry supports it. - -Long-term, package registries SHOULD support uploading and distributing -provenance alongside the artifact. This model is preferred for two reasons: - -- trust: clients already trust the package registry as the source of their - artifacts, and don't need to trust an additional service; -- reliability: clients already depend on the package registry as part of - their critical path, so distributing provenance via the registry avoids - adding an additional point of failure. - -Short term, consumers of build artifacts can bootstrap a manual policy by using -the source repository only for projects that publish all artifacts and -attestations to the source repository, and later extend this to all artifacts -published to the package registry via the canonical installation tools once -a given ecosystem supports them. - -## Immutability of attestations - -Attestations SHOULD be immutable. Once an attestation is published as it -corresponds to a given artifact, that attestation is immutable and cannot be -overwritten later with a different attestation that refers to the same -artifact. Instead, a new release (and new artifacts) SHOULD be created. - -## Format of the attestation - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto [SLSA Provenance](/provenance), but -another format MAY be used if both producer and consumer agree and it meets all -the other requirements. - -## Considerations for source-based ecosystems - -Some ecosystems have support for installing directly from source repositories -(an option for Python/`pip`, Go, etc.). In these cases, there is no need to -publish or verify provenance because there is no "build" step that translates -between a source repository and an artifact that is being installed. - -However, for ecosystems that install from source repositories _via_ some -intermediary (e.g., [Homebrew installing from GitHub release artifacts generated -from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go -installing through the Go module proxy](https://proxy.golang.org/)), these -ecosystems distribute "source archives" that are not the bit-for-bit identical -form from version control. These intermediaries are transforming the original -source repository in some way that constitutes a "build" and as a result SHOULD -be providing build provenance for this "package", and the recommendations -outlined here apply. - -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.1-rc2/faq.md b/docs/spec/v1.1-rc2/faq.md deleted file mode 100644 index 90ed7bb8c..000000000 --- a/docs/spec/v1.1-rc2/faq.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Frequently asked questions -description: Answers to questions frequently asked about SLSA. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build platforms to -corroborate the provenance of a build. In this way, one can create an overall -platform that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a platform can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. - -## Q. What is the difference between a build platform, system, and service? - -Build platform and build system have been used interchangeably in the past. With -the v1.0 specification, however, there has been a unification around the term -platform as indicated in the [Terminology](terminology.md). The use of the word -`system` still exists related to software and services within the build platform -and to systems outside of a build platform like change management systems. - -A build service is a hosted build platform that is often run on shared infrastructure -instead of individuals' machines and workstations. Its use has also been replaced outside -of the requirements as it relates to the build platform. - -## Q: Is SLSA the same as TACOS? - -No. -[Trusted Attestation and Compliance for Open Source (TACOS)](https://github.com/tacosframework) -is a framework authored by Tidelift. -Per their website, TACOS is a framework -"for assessing the development practices of open source projects -against a set of secure development standards specified by the (US) -NIST Secure Software Development Framework (SSDF) V1.1" which -"vendors can use to provide self-attestation for the open source components -they rely on." - -In contrast, SLSA is a community-developed framework---including -adoptable guidelines for securing a software supply chain and -mechanism to evaluate the trustworthiness of artifacts you consume---that -is part of the Open Source Security Foundation (OpenSSF). - -## Q: How does SLSA and SLSA Provenance relate to SBOM? - -[Software Bill of Materials (SBOM)] are a frequently recommended tool for -increased software supply chain rigor. An SBOM is typically focused on -understanding software in order to evaluate risk through known vulnerabilities -and license compliance. These use-cases require fine-grained and timely data -which can be refined to improve signal-to-noise ratio. - -[SLSA Provenance] and the [Build track] are focused on trustworthiness of the -build process. To improve trustworthiness, Provenance is generated in the build -platform's trusted control plane, which in practice results in it being coarse -grained. For example, in Provenance metadata completeness of -`resolvedDependencies` information is on a best-effort basis. Further, the -`ResourceDescriptor` type does not require version and license information or -even a URI to the dependency's original location. - -While they likely include similar data, SBOMs and SLSA Provenance operate at -different levels of abstraction. The fine-grained data in an SBOM typically -describes the components present in a produced artifact, whereas SLSA -Provenance more coarsely describes parameters of a build which are external to -the build platform. - -The granularity and expressiveness of the two use-cases differs enough that -current SBOM formats were deemed not a good fit for the requirements of -the Build track. Yet SBOMs are a good practice and may form part of a future -SLSA Vulnerabilities track. Further, SLSA Provenance can increase the -trustworthiness of an SBOM by describing how the SBOM was created. - -SLSA Provenance, the wider [in-toto Attestation Framework] in which the -recommended format sits, and the various SBOM standards, are all rapidly -evolving spaces. There is ongoing investigation into linking between the -different formats and exploration of alignment on common models. This FAQ entry -describes our understanding of the intersection efforts today. We do not know -how things will evolve over the coming months and years, but we look forward to -the collaboration and improved software supply chain security. - -## Q: How to SLSA with a self-hosted runner - -Some CI systems allow producers to provide their own self-hosted runners as a build -environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage -these, classifying the SLSA build level for the resulting artifact can be confusing. - -Since the SLSA Build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance, interpretation of the -specification hinges on the platform entities involved in the provenance generation. -The SLSA [build level requirements] (secure key storage, isolation, etc.) should be -imposed on the transitive closure of the systems which are responsible for informing -the provenance generated. - -Some common situations may include: - -- The platform generates the provenance and just calls a runner for individual items. - In this situation, the provenance is only affected by the platform so there would be - no requirements imposed on the runner. -- The runner generates the provenance. In this situation, the orchestrating platform - is irrelevant and all requirements are imposed on the runner. -- The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance. Trust is - shared between the platform and the runner so the requirements are imposed on both. - -Additional requirements on the self-hosted runners may be added to Build levels -greater than L3 when such levels get defined. - -[build level requirements]: requirements.md -[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners -[Software Bill of Materials (SBOM)]: https://ntia.gov/sbom -[SLSA Provenance]: provenance.md -[Build track]: levels.md#build-track -[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/ diff --git a/docs/spec/v1.1-rc2/future-directions.md b/docs/spec/v1.1-rc2/future-directions.md deleted file mode 100644 index 217f3302c..000000000 --- a/docs/spec/v1.1-rc2/future-directions.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Future directions -description: The initial draft version (v0.1) of SLSA had a larger scope including protections against tampering with source code and a higher level of build integrity (Build L4). This page collects some early thoughts on how SLSA **might** evolve in future versions to re-introduce these notions and add other additional aspects of automatable supply chain security. ---- - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future versions to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build platform and enabling -corroboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream verifiers - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other build platforms to corroborate the - provenance. - -
- -
- -## Platform Operations track - -A Platform Operations track could provide assurances around the hardening of -platforms (e.g. build or source platforms) as they are operated. - -The initial [draft version (v0.1)] of SLSA included a section on -[common requirements](../v0.1/requirements.md#common-requirements) that formed -the foundation of the guidance for -[verifying build systems](verifying-systems.md), which **may or may not** form -the basis for a future Build Platform Operations track: - -- Controls for approval, logging, and auditing of all physical and remote - access to platform infrastructure, cryptographic secrets, and privileged - debugging interfaces. -- Conformance to security best practices to minimize the risk of compromise. -- Protection of cryptographic secrets used by the build platform. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md - -## Source Track - -The SLSA Source track will describe increasing levels of trustworthiness and completeness in a repository revision's provenance (e.g. how it was generated, who the contributors were, etc). - -The Source track will be scoped to revisions of a single repository. -The intent of each revision is determined by the [software producer](terminology.md#roles) who is also responsible for declaring which Source level should apply and administering technical controls to enforce that level. - -The primary purpose of the Source track will be to enable verification that the creation of a revision followed the producer's intended process. -Consumers will be able to examine source provenance attestations to determine if a revision meets their requirements. diff --git a/docs/spec/v1.1-rc2/images/build-model.svg b/docs/spec/v1.1-rc2/images/build-model.svg deleted file mode 100644 index 9d6bed6ca..000000000 --- a/docs/spec/v1.1-rc2/images/build-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1-rc2/images/provenance-model.svg b/docs/spec/v1.1-rc2/images/provenance-model.svg deleted file mode 100644 index 028dad49e..000000000 --- a/docs/spec/v1.1-rc2/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1-rc2/images/supply-chain-model.svg b/docs/spec/v1.1-rc2/images/supply-chain-model.svg deleted file mode 100644 index 6a37ffa05..000000000 --- a/docs/spec/v1.1-rc2/images/supply-chain-model.svg +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1-rc2/images/supply-chain-threats-build-verification.svg b/docs/spec/v1.1-rc2/images/supply-chain-threats-build-verification.svg deleted file mode 100644 index 2888f6215..000000000 --- a/docs/spec/v1.1-rc2/images/supply-chain-threats-build-verification.svg +++ /dev/null @@ -1,88 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1-rc2/images/supply-chain-threats.svg b/docs/spec/v1.1-rc2/images/supply-chain-threats.svg deleted file mode 100644 index 38421111d..000000000 --- a/docs/spec/v1.1-rc2/images/supply-chain-threats.svg +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1-rc2/images/verification-model.svg b/docs/spec/v1.1-rc2/images/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.1-rc2/images/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1-rc2/index.md b/docs/spec/v1.1-rc2/index.md deleted file mode 100644 index 731a55fab..000000000 --- a/docs/spec/v1.1-rc2/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: SLSA specification -description: SLSA is a specification for describing and incrementally improving supply chain security, established by industry consensus. It is organized into a series of levels that describe increasing security guarantees. This is **version 1.1 RC2** of the SLSA specification. ---- - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **Version 1.1 Release Candidate 2 (RC2)** of the SLSA -specification, which defines several SLSA levels and recommended attestation -formats, including provenance. - -{%- for section in site.data.nav.main %} -{%- if section.url == page.url %} -{%- for subsection in section.children %} -{%- if subsection.children %} - -## {{ subsection.title }} - -{{ subsection.description }} - - - -| Page | Description -| ---- | ----------- -{%- for child in subsection.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} -{%- endfor %} - - -{%- endif %} -{%- endfor %} -{%- endif %} -{%- endfor %} diff --git a/docs/spec/v1.1-rc2/levels.md b/docs/spec/v1.1-rc2/levels.md deleted file mode 100644 index ebc1d3bef..000000000 --- a/docs/spec/v1.1-rc2/levels.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: Security levels -description: SLSA is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This page is a descriptive overview of the SLSA levels and tracks, describing their intent. ---- - -SLSA is organized into a series of levels that provide increasing supply chain -security guarantees. This gives you confidence that software hasn’t been -tampered with and can be securely traced back to its source. - -This page is a descriptive overview of the SLSA levels and tracks, describing -their intent. For the prescriptive requirements for each level, see -[Requirements](requirements.md). For a general overview of SLSA, see -[About SLSA](principles.md). - -## Levels and tracks - -SLSA levels are split into *tracks*. Each track has its own set of levels that -measure a particular aspect of supply chain security. The purpose of tracks is -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 - - - -> 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 -> Build track. A Source track may be added in [future versions]. - -## Build track - -The SLSA build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance. Provenance describes -what entity built the artifact, what process they used, and what the inputs -were. The lowest level only requires the provenance to exist, while higher -levels provide increasing protection against tampering of the build, the -provenance, or the artifact. - -The primary purpose of the build track is to enable [verification] that the -artifact was built as expected. Consumers have some way of knowing what the -expected provenance should look like for a given package and then compare each -package artifact's actual provenance to those expectations. Doing so prevents -several classes of [supply chain threats](threats.md). - -Each ecosystem (for open source) or organization (for closed source) defines -exactly how this is implemented, including: means of defining expectations, what -provenance format is accepted, whether reproducible builds are used, how -provenance is distributed, when verification happens, and what happens on -failure. Guidelines for implementers can be found in the -[requirements](requirements.md). - -
- -### Build L0: No guarantees - -
-
Summary
- -No requirements---L0 represents the lack of SLSA. - -
Intended for
- -Development or test builds of software that are built and run on the same -machine, such as unit tests. - -
Requirements
- -n/a - -
Benefits
- -n/a - -
-
-
- -### Build L1: Provenance exists - -
-
Summary
- -Package has provenance showing how it was built. Can be used to prevent mistakes -but is trivial to bypass or forge. - -
Intended for
- -Projects and organizations wanting to easily and quickly gain some benefits of -SLSA---other than tamper protection---without changing their build workflows. - -
Requirements
- -- Software Producer: - - Follow a consistent build process so that others can form - expectations about what a "correct" build looks like. - - Run builds on a build platform that meets Build L1 requirements. - - Distribute provenance to consumers, preferably using a convention - determined by the package ecosystem. -- Build platform: - - Automatically generate [provenance] describing how the artifact was - built, including: what entity built the package, what build process - they used, and what the top-level input to the build were. - -
Benefits
- -- Makes it easier for both producers and consumers to debug, patch, rebuild, - and/or analyze the software by knowing its precise source version and build - process. - -- With [verification], prevents mistakes during the release process, such as - building from a commit that is not present in the upstream repo. - -- Aids organizations in creating an inventory of software and build platforms - used across a variety of teams. - -
Notes
- -- Provenance may be incomplete and/or unsigned at L1. Higher levels require - more complete and trustworthy provenance. - -
- -
-
- -### Build L2: Hosted build platform - -
-
Summary
- -Forging the provenance or evading verification requires an explicit "attack", -though this may be easy to perform. Deters unsophisticated adversaries or those -who face legal or financial risk. - -In practice, this means that builds run on a hosted platform that generates and -signs[^sign] the provenance. - -
Intended for
- -Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build platform, while waiting for changes to the build -platform itself required by [Build L3]. - -
Requirements
- -All of [Build L1], plus: - -- Software producer: - - Run builds on a [hosted] build platform that meets Build L2 - requirements. -- Build platform: - - Generate and sign[^sign] the provenance itself. This may be done - during the original build, an after-the-fact reproducible build, or - some equivalent system that ensures the trustworthiness of the - provenance. -- Consumer: - - Validate the authenticity of the provenance. - -
Benefits
- -All of [Build L1], plus: - -- Prevents tampering after the build through digital signatures[^sign]. - -- Deters adversaries who face legal or financial risk by evading security - controls, such as employees who face risk of getting fired. - -- Reduces attack surface by limiting builds to specific build platforms that - can be audited and hardened. - -- Allows large-scale migration of teams to supported build platforms early - while further hardening work ([Build L3]) is done in parallel. - -
-
-
- -[^sign]: Alternate means of verifying the authenticity of the provenance are - also acceptable. - -### Build L3: Hardened builds - -
-
Summary
- -Forging the provenance or evading verification requires exploiting a -vulnerability that is beyond the capabilities of most adversaries. - -In practice, this means that builds run on a hardened build platform that offers -strong tamper protection. - -
Intended for
- -Most software releases. Build L3 usually requires significant changes to -existing build platforms. - -
Requirements
- -All of [Build L2], plus: - -- Software producer: - - Run builds on a hosted build platform that meets Build L3 - requirements. -- Build platform: - - Implement strong controls to: - - prevent runs from influencing one another, even within the same - project. - - prevent secret material used to sign the provenance from being - accessible to the user-defined build steps. - -
Benefits
- -All of [Build L2], plus: - -- Prevents tampering during the build---by insider threats, compromised - credentials, or other tenants. - -- Greatly reduces the impact of compromised package upload credentials by - requiring the attacker to perform a difficult exploit of the build process. - -- Provides strong confidence that the package was built from the official - source and build process. - -
-
- - - -[build l0]: #build-l0 -[build l1]: #build-l1 -[build l2]: #build-l2 -[build l3]: #build-l3 -[future versions]: future-directions.md -[hosted]: requirements.md#isolation-strength -[previous version]: ../v0.1/levels.md -[provenance]: terminology.md -[verification]: verifying-artifacts.md diff --git a/docs/spec/v1.1-rc2/onepage.md b/docs/spec/v1.1-rc2/onepage.md deleted file mode 100644 index 083823471..000000000 --- a/docs/spec/v1.1-rc2/onepage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SLSA specification -description: A one-page rendering of all that is included in SLSA v1.1 RC2. -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.1-rc2/" %} -{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,terminology,levels,requirements,distributing-provenance,verifying-artifacts,verifying-systems,threats,attestation-model,provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.1-rc2/principles.md b/docs/spec/v1.1-rc2/principles.md deleted file mode 100644 index ae1408d65..000000000 --- a/docs/spec/v1.1-rc2/principles.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Guiding principles -description: An introduction to the guiding principles behind SLSA's design decisions. ---- - -This page is an introduction to the guiding principles behind SLSA's design -decisions. - -## Simple levels with clear outcomes - -Use [levels](levels) to communicate security state and to encourage a large -population to improve its security stance over time. When necessary, split -levels into separate tracks to recognize progress in unrelated security areas. - -**Reasoning:** Levels simplify how to think about security by boiling a complex -topic into an easy-to-understand number. It is clear that level N is better than -level N-1, even to someone with passing familiarity. This provides a convenient -way to describe the current security state as well as a natural path to improvement. - -Guidelines: - -- **Define levels in terms of concrete security outcomes.** Each level should - have clear and meaningful security value, such as stopping a particular - class of threats. Levels should represent security milestones, not just - incremental progress. Give each level an easy-to-remember mnemonic, such as - "Provenance exists." - -- **Balance level granularity.** Too many levels makes SLSA hard to understand - and remember; too few makes each level hard to achieve. Collapse levels - until each step requires a non-trivial but manageable amount of work to - implement. Separate levels if they require significant work from multiple - distinct parties, such as infrastructure work plus user behavior changes, so - long as the intermediate level still has some security value (prior bullet). - -- **Use tracks sparingly.** Additional tracks add extra complexity to SLSA, so - a new track should be seen as a last resort. Each track should have a clear, - distinct purpose with a crisply defined objective, such as trustworthy - provenance for the [Build track](levels#build-track). As a rule of thumb, a - new track may be warranted if it addresses threats unrelated to another - track. Try to avoid tracks that sound confusingly similar in either name or - objective. - -## Trust platforms, verify artifacts - -Establish trust in a small number of platforms and systems---such as change management, build, -and packaging platforms---and then automatically verify the many artifacts -produced by those platforms. - -**Reasoning**: Trusted computing bases are unavoidable---there's no choice but -to trust some platforms. Hardening and verifying platforms is difficult and -expensive manual work, and each trusted platform expands the attack surface of the -supply chain. Verifying that an artifact is produced by a trusted platform, -though, is easy to automate. - -To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited -number of platforms and then automate verification of the artifacts produced by those platforms. -The attack surface and work to establish trust do not scale with the number of artifacts produced, -as happens when artifacts each use a different trusted platform. - -**Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant -amount of central work. - -### Example - -A security engineer analyzes the architecture and implementation of a build -platform to ensure that it meets the SLSA Build Track requirements. Following the -analysis, the public keys used by the build platform to sign provenance are -"trusted" up to the given SLSA level. Downstream platforms verify the provenance -signed by the public key to automatically determine that an artifact meets the -SLSA level. - -### Corollary: Minimize the number of trusted platforms - -A corollary to this principle is to minimize the size of the trusted computing -base. Every platform we trust adds attack surface and increases the need for -manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team within an organization maintaining their own build platform, use a - shared build platform. Hardening work can be shared across all teams. -- Remove the need to trust components. For example, use end-to-end signing - to avoid the need to trust intermediate distribution platforms. - -## Trust code, not individuals - -Securely trace all software back to source code rather than trust individuals who have write access to package registries. - -**Reasoning**: Code is static and analyzable. People, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. - -**Benefits**: Removes the possibility for a trusted individual---or an -attacker abusing compromised credentials---to tamper with source code -after it has been committed. - -## Prefer attestations over inferences - -Require explicit attestations about an artifact's provenance; do not infer -security properties from a platform's configurations. - -**Reasoning**: Theoretically, access control can be configured so that the only path from -source to release is through the official channels: the CI/CD platform pulls only -from the proper source, package registry allows access only to the CI/CD platform, -and so on. We might infer that we can trust artifacts produced by these platforms -based on the platform's configuration. - -In practice, though, these configurations are almost impossible to get right and -keep right. There are often over-provisioning, confused deputy problems, or -mistakes. Even if a platform is configured properly at one moment, it might not -stay that way, and humans almost always end up getting in the access control -lists. - -Access control is still important, but SLSA goes further to provide defense in depth: it **requires proof in -the form of attestations that the package was built correctly**. - -**Benefits**: The attestation removes intermediate platforms from the trust base and ensures that -individuals who are accidentally granted access do not have sufficient permission to tamper with the package. - -## Support anonymous and pseudonymous contributions - -SLSA supports anonymous and pseudonymous 'identities' within the software supply chain. -While organizations that implement SLSA may choose otherwise, SLSA itself does not require, -or encourage, participants to be mapped to their legal identities. - -**Nothing in this specification should be taken to mean that SLSA requires participants to -reveal their legal identity.** - -**Reasoning**: SLSA uses identities for multiple purposes: as a trust anchor for attestations -(i.e. who or what is making this claim and do I trust it to do so) or for attributing actions -to an actor. Choice of identification technology is left to the organization and technical -stacks implementing the SLSA standards. - -When identities are strongly authenticated and used consistently they can often be leveraged -for both of these purposes without requiring them to be mapped to legal identities. -This reflects how identities are often used in open source where legal name means much less -to projects than the history and behavior of a given handle over time does. Meanwhile, some -organizations may choose to levy additional requirements on identities. They are free to do -so, but SLSA itself does not require it. - -**Benefits**: By _not_ requiring legal identities SLSA lowers the barriers to its adoption, -enabling all of its other benefits and maintaining support for anonymous and pseudonymous -contribution as has been practiced in the software industry for decades. diff --git a/docs/spec/v1.1-rc2/provenance.md b/docs/spec/v1.1-rc2/provenance.md deleted file mode 100644 index d8fe5dceb..000000000 --- a/docs/spec/v1.1-rc2/provenance.md +++ /dev/null @@ -1,599 +0,0 @@ ---- -title: Provenance -description: Description of SLSA provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when, and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](requirements#provenance-generation). - -## Model - -Provenance is an attestation that a particular build platform produced a set of -software artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant build platform. - The `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build platforms.) - - - The build platform implementer SHOULD define a security model for the build - platform in order to clearly identify the platform's boundaries, actors, - and interfaces. This model SHOULD then be used to identify the transitive - closure of the trusted build platform for the `builder.id` as well as the - trusted control plane. - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - platform ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `internalParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](requirements.md). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." - Such changes do not update the `predicateType`. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -### Summary - -*NOTE: This summary (in cue) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -*NOTE: This summary (in protobuf) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - -Link: [provenance.proto](schema/provenance.proto) - -*NOTE: This protobuf definition prioritizes being a human-readable summary -of the schema for readers of the specification. A version of the protobuf -definition useful for code generation is maintained in the -[in-toto attestation] repository.* - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`internalParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that -there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build platform SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
internalParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build platform is already trusted, and in many cases it is -not practical to do so. - -
resolvedDependencies -array (ResourceDescriptor) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script -fetches and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be -listed here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `internalParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `internalParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build platform. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build platform to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build platform to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the build platform that executed the invocation, which is trusted to -have correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ResourceDescriptor) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or -incident response. For example, this might reference logs generated during -the build and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted build platform. This is -[intended](verifying-artifacts#step-1-check-slsa-build-level) -to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -The `builder.id` URI SHOULD resolve to documentation explaining: - -- The scope of what this ID represents. -- The claimed SLSA Build level. -- The accuracy and completeness guarantees of the fields in the provenance. -- Any fields that are generated by the tenant-controlled build process and not - verified by the trusted control plane, except for the `subject`. -- The interpretation of any extension fields. - -
builderDependencies -array (ResourceDescriptor) - -Dependencies used by the orchestrator that are not run within the workload -and that do not affect the build, but might affect the provenance generation -or security guarantees. - -
version -map (string→string) - -Map of names of components of the build platform to their version. - -
- -The build platform, or builder for short, represents the transitive -closure of all the entities that are, by necessity, [trusted] to faithfully run -the build and record the provenance. This includes not only the software but the -hardware and people involved in running the service. For example, a particular -instance of [Tekton](https://tekton.dev/) could be a build platform, while -Tekton itself is not. For more info, see [Build -model](terminology#build-model). - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -### Extension fields - -[Extension fields]: #extension-fields - -Implementations MAY add extension fields to any JSON object to describe -information that is not captured in a standard field. Guidelines: - -- Extension fields SHOULD use names of the form `_`, e.g. - `examplebuilder_isCodeReviewed`. This practice avoids field name collisions - by namespacing each vendor. Non-extension field names never contain an - underscore. -- Extension fields MUST NOT alter the meaning of any other field. In other - words, an attestation with an absent extension field MUST be interpreted - identically to an attestation with an unrecognized (and thus ignored) - extension field. -- Extension fields SHOULD follow the [monotonic principle][parsing rules], - meaning that deleting or ignoring the extension SHOULD NOT turn a DENY - decision into an ALLOW. - -## Verification - -[Verification]: verifying-artifacts - -Please see [Verifying Artifacts][Verification] for a detailed discussion of -provenance verification. - -## Index of build types - -The following is a partial index of build type definitions. Each contains a -complete example predicate. - - - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) -- [Google Cloud Build (community-maintained)](https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1) - -To add an entry here, please send a pull request on GitHub. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "internalParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "builderDependencies": null, // not in v0.2 - "version": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.0 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build platforms, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed: - - `parameters` -> `externalParameters` (slight change in semantics) - - `environment` -> `internalParameters` (slight change in semantics) - - `materials` -> `resolvedDependencies` (slight change in semantics) - - `buildInvocationId` -> `invocationId` - - `buildStartedOn` -> `startedOn` - - `buildFinishedOn` -> `finishedOn` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - ResourceDescriptor: `annotations`, `content`, `downloadLocation`, - `mediaType`, `name` - - Builder: `builderDependencies` and `version` - - `byproducts` -- Changed naming convention for extension fields. - -Differences from RC1 and RC2: - -- Renamed `systemParameters` (RC1 + RC2) -> `internalParameters` (final). -- Changed naming convention for extension fields (in RC2). -- Renamed `localName` (RC1) -> `name` (RC2). -- Added `annotations` and `content` (in RC2). - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: threats -[trusted]: principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.1-rc2/requirements.md b/docs/spec/v1.1-rc2/requirements.md deleted file mode 100644 index c0a72d931..000000000 --- a/docs/spec/v1.1-rc2/requirements.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -title: Producing artifacts -description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers. ---- - - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is platform implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Levels](levels.md). For background, see [Terminology](terminology.md). To -better understand the reasoning behind the requirements, see -[Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -In order to produce artifacts with a specific build level, responsibility is -split between the [Producer] and [Build platform]. The build platform MUST -strengthen the security controls in order to achieve a specific level while the -producer MUST choose and adopt a build platform capable of achieving a desired -build level, implementing any controls as specified by the chosen platform. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build platform - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build platform - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Unforgeable - ✓ -
Isolation strength - Hosted - ✓✓ -
Isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure platform is beyond the -scope of this specification, all implementations MUST use industry security -best practices to be conformant to this specification. This includes, but is -not limited to, using proper access controls, securing communications, -implementing proper management of cryptographic secrets, doing frequent updates, -and promptly fixing known vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -NOTE: There were more requirements for producers in the initial -[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted -how a package can be built. These were removed in the v1.0 specification and -will be reassessed and re-added as indicated in the -[future directions](future-directions.md). - -### Choose an appropriate build platform - -The producer MUST select a build platform that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -If a producer wishes to distribute their artifact through a [package ecosystem] -that requires explicit metadata about the build process in the form of a -configuration file, the producer MUST complete the configuration file and keep -it up to date. This metadata might include information related to the artifact's -source repository and build parameters. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the -[package ecosystem], provided that the package ecosystem is capable of -distributing provenance. - -## Build Platform - -[Build platform]: #build-platform - -A package's build platform is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build platform is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build platform used -by a single software project, or even an individual's workstation. Ideally, one -build platform is used by many different software packages so that consumers can -[minimize the number of trusted platforms](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build platform is responsible for providing two things: [provenance -generation] and [isolation between builds]. The [Build level](levels.md#build-track) describes -the degree to which each of these properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build platform is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the overall provenance integrity according to -minimum requirements on its: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package by cryptographic digest and describes how that package was -produced. The format MUST be acceptable to the [package ecosystem] and/or -[consumer](verifying-artifacts.md#consumer). - -It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. - -If using an alternate format, it MUST contain the equivalent information as SLSA -Provenance at each level and SHOULD be bi-directionally translatable to SLSA -Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build platform and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only -to the build platform component that generated the provenance attestation. - -While many constraints affect choice of signing methodologies, it is -RECOMMENDED that build platforms use signing methodologies which improve the -ability to detect and remediate key compromise, such as methods which rely on -transparency logs or, when transparency isn't appropriate, time stamping -services. - -Authenticity allows the consumer to trust the contents of the provenance -attestation, such as the identity of the build platform. - -*Accuracy:* The provenance MUST be generated by the control plane (i.e. within -the trust boundary [identified in the provenance]) and not by a tenant of the -build platform (i.e. outside the trust boundary), except as noted below. - -- The data in the provenance MUST be obtained from the build platform, either - because the generator *is* the build platform or because the provenance - generator reads the data directly from the build platform. -- The build platform MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. -- Exceptions for fields that MAY be generated by a tenant of the build platform: - - The names and cryptographic digests of the output artifacts, i.e. - `subject` in [SLSA Provenance]. See [forge output digest of the - provenance](threats#forged-digest) for explanation of why this is - acceptable. - - Any field that is not marked as REQUIRED for Build L2. For example, - `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at - Build L2. Builders SHOULD document any such cases of tenant-generated - fields. - -*Completeness:* SHOULD be complete. - -- There MAY be [external parameters] that are not sufficiently captured in - the provenance. -- Completeness of resolved dependencies is best effort. - - ✓✓ -
Provenance is Unforgeable - -*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. - -- Any secret material used for authenticating the provenance, for example the - signing key used to generate a digital signature, MUST be stored in a secure - management system appropriate for such material and accessible only to the - build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - platform in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted in [Provenance - is Authentic](#provenance-authentic). (Build L3 does not require additional - fields beyond those of L2.) - -*Completeness:* SHOULD be complete. - -- [External parameters] MUST be fully enumerated. -- Completeness of resolved dependencies is best effort. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build platform is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build platform's isolation strength, see -[Verifying build platforms](verifying-systems.md). - - - - -
RequirementDescriptionL1L2L3 - -
Hosted - - -All build steps ran using a hosted build platform on shared or dedicated -infrastructure, not on an individual's workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Isolated - - -The build platform ensured that the build steps ran in an isolated environment, -free of unintended external influence. In other words, any external influence on -the build was specifically requested by the build itself. This MUST hold true -even between builds within the same tenant project. - -The build platform MUST guarantee the following: - -- It MUST NOT be possible for a build to access any secrets of the build - platform, such as the provenance signing key, because doing so would - compromise the authenticity of the provenance. -- It MUST NOT be possible for two builds that overlap in time to influence one - another, such as by altering the memory of a different build process running - on the same machine. -- It MUST NOT be possible for one build to persist or influence the build - environment of a subsequent build. In other words, an ephemeral build - environment MUST be provisioned for each build. -- It MUST NOT be possible for one build to inject false entries into a build - cache used by another build, also known as "cache poisoning". In other - words, the output of the build MUST be identical whether or not the cache is - used. -- The build platform MUST NOT open services that allow for remote influence - unless all such interactions are captured as `externalParameters` in the - provenance. - -There are no sub-requirements on the build itself. Build L3 is limited to -ensuring that a well-intentioned build runs securely. It does not require that -a build platform prevents a producer from performing a risky or insecure build. In -particular, the "Isolated" requirement does not prohibit a build from calling -out to a remote execution service or a "self-hosted runner" that is outside the -trust boundary of the build platform. - -NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" -in the initial [draft version (v0.1)](../v0.1/requirements.md). - -NOTE: This requirement is not to be confused with "Hermetic", which roughly -means that the build ran with no network access. Such a requirement requires -substantial changes to both the build platform and each individual build, and is -considered in the [future directions](future-directions.md). - - ✓ -
- -[external parameters]: provenance.md#externalParameters -[identified in the provenance]: provenance.md#model -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.1-rc2/schema/provenance.cue b/docs/spec/v1.1-rc2/schema/provenance.cue deleted file mode 100644 index 22bc5e0d8..000000000 --- a/docs/spec/v1.1-rc2/schema/provenance.cue +++ /dev/null @@ -1,48 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "internalParameters": object, - "resolvedDependencies": [ ...#ResourceDescriptor ], - }, - "runDetails": { - "builder": { - "id": string, - "builderDependencies": [ ...#ResourceDescriptor ], - "version": { ...string }, - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ResourceDescriptor ], - } - } -} - -#ResourceDescriptor: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "gitCommit": string, - [string]: string, - }, - "name": string, - "downloadLocation": string, - "mediaType": string, - "content": bytes, // base64-encoded - "annotations": { - [string]: _ // any JSON type - } -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.1-rc2/schema/provenance.proto b/docs/spec/v1.1-rc2/schema/provenance.proto deleted file mode 100644 index ae0a71ee1..000000000 --- a/docs/spec/v1.1-rc2/schema/provenance.proto +++ /dev/null @@ -1,50 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct internal_parameters = 3; - repeated ResourceDescriptor resolved_dependencies = 4; -} - -message ResourceDescriptor { - string uri = 1; - map digest = 2; - string name = 3; - string download_location = 4; - string media_type = 5; - bytes content = 6; - map annotations = 7; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ResourceDescriptor byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ResourceDescriptor builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.1-rc2/terminology.md b/docs/spec/v1.1-rc2/terminology.md deleted file mode 100644 index ba1af593c..000000000 --- a/docs/spec/v1.1-rc2/terminology.md +++ /dev/null @@ -1,342 +0,0 @@ ---- -title: Terminology -description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting. ---- - - -Before diving into the [SLSA Levels](levels.md), we need to establish a core set -of terminology and models to describe what we're protecting. - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). -| [Distribution] | The channel through which artifacts are "published" for use by others. | A registry like DockerHub or npm. Artifacts may also be distributed via physical media (e.g., a USB drive). -| Package | Artifact that is distributed. 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 (distribution). 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 -[distribution]: #distribution-model -[SLSA Provenance]: /provenance/v1 - -### Roles - -Throughout the specification, you will see reference to the following roles -that take part in the software supply chain. Note that in practice a role may -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. - -### Build model - -

Model Build

- -We model a build as running on a multi-tenant *build platform*, where each -execution is independent. - -1. A tenant invokes the build by specifying *external parameters* through an - *interface*, either directly or via some trigger. Usually, at least one of - these external parameters is a reference to a *dependency*. (External - parameters are literal values while dependencies are artifacts.) -2. The build platform's *control plane* interprets these external parameters, - fetches an initial set of dependencies, initializes a *build environment*, - and then starts the execution within that environment. -3. The build then performs arbitrary steps, which might include fetching - additional dependencies, and then produces one or more *output* artifacts. - The steps within the build environment are under the tenant's control. - The build platform isolates build environments from one another to some - degree (which is measured by the SLSA Build Level). -4. Finally, for SLSA Build L2+, the control plane outputs *provenance* - describing this whole process. - -Notably, there is no formal notion of "source" in the build model, just external -parameters and dependencies. Most build platforms have an explicit "source" -artifact to build from, which is often a git repository; in the build model, the -reference to this artifact is an external parameter while the artifact itself is -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. - -
Ambiguous terms to avoid - -- *Build recipe:* Could mean *external parameters,* but may include concrete - steps of how to perform a build. To avoid implementation details, we don't - define this term, but always use "external parameters" which is the - interface to a build platform. Similar terms are *build configuration - source* and *build definition*. -- *Builder:* Usually means *build platform*, but might be used for *build - environment*, the user who invoked the build, or a build tool from - *dependencies*. To avoid confusion, we always use "build platform". The only - exception is in the [provenance](/provenance/v1), where `builder` is used as - a more concise field name. - -
- -### Distribution model - -Software is distributed in identifiable units called packages -according to the rules and conventions of a package ecosystem. -Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and -[OCI](https://github.com/opencontainers/distribution-spec), while examples of -informal ecosystems include links to files on a website or distribution of -first-party software within a company. - -Abstractly, a consumer locates software within an ecosystem by asking a -distribution platform, such as a package registry, to resolve a -mutable package name into an immutable package artifact. -[^label] To publish a package artifact, the software producer asks -the registry to update this mapping to resolve to the new artifact. The registry -represents the entity or entities with the power to alter what artifacts are -accepted by consumers for a given package name. For example, if consumers only -accept packages signed by a particular public key, then it is access to that -public key that serves as the registry. - -The package name is the primary security boundary within a package ecosystem. -Different package names represent materially different pieces of -software---different owners, behaviors, security properties, and so on. -Therefore, **the package name is the primary unit being protected in SLSA**. -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 -| ---- | ----------- -| Distribution platform | An entity responsible for mapping package names to immutable package artifacts. -| 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 | A specific type of "distribution platform" used 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 - -- *Package repository:* Could mean either package registry or package name, - depending on the ecosystem. To avoid confusion, we always use "repository" - exclusively to mean "source repository", where there is no ambiguity. -- *Package manager* (without "client"): Could mean either package ecosystem, - package registry, or client-side tooling. - -
- -### Mapping to real-world ecosystems - -Most real-world ecosystems fit the package model above but use different terms. -The table below attempts to document how various ecosystems map to the SLSA -Package model. There are likely mistakes and omissions; corrections and -additions are welcome! - - - - - - - - - - - - - - - - - - - - - - - - - - -
Package ecosystem - Package registry - Package name - Package artifact -
Languages -
Cargo (Rust) - Registry - Crate name - Artifact -
CPAN (Perl) - PAUSE - Distribution - Release (or Distribution) -
Go - Module proxy - Module path - Module -
Maven (Java) - Repository - Group ID + Artifact ID - Artifact -
npm (JavaScript) - Registry - Package Name - Package -
NuGet (C#) - Host - Project - Package -
PyPA (Python) - Index - Project Name - Distribution -
Operating systems -
Dpkg (e.g. Debian) - ? - Package name - Package -
Flatpak - Repository - Application - Bundle -
Homebrew (e.g. Mac) - Repository (Tap) - Package name (Formula) - Binary package (Bottle) -
Pacman (e.g. Arch) - Repository - Package name - Package -
RPM (e.g. Red Hat) - Repository - Package name - Package -
Nix (e.g. NixOS) - Repository (e.g. Nixpkgs) or binary cache - Derivation name - Derivation or store object -
Storage systems -
GCS - n/a - Object name - Object -
OCI/Docker - Registry - Repository - Object -
Meta -
deps.dev: System - Packaging authority - Package - n/a -
purl: type - Namespace - Name - n/a -
- -Notes: - -- Go uses a significantly different distribution model than other ecosystems. - In Go, the package name is a source repository URL. While clients can fetch - directly from that URL---in which case there is no "package" or - "registry"---they usually fetch a zip file from a *module proxy*. The module - proxy acts as both a builder (by constructing the package artifact from - source) and a registry (by mapping package name to package artifact). People - trust the module proxy because builds are independently reproducible, and a - *checksum database* guarantees that all clients receive the same artifact - for a given URL. - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build platform is -certified to ensure conformance with the requirements at the level claimed by -the build platform. This certification should happen on a recurring cadence, with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer-defined -expectations of where the package source code was retrieved from and on what -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. - -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. - -
- -
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. - -
diff --git a/docs/spec/v1.1-rc2/threats-overview.md b/docs/spec/v1.1-rc2/threats-overview.md deleted file mode 100644 index 8b2d04a25..000000000 --- a/docs/spec/v1.1-rc2/threats-overview.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Supply chain threats -description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA could help. ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA could help. For a more technical discussion, see [Threats & mitigations](threats.md). - -## Summary - -![Supply Chain Threats](images/supply-chain-threats.svg) - -**Note that SLSA does not currently address all of the threats presented here.** -See [Threats & mitigations](threats.md) for what is currently addressed and -[Terminology](terminology.md) for an explanation of the supply chain model. - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that the source revision represents the intent of the producer, that all expected processes were followed and that the revision was not modified after being accepted. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - - - -
-Threats from -Known example -How SLSA could help -
A -Producer -SpySheriff: Software producer purports to offer anti-spyware software, but that software is actually malicious. -SLSA does not directly address this threat but could make it easier to discover malicious behavior in open source software, by forcing it into the publicly available source code. -For closed source software SLSA does not provide any solutions for malicious producers. -
B -Authoring & reviewing -SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. -Two-person review could have caught the unauthorized change. -
C -Source code management -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code system would have been a much harder target for the attackers. -
D -External build parameters -The Great Suspender: Attacker published software that was not built from the purported sources. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
E -Build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA Build levels have stronger security requirements for the build platform, making it more difficult for an attacker to forge the SLSA provenance and gain persistence. -
F -Artifact publication -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Distribution channel -Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Package selection -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
I -Usage -Default credentials: Attacker could leverage default credentials to access sensitive data. -SLSA does not address this threat. -
N/A -Dependency threats (i.e. A-H, recursively) -event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code. -Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source. -
- - - - - - -
-Availability threat -Known example -How SLSA could help -
N/A -Dependency becomes unavailable -Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. diff --git a/docs/spec/v1.1-rc2/threats.md b/docs/spec/v1.1-rc2/threats.md deleted file mode 100644 index e6ce1128c..000000000 --- a/docs/spec/v1.1-rc2/threats.md +++ /dev/null @@ -1,1031 +0,0 @@ ---- -title: Threats & mitigations -description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. ---- - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations with SLSA and other best practices. For an -introduction to the supply chain threats that SLSA is aiming to protect -against, see [Supply chain threats]. - -The examples on this page are meant to: - -- Explain the reasons for each of the SLSA [requirements](requirements.md). -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](levels.md) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - - - -
- -## Overview - -![Supply Chain Threats](images/supply-chain-threats.svg) - -This threat model covers the *software supply chain*, meaning the process by -which software is produced and consumed. We describe and cluster threats based -on where in the software development pipeline those threats occur, labeled (A) -through (I). This is useful because priorities and mitigations mostly cluster -along those same lines. Keep in mind that dependencies are -[highly recursive](#dependency-threats), so each dependency has its own threats -(A) through (I), and the same for *their* dependencies, and so on. For a more -detailed explanation of the supply chain model, see -[Terminology](terminology.md). - -Importantly, producers and consumers face *aggregate* risk across all of the -software they produce and consume, respectively. Many organizations produce -and/or consume thousands of software packages, both first- and third-party, and -it is not practical to rely on every individual team in the organization to do -the right thing. For this reason, SLSA prioritizes mitigations that can be -broadly adopted in an automated fashion, minimizing the chance of mistakes. - -## Source threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes modification of the source data at rest as well as insider threats, -when an authorized individual introduces an unauthorized change. - -SLSA does not yet address source threats, but we anticipate doing so in a -[future version](../../current-activities.md#source-track). - -### (A) Producer - -The producer of the software intentionally produces code that harms the -consumer, or the producer otherwise uses practices that are not deserving of the -consumer's trust. - -
Software producer intentionally creates a malicious revision of the source - -*Threat:* A producer intentionally creates a malicious revision with the intent of harming their consumers. - -*Mitigation:* -This kind of attack cannot be directly mitigated through SLSA controls. -Consumers must establish some basis to trust the organizations from which they consume software. -That basis may be: - -- The repo is open source with an active user-base. High numbers of engaged users may increase the likelihood that bad code is detected during code review and reduce the time-to-detection when bad revisions are accepted. -- The organization has sufficient legal or reputational incentives to dissuade it from making malicious changes. - -Ultimately this is a judgement call with no straightforward answer. - -*Example:* A producer with an otherwise good reputation decides suddenly to produce a malicious artifact with the intent to harm their consumers. - -
- -### (B) Modifying the source - -An adversary without any special administrator privileges attempts to introduce a change counter to the declared intent of the source by following the producer's official source control process. - -Threats in this category can be mitigated by following source control management best practices. - -#### (B1) Submit change without review - -
Directly submit without review - -*Threat:* Malicious code submitted to the source repository. - -*Mitigation:* The producer requires approval of all changes before they are accepted. - -*Example:* Adversary directly pushes a change to a git repo's `main` branch. -Solution: The producer can configure branch protection rules on the `main` branch. -A best practice is to require approval of any changes via a change management tool before they are accepted into the source. - -
-
Single actor controls multiple accounts - -*Threat:* An actor is able to control multiple account and effectively approve their own code changes. - -*Mitigation:* The producer must ensure that no actor is able to control or influence multiple accounts with review privileges. - -*Example:* Adversary creates a pull request using a secondary account and approves it using their primary account. -Solution: The producer must track all actors who have both explicit review permissions and the independent ability to control -a privileged bot. A common vector for this attack is to influence a robot account with the permission to review or contribute -code. Control of the robot account and an actor's own personal account is enough to exploit this vulnerability. A common -solution to this flow is to deny bot accounts from contributing or reviewing code, or to require more human reviews in those -cases. - -
-
Use a robot account to submit change - -*Threat:* Exploit a robot account that has the ability to submit changes without -two-person review. - -*Mitigation:* All changes require review by two people, even changes authored by -robots. - -*Example:* A file within the source repository is automatically generated by a -robot, which is allowed to submit without review. -Adversary compromises the robot and submits a malicious change. -Solution: Require two-person review for such changes, ignoring the robot. - -
-
Abuse of rule exceptions - -*Threat:* Rule exceptions provide vector for abuse. - -*Mitigation:* Remove rule exceptions. - -*Example:* A producer intends to require two-person review on "all changes except for documentation changes," defined as those only modifying `.md` files. -Adversary submits a malicious executable masquerading as a documentation file, `help.md`. -This avoids the two-person review rule due to the exception. -In the future, a user (or another workflow) can be induced to *execute* `help.md` and become compromised. -Technically the malicious code change met all defined policies yet the intent of the organization was defeated. -Solution: The producer adjusts the rules to prohibit such exceptions. - -
- -
Highly-permissioned actor bypasses or disables controls - -*Threat:* Trusted actor with "admin" privileges in a repository submits code by disabling existing controls. - -*Mitigation:* All actors must be subject to same controls, whether or not they have -administrator privileges. -Changes to the controls themselves should require their own review process. - -*Example 1:* A GitHub repository-level admin pushes a change without review, even though GitHub branch protection is enabled. -Solution: The producer can modify the rule to disallow bypass by administrators, or move the rule to an organization-level ruleset. - -*Example 2:* GitHub repository-level admin removes a branch requirement, pushes their change, then re-enables the requirement to cover their tracks. -Solution: The producer can configure higher-permission-level rules (such as organization-level GitHub Rulesets) to prevent repository-level tampering. - -
- -#### (B2) Evade change management process - -
Modify code after review - -*Threat:* Modify the code after it has been reviewed but before submission. - -*Mitigation:* Source control platform invalidates approvals whenever the proposed change is modified. - -*Example:* Source repository requires two-person review on all changes. -Adversary sends an initial "good" pull request to a peer, who approves it. -Adversary then modifies their proposal to contain "bad" code. - -Solution: Configure the code review rules to require review of the most recent revision before submission. -Resetting or "dismissing" votes on a PR introduces substantial friction to the process. -Depending on the security posture of the source, the producer has a few choices to deal with this situation. -They may: - -- Accept this risk. Code review is already expensive and the pros outweigh the cons here. -- Dismiss reviews when new changes are added. This is a common outcome when expert code review is required. -- Leave previous reviews intact, but require that "at least the last revision must be reviewed by someone." - -
-
Submit a change that is unreviewable - -*Threat:* Adversary crafts a change that is meaningless for a human to review that looks -benign but is actually malicious. - -*Mitigation:* Code review system ensures that all reviews are informed and -meaningful to the extent possible. For example the system could show -& resolve symlinks, render images, or verify & display provenance. - -*Example:* A proposed change updates a JPEG file to include a malicious -message, but the reviewer is only presented with a diff of the binary -file contents. The reviewer is unable to parse the contents themselves -so they do not have enough context to provide a meaningful review. -Solution: the code review system should present the reviewer with a -rendering of the image and the [embedded -metadata](https://en.wikipedia.org/wiki/Exif), allowing them to make an -informed decision. - -
-
Copy a reviewed change to another context - -*Threat:* Get a change reviewed in one context and then transfer it to a -different context. - -*Mitigation:* Approvals are context-specific. - -*Example:* MyPackage's source repository requires two-person review. Adversary -forks the repo, submits a change in the fork with review from a colluding -colleague (who is not trusted by MyPackage), then proposes the change to -the upstream repo. -Solution: The proposed change still requires two-person review in the upstream context even though it received two-person review in another context. - -
- - -
Commit graph attacks - -*Threat:* A malicious commit can be included in a sequence of commits such that it does not appear malicious in the net change presented to reviewers. - -*Mitigation:* The producer ensures that all revisions in the protected context followed the same contribution process. - -*Example:* Adversary sends a pull request containing malicious commit X and a commit Y that undoes X. -The combined change of X + Y displays zero lines of malicious code and the reviewer cannot tell that X is malicious unless they review it individually. -If X is allowed to become reachable from the protected branch, the content may become available in secured environments such as developer machines. - -Solution: Each revision in the protected context must have followed the intended process. -Ultimately, this means that either each code review results in at most a single new commit or that the full process is followed for each constituent commit in a proposed sequence. - -
- -#### (B3) Render code review ineffective - -
Collude with another trusted person - -*Threat:* Two trusted persons collude to author and approve a bad change. - -*Mitigation:* The producer can arbitrarily increase friction of their policies to reduce risk, such as requiring additional, or more senior reviewers. -The goal of policy here is to ensure that the approved changes match the intention of the producer for the source. -Increasing the friction of the policies may make it harder to circumvent, but doing so has diminishing returns. -Ultimately the producer will need to land upon a balanced risk profile that makes sense for their security posture. - -
-
Trick reviewer into approving bad code - -*Threat:* Construct a change that looks benign but is actually malicious, a.k.a. -"bugdoor." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
Reviewer blindly approves changes - -*Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber -stamping." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -#### (B4) Render change metadata ineffective - -
Forge change metadata - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -### (C) Source code management - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -
Platform admin abuses privileges - -*Threat:* Platform administrator abuses their privileges to bypass controls or -to push a malicious version of the software. - -*Mitigation:* The source platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals for -changes to the infrastructure, audit logging). A future [Platform -Operations Track](future-directions#platform-operations-track) may provide -more specific guidance on how to secure the underlying platform. - -*Example 1:* GitHostingService employee uses an internal tool to push changes to -the MyPackage source repo. - -*Example 2:* GitHostingService employee uses an internal tool to push a -malicious version of the server to serve malicious versions of MyPackage sources -to a specific CI/CD client but the regular version to everyone else, in order to -hide tracks. - -*Example 3:* GitHostingService employee uses an internal tool to push a -malicious version of the server that includes a backdoor allowing specific users -to bypass branch protections. Adversary then uses this backdoor to submit a -change to MyPackage without review. - -
-
Exploit vulnerability in SCM - -*Threat:* Exploit a vulnerability in the implementation of the source code -management system to bypass controls. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - -### (D) External build parameters - -An adversary builds from a version of the source code that does not match the -official source control repository, or changes the build parameters to inject -behavior that was not intended by the official source. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (E) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build platform pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -### (E) Build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Forge values of the provenance (other than output digest) (Build L2+) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, the trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][unforgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -platform to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Forge output digest of the provenance (n/a) - -*Threat:* The tenant-controlled build process sets output artifact digest -(`subject` in SLSA Provenance) without the trusted control plane verifying that -such an artifact was actually produced. - -*Mitigation:* None; this is not a problem. Any build claiming to produce a given -artifact could have actually produced it by copying it verbatim from input to -output.[^preimage] (Reminder: Provenance is only a claim that a particular -artifact was *built*, not that it was *published* to a particular registry.) - -*Example:* A legitimate MyPackage artifact has digest `abcdef` and is built -from source repo `good/my-package`. A malicious build from source repo -`evil/my-package` claims that it built artifact `abcdef` when it did not. -Solution: Verifier rejects because the source location does not match; the -forged digest is irrelevant. - -[^preimage]: Technically this requires the artifact to be known to the - adversary. If they only know the digest but not the actual contents, they - cannot actually build the artifact without a [preimage attack] on the digest - algorithm. However, even still there are no known concerns where this is a - problem. - -[preimage attack]: https://en.wikipedia.org/wiki/Preimage_attack - -
-
Compromise project owner (Build L2+) - -*Threat:* An adversary gains owner permissions for the artifact's build project. - -*Mitigation:* The build project owner must not have the ability to influence the -build process or provenance generation. - -*Example:* MyPackage is built on Awesome Builder under the project "mypackage". -Adversary is an owner of the "mypackage" project. Awesome Builder allows -owners to debug the build environment via SSH. An adversary uses this feature -to alter a build in progress. Solution: Build L3 requires the external parameters -to be complete in the provenance. The attackers access and/or actions within the -SSH connection would be enumerated within the external parameters. The updated -external parameters will not match the declared expectations causing verification -to fail. - -
-
Compromise other build (Build L3) - -*Threat:* Perform a malicious build that alters the behavior of a benign -build running in parallel or subsequent environments. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other or persist changes. - -*Example 1:* A build platform runs all builds for project MyPackage on -the same machine as the same Linux user. An adversary starts a malicious build -that listens for another build and swaps out source files, then starts a benign -build. The benign build uses the malicious build's source files, but its -provenance says it used benign source files. Solution: The build platform -changes architecture to isolate each build in a separate VM or similar. - -*Example 2:* A build platform uses the same machine for subsequent -builds. An adversary first runs a build that replaces the `make` binary with a -malicious version, then subsequently runs an otherwise benign build. Solution: -The builder changes architecture to start each build with a clean machine image. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build platform. - -*Mitigation:* Builds are [isolated] from the trusted build platform control -plane, and only the control plane has [access][unforgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a malicious artifact to a build cache that is later picked up by a -benign build process ([example][build-cache-poisoning-example]). - -*Mitigation:* Build caches must be [isolated][isolated] between builds to prevent -such cache poisoning attacks. In particular, the cache SHOULD be keyed by the -transitive closure of all inputs to the cached artifact, and the cache must -either be only writable by the trusted control plane or have SLSA Build L3 -provenance for each cache entry. - -*Example 1:* The cache key does not fully cover the transitive closure of all -inputs and instead only uses the digest of the source file itself. Adversary runs -a build over `auth.cc` with command line flags to gcc that define a marco -replacing `CheckAuth(ctx)` with `true`. When subsequent builds build `auth.cc` -they will get the attacker's poisoned instance that does not call `CheckAuth`. -Solution: Build cache is keyed by digest of `auth.cc`, command line, and digest of -gcc so changing the command line flags results in a different cache entry. - -*Example 2:* The tenant controlled build process has full write access to the -cache. Adversary observes a legitimate build of `auth.cc` which covers the -transitive closure of all inputs and notes the digest used for caching. The -adversary builds a malicious version of `auth.o` and directly writes it to the -build cache using the observed digest. Subsequent legitimate builds will use -the malicious version of `auth.o`. Solution: Each cache entry is keyed by the -transitive closure of the inputs, and the cache entry is itself a SLSA Build L3 -build with its own provenance that corresponds to the key. - -
-
Compromise build platform admin (verification) - -*Threat:* An adversary gains admin permissions for the artifact's build platform. - -*Mitigation:* The build platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals, audit -logging). - -*Example:* MyPackage is built on Awesome Builder. Awesome Builder allows -engineers on-call to SSH into build machines to debug production issues. An -adversary uses this access to modify a build in progress. Solution: Consumers -do not accept provenance from the build platform unless they trust sufficient -controls are in place to prevent abusing admin privileges. - -
- -### (F) Artifact publication - -An adversary uploads a package artifact that does not reflect the intent of the -package's official source control repository. - -This is the most direct threat because it is the easiest to pull off. If there -are no mitigations for this threat, then (D) and (E) are often indistinguishable -from this threat. - - - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Solution: Verifier rejects because builder is not as -expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Distribution channel - -An adversary modifies the package on the package registry using an -administrative interface or through a compromise of the infrastructure -including modification of the package in transit to the consumer. - -The distribution channel threats and mitigations look very similar to the -Artifact Publication (F) threats and mitigations with the main difference -being that these threats are mitigated by having the *consumer* perform -verification. - -The consumer's actions may be simplified if (F) produces a [VSA][vsa]. -In this case the consumer may replace provenance verification with -[VSA verification][vsa_verification]. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Replace the package with one built using an unofficial CI/CD pipeline -that does not build in the correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value or a VSA for corresponding `resourceUri`. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Adversary then replaces the original package within the -repository with the malicious package. Solution: Verifier rejects because -builder is not as expected. - -
-
Issue VSA from untrusted intermediary (expectations) - -*Threat:* Have an unofficial intermediary issue a VSA for a malicious package. - -*Mitigation*: Verifier requires VSAs to be issued by a trusted intermediary. - -*Example:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then issues a VSA of their own for the malicious -package. Solution: Verifier rejects because they only accept VSAs from -TheRepository which the adversary cannot issue since they do not have the -corresponding signing key. - -
-
Upload package without provenance or VSA (Build L1) - -*Threat:* Replace the original package with a malicious one without provenance. - -*Mitigation:* Verifier requires provenance or a VSA before accepting the package. - -*Example:* Adversary replaces MyPackage with a malicious version of MyPackage -on the package repository and deletes existing provenance. Solution: Verifier -rejects because provenance is missing. - -
-
Replace package and VSA with another (expectations) - -*Threat:* Replace a package and its VSA with a malicious package and its valid VSA. - -*Mitigation*: Consumer ensures that the VSA matches the package they've requested (not just the package they received) by following the [verification process](verification_summary#how-to-verify). - -*Example:* Adversary uploads a malicious package to `repo/evil-package`, -getting a valid VSA for `repo/evil-package`. Adversary then replaces -`repo/my-package` and its VSA with `repo/evil-package` and its VSA. -Solution: Verifier rejects because the VSA `resourceUri` field lists -`repo/evil-package` and not the expected `repo/my-package`. - -
-
Tamper with artifact after upload (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -replace it while retaining the original provenance or VSA. - -*Mitigation:* Verifier checks that the provenance or VSA's `subject` matches -the hash of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -replaces the modified version of the package in the repository and retains the -original provenance. Solution: Verifier rejects because the hash of the -artifact does not match the `subject` found within the provenance. - -
-
Tamper with provenance or VSA (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance or VSA to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance or VSA with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder or the VSA came from an expected verifier. - -*Example 1:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -*Example 2:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then modifies the original VSA's `subject` -field to match the digest of the malicious package. Solution: Verifier rejects -because the cryptographic signature is no longer valid. - -
- -## Usage threats - -A usage threat is a potential for an adversary to exploit behavior of the -consumer. - -### (H) Package selection - -The consumer requests a package that it did not intend. - -
Dependency confusion - -*Threat:* Register a package name in a public registry that shadows a name used -on the victim's internal registry, and wait for a misconfigured victim to fetch -from the public registry instead of the internal one. - -*Mitigation:* The mitigation is for the software producer to build internal -packages on a SLSA Level 2+ compliant build system and define expectations for -build provenance. Expectations must be verified on installation of the internal -packages. If a misconfigured victim attempts to install attacker's package with -an internal name but from the public registry, then verification against -expectations will fail. - -For more information see [Verifying artifacts](verifying-artifacts.md) -and [Defender's Perspective: Dependency Confusion and Typosquatting Attacks](/blog/2024/08/dep-confusion-and-typosquatting). - -
- -
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, the -requirement to make the source available can be a mild deterrent, can aid -investigation or ad-hoc analysis, and can complement source-based typosquatting -solutions. - -
- -### (I) Usage - -The consumer uses a package in an unsafe manner. - -
Improper usage - -*Threat:* The software can be used in an insecure manner, allowing an -adversary to compromise the consumer. - -*Mitigation:* This threat is not addressed by SLSA, but may be addressed by -efforts like [Secure by Design][secure-by-design]. - -
- -## Dependency threats - -A dependency threat is a potential for an adversary to introduce unintended -behavior in one artifact by compromising some other artifact that the former -depends on at build time. (Runtime dependencies are excluded from the model, as -[noted below](#runtime-dep).) - -Unlike other threat categories, dependency threats develop recursively through -the supply chain and can only be exploited indirectly. For example, if -application *A* includes library *B* as part of its build process, then a build -or source threat to *B* is also a dependency threat to *A*. Furthermore, if -library *B* uses build tool *C*, then a source or build threat to *C* is also a -dependency threat to both *A* and *B*. - -This version of SLSA does not explicitly address dependency threats, but we -expect that a future version will. In the meantime, you can [apply SLSA -recursively] to your dependencies in order to reduce the risk of dependency -threats. - - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively - -### Build dependency - -An adversary compromises the target artifact through one of its build -dependencies. Any artifact that is present in the build environment and has the -ability to influence the output is considered a build dependency. - -
Include a vulnerable dependency (library, base image, bundled file, etc.) - -*Threat:* Statically link, bundle, or otherwise include an artifact that is -compromised or has some vulnerability, causing the output artifact to have the -same vulnerability. - -*Example:* The C++ program MyPackage statically links libDep at build time. A -contributor accidentally introduces a security vulnerability into libDep. The -next time MyPackage is built, it picks up and includes the vulnerable version of -libDep, resulting in MyPackage also having the security vulnerability. - -*Mitigation:* A future -[Dependency track](../../current-activities#dependency-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -
-
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.) - -*Threat:* Use a compromised tool or other software artifact during the build -process, which alters the build process and injects unintended behavior into the -output artifact. - -*Mitigation:* This can be partially mitigated by treating build tooling, -including OS images, as any other artifact to be verified prior to use. -The threats described in this document apply recursively to build tooling -as do the mitigations and examples. A future -[Build Environment track](../../current-activities#build-environment-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -*Example:* MyPackage is a tarball containing an ELF executable, created by -running `/usr/bin/tar` during its build process. An adversary compromises the -`tar` OS package such that `/usr/bin/tar` injects a backdoor into every ELF -executable it writes. The next time MyPackage is built, the build picks up the -vulnerable `tar` package, which injects the backdoor into the resulting -MyPackage artifact. Solution: [apply SLSA recursively] to all build tools -prior to the build. The build platform verifies the disk image, -or the individual components on the disk image, against the associated -provenance or VSAs prior to running a build. Depending on where the initial -compromise took place (i.e. before/during vs *after* the build of the build tool itself), the modified `/usr/bin/tar` will fail this verification. - -
- -
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.) - -*Threat:* During the build process, use a compromised runtime dependency (such -as during testing or dynamic linking), which alters the build process and -injects unwanted behavior into the output. - -**NOTE:** This is technically the same case as [Use a compromised build -tool](#build-tool). We call it out to remind the reader that -[runtime dependencies](#runtime-dep) can become build dependencies if they are -loaded during the build. - -*Example:* MyPackage has a runtime dependency on package Dep, meaning that Dep -is not included in MyPackage but required to be installed on the user's machine -at the time MyPackage is run. However, Dep is also loaded during the build -process of MyPackage as part of a test. An adversary compromises Dep such that, -when run during a build, it injects a backdoor into the output artifact. The -next time MyPackage is built, it picks up and loads Dep during the build -process. The malicious code then injects the backdoor into the new MyPackage -artifact. - -*Mitigation:* In addition to all the mitigations for build tools, you can often -avoid runtime dependencies becoming build dependencies by isolating tests to a -separate environment that does not have write access to the output artifact. - -
- -### Related threats - -The following threats are related to "dependencies" but are not modeled as -"dependency threats". - -
Use a compromised dependency at runtime (modeled separately) - -*Threat:* Load a compromised artifact at runtime, thereby compromising the user -or environment where the software ran. - -*Example:* MyPackage lists package Dep as a runtime dependency. Adversary -publishes a compromised version of Dep that runs malicious code on the user's -machine when Dep is loaded at runtime. An end user installs MyPackage, which in -turn installs the compromised version of Dep. When the user runs MyPackage, it -loads and executes the malicious code from Dep. - -*Mitigation:* N/A - SLSA's -threat model does not explicitly model runtime dependencies. Instead, each -runtime dependency is considered a distinct artifact with its own threats. - -
- -## Availability threats - - - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA does not currently address availability threats, though future versions might. - -
Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, some -solutions to support hermetic and reproducible builds may also reduce the -impact of this threat. - -
-
De-list artifact - -*Threat:* The package registry stops serving the artifact. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
De-list provenance - -*Threat:* The package registry stops serving the provenance. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Verification threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above. - -
Tamper with recorded expectations - -*Threat:* Modify the verifier's recorded expectations, causing the verifier to -accept an unofficial package artifact. - -*Mitigation:* Changes to recorded expectations requires some form of -authorization, such as two-party review. - -*Example:* The package ecosystem records its expectations for a given package -name in a configuration file that is modifiable by that package's producer. The -configuration for MyPackage expects the source repository to be -`good/my-package`. The adversary modifies the configuration to also accept -`evil/my-package`, and then builds from that repository and uploads a malicious -version of the package. Solution: Changes to the recorded expectations require -two-party review. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Choose secure algorithms when using cryptographic digests, such -as SHA-256. - -*Examples:* Attacker crafts a malicious file with the same MD5 hash as a target -benign file. Attacker replaces the benign file with the malicious file. -Solution: Only accept cryptographic hashes with strong collision resistance. - -
- -
- - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively -[authentic]: requirements.md#provenance-authentic -[build-cache-poisoning-example]: https://adnanthekhan.com/2024/05/06/the-monsters-in-your-build-cache-github-actions-cache-poisoning/ -[exists]: requirements.md#provenance-exists -[isolated]: requirements.md#isolated -[unforgeable]: requirements.md#provenance-unforgeable -[secure-by-design]: https://www.cisa.gov/securebydesign -[supply chain threats]: threats-overview -[vsa]: verification_summary -[vsa_verification]: verification_summary#how-to-verify diff --git a/docs/spec/v1.1-rc2/use-cases.md b/docs/spec/v1.1-rc2/use-cases.md deleted file mode 100644 index f3d53d55c..000000000 --- a/docs/spec/v1.1-rc2/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two-person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package registry. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build platforms rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor-provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on the trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor-provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified by a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.1-rc2/verification_summary.md b/docs/spec/v1.1-rc2/verification_summary.md deleted file mode 100644 index 4b68327bd..000000000 --- a/docs/spec/v1.1-rc2/verification_summary.md +++ /dev/null @@ -1,418 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software producers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [resolvedDependencies](/provenance/v1#resolvedDependencies) of the artifact -being verified (recursively) or b) matching the non-source dependency -listed in `resolvedDependencies` (`subject.digest` == -`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` == -`resolvedDependencies.uri`) to a VSA _for that dependency_ and using -`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependencyLevels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "", - "version": { - "": "", - ... - } - }, - "timeVerified": , - "resourceUri": , - "policy": { - "uri": "", - "digest": { } - } - "inputAttestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verificationResult": "", - "verifiedLevels": [""], - "dependencyLevels": { - "": , - "": , - ... - }, - "slsaVersion": ".", -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`verifier.version` _map (string->string), optional_ - -> Map of names of components of the verification platform to their version. - - -`timeVerified` _string ([Timestamp]), optional_ - -> Timestamp indicating what time the verification occurred. - - -`resourceUri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. -> -> The `resourceUri` SHOULD be set to the URI from which the producer expects the -> consumer to fetch the artifact for verification. This enables the consumer to -> easily determine the expected value when [verifying](#how-to-verify). If the -> `resourceUri` is set to some other value, the producer MUST communicate the -> expected value, or how to determine the expected value, to consumers through -> an out-of-band channel. - - -`policy` _object ([ResourceDescriptor]), required_ - -> Describes the policy that the `subject` was verified against. -> -> The entry MUST contain a `uri` identifying which policy was applied and -> SHOULD contain a `digest` to indicate the exact version of that policy. - - -`inputAttestations` _array ([ResourceDescriptor]), optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `resolvedDependencies` field in [SLSA Provenance]. -> -> This field MAY be absent if the verifier does not support this feature. -> If non-empty, this field MUST contain information on _all_ the attestations -> used to perform verification. -> -> Each entry MUST contain a `digest` of the attestation and SHOULD contains a -> `uri` that can be used to fetch the attestation. - - -`verificationResult` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`verifiedLevels` _array ([SlsaResult]), required_ - -> Indicates the highest level of each track verified for the artifact (and not -> its dependencies), or "FAILED" if policy verification failed. -> -> Users MUST NOT include more than one level per SLSA track. Note that each SLSA -> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies -> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to -> include more than one level per track. - - -`dependencyLevels` _object, optional_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. -> A set but empty `dependencyLevels` object means that the artifact has **no** -> dependency at all, while an unset or null `dependencyLevels` means that the -> verifier makes no claims about the artifact's dependencies. -> -> Users MUST count each dependency only once per SLSA track, at the highest -> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`, -> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for -> `SLSA_BUILD_LEVEL_1`. - - -`slsaVersion` _string, optional_ - -> Indicates the version of the SLSA specification that the verifier used, in the -> form `.`. Example: `1.0`. If unset, the default is an -> unspecified minor version of `1.x`. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier", - "version": { - "slsa-verifier-linux-amd64": "v2.3.0", - "slsa-framework/slsa-verifier/actions/installer": "v2.3.0" - } - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "inputAttestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_BUILD_LEVEL_3"], - "dependencyLevels": { - "SLSA_BUILD_LEVEL_3": 5, - "SLSA_BUILD_LEVEL_2": 7, - "SLSA_BUILD_LEVEL_1": 1, - }, - "slsaVersion": "1.0" -} -``` - -## How to verify - -VSA consumers use VSAs to accomplish goals based on delegated trust. We call the -process of establishing a VSA's authenticity and determining whether it meets -the consumer's goals 'verification'. Goals differ, as do levels of confidence -in VSA producers, so the verification procedure changes to suit its context. -However, there are certain steps that most verification procedures have in -common. - -Verification MUST include the following steps: - -1. Verify the signature on the VSA envelope using the preconfigured roots of - trust. This step ensures that the VSA was produced by a trusted producer - and that it hasn't been tampered with. - -2. Verify the statement's `subject` matches the digest of the artifact in - question. This step ensures that the VSA pertains to the intended artifact. - -3. Verify that the `predicateType` is - `https://slsa.dev/verification_summary/v1`. This step ensures that the - in-toto predicate is using this version of the VSA format. - -4. Verify that the `verifier` matches the public key (or equivalent) used to - verify the signature in step 1. This step identifies the VSA producer in - cases where their identity is not implicitly revealed in step 1. - -5. Verify that the value for `resourceUri` in the VSA matches the expected - value. This step ensures that the consumer is using the VSA for the - producer's intended purpose. - -6. Verify that the value for `slsaResult` is `PASSED`. This step ensures the - artifact is suitable for the consumer's purposes. - -7. Verify that `verifiedLevels` contains the expected value. This step ensures - that the artifact is suitable for the consumer's purposes. - -Verification MAY additionally contain the following step: - -1. (Optional) Verify additional fields required to determine whether the VSA - meets your goal. - -Verification mitigates different threats depending on the VSA's contents and the -verification procedure. - -IMPORTANT: A VSA does not protect against compromise of the verifier, such as by -a malicious insider. Instead, VSA consumers SHOULD carefully consider which -verifiers they add to their roots of trust. - -### Examples - -1. Suppose consumer C wants to delegate to verifier V the decision for whether - to accept artifact A as resource R. Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` contains `SLSA_BUILD_LEVEL_UNEVALUATED`. - - Note: This example is analogous to traditional code signing. The expected - value for `verifiedLevels` is arbitrary but prenegotiated by the producer and - the consumer. The consumer does not need to check additional fields, as C - fully delegates the decision to V. - -2. Suppose consumer C wants to enforce the rule "Artifact A at resource R must - have a passing VSA from verifier V showing it meets SLSA Build Level 2+." - Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` is `SLSA_BUILD_LEVEL_2` or `SLSA_BUILD_LEVEL_3`. - - Note: In this example, verifying the VSA mitigates the same threats as - verifying the artifact's SLSA provenance. See - [Verifying artifacts](/spec/v1.0/verifying-artifacts) for details about which - threats are addressed by verifying each SLSA level. - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -SHOULD be one of these values: - -- `SLSA_BUILD_LEVEL_UNEVALUATED` -- `SLSA_BUILD_LEVEL_0` -- `SLSA_BUILD_LEVEL_1` -- `SLSA_BUILD_LEVEL_2` -- `SLSA_BUILD_LEVEL_3` -- `FAILED` (Indicates policy evaluation failed) - -Note that each SLSA level implies the levels below it in the same track. -For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` + -`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`). - -Users MAY use custom values here but MUST NOT use custom values starting with -`SLSA_`. - -## Change history - -- 1.1: - - Changed the `policy` object to recommend that the `digest` field of - the `ResourceDescriptor` is set. - - Added optional `verifier.version` field to record verification tools. - - Added Verification section with examples. - - Made `timeVerified` optional. -- 1.0: - - Replaced `materials` with `resolvedDependencies`. - - Relaxed `SlsaResult` to allow other values. - - Converted to lowerCamelCase for consistency with [SLSA Provenance]. - - Added `slsaVersion` field. -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SLSA Provenance]: /provenance -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/digest_set.md -[ResourceURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#resourceuri -[ResourceDescriptor]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/resource_descriptor.md -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[Timestamp]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules diff --git a/docs/spec/v1.1-rc2/verifying-artifacts.md b/docs/spec/v1.1-rc2/verifying-artifacts.md deleted file mode 100644 index 927fd8c92..000000000 --- a/docs/spec/v1.1-rc2/verifying-artifacts.md +++ /dev/null @@ -1,303 +0,0 @@ ---- -title: Verifying artifacts -description: SLSA uses provenance to indicate whether an artifact is authentic or not, but provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection verification, and this page describes how to verify artifacts and their SLSA provenance. The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that -inspection **verification**, and this page describes recommendations for how to -verify artifacts and their SLSA provenance. - -This page is divided into several sections. The first describes the process -for verifying an artifact and its provenance against a set of expectations. The -second describes how to form the expectations used to verify provenance. The -third discusses architecture choices for where provenance verification can -happen. - -## How to verify - -Verification SHOULD include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- Verifying the signature on the provenance envelope. -- Ensuring that the values for `buildType` and `externalParameters` in the - provenance match the expected values. The package ecosystem MAY allow - an approved list of `externalParameters` to be ignored during verification. - Any unrecognized `externalParameters` SHOULD cause verification to fail. - -![Threats covered by each step](images/supply-chain-threats-build-verification.svg) - -See [Terminology](terminology.md) for an explanation of the supply chain model and -[Threats & mitigations](threats.md) for a detailed explanation of each threat. - -**Note:** This section assumes that the provenance is in the recommended -[provenance format](/provenance/v1). If it is not, then the verifier SHOULD -perform equivalent checks on provenance fields that correspond to the ones -referenced here. - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "E", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This configuration - is likely in the form of a map from (builder public key identity, - `builder.id`) to (SLSA Build level) drawn from the SLSA Conformance - Program (coming soon). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the artifact in question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "E"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Verifying build platforms](verifying-systems). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "I".) -- [Threat "I"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not yet cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. Those threats are - discussed in more detail under [Threat "H"]. - -[Threat "E"]: threats#e-build-process -[Threat "F"]: threats#f-artifact-publication -[Threat "G"]: threats#g-distribution-channel -[Threat "H"]: threats#h-package-selection -[Threat "I"]: threats#i-usage - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets your expectations for that -package in order to mitigate [threat "D"]. - -In our threat model, the adversary has the ability to invoke a build and to publish -to the registry. The adversary is not able to write to the source repository, nor do -they have insider access to any trusted systems. Your expectations SHOULD be -sufficient to detect or prevent this adversary from injecting unofficial -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 - -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 -range of values (possibly any value) if it is known that any value in the range -is safe. JSON comparison is sufficient for verifying parameters. - -TIP: Difficulty in forming meaningful expectations about `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "D"]: threats#d-external-build-parameters - -### Step 3: (Optional) Check dependencies recursively - -[verify-step-3]: #step-3-optional-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. Note that SLSA v1.0 does not have any requirements on the -completeness or verification of `resolvedDependencies`. However, one might wish -to verify dependencies in order to mitigate [dependency threats] and protect against -threats further up the supply chain. If `resolvedDependencies` is incomplete, -these checks can be done on a best-effort basis. - -A [Verification Summary Attestation (VSA)][VSA] can make dependency verification -more efficient by recording the result of prior verifications. A trimming -heuristic or exception mechanism is almost always necessary when verifying -dependencies because there will be transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) - -[dependency threats]: threats#dependency-threats -[VSA]: /verification_summary -[threats]: threats - -## Forming Expectations - -Expectations are known provenance values that indicate the -corresponding artifact is authentic. For example, a package ecosystem may -maintain a mapping between package names and their canonical source -repositories. That mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git branches or tags. - -- **Defined by producer:** The package producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the package's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -- **Defined in source:** The source repository tells the verifier what their - expectations ought to be. In this model, the package name is immutably bound - to a source repository and all other external parameters are defined in the - source repository. This is how the Go ecosystem works, for example, since - the package name *is* the source repository location. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -will likely have different artifacts and therefore different provenance. Similarly, an -artifact might have different names in different package ecosystems but use the same -provenance file. - -## Architecture options - -There are several options (non-mutually exclusive) for where provenance verification -can happen: the package ecosystem at upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify provenance. For example, even if a package -ecosystem verifies provenance, consumers who get artifacts from that package -ecosystem might wish to verify provenance themselves for defense in depth. They -can do so using either client-side verification tooling or by polling a -monitor. - - - -### Package ecosystem - -[Package ecosystem]: #package-ecosystem - -A package ecosystem is a set of rules and conventions governing -how packages are distributed. Every package artifact has an ecosystem, whether it is -formal or ad-hoc. Some ecosystems are formal, such as language distribution -(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". For more background, see -[Package Model](terminology.md#package-model). - -During package upload, a package ecosystem can ensure that the artifact's -provenance matches the expected values for that package name's provenance before -accepting it into the package registry. This option is RECOMMENDED whenever -possible because doing so benefits all of the package ecosystem's clients. - -The package ecosystem is responsible for making its expectations available to -consumers, reliably redistributing artifacts and provenance, and providing tools -to enable safe artifact consumption (e.g. whether an artifact meets -expectations). - -### Consumer - -[Consumer]: #consumer - -A package artifact's consumer is the organization or individual that uses the -package artifact. - -Consumers can form their own expectations for artifacts or use the default -expectations provided by the package producer and/or package ecosystem. -When forming their own expectations, the consumer uses client-side verification tooling to ensure -that the artifact's provenance matches their expectations for that package -before use (e.g. during installation or deployment). Client-side verification -tooling can be either standalone, such as -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into -the package ecosystem client. - -### Monitor - -[Monitor]: #monitor - -A monitor is a service that verifies provenance for a set -of packages and publishes the result of that verification. The set of -packages verified by a monitor is arbitrary, though it MAY mimic the set -of packages published through one or more package ecosystems. The monitor -SHOULD publish its expectations for all the packages it verifies. - -Consumers can continuously poll a monitor to detect artifacts that -do not meet the monitor's expectations. Detecting artifacts that fail -verification is of limited benefit unless a human or automated system takes -action in response to the failed verification. diff --git a/docs/spec/v1.1-rc2/whats-new.md b/docs/spec/v1.1-rc2/whats-new.md deleted file mode 100644 index bf3bdbbd4..000000000 --- a/docs/spec/v1.1-rc2/whats-new.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: What's new -description: The changes brought by SLSA v1.1. ---- - -This document describes the major changes brought by SLSA v1.1 -relative to the prior release, [v1.0]. - -## Summary of changes - -- Clarify that attestation format schema are informative and the - specification texts (SLSA and [in-toto attestation]) are the canonical - source of definitions. -- Add procedure for verifying VSAs. -- Add verifier metadata to VSA format. -- It is now recommended that the `digest` field of `ResourceDescriptor` is - set in a Verification Summary Attestation's (VSA) `policy` object. -- Further refine the [threat model](threats). - - - -[in-toto attestation]: https://github.com/in-toto/attestation -[v1.0]: /spec/v1.0/ diff --git a/docs/spec/v1.1/about.md b/docs/spec/v1.1/about.md deleted file mode 100644 index fcf183c6a..000000000 --- a/docs/spec/v1.1/about.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: About SLSA -description: With supply chain attacks on the rise, a shared vocabulary and universal framework are needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software. ---- - -This page is an introduction to SLSA and its concepts. If you're new -to SLSA, start here! - -## What is SLSA? - -Supply-chain Levels for Software Artifacts, or SLSA ("salsa"), is a set of incrementally adoptable guidelines for supply chain security, -established by industry consensus. The specification set by SLSA is useful for -both software producers and consumers: producers can follow SLSA's guidelines to -make their software supply chain more secure, and consumers can use SLSA to make -decisions about whether to trust a software package. - -SLSA offers: - -- A common vocabulary to talk about software supply chain security -- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume -- An actionable checklist to improve your own software's security -- A way to measure your efforts toward compliance with the [Secure Software Development Framework (SSDF)](https://csrc.nist.gov/Projects/ssdf) - -## Why SLSA is needed - -High-profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply -chain integrity weaknesses that may go unnoticed, yet quickly become very -public, disruptive, and costly in today's environment when exploited. They've -also shown that there are inherent risks not just in code itself, but at -multiple points in the complex process of getting that code into software -systems—that is, in the **software supply chain**. Since these attacks are on -the rise and show no sign of decreasing, a universal framework for hardening the -software supply chain is needed, as affirmed by the U.S. Executive Order on -Improving the Nation's Cybersecurity of May 12th, 2021. - -Security techniques for vulnerability detection and analysis of source code are -essential, but are not enough on their own. Even after fuzzing or vulnerability -scanning is completed, changes to code can happen, whether unintentionally or -from insider threats or compromised accounts. Risk for code modification exists at -each link in a typical software supply chain, from source to build through -packaging and distribution. Any weaknesses in the supply chain undermine -confidence in whether the code that you run is actually the code that you -scanned. - -SLSA is designed to support automation that tracks code handling from source -to binary, protecting against tampering regardless of the complexity -of the software supply chain. As a result, SLSA increases trust that the -analysis and review performed on source code can be assumed to still apply to -the binary consumed after the build and distribution process. - -## SLSA in layperson's terms - -There has been a [lot of discussion](https://ntia.gov/page/software-bill-materials) about the need for "ingredient labels" for -software—a "software bill of materials" (SBOM) that tells users what is in their -software. Building off this analogy, SLSA can be thought of as all the food -safety handling guidelines that make an ingredient list credible. From standards -for clean factory environments so contaminants aren't introduced in packaging -plants, to the requirement for tamper-proof seals on lids that ensure nobody -changes the contents of items sitting on grocery store shelves, the entire food -safety framework ensures that consumers can trust that the ingredient list -matches what's actually in the package they buy. - -Likewise, the SLSA framework provides this trust with guidelines and -tamper-resistant evidence for securing each step of the software production -process. That means you know not only that nothing unexpected was added to the -software product, but also that the ingredient label itself wasn't tampered with -and accurately reflects the software contents. In this way, SLSA helps protect -against the risk of: - -- Code modification (by adding a tamper-evident "seal" to code after - source control) -- Uploaded artifacts that were not built by the expected CI/CD platform (by marking - artifacts with a factory "stamp" that shows which build platform created it) -- Threats against the build platform (by providing "manufacturing facility" - best practices for build platform services) - -For more exploration of this analogy, see the blog post -[SLSA + SBOM: Accelerating SBOM success with the help of SLSA](/blog/2022/05/slsa-sbom). - -## Who is SLSA for? - -In short: everyone involved in producing and consuming software, or providing -infrastructure for software. - -**Software producers**, such as an open source project, a software vendor, or a -team writing first-party code for use within the same company. SLSA gives you -protection against tampering along the supply chain to your consumers, both -reducing insider risk and increasing confidence that the software you produce -reaches your consumers as you intended. - -**Software consumers**, such as a development team using open source packages, a -government agency using vendored software, or a CISO judging organizational -risk. SLSA gives you a way to judge the security practices of the software you -rely on and be sure that what you receive is what you expected. - -**Infrastructure providers**, who provide infrastructure such as an ecosystem -package manager, build platform, or CI/CD platform. As the bridge between the -producers and consumers, your adoption of SLSA enables a secure software supply -chain between them. - -## How SLSA works - -We talk about SLSA in terms of [tracks and levels](levels.md). -A SLSA track focuses on a particular aspect of a supply chain, such as the Build -Track. SLSA v1.1 consists of only a single track ([Build](levels.md#build-track)), but future versions of -SLSA will add tracks that cover other parts of the software supply chain, such -as how source code is managed. - -Within each track, ascending levels indicate increasingly hardened security -practices. Higher levels provide better guarantees against supply chain threats, -but come at higher implementation costs. Lower SLSA levels are designed to be -easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes -used to refer to software that doesn't yet meet any SLSA level. Currently, the -SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels -to be possible in [future revisions](future-directions.md). - -The combination of tracks and levels offers an easy way to discuss whether -software meets a specific set of requirements. By referring to an artifact as -meeting SLSA Build Level 3, for example, you're indicating in one phrase that -the software artifact was built following a set of security practices that -industry leaders agree protect against particular supply chain compromises. - -## What SLSA doesn't cover - -SLSA is only one part of a thorough approach to supply chain security. There -are several areas outside SLSA's current framework that are nevertheless -important to consider together with SLSA such as: - -- Code quality: SLSA does not tell you whether the developers writing the - source code followed secure coding practices. -- Producer trust: SLSA does not address organizations that intentionally - produce malicious software, but it can reduce insider risks within an - organization you trust. SLSA's Build Track protects against tampering during - or after the build, and [future SLSA tracks](future-directions.md) intend to - protect against unauthorized modifications of source code and dependencies. -- Transitive trust for dependencies: the SLSA level of an artifact is - independent of the level of its dependencies. You can use SLSA recursively to - also judge an artifact's dependencies on their own, but there is - currently no single SLSA level that applies to both an artifact and its - transitive dependencies together. For a more detailed explanation of why, - see the [FAQ](faq#q-why-is-slsa-not-transitive). diff --git a/docs/spec/v1.1/attestation-model.md b/docs/spec/v1.1/attestation-model.md deleted file mode 100644 index 380907029..000000000 --- a/docs/spec/v1.1/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first-party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed-source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open-source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open-source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed-source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third-party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.1/distributing-provenance.md b/docs/spec/v1.1/distributing-provenance.md deleted file mode 100644 index dadf4db94..000000000 --- a/docs/spec/v1.1/distributing-provenance.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Distributing provenance -description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is platform implementers and software distributors. ---- - -In order to make provenance for artifacts available after generation -for verification, SLSA requires the distribution and verification of provenance -metadata in the form of SLSA attestations. - -This document provides specifications for distributing provenance and the -relationship between build artifacts and provenance (build attestations). It is -primarily concerned with artifacts for ecosystems that distribute build -artifacts, but some attention is also paid to ecosystems that distribute -container images or only distribute source artifacts, as many of the same -principles generally apply to any artifact or group of artifacts. - -In addition, this document is primarily for the benefit of artifact -distributors, to understand how they can adopt the distribution of SLSA -provenance. It is primarily concerned with the means of distributing -attestations and the relationship of attestations to build artifacts, and not -with the specific format of the attestation itself. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Background - -The [package ecosystem]'s maintainers are responsible for reliably -redistributing artifacts and provenance, making the producers' expectations -available to consumers, and providing tools to enable safe artifact consumption -(e.g., whether an artifact meets its producer's expectations). - -## Relationship between releases and attestations - -Attestations SHOULD be bound to artifacts, not releases. - -A single "release" of a project, package, or library might include multiple -artifacts. These artifacts result from builds on different platforms, -architectures, or environments. The builds need not happen at roughly the same -point in time and might even span multiple days. - -It is often difficult or impossible to determine when a release is 'finished' -because many ecosystems allow adding new artifacts to old releases when adding -support for new platforms or architectures. Therefore, the set of attestations -for a given release MAY grow over time as additional builds and attestations -are created. - -Thus, package ecosystems SHOULD support multiple individual attestations per -release. At the time of a given build, the relevant provenance for that build -can be added to the release, depending on the relationship to the given -artifacts. - -## Relationship between artifacts and attestations - -Package ecosystems SHOULD support a one-to-many relationship from build -artifacts to attestations to ensure that anyone is free to produce and publish -any attestation they might need. However, while there are lots of possible -attestations that can have a relationship to a given artifact, in this context -SLSA is primarily concerned with build attestations, i.e., provenance, and as -such, this specification only considers build attestations, produced by the -same maintainers as the artifacts themselves. - -By providing provenance alongside an artifact in the manner specified by a -given ecosystem, maintainers are considered to be 'elevating' these build -attestations above all other possible attestations that could be provided by -third parties for a given artifact. The ultimate goal is for maintainers to -provide the provenance necessary for a repository to be able to verify some -potential policy that requires a certain SLSA level for publication, not -support the publication of arbitrary attestations by third parties. - -As a result, this provenance SHOULD accompany the artifact at publish time, and -package ecosystems SHOULD provide a way to map a given artifact to its -corresponding attestations. The mappings can be either implicit (e.g., require a -custom filename schema that uniquely identifies the provenance over other -attestation types) or explicit (e.g., it could happen as a de-facto standard -based on where the attestation is published). - -The provenance SHOULD have a filename that is directly related to the build -artifact filename. For example, for an artifact `.`, the -attestation is `.attestation` or some similar extension (for example -[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`). - -## Where attestations are published - -There are a number of opportunities and venues to publish attestations during -and after the build process. Producers MUST publish attestations in at least -one place, and SHOULD publish attestations in more than one place: - -- **Publish attestations alongside the source repository releases**: If the - source repository hosting provider offers an artifact "release" feature, - such as [GitHub - releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), - producers SHOULD include provenance as part of such releases. This option - has the benefit of requiring no changes to the package registry to support - provenance formats, but has the disadvantage of putting the source - repository hosting provider in the critical path for installers that want to - verify policy at build-time. -- **Publish attestations alongside the artifact in the package registry**: - Many software repositories already support some variety of publishing 1:1 - related files alongside an artifact, sometimes known as “sidecar files”. - For example, PyPI supports publishing `.asc` files representing the PGP - signature for an artifact with the same filename (but different extension). - This option requires the mapping between artifact and attestation (or - attestation vessel) to be 1:1. -- **Publish attestations elsewhere, record their existence in a transparency - log**: Once an attestation has been generated and published for a build, a - hash of the attestation and a pointer to where it is indexed SHOULD be - published to a third-party transparency log that exists outside the source - repository and package registry. Not only are transparency logs such as - [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed - to be immutable, but they typically also make monitoring easier. - Requiring the presence of the attestation in a monitored transparency log - during verification helps ensure the attestation is trustworthy. - -Combining these options gives us a process for bootstrapping SLSA adoption -within an ecosystem, even if the package registry doesn't support publishing -attestations. First, interested projects modify their release process to -produce SLSA provenance. Then, they publish that provenance to their source -repository. Finally, they publish the provenance to the package registry, if -and when the registry supports it. - -Long-term, package registries SHOULD support uploading and distributing -provenance alongside the artifact. This model is preferred for two reasons: - -- trust: clients already trust the package registry as the source of their - artifacts, and don't need to trust an additional service; -- reliability: clients already depend on the package registry as part of - their critical path, so distributing provenance via the registry avoids - adding an additional point of failure. - -Short term, consumers of build artifacts can bootstrap a manual policy by using -the source repository only for projects that publish all artifacts and -attestations to the source repository, and later extend this to all artifacts -published to the package registry via the canonical installation tools once -a given ecosystem supports them. - -## Immutability of attestations - -Attestations SHOULD be immutable. Once an attestation is published as it -corresponds to a given artifact, that attestation is immutable and cannot be -overwritten later with a different attestation that refers to the same -artifact. Instead, a new release (and new artifacts) SHOULD be created. - -## Format of the attestation - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto [SLSA Provenance](/provenance), but -another format MAY be used if both producer and consumer agree and it meets all -the other requirements. - -## Considerations for source-based ecosystems - -Some ecosystems have support for installing directly from source repositories -(an option for Python/`pip`, Go, etc.). In these cases, there is no need to -publish or verify provenance because there is no "build" step that translates -between a source repository and an artifact that is being installed. - -However, for ecosystems that install from source repositories _via_ some -intermediary (e.g., [Homebrew installing from GitHub release artifacts generated -from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go -installing through the Go module proxy](https://proxy.golang.org/)), these -ecosystems distribute "source archives" that are not the bit-for-bit identical -form from version control. These intermediaries are transforming the original -source repository in some way that constitutes a "build" and as a result SHOULD -be providing build provenance for this "package", and the recommendations -outlined here apply. - -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.1/faq.md b/docs/spec/v1.1/faq.md deleted file mode 100644 index 90ed7bb8c..000000000 --- a/docs/spec/v1.1/faq.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Frequently asked questions -description: Answers to questions frequently asked about SLSA. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build platforms to -corroborate the provenance of a build. In this way, one can create an overall -platform that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a platform can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. - -## Q. What is the difference between a build platform, system, and service? - -Build platform and build system have been used interchangeably in the past. With -the v1.0 specification, however, there has been a unification around the term -platform as indicated in the [Terminology](terminology.md). The use of the word -`system` still exists related to software and services within the build platform -and to systems outside of a build platform like change management systems. - -A build service is a hosted build platform that is often run on shared infrastructure -instead of individuals' machines and workstations. Its use has also been replaced outside -of the requirements as it relates to the build platform. - -## Q: Is SLSA the same as TACOS? - -No. -[Trusted Attestation and Compliance for Open Source (TACOS)](https://github.com/tacosframework) -is a framework authored by Tidelift. -Per their website, TACOS is a framework -"for assessing the development practices of open source projects -against a set of secure development standards specified by the (US) -NIST Secure Software Development Framework (SSDF) V1.1" which -"vendors can use to provide self-attestation for the open source components -they rely on." - -In contrast, SLSA is a community-developed framework---including -adoptable guidelines for securing a software supply chain and -mechanism to evaluate the trustworthiness of artifacts you consume---that -is part of the Open Source Security Foundation (OpenSSF). - -## Q: How does SLSA and SLSA Provenance relate to SBOM? - -[Software Bill of Materials (SBOM)] are a frequently recommended tool for -increased software supply chain rigor. An SBOM is typically focused on -understanding software in order to evaluate risk through known vulnerabilities -and license compliance. These use-cases require fine-grained and timely data -which can be refined to improve signal-to-noise ratio. - -[SLSA Provenance] and the [Build track] are focused on trustworthiness of the -build process. To improve trustworthiness, Provenance is generated in the build -platform's trusted control plane, which in practice results in it being coarse -grained. For example, in Provenance metadata completeness of -`resolvedDependencies` information is on a best-effort basis. Further, the -`ResourceDescriptor` type does not require version and license information or -even a URI to the dependency's original location. - -While they likely include similar data, SBOMs and SLSA Provenance operate at -different levels of abstraction. The fine-grained data in an SBOM typically -describes the components present in a produced artifact, whereas SLSA -Provenance more coarsely describes parameters of a build which are external to -the build platform. - -The granularity and expressiveness of the two use-cases differs enough that -current SBOM formats were deemed not a good fit for the requirements of -the Build track. Yet SBOMs are a good practice and may form part of a future -SLSA Vulnerabilities track. Further, SLSA Provenance can increase the -trustworthiness of an SBOM by describing how the SBOM was created. - -SLSA Provenance, the wider [in-toto Attestation Framework] in which the -recommended format sits, and the various SBOM standards, are all rapidly -evolving spaces. There is ongoing investigation into linking between the -different formats and exploration of alignment on common models. This FAQ entry -describes our understanding of the intersection efforts today. We do not know -how things will evolve over the coming months and years, but we look forward to -the collaboration and improved software supply chain security. - -## Q: How to SLSA with a self-hosted runner - -Some CI systems allow producers to provide their own self-hosted runners as a build -environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage -these, classifying the SLSA build level for the resulting artifact can be confusing. - -Since the SLSA Build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance, interpretation of the -specification hinges on the platform entities involved in the provenance generation. -The SLSA [build level requirements] (secure key storage, isolation, etc.) should be -imposed on the transitive closure of the systems which are responsible for informing -the provenance generated. - -Some common situations may include: - -- The platform generates the provenance and just calls a runner for individual items. - In this situation, the provenance is only affected by the platform so there would be - no requirements imposed on the runner. -- The runner generates the provenance. In this situation, the orchestrating platform - is irrelevant and all requirements are imposed on the runner. -- The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance. Trust is - shared between the platform and the runner so the requirements are imposed on both. - -Additional requirements on the self-hosted runners may be added to Build levels -greater than L3 when such levels get defined. - -[build level requirements]: requirements.md -[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners -[Software Bill of Materials (SBOM)]: https://ntia.gov/sbom -[SLSA Provenance]: provenance.md -[Build track]: levels.md#build-track -[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/ diff --git a/docs/spec/v1.1/future-directions.md b/docs/spec/v1.1/future-directions.md deleted file mode 100644 index 217f3302c..000000000 --- a/docs/spec/v1.1/future-directions.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Future directions -description: The initial draft version (v0.1) of SLSA had a larger scope including protections against tampering with source code and a higher level of build integrity (Build L4). This page collects some early thoughts on how SLSA **might** evolve in future versions to re-introduce these notions and add other additional aspects of automatable supply chain security. ---- - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future versions to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build platform and enabling -corroboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream verifiers - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other build platforms to corroborate the - provenance. - -
- -
- -## Platform Operations track - -A Platform Operations track could provide assurances around the hardening of -platforms (e.g. build or source platforms) as they are operated. - -The initial [draft version (v0.1)] of SLSA included a section on -[common requirements](../v0.1/requirements.md#common-requirements) that formed -the foundation of the guidance for -[verifying build systems](verifying-systems.md), which **may or may not** form -the basis for a future Build Platform Operations track: - -- Controls for approval, logging, and auditing of all physical and remote - access to platform infrastructure, cryptographic secrets, and privileged - debugging interfaces. -- Conformance to security best practices to minimize the risk of compromise. -- Protection of cryptographic secrets used by the build platform. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md - -## Source Track - -The SLSA Source track will describe increasing levels of trustworthiness and completeness in a repository revision's provenance (e.g. how it was generated, who the contributors were, etc). - -The Source track will be scoped to revisions of a single repository. -The intent of each revision is determined by the [software producer](terminology.md#roles) who is also responsible for declaring which Source level should apply and administering technical controls to enforce that level. - -The primary purpose of the Source track will be to enable verification that the creation of a revision followed the producer's intended process. -Consumers will be able to examine source provenance attestations to determine if a revision meets their requirements. diff --git a/docs/spec/v1.1/images/build-model.svg b/docs/spec/v1.1/images/build-model.svg deleted file mode 100644 index 9d6bed6ca..000000000 --- a/docs/spec/v1.1/images/build-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1/images/provenance-model.svg b/docs/spec/v1.1/images/provenance-model.svg deleted file mode 100644 index 028dad49e..000000000 --- a/docs/spec/v1.1/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1/images/supply-chain-model.svg b/docs/spec/v1.1/images/supply-chain-model.svg deleted file mode 100644 index 6a37ffa05..000000000 --- a/docs/spec/v1.1/images/supply-chain-model.svg +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1/images/supply-chain-threats-build-verification.svg b/docs/spec/v1.1/images/supply-chain-threats-build-verification.svg deleted file mode 100644 index 2888f6215..000000000 --- a/docs/spec/v1.1/images/supply-chain-threats-build-verification.svg +++ /dev/null @@ -1,88 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1/images/supply-chain-threats.svg b/docs/spec/v1.1/images/supply-chain-threats.svg deleted file mode 100644 index 38421111d..000000000 --- a/docs/spec/v1.1/images/supply-chain-threats.svg +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.1/images/verification-model.svg b/docs/spec/v1.1/images/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.1/images/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.1/index.md b/docs/spec/v1.1/index.md deleted file mode 100644 index d6dcdddd9..000000000 --- a/docs/spec/v1.1/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: SLSA specification -description: SLSA is a specification for describing and incrementally improving supply chain security, established by industry consensus. It is organized into a series of levels that describe increasing security guarantees. This is **version 1.1** of the SLSA specification. ---- - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **Version 1.1** of the SLSA -specification, which defines several SLSA levels and recommended attestation -formats, including provenance. - -{%- for section in site.data.nav.main %} -{%- if section.url == page.url %} -{%- for subsection in section.children %} -{%- if subsection.children %} - -## {{ subsection.title }} - -{{ subsection.description }} - - - -| Page | Description -| ---- | ----------- -{%- for child in subsection.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} -{%- endfor %} - - -{%- endif %} -{%- endfor %} -{%- endif %} -{%- endfor %} diff --git a/docs/spec/v1.1/onepage.md b/docs/spec/v1.1/onepage.md deleted file mode 100644 index 06d1dce01..000000000 --- a/docs/spec/v1.1/onepage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SLSA specification -description: A one-page rendering of all that is included in SLSA v1.1. -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.1/" %} -{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,terminology,levels,requirements,distributing-provenance,verifying-artifacts,verifying-systems,threats,attestation-model,provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.1/principles.md b/docs/spec/v1.1/principles.md deleted file mode 100644 index 5f65538f4..000000000 --- a/docs/spec/v1.1/principles.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Guiding principles -description: An introduction to the guiding principles behind SLSA's design decisions. ---- - -This page is an introduction to the guiding principles behind SLSA's design -decisions. - -## Simple levels with clear outcomes - -Use [levels](levels) to communicate security state and to encourage a large -population to improve its security stance over time. When necessary, split -levels into separate tracks to recognize progress in unrelated security areas. - -**Reasoning:** Levels simplify how to think about security by boiling a complex -topic into an easy-to-understand number. It is clear that level N is better than -level N-1, even to someone with passing familiarity. This provides a convenient -way to describe the current security state as well as a natural path to improvement. - -Guidelines: - -- **Define levels in terms of concrete security outcomes.** Each level should - have clear and meaningful security value, such as stopping a particular - class of threats. Levels should represent security milestones, not just - incremental progress. Give each level an easy-to-remember mnemonic, such as - "Provenance exists." - -- **Balance level granularity.** Too many levels makes SLSA hard to understand - and remember; too few makes each level hard to achieve. Collapse levels - until each step requires a non-trivial but manageable amount of work to - implement. Separate levels if they require significant work from multiple - distinct parties, such as infrastructure work plus user behavior changes, so - long as the intermediate level still has some security value (prior bullet). - -- **Use tracks sparingly.** Additional tracks add extra complexity to SLSA, so - a new track should be seen as a last resort. Each track should have a clear, - distinct purpose with a crisply defined objective, such as trustworthy - provenance for the [Build track](levels#build-track). As a rule of thumb, a - new track may be warranted if it addresses threats unrelated to another - track. Try to avoid tracks that sound confusingly similar in either name or - objective. - -## Trust platforms, verify artifacts - -Establish trust in a small number of platforms and systems---such as change management, build, -and packaging platforms---and then automatically verify the many artifacts -produced by those platforms. - -**Reasoning**: Trusted computing bases are unavoidable---there's no choice but -to trust some platforms. Hardening and verifying platforms is difficult and -expensive manual work, and each trusted platform expands the attack surface of the -supply chain. Verifying that an artifact is produced by a trusted platform, -though, is easy to automate. - -To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited -number of platforms and then automate verification of the artifacts produced by those platforms. -The attack surface and work to establish trust do not scale with the number of artifacts produced, -as happens when artifacts each use a different trusted platform. - -**Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant -amount of central work. - -### Example - -A security engineer analyzes the architecture and implementation of a build -platform to ensure that it meets the SLSA Build Track requirements. Following the -analysis, the public keys used by the build platform to sign provenance are -"trusted" up to the given SLSA level. Downstream platforms verify the provenance -signed by the public key to automatically determine that an artifact meets the -SLSA level. - -### Corollary: Minimize the number of trusted platforms - -A corollary to this principle is to minimize the size of the trusted computing -base. Every platform we trust adds attack surface and increases the need for -manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team within an organization maintaining their own build platform, use a - shared build platform. Hardening work can be shared across all teams. -- Remove the need to trust components. For example, use end-to-end signing - to avoid the need to trust intermediate distribution platforms. - -## Trust code, not individuals - -Securely trace all software back to source code rather than trust individuals who have write access to package registries. - -**Reasoning**: Code is static and analyzable. Individuals, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. - -**Benefits**: Removes the possibility for a trusted individual---or an -attacker abusing compromised credentials---to tamper with source code -after it has been committed. - -## Prefer attestations over inferences - -Require explicit attestations about an artifact's provenance; do not infer -security properties from a platform's configurations. - -**Reasoning**: Theoretically, access control can be configured so that the only path from -source to release is through the official channels: the CI/CD platform pulls only -from the proper source, package registry allows access only to the CI/CD platform, -and so on. We might infer that we can trust artifacts produced by these platforms -based on the platform's configuration. - -In practice, though, these configurations are almost impossible to get right and -keep right. There are often over-provisioning, confused deputy problems, or -mistakes. Even if a platform is configured properly at one moment, it might not -stay that way, and humans almost always end up getting in the access control -lists. - -Access control is still important, but SLSA goes further to provide defense in depth: it **requires proof in -the form of attestations that the package was built correctly**. - -**Benefits**: The attestation removes intermediate platforms from the trust base and ensures that -individuals who are accidentally granted access do not have sufficient permission to tamper with the package. - -## Support anonymous and pseudonymous contributions - -SLSA supports anonymous and pseudonymous 'identities' within the software supply chain. -While organizations that implement SLSA may choose otherwise, SLSA itself does not require, -or encourage, participants to be mapped to their legal identities. - -**Nothing in this specification should be taken to mean that SLSA requires participants to -reveal their legal identity.** - -**Reasoning**: SLSA uses identities for multiple purposes: as a trust anchor for attestations -(i.e. who or what is making this claim and do I trust it to do so) or for attributing actions -to an actor. Choice of identification technology is left to the organization and technical -stacks implementing the SLSA standards. - -When identities are strongly authenticated and used consistently they can often be leveraged -for both of these purposes without requiring them to be mapped to legal identities. -This reflects how identities are often used in open source where legal name means much less -to projects than the history and behavior of a given handle over time does. Meanwhile, some -organizations may choose to levy additional requirements on identities. They are free to do -so, but SLSA itself does not require it. - -**Benefits**: By _not_ requiring legal identities SLSA lowers the barriers to its adoption, -enabling all of its other benefits and maintaining support for anonymous and pseudonymous -contribution as has been practiced in the software industry for decades. diff --git a/docs/spec/v1.1/provenance.md b/docs/spec/v1.1/provenance.md deleted file mode 100644 index d8fe5dceb..000000000 --- a/docs/spec/v1.1/provenance.md +++ /dev/null @@ -1,599 +0,0 @@ ---- -title: Provenance -description: Description of SLSA provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when, and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](requirements#provenance-generation). - -## Model - -Provenance is an attestation that a particular build platform produced a set of -software artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant build platform. - The `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build platforms.) - - - The build platform implementer SHOULD define a security model for the build - platform in order to clearly identify the platform's boundaries, actors, - and interfaces. This model SHOULD then be used to identify the transitive - closure of the trusted build platform for the `builder.id` as well as the - trusted control plane. - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - platform ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `internalParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](requirements.md). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." - Such changes do not update the `predicateType`. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -### Summary - -*NOTE: This summary (in cue) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -*NOTE: This summary (in protobuf) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - -Link: [provenance.proto](schema/provenance.proto) - -*NOTE: This protobuf definition prioritizes being a human-readable summary -of the schema for readers of the specification. A version of the protobuf -definition useful for code generation is maintained in the -[in-toto attestation] repository.* - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`internalParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that -there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build platform SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
internalParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build platform is already trusted, and in many cases it is -not practical to do so. - -
resolvedDependencies -array (ResourceDescriptor) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script -fetches and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be -listed here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `internalParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `internalParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build platform. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build platform to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build platform to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the build platform that executed the invocation, which is trusted to -have correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ResourceDescriptor) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or -incident response. For example, this might reference logs generated during -the build and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted build platform. This is -[intended](verifying-artifacts#step-1-check-slsa-build-level) -to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -The `builder.id` URI SHOULD resolve to documentation explaining: - -- The scope of what this ID represents. -- The claimed SLSA Build level. -- The accuracy and completeness guarantees of the fields in the provenance. -- Any fields that are generated by the tenant-controlled build process and not - verified by the trusted control plane, except for the `subject`. -- The interpretation of any extension fields. - -
builderDependencies -array (ResourceDescriptor) - -Dependencies used by the orchestrator that are not run within the workload -and that do not affect the build, but might affect the provenance generation -or security guarantees. - -
version -map (string→string) - -Map of names of components of the build platform to their version. - -
- -The build platform, or builder for short, represents the transitive -closure of all the entities that are, by necessity, [trusted] to faithfully run -the build and record the provenance. This includes not only the software but the -hardware and people involved in running the service. For example, a particular -instance of [Tekton](https://tekton.dev/) could be a build platform, while -Tekton itself is not. For more info, see [Build -model](terminology#build-model). - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -### Extension fields - -[Extension fields]: #extension-fields - -Implementations MAY add extension fields to any JSON object to describe -information that is not captured in a standard field. Guidelines: - -- Extension fields SHOULD use names of the form `_`, e.g. - `examplebuilder_isCodeReviewed`. This practice avoids field name collisions - by namespacing each vendor. Non-extension field names never contain an - underscore. -- Extension fields MUST NOT alter the meaning of any other field. In other - words, an attestation with an absent extension field MUST be interpreted - identically to an attestation with an unrecognized (and thus ignored) - extension field. -- Extension fields SHOULD follow the [monotonic principle][parsing rules], - meaning that deleting or ignoring the extension SHOULD NOT turn a DENY - decision into an ALLOW. - -## Verification - -[Verification]: verifying-artifacts - -Please see [Verifying Artifacts][Verification] for a detailed discussion of -provenance verification. - -## Index of build types - -The following is a partial index of build type definitions. Each contains a -complete example predicate. - - - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) -- [Google Cloud Build (community-maintained)](https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1) - -To add an entry here, please send a pull request on GitHub. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "internalParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "builderDependencies": null, // not in v0.2 - "version": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.0 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build platforms, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed: - - `parameters` -> `externalParameters` (slight change in semantics) - - `environment` -> `internalParameters` (slight change in semantics) - - `materials` -> `resolvedDependencies` (slight change in semantics) - - `buildInvocationId` -> `invocationId` - - `buildStartedOn` -> `startedOn` - - `buildFinishedOn` -> `finishedOn` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - ResourceDescriptor: `annotations`, `content`, `downloadLocation`, - `mediaType`, `name` - - Builder: `builderDependencies` and `version` - - `byproducts` -- Changed naming convention for extension fields. - -Differences from RC1 and RC2: - -- Renamed `systemParameters` (RC1 + RC2) -> `internalParameters` (final). -- Changed naming convention for extension fields (in RC2). -- Renamed `localName` (RC1) -> `name` (RC2). -- Added `annotations` and `content` (in RC2). - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: threats -[trusted]: principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.1/requirements.md b/docs/spec/v1.1/requirements.md deleted file mode 100644 index c0a72d931..000000000 --- a/docs/spec/v1.1/requirements.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -title: Producing artifacts -description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers. ---- - - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is platform implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Levels](levels.md). For background, see [Terminology](terminology.md). To -better understand the reasoning behind the requirements, see -[Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -In order to produce artifacts with a specific build level, responsibility is -split between the [Producer] and [Build platform]. The build platform MUST -strengthen the security controls in order to achieve a specific level while the -producer MUST choose and adopt a build platform capable of achieving a desired -build level, implementing any controls as specified by the chosen platform. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build platform - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build platform - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Unforgeable - ✓ -
Isolation strength - Hosted - ✓✓ -
Isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure platform is beyond the -scope of this specification, all implementations MUST use industry security -best practices to be conformant to this specification. This includes, but is -not limited to, using proper access controls, securing communications, -implementing proper management of cryptographic secrets, doing frequent updates, -and promptly fixing known vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -NOTE: There were more requirements for producers in the initial -[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted -how a package can be built. These were removed in the v1.0 specification and -will be reassessed and re-added as indicated in the -[future directions](future-directions.md). - -### Choose an appropriate build platform - -The producer MUST select a build platform that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -If a producer wishes to distribute their artifact through a [package ecosystem] -that requires explicit metadata about the build process in the form of a -configuration file, the producer MUST complete the configuration file and keep -it up to date. This metadata might include information related to the artifact's -source repository and build parameters. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the -[package ecosystem], provided that the package ecosystem is capable of -distributing provenance. - -## Build Platform - -[Build platform]: #build-platform - -A package's build platform is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build platform is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build platform used -by a single software project, or even an individual's workstation. Ideally, one -build platform is used by many different software packages so that consumers can -[minimize the number of trusted platforms](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build platform is responsible for providing two things: [provenance -generation] and [isolation between builds]. The [Build level](levels.md#build-track) describes -the degree to which each of these properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build platform is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the overall provenance integrity according to -minimum requirements on its: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package by cryptographic digest and describes how that package was -produced. The format MUST be acceptable to the [package ecosystem] and/or -[consumer](verifying-artifacts.md#consumer). - -It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. - -If using an alternate format, it MUST contain the equivalent information as SLSA -Provenance at each level and SHOULD be bi-directionally translatable to SLSA -Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build platform and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only -to the build platform component that generated the provenance attestation. - -While many constraints affect choice of signing methodologies, it is -RECOMMENDED that build platforms use signing methodologies which improve the -ability to detect and remediate key compromise, such as methods which rely on -transparency logs or, when transparency isn't appropriate, time stamping -services. - -Authenticity allows the consumer to trust the contents of the provenance -attestation, such as the identity of the build platform. - -*Accuracy:* The provenance MUST be generated by the control plane (i.e. within -the trust boundary [identified in the provenance]) and not by a tenant of the -build platform (i.e. outside the trust boundary), except as noted below. - -- The data in the provenance MUST be obtained from the build platform, either - because the generator *is* the build platform or because the provenance - generator reads the data directly from the build platform. -- The build platform MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. -- Exceptions for fields that MAY be generated by a tenant of the build platform: - - The names and cryptographic digests of the output artifacts, i.e. - `subject` in [SLSA Provenance]. See [forge output digest of the - provenance](threats#forged-digest) for explanation of why this is - acceptable. - - Any field that is not marked as REQUIRED for Build L2. For example, - `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at - Build L2. Builders SHOULD document any such cases of tenant-generated - fields. - -*Completeness:* SHOULD be complete. - -- There MAY be [external parameters] that are not sufficiently captured in - the provenance. -- Completeness of resolved dependencies is best effort. - - ✓✓ -
Provenance is Unforgeable - -*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. - -- Any secret material used for authenticating the provenance, for example the - signing key used to generate a digital signature, MUST be stored in a secure - management system appropriate for such material and accessible only to the - build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - platform in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted in [Provenance - is Authentic](#provenance-authentic). (Build L3 does not require additional - fields beyond those of L2.) - -*Completeness:* SHOULD be complete. - -- [External parameters] MUST be fully enumerated. -- Completeness of resolved dependencies is best effort. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build platform is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build platform's isolation strength, see -[Verifying build platforms](verifying-systems.md). - - - - -
RequirementDescriptionL1L2L3 - -
Hosted - - -All build steps ran using a hosted build platform on shared or dedicated -infrastructure, not on an individual's workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Isolated - - -The build platform ensured that the build steps ran in an isolated environment, -free of unintended external influence. In other words, any external influence on -the build was specifically requested by the build itself. This MUST hold true -even between builds within the same tenant project. - -The build platform MUST guarantee the following: - -- It MUST NOT be possible for a build to access any secrets of the build - platform, such as the provenance signing key, because doing so would - compromise the authenticity of the provenance. -- It MUST NOT be possible for two builds that overlap in time to influence one - another, such as by altering the memory of a different build process running - on the same machine. -- It MUST NOT be possible for one build to persist or influence the build - environment of a subsequent build. In other words, an ephemeral build - environment MUST be provisioned for each build. -- It MUST NOT be possible for one build to inject false entries into a build - cache used by another build, also known as "cache poisoning". In other - words, the output of the build MUST be identical whether or not the cache is - used. -- The build platform MUST NOT open services that allow for remote influence - unless all such interactions are captured as `externalParameters` in the - provenance. - -There are no sub-requirements on the build itself. Build L3 is limited to -ensuring that a well-intentioned build runs securely. It does not require that -a build platform prevents a producer from performing a risky or insecure build. In -particular, the "Isolated" requirement does not prohibit a build from calling -out to a remote execution service or a "self-hosted runner" that is outside the -trust boundary of the build platform. - -NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" -in the initial [draft version (v0.1)](../v0.1/requirements.md). - -NOTE: This requirement is not to be confused with "Hermetic", which roughly -means that the build ran with no network access. Such a requirement requires -substantial changes to both the build platform and each individual build, and is -considered in the [future directions](future-directions.md). - - ✓ -
- -[external parameters]: provenance.md#externalParameters -[identified in the provenance]: provenance.md#model -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.1/schema/provenance.cue b/docs/spec/v1.1/schema/provenance.cue deleted file mode 100644 index 22bc5e0d8..000000000 --- a/docs/spec/v1.1/schema/provenance.cue +++ /dev/null @@ -1,48 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "internalParameters": object, - "resolvedDependencies": [ ...#ResourceDescriptor ], - }, - "runDetails": { - "builder": { - "id": string, - "builderDependencies": [ ...#ResourceDescriptor ], - "version": { ...string }, - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ResourceDescriptor ], - } - } -} - -#ResourceDescriptor: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "gitCommit": string, - [string]: string, - }, - "name": string, - "downloadLocation": string, - "mediaType": string, - "content": bytes, // base64-encoded - "annotations": { - [string]: _ // any JSON type - } -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.1/schema/provenance.proto b/docs/spec/v1.1/schema/provenance.proto deleted file mode 100644 index ae0a71ee1..000000000 --- a/docs/spec/v1.1/schema/provenance.proto +++ /dev/null @@ -1,50 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct internal_parameters = 3; - repeated ResourceDescriptor resolved_dependencies = 4; -} - -message ResourceDescriptor { - string uri = 1; - map digest = 2; - string name = 3; - string download_location = 4; - string media_type = 5; - bytes content = 6; - map annotations = 7; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ResourceDescriptor byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ResourceDescriptor builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.1/terminology.md b/docs/spec/v1.1/terminology.md deleted file mode 100644 index ba1af593c..000000000 --- a/docs/spec/v1.1/terminology.md +++ /dev/null @@ -1,342 +0,0 @@ ---- -title: Terminology -description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting. ---- - - -Before diving into the [SLSA Levels](levels.md), we need to establish a core set -of terminology and models to describe what we're protecting. - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). -| [Distribution] | The channel through which artifacts are "published" for use by others. | A registry like DockerHub or npm. Artifacts may also be distributed via physical media (e.g., a USB drive). -| Package | Artifact that is distributed. 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 (distribution). 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 -[distribution]: #distribution-model -[SLSA Provenance]: /provenance/v1 - -### Roles - -Throughout the specification, you will see reference to the following roles -that take part in the software supply chain. Note that in practice a role may -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. - -### Build model - -

Model Build

- -We model a build as running on a multi-tenant *build platform*, where each -execution is independent. - -1. A tenant invokes the build by specifying *external parameters* through an - *interface*, either directly or via some trigger. Usually, at least one of - these external parameters is a reference to a *dependency*. (External - parameters are literal values while dependencies are artifacts.) -2. The build platform's *control plane* interprets these external parameters, - fetches an initial set of dependencies, initializes a *build environment*, - and then starts the execution within that environment. -3. The build then performs arbitrary steps, which might include fetching - additional dependencies, and then produces one or more *output* artifacts. - The steps within the build environment are under the tenant's control. - The build platform isolates build environments from one another to some - degree (which is measured by the SLSA Build Level). -4. Finally, for SLSA Build L2+, the control plane outputs *provenance* - describing this whole process. - -Notably, there is no formal notion of "source" in the build model, just external -parameters and dependencies. Most build platforms have an explicit "source" -artifact to build from, which is often a git repository; in the build model, the -reference to this artifact is an external parameter while the artifact itself is -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. - -
Ambiguous terms to avoid - -- *Build recipe:* Could mean *external parameters,* but may include concrete - steps of how to perform a build. To avoid implementation details, we don't - define this term, but always use "external parameters" which is the - interface to a build platform. Similar terms are *build configuration - source* and *build definition*. -- *Builder:* Usually means *build platform*, but might be used for *build - environment*, the user who invoked the build, or a build tool from - *dependencies*. To avoid confusion, we always use "build platform". The only - exception is in the [provenance](/provenance/v1), where `builder` is used as - a more concise field name. - -
- -### Distribution model - -Software is distributed in identifiable units called packages -according to the rules and conventions of a package ecosystem. -Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and -[OCI](https://github.com/opencontainers/distribution-spec), while examples of -informal ecosystems include links to files on a website or distribution of -first-party software within a company. - -Abstractly, a consumer locates software within an ecosystem by asking a -distribution platform, such as a package registry, to resolve a -mutable package name into an immutable package artifact. -[^label] To publish a package artifact, the software producer asks -the registry to update this mapping to resolve to the new artifact. The registry -represents the entity or entities with the power to alter what artifacts are -accepted by consumers for a given package name. For example, if consumers only -accept packages signed by a particular public key, then it is access to that -public key that serves as the registry. - -The package name is the primary security boundary within a package ecosystem. -Different package names represent materially different pieces of -software---different owners, behaviors, security properties, and so on. -Therefore, **the package name is the primary unit being protected in SLSA**. -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 -| ---- | ----------- -| Distribution platform | An entity responsible for mapping package names to immutable package artifacts. -| 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 | A specific type of "distribution platform" used 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 - -- *Package repository:* Could mean either package registry or package name, - depending on the ecosystem. To avoid confusion, we always use "repository" - exclusively to mean "source repository", where there is no ambiguity. -- *Package manager* (without "client"): Could mean either package ecosystem, - package registry, or client-side tooling. - -
- -### Mapping to real-world ecosystems - -Most real-world ecosystems fit the package model above but use different terms. -The table below attempts to document how various ecosystems map to the SLSA -Package model. There are likely mistakes and omissions; corrections and -additions are welcome! - - - - - - - - - - - - - - - - - - - - - - - - - - -
Package ecosystem - Package registry - Package name - Package artifact -
Languages -
Cargo (Rust) - Registry - Crate name - Artifact -
CPAN (Perl) - PAUSE - Distribution - Release (or Distribution) -
Go - Module proxy - Module path - Module -
Maven (Java) - Repository - Group ID + Artifact ID - Artifact -
npm (JavaScript) - Registry - Package Name - Package -
NuGet (C#) - Host - Project - Package -
PyPA (Python) - Index - Project Name - Distribution -
Operating systems -
Dpkg (e.g. Debian) - ? - Package name - Package -
Flatpak - Repository - Application - Bundle -
Homebrew (e.g. Mac) - Repository (Tap) - Package name (Formula) - Binary package (Bottle) -
Pacman (e.g. Arch) - Repository - Package name - Package -
RPM (e.g. Red Hat) - Repository - Package name - Package -
Nix (e.g. NixOS) - Repository (e.g. Nixpkgs) or binary cache - Derivation name - Derivation or store object -
Storage systems -
GCS - n/a - Object name - Object -
OCI/Docker - Registry - Repository - Object -
Meta -
deps.dev: System - Packaging authority - Package - n/a -
purl: type - Namespace - Name - n/a -
- -Notes: - -- Go uses a significantly different distribution model than other ecosystems. - In Go, the package name is a source repository URL. While clients can fetch - directly from that URL---in which case there is no "package" or - "registry"---they usually fetch a zip file from a *module proxy*. The module - proxy acts as both a builder (by constructing the package artifact from - source) and a registry (by mapping package name to package artifact). People - trust the module proxy because builds are independently reproducible, and a - *checksum database* guarantees that all clients receive the same artifact - for a given URL. - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build platform is -certified to ensure conformance with the requirements at the level claimed by -the build platform. This certification should happen on a recurring cadence, with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer-defined -expectations of where the package source code was retrieved from and on what -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. - -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. - -
- -
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. - -
diff --git a/docs/spec/v1.1/threats-overview.md b/docs/spec/v1.1/threats-overview.md deleted file mode 100644 index 8b2d04a25..000000000 --- a/docs/spec/v1.1/threats-overview.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Supply chain threats -description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA could help. ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA could help. For a more technical discussion, see [Threats & mitigations](threats.md). - -## Summary - -![Supply Chain Threats](images/supply-chain-threats.svg) - -**Note that SLSA does not currently address all of the threats presented here.** -See [Threats & mitigations](threats.md) for what is currently addressed and -[Terminology](terminology.md) for an explanation of the supply chain model. - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that the source revision represents the intent of the producer, that all expected processes were followed and that the revision was not modified after being accepted. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - - - -
-Threats from -Known example -How SLSA could help -
A -Producer -SpySheriff: Software producer purports to offer anti-spyware software, but that software is actually malicious. -SLSA does not directly address this threat but could make it easier to discover malicious behavior in open source software, by forcing it into the publicly available source code. -For closed source software SLSA does not provide any solutions for malicious producers. -
B -Authoring & reviewing -SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. -Two-person review could have caught the unauthorized change. -
C -Source code management -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code system would have been a much harder target for the attackers. -
D -External build parameters -The Great Suspender: Attacker published software that was not built from the purported sources. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
E -Build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA Build levels have stronger security requirements for the build platform, making it more difficult for an attacker to forge the SLSA provenance and gain persistence. -
F -Artifact publication -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Distribution channel -Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Package selection -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
I -Usage -Default credentials: Attacker could leverage default credentials to access sensitive data. -SLSA does not address this threat. -
N/A -Dependency threats (i.e. A-H, recursively) -event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code. -Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source. -
- - - - - - -
-Availability threat -Known example -How SLSA could help -
N/A -Dependency becomes unavailable -Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. diff --git a/docs/spec/v1.1/threats.md b/docs/spec/v1.1/threats.md deleted file mode 100644 index e6ce1128c..000000000 --- a/docs/spec/v1.1/threats.md +++ /dev/null @@ -1,1031 +0,0 @@ ---- -title: Threats & mitigations -description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. ---- - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations with SLSA and other best practices. For an -introduction to the supply chain threats that SLSA is aiming to protect -against, see [Supply chain threats]. - -The examples on this page are meant to: - -- Explain the reasons for each of the SLSA [requirements](requirements.md). -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](levels.md) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - - - -
- -## Overview - -![Supply Chain Threats](images/supply-chain-threats.svg) - -This threat model covers the *software supply chain*, meaning the process by -which software is produced and consumed. We describe and cluster threats based -on where in the software development pipeline those threats occur, labeled (A) -through (I). This is useful because priorities and mitigations mostly cluster -along those same lines. Keep in mind that dependencies are -[highly recursive](#dependency-threats), so each dependency has its own threats -(A) through (I), and the same for *their* dependencies, and so on. For a more -detailed explanation of the supply chain model, see -[Terminology](terminology.md). - -Importantly, producers and consumers face *aggregate* risk across all of the -software they produce and consume, respectively. Many organizations produce -and/or consume thousands of software packages, both first- and third-party, and -it is not practical to rely on every individual team in the organization to do -the right thing. For this reason, SLSA prioritizes mitigations that can be -broadly adopted in an automated fashion, minimizing the chance of mistakes. - -## Source threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes modification of the source data at rest as well as insider threats, -when an authorized individual introduces an unauthorized change. - -SLSA does not yet address source threats, but we anticipate doing so in a -[future version](../../current-activities.md#source-track). - -### (A) Producer - -The producer of the software intentionally produces code that harms the -consumer, or the producer otherwise uses practices that are not deserving of the -consumer's trust. - -
Software producer intentionally creates a malicious revision of the source - -*Threat:* A producer intentionally creates a malicious revision with the intent of harming their consumers. - -*Mitigation:* -This kind of attack cannot be directly mitigated through SLSA controls. -Consumers must establish some basis to trust the organizations from which they consume software. -That basis may be: - -- The repo is open source with an active user-base. High numbers of engaged users may increase the likelihood that bad code is detected during code review and reduce the time-to-detection when bad revisions are accepted. -- The organization has sufficient legal or reputational incentives to dissuade it from making malicious changes. - -Ultimately this is a judgement call with no straightforward answer. - -*Example:* A producer with an otherwise good reputation decides suddenly to produce a malicious artifact with the intent to harm their consumers. - -
- -### (B) Modifying the source - -An adversary without any special administrator privileges attempts to introduce a change counter to the declared intent of the source by following the producer's official source control process. - -Threats in this category can be mitigated by following source control management best practices. - -#### (B1) Submit change without review - -
Directly submit without review - -*Threat:* Malicious code submitted to the source repository. - -*Mitigation:* The producer requires approval of all changes before they are accepted. - -*Example:* Adversary directly pushes a change to a git repo's `main` branch. -Solution: The producer can configure branch protection rules on the `main` branch. -A best practice is to require approval of any changes via a change management tool before they are accepted into the source. - -
-
Single actor controls multiple accounts - -*Threat:* An actor is able to control multiple account and effectively approve their own code changes. - -*Mitigation:* The producer must ensure that no actor is able to control or influence multiple accounts with review privileges. - -*Example:* Adversary creates a pull request using a secondary account and approves it using their primary account. -Solution: The producer must track all actors who have both explicit review permissions and the independent ability to control -a privileged bot. A common vector for this attack is to influence a robot account with the permission to review or contribute -code. Control of the robot account and an actor's own personal account is enough to exploit this vulnerability. A common -solution to this flow is to deny bot accounts from contributing or reviewing code, or to require more human reviews in those -cases. - -
-
Use a robot account to submit change - -*Threat:* Exploit a robot account that has the ability to submit changes without -two-person review. - -*Mitigation:* All changes require review by two people, even changes authored by -robots. - -*Example:* A file within the source repository is automatically generated by a -robot, which is allowed to submit without review. -Adversary compromises the robot and submits a malicious change. -Solution: Require two-person review for such changes, ignoring the robot. - -
-
Abuse of rule exceptions - -*Threat:* Rule exceptions provide vector for abuse. - -*Mitigation:* Remove rule exceptions. - -*Example:* A producer intends to require two-person review on "all changes except for documentation changes," defined as those only modifying `.md` files. -Adversary submits a malicious executable masquerading as a documentation file, `help.md`. -This avoids the two-person review rule due to the exception. -In the future, a user (or another workflow) can be induced to *execute* `help.md` and become compromised. -Technically the malicious code change met all defined policies yet the intent of the organization was defeated. -Solution: The producer adjusts the rules to prohibit such exceptions. - -
- -
Highly-permissioned actor bypasses or disables controls - -*Threat:* Trusted actor with "admin" privileges in a repository submits code by disabling existing controls. - -*Mitigation:* All actors must be subject to same controls, whether or not they have -administrator privileges. -Changes to the controls themselves should require their own review process. - -*Example 1:* A GitHub repository-level admin pushes a change without review, even though GitHub branch protection is enabled. -Solution: The producer can modify the rule to disallow bypass by administrators, or move the rule to an organization-level ruleset. - -*Example 2:* GitHub repository-level admin removes a branch requirement, pushes their change, then re-enables the requirement to cover their tracks. -Solution: The producer can configure higher-permission-level rules (such as organization-level GitHub Rulesets) to prevent repository-level tampering. - -
- -#### (B2) Evade change management process - -
Modify code after review - -*Threat:* Modify the code after it has been reviewed but before submission. - -*Mitigation:* Source control platform invalidates approvals whenever the proposed change is modified. - -*Example:* Source repository requires two-person review on all changes. -Adversary sends an initial "good" pull request to a peer, who approves it. -Adversary then modifies their proposal to contain "bad" code. - -Solution: Configure the code review rules to require review of the most recent revision before submission. -Resetting or "dismissing" votes on a PR introduces substantial friction to the process. -Depending on the security posture of the source, the producer has a few choices to deal with this situation. -They may: - -- Accept this risk. Code review is already expensive and the pros outweigh the cons here. -- Dismiss reviews when new changes are added. This is a common outcome when expert code review is required. -- Leave previous reviews intact, but require that "at least the last revision must be reviewed by someone." - -
-
Submit a change that is unreviewable - -*Threat:* Adversary crafts a change that is meaningless for a human to review that looks -benign but is actually malicious. - -*Mitigation:* Code review system ensures that all reviews are informed and -meaningful to the extent possible. For example the system could show -& resolve symlinks, render images, or verify & display provenance. - -*Example:* A proposed change updates a JPEG file to include a malicious -message, but the reviewer is only presented with a diff of the binary -file contents. The reviewer is unable to parse the contents themselves -so they do not have enough context to provide a meaningful review. -Solution: the code review system should present the reviewer with a -rendering of the image and the [embedded -metadata](https://en.wikipedia.org/wiki/Exif), allowing them to make an -informed decision. - -
-
Copy a reviewed change to another context - -*Threat:* Get a change reviewed in one context and then transfer it to a -different context. - -*Mitigation:* Approvals are context-specific. - -*Example:* MyPackage's source repository requires two-person review. Adversary -forks the repo, submits a change in the fork with review from a colluding -colleague (who is not trusted by MyPackage), then proposes the change to -the upstream repo. -Solution: The proposed change still requires two-person review in the upstream context even though it received two-person review in another context. - -
- - -
Commit graph attacks - -*Threat:* A malicious commit can be included in a sequence of commits such that it does not appear malicious in the net change presented to reviewers. - -*Mitigation:* The producer ensures that all revisions in the protected context followed the same contribution process. - -*Example:* Adversary sends a pull request containing malicious commit X and a commit Y that undoes X. -The combined change of X + Y displays zero lines of malicious code and the reviewer cannot tell that X is malicious unless they review it individually. -If X is allowed to become reachable from the protected branch, the content may become available in secured environments such as developer machines. - -Solution: Each revision in the protected context must have followed the intended process. -Ultimately, this means that either each code review results in at most a single new commit or that the full process is followed for each constituent commit in a proposed sequence. - -
- -#### (B3) Render code review ineffective - -
Collude with another trusted person - -*Threat:* Two trusted persons collude to author and approve a bad change. - -*Mitigation:* The producer can arbitrarily increase friction of their policies to reduce risk, such as requiring additional, or more senior reviewers. -The goal of policy here is to ensure that the approved changes match the intention of the producer for the source. -Increasing the friction of the policies may make it harder to circumvent, but doing so has diminishing returns. -Ultimately the producer will need to land upon a balanced risk profile that makes sense for their security posture. - -
-
Trick reviewer into approving bad code - -*Threat:* Construct a change that looks benign but is actually malicious, a.k.a. -"bugdoor." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
Reviewer blindly approves changes - -*Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber -stamping." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -#### (B4) Render change metadata ineffective - -
Forge change metadata - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -### (C) Source code management - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -
Platform admin abuses privileges - -*Threat:* Platform administrator abuses their privileges to bypass controls or -to push a malicious version of the software. - -*Mitigation:* The source platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals for -changes to the infrastructure, audit logging). A future [Platform -Operations Track](future-directions#platform-operations-track) may provide -more specific guidance on how to secure the underlying platform. - -*Example 1:* GitHostingService employee uses an internal tool to push changes to -the MyPackage source repo. - -*Example 2:* GitHostingService employee uses an internal tool to push a -malicious version of the server to serve malicious versions of MyPackage sources -to a specific CI/CD client but the regular version to everyone else, in order to -hide tracks. - -*Example 3:* GitHostingService employee uses an internal tool to push a -malicious version of the server that includes a backdoor allowing specific users -to bypass branch protections. Adversary then uses this backdoor to submit a -change to MyPackage without review. - -
-
Exploit vulnerability in SCM - -*Threat:* Exploit a vulnerability in the implementation of the source code -management system to bypass controls. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - -### (D) External build parameters - -An adversary builds from a version of the source code that does not match the -official source control repository, or changes the build parameters to inject -behavior that was not intended by the official source. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (E) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build platform pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -### (E) Build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Forge values of the provenance (other than output digest) (Build L2+) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, the trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][unforgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -platform to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Forge output digest of the provenance (n/a) - -*Threat:* The tenant-controlled build process sets output artifact digest -(`subject` in SLSA Provenance) without the trusted control plane verifying that -such an artifact was actually produced. - -*Mitigation:* None; this is not a problem. Any build claiming to produce a given -artifact could have actually produced it by copying it verbatim from input to -output.[^preimage] (Reminder: Provenance is only a claim that a particular -artifact was *built*, not that it was *published* to a particular registry.) - -*Example:* A legitimate MyPackage artifact has digest `abcdef` and is built -from source repo `good/my-package`. A malicious build from source repo -`evil/my-package` claims that it built artifact `abcdef` when it did not. -Solution: Verifier rejects because the source location does not match; the -forged digest is irrelevant. - -[^preimage]: Technically this requires the artifact to be known to the - adversary. If they only know the digest but not the actual contents, they - cannot actually build the artifact without a [preimage attack] on the digest - algorithm. However, even still there are no known concerns where this is a - problem. - -[preimage attack]: https://en.wikipedia.org/wiki/Preimage_attack - -
-
Compromise project owner (Build L2+) - -*Threat:* An adversary gains owner permissions for the artifact's build project. - -*Mitigation:* The build project owner must not have the ability to influence the -build process or provenance generation. - -*Example:* MyPackage is built on Awesome Builder under the project "mypackage". -Adversary is an owner of the "mypackage" project. Awesome Builder allows -owners to debug the build environment via SSH. An adversary uses this feature -to alter a build in progress. Solution: Build L3 requires the external parameters -to be complete in the provenance. The attackers access and/or actions within the -SSH connection would be enumerated within the external parameters. The updated -external parameters will not match the declared expectations causing verification -to fail. - -
-
Compromise other build (Build L3) - -*Threat:* Perform a malicious build that alters the behavior of a benign -build running in parallel or subsequent environments. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other or persist changes. - -*Example 1:* A build platform runs all builds for project MyPackage on -the same machine as the same Linux user. An adversary starts a malicious build -that listens for another build and swaps out source files, then starts a benign -build. The benign build uses the malicious build's source files, but its -provenance says it used benign source files. Solution: The build platform -changes architecture to isolate each build in a separate VM or similar. - -*Example 2:* A build platform uses the same machine for subsequent -builds. An adversary first runs a build that replaces the `make` binary with a -malicious version, then subsequently runs an otherwise benign build. Solution: -The builder changes architecture to start each build with a clean machine image. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build platform. - -*Mitigation:* Builds are [isolated] from the trusted build platform control -plane, and only the control plane has [access][unforgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a malicious artifact to a build cache that is later picked up by a -benign build process ([example][build-cache-poisoning-example]). - -*Mitigation:* Build caches must be [isolated][isolated] between builds to prevent -such cache poisoning attacks. In particular, the cache SHOULD be keyed by the -transitive closure of all inputs to the cached artifact, and the cache must -either be only writable by the trusted control plane or have SLSA Build L3 -provenance for each cache entry. - -*Example 1:* The cache key does not fully cover the transitive closure of all -inputs and instead only uses the digest of the source file itself. Adversary runs -a build over `auth.cc` with command line flags to gcc that define a marco -replacing `CheckAuth(ctx)` with `true`. When subsequent builds build `auth.cc` -they will get the attacker's poisoned instance that does not call `CheckAuth`. -Solution: Build cache is keyed by digest of `auth.cc`, command line, and digest of -gcc so changing the command line flags results in a different cache entry. - -*Example 2:* The tenant controlled build process has full write access to the -cache. Adversary observes a legitimate build of `auth.cc` which covers the -transitive closure of all inputs and notes the digest used for caching. The -adversary builds a malicious version of `auth.o` and directly writes it to the -build cache using the observed digest. Subsequent legitimate builds will use -the malicious version of `auth.o`. Solution: Each cache entry is keyed by the -transitive closure of the inputs, and the cache entry is itself a SLSA Build L3 -build with its own provenance that corresponds to the key. - -
-
Compromise build platform admin (verification) - -*Threat:* An adversary gains admin permissions for the artifact's build platform. - -*Mitigation:* The build platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals, audit -logging). - -*Example:* MyPackage is built on Awesome Builder. Awesome Builder allows -engineers on-call to SSH into build machines to debug production issues. An -adversary uses this access to modify a build in progress. Solution: Consumers -do not accept provenance from the build platform unless they trust sufficient -controls are in place to prevent abusing admin privileges. - -
- -### (F) Artifact publication - -An adversary uploads a package artifact that does not reflect the intent of the -package's official source control repository. - -This is the most direct threat because it is the easiest to pull off. If there -are no mitigations for this threat, then (D) and (E) are often indistinguishable -from this threat. - - - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Solution: Verifier rejects because builder is not as -expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Distribution channel - -An adversary modifies the package on the package registry using an -administrative interface or through a compromise of the infrastructure -including modification of the package in transit to the consumer. - -The distribution channel threats and mitigations look very similar to the -Artifact Publication (F) threats and mitigations with the main difference -being that these threats are mitigated by having the *consumer* perform -verification. - -The consumer's actions may be simplified if (F) produces a [VSA][vsa]. -In this case the consumer may replace provenance verification with -[VSA verification][vsa_verification]. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Replace the package with one built using an unofficial CI/CD pipeline -that does not build in the correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value or a VSA for corresponding `resourceUri`. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Adversary then replaces the original package within the -repository with the malicious package. Solution: Verifier rejects because -builder is not as expected. - -
-
Issue VSA from untrusted intermediary (expectations) - -*Threat:* Have an unofficial intermediary issue a VSA for a malicious package. - -*Mitigation*: Verifier requires VSAs to be issued by a trusted intermediary. - -*Example:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then issues a VSA of their own for the malicious -package. Solution: Verifier rejects because they only accept VSAs from -TheRepository which the adversary cannot issue since they do not have the -corresponding signing key. - -
-
Upload package without provenance or VSA (Build L1) - -*Threat:* Replace the original package with a malicious one without provenance. - -*Mitigation:* Verifier requires provenance or a VSA before accepting the package. - -*Example:* Adversary replaces MyPackage with a malicious version of MyPackage -on the package repository and deletes existing provenance. Solution: Verifier -rejects because provenance is missing. - -
-
Replace package and VSA with another (expectations) - -*Threat:* Replace a package and its VSA with a malicious package and its valid VSA. - -*Mitigation*: Consumer ensures that the VSA matches the package they've requested (not just the package they received) by following the [verification process](verification_summary#how-to-verify). - -*Example:* Adversary uploads a malicious package to `repo/evil-package`, -getting a valid VSA for `repo/evil-package`. Adversary then replaces -`repo/my-package` and its VSA with `repo/evil-package` and its VSA. -Solution: Verifier rejects because the VSA `resourceUri` field lists -`repo/evil-package` and not the expected `repo/my-package`. - -
-
Tamper with artifact after upload (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -replace it while retaining the original provenance or VSA. - -*Mitigation:* Verifier checks that the provenance or VSA's `subject` matches -the hash of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -replaces the modified version of the package in the repository and retains the -original provenance. Solution: Verifier rejects because the hash of the -artifact does not match the `subject` found within the provenance. - -
-
Tamper with provenance or VSA (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance or VSA to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance or VSA with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder or the VSA came from an expected verifier. - -*Example 1:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -*Example 2:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then modifies the original VSA's `subject` -field to match the digest of the malicious package. Solution: Verifier rejects -because the cryptographic signature is no longer valid. - -
- -## Usage threats - -A usage threat is a potential for an adversary to exploit behavior of the -consumer. - -### (H) Package selection - -The consumer requests a package that it did not intend. - -
Dependency confusion - -*Threat:* Register a package name in a public registry that shadows a name used -on the victim's internal registry, and wait for a misconfigured victim to fetch -from the public registry instead of the internal one. - -*Mitigation:* The mitigation is for the software producer to build internal -packages on a SLSA Level 2+ compliant build system and define expectations for -build provenance. Expectations must be verified on installation of the internal -packages. If a misconfigured victim attempts to install attacker's package with -an internal name but from the public registry, then verification against -expectations will fail. - -For more information see [Verifying artifacts](verifying-artifacts.md) -and [Defender's Perspective: Dependency Confusion and Typosquatting Attacks](/blog/2024/08/dep-confusion-and-typosquatting). - -
- -
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, the -requirement to make the source available can be a mild deterrent, can aid -investigation or ad-hoc analysis, and can complement source-based typosquatting -solutions. - -
- -### (I) Usage - -The consumer uses a package in an unsafe manner. - -
Improper usage - -*Threat:* The software can be used in an insecure manner, allowing an -adversary to compromise the consumer. - -*Mitigation:* This threat is not addressed by SLSA, but may be addressed by -efforts like [Secure by Design][secure-by-design]. - -
- -## Dependency threats - -A dependency threat is a potential for an adversary to introduce unintended -behavior in one artifact by compromising some other artifact that the former -depends on at build time. (Runtime dependencies are excluded from the model, as -[noted below](#runtime-dep).) - -Unlike other threat categories, dependency threats develop recursively through -the supply chain and can only be exploited indirectly. For example, if -application *A* includes library *B* as part of its build process, then a build -or source threat to *B* is also a dependency threat to *A*. Furthermore, if -library *B* uses build tool *C*, then a source or build threat to *C* is also a -dependency threat to both *A* and *B*. - -This version of SLSA does not explicitly address dependency threats, but we -expect that a future version will. In the meantime, you can [apply SLSA -recursively] to your dependencies in order to reduce the risk of dependency -threats. - - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively - -### Build dependency - -An adversary compromises the target artifact through one of its build -dependencies. Any artifact that is present in the build environment and has the -ability to influence the output is considered a build dependency. - -
Include a vulnerable dependency (library, base image, bundled file, etc.) - -*Threat:* Statically link, bundle, or otherwise include an artifact that is -compromised or has some vulnerability, causing the output artifact to have the -same vulnerability. - -*Example:* The C++ program MyPackage statically links libDep at build time. A -contributor accidentally introduces a security vulnerability into libDep. The -next time MyPackage is built, it picks up and includes the vulnerable version of -libDep, resulting in MyPackage also having the security vulnerability. - -*Mitigation:* A future -[Dependency track](../../current-activities#dependency-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -
-
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.) - -*Threat:* Use a compromised tool or other software artifact during the build -process, which alters the build process and injects unintended behavior into the -output artifact. - -*Mitigation:* This can be partially mitigated by treating build tooling, -including OS images, as any other artifact to be verified prior to use. -The threats described in this document apply recursively to build tooling -as do the mitigations and examples. A future -[Build Environment track](../../current-activities#build-environment-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -*Example:* MyPackage is a tarball containing an ELF executable, created by -running `/usr/bin/tar` during its build process. An adversary compromises the -`tar` OS package such that `/usr/bin/tar` injects a backdoor into every ELF -executable it writes. The next time MyPackage is built, the build picks up the -vulnerable `tar` package, which injects the backdoor into the resulting -MyPackage artifact. Solution: [apply SLSA recursively] to all build tools -prior to the build. The build platform verifies the disk image, -or the individual components on the disk image, against the associated -provenance or VSAs prior to running a build. Depending on where the initial -compromise took place (i.e. before/during vs *after* the build of the build tool itself), the modified `/usr/bin/tar` will fail this verification. - -
- -
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.) - -*Threat:* During the build process, use a compromised runtime dependency (such -as during testing or dynamic linking), which alters the build process and -injects unwanted behavior into the output. - -**NOTE:** This is technically the same case as [Use a compromised build -tool](#build-tool). We call it out to remind the reader that -[runtime dependencies](#runtime-dep) can become build dependencies if they are -loaded during the build. - -*Example:* MyPackage has a runtime dependency on package Dep, meaning that Dep -is not included in MyPackage but required to be installed on the user's machine -at the time MyPackage is run. However, Dep is also loaded during the build -process of MyPackage as part of a test. An adversary compromises Dep such that, -when run during a build, it injects a backdoor into the output artifact. The -next time MyPackage is built, it picks up and loads Dep during the build -process. The malicious code then injects the backdoor into the new MyPackage -artifact. - -*Mitigation:* In addition to all the mitigations for build tools, you can often -avoid runtime dependencies becoming build dependencies by isolating tests to a -separate environment that does not have write access to the output artifact. - -
- -### Related threats - -The following threats are related to "dependencies" but are not modeled as -"dependency threats". - -
Use a compromised dependency at runtime (modeled separately) - -*Threat:* Load a compromised artifact at runtime, thereby compromising the user -or environment where the software ran. - -*Example:* MyPackage lists package Dep as a runtime dependency. Adversary -publishes a compromised version of Dep that runs malicious code on the user's -machine when Dep is loaded at runtime. An end user installs MyPackage, which in -turn installs the compromised version of Dep. When the user runs MyPackage, it -loads and executes the malicious code from Dep. - -*Mitigation:* N/A - SLSA's -threat model does not explicitly model runtime dependencies. Instead, each -runtime dependency is considered a distinct artifact with its own threats. - -
- -## Availability threats - - - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA does not currently address availability threats, though future versions might. - -
Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, some -solutions to support hermetic and reproducible builds may also reduce the -impact of this threat. - -
-
De-list artifact - -*Threat:* The package registry stops serving the artifact. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
De-list provenance - -*Threat:* The package registry stops serving the provenance. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Verification threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above. - -
Tamper with recorded expectations - -*Threat:* Modify the verifier's recorded expectations, causing the verifier to -accept an unofficial package artifact. - -*Mitigation:* Changes to recorded expectations requires some form of -authorization, such as two-party review. - -*Example:* The package ecosystem records its expectations for a given package -name in a configuration file that is modifiable by that package's producer. The -configuration for MyPackage expects the source repository to be -`good/my-package`. The adversary modifies the configuration to also accept -`evil/my-package`, and then builds from that repository and uploads a malicious -version of the package. Solution: Changes to the recorded expectations require -two-party review. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Choose secure algorithms when using cryptographic digests, such -as SHA-256. - -*Examples:* Attacker crafts a malicious file with the same MD5 hash as a target -benign file. Attacker replaces the benign file with the malicious file. -Solution: Only accept cryptographic hashes with strong collision resistance. - -
- -
- - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively -[authentic]: requirements.md#provenance-authentic -[build-cache-poisoning-example]: https://adnanthekhan.com/2024/05/06/the-monsters-in-your-build-cache-github-actions-cache-poisoning/ -[exists]: requirements.md#provenance-exists -[isolated]: requirements.md#isolated -[unforgeable]: requirements.md#provenance-unforgeable -[secure-by-design]: https://www.cisa.gov/securebydesign -[supply chain threats]: threats-overview -[vsa]: verification_summary -[vsa_verification]: verification_summary#how-to-verify diff --git a/docs/spec/v1.1/use-cases.md b/docs/spec/v1.1/use-cases.md deleted file mode 100644 index f3d53d55c..000000000 --- a/docs/spec/v1.1/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two-person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package registry. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build platforms rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor-provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on the trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor-provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified by a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.1/verification_summary.md b/docs/spec/v1.1/verification_summary.md deleted file mode 100644 index 4b68327bd..000000000 --- a/docs/spec/v1.1/verification_summary.md +++ /dev/null @@ -1,418 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software producers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [resolvedDependencies](/provenance/v1#resolvedDependencies) of the artifact -being verified (recursively) or b) matching the non-source dependency -listed in `resolvedDependencies` (`subject.digest` == -`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` == -`resolvedDependencies.uri`) to a VSA _for that dependency_ and using -`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependencyLevels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "", - "version": { - "": "", - ... - } - }, - "timeVerified": , - "resourceUri": , - "policy": { - "uri": "", - "digest": { } - } - "inputAttestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verificationResult": "", - "verifiedLevels": [""], - "dependencyLevels": { - "": , - "": , - ... - }, - "slsaVersion": ".", -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`verifier.version` _map (string->string), optional_ - -> Map of names of components of the verification platform to their version. - - -`timeVerified` _string ([Timestamp]), optional_ - -> Timestamp indicating what time the verification occurred. - - -`resourceUri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. -> -> The `resourceUri` SHOULD be set to the URI from which the producer expects the -> consumer to fetch the artifact for verification. This enables the consumer to -> easily determine the expected value when [verifying](#how-to-verify). If the -> `resourceUri` is set to some other value, the producer MUST communicate the -> expected value, or how to determine the expected value, to consumers through -> an out-of-band channel. - - -`policy` _object ([ResourceDescriptor]), required_ - -> Describes the policy that the `subject` was verified against. -> -> The entry MUST contain a `uri` identifying which policy was applied and -> SHOULD contain a `digest` to indicate the exact version of that policy. - - -`inputAttestations` _array ([ResourceDescriptor]), optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `resolvedDependencies` field in [SLSA Provenance]. -> -> This field MAY be absent if the verifier does not support this feature. -> If non-empty, this field MUST contain information on _all_ the attestations -> used to perform verification. -> -> Each entry MUST contain a `digest` of the attestation and SHOULD contains a -> `uri` that can be used to fetch the attestation. - - -`verificationResult` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`verifiedLevels` _array ([SlsaResult]), required_ - -> Indicates the highest level of each track verified for the artifact (and not -> its dependencies), or "FAILED" if policy verification failed. -> -> Users MUST NOT include more than one level per SLSA track. Note that each SLSA -> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies -> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to -> include more than one level per track. - - -`dependencyLevels` _object, optional_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. -> A set but empty `dependencyLevels` object means that the artifact has **no** -> dependency at all, while an unset or null `dependencyLevels` means that the -> verifier makes no claims about the artifact's dependencies. -> -> Users MUST count each dependency only once per SLSA track, at the highest -> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`, -> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for -> `SLSA_BUILD_LEVEL_1`. - - -`slsaVersion` _string, optional_ - -> Indicates the version of the SLSA specification that the verifier used, in the -> form `.`. Example: `1.0`. If unset, the default is an -> unspecified minor version of `1.x`. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier", - "version": { - "slsa-verifier-linux-amd64": "v2.3.0", - "slsa-framework/slsa-verifier/actions/installer": "v2.3.0" - } - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "inputAttestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_BUILD_LEVEL_3"], - "dependencyLevels": { - "SLSA_BUILD_LEVEL_3": 5, - "SLSA_BUILD_LEVEL_2": 7, - "SLSA_BUILD_LEVEL_1": 1, - }, - "slsaVersion": "1.0" -} -``` - -## How to verify - -VSA consumers use VSAs to accomplish goals based on delegated trust. We call the -process of establishing a VSA's authenticity and determining whether it meets -the consumer's goals 'verification'. Goals differ, as do levels of confidence -in VSA producers, so the verification procedure changes to suit its context. -However, there are certain steps that most verification procedures have in -common. - -Verification MUST include the following steps: - -1. Verify the signature on the VSA envelope using the preconfigured roots of - trust. This step ensures that the VSA was produced by a trusted producer - and that it hasn't been tampered with. - -2. Verify the statement's `subject` matches the digest of the artifact in - question. This step ensures that the VSA pertains to the intended artifact. - -3. Verify that the `predicateType` is - `https://slsa.dev/verification_summary/v1`. This step ensures that the - in-toto predicate is using this version of the VSA format. - -4. Verify that the `verifier` matches the public key (or equivalent) used to - verify the signature in step 1. This step identifies the VSA producer in - cases where their identity is not implicitly revealed in step 1. - -5. Verify that the value for `resourceUri` in the VSA matches the expected - value. This step ensures that the consumer is using the VSA for the - producer's intended purpose. - -6. Verify that the value for `slsaResult` is `PASSED`. This step ensures the - artifact is suitable for the consumer's purposes. - -7. Verify that `verifiedLevels` contains the expected value. This step ensures - that the artifact is suitable for the consumer's purposes. - -Verification MAY additionally contain the following step: - -1. (Optional) Verify additional fields required to determine whether the VSA - meets your goal. - -Verification mitigates different threats depending on the VSA's contents and the -verification procedure. - -IMPORTANT: A VSA does not protect against compromise of the verifier, such as by -a malicious insider. Instead, VSA consumers SHOULD carefully consider which -verifiers they add to their roots of trust. - -### Examples - -1. Suppose consumer C wants to delegate to verifier V the decision for whether - to accept artifact A as resource R. Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` contains `SLSA_BUILD_LEVEL_UNEVALUATED`. - - Note: This example is analogous to traditional code signing. The expected - value for `verifiedLevels` is arbitrary but prenegotiated by the producer and - the consumer. The consumer does not need to check additional fields, as C - fully delegates the decision to V. - -2. Suppose consumer C wants to enforce the rule "Artifact A at resource R must - have a passing VSA from verifier V showing it meets SLSA Build Level 2+." - Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` is `SLSA_BUILD_LEVEL_2` or `SLSA_BUILD_LEVEL_3`. - - Note: In this example, verifying the VSA mitigates the same threats as - verifying the artifact's SLSA provenance. See - [Verifying artifacts](/spec/v1.0/verifying-artifacts) for details about which - threats are addressed by verifying each SLSA level. - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -SHOULD be one of these values: - -- `SLSA_BUILD_LEVEL_UNEVALUATED` -- `SLSA_BUILD_LEVEL_0` -- `SLSA_BUILD_LEVEL_1` -- `SLSA_BUILD_LEVEL_2` -- `SLSA_BUILD_LEVEL_3` -- `FAILED` (Indicates policy evaluation failed) - -Note that each SLSA level implies the levels below it in the same track. -For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` + -`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`). - -Users MAY use custom values here but MUST NOT use custom values starting with -`SLSA_`. - -## Change history - -- 1.1: - - Changed the `policy` object to recommend that the `digest` field of - the `ResourceDescriptor` is set. - - Added optional `verifier.version` field to record verification tools. - - Added Verification section with examples. - - Made `timeVerified` optional. -- 1.0: - - Replaced `materials` with `resolvedDependencies`. - - Relaxed `SlsaResult` to allow other values. - - Converted to lowerCamelCase for consistency with [SLSA Provenance]. - - Added `slsaVersion` field. -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SLSA Provenance]: /provenance -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/digest_set.md -[ResourceURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#resourceuri -[ResourceDescriptor]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/resource_descriptor.md -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[Timestamp]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules diff --git a/docs/spec/v1.1/verifying-artifacts.md b/docs/spec/v1.1/verifying-artifacts.md deleted file mode 100644 index 98790d51c..000000000 --- a/docs/spec/v1.1/verifying-artifacts.md +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: Verifying artifacts -description: SLSA uses provenance to indicate whether an artifact is authentic or not, but provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection verification, and this page describes how to verify artifacts and their SLSA provenance. The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that -inspection **verification**, and this page describes recommendations for how to -verify artifacts and their SLSA provenance. - -This page is divided into several sections. The first describes the process -for verifying an artifact and its provenance against a set of expectations. The -second describes how to form the expectations used to verify provenance. The -third discusses architecture choices for where provenance verification can -happen. - -## How to verify - -Verification SHOULD include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- Verifying the signature on the provenance envelope. -- Ensuring that the values for `buildType` and `externalParameters` in the - provenance match the expected values. The package ecosystem MAY allow - an approved list of `externalParameters` to be ignored during verification. - Any unrecognized `externalParameters` SHOULD cause verification to fail. - -![Threats covered by each step](images/supply-chain-threats-build-verification.svg) - -See [Terminology](terminology.md) for an explanation of the supply chain model and -[Threats & mitigations](threats.md) for a detailed explanation of each threat. - -**Note:** This section assumes that the provenance is in the recommended -[provenance format](/provenance/v1). If it is not, then the verifier SHOULD -perform equivalent checks on provenance fields that correspond to the ones -referenced here. - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "E", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This configuration - is likely in the form of a map from (builder public key identity, - `builder.id`) to (SLSA Build level). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the artifact in question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "E"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Verifying build platforms](verifying-systems). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "I".) -- [Threat "I"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not yet cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. Those threats are - discussed in more detail under [Threat "H"]. - -[Threat "E"]: threats#e-build-process -[Threat "F"]: threats#f-artifact-publication -[Threat "G"]: threats#g-distribution-channel -[Threat "H"]: threats#h-package-selection -[Threat "I"]: threats#i-usage - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets your expectations for that -package in order to mitigate [threat "D"]. - -In our threat model, the adversary has the ability to invoke a build and to publish -to the registry. The adversary is not able to write to the source repository, nor do -they have insider access to any trusted systems. Your expectations SHOULD be -sufficient to detect or prevent this adversary from injecting unofficial -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 - -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 -range of values (possibly any value) if it is known that any value in the range -is safe. JSON comparison is sufficient for verifying parameters. - -TIP: Difficulty in forming meaningful expectations about `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "D"]: threats#d-external-build-parameters - -### Step 3: (Optional) Check dependencies recursively - -[verify-step-3]: #step-3-optional-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. Note that SLSA v1.0 does not have any requirements on the -completeness or verification of `resolvedDependencies`. However, one might wish -to verify dependencies in order to mitigate [dependency threats] and protect against -threats further up the supply chain. If `resolvedDependencies` is incomplete, -these checks can be done on a best-effort basis. - -A [Verification Summary Attestation (VSA)][VSA] can make dependency verification -more efficient by recording the result of prior verifications. A trimming -heuristic or exception mechanism is almost always necessary when verifying -dependencies because there will be transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) - -[dependency threats]: threats#dependency-threats -[VSA]: /verification_summary -[threats]: threats - -## Forming Expectations - -Expectations are known provenance values that indicate the -corresponding artifact is authentic. For example, a package ecosystem may -maintain a mapping between package names and their canonical source -repositories. That mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git branches or tags. - -- **Defined by producer:** The package producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the package's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -- **Defined in source:** The source repository tells the verifier what their - expectations ought to be. In this model, the package name is immutably bound - to a source repository and all other external parameters are defined in the - source repository. This is how the Go ecosystem works, for example, since - the package name *is* the source repository location. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -will likely have different artifacts and therefore different provenance. Similarly, an -artifact might have different names in different package ecosystems but use the same -provenance file. - -## Architecture options - -There are several options (non-mutually exclusive) for where provenance verification -can happen: the package ecosystem at upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify provenance. For example, even if a package -ecosystem verifies provenance, consumers who get artifacts from that package -ecosystem might wish to verify provenance themselves for defense in depth. They -can do so using either client-side verification tooling or by polling a -monitor. - - - -### Package ecosystem - -[Package ecosystem]: #package-ecosystem - -A package ecosystem is a set of rules and conventions governing -how packages are distributed. Every package artifact has an ecosystem, whether it is -formal or ad-hoc. Some ecosystems are formal, such as language distribution -(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". For more background, see -[Package Model](terminology.md#package-model). - -During package upload, a package ecosystem can ensure that the artifact's -provenance matches the expected values for that package name's provenance before -accepting it into the package registry. This option is RECOMMENDED whenever -possible because doing so benefits all of the package ecosystem's clients. - -The package ecosystem is responsible for making its expectations available to -consumers, reliably redistributing artifacts and provenance, and providing tools -to enable safe artifact consumption (e.g. whether an artifact meets -expectations). - -### Consumer - -[Consumer]: #consumer - -A package artifact's consumer is the organization or individual that uses the -package artifact. - -Consumers can form their own expectations for artifacts or use the default -expectations provided by the package producer and/or package ecosystem. -When forming their own expectations, the consumer uses client-side verification tooling to ensure -that the artifact's provenance matches their expectations for that package -before use (e.g. during installation or deployment). Client-side verification -tooling can be either standalone, such as -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into -the package ecosystem client. - -### Monitor - -[Monitor]: #monitor - -A monitor is a service that verifies provenance for a set -of packages and publishes the result of that verification. The set of -packages verified by a monitor is arbitrary, though it MAY mimic the set -of packages published through one or more package ecosystems. The monitor -SHOULD publish its expectations for all the packages it verifies. - -Consumers can continuously poll a monitor to detect artifacts that -do not meet the monitor's expectations. Detecting artifacts that fail -verification is of limited benefit unless a human or automated system takes -action in response to the failed verification. diff --git a/docs/spec/v1.1/verifying-systems.md b/docs/spec/v1.1/verifying-systems.md deleted file mode 100644 index 99e897f2a..000000000 --- a/docs/spec/v1.1/verifying-systems.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Verifying build platforms -description: Guidelines for assessing build platform security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust platforms to produce Build L3 -artifacts and provenance unless they have some proof that the provenance is -[unforgeable](requirements.md#provenance-unforgeable) and the builds are -[isolated](requirements.md#isolated). - -This page describes the parts of a build platform that consumers SHOULD assess -and provides sample questions consumers can ask when assessing a build platform. -See also [Threats & mitigations](threats.md) and the -[build model](terminology.md#build-model). - -## Threats - -### Adversary goal - -The SLSA Build track defends against an adversary whose primary goal is to -inject unofficial behavior into a package artifact while avoiding detection. -Remember that [verifiers](verifying-artifacts.md) only accept artifacts whose -provenance matches expectations. To bypass this, the adversary tries to either -(a) tamper with a legitimate build whose provenance already matches -expectations, or (b) tamper with an illegitimate build's provenance to make it -match expectations. - -More formally, if a build with external parameters P would produce an artifact -with binary hash X and a build with external parameters P' would produce an -artifact with binary hash Y, they wish to produce provenance indicating a build -with external parameters P produced an artifact with binary hash Y. - -See threats [D], [E], [F], and [G] for examples of specific threats. - -Note: Platform abuse (e.g. running non-build workloads) and attacks against -builder availability are out of scope of this document. - -### Adversary profiles - -Consumers SHOULD also evaluate the build platform's ability to defend against the -following types of adversaries. - -1. Project contributors, who can: - - Create builds on the build platform. These are the adversary's controlled - builds. - - Modify one or more controlled builds' external parameters. - - Modify one or more controlled builds' environments and run arbitrary - code inside those environments. - - Read the target build's source repo. - - Fork the target build's source repo. - - Modify a fork of the target build's source repo and build from it. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Create new builds under the target build's project or identity. - - Modify the target build's source repo and build from it. - - Modify the target build's configuration. -3. Build platform administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Run arbitrary code on the build platform. - - Read and modify network traffic. - - Access the control plane's cryptographic secrets. - - Remotely access build environments (e.g. via SSH). - -[D]: threats.md#d-external-build-parameters -[E]: threats.md#e-build-process -[F]: threats.md#f-artifact-publication -[G]: threats.md#g-distribution-channel - -## Build platform components - -Consumers SHOULD consider at least these five elements of the -[build model](terminology.md#build-model) when assessing build platforms for SLSA -conformance: external parameters, control plane, build environments, caches, -and outputs. - -![image](images/build-model.svg) - -The following sections detail these elements of the build model and give prompts -for assessing a build platform's ability to produce SLSA Build L3 provenance. The -assessment SHOULD take into account the security model used to identify the -transitive closure of the `builder.id` for the [provenance model](provenance.md#model), specifically -around the platform's boundaries, actors, and interfaces. - -### External parameters - -External parameters are the external interface to the builder and include all -inputs to the build process. Examples include the source to be built, the build -definition/script to be executed, user-provided instructions to the -control plane for how to create the build environment (e.g. which operating -system to use), and any additional user-provided strings. - -#### Prompts for assessing external parameters - -- How does the control plane process user-provided external parameters? - Examples: sanitizing, parsing, not at all -- Which external parameters are processed by the control plane and which are - processed by the build environment? -- What sort of external parameters does the control plane accept for - build environment configuration? -- How do you ensure that all external parameters are represented in the - provenance? -- How will you ensure that future design changes will not add additional - external parameters without representing them in the provenance? - -### Control plane - -The control plane is the build platform component that orchestrates each -independent build execution. It is responsible for setting up each build and -cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs -provenance for each build performed on the build platform. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -#### Prompts for assessing the control plane - -- Administration - - What are the ways an employee can use privileged access to influence a - build or provenance generation? Examples: physical access, terminal - access, access to cryptographic secrets - - What controls are in place to detect or prevent the employee from - abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many employees have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and platform - outages? Are they tested? How frequently? - -- Provenance generation - - How does the control plane observe the build to ensure the provenance's - accuracy? - - Are there situations in which the control plane will not generate - provenance for a completed build? What are they? - -- Development practices - - How do you track the control plane's software and configuration? - Example: version control - - How do you build confidence in the control plane's software supply - chain? Example: SLSA L3+ provenance, build from source - - How do you secure communications between builder components? Example: - TLS with certificate transparency. - - Are you able to perform forensic analysis on compromised build - environments? How? Example: retain base images indefinitely - -- Creating build environments - - How does the control plane share data with build environments? Example: - mounting a shared file system partition - - How does the control plane protect its integrity from build - environments? Example: not mount its own file system partitions on - build environments - - How does the control plane prevent build environments from accessing its - cryptographic secrets? Examples: dedicated secret storage, not mounting - its own file system partitions to build environments, hardware security - modules - -- Managing cryptographic secrets - - How do you store the control plane's cryptographic secrets? - - Which parts of the organization have access to the control plane's - cryptographic secrets? - - What controls are in place to detect or prevent employees abusing such - access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Build environment - -The build environment is the independent execution context where the build -takes place. In the case of a distributed build, the build environment is the -collection of all execution contexts that run build steps. Each build -environment must be isolated from the control plane and from all other build -environments, including those running builds from the same tenant or project. -Tenants are free to modify the build environment arbitrarily. Build -environments must have a means to fetch input artifacts (source, dependencies, -etc). - -#### Prompts for assessing build environments - -- Isolation technologies - - How are build environments isolated from the control plane and each - other? Examples: VMs, containers, sandboxed processes - - How is separation achieved between trusted and untrusted processes? - - How have you hardened your build environments against malicious tenants? - Examples: configuration hardening, limiting attack surface - - How frequently do you update your isolation software? - - What is your process for responding to vulnerability disclosures? What - about vulnerabilities in your dependencies? - - What prevents a malicious build from gaining persistence and influencing - subsequent builds? - -- Creation and destruction - - What operating system and utilities are available in build environments - on creation? How were these elements chosen? Examples: A minimal Linux - distribution with its package manager, OSX with HomeBrew - - How long could a compromised build environment remain active in the - build platform? - -- Network access - - Are build environments able to call out to remote execution? If so, how - do you prevent them from tampering with the control plane or other build - environments over the network? - - Are build environments able to open services on the network? If so, how - do you prevent remote interference through these services? - -### Cache - -Builders may have zero or more caches to store frequently used dependencies. -Build environments may have either read-only or read-write access to caches. - -#### Prompts for assessing caches - -- What sorts of caches are available to build environments? -- How are those caches populated? -- How are cache contents validated before use? - -### Output storage - -Output Storage holds built artifacts and their provenance. Storage may either be -shared between build projects or allocated separately per-project. - -#### Prompts for assessing output storage - -- How do you prevent builds from reading or overwriting files that belong to - another build? Example: authorization on storage -- What processing, if any, does the control plane do on output artifacts? - -## Builder evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model defined as -part of the provenance. Evidence submitted for third-party certification need not -be published. diff --git a/docs/spec/v1.1/whats-new.md b/docs/spec/v1.1/whats-new.md deleted file mode 100644 index bf3bdbbd4..000000000 --- a/docs/spec/v1.1/whats-new.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: What's new -description: The changes brought by SLSA v1.1. ---- - -This document describes the major changes brought by SLSA v1.1 -relative to the prior release, [v1.0]. - -## Summary of changes - -- Clarify that attestation format schema are informative and the - specification texts (SLSA and [in-toto attestation]) are the canonical - source of definitions. -- Add procedure for verifying VSAs. -- Add verifier metadata to VSA format. -- It is now recommended that the `digest` field of `ResourceDescriptor` is - set in a Verification Summary Attestation's (VSA) `policy` object. -- Further refine the [threat model](threats). - - - -[in-toto attestation]: https://github.com/in-toto/attestation -[v1.0]: /spec/v1.0/ diff --git a/docs/spec/v1.2-rc1/about.md b/docs/spec/v1.2-rc1/about.md deleted file mode 100644 index a763594e7..000000000 --- a/docs/spec/v1.2-rc1/about.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: About SLSA -description: With supply chain attacks on the rise, a shared vocabulary and universal framework are needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software. ---- - -This page is an introduction to SLSA and its concepts. If you're new -to SLSA, start here! - -## What is SLSA? - -Supply-chain Levels for Software Artifacts, or SLSA ("salsa"), is a set of incrementally adoptable guidelines for supply chain security, -established by industry consensus. The specification set by SLSA is useful for -both software producers and consumers: producers can follow SLSA's guidelines to -make their software supply chain more secure, and consumers can use SLSA to make -decisions about whether to trust a software package. - -SLSA offers: - -- A common vocabulary to talk about software supply chain security -- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume -- An actionable checklist to improve your own software's security -- A way to measure your efforts toward compliance with the [Secure Software Development Framework (SSDF)](https://csrc.nist.gov/Projects/ssdf) - -## Why SLSA is needed - -High-profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply -chain integrity weaknesses that may go unnoticed, yet quickly become very -public, disruptive, and costly in today's environment when exploited. They've -also shown that there are inherent risks not just in code itself, but at -multiple points in the complex process of getting that code into software -systems—that is, in the **software supply chain**. Since these attacks are on -the rise and show no sign of decreasing, a universal framework for hardening the -software supply chain is needed, as affirmed by the U.S. Executive Order on -Improving the Nation's Cybersecurity of May 12th, 2021. - -Security techniques for vulnerability detection and analysis of source code are -essential, but are not enough on their own. Even after fuzzing or vulnerability -scanning is completed, changes to code can happen, whether unintentionally or -from insider threats or compromised accounts. Risk for code modification exists at -each link in a typical software supply chain, from source to build through -packaging and distribution. Any weaknesses in the supply chain undermine -confidence in whether the code that you run is actually the code that you -scanned. - -SLSA is designed to support automation that tracks code handling from source -to binary, protecting against tampering regardless of the complexity -of the software supply chain. As a result, SLSA increases trust that the -analysis and review performed on source code can be assumed to still apply to -the binary consumed after the build and distribution process. - -## SLSA in layperson's terms - -There has been a [lot of discussion](https://ntia.gov/page/software-bill-materials) about the need for "ingredient labels" for -software—a "software bill of materials" (SBOM) that tells users what is in their -software. Building off this analogy, SLSA can be thought of as all the food -safety handling guidelines that make an ingredient list credible. From standards -for clean factory environments so contaminants aren't introduced in packaging -plants, to the requirement for tamper-proof seals on lids that ensure nobody -changes the contents of items sitting on grocery store shelves, the entire food -safety framework ensures that consumers can trust that the ingredient list -matches what's actually in the package they buy. - -Likewise, the SLSA framework provides this trust with guidelines and -tamper-resistant evidence for securing each step of the software production -process. That means you know not only that nothing unexpected was added to the -software product, but also that the ingredient label itself wasn't tampered with -and accurately reflects the software contents. In this way, SLSA helps protect -against the risk of: - -- Code modification (by adding a tamper-evident "seal" to code after - source control) -- Uploaded artifacts that were not built by the expected CI/CD platform (by marking - artifacts with a factory "stamp" that shows which build platform created it) -- Threats against the build platform (by providing "manufacturing facility" - best practices for build platform services) - -For more exploration of this analogy, see the blog post -[SLSA + SBOM: Accelerating SBOM success with the help of SLSA](/blog/2022/05/slsa-sbom). - -## Who is SLSA for? - -In short: everyone involved in producing and consuming software, or providing -infrastructure for software. - -**Software producers**, such as an open source project, a software vendor, or a -team writing first-party code for use within the same company. SLSA gives you -protection against tampering along the supply chain to your consumers, both -reducing insider risk and increasing confidence that the software you produce -reaches your consumers as you intended. - -**Software consumers**, such as a development team using open source packages, a -government agency using vendored software, or a CISO judging organizational -risk. SLSA gives you a way to judge the security practices of the software you -rely on and be sure that what you receive is what you expected. - -**Infrastructure providers**, who provide infrastructure such as an ecosystem -package manager, build platform, or CI/CD platform. As the bridge between the -producers and consumers, your adoption of SLSA enables a secure software supply -chain between them. - -## How SLSA works - -We talk about SLSA in terms of [tracks and levels](tracks.md). -A SLSA track focuses on a particular aspect of a supply chain, such as the Build -Track. - -Within each track, ascending levels indicate increasingly hardened security -practices. Higher levels provide better guarantees against supply chain threats, -but come at higher implementation costs. Lower SLSA levels are designed to be -easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes -used to refer to software that doesn't yet meet any SLSA level. Currently, the -SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels -to be possible in [future revisions](future-directions.md). - -The combination of tracks and levels offers an easy way to discuss whether -software meets a specific set of requirements. By referring to an artifact as -meeting SLSA Build Level 3, for example, you're indicating in one phrase that -the software artifact was built following a set of security practices that -industry leaders agree protect against particular supply chain compromises. - -## What SLSA doesn't cover - -SLSA is only one part of a thorough approach to supply chain security. There -are several areas outside SLSA's current framework that are nevertheless -important to consider together with SLSA such as: - -- Code quality: SLSA does not tell you whether the developers writing the - source code followed secure coding practices. -- Producer trust: SLSA does not address organizations that intentionally - produce malicious software, but it can reduce insider risks within an - organization you trust. -- Transitive trust for dependencies: the SLSA level of an artifact is - independent of the level of its dependencies. You can use SLSA recursively to - also judge an artifact's dependencies on their own, but there is - currently no single SLSA level that applies to both an artifact and its - transitive dependencies together. For a more detailed explanation of why, - see the [FAQ](faq#q-why-is-slsa-not-transitive). diff --git a/docs/spec/v1.2-rc1/assessing-build-platforms.md b/docs/spec/v1.2-rc1/assessing-build-platforms.md deleted file mode 100644 index dd17f3a0b..000000000 --- a/docs/spec/v1.2-rc1/assessing-build-platforms.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: "Build: Assessing build platforms" -description: Guidelines for assessing build platform security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust platforms to produce Build L3 -artifacts and provenance unless they have some proof that the provenance is -[unforgeable](build-requirements.md#provenance-unforgeable) and the builds are -[isolated](build-requirements.md#isolated). - -This page describes the parts of a build platform that consumers SHOULD assess -and provides sample questions consumers can ask when assessing a build platform. -See also [Threats & mitigations](threats.md) and the -[build model](terminology.md#build-model). - -## Threats - -### Adversary goal - -The SLSA Build track defends against an adversary whose primary goal is to -inject unofficial behavior into a package artifact while avoiding detection. -Remember that [verifiers](verifying-artifacts.md) only accept artifacts whose -provenance matches expectations. To bypass this, the adversary tries to either -(a) tamper with a legitimate build whose provenance already matches -expectations, or (b) tamper with an illegitimate build's provenance to make it -match expectations. - -More formally, if a build with external parameters P would produce an artifact -with binary hash X and a build with external parameters P' would produce an -artifact with binary hash Y, they wish to produce provenance indicating a build -with external parameters P produced an artifact with binary hash Y. - -See threats [D], [E], [F], and [G] for examples of specific threats. - -Note: Platform abuse (e.g. running non-build workloads) and attacks against -builder availability are out of scope of this document. - -### Adversary profiles - -Consumers SHOULD also evaluate the build platform's ability to defend against the -following types of adversaries. - -1. Project contributors, who can: - - Create builds on the build platform. These are the adversary's controlled - builds. - - Modify one or more controlled builds' external parameters. - - Modify one or more controlled builds' environments and run arbitrary - code inside those environments. - - Read the target build's source repo. - - Fork the target build's source repo. - - Modify a fork of the target build's source repo and build from it. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Create new builds under the target build's project or identity. - - Modify the target build's source repo and build from it. - - Modify the target build's configuration. -3. Build platform administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Run arbitrary code on the build platform. - - Read and modify network traffic. - - Access the control plane's cryptographic secrets. - - Remotely access build environments (e.g. via SSH). - -[D]: threats.md#d-external-build-parameters -[E]: threats.md#e-build-process -[F]: threats.md#f-artifact-publication -[G]: threats.md#g-distribution-channel - -## Build platform components - -Consumers SHOULD consider at least these five elements of the -[build model](terminology.md#build-model) when assessing build platforms for SLSA -conformance: external parameters, control plane, build environments, caches, -and outputs. - -![image](images/build-model.svg) - -The following sections detail these elements of the build model and give prompts -for assessing a build platform's ability to produce SLSA Build L3 provenance. -The assessment SHOULD take into account the security model used to identify the -transitive closure of the `builder.id` for the -[provenance model](build-provenance.md#model), specifically around the -platform's boundaries, actors, and interfaces. - -### External parameters - -External parameters are the external interface to the builder and include all -inputs to the build process. Examples include the source to be built, the build -definition/script to be executed, user-provided instructions to the -control plane for how to create the build environment (e.g. which operating -system to use), and any additional user-provided strings. - -#### Prompts for assessing external parameters - -- How does the control plane process user-provided external parameters? - Examples: sanitizing, parsing, not at all -- Which external parameters are processed by the control plane and which are - processed by the build environment? -- What sort of external parameters does the control plane accept for - build environment configuration? -- How do you ensure that all external parameters are represented in the - provenance? -- How will you ensure that future design changes will not add additional - external parameters without representing them in the provenance? - -### Control plane - -The control plane is the build platform component that orchestrates each -independent build execution. It is responsible for setting up each build and -cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs -provenance for each build performed on the build platform. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -#### Prompts for assessing the control plane - -- Administration - - What are the ways an employee can use privileged access to influence a - build or provenance generation? Examples: physical access, terminal - access, access to cryptographic secrets - - What controls are in place to detect or prevent the employee from - abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many employees have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and platform - outages? Are they tested? How frequently? - -- Provenance generation - - How does the control plane observe the build to ensure the provenance's - accuracy? - - Are there situations in which the control plane will not generate - provenance for a completed build? What are they? - -- Development practices - - How do you track the control plane's software and configuration? - Example: version control - - How do you build confidence in the control plane's software supply - chain? Example: SLSA L3+ provenance, build from source - - How do you secure communications between builder components? Example: - TLS with certificate transparency. - - Are you able to perform forensic analysis on compromised build - environments? How? Example: retain base images indefinitely - -- Creating build environments - - How does the control plane share data with build environments? Example: - mounting a shared file system partition - - How does the control plane protect its integrity from build - environments? Example: not mount its own file system partitions on - build environments - - How does the control plane prevent build environments from accessing its - cryptographic secrets? Examples: dedicated secret storage, not mounting - its own file system partitions to build environments, hardware security - modules - -- Managing cryptographic secrets - - How do you store the control plane's cryptographic secrets? - - Which parts of the organization have access to the control plane's - cryptographic secrets? - - What controls are in place to detect or prevent employees abusing such - access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Build environment - -The build environment is the independent execution context where the build -takes place. In the case of a distributed build, the build environment is the -collection of all execution contexts that run build steps. Each build -environment must be isolated from the control plane and from all other build -environments, including those running builds from the same tenant or project. -Tenants are free to modify the build environment arbitrarily. Build -environments must have a means to fetch input artifacts (source, dependencies, -etc). - -#### Prompts for assessing build environments - -- Isolation technologies - - How are build environments isolated from the control plane and each - other? Examples: VMs, containers, sandboxed processes - - How is separation achieved between trusted and untrusted processes? - - How have you hardened your build environments against malicious tenants? - Examples: configuration hardening, limiting attack surface - - How frequently do you update your isolation software? - - What is your process for responding to vulnerability disclosures? What - about vulnerabilities in your dependencies? - - What prevents a malicious build from gaining persistence and influencing - subsequent builds? - -- Creation and destruction - - What operating system and utilities are available in build environments - on creation? How were these elements chosen? Examples: A minimal Linux - distribution with its package manager, OSX with HomeBrew - - How long could a compromised build environment remain active in the - build platform? - -- Network access - - Are build environments able to call out to remote execution? If so, how - do you prevent them from tampering with the control plane or other build - environments over the network? - - Are build environments able to open services on the network? If so, how - do you prevent remote interference through these services? - -### Cache - -Builders may have zero or more caches to store frequently used dependencies. -Build environments may have either read-only or read-write access to caches. - -#### Prompts for assessing caches - -- What sorts of caches are available to build environments? -- How are those caches populated? -- How are cache contents validated before use? - -### Output storage - -Output Storage holds built artifacts and their provenance. Storage may either be -shared between build projects or allocated separately per-project. - -#### Prompts for assessing output storage - -- How do you prevent builds from reading or overwriting files that belong to - another build? Example: authorization on storage -- What processing, if any, does the control plane do on output artifacts? - -## Builder evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model defined as -part of the provenance. Evidence submitted for third-party certification need not -be published. diff --git a/docs/spec/v1.2-rc1/assessing-source-systems.md b/docs/spec/v1.2-rc1/assessing-source-systems.md deleted file mode 100644 index 0ad3ecba3..000000000 --- a/docs/spec/v1.2-rc1/assessing-source-systems.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: "Source: Assessing source control systems" -description: Guidelines for assessing source control system security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust source control systems (SCSs) unless -they have some proof that an SCS meets its -[requirements](source-requirements.md). - -This page describes the parts of an SCS that consumers SHOULD assess and -provides sample questions consumers can ask when assessing a SCS. See also -[Threats & mitigations](threats.md). - -## Threats - -### Adversary goal - -The SLSA Source track defends against an adversary whose primary goal is to -inject unofficial behavior into protected source code while avoiding detection. -Organizations typically establish change management processes to prevent this -unofficial behavior from being introduced. The adversary's goal is to bypass the -change management process. - -### Adversary profiles - -Consumers SHOULD also evaluate the source control systems' ability to defend -against the following types of adversaries. - -1. Project contributors, who can: - - Propose changes to protected branches of the source repo. - - Upload new content to the source repo. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Define the purpose of the source repo. - - Add or remove contributors to the source repo. - - Add or remove permissions granted to contributors of the source repo. - - Modify security controls within the source repo. - - Modify controls used to enforce the change management process on the - source repo. -3. Source control system administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Modify the source repo while bypassing the project maintainer's controls. - - Modify the behavior of the Source Control System itself. - - Access the control plane's cryptographic secrets. - -## Source Control System components - -Consumers SHOULD consider at least these elements when assessing a Source -Control System for SLSA conformance: control configuration, change management -interface, control plane, verifier, storage. - -![source control system components](images/source-control-system-components.svg) - -The following section details these elements. - -### Change management interface - -The change management interface is the user interface for proposing and -approving changes to protected branches within a source repository. During -normal operation all such changes go through this interface. - -### Control configuration - -Control configuration is how organizations establish technical controls in a -given source repository. If done well the configuration will reflect the intent -of the organization. - -### Technical controls - -Technical controls are the organization configured settings that are used to -determine if a revision can be introduced into storage within any particular -context and who has access to those revisions. - -The technical controls component is responsible for the storage of these -settings while the [control plane](#control-plane) is responsible for enforcing -the configured controls. - -They include: - -- Read/write ACLs, -- If approvals are required to introduce changes within a given context -- Which actors are allowed to issue those approvals -- Organization defined - [change management processes](#enforced-change-management-process) - requirements -- etc... - -### Control plane - -The control plane is the SCS component that orchestrates the introduction and -creation of new revisions into a source repository. It is responsible for -enforcing [technical controls](#technical-controls) and, at SLSA Source L3+, -generating and signing source provenance for each revision. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -### Verifier - -The verifier is the SCS component that evaluates source provenance and generates -and signs a -[verification summary attestation](source-requirements#summary-attestation) -(VSA). - -### Storage - -Storage holds source revisions and their provenance and summary attestations. - -## Assessing components - -The following are prompts for assessing a Source Control System's ability to -meet the SLSA requirements. - -### Prompts for assessing the change management interface - -- How does the SCS manage which actors are permitted to approve changes? -- What types of non-plain-text changes can the change management interface - render? How well does the SCS render those changes? -- What controls does the change management interface provide for enabling - Trusted Robot Contributions? Example: SLSA Build L3+ provenance, built from - SLSA Source L4+ source. - -### Prompts for assessing control configuration & technical controls - -- How does the SCS prevent regression in control configurations? - Examples: built-in controls that cannot change, notifying project - maintainers when controls change, requiring public declaration of control - changes. -- How does the SCS prevent individual project maintainers from tampering with - controls configured by the project? -- How does the SCS prevent SCS administrators from tampering with a project's - configured technical controls? - -### Prompts for assessing the control plane & verifier - -NOTE The control plane and verifier perform related roles within the SCS and -should typically be assessed together. - -- Administration - - What are the ways an SCS administrator can use privileged access to - influence a revision creation, provenance generation, or VSA generation? - Examples: physical access, terminal access, access to cryptographic - secrets - - What controls are in place to detect or prevent an SCS administrator - from abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many SCS maintainers have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and - platform outages? Are they tested? How frequently? - -- Control effectiveness - - How does the SCS ensure the control plane is enforcing the - [technical controls](#technical-controls) are working as intended? - -- Source provenance generation - - How does the control plane observe the revision creation to ensure the - provenance's accuracy? - - Are there situations in which the control plane will not generate - source provenance? What are they? - - What details are included in the source provenance? Are they sufficient - to mitigate tampering with other SCS components? - -- VSA generation - - How does the verifier determine what source level a revision meets? - - How does the verifier determine the organization's control expectations - and if they are met? - -- Development practices - - How do you track the control plane and verifier's software and - configuration? - Example: version control. - - How do you build confidence in the control plane's software supply - chain? Example: SLSA Build L3+ provenance, built from SLSA Source L4+ - source. - - How do you secure communications between components? Example: TLS with - certificate transparency. - -- Managing cryptographic secrets - - How do you store the control plane and verifier's cryptographic secrets? - - Which parts of the organization have access to the control plane and - verifier's cryptographic secrets? - - What controls are in place to detect or prevent SCS administrators from - abusing such access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Prompts for assessing output storage - -- How do you prevent tampering with storage directly? -- How do you prevent one project's revisions from affecting another project? - -## Source control system evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model used in the -evaluation. Evidence submitted for third-party certification need not be -published. diff --git a/docs/spec/v1.2-rc1/attestation-model.md b/docs/spec/v1.2-rc1/attestation-model.md deleted file mode 100644 index 105cd9409..000000000 --- a/docs/spec/v1.2-rc1/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first-party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed-source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open-source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open-source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed-source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third-party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /build-provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.2-rc1/build-provenance.md b/docs/spec/v1.2-rc1/build-provenance.md deleted file mode 100644 index 02d07e612..000000000 --- a/docs/spec/v1.2-rc1/build-provenance.md +++ /dev/null @@ -1,599 +0,0 @@ ---- -title: "Build: Provenance" -description: Description of SLSA build provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when, and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](requirements#provenance-generation). - -## Model - -Provenance is an attestation that a particular build platform produced a set of -software artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant build platform. - The `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build platforms.) - - - The build platform implementer SHOULD define a security model for the build - platform in order to clearly identify the platform's boundaries, actors, - and interfaces. This model SHOULD then be used to identify the transitive - closure of the trusted build platform for the `builder.id` as well as the - trusted control plane. - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - platform ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `internalParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](requirements.md). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." - Such changes do not update the `predicateType`. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -### Summary - -*NOTE: This summary (in cue) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -*NOTE: This summary (in protobuf) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - -Link: [provenance.proto](schema/provenance.proto) - -*NOTE: This protobuf definition prioritizes being a human-readable summary -of the schema for readers of the specification. A version of the protobuf -definition useful for code generation is maintained in the -[in-toto attestation] repository.* - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`internalParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that -there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build platform SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
internalParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build platform is already trusted, and in many cases it is -not practical to do so. - -
resolvedDependencies -array (ResourceDescriptor) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script -fetches and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be -listed here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `internalParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `internalParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build platform. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build platform to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build platform to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the build platform that executed the invocation, which is trusted to -have correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ResourceDescriptor) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or -incident response. For example, this might reference logs generated during -the build and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted build platform. This is -[intended](verifying-artifacts#step-1-check-slsa-build-level) -to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -The `builder.id` URI SHOULD resolve to documentation explaining: - -- The scope of what this ID represents. -- The claimed SLSA Build level. -- The accuracy and completeness guarantees of the fields in the provenance. -- Any fields that are generated by the tenant-controlled build process and not - verified by the trusted control plane, except for the `subject`. -- The interpretation of any extension fields. - -
builderDependencies -array (ResourceDescriptor) - -Dependencies used by the orchestrator that are not run within the workload -and that do not affect the build, but might affect the provenance generation -or security guarantees. - -
version -map (string→string) - -Map of names of components of the build platform to their version. - -
- -The build platform, or builder for short, represents the transitive -closure of all the entities that are, by necessity, [trusted] to faithfully run -the build and record the provenance. This includes not only the software but the -hardware and people involved in running the service. For example, a particular -instance of [Tekton](https://tekton.dev/) could be a build platform, while -Tekton itself is not. For more info, see [Build -model](terminology#build-model). - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -### Extension fields - -[Extension fields]: #extension-fields - -Implementations MAY add extension fields to any JSON object to describe -information that is not captured in a standard field. Guidelines: - -- Extension fields SHOULD use names of the form `_`, e.g. - `examplebuilder_isCodeReviewed`. This practice avoids field name collisions - by namespacing each vendor. Non-extension field names never contain an - underscore. -- Extension fields MUST NOT alter the meaning of any other field. In other - words, an attestation with an absent extension field MUST be interpreted - identically to an attestation with an unrecognized (and thus ignored) - extension field. -- Extension fields SHOULD follow the [monotonic principle][parsing rules], - meaning that deleting or ignoring the extension SHOULD NOT turn a DENY - decision into an ALLOW. - -## Verification - -[Verification]: verifying-artifacts - -Please see [Verifying Artifacts][Verification] for a detailed discussion of -provenance verification. - -## Index of build types - -The following is a partial index of build type definitions. Each contains a -complete example predicate. - - - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) -- [Google Cloud Build (community-maintained)](https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1) - -To add an entry here, please send a pull request on GitHub. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "internalParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "builderDependencies": null, // not in v0.2 - "version": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.0 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build platforms, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed: - - `parameters` -> `externalParameters` (slight change in semantics) - - `environment` -> `internalParameters` (slight change in semantics) - - `materials` -> `resolvedDependencies` (slight change in semantics) - - `buildInvocationId` -> `invocationId` - - `buildStartedOn` -> `startedOn` - - `buildFinishedOn` -> `finishedOn` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - ResourceDescriptor: `annotations`, `content`, `downloadLocation`, - `mediaType`, `name` - - Builder: `builderDependencies` and `version` - - `byproducts` -- Changed naming convention for extension fields. - -Differences from RC1 and RC2: - -- Renamed `systemParameters` (RC1 + RC2) -> `internalParameters` (final). -- Changed naming convention for extension fields (in RC2). -- Renamed `localName` (RC1) -> `name` (RC2). -- Added `annotations` and `content` (in RC2). - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: threats -[trusted]: principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.2-rc1/build-requirements.md b/docs/spec/v1.2-rc1/build-requirements.md deleted file mode 100644 index bee92afb5..000000000 --- a/docs/spec/v1.2-rc1/build-requirements.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -title: "Build: Requirements for producing artifacts" -description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers. ---- - - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is platform implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Build Track Basics](build-track-basics.md). For background, see -[Terminology](terminology.md). To better understand the reasoning behind the -requirements, see [Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -In order to produce artifacts with a specific build level, responsibility is -split between the [Producer] and [Build platform]. The build platform MUST -strengthen the security controls in order to achieve a specific level while the -producer MUST choose and adopt a build platform capable of achieving a desired -build level, implementing any controls as specified by the chosen platform. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build platform - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build platform - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Unforgeable - ✓ -
Isolation strength - Hosted - ✓✓ -
Isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure platform is beyond the -scope of this specification, all implementations MUST use industry security -best practices to be conformant to this specification. This includes, but is -not limited to, using proper access controls, securing communications, -implementing proper management of cryptographic secrets, doing frequent updates, -and promptly fixing known vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -NOTE: There were more requirements for producers in the initial -[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted -how a package can be built. These were removed in the v1.0 specification and -will be reassessed and re-added as indicated in the -[future directions](future-directions.md). - -### Choose an appropriate build platform - -The producer MUST select a build platform that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -If a producer wishes to distribute their artifact through a [package ecosystem] -that requires explicit metadata about the build process in the form of a -configuration file, the producer MUST complete the configuration file and keep -it up to date. This metadata might include information related to the artifact's -source repository and build parameters. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the -[package ecosystem], provided that the package ecosystem is capable of -distributing provenance. - -## Build Platform - -[Build platform]: #build-platform - -A package's build platform is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build platform is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build platform used -by a single software project, or even an individual's workstation. Ideally, one -build platform is used by many different software packages so that consumers can -[minimize the number of trusted platforms](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build platform is responsible for providing two things: [provenance -generation] and [isolation between builds]. The -[Build level](build-track-basics) describes the degree to which each of these -properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build platform is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the overall provenance integrity according to -minimum requirements on its: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package by cryptographic digest and describes how that package was -produced. The format MUST be acceptable to the [package ecosystem] and/or -[consumer](verifying-artifacts.md#consumer). - -It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. - -If using an alternate format, it MUST contain the equivalent information as SLSA -Provenance at each level and SHOULD be bi-directionally translatable to SLSA -Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build platform and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only -to the build platform component that generated the provenance attestation. - -While many constraints affect choice of signing methodologies, it is -RECOMMENDED that build platforms use signing methodologies which improve the -ability to detect and remediate key compromise, such as methods which rely on -transparency logs or, when transparency isn't appropriate, time stamping -services. - -Authenticity allows the consumer to trust the contents of the provenance -attestation, such as the identity of the build platform. - -*Accuracy:* The provenance MUST be generated by the control plane (i.e. within -the trust boundary [identified in the provenance]) and not by a tenant of the -build platform (i.e. outside the trust boundary), except as noted below. - -- The data in the provenance MUST be obtained from the build platform, either - because the generator *is* the build platform or because the provenance - generator reads the data directly from the build platform. -- The build platform MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. -- Exceptions for fields that MAY be generated by a tenant of the build platform: - - The names and cryptographic digests of the output artifacts, i.e. - `subject` in [SLSA Provenance]. See [forge output digest of the - provenance](threats#forged-digest) for explanation of why this is - acceptable. - - Any field that is not marked as REQUIRED for Build L2. For example, - `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at - Build L2. Builders SHOULD document any such cases of tenant-generated - fields. - -*Completeness:* SHOULD be complete. - -- There MAY be [external parameters] that are not sufficiently captured in - the provenance. -- Completeness of resolved dependencies is best effort. - - ✓✓ -
Provenance is Unforgeable - -*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. - -- Any secret material used for authenticating the provenance, for example the - signing key used to generate a digital signature, MUST be stored in a secure - management system appropriate for such material and accessible only to the - build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - platform in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted in [Provenance - is Authentic](#provenance-authentic). (Build L3 does not require additional - fields beyond those of L2.) - -*Completeness:* SHOULD be complete. - -- [External parameters] MUST be fully enumerated. -- Completeness of resolved dependencies is best effort. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build platform is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build platform's isolation strength, see -[Assessing build platforms](assessing-build-platforms.md). - - - - -
RequirementDescriptionL1L2L3 - -
Hosted - - -All build steps ran using a hosted build platform on shared or dedicated -infrastructure, not on an individual's workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Isolated - - -The build platform ensured that the build steps ran in an isolated environment, -free of unintended external influence. In other words, any external influence on -the build was specifically requested by the build itself. This MUST hold true -even between builds within the same tenant project. - -The build platform MUST guarantee the following: - -- It MUST NOT be possible for a build to access any secrets of the build - platform, such as the provenance signing key, because doing so would - compromise the authenticity of the provenance. -- It MUST NOT be possible for two builds that overlap in time to influence one - another, such as by altering the memory of a different build process running - on the same machine. -- It MUST NOT be possible for one build to persist or influence the build - environment of a subsequent build. In other words, an ephemeral build - environment MUST be provisioned for each build. -- It MUST NOT be possible for one build to inject false entries into a build - cache used by another build, also known as "cache poisoning". In other - words, the output of the build MUST be identical whether or not the cache is - used. -- The build platform MUST NOT open services that allow for remote influence - unless all such interactions are captured as `externalParameters` in the - provenance. - -There are no sub-requirements on the build itself. Build L3 is limited to -ensuring that a well-intentioned build runs securely. It does not require that -a build platform prevents a producer from performing a risky or insecure build. In -particular, the "Isolated" requirement does not prohibit a build from calling -out to a remote execution service or a "self-hosted runner" that is outside the -trust boundary of the build platform. - -NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" -in the initial [draft version (v0.1)](../v0.1/requirements.md). - -NOTE: This requirement is not to be confused with "Hermetic", which roughly -means that the build ran with no network access. Such a requirement requires -substantial changes to both the build platform and each individual build, and is -considered in the [future directions](future-directions.md). - - ✓ -
- -[external parameters]: provenance.md#externalParameters -[identified in the provenance]: provenance.md#model -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.2-rc1/build-track-basics.md b/docs/spec/v1.2-rc1/build-track-basics.md deleted file mode 100644 index eccbc36b6..000000000 --- a/docs/spec/v1.2-rc1/build-track-basics.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: "Build: Track Basics" -description: The SLSA build track is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This page is a descriptive overview of the SLSA build track levels, describing their intent. ---- - -| 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 - - - -> 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 -> Build track. In 1.2 the [Source Track](tracks#source-track) reintroduces -> coverage of source code. - -
- -## Build L0: No guarantees - -
-
Summary
- -No requirements---L0 represents the lack of SLSA. - -
Intended for
- -Development or test builds of software that are built and run on the same -machine, such as unit tests. - -
Requirements
- -n/a - -
Benefits
- -n/a - -
-
-
- -## Build L1: Provenance exists - -
-
Summary
- -Package has provenance showing how it was built. Can be used to prevent mistakes -but is trivial to bypass or forge. - -
Intended for
- -Projects and organizations wanting to easily and quickly gain some benefits of -SLSA---other than tamper protection---without changing their build workflows. - -
Requirements
- -- Software Producer: - - Follow a consistent build process so that others can form - expectations about what a "correct" build looks like. - - Run builds on a build platform that meets Build L1 requirements. - - Distribute provenance to consumers, preferably using a convention - determined by the package ecosystem. -- Build platform: - - Automatically generate [provenance] describing how the artifact was - built, including: what entity built the package, what build process - they used, and what the top-level input to the build were. - -
Benefits
- -- Makes it easier for both producers and consumers to debug, patch, rebuild, - and/or analyze the software by knowing its precise source version and build - process. - -- With [verification], prevents mistakes during the release process, such as - building from a commit that is not present in the upstream repo. - -- Aids organizations in creating an inventory of software and build platforms - used across a variety of teams. - -
Notes
- -- Provenance may be incomplete and/or unsigned at L1. Higher levels require - more complete and trustworthy provenance. - -
- -
-
- -## Build L2: Hosted build platform - -
-
Summary
- -Forging the provenance or evading verification requires an explicit "attack", -though this may be easy to perform. Deters unsophisticated adversaries or those -who face legal or financial risk. - -In practice, this means that builds run on a hosted platform that generates and -signs[^sign] the provenance. - -
Intended for
- -Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build platform, while waiting for changes to the build -platform itself required by [Build L3]. - -
Requirements
- -All of [Build L1], plus: - -- Software producer: - - Run builds on a [hosted] build platform that meets Build L2 - requirements. -- Build platform: - - Generate and sign[^sign] the provenance itself. This may be done - during the original build, an after-the-fact reproducible build, or - some equivalent system that ensures the trustworthiness of the - provenance. -- Consumer: - - Validate the authenticity of the provenance. - -
Benefits
- -All of [Build L1], plus: - -- Prevents tampering after the build through digital signatures[^sign]. - -- Deters adversaries who face legal or financial risk by evading security - controls, such as employees who face risk of getting fired. - -- Reduces attack surface by limiting builds to specific build platforms that - can be audited and hardened. - -- Allows large-scale migration of teams to supported build platforms early - while further hardening work ([Build L3]) is done in parallel. - -
-
-
- -[^sign]: Alternate means of verifying the authenticity of the provenance are - also acceptable. - -## Build L3: Hardened builds - -
-
Summary
- -Forging the provenance or evading verification requires exploiting a -vulnerability that is beyond the capabilities of most adversaries. - -In practice, this means that builds run on a hardened build platform that offers -strong tamper protection. - -
Intended for
- -Most software releases. Build L3 usually requires significant changes to -existing build platforms. - -
Requirements
- -All of [Build L2], plus: - -- Software producer: - - Run builds on a hosted build platform that meets Build L3 - requirements. -- Build platform: - - Implement strong controls to: - - prevent runs from influencing one another, even within the same - project. - - prevent secret material used to sign the provenance from being - accessible to the user-defined build steps. - -
Benefits
- -All of [Build L2], plus: - -- Prevents tampering during the build---by insider threats, compromised - credentials, or other tenants. - -- Greatly reduces the impact of compromised package upload credentials by - requiring the attacker to perform a difficult exploit of the build process. - -- Provides strong confidence that the package was built from the official - source and build process. - -
-
- - - -[build l0]: #build-l0 -[build l1]: #build-l1 -[build l2]: #build-l2 -[build l3]: #build-l3 -[future versions]: future-directions.md -[hosted]: build-requirements.md#isolation-strength -[previous version]: ../v0.1/levels.md -[provenance]: terminology.md -[verification]: verifying-artifacts.md diff --git a/docs/spec/v1.2-rc1/distributing-provenance.md b/docs/spec/v1.2-rc1/distributing-provenance.md deleted file mode 100644 index ffb6a3d86..000000000 --- a/docs/spec/v1.2-rc1/distributing-provenance.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: "Build: Distributing provenance" -description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is platform implementers and software distributors. ---- - -In order to make provenance for artifacts available after generation -for verification, SLSA requires the distribution and verification of provenance -metadata in the form of SLSA attestations. - -This document provides specifications for distributing provenance and the -relationship between build artifacts and provenance (build attestations). It is -primarily concerned with artifacts for ecosystems that distribute build -artifacts, but some attention is also paid to ecosystems that distribute -container images or only distribute source artifacts, as many of the same -principles generally apply to any artifact or group of artifacts. - -In addition, this document is primarily for the benefit of artifact -distributors, to understand how they can adopt the distribution of SLSA -provenance. It is primarily concerned with the means of distributing -attestations and the relationship of attestations to build artifacts, and not -with the specific format of the attestation itself. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Background - -The [package ecosystem]'s maintainers are responsible for reliably -redistributing artifacts and provenance, making the producers' expectations -available to consumers, and providing tools to enable safe artifact consumption -(e.g., whether an artifact meets its producer's expectations). - -## Relationship between releases and attestations - -Attestations SHOULD be bound to artifacts, not releases. - -A single "release" of a project, package, or library might include multiple -artifacts. These artifacts result from builds on different platforms, -architectures, or environments. The builds need not happen at roughly the same -point in time and might even span multiple days. - -It is often difficult or impossible to determine when a release is 'finished' -because many ecosystems allow adding new artifacts to old releases when adding -support for new platforms or architectures. Therefore, the set of attestations -for a given release MAY grow over time as additional builds and attestations -are created. - -Thus, package ecosystems SHOULD support multiple individual attestations per -release. At the time of a given build, the relevant provenance for that build -can be added to the release, depending on the relationship to the given -artifacts. - -## Relationship between artifacts and attestations - -Package ecosystems SHOULD support a one-to-many relationship from build -artifacts to attestations to ensure that anyone is free to produce and publish -any attestation they might need. However, while there are lots of possible -attestations that can have a relationship to a given artifact, in this context -SLSA is primarily concerned with build attestations, i.e., provenance, and as -such, this specification only considers build attestations, produced by the -same maintainers as the artifacts themselves. - -By providing provenance alongside an artifact in the manner specified by a -given ecosystem, maintainers are considered to be 'elevating' these build -attestations above all other possible attestations that could be provided by -third parties for a given artifact. The ultimate goal is for maintainers to -provide the provenance necessary for a repository to be able to verify some -potential policy that requires a certain SLSA level for publication, not -support the publication of arbitrary attestations by third parties. - -As a result, this provenance SHOULD accompany the artifact at publish time, and -package ecosystems SHOULD provide a way to map a given artifact to its -corresponding attestations. The mappings can be either implicit (e.g., require a -custom filename schema that uniquely identifies the provenance over other -attestation types) or explicit (e.g., it could happen as a de-facto standard -based on where the attestation is published). - -The provenance SHOULD have a filename that is directly related to the build -artifact filename. For example, for an artifact `.`, the -attestation is `.attestation` or some similar extension (for example -[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`). - -## Where attestations are published - -There are a number of opportunities and venues to publish attestations during -and after the build process. Producers MUST publish attestations in at least -one place, and SHOULD publish attestations in more than one place: - -- **Publish attestations alongside the source repository releases**: If the - source repository hosting provider offers an artifact "release" feature, - such as [GitHub - releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), - producers SHOULD include provenance as part of such releases. This option - has the benefit of requiring no changes to the package registry to support - provenance formats, but has the disadvantage of putting the source - repository hosting provider in the critical path for installers that want to - verify policy at build-time. -- **Publish attestations alongside the artifact in the package registry**: - Many software repositories already support some variety of publishing 1:1 - related files alongside an artifact, sometimes known as “sidecar files”. - For example, PyPI supports publishing `.asc` files representing the PGP - signature for an artifact with the same filename (but different extension). - This option requires the mapping between artifact and attestation (or - attestation vessel) to be 1:1. -- **Publish attestations elsewhere, record their existence in a transparency - log**: Once an attestation has been generated and published for a build, a - hash of the attestation and a pointer to where it is indexed SHOULD be - published to a third-party transparency log that exists outside the source - repository and package registry. Not only are transparency logs such as - [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed - to be immutable, but they typically also make monitoring easier. - Requiring the presence of the attestation in a monitored transparency log - during verification helps ensure the attestation is trustworthy. - -Combining these options gives us a process for bootstrapping SLSA adoption -within an ecosystem, even if the package registry doesn't support publishing -attestations. First, interested projects modify their release process to -produce SLSA provenance. Then, they publish that provenance to their source -repository. Finally, they publish the provenance to the package registry, if -and when the registry supports it. - -Long-term, package registries SHOULD support uploading and distributing -provenance alongside the artifact. This model is preferred for two reasons: - -- trust: clients already trust the package registry as the source of their - artifacts, and don't need to trust an additional service; -- reliability: clients already depend on the package registry as part of - their critical path, so distributing provenance via the registry avoids - adding an additional point of failure. - -Short term, consumers of build artifacts can bootstrap a manual policy by using -the source repository only for projects that publish all artifacts and -attestations to the source repository, and later extend this to all artifacts -published to the package registry via the canonical installation tools once -a given ecosystem supports them. - -## Immutability of attestations - -Attestations SHOULD be immutable. Once an attestation is published as it -corresponds to a given artifact, that attestation is immutable and cannot be -overwritten later with a different attestation that refers to the same -artifact. Instead, a new release (and new artifacts) SHOULD be created. - -## Format of the attestation - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto -[SLSA Build Provenance](/build-provenance), but another format MAY be used if -both producer and consumer agree and it meets all the other requirements. - -## Considerations for source-based ecosystems - -Some ecosystems have support for installing directly from source repositories -(an option for Python/`pip`, Go, etc.). In these cases, there is no need to -publish or verify provenance because there is no "build" step that translates -between a source repository and an artifact that is being installed. - -However, for ecosystems that install from source repositories _via_ some -intermediary (e.g., [Homebrew installing from GitHub release artifacts generated -from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go -installing through the Go module proxy](https://proxy.golang.org/)), these -ecosystems distribute "source archives" that are not the bit-for-bit identical -form from version control. These intermediaries are transforming the original -source repository in some way that constitutes a "build" and as a result SHOULD -be providing build provenance for this "package", and the recommendations -outlined here apply. - -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.2-rc1/faq.md b/docs/spec/v1.2-rc1/faq.md deleted file mode 100644 index 0590bd77e..000000000 --- a/docs/spec/v1.2-rc1/faq.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Frequently asked questions -description: Answers to questions frequently asked about SLSA. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build platforms to -corroborate the provenance of a build. In this way, one can create an overall -platform that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a platform can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. - -## Q. What is the difference between a build platform, system, and service? - -Build platform and build system have been used interchangeably in the past. With -the v1.0 specification, however, there has been a unification around the term -platform as indicated in the [Terminology](terminology.md). The use of the word -`system` still exists related to software and services within the build platform -and to systems outside of a build platform like change management systems. - -A build service is a hosted build platform that is often run on shared infrastructure -instead of individuals' machines and workstations. Its use has also been replaced outside -of the requirements as it relates to the build platform. - -## Q: Is SLSA the same as TACOS? - -No. -[Trusted Attestation and Compliance for Open Source (TACOS)](https://github.com/tacosframework) -is a framework authored by Tidelift. -Per their website, TACOS is a framework -"for assessing the development practices of open source projects -against a set of secure development standards specified by the (US) -NIST Secure Software Development Framework (SSDF) V1.1" which -"vendors can use to provide self-attestation for the open source components -they rely on." - -In contrast, SLSA is a community-developed framework---including -adoptable guidelines for securing a software supply chain and -mechanism to evaluate the trustworthiness of artifacts you consume---that -is part of the Open Source Security Foundation (OpenSSF). - -## Q: How does SLSA and SLSA Provenance relate to SBOM? - -[Software Bill of Materials (SBOM)] are a frequently recommended tool for -increased software supply chain rigor. An SBOM is typically focused on -understanding software in order to evaluate risk through known vulnerabilities -and license compliance. These use-cases require fine-grained and timely data -which can be refined to improve signal-to-noise ratio. - -[SLSA Provenance] and the [Build track] are focused on trustworthiness of the -build process. To improve trustworthiness, Provenance is generated in the build -platform's trusted control plane, which in practice results in it being coarse -grained. For example, in Provenance metadata completeness of -`resolvedDependencies` information is on a best-effort basis. Further, the -`ResourceDescriptor` type does not require version and license information or -even a URI to the dependency's original location. - -While they likely include similar data, SBOMs and SLSA Provenance operate at -different levels of abstraction. The fine-grained data in an SBOM typically -describes the components present in a produced artifact, whereas SLSA -Provenance more coarsely describes parameters of a build which are external to -the build platform. - -The granularity and expressiveness of the two use-cases differs enough that -current SBOM formats were deemed not a good fit for the requirements of -the Build track. Yet SBOMs are a good practice and may form part of a future -SLSA Vulnerabilities track. Further, SLSA Provenance can increase the -trustworthiness of an SBOM by describing how the SBOM was created. - -SLSA Provenance, the wider [in-toto Attestation Framework] in which the -recommended format sits, and the various SBOM standards, are all rapidly -evolving spaces. There is ongoing investigation into linking between the -different formats and exploration of alignment on common models. This FAQ entry -describes our understanding of the intersection efforts today. We do not know -how things will evolve over the coming months and years, but we look forward to -the collaboration and improved software supply chain security. - -## Q: How to SLSA with a self-hosted runner - -Some CI systems allow producers to provide their own self-hosted runners as a build -environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage -these, classifying the SLSA build level for the resulting artifact can be confusing. - -Since the SLSA Build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance, interpretation of the -specification hinges on the platform entities involved in the provenance generation. -The SLSA [build level requirements] (secure key storage, isolation, etc.) should be -imposed on the transitive closure of the systems which are responsible for informing -the provenance generated. - -Some common situations may include: - -- The platform generates the provenance and just calls a runner for individual items. - In this situation, the provenance is only affected by the platform so there would be - no requirements imposed on the runner. -- The runner generates the provenance. In this situation, the orchestrating platform - is irrelevant and all requirements are imposed on the runner. -- The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance. Trust is - shared between the platform and the runner so the requirements are imposed on both. - -Additional requirements on the self-hosted runners may be added to Build levels -greater than L3 when such levels get defined. - -[build level requirements]: build-requirements.md -[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners -[Software Bill of Materials (SBOM)]: https://ntia.gov/sbom -[SLSA Provenance]: provenance.md -[Build track]: build-track-basics.md -[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/ diff --git a/docs/spec/v1.2-rc1/future-directions.md b/docs/spec/v1.2-rc1/future-directions.md deleted file mode 100644 index a9401758a..000000000 --- a/docs/spec/v1.2-rc1/future-directions.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Future directions -description: The initial draft version (v0.1) of SLSA had a larger scope including protections against tampering with source code and a higher level of build integrity (Build L4). This page collects some early thoughts on how SLSA **might** evolve in future versions to re-introduce these notions and add other additional aspects of automatable supply chain security. ---- - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future versions to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build platform and enabling -corroboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream verifiers - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other build platforms to corroborate the - provenance. - -
- -
- -## Platform Operations track - -A Platform Operations track could provide assurances around the hardening of -platforms (e.g. build or source platforms) as they are operated. - -The initial [draft version (v0.1)] of SLSA included a section on -[common requirements](../v0.1/requirements.md#common-requirements) that formed -the foundation of the guidance for -[assessing build platforms](assessing-build-platforms.md), which **may or may not** form -the basis for a future Build Platform Operations track: - -- Controls for approval, logging, and auditing of all physical and remote - access to platform infrastructure, cryptographic secrets, and privileged - debugging interfaces. -- Conformance to security best practices to minimize the risk of compromise. -- Protection of cryptographic secrets used by the build platform. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md diff --git a/docs/spec/v1.2-rc1/images/build-env-model.svg b/docs/spec/v1.2-rc1/images/build-env-model.svg deleted file mode 100755 index ad3f8dba6..000000000 --- a/docs/spec/v1.2-rc1/images/build-env-model.svg +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2-rc1/images/build-model.svg b/docs/spec/v1.2-rc1/images/build-model.svg deleted file mode 100644 index 9d6bed6ca..000000000 --- a/docs/spec/v1.2-rc1/images/build-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2-rc1/images/provenance-model.svg b/docs/spec/v1.2-rc1/images/provenance-model.svg deleted file mode 100644 index 028dad49e..000000000 --- a/docs/spec/v1.2-rc1/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2-rc1/images/source-control-system-components.svg b/docs/spec/v1.2-rc1/images/source-control-system-components.svg deleted file mode 100644 index d0e9dded3..000000000 --- a/docs/spec/v1.2-rc1/images/source-control-system-components.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2-rc1/images/supply-chain-model.svg b/docs/spec/v1.2-rc1/images/supply-chain-model.svg deleted file mode 100644 index 6a37ffa05..000000000 --- a/docs/spec/v1.2-rc1/images/supply-chain-model.svg +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2-rc1/images/supply-chain-threats-build-verification.svg b/docs/spec/v1.2-rc1/images/supply-chain-threats-build-verification.svg deleted file mode 100644 index 2888f6215..000000000 --- a/docs/spec/v1.2-rc1/images/supply-chain-threats-build-verification.svg +++ /dev/null @@ -1,88 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2-rc1/images/supply-chain-threats.svg b/docs/spec/v1.2-rc1/images/supply-chain-threats.svg deleted file mode 100644 index 38421111d..000000000 --- a/docs/spec/v1.2-rc1/images/supply-chain-threats.svg +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2-rc1/images/verification-model.svg b/docs/spec/v1.2-rc1/images/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.2-rc1/images/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2-rc1/index.md b/docs/spec/v1.2-rc1/index.md deleted file mode 100644 index 2f2abf044..000000000 --- a/docs/spec/v1.2-rc1/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: SLSA specification -description: SLSA is a specification for describing and incrementally improving supply chain security, established by industry consensus. It is organized into a series of levels that describe increasing security guarantees. ---- - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **Version 1.2 Release Candidate 1 (RC1)** of the SLSA -specification, which defines several SLSA levels and recommended attestation -formats, including provenance. - -{%- for section in site.data.nav.main %} -{%- if section.url == page.url %} -{%- for subsection in section.children %} -{%- if subsection.children %} - -## {{ subsection.title }} - -{{ subsection.description }} - - - -| Page | Description -| ---- | ----------- -{%- for child in subsection.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} -{%- endfor %} - - -{%- endif %} -{%- endfor %} -{%- endif %} -{%- endfor %} diff --git a/docs/spec/v1.2-rc1/onepage.md b/docs/spec/v1.2-rc1/onepage.md deleted file mode 100644 index 13b731715..000000000 --- a/docs/spec/v1.2-rc1/onepage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SLSA Specification -description: A one-page rendering of all that is included in SLSA 1.2-RC1. -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.2-rc1/" %} -{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,tracks,build-track-basics,terminology,build-requirements,distributing-provenance,verifying-artifacts,assessing-build-platforms,source-requirements,verifying-source,assessing-source-systems,threats,attestation-model,provenance,build-provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.2-rc1/principles.md b/docs/spec/v1.2-rc1/principles.md deleted file mode 100644 index 535c75a7f..000000000 --- a/docs/spec/v1.2-rc1/principles.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Guiding principles -description: An introduction to the guiding principles behind SLSA's design decisions. ---- - -This page is an introduction to the guiding principles behind SLSA's design -decisions. - -## Simple levels with clear outcomes - -Use [levels](about#how-slsa-works) to communicate security state and to -encourage a large population to improve its security stance over time. When -necessary, split levels into separate tracks to recognize progress in unrelated -security areas. - -**Reasoning:** Levels simplify how to think about security by boiling a complex -topic into an easy-to-understand number. It is clear that level N is better than -level N-1, even to someone with passing familiarity. This provides a convenient -way to describe the current security state as well as a natural path to improvement. - -Guidelines: - -- **Define levels in terms of concrete security outcomes.** Each level should - have clear and meaningful security value, such as stopping a particular - class of threats. Levels should represent security milestones, not just - incremental progress. Give each level an easy-to-remember mnemonic, such as - "Provenance exists." - -- **Balance level granularity.** Too many levels makes SLSA hard to understand - and remember; too few makes each level hard to achieve. Collapse levels - until each step requires a non-trivial but manageable amount of work to - implement. Separate levels if they require significant work from multiple - distinct parties, such as infrastructure work plus user behavior changes, so - long as the intermediate level still has some security value (prior bullet). - -- **Use tracks sparingly.** Additional tracks add extra complexity to SLSA, so - a new track should be seen as a last resort. Each track should have a clear, - distinct purpose with a crisply defined objective, such as trustworthy - provenance for the [Build track](levels#build-track). As a rule of thumb, a - new track may be warranted if it addresses threats unrelated to another - track. Try to avoid tracks that sound confusingly similar in either name or - objective. - -## Trust platforms, verify artifacts - -Establish trust in a small number of platforms and systems---such as change management, build, -and packaging platforms---and then automatically verify the many artifacts -produced by those platforms. - -**Reasoning**: Trusted computing bases are unavoidable---there's no choice but -to trust some platforms. Hardening and verifying platforms is difficult and -expensive manual work, and each trusted platform expands the attack surface of the -supply chain. Verifying that an artifact is produced by a trusted platform, -though, is easy to automate. - -To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited -number of platforms and then automate verification of the artifacts produced by those platforms. -The attack surface and work to establish trust do not scale with the number of artifacts produced, -as happens when artifacts each use a different trusted platform. - -**Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant -amount of central work. - -### Example - -A security engineer analyzes the architecture and implementation of a build -platform to ensure that it meets the SLSA Build Track requirements. Following the -analysis, the public keys used by the build platform to sign provenance are -"trusted" up to the given SLSA level. Downstream platforms verify the provenance -signed by the public key to automatically determine that an artifact meets the -SLSA level. - -### Corollary: Minimize the number of trusted platforms - -A corollary to this principle is to minimize the size of the trusted computing -base. Every platform we trust adds attack surface and increases the need for -manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team within an organization maintaining their own build platform, use a - shared build platform. Hardening work can be shared across all teams. -- Remove the need to trust components. For example, use end-to-end signing - to avoid the need to trust intermediate distribution platforms. - -## Trust code, not individuals - -Securely trace all software back to source code rather than trust individuals who have write access to package registries. - -**Reasoning**: Code is static and analyzable. Individuals, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. - -**Benefits**: Removes the possibility for a trusted individual---or an -attacker abusing compromised credentials---to tamper with source code -after it has been committed. - -## Prefer attestations over inferences - -Require explicit attestations about an artifact's provenance; do not infer -security properties from a platform's configurations. - -**Reasoning**: Theoretically, access control can be configured so that the only path from -source to release is through the official channels: the CI/CD platform pulls only -from the proper source, package registry allows access only to the CI/CD platform, -and so on. We might infer that we can trust artifacts produced by these platforms -based on the platform's configuration. - -In practice, though, these configurations are almost impossible to get right and -keep right. There are often over-provisioning, confused deputy problems, or -mistakes. Even if a platform is configured properly at one moment, it might not -stay that way, and humans almost always end up getting in the access control -lists. - -Access control is still important, but SLSA goes further to provide defense in depth: it **requires proof in -the form of attestations that the package was built correctly**. - -**Benefits**: The attestation removes intermediate platforms from the trust base and ensures that -individuals who are accidentally granted access do not have sufficient permission to tamper with the package. - -## Support anonymous and pseudonymous contributions - -SLSA supports anonymous and pseudonymous 'identities' within the software supply chain. -While organizations that implement SLSA may choose otherwise, SLSA itself does not require, -or encourage, participants to be mapped to their legal identities. - -**Nothing in this specification should be taken to mean that SLSA requires participants to -reveal their legal identity.** - -**Reasoning**: SLSA uses identities for multiple purposes: as a trust anchor for attestations -(i.e. who or what is making this claim and do I trust it to do so) or for attributing actions -to an actor. Choice of identification technology is left to the organization and technical -stacks implementing the SLSA standards. - -When identities are strongly authenticated and used consistently they can often be leveraged -for both of these purposes without requiring them to be mapped to legal identities. -This reflects how identities are often used in open source where legal name means much less -to projects than the history and behavior of a given handle over time does. Meanwhile, some -organizations may choose to levy additional requirements on identities. They are free to do -so, but SLSA itself does not require it. - -**Benefits**: By _not_ requiring legal identities SLSA lowers the barriers to its adoption, -enabling all of its other benefits and maintaining support for anonymous and pseudonymous -contribution as has been practiced in the software industry for decades. diff --git a/docs/spec/v1.2-rc1/provenance.md b/docs/spec/v1.2-rc1/provenance.md deleted file mode 100644 index 9fcfabcb4..000000000 --- a/docs/spec/v1.2-rc1/provenance.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Provenance -description: Provides a description of the concept of provenance and links to the various tracks specific definitions. ---- - -In SLSA 'provenance' refers to verifiable information that can be used to track -an artifact back, through all the moving parts in a complex supply chain, to -where it came from. It’s the verifiable information about software artifacts -describing where, when, and how something was produced. - -The different SLSA tracks have their own, more specific, implementations of -provenance to account for their unique needs. - -NOTE: If you landed here via the -[in-toto attestation](https://github.com/in-toto/attestation) predicate type -`https://slsa.dev/provenance/v1` please see -[Build provenance](build-provenance.md). - -- [Build provenance](build-provenance.md) - tracks the output of a build process - back to the source code used to produce that output. -- [Source provenance](source-requirements#source-provenance-attestations) - tracks the - creation of source code revisions and the change management processes - that were in place during their creation. diff --git a/docs/spec/v1.2-rc1/requirements.md b/docs/spec/v1.2-rc1/requirements.md deleted file mode 100644 index 825e9b22a..000000000 --- a/docs/spec/v1.2-rc1/requirements.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Requirements -description: This page links to the requirements pages of the individual tracks. ---- - -SLSA is composed of [multiple tracks](about#how-slsa-works). Each track has its -own set of requirements. Follow the links below to find the requirements for -each track. - -- [Build Track Requirements](build-requirements.md) -- [Source Track Requirements](source-requirements.md) diff --git a/docs/spec/v1.2-rc1/schema/provenance.cue b/docs/spec/v1.2-rc1/schema/provenance.cue deleted file mode 100644 index 22bc5e0d8..000000000 --- a/docs/spec/v1.2-rc1/schema/provenance.cue +++ /dev/null @@ -1,48 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "internalParameters": object, - "resolvedDependencies": [ ...#ResourceDescriptor ], - }, - "runDetails": { - "builder": { - "id": string, - "builderDependencies": [ ...#ResourceDescriptor ], - "version": { ...string }, - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ResourceDescriptor ], - } - } -} - -#ResourceDescriptor: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "gitCommit": string, - [string]: string, - }, - "name": string, - "downloadLocation": string, - "mediaType": string, - "content": bytes, // base64-encoded - "annotations": { - [string]: _ // any JSON type - } -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.2-rc1/schema/provenance.proto b/docs/spec/v1.2-rc1/schema/provenance.proto deleted file mode 100644 index ae0a71ee1..000000000 --- a/docs/spec/v1.2-rc1/schema/provenance.proto +++ /dev/null @@ -1,50 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct internal_parameters = 3; - repeated ResourceDescriptor resolved_dependencies = 4; -} - -message ResourceDescriptor { - string uri = 1; - map digest = 2; - string name = 3; - string download_location = 4; - string media_type = 5; - bytes content = 6; - map annotations = 7; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ResourceDescriptor byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ResourceDescriptor builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.2-rc1/source-requirements.md b/docs/spec/v1.2-rc1/source-requirements.md deleted file mode 100644 index 2e2336797..000000000 --- a/docs/spec/v1.2-rc1/source-requirements.md +++ /dev/null @@ -1,757 +0,0 @@ ---- -title: "Source: Requirements for producing source" -description: This page covers the detailed technical requirements for producing producing source revisions at each SLSA level. The intended audience is source control system implementers and security engineers. ---- - -## Objective - -The primary purpose of the SLSA Source track is to provide producers and consumers with increasing levels of trust in the source code they produce and consume. -It describes increasing levels of trustworthiness and completeness of how a source revision was created. - -The expected process for creating a new revision is determined solely by that repository's owner (the organization) who also determines the intent of the software in the repository and administers technical controls to enforce the process. - -Consumers can review attestations to verify whether a particular revision meets their standards. - -## Definitions - -| Term | Description -| --- | --- -| Source | An identifiable set of text and binary files and associated metadata. Source is regularly used as input to a build system (see [SLSA Build Track](build-requirements.md)). -| Organization | A set of people who collectively create the Source. Examples of organizations include open-source projects, a company, or a team within a company. The organization defines the goals and methods of the source. -| Version Control System (VCS) | Software for tracking and managing changes to source. Git and Subversion are examples of version control systems. -| Revision | A specific state of the source with an identifier provided by the version control system. As an example, you can identify a git revision by its commit object ID. -| Source Control System (SCS) | A suite of tools and services (self-hosted or SaaS) relied upon by the organization to produce new revisions of the source. The role of the SCS may be fulfilled by a single service (e.g., GitHub / GitLab) or a combination of services (e.g., GitLab with Gerrit code reviews, GitHub with OpenSSF Scorecard, etc). -| Source Provenance | Information about how a revision came to exist, where it was hosted, when it was generated, what process was used, who the contributors were, and which parent revisions preceded it. -| Repository / Repo | A uniquely identifiable instance of a VCS. The repository controls access to the Source in the VCS. The objective of a repository is to reflect the intent of the organization that controls it. -| Branch | A named, moveable, pointer to a revision that tracks development in the named context over time. Branches may be modified to point to different revisions by authorized actors. Different branches may have different security requirements. -| Tag | A named pointer to a revision that does not typically move. Similar to branches, tags may be modified by authorized actors. Tags are often used by producers to indicate a more permanent name for a revision. -| Change | A set of modifications to the source in a specific context. A change can be proposed and reviewed before being accepted. -| Change History | A record of the history of revisions that preceded a specific revision. -| Push / upload / publish | When an actor adds or modifies the Source, Branches or Tags in the repository. -| Review / approve / vote | When an actor uses a change management tool to comment upon, endorse, or reject a source change proposal. - -### Source Roles - -| Role | Description -| --- | --- -| Administrator | A human who can perform privileged operations on one or more projects. Privileged actions include, but are not limited to, modifying the change history and modifying project- or organization-wide security policies. -| Trusted person | A human who is authorized by the organization to propose and approve changes to the source. -| Trusted robot | Automation authorized by the organization to act in explicitly defined contexts. The Robot’s identity and codebase cannot be unilaterally influenced. -| Untrusted person | A human who has limited access to the project. They MAY be able to read the source. They MAY be able to propose or review changes to the source. They MAY NOT approve changes to the source or perform any privileged actions on the project. -| Proposer | An actor that proposes (or uploads) a particular change to the source. -| Reviewer / Voter / Approver | An actor that reviews (or votes on) a particular change to the source. -| Merger | An actor that applies a change to the source. This actor may be the proposer. - -## Onboarding - -When onboarding a branch to the SLSA Source Track or increasing the level of -that branch, organizations are making claims about how the branch is managed -from that revision forward. This establishes [continuity](#continuity). - -No claims are made for prior revisions. - -## Basics - -NOTE: This table presents a simplified view of the requirements. See the -[Requirements](#requirements) section for the full list of requirements for each -level. - -| Track/Level | Requirements | Focus -| ----------- | ------------ | ----- -| [Source L1](#source-l1) | Use a version control system | First steps towards operational maturity -| [Source L2](#source-l2) | History and controls for protected branches & tags | Preserve history and ensure the process has been followed -| [Source L3](#source-l3) | Signed provenance | Tampering by the source control system -| [Source L4](#source-l4) | Code review | Tampering by project contributors - -
- -### Level 1: Version controlled - -
-
Summary
- -The source is stored and managed through a modern version control system. - -
Intended for
- -Organizations currently storing source in non-standard ways who want to quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem with minimal impact to their current workflows. - -
Benefits
- -Migrating to the appropriate tools is an important first step on the road to operational maturity. - -
-
-
- -### Level 2: Controls - -
-
Summary
- -Clarifies which branches and tags in a repo are consumable and guarantees that -all changes to protected branches and tags are recorded and subject to the -organization's technical controls. - -
Intended for
- -All organizations of any size producing software of any kind. - -
Benefits
- -Allows organizations and source consumers the ability to ensure the change -management process has been followed to track changes to the software over time -and attribute those changes to the actors that made them. - -
-
-
- -### Level 3: Signed and Auditable Provenance - -
-
Summary
- -The SCS generates credible, tamper-resistant, and contemporaneous evidence of how a specific revision was created. -It is provided to authorized users of the source repository in a documented format. - -
Intended for
- -Organizations that want strong guarantees and auditability of their change management processes. - -
Benefits
- -Provides information to policy enforcement tools to reduce the risk of tampering -within the SCS's storage systems. - -
-
-
- -### Level 4: Two-party review - -
-
Summary
- -The SCS requires two trusted persons to review all changes to protected -branches. - -
Intended for
- -Organizations that want strong guarantees that the software they produce is not -subject to unilateral changes that would subvert their intent. - -
Benefits
- -Makes it harder for an actor to introduce malicious changes into the software -and makes it more likely that the source reflects the intent of the -organization. - -
-
- -## Requirements - -Many examples in this document use the [git version control system](https://git-scm.com/), but use of git is not a requirement to meet any level on the SLSA source track. - -### Organization - -[Organization]: #organization - - -
RequirementDescriptionL1L2L3L4 - -
Choose an appropriate source control system 🔗 - -An organization producing source revisions MUST select a SCS capable of reaching -their desired SLSA Source Level. - -> For example, if an organization wishes to produce revisions at Source Level 3, -they MUST choose a source control system capable of producing Source Level 3 -attestations. - -✓✓✓✓ - -
Protect consumable branches and tags 🔗 - -An organization producing source revisions MUST implement a change management -process to ensure changes to source matches the organization's intent. - -The organization MUST specify which branches and tags are covered by the process -and are intended for use in its own applications or services or those of -downstream consumers of the software. - -> For example, if an organization has branches 'main' and 'experimental' and it -intends for 'main' to be protected then it MUST indicate to the SCS that 'main' -should be protected. From that point forward revisions on 'main' will be -eligible for Source Level 2+ while revisions made solely on 'experimental' will -not. - -The organization MUST use the SCS provided -[Identity Management capability](#identity-management) to configure the actors -and roles that are allowed to perform sensitive actions on protected branches -and tags. - -> For example, an organization may configure the SCS to assign users to a `maintainers` role and only allow users in `maintainers` to make updates to `main`. - -The organization MUST specify what technical controls consumers can expect to be -enforced for revisions in each protected branch and tag using the -[Enforced change management process](#enforced-change-management-process) -and it MUST document the meaning of those controls. - -> For example, an organization may claim that revisions on `main` passed unit -tests before being accepted. The organization could then configure the SCS to -enforce this requirement and store corresponding [test result attestations] for -all affected revisions. They may then embed the `ORG_SOURCE_UNIT_TESTED` -property in the [Source VSA](#source-verification-summary-attestation). Consumers -would then expect that future revisions on `main` have been united tested and -determine if that expectation has been met by looking for the -`ORG_SOURCE_UNIT_TESTED` property in the VSAs and, if desired, consult the -[test result attestations] as well. - -[test result attestations]: https://github.com/in-toto/attestation/blob/main/spec/predicates/test-result.md - -✓✓✓ - -
Safe Expunging Process 🔗 - -SCSs MAY allow the organization to expunge (remove) content from a repository and its change history without leaving a public record of the removed content, -but the organization MUST only allow these changes in order to meet legal or privacy compliance requirements. -Content changed under this process includes changing files, history, references, or any other metadata stored by the SCS. - -#### Warning - -Removing a revision from a repository is similar to deleting a package version from a registry: it's almost impossible to estimate the amount of downstream supply chain impact. -> For example, in VCSs like Git, each revision ID is based on the ones before it. When you remove a revision, you must generate new revisions (and new revision IDs) for any revisions that were built on top of it. Consumers who took a dependency on the old revisions may now be unable to refer to the source they've already integrated into their products. - -It may be the case that the specific set of changes targeted by a legal takedown can be expunged in ways that do not impact consumed revisions, which can mitigate these problems. - -It is also the case that removing content from a repository won't necessarily remove it everywhere. -The content may still exist in other copies of the repository, either in backups or on developer machines. - -#### Process - -An organization MUST document the Safe Expunging Process and describe how requests and actions are tracked and SHOULD log the fact that content was removed. -Different organizations and tech stacks may have different approaches to the problem. - -SCSs SHOULD have technical mechanisms in place which require an Administrator plus, at least, one additional 'trusted person' to trigger any expunging (removals) made under this process. - -The application of the safe expunging process and the resulting logs MAY be private to both prevent calling attention to potentially sensitive data (e.g. PII) or to comply with local laws -and regulations which may require the change to be kept private to the extent possible. -Organizations SHOULD prefer to make logs public if possible. - -✓✓✓ - -
- -### Source Control System - - -
RequirementDescriptionL1L2L3L4 - -
Repositories are uniquely identifiable 🔗 - -The repository ID is defined by the SCS and MUST be uniquely identifiable within the context of the SCS. - -✓✓✓✓ -
Revisions are immutable and uniquely identifiable 🔗 -The revision ID is defined by the SCS and MUST be uniquely identifiable within the context of the repository. -When the revision ID is a digest of the content of the revision (as in git) nothing more is needed. -When the revision ID is a number or otherwise not a digest, then the SCS MUST document how the immutability of the revision is established. -The same revision ID MAY be present in multiple repositories. - -See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). - -✓✓✓✓ -
Source Verification Summary Attestations 🔗 - -The SCS MUST generate a -[source verification summary attestation](#source-verification-summary-attestation) (Source VSA) -to indicate the SLSA Source Level of any revision at Level 1 or above. - -If a consumer is authorized to access a revision, they MUST be able to fetch the -corresponding Source VSA. - -If the SCS DOES NOT generate a VSA for a revision, the revision has Source Level -0. - -At Source Levels 1 and 2 the SCS MAY issue these attestations based on its -understanding of the underlying system (e.g. based on design docs, security -reviews, etc...), but at Level 3+ the SCS MUST use -the SCS issued [source provenance](#source-provenance) when making the issuing -the VSAs. - -✓✓✓✓ -
Protected Branches 🔗 - -The SCS MUST provide a mechanism for organizations to indicate which branches -should be protected by SLSA Source Level 2+ requirements. - -E.g. The organization may configure the SCS to protect `main` and -`refs/heads/releases/*`, but not `refs/heads/playground/*`. - -✓✓✓ -
History 🔗 - -Revisions are created by applying specific code changes (a "diff" in git) on -top of earlier revisions of a branch. This sequence of changes, the revisions -they produced, and how they were introduced into a branch constitute the history -of that branch. - -The SCS MUST record the sequence of changes, the revisions they created, -the actors that introduced them and the context they were introduced into. - -The SCS MUST prevent tampering with these records on protected branches. - -> For example, in systems like GitHub or GitLab, this can be accomplished by -enabling branch protection rules that prevent force pushes and branch deletions. - -✓✓✓ -
Enforced change management process 🔗 - -The SCS MUST - -- Ensure organization-defined technical controls are enforced for changes made - to protected branches. -- Allow organizations to specify - [additional properties](#additional-properties) to be included in the - [Source VSA](#source-verification-summary-attestation) when the corresponding controls are - enforced. -- Allow organizations to distribute additional attestations related to their - technical controls to consumers authorized to access the corresponding source - revision. -- Prevent organization-specified properties from beginning with any value - other than `ORG_SOURCE_` unless the SCS endorses the veracity of the - corresponding claims. - -> For example: enforcement of the organization-defined technical controls could -be accomplished by the configuration of branch protection rules (e.g. -[GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), -[GitLab](https://docs.gitlab.com/ee/user/project/repository/branches/protected.html)) -which require additional checks to 'pass' (e.g. unit tests, linters) or the -application and verification of [gittuf](https://github.com/gittuf/gittuf) -policies. - -✓✓✓ -
Continuity 🔗 - -In a source control system, each new revision is built on top of prior -revisions. Controls (e.g. [history](#history) or -[enforced change management process](#enforced-change-management-process)) are -only effective if they are used continuously from one revision to another. If -a control is disabled for the introduction of a new revision and then re-enabled -it is difficult to reason about the effectiveness of the control. 'Continuity' is -the concept of ensuring controls are enforced continuously from the time they -were introduced, leading to a higher degree of trust in the revisions produced -after their introduction. - -On [protected branches](#branches) continuity for [history](#history) and -[enforced change management process](#enforced-change-management-process) -controls MUST be established and tracked from a specific revision forward -through each new revision created. If there is a lapse in continuity for a -specific control, continuity of that control MUST be re-established from a new -revision. - -Continuity exceptions are allowed via the [safe expunging process](#safe-expunging-process). - -✓✓✓ -
Protected Tags 🔗 - -If the SCS supports tags (or other non-branch revision trackers), additional -care must be taken to prevent unintentional changes. -Unlike branches, tags have no built-in continuity enforcement mechanisms or -change management processes. - -The SCS MUST provide a mechanism for organizations to indicate which tags should -be protected by SLSA Source Level 2+ requirements. - -The SCS MUST prevent protected tags from being moved or deleted. - -✓✓✓ -
Identity Management 🔗 - -The SCS MUST provide an identity management system or some other means of -identifying and authenticating actors. - -The SCS MUST allow organizations to specify which actors and roles are allowed -to perform sensitive actions within a repository (e.g. creation or updates of -branches, approval of changes). - -Depending on the SCS, identity management may be provided by source control -services (e.g., GitHub, GitLab), implemented using cryptographic signatures -(e.g., using gittuf to manage public keys for actors), or extend existing -authentication systems used by the organization (e.g., Active Directory, Okta, -etc.). - -The SCS MUST document how actors are identified for the purposes of attribution. - -Activities conducted on the SCS SHOULD be attributed to authenticated -identities. - -✓✓✓ -
Source Provenance 🔗 - -[Source Provenance](#source-provenance-attestations) are attestations that -contain information about how a specific revision was created and how it came to -exist on a protected branch or how a tag came to point at it. They are -associated with the revision identifier delivered to consumers and are a -statement of fact from the perspective of the SCS. The SCS MUST document the -format and intent of all Source Provenance attestations it produces. - -At Source Level 3, Source Provenance MUST be created contemporaneously with the -branch being updated to use that revision such that they provide a credible, -auditable, record of changes. - -If a consumer is authorized to access a revision, they MUST be able to fetch the -corresponding source provenance documents for that revision. - -It is possible that an SCS can make no claims about a particular revision. - -> For example, this would happen if the revision was created on another SCS, -or if the revision was not the result of an accepted change management process. - -✓✓ -
Two party review 🔗 - -Changes in protected branches MUST be agreed to by two or more trusted persons prior to submission. -The following combinations are acceptable: - -- Uploader and reviewer are two different trusted persons. -- Two different reviewers are trusted persons. - -Reviews SHOULD cover, at least, security relevant properties of the code. - -**[Final revision approved]** This requirement applies to the final revision -submitted. I.e. if additional changes are made during the review process, those changes MUST -be reviewed as well. - -**[Context-specific approvals]** Approvals are for a specific context, such as a -repo + branch in git. Moving fully reviewed content from one context to another -still requires review. The exact definition of “context” depends on the project, -and this does not preclude well-understood automatic merges, such as cutting a release branch. - -**[Informed Review]** The SCS MUST provide a human readable diff of all -plain-text changes being reviewed and SHOULD provide mechanisms to provide human -understandable interpretations of non-plain-text changes (e.g. render images, -verify and display provenance for binaries, etc...). - -**[Trusted Robot Contributions]** An organization MAY choose to grant a Trusted -Robot a perpetual exception to a policy (e.g. a bot may be able to merge a change -that has not been reviewed by two parties). - -Examples: - -- Import and migration bots that move code from one repo to another. -- Dependabot - -✓ -
- -## Communicating source levels - -SLSA source level details are communicated using attestations. -These attestations either refer to a source revision itself or provide context needed to evaluate an attestation that _does_ refer to a revision. - -There are two broad categories of source attestations within the source track: - -1. Source verification summary attestations (Source VSAs): Used to communicate to downstream users what high level security properties a given source revision meets. -2. Source provenance attestations: Provide trustworthy, tamper-proof, metadata with the necessary information to determine what high level security properties a given source revision has. - -To provide interoperability and ensure ease of use, it's essential that the Source VSAs are applicable across all Source Control Systems. -However, due to the significant differences in how SCSs operate and how they may chose to meet the Source Track requirements, it is preferable to -allow for flexibility with the full source provenance attestations. To that end, SLSA leaves source provenance attestations undefined and up to the SCSs to determine -what works best in their environment. - -### Source verification summary attestation - -Source verification summary attestations (Source VSAs) are issued by some authority that has sufficient evidence to make the determination of a given -revision's source level. Source VSAs convey properties about the revision as a whole and summarize properties computed over all -the changes that contributed to that revision over its history. - -The source track issues Source VSAs using the [Verification Summary Attestations](./verification_summary.md) format as follows: - -1. `subject.uri` SHOULD be set to a human readable URI of the revision. -2. `subject.digest` MUST include the revision identifier (e.g. `gitCommit`) and MAY include other digests over the contents of the revision (e.g. `gitTree`, `dirHash`, etc...). -SCSs that do not use cryptographic digests MUST define a canonical type that is used to identify immutable revisions (e.g. `svn_revision_id`)[^1]. -3. `subject.annotations.source_refs` SHOULD be set to a list of references that pointed to this revision when the attestation was created. The list MAY NOT be exhaustive - - git references MUST be fully qualified (e.g. `refs/head/main` or `refs/tags/v1.0`) to reduce the likelihood of confusing downstream tooling. -4. `resourceUri` MUST be set to the URI of the repository, preferably using [SPDX Download Location](https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field). -E.g. `git+https://github.com/foo/hello-world`. -5. `verifiedLevels` MUST include the SLSA source track level the SCS asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. -MAY include additional properties as asserted by the SCS. The SCS MUST include _only_ the highest SLSA source level met by the revision. -6. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. This COULD be used to indicate the source level of any git submodules present in the revision. - -#### Additional properties - -The SLSA source track MAY create additional properties to include in -`verifiedLevels` which attest to other claims concerning a revision (e.g. if it -was code reviewed). - -The SCS MAY embed organization-provided properties within `verifiedLevels` -corresponding to technical controls enforced by the SCS. If such properties are -provided they MUST be prefixed with `ORG_SOURCE_` to distinguish them from other -properties the SCS may wish use. - -- `ORG_SOURCE_` to indicate a property that is meant for consumption by - external consumers. -- `ORG_SOURCE_INTERNAL_` to indicate a property that is not meant for - consumption by external consumers. - -The meaning of the properties is left entirely to the organization. Inclusion of -organization-provided properties within `verifiedLevels` SHOULD NOT be -considered an endorsement of the veracity of the organization defined property -by the SCS. - -#### Populating source_refs - -The Source VSA issuer may choose to populate `source_refs` in any way they wish. -Downstream users are expected to be familiar with the method used by the issuer. - -Example implementations: - -- Issue a new VSA for each merged Pull Request and add the destination branch to `source_refs`. -- Issue a new VSA each time a 'consumable branch' is updated to point to a new revision. -- Issue a new VSA each time a 'consumable tag' is created to point to a new revision. - -#### Example - -```json -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a", - "digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"}, - "annotations": {"source_refs": ["refs/heads/main", "refs/heads/release_1.0"]} -}], - -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/source_verifier", - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "git+https://github.com/foo/hello-world", - "policy": { - "uri": "https://example.com/slsa_source.policy", - }, - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_SOURCE_LEVEL_3"], -} -``` - -#### How to verify - -- VSAs for source revisions MUST follow [the standard method of VSA verification](./verification_summary.md#how-to-verify). -- Users SHOULD check that an allowed branch is listed in `subject.annotations.source_refs` to ensure the revision is from an appropriate context within the repository. -- Users SHOULD check that the expected `SLSA_SOURCE_LEVEL_` is listed within `verifiedLevels`. -- Users MUST ignore any unrecognized values in `verifiedLevels`. - -### Source provenance attestations - -Source provenance attestations provide tamper-proof evidence ([attestation model](attestation-model))) -that can be used to determine what SLSA Source Level or other high level properties a given revision meets. -This evidence can be used by: - -- an authority as the basis for issuing a [Source VSA](#source-verification-summary-attestation) -- a consumer to cross-check a [Source VSA](#source-verification-summary-attestation) they received for a revision -- a consumer to enforce a more detailed policy than the organization's change management process - -SCSs may have different methods of operating that necessitate different forms of evidence. -E.g. GitHub-based workflows may need different evidence than Gerrit-based workflows, which would both likely be different from workflows that -operate over Subversion repositories. - -These differences also mean that, depending on the configuration, the issuers of provenance attestations may vary from implementation to implementation, often because entities with the knowledge to issue them may vary. -The authority that issues [Source VSAs](#source-verification-summary-attestation) MUST understand which entity should issue each provenance attestation type, and ensure all source provenance attestations come from their expected issuers. - -'Source provenance attestations' is a generic term used to refer to any type of attestation that provides evidence the process used to create a revision. - -Example source provenance attestations: - -- A TBD attestation which describes the revision's parents and the actors involved in creating this revision. -- A "code review" attestation which describes the basics of any code review that took place. -- An "authentication" attestation which describes how the actors involved in any revision were authenticated. -- A [Vuln Scan attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/vuln.md) - which describes the results of a vulnerability scan over the contents of the revision. -- A [Test Results attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/test-result.md) - which describes the results of any tests run on the revision. -- An [SPDX attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md) - which provides a software bill of materials for the revision. -- A [SCAI attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md) used to - describe which source quality tools were run on the revision. - -Irrespective of the types of provenance attestations generated by an SCS and -their implementations, the SCS MUST document provenance -formats, and how each provenance attestation can be used to reason about the -revision's properties recorded in the summary attestation. - -[^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms. - -## Potential Change Management Controls - -In addition to the requirements for SLSA Source L4, most organizations will -require multiple of these controls as part of their required protections. - -If an organization has indicated that use of these these controls are part of -their repository's expectations, consumers SHOULD be able to verify that the -process was followed for the revision they are consuming by examining the -[summary](#source-verification-summary-attestation) or [source -provenance](#source-provenance-attestations) attestations. - -> For example: consumers can look for the related `ORG_SOURCE` properties in the -`verifiedLevels` field of the [summary attestation](#source-verification-summary-attestation). - -### Expert Code Review - -Summary: All changes to the source are pre-approved by experts in those areas. - -Intended for: Enterprise repositories and mature open source projects. - -Benefits: Prevents mistakes made by developers who are unfamiliar with the area. - -Requirements: - -#### Code ownership - -Each part of the source MUST have a clearly identified set of experts. - -#### Approvals from all relevant experts - -For each portion of the source modified by a change proposal, pre-approval MUST be granted by a member of the defined expert set. -An approval from an actor that is a member of multiple expert groups may satisfy the requirement for all groups in which they are a member. - -### Review Every Single Revision - -Summary: The final revision was reviewed by all relevant experts prior to submission. - -Intended for: The highest-of-high-security-posture repos. - -Benefits: Provides the maximum chance for experts to spot and reject problems before they ship. - -Requirements: - -#### Reset votes on all changes - -If the proposal is modified after receiving expert approval, all previously granted approvals MUST be revoked. -A new approval MUST be granted from ALL required reviewers. - -The new approval MAY be granted by an actor who approved a previous iteration. - -### Automated testing - -Summary: -The final revision was validated against a suite of automated tests. - -Intended for: -All organizations and repositories. - -Benefits: -Automatic testing has many benefits, including improved accuracy, error prevention and reduced workload on human developers. - -Requirements: -The organization MUST configure a branch protection rule to require that only revisions with passing test results can be pointed-to by the branch. - -Automatic tests SHOULD be executed in a trustworthy environment (see SLSA build track). - -Results of each test (or an aggregate) MUST be collected by the change review tool and made available for verification. - -Tests SHOULD be run against a revision created for testing by merging the topic branch (containing the proposed changes) into the target branch. - -Use of the proposed merge commit should be preferred to using the tip of the topic branch. - -### Every revision reachable from a branch was approved - -Summary: -New revisions are created based ONLY on the changes that were approved. - -Benefits: -Prevents a large class of internal threat attacks based on hiding a malicious commit in a series of good commits such that the malicious commit does not appear in the reviewed diff. - -Requirements: - -#### Context - -In many organizations it is normal to review only the "net difference" between the tip of the topic branch and the "best merge base", the closest shared commit between the topic and target branches computed at the time of review. - -The topic branch may contain many commits of which not all were intended to represent a shippable state of the repository. - -If a repository merges branches with a standard merge commit, all those unreviewed commits on the topic branch will become "reachable" from the protected branch by virtue of the multi-parent merge commit. - -When a repo is cloned, all commits _reachable_ from the main branch are fetched and become accessible from the local checkout. - -This combination of factors allows attacks where the victim performs a `git clone` operation followed by a `git reset --hard `. - -#### Mitigations - -##### Informed Review - -The reviewer is able and encouraged to make an informed decision about what they're approving. -The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. - -It is not sufficient to indicate that a file changed without showing the contents. - -##### Use only rebase operations on the protected branch - -Require a squash merge strategy for the protected branch. - -To guarantee that only commits representing reviewed diffs are cloned, the SCS MUST rebase (or "squash") the reviewed diff into a single new commit (the "squashed" commit) that has only a single parent (the revision previously pointed-to by the protected branch). -This is different than a standard merge commit strategy which would cause all the user-contributed commits to become reachable from the protected branch via the second parent. - -It is not acceptable to replay the sequence of commits from the topic branch onto the protected branch. -The intent is to reduce the accepted changes to the exact diffs that were reviewed. -Constituent commits of the topic branch may or may not have been reviewed on an individual basis, and should not become reachable from the protected branch. - -### Immutable Change Discussion - -Summary: -The discussion around a change may often be as important as the change itself. - -Intended for: -Large organizations, or any where discussion is an important part of the change management process. - -Benefits: -From any revision, it's possible for future developers to read through the discussion that ultimately produced it. -This has many educational, forensics, and security auditing benefits. - -Requirements: - -The change management tool SHOULD record a description of the proposed change and all discussions / commentary related to it. - -The change management tool MUST link this discussion to the revision itself. This is regularly done via commit metadata. - -All collected content SHOULD be made immutable if the change is accepted. -It SHOULD NOT be possible to edit the discussion around a revision after it has been accepted. - -### Fast moving repos and "merge trains" - -Large organizations must keep the number of updates to key protected branches under certain limits to allow time for code review to happen. -For example, if a team tries to merge 60 change requests per hour into the `main` branch, the tip of the `main` branch would only be stable for about 1 minute. -This would leave only 1 minute for a new diff to be both generated and reviewed before it becomes stale again. - -The normal way to work in this environment is to create a buffer branch (sometimes called a "train") to collect a certain number of approved changes. -In this model, when a change is approved for submission to the protected branch, it is added to the train branch instead. -After a certain amount of time, the train branch will be merged into the protected branch. -If there are problems detected with the contents on the train branch, it's normal for the whole train to be abandoned and a new train to be formed. -Approved changes will be re-applied to a new train in this scenario. - -The key benefit to this approach is that the protected branch remains stable for longer, allowing more time for human and automatic code review. -A key downside to this approach is that organizations will not know the final revision id that represents a change until the entire train process completes. - -A change review process will now be associated with multiple distinct revisions. - -- ID 1: The revision which was reviewed before concluding the change review process. It represents the ideal state of the protected branch applying only this proposed change. -- ID 2: The revision created when the change is applied to the train branch. It represents the state of the protected branch _after other changes have been applied_. - -It is important to note that no human or automatic review will have the chance to pre-approve ID2. This will appear to violate any organization policies that require pre-approval of changes before submission. -The SCS and the organization MUST protect this process in the same way they protect other artifact build pipelines. - -At a minimum the SCS MUST issue an attestation that the revision id generated by a merged train is identical ("MERGESAME" in git terminology) to the state of the protected branch after applying each approved changeset in sequence. -No other content may be added or removed during this process. - -## Future Considerations - -### Authentication - -- Better protection against phishing by forbidding second factors that are not - phishing resistant. -- Protect against authentication token theft by forbidding bearer tokens - (e.g. PATs). -- Including length of continuity in the VSAs diff --git a/docs/spec/v1.2-rc1/terminology.md b/docs/spec/v1.2-rc1/terminology.md deleted file mode 100644 index 5e4dc968f..000000000 --- a/docs/spec/v1.2-rc1/terminology.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: "Build: Terminology" -description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting. ---- - - -Before diving into the [Build Track](build-track-basics.md), we need to -establish a core set of terminology and models to describe what we're -protecting. - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). -| [Distribution] | The channel through which artifacts are "published" for use by others. | A registry like DockerHub or npm. Artifacts may also be distributed via physical media (e.g., a USB drive). -| Package | Artifact that is distributed. 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 (distribution). 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 -[distribution]: #distribution-model -[SLSA Provenance]: /provenance/v1 - -### Roles - -Throughout the specification, you will see reference to the following roles -that take part in the software supply chain. Note that in practice a role may -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. - -### Build model - -

Model Build

- -We model a build as running on a multi-tenant *build platform*, where each -execution is independent. - -1. A tenant invokes the build by specifying *external parameters* through an - *interface*, either directly or via some trigger. Usually, at least one of - these external parameters is a reference to a *dependency*. (External - parameters are literal values while dependencies are artifacts.) -2. The build platform's *control plane* interprets these external parameters, - fetches an initial set of dependencies, initializes a *build environment*, - and then starts the execution within that environment. -3. The build then performs arbitrary steps, which might include fetching - additional dependencies, and then produces one or more *output* artifacts. - The steps within the build environment are under the tenant's control. - The build platform isolates build environments from one another to some - degree (which is measured by the SLSA Build Level). -4. Finally, for SLSA Build L2+, the control plane outputs *provenance* - describing this whole process. - -Notably, there is no formal notion of "source" in the build model, just external -parameters and dependencies. Most build platforms have an explicit "source" -artifact to build from, which is often a git repository; in the build model, the -reference to this artifact is an external parameter while the artifact itself is -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. - -
Ambiguous terms to avoid - -- *Build recipe:* Could mean *external parameters,* but may include concrete - steps of how to perform a build. To avoid implementation details, we don't - define this term, but always use "external parameters" which is the - interface to a build platform. Similar terms are *build configuration - source* and *build definition*. -- *Builder:* Usually means *build platform*, but might be used for *build - environment*, the user who invoked the build, or a build tool from - *dependencies*. To avoid confusion, we always use "build platform". The only - exception is in the [provenance](/provenance/v1), where `builder` is used as - a more concise field name. - -
- -### Distribution model - -Software is distributed in identifiable units called packages -according to the rules and conventions of a package ecosystem. -Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and -[OCI](https://github.com/opencontainers/distribution-spec), while examples of -informal ecosystems include links to files on a website or distribution of -first-party software within a company. - -Abstractly, a consumer locates software within an ecosystem by asking a -distribution platform, such as a package registry, to resolve a -mutable package name into an immutable package artifact. -[^label] To publish a package artifact, the software producer asks -the registry to update this mapping to resolve to the new artifact. The registry -represents the entity or entities with the power to alter what artifacts are -accepted by consumers for a given package name. For example, if consumers only -accept packages signed by a particular public key, then it is access to that -public key that serves as the registry. - -The package name is the primary security boundary within a package ecosystem. -Different package names represent materially different pieces of -software---different owners, behaviors, security properties, and so on. -Therefore, **the package name is the primary unit being protected in SLSA**. -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 -| ---- | ----------- -| Distribution platform | An entity responsible for mapping package names to immutable package artifacts. -| 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 | A specific type of "distribution platform" used 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 - -- *Package repository:* Could mean either package registry or package name, - depending on the ecosystem. To avoid confusion, we always use "repository" - exclusively to mean "source repository", where there is no ambiguity. -- *Package manager* (without "client"): Could mean either package ecosystem, - package registry, or client-side tooling. - -
- -### Mapping to real-world ecosystems - -Most real-world ecosystems fit the package model above but use different terms. -The table below attempts to document how various ecosystems map to the SLSA -Package model. There are likely mistakes and omissions; corrections and -additions are welcome! - - - - - - - - - - - - - - - - - - - - - - - - - - -
Package ecosystem - Package registry - Package name - Package artifact -
Languages -
Cargo (Rust) - Registry - Crate name - Artifact -
CPAN (Perl) - PAUSE - Distribution - Release (or Distribution) -
Go - Module proxy - Module path - Module -
Maven (Java) - Repository - Group ID + Artifact ID - Artifact -
npm (JavaScript) - Registry - Package Name - Package -
NuGet (C#) - Host - Project - Package -
PyPA (Python) - Index - Project Name - Distribution -
Operating systems -
Dpkg (e.g. Debian) - ? - Package name - Package -
Flatpak - Repository - Application - Bundle -
Homebrew (e.g. Mac) - Repository (Tap) - Package name (Formula) - Binary package (Bottle) -
Pacman (e.g. Arch) - Repository - Package name - Package -
RPM (e.g. Red Hat) - Repository - Package name - Package -
Nix (e.g. NixOS) - Repository (e.g. Nixpkgs) or binary cache - Derivation name - Derivation or store object -
Storage systems -
GCS - n/a - Object name - Object -
OCI/Docker - Registry - Repository - Object -
Meta -
deps.dev: System - Packaging authority - Package - n/a -
purl: type - Namespace - Name - n/a -
- -Notes: - -- Go uses a significantly different distribution model than other ecosystems. - In Go, the package name is a source repository URL. While clients can fetch - directly from that URL---in which case there is no "package" or - "registry"---they usually fetch a zip file from a *module proxy*. The module - proxy acts as both a builder (by constructing the package artifact from - source) and a registry (by mapping package name to package artifact). People - trust the module proxy because builds are independently reproducible, and a - *checksum database* guarantees that all clients receive the same artifact - for a given URL. - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build platform is -certified to ensure conformance with the requirements at the level claimed by -the build platform. This certification should happen on a recurring cadence, with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer-defined -expectations of where the package source code was retrieved from and on what -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 assessment | [Build platforms are assessed](assessing-build-platforms.md) for their ability to meet 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 assessment | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their adherence 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 assessment | Performed by the language ecosystem packaging authority. - -
diff --git a/docs/spec/v1.2-rc1/threats-overview.md b/docs/spec/v1.2-rc1/threats-overview.md deleted file mode 100644 index 8b2d04a25..000000000 --- a/docs/spec/v1.2-rc1/threats-overview.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Supply chain threats -description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA could help. ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA could help. For a more technical discussion, see [Threats & mitigations](threats.md). - -## Summary - -![Supply Chain Threats](images/supply-chain-threats.svg) - -**Note that SLSA does not currently address all of the threats presented here.** -See [Threats & mitigations](threats.md) for what is currently addressed and -[Terminology](terminology.md) for an explanation of the supply chain model. - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that the source revision represents the intent of the producer, that all expected processes were followed and that the revision was not modified after being accepted. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - - - -
-Threats from -Known example -How SLSA could help -
A -Producer -SpySheriff: Software producer purports to offer anti-spyware software, but that software is actually malicious. -SLSA does not directly address this threat but could make it easier to discover malicious behavior in open source software, by forcing it into the publicly available source code. -For closed source software SLSA does not provide any solutions for malicious producers. -
B -Authoring & reviewing -SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. -Two-person review could have caught the unauthorized change. -
C -Source code management -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code system would have been a much harder target for the attackers. -
D -External build parameters -The Great Suspender: Attacker published software that was not built from the purported sources. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
E -Build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA Build levels have stronger security requirements for the build platform, making it more difficult for an attacker to forge the SLSA provenance and gain persistence. -
F -Artifact publication -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Distribution channel -Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Package selection -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
I -Usage -Default credentials: Attacker could leverage default credentials to access sensitive data. -SLSA does not address this threat. -
N/A -Dependency threats (i.e. A-H, recursively) -event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code. -Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source. -
- - - - - - -
-Availability threat -Known example -How SLSA could help -
N/A -Dependency becomes unavailable -Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. diff --git a/docs/spec/v1.2-rc1/threats.md b/docs/spec/v1.2-rc1/threats.md deleted file mode 100644 index 6be429c40..000000000 --- a/docs/spec/v1.2-rc1/threats.md +++ /dev/null @@ -1,1075 +0,0 @@ ---- -title: Threats & mitigations -description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. ---- - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations with SLSA and other best practices. For an -introduction to the supply chain threats that SLSA is aiming to protect -against, see [Supply chain threats]. - -The examples on this page are meant to: - -- Explain the reasons for each of the SLSA [build](build-requirements.md) and - [source](source-requirements.md) requirements. -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](about#how-slsa-works) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - - - -
- -## Overview - -![Supply Chain Threats](images/supply-chain-threats.svg) - -This threat model covers the *software supply chain*, meaning the process by -which software is produced and consumed. We describe and cluster threats based -on where in the software development pipeline those threats occur, labeled (A) -through (I). This is useful because priorities and mitigations mostly cluster -along those same lines. Keep in mind that dependencies are -[highly recursive](#dependency-threats), so each dependency has its own threats -(A) through (I), and the same for *their* dependencies, and so on. For a more -detailed explanation of the supply chain model, see -[Terminology](terminology.md). - -Importantly, producers and consumers face *aggregate* risk across all of the -software they produce and consume, respectively. Many organizations produce -and/or consume thousands of software packages, both first- and third-party, and -it is not practical to rely on every individual team in the organization to do -the right thing. For this reason, SLSA prioritizes mitigations that can be -broadly adopted in an automated fashion, minimizing the chance of mistakes. - -## Source threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes modification of the source data at rest as well as insider threats, -when an authorized individual introduces an unauthorized change. - -The SLSA Source track mitigates these threats when the consumer -[verifies source](verifying-source.md) against expectations, confirming -that the revision they received was created in the expected manner. - -### (A) Producer - -The producer of the software intentionally produces code that harms the -consumer, or the producer otherwise uses practices that are not deserving of the -consumer's trust. - -
Software producer intentionally creates a malicious revision of the source - -*Threat:* A producer intentionally creates a malicious revision with the intent of harming their consumers. - -*Mitigation:* -This kind of attack cannot be directly mitigated through SLSA controls. -Consumers must establish some basis to trust the organizations from which they consume software. -That basis may be: - -- The repo is open source with an active user-base. High numbers of engaged users may increase the likelihood that bad code is detected during code review and reduce the time-to-detection when bad revisions are accepted. -- The organization has sufficient legal or reputational incentives to dissuade it from making malicious changes. - -Ultimately this is a judgement call with no straightforward answer. - -*Example:* A producer with an otherwise good reputation decides suddenly to produce a malicious artifact with the intent to harm their consumers. - -
- -### (B) Modifying the source - -An adversary without any special administrator privileges attempts to introduce a change counter to the declared intent of the source by following the producer's official source control process. - -Threats in this category can be mitigated by following source control management best practices. - -#### (B1) Submit change without review - -
Directly submit without review(Source L4) - -*Threat:* Malicious code submitted to the source repository. - -*Mitigation:* Require approval of all changes before they are accepted. - -*Example:* Adversary directly pushes a change to a git repo's `main` branch. -Solution: The Source Control System is configured to require two party review for -contributions to the `main` branch. - -
-
Single actor controls multiple accounts - -*Threat:* An actor is able to control multiple account and effectively approve their own code changes. - -*Mitigation:* The producer must ensure that no actor is able to control or influence multiple accounts with review privileges. - -*Example:* Adversary creates a pull request using a secondary account and approves it using their primary account. -Solution: The producer must track all actors who have both explicit review permissions and the independent ability to control -a privileged bot. A common vector for this attack is to influence a robot account with the permission to review or contribute -code. Control of the robot account and an actor's own personal account is enough to exploit this vulnerability. A common -solution to this flow is to deny bot accounts from contributing or reviewing code, or to require more human reviews in those -cases. - -
-
Use a robot account to submit change - -*Threat:* Exploit a robot account that has the ability to submit changes without -two-person review. - -*Mitigation:* All changes require review by two people, even changes authored by -robots. - -*Example:* A file within the source repository is automatically generated by a -robot, which is allowed to submit without review. -Adversary compromises the robot and submits a malicious change. -Solution: Require two-person review for such changes, ignoring the robot. - -
-
Abuse of rule exceptions - -*Threat:* Rule exceptions provide vector for abuse. - -*Mitigation:* Remove rule exceptions. - -*Example:* A producer intends to require two-person review on "all changes except for documentation changes," defined as those only modifying `.md` files. -Adversary submits a malicious executable masquerading as a documentation file, `help.md`. -This avoids the two-person review rule due to the exception. -In the future, a user (or another workflow) can be induced to *execute* `help.md` and become compromised. -Technically the malicious code change met all defined policies yet the intent of the organization was defeated. -Solution: The producer adjusts the rules to prohibit such exceptions. - -
- -
Highly-permissioned actor bypasses or disables controls(verification) - -*Threat:* Trusted actor with "admin" privileges in a repository submits code by disabling existing controls. - -*Mitigation:* The Source Control System must have controls in place to prevent -and detect abusive behavior from administrators (e.g. two-person approvals, -audit logging). - -*Example:* GitHub repository-level admin removes a branch protection requirement, pushes -their change, then re-enables the requirement to cover their tracks. -Solution: Consumers do not accept claims from the Source Control System unless -they trust sufficient controls are in place to prevent repo admins from -abusing privileges. - -
- -#### (B2) Evade change management process - -
Alter change history(Source L2+) - -*Threat:* Adversary alters branch history to hide malicious activity. - -*Mitigation:* The Source Control System prevents branch history from being -altered. - -*Example:* Adversary submits a malicious commit `X` to the `main` branch. A -release is built and published from `X`. The adversary then "force pushes" -to `main` erasing the record of the malicious commit. Solution: The Source -Control System is configured to prevent force pushes to `main`. - -
-
Replace tagged content with malicious content(Source L2+) - -*Threat:* Adversary alters a tag to point at malicious content. - -*Mitigation:* The Source Control System does not allow protected tags to be updated. - -*Example:* Adversary crafts a malicious commit `X` on a development branch which -does enforce any controls. They then update the `release_1.2` tag to point to -`X`. Consumers of `release_1.2` will get the malicious revision. Solution: The -Source Control System does not allow protected tags to be updated. - -
-
Skip required checks(Source L2+) - -*Threat:* Code is submitted without following the producers documented -development process, introducing unintended behavior. - -*Mitigation:* The producer uses the Source Control System to implement technical -controls ensuring adherence to the development process. - -*Example:* An engineer submits a new feature that has a critical flaw on an -untested code path, in violation of the producer's documented process of having -high test coverage. Solution: The producer implements a technical control in the -SCS that requires 95%+ test coverage. - -
-
Modify code after review(Source L4) - -*Threat:* Modify the code after it has been reviewed but before submission. - -*Mitigation:* The Source Control System invalidates approvals whenever the proposed change is modified. - -*Example:* Source repository requires two-person review on all changes. -Adversary sends an initial "good" pull request to a peer, who approves it. -Adversary then modifies their proposal to contain "bad" code. - -Solution: Configure the code review rules to require review of the most recent revision before submission. - -
-
Submit a change that is unreviewable(Source L4) - -*Threat:* Adversary crafts a change that looks benign to a reviewer but is actually malicious. - -*Mitigation:* Code review system ensures that all reviews are informed and -meaningful to the extent possible. For example the system could show -& resolve symlinks, render images, or verify & display provenance. - -*Example:* A proposed change updates a JPEG file to include a malicious -message, but the reviewer is only presented with a diff of the binary -file contents. The reviewer is unable to parse the contents themselves -so they do not have enough context to provide a meaningful review. -Solution: the code review system should present the reviewer with a -rendering of the image and the [embedded -metadata](https://en.wikipedia.org/wiki/Exif), allowing them to make an -informed decision. - -
-
Copy a reviewed change to another context(Source L4) - -*Threat:* Get a change reviewed in one context and then transfer it to a -different context. - -*Mitigation:* Approvals are context-specific. - -*Example:* MyPackage's source repository requires two-person review. Adversary -forks the repo, submits a change in the fork with review from a colluding -colleague (who is not trusted by MyPackage), then proposes the change to -the upstream repo. -Solution: The proposed change still requires two-person review in the upstream -context even though it received two-person review in another context. - -
- - -
Commit graph attacks - -*Threat:* A malicious commit can be included in a sequence of commits such that it does not appear malicious in the net change presented to reviewers. - -*Mitigation:* The producer ensures that all revisions in the protected context followed the same contribution process. - -*Example:* Adversary sends a pull request containing malicious commit X and a commit Y that undoes X. -The combined change of X + Y displays zero lines of malicious code and the reviewer cannot tell that X is malicious unless they review it individually. -If X is allowed to become reachable from the protected branch, the content may become available in secured environments such as developer machines. - -Solution: Each revision in the protected context must have followed the intended process. -Ultimately, this means that either each code review results in at most a single new commit or that the full process is followed for each constituent commit in a proposed sequence. - -
- -#### (B3) Render code review ineffective - -
Collude with another trusted person - -*Threat:* Two trusted persons collude to author and approve a bad change. - -*Mitigation:* This threat is not currently addressed by SLSA, but the producer can arbitrarily increase friction of their policies to reduce risk, such as requiring additional, or more senior reviewers. -The goal of policy here is to ensure that the approved changes match the intention of the producer for the source. -Increasing the friction of the policies may make it harder to circumvent, but doing so has diminishing returns. -Ultimately the producer will need to land upon a balanced risk profile that makes sense for their security posture. - -
-
Trick reviewer into approving bad code - -*Threat:* Construct a change that looks benign but is actually malicious, a.k.a. -"bugdoor." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
Reviewer blindly approves changes - -*Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber -stamping." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -#### (B4) Render change metadata ineffective - -
Forge change metadata(Source L2+) - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* The Source Control System only attributes changes to authenticated -identities and, at Source L3+, records contemporaneous evidence of changes in -signed source provenance attestations. - -*Example:* Adversary 'X' creates a commit with unauthenticated metadata claiming -it was authored by 'Y'. Solution: The Source Control System records the identity -of 'X' when 'X' submits the commit to the repository. - -
- -### (C) Source code management - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -
Platform admin abuses privileges(verification) - -*Threat:* Platform administrator abuses their privileges to bypass controls or -to push a malicious version of the software. - -*Mitigation:* The source platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals for -changes to the infrastructure, audit logging). A future [Platform -Operations Track](future-directions#platform-operations-track) may provide -more specific guidance on how to secure the underlying platform. - -*Example 1:* GitHostingService employee uses an internal tool to push changes to -the MyPackage source repo. - -*Example 2:* GitHostingService employee uses an internal tool to push a -malicious version of the server to serve malicious versions of MyPackage sources -to a specific CI/CD client but the regular version to everyone else, in order to -hide tracks. - -*Example 3:* GitHostingService employee uses an internal tool to push a -malicious version of the server that includes a backdoor allowing specific users -to bypass branch protections. Adversary then uses this backdoor to submit a -change to MyPackage without review. - -*Solution:* Consumers do not accept claims from the Source Control System unless -they trust sufficient controls are in place to prevent repo admins from -abusing privileges. - -
-
Exploit vulnerability in SCM - -*Threat:* Exploit a vulnerability in the implementation of the source code -management system to bypass controls. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - -### (D) External build parameters - -An adversary builds from a version of the source code that does not match the -official source control repository, or changes the build parameters to inject -behavior that was not intended by the official source. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (E) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build platform pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -### (E) Build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Forge values of the provenance (other than output digest) (Build L2+) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, the trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][unforgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -platform to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Forge output digest of the provenance (n/a) - -*Threat:* The tenant-controlled build process sets output artifact digest -(`subject` in SLSA Provenance) without the trusted control plane verifying that -such an artifact was actually produced. - -*Mitigation:* None; this is not a problem. Any build claiming to produce a given -artifact could have actually produced it by copying it verbatim from input to -output.[^preimage] (Reminder: Provenance is only a claim that a particular -artifact was *built*, not that it was *published* to a particular registry.) - -*Example:* A legitimate MyPackage artifact has digest `abcdef` and is built -from source repo `good/my-package`. A malicious build from source repo -`evil/my-package` claims that it built artifact `abcdef` when it did not. -Solution: Verifier rejects because the source location does not match; the -forged digest is irrelevant. - -[^preimage]: Technically this requires the artifact to be known to the - adversary. If they only know the digest but not the actual contents, they - cannot actually build the artifact without a [preimage attack] on the digest - algorithm. However, even still there are no known concerns where this is a - problem. - -[preimage attack]: https://en.wikipedia.org/wiki/Preimage_attack - -
-
Compromise project owner (Build L2+) - -*Threat:* An adversary gains owner permissions for the artifact's build project. - -*Mitigation:* The build project owner must not have the ability to influence the -build process or provenance generation. - -*Example:* MyPackage is built on Awesome Builder under the project "mypackage". -Adversary is an owner of the "mypackage" project. Awesome Builder allows -owners to debug the build environment via SSH. An adversary uses this feature -to alter a build in progress. Solution: Build L3 requires the external parameters -to be complete in the provenance. The attackers access and/or actions within the -SSH connection would be enumerated within the external parameters. The updated -external parameters will not match the declared expectations causing verification -to fail. - -
-
Compromise other build (Build L3) - -*Threat:* Perform a malicious build that alters the behavior of a benign -build running in parallel or subsequent environments. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other or persist changes. - -*Example 1:* A build platform runs all builds for project MyPackage on -the same machine as the same Linux user. An adversary starts a malicious build -that listens for another build and swaps out source files, then starts a benign -build. The benign build uses the malicious build's source files, but its -provenance says it used benign source files. Solution: The build platform -changes architecture to isolate each build in a separate VM or similar. - -*Example 2:* A build platform uses the same machine for subsequent -builds. An adversary first runs a build that replaces the `make` binary with a -malicious version, then subsequently runs an otherwise benign build. Solution: -The builder changes architecture to start each build with a clean machine image. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build platform. - -*Mitigation:* Builds are [isolated] from the trusted build platform control -plane, and only the control plane has [access][unforgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a malicious artifact to a build cache that is later picked up by a -benign build process ([example][build-cache-poisoning-example]). - -*Mitigation:* Build caches must be [isolated][isolated] between builds to prevent -such cache poisoning attacks. In particular, the cache SHOULD be keyed by the -transitive closure of all inputs to the cached artifact, and the cache must -either be only writable by the trusted control plane or have SLSA Build L3 -provenance for each cache entry. - -*Example 1:* The cache key does not fully cover the transitive closure of all -inputs and instead only uses the digest of the source file itself. Adversary runs -a build over `auth.cc` with command line flags to gcc that define a marco -replacing `CheckAuth(ctx)` with `true`. When subsequent builds build `auth.cc` -they will get the attacker's poisoned instance that does not call `CheckAuth`. -Solution: Build cache is keyed by digest of `auth.cc`, command line, and digest of -gcc so changing the command line flags results in a different cache entry. - -*Example 2:* The tenant controlled build process has full write access to the -cache. Adversary observes a legitimate build of `auth.cc` which covers the -transitive closure of all inputs and notes the digest used for caching. The -adversary builds a malicious version of `auth.o` and directly writes it to the -build cache using the observed digest. Subsequent legitimate builds will use -the malicious version of `auth.o`. Solution: Each cache entry is keyed by the -transitive closure of the inputs, and the cache entry is itself a SLSA Build L3 -build with its own provenance that corresponds to the key. - -
-
Compromise build platform admin (verification) - -*Threat:* An adversary gains admin permissions for the artifact's build platform. - -*Mitigation:* The build platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals, audit -logging). - -*Example:* MyPackage is built on Awesome Builder. Awesome Builder allows -engineers on-call to SSH into build machines to debug production issues. An -adversary uses this access to modify a build in progress. Solution: Consumers -do not accept provenance from the build platform unless they trust sufficient -controls are in place to prevent abusing admin privileges. - -
- -### (F) Artifact publication - -An adversary uploads a package artifact that does not reflect the intent of the -package's official source control repository. - -This is the most direct threat because it is the easiest to pull off. If there -are no mitigations for this threat, then (D) and (E) are often indistinguishable -from this threat. - - - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Solution: Verifier rejects because builder is not as -expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Distribution channel - -An adversary modifies the package on the package registry using an -administrative interface or through a compromise of the infrastructure -including modification of the package in transit to the consumer. - -The distribution channel threats and mitigations look very similar to the -Artifact Publication (F) threats and mitigations with the main difference -being that these threats are mitigated by having the *consumer* perform -verification. - -The consumer's actions may be simplified if (F) produces a [VSA][vsa]. -In this case the consumer may replace provenance verification with -[VSA verification][vsa_verification]. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Replace the package with one built using an unofficial CI/CD pipeline -that does not build in the correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value or a VSA for corresponding `resourceUri`. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Adversary then replaces the original package within the -repository with the malicious package. Solution: Verifier rejects because -builder is not as expected. - -
-
Issue VSA from untrusted intermediary (expectations) - -*Threat:* Have an unofficial intermediary issue a VSA for a malicious package. - -*Mitigation*: Verifier requires VSAs to be issued by a trusted intermediary. - -*Example:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then issues a VSA of their own for the malicious -package. Solution: Verifier rejects because they only accept VSAs from -TheRepository which the adversary cannot issue since they do not have the -corresponding signing key. - -
-
Upload package without provenance or VSA (Build L1) - -*Threat:* Replace the original package with a malicious one without provenance. - -*Mitigation:* Verifier requires provenance or a VSA before accepting the package. - -*Example:* Adversary replaces MyPackage with a malicious version of MyPackage -on the package repository and deletes existing provenance. Solution: Verifier -rejects because provenance is missing. - -
-
Replace package and VSA with another (expectations) - -*Threat:* Replace a package and its VSA with a malicious package and its valid VSA. - -*Mitigation*: Consumer ensures that the VSA matches the package they've requested (not just the package they received) by following the [verification process](verification_summary#how-to-verify). - -*Example:* Adversary uploads a malicious package to `repo/evil-package`, -getting a valid VSA for `repo/evil-package`. Adversary then replaces -`repo/my-package` and its VSA with `repo/evil-package` and its VSA. -Solution: Verifier rejects because the VSA `resourceUri` field lists -`repo/evil-package` and not the expected `repo/my-package`. - -
-
Tamper with artifact after upload (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -replace it while retaining the original provenance or VSA. - -*Mitigation:* Verifier checks that the provenance or VSA's `subject` matches -the hash of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -replaces the modified version of the package in the repository and retains the -original provenance. Solution: Verifier rejects because the hash of the -artifact does not match the `subject` found within the provenance. - -
-
Tamper with provenance or VSA (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance or VSA to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance or VSA with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder or the VSA came from an expected verifier. - -*Example 1:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -*Example 2:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then modifies the original VSA's `subject` -field to match the digest of the malicious package. Solution: Verifier rejects -because the cryptographic signature is no longer valid. - -
- -## Usage threats - -A usage threat is a potential for an adversary to exploit behavior of the -consumer. - -### (H) Package selection - -The consumer requests a package that it did not intend. - -
Dependency confusion - -*Threat:* Register a package name in a public registry that shadows a name used -on the victim's internal registry, and wait for a misconfigured victim to fetch -from the public registry instead of the internal one. - -*Mitigation:* The mitigation is for the software producer to build internal -packages on a SLSA Level 2+ compliant build system and define expectations for -build provenance. Expectations must be verified on installation of the internal -packages. If a misconfigured victim attempts to install attacker's package with -an internal name but from the public registry, then verification against -expectations will fail. - -For more information see [Verifying artifacts](verifying-artifacts.md) -and [Defender's Perspective: Dependency Confusion and Typosquatting Attacks](/blog/2024/08/dep-confusion-and-typosquatting). - -
- -
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, the -requirement to make the source available can be a mild deterrent, can aid -investigation or ad-hoc analysis, and can complement source-based typosquatting -solutions. - -
- -### (I) Usage - -The consumer uses a package in an unsafe manner. - -
Improper usage - -*Threat:* The software can be used in an insecure manner, allowing an -adversary to compromise the consumer. - -*Mitigation:* This threat is not addressed by SLSA, but may be addressed by -efforts like [Secure by Design][secure-by-design]. - -
- -## Dependency threats - -A dependency threat is a potential for an adversary to introduce unintended -behavior in one artifact by compromising some other artifact that the former -depends on at build time. (Runtime dependencies are excluded from the model, as -[noted below](#runtime-dep).) - -Unlike other threat categories, dependency threats develop recursively through -the supply chain and can only be exploited indirectly. For example, if -application *A* includes library *B* as part of its build process, then a build -or source threat to *B* is also a dependency threat to *A*. Furthermore, if -library *B* uses build tool *C*, then a source or build threat to *C* is also a -dependency threat to both *A* and *B*. - -This version of SLSA does not explicitly address dependency threats, but we -expect that a future version will. In the meantime, you can [apply SLSA -recursively] to your dependencies in order to reduce the risk of dependency -threats. - - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively - -### Build dependency - -An adversary compromises the target artifact through one of its build -dependencies. Any artifact that is present in the build environment and has the -ability to influence the output is considered a build dependency. - -
Include a vulnerable dependency (library, base image, bundled file, etc.) - -*Threat:* Statically link, bundle, or otherwise include an artifact that is -compromised or has some vulnerability, causing the output artifact to have the -same vulnerability. - -*Example:* The C++ program MyPackage statically links libDep at build time. A -contributor accidentally introduces a security vulnerability into libDep. The -next time MyPackage is built, it picks up and includes the vulnerable version of -libDep, resulting in MyPackage also having the security vulnerability. - -*Mitigation:* A future -[Dependency track](../../current-activities#dependency-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -
-
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.) - -*Threat:* Use a compromised tool or other software artifact during the build -process, which alters the build process and injects unintended behavior into the -output artifact. - -*Mitigation:* This can be partially mitigated by treating build tooling, -including OS images, as any other artifact to be verified prior to use. -The threats described in this document apply recursively to build tooling -as do the mitigations and examples. A future -[Build Environment track](../../current-activities#build-environment-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -*Example:* MyPackage is a tarball containing an ELF executable, created by -running `/usr/bin/tar` during its build process. An adversary compromises the -`tar` OS package such that `/usr/bin/tar` injects a backdoor into every ELF -executable it writes. The next time MyPackage is built, the build picks up the -vulnerable `tar` package, which injects the backdoor into the resulting -MyPackage artifact. Solution: [apply SLSA recursively] to all build tools -prior to the build. The build platform verifies the disk image, -or the individual components on the disk image, against the associated -provenance or VSAs prior to running a build. Depending on where the initial -compromise took place (i.e. before/during vs *after* the build of the build tool itself), the modified `/usr/bin/tar` will fail this verification. - -
- -
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.) - -*Threat:* During the build process, use a compromised runtime dependency (such -as during testing or dynamic linking), which alters the build process and -injects unwanted behavior into the output. - -**NOTE:** This is technically the same case as [Use a compromised build -tool](#build-tool). We call it out to remind the reader that -[runtime dependencies](#runtime-dep) can become build dependencies if they are -loaded during the build. - -*Example:* MyPackage has a runtime dependency on package Dep, meaning that Dep -is not included in MyPackage but required to be installed on the user's machine -at the time MyPackage is run. However, Dep is also loaded during the build -process of MyPackage as part of a test. An adversary compromises Dep such that, -when run during a build, it injects a backdoor into the output artifact. The -next time MyPackage is built, it picks up and loads Dep during the build -process. The malicious code then injects the backdoor into the new MyPackage -artifact. - -*Mitigation:* In addition to all the mitigations for build tools, you can often -avoid runtime dependencies becoming build dependencies by isolating tests to a -separate environment that does not have write access to the output artifact. - -
- -### Related threats - -The following threats are related to "dependencies" but are not modeled as -"dependency threats". - -
Use a compromised dependency at runtime (modeled separately) - -*Threat:* Load a compromised artifact at runtime, thereby compromising the user -or environment where the software ran. - -*Example:* MyPackage lists package Dep as a runtime dependency. Adversary -publishes a compromised version of Dep that runs malicious code on the user's -machine when Dep is loaded at runtime. An end user installs MyPackage, which in -turn installs the compromised version of Dep. When the user runs MyPackage, it -loads and executes the malicious code from Dep. - -*Mitigation:* N/A - SLSA's -threat model does not explicitly model runtime dependencies. Instead, each -runtime dependency is considered a distinct artifact with its own threats. - -
- -## Availability threats - - - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA does not currently address availability threats, though future versions might. - -
Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, some -solutions to support hermetic and reproducible builds may also reduce the -impact of this threat. - -
-
De-list artifact - -*Threat:* The package registry stops serving the artifact. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
De-list provenance - -*Threat:* The package registry stops serving the provenance. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Verification threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above. - -
Tamper with recorded expectations - -*Threat:* Modify the verifier's recorded expectations, causing the verifier to -accept an unofficial package artifact. - -*Mitigation:* Changes to recorded expectations requires some form of -authorization, such as two-party review. - -*Example:* The package ecosystem records its expectations for a given package -name in a configuration file that is modifiable by that package's producer. The -configuration for MyPackage expects the source repository to be -`good/my-package`. The adversary modifies the configuration to also accept -`evil/my-package`, and then builds from that repository and uploads a malicious -version of the package. Solution: Changes to the recorded expectations require -two-party review. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Choose secure algorithms when using cryptographic digests, such -as SHA-256. - -*Examples:* Attacker crafts a malicious file with the same MD5 hash as a target -benign file. Attacker replaces the benign file with the malicious file. -Solution: Only accept cryptographic hashes with strong collision resistance. - -
- -
- - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively -[authentic]: build-requirements.md#provenance-authentic -[build-cache-poisoning-example]: https://adnanthekhan.com/2024/05/06/the-monsters-in-your-build-cache-github-actions-cache-poisoning/ -[exists]: build-requirements.md#provenance-exists -[isolated]: build-requirements.md#isolated -[unforgeable]: build-requirements.md#provenance-unforgeable -[secure-by-design]: https://www.cisa.gov/securebydesign -[supply chain threats]: threats-overview -[vsa]: verification_summary -[vsa_verification]: verification_summary#how-to-verify diff --git a/docs/spec/v1.2-rc1/tracks.md b/docs/spec/v1.2-rc1/tracks.md deleted file mode 100644 index 7b7b49026..000000000 --- a/docs/spec/v1.2-rc1/tracks.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Tracks -description: Provides an overview of each track and links to more specific information. ---- - -SLSA is composed of [multiple tracks](about#how-slsa-works) which are each -composed of multiple levels. Each track addresses different [threats](threats) -and has its own set of requirements and patterns of use. - -## Build Track - -The SLSA build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance. Provenance describes -what entity built the artifact, what process they used, and what the inputs -were. The lowest level only requires the provenance to exist, while higher -levels provide increasing protection against tampering of the build, the -provenance, or the artifact. - -The primary purpose of the build track is to enable -[verification](verifying-artifacts.md) that the artifact was built as expected. -Consumers have some way of knowing what the expected provenance should look like -for a given package and then compare each package artifact's actual provenance -to those expectations. Doing so prevents several classes of -[supply chain threats](threats.md). - -Each ecosystem (for open source) or organization (for closed source) defines -exactly how this is implemented, including: means of defining expectations, what -provenance format is accepted, whether reproducible builds are used, how -provenance is distributed, when verification happens, and what happens on -failure. Guidelines for implementers can be found in the -[requirements](build-requirements.md). - -- [Terminology](terminology.md) -- [Basics](build-track-basics.md) -- [Requirements](build-requirements.md) -- [Build provenance](build-provenance.md) -- [Assessing build platforms](assessing-build-platforms.md) - -## Source Track - -The SLSA source track provides producers and consumers with increasing levels of -trust in the source code they produce and consume. It describes increasing -levels of trustworthiness and completeness of how a source revision was created. - -The expected process for creating a new revision is determined solely by that -repository's owner (the organization) who also determines the intent of the -software in the repository and administers technical controls to enforce the -process. - -Consumers can review attestations to verify whether a particular revision meets their standards. - -- [Requirements](source-requirements.md) -- [Source provenance](source-requirements#source-provenance-attestations) -- [Assessing source systems](assessing-source-systems.md) diff --git a/docs/spec/v1.2-rc1/use-cases.md b/docs/spec/v1.2-rc1/use-cases.md deleted file mode 100644 index f3d53d55c..000000000 --- a/docs/spec/v1.2-rc1/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two-person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package registry. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build platforms rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor-provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on the trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor-provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified by a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.2-rc1/verification_summary.md b/docs/spec/v1.2-rc1/verification_summary.md deleted file mode 100644 index 2dfe66d4b..000000000 --- a/docs/spec/v1.2-rc1/verification_summary.md +++ /dev/null @@ -1,429 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software producers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [resolvedDependencies](/build-provenance/v1#resolvedDependencies) of the -artifact being verified (recursively) or b) matching the non-source dependency -listed in `resolvedDependencies` (`subject.digest` == -`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` == -`resolvedDependencies.uri`) to a VSA _for that dependency_ and using -`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependencyLevels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "", - "version": { - "": "", - ... - } - }, - "timeVerified": , - "resourceUri": , - "policy": { - "uri": "", - "digest": { } - } - "inputAttestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verificationResult": "", - "verifiedLevels": [""], - "dependencyLevels": { - "": , - "": , - ... - }, - "slsaVersion": ".", -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`verifier.version` _map (string->string), optional_ - -> Map of names of components of the verification platform to their version. - - -`timeVerified` _string ([Timestamp]), optional_ - -> Timestamp indicating what time the verification occurred. - - -`resourceUri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. -> -> The `resourceUri` SHOULD be set to the URI from which the producer expects the -> consumer to fetch the artifact for verification. This enables the consumer to -> easily determine the expected value when [verifying](#how-to-verify). If the -> `resourceUri` is set to some other value, the producer MUST communicate the -> expected value, or how to determine the expected value, to consumers through -> an out-of-band channel. - - -`policy` _object ([ResourceDescriptor]), required_ - -> Describes the policy that the `subject` was verified against. -> -> The entry MUST contain a `uri` identifying which policy was applied and -> SHOULD contain a `digest` to indicate the exact version of that policy. - - -`inputAttestations` _array ([ResourceDescriptor]), optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `resolvedDependencies` field in [SLSA Provenance]. -> -> This field MAY be absent if the verifier does not support this feature. -> If non-empty, this field MUST contain information on _all_ the attestations -> used to perform verification. -> -> Each entry MUST contain a `digest` of the attestation and SHOULD contains a -> `uri` that can be used to fetch the attestation. - - -`verificationResult` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`verifiedLevels` _array ([SlsaResult]), required_ - -> Indicates the highest level of each track verified for the artifact (and not -> its dependencies) verified for the artifact or "FAILED" if policy verification -> failed. -> -> Users MUST NOT include more than one level per SLSA track. Note that each SLSA -> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies -> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to -> include more than one level per track. - - -`dependencyLevels` _object, optional_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. -> A set but empty `dependencyLevels` object means that the artifact has **no** -> dependency at all, while an unset or null `dependencyLevels` means that the -> verifier makes no claims about the artifact's dependencies. -> -> Users MUST count each dependency only once per SLSA track, at the highest -> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`, -> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for -> `SLSA_BUILD_LEVEL_1`. - - -`slsaVersion` _string, optional_ - -> Indicates the version of the SLSA specification that the verifier used, in the -> form `.`. Example: `1.0`. If unset, the default is an -> unspecified minor version of `1.x`. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier", - "version": { - "slsa-verifier-linux-amd64": "v2.3.0", - "slsa-framework/slsa-verifier/actions/installer": "v2.3.0" - } - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "inputAttestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_BUILD_LEVEL_3"], - "dependencyLevels": { - "SLSA_BUILD_LEVEL_3": 5, - "SLSA_BUILD_LEVEL_2": 7, - "SLSA_BUILD_LEVEL_1": 1, - }, - "slsaVersion": "1.0" -} -``` - -## How to verify - -VSA consumers use VSAs to accomplish goals based on delegated trust. We call the -process of establishing a VSA's authenticity and determining whether it meets -the consumer's goals 'verification'. Goals differ, as do levels of confidence -in VSA producers, so the verification procedure changes to suit its context. -However, there are certain steps that most verification procedures have in -common. - -Verification MUST include the following steps: - -1. Verify the signature on the VSA envelope using the preconfigured roots of - trust. This step ensures that the VSA was produced by a trusted producer - and that it hasn't been tampered with. - -2. Verify the statement's `subject` matches the digest of the artifact in - question. This step ensures that the VSA pertains to the intended artifact. - -3. Verify that the `predicateType` is - `https://slsa.dev/verification_summary/v1`. This step ensures that the - in-toto predicate is using this version of the VSA format. - -4. Verify that the `verifier` matches the public key (or equivalent) used to - verify the signature in step 1. This step identifies the VSA producer in - cases where their identity is not implicitly revealed in step 1. - -5. Verify that the value for `resourceUri` in the VSA matches the expected - value. This step ensures that the consumer is using the VSA for the - producer's intended purpose. - -6. Verify that the value for `slsaResult` is `PASSED`. This step ensures the - artifact is suitable for the consumer's purposes. - -7. Verify that `verifiedLevels` contains the expected value. This step ensures - that the artifact is suitable for the consumer's purposes. - -Verification MAY additionally contain the following step: - -1. (Optional) Verify additional fields required to determine whether the VSA - meets your goal. - -Verification mitigates different threats depending on the VSA's contents and the -verification procedure. - -IMPORTANT: A VSA does not protect against compromise of the verifier, such as by -a malicious insider. Instead, VSA consumers SHOULD carefully consider which -verifiers they add to their roots of trust. - -### Examples - -1. Suppose consumer C wants to delegate to verifier V the decision for whether - to accept artifact A as resource R. Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` contains `SLSA_BUILD_LEVEL_UNEVALUATED`. - - Note: This example is analogous to traditional code signing. The expected - value for `verifiedLevels` is arbitrary but prenegotiated by the producer and - the consumer. The consumer does not need to check additional fields, as C - fully delegates the decision to V. - -2. Suppose consumer C wants to enforce the rule "Artifact A at resource R must - have a passing VSA from verifier V showing it meets SLSA Build Level 2+." - Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` is `SLSA_BUILD_LEVEL_2` or `SLSA_BUILD_LEVEL_3`. - - Note: In this example, verifying the VSA mitigates the same threats as - verifying the artifact's SLSA provenance. See - [Verifying artifacts](/spec/v1.0/verifying-artifacts) for details about which - threats are addressed by verifying each SLSA level. - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -SHOULD be - -- The [SLSA Track](#tracks) level the referenced artifact qualifies for as -`SLSA__LEVEL_`, or -- `SLSA__LEVEL_UNEVALUATED` if the VSA issuer does not want to - make a claim about the track level an artifact meets, or - -For example: - -- `SLSA_BUILD_LEVEL_UNEVALUATED` -- `SLSA_BUILD_LEVEL_0` -- `SLSA_BUILD_LEVEL_3` -- `SLSA_SOURCE_LEVEL_2` -- `SLSA_SOURCE_LEVEL_4` -- `FAILED` (Indicates policy evaluation failed) - -Note that each SLSA level implies the levels below it in the same track. -For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` + -`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`). - -Users MAY use custom values here but MUST NOT use custom values starting with -`SLSA_`. - -## Change history - -- 1.2: - - Update SlsaResult definition to discuss how to refer to new tracks for - additional SLSA endorsed values. -- 1.1: - - Changed the `policy` object to recommend that the `digest` field of - the `ResourceDescriptor` is set. - - Added optional `verifier.version` field to record verification tools. - - Added Verification section with examples. - - Made `timeVerified` optional. -- 1.0: - - Replaced `materials` with `resolvedDependencies`. - - Relaxed `SlsaResult` to allow other values. - - Converted to lowerCamelCase for consistency with [SLSA Provenance]. - - Added `slsaVersion` field. -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SLSA Provenance]: /provenance -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/digest_set.md -[ResourceURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#resourceuri -[ResourceDescriptor]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/resource_descriptor.md -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[Timestamp]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules diff --git a/docs/spec/v1.2-rc1/verifying-artifacts.md b/docs/spec/v1.2-rc1/verifying-artifacts.md deleted file mode 100644 index 0961a19ed..000000000 --- a/docs/spec/v1.2-rc1/verifying-artifacts.md +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: "Build: Verifying artifacts" -description: SLSA uses provenance to indicate whether an artifact is authentic or not, but provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection verification, and this page describes how to verify artifacts and their SLSA provenance. The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that -inspection **verification**, and this page describes recommendations for how to -verify artifacts and their SLSA provenance. - -This page is divided into several sections. The first describes the process -for verifying an artifact and its provenance against a set of expectations. The -second describes how to form the expectations used to verify provenance. The -third discusses architecture choices for where provenance verification can -happen. - -## How to verify - -Verification SHOULD include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- Verifying the signature on the provenance envelope. -- Ensuring that the values for `buildType` and `externalParameters` in the - provenance match the expected values. The package ecosystem MAY allow - an approved list of `externalParameters` to be ignored during verification. - Any unrecognized `externalParameters` SHOULD cause verification to fail. - -![Threats covered by each step](images/supply-chain-threats-build-verification.svg) - -See [Terminology](terminology.md) for an explanation of the supply chain model and -[Threats & mitigations](threats.md) for a detailed explanation of each threat. - -**Note:** This section assumes that the provenance is in the recommended -[provenance format](/provenance/v1). If it is not, then the verifier SHOULD -perform equivalent checks on provenance fields that correspond to the ones -referenced here. - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "E", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This configuration - is likely in the form of a map from (builder public key identity, - `builder.id`) to (SLSA Build level). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the artifact in question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "E"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Assessing build platforms](assessing-build-platforms.md). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "I".) -- [Threat "I"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not yet cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. Those threats are - discussed in more detail under [Threat "H"]. - -[Threat "E"]: threats#e-build-process -[Threat "F"]: threats#f-artifact-publication -[Threat "G"]: threats#g-distribution-channel -[Threat "H"]: threats#h-package-selection -[Threat "I"]: threats#i-usage - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets your expectations for that -package in order to mitigate [threat "D"]. - -In our threat model, the adversary has the ability to invoke a build and to publish -to the registry. The adversary is not able to write to the source repository, nor do -they have insider access to any trusted systems. Your expectations SHOULD be -sufficient to detect or prevent this adversary from injecting unofficial -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 - -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 -range of values (possibly any value) if it is known that any value in the range -is safe. JSON comparison is sufficient for verifying parameters. - -TIP: Difficulty in forming meaningful expectations about `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "D"]: threats#d-external-build-parameters - -### Step 3: (Optional) Check dependencies recursively - -[verify-step-3]: #step-3-optional-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. Note that SLSA v1.0 does not have any requirements on the -completeness or verification of `resolvedDependencies`. However, one might wish -to verify dependencies in order to mitigate [dependency threats] and protect against -threats further up the supply chain. If `resolvedDependencies` is incomplete, -these checks can be done on a best-effort basis. - -A [Verification Summary Attestation (VSA)][VSA] can make dependency verification -more efficient by recording the result of prior verifications. A trimming -heuristic or exception mechanism is almost always necessary when verifying -dependencies because there will be transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) - -[dependency threats]: threats#dependency-threats -[VSA]: /verification_summary -[threats]: threats - -## Forming Expectations - -Expectations are known provenance values that indicate the -corresponding artifact is authentic. For example, a package ecosystem may -maintain a mapping between package names and their canonical source -repositories. That mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git branches or tags. - -- **Defined by producer:** The package producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the package's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -- **Defined in source:** The source repository tells the verifier what their - expectations ought to be. In this model, the package name is immutably bound - to a source repository and all other external parameters are defined in the - source repository. This is how the Go ecosystem works, for example, since - the package name *is* the source repository location. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -will likely have different artifacts and therefore different provenance. Similarly, an -artifact might have different names in different package ecosystems but use the same -provenance file. - -## Architecture options - -There are several options (non-mutually exclusive) for where provenance verification -can happen: the package ecosystem at upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify provenance. For example, even if a package -ecosystem verifies provenance, consumers who get artifacts from that package -ecosystem might wish to verify provenance themselves for defense in depth. They -can do so using either client-side verification tooling or by polling a -monitor. - - - -### Package ecosystem - -[Package ecosystem]: #package-ecosystem - -A package ecosystem is a set of rules and conventions governing -how packages are distributed. Every package artifact has an ecosystem, whether it is -formal or ad-hoc. Some ecosystems are formal, such as language distribution -(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". For more background, see -[Package Model](terminology.md#package-model). - -During package upload, a package ecosystem can ensure that the artifact's -provenance matches the expected values for that package name's provenance before -accepting it into the package registry. This option is RECOMMENDED whenever -possible because doing so benefits all of the package ecosystem's clients. - -The package ecosystem is responsible for making its expectations available to -consumers, reliably redistributing artifacts and provenance, and providing tools -to enable safe artifact consumption (e.g. whether an artifact meets -expectations). - -### Consumer - -[Consumer]: #consumer - -A package artifact's consumer is the organization or individual that uses the -package artifact. - -Consumers can form their own expectations for artifacts or use the default -expectations provided by the package producer and/or package ecosystem. -When forming their own expectations, the consumer uses client-side verification tooling to ensure -that the artifact's provenance matches their expectations for that package -before use (e.g. during installation or deployment). Client-side verification -tooling can be either standalone, such as -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into -the package ecosystem client. - -### Monitor - -[Monitor]: #monitor - -A monitor is a service that verifies provenance for a set -of packages and publishes the result of that verification. The set of -packages verified by a monitor is arbitrary, though it MAY mimic the set -of packages published through one or more package ecosystems. The monitor -SHOULD publish its expectations for all the packages it verifies. - -Consumers can continuously poll a monitor to detect artifacts that -do not meet the monitor's expectations. Detecting artifacts that fail -verification is of limited benefit unless a human or automated system takes -action in response to the failed verification. diff --git a/docs/spec/v1.2-rc1/verifying-source.md b/docs/spec/v1.2-rc1/verifying-source.md deleted file mode 100644 index 5b28a5a75..000000000 --- a/docs/spec/v1.2-rc1/verifying-source.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: "Source: Verifying source" -description: | - SLSA uses attestations to indicate security claims associated with a repository revision, but attestations don't do anything unless somebody inspects them. - SLSA calls that inspection verification, and this page describes how to verify properties of source revisions using their SLSA source provenance attestations. - The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses attestations to indicate security claims associated with a repository -revision, but attestations don't do anything unless somebody inspects them. SLSA -calls that inspection **verification**, and this page describes how to verify -properties of source revisions using -[the attestations](source-requirements#communicating-source-levels) associated -with those revisions. - -At Source L3+, Source Control Systems (SCSs) issue detailed -[provenance attestations](source-requirements#source-provenance-attestations) of -the process that was used to create specific revisions of a repository. These -provenance attestations are issued in bespoke formats and may be too burdensome -to use in some use cases. - -[Source Verification Summary Attestations](source-requirements#source-verification-summary-attestation) -(Source VSAs) address this, making verification more efficient and ergonomic by -recording the result of prior verifications. Source VSAs may be issued by a VSA -provider to make a SLSA source level determination based on the content of those -attestations. - -## How to verify SLSA a source revision - -The source consumer checks: - -1. If they trust the SCS that issued the VSA and if the VSA applies to the - revision they've fetched. -2. If the claims made in the VSA match their expectations for how the source - should be managed. -3. (Optional): If the evidence presented in the source provenance matches the - claims made in the VSA. - -### Step 1: Check the SCS - -First, check the SLSA Source level by comparing the artifact to its VSA and the -VSA to a preconfigured root of trust. The goal is to ensure that the VSA -actually applies to the artifact in question and to assess the trustworthiness -of the VSA. This mitigates threats within "B" and "C", depending on SLSA Source -level. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized SCS - identities and the maximum SLSA Source level each SCS is trusted up to. - Different verifiers MAY use different roots of trust for repositories. The - root of trust configuration is likely in the form of a map from (SCS public - key identity, VSA `verifier.id`) to (SLSA Source level). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaSourceRootsOfTrust": [ - // A SCS trusted at SLSA Source L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "scsId": "https://somescs.example.com/slsa/l3", - "slsaSourceLevel": 3 - }, - // A different SCS that claims to be SLSA Source L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "scsId": "https://differentscs.example.com/slsa/l3", - "slsaSourceLevel": 2 - }, - // A SCS that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@refs/tags/v*.*.*" - }, - "scsId": "https://github.com/slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@refs/tags/v*.*.*", - "slsaSourceLevel": 3, - } - ... - ], - ``` - -
- -Given a revision and its VSA: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the revision in question. -3. Verify that the `predicateType` is `https://slsa.dev/verification_summary/v1`. -4. Look up the SLSA Source Level in the roots of trust, using the recognized - public keys and the `verifier.id`, defaulting to SLSA Source L1. - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check Expectations - -Next, check that the revision's VSA meets your expectations in order to mitigate -[threat "B"]. - -In our threat model, the adversary has the ability to create revisions within -the repository and get consumers to fetch that revision. The adversary is not -able to subvert controls implemented by the Producer and enforced by the SCS. -Your expectations SHOULD be sufficient to detect an un-official revision and -SHOULD make it more difficult for an adversary to create a malicious official -revision. - -You SHOULD compare the VSA against expected values for at least the following -fields: - -| What | Why -| ---- | --- -| Verifier (SCS) identity from [Step 1] | To prevent an adversary from substituting a VSA making false claims from an unintended SCS. -| `predicate.resourceUri` | To prevent an adversary from substituting a VSA for the intended repository (e.g. `git+https://github.com/IntendedOrg/hello-world`) for another (e.g. `git+https://github.com/AdversaryOrg/hello-world`) -| `subject.annotations.source_refs` | To prevent an adversary from substituting the intended revision from one branch (e.g. `release`) with another (e.g. `experimental_auth`). -| `verifiedLevels` | To ensure the expected controls were in place for the creation of the revision. E.g. `SLSA_SOURCE_LEVEL_3`, `ORG_SOURCE_STATIC_ANALYSIS`, etc... - -[Threat "B"]: threats#b-modifying-the-source - -### Step 3: Verify Evidence using Source Provenance [optional] - -Optionally, at SLSA Source Level 3 and up, check the [source provenance -attestations](source-requirements#source-provenance-attestations) directly. - -As the format and implementation of source provenance attestations are left to -the SCS, you SHOULD form expectations about the claims in source provenance -attestations and how they map to a revision's properties claimed in its VSA in -conjunction with the SCS and the producer. - -## Forming Expectations - -Expectations are known values that indicate the corresponding -revision is authentic. For example, an SCS may maintain a mapping between -repository branches & tags and the controls they claim to implement. That -mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the revision as-is. On - each update, compare the old VSA to the new VSA and alert on any - differences. - -- **Defined by producer:** The revision producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the revision's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -It is important to note that expectations are tied to a *repository branch or -tag*, whereas a VSA is tied to an *revision*. Different revisions will have -different VSAs and the claims made by those VSAs may differ. - -## Architecture options - -There are several options (non-mutually exclusive) for where VSA verification -can happen: the build system at source fetch time, the package ecosystem at -build artifact upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify VSAs. For example, even if a builder verifies -source VSAs, package ecosystems may wish to verify the source VSAs for the -artifacts they host that claim to be built from that source (as indicated by the -build provenance). diff --git a/docs/spec/v1.2-rc1/whats-new.md b/docs/spec/v1.2-rc1/whats-new.md deleted file mode 100644 index c3ed8e11e..000000000 --- a/docs/spec/v1.2-rc1/whats-new.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: What's new -description: The changes brought by SLSA 1.2 RC1. ---- - -This document describes the major changes brought by SLSA 1.2 RC1 relative to -the prior release, [v1.1]. - -## Summary of changes - -- Addition of the [Source Track](source-requirements) which helps - organizations secure their source code development process and consumers - establish trust in that source. -- Updated the [threat model](threats) to account for the threats mitigated by - the Source Track. -- Improved the structure of the spec to accomodate multiple tracks. - - - -[v1.1]: /spec/v1.1/ diff --git a/docs/spec/v1.2-rc2/about.md b/docs/spec/v1.2-rc2/about.md deleted file mode 100644 index a763594e7..000000000 --- a/docs/spec/v1.2-rc2/about.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: About SLSA -description: With supply chain attacks on the rise, a shared vocabulary and universal framework are needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software. ---- - -This page is an introduction to SLSA and its concepts. If you're new -to SLSA, start here! - -## What is SLSA? - -Supply-chain Levels for Software Artifacts, or SLSA ("salsa"), is a set of incrementally adoptable guidelines for supply chain security, -established by industry consensus. The specification set by SLSA is useful for -both software producers and consumers: producers can follow SLSA's guidelines to -make their software supply chain more secure, and consumers can use SLSA to make -decisions about whether to trust a software package. - -SLSA offers: - -- A common vocabulary to talk about software supply chain security -- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume -- An actionable checklist to improve your own software's security -- A way to measure your efforts toward compliance with the [Secure Software Development Framework (SSDF)](https://csrc.nist.gov/Projects/ssdf) - -## Why SLSA is needed - -High-profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply -chain integrity weaknesses that may go unnoticed, yet quickly become very -public, disruptive, and costly in today's environment when exploited. They've -also shown that there are inherent risks not just in code itself, but at -multiple points in the complex process of getting that code into software -systems—that is, in the **software supply chain**. Since these attacks are on -the rise and show no sign of decreasing, a universal framework for hardening the -software supply chain is needed, as affirmed by the U.S. Executive Order on -Improving the Nation's Cybersecurity of May 12th, 2021. - -Security techniques for vulnerability detection and analysis of source code are -essential, but are not enough on their own. Even after fuzzing or vulnerability -scanning is completed, changes to code can happen, whether unintentionally or -from insider threats or compromised accounts. Risk for code modification exists at -each link in a typical software supply chain, from source to build through -packaging and distribution. Any weaknesses in the supply chain undermine -confidence in whether the code that you run is actually the code that you -scanned. - -SLSA is designed to support automation that tracks code handling from source -to binary, protecting against tampering regardless of the complexity -of the software supply chain. As a result, SLSA increases trust that the -analysis and review performed on source code can be assumed to still apply to -the binary consumed after the build and distribution process. - -## SLSA in layperson's terms - -There has been a [lot of discussion](https://ntia.gov/page/software-bill-materials) about the need for "ingredient labels" for -software—a "software bill of materials" (SBOM) that tells users what is in their -software. Building off this analogy, SLSA can be thought of as all the food -safety handling guidelines that make an ingredient list credible. From standards -for clean factory environments so contaminants aren't introduced in packaging -plants, to the requirement for tamper-proof seals on lids that ensure nobody -changes the contents of items sitting on grocery store shelves, the entire food -safety framework ensures that consumers can trust that the ingredient list -matches what's actually in the package they buy. - -Likewise, the SLSA framework provides this trust with guidelines and -tamper-resistant evidence for securing each step of the software production -process. That means you know not only that nothing unexpected was added to the -software product, but also that the ingredient label itself wasn't tampered with -and accurately reflects the software contents. In this way, SLSA helps protect -against the risk of: - -- Code modification (by adding a tamper-evident "seal" to code after - source control) -- Uploaded artifacts that were not built by the expected CI/CD platform (by marking - artifacts with a factory "stamp" that shows which build platform created it) -- Threats against the build platform (by providing "manufacturing facility" - best practices for build platform services) - -For more exploration of this analogy, see the blog post -[SLSA + SBOM: Accelerating SBOM success with the help of SLSA](/blog/2022/05/slsa-sbom). - -## Who is SLSA for? - -In short: everyone involved in producing and consuming software, or providing -infrastructure for software. - -**Software producers**, such as an open source project, a software vendor, or a -team writing first-party code for use within the same company. SLSA gives you -protection against tampering along the supply chain to your consumers, both -reducing insider risk and increasing confidence that the software you produce -reaches your consumers as you intended. - -**Software consumers**, such as a development team using open source packages, a -government agency using vendored software, or a CISO judging organizational -risk. SLSA gives you a way to judge the security practices of the software you -rely on and be sure that what you receive is what you expected. - -**Infrastructure providers**, who provide infrastructure such as an ecosystem -package manager, build platform, or CI/CD platform. As the bridge between the -producers and consumers, your adoption of SLSA enables a secure software supply -chain between them. - -## How SLSA works - -We talk about SLSA in terms of [tracks and levels](tracks.md). -A SLSA track focuses on a particular aspect of a supply chain, such as the Build -Track. - -Within each track, ascending levels indicate increasingly hardened security -practices. Higher levels provide better guarantees against supply chain threats, -but come at higher implementation costs. Lower SLSA levels are designed to be -easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes -used to refer to software that doesn't yet meet any SLSA level. Currently, the -SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels -to be possible in [future revisions](future-directions.md). - -The combination of tracks and levels offers an easy way to discuss whether -software meets a specific set of requirements. By referring to an artifact as -meeting SLSA Build Level 3, for example, you're indicating in one phrase that -the software artifact was built following a set of security practices that -industry leaders agree protect against particular supply chain compromises. - -## What SLSA doesn't cover - -SLSA is only one part of a thorough approach to supply chain security. There -are several areas outside SLSA's current framework that are nevertheless -important to consider together with SLSA such as: - -- Code quality: SLSA does not tell you whether the developers writing the - source code followed secure coding practices. -- Producer trust: SLSA does not address organizations that intentionally - produce malicious software, but it can reduce insider risks within an - organization you trust. -- Transitive trust for dependencies: the SLSA level of an artifact is - independent of the level of its dependencies. You can use SLSA recursively to - also judge an artifact's dependencies on their own, but there is - currently no single SLSA level that applies to both an artifact and its - transitive dependencies together. For a more detailed explanation of why, - see the [FAQ](faq#q-why-is-slsa-not-transitive). diff --git a/docs/spec/v1.2-rc2/assessing-build-platforms.md b/docs/spec/v1.2-rc2/assessing-build-platforms.md deleted file mode 100644 index dd17f3a0b..000000000 --- a/docs/spec/v1.2-rc2/assessing-build-platforms.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: "Build: Assessing build platforms" -description: Guidelines for assessing build platform security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust platforms to produce Build L3 -artifacts and provenance unless they have some proof that the provenance is -[unforgeable](build-requirements.md#provenance-unforgeable) and the builds are -[isolated](build-requirements.md#isolated). - -This page describes the parts of a build platform that consumers SHOULD assess -and provides sample questions consumers can ask when assessing a build platform. -See also [Threats & mitigations](threats.md) and the -[build model](terminology.md#build-model). - -## Threats - -### Adversary goal - -The SLSA Build track defends against an adversary whose primary goal is to -inject unofficial behavior into a package artifact while avoiding detection. -Remember that [verifiers](verifying-artifacts.md) only accept artifacts whose -provenance matches expectations. To bypass this, the adversary tries to either -(a) tamper with a legitimate build whose provenance already matches -expectations, or (b) tamper with an illegitimate build's provenance to make it -match expectations. - -More formally, if a build with external parameters P would produce an artifact -with binary hash X and a build with external parameters P' would produce an -artifact with binary hash Y, they wish to produce provenance indicating a build -with external parameters P produced an artifact with binary hash Y. - -See threats [D], [E], [F], and [G] for examples of specific threats. - -Note: Platform abuse (e.g. running non-build workloads) and attacks against -builder availability are out of scope of this document. - -### Adversary profiles - -Consumers SHOULD also evaluate the build platform's ability to defend against the -following types of adversaries. - -1. Project contributors, who can: - - Create builds on the build platform. These are the adversary's controlled - builds. - - Modify one or more controlled builds' external parameters. - - Modify one or more controlled builds' environments and run arbitrary - code inside those environments. - - Read the target build's source repo. - - Fork the target build's source repo. - - Modify a fork of the target build's source repo and build from it. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Create new builds under the target build's project or identity. - - Modify the target build's source repo and build from it. - - Modify the target build's configuration. -3. Build platform administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Run arbitrary code on the build platform. - - Read and modify network traffic. - - Access the control plane's cryptographic secrets. - - Remotely access build environments (e.g. via SSH). - -[D]: threats.md#d-external-build-parameters -[E]: threats.md#e-build-process -[F]: threats.md#f-artifact-publication -[G]: threats.md#g-distribution-channel - -## Build platform components - -Consumers SHOULD consider at least these five elements of the -[build model](terminology.md#build-model) when assessing build platforms for SLSA -conformance: external parameters, control plane, build environments, caches, -and outputs. - -![image](images/build-model.svg) - -The following sections detail these elements of the build model and give prompts -for assessing a build platform's ability to produce SLSA Build L3 provenance. -The assessment SHOULD take into account the security model used to identify the -transitive closure of the `builder.id` for the -[provenance model](build-provenance.md#model), specifically around the -platform's boundaries, actors, and interfaces. - -### External parameters - -External parameters are the external interface to the builder and include all -inputs to the build process. Examples include the source to be built, the build -definition/script to be executed, user-provided instructions to the -control plane for how to create the build environment (e.g. which operating -system to use), and any additional user-provided strings. - -#### Prompts for assessing external parameters - -- How does the control plane process user-provided external parameters? - Examples: sanitizing, parsing, not at all -- Which external parameters are processed by the control plane and which are - processed by the build environment? -- What sort of external parameters does the control plane accept for - build environment configuration? -- How do you ensure that all external parameters are represented in the - provenance? -- How will you ensure that future design changes will not add additional - external parameters without representing them in the provenance? - -### Control plane - -The control plane is the build platform component that orchestrates each -independent build execution. It is responsible for setting up each build and -cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs -provenance for each build performed on the build platform. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -#### Prompts for assessing the control plane - -- Administration - - What are the ways an employee can use privileged access to influence a - build or provenance generation? Examples: physical access, terminal - access, access to cryptographic secrets - - What controls are in place to detect or prevent the employee from - abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many employees have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and platform - outages? Are they tested? How frequently? - -- Provenance generation - - How does the control plane observe the build to ensure the provenance's - accuracy? - - Are there situations in which the control plane will not generate - provenance for a completed build? What are they? - -- Development practices - - How do you track the control plane's software and configuration? - Example: version control - - How do you build confidence in the control plane's software supply - chain? Example: SLSA L3+ provenance, build from source - - How do you secure communications between builder components? Example: - TLS with certificate transparency. - - Are you able to perform forensic analysis on compromised build - environments? How? Example: retain base images indefinitely - -- Creating build environments - - How does the control plane share data with build environments? Example: - mounting a shared file system partition - - How does the control plane protect its integrity from build - environments? Example: not mount its own file system partitions on - build environments - - How does the control plane prevent build environments from accessing its - cryptographic secrets? Examples: dedicated secret storage, not mounting - its own file system partitions to build environments, hardware security - modules - -- Managing cryptographic secrets - - How do you store the control plane's cryptographic secrets? - - Which parts of the organization have access to the control plane's - cryptographic secrets? - - What controls are in place to detect or prevent employees abusing such - access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Build environment - -The build environment is the independent execution context where the build -takes place. In the case of a distributed build, the build environment is the -collection of all execution contexts that run build steps. Each build -environment must be isolated from the control plane and from all other build -environments, including those running builds from the same tenant or project. -Tenants are free to modify the build environment arbitrarily. Build -environments must have a means to fetch input artifacts (source, dependencies, -etc). - -#### Prompts for assessing build environments - -- Isolation technologies - - How are build environments isolated from the control plane and each - other? Examples: VMs, containers, sandboxed processes - - How is separation achieved between trusted and untrusted processes? - - How have you hardened your build environments against malicious tenants? - Examples: configuration hardening, limiting attack surface - - How frequently do you update your isolation software? - - What is your process for responding to vulnerability disclosures? What - about vulnerabilities in your dependencies? - - What prevents a malicious build from gaining persistence and influencing - subsequent builds? - -- Creation and destruction - - What operating system and utilities are available in build environments - on creation? How were these elements chosen? Examples: A minimal Linux - distribution with its package manager, OSX with HomeBrew - - How long could a compromised build environment remain active in the - build platform? - -- Network access - - Are build environments able to call out to remote execution? If so, how - do you prevent them from tampering with the control plane or other build - environments over the network? - - Are build environments able to open services on the network? If so, how - do you prevent remote interference through these services? - -### Cache - -Builders may have zero or more caches to store frequently used dependencies. -Build environments may have either read-only or read-write access to caches. - -#### Prompts for assessing caches - -- What sorts of caches are available to build environments? -- How are those caches populated? -- How are cache contents validated before use? - -### Output storage - -Output Storage holds built artifacts and their provenance. Storage may either be -shared between build projects or allocated separately per-project. - -#### Prompts for assessing output storage - -- How do you prevent builds from reading or overwriting files that belong to - another build? Example: authorization on storage -- What processing, if any, does the control plane do on output artifacts? - -## Builder evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model defined as -part of the provenance. Evidence submitted for third-party certification need not -be published. diff --git a/docs/spec/v1.2-rc2/assessing-source-systems.md b/docs/spec/v1.2-rc2/assessing-source-systems.md deleted file mode 100644 index 0ad3ecba3..000000000 --- a/docs/spec/v1.2-rc2/assessing-source-systems.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: "Source: Assessing source control systems" -description: Guidelines for assessing source control system security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust source control systems (SCSs) unless -they have some proof that an SCS meets its -[requirements](source-requirements.md). - -This page describes the parts of an SCS that consumers SHOULD assess and -provides sample questions consumers can ask when assessing a SCS. See also -[Threats & mitigations](threats.md). - -## Threats - -### Adversary goal - -The SLSA Source track defends against an adversary whose primary goal is to -inject unofficial behavior into protected source code while avoiding detection. -Organizations typically establish change management processes to prevent this -unofficial behavior from being introduced. The adversary's goal is to bypass the -change management process. - -### Adversary profiles - -Consumers SHOULD also evaluate the source control systems' ability to defend -against the following types of adversaries. - -1. Project contributors, who can: - - Propose changes to protected branches of the source repo. - - Upload new content to the source repo. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Define the purpose of the source repo. - - Add or remove contributors to the source repo. - - Add or remove permissions granted to contributors of the source repo. - - Modify security controls within the source repo. - - Modify controls used to enforce the change management process on the - source repo. -3. Source control system administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Modify the source repo while bypassing the project maintainer's controls. - - Modify the behavior of the Source Control System itself. - - Access the control plane's cryptographic secrets. - -## Source Control System components - -Consumers SHOULD consider at least these elements when assessing a Source -Control System for SLSA conformance: control configuration, change management -interface, control plane, verifier, storage. - -![source control system components](images/source-control-system-components.svg) - -The following section details these elements. - -### Change management interface - -The change management interface is the user interface for proposing and -approving changes to protected branches within a source repository. During -normal operation all such changes go through this interface. - -### Control configuration - -Control configuration is how organizations establish technical controls in a -given source repository. If done well the configuration will reflect the intent -of the organization. - -### Technical controls - -Technical controls are the organization configured settings that are used to -determine if a revision can be introduced into storage within any particular -context and who has access to those revisions. - -The technical controls component is responsible for the storage of these -settings while the [control plane](#control-plane) is responsible for enforcing -the configured controls. - -They include: - -- Read/write ACLs, -- If approvals are required to introduce changes within a given context -- Which actors are allowed to issue those approvals -- Organization defined - [change management processes](#enforced-change-management-process) - requirements -- etc... - -### Control plane - -The control plane is the SCS component that orchestrates the introduction and -creation of new revisions into a source repository. It is responsible for -enforcing [technical controls](#technical-controls) and, at SLSA Source L3+, -generating and signing source provenance for each revision. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -### Verifier - -The verifier is the SCS component that evaluates source provenance and generates -and signs a -[verification summary attestation](source-requirements#summary-attestation) -(VSA). - -### Storage - -Storage holds source revisions and their provenance and summary attestations. - -## Assessing components - -The following are prompts for assessing a Source Control System's ability to -meet the SLSA requirements. - -### Prompts for assessing the change management interface - -- How does the SCS manage which actors are permitted to approve changes? -- What types of non-plain-text changes can the change management interface - render? How well does the SCS render those changes? -- What controls does the change management interface provide for enabling - Trusted Robot Contributions? Example: SLSA Build L3+ provenance, built from - SLSA Source L4+ source. - -### Prompts for assessing control configuration & technical controls - -- How does the SCS prevent regression in control configurations? - Examples: built-in controls that cannot change, notifying project - maintainers when controls change, requiring public declaration of control - changes. -- How does the SCS prevent individual project maintainers from tampering with - controls configured by the project? -- How does the SCS prevent SCS administrators from tampering with a project's - configured technical controls? - -### Prompts for assessing the control plane & verifier - -NOTE The control plane and verifier perform related roles within the SCS and -should typically be assessed together. - -- Administration - - What are the ways an SCS administrator can use privileged access to - influence a revision creation, provenance generation, or VSA generation? - Examples: physical access, terminal access, access to cryptographic - secrets - - What controls are in place to detect or prevent an SCS administrator - from abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many SCS maintainers have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and - platform outages? Are they tested? How frequently? - -- Control effectiveness - - How does the SCS ensure the control plane is enforcing the - [technical controls](#technical-controls) are working as intended? - -- Source provenance generation - - How does the control plane observe the revision creation to ensure the - provenance's accuracy? - - Are there situations in which the control plane will not generate - source provenance? What are they? - - What details are included in the source provenance? Are they sufficient - to mitigate tampering with other SCS components? - -- VSA generation - - How does the verifier determine what source level a revision meets? - - How does the verifier determine the organization's control expectations - and if they are met? - -- Development practices - - How do you track the control plane and verifier's software and - configuration? - Example: version control. - - How do you build confidence in the control plane's software supply - chain? Example: SLSA Build L3+ provenance, built from SLSA Source L4+ - source. - - How do you secure communications between components? Example: TLS with - certificate transparency. - -- Managing cryptographic secrets - - How do you store the control plane and verifier's cryptographic secrets? - - Which parts of the organization have access to the control plane and - verifier's cryptographic secrets? - - What controls are in place to detect or prevent SCS administrators from - abusing such access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Prompts for assessing output storage - -- How do you prevent tampering with storage directly? -- How do you prevent one project's revisions from affecting another project? - -## Source control system evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model used in the -evaluation. Evidence submitted for third-party certification need not be -published. diff --git a/docs/spec/v1.2-rc2/attestation-model.md b/docs/spec/v1.2-rc2/attestation-model.md deleted file mode 100644 index 105cd9409..000000000 --- a/docs/spec/v1.2-rc2/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first-party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed-source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open-source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open-source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed-source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third-party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /build-provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.2-rc2/build-provenance.md b/docs/spec/v1.2-rc2/build-provenance.md deleted file mode 100644 index 7d03fba05..000000000 --- a/docs/spec/v1.2-rc2/build-provenance.md +++ /dev/null @@ -1,608 +0,0 @@ ---- -title: "Build: Provenance" -description: Description of SLSA build provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when, and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](requirements#provenance-generation). - -## Model - -Provenance is an attestation that a particular build platform produced a set of -software artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -> NOTE: This diagram depicts how the SLSA Provenance format is structured. It -> elaborates on the [SLSA Build Model](terminology#build-model) but only applies -> to the SLSA Provenance format specifically and not to builds in general. - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant build platform. - The `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build platforms.) - - - The build platform implementer SHOULD define a security model for the build - platform in order to clearly identify the platform's boundaries, actors, - and interfaces. This model SHOULD then be used to identify the transitive - closure of the trusted build platform for the `builder.id` as well as the - trusted control plane. - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - platform ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `internalParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](requirements.md). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." - Such changes do not update the `predicateType`. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -### Summary - -*NOTE: This summary (in cue) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -*NOTE: This summary (in protobuf) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - -Link: [provenance.proto](schema/provenance.proto) - -*NOTE: This protobuf definition prioritizes being a human-readable summary -of the schema for readers of the specification. A version of the protobuf -definition useful for code generation is maintained in the -[in-toto attestation] repository.* - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`internalParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that -there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build platform SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
internalParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build platform is already trusted, and in many cases it is -not practical to do so. - -
resolvedDependencies -array (ResourceDescriptor) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script -fetches and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be -listed here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `internalParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `internalParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build platform. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build platform to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build platform to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the build platform that executed the invocation, which is trusted to -have correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ResourceDescriptor) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or -incident response. For example, this might reference logs generated during -the build and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted build platform. This is -[intended](verifying-artifacts#step-1-check-slsa-build-level) -to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -The `builder.id` URI SHOULD resolve to documentation explaining: - -- The scope of what this ID represents. -- The claimed SLSA Build level. -- The accuracy and completeness guarantees of the fields in the provenance. -- Any fields that are generated by the tenant-controlled build process and not - verified by the trusted control plane, except for the `subject`. -- The interpretation of any extension fields. - -
builderDependencies -array (ResourceDescriptor) - -Dependencies used by the orchestrator that are not run within the workload -and that do not affect the build, but might affect the provenance generation -or security guarantees. - -
version -map (string→string) - -Map of names of components of the build platform to their version. - -
- -The build platform, or builder for short, represents the transitive -closure of all the entities that are, by necessity, [trusted] to faithfully run -the build and record the provenance. This includes not only the software but the -hardware and people involved in running the service. For example, a particular -instance of [Tekton](https://tekton.dev/) could be a build platform, while -Tekton itself is not. For more info, see [Build -model](terminology#build-model). - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -### Extension fields - -[Extension fields]: #extension-fields - -Implementations MAY add extension fields to any JSON object to describe -information that is not captured in a standard field. Guidelines: - -- Extension fields SHOULD use names of the form `_`, e.g. - `examplebuilder_isCodeReviewed`. This practice avoids field name collisions - by namespacing each vendor. Non-extension field names never contain an - underscore. -- Extension fields MUST NOT alter the meaning of any other field. In other - words, an attestation with an absent extension field MUST be interpreted - identically to an attestation with an unrecognized (and thus ignored) - extension field. -- Extension fields SHOULD follow the [monotonic principle][parsing rules], - meaning that deleting or ignoring the extension SHOULD NOT turn a DENY - decision into an ALLOW. - -## Verification - -[Verification]: verifying-artifacts - -Please see [Verifying Artifacts][Verification] for a detailed discussion of -provenance verification. - -## Index of build types - -The following is a partial index of build type definitions. Each contains a -complete example predicate. - - - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) -- [Google Cloud Build (community-maintained)](https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1) - -To add an entry here, please send a pull request on GitHub. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "internalParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "builderDependencies": null, // not in v0.2 - "version": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.2 - -- Note the difference between the *provenance* build model diagram and - the general SLSA build model diagram. - -### v1.0 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build platforms, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed: - - `parameters` -> `externalParameters` (slight change in semantics) - - `environment` -> `internalParameters` (slight change in semantics) - - `materials` -> `resolvedDependencies` (slight change in semantics) - - `buildInvocationId` -> `invocationId` - - `buildStartedOn` -> `startedOn` - - `buildFinishedOn` -> `finishedOn` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - ResourceDescriptor: `annotations`, `content`, `downloadLocation`, - `mediaType`, `name` - - Builder: `builderDependencies` and `version` - - `byproducts` -- Changed naming convention for extension fields. - -Differences from RC1 and RC2: - -- Renamed `systemParameters` (RC1 + RC2) -> `internalParameters` (final). -- Changed naming convention for extension fields (in RC2). -- Renamed `localName` (RC1) -> `name` (RC2). -- Added `annotations` and `content` (in RC2). - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: threats -[trusted]: principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.2-rc2/build-requirements.md b/docs/spec/v1.2-rc2/build-requirements.md deleted file mode 100644 index bee92afb5..000000000 --- a/docs/spec/v1.2-rc2/build-requirements.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -title: "Build: Requirements for producing artifacts" -description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers. ---- - - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is platform implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Build Track Basics](build-track-basics.md). For background, see -[Terminology](terminology.md). To better understand the reasoning behind the -requirements, see [Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -In order to produce artifacts with a specific build level, responsibility is -split between the [Producer] and [Build platform]. The build platform MUST -strengthen the security controls in order to achieve a specific level while the -producer MUST choose and adopt a build platform capable of achieving a desired -build level, implementing any controls as specified by the chosen platform. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build platform - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build platform - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Unforgeable - ✓ -
Isolation strength - Hosted - ✓✓ -
Isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure platform is beyond the -scope of this specification, all implementations MUST use industry security -best practices to be conformant to this specification. This includes, but is -not limited to, using proper access controls, securing communications, -implementing proper management of cryptographic secrets, doing frequent updates, -and promptly fixing known vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -NOTE: There were more requirements for producers in the initial -[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted -how a package can be built. These were removed in the v1.0 specification and -will be reassessed and re-added as indicated in the -[future directions](future-directions.md). - -### Choose an appropriate build platform - -The producer MUST select a build platform that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -If a producer wishes to distribute their artifact through a [package ecosystem] -that requires explicit metadata about the build process in the form of a -configuration file, the producer MUST complete the configuration file and keep -it up to date. This metadata might include information related to the artifact's -source repository and build parameters. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the -[package ecosystem], provided that the package ecosystem is capable of -distributing provenance. - -## Build Platform - -[Build platform]: #build-platform - -A package's build platform is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build platform is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build platform used -by a single software project, or even an individual's workstation. Ideally, one -build platform is used by many different software packages so that consumers can -[minimize the number of trusted platforms](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build platform is responsible for providing two things: [provenance -generation] and [isolation between builds]. The -[Build level](build-track-basics) describes the degree to which each of these -properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build platform is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the overall provenance integrity according to -minimum requirements on its: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package by cryptographic digest and describes how that package was -produced. The format MUST be acceptable to the [package ecosystem] and/or -[consumer](verifying-artifacts.md#consumer). - -It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. - -If using an alternate format, it MUST contain the equivalent information as SLSA -Provenance at each level and SHOULD be bi-directionally translatable to SLSA -Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build platform and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only -to the build platform component that generated the provenance attestation. - -While many constraints affect choice of signing methodologies, it is -RECOMMENDED that build platforms use signing methodologies which improve the -ability to detect and remediate key compromise, such as methods which rely on -transparency logs or, when transparency isn't appropriate, time stamping -services. - -Authenticity allows the consumer to trust the contents of the provenance -attestation, such as the identity of the build platform. - -*Accuracy:* The provenance MUST be generated by the control plane (i.e. within -the trust boundary [identified in the provenance]) and not by a tenant of the -build platform (i.e. outside the trust boundary), except as noted below. - -- The data in the provenance MUST be obtained from the build platform, either - because the generator *is* the build platform or because the provenance - generator reads the data directly from the build platform. -- The build platform MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. -- Exceptions for fields that MAY be generated by a tenant of the build platform: - - The names and cryptographic digests of the output artifacts, i.e. - `subject` in [SLSA Provenance]. See [forge output digest of the - provenance](threats#forged-digest) for explanation of why this is - acceptable. - - Any field that is not marked as REQUIRED for Build L2. For example, - `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at - Build L2. Builders SHOULD document any such cases of tenant-generated - fields. - -*Completeness:* SHOULD be complete. - -- There MAY be [external parameters] that are not sufficiently captured in - the provenance. -- Completeness of resolved dependencies is best effort. - - ✓✓ -
Provenance is Unforgeable - -*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. - -- Any secret material used for authenticating the provenance, for example the - signing key used to generate a digital signature, MUST be stored in a secure - management system appropriate for such material and accessible only to the - build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - platform in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted in [Provenance - is Authentic](#provenance-authentic). (Build L3 does not require additional - fields beyond those of L2.) - -*Completeness:* SHOULD be complete. - -- [External parameters] MUST be fully enumerated. -- Completeness of resolved dependencies is best effort. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build platform is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build platform's isolation strength, see -[Assessing build platforms](assessing-build-platforms.md). - - - - -
RequirementDescriptionL1L2L3 - -
Hosted - - -All build steps ran using a hosted build platform on shared or dedicated -infrastructure, not on an individual's workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Isolated - - -The build platform ensured that the build steps ran in an isolated environment, -free of unintended external influence. In other words, any external influence on -the build was specifically requested by the build itself. This MUST hold true -even between builds within the same tenant project. - -The build platform MUST guarantee the following: - -- It MUST NOT be possible for a build to access any secrets of the build - platform, such as the provenance signing key, because doing so would - compromise the authenticity of the provenance. -- It MUST NOT be possible for two builds that overlap in time to influence one - another, such as by altering the memory of a different build process running - on the same machine. -- It MUST NOT be possible for one build to persist or influence the build - environment of a subsequent build. In other words, an ephemeral build - environment MUST be provisioned for each build. -- It MUST NOT be possible for one build to inject false entries into a build - cache used by another build, also known as "cache poisoning". In other - words, the output of the build MUST be identical whether or not the cache is - used. -- The build platform MUST NOT open services that allow for remote influence - unless all such interactions are captured as `externalParameters` in the - provenance. - -There are no sub-requirements on the build itself. Build L3 is limited to -ensuring that a well-intentioned build runs securely. It does not require that -a build platform prevents a producer from performing a risky or insecure build. In -particular, the "Isolated" requirement does not prohibit a build from calling -out to a remote execution service or a "self-hosted runner" that is outside the -trust boundary of the build platform. - -NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" -in the initial [draft version (v0.1)](../v0.1/requirements.md). - -NOTE: This requirement is not to be confused with "Hermetic", which roughly -means that the build ran with no network access. Such a requirement requires -substantial changes to both the build platform and each individual build, and is -considered in the [future directions](future-directions.md). - - ✓ -
- -[external parameters]: provenance.md#externalParameters -[identified in the provenance]: provenance.md#model -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.2-rc2/build-track-basics.md b/docs/spec/v1.2-rc2/build-track-basics.md deleted file mode 100644 index eccbc36b6..000000000 --- a/docs/spec/v1.2-rc2/build-track-basics.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: "Build: Track Basics" -description: The SLSA build track is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This page is a descriptive overview of the SLSA build track levels, describing their intent. ---- - -| 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 - - - -> 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 -> Build track. In 1.2 the [Source Track](tracks#source-track) reintroduces -> coverage of source code. - -
- -## Build L0: No guarantees - -
-
Summary
- -No requirements---L0 represents the lack of SLSA. - -
Intended for
- -Development or test builds of software that are built and run on the same -machine, such as unit tests. - -
Requirements
- -n/a - -
Benefits
- -n/a - -
-
-
- -## Build L1: Provenance exists - -
-
Summary
- -Package has provenance showing how it was built. Can be used to prevent mistakes -but is trivial to bypass or forge. - -
Intended for
- -Projects and organizations wanting to easily and quickly gain some benefits of -SLSA---other than tamper protection---without changing their build workflows. - -
Requirements
- -- Software Producer: - - Follow a consistent build process so that others can form - expectations about what a "correct" build looks like. - - Run builds on a build platform that meets Build L1 requirements. - - Distribute provenance to consumers, preferably using a convention - determined by the package ecosystem. -- Build platform: - - Automatically generate [provenance] describing how the artifact was - built, including: what entity built the package, what build process - they used, and what the top-level input to the build were. - -
Benefits
- -- Makes it easier for both producers and consumers to debug, patch, rebuild, - and/or analyze the software by knowing its precise source version and build - process. - -- With [verification], prevents mistakes during the release process, such as - building from a commit that is not present in the upstream repo. - -- Aids organizations in creating an inventory of software and build platforms - used across a variety of teams. - -
Notes
- -- Provenance may be incomplete and/or unsigned at L1. Higher levels require - more complete and trustworthy provenance. - -
- -
-
- -## Build L2: Hosted build platform - -
-
Summary
- -Forging the provenance or evading verification requires an explicit "attack", -though this may be easy to perform. Deters unsophisticated adversaries or those -who face legal or financial risk. - -In practice, this means that builds run on a hosted platform that generates and -signs[^sign] the provenance. - -
Intended for
- -Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build platform, while waiting for changes to the build -platform itself required by [Build L3]. - -
Requirements
- -All of [Build L1], plus: - -- Software producer: - - Run builds on a [hosted] build platform that meets Build L2 - requirements. -- Build platform: - - Generate and sign[^sign] the provenance itself. This may be done - during the original build, an after-the-fact reproducible build, or - some equivalent system that ensures the trustworthiness of the - provenance. -- Consumer: - - Validate the authenticity of the provenance. - -
Benefits
- -All of [Build L1], plus: - -- Prevents tampering after the build through digital signatures[^sign]. - -- Deters adversaries who face legal or financial risk by evading security - controls, such as employees who face risk of getting fired. - -- Reduces attack surface by limiting builds to specific build platforms that - can be audited and hardened. - -- Allows large-scale migration of teams to supported build platforms early - while further hardening work ([Build L3]) is done in parallel. - -
-
-
- -[^sign]: Alternate means of verifying the authenticity of the provenance are - also acceptable. - -## Build L3: Hardened builds - -
-
Summary
- -Forging the provenance or evading verification requires exploiting a -vulnerability that is beyond the capabilities of most adversaries. - -In practice, this means that builds run on a hardened build platform that offers -strong tamper protection. - -
Intended for
- -Most software releases. Build L3 usually requires significant changes to -existing build platforms. - -
Requirements
- -All of [Build L2], plus: - -- Software producer: - - Run builds on a hosted build platform that meets Build L3 - requirements. -- Build platform: - - Implement strong controls to: - - prevent runs from influencing one another, even within the same - project. - - prevent secret material used to sign the provenance from being - accessible to the user-defined build steps. - -
Benefits
- -All of [Build L2], plus: - -- Prevents tampering during the build---by insider threats, compromised - credentials, or other tenants. - -- Greatly reduces the impact of compromised package upload credentials by - requiring the attacker to perform a difficult exploit of the build process. - -- Provides strong confidence that the package was built from the official - source and build process. - -
-
- - - -[build l0]: #build-l0 -[build l1]: #build-l1 -[build l2]: #build-l2 -[build l3]: #build-l3 -[future versions]: future-directions.md -[hosted]: build-requirements.md#isolation-strength -[previous version]: ../v0.1/levels.md -[provenance]: terminology.md -[verification]: verifying-artifacts.md diff --git a/docs/spec/v1.2-rc2/distributing-provenance.md b/docs/spec/v1.2-rc2/distributing-provenance.md deleted file mode 100644 index ffb6a3d86..000000000 --- a/docs/spec/v1.2-rc2/distributing-provenance.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: "Build: Distributing provenance" -description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is platform implementers and software distributors. ---- - -In order to make provenance for artifacts available after generation -for verification, SLSA requires the distribution and verification of provenance -metadata in the form of SLSA attestations. - -This document provides specifications for distributing provenance and the -relationship between build artifacts and provenance (build attestations). It is -primarily concerned with artifacts for ecosystems that distribute build -artifacts, but some attention is also paid to ecosystems that distribute -container images or only distribute source artifacts, as many of the same -principles generally apply to any artifact or group of artifacts. - -In addition, this document is primarily for the benefit of artifact -distributors, to understand how they can adopt the distribution of SLSA -provenance. It is primarily concerned with the means of distributing -attestations and the relationship of attestations to build artifacts, and not -with the specific format of the attestation itself. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Background - -The [package ecosystem]'s maintainers are responsible for reliably -redistributing artifacts and provenance, making the producers' expectations -available to consumers, and providing tools to enable safe artifact consumption -(e.g., whether an artifact meets its producer's expectations). - -## Relationship between releases and attestations - -Attestations SHOULD be bound to artifacts, not releases. - -A single "release" of a project, package, or library might include multiple -artifacts. These artifacts result from builds on different platforms, -architectures, or environments. The builds need not happen at roughly the same -point in time and might even span multiple days. - -It is often difficult or impossible to determine when a release is 'finished' -because many ecosystems allow adding new artifacts to old releases when adding -support for new platforms or architectures. Therefore, the set of attestations -for a given release MAY grow over time as additional builds and attestations -are created. - -Thus, package ecosystems SHOULD support multiple individual attestations per -release. At the time of a given build, the relevant provenance for that build -can be added to the release, depending on the relationship to the given -artifacts. - -## Relationship between artifacts and attestations - -Package ecosystems SHOULD support a one-to-many relationship from build -artifacts to attestations to ensure that anyone is free to produce and publish -any attestation they might need. However, while there are lots of possible -attestations that can have a relationship to a given artifact, in this context -SLSA is primarily concerned with build attestations, i.e., provenance, and as -such, this specification only considers build attestations, produced by the -same maintainers as the artifacts themselves. - -By providing provenance alongside an artifact in the manner specified by a -given ecosystem, maintainers are considered to be 'elevating' these build -attestations above all other possible attestations that could be provided by -third parties for a given artifact. The ultimate goal is for maintainers to -provide the provenance necessary for a repository to be able to verify some -potential policy that requires a certain SLSA level for publication, not -support the publication of arbitrary attestations by third parties. - -As a result, this provenance SHOULD accompany the artifact at publish time, and -package ecosystems SHOULD provide a way to map a given artifact to its -corresponding attestations. The mappings can be either implicit (e.g., require a -custom filename schema that uniquely identifies the provenance over other -attestation types) or explicit (e.g., it could happen as a de-facto standard -based on where the attestation is published). - -The provenance SHOULD have a filename that is directly related to the build -artifact filename. For example, for an artifact `.`, the -attestation is `.attestation` or some similar extension (for example -[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`). - -## Where attestations are published - -There are a number of opportunities and venues to publish attestations during -and after the build process. Producers MUST publish attestations in at least -one place, and SHOULD publish attestations in more than one place: - -- **Publish attestations alongside the source repository releases**: If the - source repository hosting provider offers an artifact "release" feature, - such as [GitHub - releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), - producers SHOULD include provenance as part of such releases. This option - has the benefit of requiring no changes to the package registry to support - provenance formats, but has the disadvantage of putting the source - repository hosting provider in the critical path for installers that want to - verify policy at build-time. -- **Publish attestations alongside the artifact in the package registry**: - Many software repositories already support some variety of publishing 1:1 - related files alongside an artifact, sometimes known as “sidecar files”. - For example, PyPI supports publishing `.asc` files representing the PGP - signature for an artifact with the same filename (but different extension). - This option requires the mapping between artifact and attestation (or - attestation vessel) to be 1:1. -- **Publish attestations elsewhere, record their existence in a transparency - log**: Once an attestation has been generated and published for a build, a - hash of the attestation and a pointer to where it is indexed SHOULD be - published to a third-party transparency log that exists outside the source - repository and package registry. Not only are transparency logs such as - [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed - to be immutable, but they typically also make monitoring easier. - Requiring the presence of the attestation in a monitored transparency log - during verification helps ensure the attestation is trustworthy. - -Combining these options gives us a process for bootstrapping SLSA adoption -within an ecosystem, even if the package registry doesn't support publishing -attestations. First, interested projects modify their release process to -produce SLSA provenance. Then, they publish that provenance to their source -repository. Finally, they publish the provenance to the package registry, if -and when the registry supports it. - -Long-term, package registries SHOULD support uploading and distributing -provenance alongside the artifact. This model is preferred for two reasons: - -- trust: clients already trust the package registry as the source of their - artifacts, and don't need to trust an additional service; -- reliability: clients already depend on the package registry as part of - their critical path, so distributing provenance via the registry avoids - adding an additional point of failure. - -Short term, consumers of build artifacts can bootstrap a manual policy by using -the source repository only for projects that publish all artifacts and -attestations to the source repository, and later extend this to all artifacts -published to the package registry via the canonical installation tools once -a given ecosystem supports them. - -## Immutability of attestations - -Attestations SHOULD be immutable. Once an attestation is published as it -corresponds to a given artifact, that attestation is immutable and cannot be -overwritten later with a different attestation that refers to the same -artifact. Instead, a new release (and new artifacts) SHOULD be created. - -## Format of the attestation - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto -[SLSA Build Provenance](/build-provenance), but another format MAY be used if -both producer and consumer agree and it meets all the other requirements. - -## Considerations for source-based ecosystems - -Some ecosystems have support for installing directly from source repositories -(an option for Python/`pip`, Go, etc.). In these cases, there is no need to -publish or verify provenance because there is no "build" step that translates -between a source repository and an artifact that is being installed. - -However, for ecosystems that install from source repositories _via_ some -intermediary (e.g., [Homebrew installing from GitHub release artifacts generated -from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go -installing through the Go module proxy](https://proxy.golang.org/)), these -ecosystems distribute "source archives" that are not the bit-for-bit identical -form from version control. These intermediaries are transforming the original -source repository in some way that constitutes a "build" and as a result SHOULD -be providing build provenance for this "package", and the recommendations -outlined here apply. - -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.2-rc2/faq.md b/docs/spec/v1.2-rc2/faq.md deleted file mode 100644 index 0590bd77e..000000000 --- a/docs/spec/v1.2-rc2/faq.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Frequently asked questions -description: Answers to questions frequently asked about SLSA. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build platforms to -corroborate the provenance of a build. In this way, one can create an overall -platform that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a platform can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. - -## Q. What is the difference between a build platform, system, and service? - -Build platform and build system have been used interchangeably in the past. With -the v1.0 specification, however, there has been a unification around the term -platform as indicated in the [Terminology](terminology.md). The use of the word -`system` still exists related to software and services within the build platform -and to systems outside of a build platform like change management systems. - -A build service is a hosted build platform that is often run on shared infrastructure -instead of individuals' machines and workstations. Its use has also been replaced outside -of the requirements as it relates to the build platform. - -## Q: Is SLSA the same as TACOS? - -No. -[Trusted Attestation and Compliance for Open Source (TACOS)](https://github.com/tacosframework) -is a framework authored by Tidelift. -Per their website, TACOS is a framework -"for assessing the development practices of open source projects -against a set of secure development standards specified by the (US) -NIST Secure Software Development Framework (SSDF) V1.1" which -"vendors can use to provide self-attestation for the open source components -they rely on." - -In contrast, SLSA is a community-developed framework---including -adoptable guidelines for securing a software supply chain and -mechanism to evaluate the trustworthiness of artifacts you consume---that -is part of the Open Source Security Foundation (OpenSSF). - -## Q: How does SLSA and SLSA Provenance relate to SBOM? - -[Software Bill of Materials (SBOM)] are a frequently recommended tool for -increased software supply chain rigor. An SBOM is typically focused on -understanding software in order to evaluate risk through known vulnerabilities -and license compliance. These use-cases require fine-grained and timely data -which can be refined to improve signal-to-noise ratio. - -[SLSA Provenance] and the [Build track] are focused on trustworthiness of the -build process. To improve trustworthiness, Provenance is generated in the build -platform's trusted control plane, which in practice results in it being coarse -grained. For example, in Provenance metadata completeness of -`resolvedDependencies` information is on a best-effort basis. Further, the -`ResourceDescriptor` type does not require version and license information or -even a URI to the dependency's original location. - -While they likely include similar data, SBOMs and SLSA Provenance operate at -different levels of abstraction. The fine-grained data in an SBOM typically -describes the components present in a produced artifact, whereas SLSA -Provenance more coarsely describes parameters of a build which are external to -the build platform. - -The granularity and expressiveness of the two use-cases differs enough that -current SBOM formats were deemed not a good fit for the requirements of -the Build track. Yet SBOMs are a good practice and may form part of a future -SLSA Vulnerabilities track. Further, SLSA Provenance can increase the -trustworthiness of an SBOM by describing how the SBOM was created. - -SLSA Provenance, the wider [in-toto Attestation Framework] in which the -recommended format sits, and the various SBOM standards, are all rapidly -evolving spaces. There is ongoing investigation into linking between the -different formats and exploration of alignment on common models. This FAQ entry -describes our understanding of the intersection efforts today. We do not know -how things will evolve over the coming months and years, but we look forward to -the collaboration and improved software supply chain security. - -## Q: How to SLSA with a self-hosted runner - -Some CI systems allow producers to provide their own self-hosted runners as a build -environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage -these, classifying the SLSA build level for the resulting artifact can be confusing. - -Since the SLSA Build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance, interpretation of the -specification hinges on the platform entities involved in the provenance generation. -The SLSA [build level requirements] (secure key storage, isolation, etc.) should be -imposed on the transitive closure of the systems which are responsible for informing -the provenance generated. - -Some common situations may include: - -- The platform generates the provenance and just calls a runner for individual items. - In this situation, the provenance is only affected by the platform so there would be - no requirements imposed on the runner. -- The runner generates the provenance. In this situation, the orchestrating platform - is irrelevant and all requirements are imposed on the runner. -- The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance. Trust is - shared between the platform and the runner so the requirements are imposed on both. - -Additional requirements on the self-hosted runners may be added to Build levels -greater than L3 when such levels get defined. - -[build level requirements]: build-requirements.md -[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners -[Software Bill of Materials (SBOM)]: https://ntia.gov/sbom -[SLSA Provenance]: provenance.md -[Build track]: build-track-basics.md -[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/ diff --git a/docs/spec/v1.2-rc2/future-directions.md b/docs/spec/v1.2-rc2/future-directions.md deleted file mode 100644 index a9401758a..000000000 --- a/docs/spec/v1.2-rc2/future-directions.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Future directions -description: The initial draft version (v0.1) of SLSA had a larger scope including protections against tampering with source code and a higher level of build integrity (Build L4). This page collects some early thoughts on how SLSA **might** evolve in future versions to re-introduce these notions and add other additional aspects of automatable supply chain security. ---- - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future versions to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build platform and enabling -corroboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream verifiers - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other build platforms to corroborate the - provenance. - -
- -
- -## Platform Operations track - -A Platform Operations track could provide assurances around the hardening of -platforms (e.g. build or source platforms) as they are operated. - -The initial [draft version (v0.1)] of SLSA included a section on -[common requirements](../v0.1/requirements.md#common-requirements) that formed -the foundation of the guidance for -[assessing build platforms](assessing-build-platforms.md), which **may or may not** form -the basis for a future Build Platform Operations track: - -- Controls for approval, logging, and auditing of all physical and remote - access to platform infrastructure, cryptographic secrets, and privileged - debugging interfaces. -- Conformance to security best practices to minimize the risk of compromise. -- Protection of cryptographic secrets used by the build platform. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md diff --git a/docs/spec/v1.2-rc2/images/build-env-model.svg b/docs/spec/v1.2-rc2/images/build-env-model.svg deleted file mode 100755 index ad3f8dba6..000000000 --- a/docs/spec/v1.2-rc2/images/build-env-model.svg +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2-rc2/images/build-model.svg b/docs/spec/v1.2-rc2/images/build-model.svg deleted file mode 100644 index 9d6bed6ca..000000000 --- a/docs/spec/v1.2-rc2/images/build-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2-rc2/images/provenance-model.svg b/docs/spec/v1.2-rc2/images/provenance-model.svg deleted file mode 100644 index 028dad49e..000000000 --- a/docs/spec/v1.2-rc2/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2-rc2/images/source-control-system-components.svg b/docs/spec/v1.2-rc2/images/source-control-system-components.svg deleted file mode 100644 index d0e9dded3..000000000 --- a/docs/spec/v1.2-rc2/images/source-control-system-components.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2-rc2/images/supply-chain-model.svg b/docs/spec/v1.2-rc2/images/supply-chain-model.svg deleted file mode 100644 index 6a37ffa05..000000000 --- a/docs/spec/v1.2-rc2/images/supply-chain-model.svg +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2-rc2/images/supply-chain-threats-build-verification.svg b/docs/spec/v1.2-rc2/images/supply-chain-threats-build-verification.svg deleted file mode 100644 index 2888f6215..000000000 --- a/docs/spec/v1.2-rc2/images/supply-chain-threats-build-verification.svg +++ /dev/null @@ -1,88 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2-rc2/images/supply-chain-threats.svg b/docs/spec/v1.2-rc2/images/supply-chain-threats.svg deleted file mode 100644 index 38421111d..000000000 --- a/docs/spec/v1.2-rc2/images/supply-chain-threats.svg +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2-rc2/images/verification-model.svg b/docs/spec/v1.2-rc2/images/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.2-rc2/images/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2-rc2/index.md b/docs/spec/v1.2-rc2/index.md deleted file mode 100644 index 358081238..000000000 --- a/docs/spec/v1.2-rc2/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: SLSA specification -description: SLSA is a specification for describing and incrementally improving supply chain security, established by industry consensus. It is organized into a series of levels that describe increasing security guarantees. ---- - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **Version 1.2 Release Candidate 2 (RC2)** of the SLSA -specification, which defines several SLSA levels and recommended attestation -formats, including provenance. - -{%- for section in site.data.nav.main %} -{%- if section.url == page.url %} -{%- for subsection in section.children %} -{%- if subsection.children %} - -## {{ subsection.title }} - -{{ subsection.description }} - - - -| Page | Description -| ---- | ----------- -{%- for child in subsection.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} -{%- endfor %} - - -{%- endif %} -{%- endfor %} -{%- endif %} -{%- endfor %} diff --git a/docs/spec/v1.2-rc2/onepage.md b/docs/spec/v1.2-rc2/onepage.md deleted file mode 100644 index 3f9209975..000000000 --- a/docs/spec/v1.2-rc2/onepage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SLSA Specification -description: A one-page rendering of all that is included in the SLSA Working Draft. -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.2-rc2/" %} -{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,tracks,build-track-basics,terminology,build-requirements,distributing-provenance,verifying-artifacts,assessing-build-platforms,source-requirements,verifying-source,assessing-source-systems,source-example-controls,threats,attestation-model,provenance,build-provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.2-rc2/principles.md b/docs/spec/v1.2-rc2/principles.md deleted file mode 100644 index 535c75a7f..000000000 --- a/docs/spec/v1.2-rc2/principles.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Guiding principles -description: An introduction to the guiding principles behind SLSA's design decisions. ---- - -This page is an introduction to the guiding principles behind SLSA's design -decisions. - -## Simple levels with clear outcomes - -Use [levels](about#how-slsa-works) to communicate security state and to -encourage a large population to improve its security stance over time. When -necessary, split levels into separate tracks to recognize progress in unrelated -security areas. - -**Reasoning:** Levels simplify how to think about security by boiling a complex -topic into an easy-to-understand number. It is clear that level N is better than -level N-1, even to someone with passing familiarity. This provides a convenient -way to describe the current security state as well as a natural path to improvement. - -Guidelines: - -- **Define levels in terms of concrete security outcomes.** Each level should - have clear and meaningful security value, such as stopping a particular - class of threats. Levels should represent security milestones, not just - incremental progress. Give each level an easy-to-remember mnemonic, such as - "Provenance exists." - -- **Balance level granularity.** Too many levels makes SLSA hard to understand - and remember; too few makes each level hard to achieve. Collapse levels - until each step requires a non-trivial but manageable amount of work to - implement. Separate levels if they require significant work from multiple - distinct parties, such as infrastructure work plus user behavior changes, so - long as the intermediate level still has some security value (prior bullet). - -- **Use tracks sparingly.** Additional tracks add extra complexity to SLSA, so - a new track should be seen as a last resort. Each track should have a clear, - distinct purpose with a crisply defined objective, such as trustworthy - provenance for the [Build track](levels#build-track). As a rule of thumb, a - new track may be warranted if it addresses threats unrelated to another - track. Try to avoid tracks that sound confusingly similar in either name or - objective. - -## Trust platforms, verify artifacts - -Establish trust in a small number of platforms and systems---such as change management, build, -and packaging platforms---and then automatically verify the many artifacts -produced by those platforms. - -**Reasoning**: Trusted computing bases are unavoidable---there's no choice but -to trust some platforms. Hardening and verifying platforms is difficult and -expensive manual work, and each trusted platform expands the attack surface of the -supply chain. Verifying that an artifact is produced by a trusted platform, -though, is easy to automate. - -To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited -number of platforms and then automate verification of the artifacts produced by those platforms. -The attack surface and work to establish trust do not scale with the number of artifacts produced, -as happens when artifacts each use a different trusted platform. - -**Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant -amount of central work. - -### Example - -A security engineer analyzes the architecture and implementation of a build -platform to ensure that it meets the SLSA Build Track requirements. Following the -analysis, the public keys used by the build platform to sign provenance are -"trusted" up to the given SLSA level. Downstream platforms verify the provenance -signed by the public key to automatically determine that an artifact meets the -SLSA level. - -### Corollary: Minimize the number of trusted platforms - -A corollary to this principle is to minimize the size of the trusted computing -base. Every platform we trust adds attack surface and increases the need for -manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team within an organization maintaining their own build platform, use a - shared build platform. Hardening work can be shared across all teams. -- Remove the need to trust components. For example, use end-to-end signing - to avoid the need to trust intermediate distribution platforms. - -## Trust code, not individuals - -Securely trace all software back to source code rather than trust individuals who have write access to package registries. - -**Reasoning**: Code is static and analyzable. Individuals, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. - -**Benefits**: Removes the possibility for a trusted individual---or an -attacker abusing compromised credentials---to tamper with source code -after it has been committed. - -## Prefer attestations over inferences - -Require explicit attestations about an artifact's provenance; do not infer -security properties from a platform's configurations. - -**Reasoning**: Theoretically, access control can be configured so that the only path from -source to release is through the official channels: the CI/CD platform pulls only -from the proper source, package registry allows access only to the CI/CD platform, -and so on. We might infer that we can trust artifacts produced by these platforms -based on the platform's configuration. - -In practice, though, these configurations are almost impossible to get right and -keep right. There are often over-provisioning, confused deputy problems, or -mistakes. Even if a platform is configured properly at one moment, it might not -stay that way, and humans almost always end up getting in the access control -lists. - -Access control is still important, but SLSA goes further to provide defense in depth: it **requires proof in -the form of attestations that the package was built correctly**. - -**Benefits**: The attestation removes intermediate platforms from the trust base and ensures that -individuals who are accidentally granted access do not have sufficient permission to tamper with the package. - -## Support anonymous and pseudonymous contributions - -SLSA supports anonymous and pseudonymous 'identities' within the software supply chain. -While organizations that implement SLSA may choose otherwise, SLSA itself does not require, -or encourage, participants to be mapped to their legal identities. - -**Nothing in this specification should be taken to mean that SLSA requires participants to -reveal their legal identity.** - -**Reasoning**: SLSA uses identities for multiple purposes: as a trust anchor for attestations -(i.e. who or what is making this claim and do I trust it to do so) or for attributing actions -to an actor. Choice of identification technology is left to the organization and technical -stacks implementing the SLSA standards. - -When identities are strongly authenticated and used consistently they can often be leveraged -for both of these purposes without requiring them to be mapped to legal identities. -This reflects how identities are often used in open source where legal name means much less -to projects than the history and behavior of a given handle over time does. Meanwhile, some -organizations may choose to levy additional requirements on identities. They are free to do -so, but SLSA itself does not require it. - -**Benefits**: By _not_ requiring legal identities SLSA lowers the barriers to its adoption, -enabling all of its other benefits and maintaining support for anonymous and pseudonymous -contribution as has been practiced in the software industry for decades. diff --git a/docs/spec/v1.2-rc2/provenance.md b/docs/spec/v1.2-rc2/provenance.md deleted file mode 100644 index 769ed89d0..000000000 --- a/docs/spec/v1.2-rc2/provenance.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Provenance -description: Provides a description of the concept of provenance and links to the various tracks specific definitions. ---- - -In SLSA 'provenance' refers to verifiable information that can be used to track -an artifact back, through all the moving parts in a complex supply chain, to -where it came from. It’s the verifiable information about software artifacts -describing where, when, and how something was produced. - -The different SLSA tracks may have their own, more specific, implementations of -provenance to account for their unique needs. - -NOTE: If you landed here via the -[in-toto attestation](https://github.com/in-toto/attestation) predicate type -`https://slsa.dev/provenance/v1` please see -[Build provenance](build-provenance.md). - -- [Build provenance](build-provenance.md) - tracks the output of a build process - back to the source code used to produce that output. -- [Source provenance](source-requirements#source-provenance-attestations) - tracks the - creation of source code revisions and the change management processes - that were in place during their creation. diff --git a/docs/spec/v1.2-rc2/requirements.md b/docs/spec/v1.2-rc2/requirements.md deleted file mode 100644 index 825e9b22a..000000000 --- a/docs/spec/v1.2-rc2/requirements.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Requirements -description: This page links to the requirements pages of the individual tracks. ---- - -SLSA is composed of [multiple tracks](about#how-slsa-works). Each track has its -own set of requirements. Follow the links below to find the requirements for -each track. - -- [Build Track Requirements](build-requirements.md) -- [Source Track Requirements](source-requirements.md) diff --git a/docs/spec/v1.2-rc2/schema/provenance.cue b/docs/spec/v1.2-rc2/schema/provenance.cue deleted file mode 100644 index 22bc5e0d8..000000000 --- a/docs/spec/v1.2-rc2/schema/provenance.cue +++ /dev/null @@ -1,48 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "internalParameters": object, - "resolvedDependencies": [ ...#ResourceDescriptor ], - }, - "runDetails": { - "builder": { - "id": string, - "builderDependencies": [ ...#ResourceDescriptor ], - "version": { ...string }, - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ResourceDescriptor ], - } - } -} - -#ResourceDescriptor: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "gitCommit": string, - [string]: string, - }, - "name": string, - "downloadLocation": string, - "mediaType": string, - "content": bytes, // base64-encoded - "annotations": { - [string]: _ // any JSON type - } -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.2-rc2/schema/provenance.proto b/docs/spec/v1.2-rc2/schema/provenance.proto deleted file mode 100644 index ae0a71ee1..000000000 --- a/docs/spec/v1.2-rc2/schema/provenance.proto +++ /dev/null @@ -1,50 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct internal_parameters = 3; - repeated ResourceDescriptor resolved_dependencies = 4; -} - -message ResourceDescriptor { - string uri = 1; - map digest = 2; - string name = 3; - string download_location = 4; - string media_type = 5; - bytes content = 6; - map annotations = 7; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ResourceDescriptor byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ResourceDescriptor builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.2-rc2/source-example-controls.md b/docs/spec/v1.2-rc2/source-example-controls.md deleted file mode 100644 index 4da1044d4..000000000 --- a/docs/spec/v1.2-rc2/source-example-controls.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -title: "Source: Example controls" -description: "This page provides examples of additional controls that - organizations may want to implement as they adopt the SLSA Source track." ---- - -At SLSA Source L3+ organizations are allowed and encouraged to define their own -controls that go over and above specific requirements outlined by SLSA. This -page provides some examples of what these additional controls could be. - -If an organization has indicated that use of these controls is part of -their repository's expectations, consumers SHOULD be able to verify that the -process was followed for the revision they are consuming by examining the -[summary](./source-requirements#source-verification-summary-attestation) or -[source provenance](./source-requirements#source-provenance-attestations) -attestations. - -> For example: consumers can look for the related `ORG_SOURCE` properties in -> the `verifiedLevels` field of the [summary -> attestation](./source-requirements#source-verification-summary-attestation). - -## Expert Code Review - -
-
Summary
- -All changes to the source are pre-approved by experts. - -
Intended for
- -Enterprise repositories and mature open source projects. - -
Benefits
- -Prevents mistakes by developers unfamiliar with the area. - -
- -### Requirements - -- **Code ownership** - - Each part of the source MUST have a clearly identified set of experts. - -- **Approvals from all relevant experts** - - For each portion of the source modified by a change proposal, pre-approval - MUST be granted by a member of the defined expert set. An approval from an - actor that is a member of multiple expert groups may satisfy the - requirement for all groups in which they are a member. - -## Review Every Single Revision - -
-
Summary
- -The final revision was reviewed by experts prior to submission. - -
Intended for
- -The highest-of-high-security-posture repos. - -
Benefits
- -Provides maximum chance for experts to spot problems. - -
- -### Requirements - -- **Reset votes on all changes** - - If the proposal is modified after receiving expert approval, all previously - granted approvals MUST be revoked. A new approval MUST be granted from ALL - required reviewers. - - The new approval MAY be granted by an actor who approved a previous - iteration. - -## Automated testing - -
-
Summary
- -The final revision was validated by automated tests. - -
Intended for
- -All organizations and repositories. - -
Benefits
- -Improves accuracy, prevents errors, and reduces human load. - -
- -### Requirements - -The organization MUST configure a branch protection rule to require that only -revisions with passing test results can be pointed-to by the branch. - -Automatic tests SHOULD be executed in a trustworthy environment (see SLSA -build track). - -Results of each test (or an aggregate) MUST be collected by the change review -tool and made available for verification. - -Tests SHOULD be run against a revision created for testing by merging the topic -branch (containing the proposed changes) into the target branch. - -Use of the proposed merge commit should be preferred to using the tip of the -topic branch. - -## Every revision reachable from a branch was approved - -
-
Summary
- -New revisions are created based ONLY on approved changes. - -
Intended for
- -All organizations and repositories. - -
Benefits
- -Prevents attacks that hide malicious, unreviewed commits. - -
- -### Context - -In many organizations, it is normal to review only the "net difference" -between the tip of the topic branch and the "best merge base", the closest -shared commit between the topic and target branches computed at the time of -review. - -The topic branch may contain many commits of which not all were intended to -represent a shippable state of the repository. - -If a repository merges branches with a standard merge commit, all those -unreviewed commits on the topic branch will become "reachable" from the -protected branch by virtue of the multi-parent merge commit. - -When a repo is cloned, all commits _reachable_ from the main branch are -fetched and become accessible from the local checkout. - -This combination of factors allows attacks where the victim performs a `git -clone` operation followed by a `git reset --hard `. - -### Requirements - -- **Informed Review** - - The reviewer is able and encouraged to make an informed decision about - what they're approving. The reviewer MUST be presented with a full, - meaningful content diff between the proposed revision and the - previously reviewed revision. - - It is not sufficient to indicate that a file changed without showing - the contents. - -- **Use only rebase operations on the protected branch** - - Require a squash merge strategy for the protected branch. - - To guarantee that only commits representing reviewed diffs are cloned, - the SCS MUST rebase (or "squash") the reviewed diff into a single new - commit (the "squashed" commit) that has only a single parent (the - revision previously pointed-to by the protected branch). This is - different than a standard merge commit strategy which would cause all - the user-contributed commits to become reachable from the protected - branch via the second parent. - - It is not acceptable to replay the sequence of commits from the topic - branch onto the protected branch. The intent is to reduce the accepted - changes to the exact diffs that were reviewed. Constituent commits of - the topic branch may or may not have been reviewed on an individual - basis, and should not become reachable from the protected branch. - -## Immutable Change Discussion - -
-
Summary
- -The discussion around a change is preserved and immutable. - -
Intended for
- -Large orgs, or where discussion is vital to change management. - -
Benefits
- -Enables future education, forensics, and security auditing. - -
- -### Requirements - -The SCS SHOULD record a description of the proposed change and all discussions -/ commentary related to it. - -The SCS MUST link this discussion to the revision itself. This is regularly -done via commit metadata. - -All collected content SHOULD be made immutable if the change is accepted. It -SHOULD NOT be possible to edit the discussion around a revision after it has -been accepted. - -## Merge trains - -
-
Summary
- -A buffer branch (or "train") collects a certain number of approved changes -before merging into the protected branch. - -
Intended for
- -Large organizations with high-velocity repositories where the protected branch -needs to remain stable for longer periods. - -
Benefits
- -Allows more time for human and automatic code review by stabilizing the -protected branch. - -
- -### Requirements - -Large organizations must keep the number of updates to key protected branches -under certain limits to allow time for code review to happen. For example, if -a team tries to merge 60 change requests per hour into the `main` branch, the -tip of the `main` branch would only be stable for about 1 minute. This would -leave only 1 minute for a new diff to be both generated and reviewed before -it becomes stale again. - -The normal way to work in this environment is to create a buffer branch -(sometimes called a "train") to collect a certain number of approved changes. -In this model, when a change is approved for submission to the protected -branch, it is added to the train branch instead. After a certain amount of -time, the train branch will be merged into the protected branch. If there are -problems detected with the contents on the train branch, it's normal for the -whole train to be abandoned and a new train to be formed. Approved changes -will be re-applied to a new train in this scenario. - -The key benefit to this approach is that the protected branch remains stable -for longer, allowing more time for human and automatic code review. A key -downside to this approach is that organizations will not know the final -revision ID that represents a change until the entire train process completes. - -A change review process will now be associated with multiple distinct -revisions. - -- ID 1: The revision which was reviewed before concluding the change review - process. It represents the ideal state of the protected branch applying - only this proposed change. -- ID 2: The revision created when the change is applied to the train branch. - It represents the state of the protected branch _after other changes have - been applied_. - -It is important to note that no human or automatic review will have the chance -to pre-approve ID2. This will appear to violate any organization policies that -require pre-approval of changes before submission. The SCS and the -organization MUST protect this process in the same way they protect other -artifact build pipelines. - -At a minimum the SCS MUST issue an attestation that the revision ID generated -by a merged train is identical ("MERGESAME" in git terminology) to the state -of the protected branch after applying each approved changeset in sequence. -No other content may be added or removed during this process. diff --git a/docs/spec/v1.2-rc2/source-requirements.md b/docs/spec/v1.2-rc2/source-requirements.md deleted file mode 100644 index 6a3b68a1a..000000000 --- a/docs/spec/v1.2-rc2/source-requirements.md +++ /dev/null @@ -1,638 +0,0 @@ ---- -title: "Source: Requirements for producing source" -description: "This page covers the detailed technical requirements for producing source revisions at each SLSA level. The intended audience is source control system implementers and security engineers." ---- - -## Objective - -The primary purpose of the SLSA Source track is to provide producers and consumers with increasing levels of trust in the source code they produce and consume. -It describes increasing levels of trustworthiness and completeness of how a source revision was created. - -The expected process for creating a new revision is determined solely by that repository's owner (the organization) who also determines the intent of the software in the repository and administers technical controls to enforce the process. - -Consumers can review attestations to verify whether a particular revision meets their standards. - -## Definitions - -A **Version Control System (VCS)** is a system of software and protocols for -managing the version history of a set of files. Git, Mercurial, and Subversion -are all examples of version control systems. - -The following terms apply to Version Control Systems: - -| Term | Description -| --- | --- -| Source Repository (Repo) | A self-contained unit that holds the content and revision history for a set of files, along with related metadata like Branches and Tags. -| Source Revision | A specific, logically immutable snapshot of the repository's tracked files. It is uniquely identified by a revision identifier, such as a cryptographic hash like a Git commit SHA or a path-qualified sequential number like `25@trunk/` in SVN. A Source Revision includes both the content (the files) and its associated version control metadata, such as the author, timestamp, and parent revision(s). Note: Path qualification is needed for version control systems that represent Branches and Tags using paths, such as Subversion and Perforce. -| Named Reference | A user-friendly name for a specific source revision, such as `main` or `v1.2.3`. -| Change | A modification to the state of the Source Repository, such as creation of a new Source Revision based on a previous Source Revision, or creation, deletion, or modification of a Named Reference. -| Change History | A record of the history of Source Revisions that preceded a specific revision. -| Branch | A Named Reference that moves to track the Change History of a cohesive line of development within a Source Repository. E.g. `main`, `develop`, `feature-x` -| Tag | A Named Reference that is intended to be immutable. Once created, it is not moved to point to a different revision. E.g. `v1.2.3`, `release-20250722` - -> **NOTE:** The 'branch' and 'tag' features within version control systems may -not always align with the 'Branch' and 'Tag' definitions provided in this -specification. For example, in git and other version control systems, the UX may -allow 'tags' to be moved. Patterns like `latest` and `nightly` tags rely on this. -For the purposes of this specification these would be classified as 'Named References' and not as 'Tags'. - -A **Source Control System (SCS)** is a platform or combination of services -(self-hosted or SaaS) that hosts a Source Repository and provides a trusted -foundation for managing source revisions by enforcing policies for -authentication, authorization, and change management, such as mandatory code -reviews or passing status checks. - -The following terms apply to Source Control Systems: - -| Term | Description -| --- | --- -| Organization | A set of people who collectively create Source Revisions within a Source Repository. Examples of organizations include open-source projects, a company, or a team within a company. The organization defines the goals of a Source Repository and the methods used to produce new Source Revisions. -| Proposed Change | A proposal to make a Change in a Source Repository. -| Source Provenance | Information about how a Source Revision came to exist, where it was hosted, when it was generated, what process was used, who the contributors were, and which parent revisions preceded it. - -### Source Roles - -| Role | Description -| --- | --- -| Administrator | A human who can perform privileged operations on one or more projects. Privileged actions include, but are not limited to, modifying the change history and modifying project- or organization-wide security policies. -| Trusted person | A human who is authorized by the organization to propose and approve changes to the source. -| Trusted robot | Automation authorized by the organization to act in explicitly defined contexts. The robot’s identity and codebase cannot be unilaterally influenced. -| Untrusted person | A human who has limited access to the project. They MAY be able to read the source. They MAY be able to propose or review changes to the source. They MAY NOT approve changes to the source or perform any privileged actions on the project. - -## Onboarding - -When onboarding a branch to the SLSA Source Track or increasing the level of -that branch, organizations are making claims about how the branch is managed -from that revision forward. This establishes [continuity](#continuity). - -No claims are made for prior revisions. - -## Basics - -NOTE: This table presents a simplified view of the requirements. See the -[Requirements](#requirements) section for the full list of requirements for each -level. - -| Track/Level | Requirements | Focus -| ----------- | ------------ | ----- -| [Source L1](#source-l1) | Use a version control system. | Generation of discrete Source Revisions for precise consumption. -| [Source L2](#source-l2) | Preserve Change History and generate Source Provenance. | Reliable history through enforced controls and evidence. -| [Source L3](#source-l3) | Enforce organizational technical controls. | Consumer knowledge of guaranteed technical controls. -| [Source L4](#source-l4) | Require code review. | Improved code quality and resistance to insider threats. - -
- -### Level 1: Version controlled - -
-
Summary
- -The source is stored and managed through a modern version control system. - -
Intended for
- -Organizations currently storing source in non-standard ways who want to quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem with minimal impact to their current workflows. - -
Benefits
- -Migrating to the appropriate tools is an important first step on the road to operational maturity. - -
-
-
- -### Level 2: History & Provenance - -
-
Summary
- -Branch history is continuous, immutable, and retained, and the -SCS issues Source Provenance Attestations for each new Source Revision. -The attestations provide contemporaneous, tamper-resistant evidence of when -changes were made, who made them, and which technical controls were enforced. - -
Intended for
- -All organizations of any size producing software of any kind. - -
Benefits
- -Reliable history allows organizations and consumers to track changes to software -over time, enabling attribution of those changes to the actors that made them. -Source Provenance provides strong, tamper-resistant evidence of the process that -was followed to produce a Source Revision. - -
-
-
- -### Level 3: Continuous technical controls - -
-
Summary
- -The SCS is configured to enforce the Organization's technical controls for specific Named References within the Source Repository. - -
Intended for
- -Organizations that want to show evidence of their additional technical controls. - -
Benefits
- -A verifier can use this published data to ensure that a given Source Revision -was created in the correct way by verifying the Source Provenance or VSA. -Provides verifiers strong evidence of all technical controls enforced during the update of a Named Reference. - -
-
-
- -### Level 4: Two-party review - -
-
Summary
- -The SCS requires two trusted persons to review all changes to protected -branches. - -
Intended for
- -Organizations that want strong guarantees that the software they produce is not -subject to unilateral changes that would subvert their intent. - -
Benefits
- -Makes it harder for an actor to introduce malicious changes into the software -and makes it more likely that the source reflects the intent of the -organization. - -
-
- -## Requirements - -Many examples in this document use the -[git version control system](https://git-scm.com/), but use of git is not a -requirement to meet any level on the SLSA source track. - -### Organization - -[Organization]: #organization - - -
RequirementDescriptionL1L2L3L4 - -
Choose an appropriate Source Control System 🔗 - -An organization producing Source Revisions MUST select an SCS capable of reaching -their desired SLSA Source Level. - -> For example, if an organization wishes to produce revisions at Source Level 3, -they MUST choose a Source Control System capable of producing Source Level 3 -attestations. - -✓✓✓✓ - -
Configure the SCS to control access and enforce history 🔗 - -The organization MUST configure access controls to restrict sensitive operations -on the Source Repository. These controls MUST be implemented using the -SCS-provided [Identity Management capability](#identity-management). - -> For example, an organization may configure the SCS to assign users to a -`maintainers` role and only allow users in `maintainers` to make updates to -`main`. - -The SCS MUST be configured to produce a reliable [Change History](#history) for -its consumable Source Revisions. -If the SCS provides this capability by design, no additional controls are needed. -Otherwise the organization MUST provide evidence of [continuous enforcement](#continuity). - -If the SCS supports [Tags](#tag), the SCS MUST be configured to prevent them -from being moved or deleted. - -> For example, if a git tag `release1` is used to indicate a release revision -with ID `abc123`, controls must be configured to prevent that tag from being -updated to any other revision in the future. -Evidence of these controls (and their continuity) will appear in the Source -Provenance documents for revision `abc123`. - -✓✓✓ -
Safe Expunging Process 🔗 - -SCSs MAY allow the organization to expunge (remove) content from a repository -and its change history without leaving a public record of the removed content, -but the organization MUST only allow these changes in order to meet legal or -privacy compliance requirements. Content changed under this process includes -changing files, history, references, or any other metadata stored by the SCS. - -#### Warning - -Removing a revision from a repository is similar to deleting a package version -from a registry: it's almost impossible to estimate the amount of downstream -supply chain impact. - -> For example, in Git, each revision ID is based on the ones before it. -When you remove a revision, you must generate new revisions (and new revision IDs) -for any revisions that were built on top of it. Consumers who took a dependency -on the old revisions may now be unable to refer to the revision they've already -integrated into their products. - -It may be the case that the specific set of changes targeted by a legal takedown -can be expunged in ways that do not impact consumed revisions, which can mitigate -these problems. - -It is also the case that removing content from a repository won't necessarily -remove it everywhere. -The content may still exist in other copies of the repository, either in backups -or on developer machines. - -#### Process - -An organization MUST document the Safe Expunging Process and describe how -requests and actions are tracked and SHOULD log the fact that content was -removed. Different organizations and tech stacks may have different approaches -to the problem. - -SCSs SHOULD have technical mechanisms in place which require an Administrator -plus at least one additional 'trusted person' to trigger any expunging -(removals) made under this process. - -The application of the Safe Expunging Process and the resulting logs MAY be -private to prevent calling attention to potentially sensitive data or to comply -with local laws and regulations. Organizations SHOULD prefer to make logs public -if possible. - -✓✓✓ -
Continuous technical controls 🔗 - -The organization MUST provide evidence of continuous enforcement via technical -controls for any claims made in the Source Provenance attestations or VSAs (see -[control continuity](#continuity)). - -The organization MUST document the meaning of their enforced technical controls. - -> For example, if an organization implements a technical control via a custom -tool (such as required GitHub Actions workflow), it must indicate the name of -this tool, what it accomplishes, and how to find its evidence in the provenance -attestation. - -> For another example, if the organization claims that all consumable Source -Revisions on the `main` branch were tested prior to acceptance, this MUST be -explicitly enforced in the SCS. - -✓✓ - -
- -### Source Control System - - -
RequirementDescriptionL1L2L3L4 - -
Repositories are uniquely identifiable 🔗 - -The repository ID is defined by the SCS and MUST be uniquely identifiable within -the context of the SCS with a stable locator, such as a URI. - -✓✓✓✓ -
Revisions are immutable and uniquely identifiable 🔗 -The revision ID is defined by the SCS and MUST be uniquely identifiable within the context of the repository. -When the revision ID is a digest of the content of the revision (as in git) nothing more is needed. -When the revision ID is a number or otherwise not a digest, then the SCS MUST document how the immutability of the revision is established. -The same revision ID MAY be present in multiple repositories. - -See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). - -✓✓✓✓ -
Human readable changes 🔗 - -The SCS MUST provide tooling to display Changes between one Source Revision and -another in a human readable form (e.g. 'diffs') for all plain-text changes and -SHOULD provide mechanisms to provide human understandable interpretations of -non-plain-text changes (e.g. render images, verify and display provenance for -binaries, etc.). - -✓✓✓✓ -
Source Verification Summary Attestations 🔗 - -The SCS MUST generate a -[source verification summary attestation](#source-verification-summary-attestation) (Source VSA) -to indicate the SLSA Source Level of any revision at Level 1 or above. - -If a consumer is authorized to access a revision, they MUST be able to fetch the -corresponding Source VSA. - -If the SCS DOES NOT generate a VSA for a revision, the revision has Source Level -0. - -At Source Levels 1 and 2 the SCS MAY issue these attestations based on its -understanding of the underlying system (e.g. based on design docs, security -reviews, etc.), but at Level 2+ the SCS MUST use the SCS-issued -[source provenance](#source-provenance) when issuing the VSAs. - -✓✓✓✓ - -
History 🔗 - -There are three key aspects to change history: - -1. What were all the previous states of a Branch? -2. How and when did they change? -3. How does the current revision relate to previous revisions? - -To answer these questions, the SCS MUST record all changes to Named References, -including when they occurred, who made them, and the new Source Revision ID. - -If Source Revisions have ancestry relationships in the VCS, the SCS MUST ensure -that a Branch can only be updated to point to revisions that descend from the -current revision. -In git, this requires a technical control to prohibit `git push --force`. - -This requirement captures evidence that the organization intended to make the -changes captured by the new revision. - -> For example, if a branch currently points to revision `a`, it may only be -moved to a new revision `b` if `a` is an ancestor of `b`. - -✓✓✓ -
Continuity 🔗 - -Technical Controls are only effective if they are used continuously in the -history of a Branch. -'Control continuity' reflects an organization's ongoing commitment to a -technical control. - -For each technical control claimed in a VSA, continuity MUST be established and -tracked from a specific start revision. -If there is a lapse in continuity for a specific control, continuity of that -control MUST be re-established from a new revision. - -Exceptions to the continuity requirement are allowed via the [safe expunging process](#safe-expunging-process). - -> For example, the `main` branch currently points to revision `a` when a new -technical control `t` is configured. -The next revision on the `main` branch, `b` will be the first revision that was -protected by `t` and `b` is the first revision in the "continuity" of `t`. -Any revisions added to `main` while `t` is disabled will reset the continuity of `t`. - -✓✓✓ - -
Identity Management 🔗 - -The SCS MUST provide an identity management system or some other means of -identifying and authenticating actors. - -The SCS MUST allow organizations to specify which actors and roles are allowed -to perform sensitive actions within a repository (e.g. creation or updates of -branches, approval of changes). - -Depending on the SCS, identity management may be provided by source control -services (e.g., GitHub, GitLab), implemented using cryptographic signatures -(e.g., using gittuf to manage public keys for actors), or extending existing -authentication systems used by the organization (e.g., Active Directory, Okta, -etc.). - -The SCS MUST document how actors are identified for the purposes of attribution. - -Activities conducted on the SCS SHOULD be attributed to authenticated -identities. - -✓✓✓ - -
Source Provenance 🔗 - -[Source Provenance](#source-provenance-attestations) are attestations that -contain information about how a specific revision was created and how it came to -exist on a protected branch or how a tag came to point at it. They are -associated with the revision identifier delivered to consumers and are a -statement of fact from the perspective of the SCS. The SCS MUST document the -format and intent of all Source Provenance attestations it produces. - -Source Provenance MUST be created contemporaneously with the branch being -updated such that they provide a credible, auditable, record of changes. - -If a consumer is authorized to access a revision, they MUST be able to access the -corresponding Source Provenance documents for that revision. - -It is possible that an SCS can make no claims about a particular revision. - -> For example, this would happen if the revision was created on another SCS, -on an unprotected branch (such as a `topic` branch), or if the revision was not -the result of the expected process. - -✓✓✓ -
Protected Named References 🔗 - -The SCS MUST provide the ability for an organization to enforce customized technical controls for Named References. - -The SCS MUST provide a mechanism for organizations to indicate which Named -References should be protected by technical controls. - -> For example, the organization may instruct the SCS to protect `main` and -`refs/heads/releases/*`, but not `refs/heads/experimental/*` using branch -protection rules (e.g. [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), -[GitLab](https://docs.gitlab.com/ee/user/project/repository/branches/protected.html)) -or via the application and verification of [gittuf](https://github.com/gittuf/gittuf) -policies. - -> For another example, the organization may instruct the SCS to prevent the deletion of -all `refs/tags/releases/*` using tag protection rules -(e.g. [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), -[GitLab](https://docs.gitlab.com/user/project/protected_tags/)) -or via the application and verification of [gittuf](https://github.com/gittuf/gittuf) -policies. - -The SCS MUST - -- Record technical controls enforced on Named References in contemporaneously - produced attestations associated with the corresponding Source Revisions. -- Allow organizations to provide - [organization-specified properties](#additional-properties) to be included in the - [Source VSA](#source-verification-summary-attestation) when the corresponding controls are - enforced. -- Allow organizations to distribute additional attestations related to their - technical controls to consumers authorized to access the corresponding Source - Revision. -- Prevent organization-specified properties from beginning with any value - other than `ORG_SOURCE_`. - -✓✓ -
Two-party review 🔗 - -Changes in protected branches MUST be agreed to by two or more trusted persons prior to submission. -The following combinations are acceptable: - -- Uploader and reviewer are two different trusted persons. -- Two different reviewers are trusted persons. - -Reviews SHOULD cover, at least, security relevant properties of the code. - -**[Final revision approved]** This requirement applies to the final revision -submitted. I.e., if additional changes are made during the review process, those changes MUST -be reviewed as well. - -**[Context-specific approvals]** Approvals are for a specific context, such as a -repo + branch in git. Moving fully reviewed content from one context to another -still requires review. The exact definition of “context” depends on the project, -and this does not preclude well-understood automatic merges, such as cutting a release branch. - -**[Informed Review]** The SCS MUST present reviewers with a clear representation of the result of accepting the proposed change. See [Human Readable Changes](#human-readable-diff). - -**[Trusted Robot Contributions]** An organization MAY choose to grant a Trusted -Robot a perpetual exception to a policy (e.g. a bot may be able to merge a change -that has not been reviewed by two parties). - -Examples: - -- Import and migration bots that move code from one repo to another. -- Dependabot - -✓ -
- -## Communicating source levels - -SLSA source level details are communicated using attestations. -These attestations either refer to a source revision itself or provide context needed to evaluate an attestation that _does_ refer to a revision. - -There are two broad categories of source attestations within the source track: - -1. Source verification summary attestations (Source VSAs): Used to communicate to downstream users what high level security properties a given source revision meets. -2. Source provenance attestations: Provide trustworthy, tamper-proof, metadata with the necessary information to determine what high level security properties a given source revision has. - -To provide interoperability and ensure ease of use, it's essential that the Source VSAs are applicable across all Source Control Systems. -However, due to the significant differences in how SCSs operate and how they may choose to meet the Source Track requirements, it is preferable to -allow for flexibility with the full source provenance attestations. To that end, SLSA leaves source provenance attestations undefined and up to the SCSs to determine -what works best in their environment. - -### Source verification summary attestation - -Source verification summary attestations (Source VSAs) are issued by some authority that has sufficient evidence to make the determination of a given -revision's source level. Source VSAs convey properties about the revision as a whole and summarize properties computed over all -the changes that contributed to that revision over its history. - -The source track issues Source VSAs using the [Verification Summary Attestations](./verification_summary.md) format as follows: - -1. `subject.uri` SHOULD be set to a URI where a human can find details about - the revision. This field is not intended for policy decisions. Instead, it - is only intended to direct a human investigating verification failures. - - For example: `https://github.com/slsa-framework/slsa/commit/6ff3cd75c8c9e0fcedc62bd6a79cf006f185cedb` -2. `subject.digest` MUST include the revision identifier (e.g. `gitCommit`) and MAY include other digests over the contents of the revision (e.g. `gitTree`, `dirHash`, etc.). -SCSs that do not use cryptographic digests MUST define a canonical type that is used to identify immutable revisions and MUST include the repository within the type[^1]. - - For example: `svn_revision_id: svn+https://svn.myproject.org/svn/MyProject/trunk@2019` -3. `subject.annotations.sourceRefs` SHOULD be set to a list of references that pointed to this revision when the attestation was created. The list MAY be non-exhaustive. - - git references MUST be fully qualified (e.g. `refs/heads/main` or `refs/tags/v1.0`) to reduce the likelihood of confusing downstream tooling. -4. `resourceUri` MUST be set to the URI of the repository, preferably using [SPDX Download Location](https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field). -E.g. `git+https://github.com/foo/hello-world`. -5. `verifiedLevels` MUST include the SLSA source track level the SCS asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. -MAY include additional properties as asserted by the SCS. The SCS MUST include _only_ the highest SLSA source level met by the revision. -6. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. For example, this could be used to indicate the source level of any git submodules present in the revision. - -#### Additional properties - -The SLSA source track MAY create additional properties to include in -`verifiedLevels` which attest to other claims concerning a revision. - -The SCS MAY embed additional properties within `verifiedLevels` provided by the -organization as long as they are prefixed by `ORG_SOURCE_` to distinguish them -from other properties the SCS may wish to use. The SCS MUST enforce the use of -this prefix for such properties. An organization MAY further differentiate -properties using: - -- `ORG_SOURCE_` to indicate a property that is meant for consumption by - external consumers. -- `ORG_SOURCE_INTERNAL_` to indicate a property that is not meant for - consumption by external consumers. - -The meaning of the properties is left entirely to the organization. - -#### Populating sourceRefs - -The Source VSA issuer may choose to populate `sourceRefs` in any way they wish. -Downstream users are expected to be familiar with the method used by the issuer. - -Example implementations: - -- Issue a new VSA for each merged Pull Request and add the destination branch to `sourceRefs`. -- Issue a new VSA each time a Named Reference is updated to point to a new revision. - -#### Example - -```json -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a", - "digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"}, - "annotations": {"sourceRefs": ["refs/heads/main", "refs/heads/release_1.0"]} -}], - -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/source_verifier", - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "git+https://github.com/foo/hello-world", - "policy": { - "uri": "https://example.com/slsa_source.policy", - }, - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_SOURCE_LEVEL_3"], -} -``` - -#### How to verify - -See [Verifying Source](./verifying-source.md) for instructions how to verify -VSAs for Source Revisions. - -### Source provenance attestations - -Source provenance attestations provide tamper-proof evidence ([attestation model](attestation-model)) -that can be used to determine what SLSA Source Level or other high-level properties a given revision meets. -This evidence can be used by: - -- an authority as the basis for issuing a [Source VSA](#source-verification-summary-attestation) -- a consumer to cross-check a [Source VSA](#source-verification-summary-attestation) they received for a revision -- a consumer to enforce a more detailed policy than the organization's own process - -SCSs may have different methods of operating that necessitate different forms of evidence. -E.g. GitHub-based workflows may need different evidence than Gerrit-based workflows, which would both likely be different from workflows that -operate over Subversion repositories. - -These differences also mean that, depending on the configuration, the issuers of provenance attestations may vary from implementation to implementation, often because entities with the knowledge to issue them may vary. -The authority that issues [Source VSAs](#source-verification-summary-attestation) MUST understand which entity should issue each provenance attestation type, and ensure all source provenance attestations come from their expected issuers. - -'Source provenance attestations' is a generic term used to refer to any type of attestation that provides evidence of the process used to create a revision. - -Example source provenance attestations: - -- A TBD attestation which describes the revision's parents and the actors involved in creating this revision. -- A "code review" attestation which describes the basics of any code review that took place. -- An "authentication" attestation which describes how the actors involved in any revision were authenticated. -- A [Vuln Scan attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/vuln.md) - which describes the results of a vulnerability scan over the contents of the revision. -- A [Test Results attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/test-result.md) - which describes the results of any tests run on the revision. -- An [SPDX attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md) - which provides a software bill of materials for the revision. -- A [SCAI attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md) used to - describe which source quality tools were run on the revision. - -Irrespective of the types of provenance attestations generated by an SCS and -their implementations, the SCS MUST document provenance -formats, and how each provenance attestation can be used to reason about the -revision's properties recorded in the summary attestation. - -[^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms. - -## Future Considerations - -### Authentication - -- Better protection against phishing by forbidding second factors that are not - phishing resistant. -- Protect against authentication token theft by forbidding bearer tokens - (e.g. PATs). -- Including length of continuity in the VSAs diff --git a/docs/spec/v1.2-rc2/terminology.md b/docs/spec/v1.2-rc2/terminology.md deleted file mode 100644 index 5e4dc968f..000000000 --- a/docs/spec/v1.2-rc2/terminology.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: "Build: Terminology" -description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting. ---- - - -Before diving into the [Build Track](build-track-basics.md), we need to -establish a core set of terminology and models to describe what we're -protecting. - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). -| [Distribution] | The channel through which artifacts are "published" for use by others. | A registry like DockerHub or npm. Artifacts may also be distributed via physical media (e.g., a USB drive). -| Package | Artifact that is distributed. 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 (distribution). 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 -[distribution]: #distribution-model -[SLSA Provenance]: /provenance/v1 - -### Roles - -Throughout the specification, you will see reference to the following roles -that take part in the software supply chain. Note that in practice a role may -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. - -### Build model - -

Model Build

- -We model a build as running on a multi-tenant *build platform*, where each -execution is independent. - -1. A tenant invokes the build by specifying *external parameters* through an - *interface*, either directly or via some trigger. Usually, at least one of - these external parameters is a reference to a *dependency*. (External - parameters are literal values while dependencies are artifacts.) -2. The build platform's *control plane* interprets these external parameters, - fetches an initial set of dependencies, initializes a *build environment*, - and then starts the execution within that environment. -3. The build then performs arbitrary steps, which might include fetching - additional dependencies, and then produces one or more *output* artifacts. - The steps within the build environment are under the tenant's control. - The build platform isolates build environments from one another to some - degree (which is measured by the SLSA Build Level). -4. Finally, for SLSA Build L2+, the control plane outputs *provenance* - describing this whole process. - -Notably, there is no formal notion of "source" in the build model, just external -parameters and dependencies. Most build platforms have an explicit "source" -artifact to build from, which is often a git repository; in the build model, the -reference to this artifact is an external parameter while the artifact itself is -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. - -
Ambiguous terms to avoid - -- *Build recipe:* Could mean *external parameters,* but may include concrete - steps of how to perform a build. To avoid implementation details, we don't - define this term, but always use "external parameters" which is the - interface to a build platform. Similar terms are *build configuration - source* and *build definition*. -- *Builder:* Usually means *build platform*, but might be used for *build - environment*, the user who invoked the build, or a build tool from - *dependencies*. To avoid confusion, we always use "build platform". The only - exception is in the [provenance](/provenance/v1), where `builder` is used as - a more concise field name. - -
- -### Distribution model - -Software is distributed in identifiable units called packages -according to the rules and conventions of a package ecosystem. -Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and -[OCI](https://github.com/opencontainers/distribution-spec), while examples of -informal ecosystems include links to files on a website or distribution of -first-party software within a company. - -Abstractly, a consumer locates software within an ecosystem by asking a -distribution platform, such as a package registry, to resolve a -mutable package name into an immutable package artifact. -[^label] To publish a package artifact, the software producer asks -the registry to update this mapping to resolve to the new artifact. The registry -represents the entity or entities with the power to alter what artifacts are -accepted by consumers for a given package name. For example, if consumers only -accept packages signed by a particular public key, then it is access to that -public key that serves as the registry. - -The package name is the primary security boundary within a package ecosystem. -Different package names represent materially different pieces of -software---different owners, behaviors, security properties, and so on. -Therefore, **the package name is the primary unit being protected in SLSA**. -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 -| ---- | ----------- -| Distribution platform | An entity responsible for mapping package names to immutable package artifacts. -| 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 | A specific type of "distribution platform" used 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 - -- *Package repository:* Could mean either package registry or package name, - depending on the ecosystem. To avoid confusion, we always use "repository" - exclusively to mean "source repository", where there is no ambiguity. -- *Package manager* (without "client"): Could mean either package ecosystem, - package registry, or client-side tooling. - -
- -### Mapping to real-world ecosystems - -Most real-world ecosystems fit the package model above but use different terms. -The table below attempts to document how various ecosystems map to the SLSA -Package model. There are likely mistakes and omissions; corrections and -additions are welcome! - - - - - - - - - - - - - - - - - - - - - - - - - - -
Package ecosystem - Package registry - Package name - Package artifact -
Languages -
Cargo (Rust) - Registry - Crate name - Artifact -
CPAN (Perl) - PAUSE - Distribution - Release (or Distribution) -
Go - Module proxy - Module path - Module -
Maven (Java) - Repository - Group ID + Artifact ID - Artifact -
npm (JavaScript) - Registry - Package Name - Package -
NuGet (C#) - Host - Project - Package -
PyPA (Python) - Index - Project Name - Distribution -
Operating systems -
Dpkg (e.g. Debian) - ? - Package name - Package -
Flatpak - Repository - Application - Bundle -
Homebrew (e.g. Mac) - Repository (Tap) - Package name (Formula) - Binary package (Bottle) -
Pacman (e.g. Arch) - Repository - Package name - Package -
RPM (e.g. Red Hat) - Repository - Package name - Package -
Nix (e.g. NixOS) - Repository (e.g. Nixpkgs) or binary cache - Derivation name - Derivation or store object -
Storage systems -
GCS - n/a - Object name - Object -
OCI/Docker - Registry - Repository - Object -
Meta -
deps.dev: System - Packaging authority - Package - n/a -
purl: type - Namespace - Name - n/a -
- -Notes: - -- Go uses a significantly different distribution model than other ecosystems. - In Go, the package name is a source repository URL. While clients can fetch - directly from that URL---in which case there is no "package" or - "registry"---they usually fetch a zip file from a *module proxy*. The module - proxy acts as both a builder (by constructing the package artifact from - source) and a registry (by mapping package name to package artifact). People - trust the module proxy because builds are independently reproducible, and a - *checksum database* guarantees that all clients receive the same artifact - for a given URL. - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build platform is -certified to ensure conformance with the requirements at the level claimed by -the build platform. This certification should happen on a recurring cadence, with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer-defined -expectations of where the package source code was retrieved from and on what -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 assessment | [Build platforms are assessed](assessing-build-platforms.md) for their ability to meet 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 assessment | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their adherence 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 assessment | Performed by the language ecosystem packaging authority. - -
diff --git a/docs/spec/v1.2-rc2/threats-overview.md b/docs/spec/v1.2-rc2/threats-overview.md deleted file mode 100644 index 8b2d04a25..000000000 --- a/docs/spec/v1.2-rc2/threats-overview.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Supply chain threats -description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA could help. ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA could help. For a more technical discussion, see [Threats & mitigations](threats.md). - -## Summary - -![Supply Chain Threats](images/supply-chain-threats.svg) - -**Note that SLSA does not currently address all of the threats presented here.** -See [Threats & mitigations](threats.md) for what is currently addressed and -[Terminology](terminology.md) for an explanation of the supply chain model. - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that the source revision represents the intent of the producer, that all expected processes were followed and that the revision was not modified after being accepted. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - - - -
-Threats from -Known example -How SLSA could help -
A -Producer -SpySheriff: Software producer purports to offer anti-spyware software, but that software is actually malicious. -SLSA does not directly address this threat but could make it easier to discover malicious behavior in open source software, by forcing it into the publicly available source code. -For closed source software SLSA does not provide any solutions for malicious producers. -
B -Authoring & reviewing -SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. -Two-person review could have caught the unauthorized change. -
C -Source code management -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code system would have been a much harder target for the attackers. -
D -External build parameters -The Great Suspender: Attacker published software that was not built from the purported sources. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
E -Build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA Build levels have stronger security requirements for the build platform, making it more difficult for an attacker to forge the SLSA provenance and gain persistence. -
F -Artifact publication -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Distribution channel -Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Package selection -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
I -Usage -Default credentials: Attacker could leverage default credentials to access sensitive data. -SLSA does not address this threat. -
N/A -Dependency threats (i.e. A-H, recursively) -event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code. -Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source. -
- - - - - - -
-Availability threat -Known example -How SLSA could help -
N/A -Dependency becomes unavailable -Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. diff --git a/docs/spec/v1.2-rc2/threats.md b/docs/spec/v1.2-rc2/threats.md deleted file mode 100644 index 32499a6a6..000000000 --- a/docs/spec/v1.2-rc2/threats.md +++ /dev/null @@ -1,1075 +0,0 @@ ---- -title: Threats & mitigations -description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. ---- - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations with SLSA and other best practices. For an -introduction to the supply chain threats that SLSA is aiming to protect -against, see [Supply chain threats]. - -The examples on this page are meant to: - -- Explain the reasons for each of the SLSA [build](build-requirements.md) and - [source](source-requirements.md) requirements. -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](about#how-slsa-works) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - - - -
- -## Overview - -![Supply Chain Threats](images/supply-chain-threats.svg) - -This threat model covers the *software supply chain*, meaning the process by -which software is produced and consumed. We describe and cluster threats based -on where in the software development pipeline those threats occur, labeled (A) -through (I). This is useful because priorities and mitigations mostly cluster -along those same lines. Keep in mind that dependencies are -[highly recursive](#dependency-threats), so each dependency has its own threats -(A) through (I), and the same for *their* dependencies, and so on. For a more -detailed explanation of the supply chain model, see -[Terminology](terminology.md). - -Importantly, producers and consumers face *aggregate* risk across all of the -software they produce and consume, respectively. Many organizations produce -and/or consume thousands of software packages, both first- and third-party, and -it is not practical to rely on every individual team in the organization to do -the right thing. For this reason, SLSA prioritizes mitigations that can be -broadly adopted in an automated fashion, minimizing the chance of mistakes. - -## Source threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes modification of the source data at rest as well as insider threats, -when an authorized individual introduces an unauthorized change. - -The SLSA Source track mitigates these threats when the consumer -[verifies source](verifying-source.md) against expectations, confirming -that the revision they received was created in the expected manner. - -### (A) Producer - -The producer of the software intentionally produces code that harms the -consumer, or the producer otherwise uses practices that are not deserving of the -consumer's trust. - -
Software producer intentionally creates a malicious revision of the source - -*Threat:* A producer intentionally creates a malicious revision with the intent of harming their consumers. - -*Mitigation:* -This kind of attack cannot be directly mitigated through SLSA controls. -Consumers must establish some basis to trust the organizations from which they consume software. -That basis may be: - -- The repo is open source with an active user-base. High numbers of engaged users may increase the likelihood that bad code is detected during code review and reduce the time-to-detection when bad revisions are accepted. -- The organization has sufficient legal or reputational incentives to dissuade it from making malicious changes. - -Ultimately this is a judgement call with no straightforward answer. - -*Example:* A producer with an otherwise good reputation decides suddenly to produce a malicious artifact with the intent to harm their consumers. - -
- -### (B) Modifying the source - -An adversary without any special administrator privileges attempts to introduce a change counter to the declared intent of the source by following the producer's official source control process. - -Threats in this category can be mitigated by following source control management best practices. - -#### (B1) Submit change without review - -
Directly submit without review(Source L4) - -*Threat:* Malicious code submitted to the source repository. - -*Mitigation:* Require approval of all changes before they are accepted. - -*Example:* Adversary directly pushes a change to a git repo's `main` branch. -Solution: The Source Control System is configured to require two party review for -contributions to the `main` branch. - -
-
Single actor controls multiple accounts - -*Threat:* An actor is able to control multiple account and effectively approve their own code changes. - -*Mitigation:* The producer must ensure that no actor is able to control or influence multiple accounts with review privileges. - -*Example:* Adversary creates a pull request using a secondary account and approves it using their primary account. -Solution: The producer must track all actors who have both explicit review permissions and the independent ability to control -a privileged bot. A common vector for this attack is to influence a robot account with the permission to review or contribute -code. Control of the robot account and an actor's own personal account is enough to exploit this vulnerability. A common -solution to this flow is to deny bot accounts from contributing or reviewing code, or to require more human reviews in those -cases. - -
-
Use a robot account to submit change - -*Threat:* Exploit a robot account that has the ability to submit changes without -two-person review. - -*Mitigation:* All changes require review by two people, even changes authored by -robots. - -*Example:* A file within the source repository is automatically generated by a -robot, which is allowed to submit without review. -Adversary compromises the robot and submits a malicious change. -Solution: Require two-person review for such changes, ignoring the robot. - -
-
Abuse of rule exceptions - -*Threat:* Rule exceptions provide vector for abuse. - -*Mitigation:* Remove rule exceptions. - -*Example:* A producer intends to require two-person review on "all changes except for documentation changes," defined as those only modifying `.md` files. -Adversary submits a malicious executable masquerading as a documentation file, `help.md`. -This avoids the two-person review rule due to the exception. -In the future, a user (or another workflow) can be induced to *execute* `help.md` and become compromised. -Technically the malicious code change met all defined policies yet the intent of the organization was defeated. -Solution: The producer adjusts the rules to prohibit such exceptions. - -
- -
Highly-permissioned actor bypasses or disables controls(verification) - -*Threat:* Trusted actor with "admin" privileges in a repository submits code by disabling existing controls. - -*Mitigation:* The Source Control System must have controls in place to prevent -and detect abusive behavior from administrators (e.g. two-person approvals, -audit logging). - -*Example:* GitHub repository-level admin removes a branch protection requirement, pushes -their change, then re-enables the requirement to cover their tracks. -Solution: Consumers do not accept claims from the Source Control System unless -they trust sufficient controls are in place to prevent repo admins from -abusing privileges. - -
- -#### (B2) Evade change management process - -
Alter change history(Source L2+) - -*Threat:* Adversary alters branch history to hide malicious activity. - -*Mitigation:* The Source Control System prevents branch history from being -altered. - -*Example:* Adversary submits a malicious commit `X` to the `main` branch. A -release is built and published from `X`. The adversary then "force pushes" -to `main` erasing the record of the malicious commit. Solution: The Source -Control System is configured to prevent force pushes to `main`. - -
-
Replace tagged content with malicious content(Source L2+) - -*Threat:* Adversary alters a tag to point at malicious content. - -*Mitigation:* The Source Control System does not allow protected tags to be updated. - -*Example:* Adversary crafts a malicious commit `X` on a development branch which -does enforce any controls. They then update the `release_1.2` tag to point to -`X`. Consumers of `release_1.2` will get the malicious revision. Solution: The -Source Control System does not allow protected tags to be updated. - -
-
Skip required checks(Source L3+) - -*Threat:* Code is submitted without following the producers documented -development process, introducing unintended behavior. - -*Mitigation:* The producer uses the Source Control System to implement technical -controls ensuring adherence to the development process. - -*Example:* An engineer submits a new feature that has a critical flaw on an -untested code path, in violation of the producer's documented process of having -high test coverage. Solution: The producer implements a technical control in the -SCS that requires 95%+ test coverage. - -
-
Modify code after review(Source L4) - -*Threat:* Modify the code after it has been reviewed but before submission. - -*Mitigation:* The Source Control System invalidates approvals whenever the proposed change is modified. - -*Example:* Source repository requires two-person review on all changes. -Adversary sends an initial "good" pull request to a peer, who approves it. -Adversary then modifies their proposal to contain "bad" code. - -Solution: Configure the code review rules to require review of the most recent revision before submission. - -
-
Submit a change that is unreviewable(Source L4) - -*Threat:* Adversary crafts a change that looks benign to a reviewer but is actually malicious. - -*Mitigation:* Code review system ensures that all reviews are informed and -meaningful to the extent possible. For example the system could show -& resolve symlinks, render images, or verify & display provenance. - -*Example:* A proposed change updates a JPEG file to include a malicious -message, but the reviewer is only presented with a diff of the binary -file contents. The reviewer is unable to parse the contents themselves -so they do not have enough context to provide a meaningful review. -Solution: the code review system should present the reviewer with a -rendering of the image and the [embedded -metadata](https://en.wikipedia.org/wiki/Exif), allowing them to make an -informed decision. - -
-
Copy a reviewed change to another context(Source L4) - -*Threat:* Get a change reviewed in one context and then transfer it to a -different context. - -*Mitigation:* Approvals are context-specific. - -*Example:* MyPackage's source repository requires two-person review. Adversary -forks the repo, submits a change in the fork with review from a colluding -colleague (who is not trusted by MyPackage), then proposes the change to -the upstream repo. -Solution: The proposed change still requires two-person review in the upstream -context even though it received two-person review in another context. - -
- - -
Commit graph attacks - -*Threat:* A malicious commit can be included in a sequence of commits such that it does not appear malicious in the net change presented to reviewers. - -*Mitigation:* The producer ensures that all revisions in the protected context followed the same contribution process. - -*Example:* Adversary sends a pull request containing malicious commit X and a commit Y that undoes X. -The combined change of X + Y displays zero lines of malicious code and the reviewer cannot tell that X is malicious unless they review it individually. -If X is allowed to become reachable from the protected branch, the content may become available in secured environments such as developer machines. - -Solution: Each revision in the protected context must have followed the intended process. -Ultimately, this means that either each code review results in at most a single new commit or that the full process is followed for each constituent commit in a proposed sequence. - -
- -#### (B3) Render code review ineffective - -
Collude with another trusted person - -*Threat:* Two trusted persons collude to author and approve a bad change. - -*Mitigation:* This threat is not currently addressed by SLSA, but the producer can arbitrarily increase friction of their policies to reduce risk, such as requiring additional, or more senior reviewers. -The goal of policy here is to ensure that the approved changes match the intention of the producer for the source. -Increasing the friction of the policies may make it harder to circumvent, but doing so has diminishing returns. -Ultimately the producer will need to land upon a balanced risk profile that makes sense for their security posture. - -
-
Trick reviewer into approving bad code - -*Threat:* Construct a change that looks benign but is actually malicious, a.k.a. -"bugdoor." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
Reviewer blindly approves changes - -*Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber -stamping." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -#### (B4) Render change metadata ineffective - -
Forge change metadata(Source L2+) - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* The Source Control System only attributes changes to authenticated -identities and records contemporaneous evidence of changes in signed source -provenance attestations. - -*Example:* Adversary 'X' creates a commit with unauthenticated metadata claiming -it was authored by 'Y'. Solution: The Source Control System records the identity -of 'X' when 'X' submits the commit to the repository. - -
- -### (C) Source code management - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -
Platform admin abuses privileges(verification) - -*Threat:* Platform administrator abuses their privileges to bypass controls or -to push a malicious version of the software. - -*Mitigation:* The source platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals for -changes to the infrastructure, audit logging). A future [Platform -Operations Track](future-directions#platform-operations-track) may provide -more specific guidance on how to secure the underlying platform. - -*Example 1:* GitHostingService employee uses an internal tool to push changes to -the MyPackage source repo. - -*Example 2:* GitHostingService employee uses an internal tool to push a -malicious version of the server to serve malicious versions of MyPackage sources -to a specific CI/CD client but the regular version to everyone else, in order to -hide tracks. - -*Example 3:* GitHostingService employee uses an internal tool to push a -malicious version of the server that includes a backdoor allowing specific users -to bypass branch protections. Adversary then uses this backdoor to submit a -change to MyPackage without review. - -*Solution:* Consumers do not accept claims from the Source Control System unless -they trust sufficient controls are in place to prevent repo admins from -abusing privileges. - -
-
Exploit vulnerability in SCM - -*Threat:* Exploit a vulnerability in the implementation of the source code -management system to bypass controls. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - -### (D) External build parameters - -An adversary builds from a version of the source code that does not match the -official source control repository, or changes the build parameters to inject -behavior that was not intended by the official source. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (E) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build platform pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -### (E) Build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Forge values of the provenance (other than output digest) (Build L2+) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, the trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][unforgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -platform to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Forge output digest of the provenance (n/a) - -*Threat:* The tenant-controlled build process sets output artifact digest -(`subject` in SLSA Provenance) without the trusted control plane verifying that -such an artifact was actually produced. - -*Mitigation:* None; this is not a problem. Any build claiming to produce a given -artifact could have actually produced it by copying it verbatim from input to -output.[^preimage] (Reminder: Provenance is only a claim that a particular -artifact was *built*, not that it was *published* to a particular registry.) - -*Example:* A legitimate MyPackage artifact has digest `abcdef` and is built -from source repo `good/my-package`. A malicious build from source repo -`evil/my-package` claims that it built artifact `abcdef` when it did not. -Solution: Verifier rejects because the source location does not match; the -forged digest is irrelevant. - -[^preimage]: Technically this requires the artifact to be known to the - adversary. If they only know the digest but not the actual contents, they - cannot actually build the artifact without a [preimage attack] on the digest - algorithm. However, even still there are no known concerns where this is a - problem. - -[preimage attack]: https://en.wikipedia.org/wiki/Preimage_attack - -
-
Compromise project owner (Build L2+) - -*Threat:* An adversary gains owner permissions for the artifact's build project. - -*Mitigation:* The build project owner must not have the ability to influence the -build process or provenance generation. - -*Example:* MyPackage is built on Awesome Builder under the project "mypackage". -Adversary is an owner of the "mypackage" project. Awesome Builder allows -owners to debug the build environment via SSH. An adversary uses this feature -to alter a build in progress. Solution: Build L3 requires the external parameters -to be complete in the provenance. The attackers access and/or actions within the -SSH connection would be enumerated within the external parameters. The updated -external parameters will not match the declared expectations causing verification -to fail. - -
-
Compromise other build (Build L3) - -*Threat:* Perform a malicious build that alters the behavior of a benign -build running in parallel or subsequent environments. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other or persist changes. - -*Example 1:* A build platform runs all builds for project MyPackage on -the same machine as the same Linux user. An adversary starts a malicious build -that listens for another build and swaps out source files, then starts a benign -build. The benign build uses the malicious build's source files, but its -provenance says it used benign source files. Solution: The build platform -changes architecture to isolate each build in a separate VM or similar. - -*Example 2:* A build platform uses the same machine for subsequent -builds. An adversary first runs a build that replaces the `make` binary with a -malicious version, then subsequently runs an otherwise benign build. Solution: -The builder changes architecture to start each build with a clean machine image. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build platform. - -*Mitigation:* Builds are [isolated] from the trusted build platform control -plane, and only the control plane has [access][unforgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a malicious artifact to a build cache that is later picked up by a -benign build process ([example][build-cache-poisoning-example]). - -*Mitigation:* Build caches must be [isolated][isolated] between builds to prevent -such cache poisoning attacks. In particular, the cache SHOULD be keyed by the -transitive closure of all inputs to the cached artifact, and the cache must -either be only writable by the trusted control plane or have SLSA Build L3 -provenance for each cache entry. - -*Example 1:* The cache key does not fully cover the transitive closure of all -inputs and instead only uses the digest of the source file itself. Adversary runs -a build over `auth.cc` with command line flags to gcc that define a marco -replacing `CheckAuth(ctx)` with `true`. When subsequent builds build `auth.cc` -they will get the attacker's poisoned instance that does not call `CheckAuth`. -Solution: Build cache is keyed by digest of `auth.cc`, command line, and digest of -gcc so changing the command line flags results in a different cache entry. - -*Example 2:* The tenant controlled build process has full write access to the -cache. Adversary observes a legitimate build of `auth.cc` which covers the -transitive closure of all inputs and notes the digest used for caching. The -adversary builds a malicious version of `auth.o` and directly writes it to the -build cache using the observed digest. Subsequent legitimate builds will use -the malicious version of `auth.o`. Solution: Each cache entry is keyed by the -transitive closure of the inputs, and the cache entry is itself a SLSA Build L3 -build with its own provenance that corresponds to the key. - -
-
Compromise build platform admin (verification) - -*Threat:* An adversary gains admin permissions for the artifact's build platform. - -*Mitigation:* The build platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals, audit -logging). - -*Example:* MyPackage is built on Awesome Builder. Awesome Builder allows -engineers on-call to SSH into build machines to debug production issues. An -adversary uses this access to modify a build in progress. Solution: Consumers -do not accept provenance from the build platform unless they trust sufficient -controls are in place to prevent abusing admin privileges. - -
- -### (F) Artifact publication - -An adversary uploads a package artifact that does not reflect the intent of the -package's official source control repository. - -This is the most direct threat because it is the easiest to pull off. If there -are no mitigations for this threat, then (D) and (E) are often indistinguishable -from this threat. - - - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Solution: Verifier rejects because builder is not as -expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Distribution channel - -An adversary modifies the package on the package registry using an -administrative interface or through a compromise of the infrastructure -including modification of the package in transit to the consumer. - -The distribution channel threats and mitigations look very similar to the -Artifact Publication (F) threats and mitigations with the main difference -being that these threats are mitigated by having the *consumer* perform -verification. - -The consumer's actions may be simplified if (F) produces a [VSA][vsa]. -In this case the consumer may replace provenance verification with -[VSA verification][vsa_verification]. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Replace the package with one built using an unofficial CI/CD pipeline -that does not build in the correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value or a VSA for corresponding `resourceUri`. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Adversary then replaces the original package within the -repository with the malicious package. Solution: Verifier rejects because -builder is not as expected. - -
-
Issue VSA from untrusted intermediary (expectations) - -*Threat:* Have an unofficial intermediary issue a VSA for a malicious package. - -*Mitigation*: Verifier requires VSAs to be issued by a trusted intermediary. - -*Example:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then issues a VSA of their own for the malicious -package. Solution: Verifier rejects because they only accept VSAs from -TheRepository which the adversary cannot issue since they do not have the -corresponding signing key. - -
-
Upload package without provenance or VSA (Build L1) - -*Threat:* Replace the original package with a malicious one without provenance. - -*Mitigation:* Verifier requires provenance or a VSA before accepting the package. - -*Example:* Adversary replaces MyPackage with a malicious version of MyPackage -on the package repository and deletes existing provenance. Solution: Verifier -rejects because provenance is missing. - -
-
Replace package and VSA with another (expectations) - -*Threat:* Replace a package and its VSA with a malicious package and its valid VSA. - -*Mitigation*: Consumer ensures that the VSA matches the package they've requested (not just the package they received) by following the [verification process](verification_summary#how-to-verify). - -*Example:* Adversary uploads a malicious package to `repo/evil-package`, -getting a valid VSA for `repo/evil-package`. Adversary then replaces -`repo/my-package` and its VSA with `repo/evil-package` and its VSA. -Solution: Verifier rejects because the VSA `resourceUri` field lists -`repo/evil-package` and not the expected `repo/my-package`. - -
-
Tamper with artifact after upload (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -replace it while retaining the original provenance or VSA. - -*Mitigation:* Verifier checks that the provenance or VSA's `subject` matches -the hash of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -replaces the modified version of the package in the repository and retains the -original provenance. Solution: Verifier rejects because the hash of the -artifact does not match the `subject` found within the provenance. - -
-
Tamper with provenance or VSA (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance or VSA to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance or VSA with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder or the VSA came from an expected verifier. - -*Example 1:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -*Example 2:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then modifies the original VSA's `subject` -field to match the digest of the malicious package. Solution: Verifier rejects -because the cryptographic signature is no longer valid. - -
- -## Usage threats - -A usage threat is a potential for an adversary to exploit behavior of the -consumer. - -### (H) Package selection - -The consumer requests a package that it did not intend. - -
Dependency confusion - -*Threat:* Register a package name in a public registry that shadows a name used -on the victim's internal registry, and wait for a misconfigured victim to fetch -from the public registry instead of the internal one. - -*Mitigation:* The mitigation is for the software producer to build internal -packages on a SLSA Level 2+ compliant build system and define expectations for -build provenance. Expectations must be verified on installation of the internal -packages. If a misconfigured victim attempts to install attacker's package with -an internal name but from the public registry, then verification against -expectations will fail. - -For more information see [Verifying artifacts](verifying-artifacts.md) -and [Defender's Perspective: Dependency Confusion and Typosquatting Attacks](/blog/2024/08/dep-confusion-and-typosquatting). - -
- -
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, the -requirement to make the source available can be a mild deterrent, can aid -investigation or ad-hoc analysis, and can complement source-based typosquatting -solutions. - -
- -### (I) Usage - -The consumer uses a package in an unsafe manner. - -
Improper usage - -*Threat:* The software can be used in an insecure manner, allowing an -adversary to compromise the consumer. - -*Mitigation:* This threat is not addressed by SLSA, but may be addressed by -efforts like [Secure by Design][secure-by-design]. - -
- -## Dependency threats - -A dependency threat is a potential for an adversary to introduce unintended -behavior in one artifact by compromising some other artifact that the former -depends on at build time. (Runtime dependencies are excluded from the model, as -[noted below](#runtime-dep).) - -Unlike other threat categories, dependency threats develop recursively through -the supply chain and can only be exploited indirectly. For example, if -application *A* includes library *B* as part of its build process, then a build -or source threat to *B* is also a dependency threat to *A*. Furthermore, if -library *B* uses build tool *C*, then a source or build threat to *C* is also a -dependency threat to both *A* and *B*. - -This version of SLSA does not explicitly address dependency threats, but we -expect that a future version will. In the meantime, you can [apply SLSA -recursively] to your dependencies in order to reduce the risk of dependency -threats. - - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively - -### Build dependency - -An adversary compromises the target artifact through one of its build -dependencies. Any artifact that is present in the build environment and has the -ability to influence the output is considered a build dependency. - -
Include a vulnerable dependency (library, base image, bundled file, etc.) - -*Threat:* Statically link, bundle, or otherwise include an artifact that is -compromised or has some vulnerability, causing the output artifact to have the -same vulnerability. - -*Example:* The C++ program MyPackage statically links libDep at build time. A -contributor accidentally introduces a security vulnerability into libDep. The -next time MyPackage is built, it picks up and includes the vulnerable version of -libDep, resulting in MyPackage also having the security vulnerability. - -*Mitigation:* A future -[Dependency track](../../current-activities#dependency-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -
-
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.) - -*Threat:* Use a compromised tool or other software artifact during the build -process, which alters the build process and injects unintended behavior into the -output artifact. - -*Mitigation:* This can be partially mitigated by treating build tooling, -including OS images, as any other artifact to be verified prior to use. -The threats described in this document apply recursively to build tooling -as do the mitigations and examples. A future -[Build Environment track](../../current-activities#build-environment-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -*Example:* MyPackage is a tarball containing an ELF executable, created by -running `/usr/bin/tar` during its build process. An adversary compromises the -`tar` OS package such that `/usr/bin/tar` injects a backdoor into every ELF -executable it writes. The next time MyPackage is built, the build picks up the -vulnerable `tar` package, which injects the backdoor into the resulting -MyPackage artifact. Solution: [apply SLSA recursively] to all build tools -prior to the build. The build platform verifies the disk image, -or the individual components on the disk image, against the associated -provenance or VSAs prior to running a build. Depending on where the initial -compromise took place (i.e. before/during vs *after* the build of the build tool itself), the modified `/usr/bin/tar` will fail this verification. - -
- -
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.) - -*Threat:* During the build process, use a compromised runtime dependency (such -as during testing or dynamic linking), which alters the build process and -injects unwanted behavior into the output. - -**NOTE:** This is technically the same case as [Use a compromised build -tool](#build-tool). We call it out to remind the reader that -[runtime dependencies](#runtime-dep) can become build dependencies if they are -loaded during the build. - -*Example:* MyPackage has a runtime dependency on package Dep, meaning that Dep -is not included in MyPackage but required to be installed on the user's machine -at the time MyPackage is run. However, Dep is also loaded during the build -process of MyPackage as part of a test. An adversary compromises Dep such that, -when run during a build, it injects a backdoor into the output artifact. The -next time MyPackage is built, it picks up and loads Dep during the build -process. The malicious code then injects the backdoor into the new MyPackage -artifact. - -*Mitigation:* In addition to all the mitigations for build tools, you can often -avoid runtime dependencies becoming build dependencies by isolating tests to a -separate environment that does not have write access to the output artifact. - -
- -### Related threats - -The following threats are related to "dependencies" but are not modeled as -"dependency threats". - -
Use a compromised dependency at runtime (modeled separately) - -*Threat:* Load a compromised artifact at runtime, thereby compromising the user -or environment where the software ran. - -*Example:* MyPackage lists package Dep as a runtime dependency. Adversary -publishes a compromised version of Dep that runs malicious code on the user's -machine when Dep is loaded at runtime. An end user installs MyPackage, which in -turn installs the compromised version of Dep. When the user runs MyPackage, it -loads and executes the malicious code from Dep. - -*Mitigation:* N/A - SLSA's -threat model does not explicitly model runtime dependencies. Instead, each -runtime dependency is considered a distinct artifact with its own threats. - -
- -## Availability threats - - - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA does not currently address availability threats, though future versions might. - -
Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, some -solutions to support hermetic and reproducible builds may also reduce the -impact of this threat. - -
-
De-list artifact - -*Threat:* The package registry stops serving the artifact. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
De-list provenance - -*Threat:* The package registry stops serving the provenance. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Verification threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above. - -
Tamper with recorded expectations - -*Threat:* Modify the verifier's recorded expectations, causing the verifier to -accept an unofficial package artifact. - -*Mitigation:* Changes to recorded expectations requires some form of -authorization, such as two-party review. - -*Example:* The package ecosystem records its expectations for a given package -name in a configuration file that is modifiable by that package's producer. The -configuration for MyPackage expects the source repository to be -`good/my-package`. The adversary modifies the configuration to also accept -`evil/my-package`, and then builds from that repository and uploads a malicious -version of the package. Solution: Changes to the recorded expectations require -two-party review. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Choose secure algorithms when using cryptographic digests, such -as SHA-256. - -*Examples:* Attacker crafts a malicious file with the same MD5 hash as a target -benign file. Attacker replaces the benign file with the malicious file. -Solution: Only accept cryptographic hashes with strong collision resistance. - -
- -
- - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively -[authentic]: build-requirements.md#provenance-authentic -[build-cache-poisoning-example]: https://adnanthekhan.com/2024/05/06/the-monsters-in-your-build-cache-github-actions-cache-poisoning/ -[exists]: build-requirements.md#provenance-exists -[isolated]: build-requirements.md#isolated -[unforgeable]: build-requirements.md#provenance-unforgeable -[secure-by-design]: https://www.cisa.gov/securebydesign -[supply chain threats]: threats-overview -[vsa]: verification_summary -[vsa_verification]: verification_summary#how-to-verify diff --git a/docs/spec/v1.2-rc2/tracks.md b/docs/spec/v1.2-rc2/tracks.md deleted file mode 100644 index 8c014fef1..000000000 --- a/docs/spec/v1.2-rc2/tracks.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Tracks -description: Provides an overview of each track and links to more specific information. ---- - -SLSA is composed of [multiple tracks](about#how-slsa-works) which are each -composed of multiple levels. Each track addresses different [threats](threats) -and has its own set of requirements and patterns of use. - -## Build Track - -The SLSA build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance. Provenance describes -what entity built the artifact, what process they used, and what the inputs -were. The lowest level only requires the provenance to exist, while higher -levels provide increasing protection against tampering of the build, the -provenance, or the artifact. - -The primary purpose of the build track is to enable -[verification](verifying-artifacts.md) that the artifact was built as expected. -Consumers have some way of knowing what the expected provenance should look like -for a given package and then compare each package artifact's actual provenance -to those expectations. Doing so prevents several classes of -[supply chain threats](threats.md). - -Each ecosystem (for open source) or organization (for closed source) defines -exactly how this is implemented, including: means of defining expectations, what -provenance format is accepted, whether reproducible builds are used, how -provenance is distributed, when verification happens, and what happens on -failure. Guidelines for implementers can be found in the -[requirements](build-requirements.md). - -- [Terminology](terminology.md) -- [Basics](build-track-basics.md) -- [Requirements](build-requirements.md) -- [Build provenance](build-provenance.md) -- [Assessing build platforms](assessing-build-platforms.md) - -## Source Track - -The SLSA source track provides producers and consumers with increasing levels of -trust in the source code they produce and consume. It describes increasing -levels of trustworthiness and completeness of how a source revision was created. - -The expected process for creating a new revision is determined solely by that -repository's owner (the organization) who also determines the intent of the -software in the repository and administers technical controls to enforce the -process. - -Consumers can review attestations to verify whether a particular revision meets -their standards. - -- [Requirements](source-requirements.md) -- [Source provenance](source-requirements#source-provenance-attestations) -- [Assessing source systems](assessing-source-systems.md) -- [Example controls](source-example-controls.md) diff --git a/docs/spec/v1.2-rc2/use-cases.md b/docs/spec/v1.2-rc2/use-cases.md deleted file mode 100644 index f3d53d55c..000000000 --- a/docs/spec/v1.2-rc2/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two-person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package registry. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build platforms rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor-provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on the trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor-provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified by a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.2-rc2/verification_summary.md b/docs/spec/v1.2-rc2/verification_summary.md deleted file mode 100644 index 1f0019bf3..000000000 --- a/docs/spec/v1.2-rc2/verification_summary.md +++ /dev/null @@ -1,432 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software producers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [resolvedDependencies](/build-provenance/v1#resolvedDependencies) of the -artifact being verified (recursively) or b) matching the non-source dependency -listed in `resolvedDependencies` (`subject.digest` == -`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` == -`resolvedDependencies.uri`) to a VSA _for that dependency_ and using -`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependencyLevels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "", - "version": { - "": "", - ... - } - }, - "timeVerified": , - "resourceUri": , - "policy": { - "uri": "", - "digest": { } - } - "inputAttestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verificationResult": "", - "verifiedLevels": [""], - "dependencyLevels": { - "": , - "": , - ... - }, - "slsaVersion": ".", -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`verifier.version` _map (string->string), optional_ - -> Map of names of components of the verification platform to their version. - - -`timeVerified` _string ([Timestamp]), optional_ - -> Timestamp indicating what time the verification occurred. - - -`resourceUri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. -> -> The `resourceUri` SHOULD be set to the URI from which the producer expects the -> consumer to fetch the artifact for verification. This enables the consumer to -> easily determine the expected value when [verifying](#how-to-verify). If the -> `resourceUri` is set to some other value, the producer MUST communicate the -> expected value, or how to determine the expected value, to consumers through -> an out-of-band channel. - - -`policy` _object ([ResourceDescriptor]), required_ - -> Describes the policy that the `subject` was verified against. -> -> The entry MUST contain a `uri` identifying which policy was applied and -> SHOULD contain a `digest` to indicate the exact version of that policy. - - -`inputAttestations` _array ([ResourceDescriptor]), optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `resolvedDependencies` field in [SLSA Provenance]. -> -> This field MAY be absent if the verifier does not support this feature. -> If non-empty, this field MUST contain information on _all_ the attestations -> used to perform verification. -> -> Each entry MUST contain a `digest` of the attestation and SHOULD contains a -> `uri` that can be used to fetch the attestation. - - -`verificationResult` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`verifiedLevels` _array ([SlsaResult]), required_ - -> Indicates the highest level of each track verified for the artifact (and not -> its dependencies) and any [verified properties](verified-properties) verified -> for the artifact or "FAILED" if policy verification failed. -> -> Users MUST NOT include more than one level per SLSA track. Note that each SLSA -> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies -> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to -> include more than one level per track. - - -`dependencyLevels` _object, optional_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. -> A set but empty `dependencyLevels` object means that the artifact has **no** -> dependency at all, while an unset or null `dependencyLevels` means that the -> verifier makes no claims about the artifact's dependencies. -> -> Users MUST count each dependency only once per SLSA track, at the highest -> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`, -> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for -> `SLSA_BUILD_LEVEL_1`. - - -`slsaVersion` _string, optional_ - -> Indicates the version of the SLSA specification that the verifier used, in the -> form `.`. Example: `1.0`. If unset, the default is an -> unspecified minor version of `1.x`. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier", - "version": { - "slsa-verifier-linux-amd64": "v2.3.0", - "slsa-framework/slsa-verifier/actions/installer": "v2.3.0" - } - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "inputAttestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_BUILD_LEVEL_3"], - "dependencyLevels": { - "SLSA_BUILD_LEVEL_3": 5, - "SLSA_BUILD_LEVEL_2": 7, - "SLSA_BUILD_LEVEL_1": 1, - }, - "slsaVersion": "1.0" -} -``` - -## How to verify - -VSA consumers use VSAs to accomplish goals based on delegated trust. We call the -process of establishing a VSA's authenticity and determining whether it meets -the consumer's goals 'verification'. Goals differ, as do levels of confidence -in VSA producers, so the verification procedure changes to suit its context. -However, there are certain steps that most verification procedures have in -common. - -Verification MUST include the following steps: - -1. Verify the signature on the VSA envelope using the preconfigured roots of - trust. This step ensures that the VSA was produced by a trusted producer - and that it hasn't been tampered with. - -2. Verify the statement's `subject` matches the digest of the artifact in - question. This step ensures that the VSA pertains to the intended artifact. - -3. Verify that the `predicateType` is - `https://slsa.dev/verification_summary/v1`. This step ensures that the - in-toto predicate is using this version of the VSA format. - -4. Verify that the `verifier` matches the public key (or equivalent) used to - verify the signature in step 1. This step identifies the VSA producer in - cases where their identity is not implicitly revealed in step 1. - -5. Verify that the value for `resourceUri` in the VSA matches the expected - value. This step ensures that the consumer is using the VSA for the - producer's intended purpose. - -6. Verify that the value for `verificationResult` is `PASSED`. This step - ensures the artifact is suitable for the consumer's purposes. - -7. Verify that `verifiedLevels` contains the expected value. This step ensures - that the artifact is suitable for the consumer's purposes. - -Verification MAY additionally contain the following step: - -1. (Optional) Verify additional fields required to determine whether the VSA - meets your goal. - -Verification mitigates different threats depending on the VSA's contents and the -verification procedure. - -IMPORTANT: A VSA does not protect against compromise of the verifier, such as by -a malicious insider. Instead, VSA consumers SHOULD carefully consider which -verifiers they add to their roots of trust. - -### Examples - -1. Suppose consumer C wants to delegate to verifier V the decision for whether - to accept artifact A as resource R. Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` contains `SLSA_BUILD_LEVEL_UNEVALUATED`. - - Note: This example is analogous to traditional code signing. The expected - value for `verifiedLevels` is arbitrary but prenegotiated by the producer and - the consumer. The consumer does not need to check additional fields, as C - fully delegates the decision to V. - -2. Suppose consumer C wants to enforce the rule "Artifact A at resource R must - have a passing VSA from verifier V showing it meets SLSA Build Level 2+." - Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` is `SLSA_BUILD_LEVEL_2` or `SLSA_BUILD_LEVEL_3`. - - Note: In this example, verifying the VSA mitigates the same threats as - verifying the artifact's SLSA provenance. See - [Verifying artifacts](/spec/v1.0/verifying-artifacts) for details about which - threats are addressed by verifying each SLSA level. - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -SHOULD be - -- The [SLSA Track](#tracks) level the referenced artifact qualifies for as -`SLSA__LEVEL_`, or -- `SLSA__LEVEL_UNEVALUATED` if the VSA issuer does not want to - make a claim about the track level an artifact meets - -For example: - -- `SLSA_BUILD_LEVEL_UNEVALUATED` -- `SLSA_BUILD_LEVEL_0` -- `SLSA_BUILD_LEVEL_3` -- `SLSA_SOURCE_LEVEL_2` -- `SLSA_SOURCE_LEVEL_4` -- `FAILED` (Indicates policy evaluation failed) - -Note that each SLSA level implies the levels below it in the same track. -For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` + -`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`). - -Users MAY use custom values here but MUST NOT use custom values starting with -`SLSA_`. - -## Change history - -- 1.2: - - Update SlsaResult definition to discuss how to refer to new tracks and - link to [verified properties](verified-properties) for additional SLSA - endorsed values. - - Fixed a typo where the verificationResult was incorrectly referred to - as slsaResult. -- 1.1: - - Changed the `policy` object to recommend that the `digest` field of - the `ResourceDescriptor` is set. - - Added optional `verifier.version` field to record verification tools. - - Added Verification section with examples. - - Made `timeVerified` optional. -- 1.0: - - Replaced `materials` with `resolvedDependencies`. - - Relaxed `SlsaResult` to allow other values. - - Converted to lowerCamelCase for consistency with [SLSA Provenance]. - - Added `slsaVersion` field. -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SLSA Provenance]: /provenance -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/digest_set.md -[ResourceURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#resourceuri -[ResourceDescriptor]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/resource_descriptor.md -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[Timestamp]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules diff --git a/docs/spec/v1.2-rc2/verifying-artifacts.md b/docs/spec/v1.2-rc2/verifying-artifacts.md deleted file mode 100644 index 0961a19ed..000000000 --- a/docs/spec/v1.2-rc2/verifying-artifacts.md +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: "Build: Verifying artifacts" -description: SLSA uses provenance to indicate whether an artifact is authentic or not, but provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection verification, and this page describes how to verify artifacts and their SLSA provenance. The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that -inspection **verification**, and this page describes recommendations for how to -verify artifacts and their SLSA provenance. - -This page is divided into several sections. The first describes the process -for verifying an artifact and its provenance against a set of expectations. The -second describes how to form the expectations used to verify provenance. The -third discusses architecture choices for where provenance verification can -happen. - -## How to verify - -Verification SHOULD include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- Verifying the signature on the provenance envelope. -- Ensuring that the values for `buildType` and `externalParameters` in the - provenance match the expected values. The package ecosystem MAY allow - an approved list of `externalParameters` to be ignored during verification. - Any unrecognized `externalParameters` SHOULD cause verification to fail. - -![Threats covered by each step](images/supply-chain-threats-build-verification.svg) - -See [Terminology](terminology.md) for an explanation of the supply chain model and -[Threats & mitigations](threats.md) for a detailed explanation of each threat. - -**Note:** This section assumes that the provenance is in the recommended -[provenance format](/provenance/v1). If it is not, then the verifier SHOULD -perform equivalent checks on provenance fields that correspond to the ones -referenced here. - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "E", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This configuration - is likely in the form of a map from (builder public key identity, - `builder.id`) to (SLSA Build level). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the artifact in question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "E"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Assessing build platforms](assessing-build-platforms.md). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "I".) -- [Threat "I"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not yet cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. Those threats are - discussed in more detail under [Threat "H"]. - -[Threat "E"]: threats#e-build-process -[Threat "F"]: threats#f-artifact-publication -[Threat "G"]: threats#g-distribution-channel -[Threat "H"]: threats#h-package-selection -[Threat "I"]: threats#i-usage - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets your expectations for that -package in order to mitigate [threat "D"]. - -In our threat model, the adversary has the ability to invoke a build and to publish -to the registry. The adversary is not able to write to the source repository, nor do -they have insider access to any trusted systems. Your expectations SHOULD be -sufficient to detect or prevent this adversary from injecting unofficial -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 - -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 -range of values (possibly any value) if it is known that any value in the range -is safe. JSON comparison is sufficient for verifying parameters. - -TIP: Difficulty in forming meaningful expectations about `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "D"]: threats#d-external-build-parameters - -### Step 3: (Optional) Check dependencies recursively - -[verify-step-3]: #step-3-optional-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. Note that SLSA v1.0 does not have any requirements on the -completeness or verification of `resolvedDependencies`. However, one might wish -to verify dependencies in order to mitigate [dependency threats] and protect against -threats further up the supply chain. If `resolvedDependencies` is incomplete, -these checks can be done on a best-effort basis. - -A [Verification Summary Attestation (VSA)][VSA] can make dependency verification -more efficient by recording the result of prior verifications. A trimming -heuristic or exception mechanism is almost always necessary when verifying -dependencies because there will be transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) - -[dependency threats]: threats#dependency-threats -[VSA]: /verification_summary -[threats]: threats - -## Forming Expectations - -Expectations are known provenance values that indicate the -corresponding artifact is authentic. For example, a package ecosystem may -maintain a mapping between package names and their canonical source -repositories. That mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git branches or tags. - -- **Defined by producer:** The package producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the package's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -- **Defined in source:** The source repository tells the verifier what their - expectations ought to be. In this model, the package name is immutably bound - to a source repository and all other external parameters are defined in the - source repository. This is how the Go ecosystem works, for example, since - the package name *is* the source repository location. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -will likely have different artifacts and therefore different provenance. Similarly, an -artifact might have different names in different package ecosystems but use the same -provenance file. - -## Architecture options - -There are several options (non-mutually exclusive) for where provenance verification -can happen: the package ecosystem at upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify provenance. For example, even if a package -ecosystem verifies provenance, consumers who get artifacts from that package -ecosystem might wish to verify provenance themselves for defense in depth. They -can do so using either client-side verification tooling or by polling a -monitor. - - - -### Package ecosystem - -[Package ecosystem]: #package-ecosystem - -A package ecosystem is a set of rules and conventions governing -how packages are distributed. Every package artifact has an ecosystem, whether it is -formal or ad-hoc. Some ecosystems are formal, such as language distribution -(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". For more background, see -[Package Model](terminology.md#package-model). - -During package upload, a package ecosystem can ensure that the artifact's -provenance matches the expected values for that package name's provenance before -accepting it into the package registry. This option is RECOMMENDED whenever -possible because doing so benefits all of the package ecosystem's clients. - -The package ecosystem is responsible for making its expectations available to -consumers, reliably redistributing artifacts and provenance, and providing tools -to enable safe artifact consumption (e.g. whether an artifact meets -expectations). - -### Consumer - -[Consumer]: #consumer - -A package artifact's consumer is the organization or individual that uses the -package artifact. - -Consumers can form their own expectations for artifacts or use the default -expectations provided by the package producer and/or package ecosystem. -When forming their own expectations, the consumer uses client-side verification tooling to ensure -that the artifact's provenance matches their expectations for that package -before use (e.g. during installation or deployment). Client-side verification -tooling can be either standalone, such as -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into -the package ecosystem client. - -### Monitor - -[Monitor]: #monitor - -A monitor is a service that verifies provenance for a set -of packages and publishes the result of that verification. The set of -packages verified by a monitor is arbitrary, though it MAY mimic the set -of packages published through one or more package ecosystems. The monitor -SHOULD publish its expectations for all the packages it verifies. - -Consumers can continuously poll a monitor to detect artifacts that -do not meet the monitor's expectations. Detecting artifacts that fail -verification is of limited benefit unless a human or automated system takes -action in response to the failed verification. diff --git a/docs/spec/v1.2-rc2/verifying-source.md b/docs/spec/v1.2-rc2/verifying-source.md deleted file mode 100644 index 5d43abb1b..000000000 --- a/docs/spec/v1.2-rc2/verifying-source.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: "Source: Verifying source" -description: | - SLSA uses attestations to indicate security claims associated with a repository revision, but attestations don't do anything unless somebody inspects them. - SLSA calls that inspection verification, and this page describes how to verify properties of source revisions using their SLSA source provenance attestations. - The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses attestations to indicate security claims associated with a repository -revision, but attestations don't do anything unless somebody inspects them. SLSA -calls that inspection **verification**, and this page describes how to verify -properties of source revisions using -[the attestations](source-requirements#communicating-source-levels) associated -with those revisions. - -At Source L3+, Source Control Systems (SCSs) issue detailed -[provenance attestations](source-requirements#source-provenance-attestations) of -the process that was used to create specific revisions of a repository. These -provenance attestations are issued in bespoke formats and may be too burdensome -to use in some use cases. - -[Source Verification Summary Attestations](source-requirements#source-verification-summary-attestation) -(Source VSAs) address this, making verification more efficient and ergonomic by -recording the result of prior verifications. Source VSAs may be issued by a VSA -provider to make a SLSA source level determination based on the content of those -attestations. - -## How to verify a source revision - -The source consumer checks: - -1. If they trust the SCS that issued the VSA and if the VSA applies to the - revision they've fetched. -2. If the claims made in the VSA match their expectations for how the source - should be managed. -3. (Optional): If the evidence presented in the source provenance matches the - claims made in the VSA. - -### Step 1: Check the SCS - -First, check the SLSA Source level by comparing the artifact to its VSA and the -VSA to a preconfigured root of trust. The goal is to ensure that the VSA -actually applies to the artifact in question and to assess the trustworthiness -of the VSA. This mitigates threats within "B" and "C", depending on SLSA Source -level. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized SCS - identities and the maximum SLSA Source level each SCS is trusted up to. - Different verifiers MAY use different roots of trust for repositories. The - root of trust configuration is likely in the form of a map from (SCS public - key identity, VSA `verifier.id`) to (SLSA Source level). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaSourceRootsOfTrust": [ - // A SCS trusted at SLSA Source L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "scsId": "https://somescs.example.com/slsa/l3", - "slsaSourceLevel": 3 - }, - // A different SCS that claims to be SLSA Source L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "scsId": "https://differentscs.example.com/slsa/l3", - "slsaSourceLevel": 2 - }, - // A SCS that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@refs/tags/v*.*.*" - }, - "scsId": "https://github.com/slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@refs/tags/v*.*.*", - "slsaSourceLevel": 3, - } - ... - ], - ``` - -
- -Given a revision and its VSA follow the -[VSA verification instructions](./verification_summary.md#how-to-verify) and the -[validation-model] using the revision identifier to perform subject matching and -checking the `verifier.id` against the root-of-trust described above. - -### Step 2: Check Expectations - -Next, check that the revision's VSA meets your expectations in order to mitigate -[threat "B"]. - -In our threat model, the adversary has the ability to create revisions within -the repository and get consumers to fetch that revision. The adversary is not -able to subvert controls implemented by the Producer and enforced by the SCS. -Your expectations SHOULD be sufficient to detect an un-official revision and -SHOULD make it more difficult for an adversary to create a malicious official -revision. - -You SHOULD compare the VSA against expected values for at least the following -fields: - -| What | Why -| ---- | --- -| `verifier.id` identity from [Step 1] | To prevent an adversary from substituting a VSA making false claims from an unintended SCS. -| `subject.digest` from [Step 1] | To prevent an adversary from substituting a VSA from another revision. -| `verificationResult` | To prevent an adversary from providing a VSA for a revision that failed some aspect of the organization's expectations. -| `predicate.resourceUri` | To prevent an adversary from substituting a VSA for the intended repository (e.g. `git+https://github.com/IntendedOrg/hello-world`) for another (e.g. `git+https://github.com/AdversaryOrg/hello-world`) -| `subject.annotations.sourceRefs` | To prevent an adversary from substituting the intended revision from one branch (e.g. `release`) with another (e.g. `experimental_auth`). -| `verifiedLevels` | To ensure the expected controls were in place for the creation of the revision. E.g. `SLSA_SOURCE_LEVEL_3`, `ORG_SOURCE_STATIC_ANALYSIS`, etc... - -[Threat "B"]: threats#b-modifying-the-source -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 3: Verify Evidence using Source Provenance [optional] - -Optionally, at SLSA Source Level 3 and up, check the [source provenance -attestations](source-requirements#source-provenance-attestations) directly. - -As the format and implementation of source provenance attestations are left to -the SCS, you SHOULD form expectations about the claims in source provenance -attestations and how they map to a revision's properties claimed in its VSA in -conjunction with the SCS and the producer. - -## Forming Expectations - -Expectations are known values that indicate the corresponding -revision is authentic. For example, an SCS may maintain a mapping between -repository branches & tags and the controls they claim to implement. That -mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the revision as-is. On - each update, compare the old VSA to the new VSA and alert on any - differences. - -- **Defined by producer:** The revision producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the revision's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -It is important to note that expectations are tied to a *repository branch or -tag*, whereas a VSA is tied to an *revision*. Different revisions will have -different VSAs and the claims made by those VSAs may differ. - -## Architecture options - -There are several options (non-mutually exclusive) for where VSA verification -can happen: the build system at source fetch time, the package ecosystem at -build artifact upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify VSAs. For example, even if a builder verifies -source VSAs, package ecosystems may wish to verify the source VSAs for the -artifacts they host that claim to be built from that source (as indicated by the -build provenance). diff --git a/docs/spec/v1.2-rc2/whats-new.md b/docs/spec/v1.2-rc2/whats-new.md deleted file mode 100644 index 30d625d0a..000000000 --- a/docs/spec/v1.2-rc2/whats-new.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: What's new -description: The changes brought by SLSA 1.2 RC2. ---- - -This document describes the major changes brought by SLSA 1.2 RC2 relative to -the prior release [v1.1] and the prior release candidate [v1.2 RC1]. - -## Summary of changes since v1.2 RC1 - -- Improved instructions for verifying source VSAs. -- Reorganized the Source Track levels. Level 2 now focuses on history and - provenance while Level 3 focuses on continuous enforcement of technical - controls. -- Moved example source controls to [their own page](source-example-controls). -- Minor copy editing improvements. - -## Summary of changes since v1.1 - -- Addition of the [Source Track](source-requirements) which helps - organizations secure their source code development process and consumers - establish trust in that source. -- Updated the [threat model](threats) to account for the threats mitigated by - the Source Track. -- Improved the structure of the spec to accommodate multiple tracks. - - - -[v1.1]: /spec/v1.1/ -[v1.2 RC1]: /spec/v1.2-rc1/ diff --git a/docs/spec/v1.2/about.md b/docs/spec/v1.2/about.md deleted file mode 100644 index a763594e7..000000000 --- a/docs/spec/v1.2/about.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: About SLSA -description: With supply chain attacks on the rise, a shared vocabulary and universal framework are needed to provide incremental guidance to harden supply chains for more secure software production. This page introduces the main concepts behind SLSA and explains how it can help anyone involved in producing, consuming, or providing infrastructure for software. ---- - -This page is an introduction to SLSA and its concepts. If you're new -to SLSA, start here! - -## What is SLSA? - -Supply-chain Levels for Software Artifacts, or SLSA ("salsa"), is a set of incrementally adoptable guidelines for supply chain security, -established by industry consensus. The specification set by SLSA is useful for -both software producers and consumers: producers can follow SLSA's guidelines to -make their software supply chain more secure, and consumers can use SLSA to make -decisions about whether to trust a software package. - -SLSA offers: - -- A common vocabulary to talk about software supply chain security -- A way to secure your incoming supply chain by evaluating the trustworthiness of the artifacts you consume -- An actionable checklist to improve your own software's security -- A way to measure your efforts toward compliance with the [Secure Software Development Framework (SSDF)](https://csrc.nist.gov/Projects/ssdf) - -## Why SLSA is needed - -High-profile attacks like those against [SolarWinds](https://www.crowdstrike.com/blog/sunspot-malware-technical-analysis/) or [Codecov](https://about.codecov.io/apr-2021-post-mortem/) have exposed the kind of supply -chain integrity weaknesses that may go unnoticed, yet quickly become very -public, disruptive, and costly in today's environment when exploited. They've -also shown that there are inherent risks not just in code itself, but at -multiple points in the complex process of getting that code into software -systems—that is, in the **software supply chain**. Since these attacks are on -the rise and show no sign of decreasing, a universal framework for hardening the -software supply chain is needed, as affirmed by the U.S. Executive Order on -Improving the Nation's Cybersecurity of May 12th, 2021. - -Security techniques for vulnerability detection and analysis of source code are -essential, but are not enough on their own. Even after fuzzing or vulnerability -scanning is completed, changes to code can happen, whether unintentionally or -from insider threats or compromised accounts. Risk for code modification exists at -each link in a typical software supply chain, from source to build through -packaging and distribution. Any weaknesses in the supply chain undermine -confidence in whether the code that you run is actually the code that you -scanned. - -SLSA is designed to support automation that tracks code handling from source -to binary, protecting against tampering regardless of the complexity -of the software supply chain. As a result, SLSA increases trust that the -analysis and review performed on source code can be assumed to still apply to -the binary consumed after the build and distribution process. - -## SLSA in layperson's terms - -There has been a [lot of discussion](https://ntia.gov/page/software-bill-materials) about the need for "ingredient labels" for -software—a "software bill of materials" (SBOM) that tells users what is in their -software. Building off this analogy, SLSA can be thought of as all the food -safety handling guidelines that make an ingredient list credible. From standards -for clean factory environments so contaminants aren't introduced in packaging -plants, to the requirement for tamper-proof seals on lids that ensure nobody -changes the contents of items sitting on grocery store shelves, the entire food -safety framework ensures that consumers can trust that the ingredient list -matches what's actually in the package they buy. - -Likewise, the SLSA framework provides this trust with guidelines and -tamper-resistant evidence for securing each step of the software production -process. That means you know not only that nothing unexpected was added to the -software product, but also that the ingredient label itself wasn't tampered with -and accurately reflects the software contents. In this way, SLSA helps protect -against the risk of: - -- Code modification (by adding a tamper-evident "seal" to code after - source control) -- Uploaded artifacts that were not built by the expected CI/CD platform (by marking - artifacts with a factory "stamp" that shows which build platform created it) -- Threats against the build platform (by providing "manufacturing facility" - best practices for build platform services) - -For more exploration of this analogy, see the blog post -[SLSA + SBOM: Accelerating SBOM success with the help of SLSA](/blog/2022/05/slsa-sbom). - -## Who is SLSA for? - -In short: everyone involved in producing and consuming software, or providing -infrastructure for software. - -**Software producers**, such as an open source project, a software vendor, or a -team writing first-party code for use within the same company. SLSA gives you -protection against tampering along the supply chain to your consumers, both -reducing insider risk and increasing confidence that the software you produce -reaches your consumers as you intended. - -**Software consumers**, such as a development team using open source packages, a -government agency using vendored software, or a CISO judging organizational -risk. SLSA gives you a way to judge the security practices of the software you -rely on and be sure that what you receive is what you expected. - -**Infrastructure providers**, who provide infrastructure such as an ecosystem -package manager, build platform, or CI/CD platform. As the bridge between the -producers and consumers, your adoption of SLSA enables a secure software supply -chain between them. - -## How SLSA works - -We talk about SLSA in terms of [tracks and levels](tracks.md). -A SLSA track focuses on a particular aspect of a supply chain, such as the Build -Track. - -Within each track, ascending levels indicate increasingly hardened security -practices. Higher levels provide better guarantees against supply chain threats, -but come at higher implementation costs. Lower SLSA levels are designed to be -easier to adopt, but with only modest security guarantees. SLSA 0 is sometimes -used to refer to software that doesn't yet meet any SLSA level. Currently, the -SLSA Build Track encompasses Levels 1 through 3, but we envision higher levels -to be possible in [future revisions](future-directions.md). - -The combination of tracks and levels offers an easy way to discuss whether -software meets a specific set of requirements. By referring to an artifact as -meeting SLSA Build Level 3, for example, you're indicating in one phrase that -the software artifact was built following a set of security practices that -industry leaders agree protect against particular supply chain compromises. - -## What SLSA doesn't cover - -SLSA is only one part of a thorough approach to supply chain security. There -are several areas outside SLSA's current framework that are nevertheless -important to consider together with SLSA such as: - -- Code quality: SLSA does not tell you whether the developers writing the - source code followed secure coding practices. -- Producer trust: SLSA does not address organizations that intentionally - produce malicious software, but it can reduce insider risks within an - organization you trust. -- Transitive trust for dependencies: the SLSA level of an artifact is - independent of the level of its dependencies. You can use SLSA recursively to - also judge an artifact's dependencies on their own, but there is - currently no single SLSA level that applies to both an artifact and its - transitive dependencies together. For a more detailed explanation of why, - see the [FAQ](faq#q-why-is-slsa-not-transitive). diff --git a/docs/spec/v1.2/assessing-build-platforms.md b/docs/spec/v1.2/assessing-build-platforms.md deleted file mode 100644 index dd17f3a0b..000000000 --- a/docs/spec/v1.2/assessing-build-platforms.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: "Build: Assessing build platforms" -description: Guidelines for assessing build platform security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust platforms to produce Build L3 -artifacts and provenance unless they have some proof that the provenance is -[unforgeable](build-requirements.md#provenance-unforgeable) and the builds are -[isolated](build-requirements.md#isolated). - -This page describes the parts of a build platform that consumers SHOULD assess -and provides sample questions consumers can ask when assessing a build platform. -See also [Threats & mitigations](threats.md) and the -[build model](terminology.md#build-model). - -## Threats - -### Adversary goal - -The SLSA Build track defends against an adversary whose primary goal is to -inject unofficial behavior into a package artifact while avoiding detection. -Remember that [verifiers](verifying-artifacts.md) only accept artifacts whose -provenance matches expectations. To bypass this, the adversary tries to either -(a) tamper with a legitimate build whose provenance already matches -expectations, or (b) tamper with an illegitimate build's provenance to make it -match expectations. - -More formally, if a build with external parameters P would produce an artifact -with binary hash X and a build with external parameters P' would produce an -artifact with binary hash Y, they wish to produce provenance indicating a build -with external parameters P produced an artifact with binary hash Y. - -See threats [D], [E], [F], and [G] for examples of specific threats. - -Note: Platform abuse (e.g. running non-build workloads) and attacks against -builder availability are out of scope of this document. - -### Adversary profiles - -Consumers SHOULD also evaluate the build platform's ability to defend against the -following types of adversaries. - -1. Project contributors, who can: - - Create builds on the build platform. These are the adversary's controlled - builds. - - Modify one or more controlled builds' external parameters. - - Modify one or more controlled builds' environments and run arbitrary - code inside those environments. - - Read the target build's source repo. - - Fork the target build's source repo. - - Modify a fork of the target build's source repo and build from it. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Create new builds under the target build's project or identity. - - Modify the target build's source repo and build from it. - - Modify the target build's configuration. -3. Build platform administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Run arbitrary code on the build platform. - - Read and modify network traffic. - - Access the control plane's cryptographic secrets. - - Remotely access build environments (e.g. via SSH). - -[D]: threats.md#d-external-build-parameters -[E]: threats.md#e-build-process -[F]: threats.md#f-artifact-publication -[G]: threats.md#g-distribution-channel - -## Build platform components - -Consumers SHOULD consider at least these five elements of the -[build model](terminology.md#build-model) when assessing build platforms for SLSA -conformance: external parameters, control plane, build environments, caches, -and outputs. - -![image](images/build-model.svg) - -The following sections detail these elements of the build model and give prompts -for assessing a build platform's ability to produce SLSA Build L3 provenance. -The assessment SHOULD take into account the security model used to identify the -transitive closure of the `builder.id` for the -[provenance model](build-provenance.md#model), specifically around the -platform's boundaries, actors, and interfaces. - -### External parameters - -External parameters are the external interface to the builder and include all -inputs to the build process. Examples include the source to be built, the build -definition/script to be executed, user-provided instructions to the -control plane for how to create the build environment (e.g. which operating -system to use), and any additional user-provided strings. - -#### Prompts for assessing external parameters - -- How does the control plane process user-provided external parameters? - Examples: sanitizing, parsing, not at all -- Which external parameters are processed by the control plane and which are - processed by the build environment? -- What sort of external parameters does the control plane accept for - build environment configuration? -- How do you ensure that all external parameters are represented in the - provenance? -- How will you ensure that future design changes will not add additional - external parameters without representing them in the provenance? - -### Control plane - -The control plane is the build platform component that orchestrates each -independent build execution. It is responsible for setting up each build and -cleaning up afterwards. At SLSA Build L2+ the control plane generates and signs -provenance for each build performed on the build platform. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -#### Prompts for assessing the control plane - -- Administration - - What are the ways an employee can use privileged access to influence a - build or provenance generation? Examples: physical access, terminal - access, access to cryptographic secrets - - What controls are in place to detect or prevent the employee from - abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many employees have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and platform - outages? Are they tested? How frequently? - -- Provenance generation - - How does the control plane observe the build to ensure the provenance's - accuracy? - - Are there situations in which the control plane will not generate - provenance for a completed build? What are they? - -- Development practices - - How do you track the control plane's software and configuration? - Example: version control - - How do you build confidence in the control plane's software supply - chain? Example: SLSA L3+ provenance, build from source - - How do you secure communications between builder components? Example: - TLS with certificate transparency. - - Are you able to perform forensic analysis on compromised build - environments? How? Example: retain base images indefinitely - -- Creating build environments - - How does the control plane share data with build environments? Example: - mounting a shared file system partition - - How does the control plane protect its integrity from build - environments? Example: not mount its own file system partitions on - build environments - - How does the control plane prevent build environments from accessing its - cryptographic secrets? Examples: dedicated secret storage, not mounting - its own file system partitions to build environments, hardware security - modules - -- Managing cryptographic secrets - - How do you store the control plane's cryptographic secrets? - - Which parts of the organization have access to the control plane's - cryptographic secrets? - - What controls are in place to detect or prevent employees abusing such - access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Build environment - -The build environment is the independent execution context where the build -takes place. In the case of a distributed build, the build environment is the -collection of all execution contexts that run build steps. Each build -environment must be isolated from the control plane and from all other build -environments, including those running builds from the same tenant or project. -Tenants are free to modify the build environment arbitrarily. Build -environments must have a means to fetch input artifacts (source, dependencies, -etc). - -#### Prompts for assessing build environments - -- Isolation technologies - - How are build environments isolated from the control plane and each - other? Examples: VMs, containers, sandboxed processes - - How is separation achieved between trusted and untrusted processes? - - How have you hardened your build environments against malicious tenants? - Examples: configuration hardening, limiting attack surface - - How frequently do you update your isolation software? - - What is your process for responding to vulnerability disclosures? What - about vulnerabilities in your dependencies? - - What prevents a malicious build from gaining persistence and influencing - subsequent builds? - -- Creation and destruction - - What operating system and utilities are available in build environments - on creation? How were these elements chosen? Examples: A minimal Linux - distribution with its package manager, OSX with HomeBrew - - How long could a compromised build environment remain active in the - build platform? - -- Network access - - Are build environments able to call out to remote execution? If so, how - do you prevent them from tampering with the control plane or other build - environments over the network? - - Are build environments able to open services on the network? If so, how - do you prevent remote interference through these services? - -### Cache - -Builders may have zero or more caches to store frequently used dependencies. -Build environments may have either read-only or read-write access to caches. - -#### Prompts for assessing caches - -- What sorts of caches are available to build environments? -- How are those caches populated? -- How are cache contents validated before use? - -### Output storage - -Output Storage holds built artifacts and their provenance. Storage may either be -shared between build projects or allocated separately per-project. - -#### Prompts for assessing output storage - -- How do you prevent builds from reading or overwriting files that belong to - another build? Example: authorization on storage -- What processing, if any, does the control plane do on output artifacts? - -## Builder evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model defined as -part of the provenance. Evidence submitted for third-party certification need not -be published. diff --git a/docs/spec/v1.2/assessing-source-systems.md b/docs/spec/v1.2/assessing-source-systems.md deleted file mode 100644 index 0ad3ecba3..000000000 --- a/docs/spec/v1.2/assessing-source-systems.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: "Source: Assessing source control systems" -description: Guidelines for assessing source control system security. ---- - -One of SLSA's guiding [principles](principles.md) is to "trust platforms, verify -artifacts". However, consumers cannot trust source control systems (SCSs) unless -they have some proof that an SCS meets its -[requirements](source-requirements.md). - -This page describes the parts of an SCS that consumers SHOULD assess and -provides sample questions consumers can ask when assessing a SCS. See also -[Threats & mitigations](threats.md). - -## Threats - -### Adversary goal - -The SLSA Source track defends against an adversary whose primary goal is to -inject unofficial behavior into protected source code while avoiding detection. -Organizations typically establish change management processes to prevent this -unofficial behavior from being introduced. The adversary's goal is to bypass the -change management process. - -### Adversary profiles - -Consumers SHOULD also evaluate the source control systems' ability to defend -against the following types of adversaries. - -1. Project contributors, who can: - - Propose changes to protected branches of the source repo. - - Upload new content to the source repo. -2. Project maintainer, who can: - - Do everything listed under "project contributors". - - Define the purpose of the source repo. - - Add or remove contributors to the source repo. - - Add or remove permissions granted to contributors of the source repo. - - Modify security controls within the source repo. - - Modify controls used to enforce the change management process on the - source repo. -3. Source control system administrators, who can: - - Do everything listed under "project contributors" and "project - maintainers". - - Modify the source repo while bypassing the project maintainer's controls. - - Modify the behavior of the Source Control System itself. - - Access the control plane's cryptographic secrets. - -## Source Control System components - -Consumers SHOULD consider at least these elements when assessing a Source -Control System for SLSA conformance: control configuration, change management -interface, control plane, verifier, storage. - -![source control system components](images/source-control-system-components.svg) - -The following section details these elements. - -### Change management interface - -The change management interface is the user interface for proposing and -approving changes to protected branches within a source repository. During -normal operation all such changes go through this interface. - -### Control configuration - -Control configuration is how organizations establish technical controls in a -given source repository. If done well the configuration will reflect the intent -of the organization. - -### Technical controls - -Technical controls are the organization configured settings that are used to -determine if a revision can be introduced into storage within any particular -context and who has access to those revisions. - -The technical controls component is responsible for the storage of these -settings while the [control plane](#control-plane) is responsible for enforcing -the configured controls. - -They include: - -- Read/write ACLs, -- If approvals are required to introduce changes within a given context -- Which actors are allowed to issue those approvals -- Organization defined - [change management processes](#enforced-change-management-process) - requirements -- etc... - -### Control plane - -The control plane is the SCS component that orchestrates the introduction and -creation of new revisions into a source repository. It is responsible for -enforcing [technical controls](#technical-controls) and, at SLSA Source L3+, -generating and signing source provenance for each revision. The control plane is -operated by one or more administrators, who have privileges to modify the -control plane. - -### Verifier - -The verifier is the SCS component that evaluates source provenance and generates -and signs a -[verification summary attestation](source-requirements#summary-attestation) -(VSA). - -### Storage - -Storage holds source revisions and their provenance and summary attestations. - -## Assessing components - -The following are prompts for assessing a Source Control System's ability to -meet the SLSA requirements. - -### Prompts for assessing the change management interface - -- How does the SCS manage which actors are permitted to approve changes? -- What types of non-plain-text changes can the change management interface - render? How well does the SCS render those changes? -- What controls does the change management interface provide for enabling - Trusted Robot Contributions? Example: SLSA Build L3+ provenance, built from - SLSA Source L4+ source. - -### Prompts for assessing control configuration & technical controls - -- How does the SCS prevent regression in control configurations? - Examples: built-in controls that cannot change, notifying project - maintainers when controls change, requiring public declaration of control - changes. -- How does the SCS prevent individual project maintainers from tampering with - controls configured by the project? -- How does the SCS prevent SCS administrators from tampering with a project's - configured technical controls? - -### Prompts for assessing the control plane & verifier - -NOTE The control plane and verifier perform related roles within the SCS and -should typically be assessed together. - -- Administration - - What are the ways an SCS administrator can use privileged access to - influence a revision creation, provenance generation, or VSA generation? - Examples: physical access, terminal access, access to cryptographic - secrets - - What controls are in place to detect or prevent an SCS administrator - from abusing such access? Examples: two-person approvals, audit logging, - workload identities - - Roughly how many SCS maintainers have such access? - - How are privileged accounts protected? Examples: two-factor - authentication, client device security policies - - What plans do you have for recovering from security incidents and - platform outages? Are they tested? How frequently? - -- Control effectiveness - - How does the SCS ensure the control plane is enforcing the - [technical controls](#technical-controls) are working as intended? - -- Source provenance generation - - How does the control plane observe the revision creation to ensure the - provenance's accuracy? - - Are there situations in which the control plane will not generate - source provenance? What are they? - - What details are included in the source provenance? Are they sufficient - to mitigate tampering with other SCS components? - -- VSA generation - - How does the verifier determine what source level a revision meets? - - How does the verifier determine the organization's control expectations - and if they are met? - -- Development practices - - How do you track the control plane and verifier's software and - configuration? - Example: version control. - - How do you build confidence in the control plane's software supply - chain? Example: SLSA Build L3+ provenance, built from SLSA Source L4+ - source. - - How do you secure communications between components? Example: TLS with - certificate transparency. - -- Managing cryptographic secrets - - How do you store the control plane and verifier's cryptographic secrets? - - Which parts of the organization have access to the control plane and - verifier's cryptographic secrets? - - What controls are in place to detect or prevent SCS administrators from - abusing such access? Examples: two-person approvals, audit logging - - How are secrets protected in memory? Examples: secrets are stored in - hardware security modules and backed up in secure cold storage - - How frequently are cryptographic secrets rotated? Describe the rotation - process. - - What is your plan for remediating cryptographic secret compromise? How - frequently is this plan tested? - -### Prompts for assessing output storage - -- How do you prevent tampering with storage directly? -- How do you prevent one project's revisions from affecting another project? - -## Source control system evaluation - -Organizations can either self-attest to their answers or seek certification from -a third-party auditor. Evidence for self-attestation should be published on -the internet and can include information such as the security model used in the -evaluation. Evidence submitted for third-party certification need not be -published. diff --git a/docs/spec/v1.2/attestation-model.md b/docs/spec/v1.2/attestation-model.md deleted file mode 100644 index 105cd9409..000000000 --- a/docs/spec/v1.2/attestation-model.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Software attestations -description: A software attestation is an authenticated statement (metadata) about a software artifact or collection of software artifacts. The primary intended use case is to feed into automated policy engines, such as in-toto and Binary Authorization. This page provides a high-level overview of the attestation model, including standardized terminology, data model, layers, and conventions for software attestations. -layout: specifications ---- - -A software attestation is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. -The primary intended use case is to feed into automated policy engines, such as -[in-toto] and [Binary Authorization]. - -This page provides a high-level overview of the attestation model, including -standardized terminology, data model, layers, conventions for software -attestations, and formats for different use cases. - -## Overview - -A **software attestation**, not to be confused with a [remote attestation] in -the trusted computing world, is an authenticated statement (metadata) about a -software artifact or collection of software artifacts. Software attestations -are a generalization of raw artifact/code signing. - -With raw signing, a signature is directly over the artifact (or a hash of the -artifact) and *implies* a single bit of metadata about the artifact, based on -the public key. The exact meaning MUST be negotiated between signer and -verifier, and a new keyset MUST be provisioned for each bit of information. For -example, a signature might denote who produced an artifact, or it might denote -fitness for some purpose, or something else entirely. - -With an attestation, the metadata is *explicit* and the signature only denotes -who created the attestation (authenticity). A single keyset can express an -arbitrary amount of information, including things that are not possible with -raw signing. For example, an attestation might state exactly how an artifact -was produced, including the build command that was run and all of its -dependencies (as in the case of SLSA [Provenance]). - -## Formats - -This section explains how to choose the attestation format that's best suited -for your situation by considering factors such as intended use and who will be -consuming the attestation. - -### First party - -Producers of first-party code might consider the following questions: - -- Will SLSA be used only within our organization? -- Is SLSA's primary use case to manage insider risk? -- Are we developing entirely in a closed-source environment? - -If these are the main considerations, the organization can choose any format -for internal use. To make an external claim of meeting a SLSA level, however, -there needs to be a way for external users to consume and verify your provenance. -Currently, SLSA recommends using the [SLSA Provenance format] for SLSA -attestations since it is easy to verify using the [Generic SLSA Verifier]. - -### Open source - -Producers of open-source code might consider these questions: - -- Is SLSA's primary use case to convey trust in how your code was developed? -- Do you develop software with standard open-source licenses? -- Will the code be consumed by others? - -In these situations, we encourage you to use the [SLSA Provenance format]. The SLSA -Provenance format offers a path towards interoperability and cohesion across the open -source ecosystem. Users can verify any provenance statement in this format -using the [Generic SLSA Verifier]. - -### Closed source, third party - -Producers of closed-source code that is consumed by others might consider -the following questions: - -- Is my code produced for the sole purpose of specific third-party consumers? -- Is SLSA's primary use case to create trust in our organization or to comply with -audits and legal requirements? - -In these situations, you might not want to make all the details of your -provenance available externally. Consider using Verification Summary -Attestations (VSAs) to summarize provenance information in a sanitized way -that's safe for external consumption. For more about VSAs, see the [Verification -Summary Attestation] page. - -## Model and Terminology - -We define the following model to represent any software attestations, regardless -of format. Not all formats will have all fields or all layers, but to be called -a "software attestation" it MUST fit this general model. - -The key words MUST, SHOULD, and MAY are to be interpreted as described in -[RFC 2119]. - -![Attestation model diagram](/images/attestation_layers.svg) - -An example of an attestation in English follows with the components of the -attestation mapped to the component names (and colors from the model diagram above): - -![Attestation model to English mapping](/images/attestation_example_english.svg) - -Components: - -- **Artifact:** Immutable blob of data described by an attestation, usually - identified by cryptographic content hash. Examples: file content, git - commit, container digest. MAY also include a mutable locator, such as - a package name or URI. -- **Attestation:** Authenticated, machine-readable metadata about one or more - software artifacts. An attestation MUST contain at least: - - **Envelope:** Authenticates the message. At a minimum, it MUST contain: - - **Message:** Content (statement) of the attestation. The message - type SHOULD be authenticated and unambiguous to avoid confusion - attacks. - - **Signature:** Denotes the **attester** who created the attestation. - - **Statement:** Binds the attestation to a particular set of artifacts. - This is a separate layer to allow for predicate-agnostic processing - and storage/lookup. MUST contain at least: - - **Subject:** Identifies which artifacts the predicate applies to. - - **Predicate:** Metadata about the subject. The predicate type SHOULD - be explicit to avoid misinterpretation. - - **Predicate:** Arbitrary metadata in a predicate-specific schema. MAY - contain: - - **Link:** *(repeated)* Reference to a related artifact, such as - build dependency. Effectively forms a [hypergraph] where the - nodes are artifacts and the hyperedges are attestations. It is - helpful for the link to be standardized to allow predicate-agnostic - graph processing. -- **Bundle:** A collection of Attestations, which are usually but not - necessarily related. -- **Storage/Lookup:** Convention for where attesters place attestations and - how verifiers find attestations for a given artifact. - -## Recommended Suite - -We recommend a single suite of formats and conventions that work well together -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** - -[attestation bundle]: https://github.com/in-toto/attestation/blob/main/spec/v1/bundle.md -[Binary Authorization]: https://cloud.google.com/binary-authorization -[DSSE]: https://github.com/secure-systems-lab/dsse/ -[Generic SLSA Verifier]: https://github.com/slsa-framework/slsa-verifier -[hypergraph]: https://en.wikipedia.org/wiki/Hypergraph -[in-toto]: https://in-toto.io -[in-toto attestations]: https://github.com/in-toto/attestation/ -[JSON Lines]: https://jsonlines.org/ -[other predicates defined by third-parties]: https://github.com/in-toto/attestation/issues/98 -[Provenance]: /build-provenance -[remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation -[RFC 2119]: https://tools.ietf.org/html/rfc2119 -[SLSA Provenance format]: /provenance/v1 -[sigstore/cosign]: https://github.com/sigstore/cosign -[SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md -[Verification Summary Attestation]: /verification_summary/v1 diff --git a/docs/spec/v1.2/build-provenance.md b/docs/spec/v1.2/build-provenance.md deleted file mode 100644 index 7d03fba05..000000000 --- a/docs/spec/v1.2/build-provenance.md +++ /dev/null @@ -1,608 +0,0 @@ ---- -title: "Build: Provenance" -description: Description of SLSA build provenance specification for verifying where, when, and how something was produced. -layout: standard ---- -To trace software back to the source and define the moving parts in a complex -supply chain, provenance needs to be there from the very beginning. It's the -verifiable information about software artifacts describing where, when, and how -something was produced. For higher SLSA levels and more resilient integrity -guarantees, provenance requirements are stricter and need a deeper, more -technical understanding of the predicate. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/provenance/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Purpose - -Describe how an artifact or set of artifacts was produced so that: - -- Consumers of the provenance can verify that the artifact was built according - to expectations. -- Others can rebuild the artifact, if desired. - -This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance -requirements](requirements#provenance-generation). - -## Model - -Provenance is an attestation that a particular build platform produced a set of -software artifacts through execution of the `buildDefinition`. - -![Build Model](images/provenance-model.svg) - -> NOTE: This diagram depicts how the SLSA Provenance format is structured. It -> elaborates on the [SLSA Build Model](terminology#build-model) but only applies -> to the SLSA Provenance format specifically and not to builds in general. - -The model is as follows: - -- Each build runs as an independent process on a multi-tenant build platform. - The `builder.id` identifies this platform, representing the transitive - closure of all entities that are [trusted] to faithfully run the build and - record the provenance. (Note: The same model can be used for platform-less - or single-tenant build platforms.) - - - The build platform implementer SHOULD define a security model for the build - platform in order to clearly identify the platform's boundaries, actors, - and interfaces. This model SHOULD then be used to identify the transitive - closure of the trusted build platform for the `builder.id` as well as the - trusted control plane. - -- The build process is defined by a parameterized template, identified by - `buildType`. This encapsulates the process that ran, regardless of what - platform ran it. Often the build type is specific to the build platform - because most build platforms have their own unique interfaces. - -- All top-level, independent inputs are captured by the parameters to the - template. There are two types of parameters: - - - `externalParameters`: the external interface to the build. In SLSA, - these values are untrusted; they MUST be included in the provenance and - MUST be verified downstream. - - - `internalParameters`: set internally by the platform. In SLSA, these - values are trusted because the platform is trusted; they are OPTIONAL - and need not be verified downstream. They MAY be included to enable - reproducible builds, debugging, or incident response. - -- All artifacts fetched during initialization or execution of the build - process are considered dependencies, including those referenced directly by - parameters. The `resolvedDependencies` captures these dependencies, if - known. For example, a build that takes a git repository URI as a parameter - might record the specific git commit that the URI resolved to as a - dependency. - -- During execution, the build process might communicate with the build - platform's control plane and/or build caches. This communication is not - captured directly in the provenance, but is instead implied by `builder.id` - and subject to [SLSA Requirements](requirements.md). Such - communication SHOULD NOT influence the definition of the build; if it does, - it SHOULD go in `resolvedDependencies` instead. - -- Finally, the build process outputs one or more artifacts, identified by - `subject`. - -For concrete examples, see [index of build types](#index-of-build-types). - -## Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields unless otherwise noted. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." - Such changes do not update the `predicateType`. -- Unset, null, and empty field values MUST be interpreted equivalently. - -## Schema - -### Summary - -*NOTE: This summary (in cue) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - - - -```javascript -{% include_relative schema/provenance.cue %} -``` - -
-Protocol buffer schema - -*NOTE: This summary (in protobuf) is informative. In the event of a -disagreement with the text description, the text is authoritative.* - -Link: [provenance.proto](schema/provenance.proto) - -*NOTE: This protobuf definition prioritizes being a human-readable summary -of the schema for readers of the specification. A version of the protobuf -definition useful for code generation is maintained in the -[in-toto attestation] repository.* - -```proto -{% include_relative schema/provenance.proto %} -``` - -
- -### Provenance - -*NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement].* - -[Provenance]: #provenance - -REQUIRED for SLSA Build L1: `buildDefinition`, `runDetails` - - -
FieldTypeDescription - -
buildDefinition -BuildDefinition - -The input to the build. The accuracy and completeness are implied by -`runDetails.builder.id`. - -
runDetails -RunDetails - -Details specific to this particular execution of the build. - -
- -### BuildDefinition - -[BuildDefinition]: #builddefinition - -REQUIRED for SLSA Build L1: `buildType`, `externalParameters` - - -
FieldTypeDescription - -
buildType -string (TypeURI) - -Identifies the template for how to perform the build and interpret the -parameters and dependencies. - -The URI SHOULD resolve to a human-readable specification that includes: overall -description of the build type; schema for `externalParameters` and -`internalParameters`; unambiguous instructions for how to initiate the build given -this BuildDefinition, and a complete example. Example: -https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1 - -
externalParameters -object - -The parameters that are under external control, such as those set by a user or -tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that -there is no additional mechanism for an external party to influence the -build. (At lower SLSA Build levels, the completeness MAY be best effort.) - -The build platform SHOULD be designed to minimize the size and complexity of -`externalParameters`, in order to reduce fragility and ease [verification]. -Consumers SHOULD have an expectation of what "good" looks like; the more -information that they need to check, the harder that task becomes. - -Verifiers SHOULD reject unrecognized or unexpected fields within -`externalParameters`. - -
internalParameters -object - -The parameters that are under the control of the entity represented by -`builder.id`. The primary intention of this field is for debugging, incident -response, and vulnerability management. The values here MAY be necessary for -reproducing the build. There is no need to [verify][Verification] these -parameters because the build platform is already trusted, and in many cases it is -not practical to do so. - -
resolvedDependencies -array (ResourceDescriptor) - -Unordered collection of artifacts needed at build time. Completeness is best -effort, at least through SLSA Build L3. For example, if the build script -fetches and executes "example.com/foo.sh", which in turn fetches -"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" SHOULD be -listed here. - -
- -The BuildDefinition describes all of the inputs to the build. It SHOULD contain -all the information necessary and sufficient to initialize the build and begin -execution. - -The `externalParameters` and `internalParameters` are the top-level inputs to the -template, meaning inputs not derived from another input. Each is an arbitrary -JSON object, though it is RECOMMENDED to keep the structure simple with string -values to aid verification. The same field name SHOULD NOT be used for both -`externalParameters` and `internalParameters`. - -The parameters SHOULD only contain the actual values passed in through the -interface to the build platform. Metadata about those parameter values, -particularly digests of artifacts referenced by those parameters, SHOULD instead -go in `resolvedDependencies`. The documentation for `buildType` SHOULD explain -how to convert from a parameter to the dependency `uri`. For example: - -```json -"externalParameters": { - "repository": "https://github.com/octocat/hello-world", - "ref": "refs/heads/main" -}, -"resolvedDependencies": [{ - "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", - "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} -}] -``` - -Guidelines: - -- Maximize the amount of information that is implicit from the meaning of - `buildType`. In particular, any value that is boilerplate and the same - for every build SHOULD be implicit. - -- Reduce parameters by moving configuration to input artifacts whenever - possible. For example, instead of passing in compiler flags via an external - parameter that has to be [verified][Verification] separately, require the - flags to live next to the source code or build configuration so that - verifying the latter automatically verifies the compiler flags. - -- In some cases, additional external parameters might exist that do not impact - the behavior of the build, such as a deadline or priority. These extra - parameters SHOULD be excluded from the provenance after careful analysis - that they indeed pose no security impact. - -- If possible, architect the build platform to use this definition as its - sole top-level input, in order to guarantee that the information is - sufficient to run the build. - -- When build configuration is evaluated client-side before being sent to the - server, such as transforming version-controlled YAML into ephemeral JSON, - some solution is needed to make [verification] practical. Consumers need a - way to know what configuration is expected and the usual way to do that is - to map it back to version control, but that is not possible if the server - cannot verify the configuration's origins. Possible solutions: - - - (RECOMMENDED) Rearchitect the build platform to read configuration - directly from version control, recording the server-verified URI in - `externalParameters` and the digest in `resolvedDependencies`. - - - Record the digest in the provenance[^digest-param] and use a separate - provenance attestation to link that digest back to version control. In - this solution, the client-side evaluation is considered a separate - "build" that SHOULD be independently secured using SLSA, though securing - it can be difficult since it usually runs on an untrusted workstation. - -- The purpose of `resolvedDependencies` is to facilitate recursive analysis of - the software supply chain. Where practical, it is valuable to record the - URI and digest of artifacts that, if compromised, could impact the build. At - SLSA Build L3, completeness is considered "best effort". - -[^digest-param]: The `externalParameters` SHOULD reflect reality. If clients - send the evaluated configuration object directly to the build server, record - the digest directly in `externalParameters`. If clients upload the - configuration object to a temporary storage location and send that location - to the build server, record the location in `externalParameters` as a URI - and record the `uri` and `digest` in `resolvedDependencies`. - -### RunDetails - -[RunDetails]: #rundetails - -REQUIRED for SLSA Build L1: `builder` - - -
FieldTypeDescription - -
builder -Builder - -Identifies the build platform that executed the invocation, which is trusted to -have correctly performed the operation and populated this provenance. - -
metadata -BuildMetadata - -Metadata about this particular execution of the build. - -
byproducts -array (ResourceDescriptor) - -Additional artifacts generated during the build that are not considered -the "output" of the build but that might be needed during debugging or -incident response. For example, this might reference logs generated during -the build and/or a digest of the fully evaluated build configuration. - -In most cases, this SHOULD NOT contain all intermediate files generated during -the build. Instead, this SHOULD only contain files that are likely to be useful -later and that cannot be easily reproduced. - -
- -### Builder - -[Builder]: #builder - -REQUIRED for SLSA Build L1: `id` - - -
FieldTypeDescription - -
id -string (TypeURI) - -URI indicating the transitive closure of the trusted build platform. This is -[intended](verifying-artifacts#step-1-check-slsa-build-level) -to be the sole determiner of the SLSA Build level. - -If a build platform has multiple modes of operations that have differing -security attributes or SLSA Build levels, each mode MUST have a different -`builder.id` and SHOULD have a different signer identity. This is to minimize -the risk that a less secure mode compromises a more secure one. - -The `builder.id` URI SHOULD resolve to documentation explaining: - -- The scope of what this ID represents. -- The claimed SLSA Build level. -- The accuracy and completeness guarantees of the fields in the provenance. -- Any fields that are generated by the tenant-controlled build process and not - verified by the trusted control plane, except for the `subject`. -- The interpretation of any extension fields. - -
builderDependencies -array (ResourceDescriptor) - -Dependencies used by the orchestrator that are not run within the workload -and that do not affect the build, but might affect the provenance generation -or security guarantees. - -
version -map (string→string) - -Map of names of components of the build platform to their version. - -
- -The build platform, or builder for short, represents the transitive -closure of all the entities that are, by necessity, [trusted] to faithfully run -the build and record the provenance. This includes not only the software but the -hardware and people involved in running the service. For example, a particular -instance of [Tekton](https://tekton.dev/) could be a build platform, while -Tekton itself is not. For more info, see [Build -model](terminology#build-model). - -The `id` MUST reflect the trust base that consumers care about. How detailed to -be is a judgement call. For example, GitHub Actions supports both GitHub-hosted -runners and self-hosted runners. The GitHub-hosted runner might be a single -identity because it's all GitHub from the consumer's perspective. Meanwhile, -each self-hosted runner might have its own identity because not all runners are -trusted by all consumers. - -Consumers MUST accept only specific signer-builder pairs. For example, "GitHub" -can sign provenance for the "GitHub Actions" builder, and "Google" can sign -provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for -the "Google Cloud Build" builder. - -Design rationale: The builder is distinct from the signer in order to support -the case where one signer generates attestations for more than one builder, as -in the GitHub Actions example above. The field is REQUIRED, even if it is -implicit from the signer, to aid readability and debugging. It is an object to -allow additional fields in the future, in case one URI is not sufficient. - -### BuildMetadata - -[BuildMetadata]: #buildmetadata - -REQUIRED: (none) - - -
FieldTypeDescription - -
invocationId -string - -Identifies this particular build invocation, which can be useful for finding -associated logs or other ad-hoc analysis. The exact meaning and format is -defined by `builder.id`; by default it is treated as opaque and case-sensitive. -The value SHOULD be globally unique. - -
startedOn -string (Timestamp) - -The timestamp of when the build started. - -
finishedOn -string (Timestamp) - -The timestamp of when the build completed. - -
- -### Extension fields - -[Extension fields]: #extension-fields - -Implementations MAY add extension fields to any JSON object to describe -information that is not captured in a standard field. Guidelines: - -- Extension fields SHOULD use names of the form `_`, e.g. - `examplebuilder_isCodeReviewed`. This practice avoids field name collisions - by namespacing each vendor. Non-extension field names never contain an - underscore. -- Extension fields MUST NOT alter the meaning of any other field. In other - words, an attestation with an absent extension field MUST be interpreted - identically to an attestation with an unrecognized (and thus ignored) - extension field. -- Extension fields SHOULD follow the [monotonic principle][parsing rules], - meaning that deleting or ignoring the extension SHOULD NOT turn a DENY - decision into an ALLOW. - -## Verification - -[Verification]: verifying-artifacts - -Please see [Verifying Artifacts][Verification] for a detailed discussion of -provenance verification. - -## Index of build types - -The following is a partial index of build type definitions. Each contains a -complete example predicate. - - - -- [GitHub Actions Workflow (community-maintained)](https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1) -- [Google Cloud Build (community-maintained)](https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1) - -To add an entry here, please send a pull request on GitHub. - -## Migrating from 0.2 - -To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following -pseudocode. The meaning of each field is unchanged unless otherwise noted. - -```javascript -{ - "buildDefinition": { - // The `buildType` MUST be updated for v1.0 to describe how to - // interpret `inputArtifacts`. - "buildType": /* updated version of */ old.buildType, - "externalParameters": - old.invocation.parameters + { - // It is RECOMMENDED to rename "entryPoint" to something more - // descriptive. - "entryPoint": old.invocation.configSource.entryPoint, - // It is OPTIONAL to rename "source" to something more descriptive, - // especially if "source" is ambiguous or confusing. - "source": old.invocation.configSource.uri, - }, - "internalParameters": old.invocation.environment, - "resolvedDependencies": - old.materials + [ - { - "uri": old.invocation.configSource.uri, - "digest": old.invocation.configSource.digest, - } - ] - }, - "runDetails": { - "builder": { - "id": old.builder.id, - "builderDependencies": null, // not in v0.2 - "version": null, // not in v0.2 - }, - "metadata": { - "invocationId": old.metadata.buildInvocationId, - "startedOn": old.metadata.buildStartedOn, - "finishedOn": old.metadata.buildFinishedOn, - }, - "byproducts": null, // not in v0.2 - }, -} -``` - -The following fields from v0.2 are no longer present in v1.0: - -- `entryPoint`: Use `externalParameters[]` instead. -- `buildConfig`: No longer inlined into the provenance. Instead, either: - - If the configuration is a top-level input, record its digest in - `externalParameters["config"]`. - - Else if there is a known use case for knowing the exact resolved - build configuration, record its digest in `byproducts`. An example use - case might be someone who wishes to parse the configuration to look for - bad patterns, such as `curl | bash`. - - Else omit it. -- `metadata.completeness`: Now implicit from `builder.id`. -- `metadata.reproducible`: Now implicit from `builder.id`. - -## Change history - -### v1.2 - -- Note the difference between the *provenance* build model diagram and - the general SLSA build model diagram. - -### v1.0 - -Major refactor to reduce misinterpretation, including a minor change in model. - -- Significantly expanded all documentation. -- Altered the model slightly to better align with real-world build platforms, - align with reproducible builds, and make verification easier. -- Grouped fields into `buildDefinition` vs `runDetails`. -- Renamed: - - `parameters` -> `externalParameters` (slight change in semantics) - - `environment` -> `internalParameters` (slight change in semantics) - - `materials` -> `resolvedDependencies` (slight change in semantics) - - `buildInvocationId` -> `invocationId` - - `buildStartedOn` -> `startedOn` - - `buildFinishedOn` -> `finishedOn` -- Removed: - - `configSource`: No longer special-cased. Now represented as - `externalParameters` + `resolvedDependencies`. - - `buildConfig`: No longer inlined into the provenance. Can be replaced - with a reference in `externalParameters` or `byproducts`, depending on - the semantics, or omitted if not needed. - - `completeness` and `reproducible`: Now implied by `builder.id`. -- Added: - - ResourceDescriptor: `annotations`, `content`, `downloadLocation`, - `mediaType`, `name` - - Builder: `builderDependencies` and `version` - - `byproducts` -- Changed naming convention for extension fields. - -Differences from RC1 and RC2: - -- Renamed `systemParameters` (RC1 + RC2) -> `internalParameters` (final). -- Changed naming convention for extension fields (in RC2). -- Renamed `localName` (RC1) -> `name` (RC2). -- Added `annotations` and `content` (in RC2). - -### v0.2 - -Refactored to aid clarity and added `buildConfig`. The model is unchanged. - -- Replaced `definedInMaterial` and `entryPoint` with `configSource`. -- Renamed `recipe` to `invocation`. -- Moved `invocation.type` to top-level `buildType`. -- Renamed `arguments` to `parameters`. -- Added `buildConfig`, which can be used as an alternative to `configSource` - to validate the configuration. - -### rename: slsa.dev/provenance - -Renamed to "slsa.dev/provenance". - -### v0.1.1 - -- Added `metadata.buildInvocationId`. - -### v0.1 - -Initial version, named "in-toto.io/Provenance" - -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules -[purl]: https://github.com/package-url/purl-spec -[threats]: threats -[trusted]: principles#trust-systems-verify-artifacts diff --git a/docs/spec/v1.2/build-requirements.md b/docs/spec/v1.2/build-requirements.md deleted file mode 100644 index bee92afb5..000000000 --- a/docs/spec/v1.2/build-requirements.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -title: "Build: Requirements for producing artifacts" -description: This page covers the detailed technical requirements for producing artifacts at each SLSA level. The intended audience is platform implementers and security engineers. ---- - - -This page covers the detailed technical requirements for producing artifacts at -each SLSA level. The intended audience is platform implementers and security -engineers. - -For an informative description of the levels intended for all audiences, see -[Build Track Basics](build-track-basics.md). For background, see -[Terminology](terminology.md). To better understand the reasoning behind the -requirements, see [Threats and mitigations](threats.md). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Overview - -### Build levels - -In order to produce artifacts with a specific build level, responsibility is -split between the [Producer] and [Build platform]. The build platform MUST -strengthen the security controls in order to achieve a specific level while the -producer MUST choose and adopt a build platform capable of achieving a desired -build level, implementing any controls as specified by the chosen platform. - - - - - - - - - - - -
Implementer - Requirement - Degree - L1L2L3 -
Producer - Choose an appropriate build platform - ✓✓✓ -
Follow a consistent build process - ✓✓✓ -
Distribute provenance - ✓✓✓ -
Build platform - Provenance generation - Exists - ✓✓✓ -
Authentic - ✓✓ -
Unforgeable - ✓ -
Isolation strength - Hosted - ✓✓ -
Isolated - ✓ -
- -### Security Best Practices - -While the exact definition of what constitutes a secure platform is beyond the -scope of this specification, all implementations MUST use industry security -best practices to be conformant to this specification. This includes, but is -not limited to, using proper access controls, securing communications, -implementing proper management of cryptographic secrets, doing frequent updates, -and promptly fixing known vulnerabilities. - -Various relevant standards and guides can be consulted for that matter such as -the [CIS Critical Security -Controls](https://www.cisecurity.org/controls/cis-controls-list). - -## Producer - -[Producer]: #producer - -A package's producer is the organization that owns and releases the -software. It might be an open-source project, a company, a team within a -company, or even an individual. - -NOTE: There were more requirements for producers in the initial -[draft version (v0.1)](../v0.1/requirements.md#scripted-build) which impacted -how a package can be built. These were removed in the v1.0 specification and -will be reassessed and re-added as indicated in the -[future directions](future-directions.md). - -### Choose an appropriate build platform - -The producer MUST select a build platform that is capable of reaching their -desired SLSA Build Level. - -For example, if a producer wishes to produce a Build Level 3 artifact, they MUST -choose a builder capable of producing Build Level 3 provenance. - -### Follow a consistent build process - -The producer MUST build their artifact in a consistent -manner such that verifiers can form expectations about the build process. In -some implementations, the producer MAY provide explicit metadata to a verifier -about their build process. In others, the verifier will form their expectations -implicitly (e.g. trust on first use). - -If a producer wishes to distribute their artifact through a [package ecosystem] -that requires explicit metadata about the build process in the form of a -configuration file, the producer MUST complete the configuration file and keep -it up to date. This metadata might include information related to the artifact's -source repository and build parameters. - -### Distribute provenance - -The producer MUST distribute provenance to artifact consumers. The producer -MAY delegate this responsibility to the -[package ecosystem], provided that the package ecosystem is capable of -distributing provenance. - -## Build Platform - -[Build platform]: #build-platform - -A package's build platform is the infrastructure used to transform the -software from source to package. This includes the transitive closure of all -hardware, software, persons, and organizations that can influence the build. A -build platform is often a hosted, multi-tenant build service, but it could be a -system of multiple independent rebuilders, a special-purpose build platform used -by a single software project, or even an individual's workstation. Ideally, one -build platform is used by many different software packages so that consumers can -[minimize the number of trusted platforms](principles.md). For more background, -see [Build Model](terminology.md#build-model). - -The build platform is responsible for providing two things: [provenance -generation] and [isolation between builds]. The -[Build level](build-track-basics) describes the degree to which each of these -properties is met. - -### Provenance generation - -[Provenance generation]: #provenance-generation - -The build platform is responsible for generating provenance describing how the -package was produced. - -The SLSA Build level describes the overall provenance integrity according to -minimum requirements on its: - -- *Completeness:* What information is contained in the provenance? -- *Authenticity:* How strongly can the provenance be tied back to the builder? -- *Accuracy:* How resistant is the provenance generation to tampering within - the build process? - - -
RequirementDescriptionL1L2L3 - -
Provenance Exists - -The build process MUST generate provenance that unambiguously identifies the -output package by cryptographic digest and describes how that package was -produced. The format MUST be acceptable to the [package ecosystem] and/or -[consumer](verifying-artifacts.md#consumer). - -It is RECOMMENDED to use the [SLSA Provenance] format and [associated suite] -because it is designed to be interoperable, universal, and unambiguous when -used for SLSA. See that format's documentation for requirements and -implementation guidelines. - -If using an alternate format, it MUST contain the equivalent information as SLSA -Provenance at each level and SHOULD be bi-directionally translatable to SLSA -Provenance. - -- *Completeness:* Best effort. The provenance at L1 SHOULD contain sufficient - information to catch mistakes and simulate the user experience at higher - levels in the absence of tampering. In other words, the contents of the - provenance SHOULD be the same at all Build levels, but a few fields MAY be - absent at L1 if they are prohibitively expensive to implement. -- *Authenticity:* No requirements. -- *Accuracy:* No requirements. - -[SLSA Provenance]: provenance.md -[associated suite]: attestation-model#recommended-suite - -✓✓✓ -
Provenance is Authentic - -*Authenticity:* Consumers MUST be able to validate the authenticity of the -provenance attestation in order to: - -- *Ensure integrity:* Verify that the digital signature of the provenance - attestation is valid and the provenance was not tampered with after the - build. -- *Define trust:* Identify the build platform and other entities that are - necessary to trust in order to trust the artifact they produced. - -This SHOULD be through a digital signature from a private key accessible only -to the build platform component that generated the provenance attestation. - -While many constraints affect choice of signing methodologies, it is -RECOMMENDED that build platforms use signing methodologies which improve the -ability to detect and remediate key compromise, such as methods which rely on -transparency logs or, when transparency isn't appropriate, time stamping -services. - -Authenticity allows the consumer to trust the contents of the provenance -attestation, such as the identity of the build platform. - -*Accuracy:* The provenance MUST be generated by the control plane (i.e. within -the trust boundary [identified in the provenance]) and not by a tenant of the -build platform (i.e. outside the trust boundary), except as noted below. - -- The data in the provenance MUST be obtained from the build platform, either - because the generator *is* the build platform or because the provenance - generator reads the data directly from the build platform. -- The build platform MUST have some security control to prevent tenants from - tampering with the provenance. However, there is no minimum bound on the - strength. The purpose is to deter adversaries who might face legal or - financial risk from evading controls. -- Exceptions for fields that MAY be generated by a tenant of the build platform: - - The names and cryptographic digests of the output artifacts, i.e. - `subject` in [SLSA Provenance]. See [forge output digest of the - provenance](threats#forged-digest) for explanation of why this is - acceptable. - - Any field that is not marked as REQUIRED for Build L2. For example, - `resolvedDependencies` in [SLSA Provenance] MAY be tenant-generated at - Build L2. Builders SHOULD document any such cases of tenant-generated - fields. - -*Completeness:* SHOULD be complete. - -- There MAY be [external parameters] that are not sufficiently captured in - the provenance. -- Completeness of resolved dependencies is best effort. - - ✓✓ -
Provenance is Unforgeable - -*Accuracy:* Provenance MUST be strongly resistant to forgery by tenants. - -- Any secret material used for authenticating the provenance, for example the - signing key used to generate a digital signature, MUST be stored in a secure - management system appropriate for such material and accessible only to the - build service account. -- Such secret material MUST NOT be accessible to the environment running - the user-defined build steps. -- Every field in the provenance MUST be generated or verified by the build - platform in a trusted control plane. The user-controlled build steps MUST - NOT be able to inject or alter the contents, except as noted in [Provenance - is Authentic](#provenance-authentic). (Build L3 does not require additional - fields beyond those of L2.) - -*Completeness:* SHOULD be complete. - -- [External parameters] MUST be fully enumerated. -- Completeness of resolved dependencies is best effort. - -Note: This requirement was called "non-falsifiable" in the initial -[draft version (v0.1)](../v0.1/requirements.md#non-falsifiable). - - ✓ -
- -### Isolation strength - -[Isolation strength]: #isolation-strength -[Isolation between builds]: #isolation-strength - -The build platform is responsible for isolating between builds, even within the -same tenant project. In other words, how strong of a guarantee do we have that -the build really executed correctly, without external influence? - -The SLSA Build level describes the minimum bar for isolation strength. For more -information on assessing a build platform's isolation strength, see -[Assessing build platforms](assessing-build-platforms.md). - - - - -
RequirementDescriptionL1L2L3 - -
Hosted - - -All build steps ran using a hosted build platform on shared or dedicated -infrastructure, not on an individual's workstation. - -Examples: GitHub Actions, Google Cloud Build, Travis CI. - - ✓✓ -
Isolated - - -The build platform ensured that the build steps ran in an isolated environment, -free of unintended external influence. In other words, any external influence on -the build was specifically requested by the build itself. This MUST hold true -even between builds within the same tenant project. - -The build platform MUST guarantee the following: - -- It MUST NOT be possible for a build to access any secrets of the build - platform, such as the provenance signing key, because doing so would - compromise the authenticity of the provenance. -- It MUST NOT be possible for two builds that overlap in time to influence one - another, such as by altering the memory of a different build process running - on the same machine. -- It MUST NOT be possible for one build to persist or influence the build - environment of a subsequent build. In other words, an ephemeral build - environment MUST be provisioned for each build. -- It MUST NOT be possible for one build to inject false entries into a build - cache used by another build, also known as "cache poisoning". In other - words, the output of the build MUST be identical whether or not the cache is - used. -- The build platform MUST NOT open services that allow for remote influence - unless all such interactions are captured as `externalParameters` in the - provenance. - -There are no sub-requirements on the build itself. Build L3 is limited to -ensuring that a well-intentioned build runs securely. It does not require that -a build platform prevents a producer from performing a risky or insecure build. In -particular, the "Isolated" requirement does not prohibit a build from calling -out to a remote execution service or a "self-hosted runner" that is outside the -trust boundary of the build platform. - -NOTE: This requirement was split into "Isolated" and "Ephemeral Environment" -in the initial [draft version (v0.1)](../v0.1/requirements.md). - -NOTE: This requirement is not to be confused with "Hermetic", which roughly -means that the build ran with no network access. Such a requirement requires -substantial changes to both the build platform and each individual build, and is -considered in the [future directions](future-directions.md). - - ✓ -
- -[external parameters]: provenance.md#externalParameters -[identified in the provenance]: provenance.md#model -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.2/build-track-basics.md b/docs/spec/v1.2/build-track-basics.md deleted file mode 100644 index eccbc36b6..000000000 --- a/docs/spec/v1.2/build-track-basics.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: "Build: Track Basics" -description: The SLSA build track is organized into a series of levels that provide increasing supply chain security guarantees. This gives you confidence that software hasn’t been tampered with and can be securely traced back to its source. This page is a descriptive overview of the SLSA build track levels, describing their intent. ---- - -| 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 - - - -> 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 -> Build track. In 1.2 the [Source Track](tracks#source-track) reintroduces -> coverage of source code. - -
- -## Build L0: No guarantees - -
-
Summary
- -No requirements---L0 represents the lack of SLSA. - -
Intended for
- -Development or test builds of software that are built and run on the same -machine, such as unit tests. - -
Requirements
- -n/a - -
Benefits
- -n/a - -
-
-
- -## Build L1: Provenance exists - -
-
Summary
- -Package has provenance showing how it was built. Can be used to prevent mistakes -but is trivial to bypass or forge. - -
Intended for
- -Projects and organizations wanting to easily and quickly gain some benefits of -SLSA---other than tamper protection---without changing their build workflows. - -
Requirements
- -- Software Producer: - - Follow a consistent build process so that others can form - expectations about what a "correct" build looks like. - - Run builds on a build platform that meets Build L1 requirements. - - Distribute provenance to consumers, preferably using a convention - determined by the package ecosystem. -- Build platform: - - Automatically generate [provenance] describing how the artifact was - built, including: what entity built the package, what build process - they used, and what the top-level input to the build were. - -
Benefits
- -- Makes it easier for both producers and consumers to debug, patch, rebuild, - and/or analyze the software by knowing its precise source version and build - process. - -- With [verification], prevents mistakes during the release process, such as - building from a commit that is not present in the upstream repo. - -- Aids organizations in creating an inventory of software and build platforms - used across a variety of teams. - -
Notes
- -- Provenance may be incomplete and/or unsigned at L1. Higher levels require - more complete and trustworthy provenance. - -
- -
-
- -## Build L2: Hosted build platform - -
-
Summary
- -Forging the provenance or evading verification requires an explicit "attack", -though this may be easy to perform. Deters unsophisticated adversaries or those -who face legal or financial risk. - -In practice, this means that builds run on a hosted platform that generates and -signs[^sign] the provenance. - -
Intended for
- -Projects and organizations wanting to gain moderate security benefits of SLSA by -switching to a hosted build platform, while waiting for changes to the build -platform itself required by [Build L3]. - -
Requirements
- -All of [Build L1], plus: - -- Software producer: - - Run builds on a [hosted] build platform that meets Build L2 - requirements. -- Build platform: - - Generate and sign[^sign] the provenance itself. This may be done - during the original build, an after-the-fact reproducible build, or - some equivalent system that ensures the trustworthiness of the - provenance. -- Consumer: - - Validate the authenticity of the provenance. - -
Benefits
- -All of [Build L1], plus: - -- Prevents tampering after the build through digital signatures[^sign]. - -- Deters adversaries who face legal or financial risk by evading security - controls, such as employees who face risk of getting fired. - -- Reduces attack surface by limiting builds to specific build platforms that - can be audited and hardened. - -- Allows large-scale migration of teams to supported build platforms early - while further hardening work ([Build L3]) is done in parallel. - -
-
-
- -[^sign]: Alternate means of verifying the authenticity of the provenance are - also acceptable. - -## Build L3: Hardened builds - -
-
Summary
- -Forging the provenance or evading verification requires exploiting a -vulnerability that is beyond the capabilities of most adversaries. - -In practice, this means that builds run on a hardened build platform that offers -strong tamper protection. - -
Intended for
- -Most software releases. Build L3 usually requires significant changes to -existing build platforms. - -
Requirements
- -All of [Build L2], plus: - -- Software producer: - - Run builds on a hosted build platform that meets Build L3 - requirements. -- Build platform: - - Implement strong controls to: - - prevent runs from influencing one another, even within the same - project. - - prevent secret material used to sign the provenance from being - accessible to the user-defined build steps. - -
Benefits
- -All of [Build L2], plus: - -- Prevents tampering during the build---by insider threats, compromised - credentials, or other tenants. - -- Greatly reduces the impact of compromised package upload credentials by - requiring the attacker to perform a difficult exploit of the build process. - -- Provides strong confidence that the package was built from the official - source and build process. - -
-
- - - -[build l0]: #build-l0 -[build l1]: #build-l1 -[build l2]: #build-l2 -[build l3]: #build-l3 -[future versions]: future-directions.md -[hosted]: build-requirements.md#isolation-strength -[previous version]: ../v0.1/levels.md -[provenance]: terminology.md -[verification]: verifying-artifacts.md diff --git a/docs/spec/v1.2/distributing-provenance.md b/docs/spec/v1.2/distributing-provenance.md deleted file mode 100644 index ffb6a3d86..000000000 --- a/docs/spec/v1.2/distributing-provenance.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: "Build: Distributing provenance" -description: This page covers the detailed technical requirements for distributing provenance at each SLSA level. The intended audience is platform implementers and software distributors. ---- - -In order to make provenance for artifacts available after generation -for verification, SLSA requires the distribution and verification of provenance -metadata in the form of SLSA attestations. - -This document provides specifications for distributing provenance and the -relationship between build artifacts and provenance (build attestations). It is -primarily concerned with artifacts for ecosystems that distribute build -artifacts, but some attention is also paid to ecosystems that distribute -container images or only distribute source artifacts, as many of the same -principles generally apply to any artifact or group of artifacts. - -In addition, this document is primarily for the benefit of artifact -distributors, to understand how they can adopt the distribution of SLSA -provenance. It is primarily concerned with the means of distributing -attestations and the relationship of attestations to build artifacts, and not -with the specific format of the attestation itself. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). - -## Background - -The [package ecosystem]'s maintainers are responsible for reliably -redistributing artifacts and provenance, making the producers' expectations -available to consumers, and providing tools to enable safe artifact consumption -(e.g., whether an artifact meets its producer's expectations). - -## Relationship between releases and attestations - -Attestations SHOULD be bound to artifacts, not releases. - -A single "release" of a project, package, or library might include multiple -artifacts. These artifacts result from builds on different platforms, -architectures, or environments. The builds need not happen at roughly the same -point in time and might even span multiple days. - -It is often difficult or impossible to determine when a release is 'finished' -because many ecosystems allow adding new artifacts to old releases when adding -support for new platforms or architectures. Therefore, the set of attestations -for a given release MAY grow over time as additional builds and attestations -are created. - -Thus, package ecosystems SHOULD support multiple individual attestations per -release. At the time of a given build, the relevant provenance for that build -can be added to the release, depending on the relationship to the given -artifacts. - -## Relationship between artifacts and attestations - -Package ecosystems SHOULD support a one-to-many relationship from build -artifacts to attestations to ensure that anyone is free to produce and publish -any attestation they might need. However, while there are lots of possible -attestations that can have a relationship to a given artifact, in this context -SLSA is primarily concerned with build attestations, i.e., provenance, and as -such, this specification only considers build attestations, produced by the -same maintainers as the artifacts themselves. - -By providing provenance alongside an artifact in the manner specified by a -given ecosystem, maintainers are considered to be 'elevating' these build -attestations above all other possible attestations that could be provided by -third parties for a given artifact. The ultimate goal is for maintainers to -provide the provenance necessary for a repository to be able to verify some -potential policy that requires a certain SLSA level for publication, not -support the publication of arbitrary attestations by third parties. - -As a result, this provenance SHOULD accompany the artifact at publish time, and -package ecosystems SHOULD provide a way to map a given artifact to its -corresponding attestations. The mappings can be either implicit (e.g., require a -custom filename schema that uniquely identifies the provenance over other -attestation types) or explicit (e.g., it could happen as a de-facto standard -based on where the attestation is published). - -The provenance SHOULD have a filename that is directly related to the build -artifact filename. For example, for an artifact `.`, the -attestation is `.attestation` or some similar extension (for example -[in-toto](https://in-toto.io/) recommends `.intoto.jsonl`). - -## Where attestations are published - -There are a number of opportunities and venues to publish attestations during -and after the build process. Producers MUST publish attestations in at least -one place, and SHOULD publish attestations in more than one place: - -- **Publish attestations alongside the source repository releases**: If the - source repository hosting provider offers an artifact "release" feature, - such as [GitHub - releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - or [GitLab releases](https://docs.gitlab.com/ee/user/project/releases/), - producers SHOULD include provenance as part of such releases. This option - has the benefit of requiring no changes to the package registry to support - provenance formats, but has the disadvantage of putting the source - repository hosting provider in the critical path for installers that want to - verify policy at build-time. -- **Publish attestations alongside the artifact in the package registry**: - Many software repositories already support some variety of publishing 1:1 - related files alongside an artifact, sometimes known as “sidecar files”. - For example, PyPI supports publishing `.asc` files representing the PGP - signature for an artifact with the same filename (but different extension). - This option requires the mapping between artifact and attestation (or - attestation vessel) to be 1:1. -- **Publish attestations elsewhere, record their existence in a transparency - log**: Once an attestation has been generated and published for a build, a - hash of the attestation and a pointer to where it is indexed SHOULD be - published to a third-party transparency log that exists outside the source - repository and package registry. Not only are transparency logs such as - [Rekor from Sigstore](https://github.com/sigstore/rekor) guaranteed - to be immutable, but they typically also make monitoring easier. - Requiring the presence of the attestation in a monitored transparency log - during verification helps ensure the attestation is trustworthy. - -Combining these options gives us a process for bootstrapping SLSA adoption -within an ecosystem, even if the package registry doesn't support publishing -attestations. First, interested projects modify their release process to -produce SLSA provenance. Then, they publish that provenance to their source -repository. Finally, they publish the provenance to the package registry, if -and when the registry supports it. - -Long-term, package registries SHOULD support uploading and distributing -provenance alongside the artifact. This model is preferred for two reasons: - -- trust: clients already trust the package registry as the source of their - artifacts, and don't need to trust an additional service; -- reliability: clients already depend on the package registry as part of - their critical path, so distributing provenance via the registry avoids - adding an additional point of failure. - -Short term, consumers of build artifacts can bootstrap a manual policy by using -the source repository only for projects that publish all artifacts and -attestations to the source repository, and later extend this to all artifacts -published to the package registry via the canonical installation tools once -a given ecosystem supports them. - -## Immutability of attestations - -Attestations SHOULD be immutable. Once an attestation is published as it -corresponds to a given artifact, that attestation is immutable and cannot be -overwritten later with a different attestation that refers to the same -artifact. Instead, a new release (and new artifacts) SHOULD be created. - -## Format of the attestation - -The provenance is available to the consumer in a format that the consumer -accepts. The format SHOULD be in-toto -[SLSA Build Provenance](/build-provenance), but another format MAY be used if -both producer and consumer agree and it meets all the other requirements. - -## Considerations for source-based ecosystems - -Some ecosystems have support for installing directly from source repositories -(an option for Python/`pip`, Go, etc.). In these cases, there is no need to -publish or verify provenance because there is no "build" step that translates -between a source repository and an artifact that is being installed. - -However, for ecosystems that install from source repositories _via_ some -intermediary (e.g., [Homebrew installing from GitHub release artifacts generated -from the repository or GitHub Packages](https://docs.brew.sh/Bottles), [Go -installing through the Go module proxy](https://proxy.golang.org/)), these -ecosystems distribute "source archives" that are not the bit-for-bit identical -form from version control. These intermediaries are transforming the original -source repository in some way that constitutes a "build" and as a result SHOULD -be providing build provenance for this "package", and the recommendations -outlined here apply. - -[package ecosystem]: verifying-artifacts.md#package-ecosystem diff --git a/docs/spec/v1.2/faq.md b/docs/spec/v1.2/faq.md deleted file mode 100644 index 0590bd77e..000000000 --- a/docs/spec/v1.2/faq.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Frequently asked questions -description: Answers to questions frequently asked about SLSA. -layout: specifications ---- - -## Q: Why is SLSA not transitive? - -SLSA Build levels only cover the trustworthiness of a single build, with no -requirements about the build levels of transitive dependencies. The reason for -this is to make the problem tractable. If a SLSA Build level required -dependencies to be the same level, then reaching a level would require starting -at the very beginning of the supply chain and working forward. This is -backwards, forcing us to work on the least risky component first and blocking -any progress further downstream. By making each artifact's SLSA rating -independent from one another, it allows parallel progress and prioritization -based on risk. (This is a lesson we learned when deploying other security -controls at scale throughout Google.) We expect SLSA ratings to be composed to -describe a supply chain's overall security stance, as described in the case -study [vision](../../example.md#vision-case-study). - -## Q: What about reproducible builds? - -When talking about [reproducible builds](https://reproducible-builds.org), there -are two related but distinct concepts: "reproducible" and "verified -reproducible." - -"Reproducible" means that repeating the build with the same inputs results in -bit-for-bit identical output. This property -[provides](https://reproducible-builds.org/docs/buy-in/) -[many](https://wiki.debian.org/ReproducibleBuilds/About) -[benefits](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri), -including easier debugging, more confident cherry-pick releases, better build -caching and storage efficiency, and accurate dependency tracking. - -"Verified reproducible" means using two or more independent build platforms to -corroborate the provenance of a build. In this way, one can create an overall -platform that is more trustworthy than any of the individual components. This is -often -[suggested](https://www.linuxfoundation.org/en/blog/preventing-supply-chain-attacks-like-solarwinds/) -as a solution to supply chain integrity. Indeed, this is one option to secure -build steps of a supply chain. When designed correctly, such a platform can -satisfy all of the SLSA Build level requirements. - -That said, verified reproducible builds are not a complete solution to supply -chain integrity, nor are they practical in all cases: - -- Reproducible builds do not address source, dependency, or distribution - threats. -- Reproducers must truly be independent, lest they all be susceptible to the - same attack. For example, if all rebuilders run the same pipeline software, - and that software has a vulnerability that can be triggered by sending a - build request, then an attacker can compromise all rebuilders, violating the - assumption above. -- Some builds cannot easily be made reproducible, as noted above. -- Closed-source reproducible builds require the code owner to either grant - source access to multiple independent rebuilders, which is unacceptable in - many cases, or develop multiple, independent in-house rebuilders, which is - likely prohibitively expensive. - -Therefore, SLSA does not require verified reproducible builds directly. Instead, -verified reproducible builds are one option for implementing the requirements. - -For more on reproducibility, see -[Hermetic, Reproducible, or Verifiable?](https://google.github.io/building-secure-and-reliable-systems/raw/ch14.html#hermeticcomma_reproduciblecomma_or_veri) - -## Q: How does SLSA relate to in-toto? - -[in-toto](https://in-toto.io/) is a framework to secure software supply chains -hosted at the [Cloud Native Computing Foundation](https://cncf.io/). The in-toto -specification provides a generalized workflow to secure different steps in a -software supply chain. The SLSA specification recommends -[in-toto attestations](https://github.com/in-toto/attestation) as the vehicle to -express Provenance and other attributes of software supply chains. Thus, in-toto -can be thought of as the unopinionated layer to express information pertaining -to a software supply chain, and SLSA as the opinionated layer specifying exactly -what information must be captured in in-toto metadata to achieve the guarantees -of a particular level. - -in-toto's official implementations written in -[Go](https://github.com/in-toto/in-toto-golang), -[Java](https://github.com/in-toto/in-toto-java), and -[Rust](https://github.com/in-toto/in-toto-rs) include support for generating -SLSA Provenance metadata. These APIs are used in other tools generating SLSA -Provenance such as Sigstore's cosign, the SLSA GitHub Generator, and the in-toto -Jenkins plugin. - -## Q. What is the difference between a build platform, system, and service? - -Build platform and build system have been used interchangeably in the past. With -the v1.0 specification, however, there has been a unification around the term -platform as indicated in the [Terminology](terminology.md). The use of the word -`system` still exists related to software and services within the build platform -and to systems outside of a build platform like change management systems. - -A build service is a hosted build platform that is often run on shared infrastructure -instead of individuals' machines and workstations. Its use has also been replaced outside -of the requirements as it relates to the build platform. - -## Q: Is SLSA the same as TACOS? - -No. -[Trusted Attestation and Compliance for Open Source (TACOS)](https://github.com/tacosframework) -is a framework authored by Tidelift. -Per their website, TACOS is a framework -"for assessing the development practices of open source projects -against a set of secure development standards specified by the (US) -NIST Secure Software Development Framework (SSDF) V1.1" which -"vendors can use to provide self-attestation for the open source components -they rely on." - -In contrast, SLSA is a community-developed framework---including -adoptable guidelines for securing a software supply chain and -mechanism to evaluate the trustworthiness of artifacts you consume---that -is part of the Open Source Security Foundation (OpenSSF). - -## Q: How does SLSA and SLSA Provenance relate to SBOM? - -[Software Bill of Materials (SBOM)] are a frequently recommended tool for -increased software supply chain rigor. An SBOM is typically focused on -understanding software in order to evaluate risk through known vulnerabilities -and license compliance. These use-cases require fine-grained and timely data -which can be refined to improve signal-to-noise ratio. - -[SLSA Provenance] and the [Build track] are focused on trustworthiness of the -build process. To improve trustworthiness, Provenance is generated in the build -platform's trusted control plane, which in practice results in it being coarse -grained. For example, in Provenance metadata completeness of -`resolvedDependencies` information is on a best-effort basis. Further, the -`ResourceDescriptor` type does not require version and license information or -even a URI to the dependency's original location. - -While they likely include similar data, SBOMs and SLSA Provenance operate at -different levels of abstraction. The fine-grained data in an SBOM typically -describes the components present in a produced artifact, whereas SLSA -Provenance more coarsely describes parameters of a build which are external to -the build platform. - -The granularity and expressiveness of the two use-cases differs enough that -current SBOM formats were deemed not a good fit for the requirements of -the Build track. Yet SBOMs are a good practice and may form part of a future -SLSA Vulnerabilities track. Further, SLSA Provenance can increase the -trustworthiness of an SBOM by describing how the SBOM was created. - -SLSA Provenance, the wider [in-toto Attestation Framework] in which the -recommended format sits, and the various SBOM standards, are all rapidly -evolving spaces. There is ongoing investigation into linking between the -different formats and exploration of alignment on common models. This FAQ entry -describes our understanding of the intersection efforts today. We do not know -how things will evolve over the coming months and years, but we look forward to -the collaboration and improved software supply chain security. - -## Q: How to SLSA with a self-hosted runner - -Some CI systems allow producers to provide their own self-hosted runners as a build -environment (e.g. [GitHub Actions]). While there are many valid reasons to leverage -these, classifying the SLSA build level for the resulting artifact can be confusing. - -Since the SLSA Build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance, interpretation of the -specification hinges on the platform entities involved in the provenance generation. -The SLSA [build level requirements] (secure key storage, isolation, etc.) should be -imposed on the transitive closure of the systems which are responsible for informing -the provenance generated. - -Some common situations may include: - -- The platform generates the provenance and just calls a runner for individual items. - In this situation, the provenance is only affected by the platform so there would be - no requirements imposed on the runner. -- The runner generates the provenance. In this situation, the orchestrating platform - is irrelevant and all requirements are imposed on the runner. -- The platform provides the runner with some credentials for generating the provenance - or both the platform and the runner provide information for the provenance. Trust is - shared between the platform and the runner so the requirements are imposed on both. - -Additional requirements on the self-hosted runners may be added to Build levels -greater than L3 when such levels get defined. - -[build level requirements]: build-requirements.md -[GitHub Actions]: https://docs.github.com/en/actions/hosting-your-own-runners -[Software Bill of Materials (SBOM)]: https://ntia.gov/sbom -[SLSA Provenance]: provenance.md -[Build track]: build-track-basics.md -[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/ diff --git a/docs/spec/v1.2/future-directions.md b/docs/spec/v1.2/future-directions.md deleted file mode 100644 index a9401758a..000000000 --- a/docs/spec/v1.2/future-directions.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Future directions -description: The initial draft version (v0.1) of SLSA had a larger scope including protections against tampering with source code and a higher level of build integrity (Build L4). This page collects some early thoughts on how SLSA **might** evolve in future versions to re-introduce these notions and add other additional aspects of automatable supply chain security. ---- - -The initial [draft version (v0.1)] of SLSA had a larger scope including -protections against tampering with source code and a higher level of build -integrity (Build L4). This page collects some early thoughts on how SLSA -**might** evolve in future versions to re-introduce those notions and add other -additional aspects of automatable supply chain security. - -
- -## Build track - -### Build L4 - -A build L4 could include further hardening of the build platform and enabling -corroboration of the provenance, for example by providing complete knowledge of -the build inputs. - -The initial [draft version (v0.1)] of SLSA defined a "SLSA 4" that included the -following requirements, which **may or may not** be part of a future Build L4: - -- Pinned dependencies, which guarantee that each build runs on exactly the - same set of inputs. -- Hermetic builds, which guarantee that no extraneous dependencies are used. -- All dependencies listed in the provenance, which enables downstream verifiers - to recursively apply SLSA to dependencies. -- Reproducible builds, which enable other build platforms to corroborate the - provenance. - -
- -
- -## Platform Operations track - -A Platform Operations track could provide assurances around the hardening of -platforms (e.g. build or source platforms) as they are operated. - -The initial [draft version (v0.1)] of SLSA included a section on -[common requirements](../v0.1/requirements.md#common-requirements) that formed -the foundation of the guidance for -[assessing build platforms](assessing-build-platforms.md), which **may or may not** form -the basis for a future Build Platform Operations track: - -- Controls for approval, logging, and auditing of all physical and remote - access to platform infrastructure, cryptographic secrets, and privileged - debugging interfaces. -- Conformance to security best practices to minimize the risk of compromise. -- Protection of cryptographic secrets used by the build platform. - -
- -[draft version (v0.1)]: ../v0.1/requirements.md diff --git a/docs/spec/v1.2/images/build-env-model.svg b/docs/spec/v1.2/images/build-env-model.svg deleted file mode 100755 index ad3f8dba6..000000000 --- a/docs/spec/v1.2/images/build-env-model.svg +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2/images/build-model.svg b/docs/spec/v1.2/images/build-model.svg deleted file mode 100644 index 9d6bed6ca..000000000 --- a/docs/spec/v1.2/images/build-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2/images/provenance-model.svg b/docs/spec/v1.2/images/provenance-model.svg deleted file mode 100644 index 028dad49e..000000000 --- a/docs/spec/v1.2/images/provenance-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2/images/source-control-system-components.svg b/docs/spec/v1.2/images/source-control-system-components.svg deleted file mode 100644 index d0e9dded3..000000000 --- a/docs/spec/v1.2/images/source-control-system-components.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2/images/supply-chain-model.svg b/docs/spec/v1.2/images/supply-chain-model.svg deleted file mode 100644 index 6a37ffa05..000000000 --- a/docs/spec/v1.2/images/supply-chain-model.svg +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2/images/supply-chain-threats-build-verification.svg b/docs/spec/v1.2/images/supply-chain-threats-build-verification.svg deleted file mode 100644 index 2888f6215..000000000 --- a/docs/spec/v1.2/images/supply-chain-threats-build-verification.svg +++ /dev/null @@ -1,88 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2/images/supply-chain-threats.svg b/docs/spec/v1.2/images/supply-chain-threats.svg deleted file mode 100644 index 38421111d..000000000 --- a/docs/spec/v1.2/images/supply-chain-threats.svg +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/spec/v1.2/images/verification-model.svg b/docs/spec/v1.2/images/verification-model.svg deleted file mode 100644 index a29507e08..000000000 --- a/docs/spec/v1.2/images/verification-model.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/v1.2/index.md b/docs/spec/v1.2/index.md deleted file mode 100644 index e73eb0a1e..000000000 --- a/docs/spec/v1.2/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: SLSA specification -description: SLSA is a specification for describing and incrementally improving supply chain security, established by industry consensus. It is organized into a series of levels that describe increasing security guarantees. ---- - -SLSA is a specification for describing and incrementally improving supply chain -security, established by industry consensus. It is organized into a series of -levels that describe increasing security guarantees. - -This is **Version 1.2** of the SLSA specification. It defines several SLSA -levels and tracks, as well as recommended attestation formats, including -provenance. - -{%- for section in site.data.nav.main %} -{%- if section.url == page.url %} -{%- for subsection in section.children %} -{%- if subsection.children %} - -## {{ subsection.title }} - -{{ subsection.description }} - - - -| Page | Description -| ---- | ----------- -{%- for child in subsection.children %} -| [{{child.title}}]({{child.url | relative_url}}) | {{child.description}} -{%- endfor %} - - -{%- endif %} -{%- endfor %} -{%- endif %} -{%- endfor %} diff --git a/docs/spec/v1.2/onepage.md b/docs/spec/v1.2/onepage.md deleted file mode 100644 index 63e1011bb..000000000 --- a/docs/spec/v1.2/onepage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SLSA Specification -description: A one-page rendering of all that is included in the SLSA Working Draft. -noindex: true ---- -{%- comment -%} -A single page containing all the following files as different sections -{%- endcomment -%} - -{% assign dir = "/spec/v1.2/" %} -{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,tracks,build-track-basics,terminology,build-requirements,distributing-provenance,verifying-artifacts,assessing-build-platforms,source-requirements,verifying-source,assessing-source-systems,source-example-controls,threats,attestation-model,provenance,build-provenance,verification_summary" %} - -{% include onepage.liquid dir=dir filenames=filenames %} diff --git a/docs/spec/v1.2/principles.md b/docs/spec/v1.2/principles.md deleted file mode 100644 index 535c75a7f..000000000 --- a/docs/spec/v1.2/principles.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Guiding principles -description: An introduction to the guiding principles behind SLSA's design decisions. ---- - -This page is an introduction to the guiding principles behind SLSA's design -decisions. - -## Simple levels with clear outcomes - -Use [levels](about#how-slsa-works) to communicate security state and to -encourage a large population to improve its security stance over time. When -necessary, split levels into separate tracks to recognize progress in unrelated -security areas. - -**Reasoning:** Levels simplify how to think about security by boiling a complex -topic into an easy-to-understand number. It is clear that level N is better than -level N-1, even to someone with passing familiarity. This provides a convenient -way to describe the current security state as well as a natural path to improvement. - -Guidelines: - -- **Define levels in terms of concrete security outcomes.** Each level should - have clear and meaningful security value, such as stopping a particular - class of threats. Levels should represent security milestones, not just - incremental progress. Give each level an easy-to-remember mnemonic, such as - "Provenance exists." - -- **Balance level granularity.** Too many levels makes SLSA hard to understand - and remember; too few makes each level hard to achieve. Collapse levels - until each step requires a non-trivial but manageable amount of work to - implement. Separate levels if they require significant work from multiple - distinct parties, such as infrastructure work plus user behavior changes, so - long as the intermediate level still has some security value (prior bullet). - -- **Use tracks sparingly.** Additional tracks add extra complexity to SLSA, so - a new track should be seen as a last resort. Each track should have a clear, - distinct purpose with a crisply defined objective, such as trustworthy - provenance for the [Build track](levels#build-track). As a rule of thumb, a - new track may be warranted if it addresses threats unrelated to another - track. Try to avoid tracks that sound confusingly similar in either name or - objective. - -## Trust platforms, verify artifacts - -Establish trust in a small number of platforms and systems---such as change management, build, -and packaging platforms---and then automatically verify the many artifacts -produced by those platforms. - -**Reasoning**: Trusted computing bases are unavoidable---there's no choice but -to trust some platforms. Hardening and verifying platforms is difficult and -expensive manual work, and each trusted platform expands the attack surface of the -supply chain. Verifying that an artifact is produced by a trusted platform, -though, is easy to automate. - -To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited -number of platforms and then automate verification of the artifacts produced by those platforms. -The attack surface and work to establish trust do not scale with the number of artifacts produced, -as happens when artifacts each use a different trusted platform. - -**Benefits**: Allows SLSA to scale to entire ecosystems or organizations with a near-constant -amount of central work. - -### Example - -A security engineer analyzes the architecture and implementation of a build -platform to ensure that it meets the SLSA Build Track requirements. Following the -analysis, the public keys used by the build platform to sign provenance are -"trusted" up to the given SLSA level. Downstream platforms verify the provenance -signed by the public key to automatically determine that an artifact meets the -SLSA level. - -### Corollary: Minimize the number of trusted platforms - -A corollary to this principle is to minimize the size of the trusted computing -base. Every platform we trust adds attack surface and increases the need for -manual security analysis. Where possible: - -- Concentrate trust in shared infrastructure. For example, instead of each - team within an organization maintaining their own build platform, use a - shared build platform. Hardening work can be shared across all teams. -- Remove the need to trust components. For example, use end-to-end signing - to avoid the need to trust intermediate distribution platforms. - -## Trust code, not individuals - -Securely trace all software back to source code rather than trust individuals who have write access to package registries. - -**Reasoning**: Code is static and analyzable. Individuals, on the other hand, are prone to mistakes, -credential compromise, and sometimes malicious action. - -**Benefits**: Removes the possibility for a trusted individual---or an -attacker abusing compromised credentials---to tamper with source code -after it has been committed. - -## Prefer attestations over inferences - -Require explicit attestations about an artifact's provenance; do not infer -security properties from a platform's configurations. - -**Reasoning**: Theoretically, access control can be configured so that the only path from -source to release is through the official channels: the CI/CD platform pulls only -from the proper source, package registry allows access only to the CI/CD platform, -and so on. We might infer that we can trust artifacts produced by these platforms -based on the platform's configuration. - -In practice, though, these configurations are almost impossible to get right and -keep right. There are often over-provisioning, confused deputy problems, or -mistakes. Even if a platform is configured properly at one moment, it might not -stay that way, and humans almost always end up getting in the access control -lists. - -Access control is still important, but SLSA goes further to provide defense in depth: it **requires proof in -the form of attestations that the package was built correctly**. - -**Benefits**: The attestation removes intermediate platforms from the trust base and ensures that -individuals who are accidentally granted access do not have sufficient permission to tamper with the package. - -## Support anonymous and pseudonymous contributions - -SLSA supports anonymous and pseudonymous 'identities' within the software supply chain. -While organizations that implement SLSA may choose otherwise, SLSA itself does not require, -or encourage, participants to be mapped to their legal identities. - -**Nothing in this specification should be taken to mean that SLSA requires participants to -reveal their legal identity.** - -**Reasoning**: SLSA uses identities for multiple purposes: as a trust anchor for attestations -(i.e. who or what is making this claim and do I trust it to do so) or for attributing actions -to an actor. Choice of identification technology is left to the organization and technical -stacks implementing the SLSA standards. - -When identities are strongly authenticated and used consistently they can often be leveraged -for both of these purposes without requiring them to be mapped to legal identities. -This reflects how identities are often used in open source where legal name means much less -to projects than the history and behavior of a given handle over time does. Meanwhile, some -organizations may choose to levy additional requirements on identities. They are free to do -so, but SLSA itself does not require it. - -**Benefits**: By _not_ requiring legal identities SLSA lowers the barriers to its adoption, -enabling all of its other benefits and maintaining support for anonymous and pseudonymous -contribution as has been practiced in the software industry for decades. diff --git a/docs/spec/v1.2/provenance.md b/docs/spec/v1.2/provenance.md deleted file mode 100644 index 769ed89d0..000000000 --- a/docs/spec/v1.2/provenance.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Provenance -description: Provides a description of the concept of provenance and links to the various tracks specific definitions. ---- - -In SLSA 'provenance' refers to verifiable information that can be used to track -an artifact back, through all the moving parts in a complex supply chain, to -where it came from. It’s the verifiable information about software artifacts -describing where, when, and how something was produced. - -The different SLSA tracks may have their own, more specific, implementations of -provenance to account for their unique needs. - -NOTE: If you landed here via the -[in-toto attestation](https://github.com/in-toto/attestation) predicate type -`https://slsa.dev/provenance/v1` please see -[Build provenance](build-provenance.md). - -- [Build provenance](build-provenance.md) - tracks the output of a build process - back to the source code used to produce that output. -- [Source provenance](source-requirements#source-provenance-attestations) - tracks the - creation of source code revisions and the change management processes - that were in place during their creation. diff --git a/docs/spec/v1.2/requirements.md b/docs/spec/v1.2/requirements.md deleted file mode 100644 index 825e9b22a..000000000 --- a/docs/spec/v1.2/requirements.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Requirements -description: This page links to the requirements pages of the individual tracks. ---- - -SLSA is composed of [multiple tracks](about#how-slsa-works). Each track has its -own set of requirements. Follow the links below to find the requirements for -each track. - -- [Build Track Requirements](build-requirements.md) -- [Source Track Requirements](source-requirements.md) diff --git a/docs/spec/v1.2/schema/provenance.cue b/docs/spec/v1.2/schema/provenance.cue deleted file mode 100644 index 22bc5e0d8..000000000 --- a/docs/spec/v1.2/schema/provenance.cue +++ /dev/null @@ -1,48 +0,0 @@ -{ - // Standard attestation fields: - "_type": "https://in-toto.io/Statement/v1", - "subject": [...], - - // Predicate: - "predicateType": "https://slsa.dev/provenance/v1", - "predicate": { - "buildDefinition": { - "buildType": string, - "externalParameters": object, - "internalParameters": object, - "resolvedDependencies": [ ...#ResourceDescriptor ], - }, - "runDetails": { - "builder": { - "id": string, - "builderDependencies": [ ...#ResourceDescriptor ], - "version": { ...string }, - }, - "metadata": { - "invocationId": string, - "startedOn": #Timestamp, - "finishedOn": #Timestamp, - }, - "byproducts": [ ...#ResourceDescriptor ], - } - } -} - -#ResourceDescriptor: { - "uri": string, - "digest": { - "sha256": string, - "sha512": string, - "gitCommit": string, - [string]: string, - }, - "name": string, - "downloadLocation": string, - "mediaType": string, - "content": bytes, // base64-encoded - "annotations": { - [string]: _ // any JSON type - } -} - -#Timestamp: string // --
T::Z diff --git a/docs/spec/v1.2/schema/provenance.proto b/docs/spec/v1.2/schema/provenance.proto deleted file mode 100644 index ae0a71ee1..000000000 --- a/docs/spec/v1.2/schema/provenance.proto +++ /dev/null @@ -1,50 +0,0 @@ -syntax = "proto3"; - -package slsa.v1; - -import "google/protobuf/struct.proto"; -import "google/protobuf/timestamp.proto"; - -// NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the -// provenance is always serialized using JSON with lowerCamelCase. Protobuf -// tooling performs this case conversion automatically. - -message Provenance { - BuildDefinition build_definition = 1; - RunDetails run_details = 2; -} - -message BuildDefinition { - string build_type = 1; - google.protobuf.Struct external_parameters = 2; - google.protobuf.Struct internal_parameters = 3; - repeated ResourceDescriptor resolved_dependencies = 4; -} - -message ResourceDescriptor { - string uri = 1; - map digest = 2; - string name = 3; - string download_location = 4; - string media_type = 5; - bytes content = 6; - map annotations = 7; -} - -message RunDetails { - Builder builder = 1; - BuildMetadata metadata = 2; - repeated ResourceDescriptor byproducts = 3; -} - -message Builder { - string id = 1; - map version = 2; - repeated ResourceDescriptor builder_dependencies = 3; -} - -message BuildMetadata { - string invocation_id = 1; - google.protobuf.Timestamp started_on = 2; - google.protobuf.Timestamp finished_on = 3; -} diff --git a/docs/spec/v1.2/source-example-controls.md b/docs/spec/v1.2/source-example-controls.md deleted file mode 100644 index 4da1044d4..000000000 --- a/docs/spec/v1.2/source-example-controls.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -title: "Source: Example controls" -description: "This page provides examples of additional controls that - organizations may want to implement as they adopt the SLSA Source track." ---- - -At SLSA Source L3+ organizations are allowed and encouraged to define their own -controls that go over and above specific requirements outlined by SLSA. This -page provides some examples of what these additional controls could be. - -If an organization has indicated that use of these controls is part of -their repository's expectations, consumers SHOULD be able to verify that the -process was followed for the revision they are consuming by examining the -[summary](./source-requirements#source-verification-summary-attestation) or -[source provenance](./source-requirements#source-provenance-attestations) -attestations. - -> For example: consumers can look for the related `ORG_SOURCE` properties in -> the `verifiedLevels` field of the [summary -> attestation](./source-requirements#source-verification-summary-attestation). - -## Expert Code Review - -
-
Summary
- -All changes to the source are pre-approved by experts. - -
Intended for
- -Enterprise repositories and mature open source projects. - -
Benefits
- -Prevents mistakes by developers unfamiliar with the area. - -
- -### Requirements - -- **Code ownership** - - Each part of the source MUST have a clearly identified set of experts. - -- **Approvals from all relevant experts** - - For each portion of the source modified by a change proposal, pre-approval - MUST be granted by a member of the defined expert set. An approval from an - actor that is a member of multiple expert groups may satisfy the - requirement for all groups in which they are a member. - -## Review Every Single Revision - -
-
Summary
- -The final revision was reviewed by experts prior to submission. - -
Intended for
- -The highest-of-high-security-posture repos. - -
Benefits
- -Provides maximum chance for experts to spot problems. - -
- -### Requirements - -- **Reset votes on all changes** - - If the proposal is modified after receiving expert approval, all previously - granted approvals MUST be revoked. A new approval MUST be granted from ALL - required reviewers. - - The new approval MAY be granted by an actor who approved a previous - iteration. - -## Automated testing - -
-
Summary
- -The final revision was validated by automated tests. - -
Intended for
- -All organizations and repositories. - -
Benefits
- -Improves accuracy, prevents errors, and reduces human load. - -
- -### Requirements - -The organization MUST configure a branch protection rule to require that only -revisions with passing test results can be pointed-to by the branch. - -Automatic tests SHOULD be executed in a trustworthy environment (see SLSA -build track). - -Results of each test (or an aggregate) MUST be collected by the change review -tool and made available for verification. - -Tests SHOULD be run against a revision created for testing by merging the topic -branch (containing the proposed changes) into the target branch. - -Use of the proposed merge commit should be preferred to using the tip of the -topic branch. - -## Every revision reachable from a branch was approved - -
-
Summary
- -New revisions are created based ONLY on approved changes. - -
Intended for
- -All organizations and repositories. - -
Benefits
- -Prevents attacks that hide malicious, unreviewed commits. - -
- -### Context - -In many organizations, it is normal to review only the "net difference" -between the tip of the topic branch and the "best merge base", the closest -shared commit between the topic and target branches computed at the time of -review. - -The topic branch may contain many commits of which not all were intended to -represent a shippable state of the repository. - -If a repository merges branches with a standard merge commit, all those -unreviewed commits on the topic branch will become "reachable" from the -protected branch by virtue of the multi-parent merge commit. - -When a repo is cloned, all commits _reachable_ from the main branch are -fetched and become accessible from the local checkout. - -This combination of factors allows attacks where the victim performs a `git -clone` operation followed by a `git reset --hard `. - -### Requirements - -- **Informed Review** - - The reviewer is able and encouraged to make an informed decision about - what they're approving. The reviewer MUST be presented with a full, - meaningful content diff between the proposed revision and the - previously reviewed revision. - - It is not sufficient to indicate that a file changed without showing - the contents. - -- **Use only rebase operations on the protected branch** - - Require a squash merge strategy for the protected branch. - - To guarantee that only commits representing reviewed diffs are cloned, - the SCS MUST rebase (or "squash") the reviewed diff into a single new - commit (the "squashed" commit) that has only a single parent (the - revision previously pointed-to by the protected branch). This is - different than a standard merge commit strategy which would cause all - the user-contributed commits to become reachable from the protected - branch via the second parent. - - It is not acceptable to replay the sequence of commits from the topic - branch onto the protected branch. The intent is to reduce the accepted - changes to the exact diffs that were reviewed. Constituent commits of - the topic branch may or may not have been reviewed on an individual - basis, and should not become reachable from the protected branch. - -## Immutable Change Discussion - -
-
Summary
- -The discussion around a change is preserved and immutable. - -
Intended for
- -Large orgs, or where discussion is vital to change management. - -
Benefits
- -Enables future education, forensics, and security auditing. - -
- -### Requirements - -The SCS SHOULD record a description of the proposed change and all discussions -/ commentary related to it. - -The SCS MUST link this discussion to the revision itself. This is regularly -done via commit metadata. - -All collected content SHOULD be made immutable if the change is accepted. It -SHOULD NOT be possible to edit the discussion around a revision after it has -been accepted. - -## Merge trains - -
-
Summary
- -A buffer branch (or "train") collects a certain number of approved changes -before merging into the protected branch. - -
Intended for
- -Large organizations with high-velocity repositories where the protected branch -needs to remain stable for longer periods. - -
Benefits
- -Allows more time for human and automatic code review by stabilizing the -protected branch. - -
- -### Requirements - -Large organizations must keep the number of updates to key protected branches -under certain limits to allow time for code review to happen. For example, if -a team tries to merge 60 change requests per hour into the `main` branch, the -tip of the `main` branch would only be stable for about 1 minute. This would -leave only 1 minute for a new diff to be both generated and reviewed before -it becomes stale again. - -The normal way to work in this environment is to create a buffer branch -(sometimes called a "train") to collect a certain number of approved changes. -In this model, when a change is approved for submission to the protected -branch, it is added to the train branch instead. After a certain amount of -time, the train branch will be merged into the protected branch. If there are -problems detected with the contents on the train branch, it's normal for the -whole train to be abandoned and a new train to be formed. Approved changes -will be re-applied to a new train in this scenario. - -The key benefit to this approach is that the protected branch remains stable -for longer, allowing more time for human and automatic code review. A key -downside to this approach is that organizations will not know the final -revision ID that represents a change until the entire train process completes. - -A change review process will now be associated with multiple distinct -revisions. - -- ID 1: The revision which was reviewed before concluding the change review - process. It represents the ideal state of the protected branch applying - only this proposed change. -- ID 2: The revision created when the change is applied to the train branch. - It represents the state of the protected branch _after other changes have - been applied_. - -It is important to note that no human or automatic review will have the chance -to pre-approve ID2. This will appear to violate any organization policies that -require pre-approval of changes before submission. The SCS and the -organization MUST protect this process in the same way they protect other -artifact build pipelines. - -At a minimum the SCS MUST issue an attestation that the revision ID generated -by a merged train is identical ("MERGESAME" in git terminology) to the state -of the protected branch after applying each approved changeset in sequence. -No other content may be added or removed during this process. diff --git a/docs/spec/v1.2/source-requirements.md b/docs/spec/v1.2/source-requirements.md deleted file mode 100644 index 6a3b68a1a..000000000 --- a/docs/spec/v1.2/source-requirements.md +++ /dev/null @@ -1,638 +0,0 @@ ---- -title: "Source: Requirements for producing source" -description: "This page covers the detailed technical requirements for producing source revisions at each SLSA level. The intended audience is source control system implementers and security engineers." ---- - -## Objective - -The primary purpose of the SLSA Source track is to provide producers and consumers with increasing levels of trust in the source code they produce and consume. -It describes increasing levels of trustworthiness and completeness of how a source revision was created. - -The expected process for creating a new revision is determined solely by that repository's owner (the organization) who also determines the intent of the software in the repository and administers technical controls to enforce the process. - -Consumers can review attestations to verify whether a particular revision meets their standards. - -## Definitions - -A **Version Control System (VCS)** is a system of software and protocols for -managing the version history of a set of files. Git, Mercurial, and Subversion -are all examples of version control systems. - -The following terms apply to Version Control Systems: - -| Term | Description -| --- | --- -| Source Repository (Repo) | A self-contained unit that holds the content and revision history for a set of files, along with related metadata like Branches and Tags. -| Source Revision | A specific, logically immutable snapshot of the repository's tracked files. It is uniquely identified by a revision identifier, such as a cryptographic hash like a Git commit SHA or a path-qualified sequential number like `25@trunk/` in SVN. A Source Revision includes both the content (the files) and its associated version control metadata, such as the author, timestamp, and parent revision(s). Note: Path qualification is needed for version control systems that represent Branches and Tags using paths, such as Subversion and Perforce. -| Named Reference | A user-friendly name for a specific source revision, such as `main` or `v1.2.3`. -| Change | A modification to the state of the Source Repository, such as creation of a new Source Revision based on a previous Source Revision, or creation, deletion, or modification of a Named Reference. -| Change History | A record of the history of Source Revisions that preceded a specific revision. -| Branch | A Named Reference that moves to track the Change History of a cohesive line of development within a Source Repository. E.g. `main`, `develop`, `feature-x` -| Tag | A Named Reference that is intended to be immutable. Once created, it is not moved to point to a different revision. E.g. `v1.2.3`, `release-20250722` - -> **NOTE:** The 'branch' and 'tag' features within version control systems may -not always align with the 'Branch' and 'Tag' definitions provided in this -specification. For example, in git and other version control systems, the UX may -allow 'tags' to be moved. Patterns like `latest` and `nightly` tags rely on this. -For the purposes of this specification these would be classified as 'Named References' and not as 'Tags'. - -A **Source Control System (SCS)** is a platform or combination of services -(self-hosted or SaaS) that hosts a Source Repository and provides a trusted -foundation for managing source revisions by enforcing policies for -authentication, authorization, and change management, such as mandatory code -reviews or passing status checks. - -The following terms apply to Source Control Systems: - -| Term | Description -| --- | --- -| Organization | A set of people who collectively create Source Revisions within a Source Repository. Examples of organizations include open-source projects, a company, or a team within a company. The organization defines the goals of a Source Repository and the methods used to produce new Source Revisions. -| Proposed Change | A proposal to make a Change in a Source Repository. -| Source Provenance | Information about how a Source Revision came to exist, where it was hosted, when it was generated, what process was used, who the contributors were, and which parent revisions preceded it. - -### Source Roles - -| Role | Description -| --- | --- -| Administrator | A human who can perform privileged operations on one or more projects. Privileged actions include, but are not limited to, modifying the change history and modifying project- or organization-wide security policies. -| Trusted person | A human who is authorized by the organization to propose and approve changes to the source. -| Trusted robot | Automation authorized by the organization to act in explicitly defined contexts. The robot’s identity and codebase cannot be unilaterally influenced. -| Untrusted person | A human who has limited access to the project. They MAY be able to read the source. They MAY be able to propose or review changes to the source. They MAY NOT approve changes to the source or perform any privileged actions on the project. - -## Onboarding - -When onboarding a branch to the SLSA Source Track or increasing the level of -that branch, organizations are making claims about how the branch is managed -from that revision forward. This establishes [continuity](#continuity). - -No claims are made for prior revisions. - -## Basics - -NOTE: This table presents a simplified view of the requirements. See the -[Requirements](#requirements) section for the full list of requirements for each -level. - -| Track/Level | Requirements | Focus -| ----------- | ------------ | ----- -| [Source L1](#source-l1) | Use a version control system. | Generation of discrete Source Revisions for precise consumption. -| [Source L2](#source-l2) | Preserve Change History and generate Source Provenance. | Reliable history through enforced controls and evidence. -| [Source L3](#source-l3) | Enforce organizational technical controls. | Consumer knowledge of guaranteed technical controls. -| [Source L4](#source-l4) | Require code review. | Improved code quality and resistance to insider threats. - -
- -### Level 1: Version controlled - -
-
Summary
- -The source is stored and managed through a modern version control system. - -
Intended for
- -Organizations currently storing source in non-standard ways who want to quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem with minimal impact to their current workflows. - -
Benefits
- -Migrating to the appropriate tools is an important first step on the road to operational maturity. - -
-
-
- -### Level 2: History & Provenance - -
-
Summary
- -Branch history is continuous, immutable, and retained, and the -SCS issues Source Provenance Attestations for each new Source Revision. -The attestations provide contemporaneous, tamper-resistant evidence of when -changes were made, who made them, and which technical controls were enforced. - -
Intended for
- -All organizations of any size producing software of any kind. - -
Benefits
- -Reliable history allows organizations and consumers to track changes to software -over time, enabling attribution of those changes to the actors that made them. -Source Provenance provides strong, tamper-resistant evidence of the process that -was followed to produce a Source Revision. - -
-
-
- -### Level 3: Continuous technical controls - -
-
Summary
- -The SCS is configured to enforce the Organization's technical controls for specific Named References within the Source Repository. - -
Intended for
- -Organizations that want to show evidence of their additional technical controls. - -
Benefits
- -A verifier can use this published data to ensure that a given Source Revision -was created in the correct way by verifying the Source Provenance or VSA. -Provides verifiers strong evidence of all technical controls enforced during the update of a Named Reference. - -
-
-
- -### Level 4: Two-party review - -
-
Summary
- -The SCS requires two trusted persons to review all changes to protected -branches. - -
Intended for
- -Organizations that want strong guarantees that the software they produce is not -subject to unilateral changes that would subvert their intent. - -
Benefits
- -Makes it harder for an actor to introduce malicious changes into the software -and makes it more likely that the source reflects the intent of the -organization. - -
-
- -## Requirements - -Many examples in this document use the -[git version control system](https://git-scm.com/), but use of git is not a -requirement to meet any level on the SLSA source track. - -### Organization - -[Organization]: #organization - - -
RequirementDescriptionL1L2L3L4 - -
Choose an appropriate Source Control System 🔗 - -An organization producing Source Revisions MUST select an SCS capable of reaching -their desired SLSA Source Level. - -> For example, if an organization wishes to produce revisions at Source Level 3, -they MUST choose a Source Control System capable of producing Source Level 3 -attestations. - -✓✓✓✓ - -
Configure the SCS to control access and enforce history 🔗 - -The organization MUST configure access controls to restrict sensitive operations -on the Source Repository. These controls MUST be implemented using the -SCS-provided [Identity Management capability](#identity-management). - -> For example, an organization may configure the SCS to assign users to a -`maintainers` role and only allow users in `maintainers` to make updates to -`main`. - -The SCS MUST be configured to produce a reliable [Change History](#history) for -its consumable Source Revisions. -If the SCS provides this capability by design, no additional controls are needed. -Otherwise the organization MUST provide evidence of [continuous enforcement](#continuity). - -If the SCS supports [Tags](#tag), the SCS MUST be configured to prevent them -from being moved or deleted. - -> For example, if a git tag `release1` is used to indicate a release revision -with ID `abc123`, controls must be configured to prevent that tag from being -updated to any other revision in the future. -Evidence of these controls (and their continuity) will appear in the Source -Provenance documents for revision `abc123`. - -✓✓✓ -
Safe Expunging Process 🔗 - -SCSs MAY allow the organization to expunge (remove) content from a repository -and its change history without leaving a public record of the removed content, -but the organization MUST only allow these changes in order to meet legal or -privacy compliance requirements. Content changed under this process includes -changing files, history, references, or any other metadata stored by the SCS. - -#### Warning - -Removing a revision from a repository is similar to deleting a package version -from a registry: it's almost impossible to estimate the amount of downstream -supply chain impact. - -> For example, in Git, each revision ID is based on the ones before it. -When you remove a revision, you must generate new revisions (and new revision IDs) -for any revisions that were built on top of it. Consumers who took a dependency -on the old revisions may now be unable to refer to the revision they've already -integrated into their products. - -It may be the case that the specific set of changes targeted by a legal takedown -can be expunged in ways that do not impact consumed revisions, which can mitigate -these problems. - -It is also the case that removing content from a repository won't necessarily -remove it everywhere. -The content may still exist in other copies of the repository, either in backups -or on developer machines. - -#### Process - -An organization MUST document the Safe Expunging Process and describe how -requests and actions are tracked and SHOULD log the fact that content was -removed. Different organizations and tech stacks may have different approaches -to the problem. - -SCSs SHOULD have technical mechanisms in place which require an Administrator -plus at least one additional 'trusted person' to trigger any expunging -(removals) made under this process. - -The application of the Safe Expunging Process and the resulting logs MAY be -private to prevent calling attention to potentially sensitive data or to comply -with local laws and regulations. Organizations SHOULD prefer to make logs public -if possible. - -✓✓✓ -
Continuous technical controls 🔗 - -The organization MUST provide evidence of continuous enforcement via technical -controls for any claims made in the Source Provenance attestations or VSAs (see -[control continuity](#continuity)). - -The organization MUST document the meaning of their enforced technical controls. - -> For example, if an organization implements a technical control via a custom -tool (such as required GitHub Actions workflow), it must indicate the name of -this tool, what it accomplishes, and how to find its evidence in the provenance -attestation. - -> For another example, if the organization claims that all consumable Source -Revisions on the `main` branch were tested prior to acceptance, this MUST be -explicitly enforced in the SCS. - -✓✓ - -
- -### Source Control System - - -
RequirementDescriptionL1L2L3L4 - -
Repositories are uniquely identifiable 🔗 - -The repository ID is defined by the SCS and MUST be uniquely identifiable within -the context of the SCS with a stable locator, such as a URI. - -✓✓✓✓ -
Revisions are immutable and uniquely identifiable 🔗 -The revision ID is defined by the SCS and MUST be uniquely identifiable within the context of the repository. -When the revision ID is a digest of the content of the revision (as in git) nothing more is needed. -When the revision ID is a number or otherwise not a digest, then the SCS MUST document how the immutability of the revision is established. -The same revision ID MAY be present in multiple repositories. - -See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). - -✓✓✓✓ -
Human readable changes 🔗 - -The SCS MUST provide tooling to display Changes between one Source Revision and -another in a human readable form (e.g. 'diffs') for all plain-text changes and -SHOULD provide mechanisms to provide human understandable interpretations of -non-plain-text changes (e.g. render images, verify and display provenance for -binaries, etc.). - -✓✓✓✓ -
Source Verification Summary Attestations 🔗 - -The SCS MUST generate a -[source verification summary attestation](#source-verification-summary-attestation) (Source VSA) -to indicate the SLSA Source Level of any revision at Level 1 or above. - -If a consumer is authorized to access a revision, they MUST be able to fetch the -corresponding Source VSA. - -If the SCS DOES NOT generate a VSA for a revision, the revision has Source Level -0. - -At Source Levels 1 and 2 the SCS MAY issue these attestations based on its -understanding of the underlying system (e.g. based on design docs, security -reviews, etc.), but at Level 2+ the SCS MUST use the SCS-issued -[source provenance](#source-provenance) when issuing the VSAs. - -✓✓✓✓ - -
History 🔗 - -There are three key aspects to change history: - -1. What were all the previous states of a Branch? -2. How and when did they change? -3. How does the current revision relate to previous revisions? - -To answer these questions, the SCS MUST record all changes to Named References, -including when they occurred, who made them, and the new Source Revision ID. - -If Source Revisions have ancestry relationships in the VCS, the SCS MUST ensure -that a Branch can only be updated to point to revisions that descend from the -current revision. -In git, this requires a technical control to prohibit `git push --force`. - -This requirement captures evidence that the organization intended to make the -changes captured by the new revision. - -> For example, if a branch currently points to revision `a`, it may only be -moved to a new revision `b` if `a` is an ancestor of `b`. - -✓✓✓ -
Continuity 🔗 - -Technical Controls are only effective if they are used continuously in the -history of a Branch. -'Control continuity' reflects an organization's ongoing commitment to a -technical control. - -For each technical control claimed in a VSA, continuity MUST be established and -tracked from a specific start revision. -If there is a lapse in continuity for a specific control, continuity of that -control MUST be re-established from a new revision. - -Exceptions to the continuity requirement are allowed via the [safe expunging process](#safe-expunging-process). - -> For example, the `main` branch currently points to revision `a` when a new -technical control `t` is configured. -The next revision on the `main` branch, `b` will be the first revision that was -protected by `t` and `b` is the first revision in the "continuity" of `t`. -Any revisions added to `main` while `t` is disabled will reset the continuity of `t`. - -✓✓✓ - -
Identity Management 🔗 - -The SCS MUST provide an identity management system or some other means of -identifying and authenticating actors. - -The SCS MUST allow organizations to specify which actors and roles are allowed -to perform sensitive actions within a repository (e.g. creation or updates of -branches, approval of changes). - -Depending on the SCS, identity management may be provided by source control -services (e.g., GitHub, GitLab), implemented using cryptographic signatures -(e.g., using gittuf to manage public keys for actors), or extending existing -authentication systems used by the organization (e.g., Active Directory, Okta, -etc.). - -The SCS MUST document how actors are identified for the purposes of attribution. - -Activities conducted on the SCS SHOULD be attributed to authenticated -identities. - -✓✓✓ - -
Source Provenance 🔗 - -[Source Provenance](#source-provenance-attestations) are attestations that -contain information about how a specific revision was created and how it came to -exist on a protected branch or how a tag came to point at it. They are -associated with the revision identifier delivered to consumers and are a -statement of fact from the perspective of the SCS. The SCS MUST document the -format and intent of all Source Provenance attestations it produces. - -Source Provenance MUST be created contemporaneously with the branch being -updated such that they provide a credible, auditable, record of changes. - -If a consumer is authorized to access a revision, they MUST be able to access the -corresponding Source Provenance documents for that revision. - -It is possible that an SCS can make no claims about a particular revision. - -> For example, this would happen if the revision was created on another SCS, -on an unprotected branch (such as a `topic` branch), or if the revision was not -the result of the expected process. - -✓✓✓ -
Protected Named References 🔗 - -The SCS MUST provide the ability for an organization to enforce customized technical controls for Named References. - -The SCS MUST provide a mechanism for organizations to indicate which Named -References should be protected by technical controls. - -> For example, the organization may instruct the SCS to protect `main` and -`refs/heads/releases/*`, but not `refs/heads/experimental/*` using branch -protection rules (e.g. [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), -[GitLab](https://docs.gitlab.com/ee/user/project/repository/branches/protected.html)) -or via the application and verification of [gittuf](https://github.com/gittuf/gittuf) -policies. - -> For another example, the organization may instruct the SCS to prevent the deletion of -all `refs/tags/releases/*` using tag protection rules -(e.g. [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), -[GitLab](https://docs.gitlab.com/user/project/protected_tags/)) -or via the application and verification of [gittuf](https://github.com/gittuf/gittuf) -policies. - -The SCS MUST - -- Record technical controls enforced on Named References in contemporaneously - produced attestations associated with the corresponding Source Revisions. -- Allow organizations to provide - [organization-specified properties](#additional-properties) to be included in the - [Source VSA](#source-verification-summary-attestation) when the corresponding controls are - enforced. -- Allow organizations to distribute additional attestations related to their - technical controls to consumers authorized to access the corresponding Source - Revision. -- Prevent organization-specified properties from beginning with any value - other than `ORG_SOURCE_`. - -✓✓ -
Two-party review 🔗 - -Changes in protected branches MUST be agreed to by two or more trusted persons prior to submission. -The following combinations are acceptable: - -- Uploader and reviewer are two different trusted persons. -- Two different reviewers are trusted persons. - -Reviews SHOULD cover, at least, security relevant properties of the code. - -**[Final revision approved]** This requirement applies to the final revision -submitted. I.e., if additional changes are made during the review process, those changes MUST -be reviewed as well. - -**[Context-specific approvals]** Approvals are for a specific context, such as a -repo + branch in git. Moving fully reviewed content from one context to another -still requires review. The exact definition of “context” depends on the project, -and this does not preclude well-understood automatic merges, such as cutting a release branch. - -**[Informed Review]** The SCS MUST present reviewers with a clear representation of the result of accepting the proposed change. See [Human Readable Changes](#human-readable-diff). - -**[Trusted Robot Contributions]** An organization MAY choose to grant a Trusted -Robot a perpetual exception to a policy (e.g. a bot may be able to merge a change -that has not been reviewed by two parties). - -Examples: - -- Import and migration bots that move code from one repo to another. -- Dependabot - -✓ -
- -## Communicating source levels - -SLSA source level details are communicated using attestations. -These attestations either refer to a source revision itself or provide context needed to evaluate an attestation that _does_ refer to a revision. - -There are two broad categories of source attestations within the source track: - -1. Source verification summary attestations (Source VSAs): Used to communicate to downstream users what high level security properties a given source revision meets. -2. Source provenance attestations: Provide trustworthy, tamper-proof, metadata with the necessary information to determine what high level security properties a given source revision has. - -To provide interoperability and ensure ease of use, it's essential that the Source VSAs are applicable across all Source Control Systems. -However, due to the significant differences in how SCSs operate and how they may choose to meet the Source Track requirements, it is preferable to -allow for flexibility with the full source provenance attestations. To that end, SLSA leaves source provenance attestations undefined and up to the SCSs to determine -what works best in their environment. - -### Source verification summary attestation - -Source verification summary attestations (Source VSAs) are issued by some authority that has sufficient evidence to make the determination of a given -revision's source level. Source VSAs convey properties about the revision as a whole and summarize properties computed over all -the changes that contributed to that revision over its history. - -The source track issues Source VSAs using the [Verification Summary Attestations](./verification_summary.md) format as follows: - -1. `subject.uri` SHOULD be set to a URI where a human can find details about - the revision. This field is not intended for policy decisions. Instead, it - is only intended to direct a human investigating verification failures. - - For example: `https://github.com/slsa-framework/slsa/commit/6ff3cd75c8c9e0fcedc62bd6a79cf006f185cedb` -2. `subject.digest` MUST include the revision identifier (e.g. `gitCommit`) and MAY include other digests over the contents of the revision (e.g. `gitTree`, `dirHash`, etc.). -SCSs that do not use cryptographic digests MUST define a canonical type that is used to identify immutable revisions and MUST include the repository within the type[^1]. - - For example: `svn_revision_id: svn+https://svn.myproject.org/svn/MyProject/trunk@2019` -3. `subject.annotations.sourceRefs` SHOULD be set to a list of references that pointed to this revision when the attestation was created. The list MAY be non-exhaustive. - - git references MUST be fully qualified (e.g. `refs/heads/main` or `refs/tags/v1.0`) to reduce the likelihood of confusing downstream tooling. -4. `resourceUri` MUST be set to the URI of the repository, preferably using [SPDX Download Location](https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field). -E.g. `git+https://github.com/foo/hello-world`. -5. `verifiedLevels` MUST include the SLSA source track level the SCS asserts the revision meets. One of `SLSA_SOURCE_LEVEL_0`, `SLSA_SOURCE_LEVEL_1`, `SLSA_SOURCE_LEVEL_2`, `SLSA_SOURCE_LEVEL_3`. -MAY include additional properties as asserted by the SCS. The SCS MUST include _only_ the highest SLSA source level met by the revision. -6. `dependencyLevels` MAY be empty as source revisions are typically terminal nodes in a supply chain. For example, this could be used to indicate the source level of any git submodules present in the revision. - -#### Additional properties - -The SLSA source track MAY create additional properties to include in -`verifiedLevels` which attest to other claims concerning a revision. - -The SCS MAY embed additional properties within `verifiedLevels` provided by the -organization as long as they are prefixed by `ORG_SOURCE_` to distinguish them -from other properties the SCS may wish to use. The SCS MUST enforce the use of -this prefix for such properties. An organization MAY further differentiate -properties using: - -- `ORG_SOURCE_` to indicate a property that is meant for consumption by - external consumers. -- `ORG_SOURCE_INTERNAL_` to indicate a property that is not meant for - consumption by external consumers. - -The meaning of the properties is left entirely to the organization. - -#### Populating sourceRefs - -The Source VSA issuer may choose to populate `sourceRefs` in any way they wish. -Downstream users are expected to be familiar with the method used by the issuer. - -Example implementations: - -- Issue a new VSA for each merged Pull Request and add the destination branch to `sourceRefs`. -- Issue a new VSA each time a Named Reference is updated to point to a new revision. - -#### Example - -```json -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "uri": "https://github.com/foo/hello-world/commit/9a04d1ee393b5be2773b1ce204f61fe0fd02366a", - "digest": {"gitCommit": "9a04d1ee393b5be2773b1ce204f61fe0fd02366a"}, - "annotations": {"sourceRefs": ["refs/heads/main", "refs/heads/release_1.0"]} -}], - -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/source_verifier", - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "git+https://github.com/foo/hello-world", - "policy": { - "uri": "https://example.com/slsa_source.policy", - }, - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_SOURCE_LEVEL_3"], -} -``` - -#### How to verify - -See [Verifying Source](./verifying-source.md) for instructions how to verify -VSAs for Source Revisions. - -### Source provenance attestations - -Source provenance attestations provide tamper-proof evidence ([attestation model](attestation-model)) -that can be used to determine what SLSA Source Level or other high-level properties a given revision meets. -This evidence can be used by: - -- an authority as the basis for issuing a [Source VSA](#source-verification-summary-attestation) -- a consumer to cross-check a [Source VSA](#source-verification-summary-attestation) they received for a revision -- a consumer to enforce a more detailed policy than the organization's own process - -SCSs may have different methods of operating that necessitate different forms of evidence. -E.g. GitHub-based workflows may need different evidence than Gerrit-based workflows, which would both likely be different from workflows that -operate over Subversion repositories. - -These differences also mean that, depending on the configuration, the issuers of provenance attestations may vary from implementation to implementation, often because entities with the knowledge to issue them may vary. -The authority that issues [Source VSAs](#source-verification-summary-attestation) MUST understand which entity should issue each provenance attestation type, and ensure all source provenance attestations come from their expected issuers. - -'Source provenance attestations' is a generic term used to refer to any type of attestation that provides evidence of the process used to create a revision. - -Example source provenance attestations: - -- A TBD attestation which describes the revision's parents and the actors involved in creating this revision. -- A "code review" attestation which describes the basics of any code review that took place. -- An "authentication" attestation which describes how the actors involved in any revision were authenticated. -- A [Vuln Scan attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/vuln.md) - which describes the results of a vulnerability scan over the contents of the revision. -- A [Test Results attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/test-result.md) - which describes the results of any tests run on the revision. -- An [SPDX attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md) - which provides a software bill of materials for the revision. -- A [SCAI attestation](https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md) used to - describe which source quality tools were run on the revision. - -Irrespective of the types of provenance attestations generated by an SCS and -their implementations, the SCS MUST document provenance -formats, and how each provenance attestation can be used to reason about the -revision's properties recorded in the summary attestation. - -[^1]: in-toto attestations allow non-cryptographic digest types: https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#supported-algorithms. - -## Future Considerations - -### Authentication - -- Better protection against phishing by forbidding second factors that are not - phishing resistant. -- Protect against authentication token theft by forbidding bearer tokens - (e.g. PATs). -- Including length of continuity in the VSAs diff --git a/docs/spec/v1.2/terminology.md b/docs/spec/v1.2/terminology.md deleted file mode 100644 index 5e4dc968f..000000000 --- a/docs/spec/v1.2/terminology.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: "Build: Terminology" -description: Before diving into the SLSA specification levels, we need to establish a core set of terminology and models to describe what we're protecting. ---- - - -Before diving into the [Build Track](build-track-basics.md), we need to -establish a core set of terminology and models to describe what we're -protecting. - -## Software supply chain - -SLSA's framework addresses every step of the software supply chain - the -sequence of steps resulting in the creation of an artifact. We represent a -supply chain as a [directed acyclic graph] of sources, builds, dependencies, and -packages. One artifact's supply chain is a combination of its dependencies' -supply chains plus its own sources and builds. - -[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph - -![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). -| [Distribution] | The channel through which artifacts are "published" for use by others. | A registry like DockerHub or npm. Artifacts may also be distributed via physical media (e.g., a USB drive). -| Package | Artifact that is distributed. 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 (distribution). 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 -[distribution]: #distribution-model -[SLSA Provenance]: /provenance/v1 - -### Roles - -Throughout the specification, you will see reference to the following roles -that take part in the software supply chain. Note that in practice a role may -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. - -### Build model - -

Model Build

- -We model a build as running on a multi-tenant *build platform*, where each -execution is independent. - -1. A tenant invokes the build by specifying *external parameters* through an - *interface*, either directly or via some trigger. Usually, at least one of - these external parameters is a reference to a *dependency*. (External - parameters are literal values while dependencies are artifacts.) -2. The build platform's *control plane* interprets these external parameters, - fetches an initial set of dependencies, initializes a *build environment*, - and then starts the execution within that environment. -3. The build then performs arbitrary steps, which might include fetching - additional dependencies, and then produces one or more *output* artifacts. - The steps within the build environment are under the tenant's control. - The build platform isolates build environments from one another to some - degree (which is measured by the SLSA Build Level). -4. Finally, for SLSA Build L2+, the control plane outputs *provenance* - describing this whole process. - -Notably, there is no formal notion of "source" in the build model, just external -parameters and dependencies. Most build platforms have an explicit "source" -artifact to build from, which is often a git repository; in the build model, the -reference to this artifact is an external parameter while the artifact itself is -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. - -
Ambiguous terms to avoid - -- *Build recipe:* Could mean *external parameters,* but may include concrete - steps of how to perform a build. To avoid implementation details, we don't - define this term, but always use "external parameters" which is the - interface to a build platform. Similar terms are *build configuration - source* and *build definition*. -- *Builder:* Usually means *build platform*, but might be used for *build - environment*, the user who invoked the build, or a build tool from - *dependencies*. To avoid confusion, we always use "build platform". The only - exception is in the [provenance](/provenance/v1), where `builder` is used as - a more concise field name. - -
- -### Distribution model - -Software is distributed in identifiable units called packages -according to the rules and conventions of a package ecosystem. -Examples of formal ecosystems include [Python/PyPA](https://www.pypa.io), -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format), and -[OCI](https://github.com/opencontainers/distribution-spec), while examples of -informal ecosystems include links to files on a website or distribution of -first-party software within a company. - -Abstractly, a consumer locates software within an ecosystem by asking a -distribution platform, such as a package registry, to resolve a -mutable package name into an immutable package artifact. -[^label] To publish a package artifact, the software producer asks -the registry to update this mapping to resolve to the new artifact. The registry -represents the entity or entities with the power to alter what artifacts are -accepted by consumers for a given package name. For example, if consumers only -accept packages signed by a particular public key, then it is access to that -public key that serves as the registry. - -The package name is the primary security boundary within a package ecosystem. -Different package names represent materially different pieces of -software---different owners, behaviors, security properties, and so on. -Therefore, **the package name is the primary unit being protected in SLSA**. -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 -| ---- | ----------- -| Distribution platform | An entity responsible for mapping package names to immutable package artifacts. -| 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 | A specific type of "distribution platform" used 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 - -- *Package repository:* Could mean either package registry or package name, - depending on the ecosystem. To avoid confusion, we always use "repository" - exclusively to mean "source repository", where there is no ambiguity. -- *Package manager* (without "client"): Could mean either package ecosystem, - package registry, or client-side tooling. - -
- -### Mapping to real-world ecosystems - -Most real-world ecosystems fit the package model above but use different terms. -The table below attempts to document how various ecosystems map to the SLSA -Package model. There are likely mistakes and omissions; corrections and -additions are welcome! - - - - - - - - - - - - - - - - - - - - - - - - - - -
Package ecosystem - Package registry - Package name - Package artifact -
Languages -
Cargo (Rust) - Registry - Crate name - Artifact -
CPAN (Perl) - PAUSE - Distribution - Release (or Distribution) -
Go - Module proxy - Module path - Module -
Maven (Java) - Repository - Group ID + Artifact ID - Artifact -
npm (JavaScript) - Registry - Package Name - Package -
NuGet (C#) - Host - Project - Package -
PyPA (Python) - Index - Project Name - Distribution -
Operating systems -
Dpkg (e.g. Debian) - ? - Package name - Package -
Flatpak - Repository - Application - Bundle -
Homebrew (e.g. Mac) - Repository (Tap) - Package name (Formula) - Binary package (Bottle) -
Pacman (e.g. Arch) - Repository - Package name - Package -
RPM (e.g. Red Hat) - Repository - Package name - Package -
Nix (e.g. NixOS) - Repository (e.g. Nixpkgs) or binary cache - Derivation name - Derivation or store object -
Storage systems -
GCS - n/a - Object name - Object -
OCI/Docker - Registry - Repository - Object -
Meta -
deps.dev: System - Packaging authority - Package - n/a -
purl: type - Namespace - Name - n/a -
- -Notes: - -- Go uses a significantly different distribution model than other ecosystems. - In Go, the package name is a source repository URL. While clients can fetch - directly from that URL---in which case there is no "package" or - "registry"---they usually fetch a zip file from a *module proxy*. The module - proxy acts as both a builder (by constructing the package artifact from - source) and a registry (by mapping package name to package artifact). People - trust the module proxy because builds are independently reproducible, and a - *checksum database* guarantees that all clients receive the same artifact - for a given URL. - -### Verification model - -Verification in SLSA is performed in two ways. Firstly, the build platform is -certified to ensure conformance with the requirements at the level claimed by -the build platform. This certification should happen on a recurring cadence, with -the outcomes published by the platform operator for their users to review and -make informed decisions about which builders to trust. - -Secondly, artifacts are verified to ensure they meet the producer-defined -expectations of where the package source code was retrieved from and on what -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 assessment | [Build platforms are assessed](assessing-build-platforms.md) for their ability to meet 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 assessment | The build platform implementer follows secure design and development best practices, does annual penetration testing exercises, and self-certifies their adherence 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 assessment | Performed by the language ecosystem packaging authority. - -
diff --git a/docs/spec/v1.2/threats-overview.md b/docs/spec/v1.2/threats-overview.md deleted file mode 100644 index 8b2d04a25..000000000 --- a/docs/spec/v1.2/threats-overview.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Supply chain threats -description: Attacks can occur at every link in a typical software supply chain, and these kinds of attacks are increasingly public, disruptive, and costly in today's environment. This page is an introduction to possible attacks throughout the supply chain and how SLSA could help. ---- - -Attacks can occur at every link in a typical software supply chain, and these -kinds of attacks are increasingly public, disruptive, and costly in today's -environment. - -This page is an introduction to possible attacks throughout the supply chain and how -SLSA could help. For a more technical discussion, see [Threats & mitigations](threats.md). - -## Summary - -![Supply Chain Threats](images/supply-chain-threats.svg) - -**Note that SLSA does not currently address all of the threats presented here.** -See [Threats & mitigations](threats.md) for what is currently addressed and -[Terminology](terminology.md) for an explanation of the supply chain model. - -SLSA's primary focus is supply chain integrity, with a secondary focus on -availability. Integrity means protection against tampering or unauthorized -modification at any stage of the software lifecycle. Within SLSA, we divide -integrity into source integrity vs build integrity. - -**Source integrity:** Ensure that the source revision represents the intent of the producer, that all expected processes were followed and that the revision was not modified after being accepted. - -**Build integrity:** Ensure that the package is built from the correct, -unmodified sources and dependencies according to the build recipe defined by the -software producer, and that artifacts are not modified as they pass between -development stages. - -**Availability:** Ensure that the package can continue to be built and -maintained in the future, and that all code and change history is available for -investigations and incident response. - -### Real-world examples - -Many recent high-profile attacks were consequences of supply chain integrity vulnerabilities, and could have been prevented by SLSA's framework. For example: - - - - - - - - - - - - - - - -
-Threats from -Known example -How SLSA could help -
A -Producer -SpySheriff: Software producer purports to offer anti-spyware software, but that software is actually malicious. -SLSA does not directly address this threat but could make it easier to discover malicious behavior in open source software, by forcing it into the publicly available source code. -For closed source software SLSA does not provide any solutions for malicious producers. -
B -Authoring & reviewing -SushiSwap: Contractor with repository access pushed a malicious commit redirecting cryptocurrency to themself. -Two-person review could have caught the unauthorized change. -
C -Source code management -PHP: Attacker compromised PHP's self-hosted git server and injected two malicious commits. -A better-protected source code system would have been a much harder target for the attackers. -
D -External build parameters -The Great Suspender: Attacker published software that was not built from the purported sources. -A SLSA-compliant build server would have produced provenance identifying the actual sources used, allowing consumers to detect such tampering. -
E -Build process -SolarWinds: Attacker compromised the build platform and installed an implant that injected malicious behavior during each build. -Higher SLSA Build levels have stronger security requirements for the build platform, making it more difficult for an attacker to forge the SLSA provenance and gain persistence. -
F -Artifact publication -CodeCov: Attacker used leaked credentials to upload a malicious artifact to a GCS bucket, from which users download directly. -Provenance of the artifact in the GCS bucket would have shown that the artifact was not built in the expected manner from the expected source repo. -
G -Distribution channel -Attacks on Package Mirrors: Researcher ran mirrors for several popular package registries, which could have been used to serve malicious packages. -Similar to above (F), provenance of the malicious artifacts would have shown that they were not built as expected or from the expected source repo. -
H -Package selection -Browserify typosquatting: Attacker uploaded a malicious package with a similar name as the original. -SLSA does not directly address this threat, but provenance linking back to source control can enable and enhance other solutions. -
I -Usage -Default credentials: Attacker could leverage default credentials to access sensitive data. -SLSA does not address this threat. -
N/A -Dependency threats (i.e. A-H, recursively) -event-stream: Attacker controls an innocuous dependency and publishes a malicious binary version without a corresponding update to the source code. -Applying SLSA recursively to all dependencies would prevent this particular vector, because the provenance would indicate that it either wasn't built from a proper builder or that the binary did not match the source. -
- - - - - - -
-Availability threat -Known example -How SLSA could help -
N/A -Dependency becomes unavailable -Mimemagic: Producer intentionally removes package or version of package from repository with no warning. Network errors or service outages may also make packages unavailable temporarily. -SLSA does not directly address this threat. -
- -A SLSA level helps give consumers confidence that software has not been tampered -with and can be securely traced back to source—something that is difficult, if -not impossible, to do with most software today. diff --git a/docs/spec/v1.2/threats.md b/docs/spec/v1.2/threats.md deleted file mode 100644 index 32499a6a6..000000000 --- a/docs/spec/v1.2/threats.md +++ /dev/null @@ -1,1075 +0,0 @@ ---- -title: Threats & mitigations -description: A comprehensive technical analysis of supply chain threats and their corresponding mitigations in SLSA. ---- - -What follows is a comprehensive technical analysis of supply chain threats and -their corresponding mitigations with SLSA and other best practices. For an -introduction to the supply chain threats that SLSA is aiming to protect -against, see [Supply chain threats]. - -The examples on this page are meant to: - -- Explain the reasons for each of the SLSA [build](build-requirements.md) and - [source](source-requirements.md) requirements. -- Increase confidence that the SLSA requirements are sufficient to achieve the - desired [level](about#how-slsa-works) of integrity protection. -- Help implementers better understand what they are protecting against so that - they can better design and implement controls. - - - -
- -## Overview - -![Supply Chain Threats](images/supply-chain-threats.svg) - -This threat model covers the *software supply chain*, meaning the process by -which software is produced and consumed. We describe and cluster threats based -on where in the software development pipeline those threats occur, labeled (A) -through (I). This is useful because priorities and mitigations mostly cluster -along those same lines. Keep in mind that dependencies are -[highly recursive](#dependency-threats), so each dependency has its own threats -(A) through (I), and the same for *their* dependencies, and so on. For a more -detailed explanation of the supply chain model, see -[Terminology](terminology.md). - -Importantly, producers and consumers face *aggregate* risk across all of the -software they produce and consume, respectively. Many organizations produce -and/or consume thousands of software packages, both first- and third-party, and -it is not practical to rely on every individual team in the organization to do -the right thing. For this reason, SLSA prioritizes mitigations that can be -broadly adopted in an automated fashion, minimizing the chance of mistakes. - -## Source threats - -A source integrity threat is a potential for an adversary to introduce a change -to the source code that does not reflect the intent of the software producer. -This includes modification of the source data at rest as well as insider threats, -when an authorized individual introduces an unauthorized change. - -The SLSA Source track mitigates these threats when the consumer -[verifies source](verifying-source.md) against expectations, confirming -that the revision they received was created in the expected manner. - -### (A) Producer - -The producer of the software intentionally produces code that harms the -consumer, or the producer otherwise uses practices that are not deserving of the -consumer's trust. - -
Software producer intentionally creates a malicious revision of the source - -*Threat:* A producer intentionally creates a malicious revision with the intent of harming their consumers. - -*Mitigation:* -This kind of attack cannot be directly mitigated through SLSA controls. -Consumers must establish some basis to trust the organizations from which they consume software. -That basis may be: - -- The repo is open source with an active user-base. High numbers of engaged users may increase the likelihood that bad code is detected during code review and reduce the time-to-detection when bad revisions are accepted. -- The organization has sufficient legal or reputational incentives to dissuade it from making malicious changes. - -Ultimately this is a judgement call with no straightforward answer. - -*Example:* A producer with an otherwise good reputation decides suddenly to produce a malicious artifact with the intent to harm their consumers. - -
- -### (B) Modifying the source - -An adversary without any special administrator privileges attempts to introduce a change counter to the declared intent of the source by following the producer's official source control process. - -Threats in this category can be mitigated by following source control management best practices. - -#### (B1) Submit change without review - -
Directly submit without review(Source L4) - -*Threat:* Malicious code submitted to the source repository. - -*Mitigation:* Require approval of all changes before they are accepted. - -*Example:* Adversary directly pushes a change to a git repo's `main` branch. -Solution: The Source Control System is configured to require two party review for -contributions to the `main` branch. - -
-
Single actor controls multiple accounts - -*Threat:* An actor is able to control multiple account and effectively approve their own code changes. - -*Mitigation:* The producer must ensure that no actor is able to control or influence multiple accounts with review privileges. - -*Example:* Adversary creates a pull request using a secondary account and approves it using their primary account. -Solution: The producer must track all actors who have both explicit review permissions and the independent ability to control -a privileged bot. A common vector for this attack is to influence a robot account with the permission to review or contribute -code. Control of the robot account and an actor's own personal account is enough to exploit this vulnerability. A common -solution to this flow is to deny bot accounts from contributing or reviewing code, or to require more human reviews in those -cases. - -
-
Use a robot account to submit change - -*Threat:* Exploit a robot account that has the ability to submit changes without -two-person review. - -*Mitigation:* All changes require review by two people, even changes authored by -robots. - -*Example:* A file within the source repository is automatically generated by a -robot, which is allowed to submit without review. -Adversary compromises the robot and submits a malicious change. -Solution: Require two-person review for such changes, ignoring the robot. - -
-
Abuse of rule exceptions - -*Threat:* Rule exceptions provide vector for abuse. - -*Mitigation:* Remove rule exceptions. - -*Example:* A producer intends to require two-person review on "all changes except for documentation changes," defined as those only modifying `.md` files. -Adversary submits a malicious executable masquerading as a documentation file, `help.md`. -This avoids the two-person review rule due to the exception. -In the future, a user (or another workflow) can be induced to *execute* `help.md` and become compromised. -Technically the malicious code change met all defined policies yet the intent of the organization was defeated. -Solution: The producer adjusts the rules to prohibit such exceptions. - -
- -
Highly-permissioned actor bypasses or disables controls(verification) - -*Threat:* Trusted actor with "admin" privileges in a repository submits code by disabling existing controls. - -*Mitigation:* The Source Control System must have controls in place to prevent -and detect abusive behavior from administrators (e.g. two-person approvals, -audit logging). - -*Example:* GitHub repository-level admin removes a branch protection requirement, pushes -their change, then re-enables the requirement to cover their tracks. -Solution: Consumers do not accept claims from the Source Control System unless -they trust sufficient controls are in place to prevent repo admins from -abusing privileges. - -
- -#### (B2) Evade change management process - -
Alter change history(Source L2+) - -*Threat:* Adversary alters branch history to hide malicious activity. - -*Mitigation:* The Source Control System prevents branch history from being -altered. - -*Example:* Adversary submits a malicious commit `X` to the `main` branch. A -release is built and published from `X`. The adversary then "force pushes" -to `main` erasing the record of the malicious commit. Solution: The Source -Control System is configured to prevent force pushes to `main`. - -
-
Replace tagged content with malicious content(Source L2+) - -*Threat:* Adversary alters a tag to point at malicious content. - -*Mitigation:* The Source Control System does not allow protected tags to be updated. - -*Example:* Adversary crafts a malicious commit `X` on a development branch which -does enforce any controls. They then update the `release_1.2` tag to point to -`X`. Consumers of `release_1.2` will get the malicious revision. Solution: The -Source Control System does not allow protected tags to be updated. - -
-
Skip required checks(Source L3+) - -*Threat:* Code is submitted without following the producers documented -development process, introducing unintended behavior. - -*Mitigation:* The producer uses the Source Control System to implement technical -controls ensuring adherence to the development process. - -*Example:* An engineer submits a new feature that has a critical flaw on an -untested code path, in violation of the producer's documented process of having -high test coverage. Solution: The producer implements a technical control in the -SCS that requires 95%+ test coverage. - -
-
Modify code after review(Source L4) - -*Threat:* Modify the code after it has been reviewed but before submission. - -*Mitigation:* The Source Control System invalidates approvals whenever the proposed change is modified. - -*Example:* Source repository requires two-person review on all changes. -Adversary sends an initial "good" pull request to a peer, who approves it. -Adversary then modifies their proposal to contain "bad" code. - -Solution: Configure the code review rules to require review of the most recent revision before submission. - -
-
Submit a change that is unreviewable(Source L4) - -*Threat:* Adversary crafts a change that looks benign to a reviewer but is actually malicious. - -*Mitigation:* Code review system ensures that all reviews are informed and -meaningful to the extent possible. For example the system could show -& resolve symlinks, render images, or verify & display provenance. - -*Example:* A proposed change updates a JPEG file to include a malicious -message, but the reviewer is only presented with a diff of the binary -file contents. The reviewer is unable to parse the contents themselves -so they do not have enough context to provide a meaningful review. -Solution: the code review system should present the reviewer with a -rendering of the image and the [embedded -metadata](https://en.wikipedia.org/wiki/Exif), allowing them to make an -informed decision. - -
-
Copy a reviewed change to another context(Source L4) - -*Threat:* Get a change reviewed in one context and then transfer it to a -different context. - -*Mitigation:* Approvals are context-specific. - -*Example:* MyPackage's source repository requires two-person review. Adversary -forks the repo, submits a change in the fork with review from a colluding -colleague (who is not trusted by MyPackage), then proposes the change to -the upstream repo. -Solution: The proposed change still requires two-person review in the upstream -context even though it received two-person review in another context. - -
- - -
Commit graph attacks - -*Threat:* A malicious commit can be included in a sequence of commits such that it does not appear malicious in the net change presented to reviewers. - -*Mitigation:* The producer ensures that all revisions in the protected context followed the same contribution process. - -*Example:* Adversary sends a pull request containing malicious commit X and a commit Y that undoes X. -The combined change of X + Y displays zero lines of malicious code and the reviewer cannot tell that X is malicious unless they review it individually. -If X is allowed to become reachable from the protected branch, the content may become available in secured environments such as developer machines. - -Solution: Each revision in the protected context must have followed the intended process. -Ultimately, this means that either each code review results in at most a single new commit or that the full process is followed for each constituent commit in a proposed sequence. - -
- -#### (B3) Render code review ineffective - -
Collude with another trusted person - -*Threat:* Two trusted persons collude to author and approve a bad change. - -*Mitigation:* This threat is not currently addressed by SLSA, but the producer can arbitrarily increase friction of their policies to reduce risk, such as requiring additional, or more senior reviewers. -The goal of policy here is to ensure that the approved changes match the intention of the producer for the source. -Increasing the friction of the policies may make it harder to circumvent, but doing so has diminishing returns. -Ultimately the producer will need to land upon a balanced risk profile that makes sense for their security posture. - -
-
Trick reviewer into approving bad code - -*Threat:* Construct a change that looks benign but is actually malicious, a.k.a. -"bugdoor." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
Reviewer blindly approves changes - -*Threat:* Reviewer approves changes without actually reviewing, a.k.a. "rubber -stamping." - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -#### (B4) Render change metadata ineffective - -
Forge change metadata(Source L2+) - -*Threat:* Forge the change metadata to alter attribution, timestamp, or -discoverability of a change. - -*Mitigation:* The Source Control System only attributes changes to authenticated -identities and records contemporaneous evidence of changes in signed source -provenance attestations. - -*Example:* Adversary 'X' creates a commit with unauthenticated metadata claiming -it was authored by 'Y'. Solution: The Source Control System records the identity -of 'X' when 'X' submits the commit to the repository. - -
- -### (C) Source code management - -An adversary introduces a change to the source control repository through an -administrative interface, or through a compromise of the underlying -infrastructure. - -
Platform admin abuses privileges(verification) - -*Threat:* Platform administrator abuses their privileges to bypass controls or -to push a malicious version of the software. - -*Mitigation:* The source platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals for -changes to the infrastructure, audit logging). A future [Platform -Operations Track](future-directions#platform-operations-track) may provide -more specific guidance on how to secure the underlying platform. - -*Example 1:* GitHostingService employee uses an internal tool to push changes to -the MyPackage source repo. - -*Example 2:* GitHostingService employee uses an internal tool to push a -malicious version of the server to serve malicious versions of MyPackage sources -to a specific CI/CD client but the regular version to everyone else, in order to -hide tracks. - -*Example 3:* GitHostingService employee uses an internal tool to push a -malicious version of the server that includes a backdoor allowing specific users -to bypass branch protections. Adversary then uses this backdoor to submit a -change to MyPackage without review. - -*Solution:* Consumers do not accept claims from the Source Control System unless -they trust sufficient controls are in place to prevent repo admins from -abusing privileges. - -
-
Exploit vulnerability in SCM - -*Threat:* Exploit a vulnerability in the implementation of the source code -management system to bypass controls. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Build threats - -A build integrity threat is a potential for an adversary to introduce behavior -to an artifact without changing its source code, or to build from a -source, dependency, and/or process that is not intended by the software -producer. - -The SLSA Build track mitigates these threats when the consumer -[verifies artifacts](verifying-artifacts.md) against expectations, confirming -that the artifact they received was built in the expected manner. - -### (D) External build parameters - -An adversary builds from a version of the source code that does not match the -official source control repository, or changes the build parameters to inject -behavior that was not intended by the official source. - -The mitigation here is to compare the provenance against expectations for the -package, which depends on SLSA Build L1 for provenance. (Threats against the -provenance itself are covered by (E) and (F).) - -
Build from unofficial fork of code (expectations) - -*Threat:* Build using the expected CI/CD process but from an unofficial fork of -the code that may contain unauthorized changes. - -*Mitigation:* Verifier requires the provenance's source location to match an -expected value. - -*Example:* MyPackage is supposed to be built from GitHub repo `good/my-package`. -Instead, it is built from `evilfork/my-package`. Solution: Verifier rejects -because the source location does not match. - -
-
Build from unofficial branch or tag (expectations) - -*Threat:* Build using the expected CI/CD process and source location, but -checking out an "experimental" branch or similar that may contain code not -intended for release. - -*Mitigation:* Verifier requires that the provenance's source branch/tag matches -an expected value, or that the source revision is reachable from an expected -branch. - -*Example:* MyPackage's releases are tagged from the `main` branch, which has -branch protections. Adversary builds from the unprotected `experimental` branch -containing unofficial changes. Solution: Verifier rejects because the source -revision is not reachable from `main`. - -
-
Build from unofficial build steps (expectations) - -*Threat:* Build the package using the proper CI/CD platform but with unofficial -build steps. - -*Mitigation:* Verifier requires that the provenance's build configuration source -matches an expected value. - -*Example:* MyPackage is expected to be built by Google Cloud Build using the -build steps defined in the source's `cloudbuild.yaml` file. Adversary builds -with Google Cloud Build, but using custom build steps provided over RPC. -Solution: Verifier rejects because the build steps did not come from the -expected source. - -
-
Build from unofficial parameters (expectations) - -*Threat:* Build using the expected CI/CD process, source location, and -branch/tag, but using a parameter that injects unofficial behavior. - -*Mitigation:* Verifier requires that the provenance's external parameters all -match expected values. - -*Example 1:* MyPackage is supposed to be built from the `release.yml` workflow. -Adversary builds from the `debug.yml` workflow. Solution: Verifier rejects -because the workflow parameter does not match the expected value. - -*Example 2:* MyPackage's GitHub Actions Workflow uses `github.event.inputs` to -allow users to specify custom compiler flags per invocation. Adversary sets a -compiler flag that overrides a macro to inject malicious behavior into the -output binary. Solution: Verifier rejects because the `inputs` parameter was not -expected. - -
-
Build from modified version of code modified after checkout (expectations) - -*Threat:* Build from a version of the code that includes modifications after -checkout. - -*Mitigation:* Build platform pulls directly from the source repository and -accurately records the source location in provenance. - -*Example:* Adversary fetches from MyPackage's source repo, makes a local commit, -then requests a build from that local commit. Builder records the fact that it -did not pull from the official source repo. Solution: Verifier rejects because -the source repo does not match the expected value. - -
- -### (E) Build process - -An adversary introduces an unauthorized change to a build output through -tampering of the build process; or introduces false information into the -provenance. - -These threats are directly addressed by the SLSA Build track. - -
Forge values of the provenance (other than output digest) (Build L2+) - -*Threat:* Generate false provenance and get the trusted control plane to sign -it. - -*Mitigation:* At Build L2+, the trusted control plane [generates][authentic] all -information that goes in the provenance, except (optionally) the output artifact -hash. At Build L3+, this is [hardened][unforgeable] to prevent compromise even -by determined adversaries. - -*Example 1 (Build L2):* Provenance is generated on the build worker, which the -adversary has control over. Adversary uses a malicious process to get the build -platform to claim that it was built from source repo `good/my-package` when it -was really built from `evil/my-package`. Solution: Builder generates and signs -the provenance in the trusted control plane; the worker reports the output -artifacts but otherwise has no influence over the provenance. - -*Example 2 (Build L3):* Provenance is generated in the trusted control plane, -but workers can break out of the container to access the signing material. -Solution: Builder is hardened to provide strong isolation against tenant -projects. - -
-
Forge output digest of the provenance (n/a) - -*Threat:* The tenant-controlled build process sets output artifact digest -(`subject` in SLSA Provenance) without the trusted control plane verifying that -such an artifact was actually produced. - -*Mitigation:* None; this is not a problem. Any build claiming to produce a given -artifact could have actually produced it by copying it verbatim from input to -output.[^preimage] (Reminder: Provenance is only a claim that a particular -artifact was *built*, not that it was *published* to a particular registry.) - -*Example:* A legitimate MyPackage artifact has digest `abcdef` and is built -from source repo `good/my-package`. A malicious build from source repo -`evil/my-package` claims that it built artifact `abcdef` when it did not. -Solution: Verifier rejects because the source location does not match; the -forged digest is irrelevant. - -[^preimage]: Technically this requires the artifact to be known to the - adversary. If they only know the digest but not the actual contents, they - cannot actually build the artifact without a [preimage attack] on the digest - algorithm. However, even still there are no known concerns where this is a - problem. - -[preimage attack]: https://en.wikipedia.org/wiki/Preimage_attack - -
-
Compromise project owner (Build L2+) - -*Threat:* An adversary gains owner permissions for the artifact's build project. - -*Mitigation:* The build project owner must not have the ability to influence the -build process or provenance generation. - -*Example:* MyPackage is built on Awesome Builder under the project "mypackage". -Adversary is an owner of the "mypackage" project. Awesome Builder allows -owners to debug the build environment via SSH. An adversary uses this feature -to alter a build in progress. Solution: Build L3 requires the external parameters -to be complete in the provenance. The attackers access and/or actions within the -SSH connection would be enumerated within the external parameters. The updated -external parameters will not match the declared expectations causing verification -to fail. - -
-
Compromise other build (Build L3) - -*Threat:* Perform a malicious build that alters the behavior of a benign -build running in parallel or subsequent environments. - -*Mitigation:* Builds are [isolated] from one another, with no way for one to -affect the other or persist changes. - -*Example 1:* A build platform runs all builds for project MyPackage on -the same machine as the same Linux user. An adversary starts a malicious build -that listens for another build and swaps out source files, then starts a benign -build. The benign build uses the malicious build's source files, but its -provenance says it used benign source files. Solution: The build platform -changes architecture to isolate each build in a separate VM or similar. - -*Example 2:* A build platform uses the same machine for subsequent -builds. An adversary first runs a build that replaces the `make` binary with a -malicious version, then subsequently runs an otherwise benign build. Solution: -The builder changes architecture to start each build with a clean machine image. - -
-
Steal cryptographic secrets (Build L3) - -*Threat:* Use or exfiltrate the provenance signing key or some other -cryptographic secret that should only be available to the build platform. - -*Mitigation:* Builds are [isolated] from the trusted build platform control -plane, and only the control plane has [access][unforgeable] to cryptographic -secrets. - -*Example:* Provenance is signed on the build worker, which the adversary has -control over. Adversary uses a malicious process that generates false provenance -and signs it using the provenance signing key. Solution: Builder generates and -signs provenance in the trusted control plane; the worker has no access to the -key. - -
-
Poison the build cache (Build L3) - -*Threat:* Add a malicious artifact to a build cache that is later picked up by a -benign build process ([example][build-cache-poisoning-example]). - -*Mitigation:* Build caches must be [isolated][isolated] between builds to prevent -such cache poisoning attacks. In particular, the cache SHOULD be keyed by the -transitive closure of all inputs to the cached artifact, and the cache must -either be only writable by the trusted control plane or have SLSA Build L3 -provenance for each cache entry. - -*Example 1:* The cache key does not fully cover the transitive closure of all -inputs and instead only uses the digest of the source file itself. Adversary runs -a build over `auth.cc` with command line flags to gcc that define a marco -replacing `CheckAuth(ctx)` with `true`. When subsequent builds build `auth.cc` -they will get the attacker's poisoned instance that does not call `CheckAuth`. -Solution: Build cache is keyed by digest of `auth.cc`, command line, and digest of -gcc so changing the command line flags results in a different cache entry. - -*Example 2:* The tenant controlled build process has full write access to the -cache. Adversary observes a legitimate build of `auth.cc` which covers the -transitive closure of all inputs and notes the digest used for caching. The -adversary builds a malicious version of `auth.o` and directly writes it to the -build cache using the observed digest. Subsequent legitimate builds will use -the malicious version of `auth.o`. Solution: Each cache entry is keyed by the -transitive closure of the inputs, and the cache entry is itself a SLSA Build L3 -build with its own provenance that corresponds to the key. - -
-
Compromise build platform admin (verification) - -*Threat:* An adversary gains admin permissions for the artifact's build platform. - -*Mitigation:* The build platform must have controls in place to prevent and -detect abusive behavior from administrators (e.g. two-person approvals, audit -logging). - -*Example:* MyPackage is built on Awesome Builder. Awesome Builder allows -engineers on-call to SSH into build machines to debug production issues. An -adversary uses this access to modify a build in progress. Solution: Consumers -do not accept provenance from the build platform unless they trust sufficient -controls are in place to prevent abusing admin privileges. - -
- -### (F) Artifact publication - -An adversary uploads a package artifact that does not reflect the intent of the -package's official source control repository. - -This is the most direct threat because it is the easiest to pull off. If there -are no mitigations for this threat, then (D) and (E) are often indistinguishable -from this threat. - - - -
Build with untrusted CI/CD (expectations) - -*Threat:* Build using an unofficial CI/CD pipeline that does not build in the -correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Solution: Verifier rejects because builder is not as -expected. - -
-
Upload package without provenance (Build L1) - -*Threat:* Upload a package without provenance. - -*Mitigation:* Verifier requires provenance before accepting the package. - -*Example:* Adversary uploads a malicious version of MyPackage to the package -repository without provenance. Solution: Verifier rejects because provenance is -missing. - -
-
Tamper with artifact after CI/CD (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -re-upload it using the original provenance. - -*Mitigation:* Verifier checks that the provenance's `subject` matches the hash -of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -uploads the modified version of the package to the repository along with the -provenance. Solution: Verifier rejects because the hash of the artifact does not -match the `subject` found within the provenance. - -
-
Tamper with provenance (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder. - -*Example:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -
- -### (G) Distribution channel - -An adversary modifies the package on the package registry using an -administrative interface or through a compromise of the infrastructure -including modification of the package in transit to the consumer. - -The distribution channel threats and mitigations look very similar to the -Artifact Publication (F) threats and mitigations with the main difference -being that these threats are mitigated by having the *consumer* perform -verification. - -The consumer's actions may be simplified if (F) produces a [VSA][vsa]. -In this case the consumer may replace provenance verification with -[VSA verification][vsa_verification]. - -
Build with untrusted CI/CD (expectations) - -*Threat:* Replace the package with one built using an unofficial CI/CD pipeline -that does not build in the correct way. - -*Mitigation:* Verifier requires provenance showing that the builder matched an -expected value or a VSA for corresponding `resourceUri`. - -*Example:* MyPackage is expected to be built on Google Cloud Build, which is -trusted up to Build L3. Adversary builds on SomeOtherBuildPlatform, which is only -trusted up to Build L2, and then exploits SomeOtherBuildPlatform to inject -malicious behavior. Adversary then replaces the original package within the -repository with the malicious package. Solution: Verifier rejects because -builder is not as expected. - -
-
Issue VSA from untrusted intermediary (expectations) - -*Threat:* Have an unofficial intermediary issue a VSA for a malicious package. - -*Mitigation*: Verifier requires VSAs to be issued by a trusted intermediary. - -*Example:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then issues a VSA of their own for the malicious -package. Solution: Verifier rejects because they only accept VSAs from -TheRepository which the adversary cannot issue since they do not have the -corresponding signing key. - -
-
Upload package without provenance or VSA (Build L1) - -*Threat:* Replace the original package with a malicious one without provenance. - -*Mitigation:* Verifier requires provenance or a VSA before accepting the package. - -*Example:* Adversary replaces MyPackage with a malicious version of MyPackage -on the package repository and deletes existing provenance. Solution: Verifier -rejects because provenance is missing. - -
-
Replace package and VSA with another (expectations) - -*Threat:* Replace a package and its VSA with a malicious package and its valid VSA. - -*Mitigation*: Consumer ensures that the VSA matches the package they've requested (not just the package they received) by following the [verification process](verification_summary#how-to-verify). - -*Example:* Adversary uploads a malicious package to `repo/evil-package`, -getting a valid VSA for `repo/evil-package`. Adversary then replaces -`repo/my-package` and its VSA with `repo/evil-package` and its VSA. -Solution: Verifier rejects because the VSA `resourceUri` field lists -`repo/evil-package` and not the expected `repo/my-package`. - -
-
Tamper with artifact after upload (Build L1) - -*Threat:* Take a benign version of the package, modify it in some way, then -replace it while retaining the original provenance or VSA. - -*Mitigation:* Verifier checks that the provenance or VSA's `subject` matches -the hash of the package. - -*Example:* Adversary performs a proper build, modifies the artifact, then -replaces the modified version of the package in the repository and retains the -original provenance. Solution: Verifier rejects because the hash of the -artifact does not match the `subject` found within the provenance. - -
-
Tamper with provenance or VSA (Build L2) - -*Threat:* Perform a build that would not meet expectations, then modify the -provenance or VSA to make the expectations checks pass. - -*Mitigation:* Verifier only accepts provenance or VSA with a valid [cryptographic -signature][authentic] or equivalent proving that the provenance came from an -acceptable builder or the VSA came from an expected verifier. - -*Example 1:* MyPackage is expected to be built by GitHub Actions from the -`good/my-package` repo. Adversary builds with GitHub Actions from the -`evil/my-package` repo and then modifies the provenance so that the source looks -like it came from `good/my-package`. Solution: Verifier rejects because the -cryptographic signature is no longer valid. - -*Example 2:* Verifier expects VSAs to be issued by TheRepository. Adversary -builds a malicious package and then modifies the original VSA's `subject` -field to match the digest of the malicious package. Solution: Verifier rejects -because the cryptographic signature is no longer valid. - -
- -## Usage threats - -A usage threat is a potential for an adversary to exploit behavior of the -consumer. - -### (H) Package selection - -The consumer requests a package that it did not intend. - -
Dependency confusion - -*Threat:* Register a package name in a public registry that shadows a name used -on the victim's internal registry, and wait for a misconfigured victim to fetch -from the public registry instead of the internal one. - -*Mitigation:* The mitigation is for the software producer to build internal -packages on a SLSA Level 2+ compliant build system and define expectations for -build provenance. Expectations must be verified on installation of the internal -packages. If a misconfigured victim attempts to install attacker's package with -an internal name but from the public registry, then verification against -expectations will fail. - -For more information see [Verifying artifacts](verifying-artifacts.md) -and [Defender's Perspective: Dependency Confusion and Typosquatting Attacks](/blog/2024/08/dep-confusion-and-typosquatting). - -
- -
Typosquatting - -*Threat:* Register a package name that is similar looking to a popular package -and get users to use your malicious package instead of the benign one. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, the -requirement to make the source available can be a mild deterrent, can aid -investigation or ad-hoc analysis, and can complement source-based typosquatting -solutions. - -
- -### (I) Usage - -The consumer uses a package in an unsafe manner. - -
Improper usage - -*Threat:* The software can be used in an insecure manner, allowing an -adversary to compromise the consumer. - -*Mitigation:* This threat is not addressed by SLSA, but may be addressed by -efforts like [Secure by Design][secure-by-design]. - -
- -## Dependency threats - -A dependency threat is a potential for an adversary to introduce unintended -behavior in one artifact by compromising some other artifact that the former -depends on at build time. (Runtime dependencies are excluded from the model, as -[noted below](#runtime-dep).) - -Unlike other threat categories, dependency threats develop recursively through -the supply chain and can only be exploited indirectly. For example, if -application *A* includes library *B* as part of its build process, then a build -or source threat to *B* is also a dependency threat to *A*. Furthermore, if -library *B* uses build tool *C*, then a source or build threat to *C* is also a -dependency threat to both *A* and *B*. - -This version of SLSA does not explicitly address dependency threats, but we -expect that a future version will. In the meantime, you can [apply SLSA -recursively] to your dependencies in order to reduce the risk of dependency -threats. - - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively - -### Build dependency - -An adversary compromises the target artifact through one of its build -dependencies. Any artifact that is present in the build environment and has the -ability to influence the output is considered a build dependency. - -
Include a vulnerable dependency (library, base image, bundled file, etc.) - -*Threat:* Statically link, bundle, or otherwise include an artifact that is -compromised or has some vulnerability, causing the output artifact to have the -same vulnerability. - -*Example:* The C++ program MyPackage statically links libDep at build time. A -contributor accidentally introduces a security vulnerability into libDep. The -next time MyPackage is built, it picks up and includes the vulnerable version of -libDep, resulting in MyPackage also having the security vulnerability. - -*Mitigation:* A future -[Dependency track](../../current-activities#dependency-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -
-
Use a compromised build tool (compiler, utility, interpreter, OS package, etc.) - -*Threat:* Use a compromised tool or other software artifact during the build -process, which alters the build process and injects unintended behavior into the -output artifact. - -*Mitigation:* This can be partially mitigated by treating build tooling, -including OS images, as any other artifact to be verified prior to use. -The threats described in this document apply recursively to build tooling -as do the mitigations and examples. A future -[Build Environment track](../../current-activities#build-environment-track) may -provide more comprehensive guidance on how to address more specfiic -aspects of this threat. - -*Example:* MyPackage is a tarball containing an ELF executable, created by -running `/usr/bin/tar` during its build process. An adversary compromises the -`tar` OS package such that `/usr/bin/tar` injects a backdoor into every ELF -executable it writes. The next time MyPackage is built, the build picks up the -vulnerable `tar` package, which injects the backdoor into the resulting -MyPackage artifact. Solution: [apply SLSA recursively] to all build tools -prior to the build. The build platform verifies the disk image, -or the individual components on the disk image, against the associated -provenance or VSAs prior to running a build. Depending on where the initial -compromise took place (i.e. before/during vs *after* the build of the build tool itself), the modified `/usr/bin/tar` will fail this verification. - -
- -
Use a compromised runtime dependency during the build (for tests, dynamic linking, etc.) - -*Threat:* During the build process, use a compromised runtime dependency (such -as during testing or dynamic linking), which alters the build process and -injects unwanted behavior into the output. - -**NOTE:** This is technically the same case as [Use a compromised build -tool](#build-tool). We call it out to remind the reader that -[runtime dependencies](#runtime-dep) can become build dependencies if they are -loaded during the build. - -*Example:* MyPackage has a runtime dependency on package Dep, meaning that Dep -is not included in MyPackage but required to be installed on the user's machine -at the time MyPackage is run. However, Dep is also loaded during the build -process of MyPackage as part of a test. An adversary compromises Dep such that, -when run during a build, it injects a backdoor into the output artifact. The -next time MyPackage is built, it picks up and loads Dep during the build -process. The malicious code then injects the backdoor into the new MyPackage -artifact. - -*Mitigation:* In addition to all the mitigations for build tools, you can often -avoid runtime dependencies becoming build dependencies by isolating tests to a -separate environment that does not have write access to the output artifact. - -
- -### Related threats - -The following threats are related to "dependencies" but are not modeled as -"dependency threats". - -
Use a compromised dependency at runtime (modeled separately) - -*Threat:* Load a compromised artifact at runtime, thereby compromising the user -or environment where the software ran. - -*Example:* MyPackage lists package Dep as a runtime dependency. Adversary -publishes a compromised version of Dep that runs malicious code on the user's -machine when Dep is loaded at runtime. An end user installs MyPackage, which in -turn installs the compromised version of Dep. When the user runs MyPackage, it -loads and executes the malicious code from Dep. - -*Mitigation:* N/A - SLSA's -threat model does not explicitly model runtime dependencies. Instead, each -runtime dependency is considered a distinct artifact with its own threats. - -
- -## Availability threats - - - -An availability threat is a potential for an adversary to deny someone from -reading a source and its associated change history, or from building a package. - -SLSA does not currently address availability threats, though future versions might. - -
Delete the code - -*Threat:* Perform a build from a particular source revision and then delete that -revision or cause it to get garbage collected, preventing anyone from inspecting -the code. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
A dependency becomes temporarily or permanently unavailable to the build process - -*Threat:* Unable to perform a build with the intended dependencies. - -*Mitigation:* This threat is not currently addressed by SLSA. That said, some -solutions to support hermetic and reproducible builds may also reduce the -impact of this threat. - -
-
De-list artifact - -*Threat:* The package registry stops serving the artifact. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
-
De-list provenance - -*Threat:* The package registry stops serving the provenance. - -*Mitigation:* This threat is not currently addressed by SLSA. - -
- -## Verification threats - -Threats that can compromise the ability to prevent or detect the supply chain -security threats above. - -
Tamper with recorded expectations - -*Threat:* Modify the verifier's recorded expectations, causing the verifier to -accept an unofficial package artifact. - -*Mitigation:* Changes to recorded expectations requires some form of -authorization, such as two-party review. - -*Example:* The package ecosystem records its expectations for a given package -name in a configuration file that is modifiable by that package's producer. The -configuration for MyPackage expects the source repository to be -`good/my-package`. The adversary modifies the configuration to also accept -`evil/my-package`, and then builds from that repository and uploads a malicious -version of the package. Solution: Changes to the recorded expectations require -two-party review. - -
-
Exploit cryptographic hash collisions - -*Threat:* Exploit a cryptographic hash collision weakness to bypass one of the -other controls. - -*Mitigation:* Choose secure algorithms when using cryptographic digests, such -as SHA-256. - -*Examples:* Attacker crafts a malicious file with the same MD5 hash as a target -benign file. Attacker replaces the benign file with the malicious file. -Solution: Only accept cryptographic hashes with strong collision resistance. - -
- -
- - - -[apply SLSA recursively]: verifying-artifacts.md#step-3-optional-check-dependencies-recursively -[authentic]: build-requirements.md#provenance-authentic -[build-cache-poisoning-example]: https://adnanthekhan.com/2024/05/06/the-monsters-in-your-build-cache-github-actions-cache-poisoning/ -[exists]: build-requirements.md#provenance-exists -[isolated]: build-requirements.md#isolated -[unforgeable]: build-requirements.md#provenance-unforgeable -[secure-by-design]: https://www.cisa.gov/securebydesign -[supply chain threats]: threats-overview -[vsa]: verification_summary -[vsa_verification]: verification_summary#how-to-verify diff --git a/docs/spec/v1.2/tracks.md b/docs/spec/v1.2/tracks.md deleted file mode 100644 index 8c014fef1..000000000 --- a/docs/spec/v1.2/tracks.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Tracks -description: Provides an overview of each track and links to more specific information. ---- - -SLSA is composed of [multiple tracks](about#how-slsa-works) which are each -composed of multiple levels. Each track addresses different [threats](threats) -and has its own set of requirements and patterns of use. - -## Build Track - -The SLSA build track describes increasing levels of trustworthiness and -completeness in a package artifact's provenance. Provenance describes -what entity built the artifact, what process they used, and what the inputs -were. The lowest level only requires the provenance to exist, while higher -levels provide increasing protection against tampering of the build, the -provenance, or the artifact. - -The primary purpose of the build track is to enable -[verification](verifying-artifacts.md) that the artifact was built as expected. -Consumers have some way of knowing what the expected provenance should look like -for a given package and then compare each package artifact's actual provenance -to those expectations. Doing so prevents several classes of -[supply chain threats](threats.md). - -Each ecosystem (for open source) or organization (for closed source) defines -exactly how this is implemented, including: means of defining expectations, what -provenance format is accepted, whether reproducible builds are used, how -provenance is distributed, when verification happens, and what happens on -failure. Guidelines for implementers can be found in the -[requirements](build-requirements.md). - -- [Terminology](terminology.md) -- [Basics](build-track-basics.md) -- [Requirements](build-requirements.md) -- [Build provenance](build-provenance.md) -- [Assessing build platforms](assessing-build-platforms.md) - -## Source Track - -The SLSA source track provides producers and consumers with increasing levels of -trust in the source code they produce and consume. It describes increasing -levels of trustworthiness and completeness of how a source revision was created. - -The expected process for creating a new revision is determined solely by that -repository's owner (the organization) who also determines the intent of the -software in the repository and administers technical controls to enforce the -process. - -Consumers can review attestations to verify whether a particular revision meets -their standards. - -- [Requirements](source-requirements.md) -- [Source provenance](source-requirements#source-provenance-attestations) -- [Assessing source systems](assessing-source-systems.md) -- [Example controls](source-example-controls.md) diff --git a/docs/spec/v1.2/use-cases.md b/docs/spec/v1.2/use-cases.md deleted file mode 100644 index f3d53d55c..000000000 --- a/docs/spec/v1.2/use-cases.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use cases -description: SLSA protects against tampering during the software supply chain, but how? The answer depends on the use case in which SLSA is applied. Here are descriptions of the three main use cases for SLSA. -layout: standard ---- - -SLSA protects against tampering during the software supply chain, but how? -The answer depends on the use case in which SLSA is applied. Below -describe the three main use cases for SLSA. - -
-
- -
- -## Applications of SLSA - -
- -
-
- -### First party - - - -
-
- -In its simplest form, SLSA can be used entirely within an organization to reduce -risk from internal sources. This is the easiest case in which to apply SLSA -because there is no need to transfer trust across organizational boundaries. - -Example ways an organization might use SLSA internally: - -- A small company or team uses SLSA to ensure that the code being deployed to - production in binary form is the same one that was tested and reviewed in - source form. -- A large company uses SLSA to require two-person review for every production - change, scalably across hundreds or thousands of employees/teams. -- An open source project uses SLSA to ensure that compromised credentials - cannot be abused to release an unofficial package to a package registry. - -**Case study:** [Google (Binary Authorization for Borg)](https://cloud.google.com/docs/security/binary-authorization-for-borg) - -
-
- -
-
- -### Open source - - - -
-
- -SLSA can also be used to reduce risk for consumers of open source software. The -focus here is to map built packages back to their canonical sources and -dependencies. In this way, consumers need only trust a small number of secure -build platforms rather than the many thousands of developers with upload -permissions across various packages. - -Example ways an open source ecosystem might use SLSA to protect users: - -- At upload time, the package registry rejects the package if it was not built - from the canonical source repository. -- At download time, the packaging client rejects the package if it was not - built by a trusted builder. - -**Case study:** [SUSE](https://documentation.suse.com/sbp/security/html/SBP-SLSA4/index.html) - -
-
- -
-
- -### Vendors - - - -
-
- -Finally, SLSA can be used to reduce risk for consumers of vendor-provided -software and services. Unlike open source, there is no canonical source -repository to map to, so instead the focus is on the trustworthiness of claims made -by the vendor. - -Example ways a consumer might use SLSA for vendor-provided software: - -- Prefer vendors who make SLSA claims and back them up with credible evidence. -- Require a vendor to implement SLSA as part of a contract. -- Require a vendor to be SLSA certified by a trusted third-party auditor. - -
-
- -
-
- -
-
- -
- -## Motivating example - -
- -For a look at how SLSA might be applied to open source in the future, see the -[hypothetical curl example](../../example.md). - -
-
diff --git a/docs/spec/v1.2/verification_summary.md b/docs/spec/v1.2/verification_summary.md deleted file mode 100644 index 1f0019bf3..000000000 --- a/docs/spec/v1.2/verification_summary.md +++ /dev/null @@ -1,432 +0,0 @@ ---- -title: Verification Summary Attestation (VSA) -description: Specification for a verification summary of artifacts by a trusted verifier entity. -layout: standard ---- - -Verification summary attestations communicate that an artifact has been verified -at a specific SLSA level and details about that verification. - -This document defines the following predicate type within the [in-toto -attestation] framework: - -```json -"predicateType": "https://slsa.dev/verification_summary/v1" -``` - -> Important: Always use the above string for `predicateType` rather than what is -> in the URL bar. The `predicateType` URI will always resolve to the latest -> minor version of this specification. See [parsing rules](#parsing-rules) for -> more information. - -## Purpose - -Describe what SLSA level an artifact or set of artifacts was verified at -and other details about the verification process including what SLSA level -the dependencies were verified at. - -This allows software consumers to make a decision about the validity of an -artifact without needing to have access to all of the attestations about the -artifact or all of its transitive dependencies. They can use it to delegate -complex policy decisions to some trusted party and then simply trust that -party's decision regarding the artifact. - -It also allows software producers to keep the details of their build pipeline -confidential while still communicating that some verification has taken place. -This might be necessary for legal reasons (keeping a software supplier -confidential) or for security reasons (not revealing that an embargoed patch has -been included). - -## Model - -A Verification Summary Attestation (VSA) is an attestation that some entity -(`verifier`) verified one or more software artifacts (the `subject` of an -in-toto attestation [Statement]) by evaluating the artifact and a `bundle` -of attestations against some `policy`. Users who trust the `verifier` may -assume that the artifacts met the indicated SLSA level without themselves -needing to evaluate the artifact or to have access to the attestations the -`verifier` used to make its determination. - -The VSA also allows consumers to determine the verified levels of -all of an artifact’s _transitive_ dependencies. The verifier does this by -either a) verifying the provenance of each non-source dependency listed in -the [resolvedDependencies](/build-provenance/v1#resolvedDependencies) of the -artifact being verified (recursively) or b) matching the non-source dependency -listed in `resolvedDependencies` (`subject.digest` == -`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` == -`resolvedDependencies.uri`) to a VSA _for that dependency_ and using -`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing -to establish minimum requirements on dependencies SLSA levels may use -`vsa.dependencyLevels` to do so. - -## Schema - -```jsonc -// Standard attestation fields: -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": , - "digest": { } -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "", - "version": { - "": "", - ... - } - }, - "timeVerified": , - "resourceUri": , - "policy": { - "uri": "", - "digest": { } - } - "inputAttestations": [ - { - "uri": "", - "digest": { } - }, - ... - ], - "verificationResult": "", - "verifiedLevels": [""], - "dependencyLevels": { - "": , - "": , - ... - }, - "slsaVersion": ".", -} -``` - -### Parsing rules - -This predicate follows the in-toto attestation [parsing rules]. Summary: - -- Consumers MUST ignore unrecognized fields. -- The `predicateType` URI includes the major version number and will always - change whenever there is a backwards incompatible change. -- Minor version changes are always backwards compatible and "monotonic." Such - changes do not update the `predicateType`. -- Producers MAY add extension fields using field names that are URIs. - -### Fields - -_NOTE: This section describes the fields within `predicate`. For a description -of the other top-level fields, such as `subject`, see [Statement]._ - - -`verifier` _object, required_ - -> Identifies the entity that performed the verification. -> -> The identity MUST reflect the trust base that consumers care about. How -> detailed to be is a judgment call. -> -> Consumers MUST accept only specific (signer, verifier) pairs. For example, -> "GitHub" can sign provenance for the "GitHub Actions" verifier, and "Google" -> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot -> sign for the "Google Cloud Deploy" verifier. -> -> The field is required, even if it is implicit from the signer, to aid readability and -> debugging. It is an object to allow additional fields in the future, in case one -> URI is not sufficient. - - -`verifier.id` _string ([TypeURI]), required_ - -> URI indicating the verifier’s identity. - - -`verifier.version` _map (string->string), optional_ - -> Map of names of components of the verification platform to their version. - - -`timeVerified` _string ([Timestamp]), optional_ - -> Timestamp indicating what time the verification occurred. - - -`resourceUri` _string ([ResourceURI]), required_ - -> URI that identifies the resource associated with the artifact being verified. -> -> The `resourceUri` SHOULD be set to the URI from which the producer expects the -> consumer to fetch the artifact for verification. This enables the consumer to -> easily determine the expected value when [verifying](#how-to-verify). If the -> `resourceUri` is set to some other value, the producer MUST communicate the -> expected value, or how to determine the expected value, to consumers through -> an out-of-band channel. - - -`policy` _object ([ResourceDescriptor]), required_ - -> Describes the policy that the `subject` was verified against. -> -> The entry MUST contain a `uri` identifying which policy was applied and -> SHOULD contain a `digest` to indicate the exact version of that policy. - - -`inputAttestations` _array ([ResourceDescriptor]), optional_ - -> The collection of attestations that were used to perform verification. -> Conceptually similar to the `resolvedDependencies` field in [SLSA Provenance]. -> -> This field MAY be absent if the verifier does not support this feature. -> If non-empty, this field MUST contain information on _all_ the attestations -> used to perform verification. -> -> Each entry MUST contain a `digest` of the attestation and SHOULD contains a -> `uri` that can be used to fetch the attestation. - - -`verificationResult` _string, required_ - -> Either “PASSED” or “FAILED” to indicate if the artifact passed or failed the policy verification. - - -`verifiedLevels` _array ([SlsaResult]), required_ - -> Indicates the highest level of each track verified for the artifact (and not -> its dependencies) and any [verified properties](verified-properties) verified -> for the artifact or "FAILED" if policy verification failed. -> -> Users MUST NOT include more than one level per SLSA track. Note that each SLSA -> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies -> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to -> include more than one level per track. - - -`dependencyLevels` _object, optional_ - -> A count of the dependencies at each SLSA level. -> -> Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies -> that were verified at the indicated level. Absence of a given level of -> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level. -> A set but empty `dependencyLevels` object means that the artifact has **no** -> dependency at all, while an unset or null `dependencyLevels` means that the -> verifier makes no claims about the artifact's dependencies. -> -> Users MUST count each dependency only once per SLSA track, at the highest -> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`, -> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for -> `SLSA_BUILD_LEVEL_1`. - - -`slsaVersion` _string, optional_ - -> Indicates the version of the SLSA specification that the verifier used, in the -> form `.`. Example: `1.0`. If unset, the default is an -> unspecified minor version of `1.x`. - -## Example - -WARNING: This is just for demonstration purposes. - -```jsonc -"_type": "https://in-toto.io/Statement/v1", -"subject": [{ - "name": "out/example-1.2.3.tar.gz", - "digest": {"sha256": "5678..."} -}], - -// Predicate -"predicateType": "https://slsa.dev/verification_summary/v1", -"predicate": { - "verifier": { - "id": "https://example.com/publication_verifier", - "version": { - "slsa-verifier-linux-amd64": "v2.3.0", - "slsa-framework/slsa-verifier/actions/installer": "v2.3.0" - } - }, - "timeVerified": "1985-04-12T23:20:50.52Z", - "resourceUri": "https://example.com/example-1.2.3.tar.gz", - "policy": { - "uri": "https://example.com/example_tarball.policy", - "digest": {"sha256": "1234..."} - }, - "inputAttestations": [ - { - "uri": "https://example.com/provenances/example-1.2.3.tar.gz.intoto.jsonl", - "digest": {"sha256": "abcd..."} - } - ], - "verificationResult": "PASSED", - "verifiedLevels": ["SLSA_BUILD_LEVEL_3"], - "dependencyLevels": { - "SLSA_BUILD_LEVEL_3": 5, - "SLSA_BUILD_LEVEL_2": 7, - "SLSA_BUILD_LEVEL_1": 1, - }, - "slsaVersion": "1.0" -} -``` - -## How to verify - -VSA consumers use VSAs to accomplish goals based on delegated trust. We call the -process of establishing a VSA's authenticity and determining whether it meets -the consumer's goals 'verification'. Goals differ, as do levels of confidence -in VSA producers, so the verification procedure changes to suit its context. -However, there are certain steps that most verification procedures have in -common. - -Verification MUST include the following steps: - -1. Verify the signature on the VSA envelope using the preconfigured roots of - trust. This step ensures that the VSA was produced by a trusted producer - and that it hasn't been tampered with. - -2. Verify the statement's `subject` matches the digest of the artifact in - question. This step ensures that the VSA pertains to the intended artifact. - -3. Verify that the `predicateType` is - `https://slsa.dev/verification_summary/v1`. This step ensures that the - in-toto predicate is using this version of the VSA format. - -4. Verify that the `verifier` matches the public key (or equivalent) used to - verify the signature in step 1. This step identifies the VSA producer in - cases where their identity is not implicitly revealed in step 1. - -5. Verify that the value for `resourceUri` in the VSA matches the expected - value. This step ensures that the consumer is using the VSA for the - producer's intended purpose. - -6. Verify that the value for `verificationResult` is `PASSED`. This step - ensures the artifact is suitable for the consumer's purposes. - -7. Verify that `verifiedLevels` contains the expected value. This step ensures - that the artifact is suitable for the consumer's purposes. - -Verification MAY additionally contain the following step: - -1. (Optional) Verify additional fields required to determine whether the VSA - meets your goal. - -Verification mitigates different threats depending on the VSA's contents and the -verification procedure. - -IMPORTANT: A VSA does not protect against compromise of the verifier, such as by -a malicious insider. Instead, VSA consumers SHOULD carefully consider which -verifiers they add to their roots of trust. - -### Examples - -1. Suppose consumer C wants to delegate to verifier V the decision for whether - to accept artifact A as resource R. Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` contains `SLSA_BUILD_LEVEL_UNEVALUATED`. - - Note: This example is analogous to traditional code signing. The expected - value for `verifiedLevels` is arbitrary but prenegotiated by the producer and - the consumer. The consumer does not need to check additional fields, as C - fully delegates the decision to V. - -2. Suppose consumer C wants to enforce the rule "Artifact A at resource R must - have a passing VSA from verifier V showing it meets SLSA Build Level 2+." - Consumer C verifies that: - - - The signature on the VSA envelope using V's public signing key from their - preconfigured root of trust. - - - `subject` is A. - - - `predicateType` is `https://slsa.dev/verification_summary/v1`. - - - `verifier.id` is V. - - - `resourceUri` is R. - - - `slsaResult` is `PASSED`. - - - `verifiedLevels` is `SLSA_BUILD_LEVEL_2` or `SLSA_BUILD_LEVEL_3`. - - Note: In this example, verifying the VSA mitigates the same threats as - verifying the artifact's SLSA provenance. See - [Verifying artifacts](/spec/v1.0/verifying-artifacts) for details about which - threats are addressed by verifying each SLSA level. - -
- -## _SlsaResult (String)_ - -
- -The result of evaluating an artifact (or set of artifacts) against SLSA. -SHOULD be - -- The [SLSA Track](#tracks) level the referenced artifact qualifies for as -`SLSA__LEVEL_`, or -- `SLSA__LEVEL_UNEVALUATED` if the VSA issuer does not want to - make a claim about the track level an artifact meets - -For example: - -- `SLSA_BUILD_LEVEL_UNEVALUATED` -- `SLSA_BUILD_LEVEL_0` -- `SLSA_BUILD_LEVEL_3` -- `SLSA_SOURCE_LEVEL_2` -- `SLSA_SOURCE_LEVEL_4` -- `FAILED` (Indicates policy evaluation failed) - -Note that each SLSA level implies the levels below it in the same track. -For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` + -`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`). - -Users MAY use custom values here but MUST NOT use custom values starting with -`SLSA_`. - -## Change history - -- 1.2: - - Update SlsaResult definition to discuss how to refer to new tracks and - link to [verified properties](verified-properties) for additional SLSA - endorsed values. - - Fixed a typo where the verificationResult was incorrectly referred to - as slsaResult. -- 1.1: - - Changed the `policy` object to recommend that the `digest` field of - the `ResourceDescriptor` is set. - - Added optional `verifier.version` field to record verification tools. - - Added Verification section with examples. - - Made `timeVerified` optional. -- 1.0: - - Replaced `materials` with `resolvedDependencies`. - - Relaxed `SlsaResult` to allow other values. - - Converted to lowerCamelCase for consistency with [SLSA Provenance]. - - Added `slsaVersion` field. -- 0.2: - - Added `resource_uri` field. - - Added optional `input_attestations` field. -- 0.1: Initial version. - -[SLSA Provenance]: /provenance -[SlsaResult]: #slsaresult -[DigestSet]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/digest_set.md -[ResourceURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#resourceuri -[ResourceDescriptor]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/resource_descriptor.md -[Statement]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/statement.md -[Timestamp]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#timestamp -[TypeURI]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/field_types.md#TypeURI -[in-toto attestation]: https://github.com/in-toto/attestation -[parsing rules]: https://github.com/in-toto/attestation/blob/7aefca35a0f74a6e0cb397a8c4a76558f54de571/spec/v1/README.md#parsing-rules diff --git a/docs/spec/v1.2/verifying-artifacts.md b/docs/spec/v1.2/verifying-artifacts.md deleted file mode 100644 index 0961a19ed..000000000 --- a/docs/spec/v1.2/verifying-artifacts.md +++ /dev/null @@ -1,302 +0,0 @@ ---- -title: "Build: Verifying artifacts" -description: SLSA uses provenance to indicate whether an artifact is authentic or not, but provenance doesn't do anything unless somebody inspects it. SLSA calls that inspection verification, and this page describes how to verify artifacts and their SLSA provenance. The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses provenance to indicate whether an artifact is authentic or not, but -provenance doesn't do anything unless somebody inspects it. SLSA calls that -inspection **verification**, and this page describes recommendations for how to -verify artifacts and their SLSA provenance. - -This page is divided into several sections. The first describes the process -for verifying an artifact and its provenance against a set of expectations. The -second describes how to form the expectations used to verify provenance. The -third discusses architecture choices for where provenance verification can -happen. - -## How to verify - -Verification SHOULD include the following steps: - -- Ensuring that the builder identity is one of those in the map of trusted - builder id's to SLSA level. -- Verifying the signature on the provenance envelope. -- Ensuring that the values for `buildType` and `externalParameters` in the - provenance match the expected values. The package ecosystem MAY allow - an approved list of `externalParameters` to be ignored during verification. - Any unrecognized `externalParameters` SHOULD cause verification to fail. - -![Threats covered by each step](images/supply-chain-threats-build-verification.svg) - -See [Terminology](terminology.md) for an explanation of the supply chain model and -[Threats & mitigations](threats.md) for a detailed explanation of each threat. - -**Note:** This section assumes that the provenance is in the recommended -[provenance format](/provenance/v1). If it is not, then the verifier SHOULD -perform equivalent checks on provenance fields that correspond to the ones -referenced here. - -### Step 1: Check SLSA Build level - -[Step 1]: #step-1-check-slsa-build-level - -First, check the SLSA Build level by comparing the artifact to its provenance -and the provenance to a preconfigured root of trust. The goal is to ensure that -the provenance actually applies to the artifact in question and to assess the -trustworthiness of the provenance. This mitigates some or all of [threats] "E", -"F", "G", and "H", depending on SLSA Build level and where verification happens. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized builder - identities and the maximum SLSA Build level each builder is trusted up to. - Different verifiers might use different roots of trust, but usually a - verifier uses the same roots of trust for all packages. This configuration - is likely in the form of a map from (builder public key identity, - `builder.id`) to (SLSA Build level). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaRootsOfTrust": [ - // A builder trusted at SLSA Build L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "builderId": "https://somebuilder.example.com/slsa/l3", - "slsaBuildLevel": 3 - }, - // A different builder that claims to be SLSA Build L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "builderId": "https://differentbuilder.example.com/slsa/l3", - "slsaBuildLevel": 2 - }, - // A builder that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*" - } - "builderId": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v*.*.*", - "slsaBuildLevel": 3, - } - ... - ], - ``` - -
- -Given an artifact and its provenance: - -1. [Verify][validation-model] the envelope's signature using the roots of - trust, resulting in a list of recognized public keys (or equivalent). -2. [Verify][validation-model] that statement's `subject` matches the digest of - the artifact in question. -3. Verify that the `predicateType` is `https://slsa.dev/provenance/v1`. -4. Look up the SLSA Build Level in the roots of trust, using the recognized - public keys and the `builder.id`, defaulting to SLSA Build L1. - -Resulting threat mitigation: - -- [Threat "E"]: SLSA Build L3 requires protection against compromise of the - build process and provenance generation by an external adversary, such as - persistence between builds or theft of the provenance signing key. In other - words, SLSA Build L3 establishes that the provenance is accurate and - trustworthy, assuming you trust the build platform. - - IMPORTANT: SLSA Build L3 does **not** cover compromise of the build - platform itself, such as by a malicious insider. Instead, verifiers - SHOULD carefully consider which build platforms are added to the roots - of trust. For advice on establishing trust in build platforms, see - [Assessing build platforms](assessing-build-platforms.md). -- [Threat "F"]: SLSA Build L2 covers tampering of the artifact or provenance - after the build. This is accomplished by verifying the `subject` and - signature in the steps above. -- [Threat "G"]: Verification by the consumer or otherwise outside of the - package registry covers compromise of the registry itself. (Verifying within - the registry at publication time is also valuable, but does not cover Threat - "G" or "I".) -- [Threat "I"]: Verification by the consumer covers compromise of the package - in transit. (Many ecosystems also address this threat using package - signatures or checksums.) - - NOTE: SLSA does not yet cover adversaries tricking a consumer to use an - unintended package, such as through typosquatting. Those threats are - discussed in more detail under [Threat "H"]. - -[Threat "E"]: threats#e-build-process -[Threat "F"]: threats#f-artifact-publication -[Threat "G"]: threats#g-distribution-channel -[Threat "H"]: threats#h-package-selection -[Threat "I"]: threats#i-usage - -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 2: Check expectations - -[verify-step-2]: #check-expectations - -Next, check that the package's provenance meets your expectations for that -package in order to mitigate [threat "D"]. - -In our threat model, the adversary has the ability to invoke a build and to publish -to the registry. The adversary is not able to write to the source repository, nor do -they have insider access to any trusted systems. Your expectations SHOULD be -sufficient to detect or prevent this adversary from injecting unofficial -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 - -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 -range of values (possibly any value) if it is known that any value in the range -is safe. JSON comparison is sufficient for verifying parameters. - -TIP: Difficulty in forming meaningful expectations about `externalParameters` can -be a sign that the `buildType`'s level of abstraction is too low. For example, -`externalParameters` that record a list of commands to run is likely impractical -to verify because the commands change on every build. Instead, consider a -`buildType` that defines the list of commands in a configuration file in a -source repository, then put only the source repository in -`externalParameters`. Such a design is easier to verify because the source -repository is constant across builds. - -[Threat "D"]: threats#d-external-build-parameters - -### Step 3: (Optional) Check dependencies recursively - -[verify-step-3]: #step-3-optional-check-dependencies-recursively - -Finally, recursively check the `resolvedDependencies` as available and to the -extent desired. Note that SLSA v1.0 does not have any requirements on the -completeness or verification of `resolvedDependencies`. However, one might wish -to verify dependencies in order to mitigate [dependency threats] and protect against -threats further up the supply chain. If `resolvedDependencies` is incomplete, -these checks can be done on a best-effort basis. - -A [Verification Summary Attestation (VSA)][VSA] can make dependency verification -more efficient by recording the result of prior verifications. A trimming -heuristic or exception mechanism is almost always necessary when verifying -dependencies because there will be transitive dependencies that are SLSA Build -L0. (For example, consider the compiler's compiler's compiler's ... compiler.) - -[dependency threats]: threats#dependency-threats -[VSA]: /verification_summary -[threats]: threats - -## Forming Expectations - -Expectations are known provenance values that indicate the -corresponding artifact is authentic. For example, a package ecosystem may -maintain a mapping between package names and their canonical source -repositories. That mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the package as-is. On - each version update, compare the old provenance to the new provenance and - alert on any differences. This can be augmented by having rules about what - changes are benign, such as a parameter known to be safe or a heuristic - about safe git branches or tags. - -- **Defined by producer:** The package producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the package's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -- **Defined in source:** The source repository tells the verifier what their - expectations ought to be. In this model, the package name is immutably bound - to a source repository and all other external parameters are defined in the - source repository. This is how the Go ecosystem works, for example, since - the package name *is* the source repository location. - -It is important to note that expectations are tied to a *package name*, whereas -provenance is tied to an *artifact*. Different versions of the same package name -will likely have different artifacts and therefore different provenance. Similarly, an -artifact might have different names in different package ecosystems but use the same -provenance file. - -## Architecture options - -There are several options (non-mutually exclusive) for where provenance verification -can happen: the package ecosystem at upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify provenance. For example, even if a package -ecosystem verifies provenance, consumers who get artifacts from that package -ecosystem might wish to verify provenance themselves for defense in depth. They -can do so using either client-side verification tooling or by polling a -monitor. - - - -### Package ecosystem - -[Package ecosystem]: #package-ecosystem - -A package ecosystem is a set of rules and conventions governing -how packages are distributed. Every package artifact has an ecosystem, whether it is -formal or ad-hoc. Some ecosystems are formal, such as language distribution -(e.g. [Python/PyPA](https://www.pypa.io)), operating system distribution (e.g. -[Debian/Apt](https://wiki.debian.org/DebianRepository/Format)), or artifact -distribution (e.g. [OCI](https://github.com/opencontainers/distribution-spec)). -Other ecosystems are informal, such as a convention used within a company. Even -ad-hoc distribution of software, such as through a link on a website, is -considered an "ecosystem". For more background, see -[Package Model](terminology.md#package-model). - -During package upload, a package ecosystem can ensure that the artifact's -provenance matches the expected values for that package name's provenance before -accepting it into the package registry. This option is RECOMMENDED whenever -possible because doing so benefits all of the package ecosystem's clients. - -The package ecosystem is responsible for making its expectations available to -consumers, reliably redistributing artifacts and provenance, and providing tools -to enable safe artifact consumption (e.g. whether an artifact meets -expectations). - -### Consumer - -[Consumer]: #consumer - -A package artifact's consumer is the organization or individual that uses the -package artifact. - -Consumers can form their own expectations for artifacts or use the default -expectations provided by the package producer and/or package ecosystem. -When forming their own expectations, the consumer uses client-side verification tooling to ensure -that the artifact's provenance matches their expectations for that package -before use (e.g. during installation or deployment). Client-side verification -tooling can be either standalone, such as -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier), or built into -the package ecosystem client. - -### Monitor - -[Monitor]: #monitor - -A monitor is a service that verifies provenance for a set -of packages and publishes the result of that verification. The set of -packages verified by a monitor is arbitrary, though it MAY mimic the set -of packages published through one or more package ecosystems. The monitor -SHOULD publish its expectations for all the packages it verifies. - -Consumers can continuously poll a monitor to detect artifacts that -do not meet the monitor's expectations. Detecting artifacts that fail -verification is of limited benefit unless a human or automated system takes -action in response to the failed verification. diff --git a/docs/spec/v1.2/verifying-source.md b/docs/spec/v1.2/verifying-source.md deleted file mode 100644 index 5d43abb1b..000000000 --- a/docs/spec/v1.2/verifying-source.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: "Source: Verifying source" -description: | - SLSA uses attestations to indicate security claims associated with a repository revision, but attestations don't do anything unless somebody inspects them. - SLSA calls that inspection verification, and this page describes how to verify properties of source revisions using their SLSA source provenance attestations. - The intended audience is platform implementers, security engineers, and software consumers. ---- - -SLSA uses attestations to indicate security claims associated with a repository -revision, but attestations don't do anything unless somebody inspects them. SLSA -calls that inspection **verification**, and this page describes how to verify -properties of source revisions using -[the attestations](source-requirements#communicating-source-levels) associated -with those revisions. - -At Source L3+, Source Control Systems (SCSs) issue detailed -[provenance attestations](source-requirements#source-provenance-attestations) of -the process that was used to create specific revisions of a repository. These -provenance attestations are issued in bespoke formats and may be too burdensome -to use in some use cases. - -[Source Verification Summary Attestations](source-requirements#source-verification-summary-attestation) -(Source VSAs) address this, making verification more efficient and ergonomic by -recording the result of prior verifications. Source VSAs may be issued by a VSA -provider to make a SLSA source level determination based on the content of those -attestations. - -## How to verify a source revision - -The source consumer checks: - -1. If they trust the SCS that issued the VSA and if the VSA applies to the - revision they've fetched. -2. If the claims made in the VSA match their expectations for how the source - should be managed. -3. (Optional): If the evidence presented in the source provenance matches the - claims made in the VSA. - -### Step 1: Check the SCS - -First, check the SLSA Source level by comparing the artifact to its VSA and the -VSA to a preconfigured root of trust. The goal is to ensure that the VSA -actually applies to the artifact in question and to assess the trustworthiness -of the VSA. This mitigates threats within "B" and "C", depending on SLSA Source -level. - -Once, when bootstrapping the verifier: - -- Configure the verifier's roots of trust, meaning the recognized SCS - identities and the maximum SLSA Source level each SCS is trusted up to. - Different verifiers MAY use different roots of trust for repositories. The - root of trust configuration is likely in the form of a map from (SCS public - key identity, VSA `verifier.id`) to (SLSA Source level). - -
- Example root of trust configuration - - The following snippet shows conceptually how a verifier's roots of trust - might be configured using made-up syntax. - - ```jsonc - "slsaSourceRootsOfTrust": [ - // A SCS trusted at SLSA Source L3, using a fixed public key. - { - "publicKey": "HKJEwI...", - "scsId": "https://somescs.example.com/slsa/l3", - "slsaSourceLevel": 3 - }, - // A different SCS that claims to be SLSA Source L3, - // but this verifier only trusts it to L2. - { - "publicKey": "tLykq9...", - "scsId": "https://differentscs.example.com/slsa/l3", - "slsaSourceLevel": 2 - }, - // A SCS that uses Sigstore for authentication. - { - "sigstore": { - "root": "global", // identifies fulcio/rekor roots - "subjectAlternativeNamePattern": "https://github.com/slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@refs/tags/v*.*.*" - }, - "scsId": "https://github.com/slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@refs/tags/v*.*.*", - "slsaSourceLevel": 3, - } - ... - ], - ``` - -
- -Given a revision and its VSA follow the -[VSA verification instructions](./verification_summary.md#how-to-verify) and the -[validation-model] using the revision identifier to perform subject matching and -checking the `verifier.id` against the root-of-trust described above. - -### Step 2: Check Expectations - -Next, check that the revision's VSA meets your expectations in order to mitigate -[threat "B"]. - -In our threat model, the adversary has the ability to create revisions within -the repository and get consumers to fetch that revision. The adversary is not -able to subvert controls implemented by the Producer and enforced by the SCS. -Your expectations SHOULD be sufficient to detect an un-official revision and -SHOULD make it more difficult for an adversary to create a malicious official -revision. - -You SHOULD compare the VSA against expected values for at least the following -fields: - -| What | Why -| ---- | --- -| `verifier.id` identity from [Step 1] | To prevent an adversary from substituting a VSA making false claims from an unintended SCS. -| `subject.digest` from [Step 1] | To prevent an adversary from substituting a VSA from another revision. -| `verificationResult` | To prevent an adversary from providing a VSA for a revision that failed some aspect of the organization's expectations. -| `predicate.resourceUri` | To prevent an adversary from substituting a VSA for the intended repository (e.g. `git+https://github.com/IntendedOrg/hello-world`) for another (e.g. `git+https://github.com/AdversaryOrg/hello-world`) -| `subject.annotations.sourceRefs` | To prevent an adversary from substituting the intended revision from one branch (e.g. `release`) with another (e.g. `experimental_auth`). -| `verifiedLevels` | To ensure the expected controls were in place for the creation of the revision. E.g. `SLSA_SOURCE_LEVEL_3`, `ORG_SOURCE_STATIC_ANALYSIS`, etc... - -[Threat "B"]: threats#b-modifying-the-source -[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model - -### Step 3: Verify Evidence using Source Provenance [optional] - -Optionally, at SLSA Source Level 3 and up, check the [source provenance -attestations](source-requirements#source-provenance-attestations) directly. - -As the format and implementation of source provenance attestations are left to -the SCS, you SHOULD form expectations about the claims in source provenance -attestations and how they map to a revision's properties claimed in its VSA in -conjunction with the SCS and the producer. - -## Forming Expectations - -Expectations are known values that indicate the corresponding -revision is authentic. For example, an SCS may maintain a mapping between -repository branches & tags and the controls they claim to implement. That -mapping constitutes a set of expectations. - -Possible models for forming expectations include: - -- **Trust on first use:** Accept the first version of the revision as-is. On - each update, compare the old VSA to the new VSA and alert on any - differences. - -- **Defined by producer:** The revision producer tells the verifier what their - expectations ought to be. In this model, the verifier SHOULD provide an - authenticated communication mechanism for the producer to set the revision's - expectations, and there SHOULD be some protection against an adversary - unilaterally modifying them. For example, modifications might require - two-party control, or consumers might have to accept each policy change - (another form of trust on first use). - -It is important to note that expectations are tied to a *repository branch or -tag*, whereas a VSA is tied to an *revision*. Different revisions will have -different VSAs and the claims made by those VSAs may differ. - -## Architecture options - -There are several options (non-mutually exclusive) for where VSA verification -can happen: the build system at source fetch time, the package ecosystem at -build artifact upload time, the consumers at download time, or -via a continuous monitoring system. Each option comes with its own set of -considerations, but all are valid and at least one SHOULD be used. - -More than one component can verify VSAs. For example, even if a builder verifies -source VSAs, package ecosystems may wish to verify the source VSAs for the -artifacts they host that claim to be built from that source (as indicated by the -build provenance). diff --git a/docs/spec/v1.2/whats-new.md b/docs/spec/v1.2/whats-new.md deleted file mode 100644 index 50c13acf3..000000000 --- a/docs/spec/v1.2/whats-new.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: What's new -description: The changes brought by SLSA 1.2. ---- - -This document describes the major changes brought by SLSA 1.2 relative to -the prior release [v1.1] and the prior release candidates [v1.2 RC1], -[v1.2 RC2]. - -## Summary of changes since v1.2 RC2 - -- No changes. - -## Summary of changes since v1.2 RC1 - -- Improved instructions for verifying source VSAs. -- Reorganized the Source Track levels. Level 2 now focuses on history and - provenance while Level 3 focuses on continuous enforcement of technical - controls. -- Moved example source controls to [their own page](source-example-controls). -- Minor copy editing improvements. - -## Summary of changes since v1.1 - -- Addition of the [Source Track](source-requirements) which helps - organizations secure their source code development process and consumers - establish trust in that source. -- Updated the [threat model](threats) to account for the threats mitigated by - the Source Track. -- Improved the structure of the spec to accommodate multiple tracks. - - - -[v1.1]: /spec/v1.1/ -[v1.2 RC1]: /spec/v1.2-rc1/ -[v1.2 RC2]: /spec/v1.2-rc2/ diff --git a/netlify.toml b/netlify.toml index 85e695c2e..5ab94906a 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,7 +1,12 @@ [build] -base = "docs/" -publish = "_site/" # relative to `base` directory -command = "bundle exec jekyll build" + base = "www/" + publish = "_site/" # relative to `base` directory + command = "../tools/combine-versions.sh && bundle exec jekyll build" + + [build.environment] + BUNDLE_GEMFILE = "Gemfile" [context.deploy-preview] - command = "bundle exec jekyll build --drafts --future" + base = "www/" + publish = "_site/" # relative to `base` directory + command = "../tools/combine-versions.sh && bundle exec jekyll build --drafts --future" diff --git a/resources/editable-diagrams/README.md b/resources/editable-diagrams/README.md index 50c766c5b..5c47960c6 100644 --- a/resources/editable-diagrams/README.md +++ b/resources/editable-diagrams/README.md @@ -8,7 +8,7 @@ ## What -Text and vector path editing has been preserved for these copies of the diagrams. They are not optimised and should not be published. For optimised, publishable versions, use the assets inside [docs/images](../../docs/images) +Text and vector path editing has been preserved for these copies of the diagrams. They are not optimised and should not be published. For optimised, publishable versions, use the assets inside [www/images](../../www/images) ## Included diff --git a/docs/spec/draft/about.md b/spec/about.md similarity index 100% rename from docs/spec/draft/about.md rename to spec/about.md diff --git a/docs/spec/draft/assessing-build-platforms.md b/spec/assessing-build-platforms.md similarity index 100% rename from docs/spec/draft/assessing-build-platforms.md rename to spec/assessing-build-platforms.md diff --git a/docs/spec/draft/assessing-source-systems.md b/spec/assessing-source-systems.md similarity index 100% rename from docs/spec/draft/assessing-source-systems.md rename to spec/assessing-source-systems.md diff --git a/docs/spec/draft/attestation-model.md b/spec/attestation-model.md similarity index 100% rename from docs/spec/draft/attestation-model.md rename to spec/attestation-model.md diff --git a/docs/spec/draft/build-env-track-basics.md b/spec/attested-build-env-levels.md similarity index 100% rename from docs/spec/draft/build-env-track-basics.md rename to spec/attested-build-env-levels.md diff --git a/spec/build-env-track-basics.md b/spec/build-env-track-basics.md new file mode 100644 index 000000000..9da530a3b --- /dev/null +++ b/spec/build-env-track-basics.md @@ -0,0 +1,440 @@ +--- +title: Build Environment track +description: This page gives an overview of the SLSA Build Environment track and its levels, describing their security objectives and general requirements. +mermaid: true +--- + +## Rationale + +Today's hosted [build platforms] play a central role in an artifact's supply +chain. Whether it's a cloud-hosted service like GitHub Actions or an internal +enterprise CI/CD system, the build platform has a privileged level of access +to artifacts and sensitive operations during a build (e.g., access to +producer secrets, provenance signing). + +This central and privileged role makes hosted build platforms an attractive +target for supply chain attackers. But even with strong economic and +reputational incentives to mitigate these risks, it's very challenging to +implement and operate fully secure build platforms because they are made up +of many layers of interconnected components and subsystems. + +The SLSA Build Environment track aims to address these issues by making it +possible to validate the integrity and trace the [provenance] of core build +platform components. + +## Track overview + +The SLSA Build Environment (BuildEnv) track describes increasing levels of +integrity and trustworthiness of the provenance of a build's +execution context. In this track, provenance describes how a build image +was created, how the hosted build platform deployed a build image in its +environment, and the compute platform they used. + +| Track/Level | Requirements | Focus | Trust Root +| ----------- | ------------ | ----- | ---------- +| [BuildEnv L0] | (none) | (n/a) | (n/a) +| [BuildEnv L1] | Signed build image provenance exists | Tampering during build image distribution | Signed build image provenance +| [BuildEnv L2] | Attested build environment instantiation | Tampering via the build platform's control plane | The compute platform's host interface +| [BuildEnv L3] | Hardware-attested build environment | Tampering via the compute platform's host interface | The compute platform's hardware + +> :warning: +> The Build Environment track L1+ currently requires a [hosted] build platform. +> A future version of this track may generalize requirements to cover bare-metal +> build environments. + +> :grey_exclamation: +> We may consider the addition of an L4 to the Build Environment track, which +> covers hardware-attested runtime integrity checking during a build. + +### Build environment model + +

Build Environment Model

+ +The Build Environment (BuildEnv) track expands upon the +[build model](terminology#build-model) by explicitly separating the +[build image](terminology#build-image) and [compute platform](#compute-platform) from the +abstract [build environment](#build-environment) and [build platform](terminology#platform). +Specifically, the BuildEnv track defines the following roles, components, and concepts: + +| Primary Term | Description +| --- | --- +| Build ID | An immutable identifier assigned uniquely to a specific execution of a tenant's build. In practice, the build ID may be an identifier, such as a UUID, associated with the build execution. +| Build image | The template for a build environment, such as a VM or container image. Individual components of a build image include the root filesystem, pre-installed guest OS and packages, the build executor, and the build agent. +| Build image producer | The party that creates and distributes build images. In practice, the build image producer may be the hosted build platform or a third party in a bring-your-own (BYO) build image setting. +| Build agent | A build platform-provided program that interfaces with the build platform's control plane from within a running build environment. The build agent is also responsible for executing the tenant’s build definition, i.e., running the build. In practice, the build agent may be loaded into the build environment after instantiation, and may consist of multiple components. All build agent components must be measured along with the build image. +| Build dispatch | The process of assigning a tenant's build to a pre-deployed build environment on a hosted build platform. +| Compute platform | The compute system and infrastructure underlying a build platform, i.e., the host system (hypervisor and/or OS) and hardware. In practice, the compute platform and the build platform may be managed by the same or distinct organizations. +| Host interface | The component in the compute platform that the hosted build platform uses to request resources for deploying new build environments, i.e., the VMM/hypervisor or container orchestrator. +| Boot process | In the context of builds, the process of loading and executing the layers of firmware and/or software needed to start up a build environment on the host compute platform. +| Measurement | The cryptographic hash of some component or system state in the build environment, including software binaries, configuration, or initialized run-time data. +| Quote | (Virtual) hardware-signed data that contains one or more (virtual) hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata. (Based on the definition in [section 9.5.3.1](https://trustedcomputinggroup.org/wp-content/uploads/TPM-2.0-1.83-Part-1-Architecture.pdf) of the TPM 2.0 spec) +| Reference value | A specific measurement used as the good known value for a given build environment component or state. + +**TODO:** Disambiguate similar terms (e.g., image, build job, build executor/runner) + +#### Build environment lifecycle + +A typical build environment will go through the following lifecycle: + +1. *Build image creation*: A [build image producer](#build-image-producer) + creates different [build images](#build-image) through a dedicated build + process. For the SLSA BuildEnv track, the build image producer outputs + [provenance](terminology#provenance) describing this process. +2. *Build environment instantiation*: The [hosted build platform](terminology#platform) + calls into the [host interface](#host-interface) to create a new instance + of a build environment from a given build image. The + [build agent](#build-agent) begins to wait for an incoming + [build dispatch](#build-dispatch). + For the SLSA BuildEnv track, the host interface in the compute platform + attests to the integrity of the environment's initial state during its + [boot process](#boot-process). +3. *Build dispatch*: When the tenant dispatches a new build, the hosted + build platform assigns the build to a created build environment. + For the SLSA BuildEnv track, the build platform attests to the binding + between a build environment and [build ID](#build-id). +4. *Build execution*: Finally, the build agent within the environment executes + the tenant's build definition. + +### Build environment threats + +The SLSA [Build track] defines requirements for the provenance that is produced for the build artifacts. +Trustworthiness of the build process largely depends on the trustworthiness of the [build environment] the build runs in. +The Build track assumes full trust into the [Build Platform], and provides no requirements to verify integrity of the build environment. +BuildEnv track intends to close this gap. + +Build environment is bootstrapped from a [build image], which is expected to be an artifact of a SLSA build pipeline. +Build platform verifies image security properties including provenance upon starting up the environment and makes evidence of the verification available to tenants or other auditors. + +BuildEnv track assumes full trust in the software that comes with the build image or is installed at runtime. +Malicious software having privileged access within the build environment might be able to circumvent protections provided by the BuildEnv track. +Image providers should manage vulnerabilities in the image components to reduce the risks of such attacks, e.g. by using SLSA Dependency track and hardening images with mandatory access control (MAC) policies. +Control Plane may perform additional analysis of the image SBOM as it bootstraps the build environment. + +Bootstrapping the build environment is a complex process, especially at higher SLSA levels. +[Build L3] usually requires significant changes to existing build platforms to maintain ephemeral build environments. +It is not uncommon for the build platforms to rely on public cloud providers to manage the compute resources that power build environments. +This in turn significantly expands the attack surface because added build platform dependencies become part of the [TCB]. +Cloud providers are big companies with complex infrastructure that often provide limited abilities to scope the context of trust and continuously validate it over time when using their services. + +The BuildEnv track addresses build TCB size concerns at [BuildEnv L2] and [BuildEnv L3] levels. + +[BuildEnv L1] level assumes full trust into the Build Platform including underlying [Compute Platform] (e.g., public cloud provider). + +[BuildEnv L2] level adds capabilities for verifying the Compute Platform providing evidence that the build environment is bootstrapped from the expected image with the expected early boot components (e.g. UEFI firmware) provided by the Compute Platform. +In essence L2 provides evidence of the boot time integrity of a build environment. +L2 also addresses malicious access to the build environment using compromised Build Platform Admin credentials assuming that image has Compute Platform maintenance agents disabled in it, which are typically used for providing remote access to the virtual machine using Compute Platform APIs. +It is the responsibility of the Image provider to disable/uninstall those agents. +Control Plane should verify that maintenance agents are disabled in the image upon consuming it. + +[BuildEnv L3] level reduces the Compute Platform attack surface through the use of trusted execution environments (TEEs) addressing runtime infrastructure threats that could be coming from compromised Compute Platform admin credentials (that would allow direct access to the host interface) or malicious software within the Compute Platform. +The [SEV-SNP/TDX threat model] describes this level of trust reduction through the use of memory encryption, integrity protection, and remote attestation with cryptographic keys that are certified by the hardware manufacturer. +L3 provides evidence of continuous integrity of the build environment for the whole lifetime. +TEE technologies are not infallible, so physical human access to hardware and side channel attacks are still a risk that is accepted at L3. + +This diagram outlines the lifetime of a build image between its creation and use in bootstrapping a build environment. +A Build Image could be compromised at any stage of its lifetime. +Higher SLSA BuildEnv levels secure the build environment from larger classes of threats. + +
+flowchart LR + BuildImage>Build Image] ---> |L1|BuildPlatform[[Build Platform]] + BuildPlatform[[Build Platform]] ---> |L2|ComputeProvider[[Compute Provider]] + ComputeProvider[[Compute Provider]] ---> |L3|BuildEnvironment[(Build Environment)] +
+ +[BuildEnv L1] protects from threats that happened during the build image *distribution*, i.e. in between image creation and consumption (e.g., pulling image from a shared registry) by the Build Platform. +This covers the case of unauthorized modifications to the image as it is distributed (potentially via untrusted channels). + +[BuildEnv L2] delivers boot time integrity providing cryptographic evidence that the build environment has been bootstrapped to an expected state. +The Compute platform is fully trusted at this level as it provides a virtual TPM device that performs boot measurements. + +[BuildEnv L3] extends boot time integrity into the run time all the way until the Build Environment is terminated. +L3 addresses threats coming from malicious actors (e.g., software agents or compromised admin credentials) in the Compute Platform host interface (see [SEV-SNP/TDX threat model] for the list of threats). +Vulnerabilities in the software that is legitimally included in the Build Image are out of scope. +Physical and side-channel attacks are out of scope too but may be considered in the additional future levels of this track. + +Practically, achieving L3 requires the build running in a confidential VM using technologies like [AMD SEV-SNP] and [Intel TDX]. +Compute Platform footprint in TCB is reduced but may not be eliminated completely if a confidential VM uses custom virtualization components running within it (e.g., [paravisor]). + +NOTE: [Control Plane] is considered trusted at L2 and L3 because it *verifies* the remote attestation of the build environment. +Build platforms MAY provide capabilities that let tenants perform remote attestation using a third-party verifier. +However, for the Control Plane to be considered untrusted it should have no back-door access to the build environment (e.g. via SSH). +Besides, Control Plane provides input data to the build environment (i.e. build request message) and security risks associated with compromising inputs have to be considered as well. + +For the example threats refer to the [Build Threats] section. + +## BuildEnv levels + +The primary purpose of the Build Environment (BuildEnv) track is to enable +auditing that a build was run in the expected [execution context]. + +The lowest level only requires SLSA [Build L2] Provenance to +exist for the [build image], while higher levels provide increasing +auditability of the build environment's properties and integrity of the +generated provenance attestations. The highest levels introduce further +requirements for hardware-assisted hardening of the [compute platform] +aimed at reducing the trusted computing base of a build. + +Software producers and third-party auditors can check attestations generated +by the [build image producer] and build platform against the expected +properties for a given build environment. This enables any party to detect +[several classes] of supply chain threats originating in the build +environment. + +As in the Build track, the exact implementation of this track is determined +by the build platform implementer, whether they are a commercial CI/CD service +or enterprise organization. While this track describes general minimum +requirements, this track does not dictate the following +implementation-specific details: the type of build environment, accepted +attestation formats, the type of technologies used to meet L3 requirements, +how attestations are distributed, how build environments are identified, and +what happens on failure. + +
+ +### BuildEnv L0: No guarantees + +
+
Summary
+ +No requirements---L0 represents the lack of any sort of build environment +provenance. + +
Intended for
+ +Development or test builds of software that are built and run on a local +machine, such as unit tests. + +
Requirements
+ +n/a + +
Benefits
+ +n/a + +
+
+ +
+ +### BuildEnv L1: Signed build image provenance exists + +
+
Summary
+ +The build image (i.e., VM or container image) used to instantiate the build +environment has SLSA Build Provenance showing how the image was built. + +
Intended for
+ +Build platforms and organizations wanting to ensure a baseline level of +integrity for build environments at the time of build image distribution. + +
Requirements
+ +- Build Image Producer: + - MUST automatically generate SLSA [Build L2] or higher + Provenance for created build images (i.e., VM or container images). + - MUST allow independent automatic verification of a build image's [SLSA + Build Provenance]. If the build image artifact cannot be published, for + example due to intellectual property concerns, an attestation asserting the + expected hash value of the build image MUST be generated and distributed + instead (e.g., using [SCAI] or a [Release Attestation]). If the full Build + Provenance document cannot be disclosed, a [VSA] asserting the build + image's SLSA Provenance MUST be distributed instead. + +- Build Platform: + - MUST meet SLSA [Build L2] requirements. + - Prior to the instantiation of a new build environment, the SLSA + Provenance for the selected build image MUST be automatically verified. + A signed attestation to the result of the SLSA Provenance verification + MUST be generated and distributed (e.g., via a [VSA]). + +
Benefits
+ +Provides evidence that a build image was built from the advertised +source and build process. + +
+ +
+
+ +### BuildEnv L2: Attested build environment instantiation + +
+
Summary
+ +The build environment is measured and authenticated by the compute platform +upon instantiation, attesting to the integrity of the initial state +of the environment prior to executing a build. + +
Intended for
+ +Organizations wanting to ensure that their build started from +a clean, known good state. + +
Requirements
+ +All of [BuildEnv L1], plus: + +- Build Image Producer: + - Build images MUST be created via a SLSA [Build L3] or higher build + process. + - MUST automatically generate and distribute signed [reference values] + for the following build image components: bootloader or equivalent, + guest kernel, [build agent], and root filesystem (e.g., via the image's + SLSA Provenance, or [SCAI]). + Additional build image components whose initial state is to be checked + MAY be also measured. + - The build agent MUST be capable of: + - Upon completion of the [boot process]: Automatically interfacing + with the host interface to obtain and transmit a signed quote for the + build environment's system state. + - Upon build dispatch: Automatically generating and distributing + a signed attestation that binds its boot process quote to the + assigned build ID (e.g., using [SCAI]). + +- Build Platform Requirements: + - MUST meet SLSA [Build L3] requirements. + - Prior to dispatching a tenant's build to an instantiated environment, + a signed [quote] MUST be automatically requested from the build agent, + and the contained [measurements] verified against their boot process + reference values. A signed attestation to the result of the verification + MUST be generated and distributed (e.g., via a [VSA]). + +- Compute Platform Requirements: + - The [host interface] MUST be capable of generating signed quotes for + the build environment's system state. + In a VM-based environment, this MUST be achieved by enabling a feature + like [vTPM], or equivalent, in the hypervisor. + For container-based environments, the container orchestrator MAY need + modifications to produce these attestations. + - The host interface MUST validate the measurements of the build image + components against their signed references values during the build + environment's boot process. + In a VM-based environment, this MUST be achieved by enabling a process + like [Secure Boot], or equivalent, in the hypervisor. + For container-based environments, the container orchestrator MAY need + modifications to perform these checks.[^1] + - Prior to instantiating a new build environment, the host interface + MUST automatically verify the SLSA Provenance for the selected build + image. A signed attestation to the verification of the build image's + SLSA Provenance MUST be automatically generated and distributed (e.g., + via a [VSA]). + +
Benefits
+ +Provides evidence that a build environment deployed by a hosted build +platform was instantiated from the expected build image and is at the +expected initial state, even in the face of a build platform-level +adversary. + +
+ +
+
+ +### BuildEnv L3: Hardware-attested build environment + +
+
Summary
+ +The initial state of the build's host environment is measured +and authenticated by trusted hardware, attesting to the integrity +of the build environment's underlying compute stack prior to executing +a build. + +
Intended for
+ +Organizations wanting strong assurances that their build ran on a good +known host environment. + +
Requirements
+ +All of [BuildEnv L2], plus: + +- Build Image Producer: + - Upon completion of the boot process: The build agent MUST be capable + of automatically interfacing with the *trusted hardware* component to + obtain a signed quote for the host interface's boot process and + the environment's system state. + - Upon build dispatch: The generated dispatch attestation MUST include + the host interface's boot process quote. + +- Build Platform Requirements: + - Prior to dispatching a tenant's build to an instantiated environment, + the measurements in the *host interface's* boot process quote MUST be + automatically verified against their reference values. + A signed attestation to the result of the verification MUST be generated + and distributed (e.g., via a [VSA]). + +- Compute Platform Requirements: + - MUST have trusted hardware capabilities, i.e., built-in physical + hardware features for generating measurements and quotes for its system + state. This SHOULD be achieved using a feature like [TPM], + [confidential computing], or equivalent. + - MUST enable validation of the host interface's boot process against + its reference values. This MUST be achieved by enabling a process + like [Secure Boot], or equivalent, in the host platform. + +
Benefits
+ +Provides hardware-authenticated evidence that a build ran in the expected +host environment, even in the face of a compromised host interface +(hypervisor/container orchestrator). + +
+ +
+ +## Considerations for Distributed Builds + +TODO + + + +[^1]: Since containers are executed as processes on the host platform they do not contain a traditional bootloader that starts up the execution context. + + + +[Build track]: build-track-basics.md +[Build L1]: build-track-basics.md#build-l1 +[Build L2]: build-track-basics.md#build-l2 +[Build L3]: build-track-basics.md#build-l3 +[BuildEnv L0]: #buildenv-l0 +[BuildEnv L1]: #buildenv-l1 +[BuildEnv L2]: #buildenv-l2 +[BuildEnv L3]: #buildenv-l3 +[Control plane]: terminology.md#control-plane +[Release Attestation]: https://github.com/in-toto/attestation/blob/main/spec/predicates/release.md +[SCAI]: https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md +[Secure Boot]: https://wiki.debian.org/SecureBoot#What_is_UEFI_Secure_Boot.3F +[SLSA Build Provenance]: provenance.md +[TPM]: https://trustedcomputinggroup.org/resource/tpm-library-specification/ +[VSA]: verification_summary.md +[build image]: #build-image +[confidential computing]: https://confidentialcomputing.io/wp-content/uploads/sites/10/2023/03/Common-Terminology-for-Confidential-Computing.pdf +[execution context]: terminology.md#build-environment +[hosted]: build-requirements.md#isolation-strength +[boot process]: #boot-process +[build agent]: #build-agent +[build environment]: terminology.md#build-environment +[build image producer]: #build-image-producer +[build platform]: terminology.md#platform +[build platforms]: terminology.md#platform +[Build Threats]: threats.md#build-threats +[compute platform]: #compute-platform +[host interface]: #host-interface +[measurement]: #measurement +[paravisor]: https://openvmm.dev/ +[provenance]: terminology.md#provenance +[quote]: #quote +[reference values]: #reference-value +[several classes]: #build-environment-threats +[vTPM]: https://trustedcomputinggroup.org/about/what-is-a-virtual-trusted-platform-module-vtpm/ +[AMD SEV-SNP]: https://www.amd.com/en/developer/sev.html +[Intel TDX]: https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/overview.html +[TCB]: https://csrc.nist.gov/glossary/term/trusted_computing_base +[SEV-SNP/TDX threat model]: https://www.kernel.org/doc/Documentation/security/snp-tdx-threat-model.rst diff --git a/docs/spec/draft/build-provenance.md b/spec/build-provenance.md similarity index 100% rename from docs/spec/draft/build-provenance.md rename to spec/build-provenance.md diff --git a/docs/spec/draft/build-requirements.md b/spec/build-requirements.md similarity index 100% rename from docs/spec/draft/build-requirements.md rename to spec/build-requirements.md diff --git a/docs/spec/draft/build-track-basics.md b/spec/build-track-basics.md similarity index 100% rename from docs/spec/draft/build-track-basics.md rename to spec/build-track-basics.md diff --git a/docs/spec/draft/dependency-track.md b/spec/dependency-track.md similarity index 100% rename from docs/spec/draft/dependency-track.md rename to spec/dependency-track.md diff --git a/docs/spec/draft/distributing-provenance.md b/spec/distributing-provenance.md similarity index 100% rename from docs/spec/draft/distributing-provenance.md rename to spec/distributing-provenance.md diff --git a/docs/spec/draft/faq.md b/spec/faq.md similarity index 100% rename from docs/spec/draft/faq.md rename to spec/faq.md diff --git a/docs/spec/draft/future-directions.md b/spec/future-directions.md similarity index 100% rename from docs/spec/draft/future-directions.md rename to spec/future-directions.md diff --git a/docs/spec/draft/images/build-env-model.svg b/spec/images/build-env-model.svg similarity index 100% rename from docs/spec/draft/images/build-env-model.svg rename to spec/images/build-env-model.svg diff --git a/docs/spec/draft/images/build-model.svg b/spec/images/build-model.svg similarity index 100% rename from docs/spec/draft/images/build-model.svg rename to spec/images/build-model.svg diff --git a/docs/spec/draft/images/provenance-model.svg b/spec/images/provenance-model.svg similarity index 100% rename from docs/spec/draft/images/provenance-model.svg rename to spec/images/provenance-model.svg diff --git a/docs/spec/draft/images/source-control-system-components.svg b/spec/images/source-control-system-components.svg similarity index 100% rename from docs/spec/draft/images/source-control-system-components.svg rename to spec/images/source-control-system-components.svg diff --git a/docs/spec/draft/images/supply-chain-model.svg b/spec/images/supply-chain-model.svg similarity index 100% rename from docs/spec/draft/images/supply-chain-model.svg rename to spec/images/supply-chain-model.svg diff --git a/docs/spec/draft/images/supply-chain-threats-build-verification.svg b/spec/images/supply-chain-threats-build-verification.svg similarity index 100% rename from docs/spec/draft/images/supply-chain-threats-build-verification.svg rename to spec/images/supply-chain-threats-build-verification.svg diff --git a/docs/spec/draft/images/supply-chain-threats.svg b/spec/images/supply-chain-threats.svg similarity index 100% rename from docs/spec/draft/images/supply-chain-threats.svg rename to spec/images/supply-chain-threats.svg diff --git a/docs/spec/draft/images/verification-model.svg b/spec/images/verification-model.svg similarity index 100% rename from docs/spec/draft/images/verification-model.svg rename to spec/images/verification-model.svg diff --git a/docs/spec/draft/index.md b/spec/index.md similarity index 100% rename from docs/spec/draft/index.md rename to spec/index.md diff --git a/docs/spec/v1.1/levels.md b/spec/levels.md similarity index 100% rename from docs/spec/v1.1/levels.md rename to spec/levels.md diff --git a/docs/spec/draft/onepage.md b/spec/onepage.md similarity index 100% rename from docs/spec/draft/onepage.md rename to spec/onepage.md diff --git a/docs/spec/draft/principles.md b/spec/principles.md similarity index 100% rename from docs/spec/draft/principles.md rename to spec/principles.md diff --git a/docs/spec/draft/provenance.md b/spec/provenance.md similarity index 100% rename from docs/spec/draft/provenance.md rename to spec/provenance.md diff --git a/docs/spec/draft/requirements.md b/spec/requirements.md similarity index 100% rename from docs/spec/draft/requirements.md rename to spec/requirements.md diff --git a/docs/spec/draft/schema/provenance.cue b/spec/schema/provenance.cue similarity index 100% rename from docs/spec/draft/schema/provenance.cue rename to spec/schema/provenance.cue diff --git a/docs/spec/draft/schema/provenance.proto b/spec/schema/provenance.proto similarity index 100% rename from docs/spec/draft/schema/provenance.proto rename to spec/schema/provenance.proto diff --git a/docs/spec/draft/source-example-controls.md b/spec/source-example-controls.md similarity index 100% rename from docs/spec/draft/source-example-controls.md rename to spec/source-example-controls.md diff --git a/docs/spec/draft/source-requirements.md b/spec/source-requirements.md similarity index 100% rename from docs/spec/draft/source-requirements.md rename to spec/source-requirements.md diff --git a/docs/spec/draft/terminology.md b/spec/terminology.md similarity index 100% rename from docs/spec/draft/terminology.md rename to spec/terminology.md diff --git a/docs/spec/draft/threats-overview.md b/spec/threats-overview.md similarity index 100% rename from docs/spec/draft/threats-overview.md rename to spec/threats-overview.md diff --git a/docs/spec/draft/threats.md b/spec/threats.md similarity index 100% rename from docs/spec/draft/threats.md rename to spec/threats.md diff --git a/docs/spec/draft/tracks.md b/spec/tracks.md similarity index 100% rename from docs/spec/draft/tracks.md rename to spec/tracks.md diff --git a/docs/spec/draft/use-cases.md b/spec/use-cases.md similarity index 100% rename from docs/spec/draft/use-cases.md rename to spec/use-cases.md diff --git a/docs/spec/draft/verification_summary.md b/spec/verification_summary.md similarity index 100% rename from docs/spec/draft/verification_summary.md rename to spec/verification_summary.md diff --git a/docs/spec/draft/verified-properties.md b/spec/verified-properties.md similarity index 100% rename from docs/spec/draft/verified-properties.md rename to spec/verified-properties.md diff --git a/docs/spec/draft/verifying-artifacts.md b/spec/verifying-artifacts.md similarity index 100% rename from docs/spec/draft/verifying-artifacts.md rename to spec/verifying-artifacts.md diff --git a/docs/spec/draft/verifying-source.md b/spec/verifying-source.md similarity index 100% rename from docs/spec/draft/verifying-source.md rename to spec/verifying-source.md diff --git a/docs/spec/v1.1-rc2/verifying-systems.md b/spec/verifying-systems.md similarity index 100% rename from docs/spec/v1.1-rc2/verifying-systems.md rename to spec/verifying-systems.md diff --git a/docs/spec/draft/whats-new.md b/spec/whats-new.md similarity index 100% rename from docs/spec/draft/whats-new.md rename to spec/whats-new.md diff --git a/tools/combine-versions.sh b/tools/combine-versions.sh new file mode 100755 index 000000000..397d4b935 --- /dev/null +++ b/tools/combine-versions.sh @@ -0,0 +1,83 @@ +# This script combines multiple versions of the SLSA spec into the ./spec directory for deployment. +# +# Target folder structure after running: +# ./spec/ +# draft/ # Latest draft version from /spec +# v1.0/ # Spec files from releases/v1.0 branch +# v1.0-rc1/ # Spec files from releases/v1.0-rc1 branch +# v1.0-rc2/ # Spec files from releases/v1.0-rc2 branch +# v1.1-rc1/ # Spec files from releases/v1.1-rc1 branch +# v1.1-rc2/ # Spec files from releases/v1.1-rc2 branch +# Each subdirectory contains a full copy of the spec files for that version. +# Usage: ./combine-versions.sh + +# Ensure the script is run from www/ +if [ "$(basename $(pwd))" != "www" ]; then + echo "Error: This script must be run from the www directory." + exit 1 +fi + +# --- Parse command line arguments --- +FETCH_BRANCHES=true + +for arg in "$@"; do + case "$arg" in + --nofetch) + FETCH_BRANCHES=false + ;; + --help) + echo "Usage: $0 [--fetch]" + echo "" + echo "Options:" + echo " --nofetch Do not fetch branches from the remote repository (default is to fetch)" + echo " --help Show this help message" + exit 0 + ;; + *) + echo "Unknown option: $arg" + echo "Use --help for usage information." + exit 1 + ;; + esac +done + +CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) +if [ "$CURRENT_BRANCH" = "HEAD" ]; then + # If detached, store commit SHA + CURRENT_BRANCH=$(git rev-parse HEAD) +fi + +REPO_ROOT=$(git rev-parse --show-toplevel) + +# clean spec dir +echo Cleaning spec folder +if [ -d spec ]; then + rm -rf spec +fi +mkdir spec + +# deploy draft from main +echo Populating spec/draft +mkdir spec/draft +cp -r "$REPO_ROOT/spec"/* spec/draft/ + +# deploy older versions +for FULLNAME_BRANCH in $(git branch -r --list 'origin/releases/*'); do + VERSION="$(basename $FULLNAME_BRANCH)" + RELEASE_BRANCH=releases/$VERSION + echo Populating spec/$VERSION + git -C "$REPO_ROOT" reset --hard + if [[ "$FETCH_BRANCHES" == true ]]; then + git -C "$REPO_ROOT" fetch origin $RELEASE_BRANCH:refs/remotes/origin/$RELEASE_BRANCH + fi + git -C "$REPO_ROOT" checkout $RELEASE_BRANCH + mkdir spec/$VERSION + cp -r "$REPO_ROOT/spec"/* spec/$VERSION/ +done + +# back to the original branch +git reset --hard +git checkout $CURRENT_BRANCH +echo ' +The spec folder is now ready:' +ls -F spec diff --git a/tools/diff_site b/tools/diff_site index 703e8a6e9..1b60b18a4 100755 --- a/tools/diff_site +++ b/tools/diff_site @@ -2,7 +2,7 @@ USAGE="USAGE: $0 DIR_OR_FILE DIR_OR_FILE"' Displays the diff of two built site directories, each of which can be a -local directory (usually `docs/_site`) or a `deploy-*.zip` archive downloaded +local directory (usually `www/_site`) or a `deploy-*.zip` archive downloaded from Netlify. Before diffing, we filter out innocuous changes such as the Jekyll version or git commit IDs; see `textconv` in this directory for details. diff --git a/tools/lint.sh b/tools/lint.sh index e91f35a94..1091f6943 100755 --- a/tools/lint.sh +++ b/tools/lint.sh @@ -37,7 +37,7 @@ EOF # This uses a heuristic to detect links in Markdown files, namely # `https?://slsa.dev` immediately following `(` or `]: `. check_absolute_links() { - local FILES=':/docs/*.md' + local FILES=':/www/*.md' local CMD=( git grep --break --heading --line-number -e '\((\|\]: \)https\?://slsa.dev' diff --git a/tools/textconv b/tools/textconv index 1564e698f..aa69b39df 100755 --- a/tools/textconv +++ b/tools/textconv @@ -16,5 +16,6 @@ # Ignore Jekyll version number s@Jekyll v[0-9.]\+@Jekyll v#.#.#@ -# Ignore git commit ID +# Ignore git commit ID - cover both old /docs dir and new /www one s@/slsa/blob/[0-9a-f]\+/docs/@/slsa/blob/COMMIT/docs/@g +s@/slsa/blob/[0-9a-f]\+/www/@/slsa/blob/COMMIT/docs/@g diff --git a/docs/.ruby-version b/www/.ruby-version similarity index 100% rename from docs/.ruby-version rename to www/.ruby-version diff --git a/docs/404.md b/www/404.md similarity index 100% rename from docs/404.md rename to www/404.md diff --git a/docs/Gemfile b/www/Gemfile similarity index 100% rename from docs/Gemfile rename to www/Gemfile diff --git a/docs/Gemfile.lock b/www/Gemfile.lock similarity index 100% rename from docs/Gemfile.lock rename to www/Gemfile.lock diff --git a/docs/README.md b/www/README.md similarity index 87% rename from docs/README.md rename to www/README.md index c9bf8c97a..d514931be 100644 --- a/docs/README.md +++ b/www/README.md @@ -7,11 +7,11 @@ served by [Netlify](https://netlify.com). ### Building and testing locally -1. Clone this repo and change directory to `/docs`: +1. Clone this repo and change directory to `/www`: ```bash git clone https://github.com/slsa-framework/slsa - cd slsa/docs + cd slsa/www ``` 2. Install system dependencies: @@ -95,7 +95,7 @@ downloaded from Netlify (`deploy-*.zip`). Example 1: comparing two locally built versions of the site ```bash -# Prepare version A +# Prepare version A $ bundle exec jekyll build $ mv _site _site.A # Prepare version B @@ -128,9 +128,8 @@ Team configuration: https://app.netlify.com/teams/slsa Prefer to configure the site using `netlify.toml` rather than the web UI, when possible. -To be added to ACL to allow you to configure the site, contact Mark Lodato or -Joshua Lock via email or Slack. In the event that no SLSA team member has -access, contact OpenSSF. +To be added to the ACL to allow you to configure the site, open an issue asking +for access. ### Production builds @@ -178,7 +177,7 @@ about when publishing a new version of the SLSA specification. Several configuration files govern the website layout and behavior. -#### docs/_data/versions.yml +#### www/_data/versions.yml This file defines the status of the different versions of the specification (Draft, Approved, or Retired) along with which version is the current one @@ -188,7 +187,7 @@ not the current one with a pointer to the current version). The `hidden` property was used by the version selector which was abandoned and is no longer in use. -#### docs/_data/nav/* +#### www/_data/nav/* This folder contains a set of files defining the navigation side bars to be used for the different versions of the specification. @@ -210,16 +209,16 @@ specification. Practically speaking this means that, when you remove a specific version from `main.yaml` you should always create a corresponding `v***.yaml` if none exists already. -The content of the navigation files is used (in `docs/_includes/nav.html`) to +The content of the navigation files is used (in `www/_includes/nav.html`) to define the navigation side bar but also to define (in -`docs/_includes/pagination.html`) how pages are chained via the previous and +`www/_includes/pagination.html`) how pages are chained via the previous and next links displayed at the bottom of a page). The `config.yml` file defines the mapping of the version of the specification taken from the page URL to the key in the site.data.nav array where the various navigation menu definitions are stored. -### docs/_redirects +### www/_redirects Typical website configuration type of file, defining a bunch of redirects used to maintain backwards compatibility and provide for some resilience by defining @@ -232,7 +231,7 @@ burden. This lists some of the steps one must take to publish a new version of the specification: -- Edit `docs/_data/versions.yml` to add the new version, with its status, and possibly update the status of the previous one. -- Edit `docs/_data/nav/config.yml` to add the new version -- Edit `docs/_data/main.yml` to add the new version and possibly remove any older versions to be hidden. If you remove an old version, make sure that a version specific file exists because it will be needed if the hidden version is accessed directly. -- Edit `docs/_redirects` as necessary including the definition of `/spec/latest/*` +- Edit `www/_data/versions.yml` to add the new version, with its status, and possibly update the status of the previous one. +- Edit `www/_data/nav/config.yml` to add the new version +- Edit `www/_data/main.yml` to add the new version and possibly remove any older versions to be hidden. If you remove an old version, make sure that a version specific file exists because it will be needed if the hidden version is accessed directly. +- Edit `www/_redirects` as necessary including the definition of `/spec/latest/*` diff --git a/docs/_config.yml b/www/_config.yml similarity index 100% rename from docs/_config.yml rename to www/_config.yml diff --git a/docs/_data/nav/config.yml b/www/_data/nav/config.yml similarity index 100% rename from docs/_data/nav/config.yml rename to www/_data/nav/config.yml diff --git a/www/_data/nav/draft.yml b/www/_data/nav/draft.yml new file mode 100644 index 000000000..a26cc39bd --- /dev/null +++ b/www/_data/nav/draft.yml @@ -0,0 +1,140 @@ +# Pages that show in the nav aside and in the spec index page. +# The spec index does not show top-level elements without children. + +- title: Home + url: / + +- title: Current activities + url: /current-activities + description: What the SLSA community is currently working on + +- title: SLSA Working Draft + url: /spec/draft/ + +- title: Understanding SLSA + description: > + These pages provide an overview of SLSA, how it helps protect against common + supply chain attacks, and common use cases. If you're new to SLSA or + supply chain security, start here. + children: + + - title: What's new + url: /spec/draft/whats-new + description: The changes brought by this Working Draft. + + - title: About SLSA + url: /spec/draft/about + description: An introductory guide to SLSA + + - title: Supply chain threats + url: /spec/draft/threats-overview + description: An introduction to supply chain threats + + - title: Use cases + url: /spec/draft/use-cases + description: Use cases + + - title: Guiding principles + url: /spec/draft/principles + description: Use cases + + - title: FAQ + url: /spec/draft/faq + description: Questions and more information + + - title: Future directions + url: /spec/draft/future-directions + description: Additions and changes being considered for future SLSA versions + +- title: Core specification + description: > + These pages describe SLSA's security levels and requirements for each track. + If you want to achieve SLSA a particular level, these are the requirements + you'll need to meet. + children: + + - title: Terminology + url: /spec/draft/terminology + description: Terminology and model used by SLSA + + - title: Security levels + url: /spec/draft/levels + description: Overview of SLSA's tracks and levels, intended for all audiences + + - title: Producing artifacts + url: /spec/draft/requirements + description: Detailed technical requirements for producing software artifacts, intended for platform implementers + + - title: Distributing provenance + url: /spec/draft/distributing-provenance + description: Detailed technical requirements for distributing provenance, intended for platform implementers and software distributors + + - title: Verifying artifacts + url: /spec/draft/verifying-artifacts + description: Guidance for verifying software artifacts and their SLSA provenance, intended for platform implementers and software consumers + + - title: Verifying build platforms + url: /spec/draft/verifying-systems + description: Guidelines for securing SLSA Build L3+ builders, intended for platform implementers + + - title: Integrity levels for attested build environments + url: /spec/draft/attested-build-env-levels + description: Overview of SLSA's Attested Build Environment track, intended for all audiences + + - title: Threats & mitigations + url: /spec/draft/threats + description: Detailed information about specific supply chain attacks and how SLSA helps + + - title: Securing Source Code + url: /spec/draft/source-requirements + description: Overview of the Source track + +- title: Attestation formats + description: > + These pages include the concrete schemas for SLSA attestations. The + Provenance and VSA formats are recommended, but not required by the + specification. + children: + + - title: General model + url: /spec/draft/attestation-model + description: General attestation mode + + - title: Provenance + url: /spec/draft/provenance + description: Suggested provenance format and explanation + + - title: Verification Summary + url: /spec/draft/verification_summary + description: Suggested VSA format and explanation + +- title: How to SLSA + description: > + These instructions tell you how to apply the core SLSA specification to use + SLSA in your specific situation. + children: + + - title: For developers + url: /get-started + description: How to apply SLSA requirements to your build + + - title: For organizations + url: /how-to-orgs + description: How to apply SLSA to an organization + + - title: For infrastructure providers + url: /how-to-infra + description: How to implement SLSA in source, build, and package platforms + +- title: Specification stages + url: /spec-stages + +- title: Community + url: /community + +- title: Blog + url: /blog + +- title: Single-page view + url: /spec/draft/onepage + skip_next_prev: true # don't show as a next/prev link diff --git a/docs/_data/nav/main.yml b/www/_data/nav/main.yml similarity index 100% rename from docs/_data/nav/main.yml rename to www/_data/nav/main.yml diff --git a/docs/_data/nav/v0.1.yml b/www/_data/nav/v0.1.yml similarity index 100% rename from docs/_data/nav/v0.1.yml rename to www/_data/nav/v0.1.yml diff --git a/docs/_data/nav/v0.2.yml b/www/_data/nav/v0.2.yml similarity index 100% rename from docs/_data/nav/v0.2.yml rename to www/_data/nav/v0.2.yml diff --git a/docs/_data/nav/v1.0-rc1.yml b/www/_data/nav/v1.0-rc1.yml similarity index 100% rename from docs/_data/nav/v1.0-rc1.yml rename to www/_data/nav/v1.0-rc1.yml diff --git a/docs/_data/nav/v1.0-rc2.yml b/www/_data/nav/v1.0-rc2.yml similarity index 100% rename from docs/_data/nav/v1.0-rc2.yml rename to www/_data/nav/v1.0-rc2.yml diff --git a/docs/_data/nav/v1.0.yml b/www/_data/nav/v1.0.yml similarity index 100% rename from docs/_data/nav/v1.0.yml rename to www/_data/nav/v1.0.yml diff --git a/docs/_data/nav/v1.1-rc1.yml b/www/_data/nav/v1.1-rc1.yml similarity index 100% rename from docs/_data/nav/v1.1-rc1.yml rename to www/_data/nav/v1.1-rc1.yml diff --git a/docs/_data/nav/v1.1-rc2.yml b/www/_data/nav/v1.1-rc2.yml similarity index 100% rename from docs/_data/nav/v1.1-rc2.yml rename to www/_data/nav/v1.1-rc2.yml diff --git a/docs/_data/nav/v1.2-rc1.yml b/www/_data/nav/v1.2-rc1.yml similarity index 100% rename from docs/_data/nav/v1.2-rc1.yml rename to www/_data/nav/v1.2-rc1.yml diff --git a/docs/_data/nav/v1.2-rc2.yml b/www/_data/nav/v1.2-rc2.yml similarity index 100% rename from docs/_data/nav/v1.2-rc2.yml rename to www/_data/nav/v1.2-rc2.yml diff --git a/docs/_data/versions.yml b/www/_data/versions.yml similarity index 100% rename from docs/_data/versions.yml rename to www/_data/versions.yml diff --git a/docs/_includes/analytics.html b/www/_includes/analytics.html similarity index 100% rename from docs/_includes/analytics.html rename to www/_includes/analytics.html diff --git a/docs/_includes/aside.html b/www/_includes/aside.html similarity index 100% rename from docs/_includes/aside.html rename to www/_includes/aside.html diff --git a/docs/_includes/footer.html b/www/_includes/footer.html similarity index 75% rename from docs/_includes/footer.html rename to www/_includes/footer.html index fcedbeb79..9ccc7cc9d 100644 --- a/docs/_includes/footer.html +++ b/www/_includes/footer.html @@ -11,7 +11,18 @@

- + {% assign path_parts = page.path | split: "/" %} + {% if path_parts[0] == "spec" and path_parts[1] == "draft" %} + {% assign remaining_path = page.path | remove_first: "spec/draft/" %} + {% assign github_path = {{site.github.build_revision}} | append: "/spec/" | append: remaining_path %} + {% elsif path_parts[0] == "spec" %} + {% assign version = path_parts[1] %} + {% assign remaining_path = page.path | remove_first: "spec/" | remove_first: version | remove_first: "/" %} + {% assign github_path = "releases/" | append: version | append: "/spec/" | append: remaining_path %} + {% else %} + {% assign github_path = {{site.github.build_revision}} | append: "/www/" | append: page.path %} + {% endif %} + View source on GitHub diff --git a/docs/_includes/head.html b/www/_includes/head.html similarity index 100% rename from docs/_includes/head.html rename to www/_includes/head.html diff --git a/docs/_includes/header.html b/www/_includes/header.html similarity index 100% rename from docs/_includes/header.html rename to www/_includes/header.html diff --git a/docs/_includes/levels-card.html b/www/_includes/levels-card.html similarity index 100% rename from docs/_includes/levels-card.html rename to www/_includes/levels-card.html diff --git a/docs/_includes/mermaid.html b/www/_includes/mermaid.html similarity index 100% rename from docs/_includes/mermaid.html rename to www/_includes/mermaid.html diff --git a/docs/_includes/nav-level.html b/www/_includes/nav-level.html similarity index 100% rename from docs/_includes/nav-level.html rename to www/_includes/nav-level.html diff --git a/docs/_includes/nav.html b/www/_includes/nav.html similarity index 100% rename from docs/_includes/nav.html rename to www/_includes/nav.html diff --git a/docs/_includes/onepage.liquid b/www/_includes/onepage.liquid similarity index 100% rename from docs/_includes/onepage.liquid rename to www/_includes/onepage.liquid diff --git a/docs/_includes/pagination-parse.liquid b/www/_includes/pagination-parse.liquid similarity index 100% rename from docs/_includes/pagination-parse.liquid rename to www/_includes/pagination-parse.liquid diff --git a/docs/_includes/pagination.html b/www/_includes/pagination.html similarity index 100% rename from docs/_includes/pagination.html rename to www/_includes/pagination.html diff --git a/docs/_includes/section.liquid b/www/_includes/section.liquid similarity index 100% rename from docs/_includes/section.liquid rename to www/_includes/section.liquid diff --git a/docs/_includes/specifications-list.html b/www/_includes/specifications-list.html similarity index 100% rename from docs/_includes/specifications-list.html rename to www/_includes/specifications-list.html diff --git a/docs/_includes/specifications-versions.html b/www/_includes/specifications-versions.html similarity index 100% rename from docs/_includes/specifications-versions.html rename to www/_includes/specifications-versions.html diff --git a/docs/_includes/status.html b/www/_includes/status.html similarity index 100% rename from docs/_includes/status.html rename to www/_includes/status.html diff --git a/docs/_includes/testimonial-card.html b/www/_includes/testimonial-card.html similarity index 100% rename from docs/_includes/testimonial-card.html rename to www/_includes/testimonial-card.html diff --git a/docs/_includes/toc.html b/www/_includes/toc.html similarity index 100% rename from docs/_includes/toc.html rename to www/_includes/toc.html diff --git a/docs/_includes/versions-dropdown.html b/www/_includes/versions-dropdown.html similarity index 100% rename from docs/_includes/versions-dropdown.html rename to www/_includes/versions-dropdown.html diff --git a/docs/_layouts/404.html b/www/_layouts/404.html similarity index 100% rename from docs/_layouts/404.html rename to www/_layouts/404.html diff --git a/docs/_layouts/default.html b/www/_layouts/default.html similarity index 100% rename from docs/_layouts/default.html rename to www/_layouts/default.html diff --git a/docs/_layouts/home.html b/www/_layouts/home.html similarity index 100% rename from docs/_layouts/home.html rename to www/_layouts/home.html diff --git a/docs/_layouts/post-list.html b/www/_layouts/post-list.html similarity index 100% rename from docs/_layouts/post-list.html rename to www/_layouts/post-list.html diff --git a/docs/_layouts/post.html b/www/_layouts/post.html similarity index 100% rename from docs/_layouts/post.html rename to www/_layouts/post.html diff --git a/docs/_layouts/specifications.html b/www/_layouts/specifications.html similarity index 100% rename from docs/_layouts/specifications.html rename to www/_layouts/specifications.html diff --git a/docs/_layouts/standard.html b/www/_layouts/standard.html similarity index 100% rename from docs/_layouts/standard.html rename to www/_layouts/standard.html diff --git a/docs/_posts/2022-04-08-blog-launch.md b/www/_posts/2022-04-08-blog-launch.md similarity index 100% rename from docs/_posts/2022-04-08-blog-launch.md rename to www/_posts/2022-04-08-blog-launch.md diff --git a/docs/_posts/2022-04-11-slsa-is-no-free-lunch.md b/www/_posts/2022-04-11-slsa-is-no-free-lunch.md similarity index 100% rename from docs/_posts/2022-04-11-slsa-is-no-free-lunch.md rename to www/_posts/2022-04-11-slsa-is-no-free-lunch.md diff --git a/docs/_posts/2022-05-02-slsa-sbom.md b/www/_posts/2022-05-02-slsa-sbom.md similarity index 100% rename from docs/_posts/2022-05-02-slsa-sbom.md rename to www/_posts/2022-05-02-slsa-sbom.md diff --git a/docs/_posts/2022-06-15-slsa-ssdf.md b/www/_posts/2022-06-15-slsa-ssdf.md similarity index 100% rename from docs/_posts/2022-06-15-slsa-ssdf.md rename to www/_posts/2022-06-15-slsa-ssdf.md diff --git a/docs/_posts/2022-06-20-slsa-github-workflows.md b/www/_posts/2022-06-20-slsa-github-workflows.md similarity index 100% rename from docs/_posts/2022-06-20-slsa-github-workflows.md rename to www/_posts/2022-06-20-slsa-github-workflows.md diff --git a/docs/_posts/2022-07-25-slsa-foundational-framework.md b/www/_posts/2022-07-25-slsa-foundational-framework.md similarity index 100% rename from docs/_posts/2022-07-25-slsa-foundational-framework.md rename to www/_posts/2022-07-25-slsa-foundational-framework.md diff --git a/docs/_posts/2022-08-29-slsa-github-workflows-generic-ga.md b/www/_posts/2022-08-29-slsa-github-workflows-generic-ga.md similarity index 100% rename from docs/_posts/2022-08-29-slsa-github-workflows-generic-ga.md rename to www/_posts/2022-08-29-slsa-github-workflows-generic-ga.md diff --git a/docs/_posts/2022-09-26-eo-in-plain-english.md b/www/_posts/2022-09-26-eo-in-plain-english.md similarity index 100% rename from docs/_posts/2022-09-26-eo-in-plain-english.md rename to www/_posts/2022-09-26-eo-in-plain-english.md diff --git a/docs/_posts/2022-12-05-gcb-slsa-verification.md b/www/_posts/2022-12-05-gcb-slsa-verification.md similarity index 100% rename from docs/_posts/2022-12-05-gcb-slsa-verification.md rename to www/_posts/2022-12-05-gcb-slsa-verification.md diff --git a/docs/_posts/2023-02-01-slsa-github-workflows-container-ga.md b/www/_posts/2023-02-01-slsa-github-workflows-container-ga.md similarity index 100% rename from docs/_posts/2023-02-01-slsa-github-workflows-container-ga.md rename to www/_posts/2023-02-01-slsa-github-workflows-container-ga.md diff --git a/docs/_posts/2023-02-24-slsa-v1-rc.md b/www/_posts/2023-02-24-slsa-v1-rc.md similarity index 100% rename from docs/_posts/2023-02-24-slsa-v1-rc.md rename to www/_posts/2023-02-24-slsa-v1-rc.md diff --git a/docs/_posts/2023-04-03-the-breadth-and-depth-of-slsa.md b/www/_posts/2023-04-03-the-breadth-and-depth-of-slsa.md similarity index 100% rename from docs/_posts/2023-04-03-the-breadth-and-depth-of-slsa.md rename to www/_posts/2023-04-03-the-breadth-and-depth-of-slsa.md diff --git a/docs/_posts/2023-04-04-slsa-v1-rc2.md b/www/_posts/2023-04-04-slsa-v1-rc2.md similarity index 100% rename from docs/_posts/2023-04-04-slsa-v1-rc2.md rename to www/_posts/2023-04-04-slsa-v1-rc2.md diff --git a/docs/_posts/2023-04-19-slsa-v1-final.md b/www/_posts/2023-04-19-slsa-v1-final.md similarity index 100% rename from docs/_posts/2023-04-19-slsa-v1-final.md rename to www/_posts/2023-04-19-slsa-v1-final.md diff --git a/docs/_posts/2023-05-02-in-toto-and-slsa.md b/www/_posts/2023-05-02-in-toto-and-slsa.md similarity index 100% rename from docs/_posts/2023-05-02-in-toto-and-slsa.md rename to www/_posts/2023-05-02-in-toto-and-slsa.md diff --git a/docs/_posts/2023-05-11-bringing-improved-supply-chain-security-to-the-nodejs-ecosystem.md b/www/_posts/2023-05-11-bringing-improved-supply-chain-security-to-the-nodejs-ecosystem.md similarity index 100% rename from docs/_posts/2023-05-11-bringing-improved-supply-chain-security-to-the-nodejs-ecosystem.md rename to www/_posts/2023-05-11-bringing-improved-supply-chain-security-to-the-nodejs-ecosystem.md diff --git a/docs/_posts/2023-06-13-slsa-github-workflows-container-based.md b/www/_posts/2023-06-13-slsa-github-workflows-container-based.md similarity index 100% rename from docs/_posts/2023-06-13-slsa-github-workflows-container-based.md rename to www/_posts/2023-06-13-slsa-github-workflows-container-based.md diff --git a/docs/_posts/2023-08-28-bring-your-own-builder-github.md b/www/_posts/2023-08-28-bring-your-own-builder-github.md similarity index 100% rename from docs/_posts/2023-08-28-bring-your-own-builder-github.md rename to www/_posts/2023-08-28-bring-your-own-builder-github.md diff --git a/docs/_posts/2024-04-16-tekton-chains-ibm-devsecops.md b/www/_posts/2024-04-16-tekton-chains-ibm-devsecops.md similarity index 100% rename from docs/_posts/2024-04-16-tekton-chains-ibm-devsecops.md rename to www/_posts/2024-04-16-tekton-chains-ibm-devsecops.md diff --git a/docs/_posts/2024-08-13-dep-confusion-and-typosquatting.md b/www/_posts/2024-08-13-dep-confusion-and-typosquatting.md similarity index 100% rename from docs/_posts/2024-08-13-dep-confusion-and-typosquatting.md rename to www/_posts/2024-08-13-dep-confusion-and-typosquatting.md diff --git a/docs/_posts/2025-04-04-slsa-v1.1-rc2.md b/www/_posts/2025-04-04-slsa-v1.1-rc2.md similarity index 100% rename from docs/_posts/2025-04-04-slsa-v1.1-rc2.md rename to www/_posts/2025-04-04-slsa-v1.1-rc2.md diff --git a/docs/_posts/2025-04-21-slsa-v1.1.md b/www/_posts/2025-04-21-slsa-v1.1.md similarity index 100% rename from docs/_posts/2025-04-21-slsa-v1.1.md rename to www/_posts/2025-04-21-slsa-v1.1.md diff --git a/docs/_posts/2025-04-29-slsa-source-sprint.md b/www/_posts/2025-04-29-slsa-source-sprint.md similarity index 100% rename from docs/_posts/2025-04-29-slsa-source-sprint.md rename to www/_posts/2025-04-29-slsa-source-sprint.md diff --git a/docs/_posts/2025-06-20-slsa-v1.2-rc1.md b/www/_posts/2025-06-20-slsa-v1.2-rc1.md similarity index 100% rename from docs/_posts/2025-06-20-slsa-v1.2-rc1.md rename to www/_posts/2025-06-20-slsa-v1.2-rc1.md diff --git a/docs/_posts/2025-07-22-slsa-e2e.md b/www/_posts/2025-07-22-slsa-e2e.md similarity index 100% rename from docs/_posts/2025-07-22-slsa-e2e.md rename to www/_posts/2025-07-22-slsa-e2e.md diff --git a/docs/_posts/2025-10-21-slsa-e2e-with-ampel.md b/www/_posts/2025-10-21-slsa-e2e-with-ampel.md similarity index 100% rename from docs/_posts/2025-10-21-slsa-e2e-with-ampel.md rename to www/_posts/2025-10-21-slsa-e2e-with-ampel.md diff --git a/docs/_posts/2025-11-10-slsa-v1.2-rc2.md b/www/_posts/2025-11-10-slsa-v1.2-rc2.md similarity index 100% rename from docs/_posts/2025-11-10-slsa-v1.2-rc2.md rename to www/_posts/2025-11-10-slsa-v1.2-rc2.md diff --git a/docs/_posts/2025-11-24-announce-slsa-v1.2.md b/www/_posts/2025-11-24-announce-slsa-v1.2.md similarity index 100% rename from docs/_posts/2025-11-24-announce-slsa-v1.2.md rename to www/_posts/2025-11-24-announce-slsa-v1.2.md diff --git a/docs/_posts/2025-12-18-supply-chain-robots-slsa.md b/www/_posts/2025-12-18-supply-chain-robots-slsa.md similarity index 100% rename from docs/_posts/2025-12-18-supply-chain-robots-slsa.md rename to www/_posts/2025-12-18-supply-chain-robots-slsa.md diff --git a/docs/_redirects b/www/_redirects similarity index 100% rename from docs/_redirects rename to www/_redirects diff --git a/docs/_sass/dl-as-table.scss b/www/_sass/dl-as-table.scss similarity index 100% rename from docs/_sass/dl-as-table.scss rename to www/_sass/dl-as-table.scss diff --git a/docs/_sass/minima.scss b/www/_sass/minima.scss similarity index 100% rename from docs/_sass/minima.scss rename to www/_sass/minima.scss diff --git a/docs/_sass/minima/_base.scss b/www/_sass/minima/_base.scss similarity index 100% rename from docs/_sass/minima/_base.scss rename to www/_sass/minima/_base.scss diff --git a/docs/_sass/minima/_custom.scss b/www/_sass/minima/_custom.scss similarity index 100% rename from docs/_sass/minima/_custom.scss rename to www/_sass/minima/_custom.scss diff --git a/docs/_sass/minima/_layout.scss b/www/_sass/minima/_layout.scss similarity index 100% rename from docs/_sass/minima/_layout.scss rename to www/_sass/minima/_layout.scss diff --git a/docs/_sass/minima/_syntax-highlighting.scss b/www/_sass/minima/_syntax-highlighting.scss similarity index 100% rename from docs/_sass/minima/_syntax-highlighting.scss rename to www/_sass/minima/_syntax-highlighting.scss diff --git a/docs/blog.html b/www/blog.html similarity index 100% rename from docs/blog.html rename to www/blog.html diff --git a/docs/community.md b/www/community.md similarity index 100% rename from docs/community.md rename to www/community.md diff --git a/docs/current-activities.md b/www/current-activities.md similarity index 100% rename from docs/current-activities.md rename to www/current-activities.md diff --git a/docs/fonts/ibm_plex/IBMPlexMono-Regular-Cyrillic.woff2 b/www/fonts/ibm_plex/IBMPlexMono-Regular-Cyrillic.woff2 similarity index 100% rename from docs/fonts/ibm_plex/IBMPlexMono-Regular-Cyrillic.woff2 rename to www/fonts/ibm_plex/IBMPlexMono-Regular-Cyrillic.woff2 diff --git a/docs/fonts/ibm_plex/IBMPlexMono-Regular-Latin1.woff2 b/www/fonts/ibm_plex/IBMPlexMono-Regular-Latin1.woff2 similarity index 100% rename from docs/fonts/ibm_plex/IBMPlexMono-Regular-Latin1.woff2 rename to www/fonts/ibm_plex/IBMPlexMono-Regular-Latin1.woff2 diff --git a/docs/fonts/ibm_plex/IBMPlexMono-Regular-Latin2.woff2 b/www/fonts/ibm_plex/IBMPlexMono-Regular-Latin2.woff2 similarity index 100% rename from docs/fonts/ibm_plex/IBMPlexMono-Regular-Latin2.woff2 rename to www/fonts/ibm_plex/IBMPlexMono-Regular-Latin2.woff2 diff --git a/docs/fonts/ibm_plex/IBMPlexMono-Regular-Latin3.woff2 b/www/fonts/ibm_plex/IBMPlexMono-Regular-Latin3.woff2 similarity index 100% rename from docs/fonts/ibm_plex/IBMPlexMono-Regular-Latin3.woff2 rename to www/fonts/ibm_plex/IBMPlexMono-Regular-Latin3.woff2 diff --git a/docs/fonts/ibm_plex/IBMPlexMono-Regular-Pi.woff2 b/www/fonts/ibm_plex/IBMPlexMono-Regular-Pi.woff2 similarity index 100% rename from docs/fonts/ibm_plex/IBMPlexMono-Regular-Pi.woff2 rename to www/fonts/ibm_plex/IBMPlexMono-Regular-Pi.woff2 diff --git a/docs/fonts/ibm_plex/IBMPlexMono-Regular.css b/www/fonts/ibm_plex/IBMPlexMono-Regular.css similarity index 100% rename from docs/fonts/ibm_plex/IBMPlexMono-Regular.css rename to www/fonts/ibm_plex/IBMPlexMono-Regular.css diff --git a/docs/fonts/ibm_plex/LICENSE.txt b/www/fonts/ibm_plex/LICENSE.txt similarity index 100% rename from docs/fonts/ibm_plex/LICENSE.txt rename to www/fonts/ibm_plex/LICENSE.txt diff --git a/docs/fonts/inter/Inter-Black.woff b/www/fonts/inter/Inter-Black.woff similarity index 100% rename from docs/fonts/inter/Inter-Black.woff rename to www/fonts/inter/Inter-Black.woff diff --git a/docs/fonts/inter/Inter-Black.woff2 b/www/fonts/inter/Inter-Black.woff2 similarity index 100% rename from docs/fonts/inter/Inter-Black.woff2 rename to www/fonts/inter/Inter-Black.woff2 diff --git a/docs/fonts/inter/Inter-BlackItalic.woff b/www/fonts/inter/Inter-BlackItalic.woff similarity index 100% rename from docs/fonts/inter/Inter-BlackItalic.woff rename to www/fonts/inter/Inter-BlackItalic.woff diff --git a/docs/fonts/inter/Inter-BlackItalic.woff2 b/www/fonts/inter/Inter-BlackItalic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-BlackItalic.woff2 rename to www/fonts/inter/Inter-BlackItalic.woff2 diff --git a/docs/fonts/inter/Inter-Bold.woff b/www/fonts/inter/Inter-Bold.woff similarity index 100% rename from docs/fonts/inter/Inter-Bold.woff rename to www/fonts/inter/Inter-Bold.woff diff --git a/docs/fonts/inter/Inter-Bold.woff2 b/www/fonts/inter/Inter-Bold.woff2 similarity index 100% rename from docs/fonts/inter/Inter-Bold.woff2 rename to www/fonts/inter/Inter-Bold.woff2 diff --git a/docs/fonts/inter/Inter-BoldItalic.woff b/www/fonts/inter/Inter-BoldItalic.woff similarity index 100% rename from docs/fonts/inter/Inter-BoldItalic.woff rename to www/fonts/inter/Inter-BoldItalic.woff diff --git a/docs/fonts/inter/Inter-BoldItalic.woff2 b/www/fonts/inter/Inter-BoldItalic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-BoldItalic.woff2 rename to www/fonts/inter/Inter-BoldItalic.woff2 diff --git a/docs/fonts/inter/Inter-ExtraBold.woff b/www/fonts/inter/Inter-ExtraBold.woff similarity index 100% rename from docs/fonts/inter/Inter-ExtraBold.woff rename to www/fonts/inter/Inter-ExtraBold.woff diff --git a/docs/fonts/inter/Inter-ExtraBold.woff2 b/www/fonts/inter/Inter-ExtraBold.woff2 similarity index 100% rename from docs/fonts/inter/Inter-ExtraBold.woff2 rename to www/fonts/inter/Inter-ExtraBold.woff2 diff --git a/docs/fonts/inter/Inter-ExtraBoldItalic.woff b/www/fonts/inter/Inter-ExtraBoldItalic.woff similarity index 100% rename from docs/fonts/inter/Inter-ExtraBoldItalic.woff rename to www/fonts/inter/Inter-ExtraBoldItalic.woff diff --git a/docs/fonts/inter/Inter-ExtraBoldItalic.woff2 b/www/fonts/inter/Inter-ExtraBoldItalic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-ExtraBoldItalic.woff2 rename to www/fonts/inter/Inter-ExtraBoldItalic.woff2 diff --git a/docs/fonts/inter/Inter-ExtraLight.woff b/www/fonts/inter/Inter-ExtraLight.woff similarity index 100% rename from docs/fonts/inter/Inter-ExtraLight.woff rename to www/fonts/inter/Inter-ExtraLight.woff diff --git a/docs/fonts/inter/Inter-ExtraLight.woff2 b/www/fonts/inter/Inter-ExtraLight.woff2 similarity index 100% rename from docs/fonts/inter/Inter-ExtraLight.woff2 rename to www/fonts/inter/Inter-ExtraLight.woff2 diff --git a/docs/fonts/inter/Inter-ExtraLightItalic.woff b/www/fonts/inter/Inter-ExtraLightItalic.woff similarity index 100% rename from docs/fonts/inter/Inter-ExtraLightItalic.woff rename to www/fonts/inter/Inter-ExtraLightItalic.woff diff --git a/docs/fonts/inter/Inter-ExtraLightItalic.woff2 b/www/fonts/inter/Inter-ExtraLightItalic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-ExtraLightItalic.woff2 rename to www/fonts/inter/Inter-ExtraLightItalic.woff2 diff --git a/docs/fonts/inter/Inter-Italic.woff b/www/fonts/inter/Inter-Italic.woff similarity index 100% rename from docs/fonts/inter/Inter-Italic.woff rename to www/fonts/inter/Inter-Italic.woff diff --git a/docs/fonts/inter/Inter-Italic.woff2 b/www/fonts/inter/Inter-Italic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-Italic.woff2 rename to www/fonts/inter/Inter-Italic.woff2 diff --git a/docs/fonts/inter/Inter-Light.woff b/www/fonts/inter/Inter-Light.woff similarity index 100% rename from docs/fonts/inter/Inter-Light.woff rename to www/fonts/inter/Inter-Light.woff diff --git a/docs/fonts/inter/Inter-Light.woff2 b/www/fonts/inter/Inter-Light.woff2 similarity index 100% rename from docs/fonts/inter/Inter-Light.woff2 rename to www/fonts/inter/Inter-Light.woff2 diff --git a/docs/fonts/inter/Inter-LightItalic.woff b/www/fonts/inter/Inter-LightItalic.woff similarity index 100% rename from docs/fonts/inter/Inter-LightItalic.woff rename to www/fonts/inter/Inter-LightItalic.woff diff --git a/docs/fonts/inter/Inter-LightItalic.woff2 b/www/fonts/inter/Inter-LightItalic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-LightItalic.woff2 rename to www/fonts/inter/Inter-LightItalic.woff2 diff --git a/docs/fonts/inter/Inter-Medium.woff b/www/fonts/inter/Inter-Medium.woff similarity index 100% rename from docs/fonts/inter/Inter-Medium.woff rename to www/fonts/inter/Inter-Medium.woff diff --git a/docs/fonts/inter/Inter-Medium.woff2 b/www/fonts/inter/Inter-Medium.woff2 similarity index 100% rename from docs/fonts/inter/Inter-Medium.woff2 rename to www/fonts/inter/Inter-Medium.woff2 diff --git a/docs/fonts/inter/Inter-MediumItalic.woff b/www/fonts/inter/Inter-MediumItalic.woff similarity index 100% rename from docs/fonts/inter/Inter-MediumItalic.woff rename to www/fonts/inter/Inter-MediumItalic.woff diff --git a/docs/fonts/inter/Inter-MediumItalic.woff2 b/www/fonts/inter/Inter-MediumItalic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-MediumItalic.woff2 rename to www/fonts/inter/Inter-MediumItalic.woff2 diff --git a/docs/fonts/inter/Inter-Regular.woff b/www/fonts/inter/Inter-Regular.woff similarity index 100% rename from docs/fonts/inter/Inter-Regular.woff rename to www/fonts/inter/Inter-Regular.woff diff --git a/docs/fonts/inter/Inter-Regular.woff2 b/www/fonts/inter/Inter-Regular.woff2 similarity index 100% rename from docs/fonts/inter/Inter-Regular.woff2 rename to www/fonts/inter/Inter-Regular.woff2 diff --git a/docs/fonts/inter/Inter-SemiBold.woff b/www/fonts/inter/Inter-SemiBold.woff similarity index 100% rename from docs/fonts/inter/Inter-SemiBold.woff rename to www/fonts/inter/Inter-SemiBold.woff diff --git a/docs/fonts/inter/Inter-SemiBold.woff2 b/www/fonts/inter/Inter-SemiBold.woff2 similarity index 100% rename from docs/fonts/inter/Inter-SemiBold.woff2 rename to www/fonts/inter/Inter-SemiBold.woff2 diff --git a/docs/fonts/inter/Inter-SemiBoldItalic.woff b/www/fonts/inter/Inter-SemiBoldItalic.woff similarity index 100% rename from docs/fonts/inter/Inter-SemiBoldItalic.woff rename to www/fonts/inter/Inter-SemiBoldItalic.woff diff --git a/docs/fonts/inter/Inter-SemiBoldItalic.woff2 b/www/fonts/inter/Inter-SemiBoldItalic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-SemiBoldItalic.woff2 rename to www/fonts/inter/Inter-SemiBoldItalic.woff2 diff --git a/docs/fonts/inter/Inter-Thin.woff b/www/fonts/inter/Inter-Thin.woff similarity index 100% rename from docs/fonts/inter/Inter-Thin.woff rename to www/fonts/inter/Inter-Thin.woff diff --git a/docs/fonts/inter/Inter-Thin.woff2 b/www/fonts/inter/Inter-Thin.woff2 similarity index 100% rename from docs/fonts/inter/Inter-Thin.woff2 rename to www/fonts/inter/Inter-Thin.woff2 diff --git a/docs/fonts/inter/Inter-ThinItalic.woff b/www/fonts/inter/Inter-ThinItalic.woff similarity index 100% rename from docs/fonts/inter/Inter-ThinItalic.woff rename to www/fonts/inter/Inter-ThinItalic.woff diff --git a/docs/fonts/inter/Inter-ThinItalic.woff2 b/www/fonts/inter/Inter-ThinItalic.woff2 similarity index 100% rename from docs/fonts/inter/Inter-ThinItalic.woff2 rename to www/fonts/inter/Inter-ThinItalic.woff2 diff --git a/docs/fonts/inter/Inter-italic.var.woff2 b/www/fonts/inter/Inter-italic.var.woff2 similarity index 100% rename from docs/fonts/inter/Inter-italic.var.woff2 rename to www/fonts/inter/Inter-italic.var.woff2 diff --git a/docs/fonts/inter/Inter-roman.var.woff2 b/www/fonts/inter/Inter-roman.var.woff2 similarity index 100% rename from docs/fonts/inter/Inter-roman.var.woff2 rename to www/fonts/inter/Inter-roman.var.woff2 diff --git a/docs/fonts/inter/Inter.var.woff2 b/www/fonts/inter/Inter.var.woff2 similarity index 100% rename from docs/fonts/inter/Inter.var.woff2 rename to www/fonts/inter/Inter.var.woff2 diff --git a/docs/fonts/inter/LICENSE.txt b/www/fonts/inter/LICENSE.txt similarity index 100% rename from docs/fonts/inter/LICENSE.txt rename to www/fonts/inter/LICENSE.txt diff --git a/docs/fonts/inter/inter.css b/www/fonts/inter/inter.css similarity index 100% rename from docs/fonts/inter/inter.css rename to www/fonts/inter/inter.css diff --git a/docs/fonts/prodigy/ProdigySans-Medium.ttf b/www/fonts/prodigy/ProdigySans-Medium.ttf similarity index 100% rename from docs/fonts/prodigy/ProdigySans-Medium.ttf rename to www/fonts/prodigy/ProdigySans-Medium.ttf diff --git a/docs/fonts/prodigy/ProdigySans-Medium.woff b/www/fonts/prodigy/ProdigySans-Medium.woff similarity index 100% rename from docs/fonts/prodigy/ProdigySans-Medium.woff rename to www/fonts/prodigy/ProdigySans-Medium.woff diff --git a/docs/fonts/prodigy/ProdigySans-Medium.woff2 b/www/fonts/prodigy/ProdigySans-Medium.woff2 similarity index 100% rename from docs/fonts/prodigy/ProdigySans-Medium.woff2 rename to www/fonts/prodigy/ProdigySans-Medium.woff2 diff --git a/docs/fonts/prodigy/ProdigySans-Regular.ttf b/www/fonts/prodigy/ProdigySans-Regular.ttf similarity index 100% rename from docs/fonts/prodigy/ProdigySans-Regular.ttf rename to www/fonts/prodigy/ProdigySans-Regular.ttf diff --git a/docs/fonts/prodigy/ProdigySans-Regular.woff b/www/fonts/prodigy/ProdigySans-Regular.woff similarity index 100% rename from docs/fonts/prodigy/ProdigySans-Regular.woff rename to www/fonts/prodigy/ProdigySans-Regular.woff diff --git a/docs/fonts/prodigy/ProdigySans-Regular.woff2 b/www/fonts/prodigy/ProdigySans-Regular.woff2 similarity index 100% rename from docs/fonts/prodigy/ProdigySans-Regular.woff2 rename to www/fonts/prodigy/ProdigySans-Regular.woff2 diff --git a/docs/fonts/prodigy/ProdigySans-SemiBold.ttf b/www/fonts/prodigy/ProdigySans-SemiBold.ttf similarity index 100% rename from docs/fonts/prodigy/ProdigySans-SemiBold.ttf rename to www/fonts/prodigy/ProdigySans-SemiBold.ttf diff --git a/docs/fonts/prodigy/ProdigySans-SemiBold.woff b/www/fonts/prodigy/ProdigySans-SemiBold.woff similarity index 100% rename from docs/fonts/prodigy/ProdigySans-SemiBold.woff rename to www/fonts/prodigy/ProdigySans-SemiBold.woff diff --git a/docs/fonts/prodigy/ProdigySans-SemiBold.woff2 b/www/fonts/prodigy/ProdigySans-SemiBold.woff2 similarity index 100% rename from docs/fonts/prodigy/ProdigySans-SemiBold.woff2 rename to www/fonts/prodigy/ProdigySans-SemiBold.woff2 diff --git a/docs/fonts/prodigy/ProdigySans.css b/www/fonts/prodigy/ProdigySans.css similarity index 100% rename from docs/fonts/prodigy/ProdigySans.css rename to www/fonts/prodigy/ProdigySans.css diff --git a/docs/how-to/get-started.md b/www/how-to/get-started.md similarity index 100% rename from docs/how-to/get-started.md rename to www/how-to/get-started.md diff --git a/docs/how-to/how-to-infra.md b/www/how-to/how-to-infra.md similarity index 100% rename from docs/how-to/how-to-infra.md rename to www/how-to/how-to-infra.md diff --git a/docs/how-to/how-to-orgs.md b/www/how-to/how-to-orgs.md similarity index 100% rename from docs/how-to/how-to-orgs.md rename to www/how-to/how-to-orgs.md diff --git a/docs/how-to/index.md b/www/how-to/index.md similarity index 100% rename from docs/how-to/index.md rename to www/how-to/index.md diff --git a/docs/images/Makefile b/www/images/Makefile similarity index 100% rename from docs/images/Makefile rename to www/images/Makefile diff --git a/docs/images/SLSA-Badge-full-level1.svg b/www/images/SLSA-Badge-full-level1.svg similarity index 100% rename from docs/images/SLSA-Badge-full-level1.svg rename to www/images/SLSA-Badge-full-level1.svg diff --git a/docs/images/SLSA-Badge-full-level2.svg b/www/images/SLSA-Badge-full-level2.svg similarity index 100% rename from docs/images/SLSA-Badge-full-level2.svg rename to www/images/SLSA-Badge-full-level2.svg diff --git a/docs/images/SLSA-Badge-full-level3.svg b/www/images/SLSA-Badge-full-level3.svg similarity index 100% rename from docs/images/SLSA-Badge-full-level3.svg rename to www/images/SLSA-Badge-full-level3.svg diff --git a/docs/images/SLSA-Badge-full-level4.svg b/www/images/SLSA-Badge-full-level4.svg similarity index 100% rename from docs/images/SLSA-Badge-full-level4.svg rename to www/images/SLSA-Badge-full-level4.svg diff --git a/docs/images/SLSA-Badge-level1.svg b/www/images/SLSA-Badge-level1.svg similarity index 100% rename from docs/images/SLSA-Badge-level1.svg rename to www/images/SLSA-Badge-level1.svg diff --git a/docs/images/SLSA-Badge-level2.svg b/www/images/SLSA-Badge-level2.svg similarity index 100% rename from docs/images/SLSA-Badge-level2.svg rename to www/images/SLSA-Badge-level2.svg diff --git a/docs/images/SLSA-Badge-level3.svg b/www/images/SLSA-Badge-level3.svg similarity index 100% rename from docs/images/SLSA-Badge-level3.svg rename to www/images/SLSA-Badge-level3.svg diff --git a/docs/images/SLSA-Badge-level4.svg b/www/images/SLSA-Badge-level4.svg similarity index 100% rename from docs/images/SLSA-Badge-level4.svg rename to www/images/SLSA-Badge-level4.svg diff --git a/docs/images/SLSA-SBOM.svg b/www/images/SLSA-SBOM.svg similarity index 100% rename from docs/images/SLSA-SBOM.svg rename to www/images/SLSA-SBOM.svg diff --git a/docs/images/SupplyChainDiagram.svg b/www/images/SupplyChainDiagram.svg similarity index 100% rename from docs/images/SupplyChainDiagram.svg rename to www/images/SupplyChainDiagram.svg diff --git a/docs/images/attestation_example_english.svg b/www/images/attestation_example_english.svg similarity index 100% rename from docs/images/attestation_example_english.svg rename to www/images/attestation_example_english.svg diff --git a/docs/images/attestation_layers.svg b/www/images/attestation_layers.svg similarity index 100% rename from docs/images/attestation_layers.svg rename to www/images/attestation_layers.svg diff --git a/docs/images/badge-exploded.svg b/www/images/badge-exploded.svg similarity index 100% rename from docs/images/badge-exploded.svg rename to www/images/badge-exploded.svg diff --git a/docs/images/build-model.svg b/www/images/build-model.svg similarity index 100% rename from docs/images/build-model.svg rename to www/images/build-model.svg diff --git a/docs/images/community-bg.png b/www/images/community-bg.png similarity index 100% rename from docs/images/community-bg.png rename to www/images/community-bg.png diff --git a/docs/images/datadog.png b/www/images/datadog.png similarity index 100% rename from docs/images/datadog.png rename to www/images/datadog.png diff --git a/docs/images/gh-badge-flat-square-level1.svg b/www/images/gh-badge-flat-square-level1.svg similarity index 100% rename from docs/images/gh-badge-flat-square-level1.svg rename to www/images/gh-badge-flat-square-level1.svg diff --git a/docs/images/gh-badge-flat-square-level2.svg b/www/images/gh-badge-flat-square-level2.svg similarity index 100% rename from docs/images/gh-badge-flat-square-level2.svg rename to www/images/gh-badge-flat-square-level2.svg diff --git a/docs/images/gh-badge-flat-square-level3.svg b/www/images/gh-badge-flat-square-level3.svg similarity index 100% rename from docs/images/gh-badge-flat-square-level3.svg rename to www/images/gh-badge-flat-square-level3.svg diff --git a/docs/images/gh-badge-flat-square-level4.svg b/www/images/gh-badge-flat-square-level4.svg similarity index 100% rename from docs/images/gh-badge-flat-square-level4.svg rename to www/images/gh-badge-flat-square-level4.svg diff --git a/docs/images/gh-badge-level1.svg b/www/images/gh-badge-level1.svg similarity index 100% rename from docs/images/gh-badge-level1.svg rename to www/images/gh-badge-level1.svg diff --git a/docs/images/gh-badge-level2.svg b/www/images/gh-badge-level2.svg similarity index 100% rename from docs/images/gh-badge-level2.svg rename to www/images/gh-badge-level2.svg diff --git a/docs/images/gh-badge-level3.svg b/www/images/gh-badge-level3.svg similarity index 100% rename from docs/images/gh-badge-level3.svg rename to www/images/gh-badge-level3.svg diff --git a/docs/images/gh-badge-level4.svg b/www/images/gh-badge-level4.svg similarity index 100% rename from docs/images/gh-badge-level4.svg rename to www/images/gh-badge-level4.svg diff --git a/docs/images/hero-bg.png b/www/images/hero-bg.png similarity index 100% rename from docs/images/hero-bg.png rename to www/images/hero-bg.png diff --git a/docs/images/hero-image.png b/www/images/hero-image.png similarity index 100% rename from docs/images/hero-image.png rename to www/images/hero-image.png diff --git a/docs/images/icons/android-chrome-192x192.png b/www/images/icons/android-chrome-192x192.png similarity index 100% rename from docs/images/icons/android-chrome-192x192.png rename to www/images/icons/android-chrome-192x192.png diff --git a/docs/images/icons/android-chrome-512x512.png b/www/images/icons/android-chrome-512x512.png similarity index 100% rename from docs/images/icons/android-chrome-512x512.png rename to www/images/icons/android-chrome-512x512.png diff --git a/docs/images/icons/apple-touch-icon.png b/www/images/icons/apple-touch-icon.png similarity index 100% rename from docs/images/icons/apple-touch-icon.png rename to www/images/icons/apple-touch-icon.png diff --git a/docs/images/icons/down-arrow.svg b/www/images/icons/down-arrow.svg similarity index 100% rename from docs/images/icons/down-arrow.svg rename to www/images/icons/down-arrow.svg diff --git a/docs/images/icons/favicon-16x16.png b/www/images/icons/favicon-16x16.png similarity index 100% rename from docs/images/icons/favicon-16x16.png rename to www/images/icons/favicon-16x16.png diff --git a/docs/images/icons/favicon-32x32.png b/www/images/icons/favicon-32x32.png similarity index 100% rename from docs/images/icons/favicon-32x32.png rename to www/images/icons/favicon-32x32.png diff --git a/docs/images/icons/favicon.ico b/www/images/icons/favicon.ico similarity index 100% rename from docs/images/icons/favicon.ico rename to www/images/icons/favicon.ico diff --git a/docs/images/icons/mstile-150x150.png b/www/images/icons/mstile-150x150.png similarity index 100% rename from docs/images/icons/mstile-150x150.png rename to www/images/icons/mstile-150x150.png diff --git a/docs/images/icons/safari-pinned-tab.svg b/www/images/icons/safari-pinned-tab.svg similarity index 100% rename from docs/images/icons/safari-pinned-tab.svg rename to www/images/icons/safari-pinned-tab.svg diff --git a/docs/images/intel-logo.png b/www/images/intel-logo.png similarity index 100% rename from docs/images/intel-logo.png rename to www/images/intel-logo.png diff --git a/docs/images/levelBadge1.svg b/www/images/levelBadge1.svg similarity index 100% rename from docs/images/levelBadge1.svg rename to www/images/levelBadge1.svg diff --git a/docs/images/levelBadge2.svg b/www/images/levelBadge2.svg similarity index 100% rename from docs/images/levelBadge2.svg rename to www/images/levelBadge2.svg diff --git a/docs/images/levelBadge3.svg b/www/images/levelBadge3.svg similarity index 100% rename from docs/images/levelBadge3.svg rename to www/images/levelBadge3.svg diff --git a/docs/images/levelBadge4.svg b/www/images/levelBadge4.svg similarity index 100% rename from docs/images/levelBadge4.svg rename to www/images/levelBadge4.svg diff --git a/docs/images/logo-green.svg b/www/images/logo-green.svg similarity index 100% rename from docs/images/logo-green.svg rename to www/images/logo-green.svg diff --git a/docs/images/logo-mono.svg b/www/images/logo-mono.svg similarity index 100% rename from docs/images/logo-mono.svg rename to www/images/logo-mono.svg diff --git a/docs/images/logo.svg b/www/images/logo.svg similarity index 100% rename from docs/images/logo.svg rename to www/images/logo.svg diff --git a/docs/images/logos/chainguard.png b/www/images/logos/chainguard.png similarity index 100% rename from docs/images/logos/chainguard.png rename to www/images/logos/chainguard.png diff --git a/docs/images/logos/citi.png b/www/images/logos/citi.png similarity index 100% rename from docs/images/logos/citi.png rename to www/images/logos/citi.png diff --git a/docs/images/logos/cncf.png b/www/images/logos/cncf.png similarity index 100% rename from docs/images/logos/cncf.png rename to www/images/logos/cncf.png diff --git a/docs/images/logos/datadog.png b/www/images/logos/datadog.png similarity index 100% rename from docs/images/logos/datadog.png rename to www/images/logos/datadog.png diff --git a/docs/images/logos/google.png b/www/images/logos/google.png similarity index 100% rename from docs/images/logos/google.png rename to www/images/logos/google.png diff --git a/docs/images/logos/intel.png b/www/images/logos/intel.png similarity index 100% rename from docs/images/logos/intel.png rename to www/images/logos/intel.png diff --git a/docs/images/logos/kusari.png b/www/images/logos/kusari.png similarity index 100% rename from docs/images/logos/kusari.png rename to www/images/logos/kusari.png diff --git a/docs/images/logos/linux-foundation.png b/www/images/logos/linux-foundation.png similarity index 100% rename from docs/images/logos/linux-foundation.png rename to www/images/logos/linux-foundation.png diff --git a/docs/images/logos/verizon.png b/www/images/logos/verizon.png similarity index 100% rename from docs/images/logos/verizon.png rename to www/images/logos/verizon.png diff --git a/docs/images/openssf.svg b/www/images/openssf.svg similarity index 100% rename from docs/images/openssf.svg rename to www/images/openssf.svg diff --git a/docs/images/slsa-0.svg b/www/images/slsa-0.svg similarity index 100% rename from docs/images/slsa-0.svg rename to www/images/slsa-0.svg diff --git a/docs/images/slsa-1.svg b/www/images/slsa-1.svg similarity index 100% rename from docs/images/slsa-1.svg rename to www/images/slsa-1.svg diff --git a/docs/images/slsa-2.svg b/www/images/slsa-2.svg similarity index 100% rename from docs/images/slsa-2.svg rename to www/images/slsa-2.svg diff --git a/docs/images/slsa-4.svg b/www/images/slsa-4.svg similarity index 100% rename from docs/images/slsa-4.svg rename to www/images/slsa-4.svg diff --git a/docs/images/slsa-dancing-goose-logo.svg b/www/images/slsa-dancing-goose-logo.svg similarity index 100% rename from docs/images/slsa-dancing-goose-logo.svg rename to www/images/slsa-dancing-goose-logo.svg diff --git a/docs/images/slsa-full-graph.svg b/www/images/slsa-full-graph.svg similarity index 100% rename from docs/images/slsa-full-graph.svg rename to www/images/slsa-full-graph.svg diff --git a/docs/images/supply-chain-model.svg b/www/images/supply-chain-model.svg similarity index 100% rename from docs/images/supply-chain-model.svg rename to www/images/supply-chain-model.svg diff --git a/docs/images/supply-chain-threats-build-verification.svg b/www/images/supply-chain-threats-build-verification.svg similarity index 100% rename from docs/images/supply-chain-threats-build-verification.svg rename to www/images/supply-chain-threats-build-verification.svg diff --git a/docs/images/supply-chain-threats-no-labels.svg b/www/images/supply-chain-threats-no-labels.svg similarity index 100% rename from docs/images/supply-chain-threats-no-labels.svg rename to www/images/supply-chain-threats-no-labels.svg diff --git a/docs/images/supply-chain-threats.svg b/www/images/supply-chain-threats.svg similarity index 100% rename from docs/images/supply-chain-threats.svg rename to www/images/supply-chain-threats.svg diff --git a/docs/images/v1.0-rc2/supply-chain-threats-build-verification.svg b/www/images/v1.0-rc2/supply-chain-threats-build-verification.svg similarity index 100% rename from docs/images/v1.0-rc2/supply-chain-threats-build-verification.svg rename to www/images/v1.0-rc2/supply-chain-threats-build-verification.svg diff --git a/docs/images/v1.0-rc2/supply-chain-threats.svg b/www/images/v1.0-rc2/supply-chain-threats.svg similarity index 100% rename from docs/images/v1.0-rc2/supply-chain-threats.svg rename to www/images/v1.0-rc2/supply-chain-threats.svg diff --git a/docs/images/v1.mp4 b/www/images/v1.mp4 similarity index 100% rename from docs/images/v1.mp4 rename to www/images/v1.mp4 diff --git a/docs/index.md b/www/index.md similarity index 100% rename from docs/index.md rename to www/index.md diff --git a/docs/notes/index.md b/www/notes/index.md similarity index 100% rename from docs/notes/index.md rename to www/notes/index.md diff --git a/docs/spec-stages.md b/www/spec-stages.md similarity index 100% rename from docs/spec-stages.md rename to www/spec-stages.md diff --git a/docs/vendor/alpinejs-3.10.2/cdn.min.js b/www/vendor/alpinejs-3.10.2/cdn.min.js similarity index 100% rename from docs/vendor/alpinejs-3.10.2/cdn.min.js rename to www/vendor/alpinejs-3.10.2/cdn.min.js diff --git a/docs/vendor/swiper-6.8.4/swiper-bundle.min.css b/www/vendor/swiper-6.8.4/swiper-bundle.min.css similarity index 100% rename from docs/vendor/swiper-6.8.4/swiper-bundle.min.css rename to www/vendor/swiper-6.8.4/swiper-bundle.min.css diff --git a/docs/vendor/swiper-6.8.4/swiper-bundle.min.js b/www/vendor/swiper-6.8.4/swiper-bundle.min.js similarity index 100% rename from docs/vendor/swiper-6.8.4/swiper-bundle.min.js rename to www/vendor/swiper-6.8.4/swiper-bundle.min.js diff --git a/docs/vendor/tailwindcss-2.2.19/tailwind.min.css b/www/vendor/tailwindcss-2.2.19/tailwind.min.css similarity index 100% rename from docs/vendor/tailwindcss-2.2.19/tailwind.min.css rename to www/vendor/tailwindcss-2.2.19/tailwind.min.css