How to Secure Dockerfile Build Configurations on Linux

What this check reads

Which branch runs depends on whether dockle is on PATH. If it is, the check runs dockle --exit-code 0 --format json <img> against the first 3 tagged local images and counts occurrences of "level":"FATAL" in the JSON: one or more is the WARN, a zero count is the PASS, and findings below fatal are not counted at all. If it is not, the check falls back to reading docker inspect -f '{{.Config.Healthcheck}}' on up to 10 images, where a literal <nil> means no HEALTHCHECK is defined. That fallback threshold is asymmetric: it WARNs only when every sampled image comes back <nil>, so a single image with a HEALTHCHECK passes the whole host.

The dockle branch does not work as intended today. Dockle pretty-prints its JSON with a space after the colon ("level": "FATAL"), so the compact pattern never matches and the count stays at zero. With dockle installed the check currently returns PASS whatever dockle found.

When it applies

Needs the docker binary and daemon access; otherwise SKIP. Which branch runs - and how much it actually tells you - depends on whether dockle is installed:

• With dockle - up to 3 images are audited against dockle's full checkpoint list, counting FATAL-level findings only. Lower-severity findings are ignored.
• Without dockle - up to 10 images are inspected for a single thing: whether .Config.Healthcheck is defined. The bar is very low, and asymmetric: WARN only if none of the images define a HEALTHCHECK, PASS if even one does. A host where 9 of 10 images lack a healthcheck therefore passes.

Note a HEALTHCHECK is an availability feature rather than a security control; this branch is a stand-in for a real best-practices audit, which is why the severity is LOW.

What each result means

Why it matters

Dockle implements the CIS Docker Benchmark section 4 (image) checks: no root user, no ADD for remote URLs, no credentials in ENV, no setuid files, HEALTHCHECK present, apt-get caches cleaned, etc. HEALTHCHECK (CIS Docker 4.6 / 5.26) lets the orchestrator detect hung services and avoid routing traffic to them.

Why it fails, and when it is wrong

• The dockle count never matches (known issue). The script greps for "level":"FATAL" with no space, and dockle writes "level": "FATAL". Fatal findings are counted as zero and the result is PASS.
• Even with the pattern corrected, only FATAL findings count. Dockle rates a missing non-root user (CIS-DI-0001) as WARN and a missing HEALTHCHECK (CIS-DI-0006) as INFO, so neither would move this result.
• The fallback passes if any image has a healthcheck; it is a weak proxy.
• Compose healthcheck: blocks set the check on the container, not the image; the fallback inspects images and misses them.
• Dockle FATAL levels include items that are hard to satisfy on some base images; review its output rather than treating the count as absolute.

How to fix it

for i in $(docker images --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>'); do
  echo "== $i"; dockle "$i"
done

RUN apt-get update && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*

HEALTHCHECK --interval=30s --timeout=3s CMD curl -fsS http://localhost:8080/healthz || exit 1

docker build -t app:1.4.3 . && dockle app:1.4.3
# expected: no FATAL findings

Verify the fix

# Run a real best-practices audit across every image, not three:
for i in $(docker images --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>'); do
  echo "== $i"; dockle --exit-code 0 "$i"
done
# expected: no FATAL findings

# The fallback's single test, per image:
docker images --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>' | \
  xargs -I{} sh -c 'printf "%s hc=%s\n" {} "$(docker image inspect -f "{{.Config.Healthcheck}}" {})"'
# <nil> means no HEALTHCHECK

# Confirm a healthcheck actually reports:
docker inspect -f '{{.State.Health.Status}}' <container>    # expected: healthy

Debugging

Sources

• Dockle
• Dockle checkpoints (the codes it reports)
• Docker: Dockerfile HEALTHCHECK
• Docker: Building best practices
• Docker Compose: healthcheck
• hadolint (Dockerfile linter, complements Dockle)

How the script reads this