tests/Test-Assessment.41055.ps1
|
<#
.SYNOPSIS Real-time, behavioral, and heuristic protection are enabled on Microsoft Defender Antivirus. .DESCRIPTION Evaluates the pinned Microsoft Defender Antivirus Secure Score controls by joining control profiles to the latest Microsoft Secure Score snapshot and comparing each achieved score with its maximum score. Controls with missing profiles, controls without applicable devices, and ignored controls are excluded from the roll-up. .NOTES Test ID: 41055 Workshop Task ID: SECOPS-055 Category: Endpoint threat protection Pillar: SecOps Required Module: Microsoft.Graph.Authentication Required Connection: Microsoft Graph #> function Test-Assessment-41055 { [ZtTest( Category = 'Endpoint threat protection', CompatibleLicense = ('WINDEFATP', 'MDE_LITE'), ImplementationCost = 'Low', Pillar = 'SecOps', RiskLevel = 'High', Service = ('Graph'), SfiPillar = 'Monitor and detect cyberthreats', TenantType = ('Workforce'), TestId = 41055, Title = 'Real-time, behavioral, and heuristic protection are enabled on Microsoft Defender Antivirus', UserImpact = 'Low' )] [CmdletBinding()] param() #region Data Collection Write-PSFMessage '🟦 Start' -Tag Test -Level VeryVerbose $activity = 'Checking Microsoft Defender Antivirus protection controls in Microsoft Secure Score' $defenderAntivirusControlIds = @( 'scid_2012', 'scid_91', 'scid_92', 'scid_89', 'scid_90', 'scid_5093', 'scid_6093' ) $controlProfileError = $null $secureScoreError = $null # Q1: Read MDATP Secure Score control profiles, then intersect client-side with pinned IDs. Write-ZtProgress -Activity $activity -Status 'Getting MDATP Secure Score control profiles' $mdatpControlProfiles = @() try { $controlProfileFilter = "service eq 'MDATP' and (id eq 'scid_2012' or id eq 'scid_91' or id eq 'scid_92' or id eq 'scid_89' or id eq 'scid_90' or id eq 'scid_5093' or id eq 'scid_6093')" $mdatpControlProfiles = @(Invoke-ZtGraphRequest -RelativeUri 'security/secureScoreControlProfiles' -Filter $controlProfileFilter -ApiVersion beta -ErrorAction Stop) } catch { $controlProfileError = $_ Write-PSFMessage "Failed to retrieve MDATP Secure Score control profiles: $_" -Tag Test -Level Warning } # Q2: Read the latest Secure Score snapshot; -DisablePaging returns the wrapper object. Write-ZtProgress -Activity $activity -Status 'Getting latest Secure Score snapshot' $latestSecureScore = $null try { $secureScoresResponse = Invoke-ZtGraphRequest -RelativeUri 'security/secureScores' -Top 1 -ApiVersion beta -DisablePaging -ErrorAction Stop $secureScores = @($secureScoresResponse.value) if ($secureScores.Count -gt 0) { $latestSecureScore = $secureScores[0] } } catch { $secureScoreError = $_ Write-PSFMessage "Failed to retrieve latest Secure Score snapshot: $_" -Tag Test -Level Warning } #endregion Data Collection #region Assessment Logic $passed = $false $customStatus = $null foreach ($queryError in @($controlProfileError, $secureScoreError) | Where-Object { $null -ne $_ }) { if ((Get-ZtHttpStatusCode -ErrorRecord $queryError) -in (401, 403)) { $params = @{ TestId = '41055' Title = 'Real-time, behavioral, and heuristic protection are enabled on Microsoft Defender Antivirus' Status = $false Result = '⚠️ Microsoft Graph returned HTTP 401 or 403. Verify SecurityEvents.Read.All is granted, Secure Score data is flowing, and at least one MDE device is onboarded.' CustomStatus = 'Investigate' } Add-ZtTestResultDetail @params return } } $controlProfileById = @{} foreach ($controlProfile in @($mdatpControlProfiles | Where-Object { $defenderAntivirusControlIds -contains $_.id })) { if ($null -ne $controlProfile.id -and -not $controlProfileById.ContainsKey($controlProfile.id)) { $controlProfileById[$controlProfile.id] = $controlProfile } } if ($controlProfileError -or $secureScoreError -or $null -eq $latestSecureScore) { $params = @{ TestId = '41055' Title = 'Real-time, behavioral, and heuristic protection are enabled on Microsoft Defender Antivirus' Status = $false Result = '⚠️ No Microsoft Defender Antivirus Secure Score control could be evaluated; verify SecurityEvents.Read.All is granted, Secure Score data is flowing, and at least one MDE device is onboarded.' CustomStatus = 'Investigate' } Add-ZtTestResultDetail @params return } $controlScoreByName = @{} foreach ($controlScore in @($latestSecureScore.controlScores)) { if ($null -ne $controlScore.controlName -and -not $controlScoreByName.ContainsKey($controlScore.controlName)) { $controlScoreByName[$controlScore.controlName] = $controlScore } } $evaluationResults = @() foreach ($controlId in $defenderAntivirusControlIds) { $controlProfile = if ($controlProfileById.ContainsKey($controlId)) { $controlProfileById[$controlId] } else { $null } $matchingScore = if ($controlScoreByName.ContainsKey($controlId)) { $controlScoreByName[$controlId] } else { $null } $latestStateUpdate = @() if ($null -ne $controlProfile) { $latestStateUpdate = @($controlProfile.controlStateUpdates | Sort-Object { if ($_.updatedDateTime) { [datetime]$_.updatedDateTime } else { [datetime]::MinValue } } -Descending | Select-Object -First 1) } $controlState = if ($latestStateUpdate.Count -gt 0 -and -not [string]::IsNullOrWhiteSpace($latestStateUpdate[0].state)) { $latestStateUpdate[0].state } else { 'N/A' } $isIgnored = $latestStateUpdate.Count -gt 0 -and $latestStateUpdate[0].state -eq 'ignored' $score = if ($null -ne $matchingScore -and $null -ne $matchingScore.score) { $matchingScore.score } else { $null } $maxScore = if ($null -ne $controlProfile -and $null -ne $controlProfile.maxScore) { $controlProfile.maxScore } else { $null } $scoreValue = $null $scoreIsNumeric = $false if ($null -ne $score) { try { $scoreValue = [double]$score $scoreIsNumeric = $true } catch { } } $maxScoreValue = $null $maxScoreIsNumeric = $false if ($null -ne $maxScore) { try { $maxScoreValue = [double]$maxScore $maxScoreIsNumeric = $true } catch { } } $statusReason = $null $status = if ($null -eq $controlProfile) { $statusReason = 'profile not found' 'N/A' } elseif ($null -eq $matchingScore) { $statusReason = 'no applicable devices' 'N/A' } elseif ($isIgnored) { 'Skipped' } elseif (-not $scoreIsNumeric -or -not $maxScoreIsNumeric) { 'Investigate' } elseif ($scoreValue -ge $maxScoreValue) { 'Pass' } else { 'Fail' } $controlTitle = if ($null -ne $controlProfile -and -not [string]::IsNullOrWhiteSpace($controlProfile.title)) { $controlProfile.title } else { $controlId } $evaluationResults += [PSCustomObject]@{ ControlId = $controlId ControlTitle = $controlTitle ActionUrl = if ($null -ne $controlProfile) { $controlProfile.actionUrl } else { $null } Score = if ($null -ne $score) { $score } else { 'N/A' } MaxScore = if ($null -ne $maxScore) { $maxScore } else { 'N/A' } ImplementationStatus = if ($null -ne $matchingScore -and -not [string]::IsNullOrWhiteSpace($matchingScore.implementationStatus)) { $matchingScore.implementationStatus } else { 'N/A' } State = $controlState LastModifiedDateTime = if ($null -ne $controlProfile) { $controlProfile.lastModifiedDateTime } else { $null } Status = $status StatusReason = $statusReason } } $failedItems = @($evaluationResults | Where-Object Status -eq 'Fail') $investigateItems = @($evaluationResults | Where-Object Status -eq 'Investigate') $passedItems = @($evaluationResults | Where-Object Status -eq 'Pass') if ($failedItems.Count -gt 0) { $testResultMarkdown = "❌ One or more of real-time, behavioral, or heuristic scanning is disabled.`n`n%TestResult%" } elseif ($investigateItems.Count -gt 0) { $customStatus = 'Investigate' $testResultMarkdown = "⚠️ One or more Microsoft Defender Antivirus Secure Score controls could not be evaluated.`n`n%TestResult%" } elseif ($passedItems.Count -gt 0) { $passed = $true $testResultMarkdown = "✅ Real-time, behavioral, and heuristic protection on Microsoft Defender Antivirus are enabled.`n`n%TestResult%" } else { $customStatus = 'Investigate' $testResultMarkdown = "⚠️ No Microsoft Defender Antivirus Secure Score control could be evaluated; verify SecurityEvents.Read.All is granted, Secure Score data is flowing, and at least one MDE device is onboarded.`n`n%TestResult%" } #endregion Assessment Logic #region Report Generation $totalCount = $evaluationResults.Count $countLine = "Total pinned Microsoft Defender Antivirus controls: $totalCount" $secureScoreLink = '[Microsoft Secure Score](https://security.microsoft.com/securescore)' $tableRows = '' foreach ($result in $evaluationResults) { $statusDisplay = switch ($result.Status) { 'Pass' { '✅ Pass' } 'Fail' { '❌ Fail' } 'Investigate' { '⚠️ Investigate' } 'N/A' { "N/A ($($result.StatusReason))" } default { 'Skipped' } } $lastModified = if ($result.LastModifiedDateTime) { Get-FormattedDate -DateString $result.LastModifiedDateTime } else { 'N/A' } $safeControlTitle = Get-SafeMarkdown -Text $result.ControlTitle $controlDisplay = if (-not [string]::IsNullOrWhiteSpace($result.ActionUrl)) { "[$safeControlTitle]($($result.ActionUrl)) ($($result.ControlId))" } elseif ($result.ControlTitle -ne $result.ControlId) { "$safeControlTitle ($($result.ControlId))" } else { $safeControlTitle } $tableRows += "| $controlDisplay | $($result.Score) | $($result.MaxScore) | $($result.ImplementationStatus) | $($result.State) | $lastModified | $statusDisplay |`n" } $controlTable = @" | Control title (id) | Score | Max score | Implementation status | State | Last modified | Status | | :----------------- | ----: | --------: | :-------------------- | :---- | :------------ | :----- | $tableRows "@ $formatTemplate = @' {0} {1} {2} '@ $mdInfo = $formatTemplate -f $countLine, $secureScoreLink, $controlTable $testResultMarkdown = $testResultMarkdown -replace '%TestResult%', $mdInfo #endregion Report Generation $params = @{ TestId = '41055' Title = 'Real-time, behavioral, and heuristic protection are enabled on Microsoft Defender Antivirus' Status = $passed Result = $testResultMarkdown } if ($customStatus) { $params.CustomStatus = $customStatus } Add-ZtTestResultDetail @params } |