Provenance v1.0: initial draft #525

MarkLodato · 2022-11-01T21:46:22Z

This is an initial draft v1.0 for the provenance format. It attempts to address the major sources of confusion with the current format (v0.2), particularly the separation of concerns between top-level external inputs, resolved dependencies, and per-run details.

There are still many TODOs. I hope to get this merged sooner rather than later so that we can get feedback on the schema and substance, then send further PRs to address the remaining TODOs.

(I'll rewrite the history before merging so that it's not full of all my "WIP" commits.)

Preview: https://deploy-preview-525--slsa.netlify.app/provenance/v1/

Signed-off-by: Mark Lodato <lodato@google.com>

Move all top-level inputs to their own field so that it is clear what must be verified. Move resolvedDependencies outside since it's not top-level. Create new buildDependencies containing resolvedDependencies and environment. This way buildDefinition is complete. Revert field names to their v0.2 names, since the name change isn't worth the switch. Signed-off-by: Mark Lodato <lodato@google.com>

Signed-off-by: Mark Lodato <lodato@google.com>

netlify · 2022-11-01T21:46:27Z

✅ Deploy Preview for slsa ready!

Name	Link
🔨 Latest commit	`4210074`
🔍 Latest deploy log	https://app.netlify.com/sites/slsa/deploys/63cad744a0262e0008a3f816
😎 Deploy Preview	https://deploy-preview-525--slsa.netlify.app/provenance/v1
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

Signed-off-by: Mark Lodato <lodato@google.com>

joshuagl

This is looking really good. I did a first pass review and added some minor observations and comments.

docs/provenance/v1.0.md

docs/provenance/v1.0.proto

Signed-off-by: Mark Lodato <lodato@google.com>

docs/provenance/v1.0.md

docs/provenance/v1.0.proto

docs/provenance/v1.0.md

Signed-off-by: Mark Lodato <lodato@google.com>

docs/provenance/v1.0.proto

docs/provenance/v1.0.cue

docs/github-actions-workflow/v0.1/example.json

Also move to a subdirectory (1) since we now have multiple files and (2) to make relative includes work correclty whether or not the URL has a trailing slash. Signed-off-by: Mark Lodato <lodato@google.com>

docs/provenance/v1.0.proto

jagathprakash · 2023-01-17T19:57:03Z

docs/provenance/v1.0.proto

+  // TODO: Flesh out this model more.
+  //
+  // OPTIONAL.
+  repeated ArtifactReference builderDependencies = 3;


A CI pipeline's binaries could be categorized in 2 ways.

The list of orchestrator tools like Tekton Pipeline, TektonChains, TektonTriggers...

The list of actual tools which make the build like gcc.
Should this tools from only from (1) or even (2).

This should only be (1). (2) should go in resolvedDependencies. Do you have a suggestion to make that more clear?

docs/provenance/v1.0.proto

docs/github-actions-workflow/v0.1/example.json

Signed-off-by: Mark Lodato <lodato@google.com>

MarkLodato

OK everyone, thanks for the very helpful feedback! I'm hoping to get this merged this week, so if you could review end-of-day Friday (US Eastern), that would be appreciated!

There are still many TODOs and outstanding issues, particularly on the design of the parameters. The intention is that we submit this and iterate. By having it checked in, we can more easily get feedback from potential implementers.

Preview: https://deploy-preview-525--slsa.netlify.app/provenance/v1/

NOTES:

I aggressively marked GitHub comment threads as "resolved" in order to reduce noise. I did my best to try to capture the intent either as a TODO or actually implementing it. Feel free to reopen threads, though the UI doesn't make that particularly easy...
I reorganized a bit and changed around the documentation format. Please take a look. I'm hoping this new format is now easier to follow. (The reason for moving under a directory is to make it easier to have related files, and the reason for dropping the ".0" from the URL is that is what our documentation says we would do, since minor version bumps are backwards compatible.)

Thanks all!

docs/github-actions-workflow/v0.1/example.json

docs/provenance/v1.0.md

docs/_data/versions.yml

docs/github-actions-workflow/v0.1/example.json

MarkLodato · 2023-01-18T21:27:28Z

docs/github-actions-workflow/v0.1/example.json

+                        "digest": { "sha1": "c27d339ee6075c1f744c5d4b200f7901aad2c369" }
+                    }
+                },
+                "workflow_path": { "value": ".github/workflow/release.yml" }


Is this thread OK to resolve, or is there a specific request here (hard to follow thread)?

docs/provenance/v1.0.proto

MarkLodato · 2023-01-18T21:39:52Z

docs/provenance/v1.0.proto

+  // TODO: Flesh out this model more.
+  //
+  // OPTIONAL.
+  repeated ArtifactReference builderDependencies = 3;


This should only be (1). (2) should go in resolvedDependencies. Do you have a suggestion to make that more clear?

docs/provenance/v1.0.proto

docs/provenance/v1.0.md

