merge

Merges two or more CycloneDX input files into one. Inputs can either be specified directly as positional arguments on the command-line or using the --from-folder option. Files specified as arguments are merged in the order they are given, files in the folder are merged in alphabetical order (see note below).

If both positional arguments and the --from-folder option are used, then the position arguments are merged first, followed by the files in the folder. The command will not merge the same file twice, if it is specified on the command-line and also part of the folder.

When using the --from-folder option, the program looks for files matching either of the recommended CycloneDX naming schemes: bom.json or *.cdx.json.

usage: cdx-ev merge [-h] [--from-folder <from-folder>] [--output <file>]
                    [<input> ...]

Positional Arguments

<input>

Paths to SBOM files to merge. You must specify at least two paths.

Named Arguments

--from-folder

Path to a folder with sboms to be merged

--output, -o

The path to where the output should be written. If this is a file, output is written there. If it’s a directory, output is written to a file with an auto-generated name inside that directory. If it’s not specified, output is written to stdout.

Details

Input files in the folder provided to the --from-folder option are sorted by name in a platform-specific way. In other words, they are merged in the same order they appear in your operating system’s file browser (e.g., Windows Explorer) when sorted by name.

The process runs iteratively, merging two SBOMs in each iteration. In the first round, the second submitted SBOM is merged into the first. In the second round the third would be merged into the result of the first round and so on.

In mathematical terms: \(output = (((input_1 * input_2) * input_3) * input_4 ...)\)

A few notes on the merge algorithm:

  • The metadata field is always retained from the first input and never changed through a merge with the exception of the timestamp.

  • Components are merged into the result in the order they first appear in the inputs. If any subsequent input specifies the same component (sameness in this case being defined as having identical identifying attributes such as name, version, purl, etc.), the later instance of the component will be dropped with a warning. This command cannot be used to merge information inside components.

  • The resulting dependency graph will reflect all dependencies from all inputs. Dependencies from later inputs are always added to the result, even if the component is dropped as a duplicate as described above.

  • Uniqueness of bom-refs will be ensured.

  • If the inputs contain VEX information in the form of a vulnerabilities field, this will be merged as well. For details see section on the merge-vex command.