SBOM с sbom-tool: руководство по генерации

Иллюстрация: концепция управления документами — иконки на виртуальном фоне

Быстрые ссылки

Getting Started
Generating an SBOM
SBOM Contents
Scanning Docker Images
Summary

Что такое SBOM — в одно предложение

SBOM (Software Bill of Materials) — структурированный список компонентов, библиотек и пакетов, из которых состоит ваше программное обеспечение, с привязкой к версиям, источникам и лицензиям.

Важно: SBOM помогает быстро определить, где используется уязвимая библиотека, и ускоряет реакцию при инцидентах цепочки поставок.

Введение

SBOMs стремительно набирают популярность после крупных реальных инцидентов цепочки поставок: наличие формализованного списка компонентов облегчает поиск и устранение рисков. Microsoft опубликовала подход к генерации SBOM в октябре 2021 и затем открыла исходники инструмента для Windows, macOS и Linux. Проект изначально назывался Salus, но переименован в sbom-tool из‑за конфликта имён с другим проектом.

sbom-tool генерирует документы, совместимые со стандартом SPDX (Software Package Data Exchange), который принят в ISO и позволяет передавать отчёты между инструментами экосистемы.

Установка и первый запуск

Скачать sbom-tool можно с репозитория Microsoft на GitHub (страница релизов содержит предсобранные бинарники). Выберите подходящий файл для вашей ОС, сделайте его исполняемым и переместите в каталог в PATH.

Пример для Linux:

$ wget https://github.com/microsoft/sbom-tool/releases/download/v/sbom-tool-linux-x64

$ chmod +x sbom-tool-linux-x64

$ mv sbom-tool-linux-x64 /usr/local/bin/sbom-tool

После этого можно запустить утилиту для просмотра справки:

$ sbom-tool

Ожидаемый ответ в терминале:

No action was specified

The Sbom tool generates a SBOM for any build artifact.

Usage - Microsoft.Sbom.Tool  -options

Важно: используйте релизы из официального репозитория или соберите из исходников, если нужны дополнительные проверки доверия к бинарнику.

Генерация SBOM

Новая SBOM создаётся командой generate. Обязательные и часто используемые параметры:

