detect-secrets : empêcher les secrets d'entrer dans votre code

detect-secrets empêche les nouveaux secrets d’entrer dans votre code, sans vous obliger à nettoyer tout l’historique Git d’un coup. Grâce à un système de baseline versionnable, l’outil identifie les secrets existants et les met de côté pour se concentrer sur les ajouts. C’est l’approche pragmatique adoptée par Yelp pour sécuriser des centaines de dépôts en entreprise.

Ce que vous allez apprendre

• Comprendre la philosophie baseline de detect-secrets
• Scanner un projet et créer une baseline
• Auditer les résultats pour distinguer vrais et faux positifs
• Filtrer les faux positifs avec les exclusions et l’allowlist inline
• Intégrer detect-secrets comme pre-commit hook et en CI/CD

Version actuelle

Ce guide utilise detect-secrets v1.5.0 (mai 2024). C’est la dernière version stable. Les 27 plugins intégrés couvrent AWS, Stripe, GitHub, GitLab, Slack, OpenAI, JWT, clés privées et bien d’autres.

Le problème : des secrets qui s’accumulent dans l’historique

Imaginez un dépôt Git avec 5 ans d’historique et 10 000 commits. Quelque part dans ces commits, des clés API et des mots de passe ont été commités par erreur. Les supprimer du code actuel ne suffit pas : ils restent dans l’historique Git. Et réécrire l’historique complet est souvent irréaliste.

C’est exactement ce problème que detect-secrets résout avec une approche différente des autres scanners :

Approche	Comment ça marche	Limitation
Scanner tout l’historique (Gitleaks, TruffleHog)	Parcourt chaque commit	Lent sur les gros dépôts, beaucoup de bruit
Baseline (detect-secrets)	Photographie les secrets existants, bloque les nouveaux	Ne scanne pas l’historique

Glissez pour voir

L’idée est simple : on accepte que des secrets existent déjà (c’est la baseline), et on empêche la situation d’empirer. Ensuite, on migre les secrets existants progressivement.

Comment detect-secrets fonctionne

detect-secrets repose sur deux composants qui travaillent ensemble : les plugins et les filtres.

Les plugins trouvent les secrets dans le code. Il en existe trois types :

Type	Fonctionnement	Exemple
Regex	Cherche des patterns structurés (clés AWS, tokens GitHub)	AKIA... détecté par AWSKeyDetector
Entropie	Mesure le “désordre” d’une chaîne (haute entropie = probable secret)	wJalrXUtnFEMI/K7MDENG détecté par Base64HighEntropyString
Mot-clé	Cherche des noms de variables associés aux secrets	password = "hunter2" détecté par KeywordDetector

Glissez pour voir

Les filtres éliminent les faux positifs. Par défaut, detect-secrets ignore :

• Les UUIDs (pattern reconnaissable)
• Les chaînes séquentielles (abcdefg)
• Les templates (${SECRET}, {{key}}, <placeholder>)
• Les fichiers de lock
• Les références indirectes (password = get_secret())

Trois outils, trois usages

detect-secrets fournit trois commandes distinctes :

Commande	Quand l’utiliser
detect-secrets scan	Créer ou mettre à jour la baseline
detect-secrets-hook	Bloquer les commits contenant de nouveaux secrets
detect-secrets audit	Analyser et labelliser les résultats de la baseline

Glissez pour voir

Installation

pip

pip install detect-secrets

Pour les fonctionnalités optionnelles :

# Support word-list (exclure des mots connus)
pip install detect-secrets[word_list]

# Support détecteur de gibberish (ML)
pip install detect-secrets[gibberish]

Homebrew

brew install detect-secrets

pip (venv)

Si votre système bloque l’installation globale (PEP 668) :

python3 -m venv .venv
source .venv/bin/activate
pip install detect-secrets

Vérification :

detect-secrets --version
# 1.5.0

Scanner un projet et créer la baseline

1. Créer la baseline initiale : detect-secrets scanne tous les fichiers trackés par Git et génère un fichier JSON contenant les secrets détectés.

   detect-secrets scan > .secrets.baseline

   Le fichier .secrets.baseline contient trois sections :

   • plugins_used : la liste des 27 plugins actifs
   • filters_used : les 11 filtres appliqués
   • results : les secrets détectés, regroupés par fichier

2. Vérifier ce qui a été détecté : utilisez la commande audit --report pour afficher un résumé lisible.

   detect-secrets audit .secrets.baseline --report

   Chaque secret est affiché avec son fichier, sa ligne, son type et sa catégorie (UNVERIFIED, VERIFIED_TRUE ou VERIFIED_FALSE).

