Разделы документации

Описание пайплайна (YAML)

Справочник по YAML пайплайна на агентах — стадии, шаги, параметры, секреты, отчёты, окружение шага и готовые примеры для Maven, Gradle, npm, cdxgen, Gitleaks, Semgrep, Trivy и Grype.

Пайплайн описывает, что агент делает с одним репозиторием: стадии → шаги → образ + команды, как в Jenkins. Пайплайны хранятся как шаблоны в Workflow → Пайплайны. Создают и правят их администраторы. Кнопка Проверить в редакторе показывает ошибки и план: стадии, шаги, образы и то, какие шаги получат секреты.

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

Минимальный пример

YAML
version: 1
agent:
  executor: docker
stages:
  - name: Secrets
    steps:
      - name: Gitleaks
        image: zricethezav/gitleaks:v8.30.1
        sourceReadOnly: true
        network: none
        command: [gitleaks, dir, ".", --report-format, json,
                  --report-path, "${ARCHEPELAG_OUTPUT}/gitleaks.json", --redact, --exit-code, "0"]
        reports: [{ path: gitleaks.json, format: gitleaks }]

Шаг запускается в каталоге с исходниками репозитория. Gitleaks пишет JSON-отчёт в $ARCHEPELAG_OUTPUT. Агент загружает отчёт в S3, а Archepelag разбирает его в находки.

Поля пайплайна

ПолеПо умолчаниюОписание
version1Версия формата. Других пока нет.
agent.labels[]Метки, которые должны быть у агента (все сразу). Метки агенту задаёт администратор, до 16 меток.
agent.executoranydocker, shell или any. При any пайплайн уходит агенту с исполнителем docker, если у шагов есть образ или изоляция (network: none, resources, user, sourceReadOnly, entrypoint: image). Иначе подходит любой агент.
agent.queueTimeoutMinutes1440Сколько задание может ждать агента (1–10080). Дольше — задание завершается ошибкой с причиной ожидания.
image—Образ по умолчанию для шагов без image.
registry—Имя registry из Интеграции → Nexus для шагов без своего registry.
parameters[]Параметры формы запуска, до 32 (см. Параметры).
env{}Переменные окружения всех шагов.
checkout.depth1Глубина git clone. 0 — вся история.
checkout.submodulesfalseКлонировать подмодули.
cache.scoperepositoryОбщий кэш шагов с cache: true: repository — свой у каждого репозитория (безопаснее всего), pipeline — общий у шаблона, shared — общий у всех.
timeoutMinutes180Предел на всё задание (1–2880).
artifacts[]Glob-шаблоны файлов из исходников, которые нужно сохранить в S3 (files/…), например "**/target/*.jar". До 32.
stages—Стадии по порядку, от 1 до 30.

Стадия: name, parallel (по умолчанию false) и steps (от 1 до 50 шагов). Имена стадий и шагов превращаются в ключи (sbom.maven): латиница в нижнем регистре, кириллица транслитерируется. Ключи не должны повторяться.

Поля шага

ПолеПо умолчаниюОписание
name—Имя шага. Должно содержать буквы или цифры.
imageimage пайплайнаОбраз шага (только исполнитель docker). Без образа шаг выполняется в toolbox-образе агента. ${PARAM} в образе допустим только для параметров type: choice.
registryregistry пайплайнаИмя registry из Интеграции → Nexus. Образ без хоста получает адрес и префикс registry, агент получает логин только этого registry.
run—Скрипт: выполняется как sh -e -c (или bash -e -c). Ровно одно из run и command.
command—Список аргументов (argv) без shell. Подставляются только ${ARCHEPELAG_SOURCE}, ${ARCHEPELAG_OUTPUT}, ${ARCHEPELAG_TMP}, ${ARCHEPELAG_CACHE}.
shellshsh или bash для run.
entrypointoverrideoverride — агент сам задаёт точку входа (shell или первый элемент command). image — оставить ENTRYPOINT образа (только docker).
dirкореньРабочий каталог относительно корня исходников.
env{}Переменные шага.
credentials[]Секреты, файлы конфигурации и токены интеграций (см. Секреты). До 32.
timeoutMinutes60Предел шага (1–1440).
allowFailurefalseОшибка шага не роняет задание.
alwaysfalseВыполнять шаг, даже если предыдущий упал (например, выгрузка логов).
when.exists—Glob или список glob-шаблонов. Нет совпадений — шаг пропускается (skipped).
networkdefaultnone — шаг без сети (только docker).
resources.memory, resources.cpus4g, 2Лимиты контейнера шага, например memory: 4g, cpus: "1.5" (только docker; значения по умолчанию задаёт агент).
userпользователь образаuid[:gid] или имя пользователя в контейнере (только docker).
cachefalseПодключить кэш зависимостей $ARCHEPELAG_CACHE.
sourceReadOnlyfalseИсходники только на чтение (только docker). Удобно для сканеров.
reports[]Отчёты шага (см. Отчёты). До 32.

