CVSS v4.0 Scoring Logic
Relevant source files
The following files were used as context for generating this wiki page:The CVSS v4.0 scoring module provides a complete implementation of the official FIRST.org CVSS v4.0 specification. Unlike previous formula-based versions, v4.0 introduces a MacroVector-based scoring system that uses lookup tables and interpolation to provide a more nuanced assessment of vulnerability severity. This approach groups metrics into Equivalence Classes (EQs) to determine a base score, which is then refined.
The core logic is encapsulated within the src/lib/cvss/v4/ directory, primarily in scoring.ts and lookup.ts. This system is consumed by UI components like CVSSGenericCalculator.tsx to provide a real-time, interactive scoring experience. The implementation is fully client-side, ensuring user privacy as no data is sent to a server.
Sources: src/lib/cvss/v4/scoring.ts:1-15, README.md:32-34, src/components/FAQAccordion.tsx:29-37
Core Concepts
CVSS v4.0 scoring departs significantly from the formulaic approach of v2.0 and v3.x. The key concepts are:
- MacroVector: A 6-digit string (e.g.,
012120) that represents the severity level of six different Equivalence Classes (EQs). This vector is the primary input to the scoring lookup table. - Equivalence Classes (EQs): Metrics are grouped into six EQs. Each EQ is assigned a severity level (0 for highest, 1 for middle, 2 for lowest) based on the values of its constituent metrics.
- Lookup Table: A large, predefined map (
CVSS_V4_LOOKUP) that associates each of the 270 valid MacroVector combinations with a base score. - Interpolation: After retrieving a base score from the lookup table, the final score is adjusted (interpolated) based on the "distance" of the selected metrics from the most severe combination within that MacroVector's class. This provides a granular score between the fixed points defined in the lookup table.
Sources: src/lib/cvss/v4/scoring.ts:5-15, src/components/CVSSVersionsTabs.tsx:37-39
Data Structures
The primary data structures for CVSS v4.0 are defined in src/lib/cvss/types.ts.
CVSSv4Metrics Interface
This interface holds the values for all possible CVSS v4.0 metrics, including Base, Threat, Environmental, and Supplemental metrics.
CVSSv4Score Interface
This interface represents the output of a score calculation, containing the final score, severity, vector string, and other v4.0-specific details like the MacroVector and nomenclature.
The relationship between these structures is shown below.
Sources: src/lib/cvss/types.ts:148-241
Scoring Process
The main function for calculating a score is calculateCVSSv4Score in scoring.ts. The process follows a clear sequence of steps to arrive at the final score.
Sources: src/lib/cvss/v4/scoring.ts:741-753
The following diagram illustrates the high-level data flow of the scoring algorithm.
Sources: src/lib/cvss/v4/scoring.ts:754-826
1. MacroVector Calculation
The first major step is to determine the 6-digit MacroVector. The calculateMacroVector function orchestrates this by calling a specific calculation function for each of the six Equivalence Classes (EQs).
This diagram shows how individual metrics are fed into functions to determine the level for each Equivalence Class, which are then combined into the final MacroVector.
Sources: src/lib/cvss/v4/scoring.ts:220-233
The logic for determining the level (0, 1, or 2) for each EQ is based on specific combinations of metric values.
| EQ | Name | Related Metrics | Level Determination Logic |
|---|---|---|---|
| EQ1 | Exploitability | AV, PR, UI | Based on how easily an attacker can access and interact with the vulnerability. N/N/N is highest severity. |
| EQ2 | Complexity | AC, AT | Based on conditions beyond the attacker's control. L/N is highest severity. |
| EQ3 | Vulnerable System Impact | VC, VI, VA | Based on CIA impact to the vulnerable system itself. H/H for VC/VI is highest. |
| EQ4 | Subsequent System Impact | SC, SI, SA, MSI, MSA | Based on CIA impact to downstream systems. S for MSI/MSA is highest. |
| EQ5 | Exploit Maturity | E | Based on the availability of exploit code. A (Attacked) is highest severity. |
| EQ6 | Security Requirements Impact | CR, IR, AR, VC, VI, VA | Based on the combination of security requirements and vulnerable system impact. H requirement and H impact is highest. |
Sources: src/lib/cvss/v4/scoring.ts:140-218
2. Score Interpolation
After getting a base score from the CVSS_V4_LOOKUP table using the MacroVector, an interpolation step refines the score.
- Find Max Severity Vectors: The system identifies the highest-severity combination of metric values that could produce the current MacroVector. This is done by
composeMaxVectors. - Calculate Severity Distance: The
calculateSeverityDistancesfunction computes a numerical "distance" for each EQ group by comparing the currently selected metrics against the "max severity" vector. This distance represents how far the current selection is from the worst-case scenario within its class. - Find Next Lower Scores: The system looks up the scores for adjacent, less severe MacroVectors (e.g., if the current EQ1 level is
0, it finds the score for level1). - Calculate Adjustment: The
calculateInterpolationfunction uses the distances and the difference between the current and next-lower scores to compute an adjustment value. - Apply Adjustment: This adjustment is subtracted from the initial base score to get the final, interpolated score.
This process ensures that even within the same MacroVector, different metric choices result in slightly different scores, providing a more granular result than a simple lookup.
Sources: src/lib/cvss/v4/scoring.ts:252-385, 638-738
Key Functions & Exports
The CVSS v4.0 logic is exposed through a set of functions exported from src/lib/cvss/v4/index.ts.
| Function | Description | Source File |
|---|---|---|
calculateCVSSv4Score | The main function that takes a CVSSv4Metrics object and returns a CVSSv4Score object. | scoring.ts |
calculateMacroVector | Calculates the 6-digit MacroVector string from a metrics object. | scoring.ts |
generateVector | Creates a CVSS v4.0 vector string from a CVSSv4Metrics object. | scoring.ts |
parseVector | Parses a CVSS v4.0 vector string into a CVSSv4Metrics object. | scoring.ts |
getSeverityRating | Converts a numeric score (0.0-10.0) into a qualitative rating (None, Low, Medium, High, Critical). | scoring.ts |
calculateOptionImpact | Calculates the score change if a specific metric option were selected. Used for UI hints. | scoring.ts |
calculateMetricContribution | Calculates the contribution of a single metric to the overall score. | scoring.ts |
Sources: src/lib/cvss/v4/index.ts:1-19, src/lib/cvss/v4/scoring.ts
UI Integration
The CVSSGenericCalculator.tsx component provides the user interface for the v4.0 calculator. It leverages the scoring library for real-time updates.
This sequence shows how user interactions in the UI trigger calls to the scoring library. calculateCVSSv4Score is called on every state change to update the score, while calculateOptionImpact is used to provide helpful hints to the user about how their choices affect the score without actually selecting the option.
Sources: src/components/CVSSGenericCalculator.tsx:218-248, 282-307
Conclusion
The CVSS v4.0 scoring logic in Quant is a robust and accurate TypeScript implementation of the official standard. By moving to a MacroVector and interpolation-based system, it offers a more detailed and context-aware vulnerability assessment. The codebase isolates the complex scoring logic in src/lib/cvss/v4/, allowing UI components to consume it as a pure, side-effect-free library for a responsive and interactive user experience. The inclusion of helper functions like calculateOptionImpact further enhances the UI by providing real-time feedback to the user.