Main Application Components
Relevant source files
The following files were used as context for generating this wiki page:
- src/components/CVSSCalculator.tsx
- src/components/Header.tsx
- src/components/Footer.tsx
- src/components/CVSSGenericCalculator.tsx
- src/components/ScoreHistory.tsx
- src/lib/cvss/v3/scoring.ts
- src/lib/cvss/v2/scoring.ts
- src/lib/cvss/types.ts
- src/lib/cvss/metrics-data.ts
- src/components/FAQAccordion.tsx
- README.md
The Quant application is a client-side CVSS score calculator built with Astro and React. Its architecture is centered around a set of modular React components that handle the user interface, state management, and scoring logic. All calculations and data storage occur within the user's browser, ensuring privacy and offline capability.
The main components can be categorized into three groups: core layout components that provide the main application shell, the CVSS calculator system which forms the core functionality, and the score management system for tracking and analyzing assessments. These systems are supported by a robust, pure JavaScript/TypeScript scoring library that implements the official CVSS specifications.
Core Layout Components
The application's primary layout is defined by a standard header, content area, and footer structure.
| Component | File | Description |
|---|---|---|
Header | src/components/Header.tsx | Provides top-level navigation, application branding, and a theme (dark/light mode) toggle. |
Footer | src/components/Footer.tsx | Contains links to external resources like CVSS specifications, community channels, and legal information. |
Sources: src/components/Header.tsx, src/components/Footer.tsx
Header
The Header component is a sticky element at the top of the page. It includes:
- The Quant logo, which links to the home page.
- Navigation links to
Home,Calculator,Documentation, and the project'sGitHubrepository. - A theme toggle button to switch between light and dark modes. The theme preference is persisted in
localStorage. - A responsive mobile menu (
Sheet) for smaller viewports.
Sources: src/components/Header.tsx:21-50
The theme is managed using a useState hook and a useEffect hook that reads from localStorage and applies the appropriate class to the <html> element.
Sources: src/components/Header.tsx:32-44
Footer
The Footer component is located at the bottom of every page. It is divided into four columns:
- About Quant: A brief description of the application.
- Resources: Links to the official CVSS specification documents (v4.0, v3.1, v2.0).
- Community: Links to the GitHub repository, Discord server, and Twitter/X profile.
- Legal: Links to the Apache 2.0 License and the Cyberpath website.
All external links in the footer include UTM parameters for analytics, which are defined in src/lib/constants.ts.
Sources: src/components/Footer.tsx:11-125, src/lib/constants.ts:47-51
CVSS Calculator System
The calculator is the core feature of Quant. It is composed of a parent component that manages versions and several child components for the UI, logic, and data.
The following diagram illustrates the interaction between the main calculator components.
This diagram shows how CVSSCalculator manages version selection and vector parsing, passing control to CVSSGenericCalculator which orchestrates the UI and scoring logic.
Sources: src/components/CVSSCalculator.tsx, src/components/CVSSGenericCalculator.tsx, src/lib/cvss/metrics-data.ts
Main Calculator Component (CVSSCalculator.tsx)
This component acts as the primary controller for the calculator interface. Its main responsibilities are:
- Version Management: It uses a
Tabscomponent to allow users to switch between CVSS versions (v4.0, v3.1, v3.0, v2.0). The active tab state determines which version of theCVSSGenericCalculatoris rendered. - URL Vector Parsing: On initial load, it checks the URL for a
vectorquery parameter. If found, it parses the vector, switches to the correct CVSS version tab, and passes the parsed metrics to theCVSSGenericCalculatoras initial state. - History Restoration: It listens for a custom
cvss-restore-vectorevent dispatched from theScoreManager. When this event is received, it updates its state to restore the calculator to the state defined by the provided vector string. - Settings Persistence: It manages user settings like "alternative descriptions" and "show contributions" and persists them in
localStorage.
Sources: src/components/CVSSCalculator.tsx:21-146
Generic Calculator UI (CVSSGenericCalculator.tsx)
This is a versatile component responsible for rendering the calculator UI for any given CVSS version.
- It receives the CVSS
versionas a prop. - Based on the version, it loads the appropriate metric definitions (
cvss40Metrics,cvss3Metrics,cvss2Metrics) fromsrc/lib/cvss/metrics-data.ts. - It manages the state of the selected metrics in a
metricsobject. - Whenever a metric is changed by the user, it calls the corresponding scoring function (
calculateCVSSv4Score,calculateCVSSv3Score, orcalculateCVSSv2Score) to get a new score and vector string in real-time. - It renders the metric groups (Base, Temporal, etc.) in a tabbed interface. Each metric is rendered as a
RadioGroupof options. - It can display the score impact of selecting a different metric option, which is calculated using
calculateOptionImpactfunctions from the scoring modules.
Sources: src/components/CVSSGenericCalculator.tsx:100-300
Scoring Logic and Data Models
The actual score calculation is handled by a set of pure TypeScript modules in src/lib/cvss/.
Data Models (types.ts)
The file src/lib/cvss/types.ts defines the core data structures for the application. This includes interfaces for each CVSS version's metrics (CVSSv4Metrics, CVSSv3Metrics, CVSSv2Metrics) and score results (CVSSv4Score, CVSSv3Score, CVSSv2Score).
The following diagram shows the relationship between some of the key types.
This diagram illustrates the inheritance structure of the score result types and the generalization of the metrics types.
Sources: src/lib/cvss/types.ts:38-63, 222-241, 283-294, 347-358
Scoring Engines (v2/scoring.ts, v3/scoring.ts)
These files contain the formula-based implementation of the official CVSS specifications. For example, src/lib/cvss/v3/scoring.ts implements the logic for both v3.0 and v3.1, as they are very similar.
Key functions include:
calculateCVSSv3Score(): The main function that takesCVSSv3Metricsand returns aCVSSv3Scoreobject.calculateBaseScore(): Calculates the base score from impact and exploitability sub-scores.calculateImpact(): Calculates the impact sub-score.calculateExploitability(): Calculates the exploitability sub-score.generateVector(): Creates a vector string from a metrics object.parseVector(): Creates a metrics object from a vector string.
The scoring logic for CVSS v3.1 Base Score calculation is illustrated below.
This flowchart shows the steps to calculate the CVSS v3.1 Base Score, from metric weights to the final rounded value.
Sources: src/lib/cvss/v3/scoring.ts:200-227
Score Management (ScoreHistory.tsx)
The ScoreManager component provides a comprehensive interface for managing saved CVSS scores. It is a standalone feature that interacts with the main calculator.
Functionality
- Display Scores: Lists all saved scores in a sortable, searchable table.
- Local Storage: Persists the score history in the browser's
localStorageunder the keySTORAGE_KEY. - CRUD Operations: Allows users to edit the name of a score, delete a score, and clear the entire history.
- Import/Export: Users can export their history to a JSON file and import a history from a JSON file. The import logic avoids duplicates.
- Comparison: Users can select two or more scores of the same CVSS version to see a side-by-side comparison of their metrics in a dialog.
- Charting: Users can select scores to generate aggregate charts (bar or donut) showing the distribution of severities.
Sources: src/components/ScoreHistory.tsx:1-690
Interaction Flow
The following sequence diagram shows how a user saves a score and how it is restored.
This diagram shows the process of saving a score to local storage and the event-driven mechanism for restoring a score back into the calculator.
Sources: src/components/CVSSGenericCalculator.tsx:210-226, src/components/ScoreHistory.tsx:432-449, src/components/CVSSCalculator.tsx:107-121
Informational Components
To enhance the user experience, the application includes several read-only components that provide context and help.
FAQAccordion.tsx: An accordion-style component that answers frequently asked questions about CVSS, data privacy (confirming all processing is client-side), and application features. Sources: src/components/FAQAccordion.tsxCVSSVersionsTabs.tsx: A tabbed view that provides a high-level summary of the key features and base metrics for each supported CVSS version (4.0, 3.1, 3.0, and 2.0). This helps users understand the differences between the standards. Sources: src/components/CVSSVersionsTabs.tsx
Conclusion
The Quant application's architecture is a well-structured, component-based system that effectively separates concerns. The core layout components provide a consistent user experience, while the modular CVSSCalculator and ScoreHistory systems deliver powerful, interactive features. The reliance on client-side logic and local storage makes the application fast, private, and accessible. The clear separation of UI components from the scoring engine and data models ensures maintainability and accuracy according to official CVSS standards.