Справочник

Пошаговая настройка GitLab CI

Пронумерованный путь от токена до merge request, которые блокируются реальными уязвимостями, затем все переменные, проверенные рецепты и решение проблем, специфичных для GitLab.

Открыть в Markdown

Это руководство проводит проект GitLab от нуля до сканирований ScanSuite, которые проверяют merge request и основную ветку. В первый раз выполните пронумерованные шаги по порядку; переменные, рецепты и решение проблем после них — справочный материал. Все ключи клиента описаны в разделе CI/CD и автоматизация.

ScanSuite Teams

Сканирования из конвейера работают через API команды, а оно есть только в ScanSuite Teams.

Коротко

Если вы уже знаете GitLab CI, вот и всё. Добавьте четыре переменные CI/CD (Settings → CI/CD → Variables): SCANSUITE_URL, SCANSUITE_TEAM (имя, которое показывает карточка «Автоматизация и API-токены»), SCANSUITE_PRODUCT и SCANSUITE_TOKEN (Masked, флажок Protect variable снят). Подключите шаблон со своего сервера:

include:
  - remote: '<YOUR_SCANSUITE_URL>/ci/scansuite.gitlab-ci.yml'

Затем включите Settings → Merge requests → Merge checks → Pipelines must succeed.

Скриншоты и проверенные результаты в конце страницы получены на GitLab CE 19.4 (self-managed) с собственным раннером на учебном приложении Flask с заложенными проблемами: SQL-инъекцией, внедрением команд, обходом каталогов, уязвимыми зависимостями и закоммиченным токеном GitHub.

Что вы получите

Задание GitLab запускает CI-клиент ScanSuite из образа appsec4u/scansuite-ci:1. Клиент загружает файлы под контролем Git, запускает сканирование на вашем сервере ScanSuite и ждёт его окончания, так что раннеру не нужны ни сканеры, ни много памяти. Когда сканирование закончилось, задание проходит или завершается с ошибкой по порогу качества (по умолчанию — любая уязвимость уровня High или Critical или любой секрет, которого у продукта раньше не было).

ИтогЧто вы получаете
Задание прошлоБлокирующих уязвимостей нет. Найденное всё равно сохраняется в ScanSuite.
Задание завершилось с ошибкойВ журнале перечислены все блокирующие уязвимости и секреты; на вкладке Tests конвейера и в merge request они показаны как проваленные тесты.
Отчётыscansuite-junit.xml (отчёт о тестах для GitLab), scansuite.json (сводка) и scansuite.sarif; они хранятся как артефакты задания 30 дней.

Что нужно заранее

Что нужноКак проверить
ScanSuite: роль «Администратор команды» в командеНа странице «Команды» написано: «Ваша роль в этой команде: Администратор команды».
Продукт для уязвимостейОн есть на странице «Продукты», или поручите создать его конвейеру (см. «Монорепозиторий и новые продукты»).
Для задания merge request по умолчанию (quick-classic): образы статических сканеров на сервереНа сервере ScanSuite, в каталоге установки, grep SCANSUITE_SCANNERS .env выводит static или all. Установка по умолчанию выводит none; системный администратор выполняет ./scansuite update --static-only. Или используйте quick-ai (шаг 7).
Для задания основной ветки (standard-ai) и quick-ai: AI-провайдер командыСтраница «Команды», вкладка «ИИ». После шага 2 --list-scanners не должен отмечать mlsast как NOT AVAILABLE.
GitLab: роль Maintainer в проектеВ меню проекта есть Settings → CI/CD.
РаннерВ Settings → CI/CD → Runners есть раннер в состоянии Online с исполнителем Docker, который выполняет задания без тегов, может скачать appsec4u/scansuite-ci:1 с Docker Hub и видит ваш сервер ScanSuite по HTTPS. Подойдут и общие раннеры GitLab.com, если сервер доступен из интернета.

Настройка

