mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-05-12 05:17:22 +00:00

Daniel Simpson 9efe39d7be fixing URL for eval link

2019-09-20 11:18:00 -07:00

7.3 KiB

Raw Blame History

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, ms.date

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	ms.date
Experiment with custom threat intelligence alerts	Use this end-to-end guide to start using the Microsoft Defender ATP threat intelligence API.	alert definitions, indicators of compromise, threat intelligence, custom threat intelligence, rest api, api	eADQiWindows 10XVcnh	met150	w10	deploy	library	security	macapara	mjcaparas	medium	dansimp	ITPro	M365-security-compliance	article	11/09/2017

Experiment with custom threat intelligence (TI) alerts (Deprecated)

Applies to:

Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)

Want to experience Microsoft Defender ATP? Sign up for a free trial.

With the Microsoft Defender ATP threat intelligence API, you can create custom threat intelligence alerts that can help you keep track of possible attack activities in your organization.

For more information about threat intelligence concepts, see Understand threat intelligence concepts.

This article demonstrates an end-to-end usage of the threat intelligence API to get you started in using the threat intelligence API.

You'll be guided through sample steps so you can experience how the threat intelligence API feature works. Sample steps include creating alerts definitions and indicators of compromise (IOCs), and examples of how triggered custom TI alerts look like.

Step 1: Enable the threat intelligence API and obtain authentication details

To use the threat intelligence API feature, you'll need to enable the feature. For more information, see Enable the custom threat intelligence application.

This step is required to generate security credentials that you need to use while working with the API.

Step 2: Create a sample alert definition and IOCs

This step will guide you in creating an alert definition and an IOC for a malicious IP.

Open a Windows PowerShell ISE.

Copy and paste the following PowerShell script. This script will upload a sample alert definition and IOC to Microsoft Defender ATP which you can use to generate an alert.

NOTE: Make sure you replace the authUrl, clientId, and clientSecret values with your details which you saved in when you enabled the threat intelligence application.

 $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 Microsoft 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
  }

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.

NOTE:
If you get the exception “The remote server returned an error: (407) Proxy Authentication Required", you need to add the proxy configuration by adding the following code to the PowerShell script:
```
$webclient=New-Object System.Net.WebClient
$creds=Get-Credential
$webclient.Proxy.Credentials=$creds
```

Step 3: Simulate a custom TI alert

This step will guide you in simulating an event in connection to a malicious IP that will trigger the Microsoft Defender ATP custom TI alert.

Open a Windows PowerShell ISE in the machine you onboarded to Microsoft Defender ATP.
Type Invoke-WebRequest 52.184.197.12 in the editor and click Run. This call will generate a network communication event to a Microsoft's dedicated demo server that will raise an alert based on the custom alert definition.

Step 4: Explore the custom alert in the portal

This step will guide you in exploring the custom alert in the portal.

Open Microsoft Defender Security Center on a browser.
Log in with your Microsoft Defender ATP credentials.
The dashboard should display the custom TI alert for the victim machine resulting from the simulated attack.

Note

There is a latency time of approximately 20 minutes between the time a custom TI is introduced and when it becomes effective.

7.3 KiB Raw Blame History