Signed-off-by: Mark Lodato <lodato@google.com>

trishankatdatadog

Looks good to me, thanks very much! Could we please ask another CI provider (e.g., GitLab) to contribute their own Build Type to make sure that we have designed a general enough Build Provenance?

Signed-off-by: Mark Lodato <lodato@google.com>

MarkLodato · 2023-01-19T16:31:10Z

Looks good to me, thanks very much! Could we please ask another CI provider (e.g., GitLab) to contribute their own Build Type to make sure that we have designed a general enough Build Provenance?

Good point. Added TODO noting that it's a blocker for calling it stable.

trishankatdatadog · 2023-01-20T15:10:22Z

Good point. Added TODO noting that it's a blocker for calling it stable.

Approved, but shouldn't hang on my opinion alone 🙂

joshuagl

This is a fantastic evolution of the provenance format. Thanks for calling out the bits that would especially benefit from feedback with the "RFC" markers.

I fully support merging this as-is and iterating in tree. I have made a few minor suggestions to fix some of the links, otherwise LGTM.

docs/provenance/v1/provenance.cue

docs/provenance/v1/index.md

Signed-off-by: Mark Lodato <lodato@google.com>

MarkLodato · 2023-01-20T15:49:06Z

Thanks. I fixed all those issues, I think. I'll do a "squash and merge", but I'll leave this open for a bit for you to verify if you have time.

joshuagl

LGTM

docs/provenance/v1/index.md

Signed-off-by: Mark Lodato <lodato@google.com>

MarkLodato · 2023-01-20T18:10:33Z

Thanks all! This is now squashed and merged, but please continue to provide feedback and suggestions.

feelepxyz · 2023-01-24T11:47:26Z

docs/github-actions-workflow/v0.1/example.json

+                "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",


Love having the full URL in here!

This is an initial draft v1.0 for the provenance format. It attempts to address the major sources of confusion with v0.2, particularly the separation of concerns between top-level external inputs, resolved dependencies, and per-run details. There are still many outstanding TODOs and unresolved design decisions. The idea is to submit this now so that we can more easily get feedback on the schema and substance, then send further PRs to address the remaining TODOs and RFCs. Signed-off-by: Mark Lodato <lodato@google.com>

MarkLodato added 18 commits November 1, 2022 15:54

WIP

b20437c

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: finished proto for v1.0

2a3eb61

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: inputArtifacts, parameters

ad7e823

Signed-off-by: Mark Lodato <lodato@google.com>

WIP

cdecf52

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: apply feedback

2ef3659

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: replace proto extension with Markdown link

e7dd1e0

Signed-off-by: Mark Lodato <lodato@google.com>

Update example to use latest version of proto

c3089de

Signed-off-by: Mark Lodato <lodato@google.com>

artifacts: go back to map, uri

25c78c3

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: make examples more realistic

861d844

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: add cue file

f499fad

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: add Tekton example and TODO

cec3785

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: merge everything into markdown file

82a3c28

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: remove extra divs

df6bec9

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: rewrite intro

668f41a

Signed-off-by: Mark Lodato <lodato@google.com>

WIP: rename Artifact to ArtifactReference

5a96d3a

Signed-off-by: Mark Lodato <lodato@google.com>

Use headings in change history

c397e76

Signed-off-by: Mark Lodato <lodato@google.com>

Make draft URL work

f1adaf3

Signed-off-by: Mark Lodato <lodato@google.com>

fix lint errors

f5a4b06

Signed-off-by: Mark Lodato <lodato@google.com>

ianlewis mentioned this pull request Nov 4, 2022

[discussion] Revisit inputs. slsa-framework/slsa-github-generator#1200

Open

joshuagl reviewed Nov 4, 2022

View reviewed changes

Address PR feedback

b661ee1

Signed-off-by: Mark Lodato <lodato@google.com>

laurentsimon reviewed Nov 5, 2022

View reviewed changes

docs/provenance/v1.0.md Outdated Show resolved Hide resolved

docs/provenance/v1.0.md Outdated Show resolved Hide resolved

rbehjati reviewed Nov 7, 2022

View reviewed changes

docs/provenance/v1.0.md Outdated Show resolved Hide resolved

docs/provenance/v1.0.proto Outdated Show resolved Hide resolved

asraa reviewed Nov 7, 2022

View reviewed changes

docs/provenance/v1.0.md Outdated Show resolved Hide resolved

Add builderDependencies

5aab59b

Signed-off-by: Mark Lodato <lodato@google.com>

MarkLodato force-pushed the provenance-refactor branch from f87271e to 5aab59b Compare November 7, 2022 18:20

WIP: lowercase purl, move TODO

78ae06f

Signed-off-by: Mark Lodato <lodato@google.com>

kommendorkapten reviewed Nov 10, 2022

View reviewed changes

docs/provenance/v1.0.proto Outdated Show resolved Hide resolved

marcelamelara reviewed Jan 10, 2023

