Betterleaks : détecter les secrets, puis vérifier s'ils sont actifs

Betterleaks est un scanner de secrets écrit par l'équipe de Gitleaks, qui va plus loin que la détection : il peut vérifier si le secret trouvé est encore actif. C'est la différence qui compte en pratique, parce qu'un scan classique rend une liste de candidats sans dire lesquels sont dangereux aujourd'hui. Le projet est sous licence MIT, écrit en Go, et son développement est soutenu par Aikido Security.

Ce que vous allez apprendre

• Situer Betterleaks face à Gitleaks, désormais figé, et face à TruffleHog.
• Choisir entre la version 1 stable et la version 2 en préversion, qui n'ont ni la même interface ni les mêmes canaux d'installation.
• Installer l'outil et lancer un premier scan sur un dépôt Git.
• Distinguer la détection, la validation et l'analyse, trois étapes qui n'ont pas le même coût ni les mêmes effets de bord.
• Réduire les faux positifs avec les expressions Expr, que l'outil évalue avant et après la recherche par motif.
• Relier la leçon au SOCLE : l'exigence SOCLE-SEC-GEN-6, détection de fuite de secrets et procédure de réponse, trouve ici son dispositif de détection.

Pourquoi un successeur à Gitleaks

Gitleaks reste utilisable, et son README le déclare fonctionnellement figé : son auteur n'y intègre plus de fonctionnalité et ne publie que des correctifs de sécurité. Pour un scanner de secrets, ce gel a une conséquence directe que le guide Gitleaks détaille : les règles de détection ne s'enrichissent plus, alors que de nouveaux formats de jetons apparaissent régulièrement.

Betterleaks reprend donc le même terrain avec une équipe qui inclut l'auteur d'origine. Le dépôt a été créé le 3 février 2026, il n'est pas archivé, et sa dernière version stable, la 1.9.0, date du 29 septembre 2026. Ce n'est pas un fork abandonné dans un coin : le développement y est actif, avec cinq préversions de la 2.0.0 publiées entre le 30 septembre et le 28 octobre 2026.

Ce que ce guide a mesuré, et sur quoi

Les sorties reproduites ici viennent d'un binaire 1.9.0 installé avec l'outil mise, interrogé le 2026-10-29. Les digests des images ont été relevés auprès du registre, et les dates de version auprès de l'API GitHub. Les commandes propres à la version 2 sont lues dans la documentation de la branche main et signalées comme telles : elles n'ont pas été exécutées, puisque la 2.0.0 n'est pas encore stable.

Deux versions, deux interfaces

C'est le point à régler avant d'installer quoi que ce soit, parce qu'une bonne partie de la documentation en ligne décrit une version qui n'est pas encore stable. La branche main du dépôt porte le développement de la v2, tandis que la maintenance de la v1 vit sur la branche v1.x.

	Version 1.9.0	Version 2.0.0
État	dernière version stable, du 29 septembre 2026	préversion, rc.5 du 28 octobre 2026
Scanner un dossier	betterleaks dir <chemin>	betterleaks fs <chemin>, ou le chemin seul
Valider les secrets	--validation	-v, ou --validate
Sens de -v	--verbose, affichage détaillé	--validate, appels aux fournisseurs
Configuration locale	découverte dans le dossier de la cible	--config seulement
Rapport JSON	schéma d'origine	nouvelle enveloppe et nouveau schéma de résultat
Module Go	github.com/betterleaks/betterleaks	github.com/betterleaks/betterleaks/v2

Glissez pour voir

Le drapeau -v change de sens d'une version à l'autre, et c'est un piège de la migration. En v1, il vaut --verbose et se contente d'enrichir l'affichage. En v2, il vaut --validate et déclenche des appels aux fournisseurs de jetons. Une commande recopiée telle quelle après une montée de version peut donc envoyer vos secrets à des API tierces, sans que rien ne l'annonce. Ces deux valeurs sont lues dans le code source de chaque branche.

Le tag Docker `:v2` n'existe pas encore

Le README propose docker pull ghcr.io/betterleaks/betterleaks:v2 comme canal stable de la v2. Relevé auprès du registre le 2026-10-29, ce tag ne résout rien : il n'est pas publié, puisque la 2.0.0 n'est pas sortie en version stable. Le README décrit ici l'état visé, pas l'état actuel. Pour essayer la préversion, nommez la version exacte.

Installation

Choisissez votre canal selon la version que vous visez. Les gestionnaires de paquets suivent la v1 tant que la 2.0.0 n'est pas stable, ce qui est le comportement attendu et non un retard d'empaquetage.

Conteneur (v1 stable)

L'image porte son digest : un tag seul peut être redéplacé vers un autre contenu sans que rien ne le signale.

docker pull ghcr.io/betterleaks/betterleaks:v1.9.0@sha256:e3b95b0db6c2735db17165c009b0ad6d9cef34fb4578659232b98f69d7346cac

Conteneur (v2 en préversion)

La préversion se nomme en entier, puisqu'elle ne met à jour ni latest, ni v2, ni le cask Homebrew.

docker pull ghcr.io/betterleaks/betterleaks:v2.0.0-rc.5@sha256:35f0b9cfb194d5a84000ceb91085d8a42098bedb4f7e65938fd73f02daa63d54

Go

L'installation par Go compile depuis les sources et vous laisse choisir la version exacte ; pour la version 2, le chemin du module porte le suffixe /v2.

# Version 2 en préversion
go install github.com/betterleaks/betterleaks/v2@v2.0.0-rc.5

Paquets système

Ces canaux servent la v1 jusqu'à la sortie stable de la 2.0.0.

# macOS
brew install betterleaks

# Fedora
sudo dnf install betterleaks

Le tag `latest` ne pointe pas sur la dernière stable

Relevé le 2026-10-29, latest et v1.9.0 ne résolvent pas vers le même digest. Un docker pull ghcr.io/betterleaks/betterleaks:latest ne vous donne donc pas la version 1.9.0. C'est une raison de plus de nommer la version et d'épingler par digest, dans un guide comme dans un pipeline.

Les premiers scans

Chaque source se nomme explicitement, et la v1 n'a pas de commande par défaut : un chemin donné seul ne scanne rien. L'ergonomie reste proche de celle de Gitleaks, ce qui limite le coût du changement sur les usages simples.

# Un dossier ou un fichier ; « file » et « directory » sont des alias de « dir »
betterleaks dir /chemin/de/la/cible

# Un dépôt Git local, historique compris
betterleaks git /chemin/du/depot

# Une entrée standard
cat fichier.txt | betterleaks stdin

En version 2, la commande dir s'appelle fs, avec filesystem pour forme longue, et le chemin peut se passer de sous-commande. C'est la différence la plus visible entre les deux interfaces, et la première à corriger dans un script repris tel quel. En 1.9.0, betterleaks fs répond unknown command "fs", et un chemin donné seul reçoit la même réponse.

La sortie d'un scan tient en deux lignes. Voici celle obtenue sur un fichier d'essai qui contient un faux jeton GitHub :

INF scanned ~119 bytes (119 bytes) in 110ms
WRN leaks found: 1

La première ligne se lit avant de se réjouir d'un rapport vide : un volume analysé sans rapport avec la taille de la cible signale un scan qui n'a pas vu ce que vous croyiez, par exemple un clone tronqué en CI ou un mauvais chemin de départ.

Au-delà du dépôt, Betterleaks sait interroger des sources que Gitleaks ne couvre pas : une organisation GitHub ou GitLab avec ses tickets et ses demandes de fusion, un espace Hugging Face, un bucket S3. C'est utile quand le secret ne fuit pas par le code, mais par un commentaire de ticket.

La version 2, en préversion, y ajoute l'image de conteneur, avec ses couches historiques et ses attestations. Cette source n'existe pas en version 1 : inutile de la chercher dans la liste des sous-commandes de la branche stable.

# Une organisation GitHub, en élargissant aux tickets et aux demandes de fusion
betterleaks github https://github.com/mon-organisation --include issues,prs

# Un projet GitLab et ses jobs de CI
betterleaks gitlab https://gitlab.com/mon-groupe/mon-projet --include issues,mrs,ci-jobs

Détection, validation, analyse

Ces trois mots désignent trois étapes différentes, et les confondre conduit à envoyer des secrets vers des API tierces sans l'avoir décidé.

1. La détection reste locale

   Le scan cherche des motifs, applique ses filtres et rend des résultats, sans aucune requête vers les fournisseurs de jetons. C'est le comportement par défaut dans les deux versions.

2. La validation interroge le fournisseur

   En v1, --validation demande au fournisseur si le jeton trouvé est encore valide ; en v2, c'est -v ou --validate. Le triage en profite : une clé révoquée depuis six mois ne mérite pas la même urgence qu'un jeton actif. Le prix à payer est réel aussi, puisque le secret quitte votre machine.

3. L'analyse résout l'identité et les droits

   La v2 ajoute -a, ou --analyze, qui enrichit les jetons valides avec le compte auquel ils appartiennent, leurs capacités et une gravité. L'analyse implique la validation, elle ne s'y substitue pas.

En version 2, les variables d'environnement BETTERLEAKS_VALIDATE et BETTERLEAKS_ANALYZE activent ces étapes sans toucher aux commandes, et une option explicite l'emporte sur la variable. En CI, préférez donc l'option : une variable posée au niveau d'un projet entier finit par s'appliquer à des pipelines qui ne l'attendaient pas.

La version 2 sait aussi révoquer un secret, lorsque la règle définit cette action. C'est une opération à part : aucun scan ne la déclenche, elle se lance volontairement.

# Quelles règles savent analyser, et lesquelles savent révoquer (v2)
betterleaks config show ids --analysis
betterleaks config show ids --revocation

# Révoquer explicitement, hors de tout scan (v2)
betterleaks revoke --rule <identifiant-de-regle>

La révocation n'annule pas la compromission

Révoquer un jeton trouvé est un bon premier geste, mais il ne remplace ni la rotation ni l'audit des accès. Le secret est resté lisible dans l'historique, et vous ne savez pas qui l'a lu. Le guide sur les secrets dans le code et l'historique Git détaille la marche à suivre.

Filtrer les faux positifs avec Expr

C'est la force annoncée de l'outil, et la raison pour laquelle sa configuration ressemble peu à celle de Gitleaks. Les filtres s'écrivent en Expr, un langage d'expressions, et interviennent à deux moments bien distincts.

Un prefilter s'évalue avant toute recherche par motif. Il ne voit que les attributs de la ressource, comme le chemin du fichier ou l'auteur du commit, et sert à écarter tôt ce qui ne vaut pas la peine d'être scanné. Un filter s'évalue après une correspondance, et voit en plus le résultat candidat, donc le secret lui-même et le texte qui l'entoure.

# Écarter des chemins entiers avant la recherche, qui coûte cher
prefilter = '''
matchesAny(attributes["path"], [
  `(?i)\.(?:bmp|gif|jpe?g|png|svg|tiff|pdf|exe)$`,
  `(?:^|/)node_modules(?:/.*)?$`,
  `(?:^|/)vendor(?:/.*)?$`
])
|| attributes["git.author_name"] == "renovate[bot]"
'''

# Écarter des valeurs d'exemple, après correspondance
filter = '''
containsAny(finding["secret"], [
  "EXAMPLE",
  "CHANGEME",
  "YOUR_API_KEY_HERE",
  "0000000000000000"
])
'''

La distinction a un effet direct sur la durée du scan. Un prefilter qui écarte node_modules évite de lire des milliers de fichiers ; un filter équivalent les aurait tous lus avant de jeter les résultats. Sur un dépôt volumineux, cela peut séparer un scan de demande de fusion tenable d'un scan qu'on finit par désactiver.

L'outil propose en plus un filtrage dit BPE, qui mesure à quel point une chaîne est « rare » au regard du langage naturel. L'idée est d'écarter les phrases ordinaires qu'un détecteur générique prend pour des secrets à forte entropie. Vérifiez son effet sur vos dépôts avant de compter dessus : un filtre statistique se règle sur le corpus qu'il traite.

Une configuration v1 ne vaut pas telle quelle en v2

Le passage à la version 2 change plus que des noms d'options. Le rapport JSON prend une nouvelle enveloppe, ce qui peut casser les outils qui le lisent, et le module Go change de chemin pour les projets qui intègrent le scanner comme bibliothèque. Lisez le guide de migration avant de basculer un pipeline qui fonctionne.

Intégration dans un pipeline

La v1.9.0 choisit sa configuration selon un ordre de précédence à quatre niveaux, que son aide documente : l'option --config d'abord, puis les variables BETTERLEAKS_CONFIG ou GITLEAKS_CONFIG, puis les mêmes suffixées _TOML qui portent le contenu, et enfin un .betterleaks.toml ou .gitleaks.toml trouvé dans le dossier de la cible. Sans rien de tout cela, l'outil applique sa configuration intégrée.

Ce dernier niveau est commode et risqué : il suffit de lancer le scan depuis un autre dossier pour changer de règles sans s'en apercevoir. En CI, nommez donc explicitement la configuration.

betterleaks dir . --config .betterleaks.toml --redact --report-format sarif --report-path resultats.sarif

L'option --redact masque la valeur du secret dans le rapport, et elle accepte un pourcentage : --redact=20 n'en masque qu'une partie, l'absence de valeur masquant tout. C'est précieux dès que le rapport devient un artefact de CI, qu'une équipe entière peut lire. Un scan rend le code de sortie 1 lorsqu'il trouve quelque chose, et --exit-code change cette valeur si votre plateforme en attend une autre.

Avant de brancher le tout, betterleaks config check compile la configuration sans contacter aucun fournisseur, et betterleaks config path dit quelle source a été retenue, ce qui lève le doute en une commande.

Deux cadrages valent mieux qu'un scan unique, et le guide sur le secrets scanning développe cette logique. Le scan de demande de fusion porte sur un différentiel et doit rester rapide. Le scan périodique repasse sur l'historique complet et rattrape ce que les règles d'hier ne savaient pas détecter, ce qui est précisément l'argument en faveur d'un outil encore développé.

Reprendre une configuration Gitleaks

La version 1 de Betterleaks facilite la reprise d'un existant Gitleaks : elle lit un .gitleaks.toml comme un .betterleaks.toml, --gitleaks-ignore-path accepte un .gitleaksignore, et --ignore-gitleaks-allow traite les commentaires gitleaks:allow au même titre que betterleaks:allow. La reprise n'est pas pour autant une substitution de binaire : la logique de filtrage s'écrit en Expr, et rien ne garantit l'équivalence des résultats, comme le montre l'encadré ci-dessous.

Mesurez avant de basculer

Faites tourner les deux scanners sur un dépôt qui contient un faux secret connu, et comparez les résultats un par un. Les règles ne se recouvrent pas : sur un fichier d'essai portant un jeton ghp_ et une clé AKIA, la configuration par défaut de Betterleaks 1.9.0 n'a signalé que le premier, là où Gitleaks 8.30.1 détecte aussi la seconde.

Le même essai montre ce qu'une configuration mal choisie coûte. Lancé avec la configuration intégrée, le scan rend leaks found: 1 et sort en 1. Lancé avec un fichier de configuration qui ne déclare aucune règle, il rend no leaks found et sort en 0, sur exactement le même fichier. Un pipeline vert ne dit donc rien tant que vous n'avez pas vérifié quelle configuration a été chargée.

Gitleaks, Betterleaks, TruffleHog ou Kingfisher : lequel choisir ?

Betterleaks vient de l'équipe de Gitleaks et y ajoute des règles filtrables en Expr, une validation optionnelle et de nouvelles sources. Le tableau le situe parmi les trois autres scanners du module, dont TruffleHog pour la vérification et Kingfisher pour la révocation.

Le tableau compare les quatre scanners sur ce qui compte au moment de choisir : où ils cherchent, ce qu'ils font d'un secret trouvé et comment ils s'intègrent à une chaîne de livraison. Chaque cellule vient de la documentation de l'outil lui-même à la version indiquée en en-tête. Quand cette documentation ne dit rien d'une capacité, la cellule porte « non documenté » : cela ne prouve pas que l'outil en soit incapable, seulement que sa documentation ne l'annonce pas.

Critère	Gitleaks 8.30.1	Betterleaks 1.9.0	TruffleHog 3.99.7	Kingfisher 2.16.0
Dépôt Git et historique	oui, gitleaks git (via git log -p)	oui, betterleaks git	oui, trufflehog git	oui, historique inclus
Dépôt distant, organisation	non documenté (trois modes : git, dir, stdin)	GitHub (organisation, utilisateur, PR, tickets, Actions, releases), GitLab (groupe, projet, merge requests), Hugging Face	GitHub (--org), GitLab, Hugging Face	GitHub, GitLab, Azure Repos, Bitbucket, Gitea, Hugging Face
Fichiers et répertoires	oui, gitleaks dir	oui, betterleaks dir	oui, trufflehog filesystem	oui
Image de conteneur	non documenté	non documenté	oui, trufflehog docker	oui, kingfisher scan docker
Autres sources	entrée standard	entrée standard, S3 (dont Cloudflare R2)	S3, GCS, Postman, Jenkins, Elasticsearch, CircleCI, Travis CI, syslog, entrée standard	S3, GCS, Azure Blob Storage, Jira, Confluence, Slack, Teams, Postman
Vérifie qu'un secret est actif	non documenté	oui, par une expression validate dans la règle, sur option seulement, --validation en 1.9.0 (-v ou --validate en version 2) ; statuts valid, invalid, revoked, unknown, error	oui, par appel à l'API du fournisseur, activé par défaut (--no-verification pour l'éteindre)	oui, activé par défaut (--no-validate pour l'éteindre)
Mesure le rayon d'impact	non documenté	non documenté en 1.9.0 ; la version 2 en préversion ajoute -a ou --analyze (compte, capacités et gravité des jetons valides)	oui, trufflehog analyze (permissions et ressources accessibles) pour une partie des types d'identifiants	oui, --blast-radius pour les fournisseurs pris en charge (identités, permissions, ressources)
Révoque un secret	non documenté	non documenté en 1.9.0 (la révocation n'y apparaît que comme statut rendu par la validation) ; la version 2 en préversion annonce betterleaks revoke	non documenté	oui, kingfisher revoke, pour les fournisseurs pris en charge
Hook pre-commit	oui, hooks pre-commit fournis	oui, hooks pre-commit fournis	oui, documenté (hooksPath, framework pre-commit, Husky)	oui, script d'installation et framework pre-commit
Intégration CI	action gitleaks-action (dépôt séparé), image Docker	image Docker ghcr.io/betterleaks/betterleaks ; pas d'action dédiée dans le README	action GitHub trufflesecurity/trufflehog, image Docker	image Docker ghcr.io/mongodb/kingfisher ; pas d'action dédiée dans la documentation
Formats de sortie	JSON, CSV, JUnit, SARIF, modèle	JSON, CSV, JUnit, SARIF, modèle (JSONL pour validate)	texte, JSON, SARIF, format GitHub Actions	texte lisible, JSON, JSONL, BSON, TOON, SARIF, HTML
Licence	MIT	MIT	AGPL-3.0	Apache-2.0
Langage	Go	Go	Go	Rust

Glissez pour voir

Relevé effectué le 2026-10-30 sur la dernière version publiée de chaque outil. Les versions évoluent vite : vérifiez la date avant de vous fonder sur une cellule.

Le bon outil dépend d'abord de ce que vous voulez faire d'un secret une fois trouvé. Pour bloquer un commit ou une fusion, tous les quatre conviennent, et Gitleaks suffit quand les règles sont maîtrisées et qu'il est déjà en place. Pour distinguer les secrets vivants des restes d'exemples, il faut un outil qui vérifie : Betterleaks (sur option), TruffleHog ou Kingfisher. Pour savoir ce qu'un jeton actif ouvre, TruffleHog (analyze) et Kingfisher (--blast-radius) répondent, chacun sur les fournisseurs qu'ils prennent en charge ; Betterleaks ajoute une analyse comparable dans sa version 2, encore en préversion. Pour agir sans attendre le propriétaire du secret, seul Kingfisher documente une révocation depuis la ligne de commande dans les versions stables relevées ; Betterleaks en annonce une aussi pour sa version 2.

Si la cible dépasse le dépôt (tickets, messageries, images, buckets), regardez la ligne « Autres sources » : l'étendue varie beaucoup d'un outil à l'autre. Une licence AGPL-3.0 peut aussi peser dans le choix selon l'usage qu'en fait votre organisation. Enfin, un scanner qui ne trouve rien ne prouve rien : testez celui que vous retenez sur un dépôt contenant un faux secret connu avant de le brancher en CI. Pour figer l'existant et ne bloquer que les nouveautés, le guide detect-secrets traite une approche par baseline, et la comparaison des outils de détection de secrets élargit à d'autres candidats.

---

À retenir

• Betterleaks est développé par l'équipe de Gitleaks, sous licence MIT, avec le soutien d'Aikido Security.
• Gitleaks est figé fonctionnellement et ne reçoit plus que des correctifs de sécurité, ce qui gèle ses règles de détection.
• La 1.9.0 est la dernière version stable ; la 2.0.0 reste en préversion, avec une interface et un format de rapport différents.
• Un scan ne contacte aucun fournisseur par défaut : la validation s'active avec --validation en v1, -v en v2, et elle fait sortir le secret de votre machine.
• Les filtres Expr se jouent avant ou après la recherche par motif, et ce choix décide de la durée du scan autant que de sa justesse.
• En v1, -v vaut --verbose ; en v2, il vaut --validate : le même drapeau affiche des détails ou appelle les fournisseurs selon la version.
• La configuration se choisit par un ordre de précédence dont le dernier niveau est le dossier de la cible : lancer le scan ailleurs change les règles sans prévenir.
• Le tag latest ne pointe pas sur la dernière stable, et le tag v2 n'existe pas encore : nommez la version et épinglez par digest.
• Pour l'exigence SOCLE-SEC-GEN-6, la preuve attendue est un dispositif de détection, ici un scan Betterleaks branché en hook et en CI sur vos dépôts, accompagné d'une procédure de réponse écrite : qui révoque, qui renouvelle, dans quel délai. Le scanner ne fournit que la première moitié de cette preuve.

Contrôle de connaissances

Vérifiez que l'essentiel de cette leçon est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 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

Ressources

Les liens ci-dessous pointent vers les sources officielles du projet. La branche v1.x porte la version stable documentée ici, tandis que main décrit déjà la version 2 : lire la mauvaise branche conduit à des noms de commandes erronés.

• Dépôt : github.com/betterleaks/betterleaks
• Branche de la version 1 : v1.x
• Guide de migration vers la version 2 : docs/v2_migration.md
• Langage des filtres : expr-lang.org

×

📖 Voir la documentation →