Управление пайплайнами сканирования

Что такое скан-пайплайн

Скан-пайплайн — это логическая цепочка сканирований и загрузок результатов в рамках одного продукта или репозитория. Пайплайн объединяет несколько операций (джобы) в единый процесс, позволяя отследить общий статус и дождаться завершения агрегации всех результатов.

Составные части пайплайна

Каждый пайплайн состоит из джобов (jobs):

Загрузка результатов (upload) — каждый вызов upload с привязкой к пайплайну создаёт отдельную джобу;
Сканирование (scan) — при запуске сканирования через оркестрацию Vampy (команда scan) в пайплайн попадают джобы сканеров из профиля или конкретного сканера.

Пайплайн отслеживает:

статус каждой джобы (PENDING, IN_PROGRESS, SUCCESS, ERROR);
общий статус всего пайплайна (SUCCESS, PARTIAL_SUCCESS, ERROR, PENDING, IN_PROGRESS);
завершение агрегации результатов (aggregationCompleted).

Режимы работы

Автосоздание при загрузке — пайплайн создаётся автоматически при первом upload с --pipeline-id, завершается сразу после обработки, если указан --pipeline-finish.
Автосоздание при сканировании — пайплайн создаётся при scan, завершается автоматически после выполнения всех джобов сканирования и агрегации.
Ручной режим — явное создание через pipeline create, несколько upload с одним --pipeline-id, ручной вызов pipeline finish и контроль статуса через pipeline status.

Команда pipeline и список list pipelines ходят в один и тот же API: удобно вызывать pipeline list или list pipelines — поведение совпадает.

Сценарии работы с пайплайнами

Сценарий 1: Автосоздание при загрузке (автофинал)

Пайплайн создаётся автоматически при первом upload с --pipeline-id, завершается сразу после обработки загрузки.

┌─────────────────────────────────────────────────────────────────────┐
│  Сценарий 1: Автосоздание при загрузке с автофиналом                │
└─────────────────────────────────────────────────────────────────────┘

  ┌──────────────────────────────────────────────────────────────┐
  │  vampy-cli upload --file scan.json --scanner TRIVY_FS        │
  │    --repository my-repo --pipeline-finish --check-full       │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           ├──► POST /scan_uploads/
                           │    ├─ создаёт пайплайн (PENDING)
                           │    └─ добавляет джобу загрузки
                           │
                           ├──► Обработка загрузки (BG task)
                           │    └─ парсинг, дедупликация, сохранение
                           │
                           ├──► Автофинал пайплайна
                           │    └─ POST /scan/pipelines/{id}/finish/
                           │
                           ├──► Агрегация результатов
                           │    └─ aggregationCompleted: true
                           │
                           ├──► Статус пайплайна: SUCCESS
                           │
                           └──► Проверка Quality Gate (если --check-full)
                                └─ exit code: 0 / 2 / 4

  Итог: один upload → один пайплайн → автофинал → агрегация → QG

Сценарий 2: Автосоздание при сканировании

Пайплайн создаётся при запуске scan, завершается после выполнения всех джобов сканирования и агрегации.

┌─────────────────────────────────────────────────────────────────────┐
│  Сценарий 2: Автосоздание при сканировании                          │
└─────────────────────────────────────────────────────────────────────┘

  ┌──────────────────────────────────────────────────────────────┐
  │  vampy-cli scan --repository my-repo --profile default       │
  │    --check-full --verbose                                    │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           ├──► POST /orchestration/scan/
                           │    ├─ создаёт пайплайн (PENDING)
                           │    └─ добавляет джобы сканеров из профиля
                           │
                           ├──► Оркестрация запускает сканеры
                           │    ├─ джоба 1: SEMGREP (IN_PROGRESS → SUCCESS)
                           │    ├─ джоба 2: TRIVY_FS (IN_PROGRESS → SUCCESS)
                           │    └─ джоба 3: GITLEAKS (IN_PROGRESS → SUCCESS)
                           │
                           ├──► Автофинал пайплайна
                           │    └─ все джобы завершены → finish
                           │
                           ├──► Агрегация результатов
                           │    └─ aggregationCompleted: true
                           │
                           ├──► Статус пайплайна: SUCCESS / PARTIAL_SUCCESS
                           │
                           └──► Проверка Quality Gate (если --check-full)
                                └─ exit code: 0 / 2 / 4

  Итог: scan → пайплайн с N джобами → автофинал → агрегация → QG

