detect secrets
v1.5.0
detect-secrets ist ein treffend benanntes Modul zum (Überraschung, Überraschung) Erkennen von Geheimnissen innerhalb einer Codebasis.
Im Gegensatz zu anderen ähnlichen Paketen, die sich ausschließlich auf das Auffinden von Geheimnissen konzentrieren, ist dieses Paket jedoch speziell für den Unternehmenskunden konzipiert: Es bietet ein abwärtskompatibles , systematisches Mittel für Folgendes:
Verhindern, dass neue Geheimnisse in die Codebasis gelangen,
Erkennen, ob solche Verhinderungen explizit umgangen werden, und
Bereitstellung einer Checkliste mit Geheimnissen zum Ausrollen und zur Migration auf einen sichereren Speicher.
Auf diese Weise schaffen Sie eine Trennung der Bedenken: Sie akzeptieren, dass derzeit möglicherweise Geheimnisse in Ihrem großen Repository verborgen sind (das nennen wir eine Baseline ), verhindern aber, dass dieses Problem noch größer wird, ohne sich mit dem möglicherweise gigantischen Aufwand auseinanderzusetzen bestehende Geheimnisse zu vertreiben.
Dies geschieht durch regelmäßige Diff-Ausgaben für heuristisch erstellte Regex-Anweisungen, um festzustellen, ob ein neues Geheimnis festgeschrieben wurde. Auf diese Weise wird der Aufwand vermieden, den gesamten Git-Verlauf durchzuwühlen und jedes Mal das gesamte Repository scannen zu müssen.
Einen Blick auf die jüngsten Änderungen finden Sie unter CHANGELOG.md.
Wenn Sie einen Beitrag leisten möchten, lesen Sie bitte CONTRIBUTING.md.
Eine detailliertere Dokumentation finden Sie in unserer anderen Dokumentation.
Erstellen Sie eine Basisliste potenzieller Geheimnisse, die derzeit in Ihrem Git-Repository gefunden werden.
$ discover-secrets scan > .secrets.baseline
oder um es aus einem anderen Verzeichnis auszuführen:
$ discover-secrets -C /path/to/directory scan > /path/to/directory/.secrets.baseline
Scannen von nicht von Git verfolgten Dateien:
$ discover-secrets scan test_data/ --all-files > .secrets.baseline
Dadurch wird Ihre Codebasis erneut gescannt und:
Aktualisieren/aktualisieren Sie Ihre Baseline, um sie mit der neuesten Version kompatibel zu machen.
Fügen Sie alle neuen Geheimnisse, die es findet, zu Ihrer Basislinie hinzu.
Entfernen Sie alle Geheimnisse, die sich nicht mehr in Ihrer Codebasis befinden
Dadurch werden auch alle gekennzeichneten Geheimnisse, die Sie haben, gewahrt.
$ discover-secrets scan --baseline .secrets.baseline
Für Baselines, die älter als Version 0.9 sind, erstellen Sie sie einfach neu.
Nur bereitgestellte Dateien scannen:
$ git diff --staged --name-only -z | xargs -0 discover-secrets-hook --baseline .secrets.baseline
Scannen aller verfolgten Dateien:
$ git ls-files -z | xargs -0 discover-secrets-hook --baseline .secrets.baseline
$ discover-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
$ discover-secrets scan --disable-plugin KeywordDetector --disable-plugin AWSKeyDetector
Wenn Sie nur ein bestimmtes Plugin ausführen möchten, können Sie Folgendes tun:
$ discover-secrets scan --list-all-plugins |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs discover-secrets scannen test_dataDies ist ein optionaler Schritt zum Markieren der Ergebnisse in Ihrer Baseline. Es kann verwendet werden, um Ihre Checkliste der zu migrierenden Secrets einzugrenzen oder Ihre Plugins besser zu konfigurieren, um das Signal-Rausch-Verhältnis zu verbessern.
$ discover-secrets audit .secrets.baseline
Grundlegende Verwendung:
from discover_secrets import SecretsCollectionfrom discover_secrets.settings import default_settingssecrets = SecretsCollection()with default_settings():secrets.scan_file('test_data/config.ini')import jsonprint(json.dumps(secrets.json(), indent=2))Erweiterte Konfiguration:
from discover_secrets import SecretsCollectionfrom discover_secrets.settings import transient_settingssecrets = SecretsCollection()with transient_settings({# Führen Sie Scans nur mit diesen Plugins aus.# Dieses Format ist dasselbe wie das, das in der generierten Baseline gespeichert ist.'plugins_used': [# Beispiel zum Konfigurieren eines integrierten Plugins{'name': 'Base64HighEntropyString','limit': 5,0,
},# Beispiel für die Verwendung eines benutzerdefinierten Plugins{'name': 'HippoDetector','path': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
},
],# Wir können auch die gewünschten zusätzlichen Filter angeben.# Dies ist ein Beispiel für die Verwendung der Funktion „is_identified_by_ML_model“ in der # lokalen Datei „./private-filters/example.py“. „filters_used“: [
{'path': 'file://private-filters/example.py::is_identified_by_ML_model',
},
]
}) als Einstellungen:# Wenn wir weitere Anpassungen am erstellten Einstellungsobjekt vornehmen möchten (z. B. Standardfilter deaktivieren), können wir dies wie folgt tun.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 ?
Installation über brew:
$ brew install Detect-Secrets
detect-secrets wird mit drei verschiedenen Tools geliefert, und es herrscht oft Verwirrung darüber, welches man verwenden soll. Nutzen Sie diese praktische Checkliste als Entscheidungshilfe:
Möchten Sie Geheimnisse zu Ihrer Basislinie hinzufügen? Wenn ja, verwenden Sie detect-secrets scan .
Möchten Sie vor neuen Geheimnissen warnen, die nicht in der Grundlinie enthalten sind? Wenn ja, verwenden Sie detect-secrets-hook .
Analysieren Sie die Basislinie selbst? Wenn ja, verwenden Sie 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
$ 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 hierfür ist die Verwendung des Pre-Commit-Frameworks:
# .pre-commit-config.yamlrepos:
- Repo: https://github.com/Yelp/detect-secretsrev: v1.5.0hooks:
- id: discover-secretsargs: ['--baseline', '.secrets.baseline']exclude: package.lock.jsonEs gibt Zeiten, in denen wir ein falsch positives Ergebnis von der Blockierung eines Commits ausschließen möchten, ohne eine Grundlinie dafür zu erstellen. Sie können dies tun, indem Sie einen Kommentar wie folgt hinzufügen:
Secret = „Hunter2“ # Pragma: Geheimnis der Zulassungsliste
oder
// Pragma: Allowlist Nextline Secretconst Secret = "Hunter2";
$ Detect-Secrets Audit --help
Verwendung: Detect-Secrets Audit [-h] [--diff] [--stats]
[--report] [--only-real | --only-false]
[--json]
Dateiname [Dateiname ...]
Die Prüfung einer Baseline ermöglicht es Analysten, Ergebnisse zu kennzeichnen und Plugins für das höchste Signal-Rausch-Verhältnis für ihre Umgebung zu optimieren.
Positionsargumente:
Dateiname Überprüfen Sie eine bestimmte Basisdatei, um den Unterschied zu erkennen
zwischen falsch und wahr positiv.
optionale Argumente:
-h, --help zeigt diese Hilfemeldung an und beendet den Vorgang
--diff Ermöglicht den Vergleich zweier Basisdateien, um
Unterscheiden Sie effektiv den Unterschied zwischen verschiedenen Plugins
Konfigurationen.
--stats Zeigt die Ergebnisse einer interaktiven Auditing-Sitzung an, die
wurden in einer Baseline-Datei gespeichert.
--report Zeigt einen Bericht mit den erkannten Geheimnissen an
Berichterstattung:
Zeigen Sie eine Zusammenfassung aller Erkenntnisse und getroffenen Entscheidungen an. Zur Verwendung mit dem Berichtsmodus (--report).
--only-real Nimmt nur echte Geheimnisse in den Bericht auf
--only-false Nimmt nur falsch positive Ergebnisse in den Bericht auf
Analytik:
Quantifizieren Sie den Erfolg Ihrer Plugins anhand der gekennzeichneten Ergebnisse in Ihrem
Grundlinie. Zur Verwendung mit dem Statistikmodus (--stats).
--json Gibt Ergebnisse in einem maschinenlesbaren Format aus.Dieses Tool funktioniert über ein System von Plugins und Filtern .
Plugins finden Geheimnisse im Code
Filter ignorieren falsch positive Ergebnisse, um die Scangenauigkeit zu erhöhen
Sie können beides an Ihre Präzisions-/Erinnerungsanforderungen anpassen.
Es gibt drei verschiedene Strategien, mit denen wir versuchen, Geheimnisse im Code zu finden:
Regex-basierte Regeln
Dies sind die gebräuchlichsten Plugin-Typen und funktionieren gut mit gut strukturierten Geheimnissen. Diese Geheimnisse können optional verifiziert werden, was die Scangenauigkeit erhöht. Eine alleinige Abhängigkeit davon kann sich jedoch negativ auf die Erinnerung an Ihren Scan auswirken.
Entropiedetektor
Dabei wird mithilfe verschiedener heuristischer Ansätze nach „geheimnisvoll aussehenden“ Zeichenfolgen gesucht. Dies eignet sich hervorragend für nicht strukturierte Geheimnisse, erfordert jedoch möglicherweise eine Optimierung, um die Scangenauigkeit anzupassen.
Keyword-Detektor
Dabei wird der Geheimniswert ignoriert und nach Variablennamen gesucht, die häufig mit der Zuweisung von Geheimnissen mit fest codierten Werten verbunden sind. Dies eignet sich hervorragend für „nicht geheim aussehende“ Zeichenfolgen (z. B. le3tc0de-Passwörter), erfordert jedoch möglicherweise die Optimierung von Filtern, um die Scangenauigkeit anzupassen.
Möchten Sie ein Geheimnis finden, das wir derzeit nicht entdecken? Sie können auch (einfach) Ihr eigenes Plugin entwickeln und es mit der Engine verwenden! Weitere Informationen finden Sie in der Plugin-Dokumentation.
detect-secrets verfügt über mehrere verschiedene integrierte Filter, die möglicherweise Ihren Anforderungen entsprechen.
Manchmal möchten Sie bestimmte Linien in Ihrem Scan global zulassen, wenn sie einem bestimmten Muster entsprechen. Sie können eine Regex-Regel wie folgt angeben:
$ discover-secrets scan --exclude-lines 'password = (blah|fake)'
Oder Sie können mehrere Regex-Regeln als solche angeben:
$ discover-secrets scan --exclude-lines 'password = blah' --exclude-lines 'password = fake'
Manchmal möchten Sie bestimmte Dateien bei Ihrem Scan ignorieren können. Sie können dazu ein Regex-Muster angeben. Wenn der Dateiname diesem Regex-Muster entspricht, wird er nicht gescannt:
$ discover-secrets scan --exclude-files '.*.signatur$'
Oder Sie können mehrere Regex-Muster als solche angeben:
$ discover-secrets scan --exclude-files '.*.signatur$' --exclude-files '.*/i18n/.*'
Manchmal möchten Sie bestimmte geheime Werte bei Ihrem Scan ignorieren können. Sie können eine Regex-Regel wie folgt angeben:
$ discover-secrets scan --exclude-secrets '(fakesecret|${.*})'Oder Sie können mehrere Regex-Regeln als solche angeben:
$ discover-secrets scan --exclude-secrets 'fakesecret' --exclude-secrets '${.*})'Manchmal möchten Sie einen Ausschluss auf eine bestimmte Zeile anwenden, anstatt sie global auszuschließen. Sie können dies mit der Inline-Zulassungsliste wie folgt tun:
API_KEY = 'dies-wird-normalerweise-von-einem-Plugin-erkannt' # pragma: Geheimnis der Zulassungsliste
Diese Kommentare werden in mehreren Sprachen unterstützt. z.B
const GoogleCredentialPassword = "something-secret-here"; // Pragma: Geheimnis der Zulassungsliste
Sie können auch Folgendes verwenden:
# pragma: Nextline auf die Zulassungsliste SecretAPI_KEY = 'WillAlsoBeIgnored'
Dies kann für Sie eine bequeme Möglichkeit sein, Geheimnisse zu ignorieren, ohne die gesamte Grundlinie erneut regenerieren zu müssen. Wenn Sie explizit nach diesen Geheimnissen auf der Zulassungsliste suchen müssen, können Sie auch Folgendes tun:
$ discover-secrets scan --only-allowlisted
Möchten Sie mehr benutzerdefinierte Logik schreiben, um Fehlalarme herauszufiltern? Sehen Sie sich in unserer Filterdokumentation an, wie das geht.
Mit dem Flag --exclude-secrets können Sie Regex-Regeln angeben, um geheime Werte auszuschließen. Wenn Sie jedoch stattdessen eine große Liste von Wörtern angeben möchten, können Sie das Flag --word-list verwenden.
Um diese Funktion nutzen zu können, müssen Sie unbedingt das pyahocorasick -Paket installieren oder einfach Folgendes verwenden:
$ pip install discover-secrets[word_list]
Dann können Sie es wie folgt verwenden:
$ cat wortliste.txt kein echtes Geheimnis $ cat sample.ini Passwort = kein echtes Geheimnis# Zeigt Ergebnisse an$ Detect-Secrets Scan Sample.ini# Keine Ergebnisse gefunden$ 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 wortartig sind.
Um diese Funktion nutzen zu können, müssen Sie unbedingt das Paket gibberish-detector installieren oder Folgendes verwenden:
$ pip install Detect-Secrets[Kauderwelsch]
Weitere Informationen zum Trainieren des Modells finden Sie im Paket „Gibberish-Detector“. Zur einfachen Verwendung wird ein vorab trainiertes Modell (durch die Verarbeitung von RFCs gesät) mitgeliefert.
Sie können Ihr eigenes Modell auch als solches angeben:
$ discover-secrets scan --gibberish-model custom.model
Dies ist kein Standard-Plugin, da es Geheimnisse wie password ignoriert.
Dies soll keine sichere Lösung sein, um zu verhindern, dass Geheimnisse in die Codebasis gelangen. Dies kann nur durch eine angemessene Entwicklerausbildung erreicht werden. Dieser Pre-Commit-Hook implementiert lediglich mehrere Heuristiken, um offensichtliche Fälle des Commits von Geheimnissen zu verhindern.
Dinge, die nicht verhindert werden können:
Mehrzeilige Geheimnisse
Standardpasswörter, die den KeywordDetector nicht auslösen (z. B. login = "hunter2" )
„Git-Repository wurde nicht erkannt.“ Es ist eine Warnung aufgetreten, obwohl ich mich in einem Git-Repo befinde.
Überprüfen Sie, ob Ihre git Version >= 1.8.5 ist. Wenn nicht, aktualisieren Sie es bitte und versuchen Sie es erneut. Weitere Details hier.
detect-secrets audit zeigt „Keine gültige Basisdatei!“ an. nach dem Erstellen der Grundlinie.
Stellen Sie sicher, dass die Dateikodierung Ihrer Basisdatei UTF-8 ist. Weitere Details hier.
