Tag 9: Härten
Ziel: notes-api so bauen und starten, dass der Prozess keine Rechte hat, die er nicht braucht, Build Checks plus hadolint jedes schwächere Dockerfile abweisen und dockle das fertige Image prüft. · Dauer: ca. 90 min · Voraussetzung: Tag 8
Briefing
- Im Image: numerischer User, Dateien gehören root
und sind nur lesbar (
COPY --chmod), keine Shell. Schreibrechte nur dort, wo die App schreiben muss. - Beim Start:
--read-only(Root-Dateisystem schreibgeschützt),--cap-drop ALL(auch root verliert seine Sonderrechte),--security-opt no-new-privileges(kein Rechtegewinn über setuid-Programme). - Im Build: Build Checks von BuildKit
(
docker build --check,# check=error=true) und hadolint mit.hadolint.yaml. Beide finden verschiedene Fehler. - Nach dem Build: dockle liest das fertige Image
(Config, History, Dateien) und prüft es gegen den CIS Docker Benchmark
(
CIS-DI-…) und eigene Regeln (DKL-…).
Dockerfile ──► hadolint ──► docker build --check ──► Image ──► docker run
USER root, as/FROM-Casing, USER 65532 --read-only
Registries, Secrets in ARG/ENV, 0555 --cap-drop ALL
ShellCheck Shell-Form CMD ohne Shell no-new-privileges
Drill 1: Bestandsaufnahme
source ~/docker-lab/setup/env.sh
mkdir -p ~/docker-lab/tag09 && cd ~/docker-lab/tag09
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag08/notes/." .Die zweite Kopie legt den Stand vom Ende von Tag 8 darüber – auch wenn du ihn übersprungen hast. Bau ihn und schau, wem die Dateien im Image gehören:
docker build -q -t notes-api:tag09-vorher notes-api
docker image inspect -f 'User={{.Config.User}}' notes-api:tag09-vorher
docker create --name notes-export notes-api:tag09-vorher >/dev/null
docker export notes-export | tar --numeric-owner -tvf - | grep -E 'notes-api|\.crt'
docker rm notes-export >/dev/nullErwartet (gekürzt, kann je nach Version abweichen):
sha256:…
User=65532:65532
-rw-r--r-- 0 0 0 222597 Oct 27 10:14 etc/ssl/certs/ca-certificates.crt
-rwxr-xr-x 0 0 0 7798968 Oct 29 18:02 notes-api
docker export schreibt das Dateisystem eines Containers
als tar, ganz ohne Shell im Image. Beides gehört root
(0 0), der User 65532 kann es also nicht verändern. Das ist
aber nur ein Zufall der umask im build-Stage, keine Absicht. Größen und
Zeiten weichen bei dir ab.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Rechte festschreiben mit
--chmod
Schreib das Dockerfile neu. Neu sind Zeile 2 (erklärt Drill 7) und
das --chmod am Binary im Final-Stage:
cat > notes-api/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
# check=error=true
ARG GO_VERSION=1.27
# in Produktion: @sha256:… pinnen, siehe Tag 8
FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
FROM base AS test
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
go vet ./... && go test ./...
FROM base AS build
ARG TARGETOS TARGETARCH
ARG VERSION=dev
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
-o /out/notes-api .
FROM scratch AS final
# Dateien gehören root; das Binary ist nur les- und ausführbar. Kein --chmod an
# Dateien in neuen Ordnern: Es gälte auch für die Ordner (siehe Drill 2).
COPY --link --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --link --from=build --chmod=555 /out/notes-api /notes-api
LABEL org.opencontainers.image.title="notes-api" \
org.opencontainers.image.description="Notiz-API aus dem Trainingslager" \
org.opencontainers.image.source="https://example.com/docker-lab/notes"
EXPOSE 8080
USER 65532:65532
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
CMD ["/notes-api", "healthcheck"]
STOPSIGNAL SIGTERM
ENTRYPOINT ["/notes-api"]
EOF
docker build -q -t notes-api:tag09 notes-api
docker create --name notes-export notes-api:tag09 >/dev/null
docker export notes-export | tar --numeric-owner -tvf - | grep -E 'notes-api|\.crt'
docker rm notes-export >/dev/nullErwartet (gekürzt, kann je nach Version abweichen):
sha256:…
-rw-r--r-- 0 0 0 222597 Oct 27 10:14 etc/ssl/certs/ca-certificates.crt
-r-xr-xr-x 0 0 0 7798968 Oct 29 18:11 notes-api
Das Binary hat jetzt kein Schreibrecht mehr, auch nicht für root. Die
CA-Datei gehört root und ist für 65532 ohnehin nur lesbar. Sie bekommt
bewusst kein --chmod:
Achtung: Legt
COPYfehlende Zielordner an, bekommen diese dieselben Rechte wie die Datei.--chmod=444 … /etc/ssl/certs/in einem scratch-Stage erzeugt also/etc,/etc/sslund/etc/ssl/certsmitr--r--r--, ohne dasx, das man zum Betreten eines Ordners braucht. Der User 65532 kommt dann weder an die Zertifikate noch an das von Docker eingehängte/etc/resolv.conf, jede DNS-Abfrage scheitert.--chmoddaher nur für Dateien, deren Zielordner schon existiert – wie/beim Binary.
Drei weitere Regeln:
- Nicht
--chown=65532:65532auf Programme und Konfiguration: Dann darf die App ihr eigenes Binary überschreiben.--chownnur für Verzeichnisse mit Schreibbedarf. - Mit
--linkwerden Dateien in ein leeres Dateisystem kopiert.--chownbraucht dann numerische IDs, Namen wienodelassen sich dort nicht auflösen. --chmodkann oktal (555) und ab Dockerfile 1.14 auch symbolisch (--chmod=u=rwX,go=rX,--chmod=g=u).docker/dockerfile:1ist neuer.
Fortschritt speichern? Kostenlos registrieren
Drill 3: root, Capabilities und no-new-privileges
Das scratch-Image hat kein id und kein
grep. Zum Ausprobieren nimmst du den
base-Stage, ein Alpine mit Go:
docker build -q --target base -t notes-api:tag09-base notes-api
docker run --rm notes-api:tag09-base id
docker run --rm --user 65532:65532 notes-api:tag09-base id
docker run --rm notes-api:tag09-base grep -E '^(CapEff|NoNewPrivs)' /proc/self/status
docker run --rm --cap-drop ALL --security-opt no-new-privileges \
notes-api:tag09-base grep -E '^(CapEff|NoNewPrivs)' /proc/self/status
docker run --rm --cap-drop ALL notes-api:tag09-base chown 65532 /src/go.modErwartet (gekürzt, kann je nach Version abweichen):
sha256:…
uid=0(root) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),…
uid=65532 gid=65532 groups=65532
CapEff: 00000000a80425fb
NoNewPrivs: 0
CapEff: 0000000000000000
NoNewPrivs: 1
chown: /src/go.mod: Operation not permitted
Warum? a80425fb ist die Bitmaske der Capabilities, die
Docker standardmäßig vergibt (u. a. CHOWN,
NET_RAW, SETUID). Mit
--cap-drop ALL ist sie null, und selbst root darf kein
chown mehr. NoNewPrivs: 1 verhindert, dass ein
setuid-Programm wie su dem Prozess später neue Rechte
gibt.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Read-only mit tmpfs
docker run --rm --read-only notes-api:tag09-base touch /src/neu
docker run --rm --read-only --tmpfs /tmp:rw,noexec,nosuid,size=16m \
notes-api:tag09-base sh -c 'touch /tmp/neu && echo "/tmp beschreibbar"; touch /neu'Erwartet (kann je nach Version abweichen):
touch: /src/neu: Read-only file system
/tmp beschreibbar
touch: /neu: Read-only file system
--read-only schützt das ganze Root-Dateisystem. Was die
App wirklich schreiben muss, bekommt gezielt ein --tmpfs
(flüchtig, im RAM) oder ein Volume (dauerhaft). Ein Angreifer kann dann
weder Werkzeuge ablegen noch das Binary austauschen.
Fortschritt speichern? Kostenlos registrieren
Drill 5: notes-api voll gehärtet
docker run -d --name notes-api -p 127.0.0.1:8080:8080 \
--read-only --cap-drop ALL --security-opt no-new-privileges \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag09
sleep 3
docker inspect -f '{{.State.Health.Status}}' notes-api
docker inspect notes-api \
| jq -c '.[0].HostConfig | {ReadonlyRootfs, CapDrop, SecurityOpt}'
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
-d '{"text":"gehärtet"}'
docker exec notes-api /notes-api healthcheck && echo "healthcheck per exec: ok"
docker exec notes-api shErwartet (gekürzt, kann je nach Version abweichen):
3c4f…
healthy
{"ReadonlyRootfs":true,"CapDrop":["ALL"],"SecurityOpt":["no-new-privileges"]}
{"id":"9a2e…","text":"gehärtet"}
healthcheck per exec: ok
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh":
executable file not found in $PATH: unknown
Warum klappt das ohne eine einzige Capability? Port 8080 liegt über
1024, also braucht notes-api kein NET_BIND_SERVICE. Sie
schreibt nichts auf die Platte, und der Healthcheck ist das Binary
selbst statt curl aus einer Shell. Ohne Shell kann auch ein
Angreifer mit Codeausführung kein sh starten.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Build Checks
Build Checks sind der eingebaute Linter von BuildKit (ab Dockerfile 1.8, buildx 0.15). Das Übungsobjekt:
K=~/docker-lab/code/tag09/Dockerfile.kaputt
cat "$K"Erwartet:
# syntax=docker/dockerfile:1
# Absichtlich kaputt – Übungsobjekt für Build Checks und hadolint (Tag 9)
FROM golang:1.27-alpine as build
ARG NOTES_API_KEY
WORKDIR /src
COPY . .
RUN go build -o /out/notes-api .
FROM scratch
COPY --from=build /out/notes-api /notes-api
USER root
CMD /notes-api--check baut nichts, sondern prüft nur:
docker build --check -f "$K" notes-api
echo "Exit-Code: $?"Erwartet (gekürzt, kann je nach Version abweichen):
FromAsCasing - https://docs.docker.com/go/dockerfile/rule/from-as-casing/
'as' and 'FROM' keywords' casing do not match
Dockerfile.kaputt:3
--------------------
2 | # Absichtlich kaputt – Übungsobjekt für Build Checks und hadolint (Tag 9)
3 | >>> FROM golang:1.27-alpine as build
4 | ARG NOTES_API_KEY
--------------------
SecretsUsedInArgOrEnv - https://docs.docker.com/go/dockerfile/rule/secrets-used-…
Do not use ARG or ENV instructions for sensitive data (ARG "NOTES_API_KEY")
Dockerfile.kaputt:4
…
JSONArgsRecommended - https://docs.docker.com/go/dockerfile/rule/json-args-recommended/
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior …
Dockerfile.kaputt:12
…
Exit-Code: 1
Ein normaler Build meldet dieselben Funde nur als Warnung und läuft
durch. Das Ergebnis startet trotzdem nicht, denn die Shell-Form braucht
/bin/sh, und das gibt es in scratch nicht:
docker build -t notes-api:tag09-kaputt -f "$K" notes-api 2>&1 | tail -6
docker run --rm notes-api:tag09-kaputtErwartet (gekürzt, kann je nach Version abweichen):
3 warnings found (use docker --debug to expand):
- FromAsCasing: 'as' and 'FROM' keywords' casing do not match (line 3)
- SecretsUsedInArgOrEnv: Do not use ARG or ENV instructions for sensitive data
(ARG "NOTES_API_KEY") (line 4)
- JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended
behavior related to OS signals (line 12)
docker: Error response from daemon: … exec: "/bin/sh": stat /bin/sh: no such file or
directory: unknown
Fortschritt speichern? Kostenlos registrieren
Drill 7: Die check-Direktive
Zeile 2 deines Dockerfiles macht aus jeder Warnung einen Fehler. Sie
muss wie # syntax ganz oben stehen, vor der ersten
Anweisung:
head -2 notes-api/Dockerfile
docker build --check notes-api
echo "Exit-Code: $?"Erwartet (gekürzt, kann je nach Version abweichen):
# syntax=docker/dockerfile:1
# check=error=true
[+] Building 1.1s (4/4) FINISHED docker:colima
=> [internal] load build definition from Dockerfile 0.0s
=> [internal] load metadata for docker.io/library/golang:1.27-alpine 0.6s
=> [internal] load .dockerignore 0.0s
Check complete, no warnings found.
Exit-Code: 0
Dieselben Schalter gibt es ohne Änderung am Dockerfile über das
Build-Argument BUILDKIT_DOCKERFILE_CHECK. Erst einzelne
Regeln auslassen, dann alles verschärfen:
docker build --check -f "$K" \
--build-arg BUILDKIT_DOCKERFILE_CHECK="skip=FromAsCasing,JSONArgsRecommended" \
notes-api 2>&1 | grep -E '^[A-Za-z]+ - https'
docker build -q -f "$K" --build-arg BUILDKIT_DOCKERFILE_CHECK=error=true \
notes-api 2>&1 | tail -1Erwartet (gekürzt, kann je nach Version abweichen):
SecretsUsedInArgOrEnv - https://docs.docker.com/go/dockerfile/rule/secrets-used-…
ERROR: lint violation found for rules: FromAsCasing, SecretsUsedInArgOrEnv,
JSONArgsRecommended
Im Dockerfile kombinierst du beides mit Semikolon:
# check=skip=JSONArgsRecommended;error=true.
skip=all schaltet alle Checks ab.
Sicherheit:
SecretsUsedInArgOrEnvnie perskipabschalten. Was diese Regel meldet, steht später für jeden lesbar im Image (Tag 11). Der richtige Weg ist ein Secret-Mount (Tag 13).
Fortschritt speichern? Kostenlos registrieren
Drill 8: hadolint mit .hadolint.yaml
hadolint liest die Konfiguration aus .hadolint.yaml im
aktuellen Verzeichnis, also im Projektordner:
cat > .hadolint.yaml <<'EOF'
# .hadolint.yaml – gilt für alle Dockerfiles, wenn hadolint im Projektordner läuft
failure-threshold: warning
override:
error:
- DL3002 # letzter USER ist root
- DL3025 # CMD/ENTRYPOINT in Shell-Form
trustedRegistries:
- docker.io
- gcr.io
- ghcr.io
EOF
hadolint notes-api/Dockerfile notes-worker/Dockerfile notes-web/Dockerfile
echo "Exit: $?"
hadolint - < "$K"
echo 'FROM quay.io/lab/tool:1.0' | hadolint -Erwartet:
Exit: 0
-:11 DL3002 error: Last USER should not be root
-:12 DL3025 error: Use arguments JSON notation for CMD and ENTRYPOINT arguments
-:1 DL3026 error: Use only an allowed registry in the FROM image
override hebt DL3002 und
DL3025 von Warnung auf Fehler,
failure-threshold lässt hadolint schon bei Warnungen
scheitern, trustedRegistries erlaubt nur Base-Images aus
den genannten Registries. Vergleich mit Drill 6: hadolint übersieht den
Key in ARG, die Build Checks übersehen
USER root. Du brauchst beide.
Tipp: Eine bewusste Ausnahme gehört direkt über die Zeile:
# hadolint ignore=DL3002– mit einem Kommentar, warum.
Fortschritt speichern? Kostenlos registrieren
Drill 9: dockle prüft das fertige Image
hadolint und die Build Checks lesen das Dockerfile. dockle liest das Image, also auch alles, was aus dem Base-Image stammt, und braucht dafür kein Dockerfile.
| dockle | |
|---|---|
| Aufgabe | Container-Images auf Sicherheit und Best Practices prüfen |
| Besonderheit | prüft Image-Config, History und Dateisystem; Regeln aus dem CIS Docker Benchmark |
| Projekt | github.com/goodwithtech/dockle (Apache-2.0) |
| Version im Buch | 0.4.15 (letztes Release Januar 2025) |
Zum Vergleich brauchst du das naive Image aus Tag 0 noch einmal:
docker build -q -t notes-api:naiv -f notes-api/Dockerfile.naiv notes-api
dockle --no-color notes-api:naiv | grep -E '^(FATAL|WARN|INFO)'
dockle --no-color notes-api:tag09Erwartet (gekürzt, kann je nach Version abweichen):
sha256:…
FATAL - CIS-DI-0010: Do not store credential in environment variables/files
FATAL - DKL-DI-0005: Clear apt-get caches
WARN - CIS-DI-0001: Create a user for the container
INFO - CIS-DI-0005: Enable Content trust for Docker
INFO - CIS-DI-0006: Add HEALTHCHECK instruction to the container image
INFO - CIS-DI-0008: Confirm safety of setuid/setgid files
INFO - DKL-LI-0003: Only put necessary files
SKIP - DKL-LI-0001: Avoid empty password
* failed to detect etc/shadow,etc/master.passwd
SKIP - DKL-LI-0002: Be unique UID/GROUP
* failed to detect etc/passwd
* failed to detect etc/group
INFO - CIS-DI-0005: Enable Content trust for Docker
* export DOCKER_CONTENT_TRUST=1 before docker pull/build
Das naive Image fällt mit dem Key in ENV
(CIS-DI-0010) und root (CIS-DI-0001) durch,
dazu Altlasten aus golang:1.27: apt-Listen,
setuid-Programme wie su und passwd.
notes-api:tag09 hat davon nichts. Die beiden SKIP heißen:
Ohne /etc/passwd im scratch-Image gibt es keine
Benutzerliste zu prüfen. Übrig bleibt CIS-DI-0005, Content
Trust (signierte Images über Notary).
Bewusste Ausnahmen gehören mit Begründung in
.dockleignore im aktuellen Ordner.
--exit-code 1 macht aus dockle ein Gate,
--exit-level legt fest, ab welcher Stufe:
cat > .dockleignore <<'EOF'
# .dockleignore – bewusste Ausnahmen, je mit Begründung
# Content Trust: im Labor ohne Notary; Images werden per Digest gepinnt (Tag 8)
CIS-DI-0005
EOF
dockle --no-color --exit-code 1 --exit-level info notes-api:tag09 >/dev/null
echo "tag09 – Exit-Code: $?"
dockle --no-color --exit-code 1 --exit-level warn notes-api:naiv >/dev/null
echo "naiv – Exit-Code: $?"
docker rmi notes-api:naiv >/dev/nullErwartet:
tag09 – Exit-Code: 0
naiv – Exit-Code: 1
Ohne --exit-code endet dockle immer mit 0, auch bei
FATAL; in einer Pipeline also nie vergessen. Für einzelne
Läufe geht statt der Datei auch -i CIS-DI-0005.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Die Check-Direktive steht in Zeile 2:
cd ~/docker-lab/tag09
sed -n 2p notes-api/DockerfileErwartet:
# check=error=true
hadolint und die Build Checks sind still:
hadolint notes-api/Dockerfile; echo "Exit: $?"
docker build --check notes-api 2>&1 | tail -1Erwartet:
Exit: 0
Check complete, no warnings found.
Das kaputte Dockerfile fällt durch:
docker build --check -f ~/docker-lab/code/tag09/Dockerfile.kaputt notes-api \
>/dev/null 2>&1; echo "Exit: $?"Erwartet:
Exit: 1
Das Image läuft als UID 65532:
docker image inspect --format '{{.Config.User}}' notes-api:tag09Erwartet:
65532:65532
Der gehärtete Container ist healthy:
docker ps --filter name=notes-api --format '{{.Status}}'Erwartet (Zeit weicht ab):
Up 5 minutes (healthy)
Im Container gibt es keine Shell:
docker exec notes-api sh -c trueErwartet (gekürzt):
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh":
executable file not found in $PATH
Dazu dockle:
dockle --no-color --exit-code 1 --exit-level info notes-api:tag09 >/dev/null; echo $?Erwartet: dockle findet mit der Ausnahme aus
.dockleignore nichts mehr.
0
Challenge
Prüf notes-api:tag09 und notes-web:tag09
gegen die Regeln von heute: numerischer User ungleich root, keine Shell,
HEALTHCHECK vorhanden, Start mit
--read-only --cap-drop ALL --security-opt no-new-privileges.
Ein Befehl pro Regel.
Hinweis: docker create plus
docker export | tar -t liefert die Dateiliste eines Images,
auch wenn darin weder Shell noch ls existieren.
Lösung
Erst notes-web bauen. Dann User und Healthcheck beider Images:
docker build -q -t notes-web:tag09 notes-web >/dev/null
docker image inspect --format '{{.Config.User}}' notes-api:tag09 notes-web:tag09
docker image inspect --format '{{json .Config.Healthcheck}}' notes-web:tag09Erwartet:
65532:65532
node
null
notes-web läuft als node, mit Namen statt UID, und hat
keinen Healthcheck. Gibt es eine Shell?
docker create --name notes-probe notes-web:tag09
docker export notes-probe | tar -t | grep -E '^bin/(ba)?sh$'
docker rm notes-probeErwartet (ID weicht ab):
3f9c…
bin/sh
notes-probe
Und startet notes-api gehärtet?
docker rm -f notes-api
docker run -d --name notes-hart --read-only --cap-drop ALL \
--security-opt no-new-privileges -e NOTES_API_KEY=lab-api-key-123 notes-api:tag09
sleep 5
docker ps --filter name=notes-hart --format '{{.Status}}'Erwartet (ID und Zeit weichen ab):
notes-api
7d1e…
Up 5 seconds (healthy)
notes-api besteht alles. notes-web läuft zwar als Nicht-root, aber
mit Namen statt UID, und node:24-alpine bringt eine Shell
mit. Ein USER 1000:1000 (UID des Users node im
offiziellen Image) behebt das erste, ein distroless-Image für Node das
zweite (Tag 6, Tag 8). Zum Schluss aufräumen:
docker ps -a --filter name=^notes- --format '{{.Names}}' | xargs -r docker rm -f
docker image ls --format '{{.Repository}}:{{.Tag}}' \
| grep -E '^(notes-|localhost:5001/)' | xargs -r docker rmi
docker buildx prune --builder docker-lab --all --forceFortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- In Kubernetes gehören dieselben Regeln in den
securityContext:runAsNonRoot,runAsUser: 65532,readOnlyRootFilesystem: true,allowPrivilegeEscalation: false,capabilities.drop: ["ALL"]. Der Pod Security Standard „restricted” erzwingt einen Großteil davon. - OpenShift startet Container mit einer zufälligen UID in der Gruppe
0. Dateien, die die App schreiben muss, brauchen dort Gruppenrechte, z.
B.
--chown=65532:0plus--chmod=g=u. - Mit
# check=error=truedie Frontend-Version pinnen (z. B.# syntax=docker/dockerfile:1.xstatt:1), sonst bricht ein neu eingeführter Check irgendwann ohne Codeänderung den Build. - hadolint und
docker build --checklaufen als eigener CI-Job vor dem Build;trustedRegistrieszeigt dort nur auf den internen Spiegel (Harbor, Artifactory). - Weitere Schichten: Docker-Standardprofile für seccomp und AppArmor nicht abschalten, rootless Docker oder User-Namespaces auf Build- und Laufzeit-Hosts.