You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This CVE project implements the `cve-core` common library containing the general purpose core classes for interacting with CVEs and services related to CVEs. 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 help standardize working with CVEs and CVE services.
5
+
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.
6
6
7
7
## Versioning
8
8
9
9
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.
10
10
11
+
## Usage
11
12
12
-
# Pre-requisites
13
-
#### All functionality is locked behind the following minimum requirements:
14
-
-`Node.js` (18+ required, 20+ reccomended.)
15
-
- You may want to use [`nvm`](https://github.com/nvm-sh/nvm) (or [nvm for windows](https://github.com/coreybutler/nvm-windows/releases)) to install Node.JS
16
-
17
-
#### Some functionality may require additional requirements:
18
-
-`Git`
19
-
20
-
21
-
#### Optional reccomended requirements:
22
-
-`Docker`, for hosting local instaces of external dependencies.
23
-
- e.g. [Cve Services](#cve-services) as a local docker container.
24
-
- POSIX compliant shell, for cross compatability when running CLI scripts.
25
-
- e.g. `Bash`, (or `Git Bash` for Windows)
26
-
-[`jq`](https://jqlang.github.io/jq/download/), for working with JSON files.
27
-
28
-
29
-
30
-
# Installation
31
-
Be sure to install the necessary [prequisites](#pre-requisites) before continuing here.
<summary>Edit the variables needed. See the package's README and .env-EXAMPLE for additional comments and
125
-
details on each
126
-
variable.</summary>
127
-
<ul>
128
-
<li><em><b>Note:</b> You may need to come back to this step later as some variables rely on installing other
129
-
CVE
130
-
Project packages.</em></li>
131
-
</ul>
132
-
</details>
133
-
</li>
134
-
<li>
135
-
<details>
136
-
<summary><em>[Optional]</em> Run the tests.</summary>
137
-
Note that you may need to complete the installation process of other CVE Project packages before you can run
138
-
some of the tests.
139
-
<pre># For running asynchronously</br>npm run test<br><br># For running synchronously<br>npm run test:serial<br><br># Or run tests and view coverage<br>npm run coverage<br># You can find the report file at <b>/coverage/lcov-report/index.html</b>.</pre>
140
-
</details>
141
-
</li>
142
-
<li>
143
-
<details>
144
-
<summary>Build the project.</summary>
145
-
<pre>npm run build</pre>
146
-
</details>
147
-
</li>
148
-
The CVE Project package is now installed! Double check your .env file!
149
-
</ol>
150
-
</details>
151
-
152
-
153
-
154
-
---
155
-
156
-
## Using the package in code
157
-
After installing the package:
158
-
159
-
`const CveCore = require('cve-core');`
160
-
161
-
or
162
-
163
-
`import { * as CveCore } from 'cve-core';`
164
-
165
-
then use it
166
-
167
-
`CveCore.CveId.isValidCveId('CVE-1999-0001');`
168
-
169
-
170
-
## Using the package as a command line:
171
-
172
-
Run the following in the command line after installing or building the cve-core package.
173
-
```
174
-
npx cves --help
175
-
npx cves date
176
-
```
177
-
or
178
-
```
179
-
./cves.sh --help
180
-
./cves.sh date
181
-
```
182
-
<sub>_To ensure compatability with DOS/Windows based operating systems, we have provided `./cves.bat` as an alternative for `./cves.sh`._</sub>
13
+
There are 2 ways to use this library:
14
+
1. as an npm package (note this is not yet publicly available in version 2.0.0)
15
+
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.
16
+
17
+
### Pre-Requisites
183
18
184
-
----
19
+
You only need the following to use or develop this library:
20
+
- 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).
21
+
- (optional) [`jq`](https://jqlang.github.io/jq/download/) for working with JSON files
To test or develop for cve-services, you will need to have an instance of CVE Services to point to.
@@ -197,16 +35,38 @@ To test or develop for cve-services, you will need to have an instance of CVE Se
197
35
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).
198
36
199
37
200
-
#### OpenSearch
38
+
### As NPM Package
39
+
40
+
This project is not yet set up to be used as an NPM package.
41
+
42
+
43
+
### As a "Sibling Project Import"
44
+
201
45
202
-
TBD: Release opensearch info?
203
-
inside cve-search repo:
204
-
-`docker compose up`
205
-
- unzip 1000cves.zip
206
-
-`./prep.sh`
207
-
- ...?
46
+
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.
208
47
48
+
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>`.
209
49
50
+
```bash
51
+
<cveProjects>
52
+
├── cve-core
53
+
└── <your-app>
54
+
```
55
+
56
+
1. clone 2 (or more) repositories into a common parent directory (`cveProjects` as an example)
4.`pushd cve-core && git checkout <branch> && npm i && popd` (sets cve-core to a modern, stable branch, but you can set <branch> 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
61
+
5.`git clone <url-to-your-app> <your-app>`
62
+
6.`cd <your-app>`
63
+
2. set up tokens/secrets/environment variables by making a `.env` file in the root directory.
64
+
- Copy `.env-EXAMPLE` as a starting point
65
+
- You will need to replace the `<var>` variables with your own credentials for this app to work
66
+
3.`npm i` to load dependencies.
67
+
4. For development, look at `package.json`'s `scripts` for available `npm` scripts
68
+
- 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"
69
+
5. Run `./cves.sh --help`[^1] for help on using the commands.
210
70
211
71
### Fixtures
212
72
@@ -218,13 +78,32 @@ There are several fixtures directories in this project:
218
78
219
79
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.
220
80
221
-
There is also the cve-fixtures repo that is intended for int and e2e testing. You may add files, but you may not modify or remove files once they end up in the cve-fixtures main branch. Keep the size of the cve-fixtures repository small enough where a clone will not take a significant amount of time.
81
+
### Testing
82
+
83
+
There are 2 `npm` scripts for running tests. Most of the time, just running
84
+
85
+
```bash
86
+
npm test
87
+
```
222
88
89
+
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.
223
90
224
91
## Environment Variables and Secrets
225
92
226
93
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.
227
94
95
+
## Version Conventions
96
+
97
+
The version for this library is specified in the `package.json`'s `version` field. The convention is:
98
+
99
+
- follow semver for released software: Major.Minor.Patch, e.g., `2.0.4`.
100
+
- deviate from semver during development and testing, using the following syntax instead
101
+
- 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.
102
+
103
+
228
104
### History
229
105
230
-
See [`ChangeLog.md`](./ChangeLog.md) for a full history of this project.
106
+
See [`ChangeLog.md](./ChangeLog.md) for a full history of this project.
107
+
108
+
### Footnotes
109
+
[^1]: To ensure compatability with DOS/Windows based operating systems, we have provided `./cves.bat` as an alternative for `./cves.sh`.
0 commit comments