parse-nvd 0.4.0

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.

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.

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.

Exemples d'utilisation

JSON uniquement

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

Avec filtres CVSS et exploit

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

Structure du rapport JSON

Le rapport généré contient:

• un bloc summary avec les filtres appliqués et les compteurs globaux,
• un bloc cots contenant, pour chaque entrée COTS, la liste des CVE associées,
• pour chaque CVE: le bloc cve, la métrique cvss normalisée, les critères CPE matchés, et l'indicateur exploit_available.

Rapport Markdown et PDF

Générer le Markdown depuis le CLI

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

Générer le XHTML autonome depuis le CLI

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

Le rapport XHTML embarque son style CSS directement dans la page. Il ne dépend d'aucun accès réseau ni d'aucune ressource externe.

Générer le PDF depuis le Markdown

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

Le style docs/report-a4.css est prévu pour une lecture correcte à l'impression A4.

Documentation développeur

Le projet peut générer un mini site de documentation dans docs/site:

• docs/site/index.html pour l'accueil,
• docs/site/cli-arguments.html pour les arguments CLI et leur signification,
• pages HTML des modules Python.

Développement

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