Интеграция с DefectDojo

Эта интеграция отправляет отчёты сканирования безопасности проекта в DefectDojo, систему управления уязвимостями, и поддерживает актуальность несоответствий в нём по мере выполнения пайплайнов.

Предварительные требования

Перед настройкой интеграции проверьте следующее:

• Администратор включил флаг функций defect_dojo_integration так, как описано на странице Ранний доступ.
• DefectDojo доступен из Deckhouse Code. Если его адрес находится в локальной сети, администратор установил флажок «Разрешить запросы к локальной сети от вебхуков и интеграций» или добавил адрес в поле «Локальные IP-адреса и доменные имена, к которым могут получить доступ хуки и интеграторы» в разделе «Admin» → «Настройки» → «Сеть» → «Исходящие запросы».
• У вас есть API-токен учётной записи DefectDojo, которой разрешено импортировать результаты сканирования, просматривать продукты и активности и изменять активности. Если установлен флажок «Автоматически создавать контекст», учётная запись также должна иметь право создавать продукты и активности.
• У вас есть роль «Мейнтейнер» или «Владелец» в проекте.
• В пайплайне есть задачи, которые формируют один из поддерживаемых отчётов безопасности.

Настройка интеграции с DefectDojo

Чтобы настроить интеграцию:

1. Откройте проект в Deckhouse Code.
2. Перейдите в раздел «Настройки» → «Интеграции» → «DefectDojo».
3. В группе «Включить интеграцию» установите флажок «Активные».
4. В блоке «Соединение» укажите в поле «URL DefectDojo» базовый URL инстанса DefectDojo, а в поле «API-токен» — токен для аутентификации в API DefectDojo.
5. В блоке «Доверие сертификату» выберите, как соединение решает, доверять ли серверу DefectDojo:
   • «Доверять тому, чему уже доверяет этот экземпляр» (по умолчанию);
   • «Доверять удостоверяющему центру ниже» — дополнительно доверять центру, чей PEM-сертификат вы вставите в поле «Удостоверяющий центр»;
   • «Не проверять сертификат» — выгрузка отправляется без проверки сертификата сервера и может быть перехвачена вместе со всеми несоответствиями из отчётов.
6. Заполните поля блока «Параметры импорта по умолчанию», которые применяются при импорте отчётов сканирования в DefectDojo:
   • «Название продукта» — продукт DefectDojo. Оставьте пустым, чтобы использовать полный путь проекта;
   • «Тип продукта» — тип продукта DefectDojo, используется при автоматическом создании продукта;
   • «Название активности» — активность DefectDojo. Оставьте пустым, чтобы использовать имя ветки;
   • «Минимальная критичность» — игнорировать несоответствия ниже указанной критичности при импорте (Info, Low, Medium, High, Critical — от низшей к высшей, по умолчанию Info);
   • «Автоматически создавать контекст» — создать продукт и активность, если они не существуют (по умолчанию флажок установлен);
   • «Импортированные находки» — помечать импортированные несоответствия как активные (по умолчанию флажок установлен);
   • «Подтверждённые находки» — помечать импортированные несоответствия как подтверждённые;
   • «Закрывать старые находки» — закрывать несоответствия, которые больше не фиксируются (по умолчанию флажок установлен).
7. Нажмите «Сохранить изменения».

Интеграцию можно также настроить на уровне группы или инстанса; проекты этой группы или инстанса наследуют эти настройки, если для них не заданы собственные.

Проверка подключения

Чтобы проверить заполненные в форме настройки до сохранения, нажмите «Проверить настройки». Кнопка доступна только в настройках интеграции проекта. Deckhouse Code отправляет настройки в DefectDojo и проверяет следующее:

• DefectDojo принимает API-токен.
• Продукт существует. Продукт — это значение «Название продукта» или, если оно пустое, полный путь проекта. Если продукта нет, проверка проходит, только когда установлен флажок «Автоматически создавать контекст» и заполнено поле «Тип продукта».
• Активность из поля «Название активности» существует в продукте. Это проверяется, только если поле «Название активности» заполнено, а флажок «Автоматически создавать контекст» снят.

