Skip to content
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
merged 47 commits into from
Jan 20, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
47 commits
Select commit Hold shift + click to select a range
b20437c
WIP
MarkLodato Oct 20, 2022
2a3eb61
WIP: finished proto for v1.0
MarkLodato Oct 21, 2022
ad7e823
WIP: inputArtifacts, parameters
MarkLodato Oct 21, 2022
cdecf52
WIP
MarkLodato Oct 25, 2022
2ef3659
WIP: apply feedback
MarkLodato Oct 27, 2022
e7dd1e0
WIP: replace proto extension with Markdown link
MarkLodato Oct 27, 2022
c3089de
Update example to use latest version of proto
MarkLodato Oct 28, 2022
25c78c3
artifacts: go back to map, uri
MarkLodato Oct 28, 2022
1015166
WIP: topLevelInputs and buildDependencies
MarkLodato Oct 31, 2022
861d844
WIP: make examples more realistic
MarkLodato Oct 31, 2022
f499fad
WIP: add cue file
MarkLodato Oct 31, 2022
cec3785
WIP: add Tekton example and TODO
MarkLodato Oct 31, 2022
82a3c28
WIP: merge everything into markdown file
MarkLodato Nov 1, 2022
df6bec9
WIP: remove extra divs
MarkLodato Nov 1, 2022
668f41a
WIP: rewrite intro
MarkLodato Nov 1, 2022
5a96d3a
WIP: rename Artifact to ArtifactReference
MarkLodato Nov 1, 2022
c397e76
Use headings in change history
MarkLodato Nov 1, 2022
f1adaf3
Make draft URL work
MarkLodato Nov 1, 2022
f5a4b06
fix lint errors
MarkLodato Nov 1, 2022
b661ee1
Address PR feedback
MarkLodato Nov 4, 2022
5aab59b
Add builderDependencies
MarkLodato Nov 7, 2022
78ae06f
WIP: lowercase purl, move TODO
MarkLodato Nov 9, 2022
11459e6
WIP
MarkLodato Nov 11, 2022
5d1e791
WIP: refactor - external vs system parameters
MarkLodato Nov 14, 2022
32f9d2f
Merge branch 'main' into provenance-refactor
MarkLodato Nov 15, 2022
d044c3d
WIP: fix typo in URL
MarkLodato Nov 15, 2022
3ae85a9
WIP: add todo
MarkLodato Nov 15, 2022
e60f742
Use the generic SLSA generator for the example.
MarkLodato Nov 15, 2022
479b7b3
Make builder.version a map
MarkLodato Nov 30, 2022
9ca7346
Replace .artifacts[name] with [name].artifact.
MarkLodato Nov 30, 2022
d63f6ba
Replace map with array of name/value pairs
MarkLodato Nov 30, 2022
03a0660
Revert "Replace map with array of name/value pairs"
MarkLodato Dec 8, 2022
0ca0d69
Update provenance build model
MarkLodato Jan 4, 2023
8b32358
Merge branch 'main' into provenance-refactor
MarkLodato Jan 4, 2023
622c0b5
Disable lint for blank lines betwen blockqutoes
MarkLodato Jan 4, 2023
77d5814
proto nits: consistent required/optional syntax
MarkLodato Jan 4, 2023
a18326b
More iteration on model
MarkLodato Jan 5, 2023
3b728b4
Move github actions to separate file; revise text
MarkLodato Jan 6, 2023
a4494fb
Only include major version in provenance URL.
MarkLodato Jan 6, 2023
31094f7
WIP: move to Markdown
MarkLodato Jan 18, 2023
472ba94
Finish Markdown conversion, add other param types
MarkLodato Jan 18, 2023
fdce758
address comments
MarkLodato Jan 18, 2023
268a64d
Merge branch 'main' into provenance-refactor
MarkLodato Jan 18, 2023
aba878e
fix mdlint
MarkLodato Jan 18, 2023
1987abf
add TODO about creating other build types
MarkLodato Jan 19, 2023
40aeb77
Fix typos in provenance v1.0
MarkLodato Jan 20, 2023
4210074
drop .md from link
MarkLodato Jan 20, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .markdownlint.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ MD025:
# Disable checking of YAML frontmatter.
front_matter_title: ""

# MD028/no-blanks-blockquote - Blank line inside blockquote
MD028: false

# MD029/ol-prefix - Ordered list item prefix
MD029:
# List style
Expand Down
12 changes: 12 additions & 0 deletions docs/_data/versions.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,10 @@ provenance:
v0.2:
name: Version 0.2
status: Stable
v1:
name: Version 1.0 (DRAFT)
draft: true
status: Working Draft
current: v0.2

verification_summary:
Expand All @@ -45,3 +49,11 @@ verification_summary:
name: Version 0.2
status: Stable
current: v0.2

github-actions-workflow:
versions:
v0.1:
name: Version 0.1 (DRAFT)
draft: true
status: Working Draft
current: v0.1
59 changes: 59 additions & 0 deletions docs/github-actions-workflow/v0.1/example.json
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",
Copy link
Contributor

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!

"startedOn": "2023-01-01T12:34:56Z"
}
}
},
"subject": [
{
"name": "_",
"digest": { "sha256": "fe4fe40ac7250263c5dbe1cf3138912f3f416140aa248637a60d65fe22c47da4" }
}
]
}
115 changes: 115 additions & 0 deletions docs/github-actions-workflow/v0.1/index.md
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
Loading