This application monitors Windows session events (logon, logoff, lock, unlock) and sends them to a specified API endpoint. It's designed to run as a Windows service on any version of Windows, collecting user session activity and securely transmitting it with an API key.

It is meant to be used as a service installed with the command winagentUSM.exe --service install. Then it will copy the .exe to a folder in C:\ProgramData\UserSessionMon\ where it will create a default config.ini, local record keeping with event_log.csv and error.log for errors. All these files will have permissions restricted to SYSTEM and Administrators to view and edit.

Server app is https://github.com/ghostersk/winauthmon-server

Core Features

Session Event Monitoring: Detects and logs Windows user session events (logon, logoff, lock, unlock)
Secure API Communication: Sends event data to a REST API with API key authentication
Configurable Settings: Uses config.ini for API key, server URL, debug logging, and timezone
CSV Logging: Maintains a local CSV log of all events with send status
Error Recovery: Automatically retries sending failed events
Windows Service: Can be installed and managed as a Windows service
Secure Permissions: Ensures secure file permissions for config and logs

Data Collected

For each session event, the following data is collected and sent:

Event Type: Logon, Logoff, Lock, or Unlock
Username: The Windows username associated with the session
Computer Name: The hostname of the computer
IP Address: The primary IPv4 address of the computer
Timestamp: The time of the event (in the configured timezone)

Configuration

After installing the application as a service with winagentUSM.exe --service install, the application will use a config.ini file located at C:\ProgramData\UserSessionMon\config.ini with the following structure:

[API]
api_key = 47959c6d5d8db64eb0ec3ad824ccbe82618632e2a58823d84aba92078da693fa
server_url = https://192.168.27.1:8000
debug_logs = false
timezone = Europe/London
health_check_interval = 30
health_check_path = /api/health
install_dir = C:\ProgramData\UserSessionMon

You can modify these settings directly in the config file or use command-line options.

Command-Line Usage

The application supports the following command-line options:

Service Management

winagentUSM.exe --service install    # Install the Windows service
winagentUSM.exe --service start      # Start the service
winagentUSM.exe --service stop       # Stop the service
winagentUSM.exe --service restart    # Restart the service
winagentUSM.exe --service remove     # Remove the service
winagentUSM.exe --service run        # Run the service directly (for debugging)

Configuration

winagentUSM.exe --api-key <key>           # Update the API key
winagentUSM.exe --url <url>               # Update the server URL
winagentUSM.exe --debug true|false        # Enable or disable debug logging
winagentUSM.exe --timezone <timezone>     # Update the timezone (e.g., Europe/London)
winagentUSM.exe --check-interval <mins>   # Update health check interval (0 to disable)

Help

winagentUSM.exe --help               # Display help information

Health Checks

The application includes automatic health checks to ensure connectivity and retry failed events:

Startup Check: Validates API key and server connectivity when the service starts
Periodic Checks: Runs every 30 minutes by default (configurable)
Config Change Checks: Triggered when configuration is updated via command-line flags
Failed Event Retry: Automatically retries sending failed events after successful health checks

Health Check Configuration

health_check_interval: Minutes between health checks (default: 30, set to 0 to disable)
health_check_path: API endpoint path for health checks (default: /api/health)

Installation

To install as a Windows service:

Run Command Prompt or PowerShell as Administrator
Navigate to the directory containing the executable
Execute: winagentUSM.exe --service install
(Optional) Configure: winagentUSM.exe --url "https://your-server:8000" --api-key "your-api-key"

File Locations

Executable: C:\ProgramData\UserSessionMon\winagentUSM.exe (after installation)
Config: C:\ProgramData\UserSessionMon\config.ini
Event Log: C:\ProgramData\UserSessionMon\event_log.csv
Error Log: C:\ProgramData\UserSessionMon\error.log
Service Log: C:\ProgramData\UserSessionMon\session_monitor.log

Building from Source

Prerequisites

Go 1.20 or newer
Windows operating system
Administrator rights (for service installation)

Build Steps

Clone the repository
Navigate to the project directory
Run the build command:

go build -o winagentUSM.exe ./cmd/winagent

CSV Log Format

The CSV log file contains the following columns:

eventtype,username,hostname,ipaddress,timestamp,send_status

Where send_status is:

0: Failed to send to API
1: Successfully sent to API
2: Successfully sent on retry

Example CSV:

eventtype,username,hostname,ipaddress,timestamp,send_status
Lock,Josh,DESKTOP-5D51HM9,192.168.66.34,2025-04-27T07:06:14Z,1
Unlock,Josh,DESKTOP-5D51HM9,192.168.66.34,2025-04-27T07:06:24Z,1
Lock,Josh,DESKTOP-5D51HM9,192.168.66.34,2025-04-27T07:08:30Z,1
Unlock,Josh,DESKTOP-5D51HM9,192.168.66.34,2025-04-27T07:09:10Z,1
Lock,Josh,DESKTOP-5D51HM9,192.168.66.34,2025-04-27T07:10:23Z,0
Logon,Irena,DESKTOP-5D51HM9,192.168.66.34,2025-04-27T07:10:38Z,0
Logoff,Irena,DESKTOP-5D51HM9,192.168.66.34,2025-04-27T07:10:51Z,0
Unlock,Josh,DESKTOP-5D51HM9,192.168.66.34,2025-04-27T07:11:03Z,0

Troubleshooting

Common issues and solutions:

Service Won't Start: Check error.log for details
Events Not Being Sent: Verify network connectivity and API endpoint availability
Permission Errors: Ensure the application is run as administrator