Microsoft Defender For Cloud v1.0.0

About the connector

Microsoft Defender for Cloud is a solution for cloud security posture management (CSPM) and cloud workload protection (CWP) that finds weak spots across your cloud configuration, helps strengthen the overall security posture of your environment and can protect workloads across multi-cloud and hybrid environments from evolving threats.

This document provides information about the Microsoft Defender For Cloud connector, which facilitates automated interactions, with a Microsoft Defender For Cloud server using FortiSOAR™ playbooks. Add the Microsoft Defender For Cloud Connector as a step in FortiSOAR™ playbooks and perform automated operations such as retrieving details of a specific Auto Provisioning Setting (APS), updating the state of the specific alert, etc.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 7.3.0-2034

Authored By: Fortinet

Certified: Yes

Getting Access Tokens

You can get authentication tokens to access the Microsoft Defender For Cloud APIs using the "On behalf of the User – Delegate Permission. For more information see, Create an app to access Microsoft 365 Defender APIs on behalf of a user article.

Getting Access Tokens using the On behalf of the User – Delegate Permission method

1. Ensure that the required permissions are granted for the registration of the application. Select API Permissions > Add permission > Microsoft APIs > Azure Service Management.
   Note: The 'user_impersonation' API Permission should be granted to the registered application.
2. The Redirect URL 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 URL, 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=https://management.azure.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. Enter the following details in the Connector Configuration dialog in your FortiSOAR instance:
   1. Copy the AUTH_CODE (without the "code=" prefix) and paste it in the 'Authorization Code' parameter.
   2. Copy your client ID to the 'Client ID' parameter field.
   3. Copy your tenant ID to the 'Tenant ID' parameter field.
   4. Copy your client secret to the 'Client Secret' parameter field.
   5. Copy your redirect URI to the 'Redirect URI' parameter field. By default, it is set to https://localhost/myapp.

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 following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-microsoft-defender-for-cloud

Prerequisites to configuring the connector

• You must have your Service-based URI to which you will connect and perform the automated operations.
• You must also have the Client ID and the Tenant ID of your Azure application.
• Ensure that host login.microsoftonline.com on port 443 is whitelisted.

Minimum Permissions Required

• user_impersonation API permission (see the Getting Access Tokens using the On behalf of the user – Delegate Permission method section)

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the Microsoft Defender For Cloud connector card. On the connector popup, click the Configurations tab to 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™:

operation: Get Alert List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": "",
"name": "",
"type": "",
"properties": {
"version": "",
"alertType": "",
"systemAlertId": "",
"productComponentName": "",
"alertDisplayName": "",
"description": "",
"severity": "",
"intent": "",
"startTimeUtc": "",
"endTimeUtc": "",
"resourceIdentifiers": [
{
"azureResourceId": "",
"type": ""
},
{
"workspaceId": "",
"workspaceSubscriptionId": "",
"workspaceResourceGroup": "",
"agentId": "",
"type": ""
}
],
"remediationSteps": [],
"vendorName": "",
"status": "",
"extendedLinks": [
{
"Category": "",
"Label": "",
"Href": "",
"Type": ""
}
],
"alertUri": "",
"timeGeneratedUtc": "",
"productName": "",
"processingEndTimeUtc": "",
"entities": [
{
"address": "",
"location": {
"countryCode": "",
"state": "",
"city": "",
"longitude": "",
"latitude": "",
"asn": ""
},
"type": ""
}
],
"isIncident": "",
"correlationKey": "",
"extendedProperties": {
"Property1": ""
},
"compromisedEntity": "",
"techniques": [],
"subTechniques": [],
"supportingEvidence": {
"type": "",
"title": "",
"columns": [],
"rows": [
[]
]
}
}
}
]
}

operation: Update Alert

Input parameters

Output

The output contains a non-dictionary value.

operation: Get APS

Input parameters

Output

The output contains the following populated JSON schema:
{
"id": "",
"name": "",
"type": "",
"properties": {
"autoProvision": ""
}
}

