Public/Test-GSAEdgeDiagnosticsStatus.ps1
|
# # Function: Test-GSAEdgeDiagnosticsStatus # Reads the GSA client's own cached per-channel health-check result from # HKLM:\SOFTWARE\Microsoft\Global Secure Access Client\State\EdsResults - a pipe-delimited string # the client keeps continuously up to date from its internal edge-diagnostics probes (the same # auth/m365/private/internet.edgediagnostic.globalsecureaccess.microsoft.com checks surfaced by the # Advanced Diagnostics tool and the tray icon). Confirmed via Process Monitor: both # GlobalSecureAccessClient.exe and GlobalSecureAccessClientManagerService.exe read/write this value, # e.g. "2026-11-15T19:34:32Z|User|Entra:0|M365:0|Private:0|Internet:0" (code 0 = healthy). # function Test-GSAEdgeDiagnosticsStatus { <# .SYNOPSIS Reports the GSA client's own cached per-channel edge-diagnostics health status. .DESCRIPTION Reads HKLM:\SOFTWARE\Microsoft\Global Secure Access Client\State\EdsResults, a pipe-delimited string of the form '<UTC timestamp>|<SessionContext>|Entra:<code>|M365:<code>|Private:<code>|Internet:<code>' that the GSA client keeps continuously up to date from its own internal edge-diagnostics probes (the same checks the Advanced Diagnostics tool and tray icon surface). A channel code of 0 means the client itself considers that channel healthy; any other value means the client has flagged that channel unhealthy. This is a fast, local/offline check (registry only) that complements the toolkit's own active connectivity probes (e.g. Test-GSADiagnosticUriConnectivity) by reporting what the client's always-running background health-check loop has already determined. A stale timestamp (older than -StaleAfterMinutes) suggests that background loop may be stalled. .PARAMETER StaleAfterMinutes Age, in minutes, after which the cached EdsResults timestamp is flagged as stale. Default 15. .PARAMETER PassThru Return the $true/$false test result. By default nothing is returned - only logged. .PARAMETER LogLevel Sets the minimum log level written by the module. Valid values are ERROR, WARNING, INFO, DEBUG, and SUCCESS. .OUTPUTS System.Boolean when -PassThru is specified. No output is returned by default. .EXAMPLE Test-GSAEdgeDiagnosticsStatus .EXAMPLE Test-GSAEdgeDiagnosticsStatus -StaleAfterMinutes 30 -PassThru #> [CmdletBinding()] param ( [int]$StaleAfterMinutes = 15, [switch]$PassThru, [ValidateSet("ERROR", "WARNING", "INFO", "DEBUG", "SUCCESS")] [string]$LogLevel ) if ($PSBoundParameters.ContainsKey('LogLevel')) { $script:LogLevel = $LogLevel } $registryPath = Join-Path -Path $script:GSAFwdProfileRegistryPath -ChildPath "State" $valueName = "EdsResults" Write-Log "Checking the GSA client's cached edge-diagnostics channel status (EdsResults)..." "INFO" $raw = Get-ItemPropertyValue -Path $registryPath -Name $valueName -ErrorAction SilentlyContinue if ([string]::IsNullOrWhiteSpace($raw)) { Write-Log "EdsResults registry value was not found. The client may not have completed an edge-diagnostics cycle yet, or this is an older client version that doesn't record this state." "WARNING" if ($PassThru) { return $false } return } # Format: <UTC timestamp>|<SessionContext>|Entra:<code>|M365:<code>|Private:<code>|Internet:<code> $parts = @($raw -split '\|') if ($parts.Count -lt 3) { Write-Log "EdsResults value '$raw' is not in the expected pipe-delimited format. Skipping detailed parsing." "WARNING" if ($PassThru) { return $false } return } $timestampRaw = $parts[0] $sessionContext = $parts[1] $channelParts = $parts[2..($parts.Count - 1)] $allHealthy = $true foreach ($channelPart in $channelParts) { if ($channelPart -notmatch '^(?<name>[^:]+):(?<code>-?\d+)$') { Write-Log " Could not parse channel entry '$channelPart'." "DEBUG" continue } $name = $Matches.name $code = $Matches.code if ($code -eq '0') { Write-Log " Channel '$name': healthy (code 0)." "SUCCESS" } else { Write-Log " Channel '$name': reported unhealthy by the GSA client itself (code $code)." "ERROR" $allHealthy = $false } } try { $timestamp = [datetime]::Parse($timestampRaw, [System.Globalization.CultureInfo]::InvariantCulture, [System.Globalization.DateTimeStyles]::RoundtripKind) $age = (Get-Date).ToUniversalTime() - $timestamp.ToUniversalTime() if ($age.TotalMinutes -gt $StaleAfterMinutes) { Write-Log "EdsResults was last updated $([int]$age.TotalMinutes) minute(s) ago (UTC: $($timestamp.ToString('u')), session context: $sessionContext) - older than $StaleAfterMinutes minute(s). The client's background health-check loop may be stalled." "WARNING" } else { Write-Log "EdsResults was last updated $([int]$age.TotalMinutes) minute(s) ago (session context: $sessionContext)." "INFO" } } catch { Write-Log "Could not parse EdsResults timestamp '$timestampRaw': $($_.Exception.Message)" "DEBUG" } if (-not $allHealthy) { Write-Log "Recommended action: one or more GSA forwarding-profile channels are reported unhealthy by the client's own edge diagnostics. Open Advanced Diagnostics > Health check in the GSA client tray icon, and verify connectivity to the matching *.edgediagnostic.globalsecureaccess.microsoft.com endpoint." "WARNING" if ($PassThru) { return $false } return } Write-Log "All GSA forwarding-profile channels are reported healthy by the client's own edge diagnostics." "SUCCESS" if ($PassThru) { return $true } } |