Secret Scanning in Repositories: Gitleaks vs TruffleHog

Gitleaks ist ein Open-Source-Tool zur Erkennung von Secrets in Git-Repositories und Dateisystemen. Es identifiziert unter anderem API-Schlüssel, Passwörter, Access Tokens, Zertifikate und Private Keys anhand vordefinierter oder benutzerdefinierter Regeln.

Gitleaks kann lokal als Pre-Commit Hook, in CI/CD-Pipelines oder als einmaliger Scan der gesamten Git-Historie eingesetzt werden. Dadurch lassen sich Secrets bereits vor dem Commit, vor einem Merge oder innerhalb bestehender Repository-Historien erkennen.

Ein vollständiger historischer Scan sollte nur initial oder bewusst via CI Task ausgeführt werden, da dieser längere Zeit dauern kann. Reguläre Pipelines sollen nicht bei jedem Commit die gesamte Repository-Historie erneut prüfen.

Warum Gitleaks?

Gitleaks bietet Entwicklern und Sicherheitsteams ein schnelles, zuverlässiges und intuitives Werkzeug:

Performance: Optimiert für Geschwindigkeit, sodass auch große Repositories ohne Verzögerung geprüft werden können.
Flexibilität: Unterstützt Multi-Repo-Scans, lokale Dateien sowie Stdin-Eingaben für verschiedenste Umgebungen.
CI/CD Integration: Nahtlose Einbindung in Pipelines zur kontinuierlichen Überwachung während Build, Test oder Deployment.
Detailliertes Reporting: Generiert strukturierte Berichte im JSON-, CSV- oder SARIF-Format (ideal zur Weiterverarbeitung und Auditierung).
Open Source: Eine sehr aktive Community treibt die stetige Verbesserung und Aktualität der Regeln voran.

Gitleaks vs. TruffleHog

Bei der Wahl eines Secret-Scanning-Tools sind Gitleaks und TruffleHog die beiden prominentesten Open-Source-Optionen. Beide sind hochgradig effektiv, verfolgen jedoch leicht unterschiedliche Philosophien.

Feature	Gitleaks	TruffleHog
Fokus	Statische Regex- und Entropie-Analyse. Schnell und ressourcenschonend.	Aktive Secret-Verifizierung (macht externe API-Aufrufe, um zu prüfen, ob ein Secret gültig ist).
Performance	Extrem schnell, ideal für strikte CI/CD-Pipelines und Pre-Commit-Hooks.	Langsamer wegen der Verifizierung, liefert aber extrem belastbare Ergebnisse (weniger False-Positives).
Anpassbarkeit	Hochgradig anpassbar via TOML-Dateien für interne Unternehmensmuster.	Fokus auf hunderte eingebaute Detektoren; Custom-Regexes werden unterstützt, sind aber zweitrangig.

Empfehlung: Nutze Gitleaks für schnelle, frühe Prävention in Pre-Commit-Hooks und MR-Pipelines, wo Geschwindigkeit kritisch ist. Nutze TruffleHog für geplante, tiefe historische Scans, bei denen die tatsächliche Verifizierung eines Secrets wichtiger ist als die Ausführungszeit.

Potentielles Zielbild

Der Pre-Commit Hook ist eine Präventionsmaßnahme. Die GitLab-Pipeline ist die verbindliche zentrale Komponente, da lokale Hooks mit --no-verify übersprungen werden können.

Full-Repository-Scan

Vor Aktivierung der regulären MR-Prüfung wird einmalig die gesamte erreichbare Git-Historie untersucht.

Dadurch werden auch Secrets erkannt, die:

vor Einführung von Gitleaks committed wurden,
später aus Dateien entfernt wurden,
nur in älteren Commits vorkommen,
auf einem anderen Branch vorhanden sind.

Hierfür muss vollständige Git-Historie verfügbar sein.

gitleaks dir . \
  --log-opts="--all" \
  --report-format json \
  --report-path gitleaks-full-report.json

Für einen initialen Analysejob ist es sinnvoll allow_failure: true zu setzten da bestehende Findings erwartet werden.

Merge-Request-Scan

Bei einer Merge-Request-Pipeline sollten alle Commits geprüft werden, die seit der Abzweigung vom Zielbranch erstellt wurden. Hierzu wird der Commit-Bereich CI_MERGE_REQUEST_DIFF_BASE_SHA..CI_COMMIT_SHA verwendet.

Dadurch analysiert Gitleaks den vollständigen Commit-Verlauf des Merge Requests – vom gemeinsamen Ausgangspunkt mit dem Zielbranch bis zum aktuellen Commit. So werden nicht nur Secrets im letzten Commit erkannt, sondern auch solche, die in früheren Commits des Merge Requests eingeführt und in späteren Commits wieder entfernt wurden.

main:       A──B──C
                  \
feature:           D──E──F

Der Scan umfasst den gesamten Commit-Bereich des Merge Requests:

D──E──F

Dadurch wird beispielsweise auch ein Secret erkannt, das in Commit D hinzugefügt und in Commit F wieder entfernt wurde. Ein reiner Scan des aktuellen Dateistands würde ein solches Secret hingegen nicht mehr erkennen.

