cve-dashboard/.kiro/specs/ivanti-queue-redirect/design.md

Design Document: Ivanti Queue Redirect

Overview

The Ivanti Queue Redirect feature adds an optional redirect action to completed queue items, allowing users to create a new pending queue item under a different workflow type from an existing completed item. This supports the common scenario where a CARD inventory fix is done but the finding still needs FP or Archer processing, where an item was assigned to the wrong workflow initially, or where a CARD item with a high asset score (90+) needs to go through the GRANITE program for reassignment or deletion.

The feature consists of five parts:

1. A new backend API endpoint (POST /api/ivanti/todo-queue/:id/redirect) added to the existing ivantiTodoQueue.js route module
2. GRANITE added as a fourth valid workflow type across all backend endpoints (VALID_WORKFLOW_TYPES constant)
3. A redirect modal component in the frontend for collecting target workflow type and vendor
4. A redirect button on completed queue items in the existing QueuePanel
5. Updated QueuePanel grouping: CARD and GRANITE items grouped under an "Inventory" section, with GRANITE also available in the AddToQueue popover

There are four workflow types: FP, Archer, CARD, and GRANITE. FP and Archer require a vendor string; CARD and GRANITE do not. Any completed item can redirect to any other workflow type — there is no fixed ordering between types.

The redirect operation creates a new row in ivanti_todo_queue — it does not modify or delete the original completed item. This preserves the audit trail and allows the original item to remain visible as completed.

Architecture

The feature follows the existing patterns in the codebase:

sequenceDiagram
    participant U as User
    participant QP as QueuePanel
    participant RM as RedirectModal
    participant API as POST /todo-queue/:id/redirect
    participant DB as SQLite (ivanti_todo_queue)
    participant AL as Audit Log

    U->>QP: Clicks redirect button on completed item
    QP->>RM: Opens modal with item context
    U->>RM: Selects target workflow type + vendor
    RM->>API: POST /api/ivanti/todo-queue/:id/redirect
    API->>DB: SELECT original item (verify ownership + complete status)
    API->>DB: INSERT new pending item with target workflow_type
    API->>AL: logAudit (fire-and-forget)
    API-->>RM: 201 + new item JSON
    RM->>QP: Adds new item to list, closes modal, shows success

No new database tables or schema changes are required. The redirect creates a standard ivanti_todo_queue row using the existing schema. Backend changes outside the new endpoint include: adding GRANITE to VALID_WORKFLOW_TYPES, updating all error messages to list four valid types, and treating GRANITE like CARD for vendor validation (no vendor required).

QueuePanel Grouping (Layout)

graph TD
    subgraph QueuePanel
        subgraph Inventory Section
            A[CARD items]
            B[Sub-divider - only when both exist]
            C[GRANITE items]
        end
        subgraph Vendor Groups
            D[Vendor A - FP/Archer items]
            E[Vendor B - FP/Archer items]
        end
    end

The QueuePanel groups items into two categories:

• Inventory section (top): Contains both CARD and GRANITE items under a single "Inventory" heading. CARD items appear first, followed by a subtle sub-divider (only shown when both types are present), then GRANITE items. Each item retains its workflow type badge (CARD in green, GRANITE in warm slate).
• Vendor groups (below): FP and Archer items grouped by vendor, same as current behavior.

Components and Interfaces

Backend: VALID_WORKFLOW_TYPES Constant

Updated from ['FP', 'Archer', 'CARD'] to ['FP', 'Archer', 'CARD', 'GRANITE'].

All endpoints that reference this constant (batch add, single add, PUT, redirect) automatically accept GRANITE. The vendor validation condition changes from workflow_type !== 'CARD' to workflow_type !== 'CARD' && workflow_type !== 'GRANITE' (or equivalently, checking if the type is FP or Archer). The vendorVal assignment similarly treats GRANITE like CARD: vendorVal = (workflow_type === 'CARD' || workflow_type === 'GRANITE') ? '' : vendor.trim().

All error messages for invalid workflow_type are updated to: "workflow_type must be FP, Archer, CARD, or GRANITE.".

Backend: Redirect Endpoint

