Доступно с версии 1.14.0 (EE), с флагом раннего доступа fe_security_scan_policies

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

Статический анализ кода (SAST, Static Application Security Testing) в Deckhouse Code ищет уязвимости в исходном коде проекта. За ним стоит сканер Opengrep, а само сканирование называется opengrep_sast.

Сканирование обязательное: его подмешивает в пайплайн проекта политика исполнения сканирования, которая лежит в отдельном проекте политик безопасности. Что сканируется и что приводит к ошибке пайплайна, решает политика — то есть команда безопасности. Файл .gitlab-ci.yml и настройки CI/CD проверяемого проекта на это решение не влияют.

Что делает сканирование

Сканирование opengrep_sast добавляет в пайплайн задачи opengrep_sast_scan и opengrep_sast_junit. Этап задач называет политика, по умолчанию — fe-security-scanner (раздел «Этап задач сканирования» на странице Сканирование с помощью Trivy). Задачи:

ЗадачаЧто делает
opengrep_sast_scanЗапускает сканер по репозиторию и публикует его собственный JSON-вывод как артефакт opengrep-scan/. В логе задача называет движок и образ анализатора, в котором выполнялась, путь к набору правил и число правил в нём, сколько правил выполнилось и сколько файлов прочитано.
opengrep_sast_junitЧитает этот JSON, строит из него отчёт для сводки тестов и отчёт безопасности и решает исход: задача завершается успешно, если ни одна находка не достигла порога блокировки, и с ошибкой в противном случае. Выполняется в образе Ruby.

В пайплайне имя каждой задачи несёт политику, которая её потребовала: opengrep_sast_scan:<имя политики в виде слага>-p<идентификатор проекта политик>. Групповая политика и политика проекта, обе требующие это сканирование, дают по паре задач каждая.

Две задачи opengrep_sast на этапе «fe-security-scanner» пайплайна

Обе задачи выгружают артефакты с when: always, поэтому заблокированный пайплайн сохраняет находки, которые его заблокировали.

Конец лога задачи сканирования с блоком «Scan Summary» и переменными покрытия

Репозиторий, все файлы которого написаны на языках, которых набор правил не покрывает, завершает задачу сканирования строкой лога Opengrep: nothing was scanned, so this run publishes no report.: обе задачи завершаются успешно, а отчёт не публикуется, поэтому ничто ниже по цепочке не прочитает пустой отчёт как исправленные находки.

Находки попадают туда же, куда и находки остальных сканеров политики:

ОтчётГде смотреть
Тесты (JUnit)Вкладка «Тесты» пайплайна и сводка тестов в запросе на слияние
Отчёт безопасности (sast)Страница «Отчёт об уязвимостях»
Находки, переданные в DefectDojoDefectDojo, если настроена интеграция с DefectDojo

Вкладка «Тесты» упавшего пайплайна на main: «Сводка» — 17 тестов, 8 сбоев, 0 ошибок, показатель успешности 52.94%; «Уязвимости» — 8 уровня «Высокий» и ни одного на остальных уровнях; таблица «Задания» с одной строкой opengrep_sast_junit:sast-everywhere-p2: 8 неудачных, 9 пройденных, 17 всего

Каждый тестовый случай назван по находке: уровень, идентификатор правила (основной идентификатор или, если его нет, check_id), первая строка краткого описания или сообщения, обрезанная до 255 символов, и файл со строкой в квадратных скобках. К повторяющемуся имени добавляется счётчик.

Тестовые случаи задачи на вкладке «Тесты», каждый назван по своей находке, например HIGH rules-fe.semgrep-rules.dockerfile.security.missing-user By not specifying a USER, … [Dockerfile:5], с файлом, статусом, уровнем «Высокий» и кнопкой «Подробнее»

Виджет отчёта о тестах в запросе на слияние сравнивает отчёт о тестах пайплайна запроса на слияние с отчётом пайплайна целевой ветки. Заголовок виджета зависит от задач в отчёте: «Итоги сканирования безопасности», когда все задачи принадлежат сканерам политики, «Итоги тестирования», когда таких задач нет, и «Итоги тестирования и сканирования безопасности», когда в отчёте есть и те и другие. Вкладка «Отчёты» запроса на слияние показывает тот же заголовок. Находки, которые вносит запрос на слияние, показаны в группе «Новое», за ними — уже существующие в целевой ветке; тесты, которые он исправляет, показаны в группе «Исправлено».

Виджет запроса на слияние «Итоги сканирования безопасности» развёрнут: 10 провалено из 20 тестов; ниже — задача opengrep_sast_junit:sast-everywhere-p2 и в группе «Новое» первая находка, которую вносит запрос на слияние, HIGH rules-fe.semgrep-rules.ruby.lang.security.bad-deserialization-yaml … [app/services/order_export.rb:11]

