parse-nvd 0.4.1

CLI tool to match COTS inventories against NVD CVE feeds.

parse-nvd

parse-nvd is a command-line tool that matches a COTS (Commercial Off-The-Shelf) inventory against CVE vulnerabilities published in NVD JSON exports.

Why this tool

In a risk analysis context, you typically have:

• a product/version inventory (COTS),
• large NVD data feeds,
• CVSS severity criteria.

The tool automates this matching to quickly produce an actionable report:

• filtering CVEs by CVSS score, attack vector, and impact,
• optional filtering on the presence of an exploit,
• JSON output for machine processing,
• Markdown/PDF output for human distribution.

How it works

1. Validate NVD files against the local official schema.
2. Extract the relevant CVSS metrics.
3. Match COTS against CPE entries and compare versions.
4. Apply the requested filters.
5. Generate JSON reports and optionally Markdown/XHTML reports.

Installation

pip install -e .

Running from source (without installation)

From the project root, you can launch the CLI directly from the source tree:

PYTHONPATH=src python -m parse_nvd \
  --nvd-db nvdcve-2.0-recent.json \
  --cots-list essai-cots.json \
  --output report.json

This lets you use the tool without pip install, which is convenient for quick tests or in CI environments. Just set PYTHONPATH=src to add the source directory to Python's module search path.

COTS file format

The --cots-list file must be a JSON array of objects, each with at least a name and a version field. The name must match the CPE product identifier used by the NVD (e.g. linux_kernel, openssl, gcc).

[
  { "name": "linux_kernel", "version": "5.10" },
  { "name": "openssl",      "version": "3.0.2" },
  { "name": "gcc",          "version": "10.2.0" }
]

Trailing commas are tolerated.

Obtaining NVD data feeds

The NIST NVD JSON databases can be downloaded from:

https://nvd.nist.gov/vuln/data-feeds

Available datasets include:

• Recent vulnerabilities (last 120 days)
• Historical data, split by year
• Comprehensive full database

CLI arguments

• --nvd-db FILE [FILE ...] (required) One or more NVD JSON files using the official schema.
• --cots-list FILE (required) JSON file listing COTS entries (name/version).
• --output FILE Output report path. Defaults to parse-nvd-report.json.
• --md FILE Write a Markdown report to the provided path.
• --html FILE Write a self-contained XHTML report with embedded CSS to the provided path, without any external resource.
• --verbose Display a clear synthetic console summary using rich.
• --cvss-min FLOAT Minimum CVSS base score for a CVE to be kept.
• --cvss-av VALUE Minimum attack vector filter. Accepted values (from most to least severe): NETWORK, ADJACENT, LOCAL, PHYSICAL.
• --cvss-impact-c VALUE Minimum confidentiality impact filter (NONE, LOW, HIGH).
• --cvss-impact-i VALUE Minimum integrity impact filter (NONE, LOW, HIGH).
• --cvss-impact-d VALUE Minimum availability impact filter (NONE, LOW, HIGH).
• --with-exploit Keep only CVEs for which an exploit appears to exist.
• --created-or-updated-after YYYY-MM-DD Keep only CVEs created or updated strictly after the provided date.
• --linux-order-by-system Group linux_kernel CVEs by impacted Linux subsystem in Markdown and XHTML reports.

Usage examples

JSON output only

parse-nvd \
  --nvd-db nvdcve-2.0-recent.json \
  --cots-list cots.json \
  --output report.json

With CVSS filters and exploit check

parse-nvd \
  --nvd-db nvdcve-2.0-recent.json \
  --cots-list cots.json \
  --created-or-updated-after 2026-01-01 \
  --linux-order-by-system \
  --html report.xhtml \
  --cvss-min 7.0 \
  --cvss-av NETWORK \
  --cvss-impact-c LOW \
  --cvss-impact-i LOW \
  --cvss-impact-d LOW \
  --with-exploit \
  --verbose \
  --md report.md \
  --output report.json

JSON report structure

The generated report contains:

• A summary block with applied filters, global counters, NVD source information, and all CLI options used,
• A cots block containing, for each COTS entry, the list of associated CVEs,
• For each CVE: the CVE block, the normalized CVSS metric, matched CPE criteria, and the exploit_available indicator.

Markdown and PDF reports

Generating Markdown from CLI

parse-nvd \
  --nvd-db nvdcve-2.0-recent.json \
  --cots-list cots.json \
  --md report.md \
  --output report.json

The Markdown report includes:

• NVD sources with their creation timestamps
• Applied filters
• CLI options used
• Summary table by COTS
• Detailed CVE tables grouped by COTS

Generating self-contained XHTML from CLI

parse-nvd \
  --nvd-db nvdcve-2.0-recent.json \
  --cots-list cots.json \
  --html report.xhtml \
  --output report.json

The XHTML report embeds its CSS styling directly within the page. It has no external dependencies and does not require any network access.

Generating PDF from Markdown

pandoc report.md -o report.html
python -m weasyprint --stylesheet docs/report-a4.css report.html report.pdf

The docs/report-a4.css stylesheet is optimized for A4 printing.

Scope and limitations

parse-nvd is a simple command-line tool designed for basic vulnerability matching in COTS inventories. It is intended for quick analysis and reporting at the component level.

For comprehensive vulnerability management and supply chain analysis, organizations typically use Software Bill of Materials (SBOM) in standardized formats:

• SPDX (Software Package Data Exchange) – ISO/IEC 5962 standard
• CycloneDX – OWASP dependency tracking standard

Professional tools such as Artifactory Xray, Nessus Firewall, Snyk, or WhiteSource provide enterprise-grade SBOM analysis with deeper context, license compliance checking, and remediation guidance. These tools are recommended for production environments and critical supply chain security.

Developer documentation

The project can generate a minimal documentation site in docs/site:

• docs/site/index.html – project overview
• docs/site/cli-arguments.html – CLI arguments and their meaning
• HTML pages for Python modules

Typical usage

Run the tool with an NVD database, your COTS inventory, and optional filters. It generates JSON, Markdown, and XHTML reports with vulnerability matches.

Example command:

parse-nvd \
  --nvd-db nvdcve-2.0-recent.json \
  --cots-list inventory.json \
  --cvss-min 7.0 \
  --with-exploit \
  --linux-order-by-system \
  --md report.md \
  --html report.xhtml \
  --verbose

A sample report is published here

Development

tox
tox -e pydoc
tox -e report-pdf
pytest -q
python -m build