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:

Parameter Display Name Type Default Value Is Mandatory Description
API Root String https://api.security.microsoft.com Yes API root of the Microsoft 365 Defender instance.
Tenant ID String N/A Yes Microsoft 365 Defender account tenant ID.
Client ID String N/A Yes Microsoft 365 Defender account client ID.
Client Secret Password Yes Microsoft 365 Defender account client secret.Important Note: Copy the value of the client secret and not the Secret ID.
Verify SSL Checkbox Checked Yes If enabled, verify the SSL certificate for the connection to the Microsoft 365 Defender server is valid.

Actions

Add Comment To Incident

Description

Add comment to incident in Microsoft 365 Defender.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Incident ID Integer N/A Yes Specify the ID of the incident that needs to be updated.
Comment String N/A Yes Specify the comment that needs to be added to the incident.

Run on

This action doesn't run on entities.

Action Results

Script Result
Script Result Name Value Options
is_success is_success=False
is_success is_success=True
Case Wall
Result type Value/Description Type
Output message*

The action should not fail nor stop a playbook execution:

If the 200 status code is reported (is_success=true): "Successfully added comment to incident {id} in Microsoft 365 Defender."

The action should fail and stop a playbook execution:

If a fatal error, like wrong credentials, no connection to the server, other is reported: "Add Comment To Incident". Reason: {0}''.format(error.Stacktrace)

If the 404 status code is reported in the response: "Error executing action "Add Comment To Incident". Reason: incident "{id}" wasn't found in Microsoft 365 Defender.'

If an error message is reported in the response: "Error executing action "Add Comment To Incident". Reason: {error.message}."

 General

Execute Custom Query

Description

Execute a custom hunting query in Microsoft 365 Defender.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Query String N/A Yes

Specify the query that needs to be executed. Use this parameter to provide "where" clauses.

Note: You don't need to provide a limit ("limit" keyword).
Max Results To Return Integer 50 No Specify the number of results to return.

Run on

This action doesn't run on entities.

Action Results

Script Result
Script Result Name Value Options
is_success is_success=False
is_success is_success=True
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
Result type Value/Description Type
Output message*

The action should not fail nor stop a playbook execution:

If the 200 status code is reported and data is available for some queries (is_success=true): "Successfully executed query "{query}" in Microsoft 365 Defender.

If the 200 status code is reported and data is available (is_success=false): "No data was found for the query "{query}" in Microsoft 365 Defender."

The action should fail and stop a playbook execution:

If a fatal error, like wrong credentials, no connection to the server, or other is reported: "Error executing action "Execute Custom Query". Reason: {0}''.format(error.Stacktrace)

If the 400 status code is reported: "Error executing action "Execute Custom Query". Reason: {0}''.format(message from the response)

If the 429 status code is reported: "Error executing action "Execute Custom Query". Reason: Too many queries were executed. Rate limit is reached. Wait for a minute and try again".

 General
Case Wall Table (External Entity)

Table name: Results

All values from the "Results" list.

 General

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:

Table AlertInfo
IP Entity Key IPAddress
Hostname Entity Key DeviceName
Cross Entity Operator OR

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.

Table AlertInfo
File Hash Entity Key SHA1

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

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Table Names String Yes Specify what tables should be queried.
Time Frame DDL

Last Hour

Possible Values:

Last Hour

Last 6 Hours

Last 24 Hours

Last Week

Last Month

Custom

 No Specify a time frame for the results. If "Custom" is selected, you also need to provide "Start Time".
Start Time String No Specify the start time for the results. This parameter is mandatory, if "Custom" is selected for the "Time Frame" parameter. Format: ISO 8601
End Time String No Specify the end time for the results. Format: ISO 8601. If nothing is provided and "Custom" is selected for the "Time Frame" parameter then this parameter will use current time.
Fields To Return String No Specify what fields to return.
Sort Field String Timestamp No Specify what parameter should be used for sorting.
Sort Order DDL

ASC

Possible Values:

ASC

DESC

 No Specify the order of sorting.
