TruffleHog : détecter les secrets exposés dans votre code et infrastructure

TruffleHog détecte les secrets exposés dans vos dépôts Git, images Docker, buckets cloud et plus encore. Avec plus de 800 détecteurs intégrés, il identifie et vérifie automatiquement si les credentials trouvés sont actifs. C’est l’outil de référence pour éviter que vos clés API, tokens et mots de passe ne finissent sur GitHub.

Ce que vous allez apprendre

Comprendre comment TruffleHog détecte et vérifie les secrets
Scanner différentes sources : Git, Docker, S3, Jenkins, Elasticsearch
Filtrer les résultats pour réduire les faux positifs
Intégrer TruffleHog dans vos pipelines CI/CD (GitHub Actions, GitLab CI)
Analyser les permissions des secrets découverts

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 dans une image Docker	Certificat SSL dans `/app/certs/`	Interception de trafic
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 TruffleHog résout ce problème

TruffleHog ne se contente pas de chercher des patterns avec des regex. Il suit un processus en quatre étapes qui le distingue des autres outils.

Découverte : où chercher ?

TruffleHog scanne bien plus que les dépôts Git. Il analyse 18 sources différentes, couvrant tout le cycle de développement :

Source	Commande	Ce qui est scanné
Git	`git`	Tout l’historique, toutes les branches
GitHub	`github`	Repos, orgs, issues, pull requests, gists
GitLab	`gitlab`	Repos, groupes, snippets
Docker	`docker`	Images locales ou registry, layers
Filesystem	`filesystem`	Fichiers et répertoires locaux
S3	`s3`	Buckets AWS S3
GCS	`gcs`	Buckets Google Cloud Storage
Jenkins	`jenkins`	Jobs, configurations, builds
Elasticsearch	`elasticsearch`	Index et documents
Postman	`postman`	Collections et environnements
HuggingFace	`huggingface`	Modèles, datasets, spaces
CircleCI	`circleci`	Configurations et environnements
TravisCI	`travisci`	Configurations
Syslog	`syslog`	Flux de logs
stdin	`stdin`	Entrée standard (pipes)

Classification : quel type de secret ?

TruffleHog intègre plus de 800 détecteurs capables d’identifier le type exact de chaque secret. Ce n’est pas juste “une chaîne qui ressemble à une clé” mais une identification précise :

AWS Access Key (commence par AKIA...)
Stripe API Key (commence par sk_live_ ou sk_test_)
GitHub Personal Access Token (commence par ghp_...)
Clés privées RSA, DSA, ECDSA
Tokens JWT avec vérification cryptographique
Mots de passe dans des URLs (PostgreSQL, MySQL, MongoDB)

Cette classification est importante car elle détermine comment le secret sera vérifié et quelles actions de remédiation sont nécessaires.

Vérification : le secret est-il actif ?

C’est la fonctionnalité qui distingue TruffleHog de la concurrence. Pour chaque secret détecté, il tente de l’utiliser contre l’API correspondante pour vérifier s’il est actif.

Par exemple, pour une clé AWS, TruffleHog appelle sts:GetCallerIdentity pour voir si la clé fonctionne. Pour un token GitHub, il appelle l’API GitHub. Cette vérification élimine les faux positifs et vous montre exactement quels secrets sont dangereux maintenant.

Les résultats sont classés en trois catégories :

Statut	Signification	Action requise
✅ verified	Le secret fonctionne	Rotation immédiate — le secret est actif
❓ unknown	Vérification impossible	Erreur réseau ou API — vérifier manuellement
⚠️ unverified	Détecté mais non vérifié	Peut être expiré, invalide, ou non vérifiable

Analyse : quelles permissions ?

Pour les types de secrets les plus courants (AWS, GCP, GitHub…), TruffleHog va plus loin avec la fonction Analyze. Au lieu d’un simple “oui/non” sur la validité, il découvre :

Quel compte/utilisateur possède ce secret
Quelles ressources il peut accéder
Quelles permissions il a sur ces ressources

