Metadata-Version: 2.4
Name: parse-nvd
Version: 0.4.1
Summary: CLI tool to match COTS inventories against NVD CVE feeds.
Author: Phil
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.23
Requires-Dist: rich>=13.6
Requires-Dist: semver>=3.0.4

<!-- SPDX-FileCopyrightText: 2026 Phil -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# 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

```bash
pip install -e .
```

## Running from source (without installation)

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

```bash
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`).

```json
[
  { "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](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

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

### With CVSS filters and exploit check

```bash
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

```bash
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

```bash
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

```bash
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.

![parse-nvd demo](docs/demo.gif)

Example command:

```bash
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](docs/report.html)

## Development

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