Multi-Version CVSS Support

Relevant source files

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

• src/components/CVSSVersionsTabs.tsx
• src/lib/cvss/v2/scoring.ts
• src/lib/cvss/v3/scoring.ts
• src/lib/cvss/v4/scoring.ts
• src/components/CVSSGenericCalculator.tsx
• src/components/CVSSCalculator.tsx
• src/lib/cvss/types.ts
• src/lib/cvss/metrics-data.ts

The Quant application provides comprehensive support for calculating vulnerability severity scores across multiple versions of the Common Vulnerability Scoring System (CVSS). This feature allows users to perform assessments using the latest standard (v4.0), the current industry standard (v3.1), and legacy versions (v3.0, v2.0) for historical comparisons or compatibility. The system is architected in a modular fashion, with distinct scoring engines for each CVSS version, a generic calculator UI, and a centralized data model for metric definitions.

This design ensures accuracy by implementing each version's specification independently while providing a consistent and intuitive user experience. All scoring logic is executed client-side in pure JavaScript/TypeScript, ensuring privacy and offline capability.

Sources: README.md:29-34, src/components/CVSSCalculator.tsx:13-16, src/components/FAQAccordion.tsx:30-36

Architecture Overview

The multi-version support is achieved through a combination of generic UI components and version-specific logic modules. The CVSSCalculator component acts as the main controller, managing a tabbed interface where each tab corresponds to a CVSS version. When a user selects a version, the CVSSGenericCalculator is rendered with a version-specific configuration. This configuration dictates which metric data to display and which scoring engine to use for real-time calculations.

This diagram illustrates the high-level interaction between the UI components and the backend scoring logic.

UI Components

The user interface is composed of several key React components that work together to provide a seamless multi-version experience.

CVSSCalculator

The CVSSCalculator is the primary component that orchestrates the entire calculator interface. Its main responsibilities include:

• Rendering the main tabs for version selection (v4.0, v3.1, v3.0, v2.0).
• Managing the currently active tab (activeTab state).
• Parsing the URL for a vector or version query parameter on initial load to pre-configure the calculator.
• Instantiating the CVSSGenericCalculator with the correct version and initial metrics.

Sources: src/components/CVSSCalculator.tsx:21-26, 73-90, 179-241

CVSSGenericCalculator

This is a versatile component designed to function as a calculator for any supported CVSS version. It receives the version as a prop and configures itself accordingly.

• Configuration Loading: Based on the version prop, it loads the appropriate metric definitions (metricsData), default metrics, and other version-specific settings.
• State Management: It manages the state of all selected metric values (metrics state).
• Real-time Calculation: It uses a useEffect hook to trigger a recalculation whenever the metrics state changes. It calls the appropriate calculateCVSS...Score function based on its configured version.
• Metric Rendering: It dynamically renders the metric groups (Base, Temporal, etc.) and their options from the loaded metricsData.

The following snippet shows how CVSSGenericCalculator calls the correct scoring function based on the version prop.

// File: src/components/CVSSGenericCalculator.tsx:254-276
useEffect(() => {
    let result: {
        score:  number
        vector: string
    };

    switch (version) {
        case `4.0`:
            result = calculateCVSSv4Score(metrics as CVSSv4Metrics);
            break;
        case `3.1`:
        case `3.0`:
            result = calculateCVSSv3Score(metrics as CVSSv3Metrics, version);
            break;
        case `2.0`:
            result = calculateCVSSv2Score(metrics as CVSSv2Metrics);
            break;
        default:
            result = {
                score:  0,
                vector: ``,
            };
    }

    setScore(result.score);
    setVectorString(result.vector);
}, [
    metrics,
    version,
]);

Sources: src/components/CVSSGenericCalculator.tsx:88-124, 126-143, 254-280

CVSSVersionsTabs

This is a presentational component that displays detailed information about each CVSS version within a tabbed layout. It outlines the key features and base metrics for each standard.

Version	Release Date	Key Features
v4.0	Nov 2023	MacroVector-Based Scoring, Subsequent System Impact metrics, Enhanced Supplemental Metrics.
v3.1	Jun 2019	Three Metric Groups (Base, Temporal, Environmental), Scope concept, improved real-world alignment.
v3.0	Jun 2015	Introduced Scope concept, simplified metrics from v2.0.
v2.0	Feb 2007	Original standard with three metric groups and Access Vector/Complexity/Authentication metrics.

