cve-dashboard/.kiro/specs/batch-finding-disposition/requirements.md

Requirements Document

Introduction

The Batch Finding Disposition feature adds multi-select capability to the Vulnerability Triage page's findings table, allowing engineers to select multiple findings at once and add them all to the Ivanti Queue with a shared workflow type and vendor in a single operation. Currently, each finding must be individually clicked, configured via a popover, and submitted — a repetitive process that slows down triage when working through many findings. This feature replaces that one-at-a-time flow with a batch selection toolbar and a bulk-add API endpoint.

Glossary

• Findings_Table: The sortable, filterable table of Ivanti host findings rendered in the VulnerabilityTriagePage component (ReportingPage.js), where each row represents one finding.
• Selection_Toolbar: A floating toolbar that appears above the Findings_Table when one or more findings are selected via their row checkboxes, displaying the count of selected findings and batch action controls.
• Batch_Add_Panel: The inline panel within the Selection_Toolbar that provides workflow type selection (FP, Archer, CARD), an optional vendor input, and a submit button for adding all selected findings to the queue in one operation.
• Todo_Queue_API: The backend Express router at /api/ivanti/todo-queue that manages CRUD operations on the ivanti_todo_queue table.
• Queue_Panel: The existing right-side slide-out panel (QueuePanel component) that displays the user's current queue items grouped by vendor.
• Workflow_Type: One of three disposition categories: FP (false positive), Archer (risk acceptance), or CARD (remediation card). Each finding added to the queue is assigned exactly one Workflow_Type.
• Finding: A single Ivanti host vulnerability record containing an ID, title, CVEs, IP address, severity, and other metadata.

Requirements

Requirement 1: Multi-Select Findings via Row Checkboxes

User Story: As an engineer, I want to select multiple findings using checkboxes so that I can batch-process them instead of handling each one individually.

Acceptance Criteria

1. THE Findings_Table SHALL render a checkbox in the first column of each finding row that is not already in the queue.
2. WHEN a user clicks a finding row's checkbox, THE Findings_Table SHALL toggle that Finding's selected state without opening the AddToQueuePopover.
3. WHEN one or more findings are selected, THE Findings_Table SHALL visually distinguish selected rows from unselected rows using a highlighted background.
4. THE Findings_Table SHALL maintain the selected findings set across sort and filter changes, removing only findings that are no longer visible after filtering.
5. WHEN a finding is already in the queue, THE Findings_Table SHALL display that row's checkbox as checked and disabled, preventing re-selection.
6. WHILE findings are selected, THE Findings_Table SHALL display a "Select All (visible)" control in the checkbox column header that selects all visible, non-queued findings.
7. WHEN the "Select All" control is clicked while all visible non-queued findings are already selected, THE Findings_Table SHALL deselect all findings.

Requirement 2: Selection Toolbar with Batch Actions

User Story: As an engineer, I want a toolbar that appears when I have findings selected so that I can see how many are selected and take batch actions on them.

Acceptance Criteria

1. WHEN one or more findings are selected, THE Selection_Toolbar SHALL appear as a sticky bar above the Findings_Table header row.
2. THE Selection_Toolbar SHALL display the count of currently selected findings.
3. THE Selection_Toolbar SHALL provide a "Clear Selection" button that deselects all findings and hides the Selection_Toolbar.
4. THE Selection_Toolbar SHALL provide workflow type toggle buttons for FP, Archer, and CARD, matching the existing color scheme (FP: amber, Archer: blue, CARD: green).
5. WHEN the selected Workflow_Type is FP or Archer, THE Selection_Toolbar SHALL display a vendor text input field.
6. WHEN the selected Workflow_Type is CARD, THE Selection_Toolbar SHALL hide the vendor input field and display a "No vendor required" indicator.
7. THE Selection_Toolbar SHALL provide an "Add to Queue" submit button that is enabled only when a Workflow_Type is selected and vendor is provided (for FP/Archer) or Workflow_Type is CARD.
8. THE Selection_Toolbar SHALL follow the existing dark theme design system (monospace fonts, dark gradient backgrounds, accent-colored borders).

Requirement 3: Bulk Add to Queue API Endpoint

User Story: As an engineer, I want the backend to accept multiple findings in a single request so that batch additions are processed efficiently.

Acceptance Criteria

1. THE Todo_Queue_API SHALL expose a POST /api/ivanti/todo-queue/batch endpoint that accepts an array of finding objects with a shared workflow_type and vendor.
2. THE Todo_Queue_API SHALL validate that the findings array contains between 1 and 200 items.
3. THE Todo_Queue_API SHALL validate that each finding object contains a non-empty finding_id string.
4. THE Todo_Queue_API SHALL validate that workflow_type is one of FP, Archer, or CARD.
5. WHEN workflow_type is FP or Archer, THE Todo_Queue_API SHALL validate that vendor is a non-empty string of 200 characters or fewer.
6. WHEN workflow_type is CARD, THE Todo_Queue_API SHALL accept an empty or absent vendor field.
7. THE Todo_Queue_API SHALL insert all valid findings into the ivanti_todo_queue table within a single database transaction.
8. IF any finding in the batch fails validation, THEN THE Todo_Queue_API SHALL reject the entire batch and return a 400 response with a descriptive error message.
9. THE Todo_Queue_API SHALL return a 201 response containing the array of newly created queue items with their assigned IDs.
10. THE Todo_Queue_API SHALL require authentication and the Admin or Standard_User group.
11. IF a database error occurs during the transaction, THEN THE Todo_Queue_API SHALL roll back all inserts and return a 500 response.

Requirement 4: Frontend Batch Submission Flow

User Story: As an engineer, I want clicking "Add to Queue" on the toolbar to submit all selected findings at once so that I save time during triage.

Acceptance Criteria

1. WHEN the user clicks "Add to Queue" on the Selection_Toolbar, THE Findings_Table SHALL send a single POST request to POST /api/ivanti/todo-queue/batch containing all selected findings with the chosen workflow_type and vendor.
2. WHILE the batch request is in progress, THE Selection_Toolbar SHALL disable the "Add to Queue" button and display a loading indicator.
3. WHEN the batch request succeeds, THE Findings_Table SHALL add all returned queue items to the local queue state, clear the selection, and hide the Selection_Toolbar.
4. WHEN the batch request succeeds, THE Findings_Table SHALL update each newly queued finding's row checkbox to show the checked-and-disabled (already queued) state.
5. IF the batch request fails, THEN THE Selection_Toolbar SHALL display the error message returned by the API and keep the current selection intact.
6. WHEN the batch request succeeds and the Queue_Panel is open, THE Queue_Panel SHALL reflect the newly added items immediately without requiring a manual refresh.

Requirement 5: Preserve Single-Select Popover Flow

User Story: As an engineer, I want to still be able to add a single finding to the queue quickly without going through the batch flow, so that simple one-off additions remain fast.

Acceptance Criteria

1. WHEN no findings are currently selected and a user clicks a finding row's checkbox, THE Findings_Table SHALL open the existing AddToQueuePopover for that single finding.
2. WHEN one or more findings are already selected and a user clicks another finding row's checkbox, THE Findings_Table SHALL add that finding to the selection set instead of opening the AddToQueuePopover.
3. THE AddToQueuePopover SHALL continue to use the existing single-item POST /api/ivanti/todo-queue endpoint for individual additions.

Requirement 6: Keyboard Accessibility for Multi-Select

User Story: As an engineer, I want to use keyboard shortcuts to speed up multi-select so that I can triage even faster.

Acceptance Criteria

1. WHEN a user holds Shift and clicks a finding row's checkbox, THE Findings_Table SHALL select all visible findings between the last clicked checkbox and the current checkbox (range select).
2. THE Selection_Toolbar SHALL be navigable via keyboard Tab order, with all interactive elements (workflow buttons, vendor input, submit button) reachable by Tab key.
3. WHEN the Escape key is pressed while the Selection_Toolbar is visible, THE Findings_Table SHALL clear the selection and hide the Selection_Toolbar.