3. Versionner la baseline : ajoutez le fichier au dépôt Git. Il servira de référence pour bloquer les futurs secrets.

   git add .secrets.baseline
   git commit -m "chore: add detect-secrets baseline"

Fichiers non trackés par Git

Par défaut, detect-secrets ne scanne que les fichiers trackés par Git. Pour scanner aussi les fichiers non suivis, utilisez le flag --all-files :

detect-secrets scan --all-files > .secrets.baseline

Mettre à jour la baseline

Au fil du temps, votre code évolue. Des secrets sont supprimés, d’autres ajoutés. Pour synchroniser la baseline :

detect-secrets scan --baseline .secrets.baseline

Cette commande :

• Met à jour la baseline vers le format de la dernière version
• Ajoute les nouveaux secrets détectés
• Supprime les secrets qui ne sont plus dans le code
• Préserve les labels déjà attribués lors de l’audit

Baseline et plugins

Quand vous utilisez --baseline, detect-secrets charge les plugins définis dans la baseline existante. Pour forcer l’utilisation de tous les plugins disponibles (utile après une mise à jour), ajoutez --force-use-all-plugins :

detect-secrets scan --baseline .secrets.baseline --force-use-all-plugins

Scanner une chaîne individuelle

Pour tester rapidement si une valeur est détectée comme secret :

detect-secrets scan --string "AKIAIOSFODNN7EXAMPLE"

AWSKeyDetector          : True  (unverified)
ArtifactoryDetector     : False
AzureStorageKeyDetector : False
Base64HighEntropyString : False (3.684)
BasicAuthDetector       : False
...

Chaque plugin indique True ou False. Pour les détecteurs d’entropie, le score est affiché entre parenthèses (seuil par défaut : 4.5 pour base64, 3.0 pour hex).

Les 27 plugins intégrés

detect-secrets v1.5.0 embarque 27 plugins activés par défaut :

Plugin	Ce qu’il détecte
AWSKeyDetector	Clés d’accès AWS (AKIA...)
AzureStorageKeyDetector	Clés de stockage Azure
BasicAuthDetector	Identifiants en URLs (user:pass@host)
GitHubTokenDetector	Tokens GitHub (ghp_, gho_, ghs_)
GitLabTokenDetector	Tokens GitLab (glpat-)
JwtTokenDetector	JSON Web Tokens (eyJ...)
KeywordDetector	Variables nommées password, secret, token, etc.
OpenAIDetector	Clés API OpenAI (sk-)
PrivateKeyDetector	Clés privées RSA, DSA, ECDSA, OpenSSH
SlackDetector	Tokens et webhooks Slack
StripeDetector	Clés API Stripe (sk_live_, rk_live_)
Base64HighEntropyString	Chaînes base64 à haute entropie (seuil : 4.5)
HexHighEntropyString	Chaînes hexadécimales à haute entropie (seuil : 3.0)

Glissez pour voir

Et aussi : ArtifactoryDetector, CloudantDetector, DiscordBotTokenDetector, IbmCloudIamDetector, IbmCosHmacDetector, IPPublicDetector, MailchimpDetector, NpmDetector, PypiTokenDetector, SendGridDetector, SoftlayerDetector, SquareOAuthDetector, TelegramBotTokenDetector, TwilioKeyDetector.

Désactiver des plugins

Pour réduire le bruit, désactivez les plugins inutiles :

# Désactiver le détecteur de mots-clés et les IP publiques
detect-secrets scan \
  --disable-plugin KeywordDetector \
  --disable-plugin IPPublicDetector

Scanner avec un seul plugin

Pour n’utiliser qu’un seul plugin, désactivez tous les autres :

detect-secrets scan --list-all-plugins | \
  grep -v 'AWSKeyDetector' | \
  sed "s#^#--disable-plugin #g" | \
  xargs detect-secrets scan

Régler les seuils d’entropie

Les détecteurs d’entropie acceptent un seuil entre 0.0 et 8.0. Un seuil plus bas détecte plus de secrets (mais plus de faux positifs) :

# Seuil base64 abaissé de 4.5 à 3.5
detect-secrets scan --base64-limit 3.5

# Seuil hex relevé de 3.0 à 4.0
detect-secrets scan --hex-limit 4.0

Gérer les faux positifs

Les faux positifs sont inévitables. detect-secrets propose plusieurs mécanismes pour les gérer.