C’est critique pour évaluer l’impact : une clé AWS avec accès s3:* sur tous les buckets est bien plus grave qu’une clé avec s3:GetObject sur un seul bucket public.

Installation

Plusieurs méthodes sont disponibles selon votre environnement.

La méthode la plus simple est le script d’installation officiel :

# Installation via script officiel
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b ~/.local/bin

# Vérification
~/.local/bin/trufflehog --version
# trufflehog 3.93.3

Pour une installation système (nécessite sudo) :

curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sudo sh -s -- -b /usr/local/bin

Avec Homebrew :

brew install trufflehog

# Vérification
trufflehog --version

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

# Scanner un repo GitHub
docker run --rm -it trufflesecurity/trufflehog:latest \
  github --repo https://github.com/trufflesecurity/test_keys

# Scanner un répertoire local
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest \
  filesystem /pwd

Téléchargez directement depuis les releases GitHub :

VERSION="3.93.3"
wget https://github.com/trufflesecurity/trufflehog/releases/download/v${VERSION}/trufflehog_${VERSION}_linux_amd64.tar.gz
tar xzf trufflehog_${VERSION}_linux_amd64.tar.gz
sudo install trufflehog /usr/local/bin/

Scanner un dépôt Git

Le cas d’usage le plus courant est de scanner l’historique complet d’un dépôt Git pour trouver des secrets qui ont pu être commités par le passé.

Scan de base

TruffleHog scanne tout l’historique Git, y compris les branches et les commits supprimés mais récupérables. C’est intentionnel : un attaquant ferait la même chose.

# Scanner un repo GitHub
trufflehog git https://github.com/trufflesecurity/test_keys

# Scanner uniquement les secrets vérifiés (actifs)
trufflehog git https://github.com/trufflesecurity/test_keys --results=verified

Exemple de sortie (avec un secret vérifié) :

🐷🔑🐷  TruffleHog. Unearth your secrets. 🐷🔑🐷

Found verified result 🐷🔑
Detector Type: AWS
Decoder Type: PLAIN
Raw result: AKIAYVP4CIPPERUVIFXG
Line: 4
Commit: fbc14303ffbf8fb1c2c1914e8dda7d0121633aca
File: keys
Email: counter <counter@counters-MacBook-Air.local>
Repository: https://github.com/trufflesecurity/test_keys
Timestamp: 2022-06-16 10:17:40 -0700 PDT

Cette sortie vous indique exactement :

Le type de secret : AWS Access Key
L’emplacement : fichier keys, ligne 4
Quand : commit du 16 juin 2022
Par qui : l’email de l’auteur du commit

Comprendre les options de filtrage

TruffleHog propose plusieurs options pour affiner les résultats et réduire le bruit :

# Afficher uniquement les secrets vérifiés (recommandé pour le triage)
trufflehog git <URL> --results=verified

# Afficher vérifiés + inconnus (erreurs de vérification)
trufflehog git <URL> --results=verified,unknown

# Tout afficher (y compris les faux positifs potentiels)
trufflehog git <URL> --results=verified,unverified,unknown

# Désactiver la vérification (plus rapide, mais plus de faux positifs)
trufflehog git <URL> --no-verification

# Filtrer par entropie (réduire les faux positifs sur les chaînes aléatoires)
trufflehog git <URL> --filter-entropy=3.0

Scanner un repo local

Pour scanner un repo cloné localement, utilisez le protocole file:// :

# Cloner le repo
git clone https://github.com/exemple/mon-projet.git
cd mon-projet

# Scanner (depuis le parent du repo)
cd ..
trufflehog git file://mon-projet --results=verified,unknown

Scanner une organisation GitHub complète

Pour auditer tous les repos d’une organisation :

# Sans authentification (limité par rate limiting)
trufflehog github --org=mon-organisation --results=verified

# Avec un token GitHub (recommandé)
export GITHUB_TOKEN="ghp_votre_token"
trufflehog github --org=mon-organisation --results=verified --token=$GITHUB_TOKEN

