Guardrails / pipeline

Workflows declare the token permissions they need

pipeline/least-privilege-token@v1

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

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

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
workflow	The pipeline definitions in the checkout, read as they are written: which triggers start them, what permissions they hand a job, which runner each job asks for, and every action a step reaches for and how tightly it is pinned. Names and shapes only, never a secret, an input value or an environment value.	pipelines

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": "pipeline/least-privilege-token@v1",
              "severity": "error",
              "with": {
                  "pipelines": ".github/workflows/*.yml,.github/workflows/*.yaml,.gitlab-ci.yml,azure-pipelines*.yml,Jenkinsfile",
                  "allowWriteAll": "false"
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
pipelines	Comma separated globs naming the pipeline definitions to read.	.github/workflows/*.yml,.github/workflows/*.yaml,.gitlab-ci.yml,azure-pipelines*.yml,Jenkinsfile	GUARDRAIL_INPUT_PIPELINES
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 pipeline

• pipeline/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.
• pipeline/job-timeout-set. Every job declares how long it may run, so a hung job is cut off rather than holding a runner until the platform's own limit.
• pipeline/no-script-injection. No run step interpolates a ${{ }} expression an outsider controls, such as a pull request title or a branch name, straight into the shell body.
• pipeline/no-untrusted-checkout. No workflow triggered by pull_request_target, issue_comment or workflow_run checks out a revision of its own choosing, or passes the request's revision into a command.

All 5 pipeline guardrails