aft-sbom: генерация SBOM#

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

Инструментарий AFT включает два исполняемых файла для генерации SBOM:

aft-sbom-generator — создаёт SBOM для рантаймов на основе анализа установленных deb-пакетов;
aft-flatpak-sbom — создаёт SBOM для установленных Flatpak-приложений, комбинируя данные из нескольких источников (каталогизаторов).

Формат вывода#

Оба инструмента генерируют SBOM в формате CycloneDX JSON (спецификация 1.5).

Структура документа:

{
    "bomFormat": "CycloneDX",
    "specVersion": "1.5",
    "serialNumber": "urn:uuid:<id>-<версия>",
    "version": 1,
    "metadata": {
        "timestamp": "2026-01-15T10:30:00Z",
        "component": {
            "type": "container",
            "name": "org.example.Platform",
            "version": "1.0"
        },
        "tools": [
            {
                "vendor": "AFT",
                "name": "aft-sbom-generator",
                "version": "1.0.0"
            }
        ]
    },
    "components": [ ],
    "dependencies": [ ]
}

Каждый компонент в массиве components содержит:

type — тип (library, application, framework, platform);
name — имя пакета или компонента;
version — версия;
purl — Package URL (стандартизированный идентификатор пакета);
licenses — лицензии;
hashes — контрольные суммы;
supplier — поставщик;
properties — дополнительные свойства (архитектура, тип пакета, источник).

aft-sbom-generator#

Генерирует SBOM для рантайма путём сканирования установленных deb-пакетов в корневой файловой системе.

Синтаксис#

aft-sbom-generator [ПАРАМЕТРЫ] <путь-к-rootfs> <идентификатор-рантайма>

Позиционные аргументы:

<путь-к-rootfs> — путь к корневой файловой системе рантайма;
<идентификатор-рантайма> — идентификатор рантайма (например, org.example.Platform).

Параметры#

Параметр	По умолчанию	Описание
`-v`, `--version`	`1.0.0`	Версия рантайма для записи в SBOM.
`-a`, `--arch`	`amd64`	Архитектура.
`-o`, `--output`	Автоматически	Путь к выходному файлу SBOM. По умолчанию: `<rootfs>/usr/share/sbom/<id>-<версия>.cdx.json`.
`-d`, `--description`	Автоматически	Описание рантайма (определяется из идентификатора).
`-b`, `--base-image`	Автоматически	Идентификатор базового образа.
`-f`, `--format`	`cyclonedx-json`	Формат вывода. Поддерживается только `cyclonedx-json`.
`-q`, `--quiet`		Минимальный вывод.
`-h`, `--help`		Вывод справки.

Процесс работы#

Сканирование базы данных dpkg в указанной корневой файловой системе;
Извлечение метаданных каждого установленного пакета: имя, версия, архитектура, описание, лицензия, исходный пакет, размер, контрольные суммы;
Формирование CycloneDX-документа с пакетами как компонентами типа library;
Генерация PURL для каждого пакета: pkg:deb/debian/<имя>@<версия>?arch=<архитектура>;
Сохранение результата в файл.

Помимо основного файла, копия SBOM сохраняется в /tmp/<id>-<версия>.cdx.json.

Пример#

aft-sbom-generator -v 1.0 -a amd64 /path/to/rootfs org.example.Platform

Результат: /path/to/rootfs/usr/share/sbom/org.example.Platform-1.0.cdx.json

Примечание

При использовании aft-runtime build с параметром build.sbom: true вызов aft-sbom-generator выполняется автоматически на этапе сборки рантайма.

aft-flatpak-sbom#

Генерирует SBOM для установленного Flatpak-приложения, комбинируя данные из нескольких каталогизаторов (catalogers).

Синтаксис#

aft-flatpak-sbom [ПАРАМЕТРЫ] <идентификатор-приложения>

Позиционные аргументы:

<идентификатор-приложения> — идентификатор установленного Flatpak-приложения (например, org.example.MyApp).

Параметры#

Параметр	По умолчанию	Описание
`-o`, `--output`	`<id>.cdx.json`	Путь к выходному файлу SBOM.
`-l`, `--list`		Вывести список установленных Flatpak-приложений и завершить работу.
`-v`, `--verbose`		Подробный вывод (уровень debug).
`-q`, `--quiet`		Минимальный вывод (уровень error).
`-h`, `--help`		Вывод справки.

Процесс работы#

Разрешение Flatpak-приложения: поиск в системных (/var/lib/flatpak) и пользовательских (~/.local/share/flatpak) установках.
Извлечение метаданных: чтение файла metadata из каталога развёртывания, определение рантайма, команды запуска, SDK.
Запуск каталогизаторов: последовательный вызов всех зарегистрированных каталогизаторов, каждый из которых анализирует определённый тип данных и возвращает список компонентов.
Объединение компонентов: дедупликация по нормализованному имени и версии, слияние метаданных с учётом приоритетов.
Формирование SBOM: создание CycloneDX-документа с компонентами приложения и рантайма.

Каталогизаторы#

Каталогизаторы — модули, отвечающие за обнаружение компонентов в структуре Flatpak-приложения. Каждый каталогизатор имеет приоритет: при обнаружении одного и того же компонента несколькими каталогизаторами используются данные из каталогизатора с наивысшим приоритетом.

