Guardrails / github

Workflows declare the token permissions they need

github/least-privilege-token@v1

Every workflow declares permissions, and none of them takes write access to everything.

Id	github/least-privilege-token
Version	v1
Category	github
Default severity	error
Interpreter	python3
Timeout	30 seconds
Violations tolerated	0
Collects	github

Collectors

This guardrail gathers nothing itself. It depends on the collectors below, which the CLI runs once per build before any check, and reads what they found out of GUARDRAIL_FACTS. A collector that collects nothing skips this guardrail rather than failing it.

Collector	Gathers	Inputs it is given
github	What GitHub itself reads out of the repository: the Actions workflows in .github/workflows, read as they are written, and the CODEOWNERS file, read as rules. For a workflow, which events start it, what token permissions it hands a job, which runner each job asks for, and every action a step reaches for and how tightly it is pinned. For CODEOWNERS, every pattern in file order with the owners it names, and the owners that apply to the paths a guardrail asks about, resolved the way GitHub resolves them, where the last rule to match a path is the one that owns it. Names and shapes only, never a secret, an input value or an environment value.	workflows

The inputs above are this guardrail's own, passed straight through. Configuring one in buildnote.json changes what is collected, and two guardrails configured the same way share the one collection.

Configuration

{
  "guardrails": {
      "failOn": "error",
      "comment": true,
      "checks": [
          {
              "use": "github/least-privilege-token@v1",
              "severity": "error",
              "with": {
                  "workflows": ".github/workflows/*.yml,.github/workflows/*.yaml",
                  "allowWriteAll": "false"
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
workflows	Comma separated globs naming the workflows to read.	.github/workflows/*.yml,.github/workflows/*.yaml	GUARDRAIL_INPUT_WORKFLOWS
allowWriteAll	Whether permissions: write-all is accepted. It rarely should be.	false	GUARDRAIL_INPUT_ALLOWWRITEALL

How to fix

Declare the narrowest set the workflow actually needs, at the top of the file or on the job:

permissions:
  contents: read

A workflow that declares nothing inherits the repository default, which in many organisations is still write to everything. That token is available to every step, including every third party action the workflow runs, so the blast radius of a compromised action is whatever this block says it is.

More in github

• github/actions-pinned-by-digest. Every third party action a workflow uses is pinned to a full commit sha rather than to a tag or a branch.
• github/codeowners-catch-all. CODEOWNERS declares a rule matching every path, so a file nobody thought about still has an owner.
• github/codeowners-no-unowned-rules. No rule in CODEOWNERS names an empty set of owners, which would take ownership away from everything it matches.
• github/codeowners-owners-per-rule. Every rule in CODEOWNERS names at least the minimum owners and no more than the maximum, so review is neither one person's bus factor nor everybody's problem.
• github/codeowners-parses. Every line of CODEOWNERS that is not a comment reads as a rule to GitHub, so no ownership is silently lost to a line GitHub ignores.
• github/codeowners-present. The repository carries a CODEOWNERS file where GitHub looks for one, naming at least one rule, so every change has somebody to review it.
• github/codeowners-team-owned. Every rule in CODEOWNERS names at least one GitHub team, so ownership survives the people currently in it.
• github/job-timeout-set. Every job declares how long it may run, so a hung job is cut off rather than holding a runner until GitHub's own limit.

All 11 github guardrails