Microsoft Graph Security Threat Indicators Integration User Guide

Overview

The ThreatConnect^® integration with Microsoft^® Graph enables you to send Indicators from ThreatConnect to Microsoft Graph for alerting and blocking with target products like Microsoft Sentinel™ and Microsoft Defender™ for Endpoint (formerly Microsoft Defender ATP). The integration supports Indicator types of Address, Host, CIDR, URL, User Agent, Email Address, Email Subject, and File (MD5, SHA1, and SHA256), along with the relevant context for each Indicator type.

In addition, you can leverage the Microsoft Graph Notification Service Playbook Trigger to subscribe to change notifications originating from Microsoft Graph.

Dependencies

ThreatConnect Dependencies

• Active ThreatConnect Application Programming Interface (API) key

Microsoft Graph Dependencies

• Microsoft Azure® Active Directory™ (AD) tenant with administrator rights to register an app and manage app permissions
• Azure app registration with application-level permissions for ThreatIndicators.ReadWrite.OwnedBy

Microsoft Azure App Registration Configuration

Registering and Configuring an App

To use the Microsoft Graph Security Threat Indicators App, you must register an app in the Azure portal and assign it permissions. Before following the steps in this section, verify that you have created an Azure AD tenant in the Azure portal. 

1. Register an app in Azure AD. In most cases, a type of Single Tenant should be selected and the optional Redirect URI field should be left empty.
2. Add a client secret to the app you registered in Step 1. The client secret’s value will be used as the value for the Microsoft Graph Client Secret parameter in the Microsoft Graph Security Threat Indicators App.
   Important

   Make sure to save the client secret’s value, as you will not be able to retrieve it after leaving the Client & secrets page in the Azure portal.
3. On the app page, under Manage, select API Permissions. The API permissions page will be displayed.
4. Click + Add a permission. The Request API permissions drawer will be displayed.
5. On the Microsoft API tab, select Microsoft Graph (Figure 1).
   

    

   • What type of permissions does your application require?: Select Application permissions.
   • Select permissions: Search for ThreatIndicators and then select the permission for ThreatIndicators.ReadWrite.OwnedBy. In addition, it is recommended to grant the app the following permissions so that it can create notifications:
     • Calendars.Read
     • Contacts.Read
     • Files.ReadWrite.All
     • Group.Read.All
     • Mail.Read
     • SecurityEvents.ReadWrite.All
     • User.Read.All
   • Click the Add permissions button.
6. The added permissions will now be listed under the Configured permissions section of the API permissions page. Click theicon next to Grant admin consent for ThreatConnect. A green checkmark will be displayed on the left of the Status cell for each permission (Figure 2).
   

    

7. Obtain the values for the following items, as they are required when configuring the Microsoft Graph Security Threat IndicatorsApp in ThreatConnect:
   • Client ID: The client ID of the app you registered in Step 1. To obtain this value, navigate to the Overview page for the app in Azure AD.
   • Client Secret: The value of the client secret created in Step 2. Note that the client secret’s value is displayed in the Value column of the Client secrets tab of the Clients & secrets page in Azure.
   • Tenant ID: The ID of the Azure AD tenant. To obtain this value, navigate to the Properties page in Azure AD.

Additional Resources

• Quick start: Register an application with the Microsoft identity platform
• Permissions and consent in the Microsoft identity platform endpoint
• Microsoft Graph permissions reference: Security permissions
• tiIndicator resource type

ThreatConnect Configuration

Application Installation and Configuration

1. Log into ThreatConnect with a System Administrator account.
2. Install the Microsoft Graph Security Threat Indicators App via TC Exchange™.
3. Create a Job for the Microsoft Graph Security Threat Indicators App.

Parameter Definitions

The parameters defined in Table 1 apply to the configuration parameters available when creating a Job for the Microsoft Graph Security Threat Indicators App.

Configuring the Microsoft Graph Security Notification Playbook

