nvd_client.api

HTTP client for the NVD CVE and CPE Match 2.0 APIs.

CVE methods that return a collection produce a CveListResponse. NvdApi.get_cve_by_id returns the single CveRecord and raises NvdNotFoundError when NVD has no such CVE. CPE Match methods return a CpeMatchResponse.

Transport failures, HTTP errors, and rate limits raise NvdApiError (or a subclass). They do not come back as None. A query that matches nothing is a normal page whose total_results is 0.

Classes:

• NvdApi –

  Client for /rest/json/cves/2.0 and /rest/json/cpematch/2.0.

NvdApi

NvdApi(api_key: str | None = None, proxy: str | None = None, *, config: NvdConfig | None = None)

Client for /rest/json/cves/2.0 and /rest/json/cpematch/2.0.

NvdApi(api_key) and NvdApi(api_key, proxy) still work. Pass config for the rest of the knobs (base URL, timeouts, page size, rate-limit delay, retries, user agent). A non-None api_key or proxy overrides the same field on config.

Per-call proxy overrides the client proxy for that request only. per_page=None uses the page size on the config.

The client sleeps between requests so a single instance stays inside NVD's published rate limit. It is safe to share across threads; calls take turns. Use the client as a context manager to close the connection pool.

Methods:

• close –

  Close the underlying HTTP connection pool.

• get_all_cves –

  Fetch one page of CVEs, ordered as NVD returns them.

• get_cve_by_id –

  Fetch one CVE by id.

• get_cve_by_date –

  Fetch CVEs published and/or modified inside a date range.

• get_cve_by_cpe –

  Fetch CVEs whose applicability statement matches cpe_name.

• get_cpes_by_cve –

  Fetch CPE match strings associated with a CVE id.

• get_cpes_by_criteria –

  Fetch CPE match strings for a matchStringSearch value.

• get_cpes_by_criteria_name_id –

  Fetch the CPE match string for a matchCriteriaId UUID.

Attributes:

• config –

config instance-attribute

config = base

close

close() -> None

Close the underlying HTTP connection pool.

get_all_cves

get_all_cves(per_page: int | None = None, offset: int = 0, proxy: str | None = None) -> CveListResponse

Fetch one page of CVEs, ordered as NVD returns them.

get_cve_by_id

get_cve_by_id(cve_id: str, proxy: str | None = None) -> CveRecord

Fetch one CVE by id.

Raises InvalidCVEIDError for a bad id and NvdNotFoundError when NVD has no record.

get_cve_by_date

get_cve_by_date(per_page: int | None = None, offset: int = 0, publish_start_date: datetime | None = None, publish_end_date: datetime | None = None, modify_start_date: datetime | None = None, modify_end_date: datetime | None = None, proxy: str | None = None) -> CveListResponse

Fetch CVEs published and/or modified inside a date range.

Each range needs both ends and must be at most 120 days. Naive datetimes are UTC. Aware datetimes are converted to UTC.

get_cve_by_cpe

get_cve_by_cpe(cpe_name: str, per_page: int | None = None, offset: int = 0, publish_start_date: datetime | None = None, publish_end_date: datetime | None = None, modify_start_date: datetime | None = None, modify_end_date: datetime | None = None, proxy: str | None = None) -> CveListResponse

Fetch CVEs whose applicability statement matches cpe_name.

cpe_name is sent as the cpeName parameter. NVD compares it with the CPE match criteria on each CVE. The part, vendor, product, and version components must be real values, not *.

get_cpes_by_cve

get_cpes_by_cve(cve_id: str, per_page: int | None = None, offset: int = 0, proxy: str | None = None) -> CpeMatchResponse

Fetch CPE match strings associated with a CVE id.

get_cpes_by_criteria

get_cpes_by_criteria(criteria: str, per_page: int | None = None, offset: int = 0, proxy: str | None = None) -> CpeMatchResponse

Fetch CPE match strings for a matchStringSearch value.

get_cpes_by_criteria_name_id

get_cpes_by_criteria_name_id(criteria_name_id: str, per_page: int | None = None, offset: int = 0, proxy: str | None = None) -> CpeMatchResponse

Fetch the CPE match string for a matchCriteriaId UUID.