From cb7c3bbace69dd88461587787d66dfaef8882e36 Mon Sep 17 00:00:00 2001 From: Paul Savoie Date: Fri, 22 Aug 2025 16:30:21 +0200 Subject: [PATCH 1/8] adds slsa attestations page --- docs/_data/menus/documentation.yml | 3 + docs/_sass/resources.scss | 13 ++ .../index.md} | 0 docs/origin-verification/slsa-attestations.md | 138 ++++++++++++++++++ 4 files changed, 154 insertions(+) rename docs/{origin-verification.md => origin-verification/index.md} (100%) create mode 100644 docs/origin-verification/slsa-attestations.md diff --git a/docs/_data/menus/documentation.yml b/docs/_data/menus/documentation.yml index cee5d16..44a7f88 100644 --- a/docs/_data/menus/documentation.yml +++ b/docs/_data/menus/documentation.yml @@ -59,6 +59,9 @@ - text: Origin Verification path: origin-verification + items: + - text: SLSA Attestations + path: slsa-attestations - separator: true diff --git a/docs/_sass/resources.scss b/docs/_sass/resources.scss index d0e7de0..04944c3 100644 --- a/docs/_sass/resources.scss +++ b/docs/_sass/resources.scss @@ -192,6 +192,19 @@ main > section.resources-section { } } + blockquote.quote { + background: $light-grey-background-color; + border-left: 10px solid $blockquote-line-color; + margin: 1.5em 10px; + padding: 0.5em 10px; + quotes: "\201C""\201D""\2018""\2019"; + font-style: italic; + + & > p { + margin: 0px; + } + } + /** HIGHLIGHTS **/ blockquote.panel { border: 1px solid $grey-border-color; diff --git a/docs/origin-verification.md b/docs/origin-verification/index.md similarity index 100% rename from docs/origin-verification.md rename to docs/origin-verification/index.md diff --git a/docs/origin-verification/slsa-attestations.md b/docs/origin-verification/slsa-attestations.md new file mode 100644 index 0000000..e7dc88f --- /dev/null +++ b/docs/origin-verification/slsa-attestations.md @@ -0,0 +1,138 @@ +--- +header: SLSA Build Levels +layout: resources +toc: true +show_toc: 3 +description: Describes the SLSA Build Levels +--- + +# SLSA Attestations by SignPath + +This page contains the definitions for the build types and builder IDs used within SLSA provenance files created by SignPath. + +## Build Types + +This section describes the build types for SLSA attestations that are supported by SignPath. They are expressed by the `buildDefinition.buildType` field within the provenance, containing the value `https://signpath.io/slsa/buildtypes/$build-system/v1`, where `$build-system` can have one of the following values: + +* `azure-devops`: A build from the [Azure DevOps](/documentation/trusted-build-systems/azure-devops) build system hosted by Microsoft in the cloud (at dev.azure.com). +* `github`: A build from the [GitHub Actions](/documentation/trusted-build-systems/github) build system hosted by Microsoft in the cloud (at GitHub.com). + +### Common Parameters + +All build types contain the following `buildDefinition` section within the `externalParameters`: + +| Field | Description | +| ------- | ------------------------------- | +| `path` | The path to the build definition file within the commit. | +| `branch` | If available, the source code branch containing the build definition at the time of the build. | +| `commitId` | The source code version of the build definition that was used. | +| `repository` | The source code repository identifier where the build definition is located. | + +#### Example + +``` +"externalParameters": +{ + "buildDefinition": + { + "path": ".github/workflows/build.yml", + "branch": "refs/heads/main", + "commitId": "d17077cc10b045ead742c397a4caebe1530efaf3", + "repository": "https://github.com/my-org/my-repo" + } +} +``` + + +## Builder IDs + +This section describes the guarantees made by SignPath for each SLSA Level. They are expressed by the following `runDetails.builder.id` values within the provenance: + +| Builder ID | Details | +| ---------- | ------------------------------------------- | +| `https://signpath.io/slsa/builder/generic/level1` | SLSA Level 1, independent of the build system. | +| `https://signpath.io/slsa/builder/generic/level2` | SLSA Level 2, independent of the build system. | +| `https://signpath.io/slsa/builder/$build-system/level3` | SLSA Level 3, where `$build-system` specifies the associated build system. | + +The following `$build-system` values are currently supported: +* `azure-devops`: A build from the [Azure DevOps](/documentation/trusted-build-systems/azure-devops) build system hosted by Microsoft in the cloud (at dev.azure.com). +* `github`: A build from the [GitHub Actions](/documentation/trusted-build-systems/github) build system hosted by Microsoft in the cloud (at GitHub.com). + + +### Provenance generation requirements + +For a detailed list, see the [original definition by SLSA](https://slsa.dev/spec/v1.1/requirements). + +#### SLSA Level 1: A provenance must exist + +{:.quote} +> The build process MUST generate provenance that unambiguously identifies the output package by cryptographic digest and describes how that package was produced. + +Guarantee: SignPath created a complete provenance. + +#### SLSA Level 2: The provenance is authentic + +{:.quote} +> Authenticity: Consumers MUST be able to validate the authenticity of the provenance attestation in order to ensure integrity and define trust. + +Guarantee: The provenance was digitally signed. + +{:.quote} +> Accuracy: The provenance MUST be generated by the control plane and not by a tenant of the build platform. + +Guaranteee: SignPath created the provenance. All contents are obtained from a trusted build system on the control plane and cannot be tempered with. + +#### SLSA Level 3: The provenance is unforgeable + +{:.quote} +> Accuracy: Provenance MUST be strongly resistant to forgery by tenants. + +Guarantee: The signing key is stored on SignPath and is not accessible by the environment running the user-defined build steps. + +### Isolation strength requirements + +#### SLSA Level 2: Hosted builds + +{:.quote} +> All build steps ran using a hosted build platform on shared or dedicated infrastructure, not on an individual’s workstation. + +Guarantee: All builds were reported through a [Trusted Build System](/documentation/trusted-build-systems). If the provenance is signed by SignPath, SignPath will guarantee that the build system is hosted in the cloud (e.g. GitHub.com or GitLab.com). Otherwise, the signer of the provenance confirms that they connected a self-managed build system with SignPath. + +#### SLSA Level 3: Isolated builds + +{:.quote} +> 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. + +Guarantee: If the provenance is signed by SignPath, the build was executed on a cloud-hosted trusted build system which ensures access restrictions to build platform secrets. Otherwise, the signer of the provenance confirms that they configured the self-managed build system accordingly. + +{:.quote} +> 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. + +| Build System | Guarantee | +| -- | ------------------------------ | +| Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which offer isolation (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/misc)) +| GitHub Actions | The build was executed on a GitHub-hosted runner, each job is run in a fresh instance of the runner image (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)) + +{:.quote} +> 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. + +| Build System | Guarantee | +| -- | ------------------------------ | +| Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which provide a clean virtual machien for each build run (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/misc)) +| GitHub Actions | The build was executed on a GitHub-hosted runner, each job is run in a fresh instance of the runner image (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)) + +{:.quote} +> 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. + +| Build System | Guarantee | +| -- | ------------------------------ | +| Azure DevOps | Cache usage has to be explicitly defined in the pipeline definition and cannot be shared across pipelines or branches (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/release/caching?view=azure-devops&tabs=bundler#cache-isolation-and-security)) +| GitHub Actions | Cache usage has to be explicitly defined in the workflow definition (see [the official definition](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching)) + +{:.quote} +> The build platform MUST NOT open services that allow for remote influence unless all such interactions are captured as externalParameters in the provenance + +| Build System | Guarantee | +| -- | ------------------------------ | +| Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which do not provide the ability to remotely connect (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/hosted)). +| GitHub Actions | The build was executed on a GitHub-hosted runner which does not provide the ability to remotely connect, unless explicitly specified in the build definition (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network)) From 21993b415751b1823f3bb54b4049990af63a867e Mon Sep 17 00:00:00 2001 From: Paul Savoie Date: Wed, 10 Sep 2025 16:17:39 +0200 Subject: [PATCH 2/8] updates new internal and external parameters --- docs/origin-verification/slsa-attestations.md | 65 ++++++++++++------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/docs/origin-verification/slsa-attestations.md b/docs/origin-verification/slsa-attestations.md index e7dc88f..fcb7d5e 100644 --- a/docs/origin-verification/slsa-attestations.md +++ b/docs/origin-verification/slsa-attestations.md @@ -19,14 +19,21 @@ This section describes the build types for SLSA attestations that are supported ### Common Parameters -All build types contain the following `buildDefinition` section within the `externalParameters`: +All build types contain the following `externalParameters`: + +| Field | Description +| ---------------------------------| ------------------------------- +| `buildDefinition.git.path` | The path to the build definition file within the commit. +| `buildDefinition.git.branch` | If available, the source code branch containing the build definition at the time of the build. +| `buildDefinition.git.commitId` | The source code version of the build definition that was used. +| `buildDefinition.git.repository` | The source code repository identifier where the build definition is located. + +All build types contain the following `internalParameters`: + +| Field | Description +|----------------------|----------------------------------- +| `signingRequest.url` | The URL of the signing request that processed the artifact -| Field | Description | -| ------- | ------------------------------- | -| `path` | The path to the build definition file within the commit. | -| `branch` | If available, the source code branch containing the build definition at the time of the build. | -| `commitId` | The source code version of the build definition that was used. | -| `repository` | The source code repository identifier where the build definition is located. | #### Example @@ -35,10 +42,20 @@ All build types contain the following `buildDefinition` section within the `exte { "buildDefinition": { - "path": ".github/workflows/build.yml", - "branch": "refs/heads/main", - "commitId": "d17077cc10b045ead742c397a4caebe1530efaf3", - "repository": "https://github.com/my-org/my-repo" + "git": + { + "path": ".github/workflows/build.yml", + "branch": "refs/heads/main", + "commitId": "d17077cc10b045ead742c397a4caebe1530efaf3", + "repository": "https://github.com/my-org/my-repo" + } + } +}, +"internalParameters": +{ + "signingRequest": + { + "url": "https://app.signpath.io/Web/1c2dbf99-f3e7-4030-bbd3-b4ffb160b60a/SigningRequests/a391b5cd-f73f-4873-9b06-ed736eb6744f" } } ``` @@ -48,11 +65,11 @@ All build types contain the following `buildDefinition` section within the `exte This section describes the guarantees made by SignPath for each SLSA Level. They are expressed by the following `runDetails.builder.id` values within the provenance: -| Builder ID | Details | -| ---------- | ------------------------------------------- | -| `https://signpath.io/slsa/builder/generic/level1` | SLSA Level 1, independent of the build system. | -| `https://signpath.io/slsa/builder/generic/level2` | SLSA Level 2, independent of the build system. | -| `https://signpath.io/slsa/builder/$build-system/level3` | SLSA Level 3, where `$build-system` specifies the associated build system. | +| Builder ID | Details +| --------------------------------------------------------| ------------------------------------------ +| `https://signpath.io/slsa/builder/generic/level1` | SLSA Level 1, independent of the build system. +| `https://signpath.io/slsa/builder/generic/level2` | SLSA Level 2, independent of the build system. +| `https://signpath.io/slsa/builder/$build-system/level3` | SLSA Level 3, where `$build-system` specifies the associated build system. The following `$build-system` values are currently supported: * `azure-devops`: A build from the [Azure DevOps](/documentation/trusted-build-systems/azure-devops) build system hosted by Microsoft in the cloud (at dev.azure.com). @@ -108,31 +125,31 @@ Guarantee: If the provenance is signed by SignPath, the build was executed on a {:.quote} > 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. -| Build System | Guarantee | -| -- | ------------------------------ | +| Build System | Guarantee +|----------------| ------------------------------ | Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which offer isolation (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/misc)) | GitHub Actions | The build was executed on a GitHub-hosted runner, each job is run in a fresh instance of the runner image (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)) {:.quote} > 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. -| Build System | Guarantee | -| -- | ------------------------------ | +| Build System | Guarantee +|----------------| ------------------------------ | Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which provide a clean virtual machien for each build run (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/misc)) | GitHub Actions | The build was executed on a GitHub-hosted runner, each job is run in a fresh instance of the runner image (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)) {:.quote} > 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. -| Build System | Guarantee | -| -- | ------------------------------ | +| Build System | Guarantee +|----------------| ------------------------------ | Azure DevOps | Cache usage has to be explicitly defined in the pipeline definition and cannot be shared across pipelines or branches (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/release/caching?view=azure-devops&tabs=bundler#cache-isolation-and-security)) | GitHub Actions | Cache usage has to be explicitly defined in the workflow definition (see [the official definition](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching)) {:.quote} > The build platform MUST NOT open services that allow for remote influence unless all such interactions are captured as externalParameters in the provenance -| Build System | Guarantee | -| -- | ------------------------------ | +| Build System | Guarantee +|----------------| ------------------------------ | Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which do not provide the ability to remotely connect (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/hosted)). | GitHub Actions | The build was executed on a GitHub-hosted runner which does not provide the ability to remotely connect, unless explicitly specified in the build definition (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network)) From 8ccbb6599b3f9a2b7b4a7d51b5493248d0b1bd10 Mon Sep 17 00:00:00 2001 From: Stefan Wenig Date: Fri, 12 Sep 2025 17:29:50 +0200 Subject: [PATCH 3/8] slsa attestation docs extended buildType and builder.id URIs added infos about trust, attestation vs code signing cleanup and typos --- docs/origin-verification/slsa-attestations.md | 103 +++++++++++------- 1 file changed, 62 insertions(+), 41 deletions(-) diff --git a/docs/origin-verification/slsa-attestations.md b/docs/origin-verification/slsa-attestations.md index e7dc88f..2b55f9d 100644 --- a/docs/origin-verification/slsa-attestations.md +++ b/docs/origin-verification/slsa-attestations.md @@ -3,61 +3,82 @@ header: SLSA Build Levels layout: resources toc: true show_toc: 3 -description: Describes the SLSA Build Levels +description: Describes SignPath SLSA build levels --- -# SLSA Attestations by SignPath +## SLSA attestations by SignPath -This page contains the definitions for the build types and builder IDs used within SLSA provenance files created by SignPath. +This page contains the definitions for SignPath build types and builders for SLSA provenance files. -## Build Types +SignPath creates SLSA attestation in three distinct steps: -This section describes the build types for SLSA attestations that are supported by SignPath. They are expressed by the `buildDefinition.buildType` field within the provenance, containing the value `https://signpath.io/slsa/buildtypes/$build-system/v1`, where `$build-system` can have one of the following values: +1. SignPath Pipeline Integrity gathers and verifies relevant information from a supported _origin_ CI/CD system +2. SignPath DeepSign creates SLSA provenance build based on that information (along with other code signing operations) +3. SignPath Attest signs the provenance -* `azure-devops`: A build from the [Azure DevOps](/documentation/trusted-build-systems/azure-devops) build system hosted by Microsoft in the cloud (at dev.azure.com). -* `github`: A build from the [GitHub Actions](/documentation/trusted-build-systems/github) build system hosted by Microsoft in the cloud (at GitHub.com). +{:.panel.info} +> **Attestation trust explained** +> +> In order to be able to trust an attestation issued by SignPath, clients need to: +> +> * Verify the signature on the attestation: it must be signed by an official SignPath certificate +> * Trust SignPath to evaluate the attested properties +> * SignPath evaluates and continuously monitors the services and APIs it uses from supported CI/CD systems. We do extensive research based on official vendor documentation and perform our own tests to ensure that attested properties reflect the actual configuration and build execution. +> * Trust all hosted CI/CD system supported by SignPath or verify that the _origin_ system is one that you trust. +> * SignPath cannot guarantee that the CI/CD system is actually operated in a safe way and safe from manipulation. +> +> Clients do _not_ need to trust the publisher for these security properties, as they are evaluated on the _control plane_ without relying on the provider's configuration. However, SignPath can only make technical evaluations and enforce technical policies. The quality of the source code (including build scripts) and code reviews is still up to the publisher. +> +> SignPath cannot attest builds from customer-operated CI/CD systems. However, SignPath provides features for customers to self-attest builds from centrally operated CI/CD systems for individual teams. -### Common Parameters +## Build type and builder identifier -All build types contain the following `buildDefinition` section within the `externalParameters`: +SignPath identifies build types and builders using the following URIs: -| Field | Description | -| ------- | ------------------------------- | -| `path` | The path to the build definition file within the commit. | -| `branch` | If available, the source code branch containing the build definition at the time of the build. | -| `commitId` | The source code version of the build definition that was used. | -| `repository` | The source code repository identifier where the build definition is located. | +| Provenance field | URI format | Example +|------------------|-----------------------------------------------------------------------------|----------- +| `buildType` | `https://docs.signpath.io/specs/slsa/buildtypes/$origin/v1` | `https://docs.signpath.io/specs/slsa/buildtypes/github/v1` +| `builder.id` | `https://signpath.io/slsa/builder/$origin/$buildLevel/slsa-$slsaVersion/v1` | `https://signpath.io/slsa/builder/github/build-l3/slsa-1.1/v1` -#### Example +The following parameters are used for these URIs: -``` -"externalParameters": -{ - "buildDefinition": - { - "path": ".github/workflows/build.yml", - "branch": "refs/heads/main", - "commitId": "d17077cc10b045ead742c397a4caebe1530efaf3", - "repository": "https://github.com/my-org/my-repo" - } -} -``` +| Parameter | Values +|-----------------|--------------- +| `$origin` | Origin CI/CD system (see next table) +| `$buildLevel` | `build-l1` - `build-l3` for SLSA levels Build L1 - L3 +| `$slsaVersion` | Version of the SLSA specification, currently ´1.1´ +| Supported hosted CI/CD systems | `$origin` value | Supported SLSA Build levels | Builder ID +|--------------------------------|------------------|----------------------------- +| [GitHub Actions] | `github` | Build L1 - L3 +| [Azure DevOps] | `azure-devops` | Build L1 - L3 +| [GitLab CI/CD] | `gitlab` | Build L1 - L3 -## Builder IDs +[GitHub Actions]: /trusted-build-systems/github +[Azure DevOps]: /trusted-build-systems/azure-devops +[GitLab CI/CD]: /trusted-build-systems/gitlab -This section describes the guarantees made by SignPath for each SLSA Level. They are expressed by the following `runDetails.builder.id` values within the provenance: +{:.panel.info} +> **Attestation vs. code signing** +> +> Code signing is usually performed by the publisher, using their own certificates and keys. A digital code signature guarantees that an artifact was published by the entity specified in the certificate (authenticity) and was not modified by a third party (integrity), provided code signing was implemented in a secure way. Signatures might carry implicit guarantees about additional security properties, but there is no way to verify those. +> +> Attestation provides explicit information about security properties attested by a third party. This article specifies specific SLSA attestations by SignPath for other parties. In order to create trustworthy attestations, SignPath gathers and verifies information on the _control plane_ from _hosted_ CI/CD services like GitHub.com. +> +> SLSA attestations do not contain any explicit publisher information. For Open Source projects, clients can check if source code repository URL and build definition match the expected values of the project. For software from commercial vendors, clients should rely on code signing for publisher verification. -| Builder ID | Details | -| ---------- | ------------------------------------------- | -| `https://signpath.io/slsa/builder/generic/level1` | SLSA Level 1, independent of the build system. | -| `https://signpath.io/slsa/builder/generic/level2` | SLSA Level 2, independent of the build system. | -| `https://signpath.io/slsa/builder/$build-system/level3` | SLSA Level 3, where `$build-system` specifies the associated build system. | +## Build type description -The following `$build-system` values are currently supported: -* `azure-devops`: A build from the [Azure DevOps](/documentation/trusted-build-systems/azure-devops) build system hosted by Microsoft in the cloud (at dev.azure.com). -* `github`: A build from the [GitHub Actions](/documentation/trusted-build-systems/github) build system hosted by Microsoft in the cloud (at GitHub.com). +This section describes the build types for SLSA attestations created by SignPath. They are expressed by the `buildDefinition.buildType` field within the provenance, containing the value `https://signpath.io/slsa/buildtypes/$build-system/v1`, where `$build-system` can have one of the following values: +### External parameters + +| Field | Type | Example | Description +|-------------------------------|--------|--------------------------------------------|-------------- +| `buildDefinition.path` | string | `.github/workflows/build.yml` | The path to the build definition file within the commit. +| `buildDefinition.branch` | string | `refs/heads/main` | If available, the source code branch containing the build definition at the time of the build. +| `buildDefinition.commitId` | string | `d17077cc10b045ead742c397a4caebe1530efaf3` | The source code version of the build definition that was used. +| `buildDefinition.repository` | string | `https://github.com/my-org/my-repo` | The source code repository identifier where the build definition is located. ### Provenance generation requirements @@ -80,7 +101,7 @@ Guarantee: The provenance was digitally signed. {:.quote} > Accuracy: The provenance MUST be generated by the control plane and not by a tenant of the build platform. -Guaranteee: SignPath created the provenance. All contents are obtained from a trusted build system on the control plane and cannot be tempered with. +Guarantee: SignPath created the provenance. All contents are obtained from a trusted build system on the control plane and cannot be tampered with. #### SLSA Level 3: The provenance is unforgeable @@ -96,7 +117,7 @@ Guarantee: The signing key is stored on SignPath and is not accessible by the en {:.quote} > All build steps ran using a hosted build platform on shared or dedicated infrastructure, not on an individual’s workstation. -Guarantee: All builds were reported through a [Trusted Build System](/documentation/trusted-build-systems). If the provenance is signed by SignPath, SignPath will guarantee that the build system is hosted in the cloud (e.g. GitHub.com or GitLab.com). Otherwise, the signer of the provenance confirms that they connected a self-managed build system with SignPath. +Guarantee: All builds were reported through a [Trusted Build System](/trusted-build-systems). If the provenance is signed by SignPath, SignPath will guarantee that the build system is hosted in the cloud (e.g. GitHub.com or GitLab.com). Otherwise, the signer of the provenance confirms that they connected a self-managed build system with SignPath. #### SLSA Level 3: Isolated builds @@ -118,7 +139,7 @@ Guarantee: If the provenance is signed by SignPath, the build was executed on a | Build System | Guarantee | | -- | ------------------------------ | -| Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which provide a clean virtual machien for each build run (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/misc)) +| Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which provide a clean virtual machine for each build run (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/misc)) | GitHub Actions | The build was executed on a GitHub-hosted runner, each job is run in a fresh instance of the runner image (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)) {:.quote} From bc46681270993b5004b0d1024f15e7740770727a Mon Sep 17 00:00:00 2001 From: Stefan Wenig Date: Fri, 12 Sep 2025 17:49:46 +0200 Subject: [PATCH 4/8] Update slsa-attestations.md internal/external params restored --- docs/origin-verification/slsa-attestations.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/origin-verification/slsa-attestations.md b/docs/origin-verification/slsa-attestations.md index 2b55f9d..7fa6ddd 100644 --- a/docs/origin-verification/slsa-attestations.md +++ b/docs/origin-verification/slsa-attestations.md @@ -73,12 +73,18 @@ This section describes the build types for SLSA attestations created by SignPath ### External parameters -| Field | Type | Example | Description -|-------------------------------|--------|--------------------------------------------|-------------- -| `buildDefinition.path` | string | `.github/workflows/build.yml` | The path to the build definition file within the commit. -| `buildDefinition.branch` | string | `refs/heads/main` | If available, the source code branch containing the build definition at the time of the build. -| `buildDefinition.commitId` | string | `d17077cc10b045ead742c397a4caebe1530efaf3` | The source code version of the build definition that was used. -| `buildDefinition.repository` | string | `https://github.com/my-org/my-repo` | The source code repository identifier where the build definition is located. +| Field | Type | Example | Description +|----------------------------------|--------|--------------------------------------------|-------------- +| `buildDefinition.git.repository` | string | `https://github.com/my-org/my-repo` | Source code repository identifier for the build definition +| `buildDefinition.git.path` | string | `.github/workflows/build.yml` | Path to the build definition file within the commit +| `buildDefinition.git.branch` | string | `refs/heads/main` | If available, the source code branch containing the build definition at the time of the build +| `buildDefinition.git.commitId` | string | `d17077cc10b045ead742c397a4caebe1530efaf3` | Source code version of the build definition that was used + +### Internal parameters + +| Field | Description +|----------------------|-------------- +| `signingRequest.url` | URL of the signing request that created the attestation ### Provenance generation requirements From 04c3b5121a5301bde3f95e916776c937a37c17bc Mon Sep 17 00:00:00 2001 From: Stefan Wenig Date: Tue, 23 Sep 2025 16:41:55 +0200 Subject: [PATCH 5/8] Update slsa-attestations.md --- docs/origin-verification/slsa-attestations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/origin-verification/slsa-attestations.md b/docs/origin-verification/slsa-attestations.md index 7fa6ddd..d0f5ecb 100644 --- a/docs/origin-verification/slsa-attestations.md +++ b/docs/origin-verification/slsa-attestations.md @@ -48,7 +48,7 @@ The following parameters are used for these URIs: | `$buildLevel` | `build-l1` - `build-l3` for SLSA levels Build L1 - L3 | `$slsaVersion` | Version of the SLSA specification, currently ´1.1´ -| Supported hosted CI/CD systems | `$origin` value | Supported SLSA Build levels | Builder ID +| Supported hosted CI/CD systems | `$origin` value | Supported SLSA Build levels |--------------------------------|------------------|----------------------------- | [GitHub Actions] | `github` | Build L1 - L3 | [Azure DevOps] | `azure-devops` | Build L1 - L3 From d1e341b3275db508eb33ae6793f3b933a3f7950f Mon Sep 17 00:00:00 2001 From: Stefan Wenig Date: Tue, 23 Sep 2025 16:42:47 +0200 Subject: [PATCH 6/8] Update slsa-attestations.md --- docs/origin-verification/slsa-attestations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/origin-verification/slsa-attestations.md b/docs/origin-verification/slsa-attestations.md index d0f5ecb..036c0d3 100644 --- a/docs/origin-verification/slsa-attestations.md +++ b/docs/origin-verification/slsa-attestations.md @@ -46,7 +46,7 @@ The following parameters are used for these URIs: |-----------------|--------------- | `$origin` | Origin CI/CD system (see next table) | `$buildLevel` | `build-l1` - `build-l3` for SLSA levels Build L1 - L3 -| `$slsaVersion` | Version of the SLSA specification, currently ´1.1´ +| `$slsaVersion` | Version of the SLSA specification, currently ´1.1´ | Supported hosted CI/CD systems | `$origin` value | Supported SLSA Build levels |--------------------------------|------------------|----------------------------- From c3e4343ea4054facd3ed45a0713799596de8da24 Mon Sep 17 00:00:00 2001 From: Stefan Wenig Date: Wed, 24 Sep 2025 10:40:28 +0200 Subject: [PATCH 7/8] Update slsa-attestations.md --- docs/origin-verification/slsa-attestations.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/origin-verification/slsa-attestations.md b/docs/origin-verification/slsa-attestations.md index 036c0d3..9bdae4a 100644 --- a/docs/origin-verification/slsa-attestations.md +++ b/docs/origin-verification/slsa-attestations.md @@ -35,10 +35,10 @@ SignPath creates SLSA attestation in three distinct steps: SignPath identifies build types and builders using the following URIs: -| Provenance field | URI format | Example -|------------------|-----------------------------------------------------------------------------|----------- -| `buildType` | `https://docs.signpath.io/specs/slsa/buildtypes/$origin/v1` | `https://docs.signpath.io/specs/slsa/buildtypes/github/v1` -| `builder.id` | `https://signpath.io/slsa/builder/$origin/$buildLevel/slsa-$slsaVersion/v1` | `https://signpath.io/slsa/builder/github/build-l3/slsa-1.1/v1` +| Provenance field | URI format | Example +|------------------|----------------------------------------------------------------------------------------|----------- +| `buildType` | `https://docs.signpath.io/specs/slsa/buildtypes/$origin/v1` | `https://docs.signpath.io/specs/slsa/buildtypes/github/v1` +| `builder.id` | `https://docs.signpath.io/specs/slsa/builder/$origin/$buildLevel/slsa-$slsaVersion/v1` | `https://docs.signpath.io/specs/slsa/builder/github/build-l3/slsa-1.1/v1` The following parameters are used for these URIs: From 8dd570a18d31bc1478b61d7cd2a2057374049d23 Mon Sep 17 00:00:00 2001 From: Paul Savoie Date: Thu, 27 Nov 2025 15:57:11 +0100 Subject: [PATCH 8/8] adds links and gitlab preliminary SLSA definitions --- docs/origin-verification/slsa-attestations.md | 4 ++++ docs/specs/slsa/builder/azure-devops/build-l1/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/builder/azure-devops/build-l2/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/builder/azure-devops/build-l3/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/builder/github/build-l1/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/builder/github/build-l2/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/builder/github/build-l3/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/builder/gitlab/build-l1/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/builder/gitlab/build-l2/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/builder/gitlab/build-l3/slsa-1.1/v1.md | 3 +++ docs/specs/slsa/buildtypes/azure-devops/v1.md | 3 +++ docs/specs/slsa/buildtypes/github/v1.md | 3 +++ docs/specs/slsa/buildtypes/gitlab/v1.md | 3 +++ 13 files changed, 40 insertions(+) create mode 100644 docs/specs/slsa/builder/azure-devops/build-l1/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/builder/azure-devops/build-l2/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/builder/azure-devops/build-l3/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/builder/github/build-l1/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/builder/github/build-l2/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/builder/github/build-l3/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/builder/gitlab/build-l1/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/builder/gitlab/build-l2/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/builder/gitlab/build-l3/slsa-1.1/v1.md create mode 100644 docs/specs/slsa/buildtypes/azure-devops/v1.md create mode 100644 docs/specs/slsa/buildtypes/github/v1.md create mode 100644 docs/specs/slsa/buildtypes/gitlab/v1.md diff --git a/docs/origin-verification/slsa-attestations.md b/docs/origin-verification/slsa-attestations.md index 9bdae4a..b725aef 100644 --- a/docs/origin-verification/slsa-attestations.md +++ b/docs/origin-verification/slsa-attestations.md @@ -139,6 +139,7 @@ Guarantee: If the provenance is signed by SignPath, the build was executed on a | -- | ------------------------------ | | Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which offer isolation (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/misc)) | GitHub Actions | The build was executed on a GitHub-hosted runner, each job is run in a fresh instance of the runner image (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)) +| GitLab CI/CD | The build was executed on a GitLab-hosted runner, each job runs in a newly provisioned VM (see [the oficial documentation](https://docs.gitlab.com/ci/runners/hosted_runners/)) {:.quote} > 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. @@ -147,6 +148,7 @@ Guarantee: If the provenance is signed by SignPath, the build was executed on a | -- | ------------------------------ | | Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which provide a clean virtual machine for each build run (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/security/misc)) | GitHub Actions | The build was executed on a GitHub-hosted runner, each job is run in a fresh instance of the runner image (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/use-github-hosted-runners)) +| GitLab CI/CD | The build was executed on a GitLab-hosted runner, each job runs in a newly provisioned VM (see [the oficial documentation](https://docs.gitlab.com/ci/runners/hosted_runners/)) {:.quote} > 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. @@ -155,6 +157,7 @@ Guarantee: If the provenance is signed by SignPath, the build was executed on a | -- | ------------------------------ | | Azure DevOps | Cache usage has to be explicitly defined in the pipeline definition and cannot be shared across pipelines or branches (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/release/caching?view=azure-devops&tabs=bundler#cache-isolation-and-security)) | GitHub Actions | Cache usage has to be explicitly defined in the workflow definition (see [the official definition](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching)) +| GitLab CI/CD | TODO: https://docs.gitlab.com/ci/caching/ {:.quote} > The build platform MUST NOT open services that allow for remote influence unless all such interactions are captured as externalParameters in the provenance @@ -163,3 +166,4 @@ Guarantee: If the provenance is signed by SignPath, the build was executed on a | -- | ------------------------------ | | Azure DevOps | The build was executed on a runner from the Microsoft-hosted pools, which do not provide the ability to remotely connect (see [the official documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/hosted)). | GitHub Actions | The build was executed on a GitHub-hosted runner which does not provide the ability to remotely connect, unless explicitly specified in the build definition (see [the official documentation](https://docs.github.com/en/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network)) +| GitLab CI/CD | The build was executed on a GitLab-hosted runner wich does not allow remote connections (see [the official documentation](https://docs.gitlab.com/ci/runners/hosted_runners/)) diff --git a/docs/specs/slsa/builder/azure-devops/build-l1/slsa-1.1/v1.md b/docs/specs/slsa/builder/azure-devops/build-l1/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/azure-devops/build-l1/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/builder/azure-devops/build-l2/slsa-1.1/v1.md b/docs/specs/slsa/builder/azure-devops/build-l2/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/azure-devops/build-l2/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/builder/azure-devops/build-l3/slsa-1.1/v1.md b/docs/specs/slsa/builder/azure-devops/build-l3/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/azure-devops/build-l3/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/builder/github/build-l1/slsa-1.1/v1.md b/docs/specs/slsa/builder/github/build-l1/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/github/build-l1/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/builder/github/build-l2/slsa-1.1/v1.md b/docs/specs/slsa/builder/github/build-l2/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/github/build-l2/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/builder/github/build-l3/slsa-1.1/v1.md b/docs/specs/slsa/builder/github/build-l3/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/github/build-l3/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/builder/gitlab/build-l1/slsa-1.1/v1.md b/docs/specs/slsa/builder/gitlab/build-l1/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/gitlab/build-l1/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/builder/gitlab/build-l2/slsa-1.1/v1.md b/docs/specs/slsa/builder/gitlab/build-l2/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/gitlab/build-l2/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/builder/gitlab/build-l3/slsa-1.1/v1.md b/docs/specs/slsa/builder/gitlab/build-l3/slsa-1.1/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/builder/gitlab/build-l3/slsa-1.1/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/buildtypes/azure-devops/v1.md b/docs/specs/slsa/buildtypes/azure-devops/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/buildtypes/azure-devops/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/buildtypes/github/v1.md b/docs/specs/slsa/buildtypes/github/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/buildtypes/github/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file diff --git a/docs/specs/slsa/buildtypes/gitlab/v1.md b/docs/specs/slsa/buildtypes/gitlab/v1.md new file mode 100644 index 0000000..f4690ec --- /dev/null +++ b/docs/specs/slsa/buildtypes/gitlab/v1.md @@ -0,0 +1,3 @@ +--- +redirect_to: /origin-verification/slsa-attestations +--- \ No newline at end of file