
Eine unternehmensfreundliche Methode zur Erkennung und Verhinderung von Geheimnissen im Code.
detect-secrets ist ein treffend benanntes Modul zur (Überraschung, Überraschung) Erkennung von Geheimnissen in einer Codebasis.
Im Gegensatz zu anderen ähnlichen Paketen, die sich ausschließlich auf das Auffinden von Geheimnissen konzentrieren, ist dieses Paket mit dem Unternehmenskunden im Hinterkopf entwickelt: Es bietet eine , systematische Möglichkeit:
Auf diese Weise schaffen Sie eine Trennung der Belange: Sie akzeptieren, dass es derzeit Geheimnisse geben mag, die sich in Ihrem großen Repository verstecken (dies bezeichnen wir als eine Baseline), verhindern aber, dass dieses Problem noch größer wird, ohne sich mit der potenziell gigantischen Mühe befassen zu müssen, bestehende Geheimnisse zu entfernen.
Dies geschieht durch periodische Ausführung von Diff-Ausgaben gegen heuristisch erstellte Regex-Anweisungen, um festzustellen, ob ein neues Geheimnis committet wurde. Auf diese Weise vermeidet es den Overhead des Durchwühlens der gesamten Git-Historie sowie die Notwendigkeit, jedes Mal das gesamte Repository zu scannen.
Einen Überblick über die letzten Änderungen finden Sie in CHANGELOG.md.
Wenn Sie einen Beitrag leisten möchten, lesen Sie bitte CONTRIBUTING.md.
Für eine detailliertere Dokumentation sehen Sie sich unsere weitere Dokumentation an.
Erstellen Sie eine Baseline potenzieller Geheimnisse, die derzeit in Ihrem Git-Repository gefunden werden.```bash $ detect-secrets scan > .secrets.baseline
oder, um es von einem anderen Verzeichnis aus auszuführen:```bash
$ detect-secrets -C /path/to/directory scan > /path/to/directory/.secrets.baseline
Scannen von nicht von Git verfolgten Dateien:```bash $ detect-secrets scan test_data/ --all-files > .secrets.baseline
### Hinzufügen neuer Geheimnisse zur Baseline:
Dies wird Ihre Codebasis erneut scannen und:
1. Aktualisieren/Upgraden Sie Ihre Baseline, um mit der neuesten Version kompatibel zu sein,
2. Fügen Sie alle neuen Geheimnisse, die es findet, zu Ihrer Baseline hinzu,
3. Entfernen Sie alle Geheimnisse, die nicht mehr in Ihrer Codebasis vorhanden sind
Dies wird auch alle von Ihnen markierten Geheimnisse bewahren.```bash
$ detect-secrets scan --baseline .secrets.baseline
Für Baselines älter als Version 0.9 einfach neu erstellen.
Nur gestaffelte Dateien scannen:```bash $ git diff --staged --name-only -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline
**Scannen aller verfolgten Dateien:**```bash
$ git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline
$ detect-secrets scan --list-all-plugins ArtifactoryDetector AWSKeyDetector AzureStorageKeyDetector BasicAuthDetector CloudantDetector DiscordBotTokenDetector GitHubTokenDetector GitLabTokenDetector Base64HighEntropyString HexHighEntropyString IbmCloudIamDetector IbmCosHmacDetector IPPublicDetector JwtTokenDetector KeywordDetector MailchimpDetector NpmDetector OpenAIDetector PrivateKeyDetector PypiTokenDetector SendGridDetector SlackDetector SoftlayerDetector SquareOAuthDetector StripeDetector TelegramBotTokenDetector TwilioKeyDetector
### Deaktivieren von Plugins:```bash
$ detect-secrets scan --disable-plugin KeywordDetector --disable-plugin AWSKeyDetector
Wenn Sie nur ein bestimmtes Plugin ausführen möchten, können Sie Folgendes tun:```bash
$ detect-secrets scan --list-all-plugins |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs detect-secrets scan test_data
### Überprüfung einer Baseline:
Dies ist ein optionaler Schritt, um die Ergebnisse in Ihrer Baseline zu kennzeichnen. Es kann verwendet werden, um Ihre Liste der zu migrierenden Geheimnisse einzugrenzen oder Ihre Plugins besser zu konfigurieren, um das Signal-Rausch-Verhältnis zu verbessern.```bash
$ detect-secrets audit .secrets.baseline
Grundlegende Verwendung:```python from detect_secrets import SecretsCollection from detect_secrets.settings import default_settings
secrets = SecretsCollection() with default_settings(): secrets.scan_file('test_data/config.ini')
import json print(json.dumps(secrets.json(), indent=2))
**Erweiterte Konfiguration:**```python
from detect_secrets import SecretsCollection
from detect_secrets.settings import transient_settings
secrets = SecretsCollection()
with transient_settings({
# Only run scans with only these plugins.
# This format is the same as the one that is saved in the generated baseline.
'plugins_used': [
# Example of configuring a built-in plugin
{
'name': 'Base64HighEntropyString',
'limit': 5.0,
},
# Example of using a custom plugin
{
'name': 'HippoDetector',
'path': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
},
],
# We can also specify whichever additional filters we want.
# This is an example of using the function `is_identified_by_ML_model` within the
# local file `./private-filters/example.py`.
'filters_used': [
{
'path': 'file://private-filters/example.py::is_identified_by_ML_model',
},
]
}) as settings:
# If we want to make any further adjustments to the created settings object (e.g.
# disabling default filters), we can do so as such.
settings.disable_filters(
'detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign',
'detect_secrets.filters.heuristic.is_likely_id_string',
)
secrets.scan_file('test_data/config.ini')
$ pip install detect-secrets ✨🍰✨
Installieren über [brew](https://brew.sh/):```bash
$ brew install detect-secrets
detect-secrets wird mit drei verschiedenen Werkzeugen geliefert, und es gibt oft Verwirrung darüber, welches verwendet werden soll. Verwenden Sie diese praktische Checkliste, um zu entscheiden:
detect-secrets scan.detect-secrets-hook.detect-secrets audit.$ detect-secrets scan --help usage: detect-secrets scan [-h] [--string [STRING]] [--only-allowlisted] [--all-files] [--baseline FILENAME] [--force-use-all-plugins] [--slim] [--list-all-plugins] [-p PLUGIN] [--base64-limit [BASE64_LIMIT]] [--hex-limit [HEX_LIMIT]] [--disable-plugin DISABLE_PLUGIN] [-n | --only-verified] [--exclude-lines EXCLUDE_LINES] [--exclude-files EXCLUDE_FILES] [--exclude-secrets EXCLUDE_SECRETS] [--word-list WORD_LIST_FILE] [-f FILTER] [--disable-filter DISABLE_FILTER] [path [path ...]]
Scans a repository for secrets in code. The generated output is compatible
with detect-secrets-hook --baseline.
positional arguments: path Scans the entire codebase and outputs a snapshot of currently identified secrets.
optional arguments:
-h, --help show this help message and exit
--string [STRING] Scans an individual string, and displays configured
plugins' verdict.
--only-allowlisted Only scans the lines that are flagged with allowlist secret. This helps verify that individual exceptions
are indeed non-secrets.
scan options:
--all-files Scan all files recursively (as compared to only
scanning git tracked files).
--baseline FILENAME If provided, will update existing baseline by
importing settings from it.
--force-use-all-plugins
If a baseline is provided, detect-secrets will default
to loading the plugins specified by that baseline.
However, this may also mean it doesn't perform the
scan with the latest plugins. If this flag is
provided, it will always use the latest plugins
--slim Slim baselines are created with the intention of
minimizing differences between commits. However, they
are not compatible with the audit functionality, and
slim baselines will need to be remade to be audited.
plugin options: Configure settings for each secret scanning ruleset. By default, all plugins are enabled unless explicitly disabled.
--list-all-plugins Lists all plugins that will be used for the scan. -p PLUGIN, --plugin PLUGIN Specify path to custom secret detector plugin. --base64-limit [BASE64_LIMIT] Sets the entropy limit for high entropy strings. Value must be between 0.0 and 8.0, defaults to 4.5. --hex-limit [HEX_LIMIT] Sets the entropy limit for high entropy strings. Value must be between 0.0 and 8.0, defaults to 3.0. --disable-plugin DISABLE_PLUGIN Plugin class names to disable. e.g. Base64HighEntropyString
filter options: Configure settings for filtering out secrets after they are flagged by the engine.
-n, --no-verify Disables additional verification of secrets via network call. --only-verified Only flags secrets that can be verified. --exclude-lines EXCLUDE_LINES If lines match this regex, it will be ignored. --exclude-files EXCLUDE_FILES If filenames match this regex, it will be ignored. --exclude-secrets EXCLUDE_SECRETS If secrets match this regex, it will be ignored. --word-list WORD_LIST_FILE Text file with a list of words, if a secret contains a word in the list we ignore it. -f FILTER, --filter FILTER Specify path to custom filter. May be a python module path (e.g. detect_secrets.filters.common.is_invalid_file) or a local file path (e.g. file://path/to/file.py::function_name). --disable-filter DISABLE_FILTER Specify filter to disable. e.g. detect_secrets.filters.common.is_invalid_file
### Blockieren von Geheimnissen außerhalb der Baseline```
$ detect-secrets-hook --help
usage: detect-secrets-hook [-h] [-v] [--version] [--baseline FILENAME]
[--list-all-plugins] [-p PLUGIN]
[--base64-limit [BASE64_LIMIT]]
[--hex-limit [HEX_LIMIT]]
[--disable-plugin DISABLE_PLUGIN]
[-n | --only-verified]
[--exclude-lines EXCLUDE_LINES]
[--exclude-files EXCLUDE_FILES]
[--exclude-secrets EXCLUDE_SECRETS]
[--word-list WORD_LIST_FILE] [-f FILTER]
[--disable-filter DISABLE_FILTER]
[filenames [filenames ...]]
positional arguments:
filenames Filenames to check.
optional arguments:
-h, --help show this help message and exit
-v, --verbose Verbose mode.
--version Display version information.
--json Print detect-secrets-hook output as JSON
--baseline FILENAME Explicitly ignore secrets through a baseline generated
by `detect-secrets scan`
plugin options:
Configure settings for each secret scanning ruleset. By default, all
plugins are enabled unless explicitly disabled.
--list-all-plugins Lists all plugins that will be used for the scan.
-p PLUGIN, --plugin PLUGIN
Specify path to custom secret detector plugin.
--base64-limit [BASE64_LIMIT]
Sets the entropy limit for high entropy strings. Value
must be between 0.0 and 8.0, defaults to 4.5.
--hex-limit [HEX_LIMIT]
Sets the entropy limit for high entropy strings. Value
must be between 0.0 and 8.0, defaults to 3.0.
--disable-plugin DISABLE_PLUGIN
Plugin class names to disable. e.g.
Base64HighEntropyString
filter options:
Configure settings for filtering out secrets after they are flagged by the
engine.
-n, --no-verify Disables additional verification of secrets via
network call.
--only-verified Only flags secrets that can be verified.
--exclude-lines EXCLUDE_LINES
If lines match this regex, it will be ignored.
--exclude-files EXCLUDE_FILES
If filenames match this regex, it will be ignored.
--exclude-secrets EXCLUDE_SECRETS
If secrets match this regex, it will be ignored.
-f FILTER, --filter FILTER
Specify path to custom filter. May be a python module
path (e.g.
detect_secrets.filters.common.is_invalid_file) or a
local file path (e.g.
file://path/to/file.py::function_name).
--disable-filter DISABLE_FILTER
Specify filter to disable. e.g.
detect_secrets.filters.common.is_invalid_file
Wir empfehlen, dies als Pre-Commit-Hook einzurichten. Eine Möglichkeit ist die Verwendung des pre-commit Frameworks:```yaml
repos:
#### Inline-Zulassungsliste
Es gibt Zeiten, in denen wir ein falsches Positiv vom Blockieren eines Commits ausschließen möchten, ohne dafür eine Baseline zu erstellen. Sie können dies tun, indem Sie einen Kommentar wie folgt hinzufügen:```python
secret = "hunter2" # pragma: allowlist secret
oder```javascript // pragma: allowlist nextline secret const secret = "hunter2";
### Auditieren von Geheimnissen in Baseline```bash
$ detect-secrets audit --help
usage: detect-secrets audit [-h] [--diff] [--stats]
[--report] [--only-real | --only-false]
[--json]
filename [filename ...]
Auditing a baseline allows analysts to label results, and optimize plugins for
the highest signal-to-noise ratio for their environment.
positional arguments:
filename Audit a given baseline file to distinguish the difference
between false and true positives.
optional arguments:
-h, --help show this help message and exit
--diff Allows the comparison of two baseline files, in order to
effectively distinguish the difference between various plugin
configurations.
--stats Displays the results of an interactive auditing session which
have been saved to a baseline file.
--report Displays a report with the secrets detected
reporting:
Display a summary with all the findings and the made decisions. To be used with the report mode (--report).
--only-real Only includes real secrets in the report
--only-false Only includes false positives in the report
analytics:
Quantify the success of your plugins based on the labelled results in your
baseline. To be used with the statistics mode (--stats).
--json Outputs results in a machine-readable format.
Dieses Tool arbeitet mit einem System von Plugins und Filtern.
Sie können beide an Ihre Bedürfnisse hinsichtlich Präzision/Recall anpassen.
Es gibt drei verschiedene Strategien, die wir anwenden, um Geheimnisse im Code zu finden:
Regex-basierte Regeln
Dies sind der häufigste Plugin-Typ und funktionieren gut mit gut strukturierten Geheimnissen. Diese Geheimnisse können optional verifiziert werden, was die Scan-Präzision erhöht. Allerdings kann die alleinige Abhängigkeit davon den Recall Ihres Scans negativ beeinflussen.
Entropie-Erkenner
Dieser sucht nach "geheimnisaussehenden" Zeichenfolgen durch eine Vielzahl heuristischer Ansätze. Dies ist großartig für unstrukturierte Geheimnisse, erfordert jedoch möglicherweise Feinabstimmung, um die Scan-Präzision anzupassen.
Schlüsselwort-Erkenner
Dieser ignoriert den Geheimniswert und sucht nach Variablennamen, die oft mit der Zuweisung von Geheimnissen mit hartcodierten Werten assoziiert werden. Dies ist großartig für "nicht-geheimnisaussehende" Zeichenfolgen (z.B. le3tc0de-Passwörter), erfordert jedoch möglicherweise die Anpassung von Filtern, um die Scan-Präzision zu justieren.
Möchten Sie ein Geheimnis finden, das wir derzeit nicht erkennen? Sie können auch (einfach) Ihr eigenes Plugin entwickeln und es mit der Engine verwenden! Für weitere Informationen schauen Sie in die Plugin-Dokumentation.
detect-secrets wird mit mehreren verschiedenen eingebauten Filtern geliefert, die Ihren Anforderungen entsprechen könnten.
Manchmal möchten Sie bestimmte Zeilen in Ihrem Scan global zulassen können, wenn sie einem bestimmten Muster entsprechen. Sie können eine Regex-Regel wie folgt angeben:```bash $ detect-secrets scan --exclude-lines 'password = (blah|fake)'
Oder Sie können mehrere Regex-Regeln wie folgt festlegen:```bash
$ detect-secrets scan --exclude-lines 'password = blah' --exclude-lines 'password = fake'
Manchmal möchten Sie bestimmte Dateien in Ihrem Scan ignorieren. Sie können ein Regex-Muster angeben, und wenn der Dateiname diesem Regex-Muster entspricht, wird er nicht gescannt:```bash $ detect-secrets scan --exclude-files '.*.signature$'
Oder Sie können mehrere Regex-Muster wie folgt angeben:```bash
$ detect-secrets scan --exclude-files '.*\.signature$' --exclude-files '.*/i18n/.*'
Manchmal möchten Sie bestimmte geheime Werte in Ihrem Scan ignorieren. Sie können eine Regex-Regel wie folgt angeben:```bash $ detect-secrets scan --exclude-secrets '(fakesecret|${.*})'
Oder Sie können mehrere Regex-Regeln wie folgt angeben:```bash
$ detect-secrets scan --exclude-secrets 'fakesecret' --exclude-secrets '\${.*})'
Manchmal möchte man einen Ausschluss auf eine bestimmte Zeile anwenden, anstatt ihn global auszuschließen. Dies kann man mit Inline-Allowlisting wie folgt tun:```python API_KEY = 'this-will-ordinarily-be-detected-by-a-plugin' # pragma: allowlist secret
Diese Kommentare werden in mehreren Sprachen unterstützt. z.B.```java
const GoogleCredentialPassword = "something-secret-here"; // pragma: allowlist secret
Sie können auch verwenden:```python
API_KEY = 'WillAlsoBeIgnored'
Dies kann eine bequeme Möglichkeit sein, Geheimnisse zu ignorieren, ohne die gesamte Basislinie erneut generieren zu müssen. Wenn Sie diese auf die Whitelist gesetzten Geheimnisse explizit suchen müssen, können Sie auch Folgendes tun:```bash
$ detect-secrets scan --only-allowlisted
Möchten Sie eine eigene Logik schreiben, um Fehlalarme zu filtern? Erfahren Sie, wie das in unserer Filterdokumentation funktioniert.
Das Flag --exclude-secrets ermöglicht es Ihnen, Regex-Regeln zum Ausschließen von Geheimniswerten anzugeben. Wenn Sie stattdessen eine große Liste von Wörtern angeben möchten, können Sie das Flag --word-list verwenden.
Um diese Funktion zu nutzen, installieren Sie unbedingt das Paket pyahocorasick, oder verwenden Sie einfach:```bash
$ pip install detect-secrets[word_list]
Dann können Sie es wie folgt verwenden:```bash
$ cat wordlist.txt
not-a-real-secret
$ cat sample.ini
password = not-a-real-secret
# Will show results
$ detect-secrets scan sample.ini
# No results found
$ detect-secrets scan --word-list wordlist.txt
Der Gibberish Detector ist ein einfaches ML-Modell, das versucht zu bestimmen, ob ein geheimer Wert tatsächlich Kauderwelsch ist, unter der Annahme, dass echte geheime Werte nicht wortähnlich sind.
Um diese Funktion zu nutzen, stellen Sie sicher, dass das Paket gibberish-detector installiert ist, oder verwenden Sie:
pip install trufflehog[gibberish]
``````bash
$ pip install detect-secrets[gibberish]
Schauen Sie sich das gibberish-detector Paket an, um weitere Informationen zum Trainieren des Modells zu erhalten. Ein vortrainiertes Modell (initialisiert durch Verarbeitung von RFCs) wird zur einfachen Nutzung beigelegt.
Sie können auch Ihr eigenes Modell wie folgt angeben:```bash $ detect-secrets scan --gibberish-model custom.model
Dies ist kein Standard-Plugin, da es Geheimnisse wie `password` ignoriert.
## Einschränkungen
Dies ist nicht als absolute Lösung gedacht, um zu verhindern, dass Geheimnisse in die Codebasis gelangen. Nur eine angemessene Schulung der Entwickler kann das wirklich erreichen. Dieser Pre-Commit-Hook implementiert lediglich mehrere Heuristiken, um offensichtliche Fälle des Commitens von Geheimnissen zu verhindern.
**Dinge, die nicht verhindert werden:**
- Mehrzeilige Geheimnisse
- Standard-Passwörter, die den `KeywordDetector` nicht auslösen (z.B. `login = "hunter2"`)
## FAQ
### Allgemein
- **Warnung "Git-Repository nicht erkannt." wird angezeigt, obwohl ich mich in einem Git-Repo befinde.**
Überprüfen Sie, ob Ihre `git`-Version >= 1.8.5 ist. Wenn nicht, führen Sie bitte ein Upgrade durch und versuchen Sie es erneut.
[Weitere Details hier](https://github.com/Yelp/detect-secrets/issues/220).
### Windows
- **`detect-secrets audit` zeigt nach dem Erstellen einer Baseline "Not a valid baseline file!" an.**
Stellen Sie sicher, dass die Dateikodierung Ihrer Baseline-Datei UTF-8 ist.
[Weitere Details hier](https://github.com/Yelp/detect-secrets/issues/272#issuecomment-619187136).