Current ThreatQ Version Filter
 

ThreatQ Operation for Microsoft 365 Defender

The web format of this guide reflects the most current release.  Guides for older iterations are available in PDF format.  

Integration Details

ThreatQuotient provides the following details for this integration:

Introduction

The ThreatQ Operation for Microsoft 365 Defender enables analysts to export IOCs to Microsoft 365 Defender and set actions and expirations.

The operation provides the following actions:

  • Create Policy - Whitelist or blacklist IOCs from ThreatQ in Microsoft 365 Defender.
  • Revoke Policy - Remove a policy from Microsoft 365 Defender that had previously been sent from ThreatQ.

The operation is compatible with the following indicator types:

  • SHA-1
  • SHA-256
  • MD5
  • FQDN
  • IP Address
  • URL

Prerequisites

The following is required to run the operation:

Azure Application Permissions

Your Microsoft Azure Application must have WindowsDefenderATP access for the Ti.ReadWrite.All and Ti.ReadWrite permissions.

  1. Select Add a Permission under the API permissions for your Azure Application.
  2. Click on the APIs my organization uses tab.  
  3. Search for WindowsDefenderATP and select the result.
  4. Select the Application Permissions box when prompted.
  5. Search and enable Ti.ReadWrite.All and Ti.ReadWrite permissions.
  6. Click the Add permissions button.
  7. Click on Grant admin consent for <Organization> button to fully enable the permissions.

    This last step may take several minutes to propagate the permissions to your Application.  See the following link for additional information: https://learn.microsoft.com/en-us/defender-endpoint/api/import-ti-indicators.

Installation

Perform the following steps to install the integration:

The same steps can be used to upgrade the integration to a new version.

  1. Log into https://marketplace.threatq.com/.
  2. Locate and download the integration file.
  3. Navigate to the integrations management page on your ThreatQ instance.
  4. Click on the Add New Integration button.
  5. Upload the integration file using one of the following methods:
    • Drag and drop the file into the dialog box
    • Select Click to Browse to locate the integration file on your local machine

    ThreatQ will inform you if the operation already exists on the platform and will require user confirmation before proceeding. ThreatQ will also inform you if the new version of the operation contains changes to the user configuration. The new user configurations will overwrite the existing ones for the operation and will require user confirmation before proceeding.

The operation is now installed and will be displayed in the ThreatQ UI. You will still need to configure and then enable the operation.

Configuration

ThreatQuotient does not issue API keys for third-party vendors. Contact the specific vendor to obtain API keys and other integration-related credentials.

To configure the integration:

  1. Navigate to your integrations management page in ThreatQ.
  2. Select the Operation option from the Type dropdown (optional).
  3. Click on the integration entry to open its details page.
  4. Enter the following parameters under the Configuration tab:
    Parameter Description
    Microsoft 365 Defender Tenant ID Enter your Microsoft 365 Defender Tenant ID. 
    Microsoft 365 Defender Client ID Enter your Microsoft 365 Defender Client ID to authenticate.
    Microsoft 365 Defender Client Secret Enter your Microsoft 365 Defender Client Secret to authenticate. 
    ThreatQ Configuration Screen
  5. Review any additional settings, make any changes if needed, and click on Save.
  6. Click on the toggle switch, located above the Additional Information section, to enable it.

Actions

The operation provides the following actions:

Action Description Object Types Object Subtype
Create Policy Whitelist or blacklist IOC's from ThreatQ in Microsoft 365 Defender Indicators SHA-1, SHA-256, MD5, FQDN, IP Address, URL
Revoke Policy Remove a policy from Microsoft 365 Defender that had previously been sent from ThreatQ Indicators SHA-1, SHA-256, MD5, FQDN, IP Address, URL

Create Policy

The Create Policy action exports an IOC to Microsoft 365 Defender and set the action, expiration, and severity/recommended actions if needed.  An attribute is also created for the Indicator Object that shows that the IOC has been sent.

POST https://api.securitycenter.microsoft.com/api/indicators

Sample Response:

{
  "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Indicators/$entity",
  "id": "6",
  "indicatorValue": "1111111111111111111111111111111111111111",
  "indicatorType": "FileSha1",
  "action": "AlertAndBlock",
  "createdBy": "0376d5e7-1621-4f1e-b100-6c6db1fa260f",
  "severity": "Informational",
  "category": 1,
  "application": null,
  "educateUrl": null,
  "bypassDurationHours": null,
  "title": "API Test Hash",
  "description": "API Test Description",
  "recommendedActions": null,
  "creationTimeDateTimeUtc": "2021-10-27T19:42:35.4251738Z",
  "expirationTime": null,
  "lastUpdateTime": "2021-11-10T19:57:27.1717616Z",
  "lastUpdatedBy": "0376d5e7-1621-4f1e-b100-6c6db1fa260f",
  "rbacGroupNames": [],
  "rbacGroupIds": [],
  "notificationId": null,
  "notificationBody": null,
  "version": null,
  "mitreTechniques": [],
  "historicalDetection": false,
  "lookBackPeriod": null,
  "generateAlert": false,
  "additionalInfo": null,
  "createdByDisplayName": "API Access Testing",
  "externalId": null,
  "createdBySource": "PublicApi",
  "certificateInfo": null
}

Action Run Parameters

This Action has the following Configuration options:

Parameter Description
Action The action that will be taken if the indicator is discovered in the organization.
Severity Selects the severity of the indicator. 

This setting is required for Audit, Block and Remediate and Block Execution actions.
Recommended Actions Describe the recommended action to take if the indicator is discovered in the organization. Only used for 'Audit' action or when generating an alert.
IOC Expiration An expiration to be set for the IOC within Microsoft 365 Defender.
Description A description of the indicator. If left blank, it will try to use the description within ThreatQ.
Generate Alert Generate an alert in Microsoft 365 Defender.

Revoke Policy

The Revoke Policy action revokes a policy from Microsoft 365 Defender that was created from this operation.  The action also removes the attribute that showed that the IOC had been sent.

DELETE https://api.securitycenter.microsoft.com/api/indicators/{id}

There is no API response for this action.

Known Issues/Limitations

  • The operation does not update the same indicator if changes are made when operation is rerun. Instead, it deletes the old indicator and creates a new one.
  • Microsoft 365 Defender API parameters and UI parameters have changed slightly and may do so again in the future.  Future updates of the operation will address these changes as they are made by Microsoft.  

Change Log

  • Version 1.0.0 rev-a
    • Guide Update - updated the requirements and permission sections in the Prerequisites chapter.  
  • Version 1.0.0
    • Initial release

PDF Guides

Document ThreatQ Version
ThreatQ Operation for Microsoft 365 Defender Guide v1.0.0 4.30.0 or Greater