Public/Invoke-NSPM365AuditTriage.ps1
|
function Invoke-NSPM365AuditTriage { <# .SYNOPSIS Triages a Unified Audit Log export for a suspected mailbox compromise and writes a severity-sorted Findings.csv with a timeline, IP table, sign-ins, mail read and inbox rules. .DESCRIPTION Reads one or more Purview audit CSV exports (Audit > Search > Export) and writes to -OutputPath: Findings.csv severity-sorted, the same columns as Invoke-NSPM365IocHunt's Timeline.csv every record, oldest first, with client IP, trust, country, ISP and the raw AuditData IPs.csv one row per client IP: trust, count, users, operations, geolocation and ASN Summary.csv one row per operation: count, untrusted count, first and last time SignIns.csv UserLoggedIn and UserLoginFailed in one timeline, with user agent and logon error AccessedMail.csv MailItemsAccessed, one row per message read (Get-NSPM365AccessedMessage) InboxRules.csv inbox rule and forwarding changes, flagged (Get-NSPM365InboxRuleAudit) An address is trusted when it matches -TrustedIP or its ASN is in -TrustedAsn; every other address is untrusted. Records with no client IP are not attributed either way. Microsoft's ASN (8075) is never trusted on its own, because attackers run from Azure too; it is only exempt from the hosting-provider finding. Pass -TrustedAsn 8075 to trust it. Findings: Critical a suspicious inbox rule or forwarding change from an untrusted address High a suspicious inbox rule from anywhere; a successful sign-in from a hosting, proxy or VPN address or from outside -ExpectedCountry; a mailbox folder synced (downloaded) from an untrusted address; an app consent from an untrusted address Medium app consents; messages read, sent or hard-deleted from an untrusted address; any activity from a hosting/proxy address or outside -ExpectedCountry; rule changes from an untrusted address Low soft deletes from an untrusted address; failed sign-ins from hosting/proxy addresses Untrusted activity is grouped per user and address, so one attacker session is one finding. Client IPs are looked up on ip-api.com (Resolve-NSPIpInfo) unless -SkipIpLookup: plain HTTP, non-commercial licence. Without the lookup the hosting and country findings are skipped. .PARAMETER Path One or more Purview audit CSV exports. .PARAMETER TrustedIP Known-good addresses (office egress, the user's home ISP): exact, CIDR, or a prefix ending in '*'. .PARAMETER TrustedAsn Known-good ASNs ('7018' or 'AS7018'), e.g. the user's home ISP or mobile carrier. .PARAMETER ExpectedCountry Two-letter country codes the users sign in from (US). Activity elsewhere is a finding. .PARAMETER InternalDomain The tenant's own domains, so internal forwarding isn't flagged. .PARAMETER OutputPath Report folder. Defaults to .\AuditTriage_<timestamp>. .PARAMETER SkipIpLookup Don't send the client IPs to ip-api.com. .PARAMETER StartTime Inclusive start, with an explicit offset or Z. Normalized to UTC. .PARAMETER EndTime Exclusive end, with an explicit offset or Z. Normalized to UTC. .PARAMETER Deduplicate Remove exact repeated record IDs and payloads. Conflicting records and missing IDs are retained. .PARAMETER PassThru Also return the findings. .EXAMPLE Invoke-NSPM365AuditTriage -Path .\audit.csv -TrustedIP 198.51.100.10 -ExpectedCountry US -InternalDomain contoso.com .EXAMPLE Invoke-NSPM365AuditTriage -Path .\jdoe-1.csv, .\jdoe-2.csv -TrustedIP 198.51.100.0/24 -TrustedAsn 7018, 22394 -OutputPath .\jdoe-triage .NOTES Export with every operation for the user (no operation filter) and a window starting well before the suspected compromise. MailItemsAccessed needs audit logging enabled for the mailbox; E3 tenants have it since 2024. #> [CmdletBinding()] param( [Parameter(Mandatory, Position = 0)] [string[]]$Path, [string[]]$TrustedIP = @(), [string[]]$TrustedAsn = @(), [string[]]$ExpectedCountry = @(), [string[]]$InternalDomain = @(), [string]$OutputPath, [datetimeoffset]$StartTime, [datetimeoffset]$EndTime, [switch]$Deduplicate, [switch]$SkipIpLookup, [switch]$PassThru ) $ErrorActionPreference = 'Stop' if ($PSBoundParameters.ContainsKey('StartTime') -and $PSBoundParameters.ContainsKey('EndTime') -and $StartTime -ge $EndTime) { throw 'StartTime must precede EndTime.' } # Validate trust configuration even when the export contains no matching address. foreach ($range in $TrustedIP) { $null = Test-NSPIpInRange -Ip '192.0.2.1' -Range @($range) } $inputData = Read-NSPTriageInput -Path $Path -Deduplicate:$Deduplicate $hasStart = $PSBoundParameters.ContainsKey('StartTime') $hasEnd = $PSBoundParameters.ContainsKey('EndTime') $records = @($inputData.Records | Where-Object { $rawTime = if ($_.AuditData.CreationTime) { $_.AuditData.CreationTime } else { $_.CreationDate } $utc = ConvertTo-NSPHuntUtc $rawTime (-not $hasStart -or $utc -ge $StartTime.UtcDateTime) -and (-not $hasEnd -or $utc -lt $EndTime.UtcDateTime) }) if (-not $OutputPath) { $OutputPath = Join-Path (Get-Location).ProviderPath ('AuditTriage_{0}' -f (Get-Date -Format 'yyyyMMdd_HHmmss')) } $OutputPath = New-NSPInvestigationOutput -Path $OutputPath $runManifest = [ordered]@{ SchemaVersion = 1; Status = 'InProgress'; StartedUtc = [datetime]::UtcNow.ToString('o') ModuleVersion = (Get-Module NSP.M365.Investigation).Version.ToString() LogParseVersion = (Get-Module NSP.LogParse).Version.ToString() Inputs = $inputData.Inputs; InputRecords = ($inputData.Inputs | Measure-Object -Property Rows -Sum).Sum SelectedRecords = $records.Count; ExcludedByWindow = @($inputData.Records).Count - $records.Count StartUtc = if ($PSBoundParameters.ContainsKey('StartTime')) { $StartTime.UtcDateTime.ToString('o') } else { $null } EndUtcExclusive = if ($PSBoundParameters.ContainsKey('EndTime')) { $EndTime.UtcDateTime.ToString('o') } else { $null } Deduplicate = [bool]$Deduplicate; DuplicateRecords = $inputData.DuplicateRecords ConflictingRecords = $inputData.ConflictingRecords; SkipIpLookup = [bool]$SkipIpLookup TrustParameters = @{ TrustedIP=$TrustedIP; TrustedAsn=$TrustedAsn; ExpectedCountry=$ExpectedCountry; InternalDomain=$InternalDomain } Coverage = 'Observed event bounds only; missing events and completeness are not established.' } Save-NSPInvestigationJson -Path (Join-Path $OutputPath 'RunManifest.json') -Data $runManifest if ($inputData.ConflictingRecords) { Write-Warning 'Conflicting payloads share a record ID. All conflicting variants were retained.' } $label = @($Path | ForEach-Object { [IO.Path]::GetFileNameWithoutExtension($_) }) -join '+' $hunt = @{ TenantLabel = $label; Findings = New-Object System.Collections.Generic.List[object] } $views = @(foreach ($record in $records) { ConvertTo-NSPAuditView $record }) $span = if ($views.Count) { "$($views[0].TimeUtc) -> $($views[-1].TimeUtc)" } else { 'no records' } Write-Host "Audit triage: $($views.Count) record(s) from $(@($Path).Count) file(s), $span. Output: $OutputPath" -ForegroundColor Cyan if (-not $TrustedIP -and -not $TrustedAsn) { Write-Warning 'No -TrustedIP or -TrustedAsn: every address counts as untrusted, so expect noise.' } if ($ExpectedCountry -and $SkipIpLookup) { Write-Warning '-ExpectedCountry needs the IP lookup; it is ignored with -SkipIpLookup.' } # Per-address facts, computed once. $ips = @($views | ForEach-Object ClientIP | Where-Object { $_ } | Sort-Object -Unique) $info = @{} if (-not $SkipIpLookup -and $ips.Count) { Write-Host "Looking up $($ips.Count) address(es) on ip-api.com..." -ForegroundColor DarkGray foreach ($result in (Resolve-NSPIpInfo -IPAddress $ips)) { $info[$result.IP] = $result } } $asns = @($TrustedAsn | ForEach-Object { ([string]$_) -replace '^(?i)AS', '' }) $countries = @($ExpectedCountry | ForEach-Object { $_.ToUpperInvariant() }) $trust = @{ '' = '' } $risky = @{} $foreign = @{} foreach ($ip in $ips) { $i = $info[$ip] $trusted = (Test-NSPIpInRange -Ip $ip -Range $TrustedIP) -or ($i -and $i.Asn -and $asns -contains $i.Asn) $trust[$ip] = if ($trusted) { 'Trusted' } else { 'Untrusted' } $risky[$ip] = [bool]($i -and ($i.Hosting -or $i.Proxy) -and $i.Asn -ne $script:NSPMicrosoftAsn) $foreign[$ip] = [bool]($i -and $countries.Count -and $i.CountryCode -and $countries -notcontains $i.CountryCode) } $where = { param($ip) $i = $info[$ip] if (-not $i -or $i.Status -ne 'success') { return $ip } "$ip ($(@($i.City, $i.CountryCode, $i.Isp, $(if ($i.Asn) { "AS$($i.Asn)" }) | Where-Object { $_ }) -join ', '))" } $untrusted = { param($ip) $ip -and $trust[$ip] -eq 'Untrusted' } $geoColumns = { param($ip) $i = $info[$ip] [ordered]@{ CountryCode = if ($i) { $i.CountryCode } else { '' }; City = if ($i) { $i.City } else { '' }; Isp = if ($i) { $i.Isp } else { '' }; Asn = if ($i) { $i.Asn } else { '' }; Hosting = if ($i) { $i.Hosting } else { '' }; Proxy = if ($i) { $i.Proxy } else { '' } } } $write = { param($Rows, $Name) @($Rows) | Export-Csv -LiteralPath (Join-Path $OutputPath $Name) -NoTypeInformation -Encoding UTF8 } # One finding per user and address for untrusted activity of one kind. $grouped = { param($Rows, $Severity, $Check, $What) foreach ($g in ($Rows | Group-Object UserId, ClientIP)) { $first = $g.Group[0] $times = @($g.Group | ForEach-Object TimeUtc | Sort-Object) Add-NSPHuntFinding -Hunt $hunt -Severity $Severity -Check $Check -Object $first.UserId -Time $times[0] ` -Detail ("{0} {1} from {2}, {3} -> {4}." -f $g.Count, $What, (& $where $first.ClientIP), $times[0], $times[-1]) } } # Timeline, IPs, Summary. & $write @(foreach ($v in $views) { $row = [ordered]@{ TimeUtc = $v.TimeUtc; Operation = $v.Operation; Workload = $v.Workload; UserId = $v.UserId; ClientIP = $v.ClientIP; Trust = $trust[$v.ClientIP] } $geo = & $geoColumns $v.ClientIP foreach ($key in 'CountryCode', 'Isp', 'Asn') { $row[$key] = $geo[$key] } $row.ResultStatus = $v.ResultStatus $row.RecordId = $v.RecordId $row.SourceFile = $v.Record.SourceFile $row.SourceRow = $v.Record.SourceRow $row.AuditData = if ($v.Record.PSObject.Properties['_Raw'] -and $v.Record._Raw.AuditData) { [string]$v.Record._Raw.AuditData } else { ConvertTo-Json -InputObject $v.Record.AuditData -Depth 10 -Compress } [pscustomobject]$row }) 'Timeline.csv' $ipRows = @(foreach ($g in ($views | Where-Object ClientIP | Group-Object ClientIP)) { $i = $info[$g.Name] $times = @($g.Group | ForEach-Object TimeUtc | Sort-Object) [pscustomobject]@{ ClientIP = $g.Name Trust = $trust[$g.Name] Count = $g.Count FirstUtc = $times[0] LastUtc = $times[-1] Users = @($g.Group | ForEach-Object UserId | Sort-Object -Unique) -join '; ' Operations = @($g.Group | ForEach-Object Operation | Sort-Object -Unique) -join '; ' CountryCode = if ($i) { $i.CountryCode } else { '' } Country = if ($i) { $i.Country } else { '' } Region = if ($i) { $i.Region } else { '' } City = if ($i) { $i.City } else { '' } Isp = if ($i) { $i.Isp } else { '' } Org = if ($i) { $i.Org } else { '' } Asn = if ($i) { $i.Asn } else { '' } AsName = if ($i) { $i.AsName } else { '' } Hosting = if ($i) { $i.Hosting } else { '' } Proxy = if ($i) { $i.Proxy } else { '' } Mobile = if ($i) { $i.Mobile } else { '' } } }) & $write @($ipRows | Sort-Object @{ Expression = { $_.Trust -eq 'Trusted' } }, @{ Expression = 'Count'; Descending = $true }) 'IPs.csv' & $write @(foreach ($g in ($views | Group-Object Operation | Sort-Object Count -Descending)) { $times = @($g.Group | ForEach-Object TimeUtc | Sort-Object) $bad = @($g.Group | Where-Object { & $untrusted $_.ClientIP }) [pscustomobject]@{ Operation = $g.Name Count = $g.Count UntrustedCount = $bad.Count FirstUtc = $times[0] LastUtc = $times[-1] Users = @($g.Group | ForEach-Object UserId | Sort-Object -Unique) -join '; ' UntrustedIPs = @($bad | ForEach-Object ClientIP | Sort-Object -Unique) -join '; ' } }) 'Summary.csv' # Sign-ins. $signIns = @(foreach ($v in ($views | Where-Object { $_.Operation -in 'UserLoggedIn', 'UserLoginFailed' })) { $audit = $v.Record.AuditData $extended = if ($audit.PSObject.Properties['ExtendedProperties']) { $audit.ExtendedProperties } else { @() } $row = [ordered]@{ TimeUtc = $v.TimeUtc; Operation = $v.Operation; UserId = $v.UserId; ClientIP = $v.ClientIP; Trust = $trust[$v.ClientIP] } $geo = & $geoColumns $v.ClientIP foreach ($key in $geo.Keys) { $row[$key] = $geo[$key] } $row.ResultStatus = $v.ResultStatus $row.LogonError = if ($audit.PSObject.Properties['LogonError']) { [string]$audit.LogonError } else { '' } $row.ErrorNumber = if ($audit.PSObject.Properties['ErrorNumber']) { [string]$audit.ErrorNumber } else { '' } $row.UserAgent = [string](Get-NSPAuditNameValue $extended 'UserAgent') $row.RequestType = [string](Get-NSPAuditNameValue $extended 'RequestType') $row.ApplicationId = if ($audit.PSObject.Properties['ApplicationId']) { [string]$audit.ApplicationId } else { '' } $row.RecordId = $v.RecordId [pscustomobject]$row }) & $write $signIns 'SignIns.csv' $success = @($signIns | Where-Object { $_.Operation -eq 'UserLoggedIn' -and (& $untrusted $_.ClientIP) }) & $grouped @($success | Where-Object { $risky[$_.ClientIP] }) 'High' 'Sign-in' 'successful sign-in(s) from a hosting/proxy/VPN address' & $grouped @($success | Where-Object { -not $risky[$_.ClientIP] -and $foreign[$_.ClientIP] }) 'High' 'Sign-in' 'successful sign-in(s) from outside the expected countries' & $grouped @($signIns | Where-Object { $_.Operation -eq 'UserLoginFailed' -and (& $untrusted $_.ClientIP) -and $risky[$_.ClientIP] }) 'Low' 'Sign-in' 'failed sign-in(s) from a hosting/proxy/VPN address' # Mail read. $accessed = @(if ($records.Count) { Get-NSPM365AccessedMessage -InputObject $records | Select-Object *, @{ Name = 'Trust'; Expression = { $trust[$_.ClientIP] } } }) & $write $accessed 'AccessedMail.csv' $badAccess = @($accessed | Where-Object { & $untrusted $_.ClientIP }) & $grouped @($badAccess | Where-Object MailAccessType -EQ 'Sync') 'High' 'Mail read' 'folder sync(s) - whole folders downloaded -' & $grouped @($badAccess | Where-Object MailAccessType -NE 'Sync') 'Medium' 'Mail read' 'message(s) opened' # Inbox rules and forwarding. $rules = @(if ($records.Count) { Get-NSPM365InboxRuleAudit -InputObject $records -InternalDomain $InternalDomain | Select-Object *, @{ Name = 'Trust'; Expression = { $trust[$_.ClientIP] } } }) & $write $rules 'InboxRules.csv' foreach ($rule in $rules) { $fromBad = & $untrusted $rule.ClientIP $object = if ($rule.RuleName) { "$($rule.UserId): $($rule.RuleName)" } else { "$($rule.UserId): $($rule.Operation)" } $detail = "$($rule.Operation) from $(& $where $rule.ClientIP)" if ($rule.Flags) { $detail += ". Flags: $($rule.Flags)" } if ($rule.ForwardTo) { $detail += ". Forwards to: $($rule.ForwardTo)" } if ($rule.MoveToFolder) { $detail += ". Moves to: $($rule.MoveToFolder)" } if ($rule.Suspicious) { Add-NSPHuntFinding -Hunt $hunt -Severity $(if ($fromBad) { 'Critical' } else { 'High' }) -Check 'Inbox rule' -Object $object -Detail $detail -Time $rule.TimeUtc } elseif ($fromBad -and $rule.Operation -notin 'Remove-InboxRule', 'Disable-InboxRule') { Add-NSPHuntFinding -Hunt $hunt -Severity Medium -Check 'Inbox rule' -Object $object -Detail "$detail. Not flagged, but changed from an untrusted address." -Time $rule.TimeUtc } } # App consents, sends, deletes. foreach ($v in ($views | Where-Object { $script:NSPConsentOperations -contains $_.Operation })) { $target = if ($v.Record.AuditData.PSObject.Properties['ObjectId']) { [string]$v.Record.AuditData.ObjectId } else { '' } Add-NSPHuntFinding -Hunt $hunt -Severity $(if (& $untrusted $v.ClientIP) { 'High' } else { 'Medium' }) -Check 'App consent' -Object $v.UserId -Time $v.TimeUtc ` -Detail "$($v.Operation.TrimEnd('.')) $target from $(& $where $v.ClientIP). Check the app's permissions and publisher." } $badViews = @($views | Where-Object { & $untrusted $_.ClientIP }) & $grouped @($badViews | Where-Object { $_.Operation -in 'Send', 'SendAs', 'SendOnBehalf' }) 'Medium' 'Mail sent' 'message(s) sent' & $grouped @($badViews | Where-Object Operation -EQ 'HardDelete') 'Medium' 'Mail deleted' 'hard delete(s)' & $grouped @($badViews | Where-Object { $_.Operation -in 'SoftDelete', 'MoveToDeletedItems' }) 'Low' 'Mail deleted' 'soft delete(s) / move(s) to Deleted Items' # Activity from hosting providers or unexpected countries, per address. foreach ($row in ($ipRows | Where-Object { $_.Trust -eq 'Untrusted' -and ($risky[$_.ClientIP] -or $foreign[$_.ClientIP]) })) { $why = @($(if ($risky[$row.ClientIP]) { 'a hosting/proxy/VPN address' }), $(if ($foreign[$row.ClientIP]) { 'outside the expected countries' }) | Where-Object { $_ }) -join ', ' Add-NSPHuntFinding -Hunt $hunt -Severity Medium -Check 'Address' -Object (& $where $row.ClientIP) -Time $row.FirstUtc ` -Detail "$($row.Count) record(s) from $why, $($row.FirstUtc) -> $($row.LastUtc). Users: $($row.Users). Operations: $($row.Operations)." } $sorted = @($hunt.Findings | Sort-Object @{ Expression = { $script:NSPHuntSeverityOrder[$_.Severity] } }, TimeUtc) & $write $sorted 'Findings.csv' $runManifest.Status = 'Completed' $runManifest.CompletedUtc = [datetime]::UtcNow.ToString('o') $runManifest.FirstObservedUtc = if ($views.Count) { $views[0].TimeUtc } else { $null } $runManifest.LastObservedUtc = if ($views.Count) { $views[-1].TimeUtc } else { $null } $runManifest.Reports = @(Get-ChildItem -LiteralPath $OutputPath -Filter '*.csv' | ForEach-Object { [pscustomobject]@{ File = $_.Name; Sha256 = (Get-FileHash -LiteralPath $_.FullName -Algorithm SHA256).Hash } }) Save-NSPInvestigationJson -Path (Join-Path $OutputPath 'RunManifest.json') -Data $runManifest Write-Host '' Write-Host '=== Summary ===' -ForegroundColor Cyan [pscustomobject]@{ Records = $views.Count Addresses = $ips.Count Untrusted = @($ips | Where-Object { $trust[$_] -eq 'Untrusted' }).Count Critical = @($sorted | Where-Object Severity -EQ 'Critical').Count High = @($sorted | Where-Object Severity -EQ 'High').Count Medium = @($sorted | Where-Object Severity -EQ 'Medium').Count Low = @($sorted | Where-Object Severity -EQ 'Low').Count } | Format-Table -AutoSize | Out-Host Write-Host "Findings: $(Join-Path $OutputPath 'Findings.csv')" if ($PassThru) { $sorted } } |