Using the CVSS Calculator

Relevant source files

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

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

The CVSS Calculator is an interactive, client-side tool designed for fast and accurate vulnerability severity assessment. It supports multiple versions of the Common Vulnerability Scoring System (CVSS), including v4.0, v3.1, v3.0, and v2.0. All calculations are performed within the user's browser, ensuring that no data is sent to external servers and user privacy is maintained.

The calculator provides a user-friendly interface with real-time score updates, color-coded severity indicators, and detailed metric descriptions. It is built as a modular system of React components, allowing for clear separation between the main user interface, the generic calculator logic, and the version-specific scoring engines. This design supports features like sharing assessments via URL, embedding score cards, and saving results to local storage.

Sources: README.md, src/components/FAQAccordion.tsx:30-37, src/components/CVSSCalculator.tsx

Architecture and Components

The calculator's architecture is composed of a main container component that manages different calculator versions via tabs, and a generic calculator component that is instantiated for each version.

Sources: src/components/CVSSCalculator.tsx, src/components/CVSSGenericCalculator.tsx

Component Hierarchy

The CVSSCalculator component acts as the primary entry point. It uses a tabbed interface to switch between different CVSS versions. Each tab's content is an instance of the CVSSGenericCalculator component, which is configured for a specific CVSS version (4.0, 3.1, 3.0, or 2.0).

This diagram illustrates the relationship between the main components.

Key Components

Component	Description	File
CVSSCalculator	The main stateful component. It manages the active tab, handles URL parsing for pre-filled vectors, and orchestrates the rendering of the appropriate CVSSGenericCalculator.	src/components/CVSSCalculator.tsx
CVSSGenericCalculator	A reusable component that provides the UI and logic for a single CVSS calculator version. It manages metric state, triggers score calculations, and handles user actions like copying the vector or sharing.	src/components/CVSSGenericCalculator.tsx
ScoreCard	A presentational component that displays the final score, severity rating, and the generated vector string.	src/components/cvss-calculator/ScoreCard.tsx
SettingsMenu	A dropdown menu for calculator-wide settings, such as toggling alternative metric descriptions or showing score contributions.	src/components/cvss-calculator/SettingsMenu.tsx
ExportMenu	A menu providing options to copy the vector, share a link, embed the code, or save the score.	src/components/cvss-calculator/ExportMenu.tsx

Sources: src/components/CVSSCalculator.tsx, src/components/CVSSGenericCalculator.tsx

Data Flow and State Management

The calculator's functionality is driven by React state and effects. User interactions trigger state updates, which in turn cause the score to be recalculated and the UI to re-render.

User Interaction and Score Calculation

The following sequence diagram shows the data flow when a user selects a new metric value.

This flow ensures that the score is always in sync with the selected metrics.

Sources: src/components/CVSSGenericCalculator.tsx:160-165, src/components/CVSSGenericCalculator.tsx:265-288

State Management

The primary state is managed within the CVSSGenericCalculator component using useState.

State Variable	Type	Description
metrics	CVSSMetrics	An object holding the currently selected values for all metrics of a specific CVSS version.
score	number	The calculated numerical score, updated in real-time.
vectorString	string	The generated CVSS vector string based on the current metrics.
activeGroup	string	The currently selected metric group tab (e.g., 'base-metrics').

The CVSSMetrics type is a union of version-specific metric interfaces (CVSSv4Metrics, CVSSv3Metrics, CVSSv2Metrics).

Sources: src/components/CVSSGenericCalculator.tsx:143-158, src/lib/cvss/types.ts:442-444

URL and Local Storage Integration

The calculator interacts with the browser's URL and Local Storage for persistence and sharing.

• URL Vector Parsing: On initial load, the CVSSCalculator component checks the URL for a vector query parameter. If found, it parses the vector, sets the initial state of the corresponding calculator, and switches to the correct version tab.
  Sources: src/components/CVSSCalculator.tsx:68-85
• URL Parameter Sync: The active CVSS version tab and metric group are synchronized with the URL query parameters (version and group) to allow for bookmarking and sharing specific views.
  Sources: src/components/CVSSCalculator.tsx:145-154, src/components/CVSSGenericCalculator.tsx:313-322
• Settings Persistence: User-configured settings, like should_use_alternative_description, are saved to localStorage under the key cvss_calculator_settings and loaded on mount.
  Sources: src/components/CVSSCalculator.tsx:132-141

Scoring Engines

