me0nline/LOGAR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

docs(win_server): update README.md with mTLS 1.3, dynamic PKI licensing, and Inno Setup installer instructions

Browse Source
This commit is contained in:
me0nline
2026-09-04 22:39:25 +02:00
parent 4a446a2e73
commit d61e343fbe
1 changed files with 56 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
out/win_server/README.md
+61 -177
View File
@@ -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` |
---
## 3. Exporting Client Configurations
Generate a client configuration bundle to deploy onto Windows or Linux forwarders:
```powershell
.\Server.exe --create-client-config --server-host 192.168.1.100 --server-port 9443 --client-out client_config.json
```
The output file contains the server coordinates, enrollment secret, and fingerprint, ready for client deployment.
---
## 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_IP_OR_FQDN> --server-port 9443 --client-out client_config.json
```
- Replace `<SERVER_IP_OR_FQDN>` 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
## 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
```