CVSS Vector String Parser

Relevant source files

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

• src/lib/cvss/vector-parser.ts
• src/lib/cvss/v4/scoring.ts
• src/lib/cvss/v3/scoring.ts
• src/lib/cvss/v2/scoring.ts
• src/components/CVSSCalculator.tsx
• src/lib/cvss/types.ts
• src/lib/embed.ts

The CVSS Vector String Parser is a core module in the Quant application responsible for interpreting CVSS vector strings and converting them into structured metric objects. This functionality is crucial for initializing the calculator with a pre-defined state, either from a shared URL or from the user's saved history. The system is designed as a facade that delegates parsing logic to version-specific implementations, supporting CVSS v4.0, v3.1, v3.0, and v2.0.

The parser's primary role is to deconstruct a standardized string like CVSS:4.0/AV:N/AC:L/AT:N/... into a JavaScript object that the calculator's UI and scoring engine can understand and operate on. This enables features like sharing assessments via URL and restoring previous calculations.

Sources: src/lib/cvss/vector-parser.ts, src/components/CVSSCalculator.tsx:100-116

Architecture and Data Flow

The vector parsing system is architected around a central facade, vector-parser.ts, which exposes two main functions: getVectorFromURL and parseVector. This facade determines the CVSS version from the input string and delegates the actual parsing to the appropriate version-specific parseVector function located in the scoring files for v4.0, v3.x, and v2.0.

Sources: src/lib/cvss/vector-parser.ts:14-20

High-Level Parsing Flow

The following diagram illustrates how a vector string is processed from the URL or a direct call through to the version-specific parsers.

This diagram shows the main entry points (getVectorFromURL and parseVector) and the delegation to version-specific implementations.
Sources: src/lib/cvss/vector-parser.ts:22-55, src/components/CVSSCalculator.tsx:101-103

Key Functions

The vectorParser object exposes the following key functions:

Function	Description	Return Type	Source File
getVectorFromURL	Reads the vector query parameter from the current window URL and parses it. Returns null if not found.	{ raw: string, version: string, metrics: CVSSMetrics } | null	src/lib/cvss/vector-parser.ts:57-73
parseVector	Takes a raw vector string as input, determines the version, and delegates to the correct parser.	{ raw: string, version: string, metrics: CVSSMetrics } | null	src/lib/cvss/vector-parser.ts:22-55
getVectorVersion	A utility function to quickly extract the CVSS version number from a vector string.	string | null	src/lib/cvss/vector-parser.ts:14-20

Parsed Data Structure

Upon successful parsing, the functions return an object containing the raw vector, the detected version, and a metrics object. The structure of the metrics object varies by CVSS version and is defined in src/lib/cvss/types.ts.

Example of a returned object for a CVSS v4.0 vector:

{
  "raw": "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",
  "version": "4.0",
  "metrics": {
    "AV": "N",
    "AC": "L",
    "AT": "N",
    "PR": "N",
    "UI": "N",
    "VC": "H",
    "VI": "H",
    "VA": "H",
    "SC": "N",
    "SI": "N",
    "SA": "N",
    "E": "X",
    "CR": "X",
    "...": "..."
  }
}

Sources: src/lib/cvss/vector-parser.ts:25, src/lib/cvss/types.ts:188-237

Version-Specific Parsing Logic

Each CVSS version has a dedicated parseVector function within its corresponding scoring.ts file. These functions are responsible for the detailed logic of splitting the vector string and populating a metrics object.

CVSS v4.0 Parsing

The parseVector function for v4.0 handles the most extensive set of metrics.

• File: src/lib/cvss/v4/scoring.ts
• Logic:
  1. Initializes a CVSSv4Metrics object with default values (DEFAULT_METRICS).
  2. Splits the vector string by the / delimiter.
  3. Validates that the string starts with CVSS:4.0.
  4. Iterates through each key:value pair (e.g., AV:N).
  5. Populates the corresponding property in the metrics object.

Sources: src/lib/cvss/v4/scoring.ts:503-523

CVSS v3.x Parsing

The parseVector for v3.x is unique because it must determine whether the vector is for version 3.0 or 3.1.

• File: src/lib/cvss/v3/scoring.ts
• Logic:
  1. Initializes a default CVSSv3Metrics object.
  2. Splits the vector string by /.
  3. Checks if the first part is CVSS:3.1 or CVSS:3.0 to set the version. Throws an error if neither.
  4. Iterates through metric pairs and populates the metrics object.
  5. Returns both the populated metrics object and the detected version.

Sources: src/lib/cvss/v3/scoring.ts:433-467

CVSS v2.0 Parsing

The v2.0 parser handles the legacy format.

• File: src/lib/cvss/v2/scoring.ts
• Logic:
  1. Initializes a CVSSv2Metrics object with default values (ND for optional metrics).
  2. Optionally removes parentheses () that sometimes wrap v2.0 vectors.
  3. Splits the string by / and iterates through pairs to populate the metrics object.

Sources: src/lib/cvss/v2/scoring.ts:303-324

Integration and Usage

The CVSS Vector String Parser is primarily used by the CVSSCalculator component to initialize its state.

Initial Page Load

On component mount, CVSSCalculator calls vectorParser.getVectorFromURL() to check for a vector parameter in the URL. If a valid vector is found, the component updates its state to display the correct CVSS version tab and populates the calculator with the parsed metrics.

The following sequence diagram shows this interaction:

This diagram shows how the CVSSCalculator uses the parser to handle deep links containing a full CVSS assessment.
Sources: src/components/CVSSCalculator.tsx:100-116, src/lib/embed.ts:31-34

Restoring from History

The parser is also used when a user restores a saved score from the score manager. A custom event cvss-restore-vector is dispatched with the raw vector string. The CVSSCalculator listens for this event, calls vectorParser.parseVector() with the received string, and updates its state accordingly.

Sources: src/components/CVSSCalculator.tsx:136-152

Summary

The CVSS Vector String Parser is a well-defined, modular system that acts as a gateway for initializing the calculator's state from a string representation. Its facade pattern cleanly separates the high-level API from the version-specific implementation details, making the system extensible and easy to maintain. By handling various CVSS versions and integrating seamlessly with the main calculator component, it enables key features like sharing and state restoration, which are fundamental to the user experience of the Quant application.

Sources: src/lib/cvss/vector-parser.ts, README.md:55-58