Microsoft Defender for Endpoint (Previously Microsoft Windows Defender Advanced Threat Protection (ATP))

There are two methods to ingest Microsoft Defender for Endpoint audit log data.

The existing method makes use of Azure Event Hub, see Configuration - Setup in Azure.

FortiSIEM also offers a new ingest method using the Microsoft Graph API, utilizing the Generic HTTPS Polling feature in FortiSIEM 6.6.0 and later.

This integration uses the Microsoft Graph APIs as of this writing. See Configuring Microsoft Graph Incident API using Generic HTTPS Poller and Configuring Microsoft Graph Alert API using Generic HTTPS Poller.

Configuring Microsoft Graph Incident API using Generic HTTPS Poller or Configuring Microsoft Graph Alert API using Generic HTTPS Poller

The MSDefender 365 Graph Incidents and Alerts APIs for MS365 Defender report data for all Defender services in Azure:

• Microsoft Defender for Endpoint

• Microsoft Defender Vulnerability Management

• Microsoft Defender for Office 365

• Microsoft Defender for Identity

• Microsoft Defender for Cloud Apps

You may need to enable the API to work in your tenant.

Using the Generic HTTPS Poller feature, we have two pre-built integrations for the MS365 Defender API endpoints:

• https://graph.microsoft.com/v1.0/security/incidents
  

  Reference: https://learn.microsoft.com/en-us/graph/api/security-list-incidents?view=graph-rest-1.0&tabs=http
  

• https://graph.microsoft.com/v1.0/security/alerts_v2
  

  Reference: https://learn.microsoft.com/en-us/graph/api/security-list-alerts_v2?view=graph-rest-1.0&tabs=http

You will create two credentials using the "HTTPS Advanced" protocol, each representing the API call to each endpoint. There are two pre-defined definition files that you can import from this documentation. Use the following links for complete setup instructions.

• Setup FortiSIEM credential to call the MS365 Defender Graph Incidents API Endpoint

• Setup FortiSIEM to call the MS365 Defender Graph Alerts_v2 API Endpoint

Main Topics:

• Configuration

• Sample Events

• Legacy Configuration

Configuration

The following Configuration Options are available:

• Configuring Microsoft Graph Incident API using Generic HTTPS Poller
  

  Note: For general information on Generic HTTPS Poller, see Generic Log API Poller (HTTPS Advanced) Integration.
  

  • Setup in Azure

  • Setup FortiSIEM Credential to call the MS365 Defender Graph Incidents API Endpoint

• Configuring Microsoft Graph Alert API using Generic HTTPS Poller
  

  Note: For general information on Generic HTTPS Poller, see Generic Log API Poller (HTTPS Advanced) Integration.
  

  • Setup in Azure

  • Setup FortiSIEM to call the MS365 Defender Graph Alerts_v2 API Endpoint
    

• Configuration via Azure Event Hub

  • Azure Event Hub Configuration

  • Configuration in FortiSIEM

  • Microsoft Defender for Endpoint Configuration

Configuring Microsoft Graph Incident API using Generic HTTPS Poller

To configure Microsoft Graph Incident API, you will need to perform setup in Azure and in FortiSIEM by taking the following steps.

• Setup in Azure

• FortiSIEM credential to call the MS365 Defender Graph Incidents API endpoint

Setup in Azure

Take the following steps to generate credential for the API. This process is the same for the Incident API and Alert API. If this setup was completed for either API, it does not need to be repeated again. In this situation, go to Setup in FortiSIEM for the respective API (Incident, Alert).

1. Sign in to the Azure Portal.

2. Navigate to Azure Active Directory > App registrations.

3. Click New registration.

4. Select the new App, and select the Overview tab.

5. Get the Application (client) ID and the Directory (tenant) ID, and save it. It will be used in Setup in FortiSIEM.
   

   
   

6. Click API permissions > Add a permission, and select Microsoft Graph. This adds permission of Microsoft Threat Protection > Application Permission > SecurityAlert.Read.All and SecurityIncident.Read.All to allow this App to access incident/alert API.
   

   
   