Находки opengrep_sast в списке отчёта об уязвимостях

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

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

  • администратор включил флаг функций fe_security_scan_policies так, как описано на странице Ранний доступ;
  • проект политик безопасности привязан к проекту или к группе выше него;
  • доступен GitLab Runner с executor docker, и он может загрузить оба образа, которые использует сканирование: образ сканера (раздел «Откуда берётся образ сканера») и образ Ruby, в котором выполняется вторая задача, — по умолчанию ruby:3.3.10-slim, установка перенаправляет его переменной окружения сервера FE_SCANS_REPORT_CONVERTER_IMAGE.

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

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

scan_execution_policy:
  - name: SAST everywhere
    enabled: true
    rules:
      - type: pipeline
        branches: ["*"]
    actions:
      - scan: opengrep_sast

opengrep_sast — идентификатор, который схема политики принимает для этого сканирования. Политика, в действии которой написано semgrep_sast или sast, не проходит проверку и ничего не требует, пока действие не переименовано. В политике может быть только одно действие для каждого сканера: политику со вторым действием scan: opengrep_sast сохранить нельзя. Второй набор настроек вынесите в отдельную политику.

Затем привяжите проект политик к нужному проекту или группе в разделе «Настройки» → «Политика безопасности». После этого каждый пайплайн, попадающий под правила политики, получает две задачи, описанные выше.

Ту же политику можно создать в интерфейсе. В проекте или группе выберите «Безопасность» → «Политики» и нажмите «Новая политика»:

Страница проекта «Политики»: кнопки «Редактировать проект политик» и «Новая политика» и одна строка — включённая политика «SAST everywhere» типа «Выполнение сканирования безопасности»

На экране «Выберите тип политики» выберите «Политика выполнения сканирования»:

Экран «Выберите тип политики»: единственная карточка «Политика выполнения сканирования», в описании которой названы SAST, Secret Detection, сканирование зависимостей и PT AI, и её кнопка

В редакторе политик это сканирование называется «SAST (встроенный Opengrep)» в списке «Сканирования безопасности» и считается обязательным, пока включена хотя бы одна из его групп, описанных ниже. Условия запуска — флажки под заголовком «Когда запускать сканирования»: «На любом пайплайне», «Запросы на слияние», «Ветка по умолчанию», «Сканирование по расписанию» с полем «Расписание» и «По имени ветки» с полем «Шаблон ветки». Флажки сочетаются; «На любом пайплайне» снимает флажки «Запросы на слияние», «Ветка по умолчанию» и «По имени ветки» и держит их недоступными, пока включён сам. Политику без единого условия запуска сохранить нельзя, а отправленную в репозиторий вручную отвергает схема.

Пока политику нельзя сохранить, кнопка «Настройка с запросом на слияние» недоступна, а под ней после «Сохранение недоступно:» перечислены причины. Список виден и в представлении «Режим .yaml».

Под кнопкой «Настройка с запросом на слияние» редактор называет проект политик, в который уйдёт запрос на слияние, или путь проекта, который будет создан при сохранении. Если создать его не получится, вместо этого показано предупреждение с причиной:

  • создать или связать проект политик может только владелец;
  • проект с таким путём или именем уже существует; предупреждение ссылается на страницу, где его можно связать;
  • администратор ограничил уровень видимости, который получил бы проект (видимость группы или проекта, к которым относится политика);
  • исчерпан лимит личных проектов;
  • у вас нет права создавать проекты в группе;
  • сгенерированное имя или путь недопустимы; предупреждение добавляет текст ошибки проверки;
  • проект политик связали уже после того, как открылась страница; обновите страницу, чтобы увидеть его.

Пока показано предупреждение, кнопка остаётся доступной, а сервер отклоняет сохранение по той же причине.

Что задаёт политика

Форма действия opengrep_sast собрана из групп «Образ сканера», «Правила», «Уровни правил», «Исключаемые категории», «Порог блокировки», «Игнорируемые пути» и «Дополнительные параметры». Все параметры принадлежат политике: значения записываются в задачу сервером при формировании пайплайна, поэтому собственные переменные CI/CD проверяемого проекта их не меняют.

У каждой группы есть флажок рядом с заголовком. Установленный флажок раскрывает группу, и политика забирает эту часть сканирования себе для всех проектов, которые покрывает: «Правила» начинают с пути к набору правил /rules-fe, «Уровни правил» — со всех трёх уровней, «Порог блокировки» — с «Высокий и выше», а остальные группы ничего не записывают, пока в них не заполнено поле. Снятый флажок означает, что группа ничего не записывает в политику и эта часть сканирования остаётся с ответом, который задача даёт без неё, — тем же самым. Если снять флажки у всех групп, действие opengrep_sast удаляется из политики. Сохраните политику и откройте её заново — группы, в которых что-то задано, откроются сами, поэтому сохранённая политика показывает всё, что задаёт.

Группа названа по полю, вокруг которого собрана, и это поле нарисовано без собственной подписи внутри группы: «Уровни правил» раскрываются прямо на трёх флажках уровней, «Порог блокировки» — на пороге, «Дополнительные параметры» — на текстовом поле, а «Образ сканера» держит своё поле в строке заголовка. Подсказка («?») рядом с заголовком группы несёт подсказку этого поля либо описание самой группы.

