Skip to content

Command Line Tool

Jump to bottom
Mark E. Haase edited this page Jun 18, 2024 · 7 revisions

API Key

While it is possible to use the tool without an API key, obtaining a key can improve performance by raising the rate limits set by NVD. You can obtain an API key from the NVD website and pass it to the command line tool using the --key or --keyfile parameters.

Installation

Before installation, you need to have Python Poetry installled. Next, clone the repo and run poetry install from the root directory to install its dependencies into a virtual environment.

Alternatively, you can use pip install . to install the package, which may be useful if you want a system-wide installation that does not require a virtual environment.

Usage

Before using the tool, you should activate your virtual environment, e.g. poetry shell. (If you installed system-wide using pip, then you can skip this step.)

The command line tool is called ec3-cli and you can use the --help flag to access built-in documentation.

$ ec3-cli --help
usage: ec3-cli [-h] {calculate,update} ...

CWE Calculator with Environmental CVSS

options:
  -h, --help          show this help message and exit

sub-commands:
  {calculate,update}  Use 'calculate' or 'update' mode of ec3-cli. Run 'ec3-cli {sub-command} --help' for more information.

The command line tool has two subcommands that are covered in greater depth below.

Subcommand: Update

The update subcommand downloads the CVE data that is used by the calculator. The data is cached locally so that the calculator can be run repeatedly without needing to download data each time. The basic use is:

$ ec3-cli update

*** CWE Calculator with Environmental CVSS ***

Initialized NvdCollector to search CVEs from 2024-05-14 14:29:36.855753 until 2024-06-13 14:29:36.855759.

By default, this caches the CVE data in a file named data/nvd_loaded.pickle (using Python's internal serialization format). If you don't specify a date range, the tool defaults to getting all CVEs published in the last 30 days.

Here is a more complete example:

$ ec3-cli update --keyfile nvd_api.key \
    --start-date 2023-01-01 \
    --end-date 2024-01-01

This example specifies an NVD API key (stored in a text file called nvd_api.key). It also specifies start/end dates to download a custom range of data: in this case, all CVEs published in 2023.

Subcommand: Calculate

The calculate subcommand does the actual work to compute CWE scores. The most basic usage is to pass in just a CWE identifier. For example, to query CWE-787:

$ ec3-cli calculate 787

*** CWE with Environmental CVSS Calculator ***

Calculating CVSS for CWE ID 787:
Projected CVSS: 8.10

----------------------------------------

Additional Information

 Min: 5.50
 Max: 9.80
 Average: 8.10
 Stdev: 1.30

Found 17 related CVE records:

CVE-2023-29491	CVE-2023-3812	CVE-2023-3341	CVE-2023-42753
CVE-2023-42753	CVE-2023-5367	CVE-2023-5367	CVE-2023-3164
CVE-2023-49351	CVE-2023-6340	CVE-2024-0409	CVE-2024-0409
CVE-2024-23214	CVE-2024-0745	CVE-2024-22660	CVE-2024-22662
CVE-2024-22751

----------------------------------------

The calculator estimates scores by finding related CVEs and averaging their CVSS scores. In this case, there are 38 related CVEs (based on the 30 days timeframe that was specified when running the update command above). The tool shows the min, mean, max, and standard deviation of the CVSS scores of these CVEs. In this case, the mean score is 8.10 (out of 10) which is pretty high!

The command also lets you customize the environmental metrics used in the CVSS calculations.

$ ec3-cli calculate 787 -cr H -ar L

*** CWE with Environmental CVSS Calculator ***

Calculating CVSS for CWE ID 787:
Projected CVSS: 7.78

----------------------------------------

Additional Information

 Min: 3.70
 Max: 9.80
 Average: 7.78
 Stdev: 1.87

Found 17 related CVE records:

CVE-2023-29491	CVE-2023-3812	CVE-2023-3341	CVE-2023-42753
CVE-2023-42753	CVE-2023-5367	CVE-2023-5367	CVE-2023-3164
CVE-2023-49351	CVE-2023-6340	CVE-2024-0409	CVE-2024-0409
CVE-2024-23214	CVE-2024-0745	CVE-2024-22660	CVE-2024-22662
CVE-2024-22751

----------------------------------------

This example sets the confidentiality requirement (-cr) to high (H) and the availability requirement (-ar) to low (l). This has the effect of lowering the projected CVSS to 7.87 from 8.10, which reflects how CWE-787 empirically has higher availability impact than confidentiality.

Clone this wiki locally