Sign Build Provenance with DevGuard
This guide wires up the SLSA control plane: your pipeline describes what it built, DevGuard verifies which build configuration ran and signs the provenance with a key no CI job ever sees, and the signed attestation is attached to your container image.
The only thing DevGuard needs from your build platform is an OIDC workload identity token whose claims identify the build configuration that is running. The steps below are the same everywhere — only requesting that token differs per platform. DevGuard currently maps the claims of GitHub Actions and GitLab CI tokens.
Prerequisites
- A DevGuard asset and a Personal Access Token, as for any scan
- A DevGuard instance with a provenance signing key configured (see Configuring the instance)
- A build platform that issues OIDC workload identity tokens to its jobs
| Variable | Value |
|---|---|
DEVGUARD_TOKEN | Your PAT private key |
DEVGUARD_ASSET_NAME | e.g. @myorg/projects/backend/assets/api |
Step 1: Build and generate provenance
Build and push your image, then generate an unsigned SLSA provenance statement for it with provenance generate. The statement names the image by its manifest digest, so it matches exactly the image it is attached to later.
For this walkthrough we stand in a small public image for whatever your pipeline builds:
Building files instead of an image, for example release tarballs? Pass them with --path dist/app-linux-amd64.tar.gz — they are hashed and recorded under their file name. Both flags take a comma separated list.
What you get out of this
build.provenance.json is an in-toto v1 statement with a SLSA v1 provenance predicate. It only contains what your job knows itself:
Reading it field by field:
subject— your--imageand--pathvalues, by name and digest. This is the claim the whole attestation hangs off: these exact bytes came out of this build. It is passed through to the signed statement untouched, so make it precise.externalParameters.inputs— the--input key=valuepairs, for the parameters your workflow was called with.buildType— tells a verifier how to read the build definition.runDetails.metadata— added when you pass--startedOnand--finishedOnas RFC3339 timestamps.
Everything describing the build platform — the builder, the workflow, the source repository and commit — is deliberately missing. A pipeline is not trusted to name itself, so DevGuard fills those fields in from the verified workload identity token in step 3.
Nothing is signed yet.
Step 2: Request a workload identity token
The token must be issued for the audience of the DevGuard API. devguard-scanner provenance sign reads it from DEVGUARD_ID_TOKEN, or from --idToken.
The audience must match the DevGuard instance you are signing against — its SLSA_OIDC_AUDIENCE, or its API_URL if that is not set. A token issued for a different audience is rejected.
GitHub Actions
Grant the job id-token: write and ask the runner for a token. The claim DevGuard pins the builder to is job_workflow_ref, which names the workflow that ran the job:
GitLab CI
Request the token with the id_tokens keyword, under the name the scanner expects:
Any other platform
Any build platform that mints OIDC tokens for its jobs works the same way: request a token for the DevGuard API as audience and expose it as DEVGUARD_ID_TOKEN. DevGuard verifies it against the issuer's published keys. Support for a platform is a claim mapping in DevGuard — the token has to say which build configuration ran, so that verifiers have something to pin against.
Step 3: Let DevGuard sign
DevGuard verifies the token against its issuer, then replaces every identity-bearing field of the provenance — runDetails.builder.id, the commit of the build configuration, the invocation URL, the source repository and commit, and the full set of verified claims under buildDefinition.internalParameters.devguard.workloadIdentity. Your subjects and build description are kept as sent.
The output is a DSSE envelope, or a sigstore bundle if the instance uploads to a transparency log. Pass - as the argument to read the provenance from stdin instead of a file.
Step 4: Attach it to the image
attest detects that the input is already signed and attaches it as-is, without signing it again — the signature stays DevGuard's.
The predicate type must match the one inside the signed statement, or the command fails rather than attaching a mislabelled attestation. The attestation is also uploaded to DevGuard; add --offline to skip that.
Step 5: Verify
Fetch the public key DevGuard signs with, and verify the attestation on the image:
--insecure-ignore-tlog is needed when the instance has no transparency log configured (SLSA_REKOR_URL) — there is no log entry to look up. Drop it once a log is in place.
A valid signature only tells you that this provenance really came from the build configuration it names. Your policy still has to decide whether that configuration is one you trust:
Pin that value — including its iss query parameter — to the trusted builder, and reject anything else. See what the signature means for the full verification rule.
Step 6: Move the build to a trusted builder
Everything above already keeps the signing key out of your pipeline. To get provenance that the project's own maintainers cannot forge, the build — and the job holding the token — has to run from a build configuration they cannot modify.
On GitHub Actions this is a reusable workflow in a protected repository. job_workflow_ref then names that workflow rather than the caller's, so builder.id points at the trusted configuration with no further scaffolding.
On GitLab CI there is no equivalent: an included component or template still runs under the calling project's configuration and gets the calling project's token. Trigger a pipeline in a separate, protected project instead:
That project runs steps 1–4 and is the only place a token is ever requested. Its ci_config_ref_uri is out of the triggering project's reach, so verifiers can pin builder.id to it.
For SLSA Build L3 the trusted builder additionally needs isolated, ephemeral runners: one fresh environment per build, no influence between runs, no access to platform secrets.
Configuring the instance
Self-hosted DevGuard instances need the signing side configured:
| Variable | Purpose |
|---|---|
SLSA_PRIVATE_KEY_PATH | PEM-encoded ECDSA signing key. Defaults to INTOTO_PRIVATE_KEY_PATH, then /slsa-private-key.pem. Without it, signing is disabled. |
SLSA_OIDC_AUDIENCE | Expected audience of workload identity tokens. Falls back to API_URL; if neither is set, every token is rejected. |
SLSA_OIDC_TRUSTED_ISSUERS | Comma-separated allowlist of OIDC issuers. |
SLSA_REKOR_URL | Transparency log to upload signed provenance to. Optional; without it, the response is a bare DSSE envelope. |
Generate a signing key with:
Leaving SLSA_OIDC_TRUSTED_ISSUERS empty accepts tokens from any https issuer, which lets anyone running their own OIDC provider obtain provenance naming any builder. Set it on any instance where this matters.