operation: Update APS

Input parameters

Output

The output contains the following populated JSON schema:
{
"id": "",
"name": "",
"type": "",
"properties": {
"autoProvision": ""
}
}

operation: Get ATP

Input parameters

Output

The output contains the following populated JSON schema:
{
"id": "",
"name": "",
"type": "",
"properties": {
"isEnabled": ""
}
}

operation: Update ATP

Input parameters

Output

The output contains the following populated JSON schema:
{
"id": "",
"name": "",
"type": "",
"properties": {
"isEnabled": ""
}
}

operation: Get APS List

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": "",
"name": "",
"type": "",
"properties": {
"autoProvision": ""
}
}
]
}

operation: Get Secure Score

Input parameters

Output

The output contains the following populated JSON schema:
{
"id": "",
"name": "",
"type": "",
"properties": {
"displayName": "",
"score": {
"max": "",
"current": "",
"percentage": ""
},
"weight": ""
}
}

operation: Get Locations List

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": "",
"name": "",
"type": "",
"properties": {
"homeRegionName": ""
}
}
]
}

operation: Get Storage List

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": "",
"kind": "",
"location": "",
"name": "",
"properties": {
"isHnsEnabled": "",
"creationTime": "",
"primaryEndpoints": {
"web": "",
"dfs": "",
"blob": "",
"file": "",
"queue": "",
"table": "",
"microsoftEndpoints": {
"web": "",
"dfs": "",
"blob": "",
"file": "",
"queue": "",
"table": ""
},
"internetEndpoints": {
"web": "",
"dfs": "",
"blob": "",
"file": ""
}
},
"primaryLocation": "",
"provisioningState": "",
"routingPreference": {
"routingChoice": "",
"publishMicrosoftEndpoints": "",
"publishInternetEndpoints": ""
},
"encryption": {
"services": {
"file": {
"keyType": "",
"enabled": "",
"lastEnabledTime": ""
},
"blob": {
"keyType": "",
"enabled": "",
"lastEnabledTime": ""
}
},
"keySource": ""
},
"secondaryLocation": "",
"statusOfPrimary": "",
"statusOfSecondary": "",
"supportsHttpsTrafficOnly": ""
},
"sku": {
"name": "",
"tier": ""
},
"tags": {
"key1": ""
},
"type": ""
}
]
}

operation: Get JIT List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"kind": "",
"properties": {
"virtualMachines": [
{
"id": "",
"ports": [
{
"number": "",
"protocol": "",
"allowedSourceAddressPrefix": "",
"maxRequestAccessDuration": ""
}
]
}
],
"requests": [
{
"virtualMachines": [
{
"id": "",
"ports": [
{
"number": "",
"allowedSourceAddressPrefix": "",
"endTimeUtc": "",
"status": "",
"statusReason": ""
}
]
}
],
"startTimeUtc": "",
"requestor": "",
"justification": ""
}
],
"provisioningState": ""
},
"id": "",
"name": "",
"type": "",
"location": ""
}
]
}

operation: Get Subscriptions List

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": "",
"subscriptionId": "",
"tenantId": "",
"displayName": "",
"state": "",
"subscriptionPolicies": {
"locationPlacementId": "",
"quotaId": "",
"spendingLimit": ""
},
"authorizationSource": "",
"managedByTenants": [
{
"tenantId": ""
}
],
"tags": {
"tagKey1": ""
}
}
],
"nextLink": ""
}

Included playbooks

The Sample - Microsoft Defender For Cloud - 1.0.0 playbook collection comes bundled with the Microsoft Defender For Cloud 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 Defender For Cloud connector.

• Get APS
• Get APS List
• Get ATP
• Get Alert List
• Get JIT List
• Get Locations List
• Get Secure Score
• Get Storage List
• Get Subscriptions List
• Update APS
• Update ATP
• Update Alert

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 the connector upgrade and delete.