A SLSA provenance file has two parts: buildDefinition, which says what was built and from which inputs, and runDetails, which says which platform ran the build and when. Read the subject digest, the builder id, the buildType and the externalParameters first. Those four carry most of the trust decision.
Where the file sits
SLSA provenance is the predicate of an in-toto Statement. The Statement carries the subject, which names the artifact by digest. The predicate type is https://slsa.dev/provenance/v1. The envelope around it carries the signature.
So a full read has three layers: the signature (is this authentic), the subject (is this about my artifact), and the predicate (how was it built).
buildDefinition
| Field | Meaning | Verify it? |
|---|---|---|
| buildType | A URI naming the template for how to interpret the build's parameters | Yes, compare to the type you expect |
| externalParameters | Inputs controlled from outside the platform, such as a repository, ref or workflow | Yes, and reject fields you do not recognise |
| internalParameters | Inputs set by the platform, useful for debugging and incident response | No, not required |
| resolvedDependencies | Artifacts fetched at build time | Partial, as available |
The spec says that at Build L3 the externalParameters must be complete, and verification tools should reject unrecognised fields in them. That rule matters: an extra, unexpected parameter is exactly where injected behaviour would hide.
runDetails
The builder object holds an id URI, which identifies the platform and is what a verifier looks up to decide the Build level. It can also list a version map and builder dependencies. The metadata object can hold an invocationId, startedOn and finishedOn, which help you find the logs. Byproducts lists extra artifacts such as logs.
Only the builder id is required for Build L1. Metadata fields are all optional.
A reading order that works
- Check the envelope signature against roots of trust you chose.
- Confirm the subject digest equals the digest of the file you have.
- Look up the builder id in your list of trusted builders.
- Compare buildType and externalParameters to what the project is supposed to use, including the canonical source repository.
- Glance at resolvedDependencies and the timestamps for anything odd.
Comparing the source repository is the step that catches a build from an unofficial fork. A valid signature from a trusted builder does not help if the repository named in externalParameters is not the one you expect.
What the file does not tell you
Provenance is a claim that an artifact was built, not that it was published to a given registry. It also says nothing about whether the source code was reviewed or whether a dependency is vulnerable. Pair it with scanning for those questions.
Where Safeguard fits
Safeguard's SBOM and dependency scanning covers the dependency side of the picture that resolvedDependencies only partly describes, and reachability analysis helps rank what matters. You can start with the free scan.
Quick check
Which provenance fields are required?
For Build L1, buildDefinition (with buildType and externalParameters) and runDetails (with builder id) are required. Internal parameters, dependencies and metadata are optional.
Is the subject part of the predicate?
No. The subject belongs to the surrounding in-toto Statement, not to the provenance predicate.
Sources
Last reviewed: 19 October 2026.