То, что решила свёрнутая группа, написано в конце строки её заголовка:

ГруппаЧто написано в её свёрнутой строке
«Образ сканера»Ничего: поле остаётся в строке заголовка, и ссылка на образ читается прямо там
«Правила»Путь к файлу правил и проект, из которого он читается, либо путь к набору правил в образе
«Уровни правил»Уровни, включённые политикой, например «Высокий, Средний»
«Исключаемые категории»Ничего. В группе стоят флажки
«Порог блокировки»Порог — «Высокий и выше», пока политика не выберет другой
«Игнорируемые пути»Путь к файлу фильтров и проект, из которого он читается
«Дополнительные параметры»Ничего. В свободном тексте выбора из списка нет

Поле, которое отвечает одному варианту выбора, показывается только после этого выбора, а значение скрытого формой поля удаляется из политики: названный файл правил убирает с формы и из политики поля «Путь к набору правил в образе», «Правила» и флажки группы «Исключаемые категории».

Политика, написанная вручную, может также задать в variables действия переменную FE_SCANS_OPENGREP_SRC_DIRECTORY — каталог внутри рабочей копии: сканирование тогда читает только этот каталог и сообщает находки с путями относительно рабочей копии, а каталог, которого в репозитории нет, останавливает задачу.

Раскрытый раздел «SAST (встроенный Opengrep)»: группы «Правила», «Уровни правил» и «Порог блокировки» отмечены и свёрнуты со своими сводками; группа «Игнорируемые пути» отмечена и свёрнута без сводки, поскольку заполнено только поле «Исключить пути»; группы «Образ сканера», «Исключаемые категории» и «Дополнительные параметры» не отмечены; ниже групп — поле тегов раннера

Те же группы раскрыты, и дополнительно отмечена группа «Дополнительные параметры» со значением --timeout 300

Образ сканера

Группа — это одно поле «Образ сканера» в строке заголовка. Если поле пустое, сканирование выполняется в образе, заданном для этой установки: он показан в поле серым, и его называет подсказка: «Если оставить пустым, сканирование выполняется в образе <image>.» Подсказка сообщает и то, что несёт поставляемый образ: «С продуктом поставляется opengrep 1.30.0, в образе 1.30.0-fe2, с набором правил 2.9.3-fe2.»

ПолеЧто задаёт
«Образ сканера»Образ, в котором выполняется сканирование, — ссылка целиком: путь и тег, дайджест @sha256: или оба сразу, например registry.example.com/security/opengrep-scan:1.30.0-fe2. Первая часть без точки и порта считается началом пути на Docker Hub: opengrep:1.30.0 означает docker.io/library/opengrep:1.30.0. Набор правил берётся из самого образа, поэтому для образа, который его не несёт, правила нужно назвать в политике. Если поле пустое — образ, заданный для этой установки

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

Ссылка, устроенная иначе, сохранению политики не мешает. Задача тогда стартует в образе, заданном для установки, и останавливается до сканирования с сообщением this scan cannot run the configuration the policy asks for: scanner image: …. Тег вроде latest проверку проходит, и тогда сканер меняется всякий раз, когда хранилище образов передвигает тег.

Что означает пустое поле и где администратор задаёт этот образ — в разделе Откуда берётся образ сканера. Для образа в закрытом хранилище образов под полем задаются имена переменных логина и пароля: раздел Учётные данные хранилища образов для сканера.

Правила

Группа задаёт, какие правила выполняет сканирование. Её подсказка: «Какие правила выполняет сканирование. Если ничего не менять — набор, поставляемый с продуктом. Укажите файл, чтобы выполнять свои правила рядом с ним или вместо него.»

ПолеЧто задаёт
«Путь к файлу»Путь к файлу правил внутри репозитория, из которого он читается, например .opengrep.yml, показанный в поле серым. Если поле пустое, всё сканирование — это поставленный набор, и файл не читается.
«Проект»Из какого репозитория читается файл правил, в виде группа/проект. Показывается, когда заполнено поле «Путь к файлу». Если поле пустое — из проверяемого проекта, на строящемся коммите.
«Путь к набору правил в образе»Какой из наборов, лежащих в образе сканера, выполнять (раздел «Наборы правил в образе»). По умолчанию — /rules-fe. Показывается, пока файл не назван. Если по этому пути набора нет, сканирование останавливается.
«Правила»Сами правила, в YAML сканера; записываются в задачу сервером. Показывается, пока файл не назван. Не больше 16 КБ.
«Заменить поставленный набор»По умолчанию выключено: ваши правила выполняются вместе с поставленным набором. Если установить флажок, они выполняются вместо него, и всё, что покрывал поставленный набор, перестаёт проверяться.

Источники правил отличаются тем, кто владеет файлом:

ИсточникГде лежат правилаКто ими распоряжается
Поле «Путь к файлу» пустоеВ образе сканера, по пути из поля «Путь к набору правил в образе»Поставка продукта
«Путь к файлу» заполнен, «Проект» пустойСканируемый репозиторий, на строящемся коммитеПроверяемый проект
«Путь к файлу» заполнен, «Проект» названЭтот проект, на его ветке по умолчаниюМейнтейнеры этого проекта
«Правила»Сама политикаАвтор политики