Порядок выполнения

  • Стадии выполняются по порядку. Шаги стадии — друг за другом или одновременно (parallel: true).
  • Шаг падает при коде выхода ≠ 0, таймауте, нехватке памяти или если не создан обязательный отчёт. Без allowFailure оставшиеся шаги пропускаются, кроме шагов с always: true, и задание завершается ошибкой.
  • Логи шагов и отчёты загружаются в S3 при любом исходе: при ошибке, отмене, превышении времени задания и остановке агента. Не загружаются они, только если агент потерял задание (связь с Archepelag пропала дольше аренды).
  • Отчёты из reports загружаются сразу после своего шага. Следующие шаги могут их читать (например, Grype — SBOM предыдущей стадии), но не подменить: файл, позже записанный по тому же пути, повторно не загружается.

when.exists

Шаблоны считаются от корня исходников (синтаксис picomatch): pom.xml — только в корне, **/pom.xml — где угодно. Не учитываются dot-файлы, симлинки и каталоги .git, node_modules, target, build, .gradle, vendor, dist; глубина поиска — до 8 уровней. Список совпавших путей (по одному на строку) лежит в файле $ARCHEPELAG_MATCHED_FILE. Файл только для чтения: нужен изменённый список — скопируйте его в $ARCHEPELAG_TMP.

Ограничения исполнителя shell

Исполнитель shell (pod в Kubernetes, docker-compose.shell.yml) выполняет все шаги в toolbox-образе агента: JDK, Maven, Gradle, Node и CLI-сканеры. С agent.executor: shell нельзя использовать image, network: none, resources, user, sourceReadOnly и entrypoint: image. Шаблон с такими полями выполняют только агенты с исполнителем docker.

Все шаги на исполнителе shell работают под одним пользователем. Поэтому стадия с parallel: true, где хотя бы у одного шага есть credentials, на нём выполняется последовательно, а после каждого шага завершаются все его процессы, в том числе запущенные в фоне. Фоновый процесс не переживает шаг: сервер или демон, нужный следующему шагу, запускайте в том же шаге.

Параметры

Параметры видны в форме запуска. Их значения приходят в шаг переменными окружения с тем же именем.

YAML
parameters:
  - { name: SKIP_TESTS, type: boolean, default: "true" }
  - { name: JDK, type: choice, choices: ["17", "21"], default: "21", description: Версия JDK }
  - { name: PROFILES, type: string, pattern: "[a-z0-9,-]{0,64}" }
ПолеОписание
nameИмя переменной: A-Z, 0-9, _.
typestring (по умолчанию), choice или boolean.
defaultЗначение по умолчанию, строкой. Для boolean — "true" или "false"; без default — "false", и при запуске из формы, и через API без значения. Для choice — одно из choices.
requiredПустое значение не допускается.
choicesДопустимые значения для type: choice (обязательно).
patternРегулярное выражение для type: string. Значение должно совпасть целиком.
descriptionПодсказка в форме запуска.
unsafeFreeTextРазрешить свободную строку без pattern в пайплайне с секретами (см. ниже).

