CVE-Scripts

This repository contains a python script that can be used to download CVE data from the National Vulnerability Database (NVD) and to query the data using a simple command-line interface. It is designed for the specific use case of searching for CVEs based on a package name and version.

Setup

The script makes use of a mongodb database to store the CVE data. This database can be created locally, in a docker container, or on a remote server. The script can be configured to use any of these options so long as the user has read and write access to the database.

If you're not sure which option to use, the simplest option is generally to use the official MongoDB Docker image. Instructions for setting that up can be found in their official documentation. After running the container, the script can be used without any further configuration.

Being a Python script, it requires Python 3.6 or higher. To avoid package conflicts, it is recommended to use a virtual environment. Instructions for setting that up can be found in the official Python documentation.

To make and run a simple virtual environment, follow these steps:

1. Create a new virtual environment:

   python3 -m venv venv
   

2. Activate the virtual environment:

   • On Unix or macOS:

     source venv/bin/activate
     

   • On Windows:

     venv\Scripts\activate
     

3. Install the required packages:

   python -m pip install -r requirements.txt
   

Usage

For more information on how to use the script, run:

python cve-scripts.py --help

Populating the CVE Database

The basic usage of the script is to populate the database with the latest CVE data:

python cve-scripts.py --populate

Updating the CVE Database

It is recommended to periodically update the database with the latest CVE data:

python cve-scripts.py --update

The script will warn you if the database is at least a week out of date.

NIST API Key

The database populates and updates using the NIST API. To use the NIST API, you need to obtain an API key from NIST.

Note: You do not need to have an API key to use the script. If you do not have an API key, the populating and updating of the database will just be significantly slower.

To use the NIST API key, you can specify it with the --nist-api-key option:

python cve-scripts.py --nist-api-key <api_key>

or by setting the NIST_API_KEY environment variable to have it persist across sessions:

export NIST_API_KEY=<api_key>

Searching the CVE Database

Then query the CVE database for CVEs based on a package name and version:

python cve-scripts.py --search <package_name> <version>

To search multiple packages, listing them in a file, each entry on a new line, you can specify the file with the --search-file option:

python cve-scripts.py --search-file <file_path>

Custom CVE Database URL

If you have a custom CVE database url (for example, if you have a username and password to send or a custom port), you can specify the url with the --mongo-url option:

python cve-scripts.py --mongo-url mongodb://username:password@localhost:27017

or by setting the MONGO_DB_URL environment variable to have it persist across sessions:

export MONGO_DB_URL=mongodb://username:password@localhost:27017

Hash Mode

If you instead have a collection of hashes instead of versions, you can use the --hash-mode option to query the hash. This by default will query the CIRCL hashlookup remote database. You can specify a custom hash lookup URL with the --hash-url option (though this currently doesn't do anything, custom hash database will be implemented soon):

python cve-scripts.py --hash-mode --hash-url <hash_lookup_url> --search-file <file_path>

Custom Output File

By default, the script will generate a report named report.txt in the current directory. You can specify a custom output file with the --output-file option:

python cve-scripts.py --output-file <output_file>