fleet/docs/01-Using-Fleet/13-Vulnerability-Processing.md

# Vulnerability processing
- [What to expect](#what-to-expect)
- [Configuration](#configuration)
- [Performance](#performance)

## What to expect

Vulnerability processing is enabled by default.

Fleet checks for vulnerabilities using the National Vulnerability Database (NVD). 

First, Fleet retrieves the installed software for each host using osquery queries. Then, Fleet
translates each installed software into [Common Platform Enumeration (CPE)](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) names.

Then, using the CPEs, Fleet searches the list of [Common Vulnerabilities and Exposure
(CVE)](https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures) identifiers listed in the NVD
to detect the CVEs that match the defined CPEs. 

If matches are found, they are exposed on each host's
**Host details** page and on the **Home** page in the Fleet UI. The CVEs are also exposed in the
`fleetctl get software` command and the `GET api/v1/fleet/hosts/{id}` and `GET
api/v1/fleet/software` API routes.

Vulnerability processing happens on the Fleet instance and not on the host machine. Because of this,
detected vulnerabilities cannot be used in the same way you would use an osquery query (e.g. you wouldn't
be able write a query to retrieve all CVEs).

## Configuration

To enable vulnerability processing, first enable the software inventory feature by setting the following app config:

```
---
apiVersion: v1
kind: config
spec:
  host_settings:
    enable_software_inventory: true
```

Then, enable vulnerability processing by specifying a path where Fleet will download the different
data feeds. This can be done by setting the following app config:

```
---
apiVersion: v1
kind: config
spec:
  vulnerability_settings:
    databases_path: /some/path
```

Or through environment variables:

```
FLEET_VULNERABILITIES_DATABASES_PATH=/some/path
```

The path specified needs to exist and Fleet needs to be able to read and write to and from it. This is the only mandatory
configuration needed for vulnerability processing to work. Additional options, like vulnerability check frequency, can be
found in the [configuration documentation](../02-Deploying/03-Configuration.md#vulnerabilities).

You'll need to restart the Fleet instances after changing these settings.

## Performance

Vulnerability processing is performed in one Fleet instance. If your Fleet deployment uses multiple
instances, only one will be doing the work.

In order to conduct vulnerability processing, Fleet downloads the following files:

1. A preprocessed CPE database generated by FleetDM to speed up the translation process: https://github.com/fleetdm/nvd/releases
2. The historical data for all CVEs and how to match to a CPE: from https://nvd.nist.gov/vuln/data-feeds

The database generated in step 1 is processed from the original official CPE dictionary
https://nvd.nist.gov/products/cpe. This CPE dictionary is typically updated once a day.

The matching occurs server-side to make the processing as fast as possible, but the whole process is both CPU and memory intensive.

For example, when running a development instance of Fleet on an Apple Macbook Pro with 16 cores, matching 200,000 CPEs against the CVE database will take around 10 seconds and consume about 3GBs of RAM. 

The CPU and memory usages are in burst once every hour (or the configured periodicity) on the instance that does the processing. RAM spikes are expected to not exceed the 2GBs.