Microsoft 365 Defender v1.2.0

About the connector

Microsoft 365 Defender is a unified platform for preventative protection, post-breach detection, automated investigation, and response. This connector facilitates the automated operations related to indicators such as files, machines, IP, Domain, or actor.

This document provides information about the Microsoft 365 Defender Connector, which facilitates automated interactions, with a Microsoft 365 Defender server using FortiSOAR™ playbooks. Add the Microsoft 365 Defender Connector as a step in FortiSOAR™ playbooks and perform automated operations with Microsoft 365 Defender.

Version information

Connector Version: 1.2.0

FortiSOAR™ Version Tested on: 7.6.0-5012

Microsoft 365 defender Version Tested on: Cloud Instance

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.2.0

Following enhancements have been made to the Microsoft 365 Defender Connector in version 1.2.0:

• The new parameter Fetch Incidents Since under Configurations, in Data Ingestion, replaces the old parameter Pull Incidents which are Created or Updated in Past X Minutes.
• In the action Update Incident, the conditional parameter associated with Classification has been renamed to Determination to better convey its purpose.
• Added a new parameter Filter Query in the action Get Incidents List.
• Fixed the error related to API rate limit.

NOTE: To use the new Data Ingestion features, reconfigure the connector and data ingestion. To change the default alert mapping for ingestion, refer to the Configuration step of the Data Ingestion section.

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the yum command as a root user to install the connector:

yum install cyops-connector-microsoft-365-defender

Prerequisites to configuring the connector

• You must have the URL of Microsoft 365 Defender server to which you connect and perform automated operations and credentials to access that server.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the Microsoft 365 Defender server.

Minimum Permissions Required

• For information on permissions for various access types, refer to Getting Access Tokens section.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Microsoft 365 Defender connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations:

operation: Get Incidents List

Input parameters

Output

The output contains the following populated JSON schema:

{
    "@odata.context": "",
    "value": [
        {
            "incidentId": "",
            "incidentUri": "",
            "redirectIncidentId": "",
            "incidentName": "",
            "createdTime": "",
            "lastUpdateTime": "",
            "assignedTo": "",
            "classification": "",
            "determination": "",
            "status": "",
            "severity": "",
            "tags": [],
            "comments": [],
            "alerts": [
                {
                    "alertId": "",
                    "providerAlertId": "",
                    "incidentId": "",
                    "serviceSource": "",
                    "creationTime": "",
                    "lastUpdatedTime": "",
                    "resolvedTime": "",
                    "firstActivity": "",
                    "lastActivity": "",
                    "title": "",
                    "description": "",
                    "category": "",
                    "status": "",
                    "severity": "",
                    "investigationId": "",
                    "investigationState": "",
                    "classification": "",
                    "determination": "",
                    "detectionSource": "",
                    "detectorId": "",
                    "assignedTo": "",
                    "actorName": "",
                    "threatFamilyName": "",
                    "mitreTechniques": [],
                    "devices": [],
                    "entities": [
                        {
                            "entityType": "",
                            "evidenceCreationTime": "",
                            "verdict": "",
                            "remediationStatus": "",
                            "accountName": "",
                            "userSid": "",
                            "aadUserId": "",
                            "userPrincipalName": ""
                        }
                    ]
                }
            ]
        }
    ]
}

operation: Get Incident Details

Input parameters

Output

The output contains the following populated JSON schema:

{
    "@odata.context": "",
    "incidentId": "",
    "incidentUri": "",
    "redirectIncidentId": "",
    "incidentName": "",
    "createdTime": "",
    "lastUpdateTime": "",
    "assignedTo": "",
    "classification": "",
    "determination": "",
    "status": "",
    "severity": "",
    "tags": [],
    "comments": [],
    "alerts": [
        {
            "alertId": "",
            "providerAlertId": "",
            "incidentId": "",
            "serviceSource": "",
            "creationTime": "",
            "lastUpdatedTime": "",
            "resolvedTime": "",
            "firstActivity": "",
            "lastActivity": "",
            "title": "",
            "description": "",
            "category": "",
            "status": "",
            "severity": "",
            "investigationId": "",
            "investigationState": "",
            "classification": "",
            "determination": "",
            "detectionSource": "",
            "detectorId": "",
            "assignedTo": "",
            "actorName": "",
            "threatFamilyName": "",
            "mitreTechniques": [],
            "devices": [],
            "entities": [
                {
                    "entityType": "",
                    "evidenceCreationTime": "",
                    "verdict": "",
                    "remediationStatus": "",
                    "accountName": "",
                    "userSid": "",
                    "aadUserId": "",
                    "userPrincipalName": ""
                }
            ]
        }
    ]
}

operation: Update Incident

Input parameters

Output

The output contains the following populated JSON schema:

{
    "status": "",
    "assignedTo": "",
    "classification": "",
    "determination": "",
    "tags": [],
    "comments": [
        {
            "comment": "",
            "createdBy": "",
            "createdTime": ""
        }
    ]
}

operation: Advanced Hunting

Input parameters

Output

The output contains the following populated JSON schema:

{
    "Stats": {
        "ExecutionTime": "",
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": "",
                    "misses": "",
                    "total": ""
                },
                "disk": {
                    "hits": "",
                    "misses": "",
                    "total": ""
                }
            },
            "cpu": {
                "user": "",
                "kernel": "",
                "total cpu": ""
            },
            "memory": {
                "peak_per_node": ""
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": "",
                "table_size": ""
            }
        ]
    },
    "Schema": [
        {
            "Name": "",
            "Type": ""
        }
    ],
    "Results": [
        {
            "Timestamp": "",
            "FileName": "",
            "InitiatingProcessFileName": ""
        },
        {
            "Timestamp": "",
            "FileName": "",
            "InitiatingProcessFileName": ""
        }
    ]
}

