CVE-API

Table of contents

• Project
• Contributing
  • OSS Contributor
  • Working Groups
  • Security
    • Reporting a Vulnerability
• Development
  • Technologies
  • Style Guidelines
  • Setup
  • API Documentation
  • CVE ID Year Activation
  • CVE Record Submission Validation Rules
  • Testing
• Data Registry

The CVE Services Project

This repository contains services that support the CVE Program's mission to "identify, define, and catalog publicly disclosed cybersecurity vulnerabilities."

Contributing

There are many ways one can assist:

OSS Contributor

Developers can contribute code directly. Getting started can be as fast as choosing an issue on our board.

Please read our contributor's guide for more details. We welcome all contributions!

Working Groups

The CVE project operates as multiple focused working groups. Visit the CVE Website working groups page for more information.

Security

Reporting a Vulnerability

Warning Do not put vulnerability information in a GitHub issue.

Please consult our SECURITY.md for specific instructions on reporting a vulnerability that exists in the CVE Services.

Development

Technologies

This project uses:

• Node.js 24.22.1 for local development and the production image build; CI and the development Docker image use Node.js 24.
• Express
• MongoDB replica sets for local development and testing
• Amazon DocumentDB in production
• Mongoose.js

Style Guidelines

This project follows the JavaScript Standard Style.

Setup

Run the commands below from the repository root. After cloning or updating the checkout, initialize the migrations submodule before setting up either a local application or the development Docker image:

git submodule update --init migrations

Docker

See the Docker README to run both the application and MongoDB in containers.

Local Development

Warning

DO NOT use the dev configuration on a public network. The dev environment includes credentials to enable rapid development and is not secure for public deployment.

Install dependencies

Install Node.js 24.22.1 with its bundled npm, then install the application and migration dependencies:

npm ci
npm ci --prefix migrations --include=dev

The migration tooling is a development dependency in the submodule. Repeat its install after updating the submodule.

Start MongoDB and configure the connection

The application uses transactions, so local MongoDB must run as a replica set. The Mongo-only Compose file starts one primary and two secondary members for an application running on the host:

docker compose -f docker/docker-compose.mongo-cluster.yml up -d docdb docdb-read-1 docdb-read-2 mongo-init
docker compose -f docker/docker-compose.mongo-cluster.yml logs -f mongo-init

Wait for Replica set is ready with one primary and two secondaries. before continuing. Press Ctrl+C to leave the log view; the containers keep running.

Set these local development values in a .env file at the repository root:

LOCAL_KEY=TCF25YM-39C4H6D-KA32EGF-V5XSHN3
MONGO_CONN_STRING=mongodb://127.0.0.1:27017,127.0.0.1:27018,127.0.0.1:27019/cve_dev?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false
TEST_PORT=3001

LOCAL_KEY is the API key assigned to all users created by local population. The example above is the public fixture key used by the integration suite. The connection string selects cve_dev; config/default.json supplies the default development and test database settings when no connection override is present. Leave MONGO_DB_NAME unset for this setup. If overriding it for population or migrations, keep it consistent with the database in the connection string.

MongoDB Compass is optional and can use the same connection string. Population creates the database; it does not need to be created manually. See the Mongo-only Docker instructions for image overrides and volume management.

Populate data or apply migrations

To load sample data and apply migrations, run the following command. It prompts before dropping and rebuilding the entire development database:

npm run populate:dev

To load sample data and apply migrations separately:

npm run populate:dev -- --skip-migrations
npm run db:migrate:dev

To check and apply migrations without resetting existing data:

NODE_ENV=development npm run db:migrate:status
npm run db:migrate:dev

Start the application

npm run start:dev

The default local port is 8081, configurable with PORT. Swagger UI is available at http://localhost:8081/api-docs/ once the application connects to the database. API routes use the /api/ prefix. The example TEST_PORT=3001 gives the integration suite a separate listener port. The full Docker setup uses port 3000.

API Documentation

Use the Swagger documentation for the instance you are calling:

• Test Instance
• Production

Available endpoints may differ between deployments.

Organization and user APIs are grouped under Data Registry and Legacy. Related endpoint links help compare their request formats and permissions. Utilities appears last.

Documentation is generated from route annotations and schemas. After updating them, run:

npm run swagger-autogen

npm run start:dev also generates documentation at startup. For later changes, rerun the generator and reload Swagger UI. Do not edit the generated api-docs/openapi.json directly.

CVE ID Year Activation

A year is activated automatically when an eligible CVE ID reservation is made:

• The current year can be activated at any time.
• A future year can be activated within 90 days before January 1 of that year.
• Past years are never activated automatically.

Secretariat users can activate any year using POST /api/cve-id-range/{year}. Once a year is active, the activation window no longer applies. Reservations still follow normal permissions and quota limits. See the API documentation for endpoint details.

CVE Record Submission Validation Rules

As part of submission processing, CVE Services validates requirements before accepting a CVE Record. See the CVE Record Submission Validation Rules for more information.

Testing

Run the Mocha and Chai unit tests with:

npm run test:unit-tests

Integration tests require a local replica set and reset and repopulate the selected test database before running. See the testing README for setup and commands, including the host replica and Docker configurations.

Data Registry

The Data Registry modernizes how CVE Program organizations, including CNAs, Roots, Top-Level Roots, and the Secretariat, manage organization information, hierarchy, users, and roles. Production rollout has begun and continues incrementally. Consult the target instance's API documentation for the operations available in that deployment.

The Data Registry APIs under /api/registry/ coexist with the legacy organization and user APIs. Data Registry operations use richer organization and user schemas, JSON bodies for updates, dedicated role operations, and review workflows where applicable. Legacy endpoints remain available, but switching to Data Registry endpoints requires checking the request and response schemas, permissions, and approval behavior rather than only changing the URL.

Credentialed users can access the APIs with tools such as curl or Postman, or use the Data Registry client. The client repository retains its earlier cve-user-registry-client name.

Report bugs and suggest improvements on the CVE Services issue board. See Contributing for ways to participate.