You can use the Microsoft Graph Notification Service Playbook Trigger to subscribe to change notifications originating with the Microsoft Graph cloud services for one or more resources. When Microsoft Graph detects a change on the subscribed resource, the Playbook containing this Trigger will execute. Because notifications from Microsoft Graph are batched, the Playbook leverages the Iterator Operator to go through each notification that is delivered.

Creating and Configuring the Playbook Service

Before proceeding with these instructions, confirm that a System Administrator has installed the Microsoft Graph Notification Service Playbook Trigger on your ThreatConnect instance via TC Exchange.

1. Log into ThreatConnect with a System Administrator account.
2. On the top navigation bar, hover over Playbooks and select Services. The Services screen will be displayed.
3. Click the + NEW button at the top left of the Services screen. The Select screen of the Create Service drawer will be displayed (Figure 3).
   

    

   • Name: Enter a unique name for the Service (e.g., Microsoft Graph Notifications Bi-Directional).
   • Type: Keep the selection of Playbook Trigger.
   • Service: Select Microsoft Graph Notification Service v1.0.x.
   • Click the NEXT button.
4. The Configure screen of the Create Service drawer will be displayed (Figure 4).
   

    

   • Launch Server: Select tc-job.
   • Permissions: Select the Organization(s) that will have access to the Service.
   • Allow all: Select the checkbox to grant all Organizations on the ThreatConnect instance access to the Service.
   • Enable Notifications: Select the checkbox to send an email when the Service fails to start, if desired. It is recommended to enable this setting.
   • Email Address: If you selected the Enable Notifications checkbox, enter the email address to which notifications will be sent. It is recommended to enter an email address for a ThreatConnect user with a System role of Administrator.
   • Max restart attempts on failure: Enter the number of times ThreatConnect should try to restart the Service if it fails. It is recommended to set this value to 10.
   • Click the NEXT button.
5. The Parameters screen of the Create Service drawer will be displayed (Figure 5).
   

    

   • Client ID: Enter the client ID saved during Step 7 of the “Microsoft Azure App Registration Configuration” section.
   • Client Secret: Enter the client secret value saved during Step 7 of the “Microsoft Azure App Registration Configuration” section.
   • Tenant ID: Enter the tenant ID saved during Step 7 of the “Microsoft Azure App Registration Configuration” section.
   • Click the SAVE button.
6. The Service will now be displayed on the Services tab of the Playbooks screen. Toggle the Web Hook Trigger slider on, and, if desired, adjust the Log Level.
   Note

   It is recommended that the Log Level for the Service be set to INFO, WARN, or ERROR.

Creating and Configuring the Playbook

Step 1: Creating the Playbook

1. On the top navigation bar, click Playbooks to display the Playbooks screen .
2. Hover over the NEW button at the top left of the Playbooks screen and select Create Playbook to create a Playbook. After the Playbook is created, it will open in the Playbook Designer.

Step 2: Adding and Configuring the Trigger

1. ClickTriggers on the side navigation bar of the Playbook Designer and select the Trigger created in the “Creating and Configuring the Playbook Service” section (Microsoft Graph Notifications Bi-Directional in this example) from the IT Infrastructure section. The Trigger will be displayed in the Playbook Designer (Figure 6).
   

    

2. Double-click the Trigger. The Configure section of the Edit Trigger pane will be displayed on the left side of the Playbook Designer­ (Figure 7).
   

    

   • WebHook Name: By default, the Trigger’s name will include the name of the Service created in the “Creating and Configuring the Playbook Service” section, followed by the word “Trigger.” If desired, update the Trigger’s name.
   • Timeout: Leave this field set to 0.
   • Enable Basic Authentication: Leave this checkbox cleared.
   • Enable Data Caching: Leave this checkbox cleared.
   • Click the NEXT button.
3. The Parameters section of the Edit Trigger pane will be displayed (Figure 8).
   

    

   • Resource: Enter the resource URL that corresponds to the notification subscription.
   • Change Type: Select one or more change types for the notification subscription your organization is monitoring.
     Note

     Certain subscriptions do not allow a created or deleted change type. For example, the only valid change type for a security alert is updated. In this scenario, selecting created or deleted will lead to a silent error.
   • Click the NEXT button.
