Hadolint : Analyse statique de Dockerfiles

Hadolint analyse vos Dockerfiles et détecte automatiquement les erreurs, les failles de sécurité et les mauvaises pratiques. Basé sur les recommandations officielles de Docker, il identifie les problèmes comme les versions non épinglées (DL3008), les pipes sans pipefail (DL4006) ou l’utilisation de latest (DL3007). Intégrable en CI/CD, il bloque les builds non conformes avant le déploiement.

Lorsqu’on écrit un Dockerfile, il est facile de faire des erreurs qui impactent la sécurité, les performances ou la maintenabilité des images. Hadolint s’appuie sur des règles bien définies pour proposer des corrections concrètes.

Fonctionnement

Hadolint est conçu pour analyser les Dockerfiles et détecter les erreurs, les mauvaises pratiques et les recommandations d’optimisation. Voici ses principales fonctionnalités.

Lorsqu’un Dockerfile est analysé, Hadolint renvoie une liste de recommandations classées par gravité. Chaque erreur est associée à un code spécifique qui permet de comprendre et corriger le problème.

Exemple d’analyse :

hadolint Dockerfile

Résultat typique :

Dockerfile:3 DL3008 warning: Pin versions in apt-get install
Dockerfile:6 DL4006 error: Set the SHELL option -o pipefail before RUN with a pipe in it

Hadolint aide aussi à identifier les problèmes liés aux dépendances, comme l’absence de versions épinglées dans les instructions RUN apt-get install. Cela permet d’éviter des builds non reproductibles et des erreurs inattendues.

Installation

L’installation de Hadolint est simple et s’adapte à plusieurs environnements. Voici comment procéder en fonction de votre système d’exploitation.

Linux et macOS

La méthode la plus simple consiste à télécharger le binaire directement :

sudo wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-$(uname -s)-$(uname -m)
sudo chmod +x /usr/local/bin/hadolint

Windows

Sous Windows, Hadolint peut être installé via Chocolatey :

choco install hadolint

Ou avec Scoop :

scoop install hadolint

Vérification de l’installation

On peut ensuite vérifier l’installation avec :

hadolint --version
Haskell Dockerfile Linter 2.14.0

Utilisation de base

Une fois Hadolint installé, son utilisation est simple. Il suffit de l’exécuter sur un Dockerfile pour obtenir un rapport détaillé des erreurs et recommandations.

Lancer une analyse de base

La commande la plus simple pour analyser un Dockerfile est :

hadolint Dockerfile

Si le fichier contient des erreurs, Hadolint affichera une liste avec le numéro de ligne, le code de la règle et une brève description du problème :

Dockerfile:3 DL3008 warning: Pin versions in apt-get install
Dockerfile:6 DL4006 error: Set the SHELL option -o pipefail before RUN with a pipe in it

Interpréter les résultats

Chaque message d’erreur est accompagné d’un code de règle (ex: DL3008, DL4006). Ces règles sont documentées sur le site officiel de Hadolint, ce qui permet de comprendre leur signification et comment les corriger.

Corriger les erreurs courantes

DL3008 : Ne pas installer des paquets sans version spécifique Mauvais exemple :
```
RUN apt-get install -y curl
```
Bon exemple :
```
RUN apt-get install -y curl=7.68.0-1ubuntu2.7
```

DL4006 : Utiliser SHELL pour modifier les options par défaut

Mauvais exemple :

RUN echo "Hello" | cat

Bon exemple :

SHELL ["/bin/bash", "-o", "pipefail", "-c"]
RUN echo "Hello" | cat

Exclure certaines règles

Si une règle n’est pas pertinente pour un projet, on peut l’ignorer avec :

hadolint --ignore DL3008 Dockerfile

Ou ajouter un commentaire directement dans le Dockerfile :

# hadolint ignore=DL3008
RUN apt-get install -y curl

Avec ces bases, Hadolint devient un outil incontournable pour améliorer la qualité des Dockerfiles et éviter les mauvaises pratiques.

Configuration d’Hadolint

