diff --git a/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md index f579ad0..e2ae2c2 100644 --- a/docs/ADMIN_GUIDE.md +++ b/docs/ADMIN_GUIDE.md @@ -1,369 +1,194 @@ -# LOGAR Administrator & Operations Guide -### *Complete Operations Manual for Fleet Hub Administration, Database Engines, PKI Licensing & AI Provisioning* +# 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](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Architecture-and-Design)** +* **[PKI & Licensing](https://gitea.eibl.tech/me0nline/LOGAR/wiki/PKI-and-Licensing)** +* **[State Machines & Lifecycles](https://gitea.eibl.tech/me0nline/LOGAR/wiki/State-Machines-and-Lifecycles)** +* **[API Reference](https://gitea.eibl.tech/me0nline/LOGAR/wiki/API-Reference)** --- ## Table of Contents -1. [Executive Summary & System Architecture](#1-executive-summary--system-architecture) -2. [Database Storage Engine Management](#2-database-storage-engine-management) - - [Local SQLite 3 (WAL Mode)](#local-sqlite-3-wal-mode) - - [External PostgreSQL Enterprise Backend](#external-postgresql-enterprise-backend) - - [Automated SQLite to PostgreSQL Migration](#automated-sqlite-to-postgresql-migration) -3. [Telemetry Ingestion Cache & Buffer Tuning](#3-telemetry-ingestion-cache--buffer-tuning) - - [Ingestion Modes: Direct Write vs In-Memory Queue Buffer](#ingestion-modes-direct-write-vs-in-memory-queue-buffer) - - [Tuning Parameters & Metrics](#tuning-parameters--metrics) - - [Manual Flush & Buffer Monitoring](#manual-flush--buffer-monitoring) -4. [Zero-Knowledge OpenPGP Data Encryption at Rest](#4-zero-knowledge-openpgp-data-encryption-at-rest) - - [Encryption Mechanism](#encryption-mechanism) - - [Transparent Authorized Decryption](#transparent-authorized-decryption) -5. [Subordinate CA & Dynamic PKI Licensing](#5-subordinate-ca--dynamic-pki-licensing) - - [Hierarchical PKI & Custom X.509 OIDs](#hierarchical-pki--custom-x509-oids) - - [Licensed Feature Capabilities (`enterprise_db`)](#licensed-feature-capabilities-enterprise_db) - - [Importing `.lic` Activation Packages](#importing-lic-activation-packages) - - [Automated mTLS License Renewal](#automated-mtls-license-renewal) -6. [Fleet Forwarder Management & Seat Provisioning](#6-fleet-forwarder-management--seat-provisioning) - - [Zero-Touch Linux Deployment](#zero-touch-linux-deployment) - - [Windows Edge Client Deployment](#windows-edge-client-deployment) - - [Seat Lifecycle: Approve, Revoke, Delete](#seat-lifecycle-approve-revoke-delete) -7. [Hermes AI Agent Integration](#7-hermes-ai-agent-integration) - - [Dedicated Bearer Tokens](#dedicated-bearer-tokens) - - [12-Hour Temporal Persistence Anomaly Stream](#12-hour-temporal-persistence-anomaly-stream) -8. [Security, Authentication & 2FA](#8-security-authentication--2fa) - - [Password Policies & PBKDF2 Hashing](#password-policies--pbkdf2-hashing) - - [Time-Based One-Time Password (TOTP 2FA)](#time-based-one-time-password-totp-2fa) - - [Sliding Window IP Rate Limiting](#sliding-window-ip-rate-limiting) -9. [Configuration Reference & CLI Flags](#9-configuration-reference--cli-flags) -10. [REST API Reference](#10-rest-api-reference) -11. [Operational Runbook & Troubleshooting](#11-operational-runbook--troubleshooting) +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. Executive Summary & System Architecture +## 1. Accessing the Web Console & Authentication -LOGAR is a centralized log aggregation, normalization, and provisioning system designed for enterprise server fleets. It connects heterogeneous edge nodes (Windows and Linux) with a central server hub over **Mutual TLS 1.3 (mTLS)**, normalizing incoming events and presenting structured anomaly intelligence to **Hermes AI**. +The LOGAR Server Hub provides an authenticated web management portal accessible from any modern web browser. -### Core Network Architecture +### URL & Port +* **Management Console URL**: `http://:8443/webui` +* **Protocol**: HTTP (or HTTPS behind an enterprise reverse proxy / load balancer) -```mermaid -graph TD - subgraph MasterAuthority [Master License Authority] - ROOT_CA[Master Root CA] - AUTH_API[WebSocket Licensing Hub
logar.eibl.tech] - end +### Default Credentials +Upon first launch, LOGAR initializes default administrative credentials: +* **Username**: `admin` +* **Password**: `admin_logar_2026!` - subgraph Hub [LOGAR Server Hub] - SUB_CA[Subordinate CA & PKI Engine] - INGEST_QUEUE[IngestQueueManager
In-Memory RAM Buffer] - STORAGE_ROUTER[Storage Engine Router] - SQLITE[(Local SQLite 3 WAL)] - POSTGRES[(External PostgreSQL Cluster)] - TEMP_ENG[12h Temporal Persistence Engine] - HERMES_API[Hermes REST & WebUI API
Port 8443] - MTLS_SOCKET[mTLS 1.3 Socket Listener
Port 9443] +> **Security Recommendation**: Change the default credentials immediately after initial deployment using the **User Settings** menu. - MTLS_SOCKET --> INGEST_QUEUE - INGEST_QUEUE --> STORAGE_ROUTER - STORAGE_ROUTER --> SQLITE - STORAGE_ROUTER --> POSTGRES - STORAGE_ROUTER --> TEMP_ENG - TEMP_ENG --> HERMES_API - end +--- - subgraph EdgeNodes [Fleet Edge Forwarders] - WIN_NODE[Windows Forwarder
Win_Client.exe] - LIN_NODE[Linux Forwarder
Linux_Client.bin] - end +## 2. Dashboard: Live Verified Telemetry - subgraph AI [Hermes AI Analysis Layer] - HERMES_AGENT[Hermes AI Agent] - end +**Tab: 📊 Live Telemetry** - ROOT_CA -->|Signs Sub-CA Cert| SUB_CA - AUTH_API <==>|Live mTLS Renewal| SUB_CA +The Live Telemetry view displays real-time anomalous log events aggregated across all enrolled Windows and Linux edge forwarders. - WIN_NODE ==>|1. Auto-Enrollment / mTLS Ingest| MTLS_SOCKET - LIN_NODE ==>|1. Auto-Enrollment / mTLS Ingest| MTLS_SOCKET +### 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. - HERMES_API ==>|GET /api/hermes/report| HERMES_AGENT +--- + +## 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. Database Storage Engine Management +### 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.* -LOGAR supports dual storage backends: an embedded **Local SQLite 3 (WAL Mode)** engine and an **External PostgreSQL Database Server** for enterprise clustering. - -### Local SQLite 3 (WAL Mode) -- **Status**: Standard Default (Included out of the box, zero configuration required). -- **Optimization**: Operates with Write-Ahead Logging (`PRAGMA journal_mode=WAL;`), asynchronous normal synchronization (`PRAGMA synchronous=NORMAL;`), and memory-mapped I/O (`PRAGMA mmap_size=268435456;`). -- **File Location**: Configurable via `db_path` in `server_config.json` (defaults to `logar_state.db`). - -### External PostgreSQL Enterprise Backend -- **Requirement**: Unlocked via the `enterprise_db` license capability. -- **Benefits**: Enables horizontal database scalability, clustering, multi-node replication, and centralized enterprise backup policies. -- **Connection Parameters**: - - **Host / IP**: Database hostname or IP address. - - **Port**: Default `5432`. - - **Database**: Target schema/database name (default `logar`). - - **Username / Password**: Authentication credentials. - - **SSL Mode**: Supports `prefer`, `require`, `verify-ca`, `verify-full`, `disable`, and `allow`. - - **Connect Timeout**: Timeout in seconds (default `5`s). - - **Connection Pool Size**: Maximum pooled persistent connections (default `10`). - -### Automated SQLite to PostgreSQL Migration -Administrators can migrate all historical logs, runs, active issues, seat allocations, users, and tokens from SQLite to PostgreSQL directly in the WebUI (`💾 DB Engine` -> `🚀 Migrate SQLite Data to PostgreSQL`) or via API (`POST /api/db/migrate-to-postgres`): -1. Flushes any in-memory telemetry buffers to SQLite. -2. Connects to PostgreSQL and verifies/initializes the schema. -3. Automatically transfers records table-by-table with validation. -4. Returns a detailed count of all migrated records. +### 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.* --- -## 3. Telemetry Ingestion Cache & Buffer Tuning +## 6. Hermes AI Tokens & Integration -### Ingestion Modes: Direct Write vs In-Memory Queue Buffer +**Tab: 🤖 Hermes AI** -| Feature | ⚡ Immediate Direct Write | 🚀 In-Memory Queue Buffer (`enterprise_db`) | -| :--- | :--- | :--- | -| **Ingress Latency** | Low latency, immediate DB commit | Microsecond ingestion, non-blocking | -| **Throughput** | Up to 1,500 events/sec | Up to 50,000+ events/sec | -| **Disk I/O** | Continuous write cycles | Atomic batch flushing | -| **License** | Standard Community Edition | Enterprise License (`enterprise_db`) | +Provision dedicated access tokens for Hermes AI agents to ingest anomalous telemetry. -### Tuning Parameters & Metrics -When **In-Memory Queue Buffer** is enabled, administrators can tune the buffer engine: -- **Flush Interval (seconds)**: Maximum elapsed time before buffered anomalies are written to storage (e.g. `2.0`s). -- **Batch Size Threshold**: Number of buffered events that triggers an immediate atomic flush (e.g. `100` events). -- **Max Buffer Capacity**: Upper ceiling of buffered items in memory (e.g. `50,000` events) to protect system RAM under heavy load. +### 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. -### Manual Flush & Buffer Monitoring -- **Live Monitoring**: The KPI card displays live buffer size, total events ingested, total flushed, and average flush latency. -- **Manual Trigger**: Click **`🌊 Flush Buffer Now`** or call `POST /api/db/flush-buffer` to force an immediate buffer drain. - ---- - -## 4. Zero-Knowledge OpenPGP Data Encryption at Rest - -### Encryption Mechanism -When **Data Encryption at Rest** is enabled (`encrypt_at_rest: true`): -- All sensitive log payloads, anomaly messages, and raw traces are encrypted with the server's OpenPGP public key before writing to the database table (`active_issues.message`). -- Remote database administrators or third-party database hosting providers only see armored OpenPGP ciphertext (`-----BEGIN PGP MESSAGE-----`). - -### Transparent Authorized Decryption -- The central LOGAR hub instance holds the private OpenPGP key in protected memory. -- When authenticated administrators access the WebUI or when authorized Hermes AI instances query `/api/hermes/report`, the server transparently decrypts records on-the-fly. - ---- - -## 5. Subordinate CA & Dynamic PKI Licensing - -LOGAR utilizes a hierarchical Public Key Infrastructure (PKI) for cryptographic client identity and license seat enforcement. - -### Hierarchical PKI & Custom X.509 OIDs -The Master Authority (`logar.eibl.tech`) signs the hub's Subordinate CA certificate (`certs/ca.crt`), embedding custom ASN.1 OIDs: -- **`1.3.6.1.4.1.58888.1.1` (Seat Quota)**: Encodes the authorized edge client seat capacity (e.g. `25` seats). -- **`1.3.6.1.4.1.58888.1.2` (Master Authority URL)**: Identifies the upstream licensing authority. -- **`1.3.6.1.4.1.58888.1.3` (Feature Capabilities)**: Comma-delimited list of granted features (e.g. `enterprise_db,ai_heuristics`). - -### Licensed Feature Capabilities (`enterprise_db`) -The **📜 Sub-CA & Licensing** tab displays all active licensed features: -- **`enterprise_db`**: Authorizes external PostgreSQL database pooling, high-throughput in-memory RAM buffering, and OpenPGP data-at-rest encryption. - -### Importing `.lic` Activation Packages -1. In the WebUI, navigate to **📜 Sub-CA & Licensing** and click **`📥 Import License (.lic)`**. -2. Select your `.lic` bundle or paste the JSON package. -3. The server immediately reloads the PKI trust chain and hot-reloads the active mTLS `SSLContext` without downtime. - -### Automated mTLS License Renewal -- Click **`🔄 Sync & Renew via mTLS`** in the WebUI or run: - ```bash - python src/Server.py --sync-license - ``` -- The hub connects to `logar.eibl.tech` over mTLS, sends its current seat utilization, and retrieves an updated signed CA certificate. - ---- - -## 6. Fleet Forwarder Management & Seat Provisioning - -### Zero-Touch Linux Deployment -Run the automated single-line installer on target Linux servers: -```bash -sudo ./compilation/install_linux_client.sh "http://:8443" "" +### 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 ``` -- Automatically generates a 2048-bit RSA client keypair. -- Enrolls with the hub and receives a signed client certificate. -- Deploys and starts the `logar-client.service` systemd unit. - -### Windows Edge Client Deployment -1. Download and run `LOGAR-Client-Setup.exe` on the Windows host. -2. In the Server WebUI, click **`📥 Export Client Profile`** and download `client_config.json`. -3. Place `client_config.json` into `C:\Program Files\LOGAR\client_config.json`. -4. The `LOGAR_Client` service automatically boots and connects via mTLS. - -### Seat Lifecycle: Approve, Revoke, Delete -In the **💻 Fleet Forwarders** tab: -- **Revoke**: Temporarily blocks the node at the TLS handshake level (`ssl.CERT_REQUIRED`). -- **Approve**: Re-activates a revoked node and restores telemetry ingestion. -- **Remove**: Permanently deletes the client record and immediately frees the leased seat quota. +* Or via query parameter: `http://:8443/api/hermes/report?token=hermes_live_xxxxxxxxxxxxxxxx` --- -## 7. Hermes AI Agent Integration +## 7. User Account & 2FA Security -### Dedicated Bearer Tokens -1. Navigate to **🤖 Hermes AI & Tokens** in the WebUI. -2. Enter a descriptive token name (e.g. `Hermes-Autonomous-SecOps`) and click **`Generate Token`**. -3. Copy the Bearer token for Hermes agent configuration. +**Menu: ⚙️ User Settings** -### 12-Hour Temporal Persistence Anomaly Stream -Hermes queries the real-time anomaly stream: -```bash -curl -H "Authorization: Bearer hermes_xxxxxxxxxxxx" http://:8443/api/hermes/report -``` +### Changing Administrative Credentials +1. Click the **Admin Profile** icon in the navigation bar. +2. Enter a new Username and Password. +3. Click **Update Account**. -#### JSON Telemetry Format: -```json -[ - { - "fingerprint": "corp-dc:srv-db-01:postgres_wal_checkpoint_delay", - "site": "corp-dc", - "server": "srv-db-01", - "signature": "postgres_wal_checkpoint_delay", - "severity": "WARNING", - "message": "WAL checkpoint write duration exceeded 30000ms threshold", - "os_type": "linux", - "first_seen": "2026-09-30 14:10:00", - "last_seen": "2026-09-30 17:42:15", - "consecutive_runs": 4, - "evaluation_window": "12h", - "verified": true, - "status": "VERIFIED" - } -] -``` - ---- - -## 8. Security, Authentication & 2FA - -### Password Policies & PBKDF2 Hashing -- User passwords are protected using PBKDF2-HMAC-SHA256 with 100,000 iterations and 16-byte random salts. -- Change admin credentials via the user avatar menu -> **🔑 Change Password**. - -### Time-Based One-Time Password (TOTP 2FA) -- Standard RFC 6238 TOTP with standard 30-second drift windows. -- Configure via avatar menu -> **🛡️ Two-Factor Auth (2FA)**. -- Compatible with Google Authenticator, Authy, 1Password, and Bitwarden. - -### Sliding Window IP Rate Limiting -- **Brute-Force Protection**: Enforces rate limiting on `/login` and `/api/client/enroll`. -- Excess failed attempts trigger automatic IP blocking with sliding exponential backoff. - ---- - -## 9. Configuration Reference & CLI Flags - -### `server_config.json` Specification - -```json -{ - "server_name": "LOGAR-Cloud-Hub", - "tcp_host": "0.0.0.0", - "tcp_port": 9443, - "hermes_host": "0.0.0.0", - "hermes_port": 8443, - "admin_user": "admin", - "enrollment_secret": "9a7f8e...4b", - "max_seats": 25, - "license_status": "active", - "license_server_url": "https://logar.eibl.tech", - "cert_dir": "certs", - "tls_enabled": true, - "db_path": "logar_state.db", - "storage_engine": "sqlite", - "cache_mode": "direct", - "flush_interval": 2.0, - "batch_size": 100, - "max_queue": 50000, - "encrypt_at_rest": false, - "server_fingerprint": "6FF5BE81...", - "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...", - "private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n..." -} -``` - -### CLI Arguments - -| Flag | Description | -| :--- | :--- | -| `--config ` | Path to server configuration JSON file | -| `--create-client-config` | Exports a client config bundle and exits | -| `--client-out ` | Destination path for exported client configuration | -| `--server-host ` | Embedded target host for exported client configuration | -| `--server-port ` | Embedded target port for exported client configuration | -| `--export-lic ` | Exports a `.lic` CSR activation request package | -| `--import-lic ` | Imports and activates a signed `.lic` license package | -| `--sync-license` | Connects to master authority to renew certificate & seats | - ---- - -## 10. REST API Reference - -| Method | Endpoint | Auth | Description | -| :--- | :--- | :--- | :--- | -| `GET` | `/health` | None | Health check, server name, and TLS status | -| `POST` | `/api/client/enroll` | Secret | Edge forwarder mTLS enrollment & certificate issuance | -| `GET` | `/api/clients` | Admin | List registered forwarders, activity times, and seat quota | -| `POST` | `/api/clients/approve` | Admin | Reactivate / approve an enrolled forwarder seat | -| `POST` | `/api/clients/revoke` | Admin | Revoke an enrolled forwarder seat | -| `POST` | `/api/clients/delete` | Admin | Remove forwarder record and permanently free seat | -| `GET` | `/api/hermes/report` | Hermes/Admin | Stream verified anomalies within 12h temporal window | -| `POST` | `/api/hermes/tokens/create` | Admin | Generate a named Bearer token for Hermes AI | -| `POST` | `/api/hermes/tokens/revoke` | Admin | Revoke an existing Hermes Bearer token | -| `GET` | `/api/db/stats` | Admin | Telemetry buffer stats, queue metrics, and storage info | -| `POST` | `/api/db/flush-buffer` | Admin | Force immediate drain and write of buffered telemetry | -| `POST` | `/api/db/test-connection` | Admin | Test external PostgreSQL connectivity (`enterprise_db`) | -| `POST` | `/api/db/switch-backend` | Admin | Switch backend between SQLite and PostgreSQL (`enterprise_db`) | -| `POST` | `/api/db/config` | Admin | Persist DB engine, cache mode, and encryption settings | -| `POST` | `/api/db/migrate-to-postgres` | Admin | Migrate SQLite tables to PostgreSQL (`enterprise_db`) | -| `GET` | `/api/license/status` | Admin | Subordinate CA status, seat quota, and licensed features | -| `POST` | `/api/license/import` | Admin | Import `.lic` bundle or signed CA PEM | -| `POST` | `/api/license/sync` | Admin | Sync license seats with master authority over mTLS | - ---- - -## 11. Operational Runbook & Troubleshooting - -### Diagnostic Checklist - -1. **Verify Hub Service Status**: - ```bash - # Linux - sudo systemctl status logar-server.service - # Windows PowerShell - Get-Service LOGAR_Server - ``` -2. **Check Health Endpoint**: - ```bash - curl http://localhost:8443/health - ``` -3. **Inspect Active Anomaly Telemetry**: - ```bash - curl -H "Authorization: Bearer " http://localhost:8443/api/hermes/report - ``` -4. **Certificate Validity Check**: - ```bash - openssl x509 -in certs/ca.crt -text -noout | grep -A 2 "Validity" - ``` - -### Common Issues & Remediation - -- **Issue: Forwarder rejected with `Connection Refused` or `TLS Handshake Failure`**: - - Ensure port `9443` is reachable through host and cloud firewalls. - - Verify edge node clock synchronization (NTP) with the server hub. - - Confirm the client certificate has not been revoked in the **Fleet Forwarders** tab. -- **Issue: `403 Forbidden` on PostgreSQL or Buffering settings**: - - The `enterprise_db` feature capability is required. Verify your license in **📜 Sub-CA & Licensing**. -- **Issue: Rate limit lock on admin login**: - - Wait 60 seconds for the sliding attempt window to expire, or authenticate via an existing active session. +### 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/wiki/ADMIN_GUIDE.md b/wiki/ADMIN_GUIDE.md index f579ad0..e2ae2c2 100644 --- a/wiki/ADMIN_GUIDE.md +++ b/wiki/ADMIN_GUIDE.md @@ -1,369 +1,194 @@ -# LOGAR Administrator & Operations Guide -### *Complete Operations Manual for Fleet Hub Administration, Database Engines, PKI Licensing & AI Provisioning* +# 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](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Architecture-and-Design)** +* **[PKI & Licensing](https://gitea.eibl.tech/me0nline/LOGAR/wiki/PKI-and-Licensing)** +* **[State Machines & Lifecycles](https://gitea.eibl.tech/me0nline/LOGAR/wiki/State-Machines-and-Lifecycles)** +* **[API Reference](https://gitea.eibl.tech/me0nline/LOGAR/wiki/API-Reference)** --- ## Table of Contents -1. [Executive Summary & System Architecture](#1-executive-summary--system-architecture) -2. [Database Storage Engine Management](#2-database-storage-engine-management) - - [Local SQLite 3 (WAL Mode)](#local-sqlite-3-wal-mode) - - [External PostgreSQL Enterprise Backend](#external-postgresql-enterprise-backend) - - [Automated SQLite to PostgreSQL Migration](#automated-sqlite-to-postgresql-migration) -3. [Telemetry Ingestion Cache & Buffer Tuning](#3-telemetry-ingestion-cache--buffer-tuning) - - [Ingestion Modes: Direct Write vs In-Memory Queue Buffer](#ingestion-modes-direct-write-vs-in-memory-queue-buffer) - - [Tuning Parameters & Metrics](#tuning-parameters--metrics) - - [Manual Flush & Buffer Monitoring](#manual-flush--buffer-monitoring) -4. [Zero-Knowledge OpenPGP Data Encryption at Rest](#4-zero-knowledge-openpgp-data-encryption-at-rest) - - [Encryption Mechanism](#encryption-mechanism) - - [Transparent Authorized Decryption](#transparent-authorized-decryption) -5. [Subordinate CA & Dynamic PKI Licensing](#5-subordinate-ca--dynamic-pki-licensing) - - [Hierarchical PKI & Custom X.509 OIDs](#hierarchical-pki--custom-x509-oids) - - [Licensed Feature Capabilities (`enterprise_db`)](#licensed-feature-capabilities-enterprise_db) - - [Importing `.lic` Activation Packages](#importing-lic-activation-packages) - - [Automated mTLS License Renewal](#automated-mtls-license-renewal) -6. [Fleet Forwarder Management & Seat Provisioning](#6-fleet-forwarder-management--seat-provisioning) - - [Zero-Touch Linux Deployment](#zero-touch-linux-deployment) - - [Windows Edge Client Deployment](#windows-edge-client-deployment) - - [Seat Lifecycle: Approve, Revoke, Delete](#seat-lifecycle-approve-revoke-delete) -7. [Hermes AI Agent Integration](#7-hermes-ai-agent-integration) - - [Dedicated Bearer Tokens](#dedicated-bearer-tokens) - - [12-Hour Temporal Persistence Anomaly Stream](#12-hour-temporal-persistence-anomaly-stream) -8. [Security, Authentication & 2FA](#8-security-authentication--2fa) - - [Password Policies & PBKDF2 Hashing](#password-policies--pbkdf2-hashing) - - [Time-Based One-Time Password (TOTP 2FA)](#time-based-one-time-password-totp-2fa) - - [Sliding Window IP Rate Limiting](#sliding-window-ip-rate-limiting) -9. [Configuration Reference & CLI Flags](#9-configuration-reference--cli-flags) -10. [REST API Reference](#10-rest-api-reference) -11. [Operational Runbook & Troubleshooting](#11-operational-runbook--troubleshooting) +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. Executive Summary & System Architecture +## 1. Accessing the Web Console & Authentication -LOGAR is a centralized log aggregation, normalization, and provisioning system designed for enterprise server fleets. It connects heterogeneous edge nodes (Windows and Linux) with a central server hub over **Mutual TLS 1.3 (mTLS)**, normalizing incoming events and presenting structured anomaly intelligence to **Hermes AI**. +The LOGAR Server Hub provides an authenticated web management portal accessible from any modern web browser. -### Core Network Architecture +### URL & Port +* **Management Console URL**: `http://:8443/webui` +* **Protocol**: HTTP (or HTTPS behind an enterprise reverse proxy / load balancer) -```mermaid -graph TD - subgraph MasterAuthority [Master License Authority] - ROOT_CA[Master Root CA] - AUTH_API[WebSocket Licensing Hub
logar.eibl.tech] - end +### Default Credentials +Upon first launch, LOGAR initializes default administrative credentials: +* **Username**: `admin` +* **Password**: `admin_logar_2026!` - subgraph Hub [LOGAR Server Hub] - SUB_CA[Subordinate CA & PKI Engine] - INGEST_QUEUE[IngestQueueManager
In-Memory RAM Buffer] - STORAGE_ROUTER[Storage Engine Router] - SQLITE[(Local SQLite 3 WAL)] - POSTGRES[(External PostgreSQL Cluster)] - TEMP_ENG[12h Temporal Persistence Engine] - HERMES_API[Hermes REST & WebUI API
Port 8443] - MTLS_SOCKET[mTLS 1.3 Socket Listener
Port 9443] +> **Security Recommendation**: Change the default credentials immediately after initial deployment using the **User Settings** menu. - MTLS_SOCKET --> INGEST_QUEUE - INGEST_QUEUE --> STORAGE_ROUTER - STORAGE_ROUTER --> SQLITE - STORAGE_ROUTER --> POSTGRES - STORAGE_ROUTER --> TEMP_ENG - TEMP_ENG --> HERMES_API - end +--- - subgraph EdgeNodes [Fleet Edge Forwarders] - WIN_NODE[Windows Forwarder
Win_Client.exe] - LIN_NODE[Linux Forwarder
Linux_Client.bin] - end +## 2. Dashboard: Live Verified Telemetry - subgraph AI [Hermes AI Analysis Layer] - HERMES_AGENT[Hermes AI Agent] - end +**Tab: 📊 Live Telemetry** - ROOT_CA -->|Signs Sub-CA Cert| SUB_CA - AUTH_API <==>|Live mTLS Renewal| SUB_CA +The Live Telemetry view displays real-time anomalous log events aggregated across all enrolled Windows and Linux edge forwarders. - WIN_NODE ==>|1. Auto-Enrollment / mTLS Ingest| MTLS_SOCKET - LIN_NODE ==>|1. Auto-Enrollment / mTLS Ingest| MTLS_SOCKET +### 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. - HERMES_API ==>|GET /api/hermes/report| HERMES_AGENT +--- + +## 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. Database Storage Engine Management +### 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.* -LOGAR supports dual storage backends: an embedded **Local SQLite 3 (WAL Mode)** engine and an **External PostgreSQL Database Server** for enterprise clustering. - -### Local SQLite 3 (WAL Mode) -- **Status**: Standard Default (Included out of the box, zero configuration required). -- **Optimization**: Operates with Write-Ahead Logging (`PRAGMA journal_mode=WAL;`), asynchronous normal synchronization (`PRAGMA synchronous=NORMAL;`), and memory-mapped I/O (`PRAGMA mmap_size=268435456;`). -- **File Location**: Configurable via `db_path` in `server_config.json` (defaults to `logar_state.db`). - -### External PostgreSQL Enterprise Backend -- **Requirement**: Unlocked via the `enterprise_db` license capability. -- **Benefits**: Enables horizontal database scalability, clustering, multi-node replication, and centralized enterprise backup policies. -- **Connection Parameters**: - - **Host / IP**: Database hostname or IP address. - - **Port**: Default `5432`. - - **Database**: Target schema/database name (default `logar`). - - **Username / Password**: Authentication credentials. - - **SSL Mode**: Supports `prefer`, `require`, `verify-ca`, `verify-full`, `disable`, and `allow`. - - **Connect Timeout**: Timeout in seconds (default `5`s). - - **Connection Pool Size**: Maximum pooled persistent connections (default `10`). - -### Automated SQLite to PostgreSQL Migration -Administrators can migrate all historical logs, runs, active issues, seat allocations, users, and tokens from SQLite to PostgreSQL directly in the WebUI (`💾 DB Engine` -> `🚀 Migrate SQLite Data to PostgreSQL`) or via API (`POST /api/db/migrate-to-postgres`): -1. Flushes any in-memory telemetry buffers to SQLite. -2. Connects to PostgreSQL and verifies/initializes the schema. -3. Automatically transfers records table-by-table with validation. -4. Returns a detailed count of all migrated records. +### 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.* --- -## 3. Telemetry Ingestion Cache & Buffer Tuning +## 6. Hermes AI Tokens & Integration -### Ingestion Modes: Direct Write vs In-Memory Queue Buffer +**Tab: 🤖 Hermes AI** -| Feature | ⚡ Immediate Direct Write | 🚀 In-Memory Queue Buffer (`enterprise_db`) | -| :--- | :--- | :--- | -| **Ingress Latency** | Low latency, immediate DB commit | Microsecond ingestion, non-blocking | -| **Throughput** | Up to 1,500 events/sec | Up to 50,000+ events/sec | -| **Disk I/O** | Continuous write cycles | Atomic batch flushing | -| **License** | Standard Community Edition | Enterprise License (`enterprise_db`) | +Provision dedicated access tokens for Hermes AI agents to ingest anomalous telemetry. -### Tuning Parameters & Metrics -When **In-Memory Queue Buffer** is enabled, administrators can tune the buffer engine: -- **Flush Interval (seconds)**: Maximum elapsed time before buffered anomalies are written to storage (e.g. `2.0`s). -- **Batch Size Threshold**: Number of buffered events that triggers an immediate atomic flush (e.g. `100` events). -- **Max Buffer Capacity**: Upper ceiling of buffered items in memory (e.g. `50,000` events) to protect system RAM under heavy load. +### 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. -### Manual Flush & Buffer Monitoring -- **Live Monitoring**: The KPI card displays live buffer size, total events ingested, total flushed, and average flush latency. -- **Manual Trigger**: Click **`🌊 Flush Buffer Now`** or call `POST /api/db/flush-buffer` to force an immediate buffer drain. - ---- - -## 4. Zero-Knowledge OpenPGP Data Encryption at Rest - -### Encryption Mechanism -When **Data Encryption at Rest** is enabled (`encrypt_at_rest: true`): -- All sensitive log payloads, anomaly messages, and raw traces are encrypted with the server's OpenPGP public key before writing to the database table (`active_issues.message`). -- Remote database administrators or third-party database hosting providers only see armored OpenPGP ciphertext (`-----BEGIN PGP MESSAGE-----`). - -### Transparent Authorized Decryption -- The central LOGAR hub instance holds the private OpenPGP key in protected memory. -- When authenticated administrators access the WebUI or when authorized Hermes AI instances query `/api/hermes/report`, the server transparently decrypts records on-the-fly. - ---- - -## 5. Subordinate CA & Dynamic PKI Licensing - -LOGAR utilizes a hierarchical Public Key Infrastructure (PKI) for cryptographic client identity and license seat enforcement. - -### Hierarchical PKI & Custom X.509 OIDs -The Master Authority (`logar.eibl.tech`) signs the hub's Subordinate CA certificate (`certs/ca.crt`), embedding custom ASN.1 OIDs: -- **`1.3.6.1.4.1.58888.1.1` (Seat Quota)**: Encodes the authorized edge client seat capacity (e.g. `25` seats). -- **`1.3.6.1.4.1.58888.1.2` (Master Authority URL)**: Identifies the upstream licensing authority. -- **`1.3.6.1.4.1.58888.1.3` (Feature Capabilities)**: Comma-delimited list of granted features (e.g. `enterprise_db,ai_heuristics`). - -### Licensed Feature Capabilities (`enterprise_db`) -The **📜 Sub-CA & Licensing** tab displays all active licensed features: -- **`enterprise_db`**: Authorizes external PostgreSQL database pooling, high-throughput in-memory RAM buffering, and OpenPGP data-at-rest encryption. - -### Importing `.lic` Activation Packages -1. In the WebUI, navigate to **📜 Sub-CA & Licensing** and click **`📥 Import License (.lic)`**. -2. Select your `.lic` bundle or paste the JSON package. -3. The server immediately reloads the PKI trust chain and hot-reloads the active mTLS `SSLContext` without downtime. - -### Automated mTLS License Renewal -- Click **`🔄 Sync & Renew via mTLS`** in the WebUI or run: - ```bash - python src/Server.py --sync-license - ``` -- The hub connects to `logar.eibl.tech` over mTLS, sends its current seat utilization, and retrieves an updated signed CA certificate. - ---- - -## 6. Fleet Forwarder Management & Seat Provisioning - -### Zero-Touch Linux Deployment -Run the automated single-line installer on target Linux servers: -```bash -sudo ./compilation/install_linux_client.sh "http://:8443" "" +### 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 ``` -- Automatically generates a 2048-bit RSA client keypair. -- Enrolls with the hub and receives a signed client certificate. -- Deploys and starts the `logar-client.service` systemd unit. - -### Windows Edge Client Deployment -1. Download and run `LOGAR-Client-Setup.exe` on the Windows host. -2. In the Server WebUI, click **`📥 Export Client Profile`** and download `client_config.json`. -3. Place `client_config.json` into `C:\Program Files\LOGAR\client_config.json`. -4. The `LOGAR_Client` service automatically boots and connects via mTLS. - -### Seat Lifecycle: Approve, Revoke, Delete -In the **💻 Fleet Forwarders** tab: -- **Revoke**: Temporarily blocks the node at the TLS handshake level (`ssl.CERT_REQUIRED`). -- **Approve**: Re-activates a revoked node and restores telemetry ingestion. -- **Remove**: Permanently deletes the client record and immediately frees the leased seat quota. +* Or via query parameter: `http://:8443/api/hermes/report?token=hermes_live_xxxxxxxxxxxxxxxx` --- -## 7. Hermes AI Agent Integration +## 7. User Account & 2FA Security -### Dedicated Bearer Tokens -1. Navigate to **🤖 Hermes AI & Tokens** in the WebUI. -2. Enter a descriptive token name (e.g. `Hermes-Autonomous-SecOps`) and click **`Generate Token`**. -3. Copy the Bearer token for Hermes agent configuration. +**Menu: ⚙️ User Settings** -### 12-Hour Temporal Persistence Anomaly Stream -Hermes queries the real-time anomaly stream: -```bash -curl -H "Authorization: Bearer hermes_xxxxxxxxxxxx" http://:8443/api/hermes/report -``` +### Changing Administrative Credentials +1. Click the **Admin Profile** icon in the navigation bar. +2. Enter a new Username and Password. +3. Click **Update Account**. -#### JSON Telemetry Format: -```json -[ - { - "fingerprint": "corp-dc:srv-db-01:postgres_wal_checkpoint_delay", - "site": "corp-dc", - "server": "srv-db-01", - "signature": "postgres_wal_checkpoint_delay", - "severity": "WARNING", - "message": "WAL checkpoint write duration exceeded 30000ms threshold", - "os_type": "linux", - "first_seen": "2026-09-30 14:10:00", - "last_seen": "2026-09-30 17:42:15", - "consecutive_runs": 4, - "evaluation_window": "12h", - "verified": true, - "status": "VERIFIED" - } -] -``` - ---- - -## 8. Security, Authentication & 2FA - -### Password Policies & PBKDF2 Hashing -- User passwords are protected using PBKDF2-HMAC-SHA256 with 100,000 iterations and 16-byte random salts. -- Change admin credentials via the user avatar menu -> **🔑 Change Password**. - -### Time-Based One-Time Password (TOTP 2FA) -- Standard RFC 6238 TOTP with standard 30-second drift windows. -- Configure via avatar menu -> **🛡️ Two-Factor Auth (2FA)**. -- Compatible with Google Authenticator, Authy, 1Password, and Bitwarden. - -### Sliding Window IP Rate Limiting -- **Brute-Force Protection**: Enforces rate limiting on `/login` and `/api/client/enroll`. -- Excess failed attempts trigger automatic IP blocking with sliding exponential backoff. - ---- - -## 9. Configuration Reference & CLI Flags - -### `server_config.json` Specification - -```json -{ - "server_name": "LOGAR-Cloud-Hub", - "tcp_host": "0.0.0.0", - "tcp_port": 9443, - "hermes_host": "0.0.0.0", - "hermes_port": 8443, - "admin_user": "admin", - "enrollment_secret": "9a7f8e...4b", - "max_seats": 25, - "license_status": "active", - "license_server_url": "https://logar.eibl.tech", - "cert_dir": "certs", - "tls_enabled": true, - "db_path": "logar_state.db", - "storage_engine": "sqlite", - "cache_mode": "direct", - "flush_interval": 2.0, - "batch_size": 100, - "max_queue": 50000, - "encrypt_at_rest": false, - "server_fingerprint": "6FF5BE81...", - "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...", - "private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n..." -} -``` - -### CLI Arguments - -| Flag | Description | -| :--- | :--- | -| `--config ` | Path to server configuration JSON file | -| `--create-client-config` | Exports a client config bundle and exits | -| `--client-out ` | Destination path for exported client configuration | -| `--server-host ` | Embedded target host for exported client configuration | -| `--server-port ` | Embedded target port for exported client configuration | -| `--export-lic ` | Exports a `.lic` CSR activation request package | -| `--import-lic ` | Imports and activates a signed `.lic` license package | -| `--sync-license` | Connects to master authority to renew certificate & seats | - ---- - -## 10. REST API Reference - -| Method | Endpoint | Auth | Description | -| :--- | :--- | :--- | :--- | -| `GET` | `/health` | None | Health check, server name, and TLS status | -| `POST` | `/api/client/enroll` | Secret | Edge forwarder mTLS enrollment & certificate issuance | -| `GET` | `/api/clients` | Admin | List registered forwarders, activity times, and seat quota | -| `POST` | `/api/clients/approve` | Admin | Reactivate / approve an enrolled forwarder seat | -| `POST` | `/api/clients/revoke` | Admin | Revoke an enrolled forwarder seat | -| `POST` | `/api/clients/delete` | Admin | Remove forwarder record and permanently free seat | -| `GET` | `/api/hermes/report` | Hermes/Admin | Stream verified anomalies within 12h temporal window | -| `POST` | `/api/hermes/tokens/create` | Admin | Generate a named Bearer token for Hermes AI | -| `POST` | `/api/hermes/tokens/revoke` | Admin | Revoke an existing Hermes Bearer token | -| `GET` | `/api/db/stats` | Admin | Telemetry buffer stats, queue metrics, and storage info | -| `POST` | `/api/db/flush-buffer` | Admin | Force immediate drain and write of buffered telemetry | -| `POST` | `/api/db/test-connection` | Admin | Test external PostgreSQL connectivity (`enterprise_db`) | -| `POST` | `/api/db/switch-backend` | Admin | Switch backend between SQLite and PostgreSQL (`enterprise_db`) | -| `POST` | `/api/db/config` | Admin | Persist DB engine, cache mode, and encryption settings | -| `POST` | `/api/db/migrate-to-postgres` | Admin | Migrate SQLite tables to PostgreSQL (`enterprise_db`) | -| `GET` | `/api/license/status` | Admin | Subordinate CA status, seat quota, and licensed features | -| `POST` | `/api/license/import` | Admin | Import `.lic` bundle or signed CA PEM | -| `POST` | `/api/license/sync` | Admin | Sync license seats with master authority over mTLS | - ---- - -## 11. Operational Runbook & Troubleshooting - -### Diagnostic Checklist - -1. **Verify Hub Service Status**: - ```bash - # Linux - sudo systemctl status logar-server.service - # Windows PowerShell - Get-Service LOGAR_Server - ``` -2. **Check Health Endpoint**: - ```bash - curl http://localhost:8443/health - ``` -3. **Inspect Active Anomaly Telemetry**: - ```bash - curl -H "Authorization: Bearer " http://localhost:8443/api/hermes/report - ``` -4. **Certificate Validity Check**: - ```bash - openssl x509 -in certs/ca.crt -text -noout | grep -A 2 "Validity" - ``` - -### Common Issues & Remediation - -- **Issue: Forwarder rejected with `Connection Refused` or `TLS Handshake Failure`**: - - Ensure port `9443` is reachable through host and cloud firewalls. - - Verify edge node clock synchronization (NTP) with the server hub. - - Confirm the client certificate has not been revoked in the **Fleet Forwarders** tab. -- **Issue: `403 Forbidden` on PostgreSQL or Buffering settings**: - - The `enterprise_db` feature capability is required. Verify your license in **📜 Sub-CA & Licensing**. -- **Issue: Rate limit lock on admin login**: - - Wait 60 seconds for the sliding attempt window to expire, or authenticate via an existing active session. +### 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/wiki/Admin-Guide.md b/wiki/Admin-Guide.md new file mode 100644 index 0000000..e2ae2c2 --- /dev/null +++ b/wiki/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](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Architecture-and-Design)** +* **[PKI & Licensing](https://gitea.eibl.tech/me0nline/LOGAR/wiki/PKI-and-Licensing)** +* **[State Machines & Lifecycles](https://gitea.eibl.tech/me0nline/LOGAR/wiki/State-Machines-and-Lifecycles)** +* **[API Reference](https://gitea.eibl.tech/me0nline/LOGAR/wiki/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.