Guardrails / docker

Dockerfiles declare no credential arguments

docker/no-build-secrets@v1

No ARG or ENV declared in a Dockerfile has a name that looks like a credential.

Id	docker/no-build-secrets
Version	v1
Category	docker
Default severity	error
Interpreter	python3
Timeout	30 seconds
Violations tolerated	0
Collects	docker

Collectors

This guardrail doesn't gather anything itself. It relies on the collectors below, which the CLI runs once per build before any check, and reads what they found from GUARDRAIL_FACTS. If a collector collects nothing, this guardrail is skipped, not failed.

Collector	Gathers	Inputs it is given
docker	Every Dockerfile in the tree, parsed without a tool: the stages it builds, the image each one starts from and how that image is pinned, the user the image ends as, the ports it exposes, the paths it copies in and the names of the build arguments and environment variables it declares, plus the findings of a hadolint report when the build already left one behind.	none

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

Configuration

{
  "guardrails": {
      "failOn": "error",
      "checks": [
          {
              "use": "docker/no-build-secrets@v1",
              "severity": "error",
              "with": {
                  "patterns": "*SECRET*,*TOKEN*,*PASSWORD*,*KEY*,*CREDENTIAL*"
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
patterns	Comma separated glob patterns, matched case-insensitively against the name of every ARG and every ENV. Only names are matched, because the collector records no values, which is what makes these facts safe to attach to a build.	*SECRET*,*TOKEN*,*PASSWORD*,*KEY*,*CREDENTIAL*	GUARDRAIL_INPUT_PATTERNS

How to fix

Pass the credential in at build time with a secret mount, which leaves nothing behind in the image:

RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci

docker build --secret id=npm_token,env=NPM_TOKEN .

An ARG is recorded in the image history, and docker history prints it. An ENV stays in the image, and docker inspect prints it. Either way, anyone who can pull the image can read the value, and once a value has reached a registry you have to rotate it, because deleting it is not enough.

This guardrail only sees names, never values: the collector records neither the default next to an ARG nor the value next to an ENV. A name containing TOKEN is reason enough to rotate the credential.

More in docker

• docker/base-pinned. Every image a Dockerfile builds from is pinned to a digest, so rebuilding the same commit starts from the same bytes.
• docker/healthcheck. Every Dockerfile declares a HEALTHCHECK, so the orchestrator can tell a container that is running from one that is actually working.
• docker/lint-clean. Every finding the Dockerfile linter reported is below the severity your team gates on.
• docker/nonroot-user. Every Dockerfile ends with a USER that is not root, so the container runs its process without privileges.

All 5 docker guardrails