Skip to content

Commit cb7c3bb

Browse files
paulsavoiepaulsavoie
committed
adds slsa attestations page
1 parent 9c7e181 commit cb7c3bb

4 files changed

Lines changed: 154 additions & 0 deletions

File tree

‎docs/_data/menus/documentation.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,9 @@
5959

6060
- text: Origin Verification
6161
path: origin-verification
62+
items:
63+
- text: SLSA Attestations
64+
path: slsa-attestations
6265

6366
- separator: true
6467

‎docs/_sass/resources.scss‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,19 @@ main > section.resources-section {
192192
}
193193
}
194194

195+
blockquote.quote {
196+
background: $light-grey-background-color;
197+
border-left: 10px solid $blockquote-line-color;
198+
margin: 1.5em 10px;
199+
padding: 0.5em 10px;
200+
quotes: "\201C""\201D""\2018""\2019";
201+
font-style: italic;
202+
203+
& > p {
204+
margin: 0px;
205+
}
206+
}
207+
195208
/** HIGHLIGHTS **/
196209
blockquote.panel {
197210
border: 1px solid $grey-border-color;

docs/origin-verification.md renamed to docs/origin-verification/index.md

File renamed without changes.

‎docs/origin-verification/slsa-attestations.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
header: SLSA Build Levels
3+
layout: resources
4+
toc: true
5+
show_toc: 3
6+
description: Describes the SLSA Build Levels
7+
---
8+
9+
# SLSA Attestations by SignPath
10+
11+
This page contains the definitions for the build types and builder IDs used within SLSA provenance files created by SignPath.
12+
13+
## Build Types
14+
15+
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:
16+
17+
* `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).
18+
* `github`: A build from the [GitHub Actions](/documentation/trusted-build-systems/github) build system hosted by Microsoft in the cloud (at GitHub.com).
19+
20+
### Common Parameters
21+
22+
All build types contain the following `buildDefinition` section within the `externalParameters`:
23+
24+
| Field | Description |
25+
| ------- | ------------------------------- |
26+
| `path` | The path to the build definition file within the commit. |
27+
| `branch` | If available, the source code branch containing the build definition at the time of the build. |
28+
| `commitId` | The source code version of the build definition that was used. |
29+
| `repository` | The source code repository identifier where the build definition is located. |
30+
31+
#### Example
32+
33+
```
34+
"externalParameters":
35+
{
36+
"buildDefinition":
37+
{
38+
"path": ".github/workflows/build.yml",
39+
"branch": "refs/heads/main",
40+
"commitId": "d17077cc10b045ead742c397a4caebe1530efaf3",
41+
"repository": "https://github.com/my-org/my-repo"
42+
}
43+
}
44+
```
45+
46+
47+
## Builder IDs
48+
49+
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:
50+
51+
| Builder ID | Details |
52+
| ---------- | ------------------------------------------- |
53+
| `https://signpath.io/slsa/builder/generic/level1` | SLSA Level 1, independent of the build system. |
54+
| `https://signpath.io/slsa/builder/generic/level2` | SLSA Level 2, independent of the build system. |
55+
| `https://signpath.io/slsa/builder/$build-system/level3` | SLSA Level 3, where `$build-system` specifies the associated build system. |
56+
57+
The following `$build-system` values are currently supported:
58+
* `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).
59+
* `github`: A build from the [GitHub Actions](/documentation/trusted-build-systems/github) build system hosted by Microsoft in the cloud (at GitHub.com).
60+
61+
62+
### Provenance generation requirements
63+
64+
For a detailed list, see the [original definition by SLSA](https://slsa.dev/spec/v1.1/requirements).
65+
66+
#### SLSA Level 1: A provenance must exist
67+
68+
{:.quote}
69+
> The build process MUST generate provenance that unambiguously identifies the output package by cryptographic digest and describes how that package was produced.
70+
71+
Guarantee: SignPath created a complete provenance.
72+
73+
#### SLSA Level 2: The provenance is authentic
74+
75+
{:.quote}
76+
> Authenticity: Consumers MUST be able to validate the authenticity of the provenance attestation in order to ensure integrity and define trust.
77+
78+
Guarantee: The provenance was digitally signed.
79+
80+
{:.quote}
81+
> Accuracy: The provenance MUST be generated by the control plane and not by a tenant of the build platform.
82+
83+
Guaranteee: SignPath created the provenance. All contents are obtained from a trusted build system on the control plane and cannot be tempered with.
84+
85+
#### SLSA Level 3: The provenance is unforgeable
86+
87+
{:.quote}
88+
> Accuracy: Provenance MUST be strongly resistant to forgery by tenants.
89+
90+
Guarantee: The signing key is stored on SignPath and is not accessible by the environment running the user-defined build steps.
91+
92+
### Isolation strength requirements
93+
94+
#### SLSA Level 2: Hosted builds
95+
96+
{:.quote}
97+
> All build steps ran using a hosted build platform on shared or dedicated infrastructure, not on an individual’s workstation.
98+
99+
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.
100+
101+
#### SLSA Level 3: Isolated builds
102+
103+
{:.quote}
104+
> 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.
105+
106+
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.
107+
108+
{:.quote}
109+
> 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.
110+
111+
| Build System | Guarantee |
112+
| -- | ------------------------------ |
113+
| 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))
114+
| 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))
115+
116+
{:.quote}
117+
> 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.
118+
119+
| Build System | Guarantee |
120+
| -- | ------------------------------ |
121+
| 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))
122+
| 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))
123+
124+
{:.quote}
125+
> 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.
126+
127+
| Build System | Guarantee |
128+
| -- | ------------------------------ |
129+
| 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))
130+
| 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))
131+
132+
{:.quote}
133+
> The build platform MUST NOT open services that allow for remote influence unless all such interactions are captured as externalParameters in the provenance
134+
135+
| Build System | Guarantee |
136+
| -- | ------------------------------ |
137+
| 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)).
138+
| 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))

0 commit comments

Comments
 (0)