Advanced Hunting using PowerShell
Applies to:
Want to experience Microsoft Defender for Endpoint? Sign up for a free trial.
Note
If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.
Tip
For better performance, you can use server closer to your geo location:
- us.api.security.microsoft.com
- eu.api.security.microsoft.com
- uk.api.security.microsoft.com
- au.api.security.microsoft.com
- swa.api.security.microsoft.com
- ina.api.security.microsoft.com
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.securitycenter.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 article
Tip
Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.
Phản hồi
https://aka.ms/ContentUserFeedback.
Sắp ra mắt: Trong năm 2024, chúng tôi sẽ dần gỡ bỏ Sự cố với GitHub dưới dạng cơ chế phản hồi cho nội dung và thay thế bằng hệ thống phản hồi mới. Để biết thêm thông tin, hãy xem:Gửi và xem ý kiến phản hồi dành cho