detect secrets
v1.5.0
detect-secrets é um módulo apropriadamente nomeado para (surpresa, surpresa) detectar segredos dentro de uma base de código.
No entanto, ao contrário de outros pacotes semelhantes que se concentram apenas na descoberta de segredos, este pacote foi projetado tendo o cliente corporativo em mente: fornecendo um meio sistemático e compatível com versões anteriores de:
Impedindo que novos segredos entrem na base de código,
Detectar se tais prevenções são explicitamente ignoradas e
Fornecendo uma lista de verificação de segredos para rolar e migrar para um armazenamento mais seguro.
Dessa forma, você cria uma separação de preocupações: aceitando que atualmente pode haver segredos escondidos em seu grande repositório (isso é o que chamamos de linha de base ), mas evitando que esse problema se torne ainda maior, sem lidar com o esforço potencialmente gigantesco de afastar os segredos existentes.
Ele faz isso executando resultados diff periódicos em declarações regex elaboradas heuristicamente, para identificar se algum novo segredo foi confirmado. Dessa forma, evita-se a sobrecarga de vasculhar todo o histórico do git, bem como a necessidade de verificar todo o repositório todas as vezes.
Para ver as mudanças recentes, consulte CHANGELOG.md.
Se você deseja contribuir, consulte CONTRIBUTING.md.
Para documentação mais detalhada, verifique nossa outra documentação.
Crie uma linha de base de segredos potenciais encontrados atualmente em seu repositório git.
$ detecção de segredos > .secrets.baseline
ou, para executá-lo em um diretório diferente:
$ detect-secrets -C /caminho/para/varredura de diretório > /caminho/para/diretório/.secrets.baseline
Verificando arquivos rastreados não git:
$ detect-secrets scan test_data/ --all-files > .secrets.baseline
Isso verificará novamente sua base de código e:
Atualize/atualize sua linha de base para ser compatível com a versão mais recente,
Adicione quaisquer novos segredos encontrados à sua linha de base,
Remova quaisquer segredos que não estejam mais em sua base de código
Isso também preservará todos os segredos rotulados que você possui.
$ detect-secrets scan --baseline.secrets.baseline
Para linhas de base anteriores à versão 0.9, basta recriá-las.
Verificando apenas arquivos preparados:
$ git diff --staged --name-only -z | xargs -0 detect-secrets-hook --baseline.secrets.baseline
Verificando todos os arquivos rastreados:
$ git ls-arquivos -z | xargs -0 detect-secrets-hook --baseline.secrets.baseline
$ detect-secrets scan --list-all-plugins Detector de artefato AWSKeyDetector AzureStorageKeyDetector BasicAuthDetector Detector de nuvem DiscordBotTokenDetector GitHubTokenDetector GitLabTokenDetector Base64HighEntropyString HexHighEntropyString IBMCloudIamDetector IbmCosHmacDetector IPPublicDetector JwtTokenDetector Detector de palavras-chave MailchimpDetector Detector Npm OpenAIDetector Detector de chave privada Detector PypiToken SendGridDetector SlackDetector Detector de camada suave SquareOAuthDetector StripeDetector TelegramBotTokenDetector TwilioKeyDetector
$ detect-secrets scan --disable-plugin KeywordDetector --disable-plugin AWSKeyDetector
Se quiser executar apenas um plugin específico, você pode fazer:
$ detect-secrets scan --list-all-plugins |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs detecta segredos verificando test_dataEsta é uma etapa opcional para rotular os resultados em sua linha de base. Ele pode ser usado para restringir sua lista de verificação de segredos para migrar ou para configurar melhor seus plug-ins para melhorar sua relação sinal-ruído.
$ auditoria de detecção de segredos .secrets.baseline
Uso Básico:
de detect_secrets importar SecretsCollectionde detect_secrets.settings importar default_settingssecrets = SecretsCollection() com default_settings():secrets.scan_file('test_data/config.ini')import jsonprint(json.dumps(secrets.json(), indent=2))Configuração mais avançada:
from detect_secrets import SecretsCollectionfrom detect_secrets.settings import transient_settingssecrets = SecretsCollection()with transient_settings({# Execute verificações apenas com esses plug-ins.# Este formato é o mesmo que é salvo na linha de base gerada.'plugins_used': [# Exemplo de configurar um plugin integrado{'name': 'Base64HighEntropyString','limit': 5.0,
},# Exemplo de uso de um plugin personalizado{'name': 'HippoDetector','path': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
},
],# Também podemos especificar quaisquer filtros adicionais que desejarmos.# Este é um exemplo de uso da função `is_identified_by_ML_model` dentro do# arquivo local `./private-filters/example.py`.'filters_used': [
{'caminho': 'arquivo://filtros privados/example.py::é_identificado_por_ML_model',
},
]
}) como configurações:# Se quisermos fazer mais ajustes no objeto de configurações criado (por exemplo# desabilitando filtros padrão), podemos fazê-lo como tal.settings.disable_filters('detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign','detect_secrets .filtros.heurística.é_provavelmente_id_string',
)secrets.scan_file('test_data/config.ini')$ pip instalar detectar segredos ?
Instale via brew:
$ brew install detectar segredos
detect-secrets vem com três ferramentas diferentes e muitas vezes há confusão sobre qual delas usar. Use esta lista de verificação útil para ajudá-lo a decidir:
Você deseja adicionar segredos à sua linha de base? Nesse caso, use detect-secrets scan .
Você deseja alertar sobre novos segredos que não estão na linha de base? Nesse caso, use detect-secrets-hook .
Você está analisando a linha de base em si? Nesse caso, use 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 isso como um gancho de pré-confirmação. Uma maneira de fazer isso é usando a estrutura de pré-commit:
# .pre-commit-config.yamlrepos:
- repositório: https://github.com/Yelp/detect-secretsrev: v1.5.0hooks:
- id: detect-secretsargs: ['--baseline', '.secrets.baseline']excluir: package.lock.jsonHá momentos em que queremos excluir um falso positivo do bloqueio de um commit, sem criar uma linha de base para fazer isso. Você pode fazer isso adicionando um comentário como tal:
secret = "hunter2" # pragma: segredo da lista de permissões
ou
// pragma: lista de permissões nextline secretconst secret = "hunter2";
$ detectar-segredos auditoria --help
uso: auditoria de detecção de segredos [-h] [--diff] [--stats]
[--relatório] [--apenas-real | --apenas-falso]
[--json]
nome do arquivo [nome do arquivo ...]
Auditar uma linha de base permite que os analistas rotulem os resultados e otimizem plug-ins para obter a maior relação sinal-ruído para seu ambiente.
argumentos posicionais:
nome do arquivo Auditar um determinado arquivo de linha de base para distinguir a diferença
entre falsos e verdadeiros positivos.
argumentos opcionais:
-h, --help mostra esta mensagem de ajuda e sai
--diff Permite a comparação de dois arquivos de linha de base, para
distinguir efetivamente a diferença entre vários plugins
configurações.
--stats Exibe os resultados de uma sessão de auditoria interativa que
foram salvos em um arquivo de linha de base.
--report Exibe um relatório com os segredos detectados
relatórios:
Exiba um resumo com todas as descobertas e as decisões tomadas. Para ser usado com o modo de relatório (--report).
--only-real Inclui apenas segredos reais no relatório
--only-false Inclui apenas falsos positivos no relatório
análise:
Quantifique o sucesso de seus plug-ins com base nos resultados rotulados em seu
linha de base. Para ser usado com o modo estatístico (--stats).
--json As saídas resultam em um formato legível por máquina.Esta ferramenta opera através de um sistema de plugins e filtros .
Plugins encontram segredos no código
Os filtros ignoram falsos positivos para aumentar a precisão da verificação
Você pode ajustar ambos para atender às suas necessidades de precisão/recuperação.
Existem três estratégias diferentes que empregamos para tentar encontrar segredos no código:
Regras baseadas em Regex
Este é o tipo de plugin mais comum e funciona bem com segredos bem estruturados. Opcionalmente, esses segredos podem ser verificados, o que aumenta a precisão da digitalização. No entanto, depender apenas deles pode afetar negativamente a recuperação da sua digitalização.
Detector de entropia
Isso procura strings de "aparência secreta" por meio de uma variedade de abordagens heurísticas. Isso é ótimo para segredos não estruturados, mas pode exigir ajustes para ajustar a precisão da digitalização.
Detector de palavras-chave
Isso ignora o valor do segredo e procura nomes de variáveis que são frequentemente associados à atribuição de segredos com valores codificados. Isso é ótimo para strings "que não parecem secretas" (por exemplo, senhas le3tc0de), mas pode exigir filtros de ajuste para ajustar a precisão da varredura.
Quer encontrar um segredo que ainda não descobrimos? Você também pode (facilmente) desenvolver seu próprio plugin e usá-lo com o mecanismo! Para mais informações, verifique a documentação do plugin.
detect-secrets vem com vários filtros integrados diferentes que podem atender às suas necessidades.
Às vezes, você deseja permitir globalmente determinadas linhas em sua digitalização, se elas corresponderem a um padrão específico. Você pode especificar uma regra regex da seguinte forma:
$ detect-secrets scan --exclude-lines 'senha = (blá | falso)'
Ou você pode especificar várias regras de regex como estas:
$ detect-secrets scan --exclude-lines 'senha = blá' --exclude-lines 'senha = falso'
Às vezes, você deseja ignorar determinados arquivos em sua verificação. Você pode especificar um padrão regex para fazer isso e, se o nome do arquivo atender a esse padrão regex, ele não será verificado:
$ detect-secrets scan --exclude-files '.*.signature$'
Ou você pode especificar vários padrões regex como:
$ detect-secrets scan --exclude-files '.*.signature$' --exclude-files '.*/i18n/.*'
Às vezes, você deseja ignorar certos valores secretos em sua verificação. Você pode especificar uma regra regex da seguinte forma:
$ detect-secrets scan --exclude-secrets '(fakesecret|${.*})'Ou você pode especificar várias regras de regex como estas:
$ detect-secrets scan --exclude-secrets 'fakesecret' --exclude-secrets '${.*})'Às vezes, você deseja aplicar uma exclusão a uma linha específica, em vez de excluí-la globalmente. Você pode fazer isso com a lista de permissões in-line da seguinte forma:
API_KEY = 'isto-normalmente-será-detectado-por-um-plugin' # pragma: segredo da lista de permissões
Esses comentários são suportados em vários idiomas. por exemplo
const GoogleCredentialPassword = "algo secreto aqui"; // pragma: segredo da lista de permissões
Você também pode usar:
# pragma: lista de permissões nextline secretAPI_KEY = 'WillAlsoBeIgnored'
Essa pode ser uma maneira conveniente de ignorar segredos, sem precisar regenerar toda a linha de base novamente. Se precisar pesquisar explicitamente esses segredos permitidos, você também pode fazer:
$ detect-secrets scan --only-allowlisted
Quer escrever mais lógica personalizada para filtrar falsos positivos? Confira como fazer isso em nossa documentação de filtros.
O sinalizador --exclude-secrets permite especificar regras de regex para excluir valores secretos. No entanto, se você quiser especificar uma lista grande de palavras, poderá usar o sinalizador --word-list .
Para usar esse recurso, certifique-se de instalar o pacote pyahocorasick ou simplesmente use:
$ pip instalar detectar-segredos[lista_palavras]
Então, você pode usá-lo como tal:
$ lista de palavras de gato.txt não é um segredo real $ gato amostra.ini password = not-a-real-secret# Mostrará resultados$ detect-secrets scan sample.ini# Nenhum resultado encontrado$ detect-secrets scan --word-list wordlist.txt
O Gibberish Detector é um modelo de ML simples, que tenta determinar se um valor secreto é realmente algo sem sentido, com a suposição de que os valores secretos reais não são semelhantes a palavras.
Para usar esse recurso, certifique-se de instalar o pacote gibberish-detector ou use:
$ pip install detectar-segredos[algaraviada]
Confira o pacote gibberish-detector para obter mais informações sobre como treinar o modelo. Um modelo pré-treinado (semeado pelo processamento de RFCs) será incluído para facilitar o uso.
Você também pode especificar seu próprio modelo como tal:
$ detect-secrets scan --gibberish-model custom.model
Este não é um plugin padrão, visto que irá ignorar segredos como password .
Isso não pretende ser uma solução infalível para evitar que segredos entrem na base de código. Somente a educação adequada do desenvolvedor pode realmente fazer isso. Este gancho de pré-confirmação apenas implementa várias heurísticas para tentar evitar casos óbvios de confirmação de segredos.
Coisas que não serão evitadas:
Segredos multilinhas
Senhas padrão que não acionam o KeywordDetector (por exemplo, login = "hunter2" )
"Não foi detectado o repositório git." aviso encontrado, mesmo que eu esteja em um repositório git.
Verifique se sua versão git é >= 1.8.5. Caso contrário, atualize-o e tente novamente. Mais detalhes aqui.
detect-secrets audit exibe "Não é um arquivo de linha de base válido!" depois de criar a linha de base.
Certifique-se de que a codificação do arquivo de linha de base seja UTF-8. Mais detalhes aqui.
