Skip to content

ci: declare least-privilege token permissions in every workflow - #231

Merged
shockalotti merged 1 commit into
Calnode:mainfrom
distronode-corporation:up/workflow-permissions
Nov 10, 2026
Merged

shockalotti merged 1 commit into
Calnode:mainfrom
distronode-corporation:up/workflow-permissions

Conversation

@distronode-com

@distronode-com distronode-com commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

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.yml and test-module.yml set no top-level permissions:, so they run with the repository's default token, and cla.yml grants actions, contents and statuses write 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.

Workflow Before After
ci.yml no permissions: contents: read. The job checks out and fetches the base branch, and writes nothing.
docker-publish.yml no top-level block contents: read. Jobs keep their grants: build has packages: write (push to GHCR), arm64-smoke packages: read, release contents: write (gh release create).
ns8-module.yml no top-level block contents: read. build keeps packages: write.
test-module.yml no top-level block contents: read. The job keeps statuses: write and pull-requests: write: the called NethServer workflow sets a commit status with gh api .../statuses and comments UI screenshots on the pull request.
cla.yml actions, contents, pull-requests, statuses write, workflow-wide contents: read at the top; the cla job gets actions, contents and pull-requests write.
audit.yml read-all contents: read. The scorecard job's own grants are unchanged.

pullfrog.yml and release-verify.yml already do this and are unchanged. Each grant has a short comment saying what uses it.

The grant that is dropped: statuses: write on the CLA job. I went through contributor-assistant/github-action v2.6.1 (the version cla.yml uses) for every call it makes with the workflow token:

  • repos.getContent and createOrUpdateFileContents on signatures/version1/cla.json: contents: write
  • issues.createComment, updateComment and listComments on the pull request: pull-requests: write
  • actions.listRepoWorkflows, listWorkflowRuns and reRunWorkflow, to re-run the CLA check once everyone has signed: actions: write

It 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-all to contents: read. The sbom and claims-guard jobs 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 on main. That is an expectation: the published score comes from Scorecard's own scheduled run after merge.

How it was checked

  • Every workflow parses, and the effective permissions in the table were read back from the parsed files.
  • actionlint 1.7.12 reports the same six shellcheck notes as on main, none in lines this touches.
  • zizmor 1.31.1: the two excessive-permissions findings on main (audit.yml's read-all, and ci.yml with no block) are gone, and nothing new appears.
  • Not run: the writing jobs themselves (GHCR pushes, the release, the CLA bot). They keep exactly the grants they have today, apart from statuses above. This PR's own CI exercises ci.yml, audit.yml and the pull-request paths of docker-publish.yml and ns8-module.yml. cla.yml runs from main on pull_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

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>

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

  • ci.yml gets contents: read — the single check job only checks out (full history, plus one git fetch origin <base> for the CLA-ledger step) and writes nothing back to GitHub.
  • docker-publish.yml / ns8-module.yml get read-only defaults — the job-level grants that already existed (packages: write on the image builds, packages: read on arm64-smoke, contents: write on release, which runs gh release create) sit unchanged on top of the read-only token.
  • audit.yml: read-all → contents: read — sbom and claims-guard only check out, build, scan and upload a workflow artifact; the scorecard job's security-events/id-token grant is untouched.
  • cla.yml moves its writes onto the job — top-level contents: read, job-level actions/contents/pull-requests write. Dropping statuses: write is consistent with the action: I read contributor-assistant/github-action@v2.6.1's src/*.ts and it calls only git.*, issues.*, pulls.get, actions.*, repos.getContent and GraphQL — never the statuses endpoint.
  • test-module.yml gains a read-only default — the caller job's grant set (contents, pull-requests, statuses) is identical to main; 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?

Pullfrog  | View workflow run | Using deepseek-v4.1-flash | 𝕏

@shockalotti
shockalotti merged commit 1509c3c into Calnode:main Nov 10, 2026
11 checks passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants