TruffleHog : trouver, vérifier et analyser les identifiants divulgués

Quatre étapes pour trouver des secrets

TruffleHog est un outil en ligne de commande pour trouver des identifiants divulgués. Le README décrit son fonctionnement en quatre étapes : découverte, classification, validation et analyse. Dans ce contexte, un secret est un identifiant qu'une machine utilise pour s'authentifier auprès d'une autre machine, ce qui inclut les clés API, les mots de passe de base de données, les clés de chiffrement privées, etc. La découverte recherche dans des sources comme les dépôts Git, les discussions, les wikis, les journaux, les plateformes de test d'API, les stockages d'objets et les systèmes de fichiers. La classification associe ce qui est trouvé à plus de 800 types de secrets et les relie à l'identité à laquelle ils appartiennent, ce qui permet de reconnaître une chaîne comme un secret AWS, un secret Stripe, un secret Cloudflare, un mot de passe Postgres ou une clé privée SSL. La validation va plus loin en tentant de se connecter avec chaque secret classifié pour confirmer s'il est encore actif. L'analyse, appliquée à environ vingt des types d'identifiants les plus couramment divulgués, envoie plusieurs requêtes pour apprendre qui a créé le secret, à quelles ressources il peut accéder et quelles permissions il détient sur ces ressources.

Sources et cibles de scan

La surface de commande est organisée en sous-commandes par source de données. Le README liste git, github, gitlab, huggingface, docker, s3, filesystem, syslog, circleci, travisci, gcs, postman, jenkins, elasticsearch, stdin et multi-scan. Chaque sous-commande a ses propres options, visibles avec --help. La section de démarrage rapide montre des invocations représentatives : trufflehog git https://github.com/trufflesecurity/test_keys --results=verified scanne un dépôt, trufflehog github --org=trufflesecurity scanne une organisation, trufflehog s3 --bucket=<bucket name> scanne un bucket S3, trufflehog gcs --project-id=<project-ID> --cloud-environment scanne Google Cloud Storage, trufflehog docker --image trufflesecurity/secrets scanne une image conteneur, et trufflehog filesystem path/to/file1.txt scanne des fichiers et répertoires locaux. Une commande expérimentale github-experimental énumère les commits supprimés et cachés d'un dépôt GitHub ; le README avertit qu'il s'agit d'une fonctionnalité alpha et que l'énumération de tous les commits valides peut prendre de vingt minutes à quelques heures selon la taille du dépôt.

Ce que signifie verified

Le README définit trois statuts de résultat. Un résultat verified est un identifiant confirmé comme valide et actif par un test contre l'API à laquelle il semble appartenir. Un résultat unverified est détecté mais non confirmé valide ; il peut être invalide, expiré ou avoir une vérification désactivée. Un résultat unknown signifie que la vérification a été tentée mais a échoué, par exemple à cause d'une erreur réseau ou d'API. Le README donne l'exemple du détecteur AWS : il effectue un appel API GetCallerIdentity pour vérifier si un identifiant AWS est actif. Pour les clés privées, la vérification confirme que la clé peut être utilisée en direct pour l'authentification SSH ou SSL, via une technologie que le README appelle Driftwood, testée contre des millions d'utilisateurs GitHub et des milliards de certificats TLS. Le README ne quantifie pas les taux de détection, les faux positifs ou la couverture de vérification au-delà des nombres de détecteurs annoncés.

Installation et vérification des artefacts

Plusieurs chemins d'installation sont documentés. Les utilisateurs macOS peuvent exécuter brew install trufflehog. Docker est pris en charge avec un montage du répertoire courant vers /pwd ; le README montre des variantes pour Unix, l'invite de commandes Windows, Windows PowerShell et les Mac M1/M2, ces derniers avec --platform linux/arm64. Les versions binaires se téléchargent et se décompressent depuis la page des releases GitHub. La compilation depuis les sources utilise git clone puis cd trufflehog; go install. Un script d'installation est disponible dans scripts/install.sh, avec un drapeau -v pour vérifier la signature de la somme de contrôle et un argument de tag de version pour installer une version spécifique. Le README explique que des sommes de contrôle sont appliquées à tous les artefacts et que le fichier de sommes est signé avec cosign. La vérification nécessite de télécharger les fichiers de sommes, pem et sig depuis la page des releases, d'exécuter cosign verify-blob avec une expression régulière d'identité de certificat correspondant au workflow GitHub, puis sha256sum --ignore-missing -c pour confirmer les hachages des artefacts.

Configuration, détecteurs personnalisés et drapeaux

