Guide des secrets de build Docker : sécuriser le développement d’images de conteneur

J’ai vu quantité d’images Docker exposées par erreur, contenant des clés d’API, des mots de passe de base de données et des jetons d’authentification intégrés en dur dans leurs couches. Ces failles de sécurité surviennent souvent pendant le processus de build : les développeurs ont besoin d’un accès temporaire à des ressources privées, mais finissent par « cuire » des identifiants dans l’image finale.

Le problème, c’est que les méthodes classiques de gestion des identifiants pendant les builds, comme les variables d’environnement ou les arguments de build, ne sont pas pensées pour un usage éphémère. Elles laissent des traces permanentes dans les métadonnées ou les couches de l’image, créant des vulnérabilités qui persistent bien après la fin du build. D’où un dilemme : comment s’authentifier auprès de ressources privées pendant les builds sans compromettre la sécurité ?

Les secrets de build Docker résolvent ce problème critique en offrant un mécanisme pour utiliser des données sensibles durant les builds sans laisser de traces dans l’artéfact final. 

Dans ce tutoriel, je vous montre comment mettre en place ces secrets efficacement, des notions de base aux intégrations CI/CD avancées, pour des builds de conteneurs réellement sécurisés.

Si vous débutez avec Docker, je vous recommande l’un de nos cours, comme Introduction to Docker, Containerization and Virtualization with Docker and Kubernetes, ou Intermediate Docker. 

Qu’est-ce que les secrets de build Docker ?

Commençons par comprendre ce qui différencie les secrets de build des autres approches de gestion d’identifiants. Les secrets de build Docker sont des informations sensibles, éphémères, disponibles pendant le processus de build mais jamais stockées dans les couches de l’image ni sur le système de fichiers. Ils existent uniquement en mémoire durant des étapes précises et disparaissent une fois ces étapes terminées.

Le besoin de secrets de build découle des workflows modernes de développement d’applications. 

Vous devez souvent vous authentifier auprès de registres de packages privés, cloner des dépôts Git privés, télécharger des logiciels sous licence ou accéder à des API internes pendant les builds. 

Sans secrets de build, les développeurs adoptent des contournements risqués : identifiants en dur dans les Dockerfiles, passage de secrets via des arguments de build (qui persistent dans les métadonnées), ou création d’images de base trop permissives intégrant des identifiants.

Les risques d’une gestion inadéquate des secrets sont considérables. Des identifiants exposés peuvent conduire à un accès non autorisé aux systèmes de production, des fuites de données, des violations de conformité et des dommages réputationnels importants. Les fuites courantes touchent les clés d’API pour les gestionnaires de packages, les clés SSH pour les opérations Git, les jetons d’authentification pour des services internes et les identifiants de base de données pour des migrations au moment du build.

Docker BuildKit : la base des secrets de build sécurisés

Avant de passer à la mise en œuvre, vous devez comprendre BuildKit, le moteur de build moderne qui rend possibles des secrets sécurisés. BuildKit est le builder de nouvelle génération de Docker, qui remplace l’ancien moteur et apporte de fortes améliorations en performance, en cache et en sécurité.

BuildKit utilise un modèle d’exécution en graphe qui suit les dépendances entre étapes. Cette architecture permet de monter les secrets comme des systèmes de fichiers temporaires, présents uniquement durant des instructions RUN spécifiques, garantissant qu’ils n’entrent jamais dans les couches de l’image. 

À la différence des builds Docker classiques, où tout le contexte de build influence le cache, BuildKit traite les secrets comme des ressources spéciales qui contournent totalement le cache des couches.

Activer BuildKit est simple. Depuis Docker 23.0, il est actif par défaut. Pour les versions antérieures, définissez la variable d’environnement DOCKER_BUILDKIT=1 avant d’exécuter vos commandes de build :

export DOCKER_BUILDKIT=1
docker build -t myapp .

Vous pouvez aussi l’activer de façon permanente via la configuration du démon Docker, ou utiliser Docker Buildx, qui s’appuie toujours sur BuildKit. La grande différence avec les builds classiques : les secrets pourraient persister dans les couches intermédiaires si l’on n’y prend garde, alors que BuildKit garantit leur caractère éphémère et qu’ils ne sont jamais écrits sur le disque de l’image.

Avec la base sécurisée de BuildKit, voyons maintenant les différents types de secrets qu’il prend en charge et comment les implémenter efficacement.

