Plumber pour GitLab CI/CD : premier scan de conformité

Si votre pipeline GitLab CI/CD utilise des images Docker non épinglées, des includes sur main ou un build basé sur Docker-in-Docker, vous n’avez pas besoin de commencer par une plateforme complète de gouvernance. Vous avez besoin d’un premier scan clair. Plumber sert à ça : vous créez une configuration minimale, vous lancez plumber analyze, vous lisez trois ou quatre problèmes concrets, puis vous intégrez le contrôle dans GitLab CI/CD avec le composant officiel. Dans ce guide, on commence volontairement par la CLI, ensuite seulement par le composant GitLab, puis on termine par le PBOM, le score A-E et la Platform.

Ce que vous allez apprendre

• Créer une configuration minimale avec plumber config init, puis la valider avant le premier scan
• Lancer une analyse locale sur un dépôt GitLab et comprendre l’auto-détection du projet
• Corriger trois erreurs fréquentes : image non épinglée, include mutable, branche non protégée
• Ajouter le composant GitLab CI/CD officiel sans créer de doubles pipelines ni de job .pre inutilisable
• Exporter un PBOM et l’exploiter avec Trivy ou Grype

Version actuelle

Ce guide utilise Plumber CLI v0.1.84. Les versions récentes ont ajouté la commande plumber explain, le score A-E, les commentaires de merge request, les badges de conformité et plusieurs contrôles utiles pour GitLab CI/CD : DinD, scripts non vérifiés, variables surchargées et digest pinning.

Plumber en une phrase

Plumber est un scanner de conformité pour GitLab CI/CD. Il lit votre configuration de pipeline, interroge votre projet GitLab, puis signale les écarts les plus fréquents : images non fiables, tags mutables, branches non protégées, includes obsolètes, scripts téléchargés sans vérification ou usage de Docker-in-Docker.

Par où commencer ?

Votre situation	Porte d’entrée recommandée	Pourquoi
Vous découvrez Plumber	CLI locale	Vous comprenez d’abord ce que l’outil détecte et comment lire la sortie
Vous voulez l’ajouter rapidement à un pipeline existant	Composant GitLab CI/CD	Vous évitez d’écrire un job manuel complet
Vous devez centraliser plusieurs projets	Platform	Vous passez de l’analyse projet par projet à la gouvernance

Glissez pour voir

Recommandation pratique

Commencez par la CLI ou le composant GitLab. Gardez la Platform pour plus tard, quand vous aurez besoin d’historique, de reporting ou de pilotage multi-projets.

Prérequis

Avant de lancer votre premier scan, vous avez besoin de :

• un dépôt Git lié à un projet GitLab ;
• un token GitLab avec les scopes read_api et read_repository ;
• le rôle Maintainer sur le projet, ou un Project Access Token doté de ce rôle ;
• un terminal interactif si vous voulez utiliser plumber config init ;
• au moins une configuration .plumber.yaml si vous passez par la CLI.

Nuance importante entre CLI et composant GitLab

La CLI attend un fichier de configuration et échoue si elle n’en trouve pas. Le composant GitLab CI/CD, lui, peut retomber sur la configuration par défaut embarquée dans l’image si vous n’avez pas encore de .plumber.yaml dans le dépôt.

Installation

mise

mise use -g github:getplumber/plumber@0.1.84

Activation mise requise

L’installation via mise nécessite l’activation de mise dans votre shell, ou utilisez mise exec -- plumber.

Homebrew

brew tap getplumber/plumber
brew install getplumber/plumber/plumber@0.1.84

Binaire

# Télécharger une version précise depuis la page Releases
# https://github.com/getplumber/plumber/releases

Docker

# Toujours épingler la version, pas :latest
docker pull getplumber/plumber:0.1.84

Vérification :

plumber version

Vous devez voir plumber version 0.1.84 ou une version plus récente.

Notification de mise à jour

Depuis v0.1.45, Plumber vérifie automatiquement si une nouvelle version est disponible et vous en informe à la fin de chaque analyse. Désactivable avec PLUMBER_NO_UPDATE_CHECK=1.