Sources: src/components/CVSSVersionsTabs.tsx:28-251

Scoring Logic

The core of the feature lies in the separate, self-contained scoring modules for each CVSS version.

CVSS v4.0 Scoring (src/lib/cvss/v4/scoring.ts)

CVSS v4.0 uses a modern, lookup-based approach rather than a direct formula.

1. MacroVector Calculation: Metrics are mapped to 6 Equivalence Classes (EQ1-EQ6). The combination of these levels forms a 6-digit MacroVector string (e.g., "012210").
2. Lookup Score: This MacroVector is used as a key to find a base score from a large lookup table (CVSS_V4_LOOKUP).
3. Interpolation: The final score is interpolated from the base lookup score by calculating the "distance" of the selected metrics from the highest-severity metrics within that MacroVector's equivalence class.

This flowchart shows the v4.0 scoring process.

CVSS v3.x Scoring (src/lib/cvss/v3/scoring.ts)

CVSS v3.0 and v3.1 use a formula-based system. The logic is mostly shared, with a key difference in the rounding function.

1. Calculate ISS: The Impact Sub-Score (ISS) is calculated from the Confidentiality, Integrity, and Availability metrics.
2. Calculate Impact: The Impact score is derived from the ISS, and the formula changes if the Scope (S) is "Changed".
3. Calculate Exploitability: The Exploitability score is calculated from Attack Vector (AV), Attack Complexity (AC), Privileges Required (PR), and User Interaction (UI).
4. Calculate Base Score: The Base Score is a combination of the Impact and Exploitability scores.
5. Round Up: The final score is rounded to one decimal place. v3.1 uses a specific roundUpV31 function that rounds up, while v3.0 uses a roundUpV30 function that rounds to the nearest 0.1.

// File: src/lib/cvss/v3/scoring.ts:167-178
/**
 * CVSS v3.0 roundup function - rounds to nearest 0.1
 */
function roundUpV30(value: number): number {
    const roundMultiplier = 10;
    return Math.ceil(value * roundMultiplier) / roundMultiplier;
}

/**
 * CVSS v3.1 roundup function - rounds up to 1 decimal place
 * Implementation follows the specification exactly
 */
function roundUpV31(value: number): number {
    const intInput = Math.round(value * 100000);
    const remainder = intInput % 10000;
    if (remainder === 0) {
        return intInput / 100000;
    }
    return (Math.floor(intInput / 10000) + 1) / 10;
}

Sources: src/lib/cvss/v3/scoring.ts:1-16, 167-187, 568-601

CVSS v2.0 Scoring (src/lib/cvss/v2/scoring.ts)

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

1. Calculate Impact: Calculated from Confidentiality, Integrity, and Availability.
2. Calculate Exploitability: Calculated from Access Vector (AV), Access Complexity (AC), and Authentication (Au).
3. Calculate Base Score: The Base Score is calculated using the formula Roundup(((0.6 * Impact) + (0.4 * Exploitability) - 1.5) * f(Impact)), where f(Impact) is 0 if Impact is 0, and 1.176 otherwise.

Sources: src/lib/cvss/v2/scoring.ts:1-10, 155-165

Data Models and Types

A strong type system and centralized data definitions are key to the maintainability of the multi-version support.

Unified Types (src/lib/cvss/types.ts)

The types.ts file defines TypeScript interfaces for every CVSS version's metrics and score results. Union types like CVSSMetrics and CVSSScore allow components like CVSSGenericCalculator to handle different versions in a type-safe manner.

// File: src/lib/cvss/types.ts:468-472
/**
 * Union type for all CVSS metrics
 */
export type CVSSMetrics = CVSSv4Metrics | CVSSv3Metrics | CVSSv2Metrics;

/**
 * Union type for all CVSS scores
 */
export type CVSSScore = CVSSv4Score | CVSSv3Score | CVSSv2Score;

This class diagram shows the relationship between the main score and metric types.

Metric Definitions (src/lib/cvss/metrics-data.ts)

This file serves as a central database for all metric information. It exports constants (cvss40Metrics, cvss3Metrics, cvss2Metrics) that contain the labels, descriptions, and possible values for every metric in every supported CVSS version. This separation of data from logic allows the CVSSGenericCalculator to be version-agnostic; it simply renders the data it is given.

The data is structured into MetricGroup objects, each containing an array of MetricDefinition.

Sources: src/lib/cvss/metrics-data.ts:1-29, 34, 521, 888