Сценарий 3: Ручной режим (несколько загрузок)

Явное создание пайплайна, несколько загрузок с одним --pipeline-id, ручной финиш и контроль статуса.

┌─────────────────────────────────────────────────────────────────────┐
│  Сценарий 3: Ручной режим (несколько загрузок в один пайплайн)      │
└─────────────────────────────────────────────────────────────────────┘

  ┌──────────────────────────────────────────────────────────────┐
  │  1. vampy-cli pipeline create --repository my-repo           │
  │       --pipeline-id "$CI_COMMIT_SHA"                         │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           └──► POST /scan/pipelines/
                                └─ создаёт пайплайн (PENDING)

  ┌──────────────────────────────────────────────────────────────┐
  │  2. vampy-cli upload --file trivy.json --scanner TRIVY_FS    │
  │       --repository my-repo --pipeline-id "$CI_COMMIT_SHA"    │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           └──► POST /scan_uploads/
                                ├─ привязывает к существующему пайплайну
                                └─ добавляет джобу 1: TRIVY_FS

  ┌──────────────────────────────────────────────────────────────┐
  │  3. vampy-cli upload --file semgrep.json --scanner SEMGREP   │
  │       --repository my-repo --pipeline-id "$CI_COMMIT_SHA"    │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           └──► POST /scan_uploads/
                                └─ добавляет джобу 2: SEMGREP

  ┌──────────────────────────────────────────────────────────────┐
  │  4. vampy-cli upload --file gitleaks.json --scanner GITLEAKS │
  │       --repository my-repo --pipeline-id "$CI_COMMIT_SHA"    │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           └──► POST /scan_uploads/
                                └─ добавляет джобу 3: GITLEAKS

  ┌──────────────────────────────────────────────────────────────┐
  │  5. vampy-cli pipeline status --pipeline-id "$CI_COMMIT_SHA" │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           └──► GET /scan/pipelines/{id}/status/
                                └─ статус: IN_PROGRESS (джобы обрабатываются)

  ┌──────────────────────────────────────────────────────────────┐
  │  6. vampy-cli pipeline finish --pipeline-id "$CI_COMMIT_SHA" │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           ├──► POST /scan/pipelines/{id}/finish/
                           │    └─ сигнал: внешние задачи выполнены
                           │
                           └──► Агрегация результатов
                                └─ aggregationCompleted: true

  ┌──────────────────────────────────────────────────────────────┐
  │  7. vampy-cli pipeline status --pipeline-id "$CI_COMMIT_SHA" │
  │       --check-pipeline --verbose                             │
  └────────────────────────┬─────────────────────────────────────┘
                           │
                           └──► GET /scan/pipelines/{id}/status/ (опрос)
                                └─ статус: SUCCESS
                                └─ exit code: 0

  Итог: create → upload × N → finish → status → агрегация завершена

Создание пайплайна

Создаётся запись со статусом PENDING. Нужен хотя бы один из параметров: --repository или --product.

vampy-cli pipeline create --repository my-repository --pipeline-id "$CI_COMMIT_SHA"

или с указанием имени пайплайна

vampy-cli pipeline create --repository my-repository --pipeline-id "$CI_COMMIT_SHA" --pipeline-name "release-$CI_COMMIT_TAG"

Опционально: --branch, --profile, --pipeline-name, --pipeline-id (внешний идентификатор, например хеш коммита в CI).

Список пайплайнов

Фильтр по репозиторию или продукту обязателен (--repository или --product). Ветка --branch учитывается вместе с --repository (для продукта ветка в запрос не передаётся). Пагинация: --limit, --offset.

vampy-cli pipeline list --repository my-repository --branch main --limit 10

То же через list:

vampy-cli list pipelines --product my-product --offset 0 --limit 20

Статус пайплайна

Нужен --pipeline-id (внутренний UUID или внешний ID). Однократный запрос статуса — без дополнительных флагов. Полный ответ (профиль, relation, агрегаты) — --details.

