Microsoft Graph Security Threat Indicators Integration User Guide

Overview

The Microsoft Graph Security Threat Indicators job app sends a set of Indicators and their metadata from ThreatConnect® to Microsoft® Graph for alerting or blocking with Microsoft Defender for Endpoint (formerly Microsoft Defender ATP). You can curate the Indicator set by the following factors:

• ThreatConnect owner
• Indicator type (Address, File, Host, URL)
• Tags applied to the Indicator
• ThreatAssess score
• Threat Rating
• Confidence Rating
• False positive count

Alternatively, you can use a ThreatConnect Query Language (TQL) query to filter to a specific set of Indicators to send to Microsoft Graph.

Dependencies

ThreatConnect Dependencies

• Active ThreatConnect 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 Entra™ ID tenant with administrator rights to register an app and manage app permissions
• Entra ID app registration with application-level permissions for Ti.ReadWrite.All

Microsoft Entra ID Setup and Configuration

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

Follow these steps to register an app in the Entra admin center and assign the permissions it requires to integrate with the Microsoft Graph Security Threat Indicators app:

1. Register an app in Entra ID. In most cases, you should select a type of Single Tenant, and you should leave the optional Redirect URI field empty.
2. Add a client secret to the app you registered in Step 1.
   Important

   Record the client secret’s value, as you will not be able to retrieve it after leaving the Certificates & secrets page in the Entra admin center. You will need this value when configuring a job for the Microsoft Graph Security Threat Indicators app.
3. On the app’s page (Home > App Registrations > <app name>), under the Manage menu, select API Permissions.
4. Click + Add a permission.
5. On the Request API permissions drawer, select the APIs my organization uses tab.
6. Search for and select WindowsDefenderATP(Figure 1).

   

    

7. Fill out the fields for WindowsDefenderATP on the Request API permissions drawer (Figure 2) as follows:

   

    

   • What type of permissions does your application require?: Select Application permissions.
   • Select permissions: Search for Ti and then select the permission for Ti.ReadWrite.All. 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 Add permissions.
8. The added permissions will now be listed under the Configured permissions section of the API permissions page. Click Grant admin consent for ThreatConnect. A green checkmark will be added to the Status cell for each permission (Figure 3).

   

    

9. Obtain values for the following items, as they are required when configuring a job for the Microsoft Graph Security Threat Indicators app 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 Entra ID.
   • Client Secret: The value of the client secret you recorded in Step 2.
   • Tenant ID: The ID of the Entra ID tenant. To obtain this value, navigate to the Properties page in Microsoft Entra ID.

Additional Resources

• Quickstart: Register an application in Microsoft Entra ID
• Overview of permissions and consent in the Microsoft identity platform
• Configure app permissions for a web API
• Microsoft Graph permissions reference
• Indicator resource type

ThreatConnect Application Setup and Configuration

After you install the Microsoft Graph Security Threat Indicators app on your ThreatConnect instance, you can create a job for it in an Organization.

Install the Microsoft Graph Security Threat Indicators App

Follow these steps to install the Microsoft Graph Security Threat Indicators app on your ThreatConnect instance:

1. Log into ThreatConnect with a System Administrator account.
2. From the Settingsmenu on the top navigation bar, select TC Exchange Settings.
3. Select the Catalog tab on the TC Exchange™ Settings screen.
4. Locate the Microsoft Graph Security Threat Indicators app on the Catalog tab.
   Important

   There are three entries for Microsoft Graph Security Threat Indicators on the Catalog tab. Locate the app with Organization in the Category column and 3.0.0 in the Version column.
5. Click Installin the Options column for the app.
6. Select the Allow all organizations checkbox in the app’s Release Notes window.
   Important

   If you do not select this checkbox, you will not be able to create a job for the app in any Organization. It is not possible to allow only a subset of Organizations on a ThreatConnect instance to use a job app.
7. Click INSTALL in the app’s Release Notes window.

Create a Job for the Microsoft Graph Security Threat Indicators App in an Organization

Follow these steps to create a job for the Microsoft Graph Security Threat Indicators app in an Organization:

1. Log into ThreatConnect with an Organization Administrator account in the Organization in which you are creating a job for the Microsoft Graph Security Threat Indicators app.
   Important

   Your user account’s home Organization must be the same as the Organization in which you are creating the job, as some of the configuration options are determined by the home Organization of the user account configuring the job.