Файл в проверяемом проекте задача читает из своей рабочей копии. Файл в другом проекте задача читает сама, через API, своим токеном задачи CI, поэтому кому разрешено его читать, решает этот проект: его мейнтейнер добавляет проверяемый проект в разделе «Настройки» → «CI/CD» → «Права доступа токена заданий CI/CD». Задача останавливается и называет эту настройку, если проект отвечает 401, 403 или 404, а также если файла нет или он пустой. Названный проект читается всегда на его ветке по умолчанию, на какой бы ветке ни выполнялся проверяемый пайплайн.

Правила, которые приносит политика — из файла или из поля «Правила», — задача записывает в образ по пути /rules/policy/rules.yml, поэтому их находки в отчётах названы rules.policy.<идентификатор правила>; находки поставленного набора названы по пути к набору, при пути по умолчанию — rules-fe.<идентификатор правила>. Перед сканированием задача проверяет принесённый набор: набор, который сканер не может разобрать, набор без единого правила и набор, правилам которого нужен движок новее, чем в образе, останавливают задачу и печатают вывод сканера. Снятый флажок «Заменить поставленный набор» оставляет поставленный набор выполняться рядом с ними.

Уровни правил

Группа задаёт, правила каких уровней вообще выполняются.

ПолеЧто задаёт
«Уровни правил»«Высокий» (ERROR), «Средний» (WARNING), «Информационный» (INFO). Все три флажка изначально установлены — именно это сканирование и выполняет, пока политика не задала своих уровней.

Уровень — это ровно те правила, которые сканер помечает им: «Высокий» — правила ERROR, «Средний» — WARNING, «Информационный» — INFO; находка попадает в отчёт с уровнем сработавшего правила. Снятый флажок исключает из сканирования ровно правила этого уровня.

Последний оставшийся установленный флажок снять нельзя: опустевший список удаляется из политики, а политика, которая не называет уровней, — это то состояние, в котором выполняются все уровни.

«Уровни правил» и «Порог блокировки» выглядят одинаково, а делают разное:

ПолеНа что влияетНаходка ниже уровня
«Уровни правил»Какие правила выполняютсяЕё не существует: правило не выполнялось
«Порог блокировки»Какие находки приводят к ошибке пайплайнаОна есть в отчёте, но не блокирует

Порог покрывает свой уровень и все уровни выше — это и означает «и выше»; уровень правил покрывает правила, помеченные сканером этим уровнем, и никакие другие.

Поэтому исключённый уровень убирает свои находки и из отчёта: отчёт об уязвимостях и DefectDojo становятся меньше, и в логе задачи об этом ничего не сказано. Порог, которого не достигает ни один установленный уровень, не сработает никогда; форма говорит об этом рядом с порогом: «Ни один уровень правил, способный достичь этого порога, не включён, поэтому пайплайн не упадёт никогда.» Уровни, после которых в наборе не остаётся ни одного правила, останавливают задачу сканирования с сообщением no rule survived the levels this policy runs.

Исключаемые категории

Группа задаёт, какие категории поставленного набора сканирование не выполняет. Она показывается, пока правила берутся из поставленного набора: названный файл правил убирает группу с формы, потому что у своих правил категорий нет.

ПолеЧто задаёт
«Исключить правила для секретов»По умолчанию выключено. Если установить флажок, правила, которые сообщают об учётных данных, попавших в репозиторий, при сканировании не применяются.
«Исключить правила для конфигурации»По умолчанию выключено. Если установить флажок, правила, которые читают конфигурацию и инфраструктурный код — Terraform, Dockerfile, манифесты Kubernetes, конфигурацию CI, — при сканировании не применяются.
«Исключить правила для вредоносного кода»По умолчанию выключено. Если установить флажок, правила, которые ищут признаки намеренно скрытого кода, при сканировании не применяются.

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

Что лежит в каждой категории и какой набор правил нужен для исключения — в разделе «Категории внутри поставленного набора».

Порог блокировки

Группа задаёт, что находка делает с пайплайном.

ПолеЧто задаёт
«Порог блокировки»Что приводит к ошибке пайплайна. Находки ниже порога всё равно попадают в отчёт и в отчёт об уязвимостях: порог решает только исход пайплайна. По умолчанию — «Высокий и выше».

Значения порога, каждое с подсказкой, которую форма показывает рядом:

ЗначениеЧто приводит к ошибке пайплайна
«Высокий и выше» (по умолчанию)Находка высокого уровня роняет пайплайн. Средний и информационный только попадают в отчёт.
«Средний и выше»Средний и высокий уровни роняют пайплайн. Информационный только попадает в отчёт.
«Любая находка»Любая находка роняет пайплайн, какого бы уровня она ни была.
«Только сообщать, ничего не блокировать»Ничто не роняет пайплайн. Находки всё равно фиксируются в отчёте и попадают в отчёт об уязвимостях.