Added to backend/routes/ivantiTodoQueue.js inside the existing createIvantiTodoQueueRouter factory function.

POST /api/ivanti/todo-queue/:id/redirect

Request body:

{
  "workflow_type": "FP" | "Archer" | "CARD" | "GRANITE",
  "vendor": "string (required for FP/Archer, omitted for CARD/GRANITE)"
}

Success response (201):

{
  "id": 42,
  "user_id": 1,
  "finding_id": "12345",
  "finding_title": "...",
  "cves_json": "[...]",
  "ip_address": "10.0.0.1",
  "hostname": "host.example.com",
  "vendor": "Cisco",
  "workflow_type": "FP",
  "status": "pending",
  "created_at": "...",
  "updated_at": "...",
  "cves": ["CVE-2024-1234"]
}

Error responses:

Status	Condition
400	Item not in "complete" status
400	Invalid workflow_type
400	Missing/invalid vendor for FP/Archer
404	Item not found or belongs to different user
500	Database error

Auth: requireAuth(db), requireGroup('Admin', 'Standard_User')

Backend: Vendor Validation Logic

The vendor requirement is conditional on workflow type across all endpoints:

Workflow Type	Vendor Required	vendorVal
FP	Yes — non-empty, ≤ 200 chars	vendor.trim()
Archer	Yes — non-empty, ≤ 200 chars	vendor.trim()
CARD	No	'' (empty string)
GRANITE	No	'' (empty string)

The condition for requiring vendor changes from workflow_type !== 'CARD' to workflow_type === 'FP' || workflow_type === 'Archer' (or equivalently !['CARD', 'GRANITE'].includes(workflow_type)).

Backend: PUT Validation Fix

In the existing PUT /:id handler, the error message for invalid workflow_type is updated to "workflow_type must be FP, Archer, CARD, or GRANITE.". The same update applies to the batch add, single add, and redirect endpoints.

Frontend: RedirectModal Component

A modal component rendered inside the QueuePanel. It receives the item being redirected and collects:

• Target workflow type (radio buttons: FP, Archer, CARD, GRANITE)
• Vendor (text input, shown only when FP or Archer is selected)

The modal displays read-only context: finding title, finding ID, and current workflow type.

WORKFLOW_OPTIONS constant (updated to include GRANITE):

const WORKFLOW_OPTIONS = [
  { key: 'FP',      label: 'FP',      col: '#F59E0B', rgb: '245,158,11' },
  { key: 'Archer',  label: 'Archer',  col: '#0EA5E9', rgb: '14,165,233' },
  { key: 'CARD',    label: 'CARD',    col: '#10B981', rgb: '16,185,129' },
  { key: 'GRANITE', label: 'GRANITE', col: '#A1887F', rgb: '161,136,127' },
];

The needsVendor condition changes from workflowType === 'FP' || workflowType === 'Archer' — this remains the same since GRANITE, like CARD, does not need vendor.

Props:

{
  item: Object,        // The completed queue item being redirected
  onClose: Function,   // Close the modal
  onRedirect: Function // Callback with the new item after successful redirect
}

Frontend: QueuePanel Changes

Grouping Logic

The current grouping logic filters workflow_type === 'CARD' into a separate top section. This changes to group both CARD and GRANITE into an "Inventory" section:

const grouped = useMemo(() => {
    const inventoryItems = items.filter((i) => i.workflow_type === 'CARD' || i.workflow_type === 'GRANITE');
    const cardItems    = inventoryItems.filter((i) => i.workflow_type === 'CARD');
    const graniteItems = inventoryItems.filter((i) => i.workflow_type === 'GRANITE');
    const otherItems   = items.filter((i) => i.workflow_type !== 'CARD' && i.workflow_type !== 'GRANITE');

    // Vendor groups for FP/Archer items
    const map = {};
    otherItems.forEach((item) => {
        const v = item.vendor || 'Unknown';
        if (!map[v]) map[v] = [];
        map[v].push(item);
    });
    const vendorGroups = Object.keys(map).sort().map((vendor) => ({
        key: vendor, label: vendor, items: map[vendor], isInventory: false,
    }));

    return inventoryItems.length > 0
        ? [{ key: '__INVENTORY__', label: 'Inventory', cardItems, graniteItems, items: inventoryItems, isInventory: true }, ...vendorGroups]
        : vendorGroups;
}, [items]);

Inventory Section Rendering

The Inventory section header uses the existing accent color for the section label. Within the section:

1. CARD items render first
2. A subtle sub-divider appears only when both CARD and GRANITE items exist
3. GRANITE items render below the sub-divider

Each item retains its individual workflow type badge with distinct colors.

Workflow Type Color Mapping

Updated to include GRANITE:

const wfColor = item.workflow_type === 'FP'      ? { col: '#F59E0B', rgb: '245,158,11' }
              : item.workflow_type === 'Archer'   ? { col: '#0EA5E9', rgb: '14,165,233' }
              : item.workflow_type === 'GRANITE'  ? { col: '#A1887F', rgb: '161,136,127' }
              :                                     { col: '#10B981', rgb: '16,185,129' };

GRANITE Item Rendering

GRANITE items render identically to CARD items — showing hostname and ip_address fields (not CVEs), since GRANITE is also an inventory-category workflow. The condition changes from isCardItem to isInventoryItem:

const isInventoryItem = item.workflow_type === 'CARD' || item.workflow_type === 'GRANITE';

Redirect Button

A redirect icon button (CornerUpRight from lucide-react) on each completed queue item row, next to the existing delete button. Visible only when item.status === 'complete' and canWrite is true.

Frontend: AddToQueue Popover

The AddToQueue popover (defined inline in ReportingPage.js) adds GRANITE as a fourth workflow type button:

const QUEUE_WORKFLOW_OPTIONS = [
  { key: 'FP',      label: 'FP',      col: '#F59E0B', rgb: '245,158,11' },
  { key: 'Archer',  label: 'Archer',  col: '#0EA5E9', rgb: '14,165,233' },
  { key: 'CARD',    label: 'CARD',    col: '#10B981', rgb: '16,185,129' },
  { key: 'GRANITE', label: 'GRANITE', col: '#A1887F', rgb: '161,136,127' },
];

When GRANITE is selected, no vendor field is required — same behavior as CARD. The submit logic uses the same condition: workflow_type === 'FP' || workflow_type === 'Archer' to determine if vendor is needed.

Frontend: API Call

const res = await fetch(`${API_BASE}/ivanti/todo-queue/${itemId}/redirect`, {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ workflow_type, vendor })
});

Data Models

No schema changes. The redirect creates a standard ivanti_todo_queue row:

Column	Source
user_id	req.user.id (current user)
finding_id	Copied from original item
finding_title	Copied from original item
cves_json	Copied from original item
ip_address	Copied from original item
hostname	Copied from original item
vendor	From request body (FP/Archer) or empty string (CARD/GRANITE)
workflow_type	From request body (FP, Archer, CARD, or GRANITE)
status	'pending' (always)

The original completed item remains unchanged.

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: Redirect preserves finding data

For any completed queue item with arbitrary finding_id, finding_title, cves_json, ip_address, and hostname values, and for any valid target workflow type (FP, Archer, CARD, or GRANITE), redirecting that item SHALL produce a new queue item where finding_id, finding_title, cves_json, ip_address, and hostname are identical to the original, status is "pending", and workflow_type matches the requested target.

Validates: Requirements 1.1, 1.7

Property 2: Vendor requirement is conditional on workflow type

For any redirect request, if the target workflow_type is "FP" or "Archer", the request SHALL be accepted if and only if vendor is a non-empty string of 200 characters or fewer. If the target workflow_type is "CARD" or "GRANITE", the request SHALL be accepted regardless of whether vendor is provided.

Validates: Requirements 1.2, 1.3, 6.2

Property 3: Successful redirect produces correct audit entry

For any successful redirect operation, the audit log entry SHALL contain action "queue_item_redirected", entityType "ivanti_todo_queue", the original item's ID as entityId, and details including the original workflow_type, the target workflow_type, the new item's ID, and the vendor.

Validates: Requirements 2.1, 2.2

Error Handling

Scenario	HTTP Status	Error Message	Behavior
Item not found or belongs to another user	404	"Queue item not found."	Consistent with existing DELETE/PUT pattern
Item status is not "complete"	400	"Only completed queue items can be redirected."	Prevents redirecting pending items
Invalid workflow_type	400	"workflow_type must be FP, Archer, CARD, or GRANITE."	Same message across all endpoints
Missing/invalid vendor for FP/Archer	400	"vendor is required for FP and Archer workflows."	Same message as existing endpoints
Vendor exceeds 200 chars	400	"vendor must be under 200 chars."	Same message as existing endpoints
Database insert failure	500	"Internal server error."	Consistent with existing error pattern
Frontend API error	—	Display error message from API in modal	Modal stays open so user can retry or cancel

The redirect endpoint reuses the existing isValidVendor() helper and VALID_WORKFLOW_TYPES constant from ivantiTodoQueue.js for consistent validation. All error messages for invalid workflow_type now list all four valid options: FP, Archer, CARD, and GRANITE.

Audit logging uses the existing fire-and-forget pattern — a failed audit log write does not block or fail the redirect response.

Testing Strategy

Unit Tests (Example-Based)

Backend:

• Redirect a completed CARD item to FP with vendor → 201, new item returned
• Redirect a completed FP item to CARD without vendor → 201, new item returned
• Redirect a completed FP item to GRANITE without vendor → 201, new item returned
• Redirect a completed GRANITE item to Archer with vendor → 201, new item returned
• Redirect a pending item → 400
• Redirect another user's item → 404
• Redirect with invalid workflow_type → 400 with message listing FP, Archer, CARD, GRANITE
• Redirect to FP without vendor → 400
• Redirect to FP with vendor > 200 chars → 400
• Redirect non-existent item → 404
• PUT with invalid workflow_type returns error message "workflow_type must be FP, Archer, CARD, or GRANITE."
• Batch add with workflow_type GRANITE and no vendor → 201
• Single add with workflow_type GRANITE and no vendor → 201
• Verify audit log is called with correct fields on successful redirect
• Verify VALID_WORKFLOW_TYPES includes all four types

Frontend:

• Redirect button visible on completed items, hidden on pending items
• Clicking redirect button opens modal with correct item context
• Modal shows all four workflow type options (FP, Archer, CARD, GRANITE)
• Modal shows vendor field for FP/Archer, hides for CARD and GRANITE
• Modal displays finding title, finding ID, current workflow type
• Successful redirect closes modal, adds new item to list, shows notification
• Failed redirect shows error message, modal stays open
• QueuePanel groups CARD and GRANITE items under "Inventory" section
• Sub-divider shown only when both CARD and GRANITE items exist in Inventory section
• "Inventory" heading shown even when only one sub-type present
• GRANITE badge uses warm slate color (#A1887F)
• CARD badge uses green color (#10B981)
• AddToQueue popover shows GRANITE as fourth option with warm slate color
• Selecting GRANITE in AddToQueue popover does not require vendor

Property-Based Tests

Library: fast-check (JavaScript property-based testing library)

Each property test runs a minimum of 100 iterations.

• Property 1: Generate random queue item data (finding_id, finding_title, cves_json, ip_address, hostname with varying lengths, special characters, null optionals) and random valid workflow_type from all four types (FP, Archer, CARD, GRANITE). Mock the database layer. Verify the INSERT parameters preserve all finding fields and set status to "pending".

  • Tag: Feature: ivanti-queue-redirect, Property 1: Redirect preserves finding data

• Property 2: Generate random (workflow_type, vendor) pairs where workflow_type is drawn from all four valid types and vendor is drawn from a mix of valid strings, empty strings, whitespace, strings of length 200, and strings of length 201. Verify that the validation logic accepts/rejects correctly: FP/Archer require non-empty vendor ≤ 200 chars; CARD/GRANITE accept without vendor.

  • Tag: Feature: ivanti-queue-redirect, Property 2: Vendor requirement is conditional on workflow type

• Property 3: Generate random successful redirect scenarios with varying item data and all four workflow types. Mock logAudit. Verify the audit call contains the correct action, entityType, entityId, and all required detail fields.

  • Tag: Feature: ivanti-queue-redirect, Property 3: Successful redirect produces correct audit entry