2. From the Automation & Feeds dropdown on the top navigation bar, select Jobs.
3. Click + Create Job and select New Job.
4. Follow the instructions in Table 1 to fill out the fields in the Add Job drawer.

    

   Name	Description	Required?
   Job Details Tab
   Job Name	Enter a name for the job.	Yes
   Run Program	Select Microsoft Graph Security Threat Indicators (3.0.0) from the dropdown.	Yes
   Parameters Tab
   Api User	Select the API user in your Organization that will run the job.	Yes
   Microsoft Graph Client ID	Enter the client ID of the app you registered in Entra ID.	Yes
   Microsoft Graph Client Secret	Enter the client secret for the app you registered in Entra ID.	Yes
   Microsoft Graph Tenant ID	Enter the ID of the Entra ID tenant.	Yes
   Action to Take	Select the action to take for each Indicator found in Microsoft Defender for Endpoint: Alert Block	Yes
   Expiration Days - File	Enter the time to live (TTL) for File Indicators in Microsoft Graph. The default value is 30.	Yes
   Expiration Days - Network	Enter the TTL for Network Indicators (Address, Host, URL) in Microsoft Graph. The default value is 30.	Yes
   Owners	Select the ThreatConnect owners from which to send Indicators to Microsoft Graph. Important If you do not select at least one owner, the Microsoft Graph Security Threat Indicators app will not send any Indicators to Microsoft Graph (unless you provide a TQL query in the TQL field).	No
   Indicator Types	Select the types of Indicators to send to Microsoft Graph: Address MD5 SHA1 SHA256 Host URL Important If you do not select at least one Indicator type, the Microsoft Graph Security Threat Indicators app will not send any Indicators to Microsoft Graph (unless you provide a TQL query in the TQL field).	No
   Last Run	Enter the lookback period for Indicator ingestion, in number of days. Indicators whose Last Modified date is within this lookback period will be ingested during the job’s run. Warning If you select the Only Send Indicators Modified Since Last Run checkbox under this field, you must enter a Last Run value. If you do not, the job may fail or return undesired results.	No
   Only Send Indicators Modified Since Last Run	Select this checkbox to send only filtered Indicators modified after the job’s last run (i.e., the datetime in the Indicator’s Last Modified field is after the datetime of the job’s last run) to Microsoft Graph. Clear this checkbox to send all filtered Indicators to Microsoft Graph each time the job runs. Important It is recommended to select the Only Send Indicators Modified Since Last Run checkbox in order to streamline performance and avoid sending Indicators to Microsoft Graph that were sent during previous runs.	No
   TQL	Enter a ThreatConnect Query Language (TQL) query for filtering Indicators to send to Microsoft Graph. Note If you enter a query in this field, all other filter-based parameters (Owners, Indicator Types, Tags Filter, Minimum ThreatAssess Score, Minimum Threat Rating, Minimum Confidence Rating, and False Positive Threshold) will be ignored.	No
   Tag Filter	Enter Tags (comma delimited) on which to filter Indicators to send to Microsoft Graph. At least one of the specified Tags must be applied to an Indicator for it to be sent to Microsoft Graph.	No
   Minimum ThreatAssess Score	Enter the minimum ThreatAssess score for Indicators to send to Microsoft Graph.	No
   Minimum Threat Rating	Enter the minimum Threat Rating for Indicators to send to Microsoft Graph.	No
   Minimum Confidence Rating	Enter the minimum Confidence Rating for Indicators to send to Microsoft Graph.	No
   False Positive Threshold	Enter the maximum number of false positives for Indicators to send to Microsoft Graph.	No
   Logging Level	Select the logging level for the job.	Yes
   Indicator Reserve Count	Important Microsoft Defender for Endpoint has a limit of 15,000 Indicators per tenant. The Indicator Reserve Count parameter is used to decrease the maximum number of Indicators the Microsoft Graph Security Threat Indicators app sends to Microsoft Graph to avoid reaching this limit. Once the limit is reached, no more Indicators can be sent to Microsoft Graph until existing Indicators are removed after their TTL expires. Enter the number of Indicators (0–15,000) to reserve (that is, the number of Indicators not to send to Microsoft Graph). Entering a value for this parameter decreases the maximum number of Indicators the Microsoft Graph Security Threat Indicators app sends to Microsoft Graph, thus creating a reserve count for Indicators that may be sent to Microsoft Graph later (e.g., during an ad hoc job run). Leaving this field blank is equivalent to entering a value of 0. Example If you enter 3000, then the Microsoft Graph Security Threat Indicators app will send a maximum of 12,000 Indicators to Microsoft Graph, leaving a reserve of 3,000 “slots” for Indicators sent at a later time. 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

5. Click Save in the Add Job drawer to create the job for the Microsoft Graph Security Threat Indicators app in the Organization.

Data Mappings

The data mappings in Table 2 through Table 4 define how data from ThreatConnect are mapped to Microsoft Graph API endpoints for each Indicator type.

All Indicator Types

ThreatConnect object types: Address, File, Host, and URL Indicator

Network Indicators

ThreatConnect object types: Address, Host, and URL Indicator

File Indicators

ThreatConnect object type: File Indicator

Troubleshooting

The Microsoft Graph Security Threat Indicators app is installed on my ThreatConnect instance, but it is not listed in the Run Program dropdown when I try to create a job for it on the Jobs screen. Why can’t I create a job for this app?

If your System Administrator did not select the Allow all organizations checkbox when installing the Microsoft Graph Security Threat Indicators app, you will not be able to create a job for the app in any Organization. To fix this problem, your System Administrator must uninstall the app (TC Exchange Settings > Installed > Options ⋮ for the app > Uninstall) and then reinstall it, making sure to select the Allow all organizations checkbox.

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

30067-04 EN Rev. A