npm package: @noah.jaffe/alpha
Description: TBD
Author: MITRE@The CVE Program
Latest version: 2.0.0-rc13

# CVE Core

## Overview

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.

## 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.


# Pre-requisites
#### All functionality is locked behind the following minimum requirements:
- `Node.js` (18+ required, 20+ reccomended.)
  - 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

#### Some functionality may require additional requirements:
- `Git`


#### Optional reccomended requirements:
- `Docker`, for hosting local instaces of external dependencies.
  - e.g. [Cve Services](#cve-services) as a local docker container.
- POSIX compliant shell, for cross compatability when running CLI scripts.
  - e.g. `Bash`, (or `Git Bash` for Windows)
- [`jq`](https://jqlang.github.io/jq/download/), for working with JSON files.



# Installation
Be sure to install the necessary [prequisites](#pre-requisites) before continuing here. 

There are multiple ways to install the packages.

<details>
  <summary>
    <h3>Option 1: Install via npm</h3>
  </summary>
  <ol>
    <li>
      <details>
        <summary>Install via npm.</summary>
        <pre>npm install git+https://github.com/CVEProject/[name].git</pre>
      </details>
    </li>
    <li>
      <details>
        <summary>Setup your .env file.</summary>
        <ul>
          <li>If you already have an existing .env file:<ul>
              <li>
                <pre>cat node_modules/[name]/.env-EXAMPLE >> .env</pre>
              </li>
          </li>
        </ul>
    <li>Or you can start a new .env from scratch with:<ul>
        <li>
          <pre>cp node_modules/[name]/.env-EXAMPLE .env</pre>
        </li>
    </li>
    </ul>
    <li>
      <details>
        <summary>Edit the variables needed. See the package's README and .env-EXAMPLE for additional comments and
          details on each variable.</summary>
    </li>
    <ul>
      <li><em><b>Note:</b> You may need to come back to this step later as some variables rely on installing other CVE
          Project packages.</em></li>
    </ul>
</details>
</details>
</li>
The CVE Project package is now installed! Double check your .env file!
</ol>
</details>

<details>
  <summary>
    <h3>Option 2: Build from source</h3>
  </summary>
  <ol>
    <li>
      <details>
        <summary>Clone the source repository.</summary>
        <pre>git clone https://github.com/CVEProject/[name].git</pre>
      </details>
    </li>
    <li>
      <details>
        <summary>Enter the newly cloned repository.</summary>
        <pre>cd [name]</pre>
      </details>
    </li>
    <li>
      <details>
        <summary>Build the package dependencies.</summary>
        <pre>npm i</pre>
      </details>
    </li>
    <li>
      <details>
        <summary>Setup your .env file.</summary>
        <ul>
          <li>If you already have an existing .env file:
            <ul>
              <li>
                <pre>cat node_modules/[name]/.env-EXAMPLE >> .env</pre>
              </li>
              <li>Or you can start a new .env from scratch with:
                <ul>
                  <li>
                    <pre>cp node_modules/[name]/.env-EXAMPLE .env</pre>
                  </li>
                </ul>
              </li>
            </ul>
          </li>
        </ul>
      </details>
    </li>
    <li>
      <details>
        <summary>Edit the variables needed. See the package's README and .env-EXAMPLE for additional comments and
          details on each
          variable.</summary>
        <ul>
          <li><em><b>Note:</b> You may need to come back to this step later as some variables rely on installing other
              CVE
              Project packages.</em></li>
        </ul>
      </details>
    </li>
    <li>
      <details>
        <summary><em>[Optional]</em> Run the tests.</summary>
        Note that you may need to complete the installation process of other CVE Project packages before you can run
        some of the tests.
        <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>
      </details>
    </li>
    <li>
      <details>
        <summary>Build the project.</summary>
        <pre>npm run build</pre>
      </details>
    </li>
    The CVE Project package is now installed! Double check your .env file!
  </ol>
</details>



---

## Using the package in code
After installing the package:

`const CveCore = require('cve-core');`

or

`import { * as CveCore } from 'cve-core';`

then use it

`CveCore.CveId.isValidCveId('CVE-1999-0001');`


## Using the package as a command line:

Run the following in the command line after installing or building the cve-core package.
```
npx cves --help
npx cves date
```
or
```
./cves.sh --help
./cves.sh date
```
<sub>_To ensure compatability with DOS/Windows based operating systems, we have provided `./cves.bat` as an alternative for `./cves.sh`._</sub>

----

# Additional 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).


#### OpenSearch

TBD: Release opensearch info?
inside cve-search repo:
- `docker compose up`
- unzip 1000cves.zip
- `./prep.sh`
- ...?



### 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.

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.


## 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.

### History

See [`ChangeLog.md`](./ChangeLog.md) for a full history of this project.