cyclonedx/cyclonedx-cliCLI pour la génération, l'analyse, la fusion, le diffing, la validation, la signature et la conversion de SBOM CycloneDX dans les formats JSON, XML, Protobuf, CSV et 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
L'outil CycloneDX CLI prend actuellement en charge l'analyse, la modification, la génération de diff, la fusion, la conversion de format, la signature et la vérification des BOM.
La conversion est prise en charge entre CycloneDX XML, JSON, Protobuf, CSV et SPDX JSON v2.3.
Les binaires peuvent être téléchargés depuis la page des versions.
Remarque : l'outil CycloneDX CLI est conçu pour des cas d'utilisation d'automatisation. Toutes les commandes disposant de l'option --input-file prennent également en charge la lecture de l'entrée depuis stdin. De même, toutes les commandes disposant de l'option --output-file prennent en charge l'écriture vers stdout. Vous devrez toutefois fournir les formats d'entrée/sortie.
Par exemple :
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).
Génération d'une BOM de code source, en excluant le répertoire du dépôt Git :
cyclonedx-cli add files --no-input --output-format json --exclude /.git/**
Ajout de fichiers de sortie de build, depuis le répertoire bin, à une BOM existante :
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.
Rapport sur les composants inclus plusieurs fois avec des versions différentes :
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)
Conversion du format XML vers JSON :
cyclonedx-cli convert --input-file sbom.xml --output-file sbom.json
Conversion du format XML vers JSON et envoi du résultat vers d'autres outils via un pipe :
cyclonedx-cli convert --input-file sbom.xml --output-format json | grep "somthing"
Le format CSV est une représentation limitée de la liste des composants d'une BOM.
L'objectif est de fournir un moyen simple aux utilisateurs de produire et de consommer des BOM pour des cas d'utilisation simples, y compris des cas simples de migration de données.
Les seuls champs obligatoires sont les champs name et version du composant. Les autres peuvent être laissés vides ou les colonnes peuvent être omises.
La conversion entre les formats SPDX et CycloneDX peut entraîner une perte de certaines informations. La fonctionnalité de conversion est fournie par la bibliothèque CycloneDX.Spdx.Interop, qui fait partie du projet de bibliothèque CycloneDX .NET.
Pour plus de détails sur les informations perdues, consultez la page du projet 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.
Rapport sur les composants présentant des changements de version :
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).
Remarque : pour effectuer une fusion hiérarchique, toutes les BOM doivent décrire le sujet de la BOM dans l'élément de composant des métadonnées.
Fusion de deux BOM au format XML :
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-file sbom_all.xml
Fusion de deux BOM et envoi du résultat vers d'autres outils via un pipe :
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-format json | grep "something"
Signe une BOM ou un fichier
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)
Valide la BOM et renvoie un code de sortie non nul (pratique pour « casser » automatiquement un build, etc.)
cyclonedx-cli validate --input-file sbom.xml --fail-on-errors
Vérifie les signatures des BOM et des fichiers
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)
L'outil CycloneDX CLI peut également être exécuté avec docker : docker run cyclonedx/cyclonedx-cli.
Pour Linux et MacOS, la CLI peut être installée via le tap Homebrew CycloneDX :
brew install cyclonedx/cyclonedx/cyclonedx-cli
Des builds officiellement pris en charge sont disponibles pour ces plateformes :
Des builds pris en charge par la communauté sont disponibles pour ces plateformes :
Les dépendances d'exécution .NET Core sont requises.
Pour Windows, elles devraient être préinstallées.
Pour Ubuntu, il s'agit de libc6 libgcc1 libgssapi-krb5-2 libicu66 libssl1.1 libstdc++6 zlib1g.
gron transforme le JSON en affectations distinctes pour faciliter la recherche avec grep et visualiser le « chemin » absolu qui y mène.
Par commodité, gron est inclus dans l'image Docker de la CLI CycloneDX.
Exemple d'utilisation qui liste tous les noms et versions de composants
$ 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";
Ou l'équivalent avec une BOM au format 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";
Pour plus de détails sur l'utilisation de gron, consultez la page du projet gron.
Pour plus de détails sur l'utilisation de grep, consultez la page de manuel de grep.
La permission de modifier et de redistribuer est accordée selon les termes de la licence Apache 2.0. Consultez le fichier LICENSE pour la licence complète.
Les pull requests sont les bienvenues. Mais veuillez d'abord lire les directives de contribution de CycloneDX.
Pour compiler et tester la solution localement, vous devez avoir .NET 8 installé. Les commandes standard comme dotnet build et dotnet test fonctionnent.
Il est généralement attendu que les pull requests incluent des tests pertinents. Les tests sont exécutés automatiquement sur Windows, MacOS et Linux pour chaque pull request. Les avertissements de compilation feront échouer le build.
Veuillez nous informer si vous rencontrez des difficultés à déboguer un test qui échoue sur une plateforme à laquelle vous n'avez pas accès.