Max Results To Return Integer 50 No Specify how many results to return. Default: 50.
IP Entity Key String No Specify what key should be used with IP entities. Please refer to the action documentation for details.
Hostname Entity Key String No Specify what key should be used with Hostname entities. Please refer to the action documentation for details.
File Hash Entity Key String No Specify what key should be used with File Hash entities. Please refer to the action documentation for details.
User Entity Key String No Specify what key should be used with User entities. Please refer to the action documentation for details.
URL Entity Key String No Specify what key should be used with URL entities. Please refer to the action documentation for details.
Email Address Entity Key String No Specify what key should be used with Email Address (User entity with email regex) entities. Please refer to the action documentation for details.
Stop If Not Enough Entities Checkbox True Yes If enabled, action will not start execution, unless all of the entity types are available for the specified ".. Entity Keys". Example: if "IP Entity Key" and "File Hash Entity Key" are specified, but in the scope there are no file hashes then if this parameter is enabled, action will not execute the query.
Cross Entity Operator DDL

OR

Possible Values:

OR

AND

 Yes Specify what should be the logical operator used between different entity types.

Run On

This action runs on the following entities:

  • IP Address
  • Host
  • User
  • Hash
  • URL

Action Results

Script Result
Script Result Name Value Options
is_success is_success=False
is_success is_success=True
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
Result type Value/Description Type
Output message*

The action should not fail nor stop a playbook execution:
if 200 and data is available some(is_success = true): "Successfully executed query "{query}" in Microsoft 365 Defender.

if 200 and data is available (is_success = false): "No data was found for the query "{query}" in Microsoft 365 Defender."

If "Stop If Not Enough Entities" is enabled and not enough entity types are available for the provided "Entity Keys" (is_success=false): Action wasn't able to build the query, because not enough entity types were supplied for the specified ".. Entity Keys". Please disable "Stop If Not Enough Entities" parameter or provide at least one entity for each specified ".. Entity Key".


The action should fail and stop a playbook execution:
if fatal error, like wrong credentials, no connection to server, other: "Error executing action "Execute Query". Reason: {0}''.format(error.Stacktrace)

if 400: "Error executing action "Execute Query". Reason: {0}''.format(message from the response)

If 429: "Error executing action "Execute Query". Reason: Too many queries were executed. Rate limit is reached. Wait for a minute and try again".

if Start Time is empty, when "Time Frame" is "Custom": "Error executing action "Execute Entity Query". Reason: "Start Time" should be provided, when "Custom" is selected in "Time Frame" parameter."

 General

Case Wall Table

(External Entity)

Name: Results

All values from "Results" list.

 General

Execute Query

Description

Execute hunting query in Microsoft 365 Defender.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Table Names String N/A Yes Specify what tables should be queried.
Query String N/A No Specify the query that needs to be executed. Use this parameter to provide |where clauses. Note: you don't need to provide time filter, limiting and sorting.
Time Frame DDL

Last Hour

Possible Values:

Last Hour

Last 6 Hours

Last 24 Hours

Last Week

Last Month

Custom

 No Specify a time frame for the results. If "Custom" is selected, you also need to provide "Start Time".
Start Time String N/A No Specify the start time for the results. This parameter is mandatory, if "Custom" is selected for the "Time Frame" parameter. Format: ISO 8601
End Time String N/A No Specify the end time for the results. Format: ISO 8601. If nothing is provided and "Custom" is selected for the "Time Frame" parameter then this parameter will use current time.
Fields To Return String N/A No Specify what fields to return.
Sort Field String Timestamp No Specify what parameter should be used for sorting.
Sort Order DDL

ASC

Possible Values:

ASC

DESC

 No Specify the order of sorting.
Max Results To Return Integer 50 No Specify how many results to return. Default: 50.

Run On

This action doesn't run on entities.

Action Results

Script Result
Script Result Name Value Options
is_success is_success=False
is_success is_success=True
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
Result type Value/Description Type
Output message*

The action should not fail nor stop a playbook execution:
if 200 and data is available some(is_success = true): "Successfully executed query "{query}" in Microsoft 365 Defender.

if 200 and data is available (is_success = false): "No data was found for the query "{query}" in Microsoft 365 Defender."

The action should fail and stop a playbook execution:
if fatal error, like wrong credentials, no connection to server, other: "Error executing action "Execute Query". Reason: {0}''.format(error.Stacktrace)

if 400: "Error executing action "Execute Query". Reason: {0}''.format(message from the response)

If 429: "Error executing action "Execute Query". Reason: Too many queries were executed. Rate limit is reached. Wait for a minute and try again".

 General

Case Wall Table

(External Entity)

Name: Results

All values from "Results" list.

 General

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
Script Result Name Value Options
is_success is_success=False
is_success is_success=True
Case Wall
Result type Value/Description Type
Output message*

The action should not fail nor stop a playbook execution:
if successful: "Successfully connected to the Microsoft 365 Defender server with the provided connection parameters!"

