validate

Validates an SBOM against a JSON schema.

usage: cdx-ev validate [-h]
                       [--schema-type {default,strict,custom} | --schema-path <schema-path>]
                       [--filename-pattern FILENAME_PATTERN | --no-filename-validation]
                       [--report-format {warnings-ng,gitlab-code-quality}]
                       [--report-path <file>]
                       <input>

Positional Arguments

<input>: Path to the SBOM file to validate.

Named Arguments

--schema-type

Possible choices: default, strict, custom

Use a built-in schema for validation.

--schema-path

Path to the JSON schema file to validate against.

--filename-pattern

Regex for validation of filename. If not specified, a default regex depending on the schema is applied. To disable filename validation altogether, use --no-filename-validation.

Default: ''

--no-filename-validation

Disable filename validation

Default: False

--report-format

Possible choices: warnings-ng, gitlab-code-quality

Write results to a file in the specified format. Must be combined with the --report-path option.

--report-path

The path to where the report file should be written. Must be combined with the --report-format option.

Schema selection

This tool can validate SBOMs against any user-provided JSON schema but for convenience, two schema types are built in:

The default schema type validates against the stock CycloneDX schema.
The strict schema type refers to the strict variants of the stock CycloneDX schema which were discontinued after version 1.3.
The custom schema type uses a more restrictive schema which accepts a subset of CycloneDX. Additional requirements incorporated into the schema mostly originate from the NTIA.

You can select the schema with the --schema-type or --schema-path options:

cdx-ev validate bom.json [--schema-type default]           # stock CycloneDX schema
cdx-ev validate bom.json --schema-type custom              # built-in custom schema
cdx-ev validate bom.json --schema-path <json_schema.json>  # your own schema

For all built-in schemas, the tool determines the CycloneDX version from the input SBOM. The following versions are currently supported:

Type	Supported CycloneDX versions
`default`	1.2 to 1.6
`strict`	1.2 to 1.3
`custom`	1.3 to 1.6

Validation of filename

The tool, by default, also validates the filename of the SBOM. Which filenames are accepted depends on several command-line options:

--no-filename-validation completely disables validation.
Use --filename-pattern to provide a custom regex.
- The filename must be a full match, regex anchors (^ and $) are not required.
- Regex patterns often include special characters. Pay attention to escaping rules for your shell to ensure proper results.
In all other cases, the acceptable filenames depend on the selected schema:
- When using the stock CycloneDX schema (--schema-type default or no option at all) or when using your own schema (--schema-path option), the validator accepts the two patterns recommended by the CycloneDX specification: bom.json or *.cdx.json.
- When validating against the built-in custom schema (--schema-type custom), filenames must match one of these patterns: bom.json or <name>_<version>_<hash>|<timestamp>|<hash>_<timestamp>.cdx.json. See below for explanations of the placeholders.

<name> and <version> correspond to the respective fields in metadata.component in the SBOM.

<timestamp> corresponds to metadata.timestamp and <hash> means any value in metadata.component.hashes[].content.

Either <timestamp> or <hash> must be present. If both are specified, <hash> must come first.

Output

By default, the command writes human-readable validation results to stdout only. For integration into CI/CD several machine-readable report formats are supported as well. To have a report written to a file, select the format using the --report-format option and an output path using the --report-path option.

These formats are currently supported:

Examples:

# Write human-readable messages to stdout and a report in warnings-ng format to report.json
cdx-ev validate bom.json --report-format warnings-ng --report-path report.json

# Write only a report in GitLab Code Quality format to cq.json
cdx-ev --quiet validate bom.json --report-format gitlab-code-quality --report-path cq.json