Détecter les secrets exposés dans votre code

Un secret commité dans Git y reste, même après suppression du fichier. Une image Docker publiée avec un token embarqué est exploitable en quelques minutes. La détection automatisée est le seul moyen fiable d'intercepter ces fuites avant qu'elles ne deviennent des incidents. Ce guide compare les principaux outils de détection, Gitleaks, TruffleHog, Trivy et detect-secrets, et propose une stratégie combinée couvrant le poste développeur, la CI/CD, les images conteneur et le filesystem.

Ce que vous allez apprendre

La détection de secrets est le filet de sécurité qui rattrape ce qui a échappé aux bonnes pratiques. Concrètement, vous saurez :

• Choisir l'outil adapté à chaque surface : Gitleaks, TruffleHog, Trivy, detect-secrets.
• Bloquer un secret avant le push avec un hook pre-commit.
• Intégrer la détection dans un pipeline CI/CD et sur les images conteneur.
• Combiner plusieurs outils pour une couverture complète (poste, CI, images, historique).
• Relier cette détection au modèle de menaces SOCLE, qui en fait une exigence (détection de fuite et procédure de réponse).

Pourquoi détecter tôt

Plus un secret exposé reste longtemps sans être détecté, plus le risque d'exploitation augmente. Les études montrent qu'un secret commité dans un dépôt public est scanné par des bots en moins de 5 minutes.

Moment de détection	Coût de remédiation	Risque résiduel
Avant le commit (pre-commit)	Très faible	Nul
À la pull request (CI)	Faible	Limité (branche)
Après merge (scan périodique)	Moyen	Élevé (historique)
Après publication (image, release)	Élevé	Critique

Glissez pour voir

L'objectif est de déplacer la détection le plus à gauche possible dans le cycle de développement : pre-commit > CI > scan périodique.

Panorama des outils

Quatre outils couvrent la majorité des besoins. Chacun a un positionnement distinct.

Critère	Gitleaks	TruffleHog	Trivy	detect-secrets
Type	Motifs regex + entropie	Motifs + vérification active	Scanner multi-cibles	Motifs + baseline
Git (historique)	Oui	Oui	Non	Oui
Filesystem	Oui	Oui	Oui	Oui
Images Docker	Non	Non	Oui	Non
Vérification active	Non	Oui (appels API)	Non	Non
Faux positifs	Modérés	Faibles (grâce à la vérification)	Modérés	Gérables (baseline)
Vitesse	Rapide	Moyenne	Rapide	Rapide
Pre-commit natif	Oui	Non	Non	Oui
Licence	MIT	AGPL-3.0	Apache 2.0	Apache 2.0

Glissez pour voir

Astuce

Aucun outil ne couvre toutes les surfaces seul. La combinaison de deux ou trois outils offre la meilleure couverture.

Pour le détail d'installation et de configuration avancée de chaque outil :

• Guide Gitleaks, installation, règles custom, .gitleaks.toml
• Guide TruffleHog, vérification active, scan GitHub/GitLab
• Guide Trivy, scan d'images, de fichiers et de dépendances

Détection pre-commit

Le hook pre-commit bloque le commit si un secret est détecté dans les fichiers stagés. C'est la première ligne de défense.

Avec Gitleaks

1. Installer Gitleaks

   # Linux (binaire)
   curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz | tar xz
   sudo mv gitleaks /usr/local/bin/
   
   # macOS
   brew install gitleaks

   Vérifiez l'installation :

   gitleaks version

2. Configurer le hook pre-commit

   Avec le framework pre-commit, ajoutez dans .pre-commit-config.yaml :

   repos:
     - repo: https://github.com/gitleaks/gitleaks
       rev: v8.30.1
       hooks:
         - id: gitleaks

   Puis installez le hook :

   pre-commit install

3. Tester le hook

   Créez un fichier de test contenant un faux secret :

   echo 'GITHUB_TOKEN="ghp_0123456789abcdefghijklmnopqrstuvwxyz"' > test-secret.txt
   git add test-secret.txt
   git commit -m "test"

   Le commit doit être bloqué, avec la règle github-pat dans le message.

   Le motif de test n'est pas interchangeable. Une clé AWS AKIA… associée à sa valeur d'exemple publique ne lève pas sur gitleaks 8.30.1 : la règle exige une entropie que les chaînes de documentation n'atteignent pas. Un apprenant qui teste avec elle voit son commit passer et croit son hook cassé. Les motifs qui lèvent à coup sûr sont un jeton ghp_ et un bloc PEM de clé privée.

   # Nettoyez après le test
   git reset HEAD test-secret.txt
   rm test-secret.txt

