`cargo-cyclonedx`

The CycloneDX plugin for cargo creates a custom cargo subcommand that generates a Software Bill-of-Materials (SBOM) file that describes the cargo project.

CycloneDX is a lightweight SBOM specification that is easily created, human and machine readable, and simple to parse.

Usage

Installing

cargo install cargo-cyclonedx

Executing from `cargo`

cargo cyclonedx

This produces a bom.xml file adjacent to every Cargo.toml file that exists in the workspace.

Command-line options

--format (xml or json): Defaults to XML output
--all: Include the transitive dependencies for the project rather than only the top-level dependencies
--manifest-path: where to find the Cargo.toml file if other than the default cargo location of the current directory
--output-cdx: Include .cdx in the filename as described in the recognized file patterns
--output-pattern (bom or package)
- bom: Outputs a prefix of bom for the filename
- package: Outputs a prefix using the Cargo.toml package name for the filename
--output-prefix: Outputs a custom prefix for the filename

Notes:

--output-cdx, --output-pattern, and --output-prefix are a group of options. Passing any of them as arguments will override any output_options configurations in Cargo.toml files.
--output-pattern and --output-prefix cannot be passed as arguments at the same time.

Manifest Configuration

There are several locations you can set configuration options for convenience. If your project uses a Cargo workspace, you can set configuration as toml values under [workspace.metadata.cyclonedx] in your workspace manifest. These configuration values will propagate to your workspace packages unless you override the values either by specifying toml values under [package.metadata.cyclonedx] in your package manifest or with command-line options.

Option	Values (*default)	Description
`included_dependencies`	`top-level`*, `all`	Either only direct (`top-level`) or including transitive (`all`) dependencies
`format`	`xml`*, `json`	Output format for the SBOM
`output_options`	`<defined below>`	A collection of options for file output

Output Options

Option	Values (*default)	Description
`cdx`	`true` / `false`*	Determines if `.cdx` is included in the filename as described in the recognized file patterns
`pattern`	`bom`*, `package`	`bom` outputs `bom`, while `package` outputs the `Cargo.toml` package name as the prefix
`prefix`	`<filename prefix>`	Outputs a custom value for the prefix

Notes:

output_options values are merged as a single configuration, so a package-level configuration will override the whole workspace-level configuration.
pattern and prefix cannot be configured at the same time.

Precedence

Configuration options will be merged and applied in the following order from lowest to highest precedence.

Defaults
Workspace manifest metadata
Package manifest metadata
Command-line options

Example Workspace Configuration

[workspace.metadata.cyclonedx]
included_dependencies = "top-level"
format = "xml"
output_options = { cdx = false, prefix = "cyclonedx" }

Example Package Configuration

You can also specify your configuration in using package metadata in your package manifest.

[package.metadata.cyclonedx]
included_dependencies = "all"
format = "json"
output_options = { cdx = true, pattern = "package" }

Copyright & 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.

cargo-cyclonedx 0.3.4

cargo-cyclonedx