Microsoft 365 Defender

This document describes how to integrate Microsoft 365 Defender with Google Security Operations (Google SecOps).

Integration version: 19.0

Use cases

Integrating Microsoft 365 Defender with Google SecOps can help you solve the following use cases:

  • Automated incident response: use the Google SecOps capabilities to automatically isolate the affected endpoint and initiate a scan for further compromise.

  • Phishing investigation and remediation: use the Google SecOps capabilities to automatically extract relevant information, such as the sender, subject, and attachments, and enrich it with threat intelligence data.

  • Vulnerability management: use the Google SecOps capabilities to automate vulnerability scanning and remediation workflows.

  • Compliance reporting and auditing: use the Google SecOps capabilities to automate the collecting and reporting of security data from Microsoft 365 Defender, simplifying compliance audits, and demonstrating adherence to security standards.

  • Alert prioritization and triage: use the Google SecOps capabilities to analyze alerts from Microsoft 365 Defender and prioritize them based on severity and potential impact.

  • Automated malware analysis: use the Google SecOps capabilities to automatically submit the sample of a malware that Microsoft 365 Defender has detected to a sandbox environment for dynamic analysis.

Before you begin

Before configuring the integration in the Google SecOps platform, complete the following steps:

  1. Create the Microsoft Entra application.

  2. Configure the API permissions for your app.

  3. Create a client secret.

Create the Microsoft Entra application

To create the Microsoft Entra application, complete the following steps:

  1. Sign in to the Azure portal as a user administrator or a password administrator.

  2. Select Microsoft Entra ID.

  3. Go to App registrations > New registration.

  4. Enter the name of the application.

  5. Click Register.

  6. Save the Application (client) ID and Directory (tenant) ID values to use them later when configuring the integration parameters.

Configure the API permissions

To configure the API permissions for the integration, complete the following steps:

  1. In the Azure portal, go to Manage > API Permissions > Add a permission.

  2. In the Request API permissions window, select APIs my organization uses.

  3. Select Microsoft Graph > Application permissions.

  4. Select the following permissions:

    • SecurityAlert.Read.All
    • SecurityIncident.ReadWrite.All

  5. Click Add permissions.

  6. In the Request API permissions window, select APIs my organization uses.

  7. Select Microsoft Threat Protection > Application permissions.

  8. Select the following permission:

    • AdvancedHunting.Read.All

  9. Click Add permissions.

  10. Click Grant admin consent for YOUR_ORGANIZATION_NAME.

    When the Grant admin consent confirmation dialog appears, click Yes.

Create a client secret

To create a client secret, complete the following steps:

  1. Navigate to Certificates and secrets > New client secret.

  2. Provide a description for a client secret and set its expiration deadline.

  3. Click Add.

  4. Save the value of the client secret (not the secret ID) to use it as the Client Secret parameter value when configuring the integration.

    The client secret value is only displayed once.

Integrate Microsoft 365 Defender with Google SecOps

The Microsoft 365 Defender integration requires the following parameters:

Parameter Description
Login API Root Required

The login API root of the Microsoft 365 Defender instance.

The default value is https://login.microsoftonline.com.
Graph API Root Required

The API root of the Microsoft Graph service.

The default value is https://graph.microsoft.com.
API Root Required

The API root of the Microsoft 365 Defender instance.

The default value is https://api.security.microsoft.com.
Tenant ID Required

The Microsoft Entra ID (tenant ID) value of your Microsoft Entra ID account.
Client ID Required

The application (client) ID value of your Microsoft Entra ID account.
Client Secret Required

The client secret value of the Microsoft Entra ID application.
Verify SSL Optional

If selected, the integration verifies that the SSL certificate for connecting to the Microsoft 365 Defender server is valid.

Selected by default.

For instructions about configuring an integration in Google SecOps, see Configure integrations.

You can make changes at a later stage if needed. After you configure an integration instance, you can use it in playbooks. For more information about configuring and supporting multiple instances, see Supporting multiple instances.

Actions

For more information about actions, see Respond to pending actions from your workdesk and Perform a manual action.

Add Comment To Incident

Use the Add Comment To Incident action to add a comment to an incident in Microsoft 365 Defender.

This action doesn't run on Google SecOps entities.

Action inputs

The Add Comment To Incident action requires the following parameters:

Parameter Description
Incident ID Required

The ID of the incident to add the comment to.
Comment Required

