Defender for Endpoint status report with Microsoft Graph PowerShell

When monitoring the status of your Defender for Endpoint agent, you may need to periodically view the overall state of all your devices. Likewise, you may generally need quick access to this report data to evaluate compliance, while you may not yet be ready to implement device compliance restrictions with your Conditional Access policies. 

You can log in to the Intune Portal and select Reports > Microsoft Defender Antivirus and generate a status report, however, you may want the reports to be automatically exported or sent to you via email programmatically and without having to log in to the web portal.

In this article, I will show you how to use Microsoft Graph PowerShell to generate a Defender for Endpoint status report and export it to your device.

Requirements

To run this script, you need to ensure you meet the following requirements:

  • You need to have the latest version of Microsoft Graph PowerShell installed.
  • You need access to a Global Administrator to consent to the DeviceManagementConfiguration.Read.All Graph API permission.

The script will also export the report data to your local system, you will need to ensure your user account has access to the local where the report will be saved.

View reports from the portal

The Defender for Endpoint agent status information can also be accessed from the Intune admin portal. It might me useful to correlate the information you export with PowerShell to the information in the portal to ensure you are exporting the correct data. To view and export this data from the Intune admin portal, follow the below steps:

1. Log in to intune.microsoft.com

2. Select Reports > Microsoft Defender Antivirus.

3. Select the Reports tab, then Antivirus agent status.

The report can then be exported by selecting the Export button.

Defender for Endpoint agent status report
Defender for Endpoint agent status report

Generating the Defender For Endpoint status report with PowerShell

The official documentation for using the APIs to export reports using Microsoft Graph is here. What it doesn’t show you is how to build a programmatic solution around this information.

The below script will first initialise the report request, then loop through checking for the report to complete processing. Once complete, it will export the report files to your defined location. On line 2, ensure you change the output path to your desired location.

#Define the output path
$OutputPath = "C:\temp\report.zip"

#Connect to Microsoft Graph
Connect-MgGraph -Scopes DeviceManagementConfiguration.Read.All

#Define body of request, including the report name
$body = @'
{
  "filter": "",
  "format": "csv",
  "select": [
    "DeviceName",
    "_ManagedBy",
    "IsWDATPSenseRunning",
    "WDATPOnboardingState",
    "LastReportedDateTime",
    "UPN",
    "DeviceId"
  ],
  "skip": 0,
  "top": 0,
  "search": "",
  "reportName": "DefenderAgents"
}
'@

#Initiate report processing
$response = Invoke-MgGraphRequest -Method POST -uri "/beta/deviceManagement/reports/exportJobs" -Body $body

$uri = "/beta/deviceManagement/reports/exportJobs('" + "$($response.id)" + "')"

#Loop until report processing is complete
Do {
    $response2 = Invoke-MgGraphRequest -Method GET -Uri $uri
    write-host "processing report..."
    Start-Sleep -Seconds 1
} until ($null -ne $response2.url)

#Export report
Write-host "Exporting report to" $OutputPath
Invoke-MgGraphRequest -Method GET -Uri $response2.url -OutputFilePath $OutputPath

Daniel Bradley

My name is Daniel Bradley and I work with Microsoft 365 and Azure as an Engineer and Consultant. I enjoy writing technical content for you and engaging with the community. All opinions are my own.

Leave a Reply