Pour éviter de répeter les ignore à répéition, il suffit de créer un fichier .hadolint.yaml pour gérer la configuration :

ignored:
  - DL3008
  - DL4006

Intégration dans un pipeline CI/CD

L’intégration de Hadolint dans un pipeline CI/CD permet d’automatiser la vérification des Dockerfiles et d’empêcher le déploiement de mauvaises pratiques

GitLab CI/CD

Dans un projet GitLab, on peut ajouter une étape d’analyse Hadolint dans le fichier .gitlab-ci.yml :

stages:
  - lint

hadolint:
  image: hadolint/hadolint:v2.14.0-alpine
  stage: lint
  script:
    - hadolint Dockerfile

Si des erreurs sont détectées, le pipeline échouera et demandera une correction avant de poursuivre le déploiement.

GitHub Actions

Pour GitHub, on peut créer un workflow .github/workflows/hadolint.yml :

name: Hadolint

on: [push, pull_request]

jobs:
  hadolint:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Run Hadolint
        uses: hadolint/hadolint-action@v3.3.0
        with:
          dockerfile: Dockerfile

Ce workflow exécute Hadolint à chaque push ou pull request et affiche les erreurs directement dans l’interface de GitHub Actions.

À retenir

Prochaines étapes

Écrire un Dockerfile Bonnes pratiques pour rédiger des Dockerfiles efficaces

Trivy Scanner les vulnérabilités de vos images Docker

Dockle Vérifier les bonnes pratiques de sécurité des images

Container Structure Test Valider la structure de vos images Docker

Plus d’infos

Questions fréquentes

Qu'est-ce que Hadolint et à quoi sert-il ?

Hadolint est un linter pour Dockerfiles qui détecte automatiquement les erreurs de syntaxe, les mauvaises pratiques et les problèmes de sécurité. Basé sur les recommandations officielles de Docker et ShellCheck pour les scripts bash, il aide à écrire des images plus légères et reproductibles.

Définition

Hadolint (Haskell Dockerfile Linter) est un outil d'analyse statique conçu spécifiquement pour les Dockerfiles.

Fonctionnalités principales

Détection des erreurs : syntaxe incorrecte, instructions mal formées
Bonnes pratiques : versions non épinglées, utilisation de latest
Sécurité : droits root, secrets exposés
Shell : intègre ShellCheck pour analyser les commandes RUN

Exemple d'utilisation

hadolint Dockerfile
# Sortie : Dockerfile:3 DL3008 warning: Pin versions in apt-get install

Que signifie l'erreur DL3008 dans Hadolint ?

L'erreur DL3008 indique que les paquets installés via apt-get ne sont pas épinglés à une version spécifique. Cela rend les builds non reproductibles car la version installée peut changer. La solution est d'ajouter la version : apt-get install curl=7.68.0-1.

Signification

DL3008 : "Pin versions in apt-get install"

Cette règle signale que vous installez des paquets sans spécifier leur version exacte.

Problème

# ❌ Mauvais : version non déterministe
RUN apt-get install -y curl

Sans version épinglée, chaque build peut installer une version différente, rendant vos images non reproductibles.

Solution

# ✅ Bon : version épinglée
RUN apt-get install -y curl=7.68.0-1ubuntu2.7

Trouver la version

apt-cache policy curl

Que signifie l'erreur DL4006 dans Hadolint ?

L'erreur DL4006 signale un pipe dans une commande RUN sans l'option pipefail activée. Sans pipefail, seul le code de retour de la dernière commande est vérifié, masquant les erreurs des commandes précédentes. Ajoutez SHELL ["/bin/bash", "-o", "pipefail", "-c"] avant le RUN.

Signification

DL4006 : "Set the SHELL option -o pipefail before RUN with a pipe in it"

Problème

# ❌ Mauvais : si curl échoue, l'erreur est masquée
RUN curl -s https://example.com | grep pattern

Sans pipefail, seul le code de retour de grep est vérifié. Si curl échoue, le build continue.

