Gitleaks : scanner vos dépôts Git pour détecter les secrets exposés

Gitleaks détecte les secrets exposés dans vos dépôts Git, fichiers et archives. Rapide et hautement configurable, c’est l’outil de référence pour les pre-commit hooks et les pipelines CI/CD. Avec plus de 150 règles intégrées, il identifie les clés AWS, tokens GitHub, Stripe, Slack et bien d’autres.

Ce que vous allez apprendre

Comprendre comment Gitleaks détecte les secrets avec des règles regex
Scanner différentes sources : dépôts Git, fichiers, archives, entrée standard
Configurer des règles personnalisées et des exclusions
Intégrer Gitleaks dans vos pipelines CI/CD (GitHub Actions, GitLab CI)
Utiliser les fonctionnalités avancées : décodage, archives, baseline

Le problème des secrets dans le code

Imaginez : un développeur pousse un commit contenant une clé API AWS. En quelques minutes, des bots automatisés scannent GitHub, trouvent la clé, et commencent à miner du Bitcoin sur votre compte. C’est arrivé. Plusieurs fois.

Les secrets se retrouvent exposés pour plusieurs raisons :

Situation	Exemple	Risque
Fichier de config commité	`.env` oublié dans `.gitignore`	Clés API en clair dans l’historique Git
Mot de passe hardcodé	`password = "admin123"` dans le code	Accès à la base de données
Token dans les logs	`Authorization: Bearer sk_live_...`	Compromission de compte
Secret encodé en base64	`YXdzX3NlY3JldF9hY2Nlc3Nfa2V5...`	Fausse impression de sécurité
Historique Git	Secret supprimé mais présent dans un ancien commit	Reste accessible via `git log`

Le problème : même si vous supprimez un secret, il reste dans l’historique Git. Et les scanners malveillants analysent tout l’historique, pas juste la branche principale.

Comment Gitleaks résout ce problème

Gitleaks utilise une approche basée sur des règles regex et des mots-clés pour détecter les secrets. Contrairement à d’autres outils, il ne vérifie pas si les secrets sont actifs — il se concentre sur la vitesse et la configurabilité.

Fonctionnement en trois étapes

Découverte — Gitleaks parcourt les sources (Git, fichiers, archives, stdin)
Classification — Chaque ligne est comparée aux 150+ règles intégrées
Rapport — Les secrets trouvés sont affichés avec leur emplacement exact

Points forts de Gitleaks

Caractéristique	Détail
Rapidité	Écrit en Go, très performant
Configurabilité	Règles TOML personnalisables
Décodage	Base64, hex, URL encoding (v8.26+)
Archives	ZIP, tar.gz, 7z… (v8.27+)
Règles composites	Secrets multi-parties (v8.28+)
Intégration	Pre-commit, GitHub Actions, GitLab CI

Ce que Gitleaks détecte

Gitleaks intègre plus de 150 règles pour détecter :

Cloud providers : AWS, GCP, Azure, DigitalOcean
Paiements : Stripe, PayPal, Square
Authentification : GitHub, GitLab, Slack, Discord
Bases de données : PostgreSQL, MySQL, MongoDB dans les URLs
Clés privées : RSA, DSA, ECDSA, OpenSSH
IA/ML : OpenAI, Anthropic, HuggingFace, Perplexity

Installation

Plusieurs méthodes sont disponibles selon votre environnement.

Téléchargez le binaire depuis les releases GitHub :

# Télécharger la dernière version
VERSION="8.30.0"
wget https://github.com/gitleaks/gitleaks/releases/download/v${VERSION}/gitleaks_${VERSION}_linux_x64.tar.gz

# Extraire et installer
tar xzf gitleaks_${VERSION}_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/

# Vérification
gitleaks version
# 8.30.0

Avec Homebrew :

brew install gitleaks

# Vérification
gitleaks version

L’image Docker est idéale pour les environnements CI/CD :

# Depuis Docker Hub
docker pull zricethezav/gitleaks:latest

# Scanner un répertoire local
docker run --rm -v "$PWD:/path" zricethezav/gitleaks:latest dir /path

# Depuis GitHub Container Registry
docker pull ghcr.io/gitleaks/gitleaks:latest

Pour une gestion de versions flexible :

# Ajouter le plugin
asdf plugin add gitleaks

# Installer une version spécifique
asdf install gitleaks 8.30.0

# Définir comme version globale
asdf set --home gitleaks 8.30.0

Commandes principales

Depuis la version 8.19.0, Gitleaks utilise trois commandes principales : git, dir et stdin. Les anciennes commandes detect et protect sont dépréciées mais toujours fonctionnelles.

Scanner un dépôt Git

La commande git scanne l’historique complet d’un dépôt Git, y compris toutes les branches.

# Scanner le dépôt dans le répertoire courant
gitleaks git

# Scanner un dépôt spécifique
gitleaks git /chemin/vers/mon-repo

# Afficher les détails (mode verbose)
gitleaks git -v

# Masquer la bannière
gitleaks git --no-banner

Exemple de sortie :

Finding:     aws_access_key_id = AKIAIOSFODNN7EXAMPLE
Secret:      AKIAIOSFODNN7EXAMPLE
RuleID:      aws-access-token
Entropy:     3.646439
File:        config.env
Line:        4
Commit:      fbc14303ffbf8fb1c2c1914e8dda7d0121633aca
Author:      dev@example.com
Date:        2024-06-16T17:17:40Z
Fingerprint: fbc14303ffbf8fb1c2c1914e8dda7d0121633aca:config.env:aws-access-token:4
Link:        https://github.com/org/repo/blob/fbc14303.../config.env#L4

Cette sortie vous indique :

Le type de secret : aws-access-token
L’emplacement : fichier config.env, ligne 4
Le commit : hash, auteur, date
Le lien direct : vers la ligne sur GitHub/GitLab

Filtrer par plage de commits

Utilisez --log-opts pour passer des options à git log :

# Scanner uniquement les 10 derniers commits
gitleaks git --log-opts="--max-count=10"

# Scanner une plage de commits
gitleaks git --log-opts="HEAD~20..HEAD"

# Scanner uniquement une branche spécifique
gitleaks git --log-opts="--all develop..main"

Scanner avant un commit (pre-commit)

L’option --staged scanne uniquement les fichiers stagés, idéal pour les hooks pre-commit :

# Scanner les fichiers stagés
gitleaks git --staged

# Scanner avec git diff (mode pre-commit)
gitleaks git --pre-commit

Scanner des fichiers ou répertoires

La commande dir scanne des fichiers ou répertoires sans historique Git :

# Scanner un répertoire
gitleaks dir /chemin/vers/dossier

# Scanner un fichier spécifique
gitleaks dir config.env

# Scanner plusieurs chemins
gitleaks dir fichier1.log fichier2.env /etc/config/

Scanner l’entrée standard (stdin)

La commande stdin permet de scanner des données en pipeline :

# Scanner un fichier via pipe
cat config.env | gitleaks stdin

# Scanner la sortie d'une commande
kubectl logs deployment/mon-app | gitleaks stdin

# Scanner un fichier décompressé à la volée
gunzip -c logs.gz | gitleaks stdin

Fonctionnalités avancées

Décodage automatique (v8.26+)

Gitleaks peut décoder automatiquement les secrets encodés en base64, hexadécimal ou URL encoding. Par défaut, le décodage est activé avec une profondeur de 5.

# Activer le décodage récursif (profondeur 2)
gitleaks dir /chemin --max-decode-depth=2

# Désactiver le décodage
gitleaks dir /chemin --max-decode-depth=0

Exemple : un token Stripe encodé en base64 sera détecté :

# Fichier contenant : c2tfbGl2ZV80ZUMzOUhxTHlqV0Rhcmp0VDF6ZHA3ZGMK

Finding:     sk_live_4eC39HqLyjWDarjtT1zdp7dc
Secret:      sk_live_4eC39HqLyjWDarjtT1zdp7dc
RuleID:      stripe-access-token
Tags:        [decoded:base64 decode-depth:1]

Les tags decoded:base64 et decode-depth:1 indiquent que le secret a été trouvé après décodage.

Scan d’archives (v8.27+)

Gitleaks peut extraire et scanner le contenu des archives :

# Scanner une archive avec profondeur 1
gitleaks dir archive.tar.gz --max-archive-depth=1

# Scanner des archives imbriquées (profondeur 3)
gitleaks dir archives/ --max-archive-depth=3

Formats supportés : zip, tar, tar.gz, tar.bz2, tar.xz, 7z, rar, et plus.

Le chemin dans les résultats indique l’emplacement dans l’archive :

File:   nested.tar.gz!inner/files.tar!config/.env

Cela signifie : .env est dans files.tar, qui est dans nested.tar.gz.

Baseline : ignorer les secrets connus

La baseline permet d’ignorer les secrets déjà identifiés lors de scans ultérieurs. Utile pour les projets avec un historique contenant des secrets déjà traités.

Créer la baseline en générant un rapport initial
Fenêtre de terminal
```
gitleaks git --report-path baseline.json
```
Utiliser la baseline pour les scans suivants
Fenêtre de terminal
```
gitleaks git --baseline-path baseline.json --report-path findings.json
```
Seuls les nouveaux secrets seront rapportés.

Formats de sortie

Gitleaks supporte plusieurs formats de rapport :

# JSON (défaut si --report-path est utilisé)
gitleaks git -f json -r report.json

# CSV
gitleaks git -f csv -r report.csv

# SARIF (pour GitHub Code Scanning)
gitleaks git -f sarif -r report.sarif

# JUnit (pour CI/CD)
gitleaks git -f junit -r report.xml

# Template personnalisé
gitleaks git -f template --report-template custom.tmpl -r report.txt

# Sortie JSON vers stdout
gitleaks git -f json -r -

Configuration

Gitleaks est hautement configurable via un fichier .gitleaks.toml.

Ordre de précédence

Option --config ou -c
Variable d’environnement GITLEAKS_CONFIG (chemin fichier)
Variable d’environnement GITLEAKS_CONFIG_TOML (contenu TOML)
Fichier .gitleaks.toml dans le répertoire scanné

Si aucune configuration n’est trouvée, Gitleaks utilise les règles par défaut.

Étendre la configuration par défaut

# Titre de la configuration
title = "Configuration personnalisée"

# Étendre la configuration par défaut
[extend]
useDefault = true

# Désactiver certaines règles par défaut
disabledRules = ["generic-api-key"]

Créer une règle personnalisée

[[rules]]
# Identifiant unique
id = "internal-api-key"

# Description
description = "Clé API interne de l'entreprise"

# Expression régulière (syntaxe Go)
regex = '''int_[a-zA-Z0-9]{32}'''

# Mots-clés pour pré-filtrage (optimisation)
keywords = ["int_", "internal_api"]

# Entropie minimum (optionnel)
entropy = 3.5

# Tags pour le reporting
tags = ["internal", "api-key"]

Allowlists : exclure des faux positifs

Vous pouvez définir des allowlists au niveau global ou par règle :

# Allowlist globale (s'applique à toutes les règles)
[[allowlists]]
description = "Fichiers de test et documentation"
paths = [
  '''tests/''',
  '''fixtures/''',
  '''\.md$''',
]

# Allowlist pour une règle spécifique
[[rules]]
id = "aws-access-token"

  [[rules.allowlists]]
  description = "Clés de test AWS"
  regexes = ['''AKIAIOSFODNN7EXAMPLE''']
  stopwords = ["example", "test", "demo"]

Allowlists partagées (v8.25+)

Depuis v8.25, vous pouvez définir une allowlist et l’appliquer à plusieurs règles :

[[allowlists]]
# Appliquer à des règles spécifiques
targetRules = ["aws-access-token", "generic-api-key"]
description = "Fichiers de test"
paths = ['''tests/.*\.json$''']

Règles composites (v8.28+)

Les règles composites permettent de détecter des secrets multi-parties (ex: clé + secret) :

[[rules]]
id = "aws-keypair"
description = "Paire clé/secret AWS"
regex = '''AKIA[0-9A-Z]{16}'''

  # Règle requise : le secret doit être proche
  [[rules.required]]
  id = "aws-secret-pattern"
  withinLines = 5  # Le secret doit être dans les 5 lignes suivantes

Ignorer un secret spécifique dans le code

Ajoutez un commentaire gitleaks:allow pour ignorer une ligne :

# Cette clé est un exemple pour la documentation
AWS_KEY = "AKIAIOSFODNN7EXAMPLE"  # gitleaks:allow

Fichier .gitleaksignore

Ajoutez les fingerprints des secrets à ignorer :

# Format : fingerprint (depuis le rapport JSON)
fbc14303ffbf8fb1c2c1914e8dda7d0121633aca:config.env:aws-access-token:4
77b2a3e56973785a52ba4ae4b8dac61d4bac016f:keys:private-key:6

Intégration CI/CD

Pre-commit hook

Bloquez les secrets avant qu’ils ne soient commités :

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

Installer pre-commit
Fenêtre de terminal
```
pip install pre-commit
```

Créer le fichier de configuration

cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.0
    hooks:
      - id: gitleaks
EOF

Installer les hooks
Fenêtre de terminal
```
pre-commit install
```

Tester

git add . && git commit -m "test"
# Si un secret est détecté, le commit sera bloqué

Pour désactiver temporairement le hook :

SKIP=gitleaks git commit -m "skip check"

GitHub Actions

Utilisez l’action officielle Gitleaks :

name: Gitleaks

on:
  push:
    branches: [main]
  pull_request:

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Important : récupérer tout l'historique

      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

Intégrez Gitleaks dans vos merge requests :

stages:
  - security

gitleaks:
  stage: security
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks git --source="$CI_PROJECT_DIR" --verbose --exit-code 1
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
  allow_failure: false

Pour générer un rapport SARIF compatible avec GitLab Security Dashboard :

gitleaks:
  stage: security
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks git --source="$CI_PROJECT_DIR" -f sarif -r gl-sast-report.sarif
  artifacts:
    reports:
      sast: gl-sast-report.sarif
    paths:
      - gl-sast-report.sarif

Dépannage

Symptôme	Cause probable	Solution
Aucun résultat	Pas de secret trouvé	Normal si le repo est propre
Faux positifs nombreux	Secrets de test, exemples	Utiliser `.gitleaksignore` ou allowlists
Scan très lent	Historique Git volumineux	Utiliser `--log-opts="--max-count=100"`
Erreur “no such file”	URL distante non supportée	Cloner le repo localement d’abord
Secret encodé non détecté	Décodage désactivé	Vérifier `--max-decode-depth`
Archive non scannée	Scan d’archives désactivé	Activer `--max-archive-depth=1`

Logs de débogage

# Niveau debug
gitleaks git --log-level=debug

# Niveau trace (très verbeux)
gitleaks git --log-level=trace

Fichier lent à scanner

Depuis v8.26, Gitleaks identifie les fichiers lents :

gitleaks git --log-level=debug 2>&1 | grep "slow"

Ajoutez ces fichiers à une allowlist ou utilisez --max-target-megabytes :

# Ignorer les fichiers > 10 MB
gitleaks git --max-target-megabytes=10

Bonnes pratiques

Prévention : empêcher les secrets d’arriver dans Git

Pre-commit hooks — Bloquer les commits contenant des secrets
Fichiers .gitignore — Exclure .env, *.pem, credentials.json
Gestionnaire de secrets — Utiliser Vault, AWS Secrets Manager, ou Passbolt
Variables d’environnement — Injecter les secrets au runtime

Détection : scanner régulièrement

CI/CD — Scanner chaque PR et push
Scans périodiques — Auditer l’organisation complète chaque semaine
Nouveaux repos — Ajouter Gitleaks dès la création

Remédiation : réagir aux découvertes

Rotation immédiate — Révoquer et recréer le secret exposé
Audit des accès — Vérifier les logs d’utilisation du secret compromis
Nettoyage de l’historique — Utiliser git filter-branch ou BFG Repo-Cleaner
Post-mortem — Comprendre comment le secret a été exposé

Comparaison avec TruffleHog

Gitleaks et TruffleHog sont les deux outils open source les plus populaires pour la détection de secrets :

Critère	Gitleaks	TruffleHog
Vitesse	✅ Très rapide	⚠️ Plus lent (vérification)
Vérification automatique	❌ Non	✅ Oui (800+ APIs)
Sources supportées	3 (Git, dir, stdin)	18 (Git, Docker, S3, Jenkins…)
Nombre de règles	150+	800+
Configuration	TOML flexible	YAML simple
Décodage	✅ Base64, hex, URL	❌ Non
Archives	✅ ZIP, tar…	❌ Non
Règles composites	✅ (v8.28+)	❌ Non

Recommandation :

Gitleaks — Idéal pour les pre-commit hooks et les scans CI/CD rapides
TruffleHog — Préférable pour les audits de sécurité avec vérification des secrets actifs

Vous pouvez utiliser les deux : Gitleaks en pre-commit pour la rapidité, TruffleHog en scan périodique pour la vérification.

À retenir

Trois commandes — git (historique), dir (fichiers), stdin (pipeline)
150+ règles intégrées — AWS, Stripe, GitHub, Slack, et bien plus
Décodage automatique — Base64, hex, URL encoding détectés
Scan d’archives — ZIP, tar.gz, 7z… avec --max-archive-depth
Baseline — Ignorer les secrets déjà traités
Pre-commit — Bloquer les secrets avant qu’ils n’atteignent Git
Rotation immédiate — Un secret exposé = un secret compromis

Prochaines étapes

TruffleHog Scanner avec vérification automatique des secrets

SOPS Chiffrer les fichiers de secrets dans Git

Pre-commit Framework de hooks Git multi-langages

Passbolt Gestionnaire de mots de passe pour équipes DevOps

Ressources

Site officiel : github.com/gitleaks/gitleaks
Playground : gitleaks.io/playground
Configuration par défaut : gitleaks.toml
Action GitHub : gitleaks-action