provenance.md

Getting Started

To get started, follow the Getting Started section from the main README.

As an example, to run the provenance tool from the tiiuae/sbomnix repository:

# '--' signifies the end of argument list for `nix`.
# '--help' is the first argument to `provenance`
nix run github:tiiuae/sbomnix#provenance -- --help

provenance

provenance is a command line tool to generate SLSA v1.0 compliant provenance attestation files in json format for any nix flake or derivation.

To generate provenance file for nixpkgs#hello:

provenance nixpkgs#hello

To generate provenance file for curl-8.6.0 in your nix store:

provenance /nix/store/fh7vxc5xgiwl6z7vwq5c3lj84mpcs4br-curl-8.6.0-bin

By default the dependencies are resolved only at the top level. ie. only direct dependencies. To get all dependencies recursively, you can use the --recursive option. Note the this will result in a very long provenance file.

The dependencies listed are the nix buildtime dependencies of the derivation.

Example recursive provenance which is saved into a file:

provenance nixpkgs#hello --recursive -out ./provenance.json

Build metadata

The build metadata to be used in the provenance is supplied through environment variables. These fields cannot be automatically derived from the nix derivation as they are build platform dependant.

Variable	Type	Explanation
PROVENANCE_BUILD_TYPE	str	Corresponds to SLSA buildDefinition.buildType
PROVENANCE_BUILDER_ID	str	Corresponds to SLSA runDetails.builder.id
PROVENANCE_INVOCATION_ID	str/int	Corresponds to SLSA buildMetadata.invocationId
PROVENANCE_TIMESTAMP_BEGIN	int (unix timestamp)	Is parsed into SLSA buildMetadata.startedOn
PROVENANCE_TIMESTAMP_FINISHED	int (unix timestamp)	Is parsed into SLSA buildMetadata.finishedOn
PROVENANCE_EXTERNAL_PARAMS	json	Corresponds to SLSA buildDefinition.externalParameters
PROVENANCE_INTERNAL_PARAMS	json	Corresponds to SLSA buildDefinition.internalParameters
PROVENANCE_OUTPUT_FILE	path	Has the same function as the --out argument.

Example usage in a simplified build script:

target="nixpkgs#hello"

PROVENANCE_TIMESTAMP_BEGIN="$(date +%s)"

nix build $target

PROVENANCE_TIMESTAMP_FINISHED="$(date +%s)"

PROVENANCE_EXTERNAL_PARAMS="$(jq -n --arg target "$target" '$ARGS.named')"
PROVENANCE_INTERNAL_PARAMS="$(jq -n --arg nixVersion "$(nix --version)" '$ARGS.named')"

export PROVENANCE_TIMESTAMP_BEGIN
export PROVENANCE_TIMESTAMP_FINISHED
export PROVENANCE_EXTERNAL_PARAMS
export PROVENANCE_INTERNAL_PARAMS

provenance $target --out ./provenance.json