Шаг 1. Выпустите токен в ScanSuite

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

  1. 01
    Откройте страницу «Команды»

    «Команды» в боковом меню, затем вкладка «Люди». Прокрутите до карточки «Автоматизация и API-токены». В её верхней строке написано «Имя этой команды в конвейерах и адресах API (SCANSUITE_TEAM)» и жирным — имя: это значение SCANSUITE_TEAM. Первая команда установки называется default, даже если её переименовали.

  2. 02
    Заведите сервисный аккаунт

    В поле «Новый сервисный аккаунт» укажите имя, например gitlab-ci, в поле «Роль» выберите «Оператор» (роль по умолчанию, «Читатель», запускать сканирования не может) и нажмите «Создать». Проверка: аккаунт появился в списке с ролью «Оператор» и отметкой «Активно».

  3. 03
    Выпустите токен

    Нажмите «Новый токен» у нового аккаунта. Заполните «Имя токена» (например, gitlab-backend) и «Срок действия (дней)» (по умолчанию 30, не больше 90), в поле «Что он может?» оставьте «Конвейер CI» и нажмите «Создать токен». Проверка: открывается окно «Ваш новый токен».

Карточка «Автоматизация и API-токены» в ScanSuite
Карточка «Автоматизация и API-токены»: имя команды для конвейеров, сервисные аккаунты и их токены
Окно нового токена в ScanSuite
Новый токен с набором «Конвейер CI»

Окно «Ваш новый токен» показывает токен с кнопкой «Копировать», строку «Имя этой команды в конвейерах и адресах API (SCANSUITE_TEAM)» и блок «Проверьте подключение» с двумя командами, в которые уже подставлены сервер, команда и токен: «Через клиент для конвейеров (Docker)» и «Через curl».

Скопируйте токен. Он показывается один раз; держите его у себя, только пока на шаге 3 он не попадёт в GitLab, и никогда не вставляйте его в чат, заявку или репозиторий. Если токен потерялся, отзовите его в карточке и выпустите новый.

Набор «Конвейер CI» даёт токену то, что нужно конвейеру, и ничего больше: запуск и остановку сканирований, просмотр продуктов, сканирований, уязвимостей и найденных учётных данных, скачивание отчётов и создание продуктов. У каждого токена в списке виден срок действия; за 14 дней до его истечения журнал задания начинает предупреждать. Список прав — в разделе CI/CD и автоматизация.

Шаг 2. Проверьте токен

Выполните эти команды в своём терминале: вторая просит вставить токен.

bash
export SCANSUITE_URL=<YOUR_SCANSUITE_URL> SCANSUITE_TEAM=<YOUR_TEAM>
read -rs SCANSUITE_TOKEN && export SCANSUITE_TOKEN
docker run --rm -e SCANSUITE_URL -e SCANSUITE_TEAM -e SCANSUITE_TOKEN appsec4u/scansuite-ci:1 --check

Ожидаемый вывод: Connected to … the server accepts the API token for team … (role operator), права токена и срок его действия, и The token can run pipeline scans. Если токен отклонён, клиент завершается с кодом 3 и называет причину: срок истёк, токен отозван, сервисный аккаунт отключён, команда не активна, токен неизвестен или принадлежит другой команде (тогда сообщение называет команду, которую нужно указать). Как исправить каждую из них, сказано в разделе CI/CD и автоматизация. Чтобы увидеть, какие сканеры может запускать ваша команда, укажите --list-scanners вместо --check.

Шаг 3. Добавьте переменные CI/CD в GitLab

В проекте GitLab: Settings → CI/CD → Variables → Add variable, по разу для каждой переменной:

KeyValueВидимость и флажки
SCANSUITE_URLАдрес вашего сервера ScanSuite, например https://scansuite.example.comVisible
SCANSUITE_TEAMИмя команды из карточки «Автоматизация и API-токены» (шаг 1) или из окна нового токена.Visible
SCANSUITE_PRODUCTТочное название продукта, как на странице «Продукты». Или SCANSUITE_PRODUCT_ID с его номером.Visible
SCANSUITE_TOKENТокен из шага 1.Masked, флажок Protect variable снят

Добавьте SCANSUITE_TOKEN сами: видимость Masked, флажок Protect variable снят.

Панель Add variable в GitLab
SCANSUITE_TOKEN: видимость Masked, флажок Protect variable снят
Снимите флажок Protect variable у SCANSUITE_TOKEN

GitLab ставит флажок Protect variable по умолчанию. Защищённая переменная доступна только конвейерам защищённых веток и тегов, поэтому любой merge request из обычной ветки завершится ошибкой Set SCANSUITE_TOKEN ... с кодом выхода 3. Оставляйте токен защищённым, только если все конвейеры со сканированием запускаются на защищённых ветках или тегах.

