From 6644826fcfcf5c4620803bab2b669c39e4c61d50 Mon Sep 17 00:00:00 2001
From: Zarithas <drivenelement@proton.me>
Date: Mon, 22 Dec 2025 12:26:35 -0500
Subject: [PATCH] Add User Stories and Use Cases

---
 User-Stories-and-Use-Cases.md | 510 ++++++++++++++++++++++++++++++++++
 1 file changed, 510 insertions(+)
 create mode 100644 User-Stories-and-Use-Cases.md

diff --git a/User-Stories-and-Use-Cases.md b/User-Stories-and-Use-Cases.md
new file mode 100644
index 0000000..6949755
--- /dev/null
+++ b/User-Stories-and-Use-Cases.md
@@ -0,0 +1,510 @@
+# Loxide
+## User Stories and Use Cases
+
+**Version 1.0 | December 2025**
+
+---
+
+## Epic 1: Multi-Agent Operations
+
+**Epic Statement:** As a administrator, I need to perform bulk operations on multiple endpoints efficiently.
+
+---
+
+### US-1.1: Agent Selection
+
+**User Story:** As a administrator, I want to select multiple agents using various methods so that I can perform bulk operations efficiently.
+
+**Acceptance Criteria:**
+- ✅ Can paste a list of device names (700+ lines)
+- ✅ Can use wildcards (* and ?) for pattern matching
+- ✅ Can import device names from a file
+- ✅ Can toggle between exact and fuzzy matching
+- ✅ Unmatched entries are clearly displayed
+- ✅ Can select/deselect all matched agents
+
+**Priority:** High  
+**Story Points:** 8
+
+---
+
+### US-1.2: Agent Policy Move
+
+**User Story:** As a administrator, I want to move selected agents to a different policy group so that I can organize endpoints by security requirements.
+
+**Acceptance Criteria:**
+- ✅ Can select destination policy from list
+- ✅ Move operation provides progress feedback
+- ✅ Success/failure results are color-coded
+- ✅ Can export results to CSV
+
+**Priority:** High  
+**Story Points:** 5
+
+---
+
+### US-1.3: Toggle Enforcement Mode
+
+**User Story:** As a administrator, I want to toggle agents between audit and enforcement mode so that I can gradually roll out policy enforcement.
+
+**Acceptance Criteria:**
+- ✅ Clear indication of current mode
+- ✅ Confirmation before mode change
+- ✅ Results displayed after operation
+
+**Priority:** High  
+**Story Points:** 3
+
+---
+
+### US-1.4: View Agent Execution History
+
+**User Story:** As a administrator, I want to view execution history for selected agents so that I can understand what applications are running.
+
+**Acceptance Criteria:**
+- ✅ Date range selector (1-365 days)
+- ✅ Results displayed in DataTable
+- ✅ Export to CSV functionality
+- ✅ Sortable columns
+
+**Priority:** Medium  
+**Story Points:** 5
+
+---
+
+## Epic 2: Policy Preparation
+
+**Epic Statement:** As a administrator, I need to prepare policies for enforcement by analyzing execution history.
+
+---
+
+### US-2.1: Policy Selection
+
+**User Story:** As a administrator, I want to select source policies for analysis so that I can review their execution history.
+
+**Acceptance Criteria:**
+- ✅ Multi-select with checkboxes
+- ✅ Filter/search capability
+- ✅ Policy hierarchy visible
+
+**Priority:** High  
+**Story Points:** 5
+
+---
+
+### US-2.2: Configure Analysis Parameters
+
+**User Story:** As a administrator, I want to configure history days and allowlists so that I can customize the analysis scope.
+
+**Acceptance Criteria:**
+- ✅ History days configurable from 1 to 365
+- ✅ Default value clearly indicated
+- ✅ Allowlist selection available
+- ✅ Input validation with helpful error messages
+
+**Priority:** High  
+**Story Points:** 3
+
+---
+
+### US-2.3: Review Analysis Results
+
+**User Story:** As a administrator, I want to review categorized execution history so that I can make informed enforcement decisions.
+
+**Acceptance Criteria:**
+- ✅ Results categorized: Approved, Unapproved, Needs Review
+- ✅ Hash reputation data displayed
+- ✅ Publisher information shown
+- ✅ Export to CSV available
+- ✅ Color-coded categories
+
+**Priority:** High  
+**Story Points:** 8
+
+---
+
+### US-2.4: Add Hashes to Allowlist
+
+**User Story:** As a administrator, I want to add approved hashes to an allowlist so that they won't be blocked after enforcement.
+
+**Acceptance Criteria:**
+- ✅ Select hashes from analysis results
+- ✅ Choose target allowlist
+- ✅ Confirmation before adding
+- ✅ Success/failure feedback
+
+**Priority:** Medium  
+**Story Points:** 5
+
+---
+
+## Epic 3: Quiet Agent Detection
+
+**Epic Statement:** As a administrator, I need to identify inactive endpoints ready for enforcement.
+
+---
+
+### US-3.1: Configure Quiet Threshold
+
+**User Story:** As a administrator, I want to set quiet day thresholds so that I can define what constitutes an inactive agent.
+
+**Acceptance Criteria:**
+- ✅ Configurable quiet days parameter
+- ✅ History days parameter
+- ✅ Clear explanation of thresholds
+- ✅ Input validation
+
+**Priority:** High  
+**Story Points:** 3
+
+---
+
+### US-3.2: Run Quiet Agent Analysis
+
+**User Story:** As a administrator, I want the system to analyze agent activity using high-performance Rust code so that I can quickly identify quiet agents.
+
+**Acceptance Criteria:**
+- ✅ Progress bar during analysis
+- ✅ Console output for Rust progress
+- ✅ Non-blocking UI during analysis
+- ✅ Clear completion notification
+
+**Priority:** High  
+**Story Points:** 8
+
+---
+
+### US-3.3: View Quiet Agents
+
+**User Story:** As a administrator, I want to see a list of quiet agents so that I can move them to enforcement.
+
+**Acceptance Criteria:**
+- ✅ Results displayed in sortable table
+- ✅ Can select agents for bulk move
+- ✅ Last activity date shown
+- ✅ Export to CSV
+
+**Priority:** High  
+**Story Points:** 5
+
+---
+
+## Epic 4: OTP Management
+
+**Epic Statement:** As an support technician, I need to manage temporary policy bypasses for end users.
+
+---
+
+### US-4.1: Generate OTP
+
+**User Story:** As an support technician, I want to generate an OTP for an agent so that a user can temporarily bypass policy restrictions.
+
+**Acceptance Criteria:**
+- ✅ Select agent by hostname
+- ✅ Specify duration in minutes
+- ✅ Enter purpose/ticket number
+- ✅ OTP code displayed clearly
+- ✅ Copy to clipboard functionality
+
+**Priority:** High  
+**Story Points:** 5
+
+---
+
+### US-4.2: View Active OTPs
+
+**User Story:** As a administrator, I want to view all active OTP sessions so that I can monitor temporary policy bypasses.
+
+**Acceptance Criteria:**
+- ✅ List all active OTPs
+- ✅ Show hostname, purpose, expiration
+- ✅ Filter by status
+- ✅ Refresh capability (r key)
+- ✅ Sortable columns
+
+**Priority:** High  
+**Story Points:** 5
+
+---
+
+### US-4.3: Revoke OTP
+
+**User Story:** As a administrator, I want to revoke an active OTP so that I can end a temporary bypass immediately.
+
+**Acceptance Criteria:**
+- ✅ Select OTPs for revocation (checkbox)
+- ✅ Bulk revoke capability
+- ✅ Confirmation before revocation
+- ✅ Results displayed after operation
+- ✅ Auto-refresh list after revocation
+
+**Priority:** High  
+**Story Points:** 5
+
+---
+
+### US-4.4: View OTP Activities
+
+**User Story:** As a administrator, I want to see what applications were executed during an OTP session so that I can audit temporary bypasses.
+
+**Acceptance Criteria:**
+- ✅ Select OTP to view
+- ✅ Display execution list
+- ✅ Show file, hash, timestamp
+- ✅ Export capability
+
+**Priority:** Medium  
+**Story Points:** 5
+
+---
+
+## Epic 5: Execution History
+
+**Epic Statement:** As a analyst, I need to investigate execution events on endpoints.
+
+---
+
+### US-5.1: Query Execution History
+
+**User Story:** As a analyst, I want to query execution history for specific agents so that I can investigate security events.
+
+**Acceptance Criteria:**
+- ✅ Select agent by hostname
+- ✅ Configure date range (start/end)
+- ✅ Filter by execution type
+- ✅ Results in sortable DataTable
+- ✅ Pagination for large results
+
+**Priority:** High  
+**Story Points:** 8
+
+---
+
+### US-5.2: Export History
+
+**User Story:** As a analyst, I want to export execution history to CSV so that I can perform offline analysis.
+
+**Acceptance Criteria:**
+- ✅ Export button available (e key)
+- ✅ All visible columns included
+- ✅ Proper CSV formatting
+- ✅ Timestamp in filename
+- ✅ Notification on success
+
+**Priority:** Medium  
+**Story Points:** 3
+
+---
+
+### US-5.3: Hash Reputation Lookup
+
+**User Story:** As a analyst, I want to see reputation data for executed files so that I can assess risk.
+
+**Acceptance Criteria:**
+- ✅ VirusTotal score displayed
+- ✅ Publisher information shown
+- ✅ Known allowlist membership indicated
+- ✅ Risk categorization (approved/unapproved/needs_review)
+
+**Priority:** Medium  
+**Story Points:** 5
+
+---
+
+## Epic 6: Server Monitoring
+
+**Epic Statement:** As a system administrator, I need to monitor Airlock server activity.
+
+---
+
+### US-6.1: View Server Logs
+
+**User Story:** As a system administrator, I want to view recent server activity so that I can monitor system health.
+
+**Acceptance Criteria:**
+- ✅ Default view of last 72 hours
+- ✅ Datetime properly formatted (YYYY-MM-DD HH:MM:SS)
+- ✅ Refresh via keyboard shortcut (r)
+- ✅ Escape to return to main menu
+- ✅ Auto-scroll to latest entries
+
+**Priority:** Medium  
+**Story Points:** 5
+
+---
+
+## Epic 7: Application Configuration
+
+**Epic Statement:** As a power user, I need to customize the application to my preferences.
+
+---
+
+### US-7.1: Theme Selection
+
+**User Story:** As a power user, I want to change the UI theme so that I can work comfortably in different lighting conditions.
+
+**Acceptance Criteria:**
+- ✅ Multiple themes available (textual-dark, gruvbox, retro-terminal, amber-terminal)
+- ✅ Theme persists across sessions
+- ✅ Preview before applying
+- ✅ Saved to user config
+
+**Priority:** Low  
+**Story Points:** 3
+
+---
+
+### US-7.2: Working Directory Access
+
+**User Story:** As a power user, I want to access my working directory from within the application so that I can manage exported files.
+
+**Acceptance Criteria:**
+- ✅ Directory tree visible in main menu
+- ✅ Keyboard shortcut to open in file manager (f)
+- ✅ Configurable working directory
+- ✅ Auto-create directory structure
+
+**Priority:** Low  
+**Story Points:** 3
+
+---
+
+### US-7.3: Credential Management
+
+**User Story:** As a user, I want my API credentials stored securely so that I don't have to enter them every time.
+
+**Acceptance Criteria:**
+- ✅ First-time setup prompts for API key
+- ✅ Master password protects credentials
+- ✅ Password complexity requirements enforced
+- ✅ 3 retry attempts on wrong password
+- ✅ Platform-native keyring used
+
+**Priority:** High  
+**Story Points:** 8
+
+---
+
+## Epic 8: Statistics and Reporting
+
+**Epic Statement:** As a administrator, I need visibility into my environment's security posture.
+
+---
+
+### US-8.1: View System Statistics
+
+**User Story:** As a administrator, I want to see an overview of agents and policies so that I can understand my environment.
+
+**Acceptance Criteria:**
+- ✅ Total agent count
+- ✅ Total policy count
+- ✅ Agent status breakdown (Online/Offline/Hidden/Safemode)
+- ✅ Visual charts using plotext
+- ✅ Configurable time range (1/7/30 days)
+
+**Priority:** Medium  
+**Story Points:** 5
+
+---
+
+### US-8.2: View Execution Statistics
+
+**User Story:** As a administrator, I want to see execution statistics so that I can identify trends.
+
+**Acceptance Criteria:**
+- ✅ Execution counts by type
+- ✅ Top executed files
+- ✅ Top blocked files
+- ✅ Visual bar charts
+- ✅ Refresh capability
+
+**Priority:** Medium  
+**Story Points:** 5
+
+
+---
+
+## Phase 2: LEMON Integration
+
+**Project:** LEMON (Loxide Execution MONitoring)  
+**Previous Codename:** Overlock  
+**Status:** Phase 2 - Separate Project
+
+LEMON user stories are documented separately in `LEMON_03_User_Stories.md`.
+
+**Summary of Phase 2 Loxide Stories:**
+- LEMON Sessions Screen - View/create/cancel sessions
+- LEMON Hash Review Screen - Approve/reject pending hashes
+- Certificate Setup - Configure mTLS authentication
+- Audit Chain Verification - Verify log integrity
+
+See LEMON documentation for complete user stories.
+
+---
+
+## Acceptance Test Scenarios
+
+### Scenario: Bulk Agent Move
+
+```gherkin
+Given I am on the Multi-Agent Operations screen
+When I paste 100 device names into the selector
+And I click Search
+Then I should see matched agents in the selection list
+When I select 50 agents using checkboxes
+And I choose "Production Policy" as destination
+And I click "Move Selected"
+Then I should see a progress indicator
+And I should see 50 success results with green indicators
+And I should be able to export results to CSV
+```
+
+### Scenario: OTP Generation and Revocation
+
+```gherkin
+Given I am on the OTP Management screen
+When I search for agent "DESKTOP-001"
+And I set duration to 60 minutes
+And I enter purpose "Ticket #12345 - Software installation"
+And I click Generate OTP
+Then I should see an 8-character OTP code
+And I should be able to copy it to clipboard
+
+Given the OTP is active
+When I navigate to OTP Revoke screen
+And I select the OTP for "DESKTOP-001"
+And I click "Revoke Selected"
+Then I should see confirmation dialog
+When I confirm revocation
+Then I should see success message
+And the OTP should no longer appear in active list
+```
+
+### Scenario: Policy Preparation Workflow
+
+```gherkin
+Given I am on the Policy Prep screen
+When I select "Audit Policy A" and "Audit Policy B"
+And I set history days to 30
+And I click Next
+Then I should see execution history being fetched
+
+When the fetch completes
+Then I should see categorized results:
+  | Category | Count |
+  | Approved | 150 |
+  | Unapproved | 25 |
+  | Needs Review | 10 |
+
+When I click "Export to CSV"
+Then I should see a file saved notification
+And the CSV should contain all execution records
+```
+
+---
+
+## License
+
+Copyright (C) 2025 James Brotosky, Brandon Wickline
+
+GNU Affero General Public License v3.0