Premier scan local en 5 minutes

Le chemin le plus simple est toujours le même : configurer, valider, scanner, corriger.

1. Créez une configuration minimale avec le wizard interactif

   plumber config init
   plumber config validate

   plumber config init pose des questions ciblées puis génère un fichier court, adapté à votre projet. plumber config validate vérifie ensuite que le YAML est correct et signale les fautes de frappe dans les noms de contrôles ou de clés.

2. Créez votre token GitLab

   Dans GitLab, ouvrez User Settings -> Access Tokens et créez un token avec read_api et read_repository.

   export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

3. Lancez l’analyse depuis le dépôt Git

   cd mon-projet
   plumber analyze

   Si votre dépôt possède un remote origin pointant vers GitLab, Plumber détecte automatiquement l’URL GitLab et le chemin du projet.

4. Lisez d’abord le résumé, pas toute la sortie

   Cherchez en priorité :

   • le pourcentage de conformité global ;
   • les contrôles en échec ;
   • les codes ISSUE-XXX ;
   • le nom précis du job concerné.

Chemin alternatif pour CI ou scripts

Si vous n’avez pas de terminal interactif, utilisez :

plumber config generate --output .plumber.yaml
plumber config validate

config generate écrit le template officiel complet, commenté. Il est plus long, mais il convient mieux à un premier commit ou à un usage automatisé.

Exemple réel de premier scan

Sur le dépôt de lab Pipeline Craft, la commande suivante permet d’analyser une branche de solution :

plumber analyze --config /tmp/plumber-guide.yaml --branch solution/lab-12 --score-point

Voici le début de la sortie observée :

Auto-detected GitLab URL: https://gitlab.com
Auto-detected project: Bob74/pipeline-craft
Using configuration: /tmp/plumber-guide.yaml
Analyzing project: Bob74/pipeline-craft on https://gitlab.com

Using remote CI configuration from branch: solution/lab-12
✓ [████████████████████] (18/18) Analysis complete

Et le résumé utile à lire :

Status: FAILED
Total (required: 100%): 75.0%

Controls in failure:
- ISSUE-103 ×5 : images non épinglées par digest
- ISSUE-412 ×1 : Docker-in-Docker détecté
- ISSUE-401 ×5 : jobs hardcodés

Plumber Score: E (0.0 / 100 pts)

Si l’auto-détection ne marche pas

Le cas le plus fréquent est simple : le dépôt n’a pas de remote origin, ou l’URL du remote ne pointe pas vers GitLab.

Dans ce cas, passez explicitement les paramètres :

plumber analyze --gitlab-url https://gitlab.com --project mon-groupe/mon-projet

Auto-détection : la règle à retenir

L’auto-détection fonctionne si votre dépôt Git possède un remote nommé origin vers GitLab, en SSH ou en HTTPS.

Trois erreurs fréquentes à corriger d’abord

Quand on débute, il est inutile de mémoriser immédiatement les 14 contrôles. Commencez par ces trois familles d’erreurs. Elles couvrent déjà une grande partie des problèmes visibles sur les pipelines réels.

1. Images non épinglées par digest

Dans le lab testé, Plumber a signalé :

HIGH [ISSUE-103] Job 'pytest' uses image without digest pinning: docker.io/python:3.12-slim
HIGH [ISSUE-103] Job 'docker-build' uses image without digest pinning: docker.io/docker:27

Le problème n’est pas seulement l’usage de latest. Un tag de version comme python:3.12-slim reste mutable. Si le registre republie l’image, votre pipeline peut exécuter autre chose demain.

Pour activer le mode strict, la clé se trouve ici :

.plumber.yaml

controls:
  containerImageMustNotUseForbiddenTags:
    enabled: true
    containerImagesMustBePinnedByDigest: true

Nuance importante sur ISSUE-103

Même si l’erreur remontée est ISSUE-103 (image non épinglée par digest), l’activation se fait toujours dans le contrôle containerImageMustNotUseForbiddenTags via la clé containerImagesMustBePinnedByDigest.

2. Includes sur main, master ou HEAD