# Inclure les issues et pull requests
trufflehog github --org=mon-organisation --issue-comments --pr-comments

L’option --token est fortement recommandée car les scans non authentifiés sont limités à 60 requêtes/heure contre 5000 avec un token.

Scanner d’autres sources

Images Docker

Les images Docker contiennent souvent des secrets dans leurs layers : certificats, fichiers de configuration, variables d’environnement.

# Scanner une image depuis un registry
trufflehog docker --image nginx:latest

# Scanner une image locale (préfixe docker://)
trufflehog docker --image docker://mon-image:tag

# Scanner plusieurs images
trufflehog docker --image postgres:15 --image redis:7

# Scanner une image exportée en tarball
trufflehog docker --image file://chemin/vers/image.tar

TruffleHog analyse chaque layer de l’image, ce qui permet de trouver des secrets même s’ils ont été “supprimés” dans un layer ultérieur (une erreur classique dans les Dockerfiles).

Buckets S3

Pour scanner des buckets AWS S3, TruffleHog utilise les credentials AWS de votre environnement (variables d’environnement, fichier ~/.aws/credentials, ou rôle IAM).

# Scanner un bucket spécifique
trufflehog s3 --bucket=mon-bucket-data

# Scanner avec un rôle IAM (cross-account)
trufflehog s3 --bucket=bucket-autre-compte --role-arn=arn:aws:iam::123456789:role/TruffleHogRole

# Scanner tous les buckets accessibles via plusieurs rôles
trufflehog s3 --role-arn=arn:aws:iam::111:role/Role1 --role-arn=arn:aws:iam::222:role/Role2

Buckets Google Cloud Storage

Pour GCS, authentifiez-vous avec gcloud auth login ou un fichier de credentials :

# Scanner un projet GCS complet
trufflehog gcs --project-id=mon-projet-gcp --cloud-environment

# Afficher uniquement les secrets vérifiés
trufflehog gcs --project-id=mon-projet-gcp --results=verified

Jenkins

Jenkins stocke souvent des secrets dans les configurations de jobs :

trufflehog jenkins --url https://jenkins.example.com \
  --username admin \
  --password votre-api-token

Elasticsearch

Pour scanner les données dans Elasticsearch :

# Cluster local avec authentification basique
trufflehog elasticsearch --nodes 192.168.1.10 \
  --username elastic \
  --password changeme

# Elastic Cloud
trufflehog elasticsearch \
  --cloud-id 'mon-cluster:dXMtY2VudHJhbD...' \
  --api-key 'MlVtVjBZ...ZSYlduYnF1djh3NG5FQQ=='

HuggingFace

Depuis v3.88, TruffleHog peut scanner les modèles, datasets et spaces HuggingFace :

# Scanner un modèle spécifique
trufflehog huggingface --model meta-llama/Llama-2-7b

# Scanner une organisation complète
trufflehog huggingface --org huggingface

# Inclure les discussions et PRs
trufflehog huggingface --model mon-modele --include-discussions --include-prs

Fichiers locaux

Pour scanner des fichiers ou répertoires locaux (logs, exports, configs) :

# Scanner un répertoire
trufflehog filesystem /chemin/vers/dossier

# Scanner des fichiers spécifiques
trufflehog filesystem fichier1.log fichier2.env /etc/config/

# Désactiver la vérification (scan rapide)
trufflehog filesystem /var/log --no-verification

Entrée standard (stdin)

Utile pour les pipelines et l’analyse de données décompressées :

# Scanner un fichier S3 compressé à la volée
aws s3 cp s3://mon-bucket/logs.gz - | gunzip -c | trufflehog stdin

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

Sorties et formats

Format texte (par défaut)

Le format texte coloré est lisible pour les humains :

Found verified result 🐷🔑
Detector Type: AWS
Raw result: AKIAIOSFODNN7EXAMPLE
File: config.env
Line: 2

Format JSON

