Gids voor Docker Build Secrets: veilig containerimages ontwikkelen

Ik heb ontelbare Docker-images gezien die per ongeluk zijn blootgesteld, met hardcoded API-sleutels, databasewachtwoorden en authenticatietokens die in hun lagen zijn ingebakken. Deze beveiligingslekken ontstaan vaak tijdens het buildproces, wanneer ontwikkelaars tijdelijk toegang nodig hebben tot privéresources maar onbedoeld inloggegevens in het uiteindelijke image bakken.

De uitdaging is dat traditionele manieren om met inloggegevens om te gaan tijdens builds, zoals omgevingsvariabelen of build-argumenten, niet zijn ontworpen voor eenmalig gebruik. Ze laten permanente sporen achter in imagemetadata of lagen, wat beveiligingsrisico's creëert die lang na de build blijven bestaan. Dit leidt tot een dilemma: hoe authenticeren tot privéresources tijdens builds zonder de beveiliging in gevaar te brengen?

Docker build secrets lossen deze cruciale beveiligingsuitdaging op door een mechanisme te bieden om gevoelige data tijdens image-builds te gebruiken zonder sporen achter te laten in het uiteindelijke artefact. 

In deze tutorial laat ik je zien hoe je build secrets effectief implementeert, van basisconcepten tot geavanceerde CI/CD-integratie, zodat je container-builds veilig blijven.

Als je nieuw bent met Docker, raad ik je aan om een van onze cursussen te volgen, zoals Introduction to Docker, Containerization and Virtualization with Docker and Kubernetes of Intermediate Docker. 

Wat zijn Docker build secrets?

Laten we beginnen met begrijpen wat build secrets anders maakt dan andere manieren van credential management. Docker build secrets zijn vluchtige stukjes gevoelige informatie die beschikbaar zijn tijdens het buildproces, maar nooit worden opgeslagen in de imagelagen of het bestandssysteem. Ze bestaan alleen in het geheugen tijdens specifieke buildstappen en verdwijnen zodra die stappen voltooid zijn.

De noodzaak van build secrets komt voort uit moderne ontwikkelworkflows. 

Je moet tijdens builds vaak authenticeren tegen privé package repositories, privé Git-repositories clonen, gelicentieerde software downloaden of interne API’s benaderen. 

Zonder build secrets grijpen ontwikkelaars naar gevaarlijke workarounds, zoals inloggegevens hardcoden in Dockerfiles, secrets doorgeven als build-argumenten (die blijven bestaan in imagemetadata) of te ruime base images maken met ingebedde credentials.

De risico’s van gebrekkige omgang met secrets zijn groot. Blootgestelde inloggegevens kunnen leiden tot ongeautoriseerde toegang tot productieomgevingen, datalekken, compliance-overtredingen en aanzienlijke reputatieschade. Veelvoorkomende lekken betreffen API-sleutels voor package managers, SSH-sleutels voor Git-acties, authenticatietokens voor interne services en databasecredentials voor build-time migraties.

Docker BuildKit: de basis voor veilige build secrets

Voordat we in de implementatie duiken, moet je BuildKit begrijpen, de moderne build-engine die veilige secrets mogelijk maakt. BuildKit is Docker’s next-gen builder die de klassieke engine vervangt en grote verbeteringen biedt in performance, caching en security.

BuildKit gebruikt een grafiekgebaseerd executiemodel dat afhankelijkheden tussen buildstappen volgt. Deze architectuur stelt BuildKit in staat secrets te mounten als tijdelijke bestandssystemen die alleen bestaan tijdens specifieke RUN-instructies, zodat ze nooit onderdeel worden van de imagelagen. 

In tegenstelling tot klassieke Docker-builds, waar alles in de buildcontext onderdeel wordt van de buildcache, behandelt BuildKit secrets als speciale resources die de layer cache volledig omzeilen.

BuildKit inschakelen is eenvoudig. Voor Docker 23.0 en hoger is BuildKit de standaardbuilder. Voor eerdere versies stel je de omgevingsvariabele DOCKER_BUILDKIT=1 in voordat je buildcommando’s uitvoert:

export DOCKER_BUILDKIT=1
docker build -t myapp .

Je kunt het ook permanent inschakelen door de Docker-daemon te configureren of Docker Buildx te gebruiken, dat altijd BuildKit gebruikt. Het belangrijkste verschil tussen klassieke builds en BuildKit-builds is dat secrets in klassieke builds in tussenlagen zouden blijven bestaan als je niet oplet, terwijl BuildKit garandeert dat secrets vluchtig zijn en nooit als onderdeel van het image op schijf worden geschreven.