7. Click API permissions > Grant admin consent for Default Directory, and click Yes to granted admin consent for the requested permissions.

8. Navigate to Certificates & secrets > Client secrets, and click New client secret to generate a new client secret.
   

   

9. Record the value for Setup in FortiSIEM.
   

   Proceed with Setup FortiSIEM Credential to call the MS365 Defender Graph Incidents API Endpoint or Setup FortiSIEM to call the MS365 Defender Graph Alerts_v2 API Endpoint.
   

Setup FortiSIEM Credential to call the MS365 Defender Graph Incidents API Endpoint

To configure the Microsoft Incident API to FortiSIEM, take the following steps.

Create a New Device/Application

1. Navigate to ADMIN > Device Support > Devices/Apps.

2. Click New.

3. From the Device/Application Type Definition dialog box, take the following steps.

   1. From the Category drop-down list, select Device.

   2. In the Vendor field, enter "WindowsDefenderIncident".

   3. In the Model field, enter "Windows Defender".

   4. In the Version field, enter the version number, for example, "1".

   5. From the Device/App Group drop-down list, select Server.

   6. From the Access Protocol drop-down list, remove SSH, SNMP, and TELNET.

   7. From the Access Protocol drop-down list, select HTTPS Advanced.

   8. Click Save.

Create the Credentials Configuration

1. Navigate to ADMIN > Setup > Credentials.

2. Under Step 1: Enter Credentials, click New.

3. In the Name field, enter a name, for example "Windows Defender Incident".

4. From the Device Type drop-down list, select the device type you just created in Create a New Device/Application.

5. From the Authentication drop-down list, select Oauth2.0.

6. Download the following file: MicrosoftWindowsDefenderIncidentAPI_http_advanced_definition.json.

7. Click Import Definition.

8. Select the file you just downloaded from step 6, and click Import.

9. Click Yes to overwrite.

10. Click on the General Parameters icon, and take the following steps.

    1. In the Host Name field, confirm the information is "https://graph.microsoft.com".

    2. In the URI Stem field, confirm the input is "/v1.0/security/incidents".

    3. From the HTTP Method drop-down list, the selection should be GET.

    4. The Disable SSL Certificate Check check box should be unchecked.

    5. The JSON Response Log Key field should be "value".

    6. The Log Header field should be "Microsoft 365 Defender Incident".

    7. Click OK.

11. Click the Authentication Parameters icon, and take the following steps.

    1. With the General tab selected, take the following steps.

       1. In the Access Token URL field, enter "https://login.microsoftonline.com/{Tenant ID}/oauth2/v2.0/token" where {Tenant ID} is the tenant ID you recorded from Setup in Azure.

       2. In the Client Id field, enter the Client ID you recorded from Setup in Azure.

       3. In the Client Secret field, enter the client secret you recorded from Setup in Azure.

       4. Click OK.

    2. Click Save.

Create the Credentials Mapping

1. Under Step 2: Enter IP Range to Credential Associations, click New.

2. From the Device Credential Mapping Definition dialog box, take the following steps.

   1. In the IP/Host Name field, enter "graph.microsoft.com".

   2. From the Credentials drop-down list, select the credential you just created.

   3. Click Save.

Test the Credential

1. Ensure the credentials mapping you just created is selected. If not, select it.

2. Under Step 2: Enter IP Range to Credentials Association, click the Test drop-down list, and select Test Connectivity without Ping.
   

   If successful, the new job will appear in the ADMIN > Setup Pull Events table. Events can then be queried in ANALYTICS.
   

   If you encounter an error, refer to Common Errors for additional information that may help you resolve the issue.

Configuring Microsoft Graph Alert API using Generic HTTPS Poller

To configure Microsoft Graph Alert API, you will need to perform setup in Azure and in FortiSIEM by taking the following steps. If you have already done the setup in Azure for the Incident API, you can skip Setup in Azure, and proceed immediately to Setup FortiSIEM to call the MS365 Defender Graph Alerts_v2 API Endpoint.

• Setup in Azure