-b (BuildDropPath) — папка, куда будут записаны сгенерированные SPDX-манифесты.
-bc (BuildComponentPath) — папка, которая будет просканирована на предмет зависимостей проекта.
-nsb (NamespaceUriBase) — базовый URL, используемый как namespace для манифеста SBOM (например, https://example.com/sbom).

Если инструмент не может определить имя и версию проекта автоматически, их можно указать явно:

-pn (PackageName) — имя проекта/пакета.
-pv (PackageVersion) — версия проекта, соответствующая релизу.

Пример генерации SBOM для текущей рабочей директории (директория sbom-output должна существовать заранее):

$ mkdir sbom-output

$ sbom-tool generate -b sbom-output -bc . -pn example -pv 1.0 -nsb https://example.com/sbom

После выполнения в терминале появится обзор результатов сканирования:

[INFO] Enumerated 3728 files and 607 directories in 00:00:00.5938034 

[INFO] |Component Detector Id |Detection Time |# Components Found |# Explicitly Referenced |

...

[INFO] |Npm |0.63 seconds |241 |0 |

...

[INFO] |Total |0.64 seconds |241 |0 |

[INFO] Detection time: 0.6374678 seconds.

sbom-tool поддерживает множество форматов: npm, NuGet, PyPi, Maven, Rust Crates, Ruby gems и пакеты Linux внутри Docker-образов. В сумме поддерживается 19 различных языков/форматов зависимостей. Также поддерживаются ссылки на удалённые репозитории GitHub.

Совет: генерируйте SBOM как часть CI/CD (например, в шаге сборки), чтобы документ всегда соответствовал конкретному артефакту релиза.

Содержимое сгенерированного SBOM

По умолчанию результат записывается в путь _manifest/spdx_2.2/manifest.spdx.json внутри указанной вами папки сборки. Это подробный JSON-файл, предназначенный для автоматизированной обработки.

Пример фрагмента из результата (формат SPDX JSON):

{
  "files": [],
  "packages": [
    {
      "name": "color-convert",
      "SPDXID": "SPDXRef-Package-A72B0922E46D9828746F346D7FD11B7F81EDEB15B92BEEDAE087F5F7407FECDC",
      ...
    }
  ]
}

В отчёте обычно присутствуют четыре основных раздела:

Раздел files — файлы исходного кода, которые вы написали в проекте. Этот раздел заполняется не всегда: sbom-tool добавляет его для некоторых типов проектов (например, для C#-решений).
Раздел packages — каталог третьих компонентов и библиотек, найденных в проекте: менеджер пакетов, версия и информация о лицензии.
Раздел relationships — отношения между компонентами (наиболее распространённое — DEPENDS_ON). Также встречаются CREATED_BY, DEPENDENCY_OF, PATCH_FOR и т. д.
Метаданные отчёта — поля name, documentNamespace, spdxVersion, creationInfo, которые идентифицируют SBOM, инструмент и версию спецификации SPDX.

Практическое применение: сгенерированную SPDX-JSON можно передавать в такие инструменты, как Grype, для автоматизированного поиска уязвимостей и устаревших зависимостей.

Сканирование Docker-образов

sbom-tool умеет анализировать уже существующие Docker-образы. Для этого добавьте флаг -di и укажите тег или digest образа. Прочие параметры остаются такими же.

Пример:

$ sbom-tool generate -di ubuntu:latest -b sbom-output -bc . -pn demo -pv 1.0 -nsb https://demo.com/demo

Инструмент разберёт образ, определит пакеты внутри него и включит их в общий SBOM вместе с зависимостями из исходной директории. Можно перечислить несколько образов через запятую.

Важно: при сканировании образов учтите различия в менеджерах пакетов внутри разных базовых слоёв (apt, rpm, apk и т. д.). sbom-tool агрегирует результаты, но для глубокой проверки пакетов ОС иногда полезно запускать специализированные сканеры безопасности.

Когда sbom-tool может не подойти (ограничения)

Если проект использует нестандартные форматы зависимостей или собственные менеджеры пакетов, sbom-tool может не распознать компоненты автоматически.
Если вам нужен другой формат, например CycloneDX, потребуется либо конвертация SPDX → CycloneDX, либо использование других инструментов.
Для максимально подробного анализа контейнерного слоя может потребоваться сторонний инструмент, специализированный на пакетах ОС.

Альтернатива: инструменты вроде Syft (Anchore), CycloneDX CLI или интеграция с платформами SCA дают другие форматы, дополнительные плагины и интеграции.

Практическая методология внедрения (мини‑методика)

Подготовка: добавьте sbom-tool в репозиторий или используйте системный пакет/бинарник в CI.
Определите каталог(и) для сканирования и унифицируйте параметры -pn, -pv, -nsb в конвейер.
В CI добавьте шаг генерации SBOM после этапа сборки артефакта, до упаковки/релиза.
Сохраните артефакт SBOM как часть релиза (release asset) и в хранилище артефактов.
Интегрируйте в процесс автоматического сканирования уязвимостей (Grype, Trivy и т. п.) и в процесс контроля лицензий.
Регулярно проводите ревизию скриптов генерации и обновляйте sbom-tool по мере релизов.

Playbook: шаги при обнаружении уязвимости по SBOM

Получить тикет или уведомление от сканера уязвимостей.
По SBOM найти все продукты, зависящие от уязвимой версии (используя поле relationships).
Определить, влияет ли уязвимость на используемую конфигурацию (контекст использования).
Подготовить план обновления зависимостей: обновить библиотеку, проверить совместимость, собрать и протестировать артефакт.
Выпустить патч‑релиз с новым SBOM и закрыть тикет.
При невозможности автоматического обновления — определить компенсационные меры (микрофрагментация, WAF, ограничение доступа).

Role‑based чек‑листы

Для разработчика:
- Включить команды генерации SBOM в локальные скрипты (make, npm script).
- Уточнить, какие зависимости являются direct/indirect.
- Обновлять зависимости и проверять тесты.
Для инженера безопасности:
- Включить SBOM в процесс сканирования уязвимостей.
- Настроить оповещения для критических CVE.
- Аудит лицензий из packages.
Для релиз‑менеджера:
- Хранить SBOM как артефакт релиза.
- Проверять соответствие PackageVersion релизной версии.
- Обеспечить доступ к SBOM для клиентов, если требуется.

Тестовые случаи и критерии приёмки

Критерии приёмки для автоматического шага генерации SBOM в CI:

CI шаг успешно завершает sbom-tool без ошибок.
В каталоге артефактов появился файл _manifest/spdx_2.2/manifest.spdx.json.
В поле documentNamespace присутствует ожидаемый -nsb URL.
Количество пакетов в packages совпадает с ожидаемым для контрольной сборки.
SBOM включён как артефакт релиза и доступен для скачивания.

Тесты (пример):

Запуск генерации в чистой среде: проверка наличия manifest.spdx.json.
Проверка работоспособности при отсутствии package.json — инструмент не должен падать с необработанным исключением.
Сканирование Docker-образа с типичными пакетами ОС и проверка, что найденные пакеты включены в итоговый SBOM.

Decision tree — как выбрать способ генерации SBOM

flowchart TD
  A[Есть ли Docker-образы?] -->|Да| B[Нужен ли анализ образа?| если да]
  A -->|Нет| C[Сканировать исходники напрямую]
  B --> D{Использовать sbom-tool}
  C --> D
  D --> E[Формат SPDX подходит?]
  E -->|Да| F[Генерировать SPDX с sbom-tool]
  E -->|Нет| G[Рассмотреть Syft/CycloneDX или конверсию]

Безопасность и конфиденциальность

SBOM обычно содержит метаданные о пакетах и версиях, но не обязателен для хранения секретов. Убедитесь, что в каталогах, которые вы сканируете (-bc), не лежат секретные файлы (ключи, токены). При необходимости исключите чувствительные пути.
Для соответствия требованиям конфиденциальности проверьте, не включаются ли в SBOM артефакты, содержащие персональные данные. SBOM сам по себе предназначен для описания компонентов, а не данных.

Советы по интеграции в CI/CD (пример для GitHub Actions)

Простой шаг для GitHub Actions:

- name: Generate SBOM
  run: |
    wget https://github.com/microsoft/sbom-tool/releases/download/v/sbom-tool-linux-x64 -O sbom-tool
    chmod +x sbom-tool
    ./sbom-tool generate -b sbom-output -bc . -pn ${{ github.repository }} -pv ${{ github.ref_name }} -nsb https://example.com/sbom
- name: Upload SBOM artifact
  uses: actions/upload-artifact@v3
  with:
    name: sbom
    path: sbom-output/_manifest/spdx_2.2/manifest.spdx.json

Адаптируйте шаг под вашу CI-систему (GitLab CI, Jenkins, Azure Pipelines и т. п.).

Совместимость и миграция

sbom-tool производит SPDX v2.2 JSON; если ваша экосистема использует другой формат (CycloneDX), вы можете конвертировать SPDX → CycloneDX с помощью дополнений или сторонних конвертеров.
При миграции старых конвейеров убедитесь, что PackageVersion и PackageName устанавливаются последовательно с релизной нумерацией.

Примеры, когда SBOM особенно полезен

При обнаружении массовой уязвимости в популярной библиотеке (например, Log4j): по SBOM можно быстро найти релизы, содержащие уязвимую версию.
В условиях поставок ПО для регулируемых отраслей: SBOM помогает доказать состав ПО и соответствие требованиям лицензирования.

Частые ошибки и как их избежать

Не включать sbom-tool в PATH без проверки целостности скачанного бинарника — используйте подписанные релизы или собирайте из исходников.
Не исключать временные директории сборки — это может привести к шуму в отчёте.
Сохранять SBOM только локально; лучше — как часть артефактов CI и в релизе.

Краткий глоссарий (одной строкой)

SBOM — список компонентов ПО; SPDX — стандарт для обмена данными о пакетах; PackageName/PackageVersion — имя и версия проекта; DEPENDS_ON — зависимость между компонентами.

Краткое резюме

SBOM Tool — простой способ генерировать SPDX-совместимые SBOM как для исходного кода, так и для Docker-образов. Интеграция генерации SBOM в CI помогает автоматически отслеживать состав релизов, ускоряет реакцию на уязвимости и облегчает аудит лицензий.

Важно: выбирая sbom-tool, учитывайте поддерживаемые форматы и требования к совместимости. Если нужен другой формат, рассмотрите альтернативные инструменты или конвертацию.

Важно: генерируйте SBOM регулярно, храните их вместе с артефактами релиза и подключайте автоматические проверки уязвимостей — это значительно уменьшит время реакции при инцидентах цепочки поставок.