The comment to add to the incident.

Action outputs

The Add Comment To Incident action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Add Comment To Incident action can return the following output messages:

Output message Message description
Successfully added comment to incident INCIDENT_ID in Microsoft 365 Defender. The action succeeded.
Error executing action "Add Comment To Incident". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table lists the value for the script result output when using the Add Comment To Incident action:

Script result name Value
is_success True or False

Execute Custom Query

Use the Execute Custom Query action to execute a custom hunting query in Microsoft 365 Defender.

This action doesn't run on Google SecOps entities.

Action inputs

The Execute Custom Query action requires the following parameters:

Parameter Description
Query Required

The query to execute in Microsoft 365 Defender for result filtering.
Max Results To Return Optional

The maximum number of results to return from the query.

The default value is `50`.

Action outputs

The Execute Custom Query action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example shows the JSON result output received when using the Execute Custom Query action:

{"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": ""
    }
]}
Output messages

The Execute Custom Query action can return the following output messages:

Output message Message description

Successfully executed query "QUERY" in Microsoft 365 Defender.

No data was found for the query "QUERY" in Microsoft 365 Defender.

 The action succeeded.
Error executing action "Execute Custom Query". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table lists the value for the script result output when using the Execute Custom Query action:

Script result name Value
is_success True or False

Execute Entity Query

Use the Execute Entity Query action to execute a hunting query that is based on entities in Microsoft 365 Defender.

This action uses a where filter that is based on entities.

This action runs on the following Google SecOps entities:

  • IP Address
  • Host
  • User
  • Hash
  • URL

You can use the Execute Entity Query action to retrieve information that is related to entities, such as retrieve the results from a table and filter the results based on entities.

Unlike the Execute Query action that requires you to use specific formatting, the Execute Entity Query action doesn't use the query input.

When using the Execute Query action to retrieve the alerts that are related to an endpoint, format the | where clause as follows:

AlertInfo | where DeviceName == "Host-1" or IPAddress == "192.0.2.1" | top 100
by Timestamp desc

To retrieve the alerts that are related to an endpoint, the Execute Entity Query action requires you to configure the Table, IP Entity Key, Hostname Entity Key, and Cross Entity Operator parameters as follows:

Parameter AlertInfo value
IP Entity Key IPAddress
Hostname Entity Key DeviceName
Cross Entity Operator OR

To check how many endpoints the provided hashes affect, the Execute Entity Query action requires you to enter the SHA1 value for the File Hash Entity Key parameter.

The Cross Entity Operator only impacts the query when you configure multiple values for the Entity Keys parameter.

Action inputs

The Execute Entity Query action requires the following parameters:

Parameter Description
Table Names Required

A comma-separated list of tables to query in Microsoft 365 Defender.
Time Frame Optional

The time period for the query results.

The default value is Last Hour.

The possible values are as follows:

  • Last Hour
  • Last 6 Hours
  • Last 24 Hours
  • Last Week
  • Last Month
  • Custom
Start Time Optional

The start time for the query results.

If you set the Time Frame parameter to Custom, this parameter is required.
End Time Optional

The end time for the query results.

If you don't set a value and set the Time Frame parameter to Custom, the action sets this parameter to the current time value by default.
Fields To Return Optional

A comma-separated list of fields to include in the results.
Sort Field Optional

The field to sort the results by.

The default value is Timestamp.
Sort Order Optional

The order to sort the results (ascending or descending).

The default value is ASC.

The possible values are as follows:

  • ASC
  • DESC
Max Results To Return Optional

The maximum number of results to return.

The default value is 50.
IP Entity Key Optional

The key to use for filtering by the IP Address entity.
Hostname Entity Key Optional

The key to use for filtering by the Hostname entity.
File Hash Entity Key Optional

The key to use for filtering by the File Hash entity.
User Entity Key Optional

The key to use for filtering by the User entity.
URL Entity Key Optional

The key to use for filtering by the URL entity.
Email Address Entity Key Optional

The key to use for filtering by the Email Address entity. The action accepts the User entity that matches the email regular expression.
Stop If Not Enough Entities Optional

If selected, the action runs if all specified entity types are present.

Selected by default.
Cross Entity Operator Required

The logical operator to use between different entity types in the query.

The default value is OR.

The possible values are as follows:

  • OR
  • AND

Action outputs

