diff --git a/out/win_server/README.md b/out/win_server/README.md index dcc474c..81470cd 100644 --- a/out/win_server/README.md +++ b/out/win_server/README.md @@ -1,31 +1,45 @@ # LOGAR Windows Server Hub -Standalone compiled executable distribution for Windows Server environments (`Server.exe`). +Standalone compiled executable and installer distribution for Windows Server environments (`Server.exe`). --- ## Overview -`Server.exe` is a self-contained, pre-compiled native Windows PE executable that serves as the central log aggregation, temporal persistence analyzer, and reporting hub of the LOGAR infrastructure. +`Server.exe` is a self-contained, pre-compiled native Windows PE executable that serves as the central log aggregation, temporal persistence analyzer, dynamic PKI certificate authority, and reporting hub of the LOGAR infrastructure. ### Key Architecture & Capabilities -- **Pre-compiled & Dependency-Free**: Ships as a standalone Windows executable (`Server.exe`). No Python installation, pip packages, or GnuPG binaries are required on Windows Server. -- **Authenticated TCP Ingestion Socket (Port 9443)**: Ingests framed OpenPGP encrypted log batches streamed from edge forwarder nodes (`Win_Client.exe` and `Linux_Client.bin`). -- **Warning Persistence & Immediate Error Routing**: High-severity `ERROR`, `CRITICAL`, and `FATAL` events are promoted to `VERIFIED` immediately on their first occurrence. Operational `WARNING` and `INFO` events are evaluated against an episodic threshold, requiring persistence across at least 4 distinct client transmission cycles within a rolling 12-hour evaluation window before promotion to `VERIFIED`. -- **Embedded Hermes Reporting API (Port 8443)**: Integrated REST API exposing `/api/hermes/report` for external dashboards, monitoring agents, and scrapers. -- **Pure-Python OpenPGP Cryptography**: Automatically generates RSA-2048 encryption keys and a SHA-256 fingerprint on first launch without external dependencies. -- **State Database**: Stores issue lifecycle records, run counters, and machine telemetry in a local SQLite database (`logar_state.db`). +- **Pre-compiled & Dependency-Free**: Ships as a standalone Windows executable (`Server.exe`) or full installer (`LOGAR-Server-Setup.exe`). No Python installation, pip packages, or GnuPG binaries are required on Windows Server. +- **Mutual TLS 1.3 (mTLS) Ingestion (Port 9443)**: Enforces mutual TLS 1.3 authentication for all incoming edge connections. Validates client certificates against an internal Root CA and verifies active licensing in SQLite. +- **Dynamic PKI & License Accounting**: Built-in Root CA generates server TLS certificates with SANs and dynamically signs client certificates via `POST /api/client/enroll` while enforcing seat limits (`max_seats`). +- **Warning Persistence & Immediate Error Routing**: High-severity `ERROR`, `CRITICAL`, and `FATAL` events are promoted to `VERIFIED` immediately on their first occurrence. Operational `WARNING` and `INFO` events require persistence across at least 4 distinct transmission cycles within a rolling 12-hour evaluation window. +- **Embedded Hermes Reporting & Management API (Port 8443)**: Integrated REST API exposing `/api/hermes/report`, `/api/clients`, and `/api/client/enroll`. +- **State Database**: Stores issue lifecycle records, client telemetry, and licensing quotas in a local SQLite database (`logar_state.db`). --- -## 1. Initializing & Generating Server Configuration +## 1. Automated Installation via Inno Setup (Recommended) + +Run the self-contained installer built from `compilation/installer_server.iss`: +```powershell +.\LOGAR-Server-Setup.exe +``` +This installer: +1. Installs `Server.exe` and bundled `nssm.exe` to `C:\Program Files\LOGAR-Server\`. +2. Registers and starts the `LOGAR_Server` Windows service automatically via NSSM. +3. Redirects stdout and stderr logs to `C:\ProgramData\LOGAR-Server\server.log` and `server_err.log`. + +--- + +## 2. Initializing & Generating Server Configuration ### Step 1: Automatic First-Run Generation When launched without an existing `server_config.json`, `Server.exe` automatically initializes: -1. An OpenPGP RSA-2048 encryption keypair (`private_key` and `public_key`). -2. A SHA-256 public encryption fingerprint (`server_fingerprint`). -3. A cryptographically random secret authentication token (`auth_token`). -4. Default network socket coordinates (TCP 9443, Hermes API 8443). +1. An internal Root CA (`certs/ca.crt` and `certs/ca.key`). +2. A server TLS certificate (`certs/server.crt` and `certs/server.key`) with SANs. +3. An OpenPGP RSA-2048 keypair (`private_key` and `public_key`). +4. Cryptographically random authentication tokens and enrollment secrets. +5. Default network socket coordinates (mTLS 9443, Hermes API 8443). Open PowerShell and run: ```powershell @@ -37,11 +51,20 @@ Output: [+] Successfully generated new server config and OpenPGP keypair. [+] Server Encryption Fingerprint: 375388960531264EA0648EC0D2C4E4ABC6F22AC2 [+] Saved to: server_config.json +============================================================ + LOGAR Server Hub: LOGAR-Cloud-Hub + Transport Security: mTLS (TLS 1.3) + License Quota: 10 Active Seats + Server Encryption Fingerprint: 375388960531264EA0648EC0D2C4E4ABC6F22AC2 + Evaluation Window: 12 hours | 4-Run Rule: Warnings | Immediate Pass: Errors +============================================================ +[*] LOGAR mTLS TLSv1.3 Socket Server listening on 0.0.0.0:9443 +[*] Hermes Reporting API available at http://0.0.0.0:8443/api/hermes/report +[*] Client Enrollment API available at http://0.0.0.0:8443/api/client/enroll ``` ### Step 2: Configuration Fields Reference The generated `server_config.json` contains: - ```json { "server_name": "LOGAR-Windows-Hub", @@ -50,6 +73,10 @@ The generated `server_config.json` contains: "hermes_host": "0.0.0.0", "hermes_port": 8443, "auth_token": "a1b2c3d4e5f67890abcdef1234567890...", + "enrollment_secret": "e1f2a3b4c5d6...", + "max_seats": 10, + "cert_dir": "certs", + "tls_enabled": true, "db_path": "logar_state.db", "evaluation_window_hours": 12, "min_persistence_runs": 4, @@ -59,179 +86,36 @@ The generated `server_config.json` contains: } ``` -| Parameter | Default | Description | -| :--- | :--- | :--- | -| `server_name` | `"LOGAR-Windows-Hub"` | Identifier for this hub instance | -| `tcp_host` | `"0.0.0.0"` | Network interface to bind for incoming client socket traffic | -| `tcp_port` | `9443` | TCP port for incoming edge log batches | -| `hermes_host` | `"0.0.0.0"` | Network interface to bind for Hermes HTTP API | -| `hermes_port` | `8443` | HTTP port for the Hermes reporting endpoint | -| `auth_token` | *(auto-generated)* | Pre-shared authentication secret required in client envelopes | -| `db_path` | `"logar_state.db"` | Path to persistent SQLite issue database | -| `evaluation_window_hours` | `12` | Rolling evaluation window in hours for warning persistence | -| `min_persistence_runs` | `4` | Consecutive runs required to promote warning issues to `VERIFIED` | - --- -## 2. Generating Client Configuration Bundles +## 3. Exporting Client Configurations -Edge forwarders (`Win_Client.exe` and `Linux_Client.bin`) require an anonymous client configuration bundle that includes the server socket target, authentication token, and encryption public key, without exposing sensitive server names or private keys. - -Run the following command on the server: +Generate a client configuration bundle to deploy onto Windows or Linux forwarders: ```powershell -.\Server.exe --create-client-config --server-host --server-port 9443 --client-out client_config.json +.\Server.exe --create-client-config --server-host 192.168.1.100 --server-port 9443 --client-out client_config.json ``` - -- Replace `` with the reachable IP or DNS name of your LOGAR server. -- Distribute `client_config.json` to client forwarder nodes along with `Win_Client.exe` or `Linux_Client.bin`. +The output file contains the server coordinates, enrollment secret, and fingerprint, ready for client deployment. --- -## 3. Running Interactively +## 4. Manual Windows Service Setup (via NSSM) ```powershell -.\Server.exe --config C:\LOGAR-Server\server_config.json -``` - -### Command-Line Arguments -| Argument | Description | -| :--- | :--- | -| `--config` | Path to server configuration JSON file (default: `server_config.json`) | -| `--create-client-config` | Exports an anonymous client configuration bundle and exits | -| `--server-host` | Hostname/IP to embed in the exported client configuration | -| `--server-port` | Port to embed in the exported client configuration (default: `9443`) | -| `--client-out` | Destination path for exported client configuration (default: `client_config.json`) | - ---- - -## 4. Installing as a Continuous Windows Service - -Because `Server.exe` acts as a continuous server hub (listening for TCP connections and HTTP API queries), it should run persistently in the background. - -### Method A: Native Windows Service via NSSM (Recommended) -[NSSM (Non-Sucking Service Manager)](https://nssm.cc/) is the industry standard for wrapping standalone executables into formal Windows services managed by `services.msc`. - -1. Place `Server.exe` and `server_config.json` in `C:\LOGAR-Server\`. -2. Open **Elevated PowerShell (Run as Administrator)**: - ```powershell - # Create deployment folder - New-Item -ItemType Directory -Path "C:\LOGAR-Server" -Force - Copy-Item "Server.exe", "server_config.json" -Destination "C:\LOGAR-Server\" - - # Install Windows Service via NSSM - nssm.exe install LOGAR_Server "C:\LOGAR-Server\Server.exe" "--config C:\LOGAR-Server\server_config.json" - nssm.exe set LOGAR_Server AppDirectory "C:\LOGAR-Server" - nssm.exe set LOGAR_Server Description "LOGAR Central Aggregation Hub Service" - nssm.exe set LOGAR_Server Start SERVICE_AUTO_START - nssm.exe set LOGAR_Server AppStdout "C:\LOGAR-Server\server_out.log" - nssm.exe set LOGAR_Server AppStderr "C:\LOGAR-Server\server_err.log" - - # Start the service - nssm.exe start LOGAR_Server - ``` -3. Verify status in PowerShell: - ```powershell - Get-Service -Name "LOGAR_Server" - ``` - -### Method B: Windows Task Scheduler (Startup Daemon) -If third-party service wrappers are restricted by organizational policy, configure a Task Scheduler job triggered at boot under the `SYSTEM` account: - -```powershell -# Action: Launch Server.exe -$Action = New-ScheduledTaskAction -Execute "C:\LOGAR-Server\Server.exe" ` - -Argument "--config C:\LOGAR-Server\server_config.json" ` - -WorkingDirectory "C:\LOGAR-Server" - -# Trigger: At system startup -$Trigger = New-ScheduledTaskTrigger -AtStartup - -# Settings: Restart on failure, no execution time limit -$Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries ` - -DontStopIfGoingOnBatteries ` - -StartWhenAvailable ` - -RestartCount 3 ` - -RestartInterval (New-TimeSpan -Minutes 1) ` - -ExecutionTimeLimit ([TimeSpan]::Zero) - -# Register task under SYSTEM with highest privileges -Register-ScheduledTask -TaskName "LOGAR_Server_Daemon" ` - -Action $Action ` - -Trigger $Trigger ` - -Settings $Settings ` - -User "NT AUTHORITY\SYSTEM" ` - -RunLevel Highest ` - -Description "LOGAR Central Hub Daemon" - -# Start the task immediately -Start-ScheduledTask -TaskName "LOGAR_Server_Daemon" -Get-ScheduledTask -TaskName "LOGAR_Server_Daemon" +.\nssm.exe install LOGAR_Server "C:\LOGAR-Server\Server.exe" +.\nssm.exe set LOGAR_Server AppDirectory "C:\LOGAR-Server" +.\nssm.exe set LOGAR_Server AppStdout "C:\ProgramData\LOGAR-Server\server.log" +.\nssm.exe set LOGAR_Server AppStderr "C:\ProgramData\LOGAR-Server\server_err.log" +.\nssm.exe start LOGAR_Server ``` --- -## 5. Hermes Reporting API & Health Checks +## 5. Uninstallation -Test the embedded Hermes REST endpoint locally using PowerShell: +If installed via the Inno Setup installer, use **Windows Add/Remove Programs**. +If installed manually via NSSM: ```powershell -$report = Invoke-RestMethod -Uri "http://127.0.0.1:8443/api/hermes/report" -Method GET -$report | Format-Table fingerprint, status, consecutive_runs, first_seen, last_seen -``` - -### Response Format: -```json -[ - { - "fingerprint": "win-dc-01.corp.internal:DiskCorruptionDetected", - "server": "win-dc-01.corp.internal", - "signature": "DiskCorruptionDetected", - "consecutive_runs": 4, - "first_seen": "2026-09-04T08:15:00Z", - "last_seen": "2026-09-04T15:00:00Z", - "status": "VERIFIED", - "verified": true, - "os_type": "windows", - "sample_message": "An error was detected on device \\Device\\Harddisk0\\DR0 during a paging operation." - } -] -``` - ---- - -## 6. Windows Defender Firewall Configuration - -Open the necessary inbound firewall ports to allow incoming edge forwarder socket streams and HTTP API queries: - -```powershell -# Allow TCP 9443 for edge log forwarding -New-NetFirewallRule -DisplayName "LOGAR TCP Log Ingestion" ` - -Direction Inbound ` - -LocalPort 9443 ` - -Protocol TCP ` - -Action Allow - -# Allow TCP 8443 for Hermes Reporting REST API -New-NetFirewallRule -DisplayName "LOGAR Hermes Reporting API" ` - -Direction Inbound ` - -LocalPort 8443 ` - -Protocol TCP ` - -Action Allow -``` - ---- - -## 7. Uninstallation & Removal - -To remove the server service: -```powershell -# If installed via NSSM: -nssm.exe stop LOGAR_Server -nssm.exe remove LOGAR_Server confirm - -# If installed via Task Scheduler: -Unregister-ScheduledTask -TaskName "LOGAR_Server_Daemon" -Confirm:$false - -# Clean files -Remove-Item -Recurse -Force "C:\LOGAR-Server" +.\nssm.exe stop LOGAR_Server +.\nssm.exe remove LOGAR_Server confirm ```