cyclonedx/cyclonedx-cliCLI para generar, analizar, fusionar, comparar (diffing), validar, firmar y convertir SBOMs de CycloneDX en formatos JSON, XML, Protobuf, CSV y 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
La herramienta CLI de CycloneDX actualmente admite análisis de BOM, modificación, comparación (diff), fusión, conversión de formatos, firma y verificación.
La conversión es compatible entre CycloneDX XML, JSON, Protobuf, CSV y SPDX JSON v2.3.
Los binarios se pueden descargar desde la página de versiones.
Nota: La herramienta CLI de CycloneDX está diseñada para casos de uso de automatización. Cualquier comando que tenga la opción --input-file también admite la entrada desde stdin. Del mismo modo, cualquier comando que tenga la opción --output-file admite la salida a stdout. Sin embargo, deberá especificar los formatos de entrada/salida.
Por ejemplo:
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).
Generando un BOM de código fuente, excluyendo el directorio del repositorio Git:
cyclonedx-cli add files --no-input --output-format json --exclude /.git/**
Agregando archivos de salida de compilación, desde el directorio bin, a un BOM existente:
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.
Informando sobre componentes que se incluyen varias veces con distintas versiones:
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)
Convirtiendo de formato XML a JSON:
cyclonedx-cli convert --input-file sbom.xml --output-file sbom.json
Convirtiendo de formato XML a JSON y canalizando la salida a herramientas adicionales:
cyclonedx-cli convert --input-file sbom.xml --output-format json | grep "somthing"
El formato CSV es una representación limitada de la lista de componentes de un BOM.
La intención es proporcionar una forma sencilla de que los usuarios produzcan y consuman BOMs para casos de uso simples. Incluyendo casos de uso simples de migración de datos.
Los únicos campos obligatorios son los campos de componente name y version. Los demás pueden dejarse en blanco u omitirse las columnas.
La conversión entre los formatos SPDX y CycloneDX puede provocar la pérdida de cierta información. La funcionalidad de conversión la proporciona la librería CycloneDX.Spdx.Interop, que forma parte del proyecto de librería CycloneDX .NET.
Para más detalles sobre qué información se pierde, consulte la página del proyecto 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.
Informando sobre componentes con cambios de versión:
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).
Nota: Para realizar una fusión jerárquica, todos los BOMs deben tener el sujeto del BOM descrito en el elemento de componente de metadatos.
Fusionar dos BOMs en formato XML:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-file sbom_all.xml
Fusionando dos BOMs y canalizando la salida a herramientas adicionales:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-format json | grep "something"
Firmar un BOM o archivo
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)
Validar BOM y devolver un código de salida distinto de cero (útil para "romper" automáticamente una compilación, etc.)
cyclonedx-cli validate --input-file sbom.xml --fail-on-errors
Verificar firmas de BOMs y archivos
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)
La herramienta CLI de CycloneDX también se puede ejecutar usando docker docker run cyclonedx/cyclonedx-cli.
Para Linux y MacOS, la CLI se puede instalar mediante el tap de CycloneDX Homebrew:
brew install cyclonedx/cyclonedx/cyclonedx-cli
Las compilaciones con soporte oficial están disponibles para estas plataformas:
Las compilaciones con soporte de la comunidad están disponibles para estas plataformas:
Se requieren dependencias de runtime de .NET Core.
Para Windows, estas deberían estar preinstaladas.
Para Ubuntu, estas son libc6 libgcc1 libgssapi-krb5-2 libicu66 libssl1.1 libstdc++6 zlib1g.
gron transforma JSON en asignaciones discretas para que sea más fácil hacer grep de lo que buscas y ver la 'ruta' absoluta hacia ello.
Para mayor comodidad, gron está incluido en la imagen Docker de CycloneDX CLI.
Ejemplo de uso que lista todos los nombres y versiones de componentes
$ 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";
O lo mismo usando un BOM en formato 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";
Para más detalles sobre el uso de gron, consulte la página del proyecto gron.
Para más detalles sobre el uso de grep, consulte la página man de grep.
Se concede permiso para modificar y redistribuir bajo los términos de la licencia Apache 2.0. Consulte el archivo LICENSE para obtener la licencia completa.
Las pull requests son bienvenidas. Pero por favor lea primero las directrices de contribución de CycloneDX.
Para compilar y probar la solución localmente, debe tener instalado .NET 8. Los comandos estándar como dotnet build y dotnet test funcionan.
Generalmente se espera que las pull requests incluyan pruebas relevantes. Las pruebas se ejecutan automáticamente en Windows, MacOS y Linux para cada pull request. Las advertencias de compilación romperán la compilación.
Por favor, infórmenos si tiene problemas para depurar una prueba que falla en una plataforma a la que no tiene acceso.