• Setup FortiSIEM to call the MS365 Defender Graph Alerts_v2 API Endpoint

Setup FortiSIEM to call the MS365 Defender Graph Alerts_v2 API Endpoint

To configure the Microsoft Alert API to FortiSIEM, take the following steps.

Create a New Device/Application

1. Navigate to ADMIN > Device Support > Devices/Apps.

2. Click New.

3. From the Device/Application Type Definition dialog box, take the following steps.

   1. From the Category drop-down list, select Device.

   2. In the Vendor field, enter "WindowsDefenderAlert".

   3. In the Model field, enter "Windows Defender".

   4. In the Version field, enter the version number, for example, "1".

   5. From the Device/App Group drop-down list, select Server.

   6. From the Access Protocol drop-down list, remove SSH, SNMP, and TELNET.

   7. From the Access Protocol drop-down list, select HTTPS Advanced.

   8. Click Save.

Create the Credentials Configuration

1. Navigate to ADMIN > Setup > Credentials.

2. Under Step 1: Enter Credentials, click New.

3. In the Name field, enter a name, for example "Windows Defender Alert".

4. From the Device Type drop-down list, select the device type you just created in Create a New Device/Application.

5. From the Authentication drop-down list, select Oauth2.0.

6. Download the following file: MicrosoftWindowsDefenderAlertAPI_http_advanced_definition.json.

7. Click Import Definition.

8. Select the file you just downloaded from step 6, and click Import.

9. Click Yes to overwrite.

10. Click on the General Parameters icon, and take the following steps.

    1. In the Host Name field, confirm the information is "https://graph.microsoft.com".

    2. In the URI Stem field, confirm the input is "/v1.0/security/alerts_v2".

    3. From the HTTP Method drop-down list, the selection should be GET.

    4. The Disable SSL Certificate Check check box should be unchecked.

    5. The JSON Response Log Key field should be "value".

    6. The Log Header field should be "Microsoft 365 Defender Alert".

    7. Click OK.

11. Click the Authentication Parameters icon, and take the following steps.

    1. With the General tab selected, take the following steps.

       1. In the Access Token URL field, enter "https://login.microsoftonline.com/{Tenant ID}/oauth2/v2.0/token" where {Tenant ID} is the tenant ID you recorded from Setup in Azure.

       2. In the Client Id field, enter the Client ID you recorded from Setup in Azure.

       3. In the Client Secret field, enter the client secret you recorded from Setup in Azure.

       4. Click OK.

    2. Click Save.

Create the Credentials Mapping

1. Under Step 2: Enter IP Range to Credential Associations, click New.

2. From the Device Credential Mapping Definition dialog box, take the following steps.

   1. In the IP/Host Name field, enter "graph.microsoft.com".

   2. From the Credentials drop-down list, select the credential you just created.

   3. Click Save.

Test the Credential

1. Ensure the credentials mapping you just created is selected. If not, select it.

2. Under Step 2: Enter IP Range to Credentials Association, click the Test drop-down list, and select Test Connectivity without Ping.
   

   If successful, the new job will appear in the ADMIN > Setup Pull Events table. Events can then be queried in ANALYTICS.
   

   If you encounter an error, refer to Common Errors for additional information that may help you resolve the issue.

Configuration via Azure Event Hub

To configure Microsoft Defender for Endpoint event forwarding to Azure event hub, you will be taking the following general actions.

1. Create an Event Hub Namespace and Event Hub if one does not already exist.

2. Create SAS Policy and generate primary SAS key for authentication.

3. Record the Event Hub Name Space, Event Hub Name, SAS Policy Name, Primary Key, and consumer group for FortiSIEM configuration/authentication.

4. Configure FortiSIEM for Azure Event hub integration and do test Pull.

5. Configure Microsoft Defender for Endpoint raw data streaming to allow event forwarding to Azure Event Hub created earlier.

6. Confirm Raw events are parsed.

Take the steps here to configure Microsoft Defender for Endpoint.

• Azure Event Hub Configuration

• Configuration in FortiSIEM

