a61d254ff9
New specs: archer-template-library, ccp-metrics-view-restructure, compliance-list-stale-after-sidebar-edit, compliance-metric-estimated-resolution-date, compliance-remediation-display-fix, flexible-jira-ticket-creation, forecast-burndown-chart, granite-loader-export, ivanti-queue-clear-completed-fix, multi-item-jira-ticket, queue-collapsible-sections, vendor-issue-type-dropdown New steering: archer-template-gen.md Updated: migration-registration-check hook, remediation-plan-history spec, gitlab-workflow, tech, versioning steering files
115 lines
10 KiB
Markdown
115 lines
10 KiB
Markdown
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
The STEAM Security Dashboard currently allows users to create a Jira ticket from a single Ivanti queue item via the "Create Jira Ticket" action (implemented in the `flexible-jira-ticket-creation` spec). In practice, multiple queue items often relate to the same remediation effort — same vendor, same CVE, or same host group. Users need the ability to select multiple Ivanti queue items and create ONE consolidated Jira ticket whose summary and description aggregate information from all selected items. This is not batch creation (one ticket per item) — it is consolidation (N items into 1 ticket).
|
|
|
|
## Glossary
|
|
|
|
- **Ivanti_Queue_Page**: The frontend page where users work through their Ivanti finding queue items.
|
|
- **Queue_Item**: A single row in the `ivanti_todo_queue` table representing a finding assigned to a user for triage.
|
|
- **Selection_Mode**: A UI state on the Ivanti_Queue_Page where checkboxes appear on each Queue_Item, allowing the user to select multiple items.
|
|
- **Consolidation_Modal**: The frontend modal dialog used to create a single Jira ticket from multiple selected Queue_Items, extending the existing Creation_Modal with aggregation logic.
|
|
- **Ticket_Creation_Service**: The backend endpoint (`POST /api/jira-tickets/create-in-jira`) responsible for creating issues in Jira and storing the local record.
|
|
- **Aggregated_Description**: A structured text block composed from the selected Queue_Items' metadata (finding titles, CVEs, hostnames, IP addresses, vendor) formatted for the Jira issue description.
|
|
- **Dashboard**: The STEAM Security Dashboard application.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1: Multi-Select Mode on Ivanti Queue
|
|
|
|
**User Story:** As a security analyst, I want to select multiple items from my Ivanti queue, so that I can act on them as a group.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Ivanti_Queue_Page SHALL display a "Select" toggle button that activates Selection_Mode.
|
|
2. WHILE Selection_Mode is active, THE Ivanti_Queue_Page SHALL display a checkbox on each Queue_Item row.
|
|
3. WHILE Selection_Mode is active, THE Ivanti_Queue_Page SHALL display a selection count indicator showing the number of currently selected items.
|
|
4. WHILE Selection_Mode is active, THE Ivanti_Queue_Page SHALL display a "Select All" checkbox in the table header that toggles selection of all visible Queue_Items.
|
|
5. WHEN the user deactivates Selection_Mode, THE Ivanti_Queue_Page SHALL clear all selections and hide the checkboxes.
|
|
6. THE Ivanti_Queue_Page SHALL preserve the selected items when the user scrolls or when the list re-renders due to filter changes within the same session.
|
|
|
|
### Requirement 2: Create Consolidated Jira Ticket Action
|
|
|
|
**User Story:** As a security analyst, I want to create a single Jira ticket from my selected queue items, so that I can track a group of related findings as one work item.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHILE Selection_Mode is active and at least one Queue_Item is selected, THE Ivanti_Queue_Page SHALL display a "Create Jira Ticket" action button in a floating action bar.
|
|
2. WHEN no Queue_Items are selected, THE Ivanti_Queue_Page SHALL disable the "Create Jira Ticket" action button.
|
|
3. WHEN the user activates the "Create Jira Ticket" action with multiple items selected, THE Ivanti_Queue_Page SHALL open the Consolidation_Modal.
|
|
4. WHEN the user activates the "Create Jira Ticket" action with exactly one item selected, THE Ivanti_Queue_Page SHALL open the existing single-item Creation_Modal with pre-populated fields from that item (existing behavior from flexible-jira-ticket-creation spec).
|
|
|
|
### Requirement 3: Aggregated Summary Generation
|
|
|
|
**User Story:** As a security analyst, I want the consolidated ticket summary to clearly indicate it covers multiple findings, so that I can identify multi-item tickets at a glance.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the Consolidation_Modal opens, THE Consolidation_Modal SHALL pre-populate the Summary field with a generated value in the format: "[N findings] vendor_name - first_finding_title" where N is the count of selected items, vendor_name is the common vendor (if all items share the same vendor) or "Multiple Vendors", and first_finding_title is the finding_title of the first selected item.
|
|
2. THE Consolidation_Modal SHALL truncate the generated summary to 255 characters.
|
|
3. THE Consolidation_Modal SHALL allow the user to edit the pre-populated summary before submission.
|
|
4. IF the user clears the summary field and attempts to submit, THEN THE Consolidation_Modal SHALL prevent submission and display an inline error indicating that Summary is required.
|
|
|
|
### Requirement 4: Aggregated Description Generation
|
|
|
|
**User Story:** As a security analyst, I want the consolidated ticket description to list details from each selected item, so that the Jira ticket contains all relevant finding information.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the Consolidation_Modal opens, THE Consolidation_Modal SHALL generate an Aggregated_Description containing a structured list of all selected Queue_Items.
|
|
2. THE Aggregated_Description SHALL include for each Queue_Item: finding_title, CVE IDs (from cves_json), hostname, IP address, and vendor.
|
|
3. THE Aggregated_Description SHALL group items by vendor when multiple vendors are present.
|
|
4. THE Aggregated_Description SHALL include a header line stating the total count of findings included.
|
|
5. THE Consolidation_Modal SHALL display the Aggregated_Description in an editable text area, allowing the user to modify it before submission.
|
|
6. THE Consolidation_Modal SHALL pre-populate the CVE ID field with the first CVE found across all selected items (from the first item's cves_json array), or leave it blank if no items have CVEs.
|
|
7. THE Consolidation_Modal SHALL pre-populate the Vendor field with the common vendor if all selected items share the same vendor, or leave it blank if vendors differ.
|
|
|
|
### Requirement 5: Consolidated Ticket Creation via Backend
|
|
|
|
**User Story:** As a security analyst, I want the consolidated Jira ticket to be created through the existing ticket creation endpoint, so that it is tracked and synced like any other Jira ticket.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the user submits the Consolidation_Modal, THE Dashboard SHALL send a create-ticket request to the Ticket_Creation_Service with source_context set to `ivanti_queue`, the user-provided summary, and the Aggregated_Description as the description field.
|
|
2. THE Ticket_Creation_Service SHALL accept the request and create the Jira issue using the existing creation flow without modification to the backend endpoint contract.
|
|
3. WHEN the Jira ticket is created successfully, THE Dashboard SHALL store a local record linking the ticket to the selected Queue_Item IDs via a new junction table.
|
|
4. WHEN the Jira ticket is created successfully, THE Dashboard SHALL display a success notification with the created ticket key and a link to the Jira issue.
|
|
5. IF the Jira API returns an error, THEN THE Consolidation_Modal SHALL display an error message and preserve all form field values for retry.
|
|
|
|
### Requirement 6: Queue Item to Ticket Association
|
|
|
|
**User Story:** As a security analyst, I want to see which Jira ticket was created from my queue items, so that I can track the relationship between findings and tickets.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Dashboard SHALL include a `jira_ticket_queue_items` junction table that associates a jira_ticket ID with one or more Queue_Item IDs.
|
|
2. WHEN a consolidated Jira ticket is created, THE Dashboard SHALL insert one row per selected Queue_Item into the junction table.
|
|
3. WHILE viewing a Queue_Item that has an associated Jira ticket, THE Ivanti_Queue_Page SHALL display the linked ticket key as a badge or indicator on that item's row.
|
|
4. WHEN the user clicks the ticket key indicator on a Queue_Item, THE Ivanti_Queue_Page SHALL navigate to or open the Jira ticket URL in a new tab.
|
|
5. THE junction table association SHALL persist regardless of whether the Queue_Item is later marked complete or deleted.
|
|
|
|
### Requirement 7: Database Migration for Junction Table
|
|
|
|
**User Story:** As a database administrator, I want the queue-item-to-ticket association stored in a proper junction table, so that the relationship is queryable and maintainable.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Dashboard SHALL include a migration that creates a `jira_ticket_queue_items` table with columns: id (SERIAL PRIMARY KEY), jira_ticket_id (INTEGER NOT NULL REFERENCES jira_tickets(id)), queue_item_id (INTEGER NOT NULL REFERENCES ivanti_todo_queue(id)), and created_at (TIMESTAMPTZ DEFAULT NOW()).
|
|
2. THE migration SHALL add a unique constraint on (jira_ticket_id, queue_item_id) to prevent duplicate associations.
|
|
3. THE migration SHALL add an index on queue_item_id for efficient lookup of tickets associated with a given queue item.
|
|
4. THE migration SHALL be idempotent — running it multiple times SHALL produce the same schema state without raising errors.
|
|
5. IF the `jira_tickets` or `ivanti_todo_queue` tables do not exist when the migration runs, THEN THE migration SHALL exit with an error message indicating the prerequisite tables are missing.
|
|
|
|
### Requirement 8: Consolidation Modal Source Context and Field Locking
|
|
|
|
**User Story:** As a security analyst, I want the consolidated ticket to automatically track its origin as the Ivanti queue, so that I do not need to manually set the source context.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the Consolidation_Modal opens, THE Consolidation_Modal SHALL set source_context to `ivanti_queue` and display it as read-only.
|
|
2. THE Consolidation_Modal SHALL display the count of selected items in the modal header or subtitle.
|
|
3. WHEN the Consolidation_Modal opens, THE Consolidation_Modal SHALL display a scrollable preview list of the selected Queue_Items showing finding_title and hostname for each.
|
|
4. THE Consolidation_Modal SHALL allow the user to remove individual items from the selection within the modal before submission, with a minimum of 2 items required for consolidation.
|
|
5. IF the user removes items until only 1 remains, THEN THE Consolidation_Modal SHALL display a message indicating that at least 2 items are required for consolidation and disable the submit button.
|