Pour l’intégration dans des outils ou scripts, utilisez --json :

trufflehog git <URL> --results=verified --json

Exemple de sortie JSON :

{
  "SourceMetadata": {
    "Data": {
      "Git": {
        "commit": "fbc14303ffbf8fb1c2c1914e8dda7d0121633aca",
        "file": "keys",
        "line": 4,
        "repository": "https://github.com/trufflesecurity/test_keys"
      }
    }
  },
  "DetectorType": 2,
  "DetectorName": "AWS",
  "Verified": true,
  "Raw": "AKIAYVP4CIPPERUVIFXG",
  "Redacted": "AKIAYVP4CIPPERUVIFXG",
  "ExtraData": {
    "account": "595918472158",
    "arn": "arn:aws:iam::595918472158:user/leaked-user"
  }
}

Format GitHub Actions

Pour une intégration native dans GitHub Actions avec annotations :

trufflehog git <URL> --github-actions

Intégration CI/CD

GitHub Actions

TruffleHog propose une action officielle qui scanne automatiquement les PRs et les pushes :

name: TruffleHog Secrets Scan

on:
  push:
    branches: [main]
  pull_request:

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

      - name: TruffleHog Scan
        uses: trufflesecurity/trufflehog@main
        with:
          extra_args: --results=verified,unknown

L’action scanne automatiquement les commits de la PR ou du push. Le flag fetch-depth: 0 est critique pour analyser l’historique complet.

Pour scanner uniquement les nouveaux commits (plus rapide) :

- name: TruffleHog OSS
  uses: trufflesecurity/trufflehog@main
  with:
    base: ${{ github.event.repository.default_branch }}
    head: HEAD
    extra_args: --results=verified,unknown --fail

GitLab CI

Intégrez TruffleHog dans vos merge requests GitLab :

stages:
  - security

trufflehog-scan:
  stage: security
  image: alpine:latest
  variables:
    SCAN_PATH: "."
  before_script:
    - apk add --no-cache git curl jq
    - curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin
  script:
    - trufflehog filesystem "$SCAN_PATH" --results=verified,unknown --fail --json | jq
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  allow_failure: false

L’option --fail retourne le code 183 si des secrets sont trouvés, ce qui fait échouer le pipeline.

Pre-commit hook

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

repos:
  - repo: local
    hooks:
      - id: trufflehog
        name: TruffleHog
        description: Detect secrets in your commits
        entry: bash -c 'trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail'
        language: system
        stages: ["commit", "push"]

Le pre-commit hook ne scanne que les nouveaux commits (--since-commit HEAD), ce qui le rend rapide.

Filtrage avancé et configuration

Exclure des fichiers ou chemins

Créez un fichier listant les patterns à ignorer :

# Fichiers de test
tests/
*_test.go
*.test.js