Правила безопасности параметров

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

  • Запрещённые имена. Нельзя назвать параметр так, как переменную читают сборщики и рантаймы сами: имена с префиксами LD_, DYLD_, GIT_, DOCKER_, NODE_, NPM_CONFIG_, JAVA_, _JAVA_, JDK_JAVA_, MAVEN_, GRADLE_, BASH_, SSL_, CURL_, REQUESTS_, PIP_, YARN_, CARGO_, DOTNET_, NUGET_, начинающиеся с PYTHON, PERL, RUBY, KUBE, GO, а также ENV, SHELL, SHELLOPTS, BASHOPTS, PS4, IFS, PROMPT_COMMAND, USER, LOGNAME и все *_PROXY.
  • Зарезервированные имена. ARCHEPELAG_*, HOME, PATH, CI, DOCKER_CONFIG, TMPDIR нельзя задавать ни параметром, ни в env.
  • Без пересечений. Имя параметра не совпадает с переменными env пайплайна и шагов и с переменными credentials.
  • Свободный текст. Если хотя бы у одного шага есть credentials, каждый параметр type: string должен иметь pattern. Иначе используйте choice или boolean. unsafeFreeText: true снимает запрет осознанно.
  • Образы. В image можно подставлять только параметры type: choice, например maven:3.9-eclipse-temurin-${JDK}.
  • Значения. До 4096 символов, без перевода строки и NUL. Неизвестные параметры запуск отклоняет.

Секреты и файлы конфигурации

credentials шага связывает переменную окружения с секретом. Шаг получает только свои привязки, другие шаги их не видят.

YAML
credentials:
  - { secret: NEXUS_TOKEN, env: NEXUS_TOKEN }          # значение секрета
  - { file: maven-settings, env: MAVEN_SETTINGS }      # путь к файлу конфигурации
  - { integration: codescoring, env: CS_TOKEN }        # токен интеграции
  - { registries: true, env: REGISTRY_NETRC }          # логины Nexus для реестров зависимостей (netrc)
ВидОткудаЧто получает шаг
secretНастройки → Секреты (имя в верхнем регистре)Значение в переменной env.
fileНастройки → Файлы конфигурацииПуть к файлу в переменной env. Плейсхолдеры ${ARCHEPELAG.ИМЯ_СЕКРЕТА} в файле заменяются значениями секретов (для типа Maven settings — с XML-экранированием). Имя файла можно задать полем fileName.
integrationИнтеграции: ptai, codescoring, aspm, defectdojoСохранённый токен интеграции в переменной env.
registriesОставлено для старых шаблоновПуть к пустому файлу. Логины реестров теперь подставляет прокси раннера (Настройки → Реестры зависимостей), в шаг они не передаются.

Как это защищено:

  • Archepelag расшифровывает секреты, только когда агент забирает задание, и отдаёт ему привязки только этого задания.
  • Файлы привязок лежат вне исходников. В docker они смонтированы только в свой шаг, только на чтение, в /run/archepelag/creds, и удаляются после шага.
  • Значения маскируются в логах: на агенте и ещё раз в Archepelag, включая варианты в base64, URL- и XML-кодировке. Маскирование — это страховка, а не гарантия. Логи видят те, кому виден репозиторий.
  • Каждая выдача записывается: имена выданных секретов видны в истории попыток агента.
  • Если секрета, файла или интеграции нет, задание завершается ошибкой с их именем, а секреты остальных шагов не выдаются. Исключение — registries: без подходящего Nexus шаг получает пустой файл.

Отчёты и форматы

YAML
reports:
  - { path: sbom-maven.cdx.json, format: cyclonedx, sbom: true }
  - { path: extra.json, format: raw, optional: true }

path — путь относительно $ARCHEPELAG_OUTPUT. Отчёт с одним путём объявляется в пайплайне один раз. Если обязательного отчёта нет после шага, шаг падает. Отсутствие отчёта с optional: true только пишет предупреждение в лог. Отчёт загружается сразу после своего шага, и более поздние шаги (например, сборка с кодом из репозитория) не могут его подменить.

formatЧто этоЧто попадает в находки
gitleaksJSON-отчёт GitleaksСекреты. Успешный шаг успешного задания также обновляет инвентарь секретов репозитория.
semgrepsemgrep --jsonСрабатывания правил.
sarifSARIF 2.1.0 любого инструментаРезультаты. Инструмент определяется по driver.name.
cyclonedxSBOM CycloneDX JSONУязвимости из vulnerabilities[], если они есть. С sbom: true файл считается SBOM и скачивается со страницы запуска.
trivytrivy … --format jsonУязвимости, секреты и ошибки конфигурации.
grypegrype -o jsonУязвимости.
rawЛюбой файлНичего, файл только хранится в S3.

