Guardrails / iac

Dockerfiles run as a non-root user

iac/dockerfile-nonroot-user@v1

Every Dockerfile ends on a USER that is not root, so the container runs its process unprivileged.

Id	iac/dockerfile-nonroot-user
Version	v1
Category	iac
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": "iac/dockerfile-nonroot-user@v1",
              "severity": "error",
              "with": {},
              "exemptions": []
          }
      ]
  }
}

How to fix

Create an unprivileged user in the image and switch to it before the entrypoint:

RUN addgroup -S app && adduser -S -G app app
USER app

The last USER in the file is what the container runs as, so a file that declares none runs as uid 0. A container that starts as root turns a bug in the application into a root-level problem on the host: a mounted path is writable, a capability is grantable, and an escape lands somewhere that matters.

Where the process has to bind a low port, publish it instead (docker run -p 80:8080) rather than staying root to bind 80.

More in iac

• iac/dockerfile-base-pinned. Every image a Dockerfile builds from is pinned to a digest, so a rebuild of the same commit starts from the same bytes.
• iac/dockerfile-healthcheck. Every Dockerfile declares a HEALTHCHECK, so the orchestrator can tell a container that is running from one that is working.
• iac/dockerfile-lint-clean. Every finding the Dockerfile linter reported sits below the severity the team gates on.
• iac/dockerfile-no-build-secrets. No ARG or ENV a Dockerfile declares is named like a credential.
• iac/terraform-modules-pinned. Every module a Terraform root takes from a registry or a git URL names the version it takes, so the same commit resolves to the same module twice.
• iac/terraform-no-plaintext-secrets. Every Terraform variable named like a credential declares sensitive = true.
• iac/terraform-providers-pinned. Every provider a live Terraform root requires is pinned to one exact version, and the lock file that resolves them is committed.
• iac/terraform-remote-state. Every live Terraform root stores its state in a remote backend, and no state file is left in the checkout.

All 11 iac guardrails