behavioral changes

add usage window
2026-07-08 11:36:27 -04:00 · 2026-07-08 11:27:51 -04:00
1 changed files with 251 additions and 110 deletions
@@ -11,14 +11,36 @@ $End = '2026-07-06T00:00:00Z'

 .EXAMPLE
 .\Get-UserLogonActivity.ps1
+
+Returns activity from the last 7 days.
+
+.EXAMPLE
+$Start = '2026-07-03T00:00:00Z'
+.\Get-UserLogonActivity.ps1
+
+Returns activity from the specified start date through now.
 #>

 $StartVariable = Get-Variable -Name Start -ErrorAction SilentlyContinue
 $EndVariable = Get-Variable -Name End -ErrorAction SilentlyContinue
-$UseDateRange = ($null -ne $StartVariable -and $null -ne $EndVariable)

-If (($null -ne $StartVariable) -xor ($null -ne $EndVariable)) {
-    Write-Error '$Start and $End must either both be defined or both be omitted. If omitted, the script returns the latest 15 activity events.'
+Function Test-ActivityDateRangeValue {
+    Param(
+        [AllowNull()]
+        [object]$Value
+    )
+
+    If ($null -eq $Value) { Return $false }
+    If ($Value -is [string]) { Return -not [string]::IsNullOrWhiteSpace($Value) }
+
+    Return $true
+}
+
+$StartHasValue = ($null -ne $StartVariable -and (Test-ActivityDateRangeValue -Value $StartVariable.Value))
+$EndHasValue = ($null -ne $EndVariable -and (Test-ActivityDateRangeValue -Value $EndVariable.Value))
+
+If ($EndHasValue -and -not $StartHasValue) {
+    Write-Error '$Start must be defined when $End is defined. If only $Start is defined, the script uses now for $End. If neither is defined, the script returns activity from the last 7 days.'
    Exit 1
 }

@@ -193,6 +215,28 @@ Function Resolve-UserLogonActivitySid {
    }
 }

