cdx-enrich

cdx-enrich is a .NET tool designed to enrich a CycloneDX Bill-of-Materials (BOM) with predefined data. It processes a CycloneDX SBOM and applies transformations declared in a configuration file, allowing users to enhance SBOMs generated by tools that might not capture all necessary details.

Features

• Enrich your SBOM with data your generator couldn't find.
• Transform CycloneDX SBOM files based on a configuration file.
• Designed as a pipeline step in between SBOM-generation and upload to Dependency-Track.

Installation

cdx-enrich requires .NET 8 to be installed.

To install cdx-enrich, use the .NET CLI:

dotnet tool install -g cdx-enrich

Usage

The cdx-enrich tool provides several command-line options to specify input files, output files, and configuration files.

Command-Line Options

Arguments:
  <input file>  The path to a CycloneDX SBOM to enrich.

Options:
  -if, --input-format <Auto|JSON|XML>   Specify the input file format, if necessary. [default: Auto]
  -o, --output-file <output-file>       Path to save the enriched SBOM. Leave blank to overwrite the input file.
  -of, --output-format <Auto|JSON|XML>  Specify the output file format. [default: Auto]
  -c, --config-files <config-files>     Path to one or more configuration files.
  --version                             Show version information
  -?, -h, --help                        Show help and usage information

Examples

Example 1: Basic Usage

cdx-enrich sbom.json -c config.yaml

This command takes an input SBOM (sbom.json), applies transformations defined in config.yaml, and writes the enriched SBOM back to sbom.json.

Example 2: Specifying Formats & Seperate output file

cdx-enrich sbom.cdx -if XML -o enriched_sbom.cdx -of JSON -c config.yaml

This command explicitly specifies the input and output formats as XML.

Example 3: Using Multiple Configuration Files

cdx-enrich input.bom.json -o output.bom.json -c project.yaml organization.yaml

This command takes an input SBOM (input.bom.json), applies transformations defined in both project.yaml and organization.yaml, and writes the enriched SBOM to output.bom.json.

Each configuration file can contain different sets of transformations, and they are applied in the order specified.

Configuration File

The configuration file defines the transformations to be applied to the SBOM. Currently, two actions are supported: ReplaceLicensesByURL and ReplaceLicenseByBomRef.

Example Configuration

ReplaceLicensesByURL:
- URL: "https://github.com/dotnet/corefx/blob/master/LICENSE.TXT"
  Id: "MIT"
- URL: "http://go.microsoft.com/fwlink/?LinkID=262998"
  Name: "MICROSOFT SOFTWARE LICENSE TERMS - MICROSOFT .NET LIBRARY"

ReplaceLicenseByBomRef:
- Ref: "pkg:nuget/[email protected]"
  Id: "MIT"  

Actions

ReplaceLicensesByURL

This action replaces licenses in components that match a specific URL. The replacement can specify either an SPDX License ID or a name for the license, but not both.

• URL: The URL of the license to be replaced.
• One of:
  • Id: The new SPDX License ID.
  • Name: The new license name.

ReplaceLicenseByBomRef

This action replaces licenses in a specific component identified by its BOM reference. The replacement can specify either an SPDX License ID or a name for the license, but not both.

• Ref: The BOM reference of the component whose license is to be replaced.
• One of:
  • Id: The new SPDX License ID.
  • Name: The new license name.

Issues and Contributions

If you need additional actions or encounter issues, please open an issue on the GitHub repository.

The tool is written, so that new actions can be easily added. Ensure you follow the coding style, the functional structure and include tests where applicable. Use an existing action as a template.

License

cdx-enrich is licensed under the Apache 2.0 License. See the LICENSE file for more details.