detect secrets
v1.5.0
detect-secrets — это модуль с удачным названием для (сюрприз-сюрприз) обнаружения секретов в базе кода.
Однако, в отличие от других подобных пакетов, ориентированных исключительно на поиск секретов, этот пакет разработан с учетом потребностей корпоративных клиентов: он предоставляет обратно совместимые систематические средства:
Предотвращение попадания новых секретов в кодовую базу,
Обнаружение того, что такие предупреждения явно обойдены, и
Предоставление контрольного списка секретов, которые нужно развернуть и перенести в более безопасное хранилище.
Таким образом, вы создаете разделение задач: признаете, что в настоящее время в вашем большом репозитории могут скрываться секреты (это то, что мы называем базовым уровнем ), но не допускаете увеличения этой проблемы, не прибегая к потенциально гигантским усилиям. удаления существующих секретов.
Он делает это путем периодической обработки результатов сравнения с эвристически созданными выражениями регулярных выражений, чтобы определить, был ли зафиксирован какой-либо новый секрет. Таким образом, можно избежать накладных расходов на копание всей истории git, а также необходимости каждый раз сканировать весь репозиторий.
Чтобы ознакомиться с последними изменениями, посетите CHANGELOG.md.
Если вы хотите внести свой вклад, посетите CONTRIBUTING.md.
Для получения более подробной документации ознакомьтесь с другой нашей документацией.
Создайте базовый список потенциальных секретов, которые в настоящее время находятся в вашем репозитории git.
$ сканирование секретов обнаружения > .secrets.baseline
или, чтобы запустить его из другого каталога:
$ обнаружения-секреты -C /путь/к/каталогу сканирование > /путь/к/каталогу/.secrets.baseline
Сканирование файлов, не отслеживаемых git:
$Detect-secrets scan test_data/ --all-files > .secrets.baseline
Это приведет к повторному сканированию вашей кодовой базы и:
Обновите/обновите базовую версию, чтобы она была совместима с последней версией,
Добавляйте любые новые секреты, которые он находит, в свой базовый уровень,
Удалите все секреты, которых больше нет в вашей кодовой базе.
Это также сохранит все имеющиеся у вас помеченные секреты.
$ обнаружить-секреты сканирования --baseline .secrets.baseline
Для базовых показателей старше версии 0.9 просто создайте их заново.
Сканирование только подготовленных файлов:
$ git diff --staged --name-only -z | xargs -0 обнаружить-секреты-хук --baseline .secrets.baseline
Сканирование всех отслеживаемых файлов:
$ git ls-files -z | xargs -0 обнаружить-секреты-хук --baseline .secrets.baseline
$ обнаружить-секреты сканирования --list-all-plugins ArtifactoryDetector AWSKeyDetector AzureStorageKeyDetector Базовыйдетектор аутентификации CloudantDetector DiscordBotTokenDetector GitHubTokenDetector GitLabTokenDetector Base64HighEntropyString HexHighEntropyString IBMCloudIamDetector IBMCosHmacDetector IPpublicDetector JwtTokenDetector Детектор ключевых слов MailchimpDetector Нпмдетектор OpenAIDetector Детектор приватных ключей PypiTokenDetector Отправитьгриддетектор SlackDetector SoftlayerDetector SquareOAuthDetector Полосовой детектор TelegramBotTokenDetector TwilioKeyDetector
$ обнаружить-секреты сканирования --disable-plugin KeywordDetector --disable-plugin AWSKeyDetector
Если вы хотите запустить только определенный плагин, вы можете сделать:
$ обнаружить-секреты сканирования --list-all-plugins |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs сканирование обнаруженных секретов test_dataЭто необязательный шаг для пометки результатов в базовом плане. Его можно использовать для сужения контрольного списка секретов для миграции или для лучшей настройки плагинов для улучшения соотношения сигнал/шум.
$ аудит обнаружения секретов .secrets.baseline
Основное использование:
из обнаружения_секретов импортировать SecretsCollectionиз обнаружения_секретов.settings import default_settingssecrets = SecretsCollection() с default_settings():secrets.scan_file('test_data/config.ini')import jsonprint(json.dumps(secrets.json(), indent=2))Более продвинутая конфигурация:
fromDetect_secrets import SecretsCollectionfromDetect_secrets.settings import transient_settingssecrets = SecretsCollection()with transient_settings({# Запускать сканирование только с этими плагинами.# Этот формат такой же, как тот, который сохраняется в сгенерированном базовом состоянии.'plugins_used': [# Пример настройки встроенного плагина {'name': «Base64HighEntropyString», «предел»: 5,0,
},# Пример использования специального плагина{'name': 'HippoDetector','path': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
},
],# Мы также можем указать любые дополнительные фильтры, которые нам нужны.# Это пример использования функции `is_identified_by_ML_model` в # локальном файле `./private-filters/example.py`.'filters_used': [
{'путь': 'file://private-filters/example.py::is_identified_by_ML_model',
},
]
}) в качестве настроек: # Если мы хотим внести какие-либо дополнительные изменения в созданный объект настроек (например, # отключить фильтры по умолчанию), мы можем сделать это следующим образом.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 детектор-секреты ?
Установить через Brew:
$ Brew install обнаружение секретов
В состав detect-secrets входят три разных инструмента, и часто возникает путаница, какой из них использовать. Используйте этот удобный контрольный список, который поможет вам принять решение:
Хотите добавить секреты в свою базу? Если это так, используйте detect-secrets scan .
Вы хотите предупредить о новых секретах, отсутствующих в базовой версии? Если да, используйтеDetect 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
$ 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
Мы рекомендуем настроить это как перехватчик перед фиксацией. Один из способов сделать это — использовать структуру предварительной фиксации:
# .pre-commit-config.yamlrepos:
- репозиторий: https://github.com/Yelp/detect-secretsrev: v1.5.0hooks:
- id:Detect-secretsargs: ['--baseline', '.secrets.baseline']исключить: package.lock.jsonБывают случаи, когда мы хотим исключить ложное срабатывание из блокировки коммита, не создавая для этого базовый уровень. Вы можете сделать это, добавив комментарий следующим образом:
secret = "hunter2" # pragma: секрет белого списка
или
// прагма: список разрешений nextline secretconst secret = "hunter2";
$ аудит секретов обнаружения --help
использование: аудит обнаружения секретов [-h] [--diff] [--stats]
[--отчет] [--только-реальный | --only-false]
[--json]
имя файла [имя файла ...]
Аудит базового уровня позволяет аналитикам маркировать результаты и оптимизировать плагины для достижения максимального соотношения сигнал/шум для их среды.
позиционные аргументы:
имя_файла Аудит данного базового файла, чтобы определить разницу
между ложными и истинными срабатываниями.
необязательные аргументы:
-h, --help показать это справочное сообщение и выйти
--diff Позволяет сравнивать два базовых файла, чтобы
эффективно различать разницу между различными плагинами
конфигурации.
--stats Отображает результаты интерактивного сеанса аудита, который
были сохранены в базовом файле.
--report Отображает отчет с обнаруженными секретами
отчетность:
Отображение сводки со всеми выводами и принятыми решениями. Используется с режимом отчета (--report).
--only-real Включает в отчет только реальные секреты
--only-false В отчет включаются только ложные срабатывания
аналитика:
Оцените успех ваших плагинов на основе отмеченных результатов в вашем
базовый уровень. Используется с режимом статистики (--stats).
--json Выводит результаты в машиночитаемом формате.Этот инструмент работает через систему плагинов и фильтров .
Плагины находят секреты в коде
Фильтры игнорируют ложные срабатывания, чтобы повысить точность сканирования.
Вы можете настроить оба параметра в соответствии с вашими потребностями в точности и отзыве.
Мы используем три разные стратегии, чтобы попытаться найти секреты в коде:
Правила на основе регулярных выражений
Это наиболее распространенный тип плагинов, который хорошо работает с хорошо структурированными секретами. Эти секреты можно дополнительно проверить, что повышает точность сканирования. Однако зависимость только от них может отрицательно повлиять на запоминание вашего сканирования.
Детектор энтропии
Он ищет «секретные» строки с помощью различных эвристических подходов. Это отлично подходит для неструктурированных секретов, но может потребоваться настройка для регулировки точности сканирования.
Детектор ключевых слов
При этом секретное значение игнорируется и выполняется поиск имен переменных, которые часто связаны с присвоением секретам жестко запрограммированных значений. Это отлично подходит для «не секретных» строк (например, паролей le3tc0de), но может потребоваться настройка фильтров для регулировки точности сканирования.
Хотите узнать секрет, который нам пока не раскрыт? Вы также можете (легко) разработать свой собственный плагин и использовать его с движком! Для получения дополнительной информации ознакомьтесь с документацией плагина.
В состав detect-secrets входит несколько различных встроенных фильтров, которые могут удовлетворить ваши потребности.
Иногда вам нужно иметь возможность глобально разрешать определенные строки при сканировании, если они соответствуют определенному шаблону. Вы можете указать правило регулярного выражения как таковое:
$ обнаружить-секреты сканирования --exclude-lines 'пароль = (бла | подделка)'
Или вы можете указать несколько правил регулярных выражений как таковых:
$ обнаружить-секреты сканирования --exclude-lines 'пароль = бла' --exclude-lines 'пароль = подделка'
Иногда вам нужно иметь возможность игнорировать определенные файлы при сканировании. Для этого вы можете указать шаблон регулярного выражения, и если имя файла соответствует этому шаблону регулярного выражения, оно не будет сканироваться:
$ обнаружить-секреты сканирования --exclude-files '.*.signature$'
Или вы можете указать несколько шаблонов регулярных выражений как таковые:
$ обнаружения-секретов сканирования --exclude-files '.*.signature$' --exclude-files '.*/i18n/.*'
Иногда вам нужно иметь возможность игнорировать определенные секретные значения при сканировании. Вы можете указать правило регулярного выражения как таковое:
$ обнаружения-секретов сканирования --exclude-secrets '(fakesecret|${.*})'Или вы можете указать несколько правил регулярных выражений как таковых:
$ обнаружения-секретов сканирования --exclude-secrets 'fakesecret' --exclude-secrets '${.*})'Иногда требуется применить исключение к конкретной строке, а не исключать ее глобально. Вы можете сделать это с помощью встроенного белого списка:
API_KEY = 'обычно это будет обнаружено плагином' # pragma: секрет белого списка
Эти комментарии поддерживаются на нескольких языках. например
const GoogleCredentialPassword = "что-то-секретное-здесь"; // прагма: секрет белого списка
Вы также можете использовать:
# прагма: список разрешений следующей строки secretAPI_KEY = 'WillAlsoBeIgnored'
Это может быть удобным способом игнорировать секреты без необходимости заново создавать всю базовую структуру. Если вам нужно явно выполнить поиск этих секретов из разрешенного списка, вы также можете сделать:
$ обнаружить-секреты сканирования --only-allowlisted
Хотите написать дополнительную логику для фильтрации ложных срабатываний? Узнайте, как это сделать, в нашей документации по фильтрам.
Флаг --exclude-secrets позволяет указать правила регулярных выражений для исключения секретных значений. Однако, если вы хотите вместо этого указать большой список слов, вы можете использовать флаг --word-list .
Чтобы использовать эту функцию, обязательно установите пакет pyahocorasick или просто используйте:
$ pip install детектив-секреты[word_list]
Затем вы можете использовать его как таковой:
$ кот список слов.txt не настоящий секрет $ кот sample.ini пароль = не-настоящий-секрет# Покажет результаты$ сканирование обнаружения секретов sample.ini# Результаты не найдены$ сканирование обнаружения секретов --word-list wordlist.txt
Детектор тарабарщины — это простая модель машинного обучения, которая пытается определить, является ли секретное значение на самом деле тарабарщиной, при условии, что настоящие секретные значения не похожи на слова.
Чтобы использовать эту функцию, обязательно установите пакет gibberish-detector или используйте:
$ pip installDetect-secrets[тарабарщина]
Ознакомьтесь с пакетом gibberish-detector для получения дополнительной информации о том, как обучать модель. Для удобства использования будет включена предварительно обученная модель (набранная путем обработки RFC).
Вы также можете указать свою собственную модель как таковую:
$ обнаружить-секреты сканирования --gibberish-model custom.model
Это не плагин по умолчанию, поскольку он игнорирует такие секреты, как password .
Это не должно быть надежным решением для предотвращения попадания секретов в кодовую базу. Только правильное образование разработчиков может действительно сделать это. Этот перехватчик перед фиксацией просто реализует несколько эвристик, чтобы попытаться предотвратить очевидные случаи передачи секретов.
Вещи, которые нельзя предотвратить:
Многострочные секреты
Пароли по умолчанию, которые не запускают KeywordDetector (например, login = "hunter2" )
«Не обнаружен репозиторий git». Обнаружено предупреждение, хотя я нахожусь в репозитории git.
Проверьте, является ли ваша версия git >= 1.8.5. Если нет, обновите его и повторите попытку. Более подробная информация здесь.
detect-secrets audit отображает «Недопустимый базовый файл!» после создания базовой линии.
Убедитесь, что кодировка вашего базового файла — UTF-8. Более подробная информация здесь.