Variable	Bedeutung
`CI_MERGE_REQUEST_DIFF_BASE_SHA`	Gemeinsame Ausgangsbasis des Merge Requests
`CI_COMMIT_SHA`	Aktueller Commit der Pipeline

Pre-Commit Hook

Der Gitleaks Pre-Commit Hook verhindert, dass Secrets bereits beim lokalen Commit in das Repository gelangen. Er prüft die für den Commit vorgesehenen Änderungen und bricht den Commit bei einem gefundenen Secret ab.

Der Hook muss einmalig eingerichtet werden, ein Beispiel liegt unter pre-commit (./githooks/pre-commit). Der Pre-Commit Hook muss bei jedem einmal installiert werden via:

chmod +x ./githooks/pre-commit
git config core.hooksPath .githooks

Da mit dem Pre-Commit Script Gitleaks ausgeführt wird, muss hierfür auch Gitleaks lokal installiert sein. Dies geht via Brew: brew install gitleaks.

Nachdem der Hook installiert wurde, werden Commits mit Secrets verhindert und geben eine Fehlermeldung aus.

Eigenschaften

Führt den Scan vor jedem lokalen Commit aus.
Prüft die für den Commit vorgesehenen Änderungen.
Verhindert Commits mit erkannten Secrets.
⚠️ Wird nicht automatisch nach einem git clone installiert.
⚠️ Prüft keine historischen Commits.
Kann lokal umgangen werden.

Da lokale Hooks jederzeit umgangen oder deaktiviert werden können, ersetzt der Pre-Commit Hook nicht die zentrale Prüfung in der GitLab-CI. Die Pipeline bleibt die verbindliche Sicherheitsinstanz vor dem Merge in den Zielbranch.

Baseline vs. `.gitleaks.toml`

Die Datei .gitleaks.toml steuert die Erkennungslogik von Gitleaks und legt fest, welche Muster als Secrets erkannt werden. Sie ermöglicht die Definition eigener Secret-Regeln, Regex-Ausdrücke, Keywords, Entropy-Grenzwerte und Allowlists. Darüber hinaus können die Standardregeln von Gitleaks über extend erweitert oder angepasst werden.

Die Baseline (.gitleaks-baseline.json) enthält keine Erkennungsregeln und beeinflusst daher nicht, welche Secrets Gitleaks findet. Stattdessen speichert sie bereits bekannte und bewertete Findings, sodass diese bei zukünftigen Scans unterdrückt werden. Dadurch können sich Entwickler auf neu hinzugekommene Secrets konzentrieren, ohne dass bereits akzeptierte historische Findings die Ergebnisse erneut beeinflussen. Die Baseline verändert nicht, welche Secrets erkannt werden.

Eigenschaft	`.gitleaks.toml`	Baseline (`.gitleaks-baseline.json`)
Zweck	Definiert, was als Secret erkannt wird	Definiert, welche bekannten Findings ignoriert werden
Inhalt	Regeln, Regex, Keywords, Entropie, Allowlists	Bereits erkannte und bewertete Findings
Wird bei jedem Scan verwendet	✅ Ja	Optional
Beeinflusst die Erkennung	✅ Ja	❌ Nein
Unterdrückt bekannte Findings	❌ Nein	✅ Ja
Eigene Regeln möglich	✅ Ja	❌ Nein
Typischer Einsatzzweck	Organisationsspezifische Secret-Muster definieren	Historische Altlasten ausblenden

Zusammenspiel

                 .gitleaks.toml
                        │
                        │
          Welche Muster sind Secrets?
                        │
                        ▼
                 Gitleaks Scan
                        │
                        ▼
                Gefundene Findings
                        │
                        ▼
      .gitleaks-baseline.json
                        │
                        │
 Welche bekannten Findings werden ignoriert?
                        │
                        ▼
              Finales Scan-Ergebnis

Fazit

Der Schutz von Secrets ist ein kritischer Bestandteil in der Softwareentwicklung. Mit Gitleaks steht ein leistungsstarkes Open-Source-Tool zur Verfügung, um durch automatisierte Scans und maßgeschneiderte Erkennungsregeln sowohl präventiv (via Pre-Commit Hook) als auch kontinuierlich (via CI/CD Pipeline) Codebases abzusichern. Durch die Trennung von globalen Erkennungsregeln (.gitleaks.toml) und der Unterdrückung historischer Altlasten (Baseline) ermöglicht es eine effiziente Fehlerbehebung ohne Entwicklungs-Workflows zu blockieren.

Best Practices

`.gitleaks.toml`

Standardregeln über extend erweitern.
Organisationsspezifische Secret-Muster ergänzen.
Änderungen per Merge Request und Code Review freigeben.
Nach jeder Regeländerung einen vollständigen Repository-Scan durchführen.

Baseline

Nur nach einem vollständigen Repository-Scan erstellen.
Ausschließlich bewertete historische Findings aufnehmen.
Niemals automatisch aktualisieren.
Änderungen ausschließlich über einen Merge Request durchführen.
Behobene Findings regelmäßig aus der Baseline entfernen.

Beispiel:

gitleaks dir . \
  --report-format json \
  --report-path gitleaks-full-report.json \
  --baseline-path ./.gitlab/test-baseline.json \
  --config ./.gitlab/secret-detection-ruleset.toml