detect-secrets: Secret Scanning mit eingecheckter Baseline

detect-secrets ist Yelps Apache-2.0-Secret-Scanner für Git-Repositories, und die Idee, die ihn von allen anderen unterscheidet, ist die Baseline. Sie akzeptieren, dass ein Repository bereits Secrets enthalten kann, halten fest, was drin ist, und von da an blockiert das Tool nur noch neue. Das ist ein bewusst unspektakuläres Design und nach wie vor die richtige Form für eine Codebasis, für die niemand Zeit zum Aufräumen hat. Der Haken ist der Wartungszustand: 1.5.0 vom 6. Mai 2024 ist immer noch die neueste Version, der letzte Commit auf master stammt aus April 2026.

Er gehört an dieselbe Stelle wie gitleaks und TruffleHog, vor den Commit oder vor die Pipeline. Er ist kein Secret Manager: Er findet, er blockiert, und er übergibt eine Liste zum Rotieren. GitHubs eigenes Secret Scanning deckt nur bei GitHub gehostete Repositories ab und braucht für private Repositories GitHub Secret Protection; für GitLab, Bitbucket oder eine selbst gehostete Forge tut es nichts. Wo ein Scanner in die Geschichte rund um Sandbox-Pflichten für Agenten gehört, steht in Sandboxing von Coding-Agenten in der CI.

Was es ist

Das Paket bringt drei Kommandos mit, und das README ist ungewöhnlich klar darüber, welches wann gehört. detect-secrets scan erzeugt oder aktualisiert die Baseline, detect-secrets-hook prüft eine Dateiliste dagegen und endet mit einem Fehlercode, sobald etwas Neues auftaucht, und detect-secrets audit ist eine interaktive Sitzung, die Funde als echte Secrets oder Fehlalarme labelt und diese Labels zurück in die Baseline schreibt.

• Python, Apache-2.0, Version 1.5.0, veröffentlicht am 6. Mai 2024, mit 4.649 Sternen und 573 Forks. Der PyPI-Klassifizierer sagt production/stable, das beschreibt eher die API als die Roadmap.
• 27 Detektoren, die --list-all-plugins auflistet, in drei Familien: Regex-Regeln für AWS, GitHub, GitLab, Slack, Stripe, OpenAI, npm, PyPI, Telegram, Twilio und private Schlüssel; Entropie-Detektoren für Base64- und Hex-Strings; und ein Keyword-Detektor, der den Wert ignoriert und Zuweisungen an Namen wie password markiert.
• Filter laufen nach den Plugins und entscheiden, was übrig bleibt: --exclude-files, --exclude-lines, --exclude-secrets, eine Wortliste eigener Bezeichner und Inline-Pragmas.
• Verifikation ist standardmäßig an. Für erkannte Muster fragt das Tool den ausstellenden Dienst, ob das Credential echt ist. -n (--no-verify) schaltet das ab, --only-verified behält nur die bestätigten.
• Die Baseline ist der gesamte Zustand. Sie ist eine JSON-Datei im Repository mit der Plugin- und Filterkonfiguration plus einem gehashten Fingerabdruck für jeden Fund.
• Audit ist die Messung. Die Labels lassen detect-secrets audit --stats melden, wie gut jeder Detektor auf Ihrem Code funktioniert, und das ist der einzige ehrliche Weg zum Tunen.
• Drei Einsatzformen: Pre-Commit-Hook, CI-Job über gestagte oder versionierte Dateien, oder als Bibliothek über SecretsCollection, wenn es in Ihre eigene Werkzeugkette soll.

Wie es funktioniert

Die Engine hat zwei Stufen. Plugins liefern potenzielle Secrets, dann entscheiden Filter und die Verifikationsregelung, was tatsächlich gemeldet wird. Transformer normalisieren die Eingabe zuerst, weshalb sich INI-, YAML-, XML- und Markdown-Dateien zeilenweise ohne Sonderfälle pro Format prüfen lassen. Ein serialisierbares Settings-Objekt verbindet beide Hälften und steckt in der Baseline, sodass ein Scan auf einem CI-Runner exakt die Konfiguration verwendet, die die Datei auf einem Laptop erzeugt hat.

Die Verifikation ist der Mechanismus, der entscheidet, ob das Tool praktisch taugt. Seit 0.12.4 kann ein Plugin eine verify-Funktion implementieren, die den ausstellenden Dienst fragt, ob das Credential noch lebt, und dabei die Techniken aus dem keyhacks-Projekt nutzt. Die Verifikation bekommt zusätzlich fünf Zeilen Kontext vor und nach dem Treffer, weil die Forschung hinter dieser Entscheidung eine 80-prozentige Chance gefunden hat, die zweite Hälfte eines Multi-Faktor-Secrets in der Nähe zu finden. Der Zugewinn an Präzision ist groß; der Preis ist eine ausgehende Netzwerkanfrage bei jedem Commit, der eine passende Zeile berührt.

