Initial API for Github provenance generation.

[ianlewis]

See #2

[laurentsimon]

Thanks!

I like the breakdown of functionalities.

In case it's useful, here's one design pattern we use in scorecard to share the same arguments for API and CLI https://github.com/ossf/scorecard/blob/main/cmd/root.go#L47 and https://github.com/ossf/scorecard/blob/main/options/options.go

Maybe not be needed, but pointing it out in case you find it useful.

[ianlewis]

Thanks!

I like the breakdown of functionalities.

In case it's useful, here's one design pattern we use in scorecard to share the same arguments for API and CLI https://github.com/ossf/scorecard/blob/main/cmd/root.go#L47 and https://github.com/ossf/scorecard/blob/main/options/options.go

Maybe not be needed, but pointing it out in case you find it useful.

Yeah, cosign and friends do this too. I may get there eventually. Thanks for pointing it out :)

[ianlewis]

BTW, @laurentsimon are we using "The GOSST team" for the copyright headers in these projects?

[ianlewis]

Made a couple of new (hopefully) minor API decisions

• Remove the LogEntry return from Upload so that the signing API is not cosign/rekor specific and will allow us to add interfaces and perhaps support other signers
• Added fields determined by buildType to the WorkflowRun so that users of the API can override SLSA fields that are dependent on buildType if they choose to customize it.

[asraa]

This looks so good! Thank you Ian!

[laurentsimon]

Made a couple of new (hopefully) minor API decisions

• Remove the LogEntry return from Upload so that the signing API is not cosign/rekor specific and will allow us to add interfaces and perhaps support other signers
• Added fields determined by buildType to the WorkflowRun so that users of the API can override SLSA fields that are dependent on buildType if they choose to customize it.

"override" means there will be defaults, what will they be?

[ianlewis]

Made a couple of new (hopefully) minor API decisions

• Remove the LogEntry return from Upload so that the signing API is not cosign/rekor specific and will allow us to add interfaces and perhaps support other signers
• Added fields determined by buildType to the WorkflowRun so that users of the API can override SLSA fields that are dependent on buildType if they choose to customize it.

"override" means there will be defaults, what will they be?

