CVE Validation Library

The CVE Validation Library is the official library maintained by the CVE Project for validating CVE Records and CNA Containers to support better quality across the CVE vulnerability management ecosystem. Serving as a foundational backend tool, it is directly utilized by the CVE Program publishing server (i.e, CVE Services) to verify all incoming records before they are officially accepted and distributed to the CVE List.

When analyzing data, the library yields diagnostic insights by capturing both severe validation errors (such as failed JSON schema parameters or broken rules) and actionable warnings (such as pending schema deprecations). It is designed to act as the primary, living enforcement mechanism for CVE publishing. It will be continuously maintained and updated to enforce the official CVE Records validation rules as formatting requirements evolve over time.

Third-Party Integration

While built to power the central publication server infrastructure, this library is also explicitly designed for third parties interacting with the CVE List Repository. Independent developers, security researchers, and CNAs can import this package into their local utilities, automation scripts, or automated workflows. By pre-validating CVE data client-side before attempting to commit or submit records to the repository, third parties can ensure immediate acceptance, reduce submission friction, and ensure their localized vulnerability feeds perfectly match official standards.

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

The Validation Flow Diagram shows the steps for each of these three 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": []
  }
}

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": []
}

Failed leading and trailing whitespace trimming:

The three full validation methods listed under Validation Methods trim leading and trailing whitespace from string values in place before validation. This includes strings in nested objects and arrays. Keys, internal whitespace, and non-string values are preserved.

In the rare occurance that the whitespace trimming throws an error, validation stops and returns diagnostics with:

{
  "valid": false,
  "error": "FAILED_JSON_WHITESPACE_TRIMMING",
  "message": "trimJSONWhitespace failed",
  "details": {
      "errors": ["{original-error-message}"]
  },
  "warnings": []
}

CVE Program Warning

CVE Program warnings are supported that can only be added by CVE Program members at the moment.

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.

Exports

import {
  Diagnostics,
  Validate,
  ValidationErrors,
  WarningRegistry,
  addWarning,
  readJsonFile,
  resolveExistingPath,
  trimJSONWhitespace,
  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

Validation Flow Diagram

flowchart TD
    A["Input: CVE record or CNA container"] --> B["Trim whitespace in place"]
    B -->|Failure| W["Return FAILED_JSON_WHITESPACE_TRIMMING"]
    B -->|Success| C["Validate JSON schema"]
    C -->|Failure| S["Return FAILED_JSON_SCHEMA_VALIDATION"]
    C -->|Success| D["Check duplicate English language codes"]
    D -->|Pass| E["Check descriptions contain text"]
    D -->|Fail| F["Return FAILED_RULES_VALIDATION"]
    E -->|Fail| F
    E -->|Pass| T{"Container type"}
    T -->|Rejected CNA container| OK["Return success"]
    T -->|CVE record or Published CNA container| G["Check datePublic with 24-hour grace period"]
    G -->|Fail| F
    G -->|Pass| H["Check timeline dates"]
    H -->|Fail| F
    H -->|Pass| I["Check PURL syntax and restrictions"]
    I -->|Fail| F
    I -->|Pass| OK

Loading