La CLI expose des drapeaux globaux partagés et des options par commande. La sortie de git --help dans le README montre --results avec une valeur par défaut de verified,unverified,unknown, --json pour la sortie JSON, --concurrency pour le nombre de travailleurs, --no-verification pour sauter la vérification, et --fail pour quitter avec le code 183 si des résultats sont trouvés. La sélection des détecteurs se fait avec --include-detectors et --exclude-detectors, et l'analyse des archives a des limites de taille, de profondeur et de délai. Un fichier de configuration passé avec --config peut définir des détecteurs regex personnalisés et plusieurs sources ; les sources de la configuration ne sont utilisées que par la sous-commande multi-scan, tandis que les détecteurs regex personnalisés fonctionnent avec toute sous-commande. Un détecteur personnalisé nécessite au moins une expression régulière et un mot-clé, et la vérification est déléguée à un webhook qui reçoit un POST JSON contenant les correspondances regex ; une réponse 200 OK marque le secret comme vérifié, et une erreur réseau ou d'API le marque comme unknown. Le README qualifie cette fonctionnalité d'alpha et sujette à changement. La détection générique de JWT est également documentée pour les JWT utilisant la cryptographie à clé publique dont la clé publique peut être obtenue.

Intégration CI/CD et codes de sortie

Le README documente une action GitHub, trufflesecurity/trufflehog@main, avec des entrées pour path, base, head, extra_args, version et image. Le workflow d'exemple recherche les secrets vivants dans toutes les pull requests et les pushes vers main, avec fetch-depth réglé à 0 pour avoir l'historique complet. Pour les workflows autonomes, le README recommande le clonage superficiel, en calculant un fetch-depth basé sur le nombre de commits de l'événement push ou pull request. Un exemple GitLab CI installe l'outil avec le script d'installation et exécute trufflehog filesystem "$SCAN_PATH" --results=verified,unknown --fail --json dans les pipelines de merge request. Un hook pre-commit est référencé dans PreCommit.md. Les codes de sortie sont précisés : 0 pour aucune erreur et aucun résultat, 1 pour une erreur rencontrée pendant le scan, et 183 pour aucune erreur avec des résultats trouvés, renvoyé uniquement lorsque --fail est utilisé.

État du projet, licence et stabilité

Le dépôt est écrit en Go et, au moment de l'instantané des métadonnées, comptait 27 308 étoiles, 2 519 forks et 505 problèmes ouverts. Le README indique que v3 est une réécriture complète en Go, ajoutant plus de 700 détecteurs d'identifiants prenant en charge la vérification active, une prise en charge native du scan de GitHub, GitLab, Docker, des systèmes de fichiers, S3, GCS, Circle CI et Travis CI, et une disponibilité comme action GitHub et hook pre-commit. Depuis v3.0, le projet est publié sous AGPL-3.0, et le README précise que l'ancien code est conservé sous GPL 2.0 dans l'historique du dépôt et les versions de paquets précédentes. Le texte de licence accorde la liberté de copier, distribuer et modifier le logiciel, et pour les serveurs réseau exige que les opérateurs fournissent le code source des versions modifiées fonctionnant sur un serveur accessible publiquement. La licence indique également qu'il n'y a aucune garantie pour l'œuvre, sauf dans la mesure où des garanties sont fournies, et elle ne dit rien sur le support, les garanties de sécurité ou les engagements de maintenance. Le README avertit explicitement que l'API publique est instable : aucune garantie de stabilité ne peut être donnée pendant que le projet est en développement intensif. Un CLA complété est requis pour les contributions futures.

Vérifier trufflehog sur son chemin réel

Pour TruffleHog, commencez avec trufflehog git https://github.com/trufflesecurity/test_keys --results=verified, puis essayez trufflehog github --org=trufflesecurity --exclude-archived. Examinez le détecteur, le commit, le fichier et l état verified dans la sortie JSON. Pour un binaire, vérifiez trufflehog_{version}_checksums.txt avec cosign verify-blob, puis sha256sum --ignore-missing -c. Le scan révèle une exposition potentielle, mais la révocation et la rotation restent distinctes.

Conclusion éditoriale

TruffleHog est un outil en ligne de commande Go qui trouve, classifie, vérifie et analyse les identifiants divulgués dans Git, le stockage cloud, les conteneurs et d'autres sources, avec un modèle de vérification distinguant les résultats verified, unverified et unknown. Le README n'établit ni benchmarks, ni taux de détection, ni garanties de production ; l'API publique de la bibliothèque n'a aucune garantie de stabilité, et le projet est sous licence AGPL-3.0, avec un CLA requis pour les contributions.

Sources officielles

1. Official documentation
2. Official README
3. Project repository
4. Release notes