mirror of
https://github.com/MicrosoftDocs/windows-itpro-docs.git
synced 2025-05-13 13:57:22 +00:00
Merge remote-tracking branch 'refs/remotes/origin/master' into jd-sandbox
This commit is contained in:
jdeckerMS
commit
fe73dcaf40
@ -786,6 +786,7 @@
|
||||
##### [Configure HP ArcSight to pull alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
##### [Windows Defender ATP alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
##### [Pull alerts using REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
##### [Troubleshoot SIEM tool integration issues](troubleshoot-siem-windows-defender-advanced-threat-protection.md)
|
||||
#### [Use the threat intelligence API to create custom alerts](use-custom-ti-windows-defender-advanced-threat-protection.md)
|
||||
##### [Understand threat intelligence concepts](threat-indicator-concepts-windows-defender-advanced-threat-protection.md)
|
||||
##### [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -78,3 +78,4 @@ Portal label | SIEM field name | Description
|
||||
- [Configure Splunk to pull Windows Defender ATP alerts](configure-splunk-windows-defender-advanced-threat-protection.md)
|
||||
- [Configure ArcSight to pull Windows Defender ATP alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
- [Pull Windows Defender ATP alerts using REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
- [Troubleshoot SIEM tool integration issues](troubleshoot-siem-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -1,60 +0,0 @@
|
||||
$authUrl = 'Your Authorization URL'
|
||||
$clientId = 'Your Client ID'
|
||||
$clientSecret = 'Your Client Secret'
|
||||
|
||||
|
||||
Try
|
||||
{
|
||||
$tokenPayload = @{
|
||||
"resource" = 'https://graph.windows.net'
|
||||
"client_id" = $clientId
|
||||
"client_secret" = $clientSecret
|
||||
"grant_type"='client_credentials'}
|
||||
|
||||
"Fetching an access token"
|
||||
$response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
|
||||
$token = $response.access_token
|
||||
"Token fetched successfully"
|
||||
|
||||
$headers = @{
|
||||
"Content-Type" = "application/json"
|
||||
"Accept" = "application/json"
|
||||
"Authorization" = "Bearer {0}" -f $token }
|
||||
|
||||
$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
|
||||
|
||||
$alertDefinitionPayload = @{
|
||||
"Name" = "Test Alert"
|
||||
"Severity" = "Medium"
|
||||
"InternalDescription" = "A test alert used to demonstrate the Windows Defender ATP TI API feature"
|
||||
"Title" = "Test alert."
|
||||
"UxDescription" = "This is a test alert based on a sample custom alert definition. This alert was triggered manually using a provided test command. It indicates that the Threat Intelligence API has been properly enabled."
|
||||
"RecommendedAction" = "No recommended action for this test alert."
|
||||
"Category" = "SuspiciousNetworkTraffic"
|
||||
"Enabled" = "true"}
|
||||
"Creating an Alert Definition"
|
||||
$alertDefinition =
|
||||
Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
|
||||
"Alert Definition created successfully"
|
||||
$alertDefinitionId = $alertDefinition.Id
|
||||
|
||||
$iocPayload = @{
|
||||
"Type"="IpAddress"
|
||||
"Value"="52.184.197.12"
|
||||
"DetectionFunction"="Equals"
|
||||
"Enabled"="true"
|
||||
"AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
|
||||
|
||||
"Creating an Indicator of Compromise"
|
||||
$ioc =
|
||||
Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
|
||||
"Indicator of Compromise created successfully"
|
||||
|
||||
"All done!"
|
||||
}
|
||||
Catch
|
||||
{
|
||||
'Something went wrong! Got the following exception message: {0}' -f $_.Exception.Message
|
||||
}
|
||||
@ -1,50 +0,0 @@
|
||||
$authUrl = 'Your Authorization URL'
|
||||
$clientId = 'Your Client ID'
|
||||
$clientSecret = 'Your Client Secret'
|
||||
|
||||
$tokenPayload = @{
|
||||
"resource"='https://graph.windows.net'
|
||||
"client_id" = $clientId
|
||||
"client_secret" = $clientSecret
|
||||
"grant_type"='client_credentials'}
|
||||
|
||||
$response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
|
||||
$token = $response.access_token
|
||||
|
||||
$headers = @{
|
||||
"Content-Type"="application/json"
|
||||
"Accept"="application/json"
|
||||
"Authorization"="Bearer {0}" -f $token }
|
||||
|
||||
$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
|
||||
|
||||
$alertDefinitions =
|
||||
(Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) -Method Get -Headers $headers).value
|
||||
|
||||
$alertDefinitionPayload = @{
|
||||
"Name"= "The alert's name"
|
||||
"Severity"= "Low"
|
||||
"InternalDescription"= "An internal description of the Alert"
|
||||
"Title"= "The Title"
|
||||
"UxDescription"= "Description of the alerts"
|
||||
"RecommendedAction"= "The alert's recommended action"
|
||||
"Category"= "Trojan"
|
||||
"Enabled"= "true"}
|
||||
|
||||
$alertDefinition =
|
||||
Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
|
||||
|
||||
$alertDefinitionId = $alertDefinition.Id
|
||||
|
||||
$iocPayload = @{
|
||||
"Type"="Sha1"
|
||||
"Value"="dead1111eeaabbccddeeaabbccddee11ffffffff"
|
||||
"DetectionFunction"="Equals"
|
||||
"Enabled"="true"
|
||||
"AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
|
||||
|
||||
|
||||
$ioc =
|
||||
Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
|
||||
@ -1,51 +0,0 @@
|
||||
import json
|
||||
import requests
|
||||
from pprint import pprint
|
||||
|
||||
auth_url="Your Authorization URL"
|
||||
client_id="Your Client ID"
|
||||
client_secret="Your Client Secret"
|
||||
|
||||
payload = {"resource": "https://graph.windows.net",
|
||||
"client_id": client_id,
|
||||
"client_secret": client_secret,
|
||||
"grant_type": "client_credentials"}
|
||||
|
||||
response = requests.post(auth_url, payload)
|
||||
token = json.loads(response.text)["access_token"]
|
||||
|
||||
with requests.Session() as session:
|
||||
session.headers = {
|
||||
'Authorization': 'Bearer {}'.format(token),
|
||||
'Content-Type': 'application/json',
|
||||
'Accept': 'application/json'}
|
||||
|
||||
response = session.get("https://ti.securitycenter.windows.com/V1.0/AlertDefinitions")
|
||||
pprint(json.loads(response.text))
|
||||
|
||||
alert_definition = {"Name": "The alert's name",
|
||||
"Severity": "Low",
|
||||
"InternalDescription": "An internal description of the alert",
|
||||
"Title": "The Title",
|
||||
"UxDescription": "Description of the alerts",
|
||||
"RecommendedAction": "The alert's recommended action",
|
||||
"Category": "Trojan",
|
||||
"Enabled": True}
|
||||
|
||||
response = session.post(
|
||||
"https://ti.securitycenter.windows.com/V1.0/AlertDefinitions",
|
||||
json=alert_definition)
|
||||
|
||||
alert_definition_id = json.loads(response.text)["Id"]
|
||||
|
||||
ioc = {'Type': "Sha1",
|
||||
'Value': "dead1111eeaabbccddeeaabbccddee11ffffffff",
|
||||
'DetectionFunction': "Equals",
|
||||
'Enabled': True,
|
||||
"AlertDefinition@odata.bind": "AlertDefinitions({0})".format(alert_definition_id)}
|
||||
|
||||
response = session.post(
|
||||
"https://ti.securitycenter.windows.com/V1.0/IndicatorsOfCompromise",
|
||||
json=ioc)
|
||||
|
||||
pprint(json.loads(response.text))
|
||||
@ -182,3 +182,4 @@ Windows Defender ATP alerts will appear as discrete events, with "Microsoft” a
|
||||
- [Enable SIEM integration in Windows Defender ATP](enable-siem-integration-windows-defender-advanced-threat-protection.md)
|
||||
- [Configure Splunk to pull Windows Defender ATP alerts](configure-splunk-windows-defender-advanced-threat-protection.md)
|
||||
- [Pull Windows Defender ATP alerts using REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
- [Troubleshoot SIEM tool integration issues](troubleshoot-siem-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -46,6 +46,10 @@ The email notifications feature is turned off by default. Turn it on to start re
|
||||
|
||||
Check that email recipients are able to receive the email notifications by selecting **Send test email**. All recipients in the list will receive the test email.
|
||||
|
||||
Here's an example email notification:
|
||||
|
||||
|
||||
|
||||
## Remove email recipients
|
||||
|
||||
1. Select the trash bin icon beside the email address you’d like to remove.
|
||||
|
||||
@ -34,8 +34,8 @@ To use either of these supported SIEM tools you'll need to:
|
||||
|
||||
- [Enable SIEM integration in Windows Defender ATP](enable-siem-integration-windows-defender-advanced-threat-protection.md)
|
||||
- Configure the supported SIEM tool:
|
||||
- [Configure Splunk to pull alerts](configure-splunk-windows-defender-advanced-threat-protection.md)
|
||||
- [Configure HP ArcSight to pull alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
- [Configure Splunk to pull Windows Defender ATP alerts](configure-splunk-windows-defender-advanced-threat-protection.md)
|
||||
- [Configure HP ArcSight to pull Windows Defender ATP alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
For more information on the list of fields exposed in the alerts API see, [Windows Defender ATP alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md).
|
||||
|
||||
@ -51,7 +51,8 @@ For more information, see [Pull Windows Defender ATP alerts using REST API](pull
|
||||
Topic | Description
|
||||
:---|:---
|
||||
[Enable SIEM integration in Windows Defender ATP](enable-siem-integration-windows-defender-advanced-threat-protection.md)| Learn about enabling the SIEM integration feature in the **Preferences setup** page in the portal so that you can use and generate the required information to configure supported SIEM tools.
|
||||
[Configure Splunk to pull alerts](configure-splunk-windows-defender-advanced-threat-protection.md)| Learn about installing the REST API Modular Input app and other configuration settings to enable Splunk to pull Windows Defender ATP alerts.
|
||||
[Configure ArcSight to pull alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)| Learn about installing the HP ArcSight REST FlexConnector package and the files you need to configure ArcSight to pull Windows Defender ATP alerts.
|
||||
[Configure Splunk to pull Windows Defender ATP alerts](configure-splunk-windows-defender-advanced-threat-protection.md)| Learn about installing the REST API Modular Input app and other configuration settings to enable Splunk to pull Windows Defender ATP alerts.
|
||||
[Configure ArcSight to pull Windows Defender ATP alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)| Learn about installing the HP ArcSight REST FlexConnector package and the files you need to configure ArcSight to pull Windows Defender ATP alerts.
|
||||
[Windows Defender ATP alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md) | Understand what data fields are exposed as part of the alerts API and how they map to the Windows Defender ATP portal.
|
||||
[Pull Windows Defender ATP alerts using REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md) | Use the Client credentials OAuth 2.0 flow to pull alerts from Windows Defender ATP using REST API.
|
||||
[Troubleshoot SIEM tool integration issues](troubleshoot-siem-windows-defender-advanced-threat-protection.md) | Address issues you might encounter when using the SIEM integration feature.
|
||||
|
||||
@ -138,3 +138,4 @@ Use the solution explorer to view alerts in Splunk.
|
||||
- [Configure ArcSight to pull Windows Defender ATP alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
- [Windows Defender ATP alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
- [Pull Windows Defender ATP alerts using REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
- [Troubleshoot SIEM tool integration issues](troubleshoot-siem-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -53,3 +53,4 @@ You can now proceed with configuring your SIEM solution or connecting to the ale
|
||||
- [Configure ArcSight to pull Windows Defender ATP alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
- [Windows Defender ATP alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
- [Pull Windows Defender ATP alerts using REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
- [Troubleshoot SIEM tool integration issues](troubleshoot-siem-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -45,7 +45,71 @@ This step will guide you in creating an alert definition and an IOC for a malici
|
||||
NOTE:<br>
|
||||
Make sure you replace the `authUrl`, `clientId`, and `clientSecret` values with your details which you saved in when you enabled the threat intelligence application.
|
||||
|
||||
[!code[ExampleScript](./code/example-script.ps1#L1-L60)]
|
||||
```
|
||||
$authUrl = 'Your Authorization URL'
|
||||
$clientId = 'Your Client ID'
|
||||
$clientSecret = 'Your Client Secret'
|
||||
|
||||
|
||||
Try
|
||||
{
|
||||
$tokenPayload = @{
|
||||
"resource" = 'https://graph.windows.net'
|
||||
"client_id" = $clientId
|
||||
"client_secret" = $clientSecret
|
||||
"grant_type"='client_credentials'}
|
||||
|
||||
"Fetching an access token"
|
||||
$response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
|
||||
$token = $response.access_token
|
||||
"Token fetched successfully"
|
||||
|
||||
$headers = @{
|
||||
"Content-Type" = "application/json"
|
||||
"Accept" = "application/json"
|
||||
"Authorization" = "Bearer {0}" -f $token }
|
||||
|
||||
$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
|
||||
|
||||
$alertDefinitionPayload = @{
|
||||
"Name" = "Test Alert"
|
||||
"Severity" = "Medium"
|
||||
"InternalDescription" = "A test alert used to demonstrate the Windows Defender ATP TI API feature"
|
||||
"Title" = "Test alert."
|
||||
"UxDescription" = "This is a test alert based on a sample custom alert definition. This alert was triggered manually using a provided test command. It indicates that the Threat Intelligence API has been properly enabled."
|
||||
"RecommendedAction" = "No recommended action for this test alert."
|
||||
"Category" = "SuspiciousNetworkTraffic"
|
||||
"Enabled" = "true"}
|
||||
|
||||
"Creating an Alert Definition"
|
||||
$alertDefinition =
|
||||
Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
|
||||
|
||||
"Alert Definition created successfully"
|
||||
$alertDefinitionId = $alertDefinition.Id
|
||||
|
||||
$iocPayload = @{
|
||||
"Type"="IpAddress"
|
||||
"Value"="52.184.197.12"
|
||||
"DetectionFunction"="Equals"
|
||||
"Enabled"="true"
|
||||
"AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
|
||||
|
||||
"Creating an Indicator of Compromise"
|
||||
$ioc =
|
||||
Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
|
||||
"Indicator of Compromise created successfully"
|
||||
|
||||
"All done!"
|
||||
}
|
||||
Catch
|
||||
{
|
||||
'Something went wrong! Got the following exception message: {0}' -f $_.Exception.Message
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
3. Run the script and verify that the operation succeeded in the results the window. Wait up to 20 minutes until the new or updated alert definition propagates to the detection engines.
|
||||
|
||||
|
||||
BIN
windows/keep-secure/images/atp-example-email-notification.png
Normal file
BIN
windows/keep-secure/images/atp-example-email-notification.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
@ -36,19 +36,43 @@ The following example demonstrates how to obtain an Azure AD access token that y
|
||||
|
||||
Replace the *authUrl*, *clientid*, and *clientSecret* values with the ones you got from **Preferences settings** page in the portal:
|
||||
|
||||
[!code[CustomTIAPI](./code/example.ps1#L1-L14)]
|
||||
```powershell
|
||||
$authUrl = 'Your Authorization URL'
|
||||
$clientId = 'Your Client ID'
|
||||
$clientSecret = 'Your Client Secret'
|
||||
|
||||
$tokenPayload = @{
|
||||
"resource"='https://graph.windows.net'
|
||||
"client_id" = $clientId
|
||||
"client_secret" = $clientSecret
|
||||
"grant_type"='client_credentials'}
|
||||
|
||||
$response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
|
||||
$token = $response.access_token
|
||||
|
||||
```
|
||||
|
||||
<span id="header" />
|
||||
## Step 2: Create headers used for the requests with the API
|
||||
Use the following code to create the headers used for the requests with the API:
|
||||
|
||||
[!code[CustomTIAPI](./code/example.ps1#L16-L19)]
|
||||
```powershell
|
||||
$headers = @{
|
||||
"Content-Type"="application/json"
|
||||
"Accept"="application/json"
|
||||
"Authorization"="Bearer {0}" -f $token }
|
||||
|
||||
$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
|
||||
```
|
||||
|
||||
<span id="calls" />
|
||||
## Step 3: Create calls to the custom threat intelligence API
|
||||
After creating the headers, you can now create calls to the API. The following example demonstrates how you can view all the alert definition entities:
|
||||
|
||||
[!code[CustomTIAPI](./code/example.ps1#L21-L24)]
|
||||
```powershell
|
||||
$alertDefinitions =
|
||||
(Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) -Method Get -Headers $headers).value
|
||||
```
|
||||
|
||||
The response is empty on initial use of the API.
|
||||
|
||||
@ -56,18 +80,96 @@ The response is empty on initial use of the API.
|
||||
## Step 4: Create a new alert definition
|
||||
The following example demonstrates how you to create a new alert definition.
|
||||
|
||||
[!code[CustomTIAPI](./code/example.ps1#L26-L39)]
|
||||
```powershell
|
||||
$alertDefinitionPayload = @{
|
||||
"Name"= "The alert's name"
|
||||
"Severity"= "Low"
|
||||
"InternalDescription"= "An internal description of the Alert"
|
||||
"Title"= "The Title"
|
||||
"UxDescription"= "Description of the alerts"
|
||||
"RecommendedAction"= "The alert's recommended action"
|
||||
"Category"= "Trojan"
|
||||
"Enabled"= "true"}
|
||||
|
||||
$alertDefinition =
|
||||
Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
|
||||
```
|
||||
|
||||
<span id="ioc" />
|
||||
## Step 5: Create a new indicator of compromise
|
||||
You can now use the alert ID obtained from creating a new alert definition to create a new indicator of compromise.
|
||||
|
||||
[!code[CustomTIAPI](./code/example.ps1#L43-L53)]
|
||||
```powershell
|
||||
$iocPayload = @{
|
||||
"Type"="Sha1"
|
||||
"Value"="dead1111eeaabbccddeeaabbccddee11ffffffff"
|
||||
"DetectionFunction"="Equals"
|
||||
"Enabled"="true"
|
||||
"AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
|
||||
|
||||
|
||||
$ioc =
|
||||
Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
|
||||
```
|
||||
|
||||
## Complete code
|
||||
You can use the complete code to create calls to the API.
|
||||
|
||||
[!code[CustomTIAPI](./code/example.ps1#L1-L53)]
|
||||
```powershell
|
||||
$authUrl = 'Your Authorization URL'
|
||||
$clientId = 'Your Client ID'
|
||||
$clientSecret = 'Your Client Secret'
|
||||
|
||||
$tokenPayload = @{
|
||||
"resource"='https://graph.windows.net'
|
||||
"client_id" = $clientId
|
||||
"client_secret" = $clientSecret
|
||||
"grant_type"='client_credentials'}
|
||||
|
||||
$response = Invoke-RestMethod $authUrl -Method Post -Body $tokenPayload
|
||||
$token = $response.access_token
|
||||
|
||||
$headers = @{
|
||||
"Content-Type"="application/json"
|
||||
"Accept"="application/json"
|
||||
"Authorization"="Bearer {0}" -f $token }
|
||||
|
||||
$apiBaseUrl = "https://ti.securitycenter.windows.com/V1.0/"
|
||||
|
||||
$alertDefinitions =
|
||||
(Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) -Method Get -Headers $headers).value
|
||||
|
||||
$alertDefinitionPayload = @{
|
||||
"Name"= "The alert's name"
|
||||
"Severity"= "Low"
|
||||
"InternalDescription"= "An internal description of the Alert"
|
||||
"Title"= "The Title"
|
||||
"UxDescription"= "Description of the alerts"
|
||||
"RecommendedAction"= "The alert's recommended action"
|
||||
"Category"= "Trojan"
|
||||
"Enabled"= "true"}
|
||||
|
||||
$alertDefinition =
|
||||
Invoke-RestMethod ("{0}AlertDefinitions" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($alertDefinitionPayload | ConvertTo-Json)
|
||||
|
||||
$alertDefinitionId = $alertDefinition.Id
|
||||
|
||||
$iocPayload = @{
|
||||
"Type"="Sha1"
|
||||
"Value"="dead1111eeaabbccddeeaabbccddee11ffffffff"
|
||||
"DetectionFunction"="Equals"
|
||||
"Enabled"="true"
|
||||
"AlertDefinition@odata.bind"="AlertDefinitions({0})" -f $alertDefinitionId }
|
||||
|
||||
|
||||
$ioc =
|
||||
Invoke-RestMethod ("{0}IndicatorsOfCompromise" -f $apiBaseUrl) `
|
||||
-Method Post -Headers $headers -Body ($iocPayload | ConvertTo-Json)
|
||||
|
||||
```
|
||||
|
||||
## Related topics
|
||||
- [Understand threat intelligence concepts](threat-indicator-concepts-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -193,3 +193,4 @@ HTTP error code | Description
|
||||
- [Configure Splunk to pull Windows Defender ATP alerts](configure-splunk-windows-defender-advanced-threat-protection.md)
|
||||
- [Configure ArcSight to pull Windows Defender ATP alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
- [Windows Defender ATP alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
- [Troubleshoot SIEM tool integration issues](troubleshoot-siem-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -38,20 +38,45 @@ The following example demonstrates how to obtain an Azure AD access token that y
|
||||
|
||||
Replace the *auth_url*, *client_id*, and *client_secret* values with the ones you got from **Preferences settings** page in the portal:
|
||||
|
||||
[!code[CustomTIAPI](./code/example.py#L1-L17)]
|
||||
```
|
||||
import json
|
||||
import requests
|
||||
from pprint import pprint
|
||||
|
||||
auth_url="Your Authorization URL"
|
||||
client_id="Your Client ID"
|
||||
client_secret="Your Client Secret"
|
||||
|
||||
payload = {"resource": "https://graph.windows.net",
|
||||
"client_id": client_id,
|
||||
"client_secret": client_secret,
|
||||
"grant_type": "client_credentials"}
|
||||
|
||||
response = requests.post(auth_url, payload)
|
||||
token = json.loads(response.text)["access_token"]
|
||||
```
|
||||
|
||||
|
||||
<span id="session-object" />
|
||||
## Step 2: Create request session object
|
||||
Add HTTP headers to the session object, including the Authorization header with the token that was obtained.
|
||||
|
||||
[!code[CustomTIAPI](./code/example.py#L19-L23)]
|
||||
```
|
||||
with requests.Session() as session:
|
||||
session.headers = {
|
||||
'Authorization': 'Bearer {}'.format(token),
|
||||
'Content-Type': 'application/json',
|
||||
'Accept': 'application/json'}
|
||||
```
|
||||
|
||||
<span id="calls" />
|
||||
## Step 3: Create calls to the custom threat intelligence API
|
||||
After adding HTTP headers to the session object, you can now create calls to the API. The following example demonstrates how you can view all the alert definition entities:
|
||||
|
||||
[!code[CustomTIAPI](./code/example.py#L25-L26)]
|
||||
```
|
||||
response = session.get("https://ti.securitycenter.windows.com/V1.0/AlertDefinitions")
|
||||
pprint(json.loads(response.text))
|
||||
```
|
||||
|
||||
The response is empty on initial use of the API.
|
||||
|
||||
@ -59,18 +84,95 @@ The response is empty on initial use of the API.
|
||||
## Step 4: Create a new alert definition
|
||||
The following example demonstrates how you to create a new alert definition.
|
||||
|
||||
[!code[CustomTIAPI](./code/example.py#L28-L39)]
|
||||
```
|
||||
alert_definition = {"Name": "The alert's name",
|
||||
"Severity": "Low",
|
||||
"InternalDescription": "An internal description of the alert",
|
||||
"Title": "The Title",
|
||||
"UxDescription": "Description of the alerts",
|
||||
"RecommendedAction": "The alert's recommended action",
|
||||
"Category": "Trojan",
|
||||
"Enabled": True}
|
||||
|
||||
response = session.post(
|
||||
"https://ti.securitycenter.windows.com/V1.0/AlertDefinitions",
|
||||
json=alert_definition)
|
||||
```
|
||||
|
||||
<span id="ioc" />
|
||||
## Step 5: Create a new indicator of compromise
|
||||
You can now use the alert ID obtained from creating a new alert definition to create a new indicator of compromise.
|
||||
|
||||
[!code[CustomTIAPI](./code/example.py#L41-L51)]
|
||||
```
|
||||
alert_definition_id = json.loads(response.text)["Id"]
|
||||
|
||||
ioc = {'Type': "Sha1",
|
||||
'Value': "dead1111eeaabbccddeeaabbccddee11ffffffff",
|
||||
'DetectionFunction': "Equals",
|
||||
'Enabled': True,
|
||||
"AlertDefinition@odata.bind": "AlertDefinitions({0})".format(alert_definition_id)}
|
||||
|
||||
response = session.post(
|
||||
"https://ti.securitycenter.windows.com/V1.0/IndicatorsOfCompromise",
|
||||
json=ioc)
|
||||
```
|
||||
|
||||
## Complete code
|
||||
You can use the complete code to create calls to the API.
|
||||
|
||||
[!code[CustomTIAPI](./code/example.py#L1-L53)]
|
||||
```syntax
|
||||
import json
|
||||
import requests
|
||||
from pprint import pprint
|
||||
|
||||
auth_url="Your Authorization URL"
|
||||
client_id="Your Client ID"
|
||||
client_secret="Your Client Secret"
|
||||
|
||||
payload = {"resource": "https://graph.windows.net",
|
||||
"client_id": client_id,
|
||||
"client_secret": client_secret,
|
||||
"grant_type": "client_credentials"}
|
||||
|
||||
response = requests.post(auth_url, payload)
|
||||
token = json.loads(response.text)["access_token"]
|
||||
|
||||
with requests.Session() as session:
|
||||
session.headers = {
|
||||
'Authorization': 'Bearer {}'.format(token),
|
||||
'Content-Type': 'application/json',
|
||||
'Accept': 'application/json'}
|
||||
|
||||
response = session.get("https://ti.securitycenter.windows.com/V1.0/AlertDefinitions")
|
||||
pprint(json.loads(response.text))
|
||||
|
||||
alert_definition = {"Name": "The alert's name",
|
||||
"Severity": "Low",
|
||||
"InternalDescription": "An internal description of the alert",
|
||||
"Title": "The Title",
|
||||
"UxDescription": "Description of the alerts",
|
||||
"RecommendedAction": "The alert's recommended action",
|
||||
"Category": "Trojan",
|
||||
"Enabled": True}
|
||||
|
||||
response = session.post(
|
||||
"https://ti.securitycenter.windows.com/V1.0/AlertDefinitions",
|
||||
json=alert_definition)
|
||||
|
||||
alert_definition_id = json.loads(response.text)["Id"]
|
||||
|
||||
ioc = {'Type': "Sha1",
|
||||
'Value': "dead1111eeaabbccddeeaabbccddee11ffffffff",
|
||||
'DetectionFunction': "Equals",
|
||||
'Enabled': True,
|
||||
"AlertDefinition@odata.bind": "AlertDefinitions({0})".format(alert_definition_id)}
|
||||
|
||||
response = session.post(
|
||||
"https://ti.securitycenter.windows.com/V1.0/IndicatorsOfCompromise",
|
||||
json=ioc)
|
||||
|
||||
pprint(json.loads(response.text))
|
||||
```
|
||||
|
||||
## Related topics
|
||||
- [Understand threat intelligence concepts](threat-indicator-concepts-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -151,8 +151,21 @@ Event ID | Message | Resolution steps
|
||||
5 | Windows Defender Advanced Threat Protection service failed to connect to the server at _variable_ | [Ensure the endpoint has Internet access](#ensure-the-endpoint-has-an-internet-connection).
|
||||
6 | Windows Defender Advanced Threat Protection service is not onboarded and no onboarding parameters were found. Failure code: _variable_ | [Run the onboarding script again](configure-endpoints-windows-defender-advanced-threat-protection.md).
|
||||
7 | Windows Defender Advanced Threat Protection service failed to read the onboarding parameters. Failure code: _variable_ | [Ensure the endpoint has Internet access](#ensure-the-endpoint-has-an-internet-connection), then run the entire onboarding process again.
|
||||
9 | Windows Defender Advanced Threat Protection service failed to change its start type. Failure code: variable | If the event happened during onboarding, reboot and re-attempt running the onboarding script. For more information, see [Run the onboarding script again](configure-endpoints-windows-defender-advanced-threat-protection.md). <br><br>If the event happened during offboarding, contact support.
|
||||
10 | Windows Defender Advanced Threat Protection service failed to persist the onboarding information. Failure code: variable | If the event happened during onboarding, re-attempt running the onboarding script. For more information, see [Run the onboarding script again](configure-endpoints-windows-defender-advanced-threat-protection.md). <br><br>If the problem persists, contact support.
|
||||
15 | Windows Defender Advanced Threat Protection cannot start command channel with URL: _variable_ | [Ensure the endpoint has Internet access](#ensure-the-endpoint-has-an-internet-connection).
|
||||
17 | Windows Defender Advanced Threat Protection service failed to change the Connected User Experiences and Telemetry service location. Failure code: variable | [Run the onboarding script again](configure-endpoints-windows-defender-advanced-threat-protection.md). If the problem persists, contact support.
|
||||
25 | Windows Defender Advanced Threat Protection service failed to reset health status in the registry. Failure code: _variable_ | Contact support.
|
||||
27 | Failed to enable Windows Defender Advanced Threat Protection mode in Windows Defender. Onboarding process failed. Failure code: variable | Contact support.
|
||||
29 | Failed to read the offboarding parameters. Error type: %1, Error code: %2, Description: %3 | Ensure the endpoint has Internet access, then run the entire offboarding process again.
|
||||
30 | Failed to disable $(build.sense.productDisplayName) mode in Windows Defender Advanced Threat Protection. Failure code: %1 | Contact support.
|
||||
32 | $(build.sense.productDisplayName) service failed to request to stop itself after offboarding process. Failure code: %1 | Verify that the service start type is manual and reboot the machine.
|
||||
55 | Failed to create the Secure ETW autologger. Failure code: %1 | Reboot the machine.
|
||||
63 | Updating the start type of external service. Name: %1, actual start type: %2, expected start type: %3, exit code: %4 | Identify what is causing changes in start type of mentioned service. If the exit code is not 0, fix the start type manually to expected start type.
|
||||
64 | Starting stopped external service. Name: %1, exit code: %2 | Contact support if the event keeps re-appearing.
|
||||
68 | The start type of the service is unexpected. Service name: %1, actual start type: %2, expected start type: %3 | Identify what is causing changes in start type. Fix mentioned service start type.
|
||||
69 | The service is stopped. Service name: %1 | Start the mentioned service. Contact support if persists.
|
||||
|
||||
<br>
|
||||
There are additional components on the endpoint that the Windows Defender ATP agent depends on to function properly. If there are no onboarding related errors in the Windows Defender ATP agent event log, proceed with the following steps to ensure that the additional components are configured correctly.
|
||||
|
||||
|
||||
@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Troubleshoot SIEM tool integration issues in Windows Defender ATP
|
||||
description: Troubleshoot issues that might arise when using SIEM tools with Windows Defender ATP.
|
||||
keywords: troubleshoot, siem, client secret, secret
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
ms.mktglfcycl: deploy
|
||||
ms.sitesec: library
|
||||
ms.pagetype: security
|
||||
author: mjcaparas
|
||||
localizationpriority: high
|
||||
---
|
||||
|
||||
# Troubleshoot SIEM tool integration issues
|
||||
|
||||
**Applies to:**
|
||||
|
||||
- Windows 10 Enterprise
|
||||
- Windows 10 Education
|
||||
- Windows 10 Pro
|
||||
- Windows 10 Pro Education
|
||||
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||
|
||||
You might need to troubleshoot issues while pulling alerts in your SIEM tools.
|
||||
|
||||
This page provides detailed steps to troubleshoot issues you might encounter.
|
||||
|
||||
|
||||
## Learn how to get a new client secret
|
||||
If your client secret expires or if you've misplaced the copy provided when you were enabling the SIEM tool application, you'll need to get a new secret.
|
||||
|
||||
1. Login to the [Azure management portal](https://ms.portal.azure.com).
|
||||
|
||||
2. Select **Active Directory**.
|
||||
|
||||
3. Select your tenant.
|
||||
|
||||
4. Click **Application**, then select your SIEM tool application. The application name is `https://windowsdefenderatpsiemconnector`.
|
||||
|
||||
5. Select **Keys** section, then provide a key description and specify the key validity duration.
|
||||
|
||||
6. Click **Save**. The key value is displayed.
|
||||
|
||||
7. Copy the value and save it in a safe place.
|
||||
|
||||
|
||||
## Related topics
|
||||
- [Enable SIEM integration in Windows Defender ATP](enable-siem-integration-windows-defender-advanced-threat-protection.md)
|
||||
- [Configure Splunk to pull Windows Defender ATP alerts](configure-splunk-windows-defender-advanced-threat-protection.md)
|
||||
- [Configure ArcSight to pull Windows Defender ATP alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
- [Windows Defender ATP alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
- [Pull Windows Defender ATP alerts using REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
Loading…
x
Reference in New Issue
Block a user