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

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

Источник: https://scansuite.ru/documentation/reference/gitlab-ci
Проверено: 2026-10-19

Это руководство проводит проект GitLab от нуля до сканирований ScanSuite, которые проверяют merge request и основную ветку. В первый раз выполните пронумерованные шаги по порядку; переменные, рецепты и решение проблем после них — справочный материал. Все ключи клиента описаны в разделе [CI/CD и автоматизация](https://scansuite.ru/documentation/reference/cicd).

> **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. **Откройте страницу «Команды»**

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

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

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

![Карточка «Автоматизация и API-токены» в ScanSuite](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/01.png)

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

![Окно нового токена в ScanSuite](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/02.png)

*Новый токен с набором «Конвейер CI»*

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

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

Набор **«Конвейер CI»** даёт токену то, что нужно конвейеру, и ничего больше: запуск и остановку сканирований, просмотр продуктов, сканирований, уязвимостей и найденных учётных данных, скачивание отчётов и создание продуктов. У каждого токена в списке виден срок действия; за 14 дней до его истечения журнал задания начинает предупреждать. Список прав — в разделе [CI/CD и автоматизация](https://scansuite.ru/documentation/reference/cicd).

### Шаг 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 и автоматизация](https://scansuite.ru/documentation/reference/cicd#test-token). Чтобы увидеть, какие сканеры может запускать ваша команда, укажите `--list-scanners` вместо `--check`.

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

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

| Key | Value | Видимость и флажки |
|---|---|---|
| SCANSUITE_URL | Адрес вашего сервера ScanSuite, например https://scansuite.example.com | Visible |
| 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](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/03.png)

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

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

![Переменные CI/CD проекта в GitLab](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/04.png)

*Все четыре переменные; маскирован только токен*

Проверка: в переменных CI/CD проекта есть все четыре ключа, и маскированным показан только `SCANSUITE_TOKEN`. Заданные здесь переменные действуют во всех заданиях и важнее переменных из `.gitlab-ci.yml`; что это значит, когда одно из заданий пишет в другой продукт, см. в разделе [«Монорепозиторий и новые продукты»](https://scansuite.ru/documentation/reference/gitlab-ci#monorepo).

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

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

```yaml
.scansuite:
  tags: [docker]
```

![Настройки раннеров в GitLab](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/05.png)

*Раннер инстанса в сети и доступен проекту*

### Шаг 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 request | quick-classic (сигнатурный Semgrep, без AI) по файлам, изменённым в merge request |
| scansuite-default-branch | При каждом push в основную ветку | standard-ai (AI SAST с проверкой достижимости, поиск секретов с AI-проверкой, проверка зависимостей) по всему репозиторию |

> **Промпт для агента: Поручите агенту добавить задание**
>
> ```text
> Добавь ScanSuite в .gitlab-ci.yml этого репозитория по инструкции https://scansuite.ru/documentation/reference/gitlab-ci: подключи шаблон с нашего сервера ScanSuite, используй quick-ai для merge request, если у нашей команды подключён AI, и перечисли переменные CI/CD, которые я должен добавить. Останавливайся на каждом шаге с пометкой «Этот шаг выполняет человек». Никогда не спрашивай у меня токен: SCANSUITE_TOKEN я добавлю сам как маскированную незащищённую переменную.
> ```

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

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

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

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

![Граф конвейера в GitLab](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/06.png)

*Конвейер с заданием шаблона, классическим сканированием и заданиями из рецептов DAST и сканирования образа*

![Журнал задания ScanSuite в GitLab](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/07.png)

*Конец журнала: блокирующие уязвимости, итог проверки и код выхода*

| Строка журнала | Смысл |
|---|---|
| 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](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/08.png)

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

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

![Страница сканирования в ScanSuite](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/09.png)

*Сканирование, запущенное конвейером, на своей странице*

![Уязвимости в ScanSuite с фильтром по сканированию](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/10.png)

*Уязвимости, найденные этим сканированием*

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

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

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

![Настройка Merge checks в GitLab](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/11.png)

*С этой настройкой непройденное сканирование блокирует слияние*

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

![Merge request в GitLab с проваленными тестами ScanSuite](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/12.png)

*Merge request, заблокированный проверкой quick-ai*

Если в команде подключён AI, проверяйте merge request набором `quick-ai`: в тесте он нашёл выполнение кода, которое сигнатурный `quick-classic` пропустил (см. [«Проверенные результаты»](https://scansuite.ru/documentation/reference/gitlab-ci#tested)). Оба набора сканируют только изменённые файлы; поиску секретов и проверке зависимостей нужен весь репозиторий, поэтому они выполняются на основной ветке.

*.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 и автоматизация](https://scansuite.ru/documentation/reference/cicd).

| Переменная | По умолчанию в шаблоне | Что делает |
|---|---|---|
| SCANSUITE_URL, SCANSUITE_TEAM, SCANSUITE_TOKEN | — | Сервер, имя команды и токен (шаг 3). |
| SCANSUITE_PRODUCT или SCANSUITE_PRODUCT_ID | — | Продукт — по точному названию или номеру. |
| SCANSUITE_CREATE_PRODUCT | выкл. | 1 — создать SCANSUITE_PRODUCT при первом запуске. |
| SCANSUITE_PROFILE | quick-classic в задании merge request, standard-ai в задании основной ветки | Набор; для DAST — quick, standard или deep. |
| SCANSUITE_CHANGED_ONLY | 1 в задании merge request | Сканировать только изменённые файлы. |
| SCANSUITE_BASE | цель merge request | С чем сравнивает --changed-only. |
| SCANSUITE_SCAN_TYPE | sast | dast или infra для рецептов ниже. |
| SCANSUITE_TARGETS | — | URL для DAST или узлы и образы для сканирования инфраструктуры. |
| SCANSUITE_PORTS | All TCP | Порты для сканирования инфраструктуры, например Top 1000 TCP/UDP. Используйте эту переменную, а не SCANSUITE_EXTRA_ARGS: в значении есть пробелы. |
| SCANSUITE_FAIL_ON_SEVERITY | high | Минимальный блокирующий уровень; none отключает проверку. |
| SCANSUITE_MAX | — | Допустимое число уязвимостей каждого уровня, например high=0,medium=10. |
| SCANSUITE_BLOCK_CLASS | — | Классы, которые блокируют при любом уровне. |
| SCANSUITE_MIN_CONFIDENCE | any | reachable: блокируют только уязвимости с подтверждённой достижимостью. |
| SCANSUITE_FAIL_ON_SECRETS | new | new, all или none. |
| SCANSUITE_SOURCE, SCANSUITE_GIT_URL, SCANSUITE_BRANCH | auto, проект, ветка конвейера | Поручить серверу клонирование вместо загрузки (см. «Большой репозиторий»). |
| SCANSUITE_TIMEOUT | 7200 | Сколько секунд клиент ждёт сканирование. |
| SCANSUITE_IDEMPOTENCY_KEY | выводится из задания GitLab | Нужна редко: задания GitLab различаются по инстансу, проекту и времени запуска. |
| SCANSUITE_CA_BUNDLE, SCANSUITE_STRICT_TLS | —, выкл. | Путь в репозитории к сертификату вашего центра сертификации; 1 — остановиться на сертификате, который раннер не может проверить. |
| SCANSUITE_EXTRA_ARGS | пусто | Любой другой ключ клиента, например --report-zip scansuite-report.zip или --include-unreachable (у него нет переменной). Значение разбивается по пробелам без учёта кавычек, поэтому значению с пробелами нужна своя переменная. |
| GIT_DEPTH | 50 | Глубина клонирования. Если в клоне нет целевой ветки merge request, клиент её скачивает. Для full-ai и других сканирований истории Git задайте "0". |

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

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

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

Набор задаётся в задании переменной `SCANSUITE_PROFILE`. Как настроить, что останавливает задание, см. в разделе [«Когда сборка завершается с ошибкой»](https://scansuite.ru/documentation/reference/cicd#gate); про отдельные сканеры и AI-параметры — в разделе [«Статический анализ»](https://scansuite.ru/documentation/reference/cicd#static).

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

## Рецепты

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

| Цель | Задание | Главные переменные | Рецепт |
|---|---|---|---|
| Сканировать развёрнутое приложение и собранный образ | scansuite-dast, scansuite-image | SCANSUITE_SCAN_TYPE, SCANSUITE_TARGETS | DAST и сканирование образов |
| Всё и каждую ночь | scansuite-nightly | SCANSUITE_PROFILE: full-ai, GIT_DEPTH: "0", SCANSUITE_MAX | Ночное полное сканирование |
| Строгая проверка на тегах релизов | scansuite-release | SCANSUITE_MIN_CONFIDENCE: reachable, SCANSUITE_FAIL_ON_SECRETS: all | Проверка релиза по тегу |
| Свой продукт для каждого сервиса, создаётся при первом запуске | scansuite-services | SCANSUITE_EXTRA_ARGS с --product-name и --create-product | Монорепозиторий и новые продукты |
| Отчёты без блокировок | scansuite-default-branch | SCANSUITE_FAIL_ON_SEVERITY: none | Сначала без блокировок |
| Большой репозиторий, который клонирует сервер | scansuite-incremental | SCANSUITE_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](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/13.png)

*Ночное расписание для основной ветки*

**Ожидаемая строка журнала:** если уязвимостей 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](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/14.png)

*Задание релиза сохраняет полный отчёт и сводку*

**Ожидаемый результат:** в артефактах задания есть `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. **Создайте пару ключей для ScanSuite**

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

   ```bash
   ssh-keygen -t ed25519 -N "" -f scansuite-deploy
   ```
2. **Добавьте открытый ключ в GitLab**

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

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

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

> **Этот шаг выполняет человек:** Вставить закрытый ключ в ScanSuite должен администратор команды или оператор.
>
> Агент никогда не работает с закрытым ключом.

![Карточка «Ключ SSH команды» в ScanSuite](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/15.png)

*Карточка «Ключ 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-репозитории](https://scansuite.ru/documentation/usage/static-code-analysis/git-repository-authentication).

### Без шаблона

**Когда:** подключать внешний файл нельзя. Очистите 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](https://github.com/cepxeo/scansuite-ci/blob/main/gitlab/EXAMPLES.md) в репозитории scansuite-ci.

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

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

![Журнал задания GitLab с ошибкой конфигурации ScanSuite](https://scansuite.ru/static/assets/img/docs/reference/gitlab-ci/16.png)

*Ошибка конфигурации: клиент сообщает код 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 подтверждённом секрете. |
| Основная ветка без AI | standard-classic | 3–4 минуты | Остановилось на 15, в том числе на тех же инъекциях, найденных несколькими правилами, и на уязвимых версиях pyyaml, flask, jinja2 и requests. |
| Merge request, добавляющий pickle.loads и eval | quick-classic | Около минуты | Прошло: сигнатурные правила не сработали ни на одной из строк. |
| Тот же merge request | quick-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; задание прошло. |
| Клонирование на сервере, incremental | standard-ai | 13 секунд при втором запуске | Первый запуск просканировал всю ветку; второй не нашёл новых коммитов и прошёл. |
| AI-сканеры по одному | mlsast со всеми параметрами | Меньше 4 минут | AI SAST остановился на 2 Critical и 3 High; только достижимые зависимости — прошло (ни одна уязвимая зависимость не была достижима); только новые подтверждённые секреты — прошло (секрет уже был известен). |