Opengrep сообщает об уровнях ERROR, WARNING и INFO, которые сканирование показывает как высокий, средний и информационный. Критического и низкого у него нет, поэтому порога с таким именем не достигала бы ни одна находка. Значение «Только сообщать, ничего не блокировать» вносит отказ от блокировки в политику отдельным значением. Порог вне этого списка, возможный только в политике, написанной вручную, останавливает задачу до сканирования.

Игнорируемые пути

Группа задаёт, что сканирование оставляет за рамками. Её подсказка: «Что сканирование не смотрит. Собственные исключения задачи для вендорного и сгенерированного кода действуют независимо от того, что задано здесь.»

ПолеЧто задаёт
«Путь к файлу»Путь к файлу игнорируемых путей внутри репозитория, из которого он читается, в формате .semgrepignore, который читает сканер; в поле серым показан .semgrepignore. Если поле пустое, файл не читается.
«Проект»Из какого репозитория читается этот файл, в виде группа/проект. Показывается, когда заполнено поле «Путь к файлу». Если поле пустое — из проверяемого проекта, на строящемся коммите; названный проект читается так же, как файл правил, токеном задачи.
«Исключить пути»По одному пути или шаблону в строке: сторонний код, фикстуры, сгенерированные файлы. Передаются сканеру при любом файле.
«Учитывать .gitignore репозитория»По умолчанию выключено: обязательное сканирование смотрит и в игнорируемые файлы, потому что список игнорируемого принадлежит самому проверяемому проекту.

Перед сканированием задача убирает каждый .semgrepignore, который несёт репозиторий, — в корне и в подкаталогах. Файл, названный политикой, читается до этого и записывается обратно как единственный файл игнорирования для сканирования, с дописанными собственными исключениями задачи: node_modules/, vendor/, dist/, build/, .venv/ и .git/. Пустой файл останавливает задачу.

«Путь к файлу» с пустым полем «Проект» и «Учитывать .gitignore репозитория» одинаково отдают проверяемому проекту право решать, что осматривает обязательное сканирование: после этого коммит в проверяемом проекте может сузить сканирование, которое его же и проверяет, и в политике это сужение не видно. Команда, которая позволяет каждому проекту называть свои каталоги стороннего кода, фиксирует это делегирование в политике, потому что обе настройки остаются выключенными, пока эту группу не раскроют и одну из них не зададут.

Шаблон, не совпавший ни с чем, проходит проверку формы. Задача печатает, сколько файлов сканер взял в работу, сколько из них убрали фильтры и сколько он прочитал, и завершается с ошибкой, если фильтры убрали всё или в рабочей копии ничего нет.

Дополнительные параметры

Группа задаёт флаги, которых в остальной форме нет.

ПолеЧто задаёт
«Дополнительные параметры»Флаги, передаваемые сканированию как есть.

«Дополнительные параметры» настраивают ресурсы запуска: тайм-ауты, лимиты памяти, максимальный размер файла. Флаги, которыми распоряжается задача, отклоняются: --config, -c, -f, --output, -o, --json, --json-output, --sarif, --sarif-output, --junit-xml, --junit-xml-output, --emacs, --emacs-output, --vim, --vim-output, --text, --text-output, --gitlab-sast, --gitlab-sast-output, --gitlab-secrets, --gitlab-secrets-output, --metrics и --baseline-commit. Сервер отклоняет их при формировании задачи, и задача останавливается до сканирования, называя флаг.

Подсказка этого поля сообщает и то, куда попадают находки сканирования: они публикуются как отчёт безопасности, а значит, доходят до отчёта об уязвимостях и до всего, что администратор к нему подключил.

Наборы правил в образе

По умолчанию сканирование выполняет набор правил, лежащий внутри образа сканера, по пути /rules-fe. В этом каталоге лежат наборы ниже, и поле «Путь к набору правил в образе» выбирает между ними:

Путь в образеПравилЧто это
/rules-fe (по умолчанию)2825Наборы ниже вместе
/rules-fe/semgrep-rules1981Открытый набор semgrep-rules
/rules-fe/gitlab483Правила анализаторов GitLab
/rules-fe/community361Правила сообщества

Значения измерены в поставляемом образе opengrep-scan:1.30.0-fe2 и относятся к нему; в более новом образе состав может быть другим. У каждого набора свои условия распространения, и различают их именно каталоги: укажите в поле «Путь к набору правил в образе» один набор, чтобы выполнять только его.

Покрытие набора по числу правил на язык: python 618, terraform 366, javascript 352, java 341, typescript 235, go 195, c 194, scala 191, cpp 161, ruby 150, php 122, kotlin 105, а также solidity, yaml, dockerfile, swift, csharp и другие. Правило может называть несколько языков, поэтому сумма больше числа правил. Сканер выполняет только правила для языков найденных им файлов, поэтому в логе задачи на репозитории из одного JavaScript выполненных правил заметно меньше, чем в наборе.

Собственные правила задаются полями «Путь к файлу» или «Правила» и, если флажок «Заменить поставленный набор» остался снятым, выполняются вместе с тем набором, который даёт образ.

