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

# Vulnerability Processing
- [What to expect](#what-to-expect)
- [Setup](#setup)

## What to expect

Vulnerability processing is currently in beta.

At the moment, Fleet only checks for vulnerabilities against the National Vulnerability Database (NVD). The way it works is by 
first translating the software from each host into a CPE (Common Platform Enumeration) representation of the name.

With this CPE, we search the full list of CVEs (Common Vulnerabilities and Exposures) from NVD to detect the CVEs matching
the defined CPE. If any matches are found, they are exposed through the API for describing a host and through the
web frontend in the host details section.

These checks are performed in one Fleet instance. If your Fleet deployment uses multiple instances, only one will be doing
this work.

In order to do all this, 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 1 is processed from the original official CPE dictionary https://nvd.nist.gov/products/cpe. It's
updated once a day at most, depending on whether there's new data.

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 200k 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.

## Setup

By default, the software inventory feature is enabled and vulnerability checking is disabled. Both must be enabled to check for vulnerabilities.

You can check to see if the software inventory feature is enabled by running the `fleetctl get config` command. If `enable_software_inventory` is set to `true`, in the command's output, the software inventory feature is already enabled.

If you disabled the software inventory feature, you must re-enable it first by setting the following app config:

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

Fleet also needs a path where it will download the different data feeds. This can be done through the Fleet server config
YAML:

```
echo '
... rest of your config here
vulnerabilities:
  databases_path: /some/path
' > /tmp/fleet.yml
fleet serve --config /tmp/fleet.yml
```

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.

## Results

If enabled, Fleet will flag all software versions that have one or more detected CVEs in the software section of that host's **Host details** page. 

In the software section, select the right facing arrow to see the specific CVEs associated with a specific software version. The CVEs are also included in the response of the `GET api/v1/fleet/hosts/{id}` API route.

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 a query (e.g. you wouldn't be able create a policy based on a detected CVE).

This information can be used to create queries and base policies on. For example: If you see that a vulnerable version of Figma is detected on a host, you can create a query that looks for this versions of Figma:

Is Figma.app, version [vulnerable-version] installed?

`SELECT 1 FROM apps WHERE name = ‘Figma.app’ AND bundle_short_version = ‘[vulnerable-version]’;`

Then you can use this query to create a policy to track your effort to patch all hosts with this version of Figma installed.