Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/CycloneDX/cyclonedx-cli

CycloneDX CLI tool for SBOM analysis, merging, diffs and format conversions.
https://github.com/CycloneDX/cyclonedx-cli

bill-of-materials bom cyclonedx hacktoberfest mbom obom owasp package-url purl saasbom sbom sbom-generator software-bill-of-materials spdx vex

Last synced: about 1 month ago
JSON representation

CycloneDX CLI tool for SBOM analysis, merging, diffs and format conversions.

Host: GitHub
URL: https://github.com/CycloneDX/cyclonedx-cli
Owner: CycloneDX
License: apache-2.0
Created: 2020-10-22T11:25:26.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2024-09-17T11:19:21.000Z (3 months ago)
Last Synced: 2024-09-18T01:56:25.453Z (3 months ago)
Topics: bill-of-materials, bom, cyclonedx, hacktoberfest, mbom, obom, owasp, package-url, purl, saasbom, sbom, sbom-generator, software-bill-of-materials, spdx, vex
Language: C#
Homepage: https://cyclonedx.org/
Size: 632 KB
Stars: 297
Watchers: 16
Forks: 60
Open Issues: 107
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-sbom - CycloneDX CLI tool

README

[![Docker Image](https://img.shields.io/badge/docker-image-brightgreen?style=flat&logo=docker)](https://hub.docker.com/r/cyclonedx/cyclonedx-cli)
[![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](LICENSE)
[![Website](https://img.shields.io/badge/https://-cyclonedx.org-blue.svg)](https://cyclonedx.org/)
[![Slack Invite](https://img.shields.io/badge/Slack-Join-blue?logo=slack&labelColor=393939)](https://cyclonedx.org/slack/invite)
[![Group Discussion](https://img.shields.io/badge/discussion-groups.io-blue.svg)](https://groups.io/g/CycloneDX)
[![Twitter](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&label=Follow)](https://twitter.com/CycloneDX_Spec)

```
______ __ ____ _ __ ________ ____
/ ____/_ _______/ /___ ____ ___ / __ \ |/ / / ____/ / / _/
/ / / / / / ___/ / __ \/ __ \/ _ \/ / / / / / / / / / /
/ /___/ /_/ / /__/ / /_/ / / / / __/ /_/ / | / /___/ /____/ /
\____/\__, /\___/_/\____/_/ /_/\___/_____/_/|_| \____/_____/___/
/____/

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 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](https://github.com/CycloneDX/cyclonedx-cli/releases).

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 BOM filename.
--no-input Use this option to indicate that there is no input BOM.
--output-file Output BOM filename, will write to stdout if no value provided.
--input-format Specify input file format.
--output-format Specify output file format.
--base-path Base path for directory to process (defaults to current working directory if omitted).
--include Apache Ant style path and file patterns to specify what to include (defaults to all files, separate patterns with a space).
--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 BOM filename, will read from stdin if no value provided.
--input-format Specify input file format.
--output-format 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 BOM filename, will read from stdin if no value provided.
--output-file Output BOM filename, will write to stdout if no value provided.
--input-format Specify input file format.
--output-format Specify output file format.
--output-version 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.

[example.csv](example.csv)

### 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](https://github.com/CycloneDX/cyclonedx-dotnet-library).

## Diff Command

```
diff
Generate a BOM diff

Usage:
cyclonedx diff [options]

Arguments:
From BOM filename.
To BOM filename.

Options:
--from-format Specify from file format.
--to-format Specify to file format.
--output-format 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 Filename for generated private key file (defaults to "private.key")
--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 BOM filenames (separate filenames with a space).
--output-file Output BOM filename, will write to stdout if no value provided.
--input-format Specify input file format.
--output-format Specify output file format.
--hierarchical Perform a hierarchical merge.
--group Provide the group of software the merged BOM describes.
--name Provide the name of software the merged BOM describes (required for hierarchical merging).
--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 [options]

Arguments:
BOM filename

Options:
--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 [options]

Arguments:
Filename of the file the signature will be created for

Options:
--key-file Signing key filename (RSA private key in PEM format, defaults to "private.key")
--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 BOM filename, will read from stdin if no value provided.
--input-format Specify input file format.
--input-version Specify input file specification version (defaults to v1.4)
--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 [options]

Arguments:
BOM filename

Options:
--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 [options]

Arguments:
File the signature file is for

Options:
--key-file Public key filename (RSA public key in PEM format, defaults to "public.key")
--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](https://github.com/CycloneDX/homebrew-cyclonedx):

```shell
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](https://github.com/TomNomNom/gron).

For more details on grep usage refer to the [grep man page](https://www.man7.org/linux/man-pages/man1/grep.1.html).

## 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.

[License]: https://github.com/CycloneDX/cyclonedx-cli/blob/main/LICENSE

## Contributing

Pull requests are welcome. But please read the
[CycloneDX contributing guidelines](https://github.com/CycloneDX/.github/blob/master/CONTRIBUTING.md) 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.