https://github.com/cveproject/cve-core
A Javascript/Typescript library containing general purpose classes for interacting with CVEs
https://github.com/cveproject/cve-core
Last synced: 19 days ago
JSON representation
A Javascript/Typescript library containing general purpose classes for interacting with CVEs
- Host: GitHub
- URL: https://github.com/cveproject/cve-core
- Owner: CVEProject
- License: cc0-1.0
- Created: 2025-07-11T13:40:05.000Z (7 months ago)
- Default Branch: dev
- Last Pushed: 2025-08-28T17:39:21.000Z (5 months ago)
- Last Synced: 2025-08-28T23:56:07.276Z (5 months ago)
- Language: TypeScript
- Homepage:
- Size: 755 KB
- Stars: 0
- Watchers: 0
- Forks: 2
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/CVEProject/cvelistV5), and to preserve the versioning of capabilities, we decided to start this library at 2.0.0. See [the ChangeLog](./ChangeLog.md) 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](https://github.com/nvm-sh/nvm).
- (optional) [`jq`](https://jqlang.github.io/jq/download/) for working with JSON files
### External dependencies
#### [CVE Services](https://github.com/CVEProject/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](https://github.com/CVEProject/cve-services/blob/dev/README.md#docker). Note: [If you are developing on windows you may want to check out this comment explaining why your build may not be working](https://github.com/CVEProject/cve-services/issues/1171#issuecomment-2688313720).
### 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 ``.
```bash
├── cve-core
└──
```
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 && 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 `
6. `cd `
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 `` 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`[^1] 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](https://github.com/CVEProject/cvelistV5) 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
```bash
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](./ChangeLog.md) for a full history of this project.
### Footnotes
[^1]: To ensure compatability with DOS/Windows based operating systems, we have provided `./cves.bat` as an alternative for `./cves.sh`.