Переменные CI/CD проекта в GitLab
Все четыре переменные; маскирован только токен

Проверка: в переменных CI/CD проекта есть все четыре ключа, и маскированным показан только SCANSUITE_TOKEN. Заданные здесь переменные действуют во всех заданиях и важнее переменных из .gitlab-ci.yml; что это значит, когда одно из заданий пишет в другой продукт, см. в разделе «Монорепозиторий и новые продукты».

Шаг 4. Проверьте раннер

Раннеры, доступные проекту, перечислены в Settings → CI/CD → Runners. Хотя бы один из них должен быть в состоянии Online, работать с исполнителем Docker и выполнять задания без тегов. Если ваши раннеры берут только задания с тегами, добавьте тег скрытому заданию шаблона в своём .gitlab-ci.yml:

yaml
.scansuite:
  tags: [docker]
Настройки раннеров в GitLab
Раннер инстанса в сети и доступен проекту

Шаг 5. Добавьте конвейер

Сервер ScanSuite раздаёт шаблон для GitLab CI, который всегда соответствует версии сервера. Добавьте этот фрагмент в .gitlab-ci.yml в корне репозитория (если файла нет, создайте его), указав адрес своего сервера, и закоммитьте его в основную ветку. Этот push запустит первый конвейер.

.gitlab-ci.yml
include:
  - remote: '<YOUR_SCANSUITE_URL>/ci/scansuite.gitlab-ci.yml'
Задание из шаблонаКогда запускаетсяСканирование
scansuite-merge-requestВ каждом merge requestquick-classic (сигнатурный Semgrep, без AI) по файлам, изменённым в merge request
scansuite-default-branchПри каждом push в основную веткуstandard-ai (AI SAST с проверкой достижимости, поиск секретов с AI-проверкой, проверка зависимостей) по всему репозиторию
Поручите агенту добавить задание
Добавь ScanSuite в .gitlab-ci.yml этого репозитория по инструкции https://scansuite.ru/documentation/reference/gitlab-ci: подключи шаблон с нашего сервера ScanSuite, используй quick-ai для merge request, если у нашей команды подключён AI, и перечисли переменные CI/CD, которые я должен добавить. Останавливайся на каждом шаге с пометкой «Этот шаг выполняет человек». Никогда не спрашивай у меня токен: SCANSUITE_TOKEN я добавлю сам как маскированную незащищённую переменную.

Вставьте его в Claude Code или другой ИИ-агент для разработки. Подробнее — в разделе Работа с ИИ-агентами.

В конвейере уже объявлены стадии? Оставьте их и добавьте test, если её нет: задания шаблона работают в этой стадии. Если подключать внешний файл не хочется, скопируйте содержимое шаблона по тому же адресу в свой репозиторий; AI SAST считает подключение внешнего файла без фиксации версии уязвимостью уровня Medium.

Проверка: в Build → Pipelines появился новый конвейер с заданием scansuite-default-branch. Последние строки [scansuite] его журнала — либо Quality gate passed, либо Quality gate FAILED: N blocking finding(s), M blocking secret(s). Любое другое окончание разобрано в разделе «Если что-то пошло не так».

Шаг 6. Посмотрите результат

Откройте Build → Pipelines, последний конвейер, а затем задание. В конце журнала написано, что нашло сканирование и почему задание не прошло:

Граф конвейера в GitLab
Конвейер с заданием шаблона, классическим сканированием и заданиями из рецептов DAST и сканирования образа
Журнал задания ScanSuite в GitLab
Конец журнала: блокирующие уязвимости, итог проверки и код выхода
Строка журналаСмысл
Team default, product shop-api (#8)Команда и продукт, куда задание отправляет результаты.
Scan jfzyghvb (#95) Queued … FinishedИдентификатор сканирования: по нему его можно найти в ScanSuite.
Open findings in this scan: Critical 1, High 2, …Всё, что нашло сканирование.
BLOCKING [Critical] OS command injection -- app.py::host (Reachable)По строке на каждую уязвимость, из-за которой порог не пройден: файл, место в коде и причина.
BLOCKING [Secret] github_token -- …/settings.py#L3Блокирующий секрет со ссылкой на файл в GitLab.
Quality gate FAILED: 3 blocking finding(s), 1 blocking secret(s)Итог проверки.
Exit code 1: the quality gate failed …Почему задание не прошло. Ниже GitLab всегда пишет exit code 1, а настоящий код — в этой строке.

На вкладке Tests конвейера каждая блокирующая уязвимость показана как проваленный тест, с разбивкой по заданиям. Отчёты JSON и SARIF доступны на странице задания, в блоке Job artifacts: кнопки Download и Browse.

Вкладка Tests конвейера в GitLab
Вкладка Tests: по проваленному тесту на каждую блокирующую уязвимость

В ScanSuite сканирование из конвейера — обычное сканирование продукта: оно появляется в «Истории сканирований» под именем архива проекта, а на его странице перечислено, что оно нашло. Уязвимости ссылаются на файл и строку в GitLab на просканированном коммите. Разбирайте их как обычно: порог учитывает только уязвимости в статусах Open и In Progress, так что уязвимость, закрытая как ложное срабатывание или принятый риск, следующий конвейер уже не остановит.

Страница сканирования в ScanSuite
Сканирование, запущенное конвейером, на своей странице
Уязвимости в ScanSuite с фильтром по сканированию
Уязвимости, найденные этим сканированием

Шаг 7. Проверяйте merge request

Задание с ошибкой не даёт слить изменения, только если этого требует проект.

В GitLab включите Settings → Merge requests → Merge checks → Pipelines must succeed и сохраните. Это меняет порядок слияния каждого merge request в проекте, поэтому решение принимают мейнтейнеры проекта.

Настройка Merge checks в GitLab
С этой настройкой непройденное сканирование блокирует слияние

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

Merge request в GitLab с проваленными тестами ScanSuite
Merge request, заблокированный проверкой quick-ai

Если в команде подключён AI, проверяйте merge request набором quick-ai: в тесте он нашёл выполнение кода, которое сигнатурный quick-classic пропустил (см. «Проверенные результаты»). Оба набора сканируют только изменённые файлы; поиску секретов и проверке зависимостей нужен весь репозиторий, поэтому они выполняются на основной ветке.

.gitlab-ci.yml
include:
  - remote: '<YOUR_SCANSUITE_URL>/ci/scansuite.gitlab-ci.yml'

scansuite-merge-request:
  variables:
    SCANSUITE_PROFILE: quick-ai

Переменные

Задайте переменную для одного задания в блоке variables: или для всех заданий в Settings → CI/CD → Variables (переменные проекта важнее переменных задания). Параметры порога, наборы и все остальные ключи описаны в разделе CI/CD и автоматизация.

ПеременнаяПо умолчанию в шаблонеЧто делает
SCANSUITE_URL, SCANSUITE_TEAM, SCANSUITE_TOKEN—Сервер, имя команды и токен (шаг 3).
SCANSUITE_PRODUCT или SCANSUITE_PRODUCT_ID—Продукт — по точному названию или номеру.
SCANSUITE_CREATE_PRODUCTвыкл.1 — создать SCANSUITE_PRODUCT при первом запуске.
SCANSUITE_PROFILEquick-classic в задании merge request, standard-ai в задании основной веткиНабор; для DAST — quick, standard или deep.
SCANSUITE_CHANGED_ONLY1 в задании merge requestСканировать только изменённые файлы.
SCANSUITE_BASEцель merge requestС чем сравнивает --changed-only.
SCANSUITE_SCAN_TYPEsastdast или infra для рецептов ниже.
SCANSUITE_TARGETS—URL для DAST или узлы и образы для сканирования инфраструктуры.
SCANSUITE_PORTSAll TCPПорты для сканирования инфраструктуры, например Top 1000 TCP/UDP. Используйте эту переменную, а не SCANSUITE_EXTRA_ARGS: в значении есть пробелы.
SCANSUITE_FAIL_ON_SEVERITYhighМинимальный блокирующий уровень; none отключает проверку.
SCANSUITE_MAX—Допустимое число уязвимостей каждого уровня, например high=0,medium=10.
SCANSUITE_BLOCK_CLASS—Классы, которые блокируют при любом уровне.
SCANSUITE_MIN_CONFIDENCEanyreachable: блокируют только уязвимости с подтверждённой достижимостью.
SCANSUITE_FAIL_ON_SECRETSnewnew, all или none.
SCANSUITE_SOURCE, SCANSUITE_GIT_URL, SCANSUITE_BRANCHauto, проект, ветка конвейераПоручить серверу клонирование вместо загрузки (см. «Большой репозиторий»).
SCANSUITE_TIMEOUT7200Сколько секунд клиент ждёт сканирование.
SCANSUITE_IDEMPOTENCY_KEYвыводится из задания GitLabНужна редко: задания GitLab различаются по инстансу, проекту и времени запуска.
SCANSUITE_CA_BUNDLE, SCANSUITE_STRICT_TLS—, выкл.Путь в репозитории к сертификату вашего центра сертификации; 1 — остановиться на сертификате, который раннер не может проверить.
SCANSUITE_EXTRA_ARGSпустоЛюбой другой ключ клиента, например --report-zip scansuite-report.zip или --include-unreachable (у него нет переменной). Значение разбивается по пробелам без учёта кавычек, поэтому значению с пробелами нужна своя переменная.
GIT_DEPTH50Глубина клонирования. Если в клоне нет целевой ветки merge request, клиент её скачивает. Для full-ai и других сканирований истории Git задайте "0".

Скрытое задание шаблона .scansuite работает в стадии test с образом appsec4u/scansuite-ci:1, пишет scansuite-junit.xml (публикуется как отчёт о тестах), scansuite.json и scansuite.sarif и хранит их 30 дней.

Что и когда сканировать

СобытиеБез AIС AI
Merge requestquick-classicquick-ai
Основная веткаstandard-classicstandard-ai
По ночам или перед релизомfull-classicfull-ai (самый медленный и самый дорогой в AI)

Набор задаётся в задании переменной SCANSUITE_PROFILE. Как настроить, что останавливает задание, см. в разделе «Когда сборка завершается с ошибкой»; про отдельные сканеры и AI-параметры — в разделе «Статический анализ».

Для первого сканирования продукта все секреты новые. Поэтому задание, которое создаёт продукт, или первое сканирование уже существующего репозитория остановится на давно закоммиченных секретах. Разберите их в ScanSuite или на первое время задайте SCANSUITE_FAIL_ON_SECRETS: none.

Рецепты

Каждый рецепт — это задание, которое нужно добавить в .gitlab-ci.yml после include. Задания наследуют скрытое задание шаблона .scansuite, а вместе с ним образ, отчёты и артефакты.

ЦельЗаданиеГлавные переменныеРецепт
Сканировать развёрнутое приложение и собранный образscansuite-dast, scansuite-imageSCANSUITE_SCAN_TYPE, SCANSUITE_TARGETSDAST и сканирование образов
Всё и каждую ночьscansuite-nightlySCANSUITE_PROFILE: full-ai, GIT_DEPTH: "0", SCANSUITE_MAXНочное полное сканирование
Строгая проверка на тегах релизовscansuite-releaseSCANSUITE_MIN_CONFIDENCE: reachable, SCANSUITE_FAIL_ON_SECRETS: allПроверка релиза по тегу
Свой продукт для каждого сервиса, создаётся при первом запускеscansuite-servicesSCANSUITE_EXTRA_ARGS с --product-name и --create-productМонорепозиторий и новые продукты
Отчёты без блокировокscansuite-default-branchSCANSUITE_FAIL_ON_SEVERITY: noneСначала без блокировок
Большой репозиторий, который клонирует серверscansuite-incrementalSCANSUITE_SOURCE: git, --mode incrementalБольшой репозиторий
Без внешнего подключенияscansuite—Без шаблона

DAST и сканирование образов

Когда: после развёртывания на тестовый стенд и после сборки образа, на более поздней стадии. Благодаря needs: [] эти задания запускаются, даже если статическое сканирование уже остановило сборку; без этого GitLab их пропустит.

.gitlab-ci.yml
stages: [test, verify]

scansuite-dast:
  extends: .scansuite
  stage: verify
  needs: []
  variables:
    SCANSUITE_SCAN_TYPE: dast
    SCANSUITE_TARGETS: https://staging.example.com
    SCANSUITE_PROFILE: quick
    SCANSUITE_FAIL_ON_SEVERITY: critical
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PIPELINE_SOURCE != "merge_request_event"

scansuite-image:
  extends: .scansuite
  stage: verify
  needs: []
  variables:
    SCANSUITE_SCAN_TYPE: infra
    SCANSUITE_TARGETS: registry.example.com/shop/api:$CI_COMMIT_SHORT_SHA
    SCANSUITE_EXTRA_ARGS: --scanners docker_image_scan
    SCANSUITE_FAIL_ON_SEVERITY: critical
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PIPELINE_SOURCE != "merge_request_event"

Ожидаемая строка журнала: Quality gate passed или Quality gate FAILED: … со строкой BLOCKING на каждую уязвимость уровня Critical. Оговорка: цели должны быть разрешены команде (страница «Команды», вкладка «Сканирование», «Веб-цели» и «Инфраструктурные цели»); иначе задание завершится с кодом 3 ещё до начала сканирования и назовёт запрещённую цель.

Ночное полное сканирование

Когда: конвейер по расписанию. Создайте расписание в Build → Pipeline schedules и добавьте задание. Набор full-ai анализирует историю Git, поэтому задание скачивает её целиком.

.gitlab-ci.yml
scansuite-nightly:
  extends: .scansuite
  timeout: 4h
  variables:
    SCANSUITE_PROFILE: full-ai
    GIT_DEPTH: "0"
    SCANSUITE_MAX: high=0,critical=0,medium=10
    SCANSUITE_TIMEOUT: "14400"
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
Расписания конвейеров в GitLab
Ночное расписание для основной ветки

Ожидаемая строка журнала: если уязвимостей Medium больше бюджета, строка выглядит так: Medium: 12 found, 10 allowed. Оговорка: GitLab прерывает задание по собственному таймауту (по умолчанию час, значение видно в поле Timeout на странице задания) раньше, чем истечёт SCANSUITE_TIMEOUT, поэтому в задании указан timeout: 4h; ограничение самого раннера при этом сохраняется.

Проверка релиза по тегу

Когда: в репозиторий отправлен тег. Проверка строже, чем для merge request: только достижимые уязвимости, все секреты продукта, а полный отчёт сохраняется вместе с релизом.

.gitlab-ci.yml
stages: [test, release]

scansuite-release:
  extends: .scansuite
  stage: release
  variables:
    SCANSUITE_PROFILE: standard-ai
    SCANSUITE_FAIL_ON_SEVERITY: medium
    SCANSUITE_MIN_CONFIDENCE: reachable
    SCANSUITE_FAIL_ON_SECRETS: all
    SCANSUITE_EXTRA_ARGS: --report-zip scansuite-report.zip
  artifacts:
    when: always
    paths: [scansuite-report.zip, scansuite.json]
  rules:
    - if: $CI_COMMIT_TAG
Артефакты задания GitLab: scansuite-report.zip
Задание релиза сохраняет полный отчёт и сводку

Ожидаемый результат: в артефактах задания есть scansuite-report.zip. Оговорка: при all учитываются и секреты, которые прежние сканирования уже знали, поэтому релиз не пройдёт, пока не разобран каждый открытый секрет.

Монорепозиторий и новые продукты

Когда: по заданию на каждую папку сервиса, и каждое пишет в свой продукт, который создаётся при первом запуске. Продукт передаётся ключом: переменная SCANSUITE_PRODUCT в задании уступит переменной проекта из шага 3, и все сервисы окажутся в одном продукте.

.gitlab-ci.yml
scansuite-services:
  extends: .scansuite
  parallel:
    matrix:
      - SERVICE: [payments, web]
  variables:
    SCANSUITE_PROFILE: quick-classic
    SCANSUITE_CHANGED_ONLY: "1"
    SCANSUITE_EXTRA_ARGS: --source-dir services/$SERVICE --product-name $SERVICE --create-product
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Для одного нового репозитория задайте ключи один раз в скрытом задании, и их унаследуют все задания (или добавьте в переменные проекта SCANSUITE_CREATE_PRODUCT со значением 1 рядом с SCANSUITE_PRODUCT):

.gitlab-ci.yml
.scansuite:
  variables:
    SCANSUITE_EXTRA_ARGS: --product-name $CI_PROJECT_NAME --create-product

Ожидаемая строка журнала: Created product payments (#10) при первом запуске, затем Team default, product payments (#10) при каждом запуске. Оговорка: если задание задаёт собственный SCANSUITE_EXTRA_ARGS, оно заменяет значение скрытого задания, поэтому повторите в нём оба ключа.

Сначала без блокировок

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

.gitlab-ci.yml
scansuite-default-branch:
  variables:
    SCANSUITE_FAIL_ON_SEVERITY: none
    SCANSUITE_FAIL_ON_SECRETS: none

Чтобы задание останавливалось на уязвимостях, но не из-за недоступности ScanSuite, вместо этого задайте SCANSUITE_EXTRA_ARGS: --soft-fail. Ожидаемая строка журнала при недоступном сервере: WARNING: --soft-fail: exiting 0 instead of 5.

Большой репозиторий: клонирование на стороне сервера

Когда: загрузка рабочей копии идёт медленно. Сервер ScanSuite сам клонирует ветку, а с --mode incremental сканирует только то, что изменилось после его последнего сканирования этой ветки.

  1. 01
    Создайте пару ключей для ScanSuite

    Без парольной фразы: ключ, защищённый ею, ScanSuite не примет. Не используйте эту пару ни для чего другого.

    Терминал
    ssh-keygen -t ed25519 -N "" -f scansuite-deploy
  2. 02
    Добавьте открытый ключ в GitLab

    В проекте: Settings → Repository → Deploy keys → Add new key, с содержимым scansuite-deploy.pub. Права на запись не включайте.

  3. 03
    Добавьте закрытый ключ в ScanSuite

    Страница «Команды» → вкладка «Сканирование» → «Ключ SSH команды»: вставьте содержимое scansuite-deploy в поле «Закрытый ключ» и нажмите «Сохранить». Проверка: карточка показывает отпечаток ключа. Затем удалите файл.

  4. 04
    Добавьте задание

    С SSH-адресом проекта. Если SSH в GitLab работает не на порту 22, нужен адрес вида ssh:// с номером порта, как в примере ниже.

Вставить закрытый ключ в ScanSuite должен администратор команды или оператор.

Карточка «Ключ SSH команды» в ScanSuite
Карточка «Ключ SSH команды» на вкладке «Сканирование»
.gitlab-ci.yml
scansuite-incremental:
  extends: .scansuite
  variables:
    SCANSUITE_SOURCE: git
    SCANSUITE_GIT_URL: ssh://git@gitlab.example.com:2222/$CI_PROJECT_PATH.git
    SCANSUITE_PROFILE: standard-ai
    SCANSUITE_EXTRA_ARGS: --mode incremental
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Ожидаемая строка журнала: Source: ssh://…/shop-backend.git @ main (the server clones the branch head, not necessarily …); при запуске без новых коммитов — Nothing to scan: …, и задание проходит. Оговорки: сканирования из конвейера всегда клонируют с ключом SSH команды, а не с личным ключом пользователя. Сервер берёт ветку в том состоянии, в каком она была в момент запуска сканирования, а оно может быть новее коммита конвейера. При первом клонировании сервер запоминает SSH-ключ хоста Git-сервера и в дальнейшем отказывается работать, если ключ изменился: если GitLab переустановили или перенесли, клонирование завершается ошибкой could not resolve the remote revision: @@@@…, пока администратор ScanSuite не удалит старый ключ из /var/tmp/scansuite/git-auth/known_hosts в контейнере worker. Подробнее о ключах — в разделе Аутентификация в Git-репозитории.

Без шаблона

Когда: подключать внешний файл нельзя. Очистите entrypoint образа: GitLab запускает в контейнере собственную оболочку.

.gitlab-ci.yml
scansuite:
  stage: test
  image:
    name: appsec4u/scansuite-ci:1
    entrypoint: [""]
  variables:
    GIT_DEPTH: "50"
  script:
    - scansuite-ci --profile quick-classic --changed-only --junit scansuite-junit.xml --sarif scansuite.sarif
  artifacts:
    when: always
    reports: { junit: scansuite-junit.xml }
    paths: [scansuite.sarif]
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Эти же рецепты есть в примерах для GitLab в репозитории scansuite-ci.

Если что-то пошло не так

Что бы ни случилось, GitLab завершает задание с ошибкой строкой ERROR: Job failed: exit code 1. Настоящий код выхода — в последней строке клиента, которая начинается с [scansuite]; коды расшифрованы в разделе CI/CD и автоматизация.

Журнал задания GitLab с ошибкой конфигурации ScanSuite
Ошибка конфигурации: клиент сообщает код 3, а GitLab — exit code 1
Сообщение или признакПричина и решение
Set SCANSUITE_TOKEN ...Токен не попал в задание: переменная защищена (Protected), а конвейер запущен на незащищённой ветке (шаг 3), или переменной нет вовсе.
The server rejected the API token …Причина указана в сообщении: срок истёк, токен отозван, аккаунт отключён, другая команда, токен неизвестен. Выполните проверку из шага 2.
Product 'X' was not found in team YЗначение SCANSUITE_PRODUCT не совпадает с названием продукта в точности, или неверно задан SCANSUITE_TEAM. Чтобы создать продукт, добавьте --create-product.
The API token lacks permission(s): ...Токен выпущен без набора «Конвейер CI», или у сервисного аккаунта роль «Читатель». Выпустите новый токен.
Cannot run on this server: openvas: ...Сканер не настроен для вашей команды; где его настроить, сказано в сообщении.
Уязвимости попадают не в тот продуктВ задании задана переменная SCANSUITE_PRODUCT, но переменная проекта важнее. Передайте --product-name через SCANSUITE_EXTRA_ARGS.
--changed-only: no base to compare withКонвейер запущен не для merge request, или в клоне нет целевой ветки. Тогда задание сканирует всё.
This is a shallow clone, so Git history analysis sees only ...Для full-ai и других сканирований истории Git задайте GIT_DEPTH: "0".
Задание поздней стадии пропущеноСканирование на одной из предыдущих стадий завершилось с ошибкой. Добавьте заданию needs: [].
Задание завершается со статусом TimeoutРаньше сработал таймаут задания GitLab (по умолчанию час). Добавьте заданию timeout: 4h.

Отмена задания отменяет и сканирование. Если отменить конвейер в GitLab, клиент останавливает сканирование в ScanSuite до завершения задания (Cancelled scan … (pipeline interrupted)). А если клиент сам перестал ждать (SCANSUITE_TIMEOUT, код выхода 4), сканирование продолжится, если не добавить --cancel-on-timeout.

Проверенные результаты

Как каждая настройка отработала на учебном приложении в прогоне 3 октября 2026 года. Время зависит от кодовой базы и AI-провайдера.

НастройкаНаборВремяРезультат
Задание основной ветки из шаблонаstandard-aiОколо 3 минутОстановилось на 3 достижимых уязвимостях (инъекциях и обходе каталогов) и 1 подтверждённом секрете.
Основная ветка без AIstandard-classic3–4 минутыОстановилось на 15, в том числе на тех же инъекциях, найденных несколькими правилами, и на уязвимых версиях pyyaml, flask, jinja2 и requests.
Merge request, добавляющий pickle.loads и evalquick-classicОколо минутыПрошло: сигнатурные правила не сработали ни на одной из строк.
Тот же merge requestquick-aiОколо 30 секундОстановилось на двух уязвимостях Critical: небезопасной десериализации и выполнении кода через eval.
Порог critical плюс блокирующие классыstandard-ai—Всё равно остановилось на SQL-инъекциях и внедрении команд уровня High с пометкой blocked class sql_injection.
DAST и сканирование образовquick; docker_image_scan—DAST прошёл (проблемы уровней High и Medium, ниже его порога critical); образ не прошёл из-за 9 CVE уровня Critical в python:3.8-slim.
Ночное полное сканированиеfull-aiОт 7 до 25 минут2 Critical, 3 High и 2 Medium: 5 уязвимостей High и Critical остановили задание, Medium уложились в бюджет.
Проверка релизаstandard-ai—Остановилась на шести достижимых уязвимостях уровня Medium и выше, в том числе на открытом для всего интернета доступе по SSH в main.tf и подключении внешнего файла без фиксации версии, а также на известном токене GitHub.
Монорепозиторий, merge request затрагивает оба сервисаquick-classic—Задание payments остановилось на SQL-инъекции, задание web прошло: merge request заблокирован из-за одного сервиса.
Soft fail, сервер недоступен—Около минуты повторных попытокЗаписано --soft-fail: exiting 0 instead of 5; задание прошло.
Клонирование на сервере, incrementalstandard-ai13 секунд при втором запускеПервый запуск просканировал всю ветку; второй не нашёл новых коммитов и прошёл.
AI-сканеры по одномуmlsast со всеми параметрамиМеньше 4 минутAI SAST остановился на 2 Critical и 3 High; только достижимые зависимости — прошло (ни одна уязвимая зависимость не была достижима); только новые подтверждённые секреты — прошло (секрет уже был известен).

Проверено: 2026-10-19