Приоритет	Каталогизатор	Описание
100	ExistingSBOM	Поиск готовых SBOM-файлов (`.cdx.json`, `.spdx.json`) в каталогах `files/`, `files/share/sbom/`, `files/usr/share/sbom/`. Загружает все компоненты из найденных SBOM.
90	Manifest	Анализ файла `files/manifest.json` (манифест `flatpak-builder` или `buildstream`). Извлекает имена модулей, версии, URL исходного кода, хеши, патчи. Генерирует PURL для GitHub-репозиториев.
85	DebianChangelog	Поиск файлов `changelog.Debian[.gz]` в `files/share/doc/`. Извлекает имена и версии deb-пакетов. Определяет тип компонента (библиотека, данные, документация, приложение). Генерирует PURL: `pkg:deb/debian/<имя>@<версия>`.
80	DesktopFile	Анализ файлов `.desktop` в `files/share/applications/`. Извлекает имя приложения, описание, иконку, категории, MIME-типы.
75	Metadata	Чтение файла `metadata` Flatpak-приложения (секция `[Application]` или `[Runtime]`). Используется как резервный каталогизатор, гарантирующий наличие приложения в SBOM.
70	BinaryVersion	Анализ основного исполняемого файла (ELF). Извлечение версии из бинарного файла (`--version`, встроенные строки).
70	PythonDistInfo	Поиск файлов `.dist-info/METADATA` в `files/lib/python3./site-packages/`. Извлечение метаданных Python-пакетов: имя, версия, лицензия, автор. Генерирует PURL: `pkg:pypi/<имя>@<версия>`.
50	FilenamePattern	Анализ имён разделяемых библиотек по шаблону `lib<имя>.so.<мажорная>.<минорная>.<патч>`. Наименее точный каталогизатор (эвристический).

Объединение компонентов#

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

Компоненты сортируются по приоритету (от высшего к низшему).
Имя нормализуется: удаление префикса lib, суффиксов .so и .bst, приведение к нижнему регистру, замена дефисов на подчёркивания.
Для пары (нормализованное имя, версия) сохраняется компонент с наивысшим приоритетом.
Недостающие метаданные (лицензия, поставщик, описание, URL, хеши) дополняются из компонентов с более низким приоритетом.

Пример#

Генерация SBOM для установленного приложения:

aft-flatpak-sbom org.example.MyApp

Результат: org.example.MyApp.cdx.json

Генерация с указанием выходного файла:

aft-flatpak-sbom -o /path/to/output.cdx.json org.example.MyApp

Вывод списка установленных приложений:

aft-flatpak-sbom --list

Интеграция SBOM в процесс сборки#

SBOM генерируется автоматически при сборке рантаймов и приложений, если соответствующий параметр включён.

В aft-runtime#

build:
  sbom: true

SBOM встраивается в рантайм: usr/share/sbom/<id>-<версия>.cdx.json. При сборке SDK генерируется отдельный SBOM.

В aft-app#

build:
  sbom: true

SBOM генерируется по умолчанию (sbom: true). Для отключения:

build:
  sbom: false

Или в командной строке:

sudo aft-app package --no-sbom ...

SBOM рантайма используется на шаге 4 (сравнение с рантаймом) для определения, какие библиотеки уже присутствуют в рантайме и не нуждаются в включении в пакет приложения.

Структура компонента в SBOM#

Каждый компонент в массиве components содержит следующие поля (в зависимости от каталогизатора заполняются различные подмножества):

{
    "type": "library",
    "name": "zlib",
    "version": "1.2.13",
    "bom-ref": "zlib@1.2.13",
    "purl": "pkg:deb/debian/zlib1g@1.2.13?arch=amd64",
    "description": "Compression library",
    "supplier": {
        "name": "Debian Project"
    },
    "licenses": [
        {
            "license": {
                "id": "Zlib"
            }
        }
    ],
    "hashes": [
        {
            "alg": "SHA-256",
            "content": "abc123..."
        }
    ],
    "externalReferences": [
        {
            "type": "distribution",
            "url": "https://example.com/zlib-1.2.13.tar.xz"
        },
        {
            "type": "vcs",
            "url": "https://github.com/madler/zlib.git",
            "comment": "commit:abc123"
        }
    ],
    "properties": [
        {
            "name": "aft:source",
            "value": "debian_changelog"
        },
        {
            "name": "aft:priority",
            "value": "85"
        },
        {
            "name": "aft:scope",
            "value": "runtime"
        }
    ]
}

Свойства aft:source и aft:priority позволяют определить, каким каталогизатором был обнаружен компонент. Свойство aft:scope принимает значение runtime (компонент рантайма) или application (компонент приложения).

aft-sbom: генерация SBOM

Содержание

aft-sbom: генерация SBOM#

Формат вывода#

aft-sbom-generator#

Синтаксис#

Параметры#

Процесс работы#

Пример#

aft-flatpak-sbom#

Синтаксис#

Параметры#

Процесс работы#

Каталогизаторы#

Объединение компонентов#

Пример#

Интеграция SBOM в процесс сборки#

В aft-runtime#

В aft-app#

Структура компонента в SBOM#