# Fixtures et mocks
fixtures/
**/mocks/**

# Documentation
docs/
*.md

Utilisez-le avec --exclude-paths :

trufflehog git <URL> --exclude-paths=exclusions.txt

Inclure uniquement certains fichiers

L’inverse est aussi possible avec --include-paths :

# Scanner uniquement les fichiers de config
*.env
*.yaml
*.yml
*.json
config/

trufflehog git <URL> --include-paths=inclusions.txt

Sélectionner des détecteurs spécifiques

Si vous cherchez un type de secret particulier :

# Chercher uniquement les clés AWS
trufflehog git <URL> --include-detectors=AWS

# Chercher AWS et GitHub
trufflehog git <URL> --include-detectors=AWS,GitHub

# Exclure les détecteurs de clés privées (beaucoup de faux positifs)
trufflehog git <URL> --exclude-detectors=PrivateKey

Ignorer des secrets spécifiques

Pour ignorer un secret connu (canary token, clé de test), ajoutez un commentaire trufflehog:ignore sur la même ligne :

# Cette clé est un canary token pour la détection d'intrusion
AWS_KEY = "AKIAIOSFODNN7EXAMPLE"  # trufflehog:ignore

Fichier de configuration

Pour les options utilisées fréquemment, créez un fichier de configuration :

# Configuration TruffleHog
detectors:
  include:
    - AWS
    - GitHub
    - Slack
    - Stripe
  exclude:
    - PrivateKey

options:
  results: verified,unknown
  fail: true
  concurrency: 8

trufflehog git <URL> --config=trufflehog.yaml

Détecteurs personnalisés

TruffleHog permet de définir vos propres détecteurs avec des regex et un endpoint de vérification.

detectors:
  - name: InternalAPIKey
    keywords:
      - "X-Internal-Key"
      - "internal_api"
    regex:
      secret: 'int_[a-zA-Z0-9]{32}'
    verify:
      endpoint: https://verify.internal.example.com/check
      unsafe: false
      headers:
        - 'Content-Type: application/json'

Utilisez-le avec :

trufflehog git <URL> --config=custom-detectors.yaml

L’endpoint de vérification reçoit un POST avec les groupes capturés et doit retourner 200 si le secret est valide.

Dépannage

Symptôme	Cause probable	Solution
Aucun résultat affiché	Pas de secret trouvé	Normal si le repo est propre
Scan très lent	Historique Git volumineux	Utiliser `--max-depth=100`
Erreur de rate limiting	API GitHub saturée	Ajouter `--token` avec un PAT
Faux positifs nombreux	Secrets de test, fixtures	Utiliser `--results=verified` ou `--exclude-paths`
`permission denied` sur Docker	Pas d’accès au socket Docker	Ajouter l’utilisateur au groupe `docker`
`unknown` pour tous les résultats	Réseau bloqué vers les APIs	Vérifier le proxy/firewall
Erreur `git clone timeout`	Repo très volumineux	Augmenter avec `--clone-timeout=30m`

Logs de débogage

Pour comprendre ce que fait TruffleHog :

# Niveau info (par défaut)
trufflehog git <URL> --log-level=0

# Niveau debug
trufflehog git <URL> --log-level=2

# Niveau trace (très verbeux)
trufflehog git <URL> --log-level=5

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, pas dans le code

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 TruffleHog 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 Gitleaks

TruffleHog et Gitleaks sont les deux outils open source les plus populaires pour la détection de secrets. Voici comment ils se comparent :

Critère	TruffleHog	Gitleaks
Vérification automatique	✅ Oui (800+ APIs)	❌ Non
Sources supportées	18 (Git, Docker, S3, Jenkins…)	2 (Git, filesystem)
Nombre de détecteurs	800+	150+
Analyse des permissions	✅ (commande `analyze`)	❌
Performance	Moyenne	Rapide
Configuration	YAML simple	TOML flexible
Langage	Go	Go

Recommandation : TruffleHog est préférable pour les audits de sécurité grâce à la vérification automatique. Gitleaks est plus rapide pour les scans pre-commit où les faux positifs sont gérés manuellement.

À retenir

Vérification automatique — TruffleHog teste si chaque secret fonctionne, éliminant les faux positifs
18 sources — Au-delà de Git : Docker, S3, Jenkins, Elasticsearch, HuggingFace…
800+ détecteurs — AWS, GitHub, Stripe, Slack, Postgres, et bien plus
Historique complet — Scanne tous les commits, toutes les branches
--results=verified — L’option la plus importante pour le triage
Pre-commit — Bloquez les secrets avant qu’ils ne soient commités
Rotation immédiate — Un secret exposé = un secret compromis

Prochaines étapes

Gitleaks Alternative plus rapide pour les pre-commit hooks

SOPS Chiffrer les fichiers de secrets dans Git

Passbolt Gestionnaire de mots de passe pour équipes DevOps

Pre-commit Framework de hooks Git multi-langages

Ressources

Documentation officielle : github.com/trufflesecurity/trufflehog
Liste des détecteurs : trufflesecurity.com/detectors
Action GitHub : marketplace/actions/trufflehog-oss