Implement edge filtering, state tracking, clean out/ directory, and add Gitea CI workflow

out/win_client/README.md

@@ -1,31 +1,127 @@
 # LOGAR Windows Edge Forwarder
 
-Lightweight edge log forwarder for Windows servers.
+Standalone compiled executable distribution for Windows Server and workstation environments.
 
-## Features
-- **Zero Local State**: No local database or state tracking. Forwarder simply scans recent logs and streams candidates.
-- **Edge Noise Stripping**: Strips conversational/informational noise (INFO, DEBUG, Audit) at the source.
-- **End-to-End OpenPGP Encryption**: Encrypts logs using the server's public key so that only the server can decrypt them.
-- **Authenticated TCP Socket**: Connects directly via raw TCP framing with token verification.
-- **No GPG Binary Required**: Pure-Python cryptography (`pgpy` + `cryptography`).
+---
 
-## Installation
-```powershell
-python -m pip install -r requirements.txt
+## Overview
+`Win_Client.exe` is a self-contained, pre-compiled executable that queries the Windows Application Event Log, filters candidate events at the source, encrypts the payload using OpenPGP, and streams records over an authenticated TCP socket to the central LOGAR hub.
+
+### Key Capabilities
+- **Pre-compiled & Dependency-Free**: Ships as a standalone native Windows executable (`Win_Client.exe`). No Python installation, pip packages, or GnuPG binaries are required on the host.
+- **Source-Level Filtering**: Retains events spanning `INFO`, `WARNING`, and `ERROR`. Strips audit success/failure 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.
+- **End-to-End Encryption**: Encrypts payloads using the server's OpenPGP public key before transmission.
+
+---
+
+## 1. Generating & Deploying the Configuration File
+
+### Step 1: Generate `client_config.json` on the Server
+Run the following command on your central LOGAR server to export a client bundle tailored for your environment:
+
+```bash
+python Server.py --create-client-config --server-host <SERVER_IP_OR_DNS> --server-port 9443 --client-out client_config.json
 ```
 
-## Configuration
-Place the `client_config.json` generated by the server (`Server.py --create-client-config`) in the same directory as `Win_Client.py`.
+- Replace `<SERVER_IP_OR_DNS>` with the reachable IP address or FQDN of your central LOGAR server hub.
+- Default TCP port is `9443`.
 
-## Running the Forwarder
-```powershell
-python Win_Client.py --hours 6
+### Step 2: Configuration Structure
+The generated `client_config.json` contains:
+
+```json
+{
+  "server_host": "192.168.1.100",
+  "server_port": 9443,
+  "server_fingerprint": "375388960531264EA0648EC0D2C4E4ABC6F22AC2",
+  "server_public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...",
+  "auth_token": "a1b2c3d4e5f6..."
+}
 ```
 
-## Scheduled Task Deployment
-To run periodically via Windows Task Scheduler (e.g., every 3 hours):
+> [!NOTE]
+> A reference example is provided in `client_config.sample.json`. The configuration file contains **no host-specific names or site names** to ensure client anonymity and easy redistribution.
+
+### Step 3: Copy to Edge Node
+Place `Win_Client.exe` and `client_config.json` in the target directory (recommended: `C:\LOGAR\`):
+
 ```powershell
-$Action = New-ScheduledTaskAction -Execute "python.exe" -Argument "C:\LOGAR\Win_Client.py --hours 6" -WorkingDirectory "C:\LOGAR"
+New-Item -ItemType Directory -Path "C:\LOGAR" -Force
+Copy-Item "Win_Client.exe", "client_config.json" -Destination "C:\LOGAR\"
+```
+
+---
+
+## 2. Running Manually
+
+Test the forwarder interactively from PowerShell or Command Prompt:
+
+```powershell
+cd C:\LOGAR
+.\Win_Client.exe --hours 24
+```
+
+### 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 |
+
+---
+
+## 3. Installing as a Background Service / Scheduled Task
+
+Edge forwarders run as episodic background processes (run, forward unsent candidate records, commit state, and terminate). On Windows, this is natively managed via Windows Task Scheduler running as a background service under `SYSTEM`.
+
+### Method A: Windows Scheduled Task via PowerShell (Recommended)
+Open an **Elevated PowerShell (Run as Administrator)** window and execute:
+
+```powershell
+# Define action and periodic trigger (every 3 hours indefinitely)
+$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)
-Register-ScheduledTask -TaskName "LOGAR_Windows_Forwarder" -Action $Action -Trigger $Trigger -Description "LOGAR Edge Forwarder"
+
+# Configure task settings (wake on sleep, start when ready, run hidden)
+$Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Minutes 15)
+
+# Register task running under the local SYSTEM account with highest privileges
+Register-ScheduledTask -TaskName "LOGAR_Forwarder" `
+                       -Action $Action `
+                       -Trigger $Trigger `
+                       -Settings $Settings `
+                       -User "NT AUTHORITY\SYSTEM" `
+                       -RunLevel Highest `
+                       -Description "LOGAR Windows Edge Log Forwarder Service"
+
+# Verify task creation and trigger immediate execution
+Start-ScheduledTask -TaskName "LOGAR_Forwarder"
+Get-ScheduledTask -TaskName "LOGAR_Forwarder"
+```
+
+### Method B: Continuous Windows Service via NSSM
+If your organizational policy requires a formal Windows Service listed under `services.msc`:
+
+1. Download [NSSM (Non-Sucking Service Manager)](https://nssm.cc/).
+2. Install the service using NSSM:
+   ```cmd
+   nssm.exe install LOGAR_Forwarder "C:\LOGAR\Win_Client.exe" "--hours 24"
+   nssm.exe set LOGAR_Forwarder AppDirectory "C:\LOGAR"
+   nssm.exe set LOGAR_Forwarder AppRestartDelay 10800000
+   nssm.exe start LOGAR_Forwarder
+   ```
+   *(Note: `AppRestartDelay 10800000` pauses 3 hours between execution cycles).*
+
+---
+
+## 4. Uninstallation & Removal
+
+To remove the scheduled task:
+
+```powershell
+Unregister-ScheduledTask -TaskName "LOGAR_Forwarder" -Confirm:$false
+Remove-Item -Recurse -Force "C:\LOGAR"
 ```