Awesome
______ __ ____ _ __ ________ ____
/ ____/_ _______/ /___ ____ ___ / __ \ |/ / / ____/ / / _/
/ / / / / / ___/ / __ \/ __ \/ _ \/ / / / / / / / / / /
/ /___/ /_/ / /__/ / /_/ / / / / __/ /_/ / | / /___/ /____/ /
\____/\__, /\___/_/\____/_/ /_/\___/_____/_/|_| \____/_____/___/
/____/
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
The CycloneDX CLI tool currently supports BOM analysis, modification, diffing, merging, format conversion, signing and verification.
Conversion is supported between CycloneDX XML, JSON, Protobuf, CSV, and SPDX JSON v2.2.
Binaries can be downloaded from the releases page.
Note: The CycloneDX CLI tool is built for automation use cases. Any commands that have the --input-file option also support feeding input from stdin. Likewise, any commands that have the --output-file option support output to stdout. However, you will need to supply the input/output formats.
For example:
cat bom.json | cyclonedx-cli convert --input-format json --output-format xml > bom.xml
Commands
Add Command
Add File Subcommand
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).
Examples
Generating a source code BOM, excluding Git repository directory:
cyclonedx-cli add files --no-input --output-format json --exclude /.git/**
Adding build output files, from bin directory, to existing BOM:
cyclonedx-cli add files --input-file bom.json --output-format json --base-path bin
Analyze Command
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.
Examples
Reporting on components that are included multiple times with different versions:
cyclonedx-cli analyze --input-file sbom.xml --multiple-component-versions
Convert Command
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> Specify output BOM specification version. (ignored for CSV and SPDX formats)
Examples
Converting from XML to JSON format:
cyclonedx-cli convert --input-file sbom.xml --output-file sbom.json
Converting from XML to JSON format and piping output to additional tools:
cyclonedx-cli convert --input-file sbom.xml --output-format json | grep "somthing"
CSV Format
The CSV format is a limited representation of the list of components in a BOM.
The intention is to provide a simple way for users to produce and consume BOMs for simple use cases. Including simple data migration use cases.
The only required fields are the component name and version fields. Others
can be left blank or the columns omitted.
SPDX Format
Converting between SPDX and CycloneDX formats can result in the loss of some
information. The conversion functionality is provided by the
CycloneDX.Spdx.Interop library, which is part of the CycloneDX .NET library
project.
For more details on what information is lost refer to the CycloneDX .NET Library project page.
Diff Command
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.
Examples
Reporting on components with version changes:
cyclonedx-cli diff sbom-from.xml sbom-to.xml --component-versions
Keygen Command
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 Command
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> 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).
Note: To perform a hierarchical merge all BOMs need the subject of the BOM described in the metadata component element.
Examples
Merge two XML formatted BOMs:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-file sbom_all.xml
Merging two BOMs and piping output to additional tools:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-format json | grep "something"
Sign Command
Sign a BOM or file
Sign Bom Subcommand
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")
Sign File Subcommand
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 Command
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> Specify input file specification version (defaults to v1.6)
--fail-on-errors Fail on validation errors (return a non-zero exit code)
Examples
Validate BOM and return non-zero exit code (handy for automatically "breaking" a build, etc)
cyclonedx-cli validate --input-file sbom.xml --fail-on-errors
Verify Command
Verify signatures for BOMs and files
Verify All Subcommand
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")
Verify File Subcommand
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)
Docker Image
The CycloneDX CLI tool can also be run using docker docker run cyclonedx/cyclonedx-cli.
Homebrew
For Linux and MacOS, the CLI can be installed via the CycloneDX Homebrew tap:
brew install cyclonedx/cyclonedx/cyclonedx-cli
Supported Platforms
Officially supported builds are available for these platforms:
- Windows x64 (win-x64)
- Linux x64 (linux-x64)
- Linux musl x64 (linux-musl-x64, includes Alpine Linux)
- MacOS x64 (osx-x64)
Community supported builds are available for these platforms:
- Windows x86 (win-x86)
- Windows ARM (win-arm)
- Windows ARM x64 (win-arm64)
- Linux ARM (linux-arm)
- Linux ARM x64 (linux-arm64)
- MacOS ARM x64 (osx-arm64)
.NET Core runtime dependencies are required.
For Windows these should be preinstalled.
For Ubuntu these are libc6 libgcc1 libgssapi-krb5-2 libicu66 libssl1.1 libstdc++6 zlib1g.
Using gron for adhoc searching and analysis
gron transforms JSON into discrete assignments to make it easier to grep for what you want and see the absolute 'path' to it.
For convenience, gron is included in the CycloneDX CLI Docker image.
Example usage that lists all component names and versions
$ 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";
Or the same using an XML format BOM
$ 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";
For more details on gron usage refer to the gron project page.
For more details on grep usage refer to the grep man page.
License
Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. See the LICENSE file for the full license.
Contributing
Pull requests are welcome. But please read the CycloneDX contributing guidelines first.
To build and test the solution locally you should have .NET 6
installed. Standard commands like dotnet build and dotnet test work.
It is generally expected that pull requests will include relevant tests. Tests are automatically run on Windows, MacOS and Linux for every pull request. Build warnings will break the build.
Please let us know if you are having trouble debugging a test that is failing for a platform that you don't have access to.