cve-dashboard/.kiro/specs/vcl-compliance-reporting/requirements.md

Requirements Document

Introduction

This feature adds executive-level VCL (Vulnerability Compliance Level) reporting capabilities to the STEAM Security Dashboard's Compliance module. Leadership requires a dedicated reporting page that mirrors the layout of their existing VCL spreadsheet deck used for executive presentations. The feature also extends device records with remediation tracking fields and introduces bulk upload support for updating approximately 1,000 device records at once with resolution dates, remediation plans, and notes.

Glossary

• Dashboard: The STEAM Security Dashboard application
• Compliance_Module: The existing AEO Compliance section of the Dashboard, which handles weekly xlsx upload, diff preview, per-team metric health cards, and device-level violation tracking
• VCL_Report_Page: A new page within the Compliance_Module that displays executive-level compliance summary statistics, trend charts, and vertical breakdown tables
• Device_Record: A compliance_items row representing a non-compliant asset tracked in the system, identified by hostname and metric_id
• Resolution_Date: A date field on a Device_Record indicating the target date by which remediation is expected to be complete
• Remediation_Plan: A free-text field on a Device_Record describing the planned approach to bring the device into compliance
• Vertical: A logical grouping of devices by business function or organizational unit (e.g., a team or department responsible for a set of assets)
• Compliance_Percentage: The ratio of compliant devices to total in-scope devices, expressed as a percentage
• Target_Compliance: The organization-defined compliance percentage threshold that all verticals are expected to meet
• Burndown: A month-over-month projection of how many non-compliant devices will be remediated, shown as actual (historical) and forecasted (future) values
• Heavy_Hitter: A vertical with a disproportionately high count of non-compliant devices relative to other verticals
• Bulk_Upload: The process of uploading an xlsx file to update multiple Device_Records simultaneously with remediation metadata
• Diff_Preview: A summary view showing proposed changes before they are committed to the database, allowing the user to review and confirm or cancel

Requirements

Requirement 1: Resolution Date Field on Device Records

User Story: As a compliance analyst, I want to set a target resolution date on each non-compliant device, so that leadership can track remediation timelines.

Acceptance Criteria

1. THE Dashboard SHALL store a Resolution_Date field on each Device_Record in the compliance_items table
2. WHEN a user opens the ComplianceDetailPanel for a device, THE Dashboard SHALL display the Resolution_Date field as an editable date input
3. WHEN the user sets or changes the Resolution_Date value and saves, THE Dashboard SHALL persist the updated value to the database
4. THE Dashboard SHALL display the Resolution_Date as a column in the compliance device table view
5. IF the user clears the Resolution_Date field, THEN THE Dashboard SHALL store a null value and display the column cell as empty

Requirement 2: Remediation Plan Field on Device Records

User Story: As a compliance analyst, I want to document a remediation plan for each non-compliant device, so that teams have a clear record of the intended fix.

Acceptance Criteria

1. THE Dashboard SHALL store a Remediation_Plan field on each Device_Record in the compliance_items table
2. WHEN a user opens the ComplianceDetailPanel for a device, THE Dashboard SHALL display the Remediation_Plan field as an editable text area
3. WHEN the user enters or modifies the Remediation_Plan text and saves, THE Dashboard SHALL persist the updated value to the database
4. THE Dashboard SHALL display the Remediation_Plan as a column in the compliance device table view, truncated to 80 characters with an ellipsis when the text exceeds that length
5. THE Dashboard SHALL limit the Remediation_Plan field to 2000 characters

Requirement 3: VCL Executive Summary Statistics Bar

User Story: As an executive, I want to see high-level compliance statistics at a glance, so that I can quickly assess the organization's security posture.

Acceptance Criteria

1. THE VCL_Report_Page SHALL display a summary statistics bar containing: Total Devices, In-Scope count, Compliant count, Non-Compliant count, Remediations Required count, Current Compliance_Percentage, and Target_Compliance percentage
2. WHEN the VCL_Report_Page loads, THE Dashboard SHALL compute the summary statistics from the current compliance data in the database
3. THE Dashboard SHALL format Compliance_Percentage and Target_Compliance as whole-number percentages with a percent sign
4. WHEN the underlying compliance data changes due to a new upload, THE Dashboard SHALL reflect updated statistics upon page refresh

Requirement 4: Compliance Overview Trend Chart

User Story: As an executive, I want to see a monthly compliance trend chart, so that I can understand whether compliance is improving over time.

Acceptance Criteria

1. THE VCL_Report_Page SHALL display a "Compliance Overview" chart showing monthly compliance data
2. THE Chart SHALL render compliant asset counts as vertical bars for each month
3. THE Chart SHALL render the actual Compliance_Percentage as a solid line overlaid on the bar chart
4. THE Chart SHALL render the forecasted Compliance_Percentage as a dashed line extending beyond the current month
5. THE Chart SHALL render the Target_Compliance threshold as a horizontal reference line
6. WHEN fewer than two months of historical data exist, THE Dashboard SHALL display the chart with available data points without forecasting

Requirement 5: Non-Compliant Assets Status Chart

User Story: As an executive, I want to see the breakdown of non-compliant asset statuses, so that I can understand how many are blocked versus in progress.

Acceptance Criteria

1. THE VCL_Report_Page SHALL display a "Status of Non-Compliant Assets" donut chart
2. THE Chart SHALL segment non-compliant devices into "Blocked" and "In-Progress" categories
3. THE Chart SHALL display the count and percentage for each segment
4. WHEN all non-compliant devices belong to a single category, THE Chart SHALL render a full donut in that category's color with the count displayed

Requirement 6: Heavy Hitters Table

User Story: As an executive, I want to see which verticals have the most non-compliant devices, so that I can focus leadership attention on the highest-impact areas.

Acceptance Criteria

1. THE VCL_Report_Page SHALL display a "Heavy Hitters" table showing verticals ranked by non-compliant device count in descending order
2. THE Table SHALL include columns: Vertical name with Responsible Team, Non-Compliant count, Compliance Date (target), and Notes
3. THE Dashboard SHALL derive the Heavy Hitters list from verticals with the highest non-compliant device counts
4. WHEN a vertical has no target Compliance Date set, THE Table SHALL display the cell as empty

Requirement 7: Vertical Breakdown Table

User Story: As an executive, I want a detailed breakdown of compliance by vertical with burndown projections, so that I can track each team's remediation progress against their timeline.

Acceptance Criteria

1. THE VCL_Report_Page SHALL display a detailed vertical breakdown table
2. THE Table SHALL include columns: Vertical, Current Vertical Compliance_Percentage, Responsible Team, Non-Compliant Devices count, Actual Burndown (by month), Forecasted Burndown (by month from current month through Q4 2026), Count Blockers, Count RAs, and Notes
3. THE Dashboard SHALL compute Current Vertical Compliance_Percentage as the ratio of compliant to total in-scope devices within each vertical
4. THE Dashboard SHALL populate Actual Burndown columns with historical monthly remediation counts from upload history
5. THE Dashboard SHALL populate Forecasted Burndown columns with projected monthly remediation counts based on Resolution_Date values of non-compliant devices in each vertical
6. WHEN a vertical has no non-compliant devices, THE Table SHALL display zero values for Non-Compliant Devices, Blockers, and RAs columns

Requirement 8: Bulk Upload for Device Remediation Metadata

User Story: As a compliance analyst, I want to upload an xlsx file to update resolution dates, remediation plans, and notes for many devices at once, so that I do not have to edit each device individually.

Acceptance Criteria

1. THE Dashboard SHALL provide a bulk upload control on the VCL_Report_Page that accepts an xlsx file
2. WHEN the user uploads an xlsx file, THE Dashboard SHALL parse the file and match rows to existing Device_Records by hostname
3. WHEN the file is parsed successfully, THE Dashboard SHALL display a Diff_Preview showing: total rows matched, rows with changes, and a summary of fields to be updated (Resolution_Date, Remediation_Plan, Notes)
4. THE Diff_Preview SHALL highlight rows where the uploaded value differs from the current database value
5. WHEN the user confirms the Diff_Preview, THE Dashboard SHALL commit all changes to the database in a single transaction
6. IF the user cancels the Diff_Preview, THEN THE Dashboard SHALL discard the parsed data without modifying any records
7. IF a row in the uploaded file references a hostname not found in the database, THEN THE Dashboard SHALL flag that row as unmatched in the Diff_Preview and exclude it from the commit
8. THE Dashboard SHALL support xlsx files containing up to 2000 rows without timeout or failure

Requirement 9: Bulk Upload Field Mapping and Validation

User Story: As a compliance analyst, I want the bulk upload to validate my data before committing, so that I do not accidentally corrupt device records with malformed data.

Acceptance Criteria

1. THE Dashboard SHALL require the uploaded xlsx file to contain a "Hostname" column for row matching
2. THE Dashboard SHALL recognize and map the following optional columns: "Resolution Date", "Remediation Plan", "Notes"
3. WHEN a Resolution Date value cannot be parsed as a valid date, THE Dashboard SHALL flag that cell as invalid in the Diff_Preview and exclude the row from the commit
4. WHEN a Remediation Plan value exceeds 2000 characters, THE Dashboard SHALL flag that cell as invalid in the Diff_Preview and exclude the row from the commit
5. IF the uploaded file contains no recognizable columns beyond Hostname, THEN THE Dashboard SHALL display an error message indicating no updatable fields were found
6. THE Dashboard SHALL display the count of valid rows, invalid rows, and unmatched rows in the Diff_Preview summary