detect secrets
v1.5.0
detect-secrets es un módulo con un nombre apropiado para (sorpresa, sorpresa) detectar secretos dentro de una base de código.
Sin embargo, a diferencia de otros paquetes similares que se centran únicamente en encontrar secretos, este paquete está diseñado pensando en el cliente empresarial: proporciona un medio sistemático y compatible con versiones anteriores de:
Evitar que nuevos secretos entren en la base del código,
Detectar si dichas prevenciones se eluden explícitamente, y
Proporcionar una lista de verificación de secretos para transferir y migrar a un almacenamiento más seguro.
De esta manera, crea una separación de preocupaciones: acepta que actualmente puede haber secretos escondidos en su gran repositorio (esto es a lo que nos referimos como línea de base ), pero evita que este problema crezca, sin lidiar con el esfuerzo potencialmente gigantesco. de alejar los secretos existentes.
Para ello, ejecuta resultados de diferencias periódicos contra declaraciones de expresiones regulares elaboradas heurísticamente, para identificar si se ha cometido algún nuevo secreto. De esta manera, evita la sobrecarga de buscar en todo el historial de git, así como la necesidad de escanear todo el repositorio cada vez.
Para ver los cambios recientes, consulte CHANGELOG.md.
Si desea contribuir, consulte CONTRIBUTING.md.
Para obtener documentación más detallada, consulte nuestra otra documentación.
Cree una línea de base de los secretos potenciales que se encuentran actualmente en su repositorio de git.
$ detección de escaneo de secretos > .secrets.baseline
o, para ejecutarlo desde un directorio diferente:
$ detectar-secretos -C /ruta/al/escaneo de directorio > /ruta/al/directorio/.secrets.baseline
Escaneo de archivos rastreados que no son de git:
$ detectar-secretos escanear test_data/ --todos-archivos > .secrets.baseline
Esto volverá a escanear su código base y:
Actualice/actualice su línea base para que sea compatible con la última versión,
Agregue cualquier secreto nuevo que encuentre a su línea de base,
Elimina cualquier secreto que ya no esté en tu código base
Esto también preservará los secretos etiquetados que tenga.
$ detección de escaneo de secretos --baseline .secrets.baseline
Para líneas base anteriores a la versión 0.9, simplemente vuelva a crearlas.
Escaneo de archivos preparados únicamente:
$ git diff --staged --name-only -z | xargs -0 detectar-secretos-hook --baseline .secrets.baseline
Escaneando todos los archivos rastreados:
$ git ls-files -z | xargs -0 detectar-secretos-hook --baseline .secrets.baseline
$ detectar-escaneo de secretos --listar-todos-complementos detector artístico AWSKeyDetector AzureStorageKeyDetector Detector de autenticación básica Detector de nubes DiscordBotTokenDetector Detector de tokens de GitHub Detector de tokens GitLab Base64AltaEntropíaCadena Cadena hexadecimal de alta entropía IBMCloudIamDetector IBMCosHmacDetector IPPublicDetector JwtTokenDetector Detector de palabras clave MailchimpDetector NpmDetector OpenAIDetector Detector de claves privadas Detector de tokens Pypi EnviarGridDetector Detector de holgura Detector de capa suave SquareOAuthDetector detector de rayas TelegramBotTokenDetector TwilioKeyDetector
$ detección de escaneo de secretos --disable-plugin KeywordDetector --disable-plugin AWSKeyDetector
Si solo desea ejecutar un complemento específico, puede hacer:
$ detectar-escaneo de secretos --list-all-plugins |
grep -v 'Detector de autenticación básica' |
sed "s#^#--disable-plugin #g" |
xargs detectar-secretos escanear test_dataEste es un paso opcional para etiquetar los resultados en su línea base. Puede usarse para reducir su lista de verificación de secretos para migrar o para configurar mejor sus complementos para mejorar su relación señal-ruido.
$ auditoría de detección de secretos .secrets.baseline
Uso básico:
de detect_secrets importar SecretsCollection de detect_secrets.settings importar default_settingssecrets = SecretsCollection()con default_settings():secrets.scan_file('test_data/config.ini')importar jsonprint(json.dumps(secrets.json(), indent=2))Configuración más avanzada:
from detect_secrets import SecretsCollectionfrom detect_secrets.settings import transient_settingssecrets = SecretsCollection()with transient_settings({# Ejecute análisis solo con estos complementos.# Este formato es el mismo que se guarda en la línea base generada.'plugins_used': [# Ejemplo de configurar un complemento integrado{'nombre': 'Base64HighEntropyString','límite': 5.0,
},# Ejemplo de uso de un complemento personalizado{'nombre': 'HippoDetector','ruta': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
},
],# También podemos especificar los filtros adicionales que queramos.# Este es un ejemplo del uso de la función `is_identified_by_ML_model` dentro del# archivo local `./private-filters/example.py`.'filters_used': [
{'ruta': 'archivo://filtros-privados/ejemplo.py::is_identified_by_ML_model',
},
]
}) como configuración:# Si queremos realizar más ajustes al objeto de configuración creado (por ejemplo, # deshabilitar los filtros predeterminados), podemos hacerlo así.settings.disable_filters('detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign','detect_secrets .filters.heuristic.is_likely_id_string',
)secretos.scan_file('test_data/config.ini')$ pip instalar detectar-secretos ?
Instalar mediante cerveza:
$ brew instalar detectar-secretos
detect-secrets viene con tres herramientas diferentes y, a menudo, existe confusión sobre cuál usar. Utilice esta práctica lista de verificación para ayudarle a decidir:
¿Quieres agregar secretos a tu línea base? Si es así, utilice detect-secrets scan .
¿Quieres alertar sobre nuevos secretos que no están en la línea de base? Si es así, utilice detect-secrets-hook .
¿Estás analizando la línea de base en sí? Si es así, utilice 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
Recomendamos configurar esto como un gancho de confirmación previa. Una forma de hacerlo es utilizando el marco de compromiso previo:
# .pre-commit-config.yamlrepos:
- repositorio: https://github.com/Yelp/detect-secretsrev: v1.5.0hooks:
- id: detect-secretsargs: ['--baseline', '.secrets.baseline']excluir: paquete.lock.jsonHay ocasiones en las que queremos excluir un falso positivo del bloqueo de una confirmación, sin crear una línea de base para hacerlo. Puedes hacerlo agregando un comentario como tal:
secreto = "hunter2" # pragma: secreto de lista permitida
o
// pragma: lista de permitidos nextline secretconst secret = "hunter2";
$ auditoría de detección de secretos --ayuda
uso: auditoría de detección de secretos [-h] [--diff] [--stats]
[--reporte] [--sólo-real | --sólo-falso]
[--json]
nombre de archivo [nombre de archivo...]
Auditar una línea de base permite a los analistas etiquetar los resultados y optimizar los complementos para obtener la relación señal-ruido más alta para su entorno.
argumentos posicionales:
nombre de archivo Auditar un archivo de referencia determinado para distinguir la diferencia
entre falsos y verdaderos positivos.
argumentos opcionales:
-h, --help muestra este mensaje de ayuda y sale
--diff Permite comparar dos archivos de línea base, para
distinguir efectivamente la diferencia entre varios complementos
configuraciones.
--stats Muestra los resultados de una sesión de auditoría interactiva que
se han guardado en un archivo de referencia.
--report Muestra un informe con los secretos detectados
informes:
Mostrar un resumen con todos los hallazgos y las decisiones tomadas. Para ser utilizado con el modo de informe (--report).
--only-real Solo incluye secretos reales en el informe
--only-false Solo incluye falsos positivos en el informe
analítica:
Cuantifique el éxito de sus complementos en función de los resultados etiquetados en su
base. Para ser utilizado con el modo de estadísticas (--stats).
--json Genera los resultados en un formato legible por máquina.Esta herramienta opera a través de un sistema de complementos y filtros .
Los complementos encuentran secretos en el código
Los filtros ignoran los falsos positivos para aumentar la precisión del escaneo
Puede ajustar ambos para adaptarlos a sus necesidades de precisión/recuperación.
Hay tres estrategias diferentes que empleamos para intentar encontrar secretos en el código:
Reglas basadas en expresiones regulares
Estos son el tipo de complemento más común y funcionan bien con secretos bien estructurados. Estos secretos se pueden verificar opcionalmente, lo que aumenta la precisión del escaneo. Sin embargo, depender únicamente de estos puede afectar negativamente la recuperación de su escaneo.
Detector de entropía
Esto busca cadenas de "aspecto secreto" a través de una variedad de enfoques heurísticos. Esto es excelente para secretos no estructurados, pero puede requerir ajustes para ajustar la precisión del escaneo.
Detector de palabras clave
Esto ignora el valor secreto y busca nombres de variables que a menudo están asociados con la asignación de secretos con valores codificados. Esto es excelente para cadenas que "no parecen secretas" (por ejemplo, contraseñas le3tc0de), pero puede requerir filtros de ajuste para ajustar la precisión del escaneo.
¿Quieres encontrar un secreto que actualmente no captamos? ¡También puedes (fácilmente) desarrollar tu propio complemento y usarlo con el motor! Para obtener más información, consulte la documentación del complemento.
detect-secrets viene con varios filtros integrados diferentes que pueden satisfacer sus necesidades.
A veces, desea poder permitir globalmente ciertas líneas en su escaneo, si coinciden con un patrón específico. Puede especificar una regla de expresiones regulares como tal:
$ detectar-secretos escaneo --exclude-lines 'contraseña = (bla|falso)'
O puede especificar varias reglas de expresiones regulares como tales:
$ detección de escaneo de secretos --exclude-lines 'contraseña = bla' --exclude-lines 'contraseña = falsa'
A veces, desea poder ignorar ciertos archivos en su análisis. Puede especificar un patrón de expresión regular para hacerlo y, si el nombre del archivo cumple con este patrón de expresión regular, no se escaneará:
$ detectar-escaneo de secretos --excluir-archivos '.*.firma$'
O puede especificar múltiples patrones de expresiones regulares como tales:
$ detección de escaneo de secretos --exclude-files '.*.signature$' --exclude-files '.*/i18n/.*'
A veces, desea poder ignorar ciertos valores secretos en su análisis. Puede especificar una regla de expresiones regulares como tal:
$ detectar-secretos escaneo --exclude-secrets '(fakesecret|${.*})'O puede especificar varias reglas de expresiones regulares como tales:
$ detección de escaneo de secretos --exclude-secrets 'fakesecret' --exclude-secrets '${.*})'A veces, desea aplicar una exclusión a una línea específica, en lugar de excluirla globalmente. Puede hacerlo con una lista de permitidos en línea como tal:
API_KEY = 'esto-normalmente-ser-detectado-por-un-complemento' # pragma: secreto de la lista permitida
Estos comentarios se admiten en varios idiomas. p.ej
const GoogleCredentialPassword = "algo-secreto-aquí"; // pragma: secreto de lista permitida
También puedes utilizar:
# pragma: lista de permitidos siguiente línea secretAPI_KEY = 'WillAlsoBeIgnored'
Esta puede ser una manera conveniente de ignorar secretos, sin necesidad de regenerar toda la línea base nuevamente. Si necesita buscar explícitamente estos secretos incluidos en la lista permitida, también puede hacer lo siguiente:
$ detección de escaneo de secretos --solo en lista permitida
¿Quiere escribir más lógica personalizada para filtrar falsos positivos? Vea cómo hacer esto en nuestra documentación de filtros.
El indicador --exclude-secrets le permite especificar reglas de expresiones regulares para excluir valores secretos. Sin embargo, si desea especificar una lista grande de palabras, puede usar la marca --word-list .
Para utilizar esta función, asegúrese de instalar el paquete pyahocorasick o simplemente utilice:
$ pip instalar detectar-secretos[lista_palabras]
Entonces, puedes usarlo como tal:
$ gato lista de palabras.txt no es un secreto real $ gato muestra.ini contraseña = not-a-real-secret# Mostrará resultados$ detect-secrets scan sample.ini# No se encontraron resultados$ detect-secrets scan --word-list wordlist.txt
El detector de galimatías es un modelo de aprendizaje automático simple que intenta determinar si un valor secreto es realmente un galimatías, asumiendo que los valores secretos reales no se parecen a palabras.
Para utilizar esta función, asegúrese de instalar el paquete gibberish-detector o utilice:
$ pip instalar detectar-secretos[galimatías]
Consulte el paquete detector de galimatías para obtener más información sobre cómo entrenar el modelo. Se incluirá un modelo previamente entrenado (sembrado mediante el procesamiento de RFC) para facilitar su uso.
También puedes especificar tu propio modelo como tal:
$ detectar-escaneo de secretos --gibberish-model custom.model
Este no es un complemento predeterminado, dado que ignorará secretos como password .
Esto no pretende ser una solución segura para evitar que los secretos entren en el código base. Sólo una educación adecuada para desarrolladores puede realmente lograr eso. Este gancho de confirmación previa simplemente implementa varias heurísticas para tratar de prevenir casos obvios de comisión de secretos.
Cosas que no se podrán prevenir:
Secretos multilínea
Contraseñas predeterminadas que no activan KeywordDetector (por ejemplo, login = "hunter2" )
"No se detectó el repositorio de git". Se encontró una advertencia, aunque estoy en un repositorio de git.
Verifique si su versión git es >= 1.8.5. De lo contrario, actualícelo y vuelva a intentarlo. Más detalles aquí.
detect-secrets audit muestra "¡No es un archivo de referencia válido!" después de crear la línea de base.
Asegúrese de que la codificación del archivo de referencia sea UTF-8. Más detalles aquí.
