Skip to content

nvd.md

Latest commit

 

History

History
166 lines (125 loc) · 5.15 KB

nvd.md

File metadata and controls

166 lines (125 loc) · 5.15 KB

NVD

NVD stands for National Vulnerability Database, which is the U.S. government repository of standards-based vulnerability management data. This database is maintained by NIST (National Institute of Standards and Technology).

Implementation Notes

The NVD integration uses the REST API (v2.0) available at services.nvd.nist.gov.

Search Parameters

While the NVD API supports CPE matching via parameters like cpeName and virtualMatchString, we've chosen not to use them for NPM packages. This decision was made because:

  1. The CPE format for npm packages is not standardized in NVD
  2. Attempted CPE patterns (like cpe:2.3:a:*:package-name:*:*:*:*:*:node.js:*:*) resulted in 404 errors
  3. Keyword search provides more flexible results for JavaScript/NPM packages

The implementation might be enhanced in the future if NVD provides clearer guidelines for CPE matching of npm packages.

Parameter Constraints

Some parameters have mutual exclusivity constraints enforced by the NVD API:

  • cvssV2Severity, cvssV3Severity, and cvssV4Severity cannot be combined with each other.
  • cvssV2Metrics, cvssV3Metrics, and cvssV4Metrics cannot be combined with each other.
  • keywordExactMatch requires keywordSearch to be set.
  • pubStartDate and pubEndDate must be used together; the maximum range is 120 days.
  • lastModStartDate and lastModEndDate must be used together; the maximum range is 120 days.

Format

The NVD API returns detailed vulnerability information.

The NVD interface is exported as root like StandardVulnerability.

export interface NVD {
  cve: Cve;
}

API

Constructor

import * as vulnera from "@nodesecure/vulnera";

const db = new vulnera.Database.NVD({
  credential: new vulnera.ApiCredential({
    type: "querystring",
    name: "apiKey",
    value: "your-api-key"
  })
});
export interface NVDOptions {
  credential: ApiCredential;
  /**
   * Delay in milliseconds between consecutive requests in findMany.
   *
   * The NVD API enforces rate limits:
   * - Without API key: 5 requests per 30-second window → set ~6 000 ms
   * - With API key:   50 requests per 30-second window → set ~600 ms
   *
   * @default 6000
   */
  requestDelay?: number;
}

Rate limiting: The NVD API enforces strict rate limits (see NVD developer docs). findMany sends requests sequentially with a requestDelay pause between each one to avoid being throttled. The default of 6 000 ms is safe for unauthenticated use. If you supply an API key you can safely lower it to ~600 ms.

find(parameters: NVDApiParameter): Promise<NVD[]>

Find vulnerabilities using any combination of available NVD API parameters.

export type NVDApiParameter = {
  // Keyword search
  keywordSearch?: string;
  keywordExactMatch?: boolean;

  // Convenience fields (used by findBySpec / findMany)
  packageName?: string;
  ecosystem?: string; // default: "npm"

  // CVE identification
  cveId?: string;
  cveTag?: "disputed" | "unsupported-when-assigned" | "exclusively-hosted-service";
  cweId?: string;
  sourceIdentifier?: string;

  // CVSS severity (mutually exclusive across versions)
  cvssV2Severity?: "LOW" | "MEDIUM" | "HIGH";
  cvssV3Severity?: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
  cvssV4Severity?: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";

  // CVSS vector strings (mutually exclusive across versions)
  cvssV2Metrics?: string;
  cvssV3Metrics?: string;
  cvssV4Metrics?: string;

  // Boolean flags
  noRejected?: boolean;
  hasKev?: boolean;
  hasCertAlerts?: boolean;
  hasCertNotes?: boolean;
  hasOval?: boolean;

  // Date ranges (ISO-8601, max 120-day window per pair)
  pubStartDate?: string;
  pubEndDate?: string;
  lastModStartDate?: string;
  lastModEndDate?: string;

  // Pagination
  resultsPerPage?: number; // default and max: 2000
  startIndex?: number;     // default: 0
};

Examples:

// Filter by CVSSv3 severity
const vulns = await db.find({ keywordSearch: "express", cvssV3Severity: "CRITICAL" });

// Return only CVEs in the CISA Known Exploited Vulnerabilities catalog
const kevVulns = await db.find({ keywordSearch: "log4j", hasKev: true });

// Paginate results
const page2 = await db.find({ keywordSearch: "lodash", resultsPerPage: 100, startIndex: 100 });

// Filter by publication date range
const recent = await db.find({
  pubStartDate: "2024-01-01T00:00:00.000Z",
  pubEndDate:   "2024-04-30T23:59:59.000Z"
});

findByCveId(cveId: string): Promise<NVD[]>

Find a specific vulnerability by its CVE identifier.

const vuln = await db.findByCveId("CVE-2021-44228");
console.log(vuln);

findBySpec(spec: string): Promise<NVD[]>

Find vulnerabilities of a given package using the NPM spec format packageName@version.

const vulns = await db.findBySpec("express@4.0.0");
console.log(vulns);

findMany<T extends string>(specs: T[]): Promise<Record<T, NVD[]>>

Find vulnerabilities for many packages using the spec format.

Returns a Record where keys are equal to the provided specs.

const vulns = await db.findMany(["express@4.0.0", "lodash@4.17.0"]);
console.log(vulns);