The Execute Entity Query action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example shows the JSON result output received when using the Execute Entity Query action:

 {
        "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": ""
  }
Output messages

The Execute Entity Query action can return the following output messages:

Output message Message description

Successfully executed query "QUERY" in Microsoft 365 Defender.

Action wasn't able to build the query, because not enough entity types were supplied for the specified "ENTITY_KEYS". Please disable the "Stop If Not Enough Entities" parameter or provide at least one entity for each specified ENTITY_KEY.

No data was found for the query "QUERY" in Microsoft 365 Defender."

 The action succeeded.
Error executing action "Execute Entity Query". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table lists the value for the script result output when using the Execute Entity Query action:

Script result name Value
is_success True or False

Execute Query

Use the Execute Query action to execute hunting queries in Microsoft 365 Defender.

This action doesn't run on Google SecOps entities.

Action inputs

The Execute Query action requires the following parameters:

Parameter Description
Table Names Required

A comma-separated list of table names to query in Microsoft 365 Defender.
Query Optional

A query to execute.

Use this parameter to provide the | where clause. The time filter, limiting, and sorting are optional.
Time Frame Optional

The time period for the query results.

The default value is Last Hour.

The possible values are as follows:

  • Last Hour
  • Last 6 Hours
  • Last 24 Hours
  • Last Week
  • Last Month
  • Custom
Start Time Optional

The start time for the query results in the ISO 8601 format.

If you set the Time Frame parameter to Custom, this parameter is required.
End Time Optional

The end time for the query results in the ISO 8601 format.

If you don't set a value and set the Time Frame parameter to Custom, the action sets this parameter to the current time value by default.
Fields To Return Optional

A comma-separated list of fields to include in the results.
Sort Field Optional

The field to sort the results by.

The default value is Timestamp.
Sort Order Optional

The order to sort the results (ascending or descending).

The default value is ASC.

The possible values are as follows:

  • ASC
  • DESC
Max Results To Return Optional

The maximum number of results to return.

The default value is 50.

Action outputs

The Execute Query action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Available
Output messages Available
Script result Available
JSON result

The following example shows the JSON result output received when using the Execute Query action:

{"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": ""
    }
]}
Output messages

The Execute Query action can return the following output messages:

Output message Message description

Successfully executed query "QUERY" in Microsoft 365 Defender.

No data was found for the query "QUERY" in Microsoft 365 Defender."

 The action succeeded.
Error executing action "Execute Query". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table lists the value for the script result output when using the Execute Query action:

Script result name Value
is_success True or False

Ping

Use the Ping action to test the connectivity to Microsoft 365 Defender.

The action doesn't run on Google SecOps entities.

Action inputs

None.

Action outputs

The Ping action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
JSON result

The following example shows the JSON result output received when using the Ping action:

Output messages

The Ping action can return the following output messages:

Output message Message description
Successfully connected to the Microsoft 365 Defender server with the provided connection parameters! The action succeeded.
Failed to connect to the Microsoft 365 Defender server! Error is ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.
Script result

The following table lists the value for the script result output when using the Ping action:

Script result name Value
is_success True or False

Update Incident

Use the Update Incident action to update incidents in Microsoft 365 Defender.

Following the API limitations, this action doesn't fail even if you set an invalid username value to the Assign To parameter.

This action doesn't run on Google SecOps entities.

Action inputs

The Update Incident action requires the following parameters:

Parameter Description
Incident ID Required

The ID of the incident to update in Microsoft 365 Defender.
Status Optional

The status to set for the incident in Microsoft 365 Defender.

The default value is Select One.

The possible values are as follows:

  • Select One
  • Active
  • Resolved
Classification Optional

The classification to set for the incident in Microsoft 365 Defender.

The default value is Select One.

The possible values are as follows:

  • Select One
  • False Positive
  • True Positive
Determination Optional

The determination to set for the incident in Microsoft 365 Defender.

This parameter only applies if the Classification parameter value is True Positive.

The default value is Select One.

The possible values are as follows:

  • Select One
  • Not Available
  • Apt
  • Malware
  • Security Personnel
  • Security Testing
  • Unwanted Software
  • Other
Assign To Optional

The user to assign the incident to in Microsoft 365 Defender.

Action outputs

The Update Incident action provides the following outputs:

Action output type Availability
Case wall attachment Not available
Case wall link Not available
Case wall table Not available
Enrichment table Not available
JSON result Not available
Output messages Available
Script result Available
Output messages

