Guardrails / docker

Dockerfile base images are pinned

docker/base-pinned@v1

Every image a Dockerfile builds from is pinned to a digest, so a rebuild of the same commit starts from the same bytes.

Id	docker/base-pinned
Version	v1
Category	docker
Default severity	error
Interpreter	python3
Timeout	30 seconds
Violations tolerated	0
Collects	docker

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
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, enriched with the findings of a hadolint report when the build already left one behind.	none

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": "docker/base-pinned@v1",
              "severity": "error",
              "with": {
                  "allowTags": "false",
                  "registries": ""
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
allowTags	Whether a tag other than latest counts as a pin. false requires a digest, which is the only reference that resolves to the same image twice.	false	GUARDRAIL_INPUT_ALLOWTAGS
registries	Comma separated registries an image may come from, such as docker.io,ghcr.io. Empty means any registry. An image naming no registry comes from Docker Hub, so name docker.io to allow those.	``	GUARDRAIL_INPUT_REGISTRIES

How to fix

Pin the image to the digest its tag resolves to today, so the base cannot change under a rebuild:

FROM node:20.11.1-alpine@sha256:e4b0d6d6b1a2c2a58e8dd8a0e0b1f0d0c2c9f9c5b3a1e0d9c8b7a6f5e4d3c2b1 AS build

docker buildx imagetools inspect node:20.11.1-alpine prints the digest to paste in, and Renovate and Dependabot both raise pull requests against a pinned digest, so the pin is maintained rather than frozen.

A tag moves whenever the publisher pushes. Two builds of the same commit then produce different images, and the one an auditor asks about is not the one that ran.

More in docker

• docker/healthcheck. Every Dockerfile declares a HEALTHCHECK, so the orchestrator can tell a container that is running from one that is working.
• docker/lint-clean. Every finding the Dockerfile linter reported sits below the severity the team gates on.
• docker/no-build-secrets. No ARG or ENV a Dockerfile declares is named like a credential.
• docker/nonroot-user. Every Dockerfile ends on a USER that is not root, so the container runs its process unprivileged.

All 5 docker guardrails