Die Baseline übernimmt dann das Trennen der Belange. detect-secrets scan --baseline .secrets.baseline scannt den Baum neu, migriert die Datei in das aktuelle Format, fügt neue Funde hinzu, entfernt verschwundene und erhält die Audit-Labels, sodass der Diff klein genug zum Review bleibt. Das Flag --slim geht weiter und minimiert den Diff zwischen Commits, kostet aber die Audit-Funktion: schlanke Baselines lassen sich später nicht mehr auditieren und müssen neu erzeugt werden.

Erste Schritte

Die Installation ist pip install detect-secrets oder brew install detect-secrets. Version 1.5.0 unterstützt Python 3.8 bis 3.12 und hat 3.6 und 3.7 fallengelassen; master enthält bereits Python-3.13-Unterstützung, die aber in keinem Release steht, eine 3.13-Umgebung muss also aus Git installieren. Die dokumentierte Einrichtung ist ein Pre-Commit-Hook mit der Baseline als Argument.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']
        exclude: package.lock.json

Danach erzeugen Sie die Baseline einmal im Repository-Root und checken sie ein. Von diesem Moment an läuft der Hook bei jedem Commit und schlägt nur bei Zeilen fehl, die nicht in der Datei stehen. Der erste Scan eines alten Repositorys kann Tausende Funde liefern, und genau dafür gibt es die Baseline.

pip install detect-secrets

# once, from the repository root: record what is already there
detect-secrets scan > .secrets.baseline

# after real leaks are rotated, or the repo legitimately grew
detect-secrets scan --baseline .secrets.baseline

# label findings once, then keep the labels
detect-secrets audit .secrets.baseline

# CI: fail the build on anything the baseline does not list
git diff --staged --name-only -z | xargs -0 \
  detect-secrets-hook --baseline .secrets.baseline

Inline-Allowlisting ist die zweite Hälfte des Ablaufs. Eine Zeile mit # pragma: allowlist secret am Ende oder eine Zeile darüber mit // pragma: allowlist nextline secret wird übersprungen, ohne die Baseline anzufassen, und das ist das richtige Werkzeug für Testfixtures oder Doku-Beispiele. detect-secrets scan --only-allowlisted dreht die Prüfung um und meldet genau diese Zeilen, damit das Pragma nicht unauffällig zum Ort für echte Zugangsdaten wird.

Signal und Rauschen

Von Haus aus sind die Detektoren auf ein generisches Repository abgestimmt, und die Arbeit danach ist das Tunen auf Ihres. Der Audit-Schritt ist keine Formalität: Er ist die einzige verfügbare Messung, und er ist manuell.

1. Baseline erzeugen, dann eine repräsentative Stichprobe mit detect-secrets audit labeln. Ohne das funktioniert nichts weiter auf dieser Liste.
2. Die Statistik lesen. Detektoren, die überwiegend Fehlalarme liefern, werden mit --disable-plugin abgeschaltet oder mit --exclude-files und --exclude-lines eingegrenzt.
3. Schieben Sie statt Detektoren zu löschen die Entropie-Schwellen: --base64-limit steht standardmäßig auf 4.5, --hex-limit auf 3.0, und das sind die beiden Stellschrauben, die das Tool anbietet.
4. Ergänzen Sie eine Wortliste eigener Bezeichner über --word-list; dafür braucht es das Extra detect-secrets[word_list].
5. Erwägen Sie das optionale Gibberish-Modell für Secrets, die wie Wörter aussehen. Es ist nicht standardmäßig aktiv, weil es Werte wie password ebenfalls übergeht.
6. Nach jeder Änderung mit --baseline neu scannen und den Diff der Baseline-Datei lesen. Ein kleinerer Diff bedeutet weniger Rauschen, nicht weniger Secrets.

Der Rotations-Workflow

Das dritte Kommando bezahlt das Tunen, und es findet nichts Neues. Audit-Labels schreiben is_secret in die Baseline; zusammen mit --report entsteht daraus die Liste der Credentials, die noch im Repository liegen und ersetzt werden müssen. Diese Liste macht aus einem Scan eine Sicherheitsaufgabe mit Verantwortlichem und Frist.

