380 lines
11 KiB
Markdown
380 lines
11 KiB
Markdown
# Loxide
|
|
|
|
A Python/Rust toolkit for secure, auditable, and automated Airlock agent and policy management. Designed for enterprise environments, Loxide provides advanced policy workflows, device tracking, and a modern terminal-based interface for security administrators who need bulk operations and streamlined workflows not available in the standard Airlock console.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
- [Features](#features)
|
|
- [Installation](#installation)
|
|
- [Configuration](#configuration)
|
|
- [Usage](#usage)
|
|
- [Workflows](#workflows)
|
|
- [Architecture](#architecture)
|
|
- [Keyboard Reference](#keyboard-reference)
|
|
- [Roadmap](#roadmap)
|
|
- [Authors](#authors)
|
|
- [License](#license)
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### Multi-Agent Operations
|
|
|
|
Select and operate on multiple endpoints simultaneously using hostname, wildcard patterns (`*`, `?`), or file import. Supports lists of 700+ devices with fuzzy matching.
|
|
|
|
- Move agents between policy groups in bulk
|
|
- Toggle between audit and enforcement modes
|
|
- Generate OTPs for multiple agents at once
|
|
- View execution history across selected devices
|
|
- Export operation results to CSV
|
|
|
|
### Policy Preparation Workflow
|
|
|
|
A guided multi-step wizard for safely transitioning policies from audit to enforcement:
|
|
|
|
1. Select source policies for analysis (multi-select with checkboxes)
|
|
2. Choose destination policy and allowlist
|
|
3. Configure analysis parameters (1-365 day history window)
|
|
4. Fetch and categorize execution history data
|
|
5. Review unapproved applications by category
|
|
6. Add approved hashes to allowlists
|
|
7. Export analysis results for documentation
|
|
|
|
### Quiet Agent Detection
|
|
|
|
Identify inactive endpoints that are ready for enforcement using high-performance Rust-powered analysis:
|
|
|
|
- Configure quiet day threshold and history parameters
|
|
- Analyze agent activity patterns efficiently
|
|
- Review quiet agent list with policy information
|
|
- Bulk move quiet agents to enforcement policies
|
|
|
|
### OTP Management
|
|
|
|
Complete One-Time Password lifecycle management for handling application blocking issues:
|
|
|
|
- Generate OTPs with configurable duration and purpose
|
|
- Monitor active OTP sessions in real-time
|
|
- View applications executed during OTP windows
|
|
- Revoke active OTPs when needed
|
|
- Analyze historical OTP activity
|
|
|
|
### Execution History Analysis
|
|
|
|
Detailed analysis of application execution events across your environment:
|
|
|
|
- Date range selection (configurable 1-365 days)
|
|
- Filter by agent, policy, filename, publisher, or hash
|
|
- Categorize executions by approval status (18 execution types)
|
|
- VirusTotal reputation data via Airlock's integration
|
|
- Export results to CSV for external analysis
|
|
|
|
### Server Activity Monitoring
|
|
|
|
Real-time visibility into Airlock server operations:
|
|
|
|
- DataTable display of server activity logs
|
|
- Configurable time window (default 72 hours)
|
|
- Auto-refresh capability
|
|
- Search and filter functionality
|
|
|
|
### Modern Terminal Interface
|
|
|
|
Built with Textual 6.5.0 for a responsive, keyboard-driven experience:
|
|
|
|
- Full keyboard navigation with discoverable shortcuts
|
|
- Tab-based workflow organization
|
|
- Toast notifications for operations
|
|
- Color-coded status indicators
|
|
- Multiple theme options (Gruvbox, Amber Terminal, Retro Terminal)
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.10 or higher
|
|
- Access to Airlock API server
|
|
- Network access to private PyPI server (for airlock_libs)
|
|
- Modern terminal with Unicode support (80x24 minimum, 120x40 recommended)
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.racooncity.org/brotoskyj/loxide.git
|
|
cd loxide
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Run the application
|
|
python Loxide.py
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
```
|
|
# Core TUI Framework
|
|
textual==6.5.0
|
|
|
|
# API and Data Handling
|
|
requests==2.32.5
|
|
pandas==2.3.3
|
|
numpy==2.3.4
|
|
|
|
# Database
|
|
pymongo==4.15.3
|
|
|
|
# Security
|
|
cryptography==46.0.3
|
|
keyring==25.6.0
|
|
|
|
# Utilities
|
|
python-dotenv==1.2.1
|
|
tqdm==4.67.1
|
|
urllib3==2.5.0
|
|
pyperclip==1.11.0
|
|
|
|
# Private Package (Rust integration)
|
|
--extra-index-url https://git.racooncity.org/api/packages/brotoskyj/pypi/simple/
|
|
airlock_libs==5.2.1
|
|
```
|
|
|
|
See also: [airlock_libs documentation](https://git.racooncity.org/brotoskyj/-/packages/pypi/airlock-libs/)
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### First Run
|
|
|
|
On first launch, Loxide will prompt for your Airlock API credentials. These are securely stored using your platform's native keyring (Windows Credential Manager, macOS Keychain, or Linux Secret Service) with an additional encryption layer.
|
|
|
|
### Configuration Files
|
|
|
|
Loxide uses two configuration files:
|
|
|
|
| File | Location | Purpose |
|
|
|------|----------|---------|
|
|
| `system_config.json` | Application directory | System defaults, bundled with application |
|
|
| `user_config.json` | User home directory | User preferences, created on first run |
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `LOXIDE_LOG_LEVEL` | Logging verbosity (DEBUG, INFO, WARNING, ERROR) |
|
|
| `HTTPS_PROXY` | Proxy server for Airlock API connections |
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
python Loxide.py
|
|
```
|
|
|
|
### Main Interface
|
|
|
|
The application opens to a tabbed interface with the following sections:
|
|
|
|
| Tab | Description |
|
|
|-----|-------------|
|
|
| Dashboard | Summary statistics and environment overview |
|
|
| Agent Operations | Multi-agent selection and bulk operations |
|
|
| Policy Prep | Policy enforcement preparation wizard |
|
|
| Quiet Agents | Inactive agent detection workflow |
|
|
| OTP Management | OTP generation, monitoring, and revocation |
|
|
|
|
### User Classes
|
|
|
|
Loxide supports three primary user roles:
|
|
|
|
- **Administrator** — Full access to all functionality, policy management, bulk operations
|
|
- **Analyst** — Monitoring, investigation, and reporting (execution history, OTP activity, logs)
|
|
- **Support** — Targeted operations like OTP generation for end-user issues
|
|
|
|
---
|
|
|
|
## Workflows
|
|
|
|
### Moving Agents to a New Policy
|
|
|
|
1. Navigate to **Agent Operations** tab
|
|
2. Enter device names (paste list, use wildcards, or load from file)
|
|
3. Click **Search** to find matching agents
|
|
4. Select agents using checkboxes (or Select All)
|
|
5. Click **Move to Policy**
|
|
6. Select destination policy from the tree
|
|
7. Confirm the operation
|
|
|
|
### Preparing a Policy for Enforcement
|
|
|
|
1. Navigate to **Policy Prep** tab
|
|
2. Select source policies to analyze
|
|
3. Choose destination enforcement policy
|
|
4. Set history days (how far back to analyze)
|
|
5. Select target allowlist for approved hashes
|
|
6. Click **Fetch Data** to retrieve execution history
|
|
7. Review unapproved applications by category
|
|
8. Add approved hashes to the allowlist
|
|
9. Export results for documentation
|
|
|
|
### Generating an OTP
|
|
|
|
1. Navigate to **Agent Operations** tab
|
|
2. Search for and select the target agent
|
|
3. Click **Generate OTP**
|
|
4. Set duration (in minutes) and purpose
|
|
5. Copy the generated OTP code
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Loxide/
|
|
├── Loxide.py # Main application entry point
|
|
├── API.py # AirlockAPIWrapper - all API calls
|
|
├── setup.py # Initialization, logging, config loading
|
|
├── configmanager.py # System/user configuration management
|
|
│
|
|
├── models/ # Data models
|
|
│ ├── agent.py # Agent data model
|
|
│ ├── policy.py # Policy data model
|
|
│ └── execution.py # Execution event model
|
|
│
|
|
├── services/ # Business logic
|
|
│ └── security.py # Credential management
|
|
│
|
|
├── utils/ # Helper functions
|
|
│ └── utils.py # Utility functions
|
|
│
|
|
└── TUI/
|
|
├── Screens/ # Full-page workflow screens
|
|
│ ├── policyprepworkflowscreen.py
|
|
│ ├── quietagentworkflowscreen.py
|
|
│ ├── moveagentworkflowscreen.py
|
|
│ ├── executionhistoryscreen.py
|
|
│ ├── otpworkflowscreen.py
|
|
│ ├── otpactivityscreen.py
|
|
│ ├── otprevokescreen.py
|
|
│ └── allowlistselectionscreen.py
|
|
│
|
|
├── Widgets/ # Reusable UI components
|
|
│ ├── policyselector.py
|
|
│ ├── policytreewidget.py
|
|
│ ├── multiagentselector.py
|
|
│ ├── agentmoveoperations.py
|
|
│ ├── serverlogwidget.py
|
|
│ ├── resultsdisplay.py
|
|
│ └── themeselector.py
|
|
│
|
|
└── Themes/ # Color themes
|
|
├── theme_amber_terminal.py
|
|
└── theme_retro_terminal.py
|
|
```
|
|
|
|
### Design Principles
|
|
|
|
- **Layered Architecture** — Clear separation between presentation, business logic, data access, and infrastructure
|
|
- **Screen vs Widget Pattern** — Screens have headers/footers and are pushed; widgets are embedded components
|
|
- **Secure by Default** — API keys encrypted at rest, secure credential storage
|
|
- **Cross-Platform** — Works on Windows 10/11 and Linux (Ubuntu 24+)
|
|
|
|
---
|
|
|
|
## Keyboard Reference
|
|
|
|
### Global
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `q` | Quit application |
|
|
| `Tab` | Next widget |
|
|
| `Shift+Tab` | Previous widget |
|
|
| `←` `→` | Navigate tabs |
|
|
| `?` | Show help |
|
|
|
|
### Screens
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `Escape` | Go back / Cancel |
|
|
| `r` | Refresh data |
|
|
| `e` | Export to CSV |
|
|
|
|
### Data Tables
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `↑` `↓` | Move cursor |
|
|
| `Page Up/Down` | Scroll page |
|
|
| `Home` / `End` | First / last row |
|
|
| `Space` | Toggle selection |
|
|
| `Enter` | Select / activate |
|
|
| `a` | Select all |
|
|
| `n` | Deselect all |
|
|
|
|
---
|
|
|
|
## Roadmap
|
|
|
|
### Planned Features
|
|
|
|
- **Carbon Black-style Local Approval** — Enable local user approvals for policy exceptions and enforcement actions
|
|
|
|
- **Audit Logging & Export** — Detailed logging and export capabilities for compliance and analysis
|
|
|
|
- **LEMON Integration** — Phase 2 integration with LEMON for enhanced analytics
|
|
|
|
- **Offline Mode** — Cached data review when Airlock server is unreachable
|
|
|
|
---
|
|
|
|
## Performance
|
|
|
|
| Metric | Target |
|
|
|--------|--------|
|
|
| Application startup | < 5 seconds |
|
|
| Agent list load (1000 agents) | < 10 seconds |
|
|
| Execution history (30 days, single agent) | < 15 seconds |
|
|
| UI response time | < 100 milliseconds |
|
|
| CSV export (10,000 rows) | < 30 seconds |
|
|
| Memory usage (idle) | < 200 MB |
|
|
|
|
---
|
|
|
|
## Authors
|
|
|
|
- **Brandon Wickline** — Lead Python Developer
|
|
- **James Brotosky** — Lead Rust Developer
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
**Loxide** is licensed under the **GNU Affero General Public License v3.0**.
|
|
|
|
You may copy, distribute, and modify the software under the terms of the AGPL-3.0 license.
|
|
|
|
```
|
|
Copyright (C) 2025 James Brotosky, Brandon Wickline
|
|
|
|
This program is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU Affero General Public License as published
|
|
by the Free Software Foundation, either version 3 of the License, or
|
|
(at your option) any later version.
|
|
```
|
|
|
|
See the [LICENSE](LICENSE.md) file for full details, or visit [gnu.org/licenses/agpl-3.0.html](https://www.gnu.org/licenses/agpl-3.0.html) |