Intel CVE Binary Tool

# CVE Binary Tool quick start / README

[![Build Status](https://github.com/intel/cve-bin-tool/actions/workflows/cve_bin_tool_action.yml/badge.svg?branch=main&event=push)](https://github.com/intel/cve-bin-tool/actions)
[![codecov](https://codecov.io/gh/intel/cve-bin-tool/branch/main/graph/badge.svg)](https://codecov.io/gh/intel/cve-bin-tool)
[![Gitter](https://badges.gitter.im/cve-bin-tool/community.svg)](https://gitter.im/cve-bin-tool/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
[![On ReadTheDocs](https://readthedocs.org/projects/cve-bin-tool/badge/?version=latest&style=flat)](https://cve-bin-tool.readthedocs.io/en/latest/)
[![On PyPI](https://img.shields.io/pypi/v/cve-bin-tool)](https://pypi.org/project/cve-bin-tool/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5380/badge)](https://bestpractices.coreinfrastructure.org/projects/5380)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/intel/cve-bin-tool/badge)](https://securityscorecards.dev/viewer/?uri=github.com/intel/cve-bin-tool)

The CVE Binary Tool is a free, open source tool to help you find known vulnerabilities in software, using data from the [National Vulnerability Database](https://nvd.nist.gov/) (NVD) list of [Common Vulnerabilities and Exposures](<https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures#:~:text=Common%20Vulnerabilities%20and%20Exposures%20(CVE)%20is%20a%20dictionary%20of%20common,publicly%20known%20information%20security%20vulnerabilities.>) (CVEs) as well as known vulnerability data from [Redhat](https://access.redhat.com/hydra/rest/securitydata), [Open Source Vulnerability Database (OSV)](https://osv.dev/), [Gitlab Advisory Database (GAD)](https://advisories.gitlab.com/), and [Curl](https://curl.se/docs/vuln.json).

CVE Binary Tool uses the NVD API but is not endorsed or certified by the NVD.

The tool has two main modes of operation:

1. A binary scanner which helps you determine which packages may have been included as part of a piece of software. There are <!-- NUMBER OF CHECKERS START-->394<!--NUMBER OF CHECKERS END--> checkers.  Our initial focus was on common, vulnerable open source components such as openssl, libpng, libxml2 and expat.

2. Tools for scanning known component lists in various formats, including .csv, several linux distribution package lists, language specific package scanners and several Software Bill of Materials (SBOM) formats.  

It is intended to be used as part of your continuous integration system to enable regular vulnerability scanning and give you early warning of known issues in your supply chain.  It can also be used to auto-detect components and create SBOMs.

What CVE Binary Tool does when it runs:

![Diagram of cve-bin-tool's workflow, described in text with more detail below.](https://raw.githubusercontent.com/intel/cve-bin-tool/main/doc/images/cve-bin-tool-workflow-800px.png)

1. Download CVE Data (from NVD, Redhat, OSV, Gitlab, and Curl).
   - This happens once per day by default, not every time a scan is run.
   - On first run, downloading all data can take some time.
2. Create/read a component list. There are two modes of operation:
   1. Creates a component list (including versions) using a combination of binary checkers and language component lists (such as python's requirements.txt).
   2. Read SBOM (use an existing component list in a standardized Software Bill of Materials format.)
3. Create CVE List
   - This looks up all components found or read from an existing bill of materials and reports back any known issues associated with them
4. Include triage/additional data
   - There are several options for adding triage/notes, information from previous reports to track vulnerability change over time, or known fix data
5. Generate report in one or more formats (console, json, csv, html, pdf)

For more details, see our [documentation](https://cve-bin-tool.readthedocs.io/en/latest/) or this [quickstart guide](https://cve-bin-tool.readthedocs.io/en/latest/README.html)

- [CVE Binary Tool quick start / README](#cve-binary-tool-quick-start--readme)
  - [Installing CVE Binary Tool](#installing-cve-binary-tool)
  - [Most popular usage options](#most-popular-usage-options)
    - [Finding known vulnerabilities using the binary scanner](#finding-known-vulnerabilities-using-the-binary-scanner)
    - [Scanning an SBOM file for known vulnerabilities](#scanning-an-sbom-file-for-known-vulnerabilities)
    - [Generating an SBOM](#generating-an-sbom)
    - [Generating a VEX](#generating-a-vex)
    - [Triaging vulnerabilities](#triaging-vulnerabilities)
    - [Using the tool offline](#using-the-tool-offline)
    - [Using CVE Binary Tool in GitHub Actions](#using-cve-binary-tool-in-github-actions)
  - [Output Options](#output-options)
  - [Configuration](#configuration)
  - [Auto-detection of components](#auto-detection-of-components)
    - [Binary checker list](#binary-checker-list)
    - [Language Specific checkers](#language-specific-checkers)
    - [Supported Archive Formats](#supported-archive-formats)
  - [Additional Requirements](#additional-requirements)
  - [Limitations](#limitations)
  - [Feedback \& Contributions](#feedback--contributions)
  - [Security Issues](#security-issues)
  - [Full option list](#full-option-list)

## Installing CVE Binary Tool

CVE Binary Tool can be installed using pip:

```console
pip install cve-bin-tool
```

If you want to try the latest code from
[the cve-bin-tool github](https://github.com/intel/cve-bin-tool) or do development, you can also `pip install --user -e .` to install a local copy from a directory.  The [Contributor Documentation](https://github.com/intel/cve-bin-tool/blob/main/CONTRIBUTING.md) covers how to set up for local development in more detail.

Pip will install the python requirements for you, but for some types of extraction we use system libraries. If you have difficulties extracting files, you may want to look at our [additional Requirements lists for Linux and Windows](#additional-requirements).

On first usage (and by default, once per day) The tool will download vulnerability data from [a set of known vulnerability data sources](https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#data-sources).  Due to reliability issues with NVD, as of release 3.3 we will be using our own NVD mirror at [https://cveb.in/](https://cveb.in/) by default rather than contacting NVD directly.  If you wish to get data directly from the NVD servers you must [provide your own NVD_API_KEY](https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#--nvd-api-key-nvd_api_key) to use their API.

If you are using a release prior to 3.3 that does not use our mirror, please use an NVD_API_KEY as described above.

## Most popular usage options

### Finding known vulnerabilities using the binary scanner

To run the binary scanner on a directory or file:

```bash
cve-bin-tool <directory/file>
```

> **Note**: That this option will also use any [language specific checkers](#language-specific-checkers) to find known vulnerabilities in components.

By default, the tool assumes you are attempting to scan a whole directory, but if you provide it with a single .csv or .json file that lists dependencies it will treat it as a bill of materials.  You can also specify bill of materials files directly using [the `--input-file` option](https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md#-i-input_file---input-file-input_file) or scan SBOMs with the instructions below.

### Scanning an SBOM file for known vulnerabilities

To scan a software bill of materials file (SBOM):

```bash
cve-bin-tool --sbom <sbom_filetype> --sbom-file <sbom_filename>
```

Valid SBOM types are [SPDX](https://spdx.dev/specifications/),
[CycloneDX](https://cyclonedx.org/specification/overview/), and [SWID](https://csrc.nist.gov/projects/software-identification-swid/guidelines).
Scanning of product names within an SBOM file is case insensitive.

The [SBOM scanning how-to guide](https://github.com/intel/cve-bin-tool/blob/main/doc/how_to_guides/sbom.md) provides additional SBOM scanning examples.

### Generating an SBOM

As well as scanning SBOMs, CVE Binary Tool can be used to generate an SBOM from a scan as follows:

```bash
cve-bin-tool  --sbom-type <sbom_type> --sbom-format <sbom-format> --sbom-output <sbom_filename> <other scan options as required>
```

Valid SBOM types are [SPDX](https://spdx.dev/specifications/) and [CycloneDX](https://cyclonedx.org/specification/overview/).

The generated SBOM will include product name, version and supplier (where available). License information is not provided.

The [SBOM generation how-to guide](https://github.com/intel/cve-bin-tool/blob/main/doc/how_to_guides/sbom_generation.md) provides additional SBOM generation examples.

### Generating a VEX

As well as scanning VEX, CVE Binary Tool can be used to generate an VEX from a scan as follows:

```bash
cve-bin-tool  --vex-type <vex_type> --vex-output <vex_filename> <other scan options as required>
```

Valid VEX types are [CSAF](https://oasis-open.github.io/csaf-documentation/), [CycloneDX](https://cyclonedx.org/capabilities/vex/) and [OpenVEX](https://edu.chainguard.dev/open-source/sbom/what-is-openvex/).


The [VEX generation how-to guide](https://github.com/intel/cve-bin-tool/blob/main/doc/how_to_guides/vex_generation.md) provides additional VEX generation examples.

### Triaging vulnerabilities

The `--vex-file` option can be used to add extra triage data like remarks, comments etc. while scanning a directory so that output will reflect this triage data and you can save time of re-triaging (Usage: `cve-bin-tool --vex-file test.json /path/to/scan`).
The supported format is the [CycloneDX](https://cyclonedx.org/capabilities/vex/),[CSAF](https://oasis-open.github.io/csaf-documentation/) and [OpenVEX](https://edu.chainguard.dev/open-source/sbom/what-is-openvex/) VEX format which can be generated using the `--vex-output` option.

Typical usage:

1. Generate triage file using `cve-bin-tool /path/to/scan --vex-output triage.json`
2. Edit triage.json with your favourite text editor to provide triage information on the vulnerabilities listed.
3. Use this triage file for future scans as follows: `cve-bin-tool /path/to/scan --vex-file triage.json`

For better usage guide refer this [link](https://cve-bin-tool.readthedocs.io/en/latest/triaging_process.html) .

It should be possible to share triage data across different runs of cve-bin-tool or with other tools that support the CycloneDX VEX, OpenVEX and CSAF format.  This would be particularly useful for teams that scan related products or containers, teams that need to use multiple tools for compliance reasons, companies that have a central security policy group that provides guidance on vulnerability triage, and more.

### Using the tool offline

Specifying the `--offline` option when running a scan ensures that cve-bin-tool doesn't attempt to download the latest database files or to check for a newer version of the tool.

Note that you will need to obtain a copy of the vulnerability data before the tool can run in offline mode. [The offline how-to guide contains more information on how to set up your database.](https://github.com/intel/cve-bin-tool/blob/main/doc/how_to_guides/offline.md)

### Using CVE Binary Tool in GitHub Actions

If you want to integrate cve-bin-tool as a part of your github action pipeline, you can use cve-bin-tool's official GitHub Action. Find more details [here](https://github.com/intel/cve-bin-tool-action/#cve-binary-tool-github-action). The GitHub Action provide reports on the security tab, which is available to open source projects as well as GitHub customers who have paid for that access.  

We also provide an example [GitHub action](https://github.com/intel/cve-bin-tool/blob/main/doc/how_to_guides/cve_scanner_gh_action.yml) if you wish to use the tool directly.  This may be a good choice for teams who want to store reports in an evidence locker or those who don't have access to the GitHub Security tab.

## Output Options

The CVE Binary Tool provides console-based output by default. If you wish to provide another format, you can specify this and a filename on the command line using `--format`. The valid formats are CSV, JSON, JSON2, console, HTML and PDF. The output filename can be specified using the `--output-file` flag.

You can also specify multiple output formats by using comma (',') as separator:

```bash
cve-bin-tool file -f csv,json,json2,html -o report
```

Note: You must not use spaces between the commas (',') and the output formats.

The reported vulnerabilities can additionally be reported in the
Vulnerability Exploitability  eXchange (VEX) format by specifying `--vex-output` with type defined using `--vex-type` command line option.
The generated VEX file can then be used as a `--vex-file` to support
a triage process.

If you wish to use PDF support, you will need to install the `reportlab`
library separately.

If you intend to use PDF support when you install cve-bin-tool you can specify it and report lab will be installed as part of the cve-bin-tool install:

```console
pip install cve-bin-tool[PDF]
```

If you've already installed cve-bin-tool you can add reportlab after the fact
using pip:

```console
pip install --upgrade reportlab
```

Note that reportlab was taken out of the default cve-bin-tool install because
it has a known CVE associated with it
([CVE-2020-28463](https://nvd.nist.gov/vuln/detail/CVE-2020-28463)). The
cve-bin-tool code uses the recommended mitigations to limit which resources
added to PDFs, as well as additional input validation. This is a bit of a
strange CVE because it describes core functionality of PDFs: external items,
such as images, can be embedded in them, and thus anyone viewing a PDF could
load an external image (similar to how viewing a web page can trigger external
loads). There's no inherent "fix" for that, only mitigations where users of
the library must ensure only expected items are added to PDFs at the time of
generation.

Since users may not want to have software installed with an open, unfixable CVE
associated with it, we've opted to make PDF support only available to users who
have installed the library themselves. Once the library is installed, the PDF
report option will function.

## Configuration

You can use `--config` option to provide configuration file for the tool. You can still override options specified in config file with command line arguments. See our sample config files in the
[test/config](https://github.com/intel/cve-bin-tool/blob/main/test/config/)

## Auto-detection of components

CVE Binary tool attempts to do auto-detection of components using binary checkers, supported language component lists, and file extraction methods.  The supported tools for auto-detection are listed below.

### Binary checker list

The following checkers are available for finding components in binary files:

<!--CHECKERS TABLE BEGIN-->
|   |  |  | Available checkers |  |  |  |
|--------------- |---------------- |------------------ |----------- |------------- |------------- |----------------- |
| accountsservice |acpid |apache_http_server |apcupsd |apparmor |apr |asn1c |
| assimp |asterisk |atftp |avahi |axel |bash |bind |
| binutils |bird |bison |bluez |boa |boinc |botan |
| bro |bubblewrap |busybox |bwm_ng |bzip2 |c_ares |capnproto |
| ceph |cflow |chess |chrony |civetweb |clamav |clang |
| collectd |commons_compress |connman |coreutils |cpio |cpp_httplib |cronie |
| cryptsetup |cups |curl |cvs |darkhttpd |dav1d |davfs2 |
| dbus |debianutils |dhclient |dhcpcd |dhcpd |djvulibre |dlt_daemon |
| dmidecode |dnsmasq |docker |domoticz |dosfstools |dotnet |dovecot |
| doxygen |dpkg |dropbear |e2fsprogs |ed |elfutils |emacs |
| enscript |exfatprogs |exim |exiv2 |f2fs_tools |faad2 |fastd |
| ffmpeg |file |firefox |flac |fluidsynth |freeradius |freerdp |
| fribidi |frr |gawk |gcc |gdal |gdb |gdk_pixbuf |
| gettext |ghostscript |gimp |git |glib |glibc |gmp |
| gnomeshell |gnupg |gnutls |go |gpgme |gpsd |graphicsmagick |
| grep |grub2 |gsasl |gstreamer |guile |gupnp |gvfs |
| gzip |haproxy |harfbuzz |haserl |hdf5 |heimdal |hostapd |
| hunspell |hwloc |i2pd |icecast |icu |imagemagick |indent |
| inetutils |iperf3 |ipmitool |ipsec_tools |iptables |irssi |iucode_tool |
| iwd |jack2 |jacksondatabind |janus |jasper |jhead |jq |
| json_c |kbd |keepalived |kerberos |kexectools |kodi |kubernetes |
| ldns |lftp |libarchive |libass |libbpg |libcoap |libconfuse |
| libcurl |libdb |libde265 |libebml |libevent |libexpat |libgcrypt |
| libgd |libgit2 |libheif |libical |libidn2 |libinput |libjpeg |
| libjpeg_turbo |libksba |liblas |libmatroska |libmemcached |libmicrohttpd |libmodbus |
| libnss |libopenmpt |libpcap |libraw |libreoffice |libreswan |librsvg |
| librsync |libsamplerate |libseccomp |libsndfile |libsolv |libsoup |libsrtp |
| libssh |libssh2 |libtasn1 |libtiff |libtomcrypt |libupnp |libuv |
| libvips |libvirt |libvncserver |libvorbis |libvpx |libxslt |libyaml |
| libyang |lighttpd |linux_kernel |linuxptp |lldpd |logrotate |lrzip |
| lua |luajit |lxc |lynx |lz4 |mailx |mariadb |
| mbedtls |mdadm |memcached |micropython |minetest |mini_httpd |minicom |
| minidlna |miniupnpc |miniupnpd |moby |modsecurity |monit |mosquitto |
| motion |mp4v2 |mpg123 |mpv |msmtp |mtr |mupdf |
| mutt |mysql |nano |nasm |nbd |ncurses |neon |
| nessus |netatalk |netdata |netkit_ftp |netpbm |nettle |nghttp2 |
| nginx |ngircd |nmap |node |ntfs_3g |ntp |ntpsec |
| oath_toolkit |open_iscsi |open_vm_tools |openafs |openblas |opencv |openjpeg |
| openldap |opensc |openssh |openssl |openswan |openvpn |openvswitch |
| orc |p7zip |pango |patch |pcre |pcre2 |pcsc_lite |
| perl |php |picocom |pigz |pixman |png |polarssl_fedora |
| poppler |postgresql |ppp |privoxy |procps_ng |proftpd |protobuf_c |
| pspp |pure_ftpd |putty |python |qemu |qpdf |qt |
| quagga |radare2 |radvd |raptor |rauc |rdesktop |readline |
| redis |rpm |rsync |rsyslog |rtl_433 |rtmpdump |runc |
| rust |samba |sane_backends |sasl |sdl |seahorse |shadowsocks_libev |
| snapd |sngrep |snort |socat |sofia_sip |speex |spice |
| sqlite |squashfs |squid |sslh |stellarium |strongswan |stunnel |
| subversion |sudo |suricata |sylpheed |syslogng |sysstat |systemd |
| tar |tbb |tcpdump |tcpreplay |terminology |tesseract |thrift |
| thttpd |thunderbird |timescaledb |tinyproxy |tor |toybox |tpm2_tss |
| traceroute |transmission |trousers |ttyd |twonky_server |u_boot |udisks |
| unbound |unixodbc |upx |util_linux |uwsgi |varnish |vim |
| vlc |vorbis_tools |vsftpd |wavpack |webkitgtk |wget |wireshark |
| wolfssl |wpa_supplicant |xerces |xml2 |xpdf |xscreensaver |xwayland |
| xz |yasm |zabbix |zchunk |zeek |zlib |znc |
| zsh |zstandard | | | | | |
<!--CHECKERS TABLE END-->

All the checkers can be found in the checkers directory, as can the
[instructions on how to add a new checker](https://github.com/intel/cve-bin-tool/blob/main/cve_bin_tool/checkers/README.md).
Support for new checkers can be requested via
[GitHub issues](https://github.com/intel/cve-bin-tool/issues).

### Language Specific checkers

A number of checkers are available for finding vulnerable components in specific language packages.

| Language   | Files supported                                 |
| ---------- | ----------------------------------------------- |
| Dart         | `pubspec.lock` |
| Go         | `Go.mod` |
| Java       | `pom.xml`; JAR, WAR and EAR archives |
| JavaScript | `package-lock.json`, `yarn.lock` |
| Rust       | `Cargo.lock` |
| Ruby       | `Gemfile.lock` |
| R          | `renv.lock` |
| Swift      | `Package.resolved` |
| Python     | `requirements.txt`, `