Если все проверки пройдены, выводится сообщение «Соединение успешно.». Иначе выводится сообщение «Ошибка подключения. Проверьте настройки интеграции.» и причина.

При нажатии «Сохранить изменения» в собственных настройках интеграции проекта Deckhouse Code выполняет те же проверки, если интеграция активна и изменились URL, токен, продукт, тип продукта, активность или флажок «Автоматически создавать контекст». Если проверка не пройдена, настройки не сохраняются. Если DefectDojo недоступен или отвечает не так, как ожидается, настройки сохраняются без проверки.

Работа интеграции

Пока интеграция активна, Deckhouse Code отправляет в DefectDojo отчёты безопасности из пайплайнов проекта.

Автоматический импорт результатов сканирования

Когда в пайплайне проекта завершается задача сканирования безопасности, Deckhouse Code импортирует отчёты пайплайна в DefectDojo.

Поддерживаются результаты следующих типов сканирования:

• статическое тестирование безопасности приложений (SAST);
• обнаружение секретов;
• сканирование зависимостей;
• сканирование контейнеров;
• динамическое тестирование безопасности приложений (DAST).

Отчёты отправляет сам Deckhouse Code, поэтому в пайплайне не нужны ни отдельная задача, ни учётные данные DefectDojo в CI-переменных.

Сопоставление сущностей в DefectDojo

По умолчанию Deckhouse Code использует следующие соответствия:

• Продукт (Product) — значение «Название продукта» или, если оно пустое, полный путь проекта;
• Активность (Engagement) — значение «Название активности» или, если оно пустое, ветка или тег, на которых выполнялся пайплайн. Для пайплайна запроса на слияние это refs/merge-requests/<IID>/head, где <IID> — номер запроса на слияние;
• Тест (Test) — имя CI-задачи, сформировавшей отчёт.

У каждой задачи сканирования свой тест, поэтому сканеры не закрывают несоответствия друг друга. При повторном запуске задачи сканирования импортируется только отчёт её последнего запуска. Если переименовать задачу сканирования, её отчёты перестают импортироваться в тест со старым именем.

Параметры импорта

При импорте результатов Deckhouse Code передаёт в DefectDojo значения из блока «Параметры импорта по умолчанию», а также дату завершения задачи сканирования, идентификатор пайплайна, SHA коммита и его короткую форму в качестве версии, имя ветки или тега и URL проекта. После импорта Deckhouse Code записывает те же SHA коммита, версию, ветку или тег, идентификатор пайплайна и URL проекта в саму активность DefectDojo.

Диагностика

О проблемах интеграции сообщают форма настроек, результат кнопки «Проверить настройки» и страница пайплайна.

Настройки не сохраняются

Если проверка в DefectDojo не пройдена, форма показывает причину и не сохраняет настройки:

Импорт завершается ошибкой

Отчёт, который не попал в DefectDojo, отображается на странице пайплайна в предупреждении «Предупреждения выгрузки отчётов о безопасности» строкой DefectDojo did not receive the report of job "<JOB_NAME>" (<SCAN_TYPE>): <REASON>. Строки выводятся на английском языке. <SCAN_TYPE> — тип сканирования DefectDojo, например GitLab SAST Report, а <REASON> — одна из причин:

Если DefectDojo недоступен, не отвечает за время тайм-аута или отвечает кодом 429 или 5xx, выгрузка повторяется до трёх раз с увеличивающейся задержкой. Если все повторы не удались, в предупреждении появляется одна строка для всего пайплайна: DefectDojo upload of this pipeline's security reports failed and the retries are spent: <REASON>.

Защита API-токена

Используйте отдельную учётную запись DefectDojo только с правами, перечисленными в разделе «Предварительные требования». Сохранённый токен в форме не отображается. Чтобы заменить его, введите новый токен в поле «Введите новый API-токен»; если оставить поле пустым, сохраняется текущий API-токен.

Дополнительные ресурсы

• Непрерывная сборка и поставка ПО
• Отчёт об уязвимостях
• SAST-сканирование с помощью Opengrep
• Интеграции со сканерами безопасности