Guardrails / iac

Dockerfiles declare a health check

iac/dockerfile-healthcheck@v1

Every Dockerfile declares a HEALTHCHECK, so the orchestrator can tell a container that is running from one that is working.

Id	iac/dockerfile-healthcheck
Version	v1
Category	iac
Default severity	warning
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-healthcheck@v1",
              "severity": "warning",
              "with": {
                  "finalStageOnly": "true",
                  "ignore": ""
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
finalStageOnly	Whether only the file's last stage is judged. A build stage is thrown away and never runs, so it has nothing to health check.	true	GUARDRAIL_INPUT_FINALSTAGEONLY
ignore	Comma separated globs naming Dockerfiles that are not judged, such as one that only ever builds a job image.	``	GUARDRAIL_INPUT_IGNORE

How to fix

Add a HEALTHCHECK to the Dockerfile, probing the thing the container exists to do rather than the process being alive:

HEALTHCHECK --interval=30s --timeout=3s --start-period=20s \
  CMD curl -fsS http://localhost:8080/health || exit 1

Without one the runtime knows only that PID 1 has not exited. A process that is deadlocked, out of connections or serving 500s stays in the load balancer's rotation until somebody notices.

A Kubernetes deployment declares this as a readinessProbe instead, and that is a complete answer: set healthcheck to false for images that only ever run under a manifest that has one.

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-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/dockerfile-nonroot-user. Every Dockerfile ends on a USER that is not root, so the container runs its process unprivileged.
• 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