Skip to content

Commit 49176b3

Browse files
laurentsimonlaurentsimon
authored
📖 Update doc (slsa-framework#175)
* Split provenance doc * update * update * update * update
1 parent 350bdec commit 49176b3

File tree

3 files changed

+118
-140
lines changed

3 files changed

+118
-140
lines changed

‎PROVENANCE_FORMAT.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
Each of the projects utilize the same base GitHub workflow SLSA provenance. The common fields of the SLSA provenance predicate attested to are below.
2+
3+
## Since v1.0.0
4+
5+
`BuildType`: This is the URI for the particular provenance builder, for example, the go or generic builder.
6+
```json
7+
"buildType": "https://github.com/slsa-framework/slsa-github-generator/go@v1"
8+
```
9+
`Builder.Id`: The builder ID refers to the fully qualified URI of the trusted builder's workflow and its reference.
10+
```json
11+
"builder": {
12+
"id": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v0.0.1"
13+
}
14+
```
15+
`Invocation`: Identifies the event that kicked off the build. This describes the workflow run and includes GitHub workflow event information, entrypoint, and parameters from trigger events.
16+
`Invocation.configSource`: This describes the calling workflow's source and the entrypoint of the build.
17+
```json
18+
"configSource": {
19+
"uri": "git+https://github.com/laurentsimon/slsa-verifier-test-gen@refs/heads/main",
20+
"digest": {
21+
"sha1": "15bf79ea9c89fffbf5dd02c6b5b686b291bfcbd2"
22+
},
23+
"entryPoint": ".github/workflows/release.yml"
24+
},
25+
```
26+
`Invocation.parameters`: This describes any parameters from trigger events.
27+
28+
`Invocation.environment`: This describes the GitHub workflow builder-controlled environment variables, including the event information, required to reproduce the build. See `github` content [documentation](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context) for more information.
29+
30+
31+
| Name | Value | Description |
32+
| ---------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
33+
| `github_event_name` | `workflow_dispatch`, `schedule`, `push`, etc | Name of the [event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#available-events) that initiated the workflow run. |
34+
| `github_event_payload` | `"{"inputs": null, "repository": { ... }}"` | The full [event payload](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads), including workflow inputs and repository information. |
35+
| `github_ref_type` | `"branch"` | The type of ref that triggered the workflow run. |
36+
| `github_ref` | `"refs/heads/main"` | The ref that triggered the workflow run. |
37+
| `github_base_ref` | `"feat/feat-branch"` | The ref or source branch of the pull request in a workflow run. Only populated on pull requests. |
38+
| `github_head_ref` | `"feat/feat-branch"` | The is ref or source branch of the pull request in a workflow run. |
39+
| `github_actor` | `"laurentsimon"` | The username of the user that initiated the workflow run. |
40+
| `github_sha1` | `"b54fb2ec8807a93b58d5f298b7e6b785ea7078bb"` | The is the commit SHA that triggered the workflow run. |
41+
| `github_repository_owner` | `"slsa-framework"` | The owner of the repository. |
42+
| `github_repository_id` | `"8923542"` | The is the unique ID of the repository. |
43+
| `github_actor_id` | `"973615"` | The is the unique ID of the actor that triggered the workflow run. |
44+
| `github_repository_owner_id` | `"123456"` | The is the unique ID of the owner of the repository. |
45+
| `github_run_attempt` | `"1"` | The is run attempt of the workflow run. |
46+
| `github_run_id` | `"2436960022"` | The is the run ID for the workflow run. |
47+
| `github_run_number` | `"32"` | The is the run number of the workflow run. |
48+
49+
```json
50+
"environment": {
51+
"github_actor": "laurentsimon",
52+
"github_base_ref": "",
53+
"github_event_name": "workflow_dispatch",
54+
"github_event_payload": {
55+
"inputs": null,
56+
"ref": "refs/heads/main",
57+
"repository": { ... }
58+
},
59+
"github_head_ref": "add-field-docs",
60+
"github_ref": "refs/pull/169/merge",
61+
"github_ref_type": "branch",
62+
"github_repository_owner": "slsa-framework",
63+
"github_run_attempt": "1",
64+
"github_run_id": "2436960022",
65+
"github_run_number": "32",
66+
"github_sha1": "b54fb2ec8807a93b58d5f298b7e6b785ea7078bb",
67+
"github_repository_id": "8923542",
68+
"github_repository_owner": "ianlewis",
69+
"github_repository_owner_id": "123456",
70+
}
71+
```
72+
73+
`BuildConfig`: This contains information on the steps of the build. The default is nil, specific builders implement their own. See:
74+
- [Golang BuildConfig Format](https://github.com/slsa-framework/slsa-github-generator/blob/main/internal/builders/go/README.md#buildconfig-format).
75+
76+
`Materials`: List of materials that influenced the build, including the repository that triggered the GitHub Actions workflow.
77+
```json
78+
"materials": [
79+
{
80+
"uri": "git+https://github.com/laurentsimon/slsa-verifier-test-gen@refs/heads/main",
81+
"digest": {
82+
"sha1": "15bf79ea9c89fffbf5dd02c6b5b686b291bfcbd2"
83+
}
84+
},
85+
{
86+
"uri": "https://github.com/actions/virtual-environments/releases/tag/ubuntu20/20220515.1"
87+
}
88+
]
89+
```
90+
`Metadata`: Other properties of the build, including `BuildInvocationID` as the unique `RunID` and `RunAttempt`.
91+
```json
92+
"metadata": {
93+
"buildInvocationID": "2387611653-1",
94+
"completeness": {
95+
"parameters": true,
96+
"environment": false,
97+
"materials": false
98+
},
99+
"reproducible": false
100+
},
101+
102+
```
103+
104+
105+
Specific implementations of builders may define and customize their own `BuildConfig`, `Invocation`, `Materials`, and `Metadata`.

‎README.md

+5-108
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This repository contains the code, examples and technical design for the blog po
88

99
- [Golang projects](#golang-projects)
1010
- [Other projects](#other-projects)
11+
- [Provenance format](#provenance-format)
1112
- [Technical design](#technical-design)
1213
- [Blog post](#blog-post)
1314
- [Specifications](#specifications)
@@ -22,6 +23,10 @@ To generate SLSA provenance for your Golang project, follow [internal/builders/g
2223

2324
To generate SLSA provenance for other programming languages, follow [internal/builders/generic/README.md](internal/builders/generic/README.md).
2425

26+
## Provenance format
27+
28+
The format of the provenance is available in [PROVENANCE_FORMAT.md](./PROVENANCE_FORMAT.md).
29+
2530
## Technical design
2631

2732
### Blog post
@@ -32,113 +37,5 @@ Find our blog post series [here](https://security.googleblog.com/2022/04/improvi
3237

3338
For a more in-depth technical dive, read the [SPECIFICATIONS.md](./SPECIFICATIONS.md).
3439

35-
### Format
36-
37-
Each of the projects utilize the same base GitHub workflow SLSA provenance. The common fields of the SLSA provenance predicate attested to are below.
38-
39-
40-
_Added v1.0.0_
41-
42-
`BuildType`: This is the URI for the particular provenance builder, for example, the go or generic builder.
43-
```json
44-
"buildType": "https://github.com/slsa-framework/slsa-github-generator-go@v1"
45-
```
46-
`Builder.Id`: The builder ID refers to the fully qualified URI of the trusted builder's workflow and its reference.
47-
```json
48-
"builder": {
49-
"id": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v0.0.1"
50-
}
51-
```
52-
`Invocation`: Identifies the event that kicked off the build. This describes the workflow run and includes GitHub workflow event information, entrypoint, and parameters from trigger events.
53-
`Invocation.configSource`: This describes the calling workflow's source and the entrypoint of the build.
54-
```json
55-
"configSource": {
56-
"uri": "git+https://github.com/laurentsimon/slsa-verifier-test-gen@refs/heads/main",
57-
"digest": {
58-
"sha1": "15bf79ea9c89fffbf5dd02c6b5b686b291bfcbd2"
59-
},
60-
"entryPoint": "Go SLSA Release"
61-
},
62-
```
63-
`Invocation.parameters`: This describes any parameters from trigger events.
64-
65-
`Invocation.environment`: This describes the GitHub workflow builder-controlled environment variables, including the event information, required to reproduce the build. See `github` content [documentation](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context) for more information.
66-
67-
68-
| Name | Value | Description |
69-
| ---------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70-
| `github_event_name` | `workflow_dispatch` | Name of the [event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#available-events) that initiated the workflow run. |
71-
| `github_event_payload` | `"{"inputs": null,"ref": "refs/heads/main", "repository": { ... }}"` | The full event payload, including workflow inputs and repository information. |
72-
| `github_ref_type` | `"branch"` | The type of ref that triggered the workflow run. |
73-
| `github_ref` | `"refs/pull/169/merge"` | The ref that triggered the workflow run. |
74-
| `github_base_ref` | `"feat/feat-branch"` | The ref or source branch of the pull request in a workflow run. Only populated on pull requests. |
75-
| `github_head_ref` | `"feat/feat-branch"` | The is ref or source branch of the pull request in a workflow run. |
76-
| `github_actor` | `"laurentsimon"` | The username of the user that initiated the workflow run. |
77-
| `github_sha1` | `"b54fb2ec8807a93b58d5f298b7e6b785ea7078bb"` | The is the commit SHA that triggered the workflow run. |
78-
| `github_repository_owner` | `"slsa-framework"` | The owner of the repository. |
79-
| `github_repository_id` | `"8923542"` | The is the unique ID of the repository. |
80-
| `github_actor_id` | `"branch"` | The is the unique ID of the actor that triggered the workflow run. |
81-
| `github_repository_owner_id` | `"123456"` | The is the unique ID of the owner of the repository. |
82-
| `github_run_attempt` | `"1"` | The is run attempt of the workflow run. |
83-
| `github_run_id` | `"2436960022"` | The is the run ID for the workflow run. |
84-
| `github_run_number` | `"32"` | The is the run number of the workflow run. |
85-
86-
```json
87-
"environment": {
88-
"github_actor": "laurentsimon",
89-
"github_base_ref": "",
90-
"github_event_name": "workflow_dispatch",
91-
"github_event_payload": {
92-
"inputs": null,
93-
"ref": "refs/heads/main",
94-
"repository": { ... }
95-
},
96-
"github_head_ref": "add-field-docs",
97-
"github_ref": "refs/pull/169/merge",
98-
"github_ref_type": "branch",
99-
"github_repository_owner": "slsa-framework",
100-
"github_run_attempt": "1",
101-
"github_run_id": "2436960022",
102-
"github_run_number": "32",
103-
"github_sha1": "b54fb2ec8807a93b58d5f298b7e6b785ea7078bb",
104-
"github_repository_id": "8923542",
105-
"github_repository_owner": "ianlewis",
106-
"github_repository_owner_id": "123456",
107-
}
108-
```
109-
110-
`BuildConfig`: This contains information on the steps of the build. The default is nil, specific builders implement their own. See [BuildConfig Format](https://github.com/slsa-framework/slsa-github-generator/blob/main/internal/builders/go/README.md#buildconfig-format) in the Golang builder for an example.
111-
112-
`Materials`: List of materials that influenced the build, including the repository that triggered the GitHub Actions workflow.
113-
```json
114-
"materials": [
115-
{
116-
"uri": "git+https://github.com/laurentsimon/slsa-verifier-test-gen@refs/heads/main",
117-
"digest": {
118-
"sha1": "15bf79ea9c89fffbf5dd02c6b5b686b291bfcbd2"
119-
}
120-
},
121-
{
122-
"uri": "https://github.com/actions/virtual-environments/releases/tag/ubuntu20/20220515.1"
123-
}
124-
]
125-
```
126-
`Metadata`: Other properties of the build, including `BuildInvocationID` as the unique `RunID` and `RunAttempt`.
127-
```json
128-
"metadata": {
129-
"buildInvocationID": "2387611653-1",
130-
"completeness": {
131-
"parameters": true,
132-
"environment": false,
133-
"materials": false
134-
},
135-
"reproducible": false
136-
},
137-
138-
```
139-
140-
141-
Specific implementations of builders may define and customize their own `BuildConfig`, `Invocation`, `Materials`, and `Metadata`.
142-
14340

14441

‎internal/builders/go/README.md

+8-32
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,11 @@ This document explains how to use the builder for Golang projects.
1212
- [Workflow inputs](#workflow-inputs)
1313
- [Workflow Example](#workflow-example)
1414
- [Example provenance](#example-provenance)
15+
- [BuildConfig format](#buildconfig-format)
1516

1617
[Verification of provenance](#verification-of-provenance)
1718

19+
- [Installation](#installation)
1820
- [Inputs](#inputs)
1921
- [Command line examples](#command-line-examples)
2022

@@ -276,44 +278,18 @@ The `BuildConfig` contains the following fields:
276278
"workingDir": "/home/runner/work/ianlewis/actions-test"
277279
```
278280

279-
280281
## Verification of provenance
281282

282283
To verify the provenance, use the [github.com/slsa-framework/slsa-verifier](https://github.com/slsa-framework/slsa-verifier) project.
283284

285+
### Installation
286+
287+
To install the verifier, see [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation).
288+
284289
### Inputs
285290

286-
```shell
287-
$ git clone [email protected]:slsa-framework/slsa-verifier.git
288-
$ git checkout tags/v1.0.0
289-
$ go run . --help
290-
-binary string
291-
path to a binary to verify
292-
-branch string
293-
expected branch the binary was compiled from (default "main")
294-
-provenance string
295-
path to a provenance file
296-
-source string
297-
expected source repository that should have produced the binary, e.g. github.com/some/repo
298-
-tag string
299-
[optional] expected tag the binary was compiled from
300-
-versioned-tag string
301-
[optional] expected version the binary was compiled from. Uses semantic version to match the tag
302-
```
291+
The inputs of the verifier are described in [slsa-framework/slsa-verifier#available-options](https://github.com/slsa-framework/slsa-verifier#available-options).
303292

304293
### Command line examples
305294

306-
```shell
307-
$ go run . --binary ~/Downloads/binary-linux-amd64 --provenance ~/Downloads/binary-linux-amd64.intoto.jsonl --source github.com/origin/repo
308-
309-
Verified against tlog entry 1544571
310-
verified SLSA provenance produced at
311-
{
312-
"caller": "origin/repo",
313-
"commit": "0dfcd24824432c4ce587f79c918eef8fc2c44d7b",
314-
"job_workflow_ref": "/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v1.0.0",
315-
"trigger": "workflow_dispatch",
316-
"issuer": "https://token.actions.githubusercontent.com"
317-
}
318-
successfully verified SLSA provenance
319-
```
295+
A command line example is provided in [slsa-framework/slsa-verifier#example](https://github.com/slsa-framework/slsa-verifier#example).

0 commit comments

Comments
 (0)