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

CodeScoring — самостоятельно разворачиваемая платформа для анализа состава ПО (SCA, Software Composition Analysis) и поиска секретов. Интеграция с CodeScoring подключает проект к серверу CodeScoring, а политика выполнения сканирования добавляет задачи сканирования CodeScoring в пайплайны проекта и задаёт, что они сканируют.

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

Чтобы сканирование могло запуститься, убедитесь, что:

• сервер CodeScoring доступен раннеру, и у вас есть для него токен API. Версия сервера — 2026.20.0 или выше, а агента, которого он отдаёт, — 2026.27.0 или выше: задачи сканирования привязывают результат к просканированной ссылке, и на более старых версиях сканирование завершается с ошибкой вместо того, чтобы записать результат не в ту версию проекта (см. раздел «Куда записывается результат сканирования» ниже);
• администратор включил флаг функций fe_security_scan_policies так, как описано на странице Ранний доступ;
• интеграция с CodeScoring настроена и активна для проекта, или унаследована от группы выше него;
• проект политик безопасности привязан к проекту или к группе выше него;
• доступен GitLab Runner с Docker executor, и он может загрузить образ задачи сканирования (образ по умолчанию или тот, что администратор задал в интеграции).

Развёртывание самого сервера CodeScoring не входит в эту интеграцию; порядок описан в руководстве по установке от вендора.

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

Настройте интеграцию на уровне проекта или группы, в разделе «Настройки» → «Интеграции» → «CodeScoring». Форма задаёт подключение, доверие сертификату и настройки по умолчанию для задач сканирования. Опции сканирования задаются в политике выполнения сканирования.

Подключение

В разделе «Подключение» есть следующие поля:

Доверие сертификату

В разделе «Доверие сертификату» есть следующие поля:

Задачи сканирования

В разделе «Задачи сканирования» есть следующие поля:

Собственный образ задачи сканирования должен содержать curl, ca-certificates, jq, ruby и git, а также исполняемый файл каждого поискового движка секретов, который включает политика (gitleaks, trufflehog, kingfisher). Задача, в образе которой нет одной из этих команд, завершается с ошибкой и называет её.

Нажмите «Сохранить изменения», чтобы сохранить форму. Нажмите «Проверить настройки», чтобы одним запросом проверить URL-адрес, токен и доверие сертификату на сервере.

Включение сканирования

Добавьте действие codescoring в файл .deckhouse_code/security-policies/policy.yml проекта политик безопасности:

scan_execution_policy:
  - name: CodeScoring everywhere
    enabled: true
    rules:
      - type: pipeline
        branches: ["*"]
    actions:
      - scan: codescoring
        variables:
          FE_SCANS_CODESCORING_SCA: "true"
          FE_SCANS_CODESCORING_SECRETS: "true"
          FE_SCANS_CODESCORING_SECRETS_GITLEAKS: "true"

Действие должно включать хотя бы один модуль в variables: FE_SCANS_CODESCORING_SCA для SCA или FE_SCANS_CODESCORING_SECRETS вместе хотя бы с одной из переменных FE_SCANS_CODESCORING_SECRETS_GITLEAKS, FE_SCANS_CODESCORING_SECRETS_TRUFFLEHOG и FE_SCANS_CODESCORING_SECRETS_KINGFISHER для «Секретов». Политика, которая не включает ни одного модуля, не проходит проверку и пропускается без сообщения в пайплайне.

Затем привяжите проект политик: для проекта — в разделе «Безопасность» → «Политики», для группы — в разделе «Настройки» → «Политика безопасности». Опции сканирования можно также редактировать в редакторе политик, который показывает SCA и «Секреты» как два модуля, включаемых независимо друг от друга.

Редактор политик предлагает codescoring только тогда, когда для покрываемого проекта (или группы выше него) настроена активная интеграция с CodeScoring; до тех пор редактор показывает «Для использования этого сканирования в политиках безопасности требуется активная интеграция с CodeScoring.» со ссылкой «Настроить интеграцию с CodeScoring».

После применения политики каждый подходящий под неё пайплайн получает задачу codescoring_sca, если включён модуль SCA, и по одной задаче codescoring_secrets_<движок> на каждый поисковый движок секретов, выбранный в модуле «Секреты». Все эти задачи выполняются на этапе пайплайна, который называет политика, по умолчанию — fe-security-scanner (раздел «Этап задач сканирования» на странице Сканирование с помощью Trivy). Модуль, который политика не включила, не даёт ни одной задачи.

SCA

Анализ состава: от чего зависит репозиторий, какие из этих зависимостей известны как уязвимые и какой перечень их описывает.

У модуля SCA есть следующие поля:

Если включить SCA, оставив все поля по умолчанию, сканируется весь чекаут как каталог с исходниками, на стадии build, и пишется CycloneDX 1.6 JSON. В основной ветке проекта сканирование также фиксируется как версия проекта по умолчанию на сервере CodeScoring.

