diff --git a/Admin-Guide.md b/Admin-Guide.md new file mode 100644 index 0000000..520ac8a --- /dev/null +++ b/Admin-Guide.md @@ -0,0 +1,194 @@ +# WebUI Administrator Guide + +Welcome to the **LOGAR WebUI Administrator Guide**. This guide provides step-by-step instructions for managing and operating the LOGAR Server Hub through its graphical web console (`:8443/webui`). + +For deep architectural design, cryptographic protocols, X.509 OID schemas, and full REST API specifications, please refer to the dedicated technical wiki pages: +* **[Architecture & Design](Architecture-and-Design)** +* **[PKI & Licensing](PKI-and-Licensing)** +* **[State Machines & Lifecycles](State-Machines-and-Lifecycles)** +* **[API Reference](API-Reference)** + +--- + +## Table of Contents + +1. [Accessing the Web Console & Authentication](#1-accessing-the-web-console--authentication) +2. [Dashboard: Live Verified Telemetry](#2-dashboard-live-verified-telemetry) +3. [Fleet Seat Management & Client Provisioning](#3-fleet-seat-management--client-provisioning) +4. [Sub-CA & Modular Licensing](#4-sub-ca--modular-licensing) +5. [Storage Engine & Ingestion Performance](#5-storage-engine--ingestion-performance) +6. [Hermes AI Tokens & Integration](#6-hermes-ai-tokens--integration) +7. [User Account & 2FA Security](#7-user-account--2fa-security) + +--- + +## 1. Accessing the Web Console & Authentication + +The LOGAR Server Hub provides an authenticated web management portal accessible from any modern web browser. + +### URL & Port +* **Management Console URL**: `http://:8443/webui` +* **Protocol**: HTTP (or HTTPS behind an enterprise reverse proxy / load balancer) + +### Default Credentials +Upon first launch, LOGAR initializes default administrative credentials: +* **Username**: `admin` +* **Password**: `admin_logar_2026!` + +> **Security Recommendation**: Change the default credentials immediately after initial deployment using the **User Settings** menu. + +--- + +## 2. Dashboard: Live Verified Telemetry + +**Tab: 📊 Live Telemetry** + +The Live Telemetry view displays real-time anomalous log events aggregated across all enrolled Windows and Linux edge forwarders. + +### Key Controls & Information +* **Severity Filter**: Filter events by `ALL`, `CRITICAL`, `ERROR`, or `WARNING`. +* **Temporal Tracking**: View occurrence frequency (`Runs: N`), first seen timestamp, and relative last seen time (e.g. `2m ago`). +* **Source Attribution**: Inspect originating Hostname, Machine GUID, and Operating System badge (`Windows` / `Linux`). +* **Message Payload**: Inspect the raw extracted log message and normalized signature. +* **Auto-Refresh**: Live stream updates automatically; displays the latest 50 active anomaly frames. + +--- + +## 3. Fleet Seat Management & Client Provisioning + +**Tab: 💻 Client Seats** + +Manage connected edge forwarders (`Win_Client` and `Linux_Client`), enforce cryptographic seat quotas, and export client configuration profiles. + +### Seat Quota Overview +* Displays the current seat consumption ratio (e.g., `3 / 25 Seats in Use`). +* Unlicensed servers allow local log collection (`0 / 0 Seats`) while blocking remote mTLS forwarders until a license is imported. + +### Managing Enrolled Forwarders +The client seat table lists every registered forwarder with its Machine Identifier, Hostname, OS Type, IP Address, First Enrolled date, and Status: +* **🟢 Active**: The forwarder has valid mTLS certificates and is actively streaming logs. +* **🔴 Revoked**: The forwarder's mTLS certificate has been administratively revoked. Ingestion from this client is rejected. +* **Action Buttons**: + * **Revoke**: Temporarily revoke a client's seat and deny incoming connections. + * **Reactivate / Approve**: Re-enable a previously revoked client seat. + * **Delete**: Remove the client record and release the seat back to the available pool. + +### Exporting Client Configuration +Click **📥 Download Client Config** to generate and download `client_config.json`. +* Contains the server's connection endpoints (`server_host:9443`), Sub-CA public certificate, encryption fingerprint, and enrollment secret. +* Distribute this file to edge forwarders during deployment for instant zero-touch auto-enrollment. + +--- + +## 4. Sub-CA & Modular Licensing + +**Tab: 📜 Sub-CA & Licensing** + +Manage the server's Subordinate Certificate Authority (Sub-CA), verify hardware host binding, view active licensed capabilities, and apply license updates. + +### Sub-CA Status & Fingerprints +* **CA Subject**: The Distinguished Name (DN) of the local Sub-CA. +* **Server Encryption Fingerprint**: SHA-256 / OpenPGP fingerprint for encrypted payloads. +* **Validity Period**: Issue date and certificate expiration date. +* **Assigned Seat Quota**: Maximum authorized forwarder capacity. + +### ✨ Licensed Capabilities & Feature Modules +This section displays all authorized feature modules: +* **`enterprise_db`**: Multi-engine external database support (PostgreSQL / MySQL / MariaDB), high-throughput ring buffering, and zero-knowledge data encryption at rest. +* *Standard Edition*: If running without an enterprise license, standard local SQLite storage remains active. + +### License Management Operations +* **Export License Request (`.lic`)**: + Click **📤 Export CSR (.lic)** to download the server's hardware-bound certificate signing request. Send this file to your organization's Master License Authority administrator. +* **Import Signed Sub-CA Certificate**: + Paste the signed PEM certificate received from the Master Authority into the text area and click **📥 Import Signed Certificate**. The server reloads its SSLContext and updates seat quotas in-flight with zero downtime. +* **Live WebSocket Sync**: + Click **🔄 Sync with License Hub** to trigger immediate real-time synchronization with `logar.eibl.tech`. + +--- + +## 5. Storage Engine & Ingestion Performance + +**Tab: 🗄️ Database Engine** + +Configure ingestion buffering, payload encryption at rest, and database backends. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 1. INGESTION RING BUFFER & BATCH FLUSHER (Top) │ +│ • Mode: Direct (Sync) / In-Memory Ring Buffer │ +│ • Batch Flush Interval (sec) & Batch Size (events) │ +├─────────────────────────────────────────────────────────────┤ +│ 2. PAYLOAD ENCRYPTION AT REST (Middle) │ +│ • Toggle: OpenPGP / RSA-2048 Payload Encryption │ +├─────────────────────────────────────────────────────────────┤ +│ 3. STORAGE BACKEND SELECTION (Bottom) │ +│ • Local SQLite (WAL Mode) │ +│ • External SQL Server (PostgreSQL / MySQL / MariaDB) │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 1. Ingestion Ring Buffer (Top Section) +Tune log ingestion throughput to prevent socket I/O bottlenecks during high-volume spikes: +* **Cache Mode**: + * **Direct (Synchronous)**: Commits incoming log batches immediately to disk. Recommended for small deployments (< 20 nodes). + * **In-Memory Ring Buffer**: Places incoming events into an in-memory queue. A background thread flushes events in atomic batches. Recommended for large fleets (> 50 nodes). +* **Batch Flush Interval**: Time in seconds between automated queue commits (default: `2.0s`). +* **Batch Size**: Maximum events processed per database commit transaction (default: `100`). +* *Note: Ingestion buffering is an explicit opt-in setting and is not auto-enabled.* + +### 2. Payload Encryption at Rest (Middle Section) +* **Encrypt Payloads at Rest**: When enabled, log message payloads (`event_data`) stored in external databases are encrypted using the server's X.509 RSA-2048 / OpenPGP public key. +* **Zero-Knowledge Guarantee**: Database administrators or compromised SQL servers cannot read raw logs without the private key resident on the LOGAR Server Hub. +* *Note: Encryption at rest is an explicit opt-in setting.* + +### 3. Database Backend Selection (Bottom Section) +Switch between local file storage and external SQL servers: +* **Local SQLite (WAL Mode)**: + * Default, zero-configuration embedded database located at `logar_state.db`. + * Operates with Write-Ahead Logging (WAL) for high concurrency. +* **External SQL Server (PostgreSQL / MySQL / MariaDB)**: + * Select your database dialect (**PostgreSQL** or **MySQL / MariaDB**). + * Enter **Host**, **Port**, **Database Name**, **Username**, and **Password**. + * Click **💾 Save & Apply Storage Configuration**. + * The server tests connectivity, initializes required tables and indices, and migrates operational state seamlessly. +* *Licensing Note: External SQL backend options require the `enterprise_db` licensed capability. If unlicensed, these controls are visible but gracefully disabled.* + +--- + +## 6. Hermes AI Tokens & Integration + +**Tab: 🤖 Hermes AI** + +Provision dedicated access tokens for Hermes AI agents to ingest anomalous telemetry. + +### Managing Access Tokens +* **Create Token**: Enter an agent name (e.g. `Hermes-Production-Cluster`) and click **➕ Generate Token**. +* **Token Attributes**: View Token Name, Creation Date, Last Used Timestamp, and Status (`Active` / `Revoked`). +* **Revoke / Delete**: Instantly revoke access for compromised tokens or permanently delete retired tokens. + +### Connecting Hermes AI +Configure Hermes AI agents to query the structured anomaly stream: +```http +GET http://:8443/api/hermes/report +Authorization: Bearer hermes_live_xxxxxxxxxxxxxxxx +``` +* Or via query parameter: `http://:8443/api/hermes/report?token=hermes_live_xxxxxxxxxxxxxxxx` + +--- + +## 7. User Account & 2FA Security + +**Menu: ⚙️ User Settings** + +### Changing Administrative Credentials +1. Click the **Admin Profile** icon in the navigation bar. +2. Enter a new Username and Password. +3. Click **Update Account**. + +### Two-Factor Authentication (TOTP 2FA) +Enhance login security with RFC 6238 Time-Based One-Time Passwords: +1. Click **🔒 Setup Two-Factor Authentication**. +2. Scan the displayed QR Code using your preferred authenticator app (Google Authenticator, Microsoft Authenticator, 1Password, etc.). +3. Enter the 6-digit verification code from your authenticator app to confirm activation. +4. Subsequent logins will require your password followed by the 6-digit TOTP code. diff --git a/Home.md b/Home.md index 89fbb8a..17277e8 100644 --- a/Home.md +++ b/Home.md @@ -6,13 +6,22 @@ Welcome to the official technical documentation wiki for **LOGAR: Fleet Log Aggr ## Navigation & Wiki Index -1. **[Architecture and Design](Architecture-and-Design)** +1. **[WebUI Administrator Guide](Admin-Guide)** + - Accessing the management console & credentials + - Live verified anomaly telemetry stream & filtering + - Fleet seat management & client profile export + - Sub-CA certificates, modular licensing & WebSocket sync + - Ingestion ring buffer tuning & payload encryption at rest + - Database engine management (SQLite WAL / PostgreSQL / MySQL) + - Hermes AI token provisioning & TOTP 2FA security + +2. **[Architecture and Design](Architecture-and-Design)** - Core philosophy & data provisioning model - End-to-end system architecture - Zero-state edge forwarders vs centralized hub - Hermes AI reasoning integration -2. **[State Machines and Lifecycles](State-Machines-and-Lifecycles)** +3. **[State Machines and Lifecycles](State-Machines-and-Lifecycles)** - End-to-end high-level system state machine - Sub-CA bootstrap & auto-enrollment lifecycle - Live WebSocket synchronization & in-flight hot reload @@ -20,33 +29,33 @@ Welcome to the official technical documentation wiki for **LOGAR: Fleet Log Aggr - mTLS 1.3 streaming, proactive renewal & self-healing - 12-hour temporal evaluation window -3. **[PKI and Fleet Licensing](PKI-and-Licensing)** +4. **[PKI and Fleet Licensing](PKI-and-Licensing)** - Hierarchical PKI architecture & custom X.509 OIDs - Dynamic seat quotas and licensing enforcement - Bootstrap `.lic` package handling - In-flight certificate watchdog & hot SSLContext reloading - WebUI Sub-CA & Licensing dashboard -4. **[API Reference](API-Reference)** +5. **[API Reference](API-Reference)** - REST API specifications & JSON request/response schemas - Forwarder enrollment (`/api/client/enroll`) - Seat management & client telemetry (`/api/clients`) - Hermes AI log streaming (`/api/hermes/report`) - Administrator session authentication & health endpoints -5. **[Deployment and Installation](Deployment-and-Installation)** +6. **[Deployment and Installation](Deployment-and-Installation)** - Central server hub setup & configuration - Linux client deployment (`install_linux_client.sh`) - Windows client & server setup (Inno Setup & NSSM) - Dynamic machine and domain identification -6. **[Testing and Releases](Testing-and-Releases)** - - Automated unit test suite (35 tests) & end-to-end pipeline test +7. **[Testing and Releases](Testing-and-Releases)** + - Automated unit test suite (51 tests) & end-to-end pipeline test - Continuous Integration (`ci.yml`) - Automated cross-compilation release workflow (`release.yml`) - Local binary packaging & Gitea asset publisher -7. **[Branding and Asset Guide](Branding-Guide)** +8. **[Branding and Asset Guide](Branding-Guide)** - Visual identity, logo geometry & color palette - Asset inventory, icons, and installer graphics - Logo usage rules, dos and don'ts, and asset regeneration