Un include pointant sur une branche mutable rend votre pipeline difficile à reproduire et peut casser sans changement dans votre dépôt.

Avant

include:
  - project: security/templates
    file: /pipelines/sast.yml
    ref: main

Après

include:
  - project: security/templates
    file: /pipelines/sast.yml
    ref: v2.4.1

Le contrôle associé est includesMustNotUseForbiddenVersions avec ISSUE-404.

3. Branche principale non protégée

Si la branche par défaut n’est pas protégée, un push direct ou une modification non revue peut contourner vos pratiques de revue et de sécurité.

Le contrôle branchMustBeProtected vérifie cela et renvoie ISSUE-501 ou ISSUE-505 selon le problème : absence de protection ou protection incomplète.

Exemple minimal

controls:
  branchMustBeProtected:
    enabled: true
    defaultMustBeProtected: true
    namePatterns:
      - main
    allowForcePush: false

Une quatrième erreur très courante : Docker-in-Docker

Le lab a également remonté :

HIGH [ISSUE-412] Job 'docker-build' uses DinD service: docker:27-dind
Consider using Kaniko or Buildah instead

Sur des runners partagés, DinD augmente le risque d’évasion de conteneur et de mouvement latéral. Si vous construisez des images, privilégiez Kaniko ou Buildah.

Fichier de configuration : minimal d’abord, complet ensuite

Le fichier .plumber.yaml reste volontairement simple au début. Vous n’avez pas besoin d’activer tous les contrôles dès le premier jour.

Exemple minimal pour démarrer

.plumber.yaml

version: "1.0"

