deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-25 15:23:40 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

updated-4567381-batch13

Browse Source 
rebranding
This commit is contained in:
Lovina Saldanha
2020-11-11 21:26:23 +05:30
parent d4acc99d95
commit c7dc0cc6df
25 changed files with 202 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
windows/security/threat-protection/microsoft-defender-atp/pull-alerts-using-rest-api.md
View File

@ -17,24 +17,24 @@ ms.collection: M365-security-compliance
ms.topic: article
---
# Pull Microsoft Defender ATP detections using SIEM REST API
# Pull Microsoft Defender for Endpoint detections using SIEM REST API
[!INCLUDE [Microsoft 365 Defender rebranding](../../includes/microsoft-defender.md)]
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2146631)
- [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631)
>Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-pullalerts-abovefoldlink)
>Want to experience Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-pullalerts-abovefoldlink)
>[!Note]
>- [Microsoft Defender ATP Alert](alerts.md) is composed from one or more detections.
>- [Microsoft Defender ATP Detection](api-portal-mapping.md) is composed from the suspicious event occurred on the Device and its related Alert details.
>-The Microsoft Defender ATP Alert API is the latest API for alert consumption and contain a detailed list of related evidence for each alert. For more information, see [Alert methods and properties](alerts.md) and [List alerts](get-alerts.md).
>- [Microsoft Defender for Endpoint Alert](alerts.md) is composed from one or more detections.
>- [Microsoft Defender for Endpoint Detection](api-portal-mapping.md) is composed from the suspicious event occurred on the Device and its related Alert details.
>-The Microsoft Defender for Endpoint Alert API is the latest API for alert consumption and contain a detailed list of related evidence for each alert. For more information, see [Alert methods and properties](alerts.md) and [List alerts](get-alerts.md).
Microsoft Defender ATP supports the OAuth 2.0 protocol to pull detections from the API.
Microsoft Defender for Endpoint 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
@ -44,19 +44,19 @@ In general, the OAuth 2.0 protocol supports four types of flows:
For more information about the OAuth specifications, see the [OAuth Website](http://www.oauth.net).
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.
Microsoft Defender for Endpoint 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.
The _Client credential flow_ uses client credentials to authenticate against the Microsoft Defender for Endpoint 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.
Use the following method in the Microsoft Defender for Endpoint 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](enable-siem-integration.md).
- Before calling the Microsoft Defender for Endpoint 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 for Endpoint](enable-siem-integration.md).
- 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)
@ -67,7 +67,7 @@ Use the following method in the Microsoft Defender ATP API to pull detections in
## 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.
You'll use the access token to access the protected resource, which are detections in Microsoft Defender for Endpoint.
To get an access token, you'll need to do a POST request to the token issuing endpoint. Here is a sample request:
@ -92,10 +92,10 @@ The response will include an access token and expiry information.
"access_token":"eyJ0eXaioJJOIneiowiouqSuzNiZ345FYOVkaJL0625TueyaJasjhIjEnbMlWqP..."
}
```
You can now use the value in the *access_token* field in a request to the Microsoft Defender ATP API.
You can now use the value in the *access_token* field in a request to the Defender for Endpoint 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.
With an access token, your app can make authenticated requests to the Microsoft Defender for Endpoint API. Your app must append the access token to the Authorization header of each request.
### Request syntax
Method | Request URI
@ -200,7 +200,7 @@ Here is an example return value:
## Code examples
### Get access token
The following code examples demonstrate how to obtain an access token for calling the Microsoft Defender ATP SIEM API.
The following code examples demonstrate how to obtain an access token for calling the Microsoft Defender for Endpoint SIEM API.
```csharp
AuthenticationContext context = new AuthenticationContext(string.Format("https://login.windows.net/{0}", tenantId));
@ -250,7 +250,7 @@ echo ${tokenArr[1]} | cut -d "\"" -f2 | cut -d "\"" -f1 >> $scriptDir/LatestSIEM
```
### Use token to connect to the detections endpoint
The following code examples demonstrate how to use an access token for calling the Microsoft Defender ATP SIEM API to get alerts.
The following code examples demonstrate how to use an access token for calling the Defender for Endpoint SIEM API to get alerts.
```csharp
HttpClient httpClient = new HttpClient();
@ -318,7 +318,7 @@ echo $apiResponse
```
## Error codes
The Microsoft Defender ATP REST API returns the following error codes caused by an invalid request.
The Microsoft Defender for Endpoint REST API returns the following error codes caused by an invalid request.
HTTP error code | Description
:---|:---
@ -327,8 +327,8 @@ HTTP error code | Description
500 | Error in the service.
## Related topics
- [Enable SIEM integration in Microsoft Defender ATP](enable-siem-integration.md)
- [Configure ArcSight to pull Microsoft Defender ATP detections](configure-arcsight.md)
- [Configure Splunk to pull Microsoft Defender ATP detections](configure-splunk.md)
- [Microsoft Defender ATP Detection fields](api-portal-mapping.md)
- [Enable SIEM integration in Microsoft Defender for Endpoint](enable-siem-integration.md)
- [Configure ArcSight to pull Microsoft Defender for Endpoint detections](configure-arcsight.md)
- [Configure Splunk to pull Microsoft Defender for Endpoint detections](configure-splunk.md)
- [Microsoft Defender for Endpoint Detection fields](api-portal-mapping.md)
- [Troubleshoot SIEM tool integration issues](troubleshoot-siem.md)