Offline CVSS Scoring Made Simple: A Zero-Dependency JavaScript Library

Scoring CVSS vectors is a common need in vulnerability management, but most solutions rely on network calls or heavy dependencies. Enter @hailbytes/cvss-calc, a lightweight JavaScript library that parses and scores CVSS vectors entirely offline — no internet, no build steps, and no third-party APIs. With support for both v3.1 and v4.0, this 4 KB package fits seamlessly into CI pipelines, web pages, or any JavaScript environment. Below, we answer the most common questions about using it.

What is the @hailbytes/cvss-calc library and why was it created?

The @hailbytes/cvss-calc library is a zero-dependency JavaScript module that parses and scores CVSS vectors according to the official FIRST specifications (v3.1 and v4.0). It was built to solve a specific problem: scoring vectors inside CI runners that have no internet access. Many existing solutions either call out to the NVD API (slow, rate-limited, requires network egress) or pull in large dependencies that bloat your project. This library avoids both issues. At just 4 KB, it provides a single function — calculate() — that takes a CVSS vector string and returns an object with the numeric score, severity rating, and vector details. No external calls, no complex setup.

How do you score a CVSS vector using this library?

Scoring a vector is as simple as two lines of code. First, import the calculate function from the package. Then, pass your CVSS vector string to it. For example:

import { calculate } from '@hailbytes/cvss-calc';
const result = calculate('CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H');
// { score: 9.8, severity: 'Critical', version: '3.1', vector: '...' }

The library automatically detects the CVSS version from the vector string and applies the correct scoring algorithm. No flag, no conditional logic at the call site. The returned object includes score (a number), severity (a string like 'Critical'), version (e.g., '3.1' or '4.0'), and the original vector. It works identically for v4.0 vectors. You can install it via npm with npm install @hailbytes/cvss-calc and use it in any Node.js or browser environment.

Does the library support both CVSS v3.1 and v4.0?

Yes, fully. The library parses the vector string and automatically detects whether it is a v3.1 or v4.0 vector. For instance, a vector starting with CVSS:4.0 will be scored using the v4.0 specification, which includes additional metrics like Attack Complexity (AT) and Confidentiality/Integrity/Availability (VC, VI, VA). The same calculate() function handles both versions. Here's an example with a v4.0 vector:

const v4 = calculate('CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N');
// { score: 10.0, severity: 'Critical', version: '4.0', vector: '...' }

This approach eliminates the need for branching logic in your application. The library also handles invalid or malformed vectors gracefully, throwing clear errors for debugging.

Can I use this library as a web component on a webpage?

Absolutely. The package includes a custom web component that renders an interactive CVSS calculator in any HTML page. Just include the script from a CDN (like jsDelivr) and use the custom HTML tag <hailbytes-cvss-calc> with a vector attribute. For example:

<script type="module" src="https://cdn.jsdelivr.net/npm/@hailbytes/cvss-calc/dist/element.js"></script>
<hailbytes-cvss-calc vector="CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"></hailbytes-cvss-calc>

The component displays a fully interactive calculator where users can adjust metric values and see the score update in real time. You can listen for cvss-calculated events on the element to read the score programmatically. This is perfect for status pages, ticketing systems, or any scenario where you want to present a CVSS score with an editable interface.

What are some practical use cases for this library?

The library shines in environments where network access is limited or speed is critical. Three common use cases are:

• CI/CD gate for pre-deploy security: A CI pipeline that scans an SBOM (software bill of materials) for CVEs, scores them offline, and fails the build if any CVE scores ≥ 7.0 (High or Critical).
• Ticket prioritization in Jira: Automatically assign severity labels or priority levels to Jira issues based on CVSS scores from vulnerability reports.
• Static status pages: Embed the interactive web component on a status page that lists disclosed CVEs, allowing visitors to explore the impact of each vulnerability.

Because the library has zero dependencies and is only 4 KB, it loads instantly and fits into any project without adding bloat.

How does this library compare to using the NVD API?

Using the NVD (National Vulnerability Database) API to score CVSS vectors has several drawbacks: it requires a network connection (problematic in air-gapped or offline CI runners), it is rate-limited (slowing down bulk scoring), and it introduces latency and potential external dependency failures. In contrast, @hailbytes/cvss-calc works entirely offline — no network calls are made at any point. It also has no external dependencies, meaning you don't pull in any additional libraries (like old crypto modules). The library is deterministic and fast: scoring a vector takes microseconds. If you need to score hundreds of vectors in a batch, you can do so without worrying about API quotas or internet access. The only thing you lose is the dynamic database of CVEs, but for pure vector parsing and scoring, offline is both simpler and more reliable.

Is the library free and where can I find the source code?

Yes, the library is completely free and open source under the MIT license. You can use it in commercial projects, modify it, and distribute it freely. The source code and full documentation are available on GitHub at github.com/hailbytes/cvss-calc. Installation is straightforward via npm: npm install @hailbytes/cvss-calc. The repository includes API reference, examples for both Node.js and browser usage, and instructions for building the web component from source. Community contributions and bug reports are welcome.