• Microsoft Defender for Endpoint Configuration

Azure Event Hub Configuration

Create an Event Hub Namespace and Event Hub

Complete these steps in the Azure Portal:

Step 1: Create a Resource Group in Azure

Note: If you already have a Resource Group to use, skip this section

A resource group is a logical collection of Azure resources. All resources are deployed and managed in a resource group. To create a resource group:

1. Login to the Azure portal: https://portal.azure.com/
2. Click Resource groups in the left navigation pane.
3. Click Add.
4. For Subscription, select the name of the Azure subscription in which you want to create the resource group.
5. Enter a unique name for the resource group, The system immediately checks to see if the name is available in the currently selected Azure subscription.
6. Select a Region for the resource group.
7. Click Review + Create.
8. Click Create on the Review + Create page.

Note: In the example used in Step 2, a Resource Group called fsm1 was created.

Step 2: Create an Event Hub Namespace

An Event Hub namespace provides a unique scoping container, referenced by its fully-qualified domain name, in which you create one or more event hubs. To create a namespace in your resource group using the portal, complete the following steps:

1. In the Azure portal, click Create a resource at the top left of the screen.

   

2. In the “Search the Market text box, enter Select All services in the left menu, select star (*) next to Event Hubs, and then click the Create button in the ANALYTICS category.

   

3. On the Create namespace page, complete the following steps:
   1. Enter a name for the namespace. The system immediately checks to see if the name is available.
   2. Choose the pricing tier (Basic or Standard).
   3. Select the subscription in which you want to create the namespace.
   4. Select a location for the namespace.
   5. Click Create. You may have to wait a few minutes for the system to fully provision the resources.

      

4. Refresh the Event Hubs page to see the event hub namespace. You can check the status of the event hub creation in the alerts.
5. Select the namespace. You see the home page for your Event Hubs Namespace in the portal.

Step 3: Create an Event Hub

To create an event hub within the namespace, follow these steps:

1. In the Event Hubs Namespace page, click Event Hubs in the left menu.

   

2. At the top of the window, click + Event Hub.
3. Enter a name for your event hub, then click Create.

   

4. You can check the status of the event hub creation in alerts. After the event hub is created, you see it in the list of event hubs.

Step 4: Configure an Event Hub Namespace

1. Select an event hub namespace and go to Shared access policies, and then click +Add. Enter the Policy name, check the Manage box, and then click Create.

   

2. Select one of the Shared Access policies just created.
3. The Azure Python SDK needs the SAS Policy name (defined in step 4.1) and the Primary key when creating the credential in FortiSIEM. Copy the primary key and policy name to a text editor for later use.

   

   Note: When the event hub namespace is created, Azure will also create a default Shared Access Policy named RootManageSharedAcessKey.

4. Select an event hub namespace and go to Event Hubs.
5. Select an event hub and go to Consumer group. You can click +Consumer group or use default group name $default.

Note: If you have selected Basic (1 Consumer Group), then there will be no option to add a another Consumer group.

Configuration in FortiSIEM

Complete these steps in the FortiSIEM UI:

1. Go to the ADMIN > Setup > Credentials tab.
2. In Step 1: Enter Credentials:
   1. Follow the instructions in "Setting Credentials" in the User's Guide to create a new credential.
   2. Enter these settings in the Access Method Definition dialog box and click Save:

      Settings	Description
      Name	Enter a name for the credential
      Device Type	Microsoft Azure Event Hub
      Access Protocol	AZURE PYTHON SDK
      Pull Interval	The interval in which FortiSIEM will pull events from Azure Event Hub. Default is 5 minutes.
      Event Hub Namespace	The name of the Azure event hub namespace
      Event Hub Name	The name of the Azure event hub.
      SAS Policy Name	Shared Access (SAS) Policy Name
      Primary Key	The name of the primary key
      Consumer Group	The name of the consumer group
      Description	Description of the device

      Based on the example screenshots, this is the configuration in FortiSIEM:

      

