Edit

Share via


Fetch Microsoft Defender XDR incidents

Applies to:

Note

Try our new APIs using MS Graph security API. Find out more at: Use the Microsoft Graph security API - Microsoft Graph | Microsoft Learn.

Note

This action is taken by the MSSP.

There are two ways you can fetch alerts:

  • Using the SIEM method
  • Using APIs

Fetch incidents into your SIEM

To fetch incidents into your SIEM system, you'll need to take the following steps:

  • Step 1: Create a third-party application
  • Step 2: Get access and refresh tokens from your customer's tenant
  • Step 3: allow your application on Microsoft Defender XDR

Step 1: Create an application in Microsoft Entra ID

You'll need to create an application and grant it permissions to fetch alerts from your customer's Microsoft Defender XDR tenant.

  1. Sign in to the Microsoft Entra admin center.

  2. Select Microsoft Entra ID > App registrations.

  3. Click New registration.

  4. Specify the following values:

    • Name: <Tenant_name> SIEM MSSP Connector (replace Tenant_name with the tenant display name)

    • Supported account types: Account in this organizational directory only

    • Redirect URI: Select Web and type https://<domain_name>/SiemMsspConnector(replace <domain_name> with the tenant name)

  5. Click Register. The application is displayed in the list of applications you own.

  6. Select the application, then click Overview.

  7. Copy the value from the Application (client) ID field to a safe place, you will need this in the next step.

  8. Select Certificate & secrets in the new application panel.

  9. Click New client secret.

    • Description: Enter a description for the key.
    • Expires: Select In 1 year
  10. Click Add, copy the value of the client secret to a safe place, you will need this in the next step.

Step 2: Get access and refresh tokens from your customer's tenant

This section guides you on how to use a PowerShell script to get the tokens from your customer's tenant. This script uses the application from the previous step to get the access and refresh tokens using the OAuth Authorization Code Flow.

After providing your credentials, you'll need to grant consent to the application so that the application is provisioned in the customer's tenant.

  1. Create a new folder and name it: MsspTokensAcquisition.

  2. Download the LoginBrowser.psm1 module and save it in the MsspTokensAcquisition folder.

    Note

    In line 30, replace authorzationUrl with authorizationUrl.

  3. Create a file with the following content and save it with the name MsspTokensAcquisition.ps1 in the folder:

    param (
        [Parameter(Mandatory=$true)][string]$clientId,
        [Parameter(Mandatory=$true)][string]$secret,
        [Parameter(Mandatory=$true)][string]$tenantId
    )
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    
    # Load our Login Browser Function
    Import-Module .\LoginBrowser.psm1
    
    # Configuration parameters
    $login = "https://login.microsoftonline.com"
    $redirectUri = "https://SiemMsspConnector"
    $resourceId = "https://graph.windows.net"
    
    Write-Host 'Prompt the user for his credentials, to get an authorization code'
    $authorizationUrl = ("{0}/{1}/oauth2/authorize?prompt=select_account&response_type=code&client_id={2}&redirect_uri={3}&resource={4}" -f
                        $login, $tenantId, $clientId, $redirectUri, $resourceId)
    Write-Host "authorzationUrl: $authorizationUrl"
    
    # Fake a proper endpoint for the Redirect URI
    $code = LoginBrowser $authorizationUrl $redirectUri
    
    # Acquire token using the authorization code
    
    $Body = @{
        grant_type = 'authorization_code'
        client_id = $clientId
        code = $code
        redirect_uri = $redirectUri
        resource = $resourceId
        client_secret = $secret
    }
    
    $tokenEndpoint = "$login/$tenantId/oauth2/token?"
    $Response = Invoke-RestMethod -Method Post -Uri $tokenEndpoint -Body $Body
    $token = $Response.access_token
    $refreshToken= $Response.refresh_token
    
    Write-Host " ----------------------------------- TOKEN ---------------------------------- "
    Write-Host $token
    
    Write-Host " ----------------------------------- REFRESH TOKEN ---------------------------------- "
    Write-Host $refreshToken
    
  4. Open an elevated PowerShell command prompt in the MsspTokensAcquisition folder.

  5. Run the following command: Set-ExecutionPolicy -ExecutionPolicy Bypass

  6. Enter the following commands: .\MsspTokensAcquisition.ps1 -clientId <client_id> -secret <app_key> -tenantId <customer_tenant_id>

    • Replace <client_id> with the Application (client) ID you got from the previous step.
    • Replace <app_key> with the Client Secret you created from the previous step.
    • Replace <customer_tenant_id> with your customer's Tenant ID.
  7. You'll be asked to provide your credentials and consent. Ignore the page redirect.

  8. In the PowerShell window, you'll receive an access token and a refresh token. Save the refresh token to configure your SIEM connector.

Step 3: Allow your application on Microsoft Defender XDR

You'll need to allow the application you created in Microsoft Defender XDR.

You'll need to have Manage portal system settings permission to allow the application. Otherwise, you'll need to request your customer to allow the application for you.

  1. Go to https://security.microsoft.com?tid=<customer_tenant_id> (replace <customer_tenant_id> with the customer's tenant ID.

  2. Click Settings > Endpoints > APIs > SIEM.

  3. Select the MSSP tab.

  4. Enter the Application ID from the first step and your Tenant ID.

  5. Click Authorize application.

You can now download the relevant configuration file for your SIEM and connect to the Microsoft Defender XDR API. For more information, see, Pull alerts to your SIEM tools.

  • In the ArcSight configuration file / Splunk Authentication Properties file, write your application key manually by setting the secret value.
  • Instead of acquiring a refresh token in the portal, use the script from the previous step to acquire a refresh token (or acquire it by other means).

Fetch alerts from MSSP customer's tenant using APIs

For information on how to fetch alerts using REST API, see Pull alerts using REST API.

Use the Microsoft Graph security API - Microsoft Graph | Microsoft Learn

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender XDR Tech Community.