> Was detect-secrets tut, wie sich seine eingecheckte Baseline von gitleaks und TruffleHog unterscheidet, warum Verifikationsaufrufe in der CI zählen und wo das Tool aufhört. > > Web page: https://balazscsorba.com/de/blog/detect-secrets · Language: Deutsch · Also available in: [English](https://balazscsorba.com/blog/detect-secrets.md) · [Magyar](https://balazscsorba.com/hu/blog/detect-secrets.md) > Author: Balázs Csorba · Published: 2026-08-03 · Keywords: detect-secrets, detect-secrets vs gitleaks, detect-secrets baseline, secret scanning tools comparison, gitleaks vs trufflehog, rotate leaked api keys, pre-commit secret hook [Blog](https://balazscsorba.com/de/blog)/Sicherheit & Compliance # detect-secrets: Secret Scanning mit eingecheckter Baseline Was detect-secrets tut, wie sich seine eingecheckte Baseline von gitleaks und TruffleHog unterscheidet, warum Verifikationsaufrufe in der CI zählen und wo das Tool aufhört. [Balázs Csorba](https://balazscsorba.com/de/about)·3\. August 2026·10 Min. Lesezeit - Secret scanning - Pre-commit - Git - DevSecOps ![Ein breites Blatt mit fünf kleinen Quadraten, darüber eine Lupe, darunter eine gekreuzte Linie.](https://balazscsorba.com/images/blog/detect-secrets/cover.webp?v=bd656d8345) ## Das Wichtigste in Kürze - detect-secrets akzeptiert, dass ein Repository bereits Secrets enthalten kann. Eine eingecheckte .secrets.baseline hält die Funde fest, und der Hook blockiert nur neue. Die Einführung braucht also kein Aufräumprojekt voraus. - Die Präzision kommt aus Labels, nicht aus besseren Regexen: detect-secrets audit mit --stats ist die Messung, und --exclude-files, --exclude-lines, --word-list sowie die beiden Entropie-Schwellen sind die Stellschrauben. - Die Verifikation ist standardmäßig an und ruft den ausstellenden Dienst über das Netz. Das senkt Fehlalarme stark und verlangt in einer abgeschotteten CI eine bewusste Entscheidung. - Version 1.5.0 vom 6. Mai 2024 ist weiterhin die neueste Veröffentlichung, die Python-3.13-Unterstützung liegt unveröffentlicht auf master. Version pinnen und keine neue Automatisierung auf neue Detektoren planen. - gitleaks ist die einfachere Wahl für ein neues Repository, TruffleHog bestätigt, ob ein Schlüssel noch lebt. detect-secrets hat den Audit- und Rotationsablauf, den die anderen beiden nicht bieten. Auf dieser Seite 1. [Was es ist](https://balazscsorba.com/#what-it-is) 2. [Wie es funktioniert](https://balazscsorba.com/#how-it-works) 3. [Erste Schritte](https://balazscsorba.com/#getting-started) 4. [Signal und Rauschen](https://balazscsorba.com/#signal-vs-noise) 5. [Der Rotations-Workflow](https://balazscsorba.com/#rotation-workflow) 6. [Wo es schlecht sitzt](https://balazscsorba.com/#where-it-shingles) 7. [Fazit](https://balazscsorba.com/#verdict) 8. [Quellen](https://balazscsorba.com/#sources) Diesen Artikel anhören 0:000:00 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](https://balazscsorba.com/de/blog/sandboxing-coding-agents-ci-checklist). ## 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. ![detect-secrets: einmal scannen, bei jedem Commit prüfen Versionierte Git-Dateien laufen durch Transformer, Plugins und Filter, die Verifikation ruft bei passenden Plugins einen Dienst auf, und das Ergebnis landet in einer eingecheckten JSON-Baseline. Pre-Commit-Hook und Audit-Sitzung lesen nur diese Baseline.](https://balazscsorba.com/images/blog/detect-secrets/diagram-7.webp?v=ea48ecd3d7) Ein Scan erzeugt die Baseline; Hook und Audit-Sitzung lesen sie nur. 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. **Zwei Dinge vorher klären** Die Verifikation sendet bei jeder Maschine, die den Hook ausführt, Anfragen an fremde APIs. In einem abgeschotteten CI-Netz verlangsamt das entweder den Scan oder lässt ihn scheitern, also entscheiden Sie bewusst zwischen `-n` in der CI und einer Proxy-Allowlist für die Dienste, gegen die verifiziert wird. `detect-secrets audit --report` kann die Secret-Werte selbst ausgeben. Führen Sie das Audit auf einem Laptop aus und pastieren Sie die Ausgabe niemals in ein Ticket, einen Chat oder ein CI-Log. Die Baseline speichert ausschließlich Hashes. ## 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. **Das Gate in zwei Schritten ausrollen** Den Hook zunächst einen Sprint lang nur melden lassen und Funde pro Tausend geänderter Zeilen zählen. Erst dann blockierend schalten. Ein Gate, das zu oft anschlägt, wird mit `-n`, einem `SKIP`\-Präfix oder einem Force-Push umgangen, und ein umgangenes Gate ist schlimmer als keines, weil das Team sich abgedeckt fühlt. ## 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. Merkmal detect-secrets gitleaks TruffleHog Lizenz Apache-2.0 MIT AGPL-3.0 Sprache Python Go Go Erkennungsmodell 27 Detektoren: Regex, Entropie, Schlüsselwortnamen TOML-Regelsatz, Regex plus Entropie, pro Regel erweiterbar Über 800 klassifizierte Credential-Typen Verifikation Ja, ein Netzwerkaufruf je erkanntem Muster Nein Ja, es meldet sich an, um zu prüfen, ob das Credential lebt Was es liest Versionierte Git-Dateien im Arbeitsbaum, dazu die Bibliotheks-API Git-Patches über git log -p, Verzeichnisse, stdin Git, GitHub, GitLab, S3, GCS, Docker, Jenkins, Elasticsearch und mehr Bekannter Stand Akzeptierte Funde: eine eingecheckte, auditierte Baseline Funde aus einer Reportdatei als Baseline-Pfad Ergebnisfilter, kein Baseline-Konzept 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. **Eine Faustregel** Wenn im Team niemand bereit ist, die in der Baseline gelisteten Schlüssel zu rotieren, bringt detect-secrets nichts. Es senkt die Zahl künftiger Vorfälle, nicht die der bereits im Repository liegenden. ## Quellen 1. [Yelp/detect-secrets: README and usage](https://github.com/Yelp/detect-secrets) 2. [Yelp/detect-secrets: CHANGELOG (v1.5.0, 6 May 2024)](https://github.com/Yelp/detect-secrets/blob/master/CHANGELOG.md) 3. [Yelp/detect-secrets: plugin and verification documentation](https://github.com/Yelp/detect-secrets/blob/master/docs/plugins.md) 4. [detect-secrets 1.5.0 on PyPI](https://pypi.org/project/detect-secrets/) 5. [Yelp/detect-secrets: releases](https://github.com/Yelp/detect-secrets/releases) 6. [Gitleaks README (MIT, Go)](https://github.com/gitleaks/gitleaks) 7. [TruffleHog README (AGPL-3.0, credential verification)](https://github.com/trufflesecurity/trufflehog) 8. [GitHub Docs: About secret scanning](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning) 9. [betterleaks/betterleaks](https://github.com/betterleaks/betterleaks) ## Häufige Fragen Was ist eine .secrets.baseline und warum wird sie eingecheckt? Eine JSON-Datei, die alle aktuell gefundenen Secrets zusammen mit der Plugin- und Filterkonfiguration und einem Hash je Fund listet. Eingecheckt gibt sie dem Pre-Commit-Hook eine stabile Referenz: bereits gelistete Funde werden ignoriert, alles Neue bricht den Commit ab. Zugleich ist sie die Migrations-Checkliste, weil detect-secrets audit labelt, welche Einträge echte Secrets sind. Findet detect-secrets Secrets in der Git-Historie? Nein, und das ist Absicht: Das Werkzeug scannt die versionierten Dateien im Arbeitsbaum, ein vor Jahren committetes und wieder entferntes Credential sieht es also nicht. Das README begründet das mit den Kosten, die das Durchlaufen der Historie bei jedem Lauf verursachen würde. Für die Historie braucht es einen gesonderten einmaligen Scan mit gitleaks oder TruffleHog und danach ein Rewrite, falls das Credential je gültig war. Was machen --only-verified und --no-verify? Standardmäßig versucht das Tool jeden Fund zu verifizieren, indem es den Dienst anfragt, der das Credential ausgestellt hat, und dabei die Techniken aus dem keyhacks-Projekt nutzt. --only-verified meldet nur die bestätigten Credentials, das ist präzise, braucht aber ausgehende Netzverbindungen; -n (--no-verify) schaltet die Verifikation ganz ab, was ein abgeschotteter CI-Runner braucht. Wird detect-secrets noch gepflegt? Stabil, aber ruhig: 1.5.0 vom 6. Mai 2024 ist zugleich die neueste Veröffentlichung auf PyPI und der neueste GitHub-Tag. Commits kommen weiterhin in geringem Tempo, der letzte auf master ist vom April 2026, und die Python-3.13-Unterstützung wurde im Januar 2025 ohne Release gemergt. Behandeln Sie es als gepflegt statt entwickelt, pinnen Sie v1.5.0 und lesen Sie master, wenn Sie das neuere Python brauchen. Geschrieben von Balázs Csorba Senior Fullstack & AI Engineer in der Steiermark – über 10 Jahre Vue, Nuxt, Node.js und PHP, heute baue ich Werkzeuge für KI-Agenten. [KI-Entwicklung & MCP-Server →](https://balazscsorba.com/de/expertise/ai-engineer)[Über mich →](https://balazscsorba.com/de/about) ## Weitere Artikel - [Output-Guardrails für LLMs: Moderation, sicheres Rendern und Validierung, bevor etwas passiert](https://balazscsorba.com/de/blog/llm-output-guardrails-moderation) - [AI-Red-Teaming-Checkliste für LLM-Apps: was man angreifen sollte, bevor es Nutzer tun](https://balazscsorba.com/de/blog/ai-red-teaming-checklist-llm-apps) - [Slopsquatting: wenn Coding-Agenten Pakete installieren, die es nicht gibt](https://balazscsorba.com/de/blog/slopsquatting-ai-package-hallucinations) - [RAG-Poisoning: wie wenige Dokumente einen Assistenten steuern und wie man die Wissensbasis verteidigt](https://balazscsorba.com/de/blog/rag-poisoning-knowledge-base-attacks) ## Klingt nach dem, was du suchst? Erzähl mir von deinem Projekt oder deiner Stelle – ich freue mich, von dir zu hören. [Kontakt aufnehmen](mailto:contact@balazscsorba.com) [Auf LinkedIn vernetzen](https://www.linkedin.com/in/balazs-csorba)