cve-dashboard/.kiro/specs/cve-tooltip-hover/requirements.md

Requirements Document

Introduction

Add a hover tooltip to CVE badges in the Reporting Page (vuln triage view). When a user hovers over a CVE identifier badge in the findings table, the system checks whether that CVE exists in the local SQLite database. If it does, a small tooltip appears showing a brief description/blurb about that CVE. CVEs not present in the database show no tooltip.

Glossary

• Reporting_Page: The vulnerability triage view at frontend/src/components/pages/ReportingPage.js that displays Ivanti host findings in a sortable, filterable table.
• CVE_Badge: The styled <span> element in the CVEs column of the findings table that displays a CVE identifier (e.g. CVE-2024-12345) with a purple pill/box appearance.
• CVE_Tooltip: A small floating box that appears on mouse hover over a CVE_Badge, displaying a text blurb about the CVE.
• CVE_Database: The cves table in the SQLite database (backend/cve_database.db) that stores CVE records including descriptions, severity, and vendor information.
• Tooltip_Cache: An in-memory lookup (React state or ref) that stores previously fetched CVE descriptions to avoid redundant API calls during the same session.
• API_Server: The Express backend at backend/server.js that serves CVE data via /api endpoints.

Requirements

Requirement 1: CVE Tooltip Data Endpoint

User Story: As a frontend component, I want to fetch a brief description for a given CVE ID, so that the tooltip can display relevant information without loading unnecessary data.

Acceptance Criteria

1. WHEN a GET request is made to /api/cves/:cveId/tooltip, THE API_Server SHALL return a JSON object containing the cve_id, description, and severity fields for the matching CVE record.
2. WHEN a GET request is made to /api/cves/:cveId/tooltip for a CVE ID that does not exist in the CVE_Database, THE API_Server SHALL return a JSON object with { exists: false } and HTTP status 200.
3. WHEN a GET request is made to /api/cves/:cveId/tooltip for a CVE ID that exists in the CVE_Database, THE API_Server SHALL return a JSON object with { exists: true, cve_id, description, severity } and HTTP status 200.
4. THE API_Server SHALL require a valid session cookie for the /api/cves/:cveId/tooltip endpoint.
5. WHEN the description field exceeds 300 characters, THE API_Server SHALL truncate the description to 300 characters and append an ellipsis ("…").

Requirement 2: Tooltip Display on CVE Badge Hover

User Story: As a security analyst triaging findings, I want to see a brief description of a CVE when I hover over its badge in the findings table, so that I can quickly understand the vulnerability without leaving the page.

Acceptance Criteria

1. WHEN the user hovers the mouse cursor over a CVE_Badge in the Reporting_Page findings table, THE Reporting_Page SHALL display a CVE_Tooltip near the hovered badge.
2. WHEN the user moves the mouse cursor away from the CVE_Badge, THE Reporting_Page SHALL hide the CVE_Tooltip.
3. THE CVE_Tooltip SHALL display the CVE description text returned by the API_Server.
4. THE CVE_Tooltip SHALL display the severity level of the CVE using the existing severity color scheme (Critical: red, High: amber, Medium: sky blue, Low: emerald).
5. WHILE the CVE data is being fetched from the API_Server, THE CVE_Tooltip SHALL display a loading indicator.
6. WHEN the API_Server returns exists: false for a CVE ID, THE Reporting_Page SHALL not display a CVE_Tooltip for that badge.

Requirement 3: Tooltip Positioning and Styling

User Story: As a security analyst, I want the CVE tooltip to be readable and not obstruct other table content, so that I can continue triaging while viewing CVE details.

Acceptance Criteria

1. THE CVE_Tooltip SHALL appear above the hovered CVE_Badge by default.
2. WHEN there is insufficient viewport space above the CVE_Badge, THE CVE_Tooltip SHALL appear below the badge instead.
3. THE CVE_Tooltip SHALL have a maximum width of 320 pixels.
4. THE CVE_Tooltip SHALL use the design system dark theme styling: dark background gradient, accent border, monospace font for the CVE ID, and standard font for the description text.
5. THE CVE_Tooltip SHALL include a small directional arrow pointing toward the CVE_Badge.

Requirement 4: Tooltip Response Caching

User Story: As a security analyst scrolling through many findings, I want CVE tooltip data to load instantly for CVEs I have already hovered over, so that repeated hovers do not cause redundant network requests.

Acceptance Criteria

1. WHEN the Reporting_Page fetches tooltip data for a CVE ID, THE Tooltip_Cache SHALL store the response for that CVE ID.
2. WHEN the user hovers over a CVE_Badge for a CVE ID that exists in the Tooltip_Cache, THE Reporting_Page SHALL display the cached data without making an API call.
3. WHEN the user hovers over a CVE_Badge for a CVE ID where the Tooltip_Cache stores exists: false, THE Reporting_Page SHALL not display a tooltip and SHALL not make an API call.
4. WHEN the Reporting_Page performs a full data sync (refresh), THE Tooltip_Cache SHALL be cleared.

Requirement 5: Hover Delay

User Story: As a security analyst, I want the tooltip to only appear after a brief pause on a CVE badge, so that tooltips do not flash distractingly when I move the mouse across the table quickly.

Acceptance Criteria

1. WHEN the user hovers over a CVE_Badge, THE Reporting_Page SHALL wait 300 milliseconds before initiating the tooltip display sequence.
2. IF the user moves the mouse away from the CVE_Badge before 300 milliseconds have elapsed, THEN THE Reporting_Page SHALL cancel the tooltip display and not make an API call.