Категории внутри поставленного набора

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

КатегорияО чём судят её правила
КодКод самой программы
КонфигурацияКонфигурация и инфраструктурный код: Terraform, Dockerfile, манифесты Kubernetes, конфигурация CI
СекретыУчётные данные, попавшие в репозиторий
Вредоносный кодПризнаки намеренно скрытого кода: обфускация, код, собираемый во время выполнения, вызовы через промежуточные слои

Конфигурацию, секреты и вредоносный код политика может исключить — в группе «Исключаемые категории»; правила о коде выполняются в каждом сканировании.

Для исключения нужен набор правил, который несёт индекс своих категорий — файл CLASSES.tsv рядом с набором по пути из поля «Путь к набору правил в образе». Образ из поставки этого релиза такого индекса не несёт, поэтому установленный флажок останавливает на нём задачу: она называет категории, которые её просили исключить, и набор правил, у которого нет индекса для этого (раздел «Диагностика»). Флажки применимы к собственному образу, набор которого несёт индекс.

Правила для секретов и сканирование gitleaks_secret_detection смотрят на одно и то же, и каждое сканирование публикует свой отчёт безопасности, поэтому одна и та же строка становится двумя находками на двух уровнях: измерено на одном запуске, Opengrep положил попавший в репозиторий токен в отчёт с уровнем Info, а gitleaks_secret_detection — тот же токен с уровнем Critical. Наборы находок не вложены друг в друга, поэтому исключение правил для секретов передаёт категорию целиком gitleaks_secret_detection и вместе с ней убирает из SAST-отчёта те находки, которые сделал только Opengrep.

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

Откуда берётся образ сканера

Образ, в котором выполняется сканирование, разрешается сервером один раз, до старта задачи, и записывается в неё готовым значением. Переменной CI/CD он не становится, поэтому настройки проверяемого проекта не могут направить сканирование на другой сканер. Задача сканирования печатает ссылку на образ, в котором выполнялась, в начале лога строкой Analyzer image …, а рядом — движок, который несёт этот образ.

Какой это образ, следует из поля «Образ сканера» политики:

«Образ сканера» в политикеЧто загружает сканирование
ЗаполненоЭту ссылку, ровно как она написана.
ПустоеОбраз, заданный для этой установки: значение переменной окружения FE_SCANS_OPENGREP_IMAGE сервера Deckhouse Code, а если переменная не задана — образ, зафиксированный этим релизом.

FE_SCANS_OPENGREP_IMAGE — переменная окружения серверных процессов, которые формируют пайплайны: веб-сервера и Sidekiq. Администратор задаёт её в их окружении, а читается она в момент формирования задачи. То же имя среди переменных CI/CD проекта или группы ни на что не влияет: задача никогда не читает образ из переменной. В файле политики это поле — ключ FE_SCANS_OPENGREP_IMAGE в variables действия; именно его записывает редактор:

actions:
  - scan: opengrep_sast
    variables:
      FE_SCANS_OPENGREP_IMAGE: registry.example.com/security/opengrep-scan:1.30.0-fe2

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

Версия из поставки продукта

Этот релиз поставляет opengrep-scan:1.30.0-fe2: Opengrep 1.30.0 с набором правил 2.9.3-fe2. Тег нумерует образ, а движок и набор правил внутри него меняются независимо: образ, пересобранный с более новым набором правил, получает новый тег, хотя движок остался прежним. Подсказка рядом с полем «Образ сканера» называет все три номера для поставляемого образа, а лог задачи сканирования печатает версии движка и набора правил, которые выполнялись.

Поле «Образ сканера» принимает любую из этих форм фиксации версии:

  • тег, например 1.30.0-fe2, — его читает человек и с ним можно сравнивать;
  • дайджест, например @sha256:aafbcaff…, — он называет одну сборку, и подменить её нельзя;
  • оба сразу, например opengrep-scan:1.30.0-fe2@sha256:aafbcaff…, — образ загружается по дайджесту, а тег остаётся для читателя.

Ссылка без того и другого отклоняется. Хранилище образов — часть ссылки, поэтому зеркальная копия образа называется вместе со своим хранилищем.

Версия, поставляемая с релизом, пересматривается при обновлении Deckhouse Code.

Закрытый контур

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

ОбразПо умолчаниюЧем перенаправляется
Сканерopengrep-scan:1.30.0-fe2, из хранилища образов продуктаПеременная окружения сервера FE_SCANS_OPENGREP_IMAGE — она перенаправляет каждую политику с пустым полем «Образ сканера»; либо поле «Образ сканера» политики
Сборщик отчётовruby:3.3.10-slim, с Docker HubПеременная окружения сервера FE_SCANS_REPORT_CONVERTER_IMAGE

Скопируйте оба образа в своё хранилище образов контейнеров, а затем укажите это хранилище в соответствующей настройке. Если образ, заданный для установки, лежит в хранилище образов контейнеров этого же экземпляра Deckhouse Code, редактор политик спрашивает у хранилища этот тег и, если тега нет, дописывает в подсказку рядом с полем «Образ сканера»: «В реестре нет такого тега: сканирование, которое возьмёт этот образ, не сможет запуститься, пока он не появится.» Стороннее хранилище не спрашивается.

