Skip to content

run-advanced-query-sample-powershell.md

Latest commit

 

History

History
133 lines (97 loc) · 4.13 KB

run-advanced-query-sample-powershell.md

File metadata and controls

133 lines (97 loc) · 4.13 KB

title: Advanced Hunting with PowerShell API Basics ms.reviewer: description: Learn the basics of querying the Microsoft Defender for Endpoint API, using PowerShell. ms.service: defender-endpoint ms.author: painbar author: paulinbar ms.localizationpriority: medium manager: bagol audience: ITPro ms.collection:

  • m365-security
  • tier3
  • must-keep ms.topic: reference ms.subservice: reference ms.custom: api search.appverid: met150 ms.date: 01/08/2026 appliesto:
    • Microsoft Defender for Endpoint

Advanced Hunting using PowerShell

[!INCLUDE Microsoft Defender XDR rebranding]

[!INCLUDE Microsoft Defender for Endpoint API URIs for US Government]

[!INCLUDE Improve request performance]

Run advanced queries using PowerShell. For more information, see Advanced Hunting API.

In this section, we share PowerShell samples to retrieve a token and use it to run a query.

Before you begin

You first need to create an app.

Preparation instructions

  • Open a PowerShell window.

  • If your policy doesn't allow you to run the PowerShell commands, you can run the following command:

    Set-ExecutionPolicy -ExecutionPolicy Bypass

For more information, see PowerShell documentation.

Get token

  • Run the following:
$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here
$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$body = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$response = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $body -ErrorAction Stop
$aadToken = $response.access_token

Where:

  • $tenantId: ID of the tenant on behalf of which you want to run the query (that is, the query is run on the data of this tenant)
  • $appId: ID of your Microsoft Entra app (the app must have 'Run advanced queries' permission to Defender for Endpoint)
  • $appSecret: Secret of your Microsoft Entra app

Run query

Run the following query:

$token = $aadToken
$query = 'DeviceRegistryEvents | limit 10' # Paste your own query here

$url = "https://api.security.microsoft.com/api/advancedqueries/run"
$headers = @{
    'Content-Type' = 'application/json'
    Accept = 'application/json'
    Authorization = "Bearer $aadToken"
}
$body = ConvertTo-Json -InputObject @{ 'Query' = $query }
$webResponse = Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body $body -ErrorAction Stop
$response =  $webResponse | ConvertFrom-Json
$results = $response.Results
$schema = $response.Schema
  • $results contain the results of your query
  • $schema contains the schema of the results of your query

Complex queries

If you want to run complex queries (or multilines queries), save your query in a file and, instead of the first line in the above sample, run the following command:

$query = [IO.File]::ReadAllText("C:\myQuery.txt"); # Replace with the path to your file

Work with query results

You can now use the query results.

To output the results of the query in CSV format in file file1.csv, run the following command:

$results | ConvertTo-Csv -NoTypeInformation | Set-Content C:\file1.csv

To output the results of the query in JSON format in file file1.json, run the following command:

$results | ConvertTo-Json | Set-Content file1.json

Related articles

[!INCLUDE Microsoft Defender for Endpoint Tech Community]