Skip to content

Comprehensive documentation overhaul #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sei-vsarvepalli merged 4 commits into from
Apr 2, 2026
Merged

Comprehensive documentation overhaul #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8a1ce6b
docs: comprehensive documentation overhaul
jgamblin Apr 1, 2026
1b63790
docs: remove screenshots from README
jgamblin Apr 1, 2026
221d9db
docs: refocus README for CNA audience, add CONTRIBUTING.md
jgamblin Apr 1, 2026
3ed3ddc
docs: add AI Review feature and local schema references to README
jgamblin Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 43 additions & 26 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,56 @@
# cveClient Changelog

Version 1.0.22 2025-06-26
* Resolved a bug as filled in #31 multiple versions under affected tree
* Moved from jquery .data() to .attr(data- to avoid unexpected behaviors.
* ProblemTypes can be array of array with only one dictionary object - fixed issue where m*n array can be consisten in JSON view and Friendly (Minimal) view.
## Version 1.0.24 — 2026-03-28

Version 1.0.21 2025-06-24
* Added a new version of CVE Chatbot
* Ask chatGPT button
* Fixed bugs on multi-row elements
- Security: Fixed XSS vulnerability — use `.text()` instead of `.html()` for CVE ID in modal title
- Security: Prevent plaintext API key storage and harden encryption key handling
- Security: Added prototype pollution protection to `queryParser` and removed sensitive logging
- Updated SweetAlert2 from 11.4.9 to 11.26.24
- Made schema references version-agnostic with automatic schema version detection
- Added ADP (Authorized Data Publisher) read and delete support

## Version 1.0.23 — 2025-12-15

Version 1.0.20 2023-08-21
- Updates to resolve bugs including security issues (CVE-pending)
- Updates after demo to CVE AWG
- Login bug fixes
- Updated `check_json` function validation

* Add schemaToJson.js generic library to support conversion of CVE schema
* Added updates to support viewing of full schema as presented by CVE5.0 schema
## Version 1.0.22 — 2025-06-26

- Resolved a bug as filed in #31 — multiple versions under affected tree
- Moved from jQuery `.data()` to `.attr("data-")` to avoid unexpected behaviors
- ProblemTypes can be array of array with only one dictionary object — fixed issue where m\*n array can be consistent in JSON view and Friendly (Minimal) view

Version 1.0.19 2023-08-21
## Version 1.0.21 — 2025-06-24

* Fixed some bugs on cveInterface.js related to apply_diff
* Added the ability to download CVE JSON from repositories for edit/duplicate
* Moved display capabilities using CSS.
- Added a new version of CVE Chatbot
- Ask ChatGPT button
- Fixed bugs on multi-row elements
- Added `cwe-common.json` for CWE autocomplete lookup

## Version 1.0.20 — 2023-08-21

Version 1.0.18 2023-08-09
- Added `schemaToForm.js` generic library to support conversion of CVE schema
- Added updates to support viewing of full schema as presented by CVE 5.0 schema

* Fixed some bugs on cveInterface.js related to from_json and to_json routines
* The cveclientLib on 1.0.14 now support ADP capability
* The User Management interface bug fixes on duplicate ID or duplicate name field fixed.
* ADP client interface is available only via JSON editor at this time.
* Require at least One product to have STatus "affected" or "unknown".
## Version 1.0.19 — 2023-08-21

Version 1.0.17 2023-08-09
* Allow entry of CVE data without being logged in just to create mock records
* Implemented offload download button for CVE records
* Fixed XSS issue due to changes to CVE Services RSUS interface
* Pagination issues resolved
- Fixed bugs on `cveInterface.js` related to `apply_diff`
- Added the ability to download CVE JSON from repositories for edit/duplicate
- Moved display capabilities using CSS

## Version 1.0.18 — 2023-08-09

- Fixed bugs on `cveInterface.js` related to `from_json` and `to_json` routines
- The `cveClientlib.js` on 1.0.14 now supports ADP capability
- User Management interface bug fixes on duplicate ID or duplicate name field
- ADP client interface is available only via JSON editor at this time
- Require at least one product to have status "affected" or "unknown"

## Version 1.0.17 — 2023-08-09

- Allow entry of CVE data without being logged in just to create mock records
- Implemented offload download button for CVE records
- Fixed XSS issue due to changes to CVE Services RSUS interface
- Pagination issues resolved
118 changes: 118 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Contributing to cveClient

This guide covers the technical details for developers contributing to cveClient.

## Architecture

cveClient is a pure client-side JavaScript application with no backend, no build system, and no transpilation.

### Core Files

| File | Description |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`cveClientlib.js`](./cveClientlib.js) | Reusable API client library. Class `cveClient` wraps the CVE Services REST API with `rfetch()` (Fetch API wrapper that injects API key auth). Methods for CVE CRUD, user management, and org info. |
| [`cveInterface.js`](./cveInterface.js) | Main UI logic (~2000 lines). Handles login/logout, CVE operations, user management, and form-to-JSON conversion. |
| [`schemaToForm.js`](./schemaToForm.js) | Dynamically generates HTML forms from the CVE JSON 5.x schema. Bidirectional: `FormToObject()` extracts JSON from form fields, `ObjectToForm()` populates forms from JSON. Fields linked via `data-field` attributes. |
| [`autoCompleter.js`](./autoCompleter.js) | Autocomplete/suggestion UI for input fields with dynamic URL fetching (used for CWE lookup). |
| [`encrypt-storage.js`](./encrypt-storage.js) | RSA-OAEP 4096-bit encryption for API keys in browser storage using Web Crypto API + IndexedDB for key persistence. |
| [`index.html`](./index.html) | Single-page app with Bootstrap modals for all operations. |

### How It Works

1. User logs in with CNA short name, username, and API key
2. API key is encrypted and stored in browser storage (localStorage or sessionStorage)
3. All API calls go directly from the browser to CVE Services — no proxy or middleware
4. The CVE JSON 5.x schema is fetched at runtime from the [CVE Schema Project](https://github.com/CVEProject/cve-schema) to dynamically generate the "All Fields" form
5. Form data is converted to/from CVE JSON using `data-field` attribute mappings

### Key Patterns

- Heavy jQuery DOM manipulation with Bootstrap modals
- Promise-based async/await for all API calls
- State: global `client` object (session), localStorage/sessionStorage (credentials), IndexedDB (encryption keys)
- Dynamic HTML generation for array fields (versions, descriptions, references) using `duplicate()`/`unduplicate()`
- Version branches named `version-X.X.X`, PRs merged to `main`

## Local Development

There is no build step. Serve the files from any local web server:

```bash
python3 -m http.server 8080
# or
npx serve .
# or
php -S localhost:8080
```

Then open `http://localhost:8080` in your browser.

**Note:** Opening `index.html` directly from the filesystem (`file://`) will not work — browsers block network requests from local files.

## Using cveClientlib in Node.js

The `cveClientlib.js` file includes conditional exports for Node.js environments. You can use it directly in Node.js scripts (`fetch` is available natively in Node 18+):

```javascript
const cveClient = require("./cveClientlib.js");

const client = new cveClient(
"your_org_short_name",
"your_username",
"your_api_key",
"https://cveawg.mitre.org/api",
);

// Get CVE details
client.getcvedetail("CVE-2024-1234").then(function (cve) {
console.log(JSON.stringify(cve, null, 2));
});

// Reserve a CVE ID
client.reservecve(1).then(function (result) {
console.log("Reserved:", result);
});

// Get org quota
client.getquota().then(function (quota) {
console.log("Quota:", quota);
});
```

For older Node.js versions without native `fetch`, use [node-fetch](https://github.com/node-fetch/node-fetch):

```javascript
const fetch = require("node-fetch");
globalThis.fetch = fetch;
const cveClient = require("./cveClientlib.js");
```

## Running Tests

Tests use [Vitest](https://vitest.dev/) with jsdom. Requires Node.js 22+.

```bash
npm ci
npm test
```

Test suites:

- **Pure function tests** (24 tests) — `get_deep`, `set_deep`, `simpleCopy`, `checkurl`, `check_json`, `queryParser`
- **Security regression tests** (13 tests) — prototype pollution protection, XSS prevention via `safeHTML` and `cleanHTML`
- **API client tests** (14 tests) — URL construction, auth headers, CVE/ADP operations

## Dependencies

All dependencies are for the HTML UI only. The `cveClientlib.js` library has zero dependencies.

| Library | Version | Source | Integrity |
| ----------------------------------------------- | ------- | ------ | ----------- |
| [jQuery](https://jquery.com/) | 3.5.1 | CDN | SHA-384 SRI |
| [Bootstrap](https://getbootstrap.com/) | 4.3.1 | CDN | SHA-384 SRI |
| [Popper.js](https://popper.js.org/) | 1.14.7 | CDN | SHA-384 SRI |
| [Bootstrap-Table](https://bootstrap-table.com/) | 1.19.1 | CDN | SHA-384 SRI |
| [SweetAlert2](https://sweetalert2.github.io/) | 11.x | Local | — |
| [Ace Editor](https://ace.c9.io/) | 1.2.4 | Local | — |

CDN dependencies use [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) (SRI) checks. SweetAlert2 and Ace Editor are served from local copies due to build issues with their CDN versions — please review their respective license agreements.
76 changes: 71 additions & 5 deletions INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,78 @@
### Installing cveClient on your webserver (apache2, IIS, nginx, tinyhttp)
# Installing cveClient

All the files in this repository are client utilities expected to served from a webserver to run inside a web browser. Directly accessing the index.html file inside a browser will NOT work as most browsers will not allow network activity from static files on your local or network attached drive/storage.
cveClient is a pure static web application — all files are served directly to the browser with no build step, no transpilation, and no server-side processing.

Clone this repository to a web accessible folder in your webserver says into a folder called `cveClient` using git command `git clone https://github.com/CERTCC/cveClient`. Once you have cloned this folder, you can visit your webserver's relative URL at `/cveClient/` to the folder where the repository was cloned. Ensure your webserver's default index file is `index.html`
## Quick Start (Local Development)

If you use Content-Security-Policy (CSP) headers on your webserver or on your web reverse proxy, make sure the appropriate domain URLs are allowed for the folder that was cloned (`cveClient`). Below is the sample Content-Security-Policy header recommended for this folder:
Any local web server will work. Pick whichever you have installed:

`default-src 'self' blob: http://127.0.0.1:* http://localhost:*; connect-src 'self' http://127.0.0.1:* http://localhost:* *.mitre.org; script-src 'self' https://stackpath.bootstrapcdn.com https://code.jquery.com https://cdnjs.cloudflare.com https://unpkg.com https://apis.google.com blob:; style-src 'self' https://stackpath.bootstrapcdn.com 'unsafe-inline' https://unpkg.com; img-src 'self' data: blob:;object-src 'self'`
```bash
# Python
python3 -m http.server 8080

# Node.js
npx serve .

# PHP
php -S localhost:8080

# Ruby
ruby -run -e httpd . -p 8080
```

Then open `http://localhost:8080` in your browser.

**Note:** Opening `index.html` directly from the filesystem (`file://`) will not work — browsers block network requests from local files.

## Production Deployment (Apache, Nginx, IIS)

Clone the repository into a web-accessible folder on your web server:

```bash
git clone https://github.com/CERTCC/cveClient.git /var/www/html/cveClient
```

Then visit your server's URL at `/cveClient/`. Ensure your web server's default index file includes `index.html`.

### Content-Security-Policy

If you use Content-Security-Policy (CSP) headers on your web server or reverse proxy, the following CSP is recommended for the cveClient folder:

```
default-src 'self' blob: http://127.0.0.1:* http://localhost:*;
connect-src 'self' http://127.0.0.1:* http://localhost:* *.mitre.org;
script-src 'self' https://stackpath.bootstrapcdn.com https://code.jquery.com https://cdnjs.cloudflare.com https://unpkg.com https://apis.google.com blob:;
style-src 'self' https://stackpath.bootstrapcdn.com 'unsafe-inline' https://unpkg.com;
img-src 'self' data: blob:;
object-src 'self'
```

### Apache Example

Add to your `.htaccess` or virtual host configuration:

```apache
<Directory /var/www/html/cveClient>
Header set Content-Security-Policy "default-src 'self' blob: http://127.0.0.1:* http://localhost:*; connect-src 'self' http://127.0.0.1:* http://localhost:* *.mitre.org; script-src 'self' https://stackpath.bootstrapcdn.com https://code.jquery.com https://cdnjs.cloudflare.com https://unpkg.com https://apis.google.com blob:; style-src 'self' https://stackpath.bootstrapcdn.com 'unsafe-inline' https://unpkg.com; img-src 'self' data: blob:; object-src 'self'"
</Directory>
```

### Nginx Example

```nginx
location /cveClient/ {
add_header Content-Security-Policy "default-src 'self' blob: http://127.0.0.1:* http://localhost:*; connect-src 'self' http://127.0.0.1:* http://localhost:* *.mitre.org; script-src 'self' https://stackpath.bootstrapcdn.com https://code.jquery.com https://cdnjs.cloudflare.com https://unpkg.com https://apis.google.com blob:; style-src 'self' https://stackpath.bootstrapcdn.com 'unsafe-inline' https://unpkg.com; img-src 'self' data: blob:; object-src 'self'";
}
```

## CVE Services Endpoints

The application connects to one of three CVE Services environments, selectable at login:

| Environment | URL |
| ----------- | ----------------------------------- |
| Production | `https://cveawg.mitre.org/api` |
| Test | `https://cveawg-test.mitre.org/api` |
| Local | `http://127.0.0.1:3000/api` |

If you need to connect to a different endpoint, modify the `<select>` element in `index.html` (around line 670).
Loading
Loading