Пределы разбора: отчёт до 64 МБ (больший сохраняется, но не разбирается), до 20 000 находок из одного отчёта и до 50 000 на задание. Если что-то отброшено, на вкладке Файлы будет предупреждение. При каждом выполнении находки репозитория в запуске заменяются новыми, а не добавляются.

Формат и шаг отчёта Archepelag берёт из сохранённой копии шаблона запуска, а не из ответа агента.

Окружение шага

Приоритет (от сильного к слабому): служебные ARCHEPELAG_*, HOME, TMPDIR, CI → привязки credentials → env шага → параметры → env пайплайна. Переменные окружения агента в шаги не попадают, кроме прокси.

ПеременнаяЗначение
ARCHEPELAG_SOURCEКлон репозитория (docker: /workspace/src). Шаг запускается здесь или в dir.
ARCHEPELAG_OUTPUTРезультаты шага → S3 out/… (docker: /workspace/out). Общий для всех шагов задания.
ARCHEPELAG_TMPВременный каталог задания (docker: /workspace/tmp). HOME=$ARCHEPELAG_TMP/home, TMPDIR=$ARCHEPELAG_TMP/tmp.
ARCHEPELAG_CACHEКэш зависимостей, только у шагов с cache: true (docker: /workspace/cache). Если шаг их не задал, туда же указывают GRADLE_USER_HOME, npm_config_cache, YARN_CACHE_FOLDER, PIP_CACHE_DIR, TRIVY_CACHE_DIR, GRYPE_DB_CACHE_DIR.
ARCHEPELAG_COMMIT, ARCHEPELAG_BRANCHКоммит и ветка клона.
ARCHEPELAG_RUN_ID, ARCHEPELAG_JOB_ID, ARCHEPELAG_REPO_ID, ARCHEPELAG_REPO_NAME, ARCHEPELAG_REPO_SLUG, ARCHEPELAG_PROJECT_KEY, ARCHEPELAG_PIPELINE_KEYКонтекст запуска.
ARCHEPELAG_MATCHED_FILEФайл со списком путей, совпавших с when.exists (только чтение).
ARCHEPELAG_PYPI_INDEX_URL, ARCHEPELAG_PYPI_EXTRA_INDEX_URLSИндексы PyPI из анализа репозитория: основной (корпоративный — первым) и остальные через пробел.
ARCHEPELAG_MAVEN_REPOSITORIES, ARCHEPELAG_GRADLE_PLUGIN_REPOSITORIESMaven/Gradle-репозитории и репозитории плагинов Gradle из анализа, через пробел.
ARCHEPELAG_NPM_REGISTRY, ARCHEPELAG_NPM_SCOPED_REGISTRIESРеестр npm и scoped-реестры (@scope=url через пробел) из анализа.
ARCHEPELAG_GOPROXYАдреса GOPROXY из анализа, через запятую.
ARCHEPELAG_DEPENDENCY_REGISTRIESВсе найденные адреса в JSON: [{ecosystem, role, url, name?}] (NuGet, Cargo, RubyGems и др.).
HTTPS_PROXY, HTTP_PROXY, NO_PROXY, ALL_PROXY (и в нижнем регистре)Прокси агента, если он задан и у шага нет network: none.
ARCHEPELAG_PROXY_HOST, ARCHEPELAG_PROXY_PORT, ARCHEPELAG_PROXY_NON_PROXY_HOSTSТот же прокси для Java и Maven (NON_PROXY_HOSTS — через |, как в http.nonProxyHosts).
ARCHEPELAG_CA_FILE, NODE_EXTRA_CA_CERTSДополнительный CA агента (ARCHEPELAG_AGENT_CA_FILE), если задан.
SSL_CERT_FILE, REQUESTS_CA_BUNDLE, GIT_SSL_CAINFOСистемные CA вместе с дополнительным CA, если он задан.
CItrue.

В исполнителе shell агент также добавляет в JAVA_TOOL_OPTIONS параметры -XX:MaxRAMPercentage=50 (если там нет -Xmx) и -Djava.io.tmpdir.

Реестры зависимостей из анализа

