# How do I use CVE Binary Tool to scan a SBOM?

The cve-bin-tool can be used to scan a software bill of materials (SBOM) file to identify the vulnerabilities within the packages identified in the file.

## SBOM support

The cve-bin-tool supports SBOMs in the following formats

| SBOM Type | Version   | Format         | 
| --------- | --------- | ---------------| 
| SPDX      | 2.2       | TagValue       |
| SPDX      | 2.2       | RDF            |
| SPDX      | 2.2       | JSON           |
| SPDX      | 2.2       | YAML           |
| SPDX      | 2.2       | XML            |
| CycloneDX | 1.3-1.5   | XML            |
| CycloneDX | 1.3-1.5   | JSON           |
| SWID      | See Note  | XML            |

Details of the formats for each of the supported SBOM formats are available for 
 [SPDX](https://spdx.dev/) , [CycloneDX](https://cyclonedx.org/) and [SWID](https://csrc.nist.gov/Projects/Software-Identification-SWID/guidelines)

For SPDX SBOM files, it is assumed that the name of a Package precedes the version information for the package. Only modules with a package name and associated version information shall be processed.

The SWID format follows the [ISO/IEC 19770-2:2015](https://www.iso.org/standard/65666.html) standard.

## Usage

To scan a SBOM, run the tool as shown (other parameters can be specified as required e.g. format) 

```
$ cve-bin-tool --sbom <sbom type> --sbom-file <sbom filename>
```

To determine the format of the SBOM file, the following filename conventions are followed

| SBOM      | Format    | Filename extension   |
| --------- | --------- | ---------------| 
| SPDX      | TagValue  | .spdx          |
| SPDX      | RDF       | .spdx.rdf      | 
| SPDX      | JSON      | .spdx.json     |
| SPDX      | YAML      | .spdx.yaml     |
| SPDX      | YAML      | .spdx.yml      |
| SPDX      | XML       | .spdx.xml      |
| CycloneDX | XML       | .xml           |
| CycloneDX | JSON      | .json          |
| SWID      | XML       | .xml           |

## Examples

Scan a SPDX SBOM in TagValue format with the name sbom.spdx

```
cve-bin-tool --sbom spdx --sbom-file sbom.spdx
```

If the `--sbom` option is omitted, the scan defaults to a SPDX SBOM in TagValue format. The above and below examples are equivalent.

```
cve-bin-tool --sbom-file sbom.spdx
```

Scan a CycloneDX SBOM in JSON format with the name sbom.json

```
cve-bin-tool --sbom cyclonedx --sbom-file sbom.json
```

Scan a SWID SBOM in XML format with the name sbom.xml

```
cve-bin-tool --sbom swid --sbom-file sbom.xml
```

## Help

In order for vulnerabilities to be identified, the package names and version data must match with the information which is captured within the NVD database. If no vulnerabilities are being reported, adding `--log debug` to the command line will report the packages and versions of the modules extracted from the SBOM file. 

Note that package names should not include spaces and that version numbers should only contain numeric characters (and '.').

## Limitations

As some package/version number pairs cannot be resolved to a unique vendor, the reported vulnerabilities may be incomplete or inaccurate.

## Interoperability

This feature is known to work with SBOM files generated by [tern](https://github.com/tern-tools/tern).