Microsoft 365 Defender

Integration version: 17.0

Use cases

This integration applies to the following use cases:

1. Perform threat hunting actions.
2. Perform ingestion of the incidents.
3. Perform triaging action (Update Incident).

Prerequisites

Make sure that you complete all the prerequisite steps before configuring the integration.

Create and configure the Azure AD application

1. Sign in to the Azure portal as a user administrator or a password administrator.
2. Go to Azure Active Directory > App registrations > New registration.
3. In the registration form, enter a name for your application and then click Register.
4. In the Overview tab, copy the Application (client) ID and Directory (tenant) ID values to use them later when configuring the integration.

Configure the application and API permissions

1. Go to Manage > API Permissions.
2. Click Add a permission.
3. In the APIs my organization uses column, select Microsoft Threat Protection.
4. Select Application Permissions.
5. Select the AdvancedHunting.Read.All permission.
6. Click Add permissions.
7. In the APIs my organization uses column, select Microsoft Graph.
8. Select Application Permissions.
9. Select the following permissions:
   • SecurityAlert.Read.All
   • SecurityIncident.ReadWrite.All
10. Click Add permissions.

Configure client secret

1. Go to Manage > Certificates and secrets.
2. Click New client secret.
3. Create a new client secret.
   Make sure to copy the value of the client secret (not the Secret ID) to use it as a Client Secret parameter when configuring the integration.

Configure Microsoft 365 Defender integration in Google Security Operations SOAR

For detailed instructions on how to configure an integration in Google Security Operations SOAR, see Configure integrations.

Integration parameters

Use the following parameters to configure the integration:

Actions

Add Comment To Incident

Description

Add comment to incident in Microsoft 365 Defender.

Parameters

Run on

This action doesn't run on entities.

Action Results

Script Result

Case Wall

Execute Custom Query

Description

Execute a custom hunting query in Microsoft 365 Defender.

Parameters

Run on

This action doesn't run on entities.

Action Results

Script Result

JSON Result

{"Results": [
    {
        "Timestamp": "2021-04-12T07:25:00Z",
        "AlertId": "fa7a318954-6c4c-eaab-3200-08d8fd82af35",
        "Title": "CC_Sensitive information",
        "Category": "InitialAccess",
        "Severity": "Medium",
        "ServiceSource": "Microsoft Defender for Office 365",
        "DetectionSource": "Microsoft Defender for Office 365",
        "AttackTechniques": ""
    }
]}

Case Wall

Execute Entity Query

Description

Execute a hunting query based on entities in Microsoft 365 Defender. Note: this action prepares a where filter based on entities. Please refer to the documentation for more details. Supported entities: IP, Host, User, Hash, URL.

How to work with action parameters

This action gives an ability to easily retrieve information related to entities. For example, it's possible to solve the use case, where you want to see the results from a table filtered based on entities.

In order to retrieve the alerts related to endpoint via "Execute Query", the |where clause would need to look like this: AlertInfo | where DeviceName == "Host-1" or IPAddress == "10.0.0.1" | top 100 by Timestamp desc

In order to solve the same problem using "Execute Entity Query" action, you need to fill out the action parameters in the following way:

All of the other fields can be left empty.

If the use case is to see how many endpoints were affected by the provided hashes, then the configuration of the "Execute Entity Query" will have the following look.

"Cross Entity Operator" in this situation won't have an impact, because it only affects the query, when multiple "Entity Keys" are provided.

Parameters

Run On

This action runs on the following entities:

• IP Address
• Host
• User
• Hash
• URL

Action Results

Script Result

JSON Result

 {
        "Timestamp": "2021-04-12T07:25:00Z",
        "AlertId": "fa7a318954-6c4c-eaab-3200-08d8fd82af35",
        "Title": "CC_Sensitive information",
        "Category": "InitialAccess",
        "Severity": "Medium",
        "ServiceSource": "Microsoft Defender for Office 365",
        "DetectionSource": "Microsoft Defender for Office 365",
        "AttackTechniques": ""
  }

Case Wall

Execute Query

Description

Execute hunting query in Microsoft 365 Defender.

Parameters

Run On

This action doesn't run on entities.

Action Results

Script Result

JSON Result

{"Results": [
    {
        "Timestamp": "2021-04-12T07:25:00Z",
        "AlertId": "fa7a318954-6c4c-eaab-3200-08d8fd82af35",
        "Title": "CC_Sensitive information",
        "Category": "InitialAccess",
        "Severity": "Medium",
        "ServiceSource": "Microsoft Defender for Office 365",
        "DetectionSource": "Microsoft Defender for Office 365",
        "AttackTechniques": ""
    }
]}

Case Wall

Ping

Description

Test connectivity to Microsoft 365 Defender with parameters provided at the integration configuration page in the Google Security Operations SOAR Marketplace tab.

Run On

The action doesn't run on entities, nor has mandatory input parameters.

Action Results

Script Result

Case Wall

Update Incident

Description

Update incident in Microsoft 365 Defender.

Action Nuance

Parameter "Assign To" will not fail, even if invalid analyst name is specified. This is an API limitation.

Parameters

Run On

This action doesn't run on entities.

Action Results

Script Result

Case Wall

Connector

Microsoft 365 Defender - Incidents Connector

Description

Pull information about incidents and related alerts from Microsoft 365 Defender.

To accurately track incidents updates, make sure that you've granted the Microsoft Graph permissions to your app. For more information, see How to get Client ID and Client Secret.

Connector changes implemented to integration version 6.0

Version 6.0 of the integration brings a major update to how the connector works. We introduced support for a use case where incidents can be updated with new alerts. To add this support, the internal logic of the connector has been redesigned, which can cause regression problems, when upgrading from version 5.0.

To support incidents updates, we introduce an additional Microsoft Graph API to the connector. Hence, you need to add the SecurityAlert.Read.All permissions for the Microsoft Graph product to your app in the Azure portal. Without it, the connector will not work properly.

Microsoft Graph API was introduced because the native API for Microsoft 365 Defender is limited to return only 150 alerts per incident, but there can be significantly more alerts than that.

Data coming from Microsoft Graph API has a different, improved structure with more meaningful entities. You need to update the mapping when updating to version 6.0. In addition, we added support for different filtering options at the incident level and at the alert level.

Known issues

If you upgrade the integration version from 5.0 to 6.0:

• You can get duplicated Google Security Operations SOAR alerts in the first iterations of the connector. It is recommended not to set the Max Hours Backwards parameter to big values to reduce the probability of getting a duplicate. This is caused by the changes that are introduced to track incidents updates.

• The structure of the Google Security Operations SOAR event (Evidence event appeared) was updated, so you might need to revisit the playbooks.

Rate limit

API requests used in this connector have strict API limits. To make the connector stable, it is recommended to set the Max Incidents To Fetch parameter to 10 and one iteration should occur once a minute. Even with this configuration, you can still reach the rate limit because the Microsoft Graph API endpoint that is used to fetch alerts only allows 20 requests per minute.

To prevent data loss, the connector has a built-in mechanism that forces it to stop processing an incident, if you reach the rate limit. The connector waits for 90 seconds before processing any other incident. During this time, the limit will return to its maximum and the incident that was not properly processed in the previous iteration will be processed again.

Configure Microsoft 365 Defender - Incidents Connector on Google Security Operations SOAR

For detailed instructions on how to configure a connector in Google Security Operations SOAR, see Configuring the connector.

Connector parameters

Use the following parameters to configure the connector:

Connector Rules

Proxy Support

The connector supports proxy.