Container Guardrails

Enforces best practices for container definitions and builds including tag stability, registry allowlists, required labels, build traceability, and security configurations.

Overview

This policy plugin validates container definitions (Dockerfiles) and CI build commands against common best practices and security requirements. It helps ensure consistent, secure, and reproducible container builds across your organization.

Policies

This plugin provides the following policies (use include to select a subset):

Required Data

This policy reads from the following Component JSON paths:

Installation

Add to your lunar-config.yml:

policies:
  - uses: github://earthly/lunar-lib/policies/container@v1.0.0
    on: ["domain:your-domain"]
    enforcement: report-pr
    # include: [no-latest, stable-tags, build-tagged]  # Only include specific policies
    # with:
    #   allowed_registries: "docker.io,gcr.io,ghcr.io"
    #   required_labels: "org.opencontainers.image.source,git_sha"

Examples

Passing Example

{
  "containers": {
    "definitions": [
      {
        "path": "Dockerfile",
        "valid": true,
        "base_images": [
          { "reference": "golang:1.21.5-alpine", "image": "golang", "tag": "1.21.5-alpine" },
          { "reference": "gcr.io/distroless/static:nonroot", "image": "gcr.io/distroless/static", "tag": "nonroot" }
        ],
        "final_stage": {
          "user": "nonroot",
          "has_healthcheck": true
        },
        "labels": {}
      }
    ]
  }
}

Failing Examples

Using :latest tag (fails no-latest, stable-tags)

{
  "containers": {
    "definitions": [
      {
        "path": "Dockerfile",
        "valid": true,
        "base_images": [
          { "reference": "node:latest", "image": "node", "tag": "latest" }
        ]
      }
    ]
  }
}

Using unstable tag (fails stable-tags)

{
  "containers": {
    "definitions": [
      {
        "path": "Dockerfile",
        "valid": true,
        "base_images": [
          { "reference": "node:20-alpine", "image": "node", "tag": "20-alpine" }
        ]
      }
    ]
  }
}

Using disallowed registry (fails allowed-registries)

{
  "containers": {
    "definitions": [
      {
        "path": "Dockerfile",
        "valid": true,
        "base_images": [
          { "reference": "my-private-registry.com/app:1.0.0", "image": "my-private-registry.com/app", "tag": "1.0.0" }
        ]
      }
    ]
  }
}

Remediation

no-latest / stable-tags

Replace unstable tags with:

• Digest (most stable): alpine@sha256:abc123...
• Full semver (stable): alpine:3.18.4

Avoid:

• Implicit latest: FROM alpine
• Explicit latest: FROM alpine:latest
• Partial versions: FROM node:20 or FROM node:20-alpine

allowed-registries

Use images from approved registries only. Update your Dockerfile or request the registry be added to the allowlist.

required-labels

Add the required labels to your Dockerfile:

LABEL org.opencontainers.image.source="https://github.com/org/repo"
LABEL org.opencontainers.image.version="1.0.0"

healthcheck

Add a HEALTHCHECK instruction:

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost/health || exit 1

user

Add a USER instruction to run as non-root:

USER nonroot
# or
USER 1000:1000

build-tagged

Add an explicit -t/--tag flag to your docker build command:

docker build -t myregistry.io/app:v1.2.3 .

required-labels

Labels can be added in either the Dockerfile or the build command:

# In Dockerfile (static labels)
LABEL org.opencontainers.image.source="https://github.com/org/repo"

# In build command (dynamic labels)
docker build -t app:v1 --label git_sha=$GITHUB_SHA .