Секреты

Учётные данные, попавшие в репозиторий. Выберите один или несколько поисковых движков: gitleaks, trufflehog, kingfisher. Каждый выбранный движок выполняется в отдельной задаче.

Включение любого движка открывает одно общее поле:

Поиск секретов идёт по каталогу из поля «Цель сканирования» модуля SCA или по всему чекауту, если поле пустое.

Дальше у каждого движка открываются собственные элементы:

Отчёты и куда они попадают

Каждая задача выгружает следующие отчёты:

Отчёты отображаются в следующих местах:

Куда записывается результат сканирования

Deckhouse Code определяет, какую ссылку и какой коммит покрывает сканирование, и передаёт их агенту, поэтому результат записывается против того кода, который просканировали: ветки, тега или исходной ветки запроса на слияние, к которому относится пайплайн. Сканируемый проект не может задать это в своих настройках CI/CD.

Каждая задача проверяет привязку до обращения к серверу и останавливается с ненулевым кодом возврата, если ссылки нет, коммит пуст или коммит не совпадает с HEAD рабочей копии. Сканирование, которое не может сказать, какой код прочитало, завершается с ошибкой, а не записывает результат в угаданную версию.

Пайплайн ветки по умолчанию проекта дополнительно отмечает свой результат версией по умолчанию на сервере.

Два ограничения сервера, о которых стоит знать при чтении его версий; измерено на 2026.27.2:

• ветка и тег с одинаковым коротким именем попадают в одну версию проекта, потому что версия ключуется этим коротким именем; полная ссылка остаётся в самой записи анализа;
• поиск секретов записывает свой анализ в версию по умолчанию, сохраняя ссылку в записи анализа, тогда как анализ состава для той же ссылки записывается в версию этой ссылки.

Результаты, собранные до того, как сервер обновился до 2026.20.0, остаются в той версии, в которую попали: сервер не переносит анализы между версиями, поэтому версии по ссылкам наполняет повторное сканирование проекта.

Блокировка

codescoring_sca завершается с ошибкой, если агент вышел с ненулевым кодом: он нашёл что-то, что блокируют политики сервера CodeScoring, не смог выполниться или не дал результата. Собственного порога критичности здесь нет: что считать достаточно серьёзным, решают политики сервера CodeScoring, и вкладка «Тесты» отмечает как проваленные именно те несоответствия, которые блокируют эти политики.

Каждая задача codescoring_secrets_<движок> завершается с ошибкой при любом найденном секрете. Чтобы пропустить проверенное несоответствие, добавьте его в список «Игнорировать или исключить» этого движка. Чтобы только сообщать о секретах, не проваливая задачу, задайте FE_SECURITY_FAIL_ON: report_only в variables действия.

Любая задача также завершается с ошибкой, если агент johnny не удалось скачать.

Диагностика

Сканирование не появляется в пайплайне

Проверьте, что:

• интеграция с CodeScoring активна для проекта, или унаследована от группы выше него, и в ней заданы URL-адрес сервера и токен;
• проект политик безопасности привязан, и его policy.yml содержит действие codescoring;
• действие codescoring включает хотя бы один модуль в variables;
• доступен GitLab Runner с Docker executor, и он может загрузить образ задачи сканирования.

«WARNING: the CodeScoring agent (johnny) could not be downloaded»

Это сообщение появляется в логе задачи codescoring_sca: задача не смогла скачать агент, ничего не просканировала и завершается с ошибкой. Задача codescoring_secrets_<движок> в той же ситуации пишет «ERROR: the secret search could not run – the johnny agent was not delivered.». Обычно причина одна из следующих:

• Сервер CodeScoring не публикует агент для платформы раннера, например раннер на arm64 обращается к серверу, который публикует агент только под amd64. Попросите администратора задать образ под amd64 в поле «Образ задачи сканирования».
• Неверный URL-адрес сервера или токен API.
• Задача не доверяет сертификату сервера. Настройте «Доверие к сертификату» в интеграции или передайте связку CA через CI/CD-переменную типа «Файл» CODESCORING_SSL_FILE.

Задача поиска секретов проваливается при каждом запуске

Это ожидаемое поведение. Причина и способ пропустить конкретное проверенное несоответствие описаны в разделе «Блокировка» выше.

Результаты не появляются на страницах «Список зависимостей» или «Соответствие лицензий»

Проверьте, что codescoring_sca выполнилась и создала артефакт cyclonedx в формате gl-sbom.cdx.json, которого ожидают эти страницы. Порядок диагностики описан в разделе «Диагностика» страницы «Список зависимостей и соответствие лицензий».

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

• Список зависимостей и соответствие лицензий
• SAST-сканирование с помощью Opengrep
• Интеграции со сканерами безопасности