Metadata-Version: 2.4
Name: parse-nvd
Version: 0.4.0
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.

## 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.

## 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

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

### Avec filtres CVSS et exploit

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

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

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

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

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