3. In Step 2: Enter IP Range to Credential Associations, click New.
   1. Enter a host name, an IP, or an IP range in the IP/Host Name field. For this integration, enter "azure.com".
   2. Select the name of your Azure event hub credential from the Credentials drop-down list.
   3. Click Save.

      

4. Click the Test drop-down list and select Test Connectivity to test the connection to Azure event hub.
5. To see the jobs associated with Azure, select ADMIN > Setup > Pull Events.
6. To see the received events select ANALYTICS, then enter "Azure" in the search box.

Note: Azure services must be configured to write to the Event Hub before there are any events to be collected.

Microsoft Defender for Endpoint Configuration

For the latest Microsoft Defender for Endpoint information, see https://docs.microsoft.com/en-us/microsoft-365/security/defender/streaming-api-event-hub?view=o365-worldwide.

Ensure the following steps have been taken before proceeding.

1. An event hub has been created in your tenant.

2. Your contributor permissions has been configured.
   Note: If it hasn't, log in to your Azure tenant, navigate to Subscriptions > Your subscription > Resource Providers > Register to Microsoft.insights, and configure your contributor permissions.

After your event hub namespace has been created, take the following actions.

1. Define the user who will be logging into Microsoft 365 Defender as Contributor.

2. If you are connecting to an application, add the App Registration Service Principal as Reader, Azure Event Hub Data Receiver (this can also be done at Resource Group or Subscription level) by navigating to Event hubs namespace > Access control (IAM) > Add and verifying under Role assignments.

Enable raw data streaming by taking the following steps.

1. Log in to the Microsoft 365 Defender as a Global Administrator or Security Administrator.

2. Go to the Data export settings page in the Microsoft Defender portal.

3. Click on Add data export settings.

4. Choose a name for your new settings.

5. Choose Forward events to Azure Event Hubs.

6. Type your Event Hubs name and your Event Hubs resource ID.

   To get your Event Hubs resource ID, go to your Azure Event Hubs namespace page on Azure > properties tab > copy the text under Resource ID.
   

   
   

7. Choose the events you want to stream and click Save.
   

   

   On the next pull interval, you should see ingested Defender for Endpoint data.
   

   Sample Events
   

   {"category":"AdvancedHunting-AlertInfo","operationName":"Publish","properties":{"AlertId":"da637801291442337370_2831234","AttackTechniques":"[\"Ingress Tool Transfer (T1105)\",\"Deobfuscate/Decode Files or Information (T1140)\",\"Signed Script Proxy Execution (T1216)\",\"Signed Binary Proxy Execution (T1218)\",\"CMSTP (T1218.003)\",\"InstallUtil (T1218.004)\",\"Mshta (T1218.005)\",\"Regsvr32 (T1218.010)\",\"Rundll32 (T1218.011)\",\"XSL Script Processing (T1220)\"]","Category":"Execution","DetectionSource":"EDR","MachineGroup":null,"ServiceSource":"Microsoft Defender for Endpoint","Severity":"Low","Timestamp":"2022-02-10T22:29:51.4127262Z","Title":"Use of living-off-the-land binary to run malicious code"},"tenantId":"cdf65b83-41f2-4c0e-97ee-11111111111","time":"2022-02-10T22:32:24.5796030Z"}

[Legacy] Microsoft Defender for Endpoint (Previously Microsoft Windows Defender Advanced Threat Protection (ATP) )

Note: This is a Legacy configuration.

As of November 2021, Microsoft has retired the Microsoft Defender ATP SIEM APIs. Defender ATP has also been relabeled as “Microsoft Defender for Endpoint”. All integrations using the SIEM APIs will cease to function after the Microsoft Defender for Endpoint SIEM API Deprecation date of April 1st, 2022.

Please follow the configuration guide to configure Defender for Endpoint event forwarding to Azure event hub.

LEGACY

• Integration Points
• Configuring Windows Defender for FortiSIEM REST API Access
• Configuring FortiSIEM for Windows Defender ATP REST API Access

Integration Points

Protocol	Information Discovered	Used For
Windows Defender API REST API		Security and Compliance

Configuring Windows Defender for FortiSIEM REST API Access