Met BuildKits veilige fundament op zijn plek, gaan we kijken naar de verschillende soorten secrets die het mogelijk maakt en hoe je ze effectief implementeert.

Typen en implementatie van Docker build secrets

BuildKit ondersteunt drie primaire mechanismen voor het afhandelen van secrets tijdens builds, elk ontworpen voor specifieke use-cases. Begrijpen wanneer je welk type gebruikt, zorgt voor optimale beveiliging en functionaliteit.

Secret mounts: algemene gevoelige data

Secret mounts bieden de meest flexibele aanpak om tijdens builds met gevoelige data om te gaan. Je kunt secrets als bestanden mounten op opgegeven paden tijdens RUN-instructies, zodat credentials beschikbaar zijn voor buildcommando’s zonder in lagen te blijven hangen.

Het proces bestaat uit twee stappen: het secret doorgeven aan het buildcommando en het mounten in de Dockerfile. Maak eerst lokaal een secretbestand of gebruik een omgevingsvariabele. Verwijs er vervolgens naar tijdens de build:

docker build --secret id=api_key,src=./api_key.txt -t myapp .

Mount in je Dockerfile het secret tijdens de RUN-instructie die het nodig heeft:

RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) && \
    curl -H "Authorization: Bearer $API_KEY" https://api.example.com/package > /app/data.json

Standaard worden secrets gemount op /run/secrets/<id>, maar je kunt aangepaste doelen opgeven met de parameter target. 

Best practices zijn: mount secrets alleen in de specifieke RUN-commando’s die ze nodig hebben, kopieer secrets nooit naar het image-bestandssysteem en gebruik multi-stage builds om fases die secrets vereisen te scheiden van het uiteindelijke image. 

De bron kan een bestandspad zijn, of gebruik env om secrets via omgevingsvariabelen door te geven: --secret id=token,env=API_TOKEN.

Om een secret als omgevingsvariabele te mounten in plaats van als bestand, gebruik je de optie env:

RUN --mount=type=secret,id=db_user,env=DB_USER \
    --mount=type=secret,id=db_password,env=DB_PASSWORD \
    ./setup-database.sh

Je kunt zowel target als env samen gebruiken om een secret zowel als bestand als als omgevingsvariabele te mounten. 

Best practices zijn: mount secrets alleen in specifieke RUN-commando’s die ze nodig hebben, kopieer ze nooit naar het image-bestandssysteem en gebruik multi-stage builds om secret-fases te scheiden van finale images.

SSH-mounts: veilige toegang tot privéresources

SSH-mounts behandelen specifiek SSH-gebaseerde authenticatie, vooral voor toegang tot privé Git-repositories tijdens builds. In plaats van SSH-sleutels in het image te kopiëren (een beveiligingsnachtmerrie), bieden SSH-mounts tijdelijke toegang tot je SSH-agent tijdens de build.

Zorg ervoor dat je SSH-agent lokaal draait met de vereiste sleutels geladen. Verwijs vervolgens naar de SSH-mount in je Dockerfile:

RUN --mount=type=ssh \
    git clone git@github.com:myorg/private-repo.git /app

Bouw het image met SSH-forwarding ingeschakeld:

docker build --ssh default -t myapp .

Voor meerdere hosts met verschillende sleutels kun je benoemde SSH-mounts opgeven:

RUN --mount=type=ssh,id=github \
    git clone git@github.com:myorg/repo.git

Geef vervolgens specifieke sleutels door tijdens de build:

docker build --ssh github=$HOME/.ssh/github_key -t myapp .

Je zult merken dat deze aanpak de veiligheid waarborgt doordat privésleutels nooit in het image worden blootgesteld, terwijl geauthenticeerde toegang tot privérepositories tijdens het buildproces mogelijk blijft.

Git-authenticatie voor remote contexts

Wanneer je Docker-build toegang nodig heeft tot privé Git-repositories, zowel als buildcontext zelf als bij het ophalen van dependencies tijdens de build, heb je een manier nodig om te authenticeren zonder credentials in te bakken. Dit komt vooral voor bij builds vanaf een privé repository-URL of wanneer ADD-instructies privécode ophalen.

