Skip to content

nvd_client.config

Client configuration.

NVD publishes two rolling windows (https://nvd.nist.gov/developers/start-here):

  • without an API key, 5 requests in 30 seconds
  • with an API key, 50 requests in 30 seconds

The default rate_limit_delay leaves one request's worth of that window between calls (6 seconds, or 0.6 seconds when a key is set). Set the delay yourself to slow down further. NIST also recommends sleeping for several seconds between requests so bursts are not rejected.

Classes:

Attributes:

MAX_CVE_RESULTS_PER_PAGE module-attribute 

MAX_CVE_RESULTS_PER_PAGE = 2000

MAX_CPE_RESULTS_PER_PAGE module-attribute 

MAX_CPE_RESULTS_PER_PAGE = 500

RATE_LIMIT_WINDOW_SECONDS module-attribute 

RATE_LIMIT_WINDOW_SECONDS = 30

RATE_LIMIT_REQUESTS_WITHOUT_KEY module-attribute 

RATE_LIMIT_REQUESTS_WITHOUT_KEY = 5

RATE_LIMIT_REQUESTS_WITH_KEY module-attribute 

RATE_LIMIT_REQUESTS_WITH_KEY = 50

DEFAULT_BASE_URL module-attribute 

DEFAULT_BASE_URL = 'https://services.nvd.nist.gov/rest/json'

DEFAULT_USER_AGENT module-attribute 

DEFAULT_USER_AGENT = f'nvd-client/{__version__} (+https://github.com/ahur4/nvd-client)'

NvdConfig dataclass 

NvdConfig(base_url: str = DEFAULT_BASE_URL, api_key: str | None = None, timeout: float | tuple[float, float] = 30.0, results_per_page: int = MAX_CVE_RESULTS_PER_PAGE, cpe_results_per_page: int = MAX_CPE_RESULTS_PER_PAGE, rate_limit_delay: float | None = None, max_retries: int = 4, backoff_factor: float = 1.0, max_backoff: float = 60.0, user_agent: str = '', proxy: str | None = None)

Settings for nvd_client.api.NvdApi.

The object is frozen. Build a new config and a new client to change it. An empty api_key is stored as None. Naive date values are not configured here; see nvd_client.utils.format_nvd_datetime.

timeout is passed to requests and may be a single seconds value or a (connect, read) pair. results_per_page is the CVE default (NVD's maximum is 2000). CPE Match calls use cpe_results_per_page (NVD's maximum is 500).

max_retries is the number of additional attempts after the first request. Retries cover connection errors and HTTP 403, 429, 500, 502, 503, and 504. backoff_factor seconds grow as backoff_factor * 2**attempt, capped by max_backoff. A Retry-After header replaces that delay.

Attributes:

base_url class-attribute instance-attribute 

base_url: str = DEFAULT_BASE_URL

api_key class-attribute instance-attribute 

api_key: str | None = None

timeout class-attribute instance-attribute 

timeout: float | tuple[float, float] = 30.0

results_per_page class-attribute instance-attribute 

results_per_page: int = MAX_CVE_RESULTS_PER_PAGE

cpe_results_per_page class-attribute instance-attribute 

cpe_results_per_page: int = MAX_CPE_RESULTS_PER_PAGE

rate_limit_delay class-attribute instance-attribute 

rate_limit_delay: float | None = None

max_retries class-attribute instance-attribute 

max_retries: int = 4

backoff_factor class-attribute instance-attribute 

backoff_factor: float = 1.0

max_backoff class-attribute instance-attribute 

max_backoff: float = 60.0

user_agent class-attribute instance-attribute 

user_agent: str = ''

proxy class-attribute instance-attribute 

proxy: str | None = None

effective_rate_limit_delay property 

effective_rate_limit_delay: float

Seconds to wait between HTTP calls.

An explicit rate_limit_delay wins. Otherwise the delay is the published window divided by the allowed number of requests.