Defender for Endpoint Health Report

1#Requires -Version 7.02<#3.SYNOPSIS4    Fleet-wide Microsoft Defender health and exclusion audit.5 6.DESCRIPTION7    Read-only. Queries each endpoint for the protection state that actually8    matters rather than trusting the console's enrolment count.9 10.EXAMPLE11    .\Get-DefenderHealth.ps1 -ComputerName (Get-ADComputer -Filter *).Name12#>13[CmdletBinding()]14param(15    [Parameter(Mandatory, ValueFromPipeline)]16    [string[]] $ComputerName,17 18    [int]    $MaxSignatureAgeDays = 3,19    [int]    $MaxScanAgeDays      = 7,20    [int]    $ThrottleLimit       = 32,21    [string] $OutputPath          = ".\defender-health"22)23 24begin { $targets = New-Object System.Collections.Generic.List[string] }25process { $targets.AddRange($ComputerName) }26 27end {28    New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null29    Write-Host "Querying $($targets.Count) endpoints..." -ForegroundColor Cyan30 31    $results = $targets | ForEach-Object -ThrottleLimit $ThrottleLimit -Parallel {32        $name = $_33        $row = [ordered]@{34            ComputerName = $name; Reachable = $false; Error = ""35            AmServiceEnabled = $null; RealTimeProtection = $null36            TamperProtection = $null; BehaviorMonitor = $null37            SignatureAgeDays = $null; SignatureVersion = ""38            LastFullScan = $null; LastQuickScan = $null39            PathExclusions = 0; ProcessExclusions = 0; ExtensionExclusions = 040            RiskyExclusions = ""; EngineVersion = ""41        }42 43        try {44            $session = New-CimSession -ComputerName $name -OperationTimeoutSec 20 -ErrorAction Stop45            $status = Get-MpComputerStatus -CimSession $session -ErrorAction Stop46            $prefs  = Get-MpPreference    -CimSession $session -ErrorAction Stop47 48            $row.Reachable           = $true49            $row.AmServiceEnabled    = $status.AMServiceEnabled50            $row.RealTimeProtection  = $status.RealTimeProtectionEnabled51            $row.TamperProtection    = $status.IsTamperProtected52            $row.BehaviorMonitor     = $status.BehaviorMonitorEnabled53            $row.SignatureVersion    = $status.AntivirusSignatureVersion54            $row.EngineVersion       = $status.AMEngineVersion55            $row.SignatureAgeDays    = [math]::Round(((Get-Date) - $status.AntivirusSignatureLastUpdated).TotalDays, 1)56            $row.LastFullScan        = $status.FullScanEndTime57            $row.LastQuickScan       = $status.QuickScanEndTime58 59            $paths = @($prefs.ExclusionPath)60            $row.PathExclusions      = $paths.Count61            $row.ProcessExclusions   = @($prefs.ExclusionProcess).Count62            $row.ExtensionExclusions = @($prefs.ExclusionExtension).Count63 64            # An exclusion this broad is an uninstall wearing a hat65            $risky = $paths | Where-Object {66                $_ -match '^[A-Za-z]:\\?$' -or67                $_ -match '^[A-Za-z]:\\(Users|Windows|Program Files.*|ProgramData)\\?$' -or68                $_ -match '\*'69            }70            $row.RiskyExclusions = ($risky -join "; ")71 72            Remove-CimSession $session73        }74        catch { $row.Error = $_.Exception.Message }75 76        [pscustomobject] $row77    }78 79    $results | Export-Csv (Join-Path $OutputPath "defender-health.csv") -NoTypeInformation -Encoding UTF880 81    # ── Findings ─────────────────────────────────────────────────────────82    $findings = New-Object System.Collections.Generic.List[object]83    function Add-Finding {84        param($Computer, $Severity, $Message)85        $findings.Add([pscustomobject]@{ ComputerName = $Computer; Severity = $Severity; Finding = $Message })86    }87 88    foreach ($r in $results) {89        if (-not $r.Reachable) { Add-Finding $r.ComputerName "Medium" "Unreachable: $($r.Error)"; continue }90 91        if (-not $r.AmServiceEnabled)   { Add-Finding $r.ComputerName "Critical" "Defender service is not running" }92        if (-not $r.RealTimeProtection) { Add-Finding $r.ComputerName "Critical" "Real-time protection is OFF" }93        if (-not $r.TamperProtection)   { Add-Finding $r.ComputerName "High"     "Tamper protection is OFF" }94        if (-not $r.BehaviorMonitor)    { Add-Finding $r.ComputerName "High"     "Behaviour monitoring is OFF" }95        if ($r.RiskyExclusions)         { Add-Finding $r.ComputerName "Critical" "Overly broad exclusion: $($r.RiskyExclusions)" }96 97        if ($r.SignatureAgeDays -gt $MaxSignatureAgeDays) {98            Add-Finding $r.ComputerName "High" "Signatures are $($r.SignatureAgeDays) days old"99        }100        if ($r.PathExclusions -gt 25) {101            Add-Finding $r.ComputerName "Medium" "$($r.PathExclusions) path exclusions - review for sprawl"102        }103 104        $lastScan = @($r.LastFullScan, $r.LastQuickScan) | Where-Object { $_ } | Sort-Object -Descending | Select-Object -First 1105        if (-not $lastScan) {106            Add-Finding $r.ComputerName "High" "No scan has ever completed"107        }108        elseif (((Get-Date) - $lastScan).TotalDays -gt $MaxScanAgeDays) {109            Add-Finding $r.ComputerName "Medium" "Last scan was $([int]((Get-Date) - $lastScan).TotalDays) days ago"110        }111    }112 113    $order = @{ Critical = 0; High = 1; Medium = 2 }114    $findings | Sort-Object { $order[$_.Severity] }, ComputerName |115        Export-Csv (Join-Path $OutputPath "findings.csv") -NoTypeInformation -Encoding UTF8116 117    $reachable = ($results | Where-Object Reachable).Count118    Write-Host ""119    Write-Host "$reachable of $($targets.Count) endpoints responded." -ForegroundColor Green120    $findings | Group-Object Severity | Sort-Object { $order[$_.Name] } | ForEach-Object {121        $colour = switch ($_.Name) { "Critical" { "Red" } "High" { "Yellow" } default { "Gray" } }122        Write-Host "  $($_.Name): $($_.Count)" -ForegroundColor $colour123    }124}