+Function Get-UserLogonActivityKey {
+    Param(
+        [AllowNull()]
+        [object]$Sid,
+
+        [AllowNull()]
+        [string]$User
+    )
+
+    $SidString = ([string]$Sid).Trim()
+    If (-not [string]::IsNullOrWhiteSpace($SidString) -and $SidString -ne '-') {
+        Return $SidString.ToUpperInvariant()
+    }
+
+    $UserString = ([string]$User).Trim()
+    If (-not [string]::IsNullOrWhiteSpace($UserString)) {
+        Return $UserString.ToUpperInvariant()
+    }
+
+    Return ''
+}
+
 Function Get-UserLogonActivitySidFromEvent {
    Param(
        [Parameter(Mandatory=$true)]
@@ -234,6 +278,8 @@ Function New-UserLogonActivityRecord {

        [string]$Details = '',

+        [string]$UserKey = '',
+
        [int]$SourcePriority = 50,

        [switch]$AllowSystemUser
@@ -241,6 +287,11 @@ Function New-UserLogonActivityRecord {

    If (-not $AllowSystemUser -and -not (Test-UserLogonActivityUser -UserName $User)) { Return $null }

+    $ResolvedUserKey = $UserKey
+    If ([string]::IsNullOrWhiteSpace($ResolvedUserKey)) {
+        $ResolvedUserKey = Get-UserLogonActivityKey -Sid $null -User $User
+    }
+
    [PSCustomObject]@{
        Date = $TimeCreated.ToString('yyyy-MM-dd')
        Time = $TimeCreated.ToString('HH:mm:ss')
@@ -248,6 +299,7 @@ Function New-UserLogonActivityRecord {
        Activity = $Activity
        Source = $Source
        Details = $Details
+        UserKey = $ResolvedUserKey
        SourcePriority = $SourcePriority
        TimeCreated = $TimeCreated
    }
@@ -265,10 +317,11 @@ Function ConvertTo-WinlogonUserActivity {
        Default { Return $null }
    }

-    $User = Resolve-UserLogonActivitySid -Sid (Get-UserLogonActivitySidFromEvent -Event $Event)
+    $UserSid = Get-UserLogonActivitySidFromEvent -Event $Event
+    $User = Resolve-UserLogonActivitySid -Sid $UserSid
    If ([string]::IsNullOrWhiteSpace($User)) { Return $null }

-    New-UserLogonActivityRecord -TimeCreated $Event.TimeCreated -User $User -Activity $Activity -Source $Source -SourcePriority 10
+    New-UserLogonActivityRecord -TimeCreated $Event.TimeCreated -User $User -Activity $Activity -Source $Source -UserKey (Get-UserLogonActivityKey -Sid $UserSid -User $User) -SourcePriority 10
 }

 Function ConvertTo-SecurityUserActivity {
@@ -280,6 +333,7 @@ Function ConvertTo-SecurityUserActivity {
    $EventXml = [xml]$Event.ToXml()
    $UserName = Get-EventDataValueFromList -EventXml $EventXml -Names @('TargetUserName', 'SubjectUserName')
    $DomainName = Get-EventDataValueFromList -EventXml $EventXml -Names @('TargetDomainName', 'SubjectDomainName')
+    $UserSid = Get-EventDataValueFromList -EventXml $EventXml -Names @('TargetUserSid', 'SubjectUserSid')
    $LogonType = Get-EventDataValue -EventXml $EventXml -Name 'LogonType'
    $Activity = $null
    $Source = $null
@@ -334,7 +388,8 @@ Function ConvertTo-SecurityUserActivity {
        }
    }

-    New-UserLogonActivityRecord -TimeCreated $Event.TimeCreated -User (Format-UserName -DomainName $DomainName -UserName $UserName) -Activity $Activity -Source $Source -Details $Details -SourcePriority $SourcePriority
+    $User = Format-UserName -DomainName $DomainName -UserName $UserName
+    New-UserLogonActivityRecord -TimeCreated $Event.TimeCreated -User $User -Activity $Activity -Source $Source -Details $Details -UserKey (Get-UserLogonActivityKey -Sid $UserSid -User $User) -SourcePriority $SourcePriority
 }

 Function ConvertTo-TerminalServicesUserActivity {
@@ -367,7 +422,7 @@ Function ConvertTo-TerminalServicesUserActivity {
        }
    }

-    New-UserLogonActivityRecord -TimeCreated $Event.TimeCreated -User $User -Activity $Activity -Source $Source -Details ($DetailsParts -join '; ') -SourcePriority 20
+    New-UserLogonActivityRecord -TimeCreated $Event.TimeCreated -User $User -Activity $Activity -Source $Source -Details ($DetailsParts -join '; ') -UserKey (Get-UserLogonActivityKey -Sid $null -User $User) -SourcePriority 20
 }

 Function ConvertTo-PowerUserActivity {
@@ -478,12 +533,22 @@ Function Get-UniqueUserLogonActivity {

    ForEach ($ActivityEvent in (@($ActivityEvents) | Where-Object { $null -ne $_ } | Sort-Object -Property TimeCreated,User,Activity,SourcePriority)) {
        $IsDuplicate = $false
+        $ActivityEventKey = [string]$ActivityEvent.UserKey
+
+        If ([string]::IsNullOrWhiteSpace($ActivityEventKey)) {
+            $ActivityEventKey = Get-UserLogonActivityKey -Sid $null -User $ActivityEvent.User
+        }

        For ($Index = 0; $Index -lt $UniqueEvents.Count; $Index++) {
            $UniqueEvent = $UniqueEvents[$Index]
+            $UniqueEventKey = [string]$UniqueEvent.UserKey
+
+            If ([string]::IsNullOrWhiteSpace($UniqueEventKey)) {
+                $UniqueEventKey = Get-UserLogonActivityKey -Sid $null -User $UniqueEvent.User
+            }

            If (
-                $UniqueEvent.User -eq $ActivityEvent.User -and
+                $UniqueEventKey -eq $ActivityEventKey -and
                $UniqueEvent.Activity -eq $ActivityEvent.Activity -and
                [Math]::Abs(($UniqueEvent.TimeCreated - $ActivityEvent.TimeCreated).TotalSeconds) -le 5
            ) {
@@ -520,6 +585,125 @@ Function Write-UserLogonActivityOutput {
    Write-Output (($Rows | Format-Table -AutoSize | Out-String -Width 240).TrimEnd())
 }

+Function Get-PossibleUseWindow {
+    Param(
+        [AllowNull()]
+        [object[]]$ActivityEvents
+    )
+
+    $OpenWindows = @{}
+    $UseWindows = New-Object System.Collections.Generic.List[object]
+    $OpeningActivities = @('logon', 'unlock', 'remote logon', 'session reconnect', 'screensaver dismiss')
+    $ImpliedClosureDescriptions = @{
+        'unlock' = 'implied prior lock before'
+        'session reconnect' = 'implied prior disconnect before'
+        'screensaver dismiss' = 'implied prior screensaver before'
+    }
+
+    ForEach ($ActivityEvent in (@($ActivityEvents) | Where-Object { $null -ne $_ } | Sort-Object -Property TimeCreated)) {
+        $User = [string]$ActivityEvent.User
+        $UserKey = [string]$ActivityEvent.UserKey
+        $Activity = [string]$ActivityEvent.Activity
+        $Source = [string]$ActivityEvent.Source
+
+        If ([string]::IsNullOrWhiteSpace($UserKey)) {
+            $UserKey = Get-UserLogonActivityKey -Sid $null -User $User
+        }
+
+        If ($Activity -in @('sleep', 'shutdown', 'restart')) {
+            ForEach ($OpenUserKey in @($OpenWindows.Keys)) {
+                $OpenWindow = $OpenWindows[$OpenUserKey]
+                $UseWindows.Add([PSCustomObject]@{
+                    StartTime = $OpenWindow.StartTime
+                    Start = $OpenWindow.StartTime.ToString('yyyy-MM-dd HH:mm:ss')
+                    End = $ActivityEvent.TimeCreated.ToString('yyyy-MM-dd HH:mm:ss')
+                    User = $OpenWindow.User
+                    StartedBy = $OpenWindow.StartedBy
+                    EndedBy = "${Activity} / ${Source}"
+                }) | Out-Null
+                $OpenWindows.Remove($OpenUserKey)
+            }
+
+            Continue
+        }
+
+        If ([string]::IsNullOrWhiteSpace($User) -or $User -eq 'SYSTEM' -or $User -eq 'NT AUTHORITY\SYSTEM') {
+            Continue
+        }
+
+        If ($Activity -in $OpeningActivities) {
+            If ($OpenWindows.ContainsKey($UserKey) -and $ImpliedClosureDescriptions.ContainsKey($Activity)) {
+                $OpenWindow = $OpenWindows[$UserKey]
+                $UseWindows.Add([PSCustomObject]@{
+                    StartTime = $OpenWindow.StartTime
+                    Start = $OpenWindow.StartTime.ToString('yyyy-MM-dd HH:mm:ss')
+                    End = "before $($ActivityEvent.TimeCreated.ToString('yyyy-MM-dd HH:mm:ss'))"
+                    User = $OpenWindow.User
+                    StartedBy = $OpenWindow.StartedBy
+                    EndedBy = "$($ImpliedClosureDescriptions[$Activity]) ${Activity} / ${Source}"
+                }) | Out-Null
+                $OpenWindows.Remove($UserKey)
+            }
+
+            If (-not $OpenWindows.ContainsKey($UserKey)) {
+                $OpenWindows[$UserKey] = [PSCustomObject]@{
+                    StartTime = $ActivityEvent.TimeCreated
+                    User = $User
+                    StartedBy = "${Activity} / ${Source}"
+                }
+            }
+        }
+        ElseIf ($Activity -in @('logoff', 'lock', 'session disconnect')) {
+            If ($OpenWindows.ContainsKey($UserKey)) {
+                $OpenWindow = $OpenWindows[$UserKey]
+                $UseWindows.Add([PSCustomObject]@{
+                    StartTime = $OpenWindow.StartTime
+                    Start = $OpenWindow.StartTime.ToString('yyyy-MM-dd HH:mm:ss')
+                    End = $ActivityEvent.TimeCreated.ToString('yyyy-MM-dd HH:mm:ss')
+                    User = $OpenWindow.User
+                    StartedBy = $OpenWindow.StartedBy
+                    EndedBy = "${Activity} / ${Source}"
+                }) | Out-Null
+                $OpenWindows.Remove($UserKey)
+            }
+        }
+    }
+
+    ForEach ($OpenUserKey in @($OpenWindows.Keys)) {
+        $OpenWindow = $OpenWindows[$OpenUserKey]
+        $UseWindows.Add([PSCustomObject]@{
+            StartTime = $OpenWindow.StartTime
+            Start = $OpenWindow.StartTime.ToString('yyyy-MM-dd HH:mm:ss')
+            End = 'open through returned events'
+            User = $OpenWindow.User
+            StartedBy = $OpenWindow.StartedBy
+            EndedBy = 'not closed in returned events'
+        }) | Out-Null
+    }
+
+    Return $UseWindows
+}
+
+Function Write-PossibleUseWindowOutput {
+    Param(
+        [AllowNull()]
+        [object[]]$ActivityEvents
+    )
+
+    $UseWindows = @(Get-PossibleUseWindow -ActivityEvents $ActivityEvents | Sort-Object -Property StartTime)
+
+    If ($UseWindows.Count -eq 0) {
+        Write-Output ''
+        Write-Output 'Possible use windows inferred from returned events: none'
+        Return
+    }
+
+    $Rows = @($UseWindows | Select-Object Start,End,User,StartedBy,EndedBy)
+    Write-Output ''
+    Write-Output 'Possible use windows inferred from returned events:'
+    Write-Output (($Rows | Format-Table -AutoSize | Out-String -Width 240).TrimEnd())
+}
+
 # Winlogon 7001/7002 tracks user session logon/logoff more reliably than Security 4624/4634.
 $WinlogonFilter = @{
    LogName = 'System'
@@ -567,113 +751,70 @@ $PowerFilters = @(
    }
 )

-If ($UseDateRange) {
-    Try {
+Try {
+    If ($StartHasValue) {
        $StartDateTime = ConvertTo-ActivityDateTime -Value $Start -ParameterName 'Start'
+    }
+
+    If ($EndHasValue) {
        $EndDateTime = ConvertTo-ActivityDateTime -Value $End -ParameterName 'End'
    }
-    Catch {
-        Write-Error $_.Exception.Message
-        Exit 1
+
+    If (-not $EndHasValue) {
+        $EndDateTime = [DateTimeOffset]::Now
    }

-    If ($EndDateTime -le $StartDateTime) {
-        Write-Error "-End must be later than -Start."
-        Exit 1
+    If (-not $StartHasValue) {
+        $StartDateTime = $EndDateTime.AddDays(-7)
    }
-
-    $WinlogonFilter.StartTime = $StartDateTime.LocalDateTime
-    $WinlogonFilter.EndTime = $EndDateTime.LocalDateTime
-    $SecurityFilter.StartTime = $StartDateTime.LocalDateTime
-    $SecurityFilter.EndTime = $EndDateTime.LocalDateTime
-    $UnlockAuthFilter.StartTime = $StartDateTime.LocalDateTime
-    $UnlockAuthFilter.EndTime = $EndDateTime.LocalDateTime
-    $TerminalServicesFilter.StartTime = $StartDateTime.LocalDateTime
-    $TerminalServicesFilter.EndTime = $EndDateTime.LocalDateTime
-    ForEach ($PowerFilter in $PowerFilters) {
-        $PowerFilter.StartTime = $StartDateTime.LocalDateTime
-        $PowerFilter.EndTime = $EndDateTime.LocalDateTime
-    }
-
-    $ActivityEvents = New-Object System.Collections.Generic.List[object]
-
-    ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $WinlogonFilter -LogDescription 'System Winlogon event log')) {
-        Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-WinlogonUserActivity -Event $Event)
-    }
-
-    ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $SecurityFilter -LogDescription 'Security event log')) {
-        Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-SecurityUserActivity -Event $Event)
-    }
-
-    ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $UnlockAuthFilter -LogDescription 'Security unlock-authentication event log')) {
-        Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-SecurityUserActivity -Event $Event)
-    }
-
-    ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $TerminalServicesFilter -LogDescription 'Terminal Services Local Session Manager event log')) {
-        Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-TerminalServicesUserActivity -Event $Event)
-    }
-
-    ForEach ($PowerFilter in $PowerFilters) {
-        ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $PowerFilter -LogDescription 'System power event log')) {
-            Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-PowerUserActivity -Event $Event)
-        }
-    }
-
-    $OutputEvents = @(Get-UniqueUserLogonActivity -ActivityEvents $ActivityEvents | Sort-Object -Property TimeCreated)
-    Write-UserLogonActivityOutput -ActivityEvents $OutputEvents
 }