При указании флага --check-pipeline выполняется опрос до завершения самого сканирования и последующего за ним механизма агрегации (в пределах указанного --timeout):

vampy-cli pipeline status --pipeline-id "$CI_COMMIT_SHA" --check-pipeline --verbose

Коды выхода для pipeline status и ожидания пайплайна в upload (см. загрузку результатов): 0 — один из ожидаемых стейтов при опросе (SUCCESS, PARTIAL_SUCCESS, PENDING, IN_PROGRESS); 20 — ошибочный стейт (ERROR); 22 — таймаут опроса до готовности агрегации. При --check-full остановка на первом ненулевом коде (часто: BG → пайплайн → QG).

Завершение пайплайна

Сообщает платформе, что внешние задачи по пайплайну выполнены; дальше пайплайн может перейти в финальный статус.

vampy-cli pipeline finish --pipeline-id 1231231 --details

Пример вывода:

--------
Finishing scan pipeline 1231231 ...
--------
✅ Pipeline finished successfully

Связь с `upload`: ожидание пайплайна

Флаги загрузки:

Флаг	Назначение
`--pipeline-id`	Привязать загрузку к внешнему ID пайплайна (как в CI)
`--pipeline-name`	Имя пайплайна
`--pipeline-finish`	После загрузки инициировать завершение пайплайна на стороне Vampy
`--check-pipeline`	Ждать финальный статус пайплайна (нужен `--pipeline-finish`, иначе ошибка валидации)
`--check-full`	Полный контур: BG, QG и ожидание пайплайна при выполнении условий из раздела выше

Ожидание пайплайна после upload включается, если одновременно: - задан --pipeline-finish; - указан --check-full или --check-pipeline.

Сводка комбинаций:

`--check-full`	`--pipeline-finish`	Ожидание пайплайна
да	да	да (полный сценарий: BG → при необходимости пайплайн → QG)
да	нет	нет (BG и QG, без ожидания пайплайна)
нет	да	да только если добавлен `--check-pipeline`
нет	нет	нет

Пример: несколько загрузок в один пайплайн и финальное ожидание на последнем шаге:

vampy-cli pipeline create --repository my-repository --pipeline-id "$CI_COMMIT_SHA"
vampy-cli upload --repository my-repository --file report1.json --scanner TRIVY_FS \
  --pipeline-id "$CI_COMMIT_SHA"
vampy-cli upload --repository my-repository --file report2.json --scanner SEMGREP \
  --pipeline-id "$CI_COMMIT_SHA"
vampy-cli upload --repository my-repository --file report3.json --scanner GITLEAKS \
  --pipeline-id "$CI_COMMIT_SHA" --pipeline-finish --check-pipeline --verbose

Один вызов upload с автосозданием пайплайна и ожиданием всего процесса:

vampy-cli upload --repository my-repository --file scan.json --scanner TRIVY_FS \
  --pipeline-finish --check-full

Команда `scan` и пайплайн

У команды scan нет флагов --pipeline-id, --pipeline-finish и --check-pipeline: привязка и ожидание пайплайна задаются в сценариях upload. Чтобы отследить пайплайн после сканирования, используйте идентификатор из интерфейса Vampy или из CI и команды pipeline status / pipeline list / list pipelines.

Параметры подкоманд `pipeline`

`pipeline create`

Параметр	Описание
`--repository` / `--product`	Хотя бы один обязателен
`--branch`	Ветка репозитория
`--pipeline-id`	Внешний ID пайплайна
`--pipeline-name`	Имя
`--profile`	Профиль сканирования

`pipeline list` и `list pipelines`

Параметр	Описание
`--repository` или `--product`	Фильтр (один из двух обязателен)
`--branch`	Только с `--repository`
`--limit`, `--offset`	Пагинация (по умолчанию limit 20)

`pipeline status`

Параметр	Описание
`--pipeline-id`	Обязателен
`--check-pipeline`	Опрос до терминального статуса и `aggregationCompleted`
`--details`	Полные детали сущности пайплайна

`pipeline finish`

Параметр	Описание
`--pipeline-id`	Обязателен