Avec detect-secrets

L'approche de detect-secrets repose sur une baseline : un fichier .secrets.baseline qui recense les secrets connus (pour les ignorer ou les suivre).

# Créer la baseline initiale
detect-secrets scan > .secrets.baseline

# Installer le hook pre-commit
cat >> .pre-commit-config.yaml << 'EOF'
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']
EOF

pre-commit install

Note

La baseline de detect-secrets doit être versionnée dans le dépôt et auditée régulièrement. Un secret marqué comme "faux positif" dans la baseline ne sera plus détecté.

Détection en CI/CD

Le scan en CI intercepte les secrets qui ont échappé au pre-commit. Il s'exécute à chaque pull request ou push.

GitHub Actions

name: Secret Scan
on:
  pull_request:
  push:
    branches: [main]

permissions: {}

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

secret_scan:
  stage: test
  image:
    name: ghcr.io/gitleaks/gitleaks:v8.30.1@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f
    entrypoint: [""]
  script:
    - gitleaks detect --source . --verbose --log-opts="$CI_MERGE_REQUEST_DIFF_BASE_SHA..$CI_COMMIT_SHA"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Ajouter TruffleHog pour la vérification active

TruffleHog peut vérifier si un secret détecté est encore valide en testant les API correspondantes. C'est un complément idéal à Gitleaks en CI.

# Ajoutez ce job à votre pipeline GitHub Actions
trufflehog:
  runs-on: ubuntu-latest
  permissions:
    contents: read
  steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        fetch-depth: 0
        persist-credentials: false

    - name: TruffleHog scan
      run: |
        docker run --rm -v "$PWD:/repo" \
          trufflesecurity/trufflehog:3.99.2@sha256:47a84bc18a0d04a165498bbbd3bacfd84176661cbc91f8e0f85467f6a771e99a \
          git file:///repo --only-verified --fail

Attention

L'option --only-verified de TruffleHog effectue des appels réseau vers les API des fournisseurs (AWS, GitHub, Slack…). Utilisez-la uniquement en CI, pas sur un réseau restreint.

Détection sur filesystem et images

Scanner un répertoire

Certains secrets n'arrivent jamais dans Git : fichiers .env exclus par .gitignore, configurations locales, exports.

# Avec Gitleaks
gitleaks detect --source /chemin/du/projet --no-git --verbose

# Avec TruffleHog
trufflehog filesystem /chemin/du/projet --only-verified

# Avec Trivy
trivy fs --scanners secret /chemin/du/projet

Scanner une image Docker

Les images Docker peuvent contenir des secrets embarqués dans les layers. Trivy est le seul des quatre outils capable de scanner directement une image.

trivy image --scanners secret mon-image:1.4.0

Trivy inspecte chaque layer de l'image et remonte les secrets trouvés avec leur emplacement exact.

# Exemple de sortie
mon-image:1.4.0 (secrets)
============================
Total: 1 (HIGH: 1)

┌──────────┬──────────────────┬──────────┬───────────────────────────┐
│ Category │       Description│ Severity │         Match             │
├──────────┼──────────────────┼──────────┼───────────────────────────┤
│ AWS      │ AWS Access Key ID│ HIGH     │ AKIA****************     │
└──────────┴──────────────────┴──────────┴───────────────────────────┘

Astuce

Intégrez trivy image --scanners secret dans votre pipeline de build Docker, juste après le docker build. Si un secret est trouvé, l'image ne doit pas être poussée vers le registre.

Pour éviter d'embarquer des secrets dans les images, consultez le guide Fuites de secrets : logs, Docker, variables.

Vérification active des secrets

La vérification active consiste à tester si un secret détecté est encore valide. Seul TruffleHog propose cette fonctionnalité nativement.

Fournisseur	Méthode de vérification
AWS	Appel sts:GetCallerIdentity
GitHub	Appel API avec le token
Slack	Appel auth.test
Google Cloud	Appel OAuth tokeninfo
Stripe	Appel API charges

