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.

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

cdx-enrich requires .NET 8 to be installed.

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

dotnet tool install -g cdx-enrich

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

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

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.

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.

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.

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

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/Json.More.Net@1.9.0"
  Id: "MIT"

ReplaceLicenseByClearlyDefined:
- Ref: "pkg:nuget/System.Buffers@4.4.0"

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.

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.

This action replaces licenses in components by automatically retrieving license data from the ClearlyDefined service. Components are identified by their Package URL (PURL).

• Ref: The BOM reference of the component whose license is to be replaced.

This action supports the following package types:

• Crate (Provider: Crates.io)
• Gem (Provider: RubyGems)
• Maven (Provider: Maven Central)
• npm (Provider: npmjs)
• NuGet (Provider: NuGet)
• Pod (Provider: Cocoapods)
• PyPI (Provider: PyPI)

The following package types are supported by ClearlyDefined, but are currently not implemented in CdxEnrich:

• Composer (Provider: Packagist)
• Conda (Provider: CondaForge)
• Condasrc (Provider: CondaForge)
• Deb (Provider: Debian)
• Debsrc (Provider: Debian)
• Git (Provider: GitHub)
• Go (Provider: GitHub)
• SourceArchive (Provider: GitHub)

The action 'ReplaceLicenseByClearlyDefined' uses a rule-based system to convert license data from ClearlyDefined into a CycloneDX-compatible format. The rules are prioritized, and only one rule is applied per case to avoid inconsistencies.

License resolution follows a clear priority sequence. Only one rule is applied per case. If multiple rules are applicable, none is applied to avoid inconsistent results.

The system defines three main rule types:

1. LicenseIdResolveRule

• Handles simple license identifiers such as MIT, Apache-2.0

• Conditions:

  • Must not be a license placeholder (NONE, NOASSERTION, OTHER)
  • Must not be an SPDX expression
  • Must not be a license reference (e.g., starts with LicenseRef-)

• Returns the license ID as a direct CycloneDX ID

2. SpdxExpressionResolveRule

• Handles SPDX expressions and license references:

  • Expressions include operators like OR, AND, WITH
  • References begin with LicenseRef-

• Conditions:

  • Must not be a license placeholder

• Returns the full SPDX expression as-is

3. PlaceholderLicenseResolveRule

• Handles license placeholder:

  • NONE means no license declared
  • NOASSERTION means the license could not be determined
  • OTHER represents a non-standard license

• Tries the following:

  1. Checks for discovered expressions from ClearlyDefined
  2. Combines them using OR if multiple are found
  3. Validates that the result is not one of the license placeholders

• Only if all conditions are met, the combined expression is returned

1. All applicable rules are identified
2. If no rule is applicable, the original license remains unchanged
3. If more than one rule is applicable, an error is logged and the license remains unchanged
4. If exactly one rule is applicable, it is applied and its result returned

• A simple license MIT uses LicenseIdResolveRule
• A compound expression MIT OR Apache-2.0 uses SpdxExpressionResolveRule
• A license placeholder NOASSERTION with alternative expressions uses PlaceholderLicenseResolveRule, if conditions are met; otherwise, the license remains unchanged

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.

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