The Update Incident action can return the following output messages:

Output message Message description
Successfully updated incident INCIDENT_ID in Microsoft 365 Defender. The action succeeded.
Error executing action "Update Incident". Reason: ERROR_REASON

The action failed.

Check the connection to the server, input parameters, or credentials.

Connectors

For detailed instructions on how to configure a connector in Google SecOps, see Ingest your data (connectors).

Microsoft 365 Defender – Incidents Connector

Use the Microsoft 365 Defender – Incidents Connector to pull information about incidents and their related alerts from Microsoft 365 Defender.

The dynamic list works with an incident name.

Connector limitations

The Microsoft 365 Defender – Incidents Connector uses the API requests with strict API limits. To stabilize the connector, set the Max Incidents To Fetch parameter to 10 and the Run Every parameter to 1 minute. You can still reach the rate limit because the Microsoft Graph API endpoint that is used to fetch alerts only allows 20 requests for every minute.

To prevent data loss at reaching the rate limit, the connector stops processing the current incident and waits for 90 seconds before processing any other incident. In 90 seconds, the rate limit returns to its maximum value and the connector reprocesses the incident that was not properly processed in the previous iteration.

Connector inputs

The Microsoft 365 Defender – Incidents Connector requires the following parameters:

Redirected incidents can be empty in most cases.

Parameter Description
Product Field Name Required

The name of the field where the product name is stored.

The default value is event_type.
Event Field Name Required

The field name used to determine the event name (subtype).

The default value is @odata.type.
Login API Root Required

The login API root of the Microsoft 365 Defender instance.

The default value is https://login.microsoftonline.com.
Graph API Root Required

The API root of the Microsoft Graph service.

The default value is https://graph.microsoft.com.
API Root Required

The API root of the Microsoft 365 Defender instance.

The default value is https://api.security.microsoft.com.
Tenant ID Required

The Microsoft Entra ID (tenant ID) value of your Microsoft Entra ID account.
Client ID Required

The application (client) ID value of your Microsoft Entra ID account.
Client Secret Required

The client secret value of the Microsoft Entra ID application.
Verify SSL Optional

If selected, the integration verifies that the SSL certificate for connecting to the Microsoft 365 Defender server is valid.

Selected by default.
Lowest Severity To Fetch Optional

The lowest severity of incidents to fetch.
Max Hours Backwards Optional

The number of hours before the first connector iteration to retrieve incidents from. This parameter applies to the initial connector iteration after you enable the connector for the first time or the fallback value for an expired connector timestamp.

The default value is 1.
Max Incidents To Fetch Optional

The maximum number of incidents to fetch for every connector iteration.

The default value is 10.
Dynamic List Field Optional

The value that the dynamic list uses for filtering.

The possible values are Incident Name and Alert Name.

The default value is Incident Name.
Incident Status Filter Optional

A comma-separated list of incident statuses to ingest.

The default value is active, inProgress.

The possible values are as follows:

  • active
  • inProgress
  • resolved
  • redirected
Alert Detection Source Filter Optional

A comma-separated list of alert detection sources to ingest, such as antivirus, microsoftDefenderForEndpoint.
Alert Service Source Filter Optional

A comma-separated list of alert service sources to ingest, such as antivirus, microsoftDefenderForEndpoint.
Use whitelist as a blacklist Optional

If selected, the connector uses the dynamic list as a blocklist.

Not selected by default.
Disable Overflow Optional

If selected, the connector ignores the Google SecOps overflow mechanism during alert creation.

Selected by default.
Lowest Alert Severity To Fetch Optional

The lowest severity of alerts to fetch.
Environment Field Name Optional

The name of the field containing the environment name.
Environment Regex Pattern Optional

A regular expression pattern to run on the value found in the Environment Field Name field. This parameter lets you manipulate the environment field using the regular expression logic.

Use the default value .* to retrieve the required raw Environment Field Name value.

If the regular expression pattern is null or empty, or the environment value is null, the final environment result is the default environment.
PythonProcessTimeout Required

The timeout limit in seconds for the Python process that runs the current script.

The default value is 180.
Proxy Server Address Optional

The address of the proxy server to use.
Proxy Username Optional

The proxy username to authenticate with.
Proxy Password Optional

The proxy password to authenticate with.

Connector rules

  • The connector supports proxies.
  • The connector supports the dynamic lists and blocklists.