-Else {
-    $ActivityLimit = 15
-    $SearchLimit = 200
-    $MaxSearchLimit = 10000
-    $OutputEvents = @()
-
-    Do {
-        $ActivityEvents = New-Object System.Collections.Generic.List[object]
-        $WinlogonEvents = @(Get-UserLogonActivityWinEvent -FilterHashtable $WinlogonFilter -MaxEvents $SearchLimit -LogDescription 'System Winlogon event log')
-        $SecurityEvents = @(Get-UserLogonActivityWinEvent -FilterHashtable $SecurityFilter -MaxEvents $SearchLimit -LogDescription 'Security event log')
-        $UnlockAuthEvents = @(Get-UserLogonActivityWinEvent -FilterHashtable $UnlockAuthFilter -MaxEvents $SearchLimit -LogDescription 'Security unlock-authentication event log')
-        $TerminalServicesEvents = @(Get-UserLogonActivityWinEvent -FilterHashtable $TerminalServicesFilter -MaxEvents $SearchLimit -LogDescription 'Terminal Services Local Session Manager event log')
-        $PowerEvents = @()
-        $PowerFiltersMayHaveMoreEvents = $false
-
-        ForEach ($Event in $WinlogonEvents) {
-            Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-WinlogonUserActivity -Event $Event)
-        }
-
-        ForEach ($Event in $SecurityEvents) {
-            Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-SecurityUserActivity -Event $Event)
-        }
-
-        ForEach ($Event in $UnlockAuthEvents) {
-            Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-SecurityUserActivity -Event $Event)
-        }
-
-        ForEach ($Event in $TerminalServicesEvents) {
-            Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-TerminalServicesUserActivity -Event $Event)
-        }
-
-        ForEach ($PowerFilter in $PowerFilters) {
-            $CurrentPowerEvents = @(Get-UserLogonActivityWinEvent -FilterHashtable $PowerFilter -MaxEvents $SearchLimit -LogDescription 'System power event log')
-            $PowerEvents += $CurrentPowerEvents
-
-            If ($CurrentPowerEvents.Count -ge $SearchLimit) {
-                $PowerFiltersMayHaveMoreEvents = $true
-            }
-        }
-
-        ForEach ($Event in $PowerEvents) {
-            Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-PowerUserActivity -Event $Event)
-        }
-
-        $OutputEvents = @(Get-UniqueUserLogonActivity -ActivityEvents $ActivityEvents | Sort-Object -Property TimeCreated -Descending | Select-Object -First $ActivityLimit)
-
-        If ($OutputEvents.Count -ge $ActivityLimit -or (($WinlogonEvents.Count -lt $SearchLimit) -and ($SecurityEvents.Count -lt $SearchLimit) -and ($UnlockAuthEvents.Count -lt $SearchLimit) -and ($TerminalServicesEvents.Count -lt $SearchLimit) -and -not $PowerFiltersMayHaveMoreEvents) -or $SearchLimit -ge $MaxSearchLimit) {
-            Break
-        }
-
-        $SearchLimit = [Math]::Min(($SearchLimit * 2), $MaxSearchLimit)
-    } While ($true)
-
-    Write-UserLogonActivityOutput -ActivityEvents $OutputEvents
+Catch {
+    Write-Error $_.Exception.Message
+    Exit 1
 }
