CVE Validation Library

Official CVE Validation Library for validating CVE Records and CNA Containers.

Requirements

• Node.js >= 24.13.0 < 25
• ESM imports

Installation

Install from the default repository branch:

npm install --save git+https://github.com/CVEProject/cve-validation-library.git

Install from a specific branch, tag, release, or commit:

npm install --save git+https://github.com/CVEProject/cve-validation-library.git#{branch-name|tag|release|commit}

For example, to install from main:

npm install --save git+https://github.com/CVEProject/cve-validation-library.git#main

Usage

You can provide CVE Record data as an in-memory JSON object or read it from a JSON file.

Validate an in-memory CVE Record object:

import {
  Validate,
} from '@cveproject/cve-validation-library';

const validator = new Validate();

const cveRecord = {
  dataType: 'CVE_RECORD',
  dataVersion: '5.2',
  cveMetadata: {
    cveId: 'CVE-2026-0001',
    state: 'PUBLISHED',
  },
  containers: {
    cna: {
      providerMetadata: {
        orgId: '00000000-0000-4000-8000-000000000000',
        shortName: 'example',
        dateUpdated: '2026-01-01T00:00:00.000Z',
      },
      affected: [],
      descriptions: [
        {
          lang: 'en',
          value: 'Example description.',
        },
      ],
      references: [],
    },
  },
};

const cveRecordResult = await validator.validateCveRecord(cveRecord);

console.log(JSON.stringify(cveRecordResult, null, 2));

Read a CVE Record from a JSON file:

import {
  Validate,
  readJsonFile,
} from '@cveproject/cve-validation-library';

const validator = new Validate();

const cveRecord = await readJsonFile('cve-record.json');
const cveRecordResult = await validator.validateCveRecord(cveRecord);

console.log(JSON.stringify(cveRecordResult, null, 2));

TypeScript

import {
  type Diagnostics,
  type JsonObject,
  Validate,
  readJsonFile,
} from '@cveproject/cve-validation-library';

const validator = new Validate();

const cveRecord = await readJsonFile('cve-record.json') as JsonObject;
const cveRecordResult: Diagnostics = await validator.validateCveRecord(cveRecord);

console.log(JSON.stringify(cveRecordResult, null, 2));

Run the TypeScript file with tsx:

npm install -D tsx
npx tsx main.ts

Validation Methods

const validator = new Validate();

await validator.validateCveRecord(cveRecord);
await validator.validatePublishedCveCnaContainer(publishedCnaContainer);
await validator.validateRejectedCveCnaContainer(rejectedCnaContainer);

Published and rejected CNA Container validation expects a wrapper object with a cnaContainer property:

{
  "cnaContainer": {
    "descriptions": []
  }
}

Schema-only CNA Container methods are also available:

await validator.validatePublishedCveCnaContainerSchema(publishedCnaContainer);
await validator.validateRejectedCveCnaContainerSchema(rejectedCnaContainer);

Diagnostics

All validation methods return a Diagnostics object.

Examples

Successful validation:

{
  "valid": true,
  "error": null,
  "message": "SUCCESSFUL CVE JSON schema and rules validation.",
  "details": null,
  "warnings": []
}

Failed JSON schema validation:

{
  "valid": false,
  "error": "FAILED_JSON_SCHEMA_VALIDATION",
  "message": "CVE JSON schema is invalid",
  "details": {
    "errors": [
      {
        "instancePath": "/containers",
        "schemaPath": "#/oneOf/0/properties/containers/required",
        "keyword": "required",
        "params": {
            "missingProperty": "cna"
        },
        "message": "must have required property 'cna'"
      }
    ]
  },
  "warnings": []
}

Failed CVE rules validation:

{
  "valid": false,
  "error": "FAILED_RULES_VALIDATION",
  "message": "Invalid property/ies",
  "details": [
    {
      "msg": "datePublic cannot be a future date",
      "param": "containers.cna.datePublic"
    }
  ],
  "warnings": []
}

Custom warnings

Adding a warning is independent of CVE Record validation. It does not require a Diagnostics result and does not set or change validation status. Warnings are persisted by default in src/registry/cve-program/warnings.json:

import {
  addWarning,
  type DiagnosticWarning,
} from '@cveproject/cve-validation-library';

const warning: DiagnosticWarning = {
  messageId: 'CVE_SCHEMA_DEPRECATION',
  notificationMessage: 'This field will be removed in a future schema version.',
  notificationDetails: 'Use the replacement field before the warning end date.',
  schemaPath: '#/definitions/example/properties/deprecatedField',
  dateAdded: '2026-07-01T00:00:00.000Z',
  dateUpdated: '2026-07-02T00:00:00.000Z',
  dateStart: '2026-08-01T00:00:00.000Z',
  dateEnd: '2027-08-01T00:00:00.000Z',
  priority: 1,
};

addWarning(warning);

Validation methods load registered warnings into the warnings property of the Diagnostics result they return.

Use a custom registry file when the installed package directory is read-only or when warnings should be stored elsewhere:

import {
  WarningRegistry,
} from '@cveproject/cve-validation-library';

const registry = new WarningRegistry('./src/registry/cve-program/warnings.json');
registry.addWarning(warning);

WarningRegistry.addWarning also accepts the nine warning fields as positional arguments.

Create an idempotent stub warning in the default registry for local development:

npm run warning:stub

Exports

import {
  Diagnostics,
  Validate,
  ValidationErrors,
  WarningRegistry,
  addWarning,
  readJsonFile,
  resolveExistingPath,
  type JsonFilePath,
  type JsonObject,
  type JsonPrimitive,
  type JsonValue,
  type DiagnosticWarning,
  type ValidationError,
  type WarningRegistryPath,
} from '@cveproject/cve-validation-library';

Local Development

Install dependencies:

npm install

Build:

npm run build

Typecheck:

npm run typecheck

Run local smoke tests:

npm run test:local