DevGuard as SLSA Control Plane

SLSA separates two roles that most pipelines collapse into one:

  • The build platform runs the build. It compiles, tests and produces the artifact.
  • The control plane decides what may be claimed about that build, and signs it.

As long as both roles live inside the same CI job, the person who can change the pipeline can also change what the provenance says and sign it with a key they hold. The provenance becomes a statement the maintainer makes about themselves.

This is exactly where the SLSA Build track draws its lines. From Build L2 provenance "MUST be generated by the control plane" and not by a tenant, signed with a key "accessible only to the build platform component". Build L3 adds that provenance must be "strongly resistant to forgery by tenants" and that builds run in isolated, ephemeral environments.

DevGuard takes over the control plane role: it verifies which build configuration ran, using the build platform's OIDC workload identity, writes that verified identity into the provenance, and signs the result with a key that never leaves DevGuard.


The architecture

The target setup has three parties, and the separation between them is the whole point:

  1. The project — the repository being built. Its maintainers control its source and, for an ordinary pipeline, its CI configuration.
  2. The trusted builder — a build configuration the project's maintainers cannot modify, which performs the build and holds the workload identity.
  3. DevGuard, the control plane — holds the signing key, verifies the builder's workload identity, fills in every identity-bearing field of the provenance, and signs.
Note

The signing key lives on the DevGuard instance (SLSA_PRIVATE_KEY_PATH, default /slsa-private-key.pem). It is never handed to a CI job, and no API endpoint returns it. Pipelines only ever receive the signed result. This satisfies the SLSA requirement that signing material be inaccessible to the environment running user-defined build steps.

What DevGuard needs from a build platform

DevGuard makes no assumptions about how you build. The only thing it requires is a build platform that can issue OIDC workload identity tokens to its jobs, with two properties:

  • The token is minted by the platform, for an audience the job requests but cannot forge.
  • Its claims identify the build configuration that is running — not just the repository, and not something the job itself supplies.

That second property is what carries the trust. The identity in the token is only as meaningful as the configuration it names: if the claim points at a file the project's maintainers can edit, then they can make it say anything, and the resulting provenance is a statement they make about themselves. If it points at a configuration they cannot touch, a verifier can pin to it.

This is why the control plane model works on any such platform — your own build server included, as long as it issues tokens that name a build configuration out of the tenant's reach.

Where platforms differ is only in how they expose that. Some do it natively: GitHub Actions, for instance, mints a token for the reusable workflow a job runs, so a reusable workflow in a protected repository is the trusted builder with no extra scaffolding. Others require a workaround — see the GitLab case.

Independently of the identity, the SLSA L3 isolation requirements apply to wherever the trusted build runs: an ephemeral environment provisioned per build, no influence between overlapping or consecutive runs, no access to platform secrets, no cache poisoning. Those are properties of your runners, not of DevGuard.

The special case: GitLab

GitLab ID tokens carry ci_config_ref_uri, which names the CI config that ran the job. For an ordinary pipeline that is the project's own .gitlab-ci.yml — owned outright by its maintainers. Unlike GitHub's reusable workflows, GitLab has no mechanism that gives an included component or template its own identity: everything the pipeline includes still runs under the project's configuration and gets the project's token.

The workaround is to move the build out of the project entirely. Trigger a multi-project pipeline in a separate, protected project; that pipeline runs under its configuration and receives a workload identity whose ci_config_ref_uri the triggering project's maintainers cannot rewrite. Verifiers pin builder.id to that project's config.

It is more setup than the native case, and the triggering project has to grant the builder what it needs to do its job, but the resulting trust boundary is the same one.


The flow

1. The build produces unsigned provenance

The in-toto start/stop pair records the materials and products of a build step. With --generateSlsaProvenance, stop additionally writes an in-toto v1 statement carrying a SLSA v1 provenance predicate to <step>.provenance.json.

This statement describes what was built: the subjects with their digests, the resolved dependencies, and the external parameters collected by the git, GitHub and GitLab attestors. The build type is https://devguard.org/build-types/in-toto-link/v1.