Образ сканера остаётся вне досягаемости dependency proxy. Прокси кеширует образы, лежащие на Docker Hub, а образ сканера публикуется в хранилище образов продукта, поэтому из двух образов прокси кеширует образ Ruby. Установка, которая хочет перестать загружать образ сканера извне при каждом запуске — в закрытом контуре или нет, — копирует образ в своё хранилище и указывает эту копию в переменной FE_SCANS_OPENGREP_IMAGE или в поле «Образ сканера».

Учётные данные хранилища образов для сканера

Учётные данные нужны, когда образ сканера, заданный в переменной окружения сервера или в политике, находится в закрытом хранилище образов. Не записывайте пароль в policy.yml: файл хранится в репозитории открытым текстом. Политика называет две переменные CI/CD, в которых хранятся логин и пароль, а значения берутся из настроек CI/CD сканируемого проекта или группы.

В редакторе политик это поля «Переменная логина реестра» и «Переменная пароля реестра».

Поля учётных данных хранилища образов в блоке Opengrep

В файле политики это ключи variables действия:

actions:
  - scan: opengrep_sast
    variables:
      FE_SCANS_OPENGREP_IMAGE: registry.example.com/security/opengrep-scan:1.30.0-fe2
      FE_SCANS_REGISTRY_LOGIN_VARIABLE: $SCANNER_REGISTRY_USER
      FE_SCANS_REGISTRY_PASSWORD_VARIABLE: ${SCANNER_REGISTRY_PASSWORD}

Чтобы настроить доступ:

  1. В настройках CI/CD группы или проекта создайте две переменные с теми именами, которые назвала политика, — в примере SCANNER_REGISTRY_USER и SCANNER_REGISTRY_PASSWORD. Переменные группы, к которой привязана политика, действуют для всех проектов под ней.
  2. Сделайте переменную пароля маскируемой. Для обеих переменных оставьте в поле «Тип» значение «Переменная (по умолчанию)».
  3. В политике укажите имена переменных в виде $ИМЯ или ${ИМЯ}.

Что учитывать:

  • Пара одна на все сканирования действия: имена задают обе или ни одной. Имена, начинающиеся с FE_, CI_ и GITLAB_, политика отклоняет.
  • Учётные данные получают сканирования Opengrep, Gitleaks и Trivy, каждое — для хранилища своего образа. У Trivy поля находятся в блоке «Общие настройки», сразу после образа сканирования.
  • PT AI и CodeScoring берут образ, логин и пароль реестра из своей интеграции: ссылками на переменные CI/CD или самими значениями. Политика, которая называет эту пару для действия ptai или codescoring, не сохраняется (Интеграция с PT AI, Настройка интеграции CodeScoring).
  • Задачи, которые переводят отчёт сканера в JUnit (opengrep_sast_junit, gitleaks_secret_junit), учётных данных не получают: их образ задаёт администратор.
  • Сервер передаёт логин и пароль раннеру как учётные данные задачи, и раннер загружает с ними образы задачи. Сами переменные с логином и паролем остаются обычными переменными CI/CD проекта или группы и доступны сценарию задачи, как в любой задаче проекта, поэтому переменную пароля нужно сделать маскируемой.
  • Для образа сканера пара действует, даже если в DOCKER_AUTH_CONFIG проекта или раннера либо в ~/.docker/config.json раннера для того же хранилища указан другой логин.
  • DOCKER_AUTH_CONFIG проекта, группы, экземпляра и раннера (environment в config.toml) действует в задачах сканирования так же, как в любой задаче, с парой и без неё. С ним сканирование образов контейнеров и кластеров Kubernetes с помощью Trivy загружает сканируемые образы (Сканирование с помощью Trivy).
  • Образ, который поставляется с продуктом, загружается без учётных данных, даже если переменные названы: они действуют для образа, заданного в переменной окружения сервера или в политике. Исключение — Trivy: он получает учётные данные и для поставляемого образа trivy-with-db, потому что редактор политик записывает этот образ в политику.
  • Переменные должны доходить до задачи сканирования. Защищённая переменная доходит только до пайплайнов защищённых веток и тегов. У задач сканирования нет окружения, поэтому переменная с областью окружения, отличной от *, до них не доходит. Если переменная не дошла до задачи или её значение пустое, раннер загружает образ с остальными учётными данными или без логина.
  • Групповая политика опирается на групповую переменную с этим именем. Если проект задаёт переменную с тем же именем, она заменяет групповую. При неверном значении загрузка образа завершается ошибкой, и задача останавливается до первой строки сценария.
  • Сами переменные FE_SCANS_REGISTRY_LOGIN_VARIABLE и FE_SCANS_REGISTRY_PASSWORD_VARIABLE в задачу не попадают.
  • Логин и пароль может прочитать любая задача проекта, на который распространяется политика: это обычные переменные CI/CD проекта или группы.

