cyclonedx/cyclonedx-cliCLI для создания, анализа, объединения, сравнения, проверки, подписания и конвертации CycloneDX SBOM в форматах JSON, XML, Protobuf, CSV и SPDX.
______ __ ____ _ __ ________ ____
/ ____/_ _______/ /___ ____ ___ / __ \ |/ / / ____/ / / _/
/ / / / / / ___/ / __ \/ __ \/ _ \/ / / / / / / / / / /
/ /___/ /_/ / /__/ / /_/ / / / / __/ /_/ / | / /___/ /____/ /
\____/\__, /\___/_/\____/_/ /_/\___/_____/_/|_| \____/_____/___/
/____/
Usage:
cyclonedx [command] [options]
Options:
--version Show version information
-?, -h, --help Show help and usage information
Commands:
add Add information to a BOM (currently supports files)
analyze Analyze a BOM file
convert Convert between different BOM formats
diff <from-file> <to-file> Generate a BOM diff
keygen Generates an RSA public/private key pair for BOM signing
merge Merge two or more BOMs
sign Sign a BOM or file
validate Validate a BOM
verify Verify signatures in a BOM
Инструмент командной строки CycloneDX в настоящее время поддерживает анализ BOM-файлов, их изменение, сравнение, слияние, преобразование форматов, подписание и проверку подписей.
Поддерживается преобразование между CycloneDX XML, JSON, Protobuf, CSV и SPDX JSON v2.3.
Бинарные файлы можно загрузить со страницы релизов.
Примечание: инструмент командной строки CycloneDX создан для сценариев автоматизации. Любые команды, имеющие опцию --input-file, также поддерживают ввод данных из stdin. Аналогично любые команды, имеющие опцию --output-file, поддерживают вывод в stdout. Однако вам нужно будет указать форматы ввода/вывода.
Например:
cat bom.json | cyclonedx-cli convert --input-format json --output-format xml > bom.xml
files
Add files to a BOM
Usage:
cyclonedx add files [options]
Options:
--input-file <input-file> Input BOM filename.
--no-input Use this option to indicate that there is no input BOM.
--output-file <output-file> Output BOM filename, will write to stdout if no value provided.
--input-format <autodetect|json|protobuf|xml> Specify input file format.
--output-format <autodetect|json|protobuf|xml> Specify output file format.
--base-path <base-path> Base path for directory to process (defaults to current working directory if omitted).
--include <include> Apache Ant style path and file patterns to specify what to include (defaults to all files, separate patterns with a space).
--exclude <exclude> Apache Ant style path and file patterns to specify what to exclude (defaults to none, separate patterns with a space).
Создание BOM из исходного кода, исключая каталог Git-репозитория:
cyclonedx-cli add files --no-input --output-format json --exclude /.git/**
Добавление файлов результатов сборки из каталога bin в существующий BOM:
cyclonedx-cli add files --input-file bom.json --output-format json --base-path bin
analyze
Analyze a BOM file
Usage:
cyclonedx analyze [options]
Options:
--input-file <input-file> Input BOM filename, will read from stdin if no value provided.
--input-format <autodetect|json|protobuf|xml> Specify input file format.
--output-format <json|text> Specify output format (defaults to text).
--multiple-component-versions Report components that have multiple versions in use.
Вывод отчёта о компонентах, которые включаются несколько раз с разными версиями:
cyclonedx-cli analyze --input-file sbom.xml --multiple-component-versions
convert
Convert between different BOM formats
Usage:
cyclonedx convert [options]
Options:
--input-file <input-file> Input BOM filename, will read from stdin if no value provided.
--output-file <output-file> Output BOM filename, will write to stdout if no value provided.
--input-format <autodetect|csv|json|protobuf|spdxjson|xml> Specify input file format.
--output-format <autodetect|csv|json|protobuf|spdxjson|xml> Specify output file format.
--output-version <v1_0|v1_1|v1_2|v1_3|v1_4|v1_5|v1_6|v1_7> Specify output BOM specification version. (ignored for CSV and SPDX formats)
Преобразование из формата XML в JSON:
cyclonedx-cli convert --input-file sbom.xml --output-file sbom.json
Преобразование из формата XML в JSON и передача вывода через конвейер дополнительным инструментам:
cyclonedx-cli convert --input-file sbom.xml --output-format json | grep "somthing"
Формат CSV является ограниченным представлением списка компонентов в BOM.
Его цель — предоставить пользователям простой способ создавать и использовать BOM-файлы для простых сценариев, включая простые случаи миграции данных.
Обязательными являются только поля компонента name и version. Остальные можно оставить пустыми или опустить соответствующие столбцы.
Преобразование между форматами SPDX и CycloneDX может привести к потере некоторой информации. Функциональность преобразования предоставляется библиотекой CycloneDX.Spdx.Interop, которая является частью проекта библиотеки CycloneDX .NET.
Более подробную информацию о том, какая информация теряется, см. на странице проекта CycloneDX .NET Library.
diff
Generate a BOM diff
Usage:
cyclonedx diff <from-file> <to-file> [options]
Arguments:
<from-file> From BOM filename.
<to-file> To BOM filename.
Options:
--from-format <autodetect|json|protobuf|xml> Specify from file format.
--to-format <autodetect|json|protobuf|xml> Specify to file format.
--output-format <json|text> Specify output format (defaults to text).
--component-versions Report component versions that have been added, removed or modified.
Вывод отчёта о компонентах с изменёнными версиями:
cyclonedx-cli diff sbom-from.xml sbom-to.xml --component-versions
keygen
Generates an RSA public/private key pair for BOM signing
Usage:
cyclonedx keygen [options]
Options:
--private-key-file <private-key-file> Filename for generated private key file (defaults to "private.key")
--public-key-file <public-key-file> Filename for generated public key file (defaults to "public.key")
merge
Merge two or more BOMs
Usage:
cyclonedx merge [options]
Options:
--input-files <input-files> Input BOM filenames (separate filenames with a space).
--output-file <output-file> Output BOM filename, will write to stdout if no value provided.
--input-format <autodetect|json|protobuf|xml> Specify input file format.
--output-format <autodetect|json|protobuf|xml> Specify output file format.
--output-version <v1_0|v1_1|v1_2|v1_3|v1_4|v1_5|v1_6|v1_7> Specify output BOM specification version.
--hierarchical Perform a hierarchical merge.
--group <group> Provide the group of software the merged BOM describes.
--name <name> Provide the name of software the merged BOM describes (required for hierarchical merging).
--version <version> Provide the version of software the merged BOM describes (required for hierarchical merging).
Примечание: для выполнения иерархического слияния во всех BOM-файлах объект BOM должен быть описан в элементе metadata component.
Слияние двух BOM-файлов в формате XML:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-file sbom_all.xml
Слияние двух BOM-файлов и передача вывода через конвейер дополнительным инструментам:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-format json | grep "something"
Подпись BOM или файла
bom
Sign the entire BOM document
Usage:
cyclonedx sign bom <bom-file> [options]
Arguments:
<bom-file> BOM filename
Options:
--key-file <key-file> Signing key filename (RSA private key in PEM format, defaults to "private.key")
file
Sign arbitrary files and generate a PKCS1 RSA SHA256 signature file
Usage:
cyclonedx sign file <file> [options]
Arguments:
<file> Filename of the file the signature will be created for
Options:
--key-file <key-file> Signing key filename (RSA private key in PEM format, defaults to "private.key")
--signature-file <signature-file> Filename of the generated signature file (defaults to the filename with ".sig" appended)
validate
Validate a BOM
Usage:
cyclonedx validate [options]
Options:
--input-file <input-file> Input BOM filename, will read from stdin if no value provided.
--input-format <autodetect|json|xml> Specify input file format.
--input-version <v1_0|v1_1|v1_2|v1_3|v1_4|v1_5|v1_6|v1_7> Specify input file specification version (defaults to v1.7)
--fail-on-errors Fail on validation errors (return a non-zero exit code)
Проверка BOM и возврат ненулевого кода завершения (удобно для автоматического «обрушения» сборки и т.п.)
cyclonedx-cli validate --input-file sbom.xml --fail-on-errors
Проверка подписей для BOM-файлов и файлов
all
Verify all signatures in a BOM
Usage:
cyclonedx verify all <bom-file> [options]
Arguments:
<bom-file> BOM filename
Options:
--key-file <key-file> Public key filename (RSA public key in PEM format, defaults to "public.key")
file
Verifies a PKCS1 RSA SHA256 signature file for an arbitrary file
Usage:
cyclonedx verify file <file> [options]
Arguments:
<file> File the signature file is for
Options:
--key-file <key-file> Public key filename (RSA public key in PEM format, defaults to "public.key")
--signature-file <signature-file> Signature file to be verified (defaults to the filename with ".sig" appended)
Инструмент командной строки CycloneDX также можно запускать через docker: docker run cyclonedx/cyclonedx-cli.
Для Linux и MacOS CLI можно установить через CycloneDX Homebrew tap:
brew install cyclonedx/cyclonedx/cyclonedx-cli
Официально поддерживаемые сборки доступны для следующих платформ:
Сборки при поддержке сообщества доступны для следующих платформ:
Требуются зависимости среды выполнения .NET Core.
Для Windows они обычно предустановлены.
Для Ubuntu это libc6 libgcc1 libgssapi-krb5-2 libicu66 libssl1.1 libstdc++6 zlib1g.
gron преобразует JSON в отдельные присваивания, чтобы было проще искать нужное с помощью grep и видеть абсолютный «путь» к нему.
Для удобства gron включён в Docker-образ CycloneDX CLI.
Пример использования, выводящий все имена и версии компонентов
$ gron bom-1.2.json | grep -E "(components\[[[:digit:]]*\].name)|(components\[[[:digit:]]*\].version)"
json.components[0].name = "tomcat-catalina";
json.components[0].version = "9.0.14";
json.components[1].name = "mylibrary";
json.components[1].version = "1.0.0";
Или то же самое с BOM в формате XML
$ cyclonedx convert --input-file bom.xml --output-format json | gron | grep -E "(components\[[[:digit:]]*\].name)|(components\[[[:digit:]]*\].version)"
json.components[0].name = "tomcat-catalina";
json.components[0].version = "9.0.14";
json.components[1].name = "mylibrary";
json.components[1].version = "1.0.0";
Более подробно об использовании gron см. на странице проекта gron.
Более подробно об использовании grep см. на man-странице grep.
Разрешение на изменение и распространение предоставляется на условиях лицензии Apache 2.0. Полный текст лицензии см. в файле LICENSE.
Пул-реквесты приветствуются. Но сначала, пожалуйста, прочтите руководство по участию в разработке CycloneDX.
Для локальной сборки и тестирования решения у вас должен быть установлен .NET 8. Стандартные команды, такие как dotnet build и dotnet test, работают.
Ожидается, что пул-реквесты будут включать соответствующие тесты. Тесты автоматически запускаются на Windows, MacOS и Linux для каждого пул-реквеста. Наличие предупреждений при сборке приведёт к её сбою.
Пожалуйста, сообщите нам, если у вас возникают трудности с отладкой теста, который падает на платформе, к которой у вас нет доступа.