Ticketing system integration – Alert update API
5 Minutes Low complexity In our last API blog we demonstrated how you can use Windows Defender ATP APIs to pull alerts using a simple PowerShell script. Typical use cases where pulling of alerts using APIs apply to ticketing system and SIEM integration scenarios. As a follow up to that blog, we’re going to demonstrate how you can apply it in two common integration use cases: Create tickets or alert objects in an external system (SIEM, ITSM) after pulling the alerts, and Update tickets or alert objects from an external system and have the changes reflected in Windows Defender ATP In this blog we’ll focus on updating the alert as part of a typical ticketing/SIEM integration. Integration flow The integration flow generally occurs in two steps: ticket creation then ticket update. Ticket/alert creation Windows Defender ATP - Pull alerts from Windows Defender ATP as demonstrated in the “Hello World” blog. External - Create ticket/alert object in the external system. Ticket update External – User updates the ticket/alert object in the external system. Windows Defender ATP - Update the alert in Windows Defender ATP according to changes in the external system. What are the differences from the “Hello World” blog? The app now needs the alert write permission (vs. the alert read permission we used) The customer must create the ticket using the ticketing system API We recommend storing the Windows Defender ATP alert ID as part of the ticket to enable later update of the corresponding Windows Defender ATP alert. The update command we demonstrate here should be called from the ticketing/SIEM system for every relevant change or a scheduled task should pull changes from the ticketing/SIEM system and update WDATP using the update command. Let’s get our hands dirty In this section, we’ll walk you through the following: Step 1: Add the required permission to your application Step 2: Create the ticket/alert from an external system Step 3: Update the Windows Defender ATP alert based on the change done on the external system Step 1 - Add the required permission to the application: With your Global administrator credentials, login to the Azure portal. Azure Active Directory > App registrations. Click the drop-down button and select “All apps”. Choose the application you created in the “Hello World” example. If you used the suggested name, it was “ContosoSIEMConnector”. In the application page choose: Settings > Required permissions > WindowsDefenderATP Check the checkbox near “Read and write all alerts” permission, then click Save. In the “Required permissions” page, select the “Grant permissions” button and then click “Yes”. Done! You have successfully added the required permissions to the application. Step 2 – Create the ticket/alert in the external system: Depending on the external system API or integration tool that you use, this step might be applied in various methods. However, the general idea is to periodically pull new alerts from Windows Defender ATP as demonstrated in the “hello world” blog. For each alert you should call the external system API to create a ticket. We recommend that you store the alert ID in the created object. It will be handy for Windows Defender ATP alert object update later. The following example is an update of the “Hello World” code. It demonstrates how to iterate over the alerts and shows how to get their alert ID. NOTE: Some SIEM platforms allow direct JSON file import. This is out of this blog’s scope. Copy this example to the same folder where you stored the “Hello World” scripts. Name it “Get-Alerts-And-Open-Ticket.ps1”. # Returns Alerts created in the past 4 hours. # Setting a place holder for a code to open a ticket in external ticketing system. $token = .\Get-Token.ps1 $dateTime = (Get-Date).ToUniversalTime().AddHours(-4).ToString("o") $url = "https://api.securitycenter.windows.com/api/alerts?`$filter=alertCreationTime ge $dateTime" $headers = @{ 'Content-Type' = 'application/json' Accept = 'application/json' Authorization = "Bearer $token" } $response = Invoke-RestMethod -Method Get -Uri $url -Headers $headers -ErrorAction Stop #foreach alert, get the alertId and the data that needed to open a ticket and call the ticketing system API to open the ticket foreach ($alert in $response.value){ $alertId = $alert.id $alertTitle = $alert.title #extract the rest of the data relevant to the ticket. # replace the next line with your code to open the ticket using the ticketing system's API [System.Windows.MessageBox]::Show("Alert title - $alertTitle. \nAlert ID - $alertId") } The script will display a message box with the alert title and alert ID. Run the script. You’re welcome to replace the message box code with your own ticketing system ticket creation code. Step 3 – Update the Windows Defender ATP alert according to the ticket/alert change: To simplify the API usage we created the following script called “Alert-Update.ps1”. Store it in the same folder with the other scripts (the same folder we saved the Get-Token.ps1). Alert-Update.ps1 param ( [Parameter(Mandatory=$true)] [string]$alertId, #an input parameter for the alert's ID [ValidatePattern("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$")] #only valid email address formats are allowed [string]$assignedTo, #an input parameter for the email address we want to assign the alert to. [Parameter()] [ValidateSet('New','InProgress','Resolved')] #validate that the input contains valid status value [string]$status, #an input parameter for alert's new status. [Parameter()] [ValidateSet('Unknown','FalsePositive','TruePositive')] #validate that the input contains valid classification value [string]$classification,#an input parameter for alert's new status. [Parameter()] [ValidateSet('NotAvailable','Apt','Malware','SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other' )] #validate that the input contains valid classification value [string]$determination #an input parameter for alert's new status. ) $token = .\Get-Token.ps1 #Execute Get-Token.ps1 script to get the authorization token $url = "https://api.securitycenter.windows.com/api/alerts/$alertId" #Set the url with the current alert ID. $body = @{} if($assignedTo -ne [string]::Empty) { $body.Add("assignedTo",$assignedTo) } if($status -ne [string]::Empty) { $body.Add("status",$status) } if($classification -ne [string]::Empty) { $body.Add("classification",$classification) } if($determination -ne [string]::Empty) { $body.Add("determination",$determination) } $headers = @{ 'Content-Type' = 'application/json' Accept = 'application/json' Authorization = "Bearer $token" } $response = Invoke-WebRequest -Method Patch -Uri $url -Body ($body | ConvertTo-Json) -Headers $headers -ErrorAction Stop if($response.StatusCode -eq 200) #check the response status code { return $true #update ended successfully } else { return $false #update failed } Option 1: Push update Ticketing systems as well as SIEM systems expose extensibility interfaces to enrich the experience with custom flows. You can use the following calls to update the Windows Defender ATP alert according to the ticket changes. For example, if an analyst decides to close the ticket as a false positive. The automation code should call the following command: .\Alert-Update.ps1 -alertId 636845233049028347_-906875643 -classification FalsePositive -status Resolved For cases of alert classification and assignment change use the following command: .\Alert-Update.ps1 -alertId 636845233049028347_-906875643 -classification FalsePositive -assignedTo haim@cotoso.com Option 2: Pull update Instead of integrating the API call into the SIEM or ticketing system, you can schedule a periodical call to collect ticket changes and update the Windows Defender ATP alert. Same is true for webhooks as a callback mechanism. For both you can use the same API calls. Tip for PowerShell newbies – use the PowerShell console Intellisense to browse for different command options. Type the script name and a hyphen to get auto-completion options (see below). Conclusion: Windows Defender ATP open API exposes the building blocks for simple scenarios as well as complex multi-stage integrations. In this example we demonstrated the typical use cases where you can apply the use of APIs to create and update tickets in the context of external tools. In the future we’ll share specific product integration examples. You’re more than welcome to share your experience or integration examples. If you are interested in specific product integration examples, let us know. In the next blog, we’ll walk you through using Windows Defender ATP APIs to isolate machine from the network which can be very handy as a quick response to a high-risk security alert. Thanks! @Haim Goldshtein, security software engineer, Windows Defender ATP @Dan Michelson, program manager, Windows Defender ATPWDATP 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 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 registration. In the registration form: Name - Name your application. Supported account type – leave the default setting. Redirect Uri – leave empty. Click Register The application I created is the authentication entity, just like a service account. I now need to set permissions to my app and save its credential for later use. On your new application page, click API Permissions > Add permission > APIs my organization uses > type WindowsDefenderATP and click on WindowsDefenderATP Note: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear Choose Application permissions > Alert.Read.All > Click on Add permissions: After clicking the Add Permissions button, on the next screen we need to grant consent for the permission to take effect. Press the "Grant admin consent for {your tenant name}" button. As explained, the registered app is an authentication entity with permission to access all alerts for reading. Now I need to get and store the authentication and authorization credentials: Key (application secret), Application ID, and Tenant ID Think of your secret like a password, Application ID as username and Tenant ID as a domain. To get credentials: In your application page, Click Certificate & Secrets Specify a key description and set an expiration for 1 year. Click Add. The application key will appear. IMPORTANT: Copy and store this key in a safe place. Treat it like a password. Get your application ID and your tenant ID: On your application page, go to Overview and copy the following 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 = 'f839b112-d9d7-94d27-9bf6-94542403f21c' ### Paste your own tenant ID here $appId = '94fbf312-ae3f-47f4-8eeb-d375d1299e8f' ### 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 @Ben Alfasi, software engineer, Windows Defender ATP
