cyclonedx/cyclonedx-cliCLI per generare, analizzare, unire, confrontare, validare, firmare e convertire SBOM CycloneDX nei formati JSON, XML, Protobuf, CSV e 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
Lo strumento CLI CycloneDX supporta attualmente analisi, modifica, differenza (diff), unione (merge), conversione di formato, firma e verifica dei BOM.
La conversione è supportata tra CycloneDX XML, JSON, Protobuf, CSV e SPDX JSON v2.3.
I binari possono essere scaricati dalla pagina delle release.
Nota: lo strumento CLI CycloneDX è pensato per casi d'uso di automazione. Tutti i comandi che hanno l'opzione --input-file supportano anche l'input da stdin. Allo stesso modo, tutti i comandi che hanno l'opzione --output-file supportano l'output su stdout. Tuttavia, dovrai specificare i formati di input/output.
Per esempio:
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).
Generazione di un BOM del codice sorgente, escludendo la directory del repository Git:
cyclonedx-cli add files --no-input --output-format json --exclude /.git/**
Aggiunta dei file di output di build, dalla directory bin, al BOM esistente:
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.
Segnalazione dei componenti inclusi più volte con versioni diverse:
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)
Conversione dal formato XML al formato JSON:
cyclonedx-cli convert --input-file sbom.xml --output-file sbom.json
Conversione dal formato XML al formato JSON e invio dell'output tramite pipe ad altri strumenti:
cyclonedx-cli convert --input-file sbom.xml --output-format json | grep "somthing"
Il formato CSV è una rappresentazione limitata dell'elenco dei componenti in un BOM.
L'intenzione è quella di fornire un modo semplice per gli utenti di produrre e consumare BOM per casi d'uso semplici. Inclusi i semplici casi d'uso di migrazione dei dati.
Gli unici campi obbligatori sono i campi name e version del componente. Gli altri
possono essere lasciati vuoti o le colonne possono essere omesse.
La conversione tra i formati SPDX e CycloneDX può comportare la perdita di alcune
informazioni. La funzionalità di conversione è fornita dalla libreria
CycloneDX.Spdx.Interop, che fa parte del progetto CycloneDX .NET library.
Per maggiori dettagli su quali informazioni vengono perse, fare riferimento alla pagina del progetto 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.
Segnalazione dei componenti con modifiche alle versioni:
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: per eseguire un merge gerarchico, tutti i BOM devono avere l'oggetto del BOM descritto nell'elemento metadata component.
Merge di due BOM in formato XML:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-file sbom_all.xml
Merge di due BOM e invio dell'output tramite pipe ad altri strumenti:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-format json | grep "something"
Firma un BOM o un file
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)
Valida il BOM e restituisce un codice di uscita diverso da zero (utile per "interrompere" automaticamente una build, ecc)
cyclonedx-cli validate --input-file sbom.xml --fail-on-errors
Verifica le firme per BOM e file
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)
Lo strumento CLI CycloneDX può essere eseguito anche usando docker docker run cyclonedx/cyclonedx-cli.
Per Linux e MacOS, la CLI può essere installata tramite il CycloneDX Homebrew tap:
brew install cyclonedx/cyclonedx/cyclonedx-cli
Build supportate ufficialmente sono disponibili per queste piattaforme:
Build supportate dalla community sono disponibili per queste piattaforme:
Sono richieste le dipendenze di runtime .NET Core.
Per Windows queste dovrebbero essere preinstallate.
Per Ubuntu queste sono libc6 libgcc1 libgssapi-krb5-2 libicu66 libssl1.1 libstdc++6 zlib1g.
gron trasforma il JSON in assegnazioni distinte per rendere più facile cercare con grep quello che vuoi e vedere il 'percorso' assoluto.
Per comodità, gron è incluso nell'immagine Docker della CLI CycloneDX.
Esempio di utilizzo che elenca tutti i nomi e le versioni dei componenti
$ 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";
Oppure lo stesso usando un BOM in 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";
Per maggiori dettagli sull'uso di gron, fare riferimento alla pagina del progetto gron.
Per maggiori dettagli sull'uso di grep, fare riferimento alla pagina man di grep.
Il permesso di modificare e ridistribuire è concesso secondo i termini della licenza Apache 2.0. Vedere il file LICENSE per la licenza completa.
Le pull request sono benvenute. Ma prima leggi le linee guida per i contributi di CycloneDX.
Per compilare e testare la soluzione localmente dovresti avere .NET 8 installato. Comandi standard come dotnet build e dotnet test funzionano.
In generale ci si aspetta che le pull request includano test pertinenti.
I test vengono eseguiti automaticamente su Windows, MacOS e Linux per ogni pull request.
Gli avvisi di compilazione interromperanno la build.
Facci sapere se hai difficoltà a eseguire il debug di un test che fallisce su una piattaforma a cui non hai accesso.