Microsoft 365 Defender v1.0.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.0.0

FortiSOAR™ Version Tested on: 7.3.0-2034 and later

Microsoft 365 Defender Tested on: Cloud Instance

Authored By: Fortinet

Certified: Yes

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.

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 the minimum permissions required, 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 from FortiSOAR™ release 4.10.0 and onwards:

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.0.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
• 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.

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 the last x minutes, status, last updated time, and assigned To fields 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.
   
   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.