-
Notifications
You must be signed in to change notification settings - Fork 219
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Provenance v1.0: initial draft #525
Merged
MarkLodato
merged 47 commits into
slsa-framework:main
from
MarkLodato:provenance-refactor
Jan 20, 2023
Merged
Changes from all commits
Commits
Show all changes
47 commits
Select commit
Hold shift + click to select a range
b20437c
WIP
MarkLodato 2a3eb61
WIP: finished proto for v1.0
MarkLodato ad7e823
WIP: inputArtifacts, parameters
MarkLodato cdecf52
WIP
MarkLodato 2ef3659
WIP: apply feedback
MarkLodato e7dd1e0
WIP: replace proto extension with Markdown link
MarkLodato c3089de
Update example to use latest version of proto
MarkLodato 25c78c3
artifacts: go back to map, uri
MarkLodato 1015166
WIP: topLevelInputs and buildDependencies
MarkLodato 861d844
WIP: make examples more realistic
MarkLodato f499fad
WIP: add cue file
MarkLodato cec3785
WIP: add Tekton example and TODO
MarkLodato 82a3c28
WIP: merge everything into markdown file
MarkLodato df6bec9
WIP: remove extra divs
MarkLodato 668f41a
WIP: rewrite intro
MarkLodato 5a96d3a
WIP: rename Artifact to ArtifactReference
MarkLodato c397e76
Use headings in change history
MarkLodato f1adaf3
Make draft URL work
MarkLodato f5a4b06
fix lint errors
MarkLodato b661ee1
Address PR feedback
MarkLodato 5aab59b
Add builderDependencies
MarkLodato 78ae06f
WIP: lowercase purl, move TODO
MarkLodato 11459e6
WIP
MarkLodato 5d1e791
WIP: refactor - external vs system parameters
MarkLodato 32f9d2f
Merge branch 'main' into provenance-refactor
MarkLodato d044c3d
WIP: fix typo in URL
MarkLodato 3ae85a9
WIP: add todo
MarkLodato e60f742
Use the generic SLSA generator for the example.
MarkLodato 479b7b3
Make builder.version a map
MarkLodato 9ca7346
Replace .artifacts[name] with [name].artifact.
MarkLodato d63f6ba
Replace map with array of name/value pairs
MarkLodato 03a0660
Revert "Replace map with array of name/value pairs"
MarkLodato 0ca0d69
Update provenance build model
MarkLodato 8b32358
Merge branch 'main' into provenance-refactor
MarkLodato 622c0b5
Disable lint for blank lines betwen blockqutoes
MarkLodato 77d5814
proto nits: consistent required/optional syntax
MarkLodato a18326b
More iteration on model
MarkLodato 3b728b4
Move github actions to separate file; revise text
MarkLodato a4494fb
Only include major version in provenance URL.
MarkLodato 31094f7
WIP: move to Markdown
MarkLodato 472ba94
Finish Markdown conversion, add other param types
MarkLodato fdce758
address comments
MarkLodato 268a64d
Merge branch 'main' into provenance-refactor
MarkLodato aba878e
fix mdlint
MarkLodato 1987abf
add TODO about creating other build types
MarkLodato 40aeb77
Fix typos in provenance v1.0
MarkLodato 4210074
drop .md from link
MarkLodato File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
{ | ||
"predicateType": "https://slsa.dev/provenance/v1?draft", | ||
"predicate": { | ||
"buildDefinition": { | ||
"buildType": "https://slsa.dev/github-actions-workflow/v0.1?draft", | ||
"externalParameters": { | ||
"inputs": { | ||
"mapValue": { | ||
"build_id": "123456768", | ||
"deploy_target": "deployment_sys_1a", | ||
"perform_deploy": "true" | ||
} | ||
}, | ||
"source": { | ||
"artifactRef": { | ||
"uri": "git+https://github.com/octocat/hello-world@refs/heads/main", | ||
"digest": { "sha1": "c27d339ee6075c1f744c5d4b200f7901aad2c369" } | ||
} | ||
}, | ||
"inputs": { | ||
"mapValue": { | ||
"mascot": "Mona" | ||
} | ||
}, | ||
"workflowPath": { | ||
"scalarValue": ".github/workflow/release.yml" | ||
} | ||
}, | ||
"systemParameters": { | ||
"github": { | ||
"mapValue": { | ||
"actor": "MarkLodato", | ||
"event_name": "workflow_dispatch" | ||
} | ||
} | ||
}, | ||
"resolvedDependencies": [ | ||
{ | ||
"uri": "https://github.com/actions/virtual-environments/releases/tag/ubuntu20/20220515.1" | ||
} | ||
] | ||
}, | ||
"runDetails": { | ||
"builder": { | ||
"id": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/builder_go_slsa3.yml@refs/tags/v0.0.1" | ||
}, | ||
"metadata": { | ||
"invocationId": "https://github.com/octocat/hello-world/actions/runs/1536140711/attempts/1", | ||
"startedOn": "2023-01-01T12:34:56Z" | ||
} | ||
} | ||
}, | ||
"subject": [ | ||
{ | ||
"name": "_", | ||
"digest": { "sha256": "fe4fe40ac7250263c5dbe1cf3138912f3f416140aa248637a60d65fe22c47da4" } | ||
} | ||
] | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,115 @@ | ||
--- | ||
title: "Build Type: GitHub Actions Workflow" | ||
layout: standard | ||
hero_text: | | ||
A [SLSA Provenance](../../provenance/v1) `buildType` that describes the | ||
execution of a GitHub Actions workflow. | ||
--- | ||
|
||
## Description | ||
|
||
This `buildType` describes the execution of a top-level [GitHub Actions] | ||
workflow (as a whole). | ||
|
||
Note: This type is not meant to describe execution of subsets of the top-level | ||
workflow, such as an action, a job, or a reusable workflow. | ||
|
||
[GitHub Actions]: https://docs.github.com/en/actions | ||
|
||
## Build Definition | ||
|
||
### External parameters | ||
|
||
All external parameters are REQUIRED unless empty. | ||
|
||
<table> | ||
<tr><th>Parameter<th>Type<th>Description | ||
|
||
<tr id="inputs"><td><code>inputs</code><td>mapValue<td> | ||
|
||
The [inputs context], with each value converted to string. Every non-empty input | ||
value MUST be recorded. Empty values SHOULD be omitted. | ||
|
||
Note: Only `workflow_dispatch` events and reusable workflows have inputs. | ||
|
||
<tr id="source"><td><code>source</code><td>artifact<td> | ||
|
||
The git repository containing the top-level workflow YAML file. | ||
|
||
This can be computed from the [github context] using | ||
`"git+" + github.server_url + "/" + github.repository + "@" + github.ref`. | ||
|
||
<tr id="vars"><td><code>vars</code><td>vars<td> | ||
|
||
The [vars context], with each value converted to string. Every non-empty input | ||
value MUST be recorded. Empty values SHOULD be omitted. | ||
|
||
<tr id="workflowPath"><td><code>workflowPath</code><td>string<td> | ||
|
||
The path to the workflow YAML file within `source`. | ||
|
||
Note: this cannot be computed directly from the [github context]: the | ||
`github.workflow` context field only provides the *name* of the workflow, not | ||
the path. See [getEntryPoint] for one possible implementation. | ||
|
||
[getEntryPoint]: https://github.com/slsa-framework/slsa-github-generator/blob/ae7e58c315b65aa92b9440d5ce25d795845b3b2a/slsa/buildtype.go#L94-L135 | ||
|
||
</table> | ||
|
||
[github context]: https://docs.github.com/en/actions/learn-github-actions/contexts#github-context | ||
[inputs context]: https://docs.github.com/en/actions/learn-github-actions/contexts#inputs-context | ||
[vars context]: https://docs.github.com/en/actions/learn-github-actions/contexts#vars-context | ||
|
||
### System parameters | ||
|
||
All system parameters are OPTIONAL. | ||
|
||
| Parameter | Type | Description | | ||
| -------------------- | -------- | ----------- | | ||
| `github` | mapValue | A subset of the [github context] as described below. Only includes parameters that are likely to have an effect on the build and that are not already captured elsewhere. | | ||
|
||
The `github` map SHOULD contains the following elements: | ||
|
||
| GitHub Context Parameter | Description | | ||
| ------------------------------- | ----------- | | ||
| `github.mapValue["actor"]` | The username of the user that triggered the initial workflow run. | | ||
| `github.mapValue["event_name"]` | The name of the event that triggered the workflow run. | | ||
|
||
> TODO: What about `actor_id`, `repository_id`, and `repository_owner_id`? Those | ||
> are not part of the context so they're harder to describe, and the repository | ||
> ones should arguably go on the `source` paramater rather than be here. | ||
> | ||
> Also `base_ref` and `head_ref` are similar in that they are annotations about | ||
> `source` rather than a proper parameter. | ||
|
||
> TODO: None of these are really "parameters", per se, but rather metadata | ||
> about the build. Perhaps they should go in `runDetails` instead? The problem | ||
> is that we don't have an appropriate field for it currently. | ||
|
||
### Resolved dependencies | ||
|
||
The resolved dependencies MAY contain any artifacts known to be input to the | ||
workflow, such as the specific versions of the virtual environments used. | ||
|
||
## Run details | ||
|
||
### Metadata | ||
|
||
The `invocationId` SHOULD be set to `github.server_url + "/actions/runs/" + | ||
github.run_id + "/attempts/" + github.run_attempt`. | ||
|
||
## Example | ||
|
||
```json | ||
{% include_relative example.json %} | ||
``` | ||
|
||
Note: The `builder.id` in the example assumes that the build runs under | ||
[slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator). | ||
If GitHub itself generated the provenance, the `id` would be different. | ||
|
||
## Version history | ||
|
||
### v0.1 | ||
|
||
Initial version |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Love having the full URL in here!