Skip to content

Commit 350bdec

Browse files
asraaasraa
authored
Add provenance field docs for the GitHub hosted build (#169)
* Add docs on provenance fields Signed-off-by: Asra Ali <[email protected]> * update Signed-off-by: Asra Ali <[email protected]> * add v1 Signed-off-by: Asra Ali <[email protected]> * add v1 Signed-off-by: Asra Ali <[email protected]> * update Signed-off-by: Asra Ali <[email protected]>
1 parent 3fbcc15 commit 350bdec

File tree

2 files changed

+149
-2
lines changed

2 files changed

+149
-2
lines changed

‎README.md‎

Lines changed: 113 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@ This repository contains the code, examples and technical design for the blog po
1616

1717
## Golang projects
1818

19-
To generate SLSA provenance for your Golang project, follow [internal/builders/go/README.md](internal/builders/go/README.md)
19+
To generate SLSA provenance for your Golang project, follow [internal/builders/go/README.md](internal/builders/go/README.md).
2020

2121
## Other projects
2222

23-
To generate SLSA provenance for other programming languages, follow [internal/builders/generic/README.md](internal/builders/generic/README.md)
23+
To generate SLSA provenance for other programming languages, follow [internal/builders/generic/README.md](internal/builders/generic/README.md).
2424

2525
## Technical design
2626

@@ -31,3 +31,114 @@ Find our blog post series [here](https://security.googleblog.com/2022/04/improvi
3131
### Specifications
3232

3333
For a more in-depth technical dive, read the [SPECIFICATIONS.md](./SPECIFICATIONS.md).
34+
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+
143+
144+

‎internal/builders/go/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,42 @@ An example of the provenance generated from this repo is below:
241241
}
242242
```
243243

244+
### BuildConfig format
245+
246+
The `BuildConfig` contains the following fields:
247+
248+
`version`: The version of the `BuildConfig` format.
249+
250+
`steps`: The steps that were performed in the buid.
251+
252+
`steps[*].command`: The list of commands that were executed in a step.
253+
254+
```json
255+
"command": [
256+
"/opt/hostedtoolcache/go/1.17.10/x64/bin/go",
257+
"mod",
258+
"vendor"
259+
],
260+
```
261+
262+
`steps[*].env`: Any environment variables used in the command, including any OS environment variables and those set in the configuration file.
263+
264+
```json
265+
"env": [
266+
"GOOS=linux",
267+
"GOARCH=amd64",
268+
"GO111MODULE=on",
269+
"CGO_ENABLED=0"
270+
],
271+
```
272+
273+
`steps[*].workingDir`: The working directory where the steps were performed in the runner.
274+
275+
```json
276+
"workingDir": "/home/runner/work/ianlewis/actions-test"
277+
```
278+
279+
244280
## Verification of provenance
245281

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

0 commit comments

Comments
 (0)