The builder at this point is only a placeholder — a pipeline is never trusted to name itself.

2. The job proves its identity

The job requests an OIDC ID token from its build platform, with the DevGuard API as the audience. The token is issued by the platform, not by the project: a job can ask for one, but cannot choose what it says.

3. DevGuard verifies and fills in the identity

devguard-scanner provenance sign sends the statement and the token to POST /api/v1/slsa/build-provenance/. DevGuard:

  1. Reads the issuer from the token without trusting it yet, and checks it against the configured allowlist (SLSA_OIDC_TRUSTED_ISSUERS) and that it is an https URL.
  2. Discovers the issuer's OIDC configuration, fetches its JWKS, and verifies signature, audience (SLSA_OIDC_AUDIENCE, falling back to API_URL) and expiry. Verifiers are cached per issuer.
  3. Overwrites every field that describes who built the artifact, discarding whatever the client sent:
Provenance fieldFilled from the verified token
predicate.runDetails.builder.idthe CI config that ran the build, with the issuer appended as ?iss=
predicate.runDetails.builder.version.ciConfigShathe commit of that CI config
predicate.runDetails.metadata.invocationIdthe URL of the concrete job run
predicate.buildDefinition.resolvedDependencies[]the source repository as git+<issuer>/<path>@<ref> with its gitCommit
predicate.buildDefinition.internalParameters.devguard.workloadIdentityevery claim of the verified token

If the statement already contains a resolved dependency for that same repository with a different commit than the token, the request is rejected rather than silently corrected.

Subjects and the build description are kept exactly as the builder reported them. DevGuard does not re-run your build; it establishes who ran it.

4. DevGuard signs

The statement is signed into a DSSE envelope with payload type application/vnd.in-toto+json. If a transparency log is configured (SLSA_REKOR_URL), the envelope is uploaded to Rekor and the response is a sigstore bundle containing the envelope plus its inclusion proof. Without it, the response is the bare DSSE envelope and verifiers have to skip the transparency log check.

5. The artifact gets the attestation

devguard-scanner attest recognises already-signed input — a DSSE envelope or a sigstore bundle — and attaches it to the image and uploads it as-is, without signing it a second time, so the signature chain back to DevGuard stays intact.


Relationship to sigstore keyless signing

None of this is a new idea. Proving who built something with a short-lived OIDC workload identity instead of a long-lived signing key is exactly the model behind sigstore keyless signing, which cosign sign --identity-token has implemented for years:

  1. The CI job gets an OIDC token from its build platform.
  2. Fulcio verifies that token and issues a short-lived certificate binding the key to the identity in it.
  3. Rekor records the signature in a public transparency log.
  4. Verifiers check --certificate-identity and --certificate-oidc-issuer — the same pin on the build configuration described above.

Why DevGuard does it itself

The friction is step 2. The public good Fulcio accepts a fixed, enumerated set of OIDC issuers. It is not a short list — GitHub Actions, GitLab.com, Buildkite, CircleCI, Codefresh, Chainguard and wildcard patterns for managed Kubernetes clusters are all in there — but it is a list, maintained in Fulcio's own configuration.

If your builds run on a self-hosted GitLab, a GitHub Enterprise Server, or your own build server, your issuer is not on it, and there is no way to add it short of running your own sigstore stack: a Fulcio instance, a Rekor instance and a certificate authority to anchor them.

That is a lot of infrastructure to gain one property: deciding which issuers you trust. DevGuard implements the same trust model directly against that property. The issuer allowlist is a configuration value, the identity binding is written into the provenance instead of into a certificate, and the signature comes from the instance key.

Note

To be clear about the trade: running your own sigstore instance is about as secure as this. The trust root is the same in both cases — your issuer allowlist, and a signing key only the platform can reach. What sigstore adds on top is short-lived keys instead of a long-lived one, and an ecosystem of verification tooling that already understands certificate identities. What it costs is operating four more services.

