AirlockTools/docs/01_Software_Requirements_Specification.md

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 HTTPS (port 443) 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)
Bypasses policy entirely	Captures hashes for permanent approval
Time-limited bypass only	Results in allowlist additions
No record of what ran	Full hash capture during window
Must re-request for same apps	One-time approval, permanent trust
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