CVE Core

Overview

This CVE project implements the cve-core common library containing the general purpose core classes for interacting with CVEs and CVE services. The intent is for this library to become a public npm package, where it can be used in any Typescript or Javascript (ESM) application to simplify and standardize working with CVEs and CVE services.

Versioning

The first version of this library is version 2.0.0. This is because the capabilities of this library have already been in use in cvelistV5, and to preserve the versioning of capabilities, we decided to start this library at 2.0.0. See the ChangeLog for specific details.

Usage

There are 2 ways to use this library:

1. as an npm package (note this is not yet publicly available in version 2.0.0)
2. as a "sibling project import" (this is the only way to use this library in version 2.0.0). This approach is useful when you need to both make changes to cve-core and your project, since it allows changing code in either repository without needing to publish a new version.

Pre-Requisites

You only need the following to use or develop this library:

• a modern NodeJS (see package.json's engines.node value for supported versions) to develop and/or run this project. The easiest way to do this is to use nvm.
• (optional) jq for working with JSON files

External dependencies

CVE Services

To test or develop for cve-services, you will need to have an instance of CVE Services to point to.

.Env variables to be required:

• CVE_SERVICES_URL - URL for cve-services.
• CVE_API_ORG - The org short name for the user.
• CVE_API_USER - The user name.
• CVE_API_KEY - The key for this org user.

To test against a local version of cve-services you will need to build the cve-services docker container. See here for docker build instructions. Note: If you are developing on windows you may want to check out this comment explaining why your build may not be working.

As NPM Package

This project is not yet set up to be used as an NPM package.

As a "Sibling Project Import"

This setup allows you to work on this library project and the application project simultaneously. It is currently the only way to use this library.

To use it this way, the directory location of this library and that of your application must be maintained in a strict hierarchical fashion as can be seen below. This is because when we run npm install cve-core later in the instructions, npm will make a soft link to the files in this repository from <your-app>.

<cveProjects>
├── cve-core
└── <your-app>

1. clone 2 (or more) repositories into a common parent directory (cveProjects as an example)
   1. mkdir cveProjects
   2. cd cveProjects
   3. git clone git@gitlab.mitre.org:cve-projects/cve-core.git
   4. pushd cve-core && git checkout <branch> && npm i && popd (sets cve-core to a modern, stable branch, but you can set to any branch in cve-core). Your project may contain a cve-layers section in the package.json to specify a specific branch needed. If not, use the develop branch for a stable version with the latest functionality
   5. git clone <url-to-your-app> <your-app>
   6. cd <your-app>
2. set up tokens/secrets/environment variables by making a .env file in the root directory.
   • Copy .env-EXAMPLE as a starting point
   • You will need to replace the <var> variables with your own credentials for this app to work
3. npm i to load dependencies.
4. For development, look at package.json's scripts for available npm scripts
   • of special interest is the npm run build command, which builds this project into a single index.js file that contains all the necessary code and libraries to run as a Github action or to be used with cves.sh as a CLI. This is a useful step to check that the code "compiles"
5. Run ./cves.sh --help¹ for help on using the commands.

Fixtures

There are several fixtures directories in this project:

1. ./cves - a partial and not necessarily up-to-date collection of CVEs arranged in the expected cvelistV5 project location. The files here are NOT intended to be up-to-date with actual CVE content. If they are outdated, they should remain outdated for tests already written using them. It may also contain test-only fake CVEs in ./cves/1970/. This is to be considered the de facto location for CVE test files that needs to be verified in the expected locations when deployed.

2. ./test/fixtures - collection of subdirectories for specific tests. For example, ./test/fixtures/cve/5 contain test files that are copied and then maninpulated during testing for specific purposes.

For src/core/Delta.test.ts to work properly, do not commit pretend_github_repository/1970/0xxx/CVE-1970-0999.json. It is intended to be copied from fixtures during testing to test that a new file shows up in the new list of an activity's delta.

Testing

There are 2 npm scripts for running tests. Most of the time, just running

npm test

should do it. However, there are times, when tests in git.test.ts and gitSync.test.ts fail due to the way Jest runs everything in parallel, and some tests in those files will report errors because of race conditions. To mitigate this, run npm run test first, and if you get errors in any of the git test files, re-run Jest using npm run test-serial to run tests in "runInBand" (that is, one at a time in serial) mode. This approach is slower, but should solve any race conditions that may occur during testing.

Environment Variables and Secrets

There are 3 CVE-related "secret" environment variables: CVE_API_KEY, CVE_API_ORG, and CVE_API_USER. These need to be defined as specified in the Setup section above.

Version Conventions

The version for this library is specified in the package.json's version field. The convention is:

• follow semver for released software: Major.Minor.Patch, e.g., 2.0.4.
• deviate from semver during development and testing, using the following syntax instead
  • the version number that it branched from, appending to it +feature_YYYY-MM-DD, e.g., 2.0.0+search_2025-01-24, where the date is the date that the npm run build command was built. For frequently updated code, you can also append aHH or pHH for AM and PM local timestamps.

History

See `ChangeLog.md for a full history of this project.

Footnotes

Footnotes

1. To ensure compatability with DOS/Windows based operating systems, we have provided ./cves.bat as an alternative for ./cves.sh. ↩