+
+If ($EndDateTime -le $StartDateTime) {
+    Write-Error "-End must be later than -Start."
+    Exit 1
+}
+
+$WinlogonFilter.StartTime = $StartDateTime.LocalDateTime
+$WinlogonFilter.EndTime = $EndDateTime.LocalDateTime
+$SecurityFilter.StartTime = $StartDateTime.LocalDateTime
+$SecurityFilter.EndTime = $EndDateTime.LocalDateTime
+$UnlockAuthFilter.StartTime = $StartDateTime.LocalDateTime
+$UnlockAuthFilter.EndTime = $EndDateTime.LocalDateTime
+$TerminalServicesFilter.StartTime = $StartDateTime.LocalDateTime
+$TerminalServicesFilter.EndTime = $EndDateTime.LocalDateTime
+ForEach ($PowerFilter in $PowerFilters) {
+    $PowerFilter.StartTime = $StartDateTime.LocalDateTime
+    $PowerFilter.EndTime = $EndDateTime.LocalDateTime
+}
+
+$ActivityEvents = New-Object System.Collections.Generic.List[object]
+
+ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $WinlogonFilter -LogDescription 'System Winlogon event log')) {
+    Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-WinlogonUserActivity -Event $Event)
+}
+
+ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $SecurityFilter -LogDescription 'Security event log')) {
+    Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-SecurityUserActivity -Event $Event)
+}
+
+ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $UnlockAuthFilter -LogDescription 'Security unlock-authentication event log')) {
+    Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-SecurityUserActivity -Event $Event)
+}
+
+ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $TerminalServicesFilter -LogDescription 'Terminal Services Local Session Manager event log')) {
+    Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-TerminalServicesUserActivity -Event $Event)
+}
+
+ForEach ($PowerFilter in $PowerFilters) {
+    ForEach ($Event in (Get-UserLogonActivityWinEvent -FilterHashtable $PowerFilter -LogDescription 'System power event log')) {
+        Add-UserLogonActivityRecord -ActivityEvents $ActivityEvents -ActivityEvent (ConvertTo-PowerUserActivity -Event $Event)
+    }
+}
+
+$OutputEvents = @(Get-UniqueUserLogonActivity -ActivityEvents $ActivityEvents | Sort-Object -Property TimeCreated)
+Write-UserLogonActivityOutput -ActivityEvents $OutputEvents
+Write-PossibleUseWindowOutput -ActivityEvents $OutputEvents
Author	SHA1	Message	Date
dyoder	cf40e50c30	behavioral changes	2026-07-08 11:36:27 -04:00
dyoder	ac85a06003	add usage window	2026-07-08 11:27:51 -04:00