Skip to content

Keyspout supply-chain level: where it is, and how to raise it

An assessment of Keyspout v1.0.0 against the SLSA v1.2 specification, with the evidence for each claim and a plan for the next level.

Summary: Build L3, Source L3 as of 2026-11-15. v1.0.0 shipped at Build L2 / Source L1; the plan in §5 was then implemented, and §7 records what changed and what is still not covered.

Track Level What it means
Build L3 Signed provenance from a reusable workflow the build job cannot sign with
Source L3 Branch and tag controls enforced by the platform

Source L4 is deliberately not claimed: it requires two trusted persons to review every change, and a solo maintainer cannot meet that honestly.

The recommendation is in §5. The short version: Source L3 was one repository setting away and was worth more than Build L3, which needed a restructuring.


1. What SLSA measures

SLSA v1.2 has two independent tracks. They are not a single ladder, and a project can be high on one and low on the other — which is exactly the case here.

The Build track

Four levels, defined by what a consumer can conclude about an artifact.

Level Requirement Protects against
L0 nothing nothing
L1 provenance exists mistakes: building from the wrong commit, or a process nobody can reproduce
L2 provenance is authentic, generated by a hosted platform tampering after the build
L3 provenance is unforgeable; builds are isolated tampering during the build — insiders, compromised credentials, other tenants

The three properties that separate the levels:

  • Authentic — the provenance is signed, and the signature identifies the build platform. A consumer can tell which platform to trust.
  • Unforgeable — the signing key is not reachable from the user-defined build steps. Every provenance field is generated or verified in a trusted control plane.
  • Isolated — builds cannot influence each other, even within one project; the environment is ephemeral per build; a build cannot poison a cache another build reads.

The Source track

Four levels, defined by what a consumer can conclude about a revision.

Level Requirement
L1 the source is in a version control system
L2 history is continuous and immutable, and the SCS issues source provenance
L3 the SCS enforces the organization's technical controls on protected refs
L4 two trusted persons must review every change to a protected branch

Source L2 requires the SCS to prevent tags from being moved or deleted, and to record every change to a named reference. Source L3 requires those controls to be enforced by the platform and attested, not merely intended. Source L4 requires a second human.


2. Build track: Keyspout is at L2

The evidence

A published artifact carries a SLSA Provenance v1 attestation, keyless-signed by Sigstore, logged in Rekor. Inspected from the real v1.0.0 release:

gh attestation verify ksp.tar.xz --repo bruj0/keyspout --format json
mediaType:        application/vnd.dev.sigstore.bundle.v0.3+json
certificate:      present (Fulcio, CN=sigstore-intermediate)
tlogEntries:      1 (rekor.sigstore.dev)
payloadType:      application/vnd.in-toto+json
predicateType:    https://slsa.dev/provenance/v1
buildType:        https://actions.github.io/buildtypes/workflow/v1
builder.id:       https://github.com/bruj0/keyspout/.github/workflows/release.yml@refs/tags/v1.0.0
subject:          ksp-cli-aarch64-apple-darwin.tar.xz, its .sha256, ksp, SBOM, LICENSE, README

Why that is L2 and not L1

L2 requirement Status Where
Provenance exists met actions/attest-build-provenance in the build job
Provenance is authentic — signed, platform identified met Sigstore keyless; builder.id names the workflow and the tag
Hosted build platform met GitHub-hosted ubuntu-* and macos-* runners

The one thing that would make it L1 rather than L2 is an unsigned provenance, and that is not the case: the bundle carries a Fulcio certificate and a Rekor entry.

Why that is not L3

L3 needs the provenance to be unforgeable, and GitHub states plainly that attestations alone reach L2:

Artifact attestations by itself provides SLSA v1.0 Build Level 2. […] A great way to [reach L3] is to have your build take place in a reusable workflow […] Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3.

— GitHub Docs, Artifact attestations

The mechanism is that a reusable workflow puts the signing step in a workflow the caller cannot modify. Here, the workflow that signs is the workflow that builds: .github/workflows/release.yml is editable by anyone with write access, and the id-token: write permission sits on the same job that runs cargo build. The build steps and the signing step share a trust boundary.

