Образ генератора SBOM cdxgen на distroless: SBOM проекта без сети и без установки зависимостей, без оболочки внутри и от непривилегированного пользователя.
Что делает:
- строит SBOM в формате CycloneDX по манифестам и lock-файлам проекта: каталог монтируется только на чтение, сеть контейнеру не нужна;
- для Python-проекта без lock-файла сначала разрешает зависимости через
uv pip compile— без установки и сборки пакетов; - не содержит оболочки,
apt,npmиpip: в образе только Node.js, cdxgen,uvи стандартная библиотека Python; - публикуется в Docker Hub и GHCR для
linux/amd64иlinux/arm64с provenance, SBOM и подписью cosign keyless; - перед каждой публикацией проходит пайплайн безопасности: gitleaks, hadolint, Trivy по Dockerfile и по сборке образа, SBOM.
| Компонент | Версия | Источник |
|---|---|---|
| cdxgen | 12.9.0 | npm-пакет @cyclonedx/cdxgen, зависимости по package-lock.json |
| Node.js | 24 | база gcr.io/distroless/nodejs24-debian13:nonroot |
| uv | 0.13.6 | ghcr.io/astral-sh/uv |
| Python, только stdlib | 3.12 | python:3.12-slim без pip, ensurepip, idlelib, tkinter и тестов |
- Пользователь
65532:65532, рабочий каталог/app,HOME=/tmp. ENTRYPOINT— cdxgen: аргументы после имени образа уходят ему напрямую.- Базовые образы закреплены по digest в
ARGв Dockerfile. - Поверх пакета базы лежит
zlib1g1.3.2-4 из Debian sid: в trixie исправления CVE-2026-76844 и CVE-2026-85091 ещё нет. Наложение временное, это стадияzlibвDockerfile. Trivy показывает обе CVE и закрытую той же версией CVE-2026-27171 и на исправленном пакете, пока исправлений нет в trixie: это ложные срабатывания, исключения с причиной — в .trivyignore.yaml. - Версия образа равна версии cdxgen внутри, тег
latestпереставляет каждый прогонrelease. LICENSEиNOTICEрепозитория лежат в образе в/licenses.
docker pull geminishkvdev/cdxgen-distroless:12.9.0
docker pull ghcr.io/geminishkv/cdxgen-distroless:12.9.0Тег повторяет версию cdxgen и может быть пересобран при обновлении базовых образов, поэтому в пайплайнах стоит закреплять digest. Он печатается в сводке прогона release, в заметках GitHub Release и в описании на Docker Hub:
docker pull ghcr.io/geminishkv/cdxgen-distroless@sha256:<digest>Установка зависимостей ради SBOM исполняет на агенте CI чужой код: сборочные и install-скрипты пакетов. Образ рассчитан на режим, где этого не происходит: cdxgen только читает файлы проекта.
IMAGE=geminishkvdev/cdxgen-distroless:12.9.0
docker create --name cdxgen-sbom --network none \
-v "$PWD":/app:ro "$IMAGE" \
-t js --spec-version 1.6 --no-install-deps -o /tmp/bom.json /app
docker start -a cdxgen-sbom
docker cp cdxgen-sbom:/tmp/bom.json bom.json
docker rm cdxgen-sbom| Параметр | Зачем |
|---|---|
--network none |
сеть контейнеру не нужна |
-v "$PWD":/app:ro |
проект монтируется только на чтение |
-t js |
тип проекта, список типов — в документации cdxgen |
--spec-version 1.6 |
версия CycloneDX; по умолчанию у cdxgen 1.7, пайплайн репозитория использует 1.6 |
--no-install-deps |
cdxgen не пытается ставить зависимости и читает lock-файлы как есть |
-o /tmp/bom.json |
результат пишется внутри контейнера и забирается через docker cp |
Результат копируется из остановленного контейнера, поэтому вместо docker run --rm используются docker create и docker start -a. Capabilities контейнеру не нужны: команда работает и с --cap-drop ALL --security-opt no-new-privileges.
Без lock-файла и без сети cdxgen вернёт пустой SBOM. Сначала зависимости разрешает uv, затем cdxgen строит SBOM по закреплённому списку уже без сети:
mkdir -p sbom-work && cp pyproject.toml sbom-work/
docker create --name cdxgen-uv --entrypoint /usr/local/bin/uv \
-v "$PWD":/app:ro "$IMAGE" \
pip compile --no-build --no-config --no-sources --no-python-downloads \
/app/pyproject.toml -o /tmp/requirements.txt
docker start -a cdxgen-uv
docker cp cdxgen-uv:/tmp/requirements.txt sbom-work/requirements.txt
docker rm cdxgen-uv
docker create --name cdxgen-sbom --network none \
-v "$PWD/sbom-work":/app:ro "$IMAGE" \
-t python --spec-version 1.6 --no-install-deps -o /tmp/bom.json /app
docker start -a cdxgen-sbom
docker cp cdxgen-sbom:/tmp/bom.json bom.json
docker rm cdxgen-sbomПараметр uv |
Зачем |
|---|---|
--no-build |
пакеты не собираются из исходников; пакет без wheel останавливает резолв с именем пакета |
--no-config |
настройки uv из проекта (uv.toml, [tool.uv]) не читаются: проект не подменит индекс по умолчанию |
--no-sources |
[tool.uv.sources] не применяется: проект не уведёт отдельный пакет на свой индекс |
--no-python-downloads |
используется только интерпретатор образа |
Шагу резолва нужна сеть до индекса пакетов: по умолчанию это PyPI, другой индекс задаётся флагом --default-index.
В образе нет сборочных тулчейнов: JDK, Maven, Gradle, Go, .NET SDK. cdxgen видит только то, что записано в манифестах и lock-файлах проекта.
| Артефакт | Где лежит | Что это |
|---|---|---|
bom.json |
каталог запуска | SBOM проекта, CycloneDX JSON |
образ с тегами версии и latest |
Docker Hub, GHCR | индекс для linux/amd64 и linux/arm64 |
| provenance и SBOM образа | реестр, рядом с образом | аттестации BuildKit: provenance mode=max и SBOM в формате SPDX от закреплённого генератора |
| подпись cosign | реестр, рядом с образом | keyless, сертификат выписан на workflow release.yml |
| аттестация происхождения GitHub | GHCR | SLSA provenance от actions/attest |
| GitHub Release | страница релизов репозито 8000 рия | заметки: изменения из CHANGELOG.md, адреса образа по digest, состав, команды запуска и проверки; во вложениях SBOM опубликованных образов по платформам (SPDX) и три схемы |
| описание на Docker Hub | страница репозитория в Docker Hub | обзор образа: теги и digest текущего выпуска, запуск, состав, проверка подписи, схемы |
security-* |
артефакты прогона Actions | отчёты слоёв, sbom-image.cdx.json от syft и sbom-cdxgen.cdx.json от cdxgen |
DIGEST=sha256:<digest>
cosign verify "ghcr.io/geminishkv/cdxgen-distroless@$DIGEST" \
--certificate-identity-regexp '^https://github.com/geminishkv/cdxgen-distroless/\.github/workflows/release\.yml@refs/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify "oci://ghcr.io/geminishkv/cdxgen-distroless@$DIGEST" --owner geminishkvПодпись сделана cosign 3 в формате bundle, для проверки нужен cosign 3.x; gh attestation verify требует выполненного gh auth login. Образ в Docker Hub подписан так же: в cosign verify меняется только адрес образа. Те же команды с подставленным digest есть в сводке прогона release и в заметках GitHub Release.
docker build -t cdxgen-distroless:dev .
python3 scripts/security/install.py trivy hadolint syft gitleaks
python3 scripts/security/hadolint.py Dockerfile
python3 scripts/security/trivy_config.py Dockerfile
python3 scripts/security/trivy_image.py cdxgen-distroless:dev
python3 scripts/security/sbom.py cdxgen-distroless:dev
python3 scripts/security/gitleaks.py
python3 -m unittest discover -s tests
pre-commit run --all-filesinstall.py скачивает сканеры в .local/security/bin по версии и sha256 из scripts/security/common.py; пины заведены для Linux x86_64 и macOS arm64, у hadolint — ещё и для Linux arm64. Отчёты складываются в .local/security/reports. Скрипты те же, что вызывает CI. pre-commit run --all-files проверяет файлы, которые уже под git. Гейт проверен на macOS arm64 и Linux x86_64; на Linux arm64 pre-commit не поднимется: у taplo нет готового wheel под эту платформу.
| Workflow | Триггер | Назначение |
|---|---|---|
ci.yml |
pull request в main, push в main, вручную |
lint: pre-commit run --all-files и unittest; security: вызов security.yml |
security.yml |
workflow_call, вручную |
сборка образа для linux/amd64, сканеры, вердикт gate, сводка report |
release.yml |
тег v*, вручную |
security, затем publish: сборка под две архитектуры, публикация, подпись, аттестация, выгрузка SBOM образа; на теге — release-notes: GitHub Release с вложениями и dockerhub-description: описание на Docker Hub |
| Job | Инструмент | Что проверяет | Гейт |
|---|---|---|---|
gitleaks |
gitleaks | секреты во всей истории git | любая находка |
hadolint |
hadolint | Dockerfile | error и warning |
trivy-config |
Trivy | misconfiguration в Dockerfile | HIGH и CRITICAL |
trivy-image |
Trivy | уязвимости пакетов ОС, npm и зависимостей бинаря uv в образе |
CRITICAL и HIGH с доступным исправлением |
sbom |
syft и cdxgen из образа | состав образа, CycloneDX 1.6 | находок не даёт |
- Один сканер — один job. Логика лежит в
scripts/security/*.py, workflow только вызывают скрипты. - Каждый скрипт проверяет покрытие: ноль просмотренных объектов считается отказом инструмента, а не успехом.
gateкрасный, если хотя бы один из четырёх гейтящих слоёв неsuccess, в том числе отменён или пропущен.report— единственный job с правом записи (pull-requests: write): сводка вGITHUB_STEP_SUMMARYи один обновляемый комментарий в pull request с рейтингом и дельтой к прошлому прогону. Когда токен только на чтение (pull request из форка), комментарий не пишется, сводка остаётся в прогоне.- Рейтинг считается по новым находкам: E — есть critical; D — high больше 5; C — high от 1 до 5 или medium больше 10; B — есть medium; A — ничего из этого.
- Исключения действуют только из файлов: принятые находки Trivy —
.trivyignore.yamlс причиной и сроком, исключения gitleaks —.gitleaks.tomlпо коммиту и пути. Комментарииgitleaks:allowи прагмыhadolint ignoreне действуют, а.hadolint.yamlв каталоге иtrivy:ignoreв Dockerfile останавливают слой. - Правила
trivy config— встроенные в закреплённую версию Trivy, набор при прогоне не обновляется. - Сканируется сборка
linux/amd64из того же Dockerfile и тех же закреплённых входов; публикуемые образы обеих архитектурpublishсобирает заново. publishзапускается только после успешногоsecurity.ymlцеликом, включаяsbomиreport.
| Куда | Чем авторизуется job | Что завести в репозитории |
|---|---|---|
| Docker Hub, образ | DOCKERHUB_USERNAME, DOCKERHUB_TOKEN |
два секрета; токен Docker Hub с правами Read & Write, если репозиторий на Docker Hub уже создан, иначе Read, Write, Delete: создать репозиторий при первой публикации может только он |
| Docker Hub, описание | DOCKERHUB_USERNAME, DOCKERHUB_DESCRIPTION_TOKEN |
ещё один секрет: отдельный токен с правами Read, Write, Delete |
| GHCR | github.token, право packages: write |
ничего |
| Подпись cosign и аттестация | OIDC, права id-token: write и attestations: write |
ничего |
| GitHub Release | github.token, право contents: write |
ничего |
Менять описание Docker Hub разрешает только токену с правом Delete, поэтому токен отдельный: в job publish, где работают сторонние actions, он не попадает. В форке достаточно завести три секрета Docker Hub и заменить адреса: образов — в env в release.yml, репозитория — в метке org.opencontainers.image.source в Dockerfile и в SECURITY.md, владельца — в .github/CODEOWNERS. Пространство имён Docker Hub не обязано совпадать с владельцем на GitHub: здесь это geminishkvdev и geminishkv.
git tag -a v12.9.0 -m "cdxgen-distroless 12.9.0"
git push origin v12.9.0Тег обязан совпадать с версией @cyclonedx/cdxgen в package.json, а в CHANGELOG.md должен быть раздел [версия] — из него собираются заметки релиза. При расхождении scripts/release_version.py останавливает publish до сборки; там же проходит сухой рендер заметок и описания Docker Hub, чтобы ошибка шаблона не всплыла после публикации образа. Ручной запуск release разрешён только с основной ветки или с тега версии.
На теге job release-notes создаёт GitHub Release. Текст собирается по шаблону scripts/templates/release_notes.md: раздел CHANGELOG.md, адреса образа по digest, состав из Dockerfile, команды запуска и проверки. Во вложениях — три схемы и SBOM опубликованных образов, которые scripts/release_sbom.py выгружает из аттестаций реестра. Release создаётся черновиком и публикуется после загрузки вложений. Затем job dockerhub-description обновляет описание репозитория на Docker Hub по шаблону scripts/templates/dockerhub.md. Ручной запуск с ветки публикует только образ.
Предпросмотр обоих текстов до релиза, с нулевым digest:
python3 scripts/release_notes.py render
python3 scripts/dockerhub_description.py renderActions закреплены по SHA; образы BuildKit, binfmt и генератора SBOM в workflow — по digest. Dependabot обновляет npm раз в неделю, GitHub Actions и хуки pre-commit раз в месяц, везде с cooldown 7 дней. Вручную обновляются базовые образы в ARG в Dockerfile (Dependabot разбирает только литеральные строки FROM, поэтому запись docker в dependabot.yml сейчас ничего не обновляет), три образа в workflow и версии сканеров в scripts/security/common.py. Стадию zlib в Dockerfile и три записи о zlib1g в .trivyignore.yaml нужно убрать, когда исправление появится в базе distroless; срок записей — 2026-12-05.
Локальный гейт — .pre-commit-config.yaml. Job lint выполняет те же хуки, кроме gitleaks: историю проверяет отдельный job; zizmor в CI работает с токеном и включает онлайн-аудиты.
Три схемы по ГОСТ 19.701-90. Исходники — docs/diagrams/*.mmd, рядом лежат SVG, отрендеренные mmdc (mermaid-cli 12.2.0). После правки исходника SVG перерендерить:
mmdc -c docs/diagrams/mermaid.config.json -i docs/diagrams/image.mmd -o docs/diagrams/image.svg
mmdc -c docs/diagrams/mermaid.config.json -i docs/diagrams/security.mmd -o docs/diagrams/security.svg
mmdc -c docs/diagrams/mermaid.config.json -i docs/diagrams/delivery.mmd -o docs/diagrams/delivery.svgВид задаёт mermaid.config.json: классический стиль, шрифт Arial, размер по содержимому и фиксированный seed, поэтому повторный рендер на той же версии даёт тот же файл.
cdxgen-distroless/
├── Dockerfile # multi-stage: build, uv, python, zlib, итог на distroless
├── .dockerignore # allowlist: package*.json, LICENSE, NOTICE
├── package.json # версия cdxgen и overrides
├── package-lock.json # закреплённое дерево зависимостей cdxgen
├── scripts/
│ ├── security/
│ │ ├── common.py # пины сканеров, покрытие, сводка слоя
│ │ ├── install.py # установка сканеров по версии и sha256
│ │ ├── gitleaks.py # секреты в истории
│ │ ├── hadolint.py # линтер Dockerfile
│ │ ├── trivy_config.py # misconfiguration
│ │ ├── trivy_image.py # уязвимости образа, гейт
│ │ ├── sbom.py # SBOM образа: syft и cdxgen
│ │ └── report.py # вердикт гейта, сводка, комментарий в PR
│ ├── templates/ # шаблоны: release_notes.md, dockerhub.md
│ ├── release_version.py # версия образа, сверка тега, CHANGELOG и ветки
│ ├── release_summary.py # сводка релиза: digest и команды проверки
│ ├── release_sbom.py # SBOM опубликованного образа из аттестаций реестра
│ ├── release_notes.py # заметки, вложения и GitHub Release тега
│ ├── dockerhub_description.py # описание репозитория на Docker Hub
│ └── check_links.py # относительные ссылки в *.md
├── tests/ # unittest: сводка, сканеры, релизные скрипты, пины
├── docs/diagrams/ # схемы: *.mmd, *.svg, mermaid.config.json
├── .github/
│ ├── workflows/ # ci.yml, security.yml, release.yml
│ ├── dependabot.yml
│ └── CODEOWNERS
├── .pre-commit-config.yaml # локальный гейт
├── .gitleaks.toml # allowlist gitleaks
├── .trivyignore.yaml # baseline Trivy
├── .markdownlint.json
├── .gitignore
├── ruff.toml
├── assets/logo.jpg
├── CHANGELOG.md
├── SECURITY.md
├── NOTICE
└── LICENSE
Лицензия — Apache-2.0, сторонние компоненты перечислены в NOTICE. Как сообщить об уязвимости — в SECURITY.md.
Copyright (c) 2026 Elijah S Shmakov