10 KiB
title, description, keywords, search.product, search.appverid, ms.prod, ms.mktglfcycl, ms.sitesec, ms.pagetype, ms.author, author, ms.localizationpriority, manager, audience, ms.collection, ms.topic
| title | description | keywords | search.product | search.appverid | ms.prod | ms.mktglfcycl | ms.sitesec | ms.pagetype | ms.author | author | ms.localizationpriority | manager | audience | ms.collection | ms.topic |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Pull Microsoft Defender ATP detections using REST API | Pull detections from Microsoft Defender ATP REST API. | detections, pull detections, rest api, request, response | eADQiWindows 10XVcnh | met150 | w10 | deploy | library | security | macapara | mjcaparas | medium | dansimp | ITPro | M365-security-compliance | article |
Pull Microsoft Defender ATP detections using SIEM REST API
Applies to:
Want to experience Microsoft Defender ATP? Sign up for a free trial.
Note
- Microsoft Defender ATP Alert is composed from one or more detections
- Microsoft Defender ATP Detection is composed from the suspicious event occurred on the Machine and its related Alert details.
Microsoft Defender ATP supports the OAuth 2.0 protocol to pull detections from the API.
In general, the OAuth 2.0 protocol supports four types of flows:
- Authorization grant flow
- Implicit flow
- Client credentials flow
- Resource owner flow
For more information about the OAuth specifications, see the OAuth Website.
Microsoft Defender ATP supports the Authorization grant flow and Client credential flow to obtain access to pull detections, with Azure Active Directory (AAD) as the authorization server.
The Authorization grant flow uses user credentials to get an authorization code, which is then used to obtain an access token.
The Client credential flow uses client credentials to authenticate against the Microsoft Defender ATP endpoint URL. This flow is suitable for scenarios when an OAuth client creates requests to an API that doesn't require user credentials.
Use the following method in the Microsoft Defender ATP API to pull detections in JSON format.
Note
Microsoft Defender Security Center merges similar alert detections into a single alert. This API pulls alert detections in its raw form based on the query parameters you set, enabling you to apply your own grouping and filtering.
Before you begin
-
Before calling the Microsoft Defender ATP endpoint to pull detections, you'll need to enable the SIEM integration application in Azure Active Directory (AAD). For more information, see Enable SIEM integration in Microsoft Defender ATP.
-
Take note of the following values in your Azure application registration. You need these values to configure the OAuth flow in your service or daemon app:
- Application ID (unique to your application)
- App key, or secret (unique to your application)
- Your app's OAuth 2.0 token endpoint
- Find this value by clicking View Endpoints at the bottom of the Azure Management Portal in your app's page. The endpoint will look like
https://login.microsoftonline.com/{tenantId}/oauth2/token.
- Find this value by clicking View Endpoints at the bottom of the Azure Management Portal in your app's page. The endpoint will look like
Get an access token
Before creating calls to the endpoint, you'll need to get an access token.
You'll use the access token to access the protected resource, which are detections in Microsoft Defender ATP.
To get an access token, you'll need to do a POST request to the token issuing endpoint. Here is a sample request:
POST /72f988bf-86f1-41af-91ab-2d7cd011db47/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
resource=https%3A%2F%2Fgraph.windows.net&client_id=35e0f735-5fe4-4693-9e68-3de80f1d3745&client_secret=IKXc6PxB2eoFNJ%2FIT%2Bl2JZZD9d9032VXz6Ul3D2WyUQ%3D&grant_type=client_credentials
The response will include an access token and expiry information.
{
"token_type": "Bearer",
"expires_in": "3599",
"ext_expires_in": "0",
"expires_on": "1488720683",
"not_before": "1488720683",
"resource": "https://graph.windows.net",
"access_token":"eyJ0eXaioJJOIneiowiouqSuzNiZ345FYOVkaJL0625TueyaJasjhIjEnbMlWqP..."
}
You can now use the value in the access_token field in a request to the Microsoft Defender ATP API.
Request
With an access token, your app can make authenticated requests to the Microsoft Defender ATP API. Your app must append the access token to the Authorization header of each request.
Request syntax
| Method | Request URI |
|---|---|
| GET | Use the URI applicable for your region. For EU: https://wdatp-alertexporter-eu.windows.com/api/alerts For US: https://wdatp-alertexporter-us.windows.com/api/alerts For UK: https://wdatp-alertexporter-uk.windows.com/api/alerts |
Request header
| Header | Type | Description |
|---|---|---|
| Authorization | string | Required. The Azure AD access token in the form Bearer <token>. |
Request parameters
Use optional query parameters to specify and control the amount of data returned in a response. If you call this method without parameters, the response contains all the alerts in your organization in the last 2 hours.
| Name | Value | Description |
|---|---|---|
| sinceTimeUtc | DateTime | Defines the lower time bound alerts are retrieved from, based on field: LastProcessedTimeUtc The time range will be: from sinceTimeUtc time to current time. NOTE: When not specified, all alerts generated in the last two hours are retrieved. |
| untilTimeUtc | DateTime | Defines the upper time bound alerts are retrieved. The time range will be: from sinceTimeUtc time to untilTimeUtc time. NOTE: When not specified, the default value will be the current time. |
| ago | string | Pulls alerts in the following time range: from (current_time - ago) time to current_time time. Value should be set according to ISO 8601 duration format E.g. ago=PT10M will pull alerts received in the last 10 minutes. |
| limit | int | Defines the number of alerts to be retrieved. Most recent alerts will be retrieved based on the number defined. NOTE: When not specified, all alerts available in the time range will be retrieved. |
| machinegroups | string | Specifies machine groups to pull alerts from. NOTE: When not specified, alerts from all machine groups will be retrieved. Example: https://wdatp-alertexporter-eu.securitycenter.windows.com/api/Alerts/?machinegroups=UKMachines&machinegroups=FranceMachines |
| DeviceCreatedMachineTags | string | Single machine tag from the registry. |
| CloudCreatedMachineTags | string | Machine tags that were created in Microsoft Defender Security Center. |
Request example
The following example demonstrates how to retrieve all the detections in your organization.
GET https://wdatp-alertexporter-eu.windows.com/api/alerts
Authorization: Bearer <your access token>
The following example demonstrates a request to get the last 20 detections since 2016-09-12 00:00:00.
GET https://wdatp-alertexporter-eu.windows.com/api/alerts?limit=20&sinceTimeUtc=2016-09-12T00:00:00.000
Authorization: Bearer <your access token>
Response
The return value is an array of alert objects in JSON format.
Here is an example return value:
{"AlertTime":"2017-01-23T07:32:54.1861171Z",
"ComputerDnsName":"desktop-bvccckk",
"AlertTitle":"Suspicious PowerShell commandline",
"Category":"SuspiciousActivity",
"Severity":"Medium",
"AlertId":"636207535742330111_-1114309685",
"Actor":null,
"LinkToWDATP":"https://securitycenter.windows.com/alert/636207535742330111_-1114309685",
"IocName":null,
"IocValue":null,
"CreatorIocName":null,
"CreatorIocValue":null,
"Sha1":"69484ca722b4285a234896a2e31707cbedc59ef9",
"FileName":"powershell.exe",
"FilePath":"C:\\Windows\\SysWOW64\\WindowsPowerShell\\v1.0",
"IpAddress":null,
"Url":null,
"IoaDefinitiondId":"7f1c3609-a3ff-40e2-995b-c01770161d68",
"UserName":null,
"AlertPart":0,
"FullId":"636207535742330111_-1114309685:9DE735BA9FF87725E392C6DFBEB2AF279035CDE229FCC00D28C0F3242C5A50AF",
"LastProcessedTimeUtc":"2017-01-23T11:33:45.0760449Z",
"ThreatCategory":null,
"ThreatFamily":null,
"ThreatName":null,
"RemediationAction":null,
"RemediationIsSuccess":null,
"Source":"Microsoft Defender ATP",
"Md5":null,
"Sha256":null,
"WasExecutingWhileDetected":null,
"FileHash":"69484ca722b4285a234896a2e31707cbedc59ef9",
"IocUniqueId":"9DE735BA9FF87725E392C6DFBEB2AF279035CDE229FCC00D28C0F3242C5A50AF"}
Code examples
Get access token
The following code example demonstrates how to obtain an access token and call the Microsoft Defender ATP API.
AuthenticationContext context = new AuthenticationContext(string.Format("https://login.windows.net/{0}", tenantId));
ClientCredential clientCredentials = new ClientCredential(clientId, clientSecret);
AuthenticationResult authenticationResult = context.AcquireTokenAsync(detectionsResource, clientCredentials).GetAwaiter().GetResult();
Use token to connect to the detections endpoint
HttpClient httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(authenticationResult.AccessTokenType, authenticationResult.AccessToken);
HttpResponseMessage response = httpClient.GetAsync("https://wdatp-alertexporter-eu.windows.com/api/alert").GetAwaiter().GetResult();
string detectionsJson = response.Content.ReadAsStringAsync().Result;
Console.WriteLine("Got detections list: {0}", detectionsJson);
Error codes
The Microsoft Defender ATP REST API returns the following error codes caused by an invalid request.
| HTTP error code | Description |
|---|---|
| 401 | Malformed request or invalid token. |
| 403 | Unauthorized exception - any of the domains is not managed by the tenant administrator or tenant state is deleted. |
| 500 | Error in the service. |