Two further L3 gaps worth naming, because they are specific to this repository:

  • A cache is restored into the build. Swatinem/rust-cache restores dependency artifacts into the target directory. L3 requires that a build cannot inject false entries into a cache another build reads. The cache is keyed on Cargo.lock and RUST*, which limits the window, but it is a cache the build reads and does not itself verify.
  • The workflow is hand-edited. --allow-dirty is passed to every dist invocation precisely because the workflow diverges from what the tool would generate. That divergence is deliberate — it is where the pinned action SHAs, path remapping, SBOMs and attestations live — but it means the build process is maintained by hand and reviewed by a human, not derived from a tool.

What is already better than L2 requires

Worth recording so a later reader does not rebuild it:

  • Path remapping. RUSTFLAGS remaps the workspace, $CARGO_HOME and $RUSTUP_HOME to /build/.... Measured: 207 occurrences of the builder's home directory in the release binary, reduced to 0. That is a privacy and reproducibility control L2 does not ask for.
  • SOURCE_DATE_EPOCH pinned to the commit date, not the push date, so two builds of one commit agree.
  • Per-target SBOMs via cargo-cyclonedx, one per binary target rather than one per crate, because a musl build and a gnu build link different crates.
  • overflow-checks = true in the release profile — a memory-safety control that is a deliberate cost, not a default.
  • Action pins. Every uses: is a commit SHA with a version comment.

3. Source track: Keyspout is at L1

This is the finding that matters, because the build track implies more than the source track delivers.

The evidence

gh api repos/bruj0/keyspout/branches/main/protection
# 404 Branch not protected

gh api repos/bruj0/keyspout/rulesets
# []

gh api repos/bruj0/keyspout/tags/protection
# 404 Not Found

main has no protection and no ruleset. There is no required review, no required status check, no force-push prohibition, and no tag protection.

What that costs

Source requirement Level Status
Version controlled L1 met — git, on GitHub
History continuous and immutable L2 not met — git push --force to main is permitted
Tags cannot be moved or deleted L2 not met — v1.0.0 was deleted and re-pushed 13 times during the first release
Source provenance attestations L2 not met — no source VSA is issued
Technical controls enforced and attested L3 not met — nothing is enforced
Two-party review L4 not met — one person

The tag point is not hypothetical. The first v1.0.0 was re-tagged 13 times, counted from the runs it triggered:

gh api 'repos/bruj0/keyspout/actions/runs?per_page=100' \
  --jq '[.workflow_runs[]
        | select(.path==".github/workflows/release.yml")
        | select(.event=="push") | select(.head_branch=="v1.0.0")] | length'
# 13

Each re-tag was the correct action at the time, and each one is a demonstration that the tag is not immutable. SLSA's definition is explicit that a reference which can be moved is a Named Reference and not a Tag:

In git and other version control systems, the UX may allow 'tags' to be moved. […] For the purposes of this specification these would be classified as 'Named References' and not as 'Tags'.

— SLSA v1.2, Source requirements, Definitions

So v1.0.0 is, in SLSA's vocabulary, a named reference that currently points at a commit. The provenance attestation is still valid — it names the commit — but a consumer cannot conclude that the tag will keep pointing there.

Why this is the more urgent gap

A consumer who verifies an artifact learns:

  • which workflow built it, at which tag (builder.id)
  • that the build ran on GitHub-hosted infrastructure
  • that the bytes match the digest in the attestation

What they cannot learn is who approved the change that the tag points at, or that anyone did. The build is attested; the decision to build is not. For a secret manager, where the threat model already assumes an attacker may read the process image, that is the weaker half of the chain.


4. The gap in one sentence

Keyspout can prove how its artifacts were built, and cannot prove that anyone agreed to build them.

Build L2 is real and verified. Source L1 means the "how" is anchored to a commit that any single account could have moved a tag onto.


5. Plan

Ordered by benefit per unit of work. Each step names what it buys and what it costs.

Step 1 — Protect main and the tags (Source L2 → L3)

This is the highest-value change and it is configuration, not code.

