Сканирование как в Jenkins, только на своих раннерах

Как вынести SAST, поиск секретов, SBOM и SCA из десятков Jenkinsfile в один шаблон Archepelag: раннеры в Docker и Kubernetes, отчёты в S3, находки на карточке репозитория.

6 мин чтения
Каменные ворота с аркой, у проёма одна коралловая точка

Автор

  • Команда Аркепелага@archepelag

У каждой команды свой Jenkinsfile, и в каждом — своя версия Gitleaks, Semgrep и генератора SBOM. Где-то сканер падает молча, где-то отчёт лежит в archiveArtifacts и его никто не открывает, где-то шаг закомментирован «до релиза». Безопасность видит не репозитории, а набор чужих пайплайнов.

Мы добавили в Archepelag пайплайны сканирования на раннерах: тот же язык стадий и шагов, что в Jenkins, но шаблон один на всю компанию, а выполняют его раннеры в вашей инфраструктуре. Ниже — как это устроено и что при этом остаётся в Jenkins.

Как было: сканеры в каждом Jenkinsfile

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

Groovy · Jenkinsfile
pipeline {
  agent { label 'docker' }
  options { timeout(time: 60, unit: 'MINUTES') }

  stages {
    stage('Secrets') {
      steps {
        sh '''
          docker run --rm -v "$WORKSPACE:/src" zricethezav/gitleaks:v8.18.0 \
            dir /src --report-format json --report-path /src/gitleaks.json --exit-code 0
        '''
      }
    }
    stage('SAST') {
      steps {
        sh 'docker run --rm -v "$WORKSPACE:/src" -w /src semgrep/semgrep semgrep scan --config auto --json -o semgrep.json'
      }
    }
    stage('SBOM') {
      when { expression { fileExists('pom.xml') } }
      steps {
        sh 'mvn -B org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom -DoutputFormat=json'
      }
    }
  }
  post {
    always { archiveArtifacts artifacts: '*.json, target/bom.json', allowEmptyArchive: true }
  }
}

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

  • версии инструментов разъезжаются: в одном репозитории Gitleaks 8.18, в соседнем — 8.30, а Semgrep вообще без тега;
  • отчёты — артефакты сборки. Чтобы понять, сколько критичных уязвимостей во всей компании, нужно обойти сотни сборок;
  • semgrep --config auto ходит в интернет, а сканер запущен с доступом к исходникам и сети одновременно;
  • любой разработчик может поправить Jenkinsfile и тихо выключить шаг.

Как стало: один шаблон на всю компанию

Пайплайн в Archepelag описывается YAML-шаблоном. Стадии идут по порядку, шаги стадии — последовательно или параллельно, у каждого шага свой образ и свои команды. Шаблоны правит администратор в Workflow → Пайплайны, команды только выбирают, какой запускать.

Шаблоны пайплайнов в Archepelag: встроенные «Полная проверка безопасности», «SBOM: Maven», «Секреты: Gitleaks» и свой E2E-шаблон
Встроенные шаблоны и свой: кто может запускать, на каких раннерах, сколько стадий и шагов

Вот встроенный шаблон «Полная проверка безопасности» — секреты и SAST параллельно, затем SBOM, затем уязвимости по SBOM. Шаг cdxgen сокращён: в продукте он ещё подставляет логины Nexus и реестры зависимостей из анализа репозитория.

YAML
version: 1
agent:
  executor: docker
stages:
  - name: Source scan
    parallel: true
    steps:
      - name: Gitleaks
        image: zricethezav/gitleaks:v8.30.1
        sourceReadOnly: true
        network: none
        timeoutMinutes: 30
        command: [gitleaks, dir, ".", --report-format, json,
                  --report-path, "${ARCHEPELAG_OUTPUT}/gitleaks.json",
                  --redact, --exit-code, "0", --no-banner]
        reports: [{ path: gitleaks.json, format: gitleaks }]
      - name: Semgrep
        image: semgrep/semgrep:1.175.1
        sourceReadOnly: true
        timeoutMinutes: 60
        resources: { memory: 4g, cpus: "2" }
        env: { SEMGREP_SEND_METRICS: "off", SEMGREP_ENABLE_VERSION_CHECK: "0" }
        command: [semgrep, scan, --config, p/default, --json,
                  --output, "${ARCHEPELAG_OUTPUT}/semgrep.json",
                  --metrics, "off", --disable-version-check, "."]
        reports: [{ path: semgrep.json, format: semgrep }]
  - name: SBOM
    steps:
      - name: cdxgen
        image: ghcr.io/cyclonedx/cdxgen:v12
        cache: true
        timeoutMinutes: 60
        run: |
          cdxgen -r -o "$ARCHEPELAG_OUTPUT/sbom.cdx.json" .
        reports: [{ path: sbom.cdx.json, format: cyclonedx, sbom: true }]
  - name: Vulnerabilities
    steps:
      - name: Grype
        image: anchore/grype:v0.118.0
        cache: true
        timeoutMinutes: 30
        command: [/grype, "sbom:${ARCHEPELAG_OUTPUT}/sbom.cdx.json",
                  -o, json, --file, "${ARCHEPELAG_OUTPUT}/grype.json"]
        reports: [{ path: grype.json, format: grype }]