Override was maybe the wrong word. "Defaults" are set by NewWorkflowRun which creates a generic WorkflowRun with a proveance-only buildType (https://github.com/slsa-framework/slsa-github-generator@v1). It basically defines the buildType and the dependent fields. Language specific builders would probably want to set their own buildType and either modify fields on the returned WorkflowRun from NewWorkflowRun, create their own version of the function, or otherwise create the WorkflowRun themselves since they would be specifying the buildType and the format of fields that are determined by the buildType (invocation, buildConfig, materials). That is because they have more specialized knowledge about the build.
HostedActionsProvenance won't have default values.

https://github.com/slsa-framework/slsa-github-generator/pull/3/files#diff-e8bae1665df5da39dc685be0a7688695ceb442878e6b76345ff46bb34924e3b3R62

It would be nice to have better extension points for other builders to set their own buildType and override specific bits like environment, or materials but I feels like it's already complicated enough.

At least, that was my thinking.

The simplest way to use it would be something like:

r := slsa.NewWorkflowRun(subjects, githubContext)
r.BuildType = golangSpecificBuildType
r.BuildConfig = /* custom Go builder config (steps etc.) */
p, _ := slsa.HostedActionsProvenance(r)
/* sign and upload */

[laurentsimon]

slsa-github-generator

Made a couple of new (hopefully) minor API decisions

• Remove the LogEntry return from Upload so that the signing API is not cosign/rekor specific and will allow us to add interfaces and perhaps support other signers
• Added fields determined by buildType to the WorkflowRun so that users of the API can override SLSA fields that are dependent on buildType if they choose to customize it.

"override" means there will be defaults, what will they be?

Override was maybe the wrong word. "Defaults" are set by NewWorkflowRun which creates a generic WorkflowRun with a proveance-only buildType (https://github.com/slsa-framework/slsa-github-generator@v1). It basically defines the buildType and the dependent fields. Language specific builders would probably want to set their own buildType and either modify fields on the returned WorkflowRun from NewWorkflowRun, create their own version of the function, or otherwise create the WorkflowRun themselves since they would be specifying the buildType and the format of fields that are determined by the buildType (invocation, buildConfig, materials). That is because they have more specialized knowledge about the build. HostedActionsProvenance won't have default values.

https://github.com/slsa-framework/slsa-github-generator/pull/3/files#diff-e8bae1665df5da39dc685be0a7688695ceb442878e6b76345ff46bb34924e3b3R62

It would be nice to have better extension points for other builders to set their own buildType and override specific bits like environment, or materials but I feels like it's already complicated enough.

At least, that was my thinking.

The simplest way to use it would be something like:

r := slsa.NewWorkflowRun(subjects, githubContext)
r.BuildType = golangSpecificBuildType
r.BuildConfig = /* custom Go builder config (steps etc.) */
p, _ := slsa.HostedActionsProvenance(r)
/* sign and upload */

Let's start with this, it's simple and is flexible to test in various scenarios/use cases.

[laurentsimon]

At least, that was my thinking.
The simplest way to use it would be something like:

r := slsa.NewWorkflowRun(subjects, githubContext)
r.BuildType = golangSpecificBuildType
r.BuildConfig = /* custom Go builder config (steps etc.) */
p, _ := slsa.HostedActionsProvenance(r)
/* sign and upload */

Let's start with this, it's simple and is flexible to test in various scenarios/use cases.

Just a last-minute thought. We could also have WithXXX() functions, which may be simple too:

r := slsa.NewWorkflowRun(subjects, githubContext)
       .WithBuildType("some_string")
       .WithBuildConfig(some_struct)

func (self * WorkflowRun) WithBuildConfig(arg interface{}) *WorkflowRun{
  self.BuildConfig = arg
  return self
}

Can do that in a follow-up PR if we want

[laurentsimon]

@ianlewis let us know when you've taken notes of the latest comments, and we'll merge. Thanks!

[ianlewis]

At least, that was my thinking.
The simplest way to use it would be something like:

r := slsa.NewWorkflowRun(subjects, githubContext)
r.BuildType = golangSpecificBuildType
r.BuildConfig = /* custom Go builder config (steps etc.) */
p, _ := slsa.HostedActionsProvenance(r)
/* sign and upload */

Let's start with this, it's simple and is flexible to test in various scenarios/use cases.

Just a last-minute thought. We could also have WithXXX() functions, which may be simple too:

r := slsa.NewWorkflowRun(subjects, githubContext)
       .WithBuildType("some_string")
       .WithBuildConfig(some_struct)

func (self * WorkflowRun) WithBuildConfig(arg interface{}) *WorkflowRun{
  self.BuildConfig = arg
  return self
}

Can do that in a follow-up PR if we want

BuildConfig is empty so this works but I think the use cases for others will often be to alter individual fields rather than set the full value (Materials, Environment, etc.) so I'm not sure this pattern really holds. I think we need some more time to see how it will actually be used.

[laurentsimon]

func (self * WorkflowRun) WithBuildConfig(arg interface{}) *WorkflowRun{
  self.BuildConfig = arg
  return self
}

Can do that in a follow-up PR if we want

BuildConfig is empty so this works but I think the use cases for others will often be to alter individual fields rather than set the full value (Materials, Environment, etc.) so I'm not sure this pattern really holds. I think we need some more time to see how it will actually be used.

Maybe AddMaterial() and AddEnvironment() would work. Let's just file an issue for later discussion

[ianlewis]

I think we're good to merge from my end.

[ianlewis]

Maybe AddMaterial() and AddEnvironment() would work. Let's just file an issue for later discussion

Filed #13

[laurentsimon]

Merging, thanks @ianlewis !