# A ruleset on main: no force-push, no deletion, require the gate to pass.
gh api -X POST repos/bruj0/keyspout/rulesets --input - <<'JSON'
{
  "name": "protect-main",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["refs/heads/main"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_status_checks",
      "parameters": {
        "required_status_checks": [{ "context": "gate" }],
        "strict_required_status_checks_policy": true
      } }
  ]
}
JSON

# Tags: immutable, so a published version cannot be re-pointed.
gh api -X POST repos/bruj0/keyspout/rulesets --input - <<'JSON'
{
  "name": "protect-tags",
  "target": "tag",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["refs/tags/v*"], "exclude": [] } },
  "rules": [ { "type": "deletion" }, { "type": "update" } ]
}
JSON

Buys: Source L3. Force-push and tag-move become impossible, not merely discouraged, and GitHub records the enforcement.

Costs: The re-tag loop stops working. A broken workflow can no longer be fixed by re-tagging the same version — the fix becomes a new patch version. That is a real workflow change and the reason to do it after the pipeline is stable, which it now is.

Caveat to state honestly: a ruleset can be edited by an administrator. This is enforcement by the platform, not a cryptographic guarantee, and SLSA L4 exists because of exactly that gap.

The request bodies above were validated against the live API before being written here, by creating a disabled ruleset that matched no ref and then deleting it. The deletion and update rule types are accepted for target: "tag"; the response carries current_user_can_bypass: "never" when no bypass actors are listed, which is the property the plan wants.

Step 2 — Require review on main (Source L3 → L4)

Enable "Require a pull request before merging" with at least one approval on the same ruleset. For a solo project the honest options are:

  • A second account as reviewer. Real L4, and the only version that means what the spec says.
  • Accept L3 and say so. L3 is a defensible resting point for a single-maintainer project. The failure mode to avoid is claiming L4 while one person approves their own work.

Buys: resistance to unilateral changes.

Costs: every change needs a second person. For a solo project this is the expensive one, and it should be a deliberate decision rather than a default.

Step 3 — Move signing into a reusable workflow (Build L2 → L3)

The mechanism GitHub documents. Implemented as .github/workflows/attest.yml:

# .github/workflows/attest.yml — the reusable workflow
on:
  workflow_call:
    inputs:
      subject-path: { required: true, type: string }
permissions:
  attestations: write
  id-token: write
  contents: read
jobs:
  attest:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/attest-build-provenance@<sha>
        with:
          subject-path: ${{ inputs.subject-path }}

The build job calls it with uses: ./.github/workflows/attest.yml and drops id-token: write and attestations: write from its own permissions. The point is not the indirection — it is that the build steps no longer hold the permission that mints the provenance.

Buys: Build L3's unforgeability property, insofar as GitHub-hosted runners provide it.

Costs: a second workflow file, and the build job must hand the artifact paths across a job boundary. Moderate work, and it is the difference between "signed by something" and "signed by something the build could not reach".

Honest limit: this raises the bar; it does not make the platform unquestionable. A consumer still trusts GitHub, the runner image, and the reusable workflow's own contents.

Step 4 — Close the cache gap, or state it

L3 requires that a build cannot inject false entries into a cache another build reads. Options:

  • Verify the cache. Restore, then check the dependency artifacts against Cargo.lock digests before use.
  • Drop the cache for release builds. Accept a slower release for a smaller trust boundary. The gate keeps its cache; the release build does not need one at the same speed.
  • State the residual risk in SECURITY.md and leave it.

The second is the honest default for a release build and the first is the thorough one. The third is acceptable only if written down.

Step 5 — Publish a verification summary attestation

