sec(2157): make "no unscoped App-token mint" a checkable property

[LukasWodka]

Refs backend#2157. The 19 add-to-kanban copies are scoped and the audit is clean (0 findings). Nothing stops the twentieth mint arriving the way the first nineteen did — nine workflows acquired a full-permission mint in one day because the first one did and the rest were copied from it.

Least privilege applied by hand is a state. This is the part that makes it a property.

What it decides, and what it refuses to guess

A mint with no permission-* input carries the App's full installation grant — contents + pull-requests + issues + org-projects write across every installed repo. The App holds bypass_reviews on staging and prod fleet-wide, so the blast radius is merge past review, not merely write.

Whether the scopes a workflow does name are the right ones is a question only its own API calls can answer, and a guard that claimed to know would be restating rather than deriving. "Asked for nothing at all" is decidable, and is what was actually going wrong.

Derived, not restated

The workflow list is the directory. Mint steps are found by parsing YAML and comparing uses: up to the @ — so a new workflow is covered automatically, and a pin bump does not silently stop the check. There's a case and a mutation for exactly that, because exact-string-including-version is the obvious wrong implementation.

Fail closed, including on zero

An unparseable workflow, a missing directory, and zero mints found are all hard errors. The last matters most: this file's premise is that mints exist, so finding none means the matcher broke — not that the fleet got clean.

Armed green over 12 pre-existing offenders

Each is exempted by name with a reason, so this lands green rather than as a red gate that trains people to skip the tier.

fr-gate is a required check on every promotion branch fleet-wide; three others read branch protection, where a narrower token is known to return less data rather than an error — that's why caller-drift keeps a PAT at all (ruleset bypass_actors is returned only to a write-access caller). Downscoping those needs measurement per workflow. It is not a thing to guess at across 13 files in one commit.

And a stale exemption is also a finding. Without that half the list stops being a burn-down and becomes cover: a full-grant mint re-introduced into an exempted file would be admitted by a row written earlier for a different reason.

Verification — and two gaps the mutation run found

13 cases, 8 mutations, each verified applied and caught. Two were uncaught on the first run, and the run is how I found out rather than review:

uncaught mutation	why the suite couldn't see it
a missing with: counts as scoped	every fixture happened to supply a with: block
the action match becomes a substring test	the look-alike fixture evil/actions-create-github-app-token doesn't contain the real name — the hyphen breaks it — so it couldn't distinguish in from split("@")[0] ==

Both are now cases. The second fixture became myorg/actions/create-github-app-token, which a substring test does wrongly match.

Separately, two cases initially failed by measuring production state: without an explicit exemption override, the live 12 rows all read as stale against a fixture directory. That failure was the stale-exemption check working on the wrong input, and the helper now says so where someone would otherwise repeat it.

Also in this PR

repo-inventory.yml's divergent reason for release-train's copy said its header "is now the ONLY difference". False in two ways — the copy also lacked the scoping until release-train#93, and it carries a second wanted comment (the Dependabot note) the reason never mentioned. Rewritten to name both, and to state the claim in a checkable form: strip every comment and blank line from that copy and from the canonical one and they are byte-identical.

What this does not do

The 12 exemptions are the remaining work, in two risk tiers — the board-writing set (loud failures, local blast radius) and fr-gate + the three protection readers (a wrong scope there blocks the train or silently returns less). Those are follow-up PRs, one tier at a time, with the exemption rows coming out as each is measured.

---

Note

Medium Risk
Changes enforce CI gates on workflow token scoping (security-sensitive), but behavior is additive with exemptions so merges stay green; wrong matcher or exemption drift could block CI or miss regressions.

Overview
Adds mint-scope, a YAML audit that flags create-github-app-token steps with no permission-* inputs (full installation grant). Twelve existing workflows stay on a named EXEMPT burn-down list; stale exemptions fail too. scripts/tests/mint-scope-selftest.py exercises the matcher on fixtures (fail-closed, version-pin matching, no false substring hits).

Wiring:make mint-scope joins lint and make check; the fixture selftest joins make selftests. The required selftests CI job now runs make mint-scope on real workflows so a new unscoped mint cannot merge while only fixture tests pass.

Docs:repo-inventory.yml updates release-train add-to-kanban.yml divergent text (checkable byte-identity after comments) and records stale-backlog.yml as deliberately absent on release-train.

^{Reviewed by Cursor Bugbot for commit 9f75177. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit b9a7629. Configure here.}

[saadqbal]

Ran the suite (13/13) and the live audit, then mutated the three properties this stands or falls on:

• Exact-string match including the @ pin (uses.strip() == MINT_ACTION) → 7 failures, including the case named for it: a DIFFERENT version pin of the mint action is still matched. That's the obvious wrong implementation and it's genuinely pinned.
• Zero mints stops being a finding (if minted == 0: → dead) → 3 failures, led by ZERO mints found is a hard error, not a clean run.
• Look-alike and path-containing action names both have their own cases and both redden under the matcher mutations.

Live audit on the real tree:

mint-scope: 13 `actions/create-github-app-token` step(s) across 33 workflow file(s)
12 unscoped, 12 exempted, 0 finding(s)

I agree with the scope decision. "Are the named scopes the right ones" is only answerable by the workflow's own API calls, and a guard claiming to know would be restating rather than deriving — whereas "asked for nothing at all" is decidable and is what actually went wrong nine times in one day. Reporting stale exemptions as findings too is the part that keeps the list from calcifying, and it's the bit most guards of this shape omit.

