doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements

2026-01-19 09:02:59 +02:00
parent 8c4bf54aed
commit 17419ba7c4
809 changed files with 170738 additions and 12244 deletions
--- a/docs/modules/unknowns/grey-queue-state-machine.md
+++ b/docs/modules/unknowns/grey-queue-state-machine.md
@@ -0,0 +1,119 @@
+# Grey Queue State Machine
+
+Sprint: SPRINT_20260118_018_Unknowns_queue_enhancement (UQ-005)
+
+## State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending: Entry created
+
+    Pending --> Processing: Start processing
+    Pending --> UnderReview: Assign to reviewer
+    Pending --> Expired: TTL exceeded
+    Pending --> Dismissed: Manual dismissal
+
+    Processing --> Retrying: Processing failed (retry)
+    Processing --> UnderReview: Needs human review
+    Processing --> Resolved: Successfully resolved
+    Processing --> Failed: Max attempts exhausted
+
+    Retrying --> Processing: Retry attempt
+    Retrying --> Failed: Max attempts exhausted
+    Retrying --> Expired: TTL exceeded
+
+    UnderReview --> Escalated: Escalate to security
+    UnderReview --> Resolved: Reviewer resolves
+    UnderReview --> Rejected: Reviewer rejects
+    UnderReview --> Pending: Unassign (reset)
+
+    Escalated --> Resolved: Security resolves
+    Escalated --> Rejected: Security rejects
+    Escalated --> UnderReview: De-escalate
+
+    Rejected --> Pending: Reopen
+    Failed --> Pending: Reset for retry
+    Dismissed --> Pending: Reopen
+
+    Resolved --> [*]
+    Expired --> [*]
+```
+
+## States
+
+| State | Description | Entry Criteria | Exit Criteria |
+|-------|-------------|----------------|---------------|
+| **Pending** | Awaiting initial processing | Entry created | Processing started, assigned, expired, or dismissed |
+| **Processing** | Actively being processed by automation | Processing started | Retry, human review, resolved, or failed |
+| **Retrying** | Waiting for retry after failed attempt | Processing failed | Retry attempt, max attempts, or TTL |
+| **UnderReview** | Assigned to human reviewer | Needs human decision | Escalated, resolved, rejected, or unassigned |
+| **Escalated** | Promoted to security team | Reviewer escalates | Security team decision |
+| **Resolved** | Evidence now sufficient (terminal) | Automated or manual resolution | N/A |
+| **Rejected** | Invalid or not actionable | Reviewer/security rejects | Can be reopened |
+| **Failed** | Exhausted all retries (terminal-ish) | Max attempts exceeded | Can be reset |
+| **Expired** | TTL exceeded (terminal) | Time limit reached | N/A |
+| **Dismissed** | Manually dismissed (terminal-ish) | Operator dismissal | Can be reopened |
+
+## State Requirements
+
+### UnderReview
+- **Requires**: `assignee` field must be set
+- **Triggers**: Assignment notification to reviewer
+- **Validation**: Cannot transition without assignee
+
+### Escalated  
+- **Requires**: `escalation_reason` field
+- **Triggers**: Notification to security team
+- **Sets**: `escalated_at` timestamp
+
+### Rejected
+- **Records**: Reason and who rejected
+- **Allows**: Reopening back to Pending
+
+## Valid Transitions
+
+```
+Pending       → [Processing, UnderReview, Expired, Dismissed]
+Processing    → [Retrying, UnderReview, Resolved, Failed]
+Retrying      → [Processing, Failed, Expired]
+UnderReview   → [Escalated, Resolved, Rejected, Pending]
+Escalated     → [Resolved, Rejected, UnderReview]
+Resolved      → []  (terminal)
+Rejected      → [Pending]
+Failed        → [Pending]
+Expired       → []  (terminal)
+Dismissed     → [Pending]
+```
+
+## Transition Audit
+
+All transitions are recorded in `grey_queue_state_transitions` table:
+
+| Column | Description |
+|--------|-------------|
+| `entry_id` | Grey queue entry reference |
+| `from_state` | Previous state |
+| `to_state` | New state |
+| `transitioned_by` | User who triggered transition |
+| `reason` | Optional reason for transition |
+| `transitioned_at` | Timestamp |
+| `metadata` | Additional context (JSONB) |
+
+## API Endpoints
+
+| Endpoint | Transition |
+|----------|------------|
+| `POST /api/grey-queue/{id}/assign` | → UnderReview |
+| `POST /api/grey-queue/{id}/escalate` | → Escalated |
+| `POST /api/grey-queue/{id}/reject` | → Rejected |
+| `POST /api/grey-queue/{id}/reopen` | → Pending |
+| `POST /api/grey-queue/{id}/resolve` | → Resolved |
+| `POST /api/grey-queue/{id}/dismiss` | → Dismissed |
+| `GET /api/grey-queue/{id}/transitions` | Get valid next states |
+
+## Code Reference
+
+- State enum: `src/Unknowns/__Libraries/StellaOps.Unknowns.Core/Models/GreyQueueEntry.cs`
+- State machine: `GreyQueueStateMachine` class in same file
+- Endpoints: `src/Unknowns/StellaOps.Unknowns.WebService/Endpoints/GreyQueueEndpoints.cs`
+- Migration: `devops/database/migrations/V20260119_001__Add_UnderReview_Escalated_Rejected_States.sql`