Repository navigation
ci: declare least-privilege token permissions in every workflow - #231
Merged
shockalotti merged 1 commit intoNov 10, 2026
Merged
Conversation
Every workflow now sets a read-only token at the top level (`permissions: contents: read`), and the jobs that write ask for it on the job itself: - ci.yml, docker-publish.yml, ns8-module.yml, test-module.yml had no top-level block, so they inherited the repository's default token. They now start read-only. The existing job-level grants are unchanged: docker-publish build (packages: write, push to GHCR) and release (contents: write, gh release create), ns8-module build (packages: write), test-module (statuses: write and pull-requests: write, used by the called NethServer workflow). - cla.yml granted actions, contents, pull-requests and statuses write to the whole workflow. They move to the cla job. statuses: write is dropped: contributor-assistant/github-action v2.6.1 never calls the commit statuses API. It commits signatures (contents), comments on the pull request (pull-requests) and re-runs the CLA run (actions). - audit.yml goes from read-all to contents: read. The sbom and claims-guard jobs only check out code and upload an artifact; the scorecard job already sets its own grants. pullfrog.yml and release-verify.yml already declare read-only top-level permissions and are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
ci.ymlgetscontents: read— the singlecheckjob only checks out (full history, plus onegit fetch origin <base>for the CLA-ledger step) and writes nothing back to GitHub.docker-publish.yml/ns8-module.ymlget read-only defaults — the job-level grants that already existed (packages: writeon the image builds,packages: readonarm64-smoke,contents: writeonrelease, which runsgh release create) sit unchanged on top of the read-only token.audit.yml:read-all→contents: read—sbomandclaims-guardonly check out, build, scan and upload a workflow artifact; thescorecardjob'ssecurity-events/id-tokengrant is untouched.cla.ymlmoves its writes onto the job — top-levelcontents: read, job-levelactions/contents/pull-requestswrite. Droppingstatuses: writeis consistent with the action: I readcontributor-assistant/github-action@v2.6.1'ssrc/*.tsand it calls onlygit.*,issues.*,pulls.get,actions.*,repos.getContentand GraphQL — never the statuses endpoint.test-module.ymlgains a read-only default — the caller job's grant set (contents,pull-requests,statuses) is identical tomain; the diff only adds the comment above it.- Comments state what consumes each grant, which is the part that keeps the next edit from re-widening a scope.
I also parsed all eight workflows locally and confirmed the effective declarations match the table in the description, including that job-level blocks replace rather than merge with the workflow-level set (so scorecard still receives only its two scopes, as on main).
ℹ️ test-module.yml's callee no longer exists on the pinned v1 ref
Unrelated to this PR's change, but the file it annotates points at a reusable workflow that upstream deleted two days ago, so the grants being described there are currently moot.
Technical details
# Stale reusable-workflow ref in .github/workflows/test-module.yml
## Affected sites
- `.github/workflows/test-module.yml:77` — `uses: NethServer/ns8-github-actions/.github/workflows/test-on-digitalocean-infra.yml@v1`
- The new comment at `.github/workflows/test-module.yml:70-72` describes that callee's behaviour (commit status via `gh api .../statuses`, PR comment for screenshots), which was accurate for the file as it existed on `main`.
## Evidence
- `GET /repos/NethServer/ns8-github-actions/contents/.github/workflows?ref=v1` lists `build-apidoc`, `check-ui-tests-needed`, `clean-apidoc`, `module-info`, `publish-branch`, `scan-with-trivy`, `test-module-qemu`, `test-on-qemu` — no `test-module.yml`, no `test-on-digitalocean-infra.yml`.
- NethServer/ns8-github-actions#77, merged 2026-11-04: "BREAKING CHANGE: test-module.yml and test-on-digitalocean-infra.yml are removed from v1; callers must switch to test-module-qemu.yml."
- `main` in that repo still contains `test-on-digitalocean-infra.yml`, which is why the grant reasoning still reads correctly.
## Required outcome
- None for this PR. The workflow is `workflow_dispatch`-only and its `do_token` secret does not exist yet, so it has not been exercised either way.
- When it is fixed separately, the replacement is `test-module-qemu.yml@v1`, which makes its own job-level permission demands (its `test-module` job declares `contents: read` + `statuses: write`, and the screenshots job wants `contents: write`), so the caller's grant set will need re-checking then.
## Open questions for the human (optional)
- Is `test-module.yml` intended to survive the upstream removal, or is it dead code worth deleting?deepseek-v4.1-flash | 𝕏
rush-skills
pushed a commit
to rush-skills/calnode
that referenced
this pull request
Nov 18, 2026
… runs Docker publish and NS8 module publish never start on pull requests from forks. The run is created with ZERO jobs, so there is no log and no annotation, and the only visible trace is a check suite concluding startup_failure or failure. CAUSE. Calnode#231 added a workflow-level `permissions: contents: read` to both files for least privilege. That is the only change to either file between the last green fork run and the first red one, and removing it restores them. WHAT IT IS NOT, which is why this took a week. It is not "workflows that declare packages: write are refused on forks". At the last green fork run (main 98b5799, 2026-11-06) the job-level build: {contents: read, packages: write} was already present and fork PRs passed for months. The declaration is necessary for the break but it is not what changed, so toning it down would not have been the fix. It is not "a job escalating above a workflow-level cap" either. Audit has a top-level `read-all` and its scorecard job escalates to security-events: write and id-token: write, and Audit ran SUCCESS with 3 jobs on fork head fe75122, the same head where these two workflows produced zero jobs. So the failing shape is narrower: a workflow-level cap plus a job asking for PACKAGES write. THE SIGNATURE, and why it proves the failure is at expansion. On head fe75122: CLA Assistant success jobs=1 CodeQL success jobs=2 CI success jobs=1 Audit success jobs=3 Docker publish failure jobs=0 NS8 module publish failure jobs=0 The decisive detail is ns8-module.yml: its `validate` job needs only contents: read, and its `build` job is the one asking for packages: write. Yet `validate` never ran either, because the whole workflow produced zero jobs. So the run is rejected before any job exists. That is a workflow-expansion failure, not a build failure wearing a strange exit code. THE FIX. Remove the workflow-level block from both files and leave a comment in its place saying there is deliberately none, and why, so nobody re-adds it as a tidy-up. Least privilege is not weakened. The repository default is already `read` (default_workflow_permissions=read), so a job without an explicit block still gets read, and every job in both files declares its own permissions anyway. What is lost is redundancy, not a guarantee. Deliberately not done: moving the packages: write work into a separate off-PR job. That is the better end state if the PR and publish paths ever need to differ more than they do, but it is a larger diff solving a problem this does not. UNPROVEN, stated plainly. There is no GitHub documentation citation here for packages-write behaviour on forks under an explicit cap. The evidence is the A/B above, a perfect correlation across every fork head, and a counterexample that narrows the rule. If fork runs still produce zero jobs after this, the rule is wider and this is not the whole story. Diff is comments plus the removal of two lines in each file. No other workflow or permission was touched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Workflow token permissions only. No job gains a permission it does not already have, and one grant is dropped.
Why
Scorecard's Token-Permissions check is at 0. Its details name two causes:
ci.yml,docker-publish.yml,ns8-module.ymlandtest-module.ymlset no top-levelpermissions:, so they run with the repository's default token, andcla.ymlgrantsactions,contentsandstatuseswrite to the whole workflow.What changes
Every workflow now has a read-only token at the top level, and a job that writes asks for it on the job itself.
ci.ymlpermissions:contents: read. The job checks out and fetches the base branch, and writes nothing.docker-publish.ymlcontents: read. Jobs keep their grants:buildhaspackages: write(push to GHCR),arm64-smokepackages: read,releasecontents: write(gh release create).ns8-module.ymlcontents: read.buildkeepspackages: write.test-module.ymlcontents: read. The job keepsstatuses: writeandpull-requests: write: the called NethServer workflow sets a commit status withgh api .../statusesand comments UI screenshots on the pull request.cla.ymlactions,contents,pull-requests,statuseswrite, workflow-widecontents: readat the top; theclajob getsactions,contentsandpull-requestswrite.audit.ymlread-allcontents: read. Thescorecardjob's own grants are unchanged.pullfrog.ymlandrelease-verify.ymlalready do this and are unchanged. Each grant has a short comment saying what uses it.The grant that is dropped:
statuses: writeon the CLA job. I went through contributor-assistant/github-action v2.6.1 (the versioncla.ymluses) for every call it makes with the workflow token:repos.getContentandcreateOrUpdateFileContentsonsignatures/version1/cla.json:contents: writeissues.createComment,updateCommentandlistCommentson the pull request:pull-requests: writeactions.listRepoWorkflows,listWorkflowRunsandreRunWorkflow, to re-run the CLA check once everyone has signed:actions: writeIt never calls the commit statuses API; the CLA result is the job's own pass or fail. The action's README example does list
statuses: write, so if you would rather keep it, it is one line on the job, and Scorecard does not count job-level grants against a workflow whose top level is read-only.audit.yml:read-alltocontents: read. Thesbomandclaims-guardjobs check out, build, scan and upload a workflow artifact, which needs no token permission. anchore/sbom-action only calls the GitHub API to compare against a base-branch SBOM (compare-pulls, off) or to attach release assets on a release or tag push, and this workflow runs on neither.Expected Scorecard effect
Token-Permissions should go from 0 to 10.
scorecard --local(v5.5.0, the version the public API currently reports) gives 10 on this branch ("GitHub workflow tokens follow principle of least privilege") and 0 onmain. That is an expectation: the published score comes from Scorecard's own scheduled run after merge.How it was checked
main, none in lines this touches.excessive-permissionsfindings onmain(audit.yml'sread-all, andci.ymlwith no block) are gone, and nothing new appears.statusesabove. This PR's own CI exercisesci.yml,audit.ymland the pull-request paths ofdocker-publish.ymlandns8-module.yml.cla.ymlruns frommainonpull_request_target, so its change takes effect after merge, with the next pull request from someone who has not signed.Part of a small set of Scorecard changes: #232 (CodeQL), #233 (pinning) and #234 (release provenance); discussion #235 lists the repository settings only a maintainer can change. Each stands on its own and they merge in any order.
🤖 Generated with Claude Code