From e1dbe32063eb0e71c79dd6d1981fa67776fba683 Mon Sep 17 00:00:00 2001 From: Maximilian Eibl Date: Fri, 4 Sep 2026 16:04:51 +0200 Subject: [PATCH] Add Windows server deployment guide and sample configuration to out/win_server --- out/win_server/README.md | 237 +++++++++++++++++++++++ out/win_server/server_config.sample.json | 14 ++ 2 files changed, 251 insertions(+) create mode 100644 out/win_server/README.md create mode 100644 out/win_server/server_config.sample.json diff --git a/out/win_server/README.md b/out/win_server/README.md new file mode 100644 index 0000000..a1e97c0 --- /dev/null +++ b/out/win_server/README.md @@ -0,0 +1,237 @@ +# LOGAR Windows Server Hub + +Standalone compiled executable 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. + +### 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`). +- **4-Run Temporal Persistence Rule**: Filters transient noise by requiring an issue signature to recur across at least 4 episodic 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`). + +--- + +## 1. 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). + +Open PowerShell and run: +```powershell +.\Server.exe +``` +Output: +``` +[!] Config 'server_config.json' not found. Initializing first-run configuration... +[+] Successfully generated new server config and OpenPGP keypair. +[+] Server Encryption Fingerprint: 375388960531264EA0648EC0D2C4E4ABC6F22AC2 +[+] Saved to: server_config.json +``` + +### Step 2: Configuration Fields Reference +The generated `server_config.json` contains: + +```json +{ + "server_name": "LOGAR-Windows-Hub", + "tcp_host": "0.0.0.0", + "tcp_port": 9443, + "hermes_host": "0.0.0.0", + "hermes_port": 8443, + "auth_token": "a1b2c3d4e5f67890abcdef1234567890...", + "db_path": "logar_state.db", + "evaluation_window_hours": 12, + "min_persistence_runs": 4, + "server_fingerprint": "375388960531264EA0648EC0D2C4E4ABC6F22AC2", + "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...", + "private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n..." +} +``` + +| 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 4-run rule | +| `min_persistence_runs` | `4` | Consecutive runs required to promote an issue to `VERIFIED` | + +--- + +## 2. Generating Client Configuration Bundles + +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: +```powershell +.\Server.exe --create-client-config --server-host --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`. + +--- + +## 3. Running Interactively + +```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" +``` + +--- + +## 5. Hermes Reporting API & Health Checks + +Test the embedded Hermes REST endpoint locally using PowerShell: + +```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" +``` diff --git a/out/win_server/server_config.sample.json b/out/win_server/server_config.sample.json new file mode 100644 index 0000000..53ae117 --- /dev/null +++ b/out/win_server/server_config.sample.json @@ -0,0 +1,14 @@ +{ + "server_name": "LOGAR-Windows-Hub", + "tcp_host": "0.0.0.0", + "tcp_port": 9443, + "hermes_host": "0.0.0.0", + "hermes_port": 8443, + "auth_token": "replace_with_secure_random_hex_token", + "db_path": "logar_state.db", + "evaluation_window_hours": 12, + "min_persistence_runs": 4, + "server_fingerprint": "AUTO_GENERATED_ON_FIRST_RUN", + "public_key": "AUTO_GENERATED_ON_FIRST_RUN", + "private_key": "AUTO_GENERATED_ON_FIRST_RUN" +}