The core logic resides in version-specific scoring engines, which implement the official FIRST.org specifications. Each engine provides functions to calculate scores, generate vectors, and parse vectors.

CVSS v4.0 Scoring

CVSS v4.0 uses a MacroVector-based lookup system.

1. calculateMacroVector: Determines a 6-digit MacroVector string by assigning metric combinations to six Equivalence Classes (EQ1-EQ6).
2. Lookup: The base score is retrieved from a large lookup table (CVSS_V4_LOOKUP) using the MacroVector as the key.
3. Interpolation: The final score is adjusted from the base value by calculating the "severity distance" from the most severe combination of metrics within that MacroVector.

Sources: src/lib/cvss/v4/scoring.ts:241-259, src/lib/cvss/v4/scoring.ts:684-729

CVSS v3.x Scoring

CVSS v3.0 and v3.1 use a formula-based approach. The main function is calculateCVSSv3Score.

The calculation flow is as follows:

• Impact Score: Calculated from Confidentiality, Integrity, and Availability (CIA) impacts, and adjusted by the Scope metric.
• Exploitability Score: Calculated from Attack Vector, Attack Complexity, Privileges Required, and User Interaction.
• Base Score: A combination of the Impact and Exploitability scores.
• Temporal/Environmental Scores: Optional adjustments to the Base Score. The final score is the Environmental Score if present, otherwise the Temporal Score, otherwise the Base Score.

A key difference between v3.1 and v3.0 is the roundUp function used.
Sources: src/lib/cvss/v3/scoring.ts:143-151, src/lib/cvss/v3/scoring.ts:585-630

CVSS v2.0 Scoring

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

• Impact: 10.41 * (1 - (1 - C) * (1 - I) * (1 - A))
• Exploitability: 20 * AV * AC * Au
• Base Score: Roundup(((0.6 * Impact) + (0.4 * Exploitability) - 1.5) * f(Impact))

The severity ratings for v2.0 are also different, with "High" being the maximum rating instead of "Critical".
Sources: src/lib/cvss/v2/scoring.ts:142-151, src/lib/cvss/v2/scoring.ts:206-217, src/lib/cvss/metrics-data.ts:1016-1042

Data Structures

The application relies on a set of well-defined TypeScript types for metrics, scores, and configurations.

Sources: src/lib/cvss/types.ts

Metric and Score Types

The core data structures are defined in src/lib/cvss/types.ts.

This diagram shows the union types CVSSMetrics and CVSSScore and their constituent version-specific interfaces.

Sources: src/lib/cvss/types.ts:442-448, src/lib/cvss/types.ts:183-200, src/lib/cvss/types.ts:285-294, src/lib/cvss/types.ts:373-382

Metric Definitions

The UI for selecting metrics is dynamically generated from data structures defined in src/lib/cvss/metrics-data.ts. Each CVSS version has an array of MetricGroup objects.

// src/lib/cvss/metrics-data.ts:15-21
export interface MetricGroup {
    name:        string
    description: string
    metrics:     Array<MetricDefinition>
}

// src/lib/cvss/metrics-data.ts:8-13
export interface MetricDefinition {
    key:         string
    label:       string
    description: string
    options:     Array<MetricOption>
}

This structure allows the CVSSGenericCalculator to render the appropriate metric groups (Base, Temporal, etc.) and their corresponding metric options for any given CVSS version.

Sources: src/lib/cvss/metrics-data.ts:8-21, src/components/CVSSGenericCalculator.tsx:361-496

Utility Features

Beyond calculation, the tool provides several utilities for sharing and managing scores.

Sharing and Exporting

The ExportMenu provides several actions, implemented as callback functions in CVSSGenericCalculator.

Function	Description
copyVector()	Copies the current vectorString to the clipboard.
shareScore()	Copies a shareable URL to the clipboard. The URL includes the encoded vectorString as a query parameter.
shareEmbeddableCode()	Generates and copies a self-contained HTML snippet for embedding a score card widget on an external website.
handleSaveToHistory()	Opens a dialog to save the current score and a user-provided name to the browser's local storage.

Sources: src/components/CVSSGenericCalculator.tsx:167-211

Embeddable Widget

The generateEmbeddableCode function in src/lib/embed.ts creates a complete HTML and JavaScript widget. This widget is designed to be self-contained, with inline CSS and sandboxed JavaScript to avoid conflicts with the host page. It displays the score, severity, and vector, and includes a link back to the main calculator application.

Sources: src/lib/embed.ts:62-297