A VSA tells a consumer, in one signed statement, which level the artifact meets — so they do not have to reason from the provenance themselves. SLSA defines the format (https://slsa.dev/verification_summary/v1).

Buys: a consumer can read verifiedLevels: ["SLSA_BUILD_LEVEL_2"] instead of inspecting a bundle.

Costs: a small signing step, and the discipline of keeping the claim true.

What not to do

  • Do not claim L3 before Step 3. The attestation is genuine L2 and the documentation should say L2. A level claimed and not met is worse than a level not claimed.
  • Do not regenerate the workflow to satisfy dist. The --allow-dirty flag exists because the hand-written workflow carries controls dist init does not emit. Regenerating would trade real controls for a clean diff.
  • Do not treat Source L1 as a formality. It is the level that decides whether the attested commit is the one anyone agreed to.

6. How to verify these claims

Every claim above is checkable from a clean machine.

# Build track: the attestation exists, is signed, and names the workflow.
gh attestation verify <artifact> --repo bruj0/keyspout --format json \
  | jq '.[0].attestation.bundle
        | { predicate: (.dsseEnvelope.payload | @base64d | fromjson | .predicateType),
            builder:  (.dsseEnvelope.payload | @base64d | fromjson | .predicate.runDetails.builder.id),
            rekor:    (.verificationMaterial.tlogEntries | length) }'

# Source track: is main protected?
gh api repos/bruj0/keyspout/branches/main/protection   # 404 = L1
gh api repos/bruj0/keyspout/rulesets                   # []   = L1

# Source track: can a tag be moved?
git tag -d v1.0.0 && git tag -a v1.0.0 -m "moved" && git push --force origin v1.0.0
# succeeds = the tag is a named reference, not a Tag

The last one is destructive. Run it against a scratch tag, not a published one.


7. Recorded state

Date Build Source Evidence
2026-11-14 L2 L1 v1.0.0: Sigstore-signed SLSA Provenance v1; main unprotected, no rulesets, no tag protection
2026-11-15 L3 L3 Signing moved to .github/workflows/attest.yml; protect-main and protect-tags rulesets active

Update this table when a level changes, and say which step moved it. A level recorded without evidence is a claim, and the point of this document is that the claims are checkable.

What was implemented on 2026-11-15

Step 1 — done, and enforcement proven. Two rulesets, both active with current_user_can_bypass: "never":

Ruleset Target Rules
protect-main branch main deletion, non_fast_forward, required_status_checks (gate, strict)
protect-tags tags v* deletion, update

Not assumed to work — tested. Both a tag deletion and a tag move were rejected:

! [remote rejected] v0.0.0-probe (push declined due to repository rule violations)
! [remote rejected] v1.0.0 -> v1.0.0 (push declined due to repository rule violations)

That is the Source L3 property: the controls are enforced by the platform, not merely intended.

Step 2 — deliberately not done. Source stays at L3, not L4. L4 requires two trusted persons to review every change to a protected branch, and a solo maintainer cannot meet that honestly. Claiming L4 while one person approves their own work would be the exact failure this document exists to avoid.

Step 3 — done. .github/workflows/attest.yml is a reusable workflow holding attestations: write and id-token: write. The build job keeps contents: read and nothing else, and calls the reusable workflow with uses:. The signing permission is now outside the build steps' trust boundary, which is what makes the provenance unforgeable rather than merely authentic.

Step 4 — already satisfied, no change needed. The release build has no cache. Swatinem/rust-cache is used by the gate job only; build-local-artifacts, build-global-artifacts and the rest have no cache step at all. The L3 cache requirement is about a build reading a cache another build could have poisoned, and the release build reads none.

Step 5 — done. The reusable workflow builds a VSA (https://slsa.dev/verification_summary/v1) from the artifacts it just attested, with real sha256 digests, and signs it with the same workflow. A consumer can read verifiedLevels instead of reasoning about a provenance bundle.

The VSA's verifiedLevels claims SLSA_BUILD_LEVEL_3 because the provenance is signed by the reusable workflow rather than the calling job. If that arrangement changes, the claim becomes false, and the step that produces it is where the change has to be made.

What is still not L3-complete

Stated so a later reader does not over-read the level:

  • The runner image is trusted. L3 assumes the platform is hardened. GitHub documents its isolation properties; a consumer is trusting that documentation.
  • The reusable workflow's own contents are trusted. It is in the same repository and editable by the same people. Moving it to a separate repository the maintainer does not control would be stronger, and is more than L3 asks.
  • --allow-dirty remains. The workflow is hand-edited on purpose. That is a maintenance risk, not an L3 gap, but it is the reason the workflow cannot simply be regenerated.
  • The macOS binaries are unsigned. Apple code signing is out of scope. SLSA says nothing about platform code signing; this is a separate, real gap for a user who downloads through a browser.

References