Embedding Scorecards and Charts
Relevant source files
The following files were used as context for generating this wiki page:
The Quant application provides a powerful feature to generate self-contained, embeddable HTML widgets for both individual CVSS scorecards and aggregate CVSS score charts. This allows users to share and display vulnerability assessment data on external websites, reports, or documentation, ensuring that the visual representation and core data are preserved outside of the Quant application.
The embedding functionality is divided into two main parts: generating widgets for single CVSS scores and generating widgets for charts that visualize multiple scores. Both are designed to be SEO-compliant and avoid styling conflicts with the host page by using scoped CSS and self-contained JavaScript.
Embedding CVSS Scorecards
The core logic for embedding a single CVSS score is handled by the generateEmbeddableCode function. This function creates a complete HTML snippet that renders a visually consistent scorecard widget.
Sources: src/lib/embed.ts, src/components/CVSSGenericCalculator.tsx:180-192
Generation Process
The generation of an embeddable scorecard is triggered from the "Export Menu" in the CVSS calculator UI. The process involves collecting the current score details and passing them to the generator function.
The following diagram illustrates the flow of generating the scorecard widget.
Key Function: generateEmbeddableCode
This function is the heart of the scorecard embedding feature. It takes the score details and constructs an HTML string.
Sources: src/lib/embed.ts:32-41
Parameters:
| Parameter | Type | Description |
|---|---|---|
version | string | The CVSS version (e.g., "4.0"). |
score | number | The numeric CVSS score. |
vectorString | string | The full CVSS vector string. |
severity | SeverityInfo | An object containing the severity label and colors. |
origin | string | The origin URL of the Quant application, used for generating links. |
Sources: src/lib/embed.ts:32-41
Widget Structure and Features
The generated widget is self-contained and includes several key components:
- Scoped CSS: To prevent style conflicts, all CSS classes are namespaced with a unique, timestamp-based identifier (e.g.,
.cvss-widget-container-1678886400). This ensures the widget's appearance is consistent regardless of the host page's stylesheets.
Sources: src/lib/embed.ts:57-59 - HTML Layout: A structured HTML block that displays the CVSS version, score, severity level, and the full vector string.
Sources: src/lib/embed.ts:182-268 - Dynamic Styling: The
getSeverityCSSfunction maps severity levels (None,Low,Medium,High,Critical) to specificoklchcolor values for text and background, ensuring the widget's colors match the application's UI.
Sources: src/lib/embed.ts:12-55 - Inline JavaScript: A small, self-executing script provides interactivity:
- A dropdown menu to copy a shareable link.
- A "Copy Vector" button that appears on hover.
- A toast notification system to confirm copy actions.
- All event listeners are scoped to the widget's unique container to avoid interfering with the host page.
Sources: src/lib/embed.ts:270-357
- Attribution Link: A "View on Quant" link at the bottom, which includes UTM parameters for tracking, directs users back to the calculator with the specific vector pre-loaded.
Sources: src/lib/embed.ts:359-366
Embedding CVSS Charts
Similar to scorecards, Quant can generate embeddable HTML for charts that visualize a collection of CVSS scores. This is managed by the generateEmbeddableChartHTML function.
Sources: src/lib/embed-chart.ts, src/components/chart-dialog.tsx:683-691
Generation Process
Chart embedding is initiated from the "Chart Dialog," which appears after a user selects multiple scores from the Score Manager. The user configures the chart's appearance, and the settings are passed to the generator function.
The following diagram shows the data flow for generating an embeddable chart.
Key Function: generateEmbeddableChartHTML
This function constructs the HTML for the chart widget based on user settings and selected score data.
Sources: src/lib/embed-chart.ts:18-22
Parameters:
| Parameter | Type | Description |
|---|---|---|
settings | typeof DEFAULT_SETTINGS | An object containing all customization options for the chart. |
selectedEntries | Array<ScoreHistoryEntry> | An array of score history entries to be visualized. |
origin | string | The origin URL of the Quant application. |
Sources: src/lib/embed-chart.ts:18-22
Chart Configuration
The settings object provides extensive customization for the chart. Key settings are defined in src/lib/constants.ts and managed within src/components/chart-dialog.tsx.
| Setting | Type | Default Value | Description |
|---|---|---|---|
chart_type | 'bar' | 'donut' | 'bar' | The type of chart to render. |
title | string | 'CVSS Scores Chart' | The main title of the chart. |
should_show_legend | boolean | true | Toggles the visibility of the chart legend. |
legend_position | 'below-title' | 'below-chart' | 'below-chart' | Positions the legend either under the title or under the chart. |
transparency | number | 70 | The opacity percentage for chart colors. |
inner_radius | number | 60 | For donut charts, the percentage of the inner radius. |
bar_radius | number | 5 | For bar charts, the border radius of the bars. |
custom_colors | Record<string, string> | {} | A map of severity names to custom hex color codes. |
severity_labels | Record<string, string> | {} | A map of severity names to custom display labels. |
Sources: src/lib/constants.ts:200-220, src/components/chart-dialog.tsx:509-535
Widget Structure and Rendering
The embedded chart widget is designed to be robust and self-sufficient.
- External Dependencies: The widget loads
Chart.jsand thechartjs-plugin-datalabelsfrom a CDN. This keeps the initial HTML payload small.
Sources: src/lib/embed-chart.ts:128-136 - Loading State: A CSS-animated spinner is displayed while the Chart.js library loads, providing feedback to the user. The chart canvas is hidden until initialization is complete.
Sources: src/lib/embed-chart.ts:153-164, src/lib/embed-chart.ts:232-239 - Chart Initialization: An inline
<script>block contains aninitChartfunction. This function waits forChartandChartDataLabelsto be defined on thewindowobject before proceeding. It then constructs the chart with the data and options embedded as JSON within the script.
Sources: src/lib/embed-chart.ts:228-283 - Dynamic Options: Chart options, such as tooltip formatters and data labels for donut charts, are configured dynamically based on the
settingsobject passed to the generator.
Sources: src/lib/embed-chart.ts:246-269
The following sequence diagram shows how the embedded chart is rendered in a user's browser.
Summary
The embedding feature is a critical component for sharing and disseminating vulnerability information generated by Quant. By creating self-contained HTML widgets with scoped CSS and minimal JavaScript, it allows for seamless integration into external platforms without technical friction or visual inconsistencies. The scorecard widget provides a detailed snapshot of a single vulnerability, while the chart widget offers a configurable, aggregated view of multiple scores, making both invaluable for reporting and communication.