One fix: the count in the prose is off, and it's off in the direction this file argues against. Two places say 13 —

• the docstring: "The 13 reusables that already carry a full grant are exempted by name"
• the comment above EXEMPT: "These 13 are the pre-existing state this guard was written to stop growing"

— but EXEMPT has 12 entries, and the PR description says 12. I think the 13 came from the mint step count (the audit reports 13 steps, 12 unscoped + 1 already scoped), which isn't the same population. Given the file's own "DERIVED, NEVER RESTATED" section, the right fix is probably not to write 12 but to let it say len(EXEMPT) — a hardcoded tally sitting directly above the list it counts is the exact pattern backend#1729 is cited for.

Also worth noting for whoever picks up the burn-down: the reasoning that a scoped canonical here means scoped fleet-wide rests on add-to-kanban.yml being the only copied workflow that mints, and the docstring says where to re-check that (copies: in repo-inventory.yml). Good that the dependency is written down rather than assumed.

[LukasWodka]

Fixed in the push just now, and the finding is this file's own rule turned on itself — thank you for catching it.

You're right about the population, which is the part that makes it a real defect rather than a typo. 13 is the mint step count the audit reports: 12 unscoped plus the one already-scoped add-to-kanban.yml. EXEMPT holds the unscoped 12. So the two numbers count different things, and the smaller one drifts the moment a row is burnt down — which is the entire purpose of the guard.

And your recommended fix is the right one rather than the obvious one. Writing 12 would have been correct today and wrong at the first burn-down. Both prose sites now carry no number, with the reason written where they were, so the next person doesn't helpfully add one back:

A hardcoded tally sitting directly above the list it counts is the exact pattern backend#1729 is cited for, in the file that cites it. The run prints the number from len(_exempt()); that is the only place it should exist.

Two comments in selftests.yml lost their case counts on the way through for the same reason.

Also in this push: the conflict against develop

develop moved three times underneath this branch (#288, #289, #291). All three hunks wanted both sides, not one:

conflict	resolution
Makefile lint	mint-scopeandmutation-house-rules-dry
SELFTEST_TARGETS	selftest-mint-scopeandselftest-house-rules
selftests.yml	the mint-scope audit step and the house-rules mutation step

The Makefile's CI-job map is now one line naming all three, since the required selftests context runs all of them.

repo-inventory.yml I kept ours deliberately: develop still carries the pre-release-train#93 wording ("the header alone"), which is now false — #93 added the scoping, so the divergence really is two comment blocks and nothing else, and ours is the version with the checkable claim in it.

On your closing note

The fleet-wide inference does rest on add-to-kanban.yml being the only copied workflow that mints — and you're right that it's worth flagging for the burn-down rather than buried. Two of the twelve are the ones I'd want measured first for a different reason: bricked-prs and merge-settings-drift read branch protection, where a narrower token returns less data rather than an error. That's why caller-drift keeps a PAT at all, and it's the reason tier 2 needs measurement per workflow instead of a sweep.

make check exit 0 · mint-scope 12 exempted, 0 findings · 41 house-rules cases · mint-scope selftest 13/13.

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 05ab193. Configure here.}

[saadqbal]

Re-approving — my earlier approval was dismissed by the three commits since, so I re-checked rather than assuming they were cosmetic. All three are good, and one is more than cosmetic.

My finding is fixed the way I hoped.9f75177a drops the hardcoded tally entirely rather than correcting 13 → 12, and the runtime figure now comes from len(_exempt()) at :215. The prose that replaced it explains why the 13 was wrong — it was the mint STEP count, of which 12 are unscoped and one already scoped — so the next reader doesn't rediscover the confusion. That's the right resolution for a file whose own thesis is "derived, never restated".

b9a76291 is the substantive one, and I'd missed it. The guard was wired only into make lint, which CI doesn't run — so on my last pass I verified a guard that could not have blocked anything. It now runs as make mint-scope inside selftests.yml, and the comment says exactly that. Worth calling out because a correct guard in a context nobody executes is the same as no guard, and it's the sort of gap a careful review of the script sails straight past.

One caveat on that: I can confirm selftests runs and passes on this PR, but I can't verify it's a required context — repos/tracebloc/.github/branches/develop/protection returns 404 for my token. Worth an admin eye if "required" is load-bearing for you; the commit message claims it and I have no reason to doubt it, I just can't see it from here.

05ab193c removes a stale-backlog.yml exempt block that the conflict resolution had reinstated after #288 deleted it. Checked the consequences rather than the diff: the real inventory still parses at schema_version 2 with 19 repos, every one carrying release_train, and the release-train entry's keys are clean. caller-drift selftest 197/0, so nothing downstream depends on the key that went.

Re-ran the guard itself: selftest 13/13, and the live audit is clean with the tally now derived —

mint-scope: 14 `actions/create-github-app-token` step(s) across 33 workflow file(s)
12 unscoped, 12 exempted, 0 finding(s)

14 steps rather than 13 because the develop merge brought in #288's scoped mint, which is the system working as intended.

Everything from my first pass stands: the version-agnostic uses: match and the zero-mints-is-an-error rule are both mutation-proved, and reporting stale exemptions keeps the list shrinking.

[LukasWodka]

/fr-pass