Types de secrets de build Docker et mise en œuvre

BuildKit prend en charge trois mécanismes principaux pour gérer les secrets pendant les builds, chacun adapté à des cas d’usage spécifiques. Savoir lequel utiliser selon la situation garantit sécurité et efficacité.

Montages de secrets : données sensibles polyvalentes

Les montages de secrets offrent l’approche la plus flexible pour manipuler des données sensibles pendant les builds. Ils permettent de monter les secrets comme des fichiers à des chemins précis durant des instructions RUN, rendant les identifiants disponibles sans les persister dans les couches.

Le processus se fait en deux temps : passer le secret à la commande de build, puis le monter dans le Dockerfile. Créez d’abord un fichier secret localement ou utilisez une variable d’environnement. Référencez-le ensuite au build :

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

Dans votre Dockerfile, montez le secret lors de l’instruction RUN qui en a besoin :

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

Par défaut, les secrets sont montés sous /run/secrets/<id>, mais vous pouvez définir une cible personnalisée avec le paramètre target. 

Bonnes pratiques : monter les secrets uniquement dans les RUN qui en ont besoin, ne jamais copier un secret dans le système de fichiers de l’image, et utiliser des builds multi‑étapes pour isoler les étapes nécessitant des secrets de l’image finale. 

La source peut être un chemin de fichier, ou env pour transmettre des secrets via des variables d’environnement : --secret id=token,env=API_TOKEN.

Pour monter un secret comme variable d’environnement au lieu d’un fichier, utilisez l’option env :

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

Vous pouvez combiner target et env pour monter un secret à la fois comme fichier et comme variable d’environnement. 

Bonnes pratiques : ne monter les secrets que dans les RUN concernés, ne jamais les copier dans le système de fichiers de l’image, et utiliser des builds multi‑étapes pour isoler ces phases de l’image finale.

Montages SSH : accès sécurisé à des ressources privées

Les montages SSH gèrent l’authentification SSH, principalement pour accéder à des dépôts Git privés pendant les builds. Plutôt que de copier des clés SSH dans l’image (catastrophique pour la sécurité), ils offrent un accès temporaire à votre agent SSH pendant le build.

Pour les utiliser, assurez-vous que votre agent SSH local tourne avec les clés nécessaires chargées. Référencez ensuite le montage SSH dans votre Dockerfile :

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

Construisez l’image avec le transfert SSH activé :

docker build --ssh default -t myapp .

Pour plusieurs hôtes avec des clés différentes, vous pouvez définir des montages SSH nommés :

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

Puis fournir les clés spécifiques au moment du build :

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

Cette approche maintient la sécurité : aucune clé privée n’est exposée dans l’image, tout en permettant un accès authentifié aux dépôts privés pendant le build.

Authentification Git pour les contextes distants

Lorsque votre build Docker doit accéder à des dépôts Git privés, soit en tant que contexte de build, soit pour récupérer des dépendances pendant le build, il faut s’authentifier sans embarquer d’identifiants. C’est courant lors d’un build depuis une URL de dépôt privé ou avec des instructions ADD qui récupèrent du code privé.

BuildKit fournit deux secrets prédéfinis pour l’authentification Git : GIT_AUTH_TOKEN et GIT_AUTH_HEADER. Ce sont des secrets « pre‑flight » qui authentifient le builder avant l’exécution de la moindre instruction Dockerfile, sécurisant la récupération initiale du dépôt.

Le schéma le plus courant utilise GIT_AUTH_TOKEN pour une authentification HTTPS par jeton :

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

Cela fonctionne parfaitement avec des instructions ADD qui récupèrent des dépôts privés :

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

Dans des environnements CI/CD éphémères, injectez les jetons depuis le coffre‑fort de votre plateforme :

- 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

Le secret GIT_AUTH_HEADER propose une alternative pour des schémas d’authentification personnalisés quand un jeton standard ne suffit pas.

Comment utiliser les secrets de build Docker

Maintenant que nous avons vu les types de secrets, voyons comment les implémenter efficacement dans des scénarios concrets.

Créer et organiser les secrets pour le build

Une bonne préparation des secrets est essentielle. Stockez-les dans des fichiers en dehors du contexte de build Docker, ajoutez-les à .gitignore et .dockerignore, et appliquez des permissions restrictives (600 ou 400).

Pour plusieurs secrets, créez un répertoire dédié :

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

Référencez-les ensuite au moment du build :

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

