Home

WDATP API “Hello World” (or using a simple PowerShell script to pull alerts via WDATP APIs)

Highlighted
Raviv Tamir
Microsoft

WDATP API “Hello World” (or using a simple PowerShell script to pull alerts via WDATP APIs)

*5 Minutes

*Low complexity

 

Applying a security solution in an enterprise environment can be a complex endeavor. Customers deploy various layers of protection solutions, investigation platforms and hunting tools. Security Operation teams attempt to tackle this task, but typically lack expensive and experienced human resources to overcome this challenge. Automation is a decent mitigation but automating the security procedures and wiring the security components all together to a solid cyber security solution, requires programmatic access to each solution.

 

In these series of blogs, we will walk you through common automation scenarios that you can achieve with Windows Defender ATP to optimize workflows. For more information on Windows Defender ATP APIs, see the full documentation.

 

We called this blog “Hello World” as every long software journey starts with a simple step. We’ll show you how to programmatically extract Windows Defender ATP alerts with a PowerShell script. You can schedule this script to run on any machine and you may modify it to use the alert information in your specific use case. We can imagine a handful of standard use cases where a Security Operations Center (SOC) can leverage this basic capability.

 

Some scenarios where this can be applied include use with security information and event management (SIEM) connectors, ticketing systems, and security orchestration and response (SOAR) solutions. SIEM connectors may be the simplest example while ticketing systems are a common one, and SOAR solutions may be a complex use case.

 

So let gets started….

 

How long it takes to go through this example?

 

It only takes 5 minutes done in two steps:

  • Application registration: takes 2 minutes
  • Use examples: only requires copy/paste of a short PowerShell script

Do I need a permission to connect?

For the app registration stage, you must have a Global administrator role in your Azure Active Directory (Azure AD) tenant.

 

Step 1 - Register the app in Azure Active Directory

 

  • With your Global administrator credentials, login to the Azure portal.
    • Azure Active Directory > App registrations > New application registration.

1.png

 

  • In the registration form:
    • Name - Enter any name of choice.
    • Application type - Use “Web app / API”. We’ll discuss the other options on future blogs.
    • Sign-on URL – For this example you can copy the following value: https://www.ContosoWdatpConnector.com
    • Click Create.

2.png

  • The application we created is the authentication entity, just like a service account. We now need to set permissions to my app and save its credential for later use.
  • Settings > Required permissions > +Add

3.png

 

  • In the "Add API access" panel:
    • Select an API
    • Paste “WindowsDefenderATP” in the search box (it will not appear in the list).
    • Select “WindowsDefenderATP”
    • Click Select

 

4.png

 

 

 

  • In this example, we only need the “Read all alerts” permission.
  • Select the “Read all alerts” permission and click Select and
  • You may select more permissions for other scenarios.

5.png

 

  • Now we need to grant permission in the "Required permission" page. It is the tenant admin consent allowing the app to access the required permissions.
    • Click Grant permission

6.png

  • As explained, the registered app is an authentication entity with permission to access all alerts for reading. Now we need to get and store the authentication and authorization credentials:
    • Key (application secret), Application ID.
  • To get credentials:
    • Click Settings > Keys
    • Specify a key description (e.g. “ContosoWdatpApi”) with duration of 1 year.