• Erst labeln, dann berichten. Ein als echtes Secret markierter Fund in der Baseline ist ein Eintrag auf der Migrationsliste.
• Beim Anbieter rotieren, nicht im Repository. Eine gelöschte Datei ändert nichts daran, ob der Schlüssel funktioniert.
• Danach mit --baseline neu scannen. Der Fund verschwindet aus der Datei, und dieser Diff ist der Beleg, dass die Migration fertig ist.
• Das Scannen der Historie getrennt halten. Das Werkzeug schaut nie in alte Commits; ein Rewrite oder ein einmaliger History-Scan ist eine andere Aufgabe.

Das ist die Trennung der Belange, die das README beschreibt, und immer noch das stärkste Argument für das Tool. Es verlangt nicht, dass Sie das Repository erst aufräumen, bevor es nützlich wird, und genau das verlangen Scanner, die man nachträglich auf eine gewachsene Codebasis setzt.

Wo es schlecht sitzt

Die Schwächen sind strukturell, nicht kosmetisch. Mehrzeilige Secrets findet es nicht, und ein Standardpasswort, das der Keyword-Detektor nicht kennt, auch nicht; das README sagt das in einem Abschnitt namens Caveats ausdrücklich. Die Git-Historie scannt es absichtlich nicht, ein vor Jahren committetes und wieder gelöschtes Credential ist für es unsichtbar. Eigene Plugins werden durch Importieren einer beliebigen Datei geladen, was die Plugin-Dokumentation selbst als Sicherheitsannahme kennzeichnet. Und das Projekt steht im Wartungsmodus: 1.5.0 vom Mai 2024 ist weiterhin der neueste Tag, die Python-3.13-Unterstützung liegt seit Januar 2025 auf master, und der Issue-Tracker zeigt 184 offene Tickets.

Der entscheidende Vergleich ist, wohin die Arbeit geht. gitleaks ist eine einzige Go-Binary mit einem ausgezeichneten TOML-Regelformat, schneller einzuführen, und der Autor schreibt inzwischen offen, dass das Projekt feature complete sei, nur noch Sicherheitspatches bekomme und die neue Arbeit in ein anderes Projekt gewandert sei. TruffleHog geht den anderen Weg: Es verifiziert Credentials gegen laufende APIs, was der einzige Weg ist, um sicher zu sein, dass ein Fund dringend ist, und das zahlt es mit rund 800 Credential-Typen und einer AGPL-3.0-Lizenz, die manche Rechtsabteilungen nicht unterschreiben. detect-secrets tauscht Breite gegen den einen Ablauf, den die anderen nicht haben: eine auditierte, eingecheckte Liste dessen, was bereits bekannt ist, und einen Weg von dort weg.

Fazit

Nimm es, aber als Infrastruktur und nicht als Projekt. Das Baseline-Modell ist die richtige Antwort für ein Repository mit jahrelanger Historie ohne Budget für eine Aufräumaktion, und es liefert das Artefakt, das eine Sicherheitsprüfung wirklich verlangt: eine Liste zum Rotieren. Es ist nicht das Werkzeug für ein neues Repository, wo gitleaks einfacher ist, und nicht für ein Team, das wissen muss, ob ein geleakter Schlüssel noch funktioniert, denn dafür ist TruffleHog zuständig.

1. Wählen, wenn das Repository bereits Secrets enthält, die Historie nicht umgeschrieben werden kann und das Ziel ist, die Blutung zu stoppen statt ein Migrationsprojekt zu starten.
2. Die Baseline im Repository behalten und ihren Diff ins Review ziehen. Eine Baseline, die sich in einem unerklärten Commit ändert, ist der Fehlermodus, auf den man achten muss.
3. Einen Tag für das Tuning einplanen. Das Tool ist genau so gut wie seine gelabelte Baseline, und das Labeln ist Handarbeit.
4. Mit serverseitigem Scannen kombinieren, nicht es ersetzen. detect-secrets blockiert auf der Maschine eines Entwicklers; etwas muss trotzdem scannen, was bereits gelandet ist.
5. Keine neue Automatisierung darauf aufbauen, dass die Detektoren noch wachsen. 1.5.0 pinnen, master lesen, wenn Python 3.13 nötig ist, und einen Nachfolger einplanen, falls das Projekt still bleibt.

Quellen

1. Yelp/detect-secrets: README and usage
2. Yelp/detect-secrets: CHANGELOG (v1.5.0, 6 May 2024)
3. Yelp/detect-secrets: plugin and verification documentation
4. detect-secrets 1.5.0 on PyPI
5. Yelp/detect-secrets: releases
6. Gitleaks README (MIT, Go)
7. TruffleHog README (AGPL-3.0, credential verification)
8. GitHub Docs: About secret scanning
9. betterleaks/betterleaks