Solution

# ✅ Bon : pipefail activé
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
RUN curl -s https://example.com | grep pattern

Alternative Alpine

Pour les images Alpine (ash/busybox), utilisez :

SHELL ["/bin/ash", "-eo", "pipefail", "-c"]

Comment ignorer une règle Hadolint ?

Pour ignorer une règle Hadolint, utilisez l'option --ignore en ligne de commande (hadolint --ignore DL3008 Dockerfile), ajoutez un commentaire inline dans le Dockerfile (# hadolint ignore=DL3008), ou configurez un fichier .hadolint.yaml avec la liste des règles ignorées.

Méthode 1 : Ligne de commande

hadolint --ignore DL3008 --ignore DL4006 Dockerfile

Méthode 2 : Commentaire inline

# hadolint ignore=DL3008
RUN apt-get install -y curl

Méthode 3 : Fichier de configuration

Créez .hadolint.yaml à la racine du projet :

ignored:
  - DL3008
  - DL4006
  - DL3015

Bonnes pratiques

Préférez ignorer au cas par cas (commentaire inline)
Documentez pourquoi vous ignorez une règle
Évitez d'ignorer les règles de sécurité

Comment intégrer Hadolint dans GitHub Actions ?

Pour intégrer Hadolint dans GitHub Actions, créez un workflow .github/workflows/hadolint.yml utilisant l'action officielle hadolint/hadolint-action@v3.3.0. Le workflow analysera automatiquement vos Dockerfiles à chaque push ou pull request et affichera les erreurs dans l'interface GitHub.

Workflow minimal

Créez .github/workflows/hadolint.yml :

name: Hadolint

on: [push, pull_request]

jobs:
  hadolint:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: hadolint/hadolint-action@v3.3.0
        with:
          dockerfile: Dockerfile

Options avancées

- uses: hadolint/hadolint-action@v3.3.0
  with:
    dockerfile: Dockerfile
    ignore: DL3008,DL4006
    failure-threshold: warning

Résultat

Les erreurs apparaissent directement dans l'onglet Checks de la PR.

Comment intégrer Hadolint dans GitLab CI ?

Pour intégrer Hadolint dans GitLab CI, ajoutez un job dans .gitlab-ci.yml utilisant l'image hadolint/hadolint:v2.14.0-alpine. Évitez l'image latest pour garantir des builds reproductibles. Le pipeline échouera si des erreurs sont détectées dans le Dockerfile.

Configuration GitLab CI

Ajoutez dans .gitlab-ci.yml :

stages:
  - lint

hadolint:
  image: hadolint/hadolint:v2.14.0-alpine
  stage: lint
  script:
    - hadolint Dockerfile

Avec fichier de configuration

hadolint:
  image: hadolint/hadolint:v2.14.0-alpine
  stage: lint
  script:
    - hadolint --config .hadolint.yaml Dockerfile

Bonnes pratiques

Pinnez la version : évitez :latest
Placez le lint en début de pipeline
Utilisez allow_failure: false pour bloquer les MR

Quelle est la différence entre Hadolint et Dockle ?

Hadolint analyse le code source des Dockerfiles avant le build pour détecter les erreurs de syntaxe et mauvaises pratiques. Dockle analyse les images Docker déjà construites pour vérifier la sécurité (secrets, droits root, ports). Les deux outils sont complémentaires dans une pipeline CI/CD.

Comparatif

Critère	Hadolint	Dockle
Analyse	Dockerfile (source)	Image construite
Moment	Avant build	Après build
Focus	Syntaxe, bonnes pratiques	Sécurité, CIS Benchmark
Détecte	DL3008, DL4006, DL3007	Secrets, root, ports

Utilisation complémentaire

# Pipeline CI/CD
stages:
  - lint      # Hadolint → vérifie le Dockerfile
  - build     # docker build
  - security  # Dockle → vérifie l'image
  - scan      # Trivy → vulnérabilités

Recommandation

Utilisez les deux : Hadolint pour le code, Dockle pour l'image finale.