Pour des secrets transmis via variables d’environnement, fréquents en CI/CD :

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

Intégration avec des builds multi‑étapes

Les builds multi‑étapes deviennent très puissants avec les secrets. Utilisez-les dans les premières étapes pour récupérer des dépendances, puis copiez uniquement les artéfacts nécessaires dans l’étape finale :

# Étape de build — secrets utilisés ici
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

# Étape finale — aucun secret présent
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"]

Ainsi, les secrets n’existent que durant l’étape « builder » et n’apparaissent jamais dans l’image finale.

Les builds multi‑étapes gèrent très bien un secret unique, mais les applications réelles sont souvent plus complexes. 

Voyons comment gérer des scénarios impliquant plusieurs secrets ou des exigences de build plus fines.

Gérer plusieurs secrets et scénarios complexes

Des builds complexes nécessitent souvent plusieurs secrets dans la même instruction RUN. BuildKit permet de monter plusieurs secrets simultanément :

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

Si plusieurs commandes ont besoin des mêmes secrets, regroupez-les dans une seule instruction RUN pour limiter les montages tout en conservant des barrières de sécurité.

Bonnes pratiques de sécurité pour les secrets de build Docker

Bien implémenter les secrets de build suppose de suivre des pratiques établies. Voici les schémas les plus efficaces pour maintenir la sécurité tout au long du processus.

Prévenir l’exposition et les fuites de secrets

Après avoir construit une image, vérifiez que des secrets n’ont pas fui en inspectant les couches :

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

Examinez les couches extraites à la recherche de données sensibles. Distinguez également les secrets de build (temporaires, utilisés pendant la construction) des secrets d’exécution (nécessaires au runtime). N’utilisez jamais des secrets de build comme identifiants d’exécution. Préférez les secrets Docker, les secrets Kubernetes ou des variables d’environnement injectées au runtime.

Ajoutez toujours les fichiers de secrets à .gitignore :

# .gitignore
.secrets/
*.key

Et à .dockerignore pour éviter de les inclure par mégarde dans les contextes de build :

# .dockerignore
.secrets/
*.key
.env

Gérer les secrets en CI/CD

Les plateformes CI/CD offrent une gestion native des secrets, qui s’intègre parfaitement aux secrets de build Docker. Avec GitHub Actions :

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

Le principe clé : exploiter les coffres-forts fournis par la plateforme plutôt que de stocker des secrets dans les dépôts. Les secrets CI/CD sont injectés comme variables d’environnement, que BuildKit peut consommer directement via la source env.

Permissions et contrôle d’accès des secrets

Si vous construisez en tant qu’utilisateur non‑root, assurez-vous que les fichiers de secrets ont des permissions de lecture adaptées. Si votre Dockerfile utilise USER pour passer à un utilisateur non‑root, montez les secrets dans des emplacements accessibles à cet utilisateur :

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

Pour une conformité renforcée, mettez en place des stratégies de rotation des secrets. Utilisez des jetons de courte durée quand c’est possible, automatisez la rotation dans les pipelines CI/CD et conservez des journaux d’audit d’utilisation des secrets. 

Prévoyez des secrets avec dates d’expiration et des processus de renouvellement automatisés afin de réduire la fenêtre d’exposition.

Jusqu’ici, nous avons parlé de builds pour un seul conteneur, mais les applications modernes reposent souvent sur plusieurs services. Voyons comment Docker Compose étend les secrets de build aux architectures multi‑services.

Intégrer les secrets de build avec Docker Compose

Docker Compose simplifie la gestion des secrets de build dans des applications multi‑services. Dans votre docker-compose.yml, définissez les secrets au niveau global et référencez-les dans la configuration de build des services :

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

Dans votre Dockerfile, montez ensuite les secrets comme d’habitude :

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

Construisez avec Compose :

docker-compose build

Ce schéma passe à l’échelle pour des applications à plusieurs services ayant des secrets distincts, avec une gestion centralisée des secrets tout en préservant des frontières de sécurité entre services.

En déployant les secrets de build, vous rencontrerez inévitablement des problèmes. Voyons les défis les plus fréquents et leurs solutions pour dépanner efficacement.

Problèmes courants et dépannage

Même avec une bonne implémentation, des difficultés peuvent surgir. Voici les problèmes les plus courants et comment les résoudre.

Erreurs de syntaxe et problèmes de déclaration de montage