Три вещи, которых нет в обычном Jenkinsfile:

  1. Образы закреплены по версии и одинаковы для всех репозиториев. Обновили Grype в шаблоне — обновили его везде.
  2. reports объявлены в шаблоне. Archepelag сам знает, что grype.json — это отчёт Grype, разбирает его в находки и привязывает к репозиторию, продукту и команде.
  3. Изоляция шага задаётся явно: sourceReadOnly — шаг не может поменять исходники, network: none — у Gitleaks нет сети вообще.

Раннеры: pull, а не push

Шаблон выполняет раннер — контейнер на отдельном скан-хосте или pod в Kubernetes. Раннер сам ходит в Archepelag по HTTPS за заданиями (long-poll), как inbound-агент Jenkins или GitLab Runner. Входящий доступ к нему не нужен, а масштаб — это просто число экземпляров.

Схема: запуск из интерфейса → Archepelag core → раннер забирает задание → git clone → отчёты в S3 → core-worker разбирает их в находки
Кто с кем разговаривает. Ключи S3 есть только у core, раннер получает presigned URL на каждый файл

У раннера нет доступа к базе, Redis и ключу шифрования — он выполняет чужой код (плагины Maven и npm), поэтому знает минимум. Задания попадают на раннеры только по меткам, которые задал администратор: шаблон с agent.labels: [docker, java] уйдёт только туда, где есть обе метки.

Раннеры в Archepelag: e2e-docker онлайн, e2e-shell нет связи
Workflow → Раннеры: метки, разрешённые пайплайны, экземпляры и последняя связь

Скан-хост с Docker

Основной режим — отдельный хост с Docker, где каждый шаг запускается своим контейнером. Токен раннера показывается один раз при создании; его кладут в файл, а не в переменные окружения — их видно в docker inspect:

Bash
umask 077
printf 'Токен раннера: '; read -rs ARCHEPELAG_TOKEN; echo
printf '%s' "$ARCHEPELAG_TOKEN" > token
unset ARCHEPELAG_TOKEN
chmod 600 token

Сам раннер — обычный compose-сервис. Фрагмент из комплекта поставки:

YAML
services:
  scan-agent:
    image: ghcr.io/security-dynasty/archepelag/scan-agent:${ARCHEPELAG_VERSION}
    restart: unless-stopped
    init: true
    stop_grace_period: 120s
    env_file: agent.env            # ARCHEPELAG_SERVER_URL=https://archepelag.example.corp
    environment:
      ARCHEPELAG_AGENT_EXECUTOR: docker
      ARCHEPELAG_AGENT_TOKEN_FILE: /run/secrets/archepelag_agent_token
      ARCHEPELAG_AGENT_WORK_DIR: /var/lib/archepelag-agent/work
    secrets: [archepelag_agent_token]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/archepelag-agent:/var/lib/archepelag-agent

secrets:
  archepelag_agent_token:
    file: ./token

Kubernetes

В кластере нет docker.sock, поэтому там работает исполнитель shell: pod из двух контейнеров. В agent — токен и связь с Archepelag, но никакого чужого кода. В runner — JDK, Maven, Gradle, Node и CLI-сканеры, другой uid, без токена и без service account. Команды между ними ходят через unix-сокет в общем emptyDir. Для масштабирования по очереди в комплекте есть KEDA ScaledJob: чистый pod на каждое задание. Манифесты лежат в комплекте поставки; сценарий для Kubernetes мы ещё обкатываем на реальном кластере, поэтому основной режим сегодня — docker.

Запуск и результат

Запустить пайплайн можно из UI: выбрали репозитории, шаблон и параметры. Форма сразу показывает, есть ли подходящие раннеры в сети, — если нет, задание подождёт в очереди, а не упадёт.

Форма запуска: выбран шаблон, подходящий раннер не в сети, задания подождут в очереди
Форма запуска честно говорит, кто возьмёт задание

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

