externalParameters are the inputs to a build that come from outside the build platform, such as a repository, a branch or a workflow file. SLSA treats them as untrusted, so the provenance must record them and a consumer must verify them. The platform's own settings are a different field.
If you only check that provenance exists and is signed, you can miss the field that tells you what a person actually asked the builder to do.
Where the field lives
In the SLSA v1.1 provenance format, buildDefinition holds the inputs and runDetails describes the run. Inside buildDefinition you find four items:
| Field | Who controls it | Trust level |
|---|---|---|
| buildType | The template for how the build runs | Identifies the template, with docs |
| externalParameters | Users and callers | Untrusted, must be verified |
| internalParameters | The build platform | Trusted, optional |
| resolvedDependencies | Fetched during the build | Best effort completeness |
The spec text says external parameters MUST be included in the provenance and MUST be verified downstream. That is strong wording for a spec that is otherwise flexible.
Why untrusted
Anyone who can start a build can influence these values. If a build can be pointed at an unusual repository or an unexpected workflow, the provenance will faithfully record that. A valid signature on provenance that says "built from a stranger's fork" is still a valid signature.
The SLSA threats overview lists modified external build parameters as a way to publish software that was not built from the purported sources. Recording the values is only useful if someone compares them with what was expected.
What a verifier should do
The verification page says the expectations should cover at least the builder identity, the canonical source repository, the build type and the external parameters. It also says verifiers should reject unrecognized fields in externalParameters. A parameter may allow a range of values if every value in that range is known to be safe.
A practical approach:
- Write down the full list of parameters your pipeline legitimately passes.
- Decide the allowed value or range for each, such as one repository and a protected branch pattern.
- Fail verification when a parameter is missing, new or out of range.
- Review the list whenever the pipeline definition changes.
What you do not need to verify
The provenance page says there is no need to verify internalParameters, because the platform is already trusted. They are useful for debugging and incident response, and sometimes for reproducing a build. Spend your checking effort on external inputs.
Common mistakes
Teams commonly verify the signature and the subject digest, then stop. Others accept any value for a parameter such as a branch name because the field "looks like metadata." Both leave a gap.
A related error is writing expectations once and never revisiting them. When a new workflow input is added, verification should fail until someone approves it. That failure is the control working.
Safeguard's policies and gates can enforce rules on pull requests and dependencies, which complements checking build inputs at deploy time. You can start with the free scan at https://gold.safeguard.sh/scan.
Quick check
Are externalParameters signed by the builder?
They are recorded in the provenance, which the builder signs. The values themselves still originate outside the platform, so they remain untrusted.
Should I verify internalParameters too?
The spec says there is no need, because the platform is already trusted.
Sources
- SLSA v1.1 provenance (page marked retired, v1.2 is current)
- SLSA v1.1 verifying artifacts
- SLSA v1.1 threats overview
Last reviewed: 19 October 2026.
