Microsoft Graph Security Threat Indicators Integration User Guide
  • 21 Nov 2023
  • 12 Minutes to read
  • Dark
    Light

Microsoft Graph Security Threat Indicators Integration User Guide

  • Dark
    Light

Article summary

Software Version
This guide applies to the Microsoft Graph Security Threat Indicators App version 2.0.x.

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.

Important
Microsoft Defender for Endpoint does not import duplicate Indicators. As such, if Microsoft Defender for Endpoint is selected as the Target Product for the Microsoft Graph Security Threat Indicators App, the number of Indicators the App sends may differ from the number of Indicators imported into Microsoft Defender for Endpoint if duplicate Indicators are present.

Dependencies

ThreatConnect Dependencies

  • Active ThreatConnect Application Programming Interface (API) key
Note
All ThreatConnect dependencies will be provided by default to subscribing ThreatConnect Cloud customers. Customers on Dedicated Cloud and On-Premises instances can enable these settings on the Account Settings screen within their ThreatConnect instance.

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).
    Figure%201_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

    • 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 theGrant%20admin%20consent%20iconicon 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).
    Figure%202_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

  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

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.

 

NameDescriptionRequired?
Api UserThe name of the ThreatConnect API user.Yes
Microsoft Graph Client IDThe client ID of the App you registered in Azure AD.Yes
Microsoft Graph Client SecretThe value of the client secret added to the app you registered in Azure AD.Yes
Microsoft Graph Tenant IDThe ID of the Azure AD tenant.Yes
Default TLP LevelThe default Traffic Light Protocol (TLP) level to apply to Indicators that do not have a Security Label. If an Indicator has multiple Security Labels applied to it, the highest level will be used.Yes
Target ProductThe security product to which Microsoft Graph will send Indicators. Accepted values include the following:
  • Microsoft Sentinel
  • Microsoft Defender for Endpoint
Yes
Action to TakeThe action to take if an Indicator is found in the security tool selected for the Target Product parameter. Accepted values include the following:
  • Alert
  • Block
Yes
Expiration Days - EmailThe number of days added to the time to live (TTL) for Email Indicators in Microsoft Graph.Yes
Expiration Days - FileThe number of days added to the TTL for File Indicators in Microsoft Graph.Yes
Expiration Days - NetworkThe number of days added to the TTL for Network Indicators in Microsoft Graph.Yes
OwnersThe ThreatConnect owner(s) whose Indicators will be sent to Microsoft Graph.No
Indicator TypesThe type(s) of Indicators that will be sent to Microsoft Graph. Accepted values include the following:
  • Address
  • CIDR
  • Email Address
  • Email Subject
  • MD5
  • SHA1
  • SHA256
  • Host
  • URL
  • User Agent
No
Last RunThis parameter designates how far back to pull Indicators on the first run. It must be filled in if the Only Send Indicators Modified Since Last Run checkbox is selected. The Job will keep this parameter up to date each time a run completes successfully.No
Only Send Indicators Modified Since Last RunIf this checkbox is selected, only Indicators modified after the last time the Job ran will be sent to Microsoft Graph. If this checkbox is cleared, all Indicators matching the filters will be sent each time the Job runs.No
TQLA custom ThreatConnect Query Language (TQL) query for filtering Indicators that will be sent to Microsoft Graph. When used, all other filter-based parameters (Owners, Indicator Types, Tags Filter, Minimum ThreatAssess Score, Minimum Confidence Rating, Minimum Threat Rating, and False Positive Threshold) will be ignored.No
Tags FilterThe Tag(s) that Indicators must include in order to be sent to Microsoft Graph. Indicators must include at least one of the specified Tags in order to be sent.No
Minimum ThreatAssess ScoreThe minimum ThreatAssess score that Indicators must have in order to be sent to Microsoft Graph.No
Minimum Confidence RatingThe minimum Confidence Rating that Indicators must have in order to be sent to Microsoft Graph.No
Minimum Threat RatingThe minimum Threat Rating that Indicators must have in order to be sent to Microsoft Graph.No
False Positive ThresholdThe maximum number of false positives that Indicators can have in order to be sent to Microsoft Graph. When used, only Indicators with a false positive count less than or equal to the specified value will be sent.No
Logging LevelDetermines the verbosity of the logging output for the application.Yes
Indicator Reserve CountThe number of Indicators the App will not send to Microsoft Graph. Use this parameter when Microsoft Defender for Endpoint is selected for the Target Product parameter, as the maximum number of Indicators that can be sent to Microsoft Defender for Endpoint is 15,000. Entering a value for this parameter decreases the maximum number of Indicators the App will send, thus creating a reserve count for sending Indicators to Microsoft Defender for Endpoint later in the day on an ad-hoc basis.
Important
If you enter a value greater than 15,000 for this parameter, the Job will not send any Indicators to Microsoft Defender for Endpoint.
No

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.

Note
This guide contains instructions that describe how to create a Playbook Service specific to the Microsoft Graph Notification Service Playbook Trigger. See Playbook Services for information on general Playbook Services creation.
  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).
    Figure%203_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.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).
    Figure%204_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

    • 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).
    Figure%205_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

  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. ClickPlaybook Designer Triggers iconTriggers 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).
    Figure%206_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

  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).
    Figure%207_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

    • 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).
    Figure%208_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

    • 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).
    Figure%209_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

    • 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).
    Figure%2010_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

    • 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. ClickPlaybook Designer Operators iconOperators 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).
    Figure%2011_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

  2. Connect the Trigger to the Iterator Operator by dragging the Trigger’s blue circle node to the Iterator Operator (Figure 12).
    Figure%2012_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

  3. Double-click on the Iterator Operator. The Edit App pane will be displayed on the left side of the Playbook Designer (Figure 13).
    Figure%2013_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

    • 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 thePlus icon_Blackbutton 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).
      Figure%2014_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

       

    • Outputs: Do not enter any output variables.
    • Click the SAVE button.
Step 4: Adding and Configuring the JMESPath App
  1. ClickPlaybook Designer Apps iconApps 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).
    Figure%2015_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

  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).
    Figure%2016_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

  3. Double-click the JMESPath App. The Edit App pane will be displayed on the left side of the Playbook Designer (Figure 17).
    Figure%2017_Microsoft%20Graph%20Security%20Threat%20Indicators%20Integration%20User%20Guide_2.0.3

     

    • 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

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

 

ThreatConnect FieldMicrosoft Graph API Field
Confidenceconfidence
"ThreatConnect | Owner: {Owner}"description
XIDexternalId
Attribute: "Phase of Intrusion"killChain
False Positive CountknownFalsePositives
Attribute: "Last Seen"lastReportedDateTime
Threat Ratingseverity
Tagstags
Security LabeltlpLevel
"Watchlist"threatType
WeblinkadditionalInformation

Email Observables

 

ThreatConnect FieldMicrosoft Graph API Field
Indicator: Email AddressemailSenderAddress
Indicator: Email SubjectemailSubject

Network Observables

 

ThreatConnect FieldMicrosoft Graph API Field
Indicator: HostdomainName
Indicator: CIDRnetworkCidrBlock
Indicator: AddressnetworkIPv4
Attribute: "Network Protocol Analysis"networkPort
Attribute: "Network Protocol Analysis"networkProtocol
Indicator: URLurl
Indicator: User AgentuserAgent

File Observables

 

ThreatConnect FieldMicrosoft Graph API Field
File Hash TypefileHashType
Indicator: FilefileHashValue

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


Was this article helpful?