Included playbooks

The Sample - Microsoft 365 Defender - 1.2.0 playbook collection comes bundled with the Microsoft 365 Defender connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Microsoft 365 Defender connector.

• > Microsoft 365 Defender > Fetch and Create Incidents
• >> Microsoft 365 Defender >> Create Alert
• Advanced Hunting
• Get Incident Details
• Get Incidents List
• Microsoft 365 Defender > Ingest
• Update Incident

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.

Getting Access Tokens

You can get authentication tokens to access the security graph APIs using two methods:

• On behalf of the User – Delegated Permission. For more information see, Accessing Microsoft 365 Defender on behalf of a user.
• Without a User - Application Permission. For more information see, Accessing Microsoft 365 Defender without a user.

Getting Access Tokens On behalf of the user – Delegated Permission method

1. Ensure that the appropriate permissions are granted to the application. Select API Permissions > Add permission > APIs my organization uses > Microsoft Threat Protection. The API Permission that should be granted to the registered application is:
   • Incident.Read
   • Incident.ReadWrite
   • AdvancedHunting.Read
2. The Redirect URI can be directed to any web application in which you want to receive responses from Azure AD. If you are unsure about what to set as a redirect URI, you can use https://localhost/myapp.
3. Copy the following URL and replace the TENANT_ID, CLIENT_ID, and REDIRECT_URI with your own tenant ID, client ID, and redirect URI: https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize?response_type=code&scope=offline_access https://api.security.microsoft.com/.default&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
4. Enter the above link with the replaced values and you will be prompted to grant permissions for your Azure Service Management. You will be automatically redirected to a link with the following structure: REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
5. Copy the AUTH_CODE (without the code= prefix) and paste it in your instance configuration in the Authorization Code parameter.
6. Enter your client ID in the Client ID parameter field.
7. Enter your client secret in the Client Secret parameter field.
8. Enter your tenant ID in the Tenant ID parameter field.
9. Enter your redirect URI in the Redirect URI parameter field. By default, it is set to https://localhost/myapp.

Getting Access Tokens Without a User – Application Permission method

1. Ensure that the appropriate permissions are granted to the application. Select API Permissions > Add permission > APIs my organization uses > Microsoft Threat Protection. The API Permission that should be granted to the registered application is:
   • Incident.Read.All
   • Incident.ReadWrite.All
   • AdvancedHunting.Read.All
2. Enter your client ID in the Client ID parameter field.
3. Enter your client secret in the Client Secret parameter field.
4. Enter your tenant ID in the Tenant ID parameter field.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling data from Defender for Endpoint. For more information on the Data Ingestion Wizard, see the Connectors Guide in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the Data Ingestion Wizard to seamlessly map Microsoft 365 Defender content to related FortiSOAR™ modules.

The Data Ingestion Wizard enables you to configure scheduled pulling of data from Microsoft 365 Defender into FortiSOAR™. It also lets you pull some sample data from Microsoft 365 Defender using which you can define the mapping of data between Microsoft 365 Defender and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users mostly require to only map any custom fields that are added to the Microsoft 365 Defender incident.

1. To begin configuring data ingestion, click Configure Data Ingestion on the Microsoft 365 Defender connector's Configurations page. Click Let's Start by fetching some data, to open the Fetch Sample Data screen.

   

   Sample data is required to create a field mapping between Microsoft 365 Defender data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.

2. On the Fetch Data screen, provide the configurations required to fetch Microsoft 365 Defender data.

   Users can choose to pull data, i.e., incidents, from Microsoft 365 Defender by specifying incidents created or updated in the Last X Minutes, Status, Owner of Incident fields, and choosing to ingest alerts separately in Alerts module, to filter incidents pulled from Microsoft 365 Defender. The fetched data is used to create a mapping between the Microsoft 365 Defender data and FortiSOAR™ incidents.

   

   NOTE: To use the Ingest Alerts Separately in Alerts Module feature, reconfigure the connector and data ingestion again.

   NOTE: If you have selected Ingest Alerts Separately in Alerts Module and intend to make changes to the default alert mapping, edit the Create Alerts step of the >> Microsoft 365 Defender >> Create Alert playbook.

   Once you have completed specifying the configurations, click Fetch Data.

3. On the Field Mapping screen, map the fields of a Microsoft 365 Defender incident to the fields of an incident present in FortiSOAR™.

   

   For more information on field mapping, see the Data Ingestionchapter in the "Connectors Guide" in the FortiSOAR™ product documentation. Once you have completed mapping fields, click Save Mapping & Continue.

4. (Optional) Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to Microsoft 365 Defender, so that the content gets pulled from the Microsoft 365 Defender integration into FortiSOAR™.

   On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.

   In the Configure Schedule Settings section, specify the Cron expression for the schedule. For example, if you want to pull data from Microsoft 365 Defender every 5 minutes, click Every X Minute and in the minute box enter */5. This would mean that based on the configuration you have set up, data, i.e., incidents will be pulled from Microsoft 365 Defender every 5 minutes.

   

   Once you have completed scheduling, click Save Settings & Continue.

5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.