4. The Response Header section of the Edit Trigger pane will be displayed (Figure 9).
   

    

   • Response Code: Enter 201 in the Response Code field to return a positive “Accepted” response to Microsoft.
   • Response Header: Leave the Key and Value fields blank.
   • Click the NEXT button.
5. The Response Body section of the Edit Trigger will be displayed (Figure 10).
   

    

   • Body: Enter a human-readable value (e.g., Accepted) or leave the field empty.
   • Click the SAVE button.

Step 3: Adding and Configuring the Iterator Operator

1. ClickOperators on the side navigation bar of the Playbook Designer and select Iterator from the list. The Iterator Operator will be displayed in the Playbook Designer (Figure 11).
   

    

2. Connect the Trigger to the Iterator Operator by dragging the Trigger’s blue circle node to the Iterator Operator (Figure 12).
   

    

3. Double-click on the Iterator Operator. The Edit App pane will be displayed on the left side of the Playbook Designer (Figure 13).
   

    

   • Job Name: Enter a name for the Iterator Operator.
   • Inputs: In the Key field, enter resource as the name for the array on which the Operator will iterate. In the Value field, enter #graph.resource_data.array.json. Click thebutton to the right of the Value field to add the key/value pair. A table with the key/value pair will be displayed (Figure 14).
     

      

   • Outputs: Do not enter any output variables.
   • Click the SAVE button.

Step 4: Adding and Configuring the JMESPath App

1. ClickApps on the side navigation of the Playbook Designer and select JMESPath from the Utility section. The JMESPath App will be displayed in the Playbook Designer (Figure 15).
   

    

2. Connect the Iterator Operator to the JMESPath App by dragging the white circle node at the bottom of the Iterator Operator to the JMESPath App. Complete the circuit back to the Iterator Operator by dragging the blue circle node from the JMESPath App to the red square on the bottom of the Iterator Operator (Figure 16).
   

    

3. Double-click the JMESPath App. The Edit App pane will be displayed on the left side of the Playbook Designer (Figure 17).
   

    

   • Job Name: Enter a name for the App.
   • JSON Data: Enter #resource and select #graph.resource_data.array.json—the value entered for the Iterator Operator in Step 3 of the “Step 3: Adding and Configuring the Iterator Operator” section.
   • JMESPath String Expressions: Leave the Key and Value fields blank.
   • Strip Quotes from String Output: Leave the checkbox selected.
   • Strip JSON formatting from String Output: Leave the checkbox cleared.
   • JMESPath StringArray Expressions: Leave the Key and Value fields blank.
   • Fail on No Results: Leave the checkbox cleared.
   • Click the SAVE button.
4. Hover over the DESIGN MODE dropdown at the top right of the Playbook Designer and select Active to activate the Playbook.

Service Considerations

• Microsoft Graph requires the ability to send notifications to your ThreatConnect server to deliver notifications. Nearly any part of the Azure cloud can originate the notification, making firewall restrictions of the notification URL problematic.
• If Microsoft Graph cannot validate the notification URL, it will not activate a subscription.
• In addition, notifications can be missed if a Playbook is disabled, or not fully propagated when a Playbook is enabled, as there is a brief delay as a subscription propagates in Azure.
• If Microsoft Graph delivers a notification and ThreatConnect does not respond within 30 seconds, it will attempt to re-deliver the notification. The prioritization of notification Playbooks may need to be increased to ensure timely processing of notifications on busy systems.

Additional Resources

• Set up notifications for changes in user data
• Microsoft Graph Explorer

Data Mappings

Table 2 through Table 5 define how data from ThreatConnect are mapped into Microsoft Graph for each Indicator (i.e., observable) type.

All Observable Types

Email Observables

Network Observables

File Observables

ThreatConnect^® is a registered trademark, and TC Exchange™ is a trademark, of ThreatConnect, Inc.
Azure^® and Microsoft^® are registered trademarks, and Active Directory™, Microsoft Defender™, and Microsoft Sentinel™ are trademarks, of Microsoft Corporation.

30067-03 EN Rev. A