The transparency log is not an either/or: point SLSA_REKOR_URL at a Rekor instance — the public one or your own — and DevGuard uploads every signed provenance to it and returns a sigstore bundle, so you get public auditability without running Fulcio.

The closest relative: slsa-github-generator

If you have seen SLSA provenance on GitHub before, it probably came from slsa-github-generator. It is worth looking at closely, because it is the same architecture as this page describes — and seeing why makes the model concrete.

The generator is a set of reusable workflows living in their own repository. Your workflow calls one with uses:, handing it the digest of the artifact you built. Because GitHub issues the OIDC token against the workflow that is actually running, the token the generator receives has job_workflow_ref pointing at the generator's workflow file, not at yours. You cannot influence what it says, even though you triggered it. The generator signs keylessly through Fulcio, and slsa-verifier then checks that the certificate identity is the generator's workflow ref.

Map that onto DevGuard and the pieces line up one to one:

slsa-github-generatorDevGuard
the reusable workflow is the trusted builderthe trusted build configuration is the trusted builder
job_workflow_ref names it, and the caller cannot forge thatthe same claim, mapped into builder.id
Fulcio binds the identity into a certificateDevGuard writes it into the provenance
slsa-verifier pins the certificate identityyour policy pins builder.id

DevGuard's GitHub mapping deliberately uses the same claim, so an artifact built through a reusable workflow gets a builder.id of the same shape — the workflow ref, plus the issuer.

The one caveat applies to both. The generic generators sign a digest their caller supplies; they vouch for which workflow asked, not that the bytes came from the source being claimed. Only the language-specific builders, which run the build themselves, close that gap. DevGuard sits in the same place, which is why pinning builder.id to a configuration that genuinely performs the build is the step that matters.

Where the two part ways is reach: slsa-github-generator is GitHub Actions and public sigstore only. The model here is the same one, available on whatever platform issues you a workload identity.

What the signature means, and what you verify

The signed provenance carries exactly one guarantee from DevGuard:

This provenance was produced by build configuration X, whose identity was issued by I. Nobody other than X can produce provenance naming X.

Whether X is a configuration worth trusting is the verifier's decision, and it is the decision that determines your actual level. The verification rule follows directly:

  1. Check the issuer. The issuer appears in builder.id as the iss query parameter and in full under internalParameters.devguard.workloadIdentity.iss. DevGuard attests what the issuer claimed; it does not vouch for the issuer. An unrecognised issuer invalidates everything downstream of it.
  2. Pin builder.id. Require the specific trusted build configuration. Provenance from a maintainer-controlled pipeline will carry a different builder.id and must fail.
  3. Check the source. The repository and gitCommit in resolvedDependencies come from the token, not from the builder's own claim.
  4. Check the subject against the digest of the artifact you are about to run.
Warning

If SLSA_OIDC_TRUSTED_ISSUERS is empty, tokens from any https issuer are accepted — anyone can stand up an OIDC provider and have DevGuard sign provenance naming any builder. Set the allowlist on any instance where this matters, and always check the issuer when verifying.


Mapping to the Build track

SLSA requirementFirst required atHow it is met
Provenance exists, identifying the output by digestL1intoto stop --generateSlsaProvenance
Provenance generated by the control plane, not the tenantL2DevGuard fills in the identity fields from the verified token; the trusted builder reports the build definition
Signing key accessible only to the build platform componentL2the key lives in DevGuard, never in a CI variable
Build runs on a hosted platform, not a workstationL2your CI platform
Provenance strongly resistant to forgery by tenantsL3the builder is a protected pipeline the project cannot modify; its identity cannot be spoofed
Signing material inaccessible to user-defined build stepsL3no CI job ever holds the key
Isolated, ephemeral build environment per runL3your runner configuration

The two requirements DevGuard cannot meet for you are the ones that belong to your infrastructure: runner isolation, and keeping the trusted builder's configuration genuinely out of the project's hands.

Have feedback? We want to hear from you!

Fields marked with * are required