============= git-secrets ============= ------------------------------------------------------------------------------------------- Предотвращает добавление паролей и других конфиденциальных данных в гит-репозиторий. ------------------------------------------------------------------------------------------- .. contents:: Содержание :depth: 2 Синтаксис ---------- :: git secrets --scan [-r|--recursive] [--cached] [--no-index] [--untracked] [...] git secrets --scan-history git secrets --install [-f|--force] [] git secrets --list [--глобальный] git secrets --add [-a|--разрешено] [-l|--литерал] [--глобальный] git secrets --add-provider [--глобальный] [аргументы...] git secrets --register-aws [--глобальный] git secrets --aws-provider [] Описание -------- Команда ``git secrets`` сканирует коммиты, сообщения к ним и слияния ``--no-ff``, чтобы предотвратить добавление секретной информации в ваши гит-репозитории. Если какой-либо коммит, сообщение к нему или любой коммит в истории слияний ``--no-ff`` совпадает с одним из ваших запрещённых регулярных выражений, то этот коммит будет отклонён. Установка git-secrets --------------------- Для использования команды ``git secrets`` её необходимо установить в путь, доступный для ``git`` при выполнении команды ``git secrets``. *nix (Linux/macOS) ~~~~~~~~~~~~~~~~~~ Вы можете использовать цель ``install`` в предоставленном Makefile для установки ``git secrets`` и страницы справки. Вы можете настроить путь установки с помощью переменных PREFIX и MANPREFIX.:: make install Windows ~~~~~~~ Запустите предоставленный PowerShell-скрипт ``install.ps1``. Это скопирует необходимые файлы в директорию установки (по умолчанию ``%USERPROFILE%/.git-secrets``) и добавит эту директорию в текущий путь пользователя ``PATH``. :: PS > ./install.ps1 Homebrew (для пользователей macOS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: brew install git-secrets .. warning:: **Вы еще не закончили! Вам НЕОБХОДИМО установить хук для каждого репозитория, который вы хотите использовать с** ``git secrets --install``. Вот пример того, как гарантировать, что каждый коммит в вашем репозитории проверяется на наличие секретной информации: :: cd /путь/до/моего/репозитория git secrets --install git secrets --register-aws Расширенная конфигурация ------------------------ Добавьте шаблон конфигурации, если вы хотите добавить хуки ко всем репозиториям, которые вы будете инициализировать или клонировать в будущем. :: git secrets --register-aws --global Добавьте хуки ко всем вашим локальным репозиториям. :: git secrets --install ~/.git-templates/git-secrets git config --global init.templateDir ~/.git-templates/git-secrets Добавьте пользовательских провайдеров для сканирования за данными безопасности. :: git secrets --add-provider -- cat /path/to/secret/file/patterns Перед публикацией репозитория ----------------------------- С помощью git-secrets также можно просканировать репозиторий вместе со всеми его версиями: :: git secrets --scan-historyПараметры --------- Режимы операции ~~~~~~~~~~~~~~~ Каждый из этих параметров должен появляться первым в командной строке. ``--install`` Устанавливает хуки Git для репозитория. Как только хуки установлены для репозитория Git, коммиты и слияния, которые не являются быстрыми, будут запрещены от помещения секретов. ``--scan`` Сканирует один или несколько файлов для секретов. Когда файл содержит секрет, соответствующий текст из файла, который сканируется, будет записан в стандартный вывод, а сценарий завершится с ненулевым статусом. Каждая соответствующая строка будет записана с именем файла, которое соответствует, двоеточием, номером строки, которая соответствует, двоеточием, и затем строкой текста, которая соответствует. Если файлы не указаны, все файлы, возвращаемые ``git ls-files``, будут сканироваться. ``--scan-history`` Сканирует репозиторий вместе со всеми его версиями. Когда файл содержит секрет, соответствующий текст из файла, который сканируется, будет записан в стандартный вывод, а сценарий завершится с ненулевым статусом. Каждая соответствующая строка будет записана с именем файла, которое соответствует, двоеточием, номером строки, которая соответствует, двоеточием, и затем строкой текста, которая соответствует. ``--list`` Выводит конфигурацию ``git-secrets`` для текущего репозитория или глобальной конфигурации Git.``--add`` Добавляет запрещённый или допустимый шаблон. ``--add-provider`` Регистрирует провайдера секретов. Провайдеры секретов — это исполняемые файлы, которые при вызове выводят запрещённые шаблоны, которые ``git-secrets`` должен рассматривать как запрещённые. ``--register-aws`` Добавляет общие шаблоны AWS в конфигурацию Git и гарантирует, что ключи, присутствующие в ``~/.aws/credentials``, не найдутся ни в одном коммите. Добавлены следующие проверки: - AWS Access Key IDs через ``(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}`` - Назначение AWS Secret Access Key через ":" или "=" с возможной окрестностью кавычками - Назначение AWS Account ID через ":" или "=" с возможной окрестностью кавычками - Допустимые шаблоны для примера AWS ключей (``AKIAIOSFODNN7EXAMPLE`` и ``wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY``) - Знаменитые учётные данные из ``~/.aws/credentials`` .. note:: Хотя шаблоны, зарегистрированные этой командой, должны поймать большинство случаев AWS учётных данных, эти шаблоны **не гарантируют**, что они будут пойманы **все**. ``git-secrets`` следует использовать как дополнительный способ страхования — вам всё равно нужно сделать свою должную работу, чтобы убедиться, что вы не коммитируете учётные данные в репозиторий. ``--aws-provider`` Провайдер секретов, который выводит учётные данные, найденные в INI-файле. Вы можете дополнительно предоставить путь к INI-файлу.Параметры для ``--install`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``-f, --force`` Переопределяет существующие хуки, если они присутствуют. ```` Когда предоставлен, устанавливает git-хуки в указанный каталог. Текущий каталог считается целевым, если ```` не указан. Если предоставленный ```` не находится в git-репозитории, каталог будет создан, а хуки будут помещены в ``/hooks``. Это может быть полезно для создания git-шаблонных директорий с помощью команды ``git init --template ``. Вы можете запустить ``git init`` в уже инициализированном репозитории. Из документации ``git init``: По документации git: запуск ``git init`` в уже существующем репозитории безопасен. Он не перезапишет уже существующие данные. Основная причина повторного запуска ``git init`` заключается в том, чтобы получить новые шаблоны (или переместить репозиторий в другое место, если используется параметр ``--separate-git-dir``). В следующих git-хуках производится установка: 1. ``pre-commit``: Используется для проверки, используются ли запрещённые шаблоны в файлах, изменённых в коммите. 2. ``commit-msg``: Используется для проверки, содержится ли запрещённый шаблон в сообщении коммита. 3. ``prepare-commit-msg``: Используется для проверки, будет ли слияние коммита вносить историю, содержащую запрещённый шаблон в любом месте. Обратите внимание, что этот хук вызывается только для слияний, не являющихся быстрыми последовательностями. .. note:: Git позволяет выполнить только один скрипт на каждый хук. Если в репозитории присутствуют субдиректории, стилизованные под Debian, такие как ``pre-commit.d`` и ``commit-msg.d``, то гит-хуки будут установлены в эти директории, что предполагает, что вы настроили соответствующие хуки для выполнения всех скриптов, найденных в этих директориях. Если эти поддиректории гита отсутствуют, то гит-хуки будут установлены в директорию ``.git/hooks`` репозитория гита. Примеры ^^^^^^^ Установка гит-хуков в текущую директорию: .. code-block:: bash cd /путь/к/моему/репозиторию git secrets --install Установка гит-хуков в другой репозиторий кроме текущего директория: .. code-block:: bash git secrets --install /путь/к/моему/репозиторию Создание шаблона гита, содержащего ``git-secrets``, а затем копирование этого шаблона в репозиторий гита: .. code-block:: bash git secrets --install ~/.git-templates/git-secrets git init --template ~/.git-templates/git-secrets Перезапись существующих хуков при наличии: .. code-block:: bash git secrets --install -f Параметры для ``--scan`` ~~~~~~~~~~~~~~~~~~~~~~~~ ``-r, --recursive`` Рекурсивное сканирование указанных файлов. Если встречается директория, она будет сканироваться. Если параметр ``-r`` не указан, директории будут игнорироваться. Параметр ``-r`` не может использоваться вместе с параметрами ``--cached``, ``--no-index`` или ``--untracked``. ``--cached`` Поиск бинарных данных, зарегистрированных в файле индекса.``--no-index`` Поиск файлов в текущей директории, которая не управляется Git. ``--untracked`` В дополнение к поиску в отслеживаемых файлах рабочего дерева, параметр ``--scan`` также выполняет поиск в непотребляемых файлах. ``...`` Путь к одному или более файлам на диске для сканирования секретов. Если пути к файлам не указаны, все файлы, возвращённые командой ``git ls-files``, будут сканироваться. Примеры ^^^^^^^ Сканирование всех файлов в репозитории:: git secrets --scan Сканирование одного файла для поиска секретов:: git secrets --scan /путь/к/файлу Рекурсивное сканирование директории для поиска секретов:: git secrets --scan -r /путь/к/директории Сканирование нескольких файлов для поиска секретов:: git secrets --scan /путь/к/файлу /путь/к/другому/файлу Вы можете выполнять сканирование путём использования маскирования файлов:: git secrets --scan /путь/к/директории/* Сканирование из стандартного ввода:: echo 'привет!' | git secrets --scan - Параметры для ``--list`` ~~~~~~~~~~~~~~~~~~~~~~~~ ``--global`` Отображает конфигурацию git-secrets в глобальном конфиге Git. Параметры для ``--add`` ~~~~~~~~~~~~~~~~~~~~~~~ ``--global`` Добавляет шаблоны в глобальный конфиг Git ``-l, --literal`` Экранирует специальные символы регулярных выражений в предоставленном шаблоне, чтобы шаблон был найден буквально.``-a, --allowed`` Определяет шаблон как допустимый вместо запрещённого. Допустимые шаблоны используются для отсеивания ложноположительных срабатываний.```` Шаблон регулярного выражения для поиска. Примеры ^^^^^^^^ Добавление запрещенного шаблона в текущий репозиторий: :: git secrets --add '[A-Z0-9]{20}' Добавление запрещенного шаблона в глобальный конфиг Git: :: git secrets --add --global '[A-Z0-9]{20}' Добавление строки, которая будет искаться буквально (``+`` экранирована): :: git secrets --add --literal 'foo+bar' Добавление допустимого шаблона: :: git secrets --add -a 'allowed pattern' Параметры для ``--register-aws`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``--global`` Добавляет специфичные для AWS переменные конфигурации в глобальный конфиг Git. Параметры для ``--aws-provider`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``[]`` Если указан, указывает настраиваемый путь до INI файла для сканирования. Если не указан, считается что используется ``~/.aws/credentials``. Параметры для ``--add-provider`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``--global`` Добавляет провайдера в глобальный конфиг Git. ```` Команда провайдера для вызова. При вызове команды ожидается, что она выведет запрещенные шаблоны через новые строки на стандартный вывод. Любые дополнительные аргументы передаются команде. Примеры ^^^^^^^^ Регистрация секретного провайдера с аргументами: :: git secrets --add-provider -- git secrets --aws-provider Извлечение секретов из файла: :: git secrets --add-provider -- cat /path/to/secret/file/patterns Определение запрещенных шаблонов ---------------------------------Шаблоны регулярных выражений, совместимых с ``egrep``, используются для определения, включает ли коммит или сообщение к нему какие-либо запрещённые шаблоны. Эти регулярные выражения определены с помощью команды ``git config``. Важно отметить, что различные системы используют различные версии ``egrep``. Например, при работе на macOS используется другая версия ``egrep``, чем при работе на системах типа Ubuntu (BSD против GNU). Вы можете добавить запрещённые шаблоны регулярных выражений в ваш конфиг git с помощью команды ``git secrets --add ``. Игнорирование ложноположительных срабатываний --------------------------------------------- Когда-то регулярное выражение может совпасть с ложноположительными значениями. Например, SHA коммитов Git очень похожи на ключи доступа AWS. Вы можете указать множество различных шаблонов регулярных выражений как ложноположительные с помощью следующей команды: :: git secrets --add --allowed 'моё регулярное выражение' Вы также можете добавить шаблоны регулярных выражений для фильтрации ложноположительных значений в файл ``.gitallowed``, расположенный в корневой директории репозитория. Строки, начинающиеся с ``#``, пропускаются (строка комментария), а пустые строки тоже пропускаются.Сначала `git-secrets` извлекает все строки из файла, содержащие запрещённое совпадение. Включаются полные пути к имени файла, которое было совпадено, за которым следует символ ``:``, затем номер строки, который был совпадён, а затем вся строка из файла, которая была совпавшей шаблоном секрета. Затем, если вы определили допустимые регулярные выражения, `git-secrets` проверяет, чтобы убедиться, что все совпавшие строки совпадают хотя бы с одним из зарегистрированных вами допустимых регулярных выражений. Если все строки, отмеченные как секреты, аннулируются допустимым совпадением, то объектный текст не содержит никаких секретов. Если любая из совпавших строк не совпадает с допустимым регулярным выражением, тогда `git-secrets` завершит коммит/слияние/сообщение об ошибке... important:: Также как плохая практика — добавление слишком жадных запрещённых шаблонов, это также плохая практика добавлять слишком щедрые допустимые шаблоны. Убедитесь, что протестировали свои шаблоны с помощью случайных вызовов к ``git secrets --scan $filename``, чтобы убедиться, что они работают так, как задумано. Поставщики секретов -------------------- Когда вам требуется проверить точное совпадение шаблона против набора известных секретов. Например, вы можете захотеть убедиться, что никакие учетные данные, присутствующие в ``~/.aws/credentials``, никогда не появятся в коммите. В таких случаях лучше хранить эти секреты в одном месте, а не распределять их по различным репозиториям Git в конфигах Git. Вы можете использовать "поставщиков секретов", чтобы получить такие типы учетных данных. Поставщик секретов — это исполняемый файл, который при вызове выводит запрещённые шаблоны, разделённые новыми строками. Вы можете добавить поставщики секретов с помощью команды ``--add-provider``: .. code-block:: bash git secrets --add-provider -- git secrets --aws-provider Обратите внимание на использование ``--``. Это гарантирует, что любые аргументы, связанные с поставщиком, передаются поставщику каждый раз при вызове его для сканирования секретов. Пример пошагового руководства ------------------------------ Рассмотрим пример. Учитывая следующий текст темы (хранящийся в ``/tmp/example``): Это тест! password=ex@mplepassword password=****** Больше тест... И следующие зарегистрированные шаблоны: :: git secrets --add 'password\\\s*=\\\s*.+' git secrets --add --allowed --literal 'ex@mplepassword' Запустив ``git secrets --scan /tmp/example``, результат будет следующим выводом ошибок: :: /tmp/example:3:password=****** [ОШИБКА] Соответствие запрещенному шаблону Возможные решения: - Отмечайте ложноположительные случаи как разрешенные с помощью: git config --add secrets.allowed ... - Перечислите ваши конфигурируемые шаблоны: git config --get-all secrets.patterns - Перечислите ваши конфигурируемые разрешенные шаблоны: git config --get-all secrets.allowed - Используйте --no-verify, если это единичный случай ложноположительного результата Разобрав это подробнее, запрещенный шаблон значений ``password\\\s*=\\\s*.+`` будет соответствовать следующим строкам: :: /tmp/example:2:password=ex@mplepassword /tmp/example:3:password=****** ...Но первое соответствие будет отфильтровано из-за того, что оно соответствует разрешенному регулярному выражению ``ex@mplepassword``. Поскольку остается еще одна строка, которая не соответствует, она считается секретом. Поскольку соответствующие строки находятся на строках, начинающихся с имени файла и номера строки (например, ``/tmp/example:3:...``), вы можете создать разрешенные шаблоны, которые учитывают имена файлов и номера строк в регулярном выражении. Например, вы можете белый список весь файл с помощью чего-то вроде этого::: git secrets --add --allowed '/tmp/example:.*' git secrets --scan /tmp/example && echo $? # Выводит: 0 Альтернативно, вы можете разрешить конкретную строку файла, если эта строка маловероятна к изменениям, используя что-то вроде следующего: :: git secrets --add --allowed '/tmp/example:3:.*' git secrets --scan /tmp/example && echo $? # Выводит: 0 Учитывайте это при создании допустимых шаблонов, чтобы гарантировать, что ваши допустимые шаблоны не будут случайно совпадать из-за того, что имя файла включено в текст субъекта, против которого проверяются допустимые шаблоны. Пропуск проверки ----------------- Используйте опцию ``--no-verify`` в случае ложноположительного совпадения в коммите, слиянии или сообщении о коммите. Это пропустит выполнение хука git и позволит вам сделать коммит или слияние. О проекте ---------- - Автор: `Майкл Даулинг `_ - Трекер ошибок: Исходный код и трекер ошибок этого проекта можно найти по адресу `https://github.com/awslabs/git-secrets `_ - Благодарность за предоставленные предложения и отзывы выражается Адриану Вачински и Ари Юэлсу из Корнеллского университета. Авторское право © 2015 Amazon.com, Inc. или его аффилированные общества. Все права защищены.