Анализ репозитория находит, откуда скачиваются зависимости: индексы в pyproject.toml, pip.conf и requirements, репозитории в build.gradle, settings.gradle и pom.xml, реестры в .npmrc, а также PIP_INDEX_URL, GOPROXY и т. п. в Dockerfile и CI. Найденное передаётся в шаги переменными ARCHEPELAG_PYPI_*, ARCHEPELAG_MAVEN_REPOSITORIES и др. (таблица выше). Если реестров несколько — несколько Nexus или публичные репозитории вроде JitPack, — передаются все: корпоративные первыми, затем публичные.

  • Берётся последний анализ ветки задания, если его нет — анализ ветки по умолчанию. Переменной нет, если реестр не найден или задан переменной вне репозитория.
  • Логинов в шаге нет. Закрытые реестры добавьте в Настройки → Реестры зависимостей: задание получит те, что подходят по меткам раннера и продукту репозитория, и пойдёт в них через прокси раннера. Логин подставляет раннер, поэтому код из репозитория его не увидит. Адреса настроенных реестров в переменных ARCHEPELAG_* указывают на прокси, а ARCHEPELAG_REGISTRY_PROXY — его базовый адрес. Если в репозитории найден реестр, для которого ничего не настроено, в логе задания будет предупреждение.
  • Адреса, прописанные в самом проекте, тоже идут через прокси. Для Maven это зеркала в settings.xml, для Gradle — init-скрипт, который меняет адреса репозиториев проекта (cdxgen получает его через GRADLE_ARGS). npm и pip получают прямой прокси раннера (npm_config_https_proxy, PIP_PROXY), поэтому сработает и .npmrc с адресом закрытого Nexus. Соединения к настроенным реестрам раннер расшифровывает сертификатом от CA задания, а доверие к этому CA шаг получает через NODE_EXTRA_CA_CERTS и PIP_CERT.
  • Встроенные SBOM-шаблоны используют переменные сами и только дополняют то, что объявлено в проекте. В своём шаблоне переменные нужно подключить явно, например export PIP_INDEX_URL="${PIP_INDEX_URL:-$ARCHEPELAG_PYPI_INDEX_URL}".

Встроенные шаблоны

Archepelag создаёт их сам, если шаблона с таким ключом ещё нет. Их можно менять, копировать и удалять; удалённый встроенный шаблон обратно не появляется. Шаблон, который не меняли, при обновлении Archepelag обновляется до новой версии; изменённый остаётся как есть. Все они рассчитаны на исполнитель docker и не требуют настраивать секреты; SBOM-шаблоны получают логины Nexus только через registries (см. выше).

КлючНазваниеЧто делает
sbom-universal-cdxgenSBOM: cdxgen (любой стек)cdxgen сам определяет экосистемы и обходит подкаталоги. Индексы PyPI, Maven-репозитории, реестры npm и GOPROXY берутся из анализа. Если сборщик не получил зависимости или не собрал проект, шаг падает и не отдаёт неполный SBOM. С параметром STRICT_SBOM = false SBOM возвращается как есть.
secrets-gitleaksСекреты: GitleaksGitleaks без сети, исходники только на чтение, значения скрыты.
sast-semgrepSAST: SemgrepSemgrep с правилами p/default (скачиваются из реестра Semgrep).
full-securityПолная проверка безопасностиGitleaks и Semgrep параллельно, затем SBOM через cdxgen и Grype по этому SBOM. Параметр STRICT_SBOM такой же, как у sbom-universal-cdxgen.
api-noirAPI: эндпоинты кода (OWASP Noir)Находит HTTP-эндпоинты в коде и пополняет эндпоинты API репозитория. Можно включить автозапуск на каждый новый коммит в «Анализ репозиториев».

Каталог шагов

Узкие сканеры поставляются как шаги, а не как отдельные пайплайны. В редакторе пайплайна нажмите «Шаг из каталога» и выберите шаг. Он попадёт в выбранную стадию или в новую стадию с подходящим названием, а нужные параметры (например, JDK) добавятся в пайплайн.

ШагЧто делает
Gitleaks, Semgrep, cdxgen, OWASP NoirТо же, что в шаблонах выше.
SBOM: Mavencyclonedx-maven-plugin (makeAggregateBom), если в корне есть pom.xml. Параметр JDK: 21, 17 или 11. Шаг подключает репозитории из анализа через settings.xml и для зависимостей, и для плагина. Адреса http:// шаг пропускает, потому что Maven их блокирует.
SBOM: GradleШаг подключает плагин org.cyclonedx.bom init-скриптом, если проект не подключил его сам. Плагин он ищет сначала в репозиториях из анализа, затем в Gradle Plugin Portal. Если в проекте есть ./gradlew, шаг запускает его. Параметр JDK: 21, 17 или 11, под Java toolchain проекта.
SBOM: npm@cyclonedx/cyclonedx-npm по package-lock.json, без dev-зависимостей. Шаг пишет реестры npm из анализа (и scoped) в пользовательский .npmrc. Если в проекте есть свой .npmrc, действует он.
Trivytrivy fs: уязвимые зависимости, секреты, ошибки конфигурации.
GrypeУязвимости по SBOM из шага cdxgen. Ставьте его в стадию после cdxgen.

