Discussion on the various fields of provenance metadata and ways to fill them

[adityasaky]

Moved from jenkinsci#32, cc @lakshya8066

What feature do you want to see added?

This issue is to discuss how to fill data in the provenance metadata. These are more elaborately described here https://slsa.dev/provenance/v0.1
The fields that need attention are listed below:

Builder

builder(object, required): This identifies the trusted entity that will run all the steps and fill the details in the provenance.
builder.id(string, required): This will indicate the builder’s identity.

Recipe

recipe(object): This will denote the steps and configuration used for the build. Along with the materials, this will completely describe the build.
recipe.type(string): This will describe the type of the recipe that was performed. This will also determine recipe.entryPoint, recipe.argument, recipe.environment and materials.
recipe.defineInMaterials(integer): If the recipe comes from material this will contain the index containing the recipe steps.
recipe.entrypoint(string): This will be a string identifying the entry point into the build. The syntax and meaning will be defined by recipe.type.
recipe.arguments(object): This will be a JSON object containing all the external inputs that were used in the build along with recipe.definedInMaterials and recipe.entryPoint. This will be considered complete only when metadata.completeness.arguments is set to true.
recipe.environments(object): This will be an arbitrary JSON object which contains any other controls that are needed by the builder to execute the recipe. This is generally needed for reproducing the build.

Metadata

metadata(object): This object will contain properties of the build.
metadata.buildInvocationId(string): This is a globally unique value that identifies that particular build invocation. This is treated as opaque and case-sensitive by default.
metadata.buildStartedOn(string): This gives the timestamp of when the build started.
metadata.buildFinishedOn(string): This gives the timestamp of when the build is completed.
metadata.completeness(object): This is an object that indicates that the builder claims certain fields in this message to be complete.
metadata.completeness.arguments(boolean): This states whether the builder claims whether all the external inputs are properly captured in the recipe or not.
metadata.completeness.environment(boolean): If the value of this is true then the builder claims that recipe.environment is complete.
metadata.completeness.materials(boolean): If the value of this is true then the builder claims that materials is complete.
metadata.reproducible(boolean): If this is true then the builder claims that if the user runs all the steps in the recipe on materials then the output produced will be identical.

Materials:

materials(array of objects): This array of objects includes the artifacts that are part of the build. These include dependencies, images, tools.
materials[*].uri(string): This is the method that will be used to reference the artifact during the build.
materials[*].digest(object): This is the set of cryptographic digest expressed as a JSON map from algorithm name to lowercase hex-encoded value.

Upstream changes

No response

[lakshya8066]

I was looking at materials and I think we already have a function for link metadata that collects Artifacts URI and creates a sha256 hash for them. We can extracts data from the output of this function and put it into provenance metadata.

[lakshya8066]

@adityasaky we should update the description with provenance v02 changes

What feature do you want to see added?

This issue is to discuss how to fill data in the provenance metadata. These are more elaborately described here https://slsa.dev/provenance/v0.2
The fields that need attention are listed below:

Builder

builder(object, required): This identifies the trusted entity that will run all the steps and fill the details in the provenance.
builder.id(string, required): This will indicate the builder’s identity.

buildType

URI indicating what type of build was performed. It determines the meaning of invocation, buildConfig and materials.

Invocation

invocation(object): Identifies the event that kicked off the build. When combined with materials, this SHOULD fully describe the build, such that re-running this invocation results in bit-for-bit identical output
invocation.configSource(object): Describes where the config file that kicked off the build came from. This is effectively a pointer to the source where buildConfig came from.
invocation.configSource.uri(string): URI indicating the identity of the source of the config.
invocation.configSource.digest(DigestSet): Collection of cryptographic digests for the contents of the artifact specified by invocation.configSource.uri.
invocation.configSource.entryPoint(string): String identifying the entry point into the build. This is often a path to a configuration file and/or a target label within that file. The syntax and meaning are defined by buildType.
invocation.parameters(object): Collection of all external inputs that influenced the build on top of invocation.configSource.
invocation.environment(object): This SHOULD be minimized to only include things that are part of the public API, that cannot be recomputed from other values in the provenance, and that actually affect the evaluation of the build.

Metadata

metadata(object): This object will contain properties of the build.
metadata.buildInvocationId(string): This is a globally unique value that identifies that particular build invocation. This is treated as opaque and case-sensitive by default.
metadata.buildStartedOn(string): This gives the timestamp of when the build started.
metadata.buildFinishedOn(string): This gives the timestamp of when the build is completed.
metadata.completeness(object): This is an object that indicates that the builder claims certain fields in this message to be complete.
metadata.completeness.parameters(boolean): This states whether the builder claims whether all the external inputs are properly captured in the recipe or not.
metadata.completeness.environment(boolean): If the value of this is true then the builder claims that recipe.environment is complete.
metadata.completeness.materials(boolean): If the value of this is true then the builder claims that materials is complete.
metadata.reproducible(boolean): If this is true then the builder claims that if the user runs all the steps in the recipe on materials then the output produced will be identical.

buildConfig (object)

Lists the steps in the build. If invocation.configSource is not available, buildConfig can be used to verify information about the build.

Materials:

materials(array of objects): This array of objects includes the artifacts that are part of the build. These include dependencies, images, tools.
materials[*].uri(string): This is the method that will be used to reference the artifact during the build.
materials[*].digest(object): This is the set of cryptographic digest expressed as a JSON map from algorithm name to lowercase hex-encoded value.

Upstream changes

No response