7.png

 

  • Click Save.
  • The application key will appear.
    IMPORTANT: Copy and store this key in a safe place. Treat it like a password.
  • Application ID: copy and store the Application ID. This is the “user name” of the credentials. See the green frame above.

 

  • Finally, we need the “Tenant ID” (a.k.a Directory ID) to target the API to the correct tenant:
    • Go back to the main screen ( https://portal.azure.com)
    • Azure Active Directory > Properties
    • Copy and store the "Directory ID"

8.png

 

 

Done! You have successfully registered an application. You may reuse this application when going through the exercises that we’ll be using in future blogs and experiments.

 

Now we’ll need to connect the API which means getting a token. The token is proof for Windows Defender ATP that an API call is authenticated and authorized.

 

 

Connecting the API:

  • Copy the text below to PowerShell ISE or to a text editor.

 

# That code get the App Context Token and save it to file name "Latest-token.txt" under the current directory

# Paste below your Tenant ID, App ID and App Secret (App key).

 

$tenantId = 'ece8fbca-9f5a-4ca3-9ce3-52c1ca6eb4d7' ### Paste your own tenant ID here

$appId = '45097602-0cfe-4cc6-925f-9f453233e62c' ### Paste your own app ID here

$appSecret = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890=' ### Paste your own app keys here

 

$resourceAppIdUri = 'https://api.securitycenter.windows.com'

$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"

$authBody = [Ordered] @{

    resource = "$resourceAppIdUri"

    client_id = "$appId"

    client_secret = "$appSecret"

    grant_type = 'client_credentials'

}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop

$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

 

  • Save the script to file. You can name it "Get-Token.ps1".
  • Running this script by pressing F5 will get a token and save it in the working folder under the name "./Latest-token.txt".

 

Note:

If you are getting an error:

\Get-Token.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.

That error indicates that your Powershell execution policy not allowing you to run scripts. You can change the execution policy by running that command in Powershell console:

PS c:\>>Set-ExecutionPolicy unrestricted -Scope CurrentUser

Consider consulting with your system administrator about your organization’s Powershell execution policy.

 

Sanity Check

  • In your browser go to: https://jwt.ms/
  • Copy the token (the content of the Latest-token.txt file).
  • Paste in the top box.
  • Look for the "roles" section. Find the Alert.Read.All role.

 

  • Now let’s gets the alerts, Copy the following text to a new PowerShell Script.

 

# Returns Alerts created in the past 48 hours.

 

$token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1

 

# Get Alert from the last 48 hours. Make sure you have alerts in that time frame.

$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")      

 

# The URL contains the type of query and the time filter we create above

# Read more about other query options and filters here

$url = "https://api.securitycenter.windows.com/api/alerts?`$filter=alertCreationTime ge $dateTime"

 

# Set the WebRequest headers

$headers = @{

    'Content-Type' = 'application/json'

    Accept = 'application/json'

    Authorization = "Bearer $token"

}

 

# Send the webrequest and get the results. 

$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

 

#Extract the alerts from the results. 

$alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json

 

#Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file

$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}   

 

#save the result as json and as csv

$outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"    

$outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"

 

Out-File -FilePath $outputJsonPath -InputObject $alerts

($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation

 

  • Save the file in the same folder you saved the previous script (Get-Token.ps1).
  • You can run the script by right-clicking on the file and choosing "Run with PowerShell" or run it from PowerShell console.
    NOTE: If you are using powershell_ise.exe make sure to change directory to the directory with the scripts.

 

  • You will now see two files (json and csv) created in the same folder as the scripts.
  • The files are the latest alert from your tenant in the past 48 hours.

 

You’re all done! You have just successfully:

  • Created and registered and application
  • Granted permission for that application to read alerts
  • Connected the API
  • Use a PowerShell script to return alerts created in the past 48 hours

 

 

In the next blog, we’ll walk you through updating alert status programmatically. I invite you to suggest more use cases that you’d like for us to blog about, provide feedback, and ask questions about this post!

 

Thanks!

@Haim Goldshtein, security software engineer, WDATP

@Dan Michelson, program manager, WDATP

 

 

2 Replies

Re: WDATP API “Hello World” (or using a simple PowerShell script to pull alerts via WDATP APIs)

This maybe naive since I don't remote, but I never saw anything, as I scrolled through, about the "Defender" Module. It is a great Module and I believe it can be used remotely or at the vary least on a providing server in a small operation?

I us it all the time from Powershell ISE.

Re: WDATP API “Hello World” (or using a simple PowerShell script to pull alerts via WDATP APIs)

Thanks for your feedback.

Happy to hear that you are using the "Defender" module. The "Defender" module covers the AV management. Here, in this blog post, we are taking the first step in encouraging our customers to try and automate WDATP procedures. Will be great to get feedback about that too. We are here for your questions and feedback.