До 5 ноября 2026 года Maven, Gradle, npm и Trivy поставлялись отдельными шаблонами (sbom-maven, sbom-gradle, sbom-npm, sca-trivy). Если шаблон не меняли, Archepelag удалит его при обновлении. Изменённый шаблон останется у вас как собственный.

Образы встроенных шаблонов и шагов каталога лежат на Docker Hub и ghcr.io. В закрытом контуре зеркалируйте их и укажите registry: (см. Установка агентов).

Примеры

Maven: SBOM через свой Nexus и settings.xml

YAML
version: 1
agent: { labels: [java], executor: docker }
registry: corp-nexus
parameters:
  - { name: JDK, type: choice, choices: ["17", "21"], default: "21" }
  - { name: SKIP_TESTS, type: boolean, default: "true" }
env: { MAVEN_OPTS: "-Xmx2g" }
stages:
  - name: SBOM
    steps:
      - name: Maven
        image: maven:3.9-eclipse-temurin-${JDK}
        when: { exists: "pom.xml" }
        cache: true
        credentials:
          - { file: maven-settings, env: MAVEN_SETTINGS }
        run: |
          mvn -B -ntp -s "$MAVEN_SETTINGS" -Dmaven.repo.local="$ARCHEPELAG_CACHE/m2" \
            -DskipTests="$SKIP_TESTS" \
            org.cyclonedx:cyclonedx-maven-plugin:2.9.1:makeAggregateBom \
            -DoutputFormat=json -DoutputName=bom
          cp target/bom.json "$ARCHEPELAG_OUTPUT/sbom-maven.cdx.json"
        reports: [{ path: sbom-maven.cdx.json, format: cyclonedx, sbom: true }]
        timeoutMinutes: 30
        resources: { memory: 4g, cpus: "2" }

maven-settings — файл конфигурации типа Maven settings с зеркалом Nexus, логином ${ARCHEPELAG.NEXUS_PASSWORD} и, если нужно, прокси. Прокси в settings.xml можно взять из окружения: <host>${env.ARCHEPELAG_PROXY_HOST}</host>, <port>${env.ARCHEPELAG_PROXY_PORT}</port>.

Gradle: SBOM через init-скрипт

Проект не меняется: плагин CycloneDX подключается init-скриптом из временного каталога.