La syntaxe de --mount est stricte. Erreurs fréquentes : virgules manquantes entre les paramètres, noms de paramètres incorrects, ou type de montage erroné. La syntaxe correcte est :

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

Si le build échoue avec « secret not found », vérifiez que BuildKit est activé et que l’ID dans le Dockerfile correspond au --secret id passé à la commande de build.

Secrets indisponibles ou introuvables

Si un secret n’est pas accessible, vérifiez que la source existe et est lisible :

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

Pour les variables d’environnement, confirmez qu’elles sont définies :

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

Confusion entre variable d’environnement et fichier

Par défaut, les secrets sont montés comme fichiers sous /run/secrets/<id>. Pour les utiliser comme variables d’environnement, lisez le contenu du fichier :

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

N’utilisez jamais les arguments de build (ARG) pour des secrets, car ils persistent dans les métadonnées de l’image.

Persistance et problèmes de cache des couches

Par conception, les secrets ne persistent pas entre deux instructions RUN. Si plusieurs RUN ont besoin du même secret, regroupez-les ou remontez le secret :

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

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

BuildKit garantit que les secrets n’entrent jamais dans le cache des couches.

Une fois les fondamentaux et le dépannage courant maîtrisés, vous pourrez rencontrer des besoins plus avancés. Explorons des cas d’usage et limites qui vont au‑delà des implémentations standard.

Usages avancés des secrets de build Docker

Pour des déploiements complexes, vous aurez des considérations supplémentaires au‑delà de la mise en œuvre basique.

Secrets dans des pipelines CI/CD complexes

Les pipelines CI/CD multi‑étapes nécessitent souvent des secrets différents selon l’étape. Implémentez des secrets spécifiques par étape plutôt que de partager des identifiants. Utilisez les fonctionnalités de portée des secrets de votre plateforme pour limiter l’accès par étape. Automatisez le nettoyage des secrets après les builds pour réduire la fenêtre d’exposition.

Secrets avec des builders non‑Docker

Des builders alternatifs comme Buildah et Kaniko offrent un support variable de la syntaxe des secrets de BuildKit. Buildah propose des montages de secrets similaires via des --secret flags. Kaniko, conçu pour Kubernetes, s’appuie sur d’autres mécanismes, typiquement les secrets Kubernetes montés en volumes. Avec des builders non‑Docker, reportez-vous à leur documentation, les implémentations pouvant fortement différer.

Secrets et conformité

Les secrets de build s’alignent avec les cadres de conformité en offrant un accès aux identifiants éphémères et traçables. 

Pour le RGPD, veillez à ce qu’aucune information personnelle ne fuite dans les couches. Pour la SOC 2, mettez en place des traces d’audit des secrets : journalisez quand et par qui les secrets sont utilisés. Conservez des preuves d’accès pour les audits de conformité.

Rotation et mise à jour des secrets

Établissez des processus de rotation des secrets sans perturber les builds. Utilisez des fichiers de secrets versionnés ou des conventions de nommage de variables d’environnement permettant de basculer entre versions. 

Automatisez la rotation dans vos pipelines CI/CD en rafraîchissant les secrets depuis des coffres centraux. Pour les jetons avec date d’expiration, surveillez l’échéance et automatisez le renouvellement.

Conclusion : bonnes pratiques et recommandations

Les secrets de build Docker constituent une avancée majeure pour la sécurité du développement d’applications conteneurisées. Tout au long de ce tutoriel, nous avons vu comment les implémenter en sécurité, des montages de base aux intégrations CI/CD complexes.

Les points clés sont simples : utilisez toujours les mécanismes de montage de secrets de BuildKit plutôt que des arguments de build ou des identifiants en dur, mettez en place des builds multi‑étapes pour isoler les phases utilisant des secrets, exploitez la gestion des secrets de votre plateforme CI/CD pour automatiser les workflows, et auditez régulièrement vos images pour vérifier qu’aucun secret n’a fuité dans les couches.

Pour les organisations qui adoptent ces pratiques, commencez par une politique de gestion des secrets indiquant lesquels nécessitent un accès au moment du build, définissez des calendriers de rotation automatisée, mettez en place des tests complets pour vérifier l’absence de persistance des secrets dans les images, et formez vos équipes de développement aux bons réflexes. En traitant les secrets de build comme un composant de sécurité essentiel, vous réduirez significativement votre surface d’attaque et construirez des applications conteneurisées plus sûres.

Pour aller plus loin, consultez les ressources suivantes :

• 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