Стадии запуска: Source scan (Gitleaks, Semgrep), SBOM (cdxgen), Vulnerabilities (Grype) — все успешно, 2 минуты 1 секунда
Полная проверка безопасности на e2e-nodegoat: 2 минуты, три стадии, четыре шага

Как это выглядит вживую — от шаблонов и раннеров до логов и находок конкретного запуска:

Находки разобраны и лежат в Archepelag, а не в артефактах сборки. Рядом — все файлы запуска: SBOM, сырые отчёты и логи каждого шага.

Находки запуска: 355, критичные уязвимости Grype в зависимостях
Находки: 355, сверху критичные
Файлы запуска: SBOM в CycloneDX, отчёты gitleaks, grype, semgrep и логи шагов
Файлы: SBOM, отчёты и логи шагов

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

Безопасность: что раннер может, а что нет

ВопросКак устроено
ТокеныТокен раннера sa_… умеет только heartbeat и взять задание. На каждую попытку — отдельный токен sj_…; его отзыв мгновенно отрезает устаревший процесс
Секреты шаговВыдаются только шагам, где объявлены в шаблоне, файлом в каталог шага и удаляются после него. В логах маскируются дважды: на раннере и в core
Контейнер шагаno-new-privileges, cap-drop ALL с минимальным набором, лимиты памяти, CPU и числа процессов, по запросу — --network none
Загрузка в S3Presigned URL до 15 минут с подписанным размером. Писать можно только в префикс своей попытки
Отмена и сбоиРаннер убивает контейнеры, загружает логи и готовые отчёты и закрывает задание. Аренда 5 минут продлевается, обновление core не убивает двухчасовую сборку

А Jenkins? Что остаётся в пайплайне сборки

Сборка и деплой остаются в Jenkins — это не меняется. Из Jenkinsfile уходят только шаги сканирования: вместо трёх docker run с разными версиями сканеров репозиторий подключается к шаблону в Archepelag, а запуск идёт из Archepelag — для одного репозитория или сразу для сотен. В Jenkinsfile остаётся то, что относится к сборке:

Groovy · Jenkinsfile
pipeline {
  agent { label 'maven' }
  options { timeout(time: 30, unit: 'MINUTES') }

  stages {
    stage('Build') {
      steps { sh './mvnw -B -ntp verify' }
    }
    stage('Publish') {
      when { branch 'main' }
      steps { sh './mvnw -B -ntp deploy -DskipTests' }
    }
  }
  // Gitleaks, Semgrep и SBOM здесь больше нет:
  // их запускает шаблон «Полная проверка безопасности» в Archepelag.
}

Следующий шаг: скан как стадия Jenkins

Следующее, что мы делаем, — запуск скана прямо из пайплайна сборки по API-токену и Quality Gate: ответ «можно выпускать или нет» по политике продукта (пороги критичности, давность последнего скана, принятые риски). Сейчас этот API ещё не открыт для токенов, поэтому ниже — черновик того, как стадия будет выглядеть:

Groovy · Jenkinsfile
// Черновик: Quality Gate API в разработке, имена эндпоинтов могут измениться.
stage('Security gate') {
  steps {
    withCredentials([string(credentialsId: 'archepelag-token', variable: 'ARCHEPELAG_TOKEN')]) {
      script {
        def gate = sh(returnStdout: true, script: '''
          curl -fsS "$ARCHEPELAG_URL/api/v1/quality-gate?repository=$ARCHEPELAG_REPO_ID&ref=$GIT_COMMIT" \
            -H "Authorization: Bearer $ARCHEPELAG_TOKEN" | jq -r .status
        ''').trim()
        if (gate == 'failed') {
          error "Archepelag: релиз заблокирован политикой продукта"
        }
      }
    }
  }
}

Что дальше

  • Исполнитель kubernetes: pod на задание, где каждый шаг — свой контейнер со своим образом, как Kubernetes plugin в Jenkins.
  • Пайплайн из репозитория (.archepelag/scan.yaml) с белым списком привязок секретов.
  • Запуск из Jenkins и GitLab CI по API-токену и Quality Gate по политике продукта.
  • Перенос встроенных сканеров PT AI, CodeScoring и ASOC в шаблоны на раннерах.
  • Живой лог шагов в интерфейсе и SBOM в виде таблицы компонентов.

Пайплайны на раннерах уже работают на наших стендах. Если хотите посмотреть их на своих репозиториях — напишите нам, покажем на демо и поможем перенести ваши Jenkinsfile в шаблоны.