mysticmomba/AirlockTools
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
Files
8fe3a05d8b657af8c60f593943997468c976897e
AirlockTools/docs/01_Software_Requirements_Specification.md
T
Zarithas 8fe3a05d8b Added Telemetry Toggle
2025-12-24 12:26:34 -05:00

1108 lines
44 KiB
Markdown
Raw Blame History

# Loxide
## Software Requirements Specification
**Document Version:** 1.0
**Date:** December 2025
**Authors:** Brandon Wickline (Lead Python Developer), James Brotosky (Lead Rust Developer)
**Status:** Approved
---
## Document Control
### Revision History
| Version | Date | Author | Description |
|---------|------|--------|-------------|
| 0.1 | Jul 2025 | B. Wickline | Initial draft |
| 0.2 | Oct 2025 | J. Brotosky | Added Rust integration requirements |
| 0.3 | Nov 2025 | B. Wickline | Added OTP management, execution history |
| 1.0 | Dec 2025 | B. Wickline | First release candidate |
### Document Approval
| Role | Name | Signature | Date |
|------|------|-----------|------|
| Lead Developer | Brandon Wickline | | |
| Lead Developer | James Brotosky | | |
| Project Sponsor | | | |
### Distribution List
This document is distributed to all project stakeholders including development team members, security administrators, and operations staff.
---
## Table of Contents
1. Introduction
2. Overall Description
3. Specific Requirements
4. External Interface Requirements
5. System Features
6. Non-Functional Requirements
7. Data Requirements
8. Security Requirements
9. Phase 2: LEMON Integration
10. Appendices
---
## 1. Introduction
### 1.1 Purpose
This Software Requirements Specification (SRS) document provides a comprehensive description of the functional and non-functional requirements for Loxide, a terminal-based user interface (TUI) application for managing Airlock endpoint security infrastructure. This document is intended for:
- Development team members responsible for implementation
- Quality assurance personnel responsible for testing
- System administrators who will deploy and operate the system
- Security personnel who will use the system for endpoint management
- Project stakeholders requiring visibility into system capabilities
This document serves as the authoritative source for system requirements and provides the foundation for design, implementation, and testing activities.
### 1.2 Scope
Loxide is a Python-based TUI application that provides an enhanced management interface for Airlock endpoint security infrastructure. The system enables security administrators to perform bulk operations on endpoints, manage security policies, generate and monitor One-Time Passwords (OTPs), and analyze execution history data.
#### 1.2.1 In Scope
The following capabilities are within the scope of this specification:
- Multi-agent selection and bulk operations on endpoints
- Policy lifecycle management including enforcement preparation
- One-Time Password (OTP) generation, monitoring, and revocation
- Execution history analysis with configurable date ranges
- Server activity log monitoring and analysis
- Quiet agent detection for enforcement readiness assessment
- Allowlist management and hash approval workflows
- Secure credential storage using platform-native mechanisms
- Configuration management with system and user-level settings
- Data export capabilities (CSV format)
- Visual analytics through terminal-based charts
#### 1.2.2 Out of Scope
The following items are explicitly excluded from this specification:
- Direct modification of Airlock server configuration
- Agent installation or removal from endpoints
- Network-level security controls
- Integration with third-party SIEM systems (planned for Phase 2)
- Mobile or web-based interfaces
- Real-time alerting and notification systems
### 1.3 Definitions, Acronyms, and Abbreviations
#### 1.3.1 Definitions
| Term | Definition |
|------|------------|
| Agent | Software component installed on endpoints that communicates with the Airlock server and enforces security policies |
| Allowlist | A collection of approved application hashes that are permitted to execute under a security policy |
| Audit Mode | Policy state where unauthorized application executions are logged but not blocked, allowing observation without enforcement |
| Baseline | A predefined set of known-good application hashes used as a reference for policy configuration |
| Blocklist | A collection of prohibited application hashes that are blocked from execution regardless of other policy settings |
| Enforcement Mode | Policy state where unauthorized application executions are actively blocked according to policy rules |
| Execution History | Log of application execution events recorded by agents, including metadata such as filename, hash, publisher, and timestamp |
| Hash | A cryptographic fingerprint (SHA-256) uniquely identifying an application binary |
| One-Time Password (OTP) | A temporary credential that allows bypassing policy restrictions for a specified duration |
| Policy | A set of rules defining which applications can execute on endpoints assigned to a policy group |
| Policy Group | A logical container for security policy configuration that can have multiple agents assigned |
| Publisher | The digital signature certificate holder that signed an application binary |
| Quiet Agent | An endpoint that has not reported any execution activity within a specified time period |
| VirusTotal (VT) Score | A reputation score from VirusTotal indicating how many antivirus engines flagged a hash as malicious |
#### 1.3.2 Acronyms
| Acronym | Expansion |
|---------|-----------|
| API | Application Programming Interface |
| CSV | Comma-Separated Values |
| GUI | Graphical User Interface |
| HTTPS | Hypertext Transfer Protocol Secure |
| JSON | JavaScript Object Notation |
| KDF | Key Derivation Function |
| OTP | One-Time Password |
| PBKDF2 | Password-Based Key Derivation Function 2 |
| TUI | Text User Interface |
| VT | VirusTotal |
| XML | Extensible Markup Language |
### 1.4 References
| Reference | Description |
|-----------|-------------|
| Airlock API Documentation | Official API reference for Airlock server endpoints |
| Textual Framework Documentation | Reference documentation for Textual TUI framework (v6.5.0) |
| Python 3.10+ Language Reference | Official Python programming language specification |
| NIST SP 800-132 | Recommendation for Password-Based Key Derivation |
| airlock_libs Documentation | Internal documentation for private Airlock library package |
### 1.5 Overview
The remainder of this document is organized as follows:
- **Section 2** provides an overall description of the product including its context, functions, user characteristics, constraints, and assumptions
- **Section 3** details specific functional requirements organized by feature area
- **Section 4** describes external interface requirements including user, hardware, software, and communication interfaces
- **Section 5** provides detailed system feature specifications
- **Section 6** specifies non-functional requirements including performance, security, and quality attributes
- **Section 7** details data requirements including data models and persistence
- **Section 8** covers security requirements in depth
- **Section 9** describes planned Phase 2 LEMON integration
- **Section 10** contains appendices with supplementary information
---
## 2. Overall Description
### 2.1 Product Perspective
Loxide operates as a client application that interfaces with an existing Airlock server infrastructure. It provides an enhanced management interface for administrators who require bulk operations, advanced analytics, and streamlined workflows not available in the standard Airlock management console.
#### 2.1.1 System Context
```
+-------------------+
| Airlock Server |
| |
| - Policy Engine |
| - Agent Manager |
| - Hash Database |
| - VT Integration |
+--------+----------+
|
| HTTPS/REST API
|
+------------------+ +--------+----------+
| Endpoints | | Loxide |
| | | |
| +------+ +----+ | | +---------------+ |
| |Agent | |Agent| |<------------->| | TUI Client | |
| +------+ +----+ | Policies | +---------------+ |
| ... | | | |
+------------------+ | +------+------+ |
| | API Wrapper | |
| +-------------+ |
| | |
| +------+------+ |
| | Rust Libs | |
| +-------------+ |
+------------------+
|
+--------+----------+
| Local Storage |
| |
| - Encrypted Keys |
| - Config Files |
| - Log Files |
+-------------------+
```
#### 2.1.2 System Interfaces
Loxide interfaces with the following external systems:
1. **Airlock Server API** - RESTful API providing access to agent management, policy configuration, OTP operations, and execution history data. VirusTotal reputation checking is performed through Airlock's built-in VT integration.
2. **Platform Keyring** - Operating system credential storage for secure API key management
3. **File System** - Local storage for configuration files, logs, and exported data
4. **Private PyPI Server** - Package repository for the airlock_libs dependency
#### 2.1.3 Relationship to Other Products
Loxide complements but does not replace the standard Airlock management console. It is designed for power users requiring:
- Bulk operations across many endpoints
- Scripted or repeatable workflows
- Terminal-based access without GUI dependencies
- Advanced filtering and analysis capabilities
- Integration with terminal-based operational workflows
### 2.2 Product Functions
Loxide provides the following major functional areas:
#### 2.2.1 Multi-Agent Operations
The system enables bulk operations on multiple endpoints simultaneously:
- Selection of agents by hostname, wildcard pattern, or file import
- Movement of agents between policy groups
- Toggling between audit and enforcement modes
- Generation of OTPs for multiple agents
- Viewing execution history for selected agents
#### 2.2.2 Policy Preparation Workflow
A guided workflow for preparing policies for enforcement:
- Selection of source policies for analysis
- Configuration of analysis parameters (history days, allowlists)
- Fetching and categorization of execution history data
- Review of unapproved applications by category
- Addition of approved hashes to allowlists
- Export of analysis results for documentation
#### 2.2.3 Quiet Agent Detection
Identification of inactive endpoints ready for enforcement:
- Configuration of quiet day threshold
- High-performance analysis using Rust libraries
- Review of quiet agent list with policy information
- Bulk movement of quiet agents to enforcement
#### 2.2.4 OTP Management
Complete One-Time Password lifecycle management:
- Generation of OTPs with configurable duration and purpose
- Monitoring of active OTP sessions
- Viewing of applications executed during OTP sessions
- Revocation of active OTPs
- Historical OTP activity analysis
#### 2.2.5 Execution History Analysis
Detailed analysis of application execution events:
- Date range selection for focused analysis
- Filtering by agent, policy, filename, publisher, or hash
- Categorization of executions by approval status
- Export of results for external analysis
- VirusTotal reputation data display (retrieved through Airlock's VT integration)
#### 2.2.6 Server Activity Monitoring
Real-time visibility into Airlock server operations:
- Display of server activity logs
- Configurable time window (default 72 hours)
- Automatic refresh capability
- Filtering and search functionality
### 2.3 User Classes and Characteristics
Loxide is designed for three primary user classes with varying levels of expertise and access requirements:
#### 2.3.1 Administrator
**Description:** Primary users responsible for managing endpoint security policies across the organization. Administrators have full access to all Loxide functionality.
**Characteristics:**
- Advanced technical expertise in endpoint security
- Familiarity with Airlock concepts and configuration
- Comfortable with terminal-based interfaces
- Responsible for policy lifecycle management
- May manage hundreds to thousands of endpoints
**Primary Activities:**
- Policy preparation and enforcement rollout
- Bulk agent operations
- Security posture assessment
- Configuration management
#### 2.3.2 Analyst
**Description:** Security operations personnel who use Loxide for monitoring, investigation, and reporting purposes. Analysts primarily consume data rather than making configuration changes.
**Characteristics:**
- Intermediate technical expertise
- Focus on monitoring and investigation
- May not have full Airlock administrative privileges
- Responsible for security event analysis
**Primary Activities:**
- Execution history analysis
- OTP activity monitoring
- Server log review
- Report generation and export
#### 2.3.3 Support
**Description:** IT support personnel who use Loxide for operational tasks such as OTP generation for end users experiencing application blocking issues.
**Characteristics:**
- Basic to intermediate technical expertise
- Ticket-driven workflow
- Need for quick, targeted operations
- Limited scope of access
**Primary Activities:**
- OTP generation for end users
- Basic agent status lookup
- Escalation of complex issues to administrators
### 2.4 Operating Environment
#### 2.4.1 Hardware Requirements
| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Processor | 64-bit x86 processor | Multi-core processor |
| Memory | 4 GB RAM | 8 GB RAM |
| Storage | 500 MB available | 1 GB available |
| Display | 80x24 terminal | 120x40 terminal |
#### 2.4.2 Software Requirements
| Component | Requirement |
|-----------|-------------|
| Operating System | Windows 10/11, Linux (Ubuntu 24+) |
| Python Runtime | 3.10 or higher (for development/pip install) |
| Terminal | Modern terminal with Unicode and ANSI escape code support |
| Network | HTTPS access to Airlock server |
#### 2.4.3 Network Requirements
- Outbound to Airlock server
- Outbound HTTPS to Gitea instance (development only)
- No inbound connections required
- Proxy support via standard environment variables
### 2.5 Design and Implementation Constraints
#### 2.5.1 Mandatory Requirements
The following requirements are mandatory and non-negotiable:
1. **Terminal-Based Interface** - The application must operate as a TUI without requiring a graphical desktop environment
2. **Secure Credential Storage** - API keys must be stored using platform-native secure storage mechanisms with encryption at rest
3. **HTTPS Communication** - All communication with the Airlock server must use HTTPS
4. **Private Dependency** - The application depends on airlock_libs package hosted on Gitea
5. **Windows Executable Distribution** - The application must be distributable as a standalone Windows executable
#### 2.5.2 Implementation Choices
The following are implementation choices that may be revisited:
| Choice | Rationale | Flexibility |
|--------|-----------|-------------|
| Textual Framework | Python async support, modern styling, active development | May consider alternatives if significant limitations discovered |
| GNU AGPL v3.0 License | Open source with copyleft | License may change based on business requirements |
| Nuitka Compilation | Produces standalone executable, good performance | May consider PyInstaller or other tools |
| PBKDF2-HMAC-SHA256 (200,000 iterations) | Industry standard, configurable security | Parameters may be updated for security improvements |
### 2.6 Assumptions and Dependencies
#### 2.6.1 Assumptions
1. Users have valid Airlock API credentials with appropriate permissions for their role
2. Network connectivity to the Airlock server is available and reliable
3. The terminal emulator supports Unicode characters and ANSI escape sequences
4. Users have basic familiarity with terminal applications
5. The Airlock server API version is compatible with the API wrapper implementation
6. Sufficient disk space is available for log files and exported data
7. VirusTotal integration is configured on the Airlock server for reputation data
#### 2.6.2 Dependencies
| Dependency | Version | Purpose |
|------------|---------|---------|
| textual | 6.5.0 | TUI framework |
| pandas | 2.3.3 | Data manipulation and analysis |
| numpy | 2.3.4 | Numerical operations (pandas dependency) |
| requests | 2.32.5 | HTTP client for API communication |
| pymongo | 4.15.3 | MongoDB client (telemetry, future features) |
| cryptography | 46.0.3 | Encryption primitives |
| keyring | 25.6.0 | Platform keyring integration |
| python-dotenv | 1.2.1 | Environment variable management |
| urllib3 | 2.5.0 | HTTP library (requests dependency) |
| plotext | 5.3.2 | Terminal-based charts |
| pyperclip | 1.11.0 | Clipboard integration |
| airlock_libs | 6.1.1 | Private Airlock integration library (Gitea) |
---
## 3. Specific Requirements
### 3.1 External Interface Requirements
#### 3.1.1 User Interfaces
##### 3.1.1.1 General UI Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| UI-001 | The system shall provide a terminal-based user interface using the Textual framework | Must |
| UI-002 | The interface shall support keyboard-only navigation for all functions | Must |
| UI-003 | The interface shall display a header showing application name and current context | Must |
| UI-004 | The interface shall display a footer showing available keyboard shortcuts | Must |
| UI-005 | The interface shall support multiple color themes selectable by the user | Should |
| UI-006 | The interface shall display progress indicators for long-running operations | Must |
| UI-007 | The interface shall display error messages as toast notifications | Must |
| UI-008 | The interface shall support a minimum terminal size of 80 columns by 24 rows | Must |
| UI-009 | The interface shall gracefully handle terminal resize events | Should |
##### 3.1.1.2 Main Screen Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| UI-010 | The main screen shall provide tabbed navigation for major functional areas | Must |
| UI-011 | The main screen shall display summary statistics for the connected environment | Should |
| UI-012 | The main screen shall indicate the currently connected Airlock server | Must |
| UI-013 | The main screen shall provide access to application settings | Must |
##### 3.1.1.3 Data Display Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| UI-020 | Data tables shall support column sorting where applicable | Should |
| UI-021 | Data tables shall support row selection for bulk operations | Must |
| UI-022 | Data tables shall display scrollbars when content exceeds visible area | Must |
| UI-023 | Data tables shall support keyboard navigation between rows and columns | Must |
| UI-024 | Charts shall render using ASCII/Unicode characters within the terminal | Must |
#### 3.1.2 Hardware Interfaces
The system does not have direct hardware interfaces. All hardware interaction is mediated through the operating system.
#### 3.1.3 Software Interfaces
##### 3.1.3.1 Airlock Server API
| ID | Requirement | Priority |
|----|-------------|----------|
| SW-001 | The system shall communicate with the Airlock server via its REST API | Must |
| SW-002 | The system shall authenticate to the API using an API key in the X-APIKey header | Must |
| SW-003 | The system shall handle API error responses and display appropriate error messages | Must |
| SW-004 | The system shall support configurable API endpoint URLs | Must |
| SW-005 | The system shall implement request timeout handling with configurable timeouts | Should |
| SW-006 | The system shall support SSL certificate verification bypass for self-signed certificates | Must |
| SW-007 | The system shall retrieve VirusTotal reputation data through Airlock's VT integration | Must |
##### 3.1.3.2 Platform Keyring
| ID | Requirement | Priority |
|----|-------------|----------|
| SW-010 | On Windows, the system shall use Windows Credential Manager for credential storage | Must |
| SW-011 | On Linux, the system shall use Secret Service (KWallet/GNOME Keyring) for credential storage | Must |
| SW-012 | The system shall encrypt API keys before storing in the keyring | Must |
| SW-013 | The system shall support credential update and deletion operations | Should |
##### 3.1.3.3 File System
| ID | Requirement | Priority |
|----|-------------|----------|
| SW-020 | The system shall store configuration files in platform-appropriate locations | Must |
| SW-021 | On Windows, configuration shall be stored in %APPDATA%\Loxide | Must |
| SW-022 | On Linux, configuration shall be stored in ~/.local/share/Loxide | Must |
| SW-023 | The system shall create configuration directories if they do not exist | Must |
| SW-024 | The system shall write log files to a logs subdirectory | Must |
| SW-025 | The system shall support exporting data to user-specified file locations | Must |
#### 3.1.4 Communications Interfaces
| ID | Requirement | Priority |
|----|-------------|----------|
| CI-001 | All API communication shall use HTTPS (TLS 1.2 or higher) | Must |
| CI-002 | The system shall use JSON format for API request and response payloads | Must |
| CI-003 | The system shall support HTTP proxy configuration via environment variables | Should |
| CI-004 | The system shall implement connection retry logic for transient failures | Should |
### 3.2 Functional Requirements
#### 3.2.1 Multi-Agent Selection (FR-001)
##### 3.2.1.1 Description
The system shall provide a multi-agent selector widget that enables users to select multiple agents for bulk operations using various selection methods.
##### 3.2.1.2 Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-001-01 | The system shall accept device names via paste input supporting 700+ lines | Must |
| FR-001-02 | The system shall support wildcard patterns using * (any characters) and ? (single character) | Must |
| FR-001-03 | The system shall provide file import functionality for device lists | Must |
| FR-001-04 | The system shall offer exact and fuzzy matching modes | Should |
| FR-001-05 | The system shall display unmatched entries for user review | Must |
| FR-001-06 | The system shall allow selection/deselection of all matched agents | Must |
| FR-001-07 | The system shall display agent count and selection status | Must |
| FR-001-08 | The system shall support search filtering of the agent list | Should |
##### 3.2.1.3 Inputs
- Text input containing device names (one per line or comma-separated)
- File path for device list import
- Wildcard pattern string
- Match mode selection (exact/fuzzy)
##### 3.2.1.4 Processing
1. Parse input text to extract individual device identifiers
2. For each identifier, query the Airlock API for matching agents
3. Apply wildcard expansion for pattern inputs
4. Compile matched and unmatched lists
5. Present results to user for selection confirmation
##### 3.2.1.5 Outputs
- List of selected agent objects with full metadata
- List of unmatched device names
- Selection count summary
#### 3.2.2 Policy Preparation Workflow (FR-002)
##### 3.2.2.1 Description
The system shall provide a multi-step wizard for preparing security policies for enforcement by analyzing execution history and managing allowlists.
##### 3.2.2.2 Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-002-01 | The system shall support selection of multiple source policies for analysis | Must |
| FR-002-02 | The system shall allow configuration of history days (1-365 days) | Must |
| FR-002-03 | The system shall allow selection of destination allowlists for hash approval | Must |
| FR-002-04 | The system shall fetch execution history for all agents in selected policies | Must |
| FR-002-05 | The system shall categorize executions by approval status (approved, unapproved, blocked) | Must |
| FR-002-06 | The system shall display unapproved executions with VT scores from Airlock's VT integration | Must |
| FR-002-07 | The system shall support adding selected hashes to allowlists | Must |
| FR-002-08 | The system shall export analysis results to CSV | Must |
| FR-002-09 | The system shall display progress during data fetch operations | Must |
| FR-002-10 | The system shall handle large execution datasets without memory exhaustion | Must |
##### 3.2.2.3 Workflow Steps
1. **Policy Selection** - User selects one or more source policies
2. **Configuration** - User configures history days and selects allowlists
3. **Data Fetch** - System retrieves execution history from Airlock
4. **Analysis** - System categorizes and summarizes execution data
5. **Review** - User reviews unapproved executions by category
6. **Approval** - User selects hashes to add to allowlist
7. **Export** - User exports results for documentation
#### 3.2.3 Quiet Agent Detection (FR-003)
##### 3.2.3.1 Description
The system shall identify agents with no recent execution activity that may be ready for enforcement mode transition.
##### 3.2.3.2 Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-003-01 | The system shall allow configuration of quiet day threshold | Must |
| FR-003-02 | The system shall analyze agent activity using high-performance Rust code | Must |
| FR-003-03 | The system shall display analysis progress with progress bar | Must |
| FR-003-04 | The system shall list quiet agents with hostname, policy, and last activity date | Must |
| FR-003-05 | The system shall support bulk selection of quiet agents for enforcement | Must |
| FR-003-06 | The system shall suspend the TUI during Rust analysis to show console progress | Must |
#### 3.2.4 OTP Management (FR-004)
##### 3.2.4.1 Description
The system shall provide complete One-Time Password lifecycle management including generation, monitoring, and revocation.
##### 3.2.4.2 Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-004-01 | The system shall generate OTPs for selected agents | Must |
| FR-004-02 | The system shall support configurable OTP duration | Must |
| FR-004-03 | The system shall require purpose/ticket number for OTP generation | Must |
| FR-004-04 | The system shall display generated OTP codes with copy-to-clipboard support | Must |
| FR-004-05 | The system shall list all active OTP sessions | Must |
| FR-004-06 | The system shall display OTP session details including agent, duration, and status | Must |
| FR-004-07 | The system shall allow revocation of active OTPs | Must |
| FR-004-08 | The system shall display applications executed during OTP sessions | Must |
| FR-004-09 | The system shall support filtering OTPs by status (active, awaiting, enforced, revoked) | Should |
#### 3.2.5 Execution History Analysis (FR-005)
##### 3.2.5.1 Description
The system shall provide detailed analysis capabilities for application execution events recorded by agents.
##### 3.2.5.2 Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-005-01 | The system shall support date range selection for history queries | Must |
| FR-005-02 | The system shall display execution events in a sortable data table | Must |
| FR-005-03 | The system shall show filename, publisher, hash, timestamp, and category | Must |
| FR-005-04 | The system shall display VT reputation scores obtained through Airlock's VT integration | Must |
| FR-005-05 | The system shall support export of execution history to CSV | Must |
| FR-005-06 | The system shall support filtering by various criteria | Should |
| FR-005-07 | The system shall handle large result sets with pagination or virtual scrolling | Should |
#### 3.2.6 Server Activity Monitoring (FR-006)
##### 3.2.6.1 Description
The system shall provide visibility into Airlock server activity logs for operational monitoring.
##### 3.2.6.2 Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-006-01 | The system shall display server activity logs | Must |
| FR-006-02 | The system shall support configurable time window (default 72 hours) | Should |
| FR-006-03 | The system shall provide refresh capability (manual and automatic) | Must |
| FR-006-04 | The system shall display timestamp, event type, user, and details | Must |
| FR-006-05 | The system shall format timestamps consistently (YYYY-MM-DD HH:MM:SS) | Must |
#### 3.2.7 Configuration Management (FR-007)
##### 3.2.7.1 Description
The system shall support two-tier configuration with system-level (immutable) and user-level (mutable) settings.
##### 3.2.7.2 Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-007-01 | The system shall load system configuration from bundled system_config.json | Must |
| FR-007-02 | The system shall load user configuration from user_config.json in config directory | Must |
| FR-007-03 | The system shall prevent modification of system configuration keys | Must |
| FR-007-04 | The system shall allow modification of user configuration keys | Must |
| FR-007-05 | The system shall create default user configuration if not present | Must |
| FR-007-06 | The system shall support UI theme selection as user preference | Should |
##### 3.2.7.3 System Configuration Keys
The following keys are system-controlled and cannot be modified by users:
- URL - Airlock server base URL
- APPNAME - Application name
- LOG_LEVEL - Logging verbosity
- BAD_PATH_PARTS - Paths to flag in analysis
- BAD_PUBLISHERS - Publishers to flag in analysis
- PUPS - Potentially Unwanted Programs list
- PATH_EXCLUSION_CONST - Path exclusion threshold
- MIN_FILES_FOR_PATH - Minimum files for path suggestion
- VT_THREAT_TOLERANCE - VirusTotal score threshold (used with Airlock's VT data)
- POLICY_MAP_ENF_AUD - Policy enforcement/audit mappings
##### 3.2.7.4 User Configuration Keys
The following keys can be modified by users:
- TELEMETRY - Opt-in/out for telemetry
- TELEM_URL - Telemetry endpoint URL
- TEXTUAL_THEME - UI theme preference
- EXTRAS - Feature flags
---
## 4. External Interface Requirements
### 4.1 Airlock API Interface
#### 4.1.1 API Overview
Loxide communicates with the Airlock server through its REST API. All operations require authentication via API key. VirusTotal reputation data is obtained through Airlock's built-in VT integration rather than direct VT API calls.
#### 4.1.2 Authentication
```
Header: X-APIKey: <api_key>
Content-Type: application/json
```
#### 4.1.3 API Endpoints Used
| Endpoint | Method | Purpose |
|----------|--------|---------|
| /v1/agent/find | POST | Search for agents |
| /v1/agent/move | POST | Move agent to policy group |
| /v1/group | POST | List policy groups |
| /v1/group/agents | POST | List agents in group |
| /v1/group/policies | POST | List allowlists for group |
| /v1/group/settings/auditmode | POST | Set audit/enforcement mode |
| /v1/application | POST | List allowlists |
| /v1/hash/application/add | POST | Add hashes to allowlist |
| /v1/hash/query | POST | Query hash information (includes VT data from Airlock) |
| /v1/otp/retrieve | POST | Generate OTP |
| /v1/otp/usage | POST | Query OTP usage |
| /v1/otp/revoke | POST | Revoke OTP |
| /v1/otp/activities | POST | Get OTP activities |
| /v1/getexechistory | POST | Get execution history |
| /v1/logging/svractivities | POST | Get server logs |
| /v1/baseline | POST | List baselines |
| /v1/blocklist | POST | List blocklists |
#### 4.1.4 Error Handling
The system shall handle the following API error conditions:
| HTTP Status | Handling |
|-------------|----------|
| 400 Bad Request | Display validation error message |
| 401 Unauthorized | Prompt for credential re-entry |
| 403 Forbidden | Display permission denied message |
| 404 Not Found | Display resource not found message |
| 500 Internal Server Error | Display server error with retry option |
| Network Error | Display connectivity error with retry option |
### 4.2 Data Export Interface
#### 4.2.1 CSV Export Format
All CSV exports shall:
- Use UTF-8 encoding with BOM for Excel compatibility
- Use comma as field delimiter
- Quote fields containing commas, quotes, or newlines
- Include header row with column names
- Use ISO 8601 format for timestamps
#### 4.2.2 Export File Naming
Default export file naming convention:
```
{export_type}_{date}_{time}.csv
Example: execution_history_2025-12-20_143022.csv
```
---
## 5. System Features
### 5.1 Agent Move Operations
#### 5.1.1 Description
Bulk agent management operations including movement between policy groups and mode toggling.
#### 5.1.2 Feature Details
**Move Agents to Policy**
- Select target policy from policy tree
- Confirm selection with agent count
- Execute move with progress indication
- Display results with success/failure counts
**Toggle Enforcement Mode**
- Display current mode for selected agents
- Confirm toggle action
- Execute toggle with progress indication
- Display results
**Local Approval**
- Approve agents locally for testing
- Log approval with purpose/ticket
#### 5.1.3 Dependencies
- Multi-Agent Selector widget
- Airlock API agent_move endpoint
- Airlock API policy_set_auditmode endpoint
### 5.2 Analytics Dashboard
#### 5.2.1 Description
Visual representation of environment status using terminal-based charts.
#### 5.2.2 Feature Details
- Policy distribution charts (agents per policy)
- Enforcement status breakdown
- Execution category breakdown
- OTP activity trends
#### 5.2.3 Dependencies
- plotext library
- Airlock API various endpoints
### 5.3 Allowlist Management
#### 5.3.1 Description
Management of application allowlists for policy configuration.
#### 5.3.2 Feature Details
- List available allowlists
- Add hashes to allowlist
- Export allowlist to XML
- View allowlist contents
---
## 6. Non-Functional Requirements
### 6.1 Performance Requirements
| ID | Requirement | Target |
|----|-------------|--------|
| PF-001 | Application startup time | < 5 seconds |
| PF-002 | Agent list load time (1000 agents) | < 10 seconds |
| PF-003 | Execution history load (30 days, single agent) | < 15 seconds |
| PF-004 | UI response to user input | < 100 milliseconds |
| PF-005 | Memory usage (idle) | < 200 MB |
| PF-006 | Memory usage (large dataset) | < 1 GB |
| PF-007 | CSV export (10,000 rows) | < 30 seconds |
### 6.2 Reliability Requirements
| ID | Requirement |
|----|-------------|
| RL-001 | The system shall handle API timeouts gracefully without crashing |
| RL-002 | The system shall recover from network interruptions |
| RL-003 | The system shall preserve unsaved user input during recoverable errors |
| RL-004 | The system shall log all errors for troubleshooting |
| RL-005 | The system shall not corrupt configuration files on abnormal termination |
### 6.3 Availability Requirements
| ID | Requirement |
|----|-------------|
| AV-001 | The system shall be available whenever the user's workstation is operational |
| AV-002 | The system shall operate in offline mode for cached data review (future) |
| AV-003 | The system shall clearly indicate when Airlock server is unreachable |
### 6.4 Maintainability Requirements
| ID | Requirement |
|----|-------------|
| MT-001 | The system shall use modular architecture with clear separation of concerns |
| MT-002 | The system shall include comprehensive logging for debugging |
| MT-003 | The system shall follow Python PEP 8 style guidelines |
| MT-004 | The system shall include type hints for public interfaces |
| MT-005 | The system shall document all public APIs with docstrings |
### 6.5 Portability Requirements
| ID | Requirement |
|----|-------------|
| PT-001 | The system shall run on Windows 10 and Windows 11 |
| PT-002 | The system shall run on Linux (Ubuntu 24+) |
| PT-003 | The system shall use platform-agnostic APIs where possible |
| PT-004 | Platform-specific code shall be isolated in dedicated modules |
### 6.6 Usability Requirements
| ID | Requirement |
|----|-------------|
| US-001 | All primary functions shall be accessible via keyboard shortcuts |
| US-002 | Keyboard shortcuts shall be displayed in the footer |
| US-003 | Error messages shall be actionable and suggest resolution |
| US-004 | Long-running operations shall display progress indicators |
| US-005 | The system shall provide confirmation dialogs for destructive operations |
| US-006 | The system shall remember user preferences across sessions |
---
## 7. Data Requirements
### 7.1 Data Models
#### 7.1.1 Agent
| Field | Type | Description |
|-------|------|-------------|
| agentid | string | Unique identifier |
| hostname | string | Device hostname |
| groupid | string | Assigned policy group |
| status | integer | Connection status (0=Offline, 1=Online, 3=Safemode) |
| username | string | Logged-in user |
| osversion | string | Operating system version |
| agentversion | string | Agent software version |
| lastcheckin | datetime | Last communication timestamp |
#### 7.1.2 Policy
| Field | Type | Description |
|-------|------|-------------|
| groupid | string | Unique identifier |
| groupname | string | Display name |
| parentid | string | Parent group ID |
| auditmode | integer | Mode (0=Enforcement, 1=Audit) |
| agentcount | integer | Number of assigned agents |
#### 7.1.3 Execution Event
| Field | Type | Description |
|-------|------|-------------|
| id | string | Unique identifier |
| hostname | string | Agent hostname |
| filename | string | Executed file name |
| filepath | string | Full file path |
| sha256 | string | File hash |
| publisher | string | Code signing publisher |
| category | integer | Execution category |
| timestamp | datetime | Execution timestamp |
| username | string | Executing user |
| commandline | string | Command line arguments |
| policyname | string | Active policy name |
| vtscore | integer | VirusTotal detection count (from Airlock VT integration) |
#### 7.1.4 OTP
| Field | Type | Description |
|-------|------|-------------|
| otpid | string | Unique identifier |
| otpcode | string | One-time password value |
| agentid | string | Associated agent |
| duration | integer | Duration in hours |
| purpose | string | Reason/ticket number |
| status | integer | Status (0=Awaiting, 1=Active, 2=Enforced, 3=Revoked) |
| createtime | datetime | Creation timestamp |
| activetime | datetime | Activation timestamp |
| expiretime | datetime | Expiration timestamp |
### 7.2 Data Persistence
#### 7.2.1 Configuration Storage
- System configuration: Bundled JSON file (read-only)
- User configuration: JSON file in config directory (read-write)
#### 7.2.2 Credential Storage
- API keys: Encrypted in platform keyring
- Encryption: AES-256-GCM
- Key derivation: PBKDF2-HMAC-SHA256
#### 7.2.3 Log Storage
- Application logs: Text files in logs directory
- Log rotation: By size or date (configurable)
- Log retention: Configurable days
---
## 8. Security Requirements
### 8.1 Authentication and Authorization
| ID | Requirement |
|----|-------------|
| SE-001 | The system shall require API key authentication for all Airlock operations |
| SE-002 | The system shall support password-protected API key storage |
| SE-003 | The system shall enforce password complexity requirements |
| SE-004 | The system shall lock out after 3 failed password attempts |
| SE-005 | The system shall not display API keys in logs or UI |
### 8.2 Credential Storage Security
| ID | Requirement |
|----|-------------|
| SE-010 | API keys shall be encrypted at rest using AES-256-GCM |
| SE-011 | Encryption keys shall be derived using PBKDF2-HMAC-SHA256 |
| SE-012 | Key derivation shall use minimum 200,000 iterations |
| SE-013 | Each credential shall use a unique random salt (128-bit) |
| SE-014 | Encrypted credentials shall be stored in platform keyring |
### 8.3 Password Requirements
| ID | Requirement |
|----|-------------|
| SE-020 | Passwords shall be minimum 12 characters |
| SE-021 | Passwords shall contain at least one uppercase letter |
| SE-022 | Passwords shall contain at least one lowercase letter |
| SE-023 | Passwords shall contain at least one digit |
| SE-024 | Passwords shall contain at least one special character |
### 8.4 Communication Security
| ID | Requirement |
|----|-------------|
| SE-030 | All API communication shall use HTTPS |
| SE-031 | The system shall support TLS 1.2 and TLS 1.3 |
| SE-032 | Certificate validation shall be configurable (for self-signed certs) |
| SE-033 | API keys shall be transmitted in headers, not URLs |
### 8.5 Data Protection
| ID | Requirement |
|----|-------------|
| SE-040 | Sensitive data shall not be written to log files |
| SE-041 | Exported data shall not contain API credentials |
| SE-042 | Memory containing credentials shall be cleared after use |
| SE-043 | Configuration files shall have restricted permissions |
### 8.6 Audit and Logging
| ID | Requirement |
|----|-------------|
| SE-050 | Security-relevant events shall be logged |
| SE-051 | Logs shall include timestamp, event type, and outcome |
| SE-052 | Authentication failures shall be logged |
| SE-053 | Administrative actions shall be logged |
---
## 9. Phase 2: LEMON Integration
### 9.1 Overview
LEMON (Loxide Execution MONitoring) is a planned backend service that will integrate with Loxide to provide automated hash-based local approval sessions. This capability is planned for Phase 2 development after the core Loxide functionality is stable.
### 9.2 Capability Summary
LEMON will enable:
- **Local Approval Sessions** - Time-limited windows where an endpoint runs in audit mode with automatic hash capture
- **Automatic Hash Approval** - Clean hashes (based on VirusTotal reputation from Airlock's VT integration and publisher rules) automatically added to allowlists
- **Manual Review Queue** - Borderline hashes queued for administrator review in Loxide
- **Device State Management** - Automatic return to enforcement mode when session expires
### 9.3 Key Differentiators from Current OTP
| Current OTP (Phase 1) | LEMON Local Approval (Phase 2) |
|-----------------------|--------------------------------|
| All hashes have to be added manually | Hash additions added automatically based on rules|
| Only Airlock records of what ran | Full hash capture during window |
| Single user operation | Multi-user coordination with RBAC |
### 9.4 Security Requirements
Given LEMON's capability to modify security controls:
- Mutual TLS authentication with internal CA certificates
- All requests cryptographically signed for non-repudiation
- Immutable, hash-chained audit log
- Role-based access control with separate LEMON credentials
### 9.5 Documentation Reference
Complete LEMON specifications are maintained in separate documents:
- LEMON_01_Software_Requirements_Specification.md
- LEMON_02_Software_Design_Document.md
- LEMON_03_User_Stories.md
---
## 10. Appendices
### Appendix A: Glossary
See Section 1.3 for definitions and acronyms.
### Appendix B: Analysis Models
Reserved for data flow diagrams and entity relationship diagrams.
### Appendix C: Requirements Traceability
Requirements traceability matrix mapping requirements to design elements, test cases, and user stories is maintained separately.
### Appendix D: Supporting Information
Additional supporting materials including UI mockups and workflow diagrams are maintained in the project documentation repository.
---
## Document Approval
This Software Requirements Specification has been reviewed and approved for implementation.
| Role | Name | Date |
|------|------|------|
| Author | Brandon Wickline | |
| Technical Reviewer | James Brotosky | |
| Approver | | |
---
*End of Document*
Reference in New Issue View Git Blame Copy Permalink