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:
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-cacherestores 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 onCargo.lockandRUST*, which limits the window, but it is a cache the build reads and does not itself verify. - The workflow is hand-edited.
--allow-dirtyis passed to everydistinvocation 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.
RUSTFLAGSremaps the workspace,$CARGO_HOMEand$RUSTUP_HOMEto/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_EPOCHpinned 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 = truein 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.lockdigests 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.mdand 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-dirtyflag exists because the hand-written workflow carries controlsdist initdoes 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-dirtyremains. 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¶
- SLSA v1.2 specification — https://slsa.dev/spec/v1.2/
- Build track basics — https://slsa.dev/spec/v1.2/build-track-basics
- Build requirements — https://slsa.dev/spec/v1.2/build-requirements
- Source requirements — https://slsa.dev/spec/v1.2/source-requirements
- GitHub, Artifact attestations — the L2/L3 boundary for GitHub Actions
SECURITY.md— what the release proves, in user-facing termsdocs/known-defects.md— the open defects this assessment assumes