cve-dashboard/.kiro/specs/fp-submission-editing/requirements.md

# Requirements Document

## Introduction

This feature adds the ability to view, edit, and resubmit existing False Positive (FP) workflow submissions in the STEAM Security Dashboard. Users need to update FP workflows when assets or findings must be added, when supporting documentation needs to be supplemented, or when submissions are rejected or returned for rework by Ivanti reviewers. The feature introduces lifecycle status tracking for FP submissions, an edit modal that loads existing submission data, and backend endpoints that proxy update, map, and attach operations to the Ivanti API.

## Glossary

- **Dashboard**: The STEAM Security Dashboard application
- **FP_Submission**: A local database record in the `ivanti_fp_submissions` table tracking a False Positive workflow submission, including its Ivanti workflow batch ID, form data, finding IDs, attachment history, and lifecycle status
- **Ivanti_API**: The Ivanti/RiskSense REST API at https://platform4.risksense.com/api/v1, authenticated via x-api-key header
- **Workflow_Batch**: An Ivanti API resource representing a group of findings submitted together under a single FP workflow request, identified by a numeric ID and a UUID
- **Lifecycle_Status**: The current state of an FP submission in its review lifecycle: submitted, approved, rejected, rework, or resubmitted
- **Edit_Modal**: The UI modal that loads an existing FP submission's data and allows the user to modify form fields, add findings, and upload additional attachments
- **Submission_History**: A chronological log of changes made to an FP submission, including edits, finding additions, attachment uploads, and status transitions
- **Queue_Panel**: The slide-out panel in the Reporting Page that displays the user's Ivanti todo queue items
- **Workflow_Badge**: The colored status badge displayed in the Workflow column of the Reporting Page findings table, showing the workflow ID and state (e.g., "FP#12345 REWORKED"). States include: expired (red), rejected (red), reworked (amber), actionable (amber), requested (sky blue)
- **Reporting_Table**: The findings table on the Reporting Page that displays host findings with columns including a Workflow column showing Workflow_Badges
- **Ivanti_Update_Endpoint**: The Ivanti API endpoint `POST /workflowBatch/falsePositive/update` used to modify workflow batch metadata (name, reason, description, expiration date)
- **Ivanti_Map_Endpoint**: The Ivanti API endpoint `POST /workflowBatch/falsePositive/{workflowBatchUuid}/map` used to add additional findings to an existing workflow batch
- **Ivanti_Attach_Endpoint**: The Ivanti API endpoint `POST /workflowBatch/falsePositive/{workflowBatchUuid}/attach` used to upload additional file attachments to an existing workflow batch

## Requirements

### Requirement 1: View and Access Existing FP Submissions

**User Story:** As an editor or admin, I want to access my existing FP workflow submissions from the reporting table's workflow badges and from a submissions list, so that I can quickly identify and edit submissions that need attention.

#### Acceptance Criteria

1. THE Dashboard SHALL display a list of FP_Submissions for the authenticated user in the Queue_Panel, showing workflow name, Ivanti workflow batch ID, Lifecycle_Status, finding count, attachment count, and submission date
2. WHEN the user clicks on an FP_Submission in the list, THE Dashboard SHALL open the Edit_Modal pre-populated with the submission's current data including form fields, associated finding IDs, and attachment history
3. THE Dashboard SHALL visually distinguish FP_Submissions by Lifecycle_Status using color-coded status badges: submitted (sky blue), approved (emerald), rejected (red), rework (amber), resubmitted (sky blue)
4. WHILE the user has the viewer role, THE Dashboard SHALL display the FP_Submission list in read-only mode with the edit action disabled
5. WHEN a finding in the Reporting_Table has a Workflow_Badge with state "reworked", "rejected", or "expired", THE Dashboard SHALL render the Workflow_Badge as a clickable element with a pointer cursor and a subtle edit icon (pencil) appended to the badge
6. WHEN the user clicks a clickable Workflow_Badge in the Reporting_Table, THE Dashboard SHALL look up the matching FP_Submission by the workflow batch ID displayed in the badge and open the Edit_Modal pre-populated with that submission's data
7. WHEN the user hovers over a clickable Workflow_Badge, THE Dashboard SHALL display a hover effect (increased border opacity and slight background brightening) to indicate the badge is interactive
8. WHILE a Workflow_Badge has state "requested" or "approved", THE Dashboard SHALL render the badge as non-interactive (no pointer cursor, no edit icon, no click handler) since those states do not require user action

### Requirement 2: Edit FP Workflow Form Fields

**User Story:** As an editor or admin, I want to update the name, reason, description, and expiration date of an existing FP submission, so that I can correct or supplement the justification when a submission is returned for rework.

#### Acceptance Criteria

1. WHEN the Edit_Modal is opened for an existing FP_Submission, THE Dashboard SHALL load and display the current values for workflow name, reason, description, expiration date, and scope override authorization in editable form fields
2. THE Dashboard SHALL apply the same validation rules to edited fields as the creation form: workflow name required and max 255 characters, reason required, description optional and max 2000 characters, expiration date required and must be a future date
3. WHEN the user modifies form fields and clicks Save, THE Dashboard SHALL send the updated fields to the Ivanti_Update_Endpoint to modify the workflow batch metadata in the Ivanti platform
4. IF the Ivanti_Update_Endpoint returns an error, THEN THE Dashboard SHALL display the error message and preserve the user's edits so the user can retry without re-entering data
5. WHEN a form field update completes successfully, THE Dashboard SHALL update the local FP_Submission record with the new field values and record the change in Submission_History

### Requirement 3: Add Findings to Existing FP Submission

**User Story:** As an editor or admin, I want to add additional findings or assets to an existing FP submission, so that I can expand the scope of a false positive workflow when new related findings are identified.

#### Acceptance Criteria

1. THE Edit_Modal SHALL display the current list of finding IDs associated with the FP_Submission and provide a mechanism to add additional findings from the user's Ivanti queue
2. WHEN the user selects additional FP-type queue items to add, THE Dashboard SHALL send the new finding IDs to the Ivanti_Map_Endpoint to map the findings to the existing Workflow_Batch
3. WHEN findings are mapped successfully, THE Dashboard SHALL update the local FP_Submission record's finding_ids_json to include the newly added finding IDs
4. WHEN findings are mapped successfully, THE Dashboard SHALL mark the corresponding queue items as complete and refresh the Queue_Panel
5. IF the Ivanti_Map_Endpoint returns an error, THEN THE Dashboard SHALL display the error message and leave the queue items in their current status

### Requirement 4: Add Attachments to Existing FP Submission

**User Story:** As an editor or admin, I want to upload additional files and screenshots to an existing FP submission, so that I can provide supplementary evidence when reviewers request more documentation.

#### Acceptance Criteria

1. THE Edit_Modal SHALL display the list of previously uploaded attachments (filename and upload status) and provide a file upload area for adding new attachments
2. THE Dashboard SHALL apply the same file constraints as the creation form: maximum 10 MB per file, allowed extensions .pdf, .png, .jpg, .jpeg, .gif, .doc, .docx, .xlsx, .csv, .txt, .zip
3. WHEN the user uploads new files, THE Dashboard SHALL send each file to the Ivanti_Attach_Endpoint to attach the file to the existing Workflow_Batch
4. WHEN an attachment upload completes successfully, THE Dashboard SHALL update the local FP_Submission record's attachment_count and attachment_results_json to include the new attachment
5. IF an attachment upload fails, THEN THE Dashboard SHALL report which attachments failed and allow the user to retry the failed uploads without re-uploading successful attachments

### Requirement 5: FP Submission Lifecycle Status Tracking

**User Story:** As an editor or admin, I want the Dashboard to track the lifecycle status of my FP submissions, so that I can see which submissions are pending review, approved, rejected, or need rework.

#### Acceptance Criteria

1. THE Dashboard SHALL store a Lifecycle_Status field for each FP_Submission with allowed values: submitted, approved, rejected, rework, resubmitted
2. WHEN a new FP workflow is created, THE Dashboard SHALL set the initial Lifecycle_Status to "submitted"
3. WHEN the user manually updates the Lifecycle_Status of an FP_Submission (e.g., marking it as rejected or rework after receiving notification), THE Dashboard SHALL record the status change with a timestamp in Submission_History
4. WHEN an FP_Submission with Lifecycle_Status "rejected" or "rework" is edited and resubmitted, THE Dashboard SHALL update the Lifecycle_Status to "resubmitted"
5. THE Dashboard SHALL prevent editing of FP_Submissions with Lifecycle_Status "approved" and display a message indicating the submission is finalized

### Requirement 6: Submission History and Audit Trail

**User Story:** As an editor or admin, I want to see a history of changes made to an FP submission, so that I can track what was modified and when for audit purposes.

#### Acceptance Criteria

1. THE Edit_Modal SHALL display a Submission_History section showing a chronological list of changes made to the FP_Submission, including: initial creation, form field edits, finding additions, attachment uploads, and status transitions
2. WHEN any modification is made to an FP_Submission, THE Dashboard SHALL log an audit entry with action "ivanti_fp_submission_edited", entity type "ivanti_workflow", the workflow batch ID as entity ID, and details including the type of change and changed values
3. WHEN a Lifecycle_Status transition occurs, THE Dashboard SHALL log an audit entry with action "ivanti_fp_status_changed", entity type "ivanti_workflow", and details including the previous status and new status

### Requirement 7: Backend API Endpoints for FP Editing

**User Story:** As a system component, the backend needs API endpoints to retrieve, update, and extend existing FP submissions, so that the frontend can perform edit operations securely.

#### Acceptance Criteria

1. THE Dashboard SHALL provide a GET /api/ivanti/fp-submissions endpoint that returns the authenticated user's FP_Submission records with all stored fields and Lifecycle_Status
2. THE Dashboard SHALL provide a PUT /api/ivanti/fp-submissions/:id endpoint that accepts updated form fields, validates the input, proxies the update to the Ivanti_Update_Endpoint, and updates the local record
3. THE Dashboard SHALL provide a POST /api/ivanti/fp-submissions/:id/findings endpoint that accepts additional finding IDs, proxies the map operation to the Ivanti_Map_Endpoint, and updates the local record
4. THE Dashboard SHALL provide a POST /api/ivanti/fp-submissions/:id/attachments endpoint that accepts file uploads, proxies each file to the Ivanti_Attach_Endpoint, and updates the local record
5. THE Dashboard SHALL provide a PATCH /api/ivanti/fp-submissions/:id/status endpoint that accepts a new Lifecycle_Status value and updates the local record with the status transition
6. THE Dashboard SHALL restrict all FP submission editing endpoints to users with "Admin" or "Standard_User" group membership
7. THE Dashboard SHALL verify that the authenticated user owns the FP_Submission before allowing any edit operation, returning a 403 status if ownership verification fails

### Requirement 8: Database Schema Updates for Editing Support

**User Story:** As a system component, the database needs additional fields and tables to support FP submission editing, lifecycle tracking, and change history.

#### Acceptance Criteria

1. THE Dashboard SHALL add a lifecycle_status column to the ivanti_fp_submissions table with allowed values: submitted, approved, rejected, rework, resubmitted, defaulting to "submitted"
2. THE Dashboard SHALL add an ivanti_workflow_batch_uuid column to the ivanti_fp_submissions table to store the UUID required by the Ivanti map and attach endpoints
3. THE Dashboard SHALL add an updated_at column to the ivanti_fp_submissions table that is set to the current timestamp on each modification
4. THE Dashboard SHALL create an ivanti_fp_submission_history table with columns: id, submission_id (foreign key), user_id, username, change_type, change_details_json, and created_at
5. THE Dashboard SHALL provide a migration script at backend/migrations/add_fp_submission_editing.js that applies the schema changes idempotently