С исполнителем Docker журнал задачи показывает, с какими учётными данными загружен образ сканера. Строка Authenticating with credentials from job payload (GitLab Registry) перед Pulling docker image означает пару из политики или интеграции: так раннер называет любые учётные данные задачи, какое бы ни было хранилище. Строка Authenticating with credentials from $DOCKER_AUTH_CONFIG означает DOCKER_AUTH_CONFIG задачи.

Образ сканера загружен с учётными данными из политики

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

Задача ищет в образе исполняемый файл opengrep, а если его нет — semgrep, который читает ту же командную строку; образ без обоих останавливает задачу с сообщением no opengrep in this image. С Semgrep сканирование выполняется с флагом --metrics=off, поэтому ничего не отправляет вендору; у Opengrep телеметрии нет, и выключать нечего. Какой бы движок ни выполнялся, сканирование запускается с --disable-version-check, а прежде чем движок вообще будет найден, задача очищает все унаследованные переменные OPENGREP_*, SEMGREP_* и PYTHON* и сбрасывает PATH, поэтому настройки CI/CD проверяемого проекта не могут подменить набор правил, базу сравнения или исполняемый файл того сканирования, которое его проверяет.

Файл игнорирования сохраняет имя .semgrepignore, а открытый набор правил внутри образа — имя своего каталога /rules-fe/semgrep-rules.

Диагностика

Лог задания opengrep_sast_scan содержит сведения об образе анализатора, используемом наборе правил и количестве обработанных файлов.

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

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

  • проект политик безопасности привязан к проекту, а файл .deckhouse_code/security-policies/policy.yml в нём содержит действие - scan: opengrep_sast: политика с semgrep_sast или sast не проходит проверку и пропускается целиком, а файл по прежнему пути .gitlab/security-policies/policy.yml не читается;
  • правила политики совпадают с пайплайном (ветка, источник пайплайна);
  • доступен GitLab Runner с executor docker.

Задача завершается с ошибкой «this scan cannot run the configuration the policy asks for»

Сервер отклонил параметр при формировании задачи, и задача сканирования останавливается до сканирования, печатая причину: «Образ сканера» с неполной ссылкой, отклоняемый флаг в поле «Дополнительные параметры», уровень правил или порог блокировки, которых у сканера нет, правила в политике длиннее 16 КБ, «Проект», записанный иначе, чем группа/проект, либо названный «Проект» при пустом поле «Путь к файлу». Исправьте параметр в политике.

Задача завершается с ошибкой «does not let this project’s jobs read it» или «is not on the default branch of»

Файл правил или файл фильтров назван с полем «Проект», и либо права доступа токена задач этого проекта («Настройки» → «CI/CD» → «Права доступа токена заданий CI/CD» в этом проекте) не содержат проверяемый проект, либо файла нет на ветке по умолчанию названного проекта. Проект, который задаче читать нельзя, отвечает так же, как отсутствующий файл, поэтому в обоих случаях проверьте права доступа.

Задача завершается с ошибкой «no rule set at … in this image»

Пути, указанного в поле «Путь к набору правил в образе», в разрешённом образе нет. Сверьте путь с таблицей выше и проверьте, какой образ используется на самом деле: лог задачи сканирования называет его строкой Analyzer image.

Задача завершается с ошибкой «carries no class index to switch them off by»

В группе «Исключаемые категории» установлен флажок, а разрешённый набор правил не несёт индекса своих категорий CLASSES.tsv. Снимите флажки или направьте сканирование на набор правил с индексом. В логе задачи напечатаны категории, которые её просили исключить, и прочитанный набор правил.

Соседнее сообщение — что индекс не содержит ни одного правила ни в одной из названных категорий — разбирается так же.

Задача завершается с ошибкой «the rule set this policy supplies …»

Набор, названный в поле «Путь к файлу» или записанный в поле «Правила», не прошёл проверку, которую задача выполняет перед сканированием: is not valid configuration for this scanner называет правило, которое сканер не может разобрать, holds no rules — пустой набор, asks for a newer scanner than this image has — правило, помеченное как несовместимое с движком в образе. За сообщением следует собственный вывод сканера.

Задача завершается с ошибкой «opengrep read no files at all»

Сканирование не осмотрело ничего и поэтому отказывается отчитываться об успехе. Обычные причины — фильтры, убравшие весь репозиторий, либо пустая рабочая копия. В логе задачи напечатано, сколько файлов она взяла в работу и сколько из них убрали фильтры.

Сканирование завершается успешно, но ничего не находит

Чаще всего набор правил не покрывает ни одного языка репозитория: задача сканирования тогда печатает Opengrep: … file(s) here, and the rule set covers none of their languages. и не публикует отчёт. Посмотрите лог задачи: в нём напечатан используемый путь к набору правил и число загруженных и выполненных правил. Тот же результат по другой причине даёт сужение полей «Уровни правил» или «Путь к набору правил в образе»: уровень или набор, который политика не включила, не выполняется, поэтому его находок в отчёте нет.

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