nvdutils
A comprehensive Python package for parsing, representing, filtering, and analyzing National Vulnerability Database (NVD) data. This library provides tools to work with CVE records, making it easier to process and extract insights from vulnerability data.
Features
- Flexible Data Loading: Load CVE data from JSON files with support for different loading strategies
- Rich Data Models: Comprehensive Pydantic models for representing CVE data including descriptions, configurations, weaknesses, metrics, and references
- Filtering Capabilities: Filter CVEs based on various criteria using profiles
- Data Collection: Utilities for downloading NVD data feeds
- Progress Tracking: Built-in progress bars and statistics for data loading operations
- Extensible Architecture: Easily extend the library with custom loaders, profiles, and strategies
Installation
pip install nvdutils
Setup
Before using the package, you need to set up the data directory and download the NVD data:
# Create data directory
mkdir ~/.nvdutils
cd ~/.nvdutils
# Clone the NVD JSON data feeds repository
git clone https://github.com/fkie-cad/nvd-json-data-feeds.git
Usage Examples
Basic Usage: Loading All CVE Data
from pathlib import Path
from nvdutils.loaders.json.default import JSONDefaultLoader
# Create a loader
loader = JSONDefaultLoader()
# Eagerly load all the data
cve_dictionary = loader.load(Path("~/.nvdutils/nvd-json-data-feeds"), include_subdirectories=True)
# Access CVEs by ID
cve = cve_dictionary.get("CVE-2023-1234")
Loading a Specific CVE by ID
from pathlib import Path
from nvdutils.loaders.json.yearly import JSONYearlyLoader
# Create a loader
loader = JSONYearlyLoader()
data_path = Path("~/.nvdutils/nvd-json-data-feeds")
# Load a specific CVE by ID
cve = loader.load_by_id("CVE-2015-5334", data_path)
# Print the CVE details
print(cve)
Filtering CVEs with Profiles
from pathlib import Path
from nvdutils.loaders.json.default import JSONDefaultLoader
from nvdutils.data.profiles.zero_click import ZeroClickProfile
# Create a loader with a profile
loader = JSONDefaultLoader(profile=ZeroClickProfile, verbose=True)
# Load CVEs that match the profile
cve_dict = loader.load(Path("~/.nvdutils/nvd-json-data-feeds"), include_subdirectories=True)
print(f"Loaded {len(cve_dict)} CVEs")
Creating Custom Profiles
from dataclasses import dataclass, field
from nvdutils.data.profiles.base import BaseProfile
from nvdutils.data.criteria.weaknesses import CWECriteria, WeaknessesCriteria
from nvdutils.common.enums.weaknesses import WeaknessType
# Define criteria for CWE-787 weaknesses
cwe_787_criteria = WeaknessesCriteria(
cwe_criteria=CWECriteria(
cwe_id='CWE-787',
is_single=True
),
weakness_type=WeaknessType.Primary
)
# Create a custom profile
@dataclass
class CWE787Profile(BaseProfile):
"""Profile for selecting CVEs with CWE-787 as the primary weakness."""
weakness_criteria: WeaknessesCriteria = field(default_factory=lambda: cwe_787_criteria)
Key Components
Loaders
- CVEDataLoader: Base class for loading CVE data
- JSONDefaultLoader: Loader for JSON data with default strategy
- JSONYearlyLoader: Loader for JSON data organized by year
Models
- CVE: Main model representing a CVE record
- Descriptions: Model for vulnerability descriptions
- Configurations: Model for affected configurations
- Weaknesses: Model for weakness types (CWEs)
- Metrics: Model for vulnerability metrics (CVSS)
- References: Model for external references
Profiles and Criteria
- BaseProfile: Base class for filtering profiles
- ZeroClickProfile: Profile for zero-click vulnerabilities
- Criteria Classes: Various criteria for filtering CVEs
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the terms specified in the LICENSE file.
1 maintainer
Release files for nvdutils 3.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nvdutils-3.5.1.tar.gz | 29.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nvdutils-3.5.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size:70.9 kB
Release files / nvdutils-3.5.1.tar.gz
| Download URL | nvdutils-3.5.1.tar.gz |
|---|---|
| Size | 29.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b17a63106cfadb35d7fdae5df0875ad61d6241493495415006e3f726392be58
|
|
BLAKE2b-256 checksum How to use checksums |
528cac05c608310059fc8b4f13eb5a9537157c7cca7e55d30ed57ce0a5937a5a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.10.7
|
Release files / nvdutils-3.5.1-py3-none-any.whl
| Download URL | nvdutils-3.5.1-py3-none-any.whl |
|---|---|
| Size | 41.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69659102d751d0246422253d13519dec4a7878d69b29d678c1b9db4b79b2ff69
|
|
BLAKE2b-256 checksum How to use checksums |
5279909cd463b5b3de31873f8742f8d802c2a872a9abb4f8f645a052ae4e5b45
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.10.7
|