Glissez pour voir

La vérification active réduit les faux positifs : un secret invalide n'est plus une urgence, c'est un point d'hygiène.

# Scanner uniquement les secrets vérifiés comme actifs
trufflehog git file:///chemin/du/repo --only-verified

# Scanner et inclure aussi les non-vérifiés
trufflehog git file:///chemin/du/repo --results=verified,unknown

Pour approfondir la vérification active : Guide TruffleHog.

Gérer les faux positifs

Un taux de faux positifs trop élevé conduit les développeurs à ignorer les alertes. Trois approches pour le maîtriser.

Exclure des patterns connus

Avec Gitleaks, créez un fichier .gitleaks.toml à la racine du dépôt :

[allowlist]
description = "Faux positifs connus"
paths = [
  '''tests/fixtures/.*''',
  '''docs/examples/.*''',
]
regexes = [
  '''EXAMPLE_.*''',
  '''AKIAIOSFODNN7EXAMPLE''',
]

Utiliser la baseline de detect-secrets

# Auditer la baseline : marquer chaque secret comme vrai ou faux positif
detect-secrets audit .secrets.baseline

L'audit interactif parcourt chaque entrée et demande une confirmation. Les faux positifs marqués ne déclenchent plus d'alerte.

Règle générale

Action	Quand
Exclure via allowlist	Pattern récurrent et vérifié (clés de test, mocks)
Baseline + audit	Projet avec beaucoup d'historique
Corriger le code	Secret réel, même si inactif

Glissez pour voir

Danger

Ne supprimez jamais un vrai secret de la liste d'exclusions uniquement parce qu'il est "inactif". Corrigez la source : retirez le secret du code et effectuez une rotation.

Stratégie combinée recommandée

Aucun outil ne couvre toutes les surfaces. La stratégie suivante combine trois outils pour une couverture complète.

Surface	Outil	Moment
Poste développeur	Gitleaks (pre-commit)	Avant chaque commit
Pull request	Gitleaks + TruffleHog (CI)	À chaque PR
Historique complet	TruffleHog (--only-verified)	Scan hebdomadaire
Images Docker	Trivy (--scanners secret)	À chaque build
Filesystem	Trivy ou Gitleaks (--no-git)	Audit ponctuel

Glissez pour voir

Le schéma montre comment ces couches se rattrapent : ce que le pre-commit laisse passer est arrêté par la CI, et ce que la CI ne voit pas ressort au scan périodique.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

1. Installer Gitleaks en pre-commit sur tous les dépôts

   C'est la mesure la plus simple et la plus efficace. Un secret bloqué avant le commit ne nécessite aucune rotation.

2. Ajouter Gitleaks en CI sur chaque pull request

   Un développeur peut ne pas avoir le hook activé. La CI est le filet de sécurité.

3. Ajouter TruffleHog en CI pour la vérification active

   Complète Gitleaks en identifiant les secrets encore valides.

4. Scanner les images Docker avec Trivy avant publication

   Ajoutez trivy image --scanners secret dans le pipeline de build, avant le docker push.

5. Planifier un scan hebdomadaire de l'historique complet

   trufflehog git file:///chemin/du/repo --only-verified --json > rapport-secrets.json

   Exploitez le rapport pour prioriser les rotations.

À retenir

• La détection pre-commit est la mesure la plus efficace : elle empêche le secret d'entrer dans l'historique Git.
• Gitleaks excelle en pre-commit et en CI grâce à sa vitesse et ses règles personnalisables.
• TruffleHog se distingue par sa vérification active : il teste si le secret est encore valide.
• Trivy est le seul outil capable de scanner les secrets dans les images Docker.
• detect-secrets convient aux projets avec un historique chargé grâce à son système de baseline.
• Aucun outil ne couvre toutes les surfaces seul : combinez pre-commit, CI et scan d'images.
• Un faux positif ignoré est moins dangereux qu'un vrai positif masqué : préférez la sensibilité à la spécificité.
• Un secret détecté, même inactif, doit être retiré du code source et faire l'objet d'une rotation.

Contrôle de connaissances

Trois questions sur la conduite à tenir après une détection : ce qu'un scanner prouve, ce qu'il ne prouve pas, et pourquoi un secret trouvé dans un dépôt se remplace au lieu de se nettoyer.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

3 questions

3 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →