CVSS Scoring Engine

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/components/CVSSGenericCalculator.tsx
• src/components/CVSSVersionsTabs.tsx
• src/components/FAQAccordion.tsx
• src/lib/constants.ts
• src/lib/cvss/metrics-data.ts
• src/lib/cvss/types.ts
• src/lib/cvss/v2/index.ts
• src/lib/cvss/v2/scoring.ts
• src/lib/cvss/v3/scoring.ts
• src/lib/cvss/v4/scoring.ts
• src/lib/embed.ts

The CVSS Scoring Engine is a core module within the Quant application responsible for calculating Common Vulnerability Scoring System (CVSS) scores. It is a pure TypeScript/JavaScript library that provides fast, accurate, and offline-capable scoring for multiple CVSS versions (v4.0, v3.1, v3.0, and v2.0). The engine is designed to be framework-agnostic and can be used in other applications, providing a clean API surface for developers.

All calculations are performed entirely on the client-side, ensuring user privacy as no data is sent to external servers. The implementation for each CVSS version adheres strictly to the official specifications published by FIRST.org, and has been tested against reference calculators for accuracy.

Sources: README.md:14-16, src/components/FAQAccordion.tsx:30-46, README.md:92-95

Architecture

The scoring engine is architecturally modular, with distinct logic encapsulated for each major CVSS version. This design ensures that the unique scoring algorithms of each standard are implemented without interference. A shared type system provides consistency for metrics, scores, and severity ratings across all versions.

The following diagram illustrates the high-level architecture of the CVSS scoring engine and its interaction with the application's UI.

Sources: src/lib/cvss/v4/scoring.ts, src/lib/cvss/v3/scoring.ts, src/lib/cvss/v2/scoring.ts, src/lib/cvss/types.ts, src/components/CVSSGenericCalculator.tsx

Core Data Structures

The engine relies on a comprehensive set of TypeScript types to ensure type safety and clarity. These types define the structure for metrics, scores, and other related data across all supported CVSS versions.

Sources: src/lib/cvss/types.ts

Key Interfaces

Interface	Description
CVSSv4Metrics	Defines the complete set of metrics for CVSS v4.0, including Base, Threat, Environmental, and Supplemental groups.
CVSSv3Metrics	Defines metrics for CVSS v3.x, including Base, Temporal, and Environmental groups.
CVSSv2Metrics	Defines metrics for CVSS v2.0, including Base, Temporal, and Environmental groups.
DetailedScore	A base interface for score results, including the final score, severity, vector, and individual score components like baseScore, temporalScore, etc.
CVSSv4Score	Extends DetailedScore with v4.0-specific results like macroVector and nomenclature.
CVSSv3Score	Extends DetailedScore for v3.x results.
CVSSv2Score	Extends DetailedScore for v2.0 results.
SeverityRating	A type alias for the qualitative severity rating string: None | Low | Medium | High | Critical.

Sources: src/lib/cvss/types.ts:20-305

Type Relationships

The following diagram shows the relationship between the main data structures used in the scoring engine.

Sources: src/lib/cvss/types.ts:31-54,233-250,290-305

Scoring Implementations

Each CVSS version has a dedicated scoring module that implements the official specification.

CVSS v4.0 Scoring

CVSS v4.0 introduces a new scoring methodology based on a "MacroVector" lookup system and interpolation, a departure from the purely formulaic approach of previous versions.

Key Logic:

1. Equivalence Classes (EQ): Metrics are grouped into 6 Equivalence Classes (EQ1-EQ6).
2. MacroVector Calculation: A 6-digit macroVector string is computed based on the metric values. Each digit represents the severity level of an EQ.
3. Base Score Lookup: The macroVector is used as a key to look up a base score from a large constant, CVSS_V4_LOOKUP.
4. Interpolation: The final score is interpolated from this base value by calculating the "severity distance" of the chosen metrics from the most severe combination within that MacroVector's equivalence class.

The main function for this process is calculateCVSSv4Score.

Sources: src/lib/cvss/v4/scoring.ts:4-15, 908-976

CVSS v3.x (v3.0 & v3.1) Scoring

CVSS v3.0 and v3.1 use a formula-based system composed of Impact and Exploitability sub-scores.

Key Logic:

1. Impact Sub-Score (ISS): Calculated from Confidentiality, Integrity, and Availability metrics.
2. Impact Score: Calculated from the ISS and the Scope (S) metric.
3. Exploitability Score: Calculated from Attack Vector (AV), Attack Complexity (AC), Privileges Required (PR), and User Interaction (UI).
4. Base Score: A combination of the Impact and Exploitability scores, capped at 10.0. The formula is adjusted if the Scope is "Changed".
5. Temporal & Environmental Scores: These are calculated by applying multipliers to the Base Score or a modified Base Score.

The primary difference between v3.0 and v3.1 lies in the implementation of the roundup function (roundUpV30 vs. roundUpV31). The calculateCVSSv3Score function orchestrates this process.

Sources: src/lib/cvss/v3/scoring.ts:5-13, 520-588

CVSS v2.0 Scoring

CVSS v2.0 also uses a formula-based system, but with different formulas and coefficients than v3.x.

Key Logic:

1. Impact Score: Calculated as 10.41 * (1 - (1 - C) * (1 - I) * (1 - A)).
2. Exploitability Score: Calculated as 20 * AV * AC * Au.
3. Base Score: Calculated using the formula Roundup(((0.6 * Impact) + (0.4 * Exploitability) - 1.5) * f(Impact)), where f(Impact) is 1.176 if Impact > 0, and 0 otherwise.
4. Severity Ratings: v2.0 uses a different set of thresholds for Low, Medium, and High ratings compared to later versions.

The main function is calculateCVSSv2Score.

Sources: src/lib/cvss/v2/scoring.ts:5-11, 311-361

Vector String Handling

A key feature of the engine is its ability to both generate and parse CVSS vector strings, which are a standardized textual representation of the selected metrics.

Function	CVSS v4.0	CVSS v3.x	CVSS v2.0	Description
generateVector	Yes	Yes	Yes	Creates a vector string (e.g., CVSS:4.0/AV:N/...) from a metrics object.
parseVector	Yes	Yes	Yes	Parses a vector string and returns a corresponding metrics object.

These functions are crucial for sharing assessments and pre-populating the calculator via URL parameters.

Sources: src/lib/cvss/v4/scoring.ts:518-632, src/lib/cvss/v3/scoring.ts:404-518, src/lib/cvss/v2/scoring.ts:223-288

UI Integration (CVSSGenericCalculator.tsx)

The scoring engine is consumed by the CVSSGenericCalculator React component, which provides the interactive user interface.

Interaction Flow:

1. The user selects a CVSS version via CVSSVersionsTabs.
2. CVSSGenericCalculator loads the corresponding VersionConfig, including metric data and default metrics.
3. The component maintains the current metrics in its state. When a user selects a metric option (e.g., changing AV from 'N' to 'A'), the updateMetric function is called.
4. A useEffect hook is triggered by the change in metrics. It calls the appropriate calculateCVSSvXScore function (e.g., calculateCVSSv4Score).
5. The returned score and vector string are stored in the component's state, causing the UI to re-render with the updated values.
6. For the "Show Contributions" feature, the component calls the calculateOptionImpact function for each unselected option to display the potential score change in real-time.

Sources: src/components/CVSSGenericCalculator.tsx:162-171, 273-301, 201-210

Embeddable Widget

The repository includes a utility to generate a self-contained HTML widget for displaying a CVSS score. The generateEmbeddableCode function in embed.ts creates an HTML string with inline CSS and sandboxed JavaScript.

This allows users to embed a dynamic and styled score card on external websites. The widget includes the score, severity, vector string, and links back to the Quant calculator.

Sources: src/lib/embed.ts:47-310, src/components/CVSSGenericCalculator.tsx:189-200