View reviewed changes

docs/provenance/v1.0.cue Outdated Show resolved Hide resolved

laurentsimon reviewed Jan 11, 2023

View reviewed changes

docs/github-actions-workflow/v0.1/example.json Outdated Show resolved Hide resolved

MarkLodato mentioned this pull request Jan 12, 2023

SLSA v1.0: Add "Verifying Build Systems" #568

Merged

ianlewis mentioned this pull request Jan 16, 2023

[feature] SLSA v0.2 support for npm builder slsa-framework/slsa-github-generator#1521

Closed

Only include major version in provenance URL.

a4494fb

Also move to a subdirectory (1) since we now have multiple files and (2) to make relative includes work correclty whether or not the URL has a trailing slash. Signed-off-by: Mark Lodato <lodato@google.com>

jagathprakash reviewed Jan 17, 2023

View reviewed changes

asraa reviewed Jan 18, 2023

View reviewed changes

docs/github-actions-workflow/v0.1/example.json Outdated Show resolved Hide resolved

MarkLodato added 3 commits January 18, 2023 11:49

WIP: move to Markdown

31094f7

Signed-off-by: Mark Lodato <lodato@google.com>

Finish Markdown conversion, add other param types

472ba94

Signed-off-by: Mark Lodato <lodato@google.com>

address comments

fdce758

Signed-off-by: Mark Lodato <lodato@google.com>

MarkLodato commented Jan 18, 2023

View reviewed changes

MarkLodato added 2 commits January 18, 2023 16:48

Merge branch 'main' into provenance-refactor

268a64d

Signed-off-by: Mark Lodato <lodato@google.com>

fix mdlint

aba878e

Signed-off-by: Mark Lodato <lodato@google.com>

trishankatdatadog reviewed Jan 19, 2023

View reviewed changes

add TODO about creating other build types

1987abf

Signed-off-by: Mark Lodato <lodato@google.com>

This was referenced Jan 19, 2023

fix: Unpack config file in BuildDefinition slsa-framework/slsa-github-generator#1547

Merged

Support v1.0 SLSA provenance format in-toto/in-toto-golang#197

Closed

trishankatdatadog approved these changes Jan 20, 2023

View reviewed changes

joshuagl approved these changes Jan 20, 2023

View reviewed changes

Fix typos in provenance v1.0

40aeb77

Signed-off-by: Mark Lodato <lodato@google.com>

joshuagl approved these changes Jan 20, 2023

View reviewed changes

docs/provenance/v1/index.md Outdated Show resolved Hide resolved

drop .md from link

4210074

Signed-off-by: Mark Lodato <lodato@google.com>

MarkLodato merged commit e5cbd09 into slsa-framework:main Jan 20, 2023

MarkLodato deleted the provenance-refactor branch January 20, 2023 18:09

feelepxyz reviewed Jan 24, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Provenance v1.0: initial draft #525

Provenance v1.0: initial draft #525

MarkLodato commented Nov 1, 2022 •

edited

Loading

netlify bot commented Nov 1, 2022 •

edited

Loading

joshuagl left a comment

jagathprakash Jan 17, 2023

MarkLodato Jan 18, 2023

MarkLodato left a comment •

edited

Loading

MarkLodato Jan 18, 2023

MarkLodato Jan 18, 2023

trishankatdatadog left a comment

MarkLodato commented Jan 19, 2023

trishankatdatadog commented Jan 20, 2023

joshuagl left a comment

MarkLodato commented Jan 20, 2023

joshuagl left a comment

MarkLodato commented Jan 20, 2023

feelepxyz Jan 24, 2023

Provenance v1.0: initial draft #525

Provenance v1.0: initial draft #525

Conversation

MarkLodato commented Nov 1, 2022 • edited Loading

netlify bot commented Nov 1, 2022 • edited Loading

✅ Deploy Preview for slsa ready!

joshuagl left a comment

Choose a reason for hiding this comment

jagathprakash Jan 17, 2023

Choose a reason for hiding this comment

MarkLodato Jan 18, 2023

Choose a reason for hiding this comment

MarkLodato left a comment • edited Loading

Choose a reason for hiding this comment

MarkLodato Jan 18, 2023

Choose a reason for hiding this comment

MarkLodato Jan 18, 2023

Choose a reason for hiding this comment

trishankatdatadog left a comment

Choose a reason for hiding this comment

MarkLodato commented Jan 19, 2023

trishankatdatadog commented Jan 20, 2023

joshuagl left a comment

Choose a reason for hiding this comment

MarkLodato commented Jan 20, 2023

joshuagl left a comment

Choose a reason for hiding this comment

MarkLodato commented Jan 20, 2023

feelepxyz Jan 24, 2023

Choose a reason for hiding this comment

MarkLodato commented Nov 1, 2022 •

edited

Loading

netlify bot commented Nov 1, 2022 •

edited

Loading

MarkLodato left a comment •

edited

Loading