controls:
  containerImageMustNotUseForbiddenTags:
    enabled: true
    tags:
      - latest
      - dev
      - main
    containerImagesMustBePinnedByDigest: true

  containerImageMustComeFromAuthorizedSources:
    enabled: true
    trustDockerHubOfficialImages: true
    trustedUrls:
      - $CI_REGISTRY_IMAGE:*
      - registry.gitlab.com/security-products/*

  branchMustBeProtected:
    enabled: true
    defaultMustBeProtected: true
    namePatterns:
      - main
    allowForcePush: false

  includesMustNotUseForbiddenVersions:
    enabled: true
    forbiddenVersions:
      - latest
      - main
      - HEAD

Commandes utiles autour de la configuration

# Vérifier le fichier
plumber config validate

# Voir la configuration effective sans commentaires
plumber config view

# Générer le template complet officiel
plumber config generate --output .plumber.yaml --force

Ajouter Plumber à GitLab CI avec le composant officiel

Une fois le premier scan local compris, le bon point d’entrée côté GitLab est le composant CI/CD officiel.

Démarrage rapide recommandé

Ajoutez d’abord le token GITLAB_TOKEN dans Settings -> CI/CD -> Variables, puis utilisez ce squelette :

.gitlab-ci.yml

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH
    - if: $CI_COMMIT_TAG

include:
  - component: gitlab.com/getplumber/plumber/plumber@v0.1.84

Ce bloc workflow:rules évite de créer à la fois un pipeline de branche et un pipeline de merge request sur le même push.

Le stage par défaut est .pre

Le composant s’exécute par défaut en .pre. Ce stage ne s’exécute que s’il existe au moins un autre job dans un stage normal. Si Plumber est le seul job de votre pipeline, forcez par exemple stage: test.

Variante personnalisée

.gitlab-ci.yml

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH
    - if: $CI_COMMIT_TAG

include:
  - component: gitlab.com/getplumber/plumber/plumber@v0.1.84
    inputs:
      stage: test
      threshold: 80
      config_file: .plumber.yaml
      pbom_file: plumber-pbom.json
      pbom_cyclonedx_file: plumber-cyclonedx-sbom.json

Priorité de configuration du composant

Le composant recherche la configuration dans cet ordre :

1. l’input config_file s’il est défini ;
2. le fichier .plumber.yaml à la racine du dépôt ;
3. la configuration par défaut embarquée dans l’image.

Et si vous écrivez un job manuel ?

Gardez cette variante pour les besoins spécifiques. Si vous voulez ajouter --mr-comment et --badge dans un job manuel, séparez-les en deux jobs : le commentaire de merge request n’a de sens qu’en pipeline de MR, et le badge ne se met à jour que sur la branche par défaut.

GitLab self-hosted : le minimum à savoir

Sur un GitLab auto-hébergé, vous ne pouvez pas consommer directement le composant depuis gitlab.com. Le chemin correct est le suivant :

1. Importez le dépôt https://gitlab.com/getplumber/plumber.git dans votre instance.

2. Activez le CI/CD Catalog dans le projet importé.

3. Publiez une release en lançant un pipeline sur un tag déjà importé, par exemple v0.1.84.

4. Consommez ensuite le composant local dans vos pipelines.

.gitlab-ci.yml

include:
  - component: gitlab.example.com/infrastructure/plumber/plumber@v0.1.84

Exporter un PBOM et l’analyser

Une fois la lecture du scan comprise, vous pouvez passer au PBOM.

Le PBOM (Pipeline Bill of Materials) est l’inventaire des dépendances de votre pipeline : images Docker, composants GitLab, templates et includes.

plumber analyze \
  --pbom plumber-pbom.json \
  --pbom-cyclonedx plumber-cyclonedx-sbom.json

Quand utiliser chaque format ?

Format	Quand l’utiliser	Ce qu’il contient
PBOM natif	Vous voulez comprendre le pipeline en détail	Métadonnées riches propres à Plumber
CycloneDX	Vous voulez brancher un autre outil	Format standard pour Trivy, Grype ou Dependency-Track

Glissez pour voir

Ce que le PBOM fait, et ce qu'il ne fait pas

Le PBOM vous dit ce qui compose votre pipeline. Il ne transforme pas automatiquement les composants GitLab ou les templates en CVE. Pour les vulnérabilités d’images, utilisez trivy image ou grype sur les images elles-mêmes, ou scannez le fichier CycloneDX généré.

Scanner le CycloneDX avec Trivy

trivy sbom plumber-cyclonedx-sbom.json --severity HIGH,CRITICAL

Scanner le CycloneDX avec Grype

grype sbom:plumber-cyclonedx-sbom.json --fail-on high

Aller plus loin après le premier scan

À ce stade, vous savez déjà lancer Plumber et lire les erreurs les plus utiles. Les fonctionnalités suivantes sont pratiques, mais elles ne doivent pas être votre point d’entrée.

Comprendre un code avec plumber explain

plumber explain ISSUE-412
# raccourci accepté : plumber explain 412

Cette commande renvoie :

• la description du problème ;
• son impact ;
• la remédiation ;
• le lien vers la documentation officielle.

Utiliser le score A-E

plumber analyze --score
plumber analyze --score-point

Sur Pipeline Craft, le scan de solution/lab-12 a produit :

Plumber Score: E
Final points: 0.0 / 100
High: 6
Medium: 5

Le score sert à prioriser. Il ne remplace pas la lecture des contrôles en échec.

Cibler seulement certains contrôles

# Uniquement les images et la protection de branche
plumber analyze --controls containerImageMustNotUseForbiddenTags,branchMustBeProtected

# Tout sauf la protection de branche
plumber analyze --skip-controls branchMustBeProtected

Commentaires de merge request et badges projet

Avec le composant GitLab, activez-les ainsi :

.gitlab-ci.yml

include:
  - component: gitlab.com/getplumber/plumber/plumber@v0.1.84
    inputs:
      mr_comment: true
      badge: true

Scope api requis

Pour mr_comment et badge, le token doit utiliser le scope api au lieu de read_api. Le commentaire de MR ne fonctionne qu’en pipeline de merge request, et le badge ne se met à jour que sur la branche par défaut.

Quand passer à la Platform ?

La Platform n’est pas le bon point de départ pour un débutant. Elle devient pertinente quand vous devez :

• suivre plusieurs projets dans le temps ;
• disposer d’un tableau de bord centralisé ;
• gérer des politiques communes à plusieurs équipes ;
• auditer des variables, des quotas ou des règles de merge request à plus grande échelle.

Règle simple

Si votre besoin tient dans “je veux comprendre et sécuriser mon pipeline”, restez sur la CLI ou le composant GitLab. Si votre besoin devient “je veux gouverner un portefeuille de projets”, regardez la Platform.

Annexe : les 14 contrôles CLI

Contrôle	Code principal	À quoi il sert
containerImageMustNotUseForbiddenTags	ISSUE-102	Bloque les tags mutables comme latest ou dev
containerImageMustComeFromAuthorizedSources	ISSUE-101	Limite les images aux registries autorisés
branchMustBeProtected	ISSUE-501 / 505	Vérifie la protection des branches critiques
pipelineMustNotIncludeHardcodedJobs	ISSUE-401	Détecte les jobs définis directement dans le YAML
includesMustBeUpToDate	ISSUE-403	Contrôle que les includes ne sont pas obsolètes
includesMustNotUseForbiddenVersions	ISSUE-404	Interdit les refs mutables comme main ou HEAD
pipelineMustIncludeComponent	ISSUE-408 / 409	Imposent des composants GitLab obligatoires
pipelineMustIncludeTemplate	ISSUE-405 / 406	Imposent des templates GitLab obligatoires
pipelineMustNotEnableDebugTrace	ISSUE-203	Empêche l’exposition des secrets dans les logs
pipelineMustNotUseUnsafeVariableExpansion	ISSUE-204	Réduit le risque d’injection via des variables contrôlées par l’utilisateur
securityJobsMustNotBeWeakened	ISSUE-410	Détecte les jobs de sécurité neutralisés
pipelineMustNotOverrideJobVariables	ISSUE-205	Empêche de surcharger certaines variables de gouvernance
pipelineMustNotExecuteUnverifiedScripts	ISSUE-411	Détecte les motifs `curl
pipelineMustNotUseDockerInDocker	ISSUE-412 / 413	Détecte DinD et son mode non sécurisé

Glissez pour voir

Dépannage

Symptôme	Cause probable	Solution
configuration file not found	Aucun .plumber.yaml présent pour la CLI	Créez le fichier avec plumber config init ou plumber config generate
401 Unauthorized	Token incomplet ou invalide	Vérifiez read_api + read_repository
403 Forbidden on MR comment	Scope insuffisant	Utilisez api si vous activez mr_comment
403 Forbidden on badge	Scope insuffisant ou rôle trop faible	Utilisez api et un rôle Maintainer
Le composant ne s’exécute pas	Job en .pre sans autre stage normal	Forcez stage: test
Deux pipelines sont créés sur le même push	workflow:rules absent	Ajoutez le bloc recommandé par GitLab
Le projet n’est pas auto-détecté	Remote Git absent ou mal nommé	Vérifiez le remote origin ou passez --gitlab-url et --project

Glissez pour voir

À retenir

• Plumber se comprend mieux par la CLI locale avant de passer au composant GitLab CI/CD
• Le chemin débutant est simple : config init, config validate, plumber analyze
• L’auto-détection repose sur un remote origin pointant vers GitLab
• Commencez par corriger les images non épinglées, les includes mutables et les branches non protégées
• Le composant GitLab est la meilleure intégration par défaut ; le job manuel vient ensuite
• Le PBOM sert à inventorier le pipeline ; le CycloneDX facilite l’intégration avec Trivy et Grype
• Le score A-E, plumber explain, les commentaires de MR et les badges sont utiles après le premier scan, pas avant
• Gardez la Platform pour les besoins de gouvernance multi-projets

Prochaines étapes

CLI GitLab Configurer le token, explorer les projets et automatiser vos actions GitLab depuis le terminal.

Sécuriser les pipelines Voir les bonnes pratiques globales de durcissement et de gouvernance CI/CD.

Trivy Scanner vos images, vos fichiers SBOM et vos dépôts avec un outil simple à intégrer.

OWASP Top 10 CI/CD Comprendre les risques que Plumber aide à réduire dans les pipelines modernes.

Ressources

• Documentation CLI Plumber
• Documentation du composant GitLab
• Référence des contrôles
• Index des issues Plumber
• Référentiel GitHub Plumber

×

📖 Voir la documentation →