detect secrets
v1.5.0
detect-secrets est un module bien nommé pour (surprise, surprise) détecter des secrets dans une base de code.
Cependant, contrairement à d'autres packages similaires qui se concentrent uniquement sur la recherche de secrets, ce package est conçu en pensant au client d'entreprise : fournir un moyen systématique et rétrocompatible de :
Empêcher de nouveaux secrets d'entrer dans la base de code,
Détecter si ces préventions sont explicitement contournées, et
Fournir une liste de contrôle des secrets à déployer et migrer vers un stockage plus sécurisé.
De cette façon, vous créez une séparation des préoccupations : accepter qu'il puisse actuellement y avoir des secrets cachés dans votre grand référentiel (c'est ce que nous appelons une référence ), mais empêcher ce problème de s'aggraver, sans faire face à l'effort potentiellement gargantuesque. de déplacer les secrets existants.
Pour ce faire, il exécute des sorties de comparaison périodiques sur des instructions regex conçues de manière heuristique, afin d'identifier si un nouveau secret a été validé. De cette façon, cela évite la surcharge liée à la recherche dans tout l’historique de Git, ainsi que la nécessité d’analyser l’intégralité du référentiel à chaque fois.
Pour un aperçu des modifications récentes, veuillez consulter CHANGELOG.md.
Si vous souhaitez contribuer, veuillez consulter CONTRIBUTING.md.
Pour une documentation plus détaillée, consultez nos autres documentations.
Créez une base de référence des secrets potentiels actuellement trouvés dans votre référentiel git.
$ analyse de détection de secrets > .secrets.baseline
ou, pour l'exécuter à partir d'un autre répertoire :
$ détecter-secrets -C /path/to/directory scan > /path/to/directory/.secrets.baseline
Analyse des fichiers suivis non-git :
$ détecter-secrets scan test_data/ --all-files > .secrets.baseline
Cela analysera à nouveau votre base de code et :
Mettre à jour/mettre à niveau votre baseline pour être compatible avec la dernière version,
Ajoutez tous les nouveaux secrets trouvés à votre référence,
Supprimez tous les secrets qui ne figurent plus dans votre base de code
Cela préservera également tous les secrets étiquetés dont vous disposez.
$ détecter-secrets scan --baseline .secrets.baseline
Pour les lignes de base antérieures à la version 0.9, recréez-la simplement.
Analyse des fichiers transférés uniquement :
$ git diff --staged --name-only -z | xargs -0 détecter-secrets-hook --baseline .secrets.baseline
Analyse de tous les fichiers suivis :
$ git ls-files -z | xargs -0 détecter-secrets-hook --baseline .secrets.baseline
$ analyse des secrets de détection --list-all-plugins Détecteur d'artefacts AWSKeyDetector AzureStorageKeyDetector Détecteur d'authentification de base Détecteur de nuages DiscordBotTokenDetector Détecteur de jetons GitHub GitLabTokenDetector Base64HighEntropyString Chaîne HexHighEntropy IBMCloudIamDetector IbmCosHmacDetector IPPublicDétecteur Détecteur de jetons Jwt Détecteur de mots-clés MailchimpDétecteur NpmDétecteur OpenAIDetector Détecteur de clé privée PypiTokenDetector EnvoyerGridDetector Détecteur de Slack SoftlayerDétecteur SquareOAuthDétecteur Détecteur de rayures TelegramBotTokenDetector TwilioKeyDetector
$ analyse des secrets --disable-plugin KeywordDetector --disable-plugin AWSKeyDetector
Si vous souhaitez exécuter uniquement un plugin spécifique, vous pouvez faire :
$ analyse des secrets de détection --list-all-plugins |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs détecte les secrets analyse test_dataIl s'agit d'une étape facultative pour étiqueter les résultats dans votre référence. Il peut être utilisé pour affiner votre liste de contrôle des secrets à migrer, ou pour mieux configurer vos plugins afin d'améliorer son rapport signal/bruit.
$ détecter-secrets audit .secrets.baseline
Utilisation de base :
à partir de detector_secrets importer SecretsCollectionfrom detect_secrets.settings importer default_settingssecrets = SecretsCollection()avec default_settings():secrets.scan_file('test_data/config.ini')import jsonprint(json.dumps(secrets.json(), indent=2))Configuration plus avancée :
from detector_secrets import SecretsCollectionfrom detect_secrets.settings import transient_settingssecrets = SecretsCollection()with transient_settings({# Exécutez uniquement des analyses avec ces plugins uniquement.# Ce format est le même que celui enregistré dans la ligne de base générée.'plugins_used': [# Exemple de configurer un plugin intégré{'name' : 'Base64HighEntropyString', 'limite' : 5.0,
},# Exemple d'utilisation d'un plugin personnalisé{'name' : 'HippoDetector','path' : 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
},
],# Nous pouvons également spécifier les filtres supplémentaires que nous souhaitons.# Ceci est un exemple d'utilisation de la fonction `is_identified_by_ML_model` dans le# fichier local `./private-filters/example.py`.'filters_used' : [
{'chemin' : 'file://private-filters/example.py::is_identified_by_ML_model',
},
]
}) en tant que paramètres :# Si nous souhaitons apporter d'autres ajustements à l'objet de paramètres créé (par exemple# désactiver les filtres par défaut), nous pouvons le faire en tant que tel.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 détecter-secrets ?
Installer via Brew :
$ Brew Install Détection des secrets
detect-secrets est livré avec trois outils différents, et il y a souvent une confusion quant à savoir lequel utiliser. Utilisez cette liste de contrôle pratique pour vous aider à décider :
Voulez-vous ajouter des secrets à votre base de référence ? Si tel est le cas, utilisez detect-secrets scan .
Voulez-vous alerter sur de nouveaux secrets qui ne figurent pas dans la ligne de base ? Si tel est le cas, utilisez detect-secrets-hook .
Analysez-vous la ligne de base elle-même ? Si tel est le cas, utilisez 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
Nous vous recommandons de le configurer comme hook de pré-validation. Une façon de procéder consiste à utiliser le framework de pré-commit :
# .pre-commit-config.yamlrepos :
- dépôt : https://github.com/Yelp/detect-secretsrev : v1.5.0hooks :
- identifiant : détecter-secretsargs : ['--baseline', '.secrets.baseline']exclure : package.lock.jsonIl y a des moments où nous souhaitons exclure un faux positif du blocage d’une validation, sans créer de référence pour le faire. Vous pouvez le faire en ajoutant un commentaire comme tel :
secret = "hunter2" # pragma : secret de la liste autorisée
ou
// pragma : liste blanche suivante secretconst secret = "hunter2" ;
$ audit de détection de secrets --help
utilisation : audit de détection de secrets [-h] [--diff] [--stats]
[--rapport] [--only-real | --seulement-faux]
[--json]
nom de fichier [nom de fichier ...]
L'audit d'une référence permet aux analystes d'étiqueter les résultats et d'optimiser les plugins pour obtenir le rapport signal/bruit le plus élevé pour leur environnement.
arguments de position :
filename Auditer un fichier de référence donné pour distinguer la différence
entre les faux et les vrais positifs.
arguments facultatifs :
-h, --help afficher ce message d'aide et quitter
--diff Permet la comparaison de deux fichiers de base, afin de
distinguer efficacement la différence entre les différents plugins
configurations.
--stats Affiche les résultats d'une session d'audit interactive qui
ont été enregistrés dans un fichier de référence.
--report Affiche un rapport avec les secrets détectés
rapport :
Affichez un résumé avec tous les résultats et les décisions prises. A utiliser avec le mode rapport (--report).
--only-real Inclut uniquement les vrais secrets dans le rapport
--only-false Inclut uniquement les faux positifs dans le rapport
analytique:
Quantifiez le succès de vos plugins en fonction des résultats étiquetés dans votre
ligne de base. A utiliser avec le mode statistiques (--stats).
--json Produit les résultats dans un format lisible par machine.Cet outil fonctionne grâce à un système de plugins et de filtres .
Les plugins trouvent des secrets dans le code
Les filtres ignorent les faux positifs pour augmenter la précision de la numérisation
Vous pouvez ajuster les deux en fonction de vos besoins de précision/rappel.
Nous utilisons trois stratégies différentes pour essayer de trouver des secrets dans le code :
Règles basées sur Regex
Il s’agit du type de plugin le plus courant et fonctionne bien avec des secrets bien structurés. Ces secrets peuvent éventuellement être vérifiés, ce qui augmente la précision de la numérisation. Cependant, dépendre uniquement de ceux-ci peut affecter négativement le rappel de votre analyse.
Détecteur d'entropie
Cela recherche des chaînes « d’apparence secrète » à travers diverses approches heuristiques. C'est idéal pour les secrets non structurés, mais cela peut nécessiter un réglage pour ajuster la précision de l'analyse.
Détecteur de mots clés
Cela ignore la valeur secrète et recherche les noms de variables souvent associés à l'attribution de secrets avec des valeurs codées en dur. C'est idéal pour les chaînes « non secrètes » (par exemple les mots de passe le3tc0de), mais peut nécessiter des filtres de réglage pour ajuster la précision de l'analyse.
Vous voulez découvrir un secret que nous ne comprenons pas actuellement ? Vous pouvez également (facilement) développer votre propre plugin, et l'utiliser avec le moteur ! Pour plus d’informations, consultez la documentation du plugin.
detect-secrets est livré avec plusieurs filtres intégrés différents qui peuvent répondre à vos besoins.
Parfois, vous souhaitez pouvoir autoriser globalement certaines lignes dans votre analyse, si elles correspondent à un modèle spécifique. Vous pouvez spécifier une règle regex comme telle :
$ analyse des secrets de détection --exclude-lines 'mot de passe = (blah|fake)'
Ou vous pouvez spécifier plusieurs règles regex comme telles :
$ analyse des secrets --exclude-lines 'mot de passe = bla' --exclude-lines 'mot de passe = faux'
Parfois, vous souhaitez pouvoir ignorer certains fichiers lors de votre analyse. Vous pouvez spécifier un modèle d'expression régulière pour ce faire, et si le nom de fichier correspond à ce modèle d'expression régulière, il ne sera pas analysé :
$ analyse des secrets de détection --exclude-files '.*.signature$'
Ou vous pouvez spécifier plusieurs modèles d'expression régulière comme tels :
$ analyse des secrets --exclude-files '.*.signature$' --exclude-files '.*/i18n/.*'
Parfois, vous souhaitez pouvoir ignorer certaines valeurs secrètes dans votre analyse. Vous pouvez spécifier une règle regex comme telle :
$ analyse de détection de secrets --exclude-secrets '(fakesecret|${.*})'Ou vous pouvez spécifier plusieurs règles regex comme telles :
$ analyse de détection de secrets --exclude-secrets 'fakesecret' --exclude-secrets '${.*})'Parfois, vous souhaitez appliquer une exclusion à une ligne spécifique, plutôt que de l'exclure globalement. Vous pouvez le faire avec la liste blanche en ligne comme telle :
API_KEY = 'ceci-sera-normalement-détecté-par-un-plugin' # pragma : secret de la liste autorisée
Ces commentaires sont pris en charge dans plusieurs langues. par exemple
const GoogleCredentialPassword = "quelque chose de secret ici" ; // pragma : secret de la liste autorisée
Vous pouvez également utiliser :
# pragma : liste blanche suivante secretAPI_KEY = 'WillAlsoBeIgnored'
Cela peut être un moyen pratique pour ignorer les secrets, sans avoir besoin de régénérer à nouveau l'intégralité de la ligne de base. Si vous devez rechercher explicitement ces secrets sur liste blanche, vous pouvez également :
$ analyse de détection de secrets --only-allowlisted
Vous souhaitez écrire une logique plus personnalisée pour filtrer les faux positifs ? Découvrez comment procéder dans notre documentation sur les filtres.
L'indicateur --exclude-secrets vous permet de spécifier des règles d'expression régulière pour exclure les valeurs secrètes. Cependant, si vous souhaitez plutôt spécifier une grande liste de mots, vous pouvez utiliser l'indicateur --word-list .
Pour utiliser cette fonctionnalité, assurez-vous d'installer le package pyahocorasick , ou utilisez simplement :
$ pip install détecter-secrets[word_list]
Ensuite, vous pouvez l'utiliser comme tel :
$ liste de mots de chat.txt pas un vrai secret $ échantillon de chat.ini mot de passe = pas-un-vrai-secret# Affichera les résultats$ analyse de détection de secrets sample.ini# Aucun résultat trouvé$ analyse de détection de secrets --word-list wordlist.txt
Le détecteur de charabia est un modèle ML simple, qui tente de déterminer si une valeur secrète est réellement du charabia, en supposant que les vraies valeurs secrètes ne ressemblent pas à des mots.
Pour utiliser cette fonctionnalité, assurez-vous d'installer le package gibberish-detector ou utilisez :
$ pip install détecter-secrets[charabia]
Consultez le package charabia-détecteur pour plus d’informations sur la façon de former le modèle. Un modèle pré-entraîné (ensemencé par le traitement des RFC) sera inclus pour une utilisation facile.
Vous pouvez également spécifier votre propre modèle comme tel :
$ analyse de détection de secrets --gibberish-model custom.model
Ce n'est pas un plugin par défaut, étant donné qu'il ignorera les secrets tels que password .
Il ne s’agit pas d’une solution infaillible pour empêcher les secrets de pénétrer dans la base de code. Seule une formation adéquate des développeurs peut réellement y parvenir. Ce hook de pré-commit implémente simplement plusieurs heuristiques pour tenter d'éviter les cas évidents de divulgation de secrets.
Choses qui ne seront pas évitées :
Secrets multilignes
Mots de passe par défaut qui ne déclenchent pas le KeywordDetector (par exemple login = "hunter2" )
"Le dépôt git n'a pas été détecté." avertissement rencontré, même si je suis dans un dépôt git.
Vérifiez si votre version git est >= 1.8.5. Si ce n'est pas le cas, veuillez le mettre à niveau, puis réessayer. Plus de détails ici.
detect-secrets audit affiche « Pas un fichier de base valide ! » après avoir créé la ligne de base.
Assurez-vous que le codage de votre fichier de base est UTF-8. Plus de détails ici.