BuildKit biedt twee vooraf gedefinieerde secrets voor Git-authenticatie: GIT_AUTH_TOKEN en GIT_AUTH_HEADER. Dit zijn "pre-flight" secrets die de builder authenticeren voordat Dockerfile-instructies worden uitgevoerd, zodat het initiële ophalen van de repository veilig is.

Het meest gebruikelijke patroon gebruikt GIT_AUTH_TOKEN voor token-gebaseerde HTTPS-authenticatie:

GIT_AUTH_TOKEN=$(cat ~/.github-token) docker build \
    --secret id=GIT_AUTH_TOKEN \
    https://github.com/myorg/private-repo.git

Dit werkt naadloos met ADD-instructies die privérepositories ophalen:

FROM alpine
ADD https://github.com/myorg/private-configs.git /configs

Voor vluchtige CI/CD-omgevingen injecteer je tokens vanuit de secret store van je platform:

- name: Build from private repo
  env:
    GIT_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    docker build --secret id=GIT_AUTH_TOKEN https://github.com/myorg/app.git

Het secret GIT_AUTH_HEADER biedt een alternatief voor aangepaste authenticatieschema’s wanneer standaard token-authenticatie niet volstaat.

Hoe gebruik je Docker build secrets

Nu we de typen build secrets hebben behandeld, gaan we bekijken hoe je ze effectief inzet in praktijksituaties.

Secrets aanmaken en structureren voor build-time

Een goede voorbereiding van secrets is cruciaal voor de veiligheid. Bewaar secrets in bestanden buiten je Docker-buildcontext, zorg dat ze in .gitignore en .dockerignore staan en gebruik restrictieve bestandsrechten (600 of 400).

Voor meerdere secrets maak je een aparte secrets-map:

mkdir -p .secrets
echo "my-api-key" > .secrets/api_key
chmod 600 .secrets/*

Verwijs er daarna naar tijdens builds:

docker build \
    --secret id=api_key,src=.secrets/api_key \
    --secret id=db_password,src=.secrets/db_password \
    -t myapp .

Voor secrets op basis van omgevingsvariabelen, gangbaar in CI/CD:

docker build \
    --secret id=api_key,env=API_KEY \
    --secret id=db_pass,env=DB_PASSWORD \
    -t myapp .

Integratie met multi-stage builds

Multi-stage builds zijn krachtig in combinatie met build secrets. Gebruik secrets in vroege fases om dependencies op te halen en kopieer daarna alleen noodzakelijke artefacten naar de laatste fase:

# Buildfase - secrets worden hier gebruikt
FROM python:3.11 AS builder
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) && \
    curl -H "Authorization: Bearer $API_KEY" https://api.company.com/data.json -o data.json && \
    pip install -r requirements.txt

# Finale fase - geen secrets aanwezig
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /app/data.json ./data.json
COPY . .
CMD ["python", "app.py"]

Dit zorgt ervoor dat secrets alleen bestaan tijdens de builder-fase en nooit in het uiteindelijke image verschijnen.

Multi-stage builds gaan elegant om met één secret, maar in de praktijk zijn toepassingen vaak complexer. 

Laten we bekijken hoe je scenario’s met meerdere secrets of complexe buildvereisten beheert

Omgaan met meerdere secrets en complexe scenario’s

Complexe builds vereisen vaak meerdere secrets binnen dezelfde RUN-instructie. BuildKit ondersteunt het gelijktijdig mounten van meerdere secrets:

RUN --mount=type=secret,id=api_key \
    --mount=type=secret,id=db_password \
    API_KEY=$(cat /run/secrets/api_key) && \
    DB_PASS=$(cat /run/secrets/db_password) && \
    ./configure.sh

Voor scenario’s waarin meerdere commando’s secrets nodig hebben, combineer je commando’s in één RUN-instructie om het aantal secret-mounts te minimaliseren en toch de veiligheidsgrenzen te behouden.

Security best practices voor Docker build secrets

Build secrets correct implementeren vereist het volgen van beproefde security-praktijken. Dit zijn de patronen die ik het meest effectief vind om de veiligheid tijdens het hele buildproces te waarborgen.

Voorkomen van blootstelling en lekken van secrets

Controleer na het bouwen van een image of secrets niet zijn gelekt door de imagelagen te inspecteren:

docker history myapp:latest
docker save myapp:latest | tar -x

Bekijk de uitgepakte lagen op gevoelige data. Maak daarnaast onderscheid tussen build-time secrets (tijdelijk, gebruikt tijdens builds) en runtime secrets (nodig wanneer containers draaien). Gebruik nooit build secrets voor runtime-credentials. Gebruik in plaats daarvan Docker secrets, Kubernetes secrets of omgevingsvariabelen die bij runtime worden geïnjecteerd.

Voeg secretbestanden altijd toe aan .gitignore:

# .gitignore
.secrets/
*.key

En aan .dockerignore om te voorkomen dat ze per ongeluk in buildcontexts terechtkomen:

# .dockerignore
.secrets/
*.key
.env

Secrets beheren in CI/CD-omgevingen

CI/CD-platforms bieden native secret management dat naadloos integreert met Docker build secrets. In GitHub Actions:

- name: Build Docker image
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: |
    docker build \
      --secret id=api_key,env=API_KEY \
      -t myapp .

Het belangrijkste principe is gebruikmaken van de secret stores van het platform, in plaats van secrets in repositories op te slaan. CI/CD-secrets worden geïnjecteerd als omgevingsvariabelen, die BuildKit direct kan gebruiken via het env-sourcetype.

Secret-permissies en toegangsbeheer

Als je bouwt als niet-rootgebruiker, zorg dan dat secretbestanden de juiste leesrechten hebben. Als je Dockerfile met USER overschakelt naar een niet-rootgebruiker, mount je secrets op locaties die voor die gebruiker toegankelijk zijn:

FROM python:3.11-slim
RUN useradd -m appuser
USER appuser

RUN --mount=type=secret,id=token,uid=1000 \
    cat /run/secrets/token > /dev/null

Implementeer voor betere security-compliance strategieën voor secretrotatie. Gebruik waar mogelijk kortlevende tokens, automatiseer rotatie in CI/CD-pijplijnen en houd auditlogs bij van het gebruik van secrets. 

Overweeg secrets met vervaldatums en geautomatiseerde vernieuwingsprocessen om blootstellingsvensters te minimaliseren.

Tot nu toe hebben we ons gericht op single-container builds, maar moderne applicaties bestaan vaak uit meerdere services. Laten we bekijken hoe Docker Compose de mogelijkheden voor build secrets uitbreidt naar multi-servicearchitecturen.

Build secrets integreren met Docker Compose

Docker Compose vereenvoudigt het beheren van build secrets in multi-serviceapplicaties. Definieer secrets bovenaan in je docker-compose.yml en verwijs ernaar in de buildconfiguratie van services:

services:
  app:
    build:
      context: .
      secrets:
        - api_key
        - db_password
  
secrets:
  api_key:
    file: ./.secrets/api_key
  db_password:
    environment: DB_PASSWORD

Mount de secrets vervolgens in je Dockerfile zoals gebruikelijk:

RUN --mount=type=secret,id=api_key \
    --mount=type=secret,id=db_password \
    ./setup.sh

Build met Compose:

docker-compose build

Dit patroon schaalt goed voor applicaties met meerdere services die verschillende secrets nodig hebben, met centraal secretbeheer en behoud van beveiligingsgrenzen tussen services.

Wanneer je build secrets implementeert in je projecten, kom je onvermijdelijk problemen tegen. Laten we de meest voorkomende uitdagingen en hun oplossingen doornemen om je te helpen effectief te troubleshooten.

Veelvoorkomende uitdagingen en troubleshooting

Zelfs met een juiste implementatie kom je uitdagingen tegen. Dit zijn de meest voorkomende issues en oplossingen.

Syntaxisfouten en problemen met mount-declaraties

De --mount-syntaxis is strikt. Veelgemaakte fouten zijn ontbrekende komma’s tussen parameters, onjuiste parameternamen en verkeerde mounttypes. De correcte syntaxis is:

RUN --mount=type=secret,id=secret_name,target=/path \
    command

Als builds falen met "secret not found", controleer dan of BuildKit is ingeschakeld en of het ID in de Dockerfile overeenkomt met de --secret id in je buildcommando.

Secrets niet beschikbaar of niet gevonden

Als secrets niet toegankelijk zijn, controleer dan of het bronbestand bestaat en leesbaar is:

cat .secrets/api_key
docker build --secret id=api_key,src=.secrets/api_key .

Controleer voor omgevingsvariabelen of ze zijn gezet:

echo $API_KEY
docker build --secret id=api_key,env=API_KEY .

Verwarring tussen omgevingsvariabele en bestand

Met build secrets worden secrets standaard als bestanden gemount op /run/secrets/<id>. Wil je ze als omgevingsvariabele gebruiken, lees dan de bestandsinhoud uit:

RUN --mount=type=secret,id=token \
    export TOKEN=$(cat /run/secrets/token) && \
    curl -H "Authorization: Bearer $TOKEN" https://api.example.com

Gebruik nooit build-argumenten (ARG) voor secrets, want die blijven bestaan in imagemetadata.

Persistentie- en layer-cachingproblemen

Secrets blijven bewust niet bestaan tussen RUN-instructies. Als meerdere RUN-commando’s hetzelfde secret nodig hebben, combineer ze dan of remount het secret:

RUN --mount=type=secret,id=token \
    command1

RUN --mount=type=secret,id=token \
    command2

BuildKit zorgt ervoor dat secrets nooit in de layer cache terechtkomen.

Als je de basis onder de knie hebt en de meest voorkomende problemen kunt oplossen, kom je soms situaties tegen die een meer geavanceerde aanpak vereisen. Laten we geavanceerde use-cases en randgevallen verkennen die verder gaan dan standaardimplementaties.

Geavanceerde toepassingen van Docker build secrets

Voor complexe deployments moet je rekening houden met extra aandachtspunten bovenop de basisimplementatie.

Secrets in complexe CI/CD-pijplijnen

Multi-stage CI/CD-pijplijnen vereisen vaak secrets in verschillende fases. Implementeer fase-specifieke secrets in plaats van credentials te delen. Gebruik features van het CI/CD-platform voor het scope’n van secrets, zodat alleen bepaalde fases toegang hebben tot bepaalde secrets. Automatiseer het opruimen van secrets na builds om blootstellingsvensters te minimaliseren.

Secrets met niet-Docker builders

Alternatieve builders zoals Buildah en Kaniko hebben wisselende ondersteuning voor de secret-syntaxis van BuildKit. Buildah ondersteunt vergelijkbare secret-mounting via --secret flags. Kaniko, ontworpen voor Kubernetes-omgevingen, gebruikt andere mechanismen, meestal Kubernetes-secrets die als volumes worden gemount. Raadpleeg bij niet-Docker builders hun specifieke documentatie, want implementaties verschillen aanzienlijk.

Secrets en security-compliance

Build secrets sluiten aan bij security-compliancekaders door auditeerbare, vluchtige toegang tot credentials te bieden. 

Voor AVG/GDPR-compliance moet je ervoor zorgen dat secrets geen persoonsgegevens in lagen lekken. SOC2-eisen profiteren van audittrails voor secrets—log wanneer secrets worden gebruikt en door wie. Houd registraties bij van secrettoegang voor compliance-audits.

Secrets roteren en bijwerken

Stel processen in voor secretrotatie zonder builds te verstoren. Gebruik versienamen voor secretbestanden of naamgevingsconventies voor omgevingsvariabelen die wisselen tussen versies mogelijk maken. 

Automatiseer rotatie in CI/CD-pijplijnen waarbij secrets uit centrale stores worden ververst. Monitor de vervaldatum van tokens en automatiseer verlengingsprocessen.

Conclusie: best practices en aanbevelingen

Docker build secrets vormen een fundamentele security-verbetering voor de ontwikkeling van gecontaineriseerde applicaties. In deze tutorial hebben we onderzocht hoe je secrets veilig implementeert, van basis-secret mounts tot complexe CI/CD-integraties.

De kernpunten zijn duidelijk: gebruik altijd de secret-mountmechanismen van BuildKit in plaats van build-argumenten of hardcoded credentials, implementeer multi-stage builds om fases met secrets te isoleren van de uiteindelijke images, maak gebruik van secretmanagement van je CI/CD-platform voor geautomatiseerde workflows en audit images regelmatig om te verifiëren dat secrets niet in lagen zijn gelekt.

Voor organisaties die deze praktijken omarmen: begin met een secretmanagementbeleid dat definieert welke secrets build-time toegang nodig hebben, stel geautomatiseerde rotatieschema’s in, implementeer uitgebreide tests om te verifiëren dat secrets niet in images achterblijven en train developmentteams in het juiste omgaan met secrets. Door build secrets te behandelen als een cruciale securitycomponent, verklein je jouw aanvalsoppervlak aanzienlijk en bouw je veiligere gecontaineriseerde applicaties.

Blijf leren met de volgende bronnen:

• Docker for Data Science Cheat Sheet
• Run a Docker Image as a Container: A Practical Beginner’s Guide
• Top 18 Docker Commands to Build, Run, and Manage Containers
• Containerization: Docker and Kubernetes for Machine Learning