YAML
      - name: Gradle
        image: gradle:8.10-jdk21
        when: { exists: ["build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts"] }
        cache: true
        run: |
          cat > "$ARCHEPELAG_TMP/cyclonedx.init.gradle" <<'EOF'
          initscript {
            repositories { maven { url 'https://nexus.corp/repository/gradle-plugins' }; gradlePluginPortal() }
            dependencies { classpath "org.cyclonedx.bom:org.cyclonedx.bom.gradle.plugin:1.10.0" }
          }
          rootProject { p ->
            p.afterEvaluate {
              if (!p.plugins.hasPlugin("org.cyclonedx.bom")) p.apply(plugin: org.cyclonedx.gradle.CycloneDxPlugin)
            }
          }
          EOF
          if [ -f ./gradlew ]; then GRADLE="sh ./gradlew"; else GRADLE="gradle"; fi
          $GRADLE --no-daemon --console=plain --init-script "$ARCHEPELAG_TMP/cyclonedx.init.gradle" cyclonedxBom
          # Плагин 3.x: build/reports/cyclonedx/*.json, 1.x: build/reports/bom.json
          for bom in build/reports/cyclonedx/*.json build/reports/bom.json; do [ -f "$bom" ] && break; done
          cp "$bom" "$ARCHEPELAG_OUTPUT/sbom-gradle.cdx.json"
        reports: [{ path: sbom-gradle.cdx.json, format: cyclonedx, sbom: true }]

С cache: true агент сам направляет GRADLE_USER_HOME в кэш. Шаг каталога «SBOM: Gradle» подставляет сюда репозитории из анализа (ARCHEPELAG_GRADLE_PLUGIN_REPOSITORIES, ARCHEPELAG_MAVEN_REPOSITORIES) перед gradlePluginPortal(); в примере адрес Nexus записан явно.

npm: SBOM по package-lock.json

YAML
      - name: npm
        image: node:22-bookworm-slim
        when: { exists: "package.json" }
        cache: true
        run: |
          if [ ! -f package-lock.json ] && [ ! -f npm-shrinkwrap.json ]; then
            npm install --package-lock-only --ignore-scripts --no-audit --no-fund
          fi
          npx --yes @cyclonedx/cyclonedx-npm@6 --package-lock-only --omit dev \
            --output-format JSON --output-file "$ARCHEPELAG_OUTPUT/sbom-npm.cdx.json"
        reports: [{ path: sbom-npm.cdx.json, format: cyclonedx, sbom: true }]

Скрипты пакетов не запускаются (--ignore-scripts). Для своего npm-реестра подключите .npmrc файлом конфигурации: npm читает путь к нему из NPM_CONFIG_USERCONFIG.

YAML
        credentials: [{ file: corp-npmrc, env: NPM_CONFIG_USERCONFIG }]

Монорепозиторий: cdxgen

YAML
      - name: cdxgen
        image: ghcr.io/cyclonedx/cdxgen:v12
        cache: true
        timeoutMinutes: 60
        resources: { memory: 4g, cpus: "2" }
        env: { FETCH_LICENSE: "false" }
        command: [cdxgen, -r, -o, "${ARCHEPELAG_OUTPUT}/sbom.cdx.json", "."]
        reports: [{ path: sbom.cdx.json, format: cyclonedx, sbom: true }]

Сканеры: Gitleaks и Semgrep параллельно, Trivy, Grype по SBOM

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
        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
        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: Trivy
        image: aquasec/trivy:0.73.0
        sourceReadOnly: true
        cache: true
        command: [trivy, fs, --format, json, --output, "${ARCHEPELAG_OUTPUT}/trivy.json",
                  --scanners, "vuln,secret,misconfig", --exit-code, "0", --no-progress, "."]
        reports: [{ path: trivy.json, format: trivy }]
  - name: SBOM
    steps:
      - name: cdxgen
        image: ghcr.io/cyclonedx/cdxgen:v12
        cache: true
        command: [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
        command: [/grype, "sbom:${ARCHEPELAG_OUTPUT}/sbom.cdx.json", -o, json, --file, "${ARCHEPELAG_OUTPUT}/grype.json"]
        reports: [{ path: grype.json, format: grype }]
  • Сканеры запускаются с целью . из корня исходников, поэтому пути в находках — относительно репозитория.
  • --exit-code 0 у Gitleaks и Trivy: найденные проблемы — это результат, а не ошибка шага.
  • $ARCHEPELAG_OUTPUT общий для шагов задания, поэтому Grype читает SBOM, который построила предыдущая стадия.
  • Trivy и Grype скачивают базы уязвимостей при запуске. В закрытом контуре задайте зеркало в env шага (TRIVY_DB_REPOSITORY, GRYPE_DB_UPDATE_URL). С cache: true базы сохраняются между запусками.

Свой CA для Java (PKIX)

Java не читает SSL_CERT_FILE. Если Maven или Gradle ходят в репозиторий с сертификатом внутреннего CA, импортируйте $ARCHEPELAG_CA_FILE в копию truststore JDK в начале шага:

Shell
cp "$JAVA_HOME/lib/security/cacerts" "$ARCHEPELAG_TMP/cacerts"
keytool -importcert -noprompt -alias corp-ca -file "$ARCHEPELAG_CA_FILE" \
  -keystore "$ARCHEPELAG_TMP/cacerts" -storepass changeit
export MAVEN_OPTS="$MAVEN_OPTS -Djavax.net.ssl.trustStore=$ARCHEPELAG_TMP/cacerts -Djavax.net.ssl.trustStorePassword=changeit"

Для Gradle добавьте те же -Djavax.net.ssl.* в JAVA_TOOL_OPTIONS. Другой вариант — свой образ шага с вашим CA в truststore.

Связанные страницы