The action should fail and stop a playbook execution:
if not successful: "Failed to connect to the Microsoft 365 Defender server! Error is {0}".format(exception.stacktrace)

 General

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

Parameter Display Name Type Default Value Is Mandatory Description
Incident ID Integer Yes Specify the id of the incident that needs to be updated.
Status DDL

Select One

Possible Values:

Select One

Active

Resolved

 No Specify what status to set for the incident.
Classification DDL

Select One

Possible Values:

Select One

False Positive

True Positive

 No Specify what classification to set for the incident.
Determination DDL

Select One

Possible Values:

Select One

Not Available

Apt

Malware

Security Personnel Security Testing Unwanted Software Other

 No Specify what determination to set for the incident.
Assign To String No Specify to whom to assign this incident.

Run On

This action doesn't run on entities.

Action Results

Script Result
Script Result Name Value Options
is_success is_success=False
is_success is_success=True
Case Wall
Result type Value/Description Type
Output message*

The action should not fail nor stop a playbook execution:
if 200 (is_success = true): "Successfully updated incident {id} in Microsoft 365 Defender.".

The action should fail and stop a playbook execution:
if fatal error, like wrong credentials, no connection to server, other: "Error executing action "Update Incident". Reason: {0}''.format(error.Stacktrace)

If 404 in the response: "Error executing action "Update Incident". Reason: incident "{id}" wasn't found in Microsoft 365 Defender.'

If "Assign To" is empty and "Status", "Classification", "Determination" have value "Select One': "Error executing action: "Update Incident". Reason: at least one of the parameters should have a value provided."

 General

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:

Parameter Display Name Type Default Value Is Mandatory Description
Product Field Name String event_type Yes Enter the source field name in order to retrieve the Product Field name.
Event Field Name String @odata.type Yes Enter the source field name in order to retrieve the Event Field name.
Environment Field Name String "" No

Describes the name of the field where the environment name is stored.

If the environment field isn't found, the environment is the default environment.
Environment Regex Pattern String .* No

A regex pattern to run on the value found in the "Environment Field Name" field.

Default is .* to catch all and return the value unchanged.

Used to allow the user to manipulate the environment field via regex logic.

If the regex pattern is null or empty, or the environment value is null, the final environment result is the default environment.
Script Timeout (Seconds) Integer 180 Yes Timeout limit for the python process running the current script.
API Root String https://api.security.microsoft.com Yes API root of the Microsoft 365 Defender instance.
Tenant ID String N/A Yes Microsoft 365 Defender account tenant ID.
Client ID String N/A Yes Microsoft 365 Defender account client ID.
Client Secret Password Yes Microsoft 365 Defender account client secret. Important: Copy the value of the client secret and not Secret ID.
Lowest Severity To Fetch String N/A No

Lowest severity that will be used to fetch incidents. Possible values:

Informational, Low, Medium, High.
Max Hours Backwards Integer 1 No Amount of hours from where to fetch incidents.
Dynamic List Field String Incident name No

Field that can be used in the dynamic list for filtering.

Possible values:

  • Incident Name
  • Alert Name

If nothing is provided, connector works with the incident name.
Disable Overflow Checkbox Yes If enabled, the connector will ignore the overflow mechanism.
Max Incidents To Fetch Integer 10 No How many incidents to process per one connector iteration. Maximum is 100.
Incident Status Filter CSV Active, In Progress No

A comma-separated list of incident statuses that need to be ingested.

If nothing is provided, the connector ingests incidents with the active and inProgress status.

Possible values:

  • active
  • inProgress
  • resolved
  • redirected

Note: It's not recommended to ingest redirected incidents because in most situations they will be empty.
Alert Detection Source Filter CSV N/A No

A comma-separated list of detection sources of alerts that need to be ingested.

Note: This is a case sensitive parameter.

Example: antivirus, microsoftDefenderForEndpoint
Alert Service Source Filter CSV N/A No

A comma-separated list of service sources of alerts that need to be ingested.

Note: This is a case sensitive parameter.

Example: antivirus, microsoftDefenderForEndpoint
Use whitelist as a blacklist Checkbox Checked Yes If enabled, dynamic list will be used as a blocklist.
Verify SSL Checkbox Checked Yes If enabled, verify the SSL certificate for the connection to the Microsoft 365 Defender server is valid.
Proxy Server Address String N/A No The address of the proxy server to use.
Proxy Username String N/A No The proxy username to authenticate with.
Proxy Password Password No The proxy password to authenticate with.

Connector Rules

Proxy Support

The connector supports proxy.