LOGAR/out/win_client/README.md

LOGAR Windows Edge Forwarder

Standalone compiled executable and installer distribution for Windows Server and workstation environments.

---

Overview

Win_Client.exe is a self-contained executable that queries the Windows Application Event Log, filters candidate events at the source, auto-enrolls with the central LOGAR hub to receive signed mTLS certificates, and streams records over mutual TLS 1.3 (mTLS) socket connection.

Key Capabilities

• Pre-compiled & Dependency-Free: Ships as a standalone native Windows executable (Win_Client.exe) or full installer (LOGAR-Client-Setup.exe). No Python installation, pip packages, or GnuPG binaries are required on the host.
• Mutual TLS 1.3 (mTLS) Ingestion: Streams directly over hardware-authenticated TLS 1.3 sockets with hardware/machine-bound client certificates.
• Automated Client Enrollment: On first run with an enrollment_secret, the client automatically calls POST /api/client/enroll on the hub, saves its certificates into certs/, and establishes secure mTLS streaming.
• Proactive Expiry Check & Reactive Self-Healing: Before each run, the client evaluates client.crt validity. If within 30 days of expiry, it automatically contacts the hub to renew certificates. If the server Root CA rotates or a TLS handshake error occurs, the client catch-heals by re-enrolling immediately and re-establishing connection without human intervention.
• Source-Level Filtering: Retains events spanning INFO, WARNING, and ERROR. Strips audit events and debug noise, skipping events older than 24 hours.
• State Tracking & Deduplication: Maintains persistent client state in client_state.json (tracking event record numbers and timestamp signatures) so every log record is forwarded exactly once without duplicates.
• Fail-Safe State Commit: State is committed only when the server returns a verified success response. In the event of a network outage, state remains unchanged and unsent events are retried automatically on the next run.
• Fleet Seat Accounting & License Revocation: Each enrolled client consumes 1 seat from the hub's master license. If revoked by an administrator via the hub WebUI, socket connections are immediately dropped and blocked until reactivated.

---

1. Automated Installation via Inno Setup (Recommended)

Run the self-contained installer built from compilation/installer_client.iss:

.\LOGAR-Client-Setup.exe

This installer:

1. Installs Win_Client.exe and bundled nssm.exe to C:\Program Files\LOGAR\.
2. Sets up directory permissions in C:\ProgramData\LOGAR\.
3. Registers and starts the LOGAR_Client Windows service automatically via NSSM.
4. Redirects stdout and stderr logs to C:\ProgramData\LOGAR\client.log and client_err.log.

---

2. Generating & Deploying the Configuration File

Step 1: Generate client_config.json on the Server

Run the following command on your central LOGAR server:

python src/Server.py --create-client-config --server-host <SERVER_IP_OR_DNS> --server-port 9443 --client-out client_config.json

• Replace <SERVER_IP_OR_DNS> with the reachable IP address or FQDN of your central LOGAR server hub.
• Default mTLS socket port is 9443; Hermes REST API port is 8443.

Step 2: Configuration Structure

The generated client_config.json contains:

{
  "server_host": "192.168.1.100",
  "server_port": 9443,
  "hermes_host": "192.168.1.100",
  "hermes_port": 8443,
  "enrollment_secret": "a1b2c3d4e5f6...",
  "cert_dir": "certs",
  "server_fingerprint": "375388960531264EA0648EC0D2C4E4ABC6F22AC2",
  "server_public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...",
  "auth_token": "a1b2c3d4e5f6..."
}

Note

The configuration contains no host-specific names or site names to ensure client anonymity and easy redistribution.

Step 3: Copy to Edge Node

Place client_config.json next to Win_Client.exe (e.g. C:\Program Files\LOGAR\ or C:\LOGAR\):

New-Item -ItemType Directory -Path "C:\LOGAR" -Force
Copy-Item "Win_Client.exe", "client_config.json" -Destination "C:\LOGAR\"

---

3. Running Manually

Test the forwarder interactively from PowerShell or Command Prompt:

cd C:\LOGAR
.\Win_Client.exe --hours 24

On first run, the client contacts http://<hermes_host>:<hermes_port>/api/client/enroll, downloads ca.crt, client.crt, and client.key into certs/, and streams logs over mTLS.

Command-Line Arguments

Argument	Default	Description
--config	client_config.json	Path to client configuration file
--hours	24	Lookback window in hours for event logs
--state-file	client_state.json	Path to persistent state tracking file
--no-state	False	Disable state tracking and send all events matching lookback window

---

4. Manual Service Installation (NSSM or Scheduled Task)

Method A: Windows Service via Bundled NSSM

# From the compilation directory or with bundled nssm.exe:
.\nssm.exe install LOGAR_Client "C:\LOGAR\Win_Client.exe" "--hours 24"
.\nssm.exe set LOGAR_Client AppDirectory "C:\LOGAR"
.\nssm.exe set LOGAR_Client AppStdout "C:\ProgramData\LOGAR\client.log"
.\nssm.exe set LOGAR_Client AppStderr "C:\ProgramData\LOGAR\client_err.log"
.\nssm.exe start LOGAR_Client

Method B: Windows Scheduled Task via PowerShell

$Action = New-ScheduledTaskAction -Execute "C:\LOGAR\Win_Client.exe" -Argument "--hours 24" -WorkingDirectory "C:\LOGAR"
$Trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Hours 3)
$Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Minutes 15)

Register-ScheduledTask -TaskName "LOGAR_Forwarder" `
                       -Action $Action `
                       -Trigger $Trigger `
                       -Settings $Settings `
                       -User "NT AUTHORITY\SYSTEM" `
                       -RunLevel Highest `
                       -Description "LOGAR Windows Edge Log Forwarder Service"

Start-ScheduledTask -TaskName "LOGAR_Forwarder"

---

5. Uninstallation

If installed via the Inno Setup installer, use Windows Add/Remove Programs or run unins000.exe in C:\Program Files\LOGAR\.

If installed manually via NSSM:

.\nssm.exe stop LOGAR_Client
.\nssm.exe remove LOGAR_Client confirm
Remove-Item -Recurse -Force "C:\LOGAR"