Allowlist inline (pragma)

Ajoutez un commentaire pragma: allowlist secret sur la ligne à exclure :

# Ce n'est pas un vrai secret, c'est un exemple
EXAMPLE_KEY = "AKIAIOSFODNN7EXAMPLE"  # pragma: allowlist secret

Pour exclure la ligne suivante :

//  pragma: allowlist nextline secret
const EXAMPLE_KEY = "AKIAIOSFODNN7EXAMPLE";

Exclure des fichiers

Ignorez des fichiers par regex :

detect-secrets scan --exclude-files '\.signature$' --exclude-files 'test_data/.*'

Exclure des lignes

Ignorez des lignes qui correspondent à un pattern :

detect-secrets scan --exclude-lines 'EXAMPLE' --exclude-lines 'fake_secret'

Exclure des valeurs de secrets

Ignorez des secrets par leur valeur :

detect-secrets scan --exclude-secrets '(fakesecret|\$\{.*\})'

Exclure avec une word-list

Pour exclure un grand nombre de faux positifs connus, utilisez un fichier de mots :

pip install detect-secrets[word_list]

wordlist.txt

example-password
test-api-key
SuperSecret123

detect-secrets scan --word-list wordlist.txt

Auditer la baseline

L’audit permet de labelliser chaque secret comme vrai positif ou faux positif. C’est utile pour :

• Établir la liste des secrets à migrer
• Mesurer la précision des plugins
• Améliorer la configuration

Audit interactif

detect-secrets audit .secrets.baseline

Pour chaque secret, detect-secrets affiche le contexte (5 lignes avant/après) et demande :

Secret:      1 of 12
Filename:    config.env
Secret Type: Secret Keyword
----------
1: DATABASE_HOST=localhost
2: DATABASE_PORT=5432
3: DATABASE_USER=admin
4: DATABASE_PASSWORD=SuperSecret123!
5: AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
----------
Should this string be committed to the repository? (y)es, (n)o, (s)kip, (q)uit:

• y (yes) : c’est un faux positif, on peut le garder
• n (no) : c’est un vrai secret, à migrer
• s (skip) : on ne sait pas, on passe
• q (quit) : arrêter et sauvegarder

Générer un rapport

# Rapport complet
detect-secrets audit --report .secrets.baseline

# Seulement les vrais secrets
detect-secrets audit --report --only-real .secrets.baseline

# Seulement les faux positifs
detect-secrets audit --report --only-false .secrets.baseline

Statistiques de précision

Après un audit interactif, mesurez la précision de vos plugins :

detect-secrets audit --stats .secrets.baseline

Base64HighEntropyString:
  - Precision: 75% (3 / 4 labelled secrets)
  - Recall:    60% (3 / 5 known true secrets)

Comparer deux configurations

Pour optimiser vos réglages, comparez deux baselines :

detect-secrets scan --base64-limit 4 > limit4.json
detect-secrets scan --base64-limit 5 > limit5.json
detect-secrets audit --diff limit4.json limit5.json

Intégration pre-commit

La méthode recommandée par la documentation officielle est d’utiliser le framework pre-commit :

1. Créer la baseline :

   detect-secrets scan > .secrets.baseline

2. Configurer le hook dans .pre-commit-config.yaml :

   .pre-commit-config.yaml

   repos:
     - repo: https://github.com/Yelp/detect-secrets
       rev: v1.5.0
       hooks:
         - id: detect-secrets
           args: ['--baseline', '.secrets.baseline']
           exclude: package.lock.json

3. Installer les hooks :

   pre-commit install

4. Tester : essayez de commiter un fichier contenant un secret non listé dans la baseline. Le commit sera bloqué.

Baseline non stagée

Si votre .secrets.baseline n’est pas dans la zone de staging (git add), le hook renverra l’erreur Your baseline file (.secrets.baseline) is unstaged. Pensez à toujours stager la baseline avec vos changements.

Intégration CI/CD

GitHub Actions

.github/workflows/detect-secrets.yml

name: Detect Secrets
on: [push, pull_request]

jobs:
  detect-secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - name: Install detect-secrets
        run: pip install detect-secrets
      - name: Scan for secrets
        run: |
          detect-secrets scan --baseline .secrets.baseline
          git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline

GitLab CI

.gitlab-ci.yml

detect-secrets:
  image: python:3.12-slim
  stage: test
  before_script:
    - pip install detect-secrets
  script:
    - detect-secrets scan --baseline .secrets.baseline
    - git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline

Utilisation comme bibliothèque Python

detect-secrets peut aussi être utilisé directement dans vos scripts Python :

from detect_secrets import SecretsCollection
from detect_secrets.settings import default_settings

secrets = SecretsCollection()
with default_settings():
    secrets.scan_file('config.env')

import json
print(json.dumps(secrets.json(), indent=2))

Pour une configuration personnalisée :

from detect_secrets import SecretsCollection
from detect_secrets.settings import transient_settings

secrets = SecretsCollection()
with transient_settings({
    'plugins_used': [
        {'name': 'AWSKeyDetector'},
        {'name': 'Base64HighEntropyString', 'limit': 5.0},
    ],
}) as settings:
    secrets.scan_file('config.env')

detect-secrets vs Gitleaks vs TruffleHog

Critère	detect-secrets	Gitleaks	TruffleHog
Langage	Python	Go	Go
Approche	Baseline + diff	Scan complet	Scan complet
Historique Git	Non (seulement les fichiers actuels)	Oui	Oui
Vérification des secrets	Oui (certains plugins)	Non	Oui (800+ détecteurs)
Plugins custom	Oui (fichiers Python)	Oui (règles TOML)	Non
Filtres custom	Oui (fichiers Python)	Oui (allowlists TOML)	Non
Audit interactif	Oui	Non	Non
Pre-commit	Oui (natif)	Oui	Oui
Performance	Rapide (pas d’historique)	Très rapide (Go)	Rapide (Go)
Cas d’usage idéal	Prévention progressive en entreprise	Scan complet d’historique	Scan multi-sources (Git, Docker, S3)

Glissez pour voir

Combinaison recommandée

L’idéal est de combiner les approches : detect-secrets en pre-commit pour bloquer les nouveaux secrets au quotidien, et Gitleaks ou TruffleHog en CI/CD pour un scan périodique de l’historique complet.

Limites et pièges

Limitation	Conséquence	Contournement
Pas de scan d’historique	Les secrets déjà commités ne sont pas détectés	Utiliser Gitleaks ou TruffleHog en complément
Secrets multi-lignes	Non détectés par défaut	Écrire un plugin custom
Mots de passe faibles	login = "hunter2" passe si le KeywordDetector ne match pas le nom de variable	Combiner avec un mot-clé personnalisé
Maintenance de la baseline	Doit être mise à jour régulièrement	Automatiser avec detect-secrets scan --baseline
Pas de scan Docker/S3	Limité aux fichiers locaux et Git	Utiliser TruffleHog pour ces cibles

Glissez pour voir

Dépannage

Symptôme	Cause	Solution
Did not detect git repository	Version de Git < 1.8.5	Mettre à jour Git
Not a valid baseline file! (Windows)	Encodage du fichier incorrect	S’assurer que .secrets.baseline est en UTF-8
Baseline vide ("results": {})	Les fichiers ne sont pas trackés par Git	Ajouter les fichiers avec git add ou utiliser --all-files
Your baseline file is unstaged	.secrets.baseline pas dans la zone de staging	Exécuter git add .secrets.baseline
Trop de faux positifs	Seuils d’entropie trop bas ou plugins trop larges	Ajuster --base64-limit, --exclude-lines, ou --disable-plugin

Glissez pour voir

À retenir

• detect-secrets adopte une approche baseline : il accepte les secrets existants et empêche les nouveaux d’entrer.
• Le scan par défaut ne couvre que les fichiers trackés par Git (pas l’historique des commits).
• 27 plugins couvrent les principaux fournisseurs cloud, tokens, clés privées et mots de passe.
• Les filtres (exclusions, allowlist inline, word-list) permettent de gérer les faux positifs.
• detect-secrets-hook est le gardien au quotidien : il bloque les commits contenant de nouveaux secrets.
• L’audit interactif permet de labelliser les résultats et de mesurer la précision des plugins.
• Pour un scan d’historique complet, combinez avec Gitleaks ou TruffleHog.

Prochaines étapes

Gitleaks : scanner l'historique Git Complétez detect-secrets avec un scan de l'historique complet de vos dépôts.

TruffleHog : scan multi-sources Étendez la détection aux images Docker, buckets S3, Jenkins et plus.

Comprendre les secrets statiques et dynamiques Pourquoi les secrets en dur sont un problème et comment les remplacer.

Secrets Scanning en CI/CD Guide complet pour intégrer la détection de secrets dans vos pipelines.

×

📖 Voir la documentation →