mysticmomba/AirlockTools
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Readme update

Browse Source
This commit is contained in:
Zarithas
2025-12-22 12:11:34 -05:00
parent 2ed1d2e4cd
commit 5b53612644
2 changed files with 287 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -14,3 +14,6 @@ securitytest.py
system_config.json system_config.json
Development/ Development/
AirlockTools_client*/ AirlockTools_client*/
*.build/
*.dist/
*.onefile-build/
docs/README.md
+283 -76
View File
@@ -1,6 +1,6 @@
# 🛡️ Loxide # Loxide
Python/Rust/Oxide toolkit for secure, auditable, and automated Airlock agent and policy management. Designed for enterprise environments, it supports advanced policy workflows, device tracking, and terminal-based interaction. 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.
![Python](https://img.shields.io/badge/python-3.10+-blue.svg) ![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
![Rust](https://img.shields.io/badge/rust-backend-orange.svg) ![Rust](https://img.shields.io/badge/rust-backend-orange.svg)
@@ -9,68 +9,125 @@ Python/Rust/Oxide toolkit for secure, auditable, and automated Airlock agent and
--- ---
## 🚀 Features ## Table of Contents
- 🔍 **Fuzzy Device Search** - [Features](#features)
Quickly locate devices using partial or approximate matches with wildcard support (`*`, `?`). - [Installation](#installation)
- [Configuration](#configuration)
- 📦 **Batch Move Devices** - [Usage](#usage)
Move multiple devices between groups or policies easily with multi-select and file import. - [Workflows](#workflows)
- [Architecture](#architecture)
- 🔄 **Toggle Enforcement/Audit Policies** - [Keyboard Reference](#keyboard-reference)
Seamlessly switch devices between enforcement and audit modes. - [Roadmap](#roadmap)
- [Authors](#authors)
- 🕵️ **Device History Search** - [License](#license)
Track agent executions with configurable date ranges (1-365 days) and CSV export.
- 🧰 **Prepare Policies for Enforcement**
Multi-step wizard to validate and stage policies before pushing to enforcement.
- 💤 **Find Quiet Hosts**
Identify inactive devices ready for enforcement using Rust-powered analysis.
- 🔐 **OTP Management**
Generate, revoke, and monitor one-time passwords for agents.
- 📋 **Server Log Viewer**
Real-time server activity monitoring with DataTable display.
- 🎛️ **Modern TUI**
Full keyboard navigation with Textual framework, toast notifications, and color-coded results.
--- ---
## 🧭 Roadmap ## Features
### Multi-Agent Operations
- ✅ **Carbon Black-style Local Approval** Select and operate on multiple endpoints simultaneously using hostname, wildcard patterns (`*`, `?`), or file import. Supports lists of 700+ devices with fuzzy matching.
Enable local user approvals for policy exceptions and enforcement actions.
- 📊 **Audit Logging & Export** - Move agents between policy groups in bulk
Add detailed logging and export capabilities for compliance and analysis. - 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 ## Installation
### Prerequisites ### Prerequisites
- Python 3.10+
- Access to Airlock API
- Network access to private PyPI server
### Install Dependencies - 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 ```bash
# Clone the repository
git clone https://git.racooncity.org/brotoskyj/loxide.git
cd loxide
# Install dependencies
pip install -r requirements.txt pip install -r requirements.txt
# Run the application
python Loxide.py
``` ```
### Requirements ### Dependencies
``` ```
# Core TUI # Core TUI Framework
textual==6.5.0 textual==6.5.0
# API and data handling # API and Data Handling
requests==2.32.5 requests==2.32.5
pandas==2.3.3 pandas==2.3.3
numpy==2.3.4 numpy==2.3.4
@@ -88,72 +145,224 @@ tqdm==4.67.1
urllib3==2.5.0 urllib3==2.5.0
pyperclip==1.11.0 pyperclip==1.11.0
# Private package # Private Package (Rust integration)
--extra-index-url https://git.racooncity.org/api/packages/brotoskyj/pypi/simple/ --extra-index-url https://git.racooncity.org/api/packages/brotoskyj/pypi/simple/
airlock_libs==5.2.1 airlock_libs==5.2.1
``` ```
See also: [airlock_libs](https://git.racooncity.org/brotoskyj/-/packages/pypi/airlock-libs/) See also: [airlock_libs documentation](https://git.racooncity.org/brotoskyj/-/packages/pypi/airlock-libs/)
--- ---
## 📖 Usage ## 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 ```bash
python Loxide.py python Loxide.py
``` ```
### Keyboard Shortcuts ### Main Interface
| Key | Action | The application opens to a tabbed interface with the following sections:
|-----|--------|
| `Tab` | Navigate between elements | | Tab | Description |
| `Enter` | Select/Confirm | |-----|-------------|
| `Escape` | Go back / Cancel | | Dashboard | Summary statistics and environment overview |
| `←` `→` | Navigate tabs | | Agent Operations | Multi-agent selection and bulk operations |
| `r` | Refresh (context-dependent) | | Policy Prep | Policy enforcement preparation wizard |
| `e` | Export to CSV | | Quiet Agents | Inactive agent detection workflow |
| `q` | Quit application | | 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
--- ---
## 🏗️ Architecture ## 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/
├── Loxide.py # Main entry point ├── Loxide.py # Main application entry point
├── API.py # AirlockAPIWrapper ├── API.py # AirlockAPIWrapper - all API calls
├── setup.py # Initialization & logging ├── setup.py # Initialization, logging, config loading
├── configmanager.py # Config management ├── configmanager.py # System/user configuration management
│ │
├── models/ # Data models ├── models/ # Data models
│ ├── agent.py # Agent data model
│ ├── policy.py # Policy data model
│ └── execution.py # Execution event model
│
├── services/ # Business logic ├── services/ # Business logic
│ └── security.py # Credential management
│
├── utils/ # Helper functions ├── utils/ # Helper functions
│ └── utils.py # Utility functions
│ │
└── TUI/ └── TUI/
├── Screens/ # Workflow screens ├── Screens/ # Full-page workflow screens
│ ├── policyprepworkflowscreen.py │ ├── policyprepworkflowscreen.py
│ ├── quietagentworkflowscreen.py │ ├── quietagentworkflowscreen.py
│ ├── agentmoveoperations.py │ ├── moveagentworkflowscreen.py
│ ├── executionhistoryscreen.py
│ ├── otpworkflowscreen.py
│ ├── otpactivityscreen.py
│ ├── otprevokescreen.py │ ├── otprevokescreen.py
│ └── executionhistoryscreen.py │ └── allowlistselectionscreen.py
│ │
└── Widgets/ # Reusable components ├── Widgets/ # Reusable UI components
├── policyselector.py │ ├── policyselector.py
├── multiagentselector.py │ ├── policytreewidget.py
└── serverlogwidget.py │ ├── multiagentselector.py
│ ├── agentmoveoperations.py
│ ├── serverlogwidget.py
│ ├── resultsdisplay.py
│ └── themeselector.py
│
└── Themes/ # Color themes
├── theme_amber_terminal.py
└── theme_retro_terminal.py
``` ```
--- ### Design Principles
## 👥 Authors - **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
- **Brandon Wickline** - *Lead Python Developer* - **Secure by Default** — API keys encrypted at rest, secure credential storage
- **James Brotosky** - *Lead Rust Developer* - **Cross-Platform** — Works on Windows 10/11 and Linux (Ubuntu 24+)
--- ---
## 📜 License ## 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**. **Loxide** is licensed under the **GNU Affero General Public License v3.0**.
@@ -168,6 +377,4 @@ by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version. (at your option) any later version.
``` ```
See the [LICENSE](LICENSE.md) file for full details, or visit 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)
[https://www.gnu.org/licenses/agpl-3.0.html](https://www.gnu.org/licenses/agpl-3.0.html)