NVD Client - CVE Lookup & NAO Enrichment

Python client for the NIST National Vulnerability Database API v2.0. Fetches CVE data and structures it for direct injection into the SIEM pipeline's Normalized Alert Object (NAO).

Setup

pip install -r scripts/requirements.txt

Requires a .env file in the project root with:

NVD_BASE_URL=https://services.nvd.nist.gov/rest/json/cves/2.0
NVD_API_KEY=<your-key>

Request a free API key at https://nvd.nist.gov/developers/request-an-api-key

CLI Usage

All commands run from the project root. Global flags (--output, --log-level) go before the subcommand.

Fetch a single CVE

python scripts/nvd_client.py cve --id CVE-2021-44228
python scripts/nvd_client.py --output summary cve --id CVE-2021-44228
python scripts/nvd_client.py --output nao-evidence cve --id CVE-2021-44228

Search by keyword

python scripts/nvd_client.py keyword --query "apache log4j" --limit 10
python scripts/nvd_client.py keyword --query "openssl" --exact --limit 5

Search by CVSS severity

python scripts/nvd_client.py severity --level CRITICAL --limit 20
python scripts/nvd_client.py severity --level HIGH --limit 50

Search recently published or modified CVEs

python scripts/nvd_client.py recent --mode published --days 7 --limit 20
python scripts/nvd_client.py recent --mode modified --days 1 --limit 50

Output formats

Flag	Description
--output json	Full structured JSON (default)
--output nao-evidence	NAO evidence[] entries, ready to insert into an alert
--output summary	Human-readable table, one line per CVE

Export to file

Create the output directory and redirect results to artifacts/CVEs/:

mkdir -p artifacts/CVEs
python scripts/nvd_client.py cve --id CVE-2021-44228 > artifacts/CVEs/CVE-2021-44228.json
python scripts/nvd_client.py --output summary cve --id CVE-2021-44228 > artifacts/CVEs/CVE-2021-44228.txt
python scripts/nvd_client.py --output nao-evidence cve --id CVE-2021-44228 > artifacts/CVEs/CVE-2021-44228.nao.json

Logging

python scripts/nvd_client.py --log-level DEBUG cve --id CVE-2023-44487

Module Usage

from scripts.nvd_client import NVDClient

client = NVDClient()

# Single CVE lookup
cve = client.get_cve("CVE-2021-44228")
print(cve.cvss_score)          # 10.0
print(cve.cvss_severity)       # CRITICAL
print(cve.kev_listed)          # True
print(cve.affected_products)   # ['apache:log4j:2.0', ...]

# Get NAO-ready evidence entry
evidence = cve.to_nao_evidence_entry()

# Convert CVSS to 0-100 risk score
risk = cve.to_nao_risk_score_input()  # 100

# Search
results = client.search_by_keyword("openssl", limit=10)
for c in results.cves:
    print(f"{c.cve_id}: {c.cvss_score}")

NAO Enrichment

The primary integration point for the SIEM pipeline. Pass a NAO dict and it gets enriched in place:

from scripts.nvd_client import NVDClient

client = NVDClient()

nao = {
    "alert_id": "ALERT-001",
    "severity": "medium",
    "risk_score": 40,
    "summary": "Vulnerability detected: CVE-2021-44228",
    "entities": {"resources": []},
    "evidence": [],
    "links": [],
}

# Enriches the NAO in place and returns it
enriched = client.enrich_nao(nao)

This will:

• Extract CVE IDs from summary and evidence automatically (or pass them explicitly with cve_ids=["CVE-..."])
• Append NVD data to evidence[]
• Add reference URLs to links[]
• Merge affected products into entities.resources[]
• Upgrade risk_score if CVSS score is higher (never downgrades)
• Force severity to high if the CVE is in CISA's Known Exploited Vulnerabilities catalog

NAO Field Mapping

CVEEnrichment field	NAO field	Notes
to_nao_evidence_entry()	evidence[]	Full evidence object
reference_urls	links[]	Deduplicated
affected_products	entities.resources[]	vendor:product:version format
to_nao_risk_score_input()	risk_score	CVSS 0-10 scaled to 0-100
cvss_severity	severity	Used when no severity set
kev_listed	severity	Forces minimum high

Error Handling

from scripts.nvd_client import NVDClient, NVDAPIError

client = NVDClient()

try:
    cve = client.get_cve("CVE-9999-99999")
except NVDAPIError as e:
    print(e)         # "No results for CVE-9999-99999"
    print(e.status)  # 404

Common errors:

Status	Meaning
403	API key invalid or missing
404	CVE ID does not exist
503	NVD rate limited or down

Rate Limits

The client enforces rate limiting automatically:

Auth	Limit	Per-request delay
With API key	~50 req / 30s	0.6s
Without key	~5 req / 30s	6.0s

AX Workspace Integration

This tool's capability manifest is stored in the SIEM workspace as AX context key siem:tool:nvd_client. The primary consumer is @SIEM_Intel-Fusion_Agent during the CVE correlation stage of the enrichment pipeline.