SEDATED

Назначение

Из-за огромного количества изменений кода, необходимых в современной среде CICD, разработчики постоянно отправляют код, который может непреднамеренно содержать конфиденциальную информацию. Такое потенциальное раскрытие конфиденциальных данных представляет собой огромный риск для организаций (2017 OWASP Top Ten #3 — Раскрытие конфиденциальных данных). SEDATED® решает эту проблему, автоматически проверяя все входящие изменения кода и предоставляя разработчику мгновенную обратную связь. Если он обнаруживает конфиденциальные данные, он предотвращает отправку коммита(ов) на Git-сервер.

**ПРИМЕЧАНИЕ: ТОЛЬКО добавляемые или изменяемые строки (начинающиеся с + в файле патча) в отправляемых коммитах сканируются SEDATED®. Удаляемые строки (начинающиеся с - в файле патча) при отправке коммитов НЕ сканируются SEDATED®.

Настройка

1. Клонируйте SEDATED®

git clone https://github.com/OWASP/SEDATED.git

cd SEDATED/

2. Обновите файлы .example

cp /config/whitelists/commit_whitelist.txt.example /config/whitelists/commit_whitelist.txt

cp /config/whitelists/repo_whitelist.txt.example /config/whitelists/repo_whitelist.txt

cp /config/enforced_repos_list.txt.example /config/enforced_repos_list.txt

3. Настройте переменные и функции /config/custom_configs.sh (по желанию)

4. Отправьте SEDATED® с реализацией, специфичной для организации

Отправьте реализацию SEDATED®, специфичную для организации, в нужный Git-репозиторий организации (GitHub, GitLab, Git и т. д.).

5. Укажите pre-receive hook на файл pre-receive.sh от SEDATED®

Инструкции по выполнению этого на экземпляре GitHub Enterprise можно найти в GitHub_Enterprise_Setup.md.

Локальное тестирование

• Настройка GitHub Docker — общие инструкции по настройке docker-контейнера GitHub в качестве Git-сервера с включённым pre-receive hook для локального тестирования.
  • Потребуются некоторые изменения, чтобы SEDATED® работал как задумано.
    • always_reject.sh необходимо заменить на скрипт pre-receive.sh от SEDATED®.
    • Сопутствующие файлы/структуру папок SEDATED® необходимо разместить в том же каталоге или сделать доступными для скрипта pre-receive.sh.
    • Могут также потребоваться некоторые дополнительные настройки, но приведённые выше инструкции — хорошая отправная точка для локального тестирования.

Описания файлов

pre-receive.sh

• Сердце и душа SEDATED®.
• Скрипт pre-receive Git hook от SEDATED®, используемый вместе с регулярными выражениями SEDATED® (config/regexes.json), определяет добавляемые или изменяемые строки кода, отправляемые в Git-экземпляр, которые содержат захардкоженные учётные данные/конфиденциальные данные (как определено в config/regexes.json), и предотвращает отправку, ЕСЛИ найдены строки, содержащие захардкоженные учётные данные/конфиденциальные данные.

/config/custom_configs.sh

• Файл пользовательских конфигураций SEDATED®, используемый вместе с pre-receive.sh, позволяет организациям настраивать свою реализацию SEDATED® без необходимости изменять какой-либо исходный код в файле pre-receive.sh SEDATED®, предоставляя встроенные настраиваемые переменные и функции, подключаемые из pre-receive.sh.

/config/enforced_repos_list.txt

• Используется, когда флаг use_enforced_repo_check_custom в config/custom_configs.sh для SEDATED® (pre-receive hook) установлен в "True".
• Позволяет SEDATED® быть «включённым» глобально на предприятии, но «принудительно применяемым» выборочно только к репозиториям, перечисленным в этом файле.
• Принудительное применение для всех репозиториев конкретной организации или пользователя можно осуществить, добавив /* в конец имени организации или пользователя, где требуется принудительное применение.
• Если SEDATED® включён глобально в организации и репозиторий не указан в файле /config/enforced_repos_list.txt, отправляющий (при отправке из командной строки) увидит настраиваемое сообщение (настраивается через файл /config/custom_configs.sh), и SEDATED® НЕ будет сканировать код, включённый в отправку.
• Флаг для включения/отключения этой функции можно найти в /config/custom_configs.sh и установить в "True" или "False".
  • "False" — каждый репозиторий, в котором SEDATED® «включён», также будет иметь «принудительное применение» SEDATED®.
  • "True" — только репозитории, в которых SEDATED® «включён» И которые перечислены в /config/enforced_repos_list.txt, будут иметь «принудительное применение» SEDATED®. Все остальные репозитории, в которых SEDATED® «включён», но которые не перечислены в файле /config/enforced_repos_list.txt, увидят только настраиваемое сообщение; код при отправках из этих репозиториев сканироваться не будет.
• Этот файл может быть пустым; он нужен только в том случае, если флаг use_enforced_repo_check_custom в config/custom_configs.sh установлен в "True".

/config/regexes.json

• Содержит регулярные выражения (regex), используемые для обнаружения конфиденциальных данных/захардкоженных учётных данных.
• Эти регулярные выражения обрабатываются GNU grep (в pre-receive.sh) с флагом -P, что делает их Perl-совместимыми регулярными выражениями (PCRE).
• Регулярные выражения можно добавлять или удалять из этого файла по мере необходимости; однако при использовании скрипта /testing/regex_testing/regex_test_script.sh потребуется обновить файл /testing/regex_testing/test_cases.txt, добавив или удалив тестовые случаи, относящиеся к обновлённым регулярным выражениям, чтобы результаты /testing/regex_testing/regex_test_script.sh были точными.
• При добавлении/изменении регулярных выражений в этом файле могут потребоваться дополнительные escape-символы \ в зависимости от желаемых регулярных выражений, поскольку этот файл имеет формат JSON.

/config/whitelists/commit_whitelist.txt

• Используется в случае ложноположительного срабатывания: один или несколько коммитов могут быть исключены из процесса сканирования, если их идентификаторы коммитов включены в этот файл.
• Идентификаторы коммитов должны быть разделены символами возврата каретки в этом файле, как показано в файле /config/whitelists/commit_whitelist.txt.example.
• Этот файл может быть пустым, но он должен существовать.

Необязательно: попросите разработчиков отправлять pull request'ы в этот файл (commit_whitelist.txt) при обнаружении ложноположительных срабатываний, чтобы их можно было проверить.

/config/whitelists/repo_whitelist.txt

• Репозитории (организация/имя пользователя), включённые в этот файл, будут полностью исключены из сканирования на предмет конфиденциальных данных/захардкоженных учётных данных до тех пор, пока они не будут удалены из этого списка.
• Используется в случае массовой отправки (например, миграции репозитория), когда SEDATED® не может просканировать новый/изменённый код, включённый в отправку, в пределах 5-секундного окна (5-секундное окно характерно для GitHub и может отличаться в других Git-экземплярах).
• Имена (организация/имя пользователя)/репозиторий должны быть разделены символами возврата каретки в этом файле, как показано в файле /config/whitelists/repo_whitelist.txt.example.
• Этот файл может быть пустым, но он должен существовать.

/testing/regex_testing/regex_test_script.sh

• Скрипт SEDATED® для тестирования регулярных выражений, используемый вместе с testing/regex_testing/test_cases.txt, — это простой, быстрый автономный способ проверить/подтвердить, что регулярные выражения внутри config/regexes.json действительны и соответствуют желаемым шаблонам, а также корректно исключают/не совпадают.
  • Тестирует регулярные выражения на списке тестовых случаев (/testing/regex_testing/test_cases.txt), чтобы убедиться, что регулярные выражения работают должным образом.
  • Включает тестирование как положительных, так и отрицательных тестовых случаев (/testing/regex_testing/test_cases.txt).
  • ОБЯЗАТЕЛЬНО используйте GNU grep при запуске скрипта, иначе скрипт завершится с ошибкой (в BSD grep нет флага -P).
  • Тестовые случаи для этого скрипта берутся из /testing/regex_testing/test_cases.txt.

/testing/regex_testing/test_cases.txt

• Список тестовых случаев, передаваемых в /testing/regex_testing/regex_test_script.sh для обработки.
• К каждому тестовому случаю добавляется>>pass или >>fail, которые сообщают скрипту /testing/regex_testing/regex_test_script.sh ожидание для регулярных выражений.
  • >>pass означает, что отправка, содержащая предшествующую строку, будет принята SEDATED® (т.е. регулярные выражения НЕ пометят предшествующую строку).
  • >>fail означает, что отправка, содержащая предшествующую строку, будет отклонена SEDATED® (т.е. регулярные выражения пометят предшествующую строку).

Настройка

Пользовательские переменные и функции предназначены для того, чтобы организации могли легко настраивать свою собственную реализацию SEDATED® без изменения основного файла pre-receive hook, который выполняет основную работу. Все пользовательские переменные и функции можно найти в /config/custom_configs.sh; объяснения переменных, содержащихся в этом файле, приведены ниже.

Пользовательские переменные

• show_SEDATED_link_custom — "True" для отображения ссылки на GitHub-репозиторий OWASP/SEDATED (с учётом регистра), в противном случае установите "False".
• documentation_link_custom — добавьте ссылку на документацию организации о том, как разработчики должны обрабатывать отклонённые отправки, и/или общую информацию, специфичную для организации, касающуюся SEDATED®.
  • Отображается разработчику, когда отправка отклонена.
  • Отображается разработчику, когда параметр enforced repo check установлен в true и репозиторий не включён в файл enforced_repos_list.txt.
• use_enforced_repo_check_custom — "True" или "False" (с учётом регистра).
  • См. описание файла /config/enforced_repos_list.txt выше, чтобы узнать больше о значении этого флага.
• enforced_repo_check_true_message_custom с настраиваемым сообщением (необходимо только в том случае, если use_enforced_repo_check_custom установлен в "True").
• obfuscate_output_custom — "True" или "False" (с учётом регистра). Используйте эту опцию, чтобы маскировать конфиденциальные данные, отображаемые в выводе SEDATED®.

Пользовательские функции

• SET_USER_REPO_NAME_CUSTOM
  • Устанавливает имя пользователя/организации/группы и имя репозитория.
  • Устанавливает имя пользователя/организации/группы и имя репозитория с помощью переменной GITHUB_REPO_NAME при использовании GitHub.
  • Если вы не используете GitHub, можно задать пользовательские переменные для получения этих имён.
  • Предоставленные не-GitHub имена настроены только для получения имён в ванильном Git, но могут потребовать корректировки в зависимости от конкретных реализаций (Git SCM).
• PRINT_ERROR_MESSAGE_CUSTOM
  • Позволяет выводить настраиваемое сообщение об ошибке при возникновении ошибок.
• EXIT_SEDATED_CUSTOM
  • Выполняет дополнительное настраиваемое действие при выходе из SEDATED® (например, запись в журнал, отправка метрик и т. д.).
  • По умолчанию используется : «ничего не делать» в качестве дополнительного действия; изменять не требуется.
• UNABLE_TO_ACCESS_REPO_WHITELIST_CUSTOM
  • Выполняет дополнительное настраиваемое действие, когда SEDATED® не может получить доступ к файлу whitelist репозитория (например, вывод сообщения об ошибке, запись в журнал, отправка метрики и т. д.).
  • По умолчанию используется : «ничего не делать» в качестве дополнительного действия; изменять не требуется.
• PUSH_ACCEPTED_CUSTOM
  • Выполняет дополнительное настраиваемое действие, когда отправка принята (например, запись в журнал, отправка метрик и т. д.).
  • По умолчанию используется : «ничего не делать» в качестве дополнительного действия; изменять не требуется.
• UNABLE_TO_ACCESS_REGEXES_CUSTOM
  • Выполняет дополнительное настраиваемое действие, когда SEDATED® не может получить доступ к файлу regexes.json.
  • По умолчанию используется : «ничего не делать» в качестве дополнительного действия; изменять не требуется.
  • SEDATED® выполнит exit 1 и выведет сообщение об ошибке, если не сможет получить доступ к регулярным выражениям; однако при желании в этих случаях может быть выполнено дополнительное настраиваемое действие (например, вывод дополнительного сообщения об ошибке, запись в журнал, отправка метрики и т. д.).
• PUSH_REJECTED_WITH_VIOLATIONS_CUSTOM
  • Выполняет дополнительное настраиваемое действие, когда отправки отклоняются из-за наличия нарушений (например, запись в журнал, отправка метрик и т. д.).
  • По умолчанию используется : «ничего не делать» в качестве дополнительного действия; изменять не требуется.
• UNABLE_TO_ACCESS_COMMIT_WHITELIST_CUSTOM
  • Выполняет дополнительное настраиваемое действие, когда SEDATED® не может получить доступ к файлу whitelist коммитов (например, запись в журнал, отправка метрик и т. д.).
  • По умолчанию используется : «ничего не делать» в качестве дополнительного действия; изменять не требуется.

Совместимость

Совместим только с SCM-инструментами, использующими систему контроля версий Git.

• GitHub
  • Полностью протестирован (Enterprise v2.15.3).
  • SEDATED® Настройка GitHub Enterprise.
• GitLab
  • Предварительно протестирован.
  • Потребуются изменения в SET_USER_REPO_NAME_CUSTOM, чтобы задать пользователя/организацию и имя репозитория.
• Git
  • Предварительно протестирован.
  • Все файлы/папки SEDATED® необходимо разместить в каталоге .git/hooks/ (кроме папки/файлов документации).
  • Удалите .sample из pre-receive.sample и скопируйте код из файла pre-receive.sh SEDATED® в файл pre-receive, который мы только что создали из файла .sample.
  • В зависимости от реализации, возможно, стоит использовать git-template или что-то подобное.
• Любой другой Git SCM-инструмент
  • Не тестировалось.
  • Вероятно, потребуются изменения в SET_USER_REPO_NAME_CUSTOM, чтобы задать пользователя/организацию и имя репозитория.
  • Для работы могут потребоваться дополнительные изменения.

Участие

Вклад в этот проект приветствуется!

Вы можете внести вклад одним из следующих способов:

• Отправьте нам свои идеи по улучшению (или любому из сообщества, кто может захотеть взяться за задачу превращения вашей идеи в реальность в кодовой базе SEDATED®) — пожалуйста, создайте issue с хорошим объяснением того, что, по вашему мнению, могло бы улучшить SEDATED® и как это могло бы практически реализоваться в кодовой базе.
• Отправьте pull request с вашими изменениями кода, чтобы сделать SEDATED® лучше, и мы проверим, протестируем и объединим их. :)

Авторы

• Dennis Kennedy
• Simeon Cloutier

Лицензия

SEDATED® лицензирован в соответствии с лицензией BSD 3-Clause "New" or "Revised".

**SEDATED® не гарантирует обнаружение каждого случая захардкоженных учётных данных, ключей, секретов и т. д. Он использует сопоставление с регулярными выражениями, и хотя он стал довольно хорош в выявлении большинства случаев, он не идеален, но мы всегда открыты для идей и/или pull request'ов, которые помогут сделать SEDATED® ещё лучше.