# 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