Microsoft Sentinel Integration User Guide

Overview

The ThreatConnect® integration with Microsoft Sentinel™ uses the Microsoft Sentinel upload indicators API to send sets of Indicators defined by ThreatConnect Query Language (TQL) queries from ThreatConnect to Microsoft Sentinel. Microsoft Sentinel then analyzes the Indicators from ThreatConnect to detect suspicious activities and alert the relevant teams with actionable data.

The following ThreatConnect Indicator types may be sent to Microsoft Sentinel:

• Address (IPv4 and IPv6)
• CIDR
• Host
• File (MD5, SHA1, SHA256)
• URL
• ASN
• Email Address
• Email Subject
• Registry Key

Dependencies

ThreatConnect Dependencies

• Active ThreatConnect Application Programming Interface (API) user account

Microsoft Sentinel Dependencies

• Active Microsoft Azure^® subscription
• Microsoft Azure Active Directory™(AD) tenant with administrator rights to create an app registration and manage permissions
• Azure app registration with an application role of Microsoft Sentinel Contributor role

Connect ThreatConnect to Microsoft Sentinel

To use the Microsoft Sentinel App in ThreatConnect, you must first follow these steps to connect ThreatConnect to Microsoft Sentinel:

1. Complete all steps in the following guide: Connect your threat intelligence platform to Microsoft Sentinel with the upload API (Preview).
   Note

   When registering an app in Azure AD, you should select an account type of Single Tenant. The optional Redirect URI field should be left empty in most cases.
2. Obtain the values for the following required items for configuring the Microsoft Sentinel App in ThreatConnect:
   1. Client ID: The client ID of the app you registered in Step 1. This value is available on the Overview page for the app in Azure AD.
   2. Client Secret: The value of the client secret created in Step 1. This value is provided in the Value column on the Client secrets tab of the Clients & secrets page in Azure.
   3. Tenant ID: The ID of the Azure AD tenant. This value is available on the Properties page in Azure AD.
   4. Workspace ID: The ID of the workspace to which Microsoft Sentinel is added. To obtain this value, navigate to Microsoft Sentinel, click Settings in the side navigation bar, and select the Workspace settings tab.

Install Microsoft Sentinel App

Follow these steps to install the Microsoft Sentinel 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 Sentinel App on the Catalog tab.
   Hint

   On the Catalog tab, the App’s Category is ApiService. After it is installed, its category on the Installed tab is REST API.
5. Click Installin the Options column for the App.
6. Click INSTALL in the App's Release Notes window.

Configure Microsoft Sentinel Service

A separate Service for the Microsoft Sentinel App must be configured for each Organization that will use it on a ThreatConnect instance. This Organization is determined by the API user credentials entered in the Service’s configuration—that is, the Organization the API user account belongs to is the Organization for which the Service is configured. The owners you can query for ThreatConnect Indicators to send to Microsoft Sentinel are the Organization and the Communities and Sources it owns or is a member of.

Follow these steps to create and configure a Service for the Microsoft Sentinel App for an Organization:

1. Log into ThreatConnect with a System Administrator account or an Organization Administrator account in the Organization for which you are configuring the Microsoft Sentinel App.
2. From the Automation & Feeds menu on the top navigation bar, select Services.
3. Click + Create New Service.
4. Fill out the fields on Step 1 (Select) of the Add Service drawer (Figure 1) as follows:

    

   • Name: Enter a name for the Service that is unique on your ThreatConnect instance and specific to the name of the Organization using the Service. The recommended format is Microsoft Sentinel - <Organization name> (e.g., Microsoft Sentinel - Demo Organization).
   • Type: Select Service API.
   • Service: Select Microsoft Sentinel v1.0.2.
   • Click Next.
5. Fill out the fields on Step 2 (Configure) of the Add Service drawer (Figure 2) as follows:

    

   • Launch Server: Select tc-job.
   • Permissions and Allow all: These fields are not relevant for Service API (REST API) Apps. Any selections made will not be applied. However, you must make a selection in order to proceed to Step 3.
     Note

     The Permissions and Allow all fields are displayed only for System Administrator accounts.
   • API Path: This field is populated with a default value of ms_sentinel. If there is already at least one Service for the Microsoft Sentinel App on your ThreatConnect instance, replace the default value with a unique API path.
   • Enable Notifications: Select this checkbox to send an email when the Service fails to start. 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 a ThreatConnect System Administrator’s email address.
   • Max restart attempts on failure: Enter the number of times ThreatConnect should try to restart the Service if it fails. The recommended value is 10.
   • Click Next.
6. Follow the instructions in Table 1 to fill out the fields in Step 3 (Parameters) of the Create Service drawer.

    

   Name	Description	Required?
   Client ID	Enter the client ID (also known as the application ID) of the app you registered in Azure AD.	Yes
   Client Secret	Enter the value of the client secret added to the app you registered in Azure AD.	Yes
   Tenant ID	Enter the ID of the Azure AD tenant.	Yes
   Sentinel Workspace ID	Enter the ID of the Microsoft Sentinel workspace.	Yes
   Sentinel Source Name	Enter the name of the Microsoft Sentinel source the Indicators will be associated with. In Microsoft Sentinel, you can filter Indicators by their source. Note By default, the Microsoft Sentinel App prepends ThreatConnect- to the specified source name to support an Azure visualization workbook in the ThreatConnect Solution for Microsoft Sentinel. Note The Sentinel Source Name parameter corresponds to the Source Name field mapped from ThreatConnect to Microsoft Sentinel, as described in the “Data Mappings” section.	Yes
   ThreatConnect Access ID	Enter the ThreatConnect API user account’s Access ID. Important The Organization that the ThreatConnect API user account belongs to is the Organization for which the Service is configured. This Organization and the Communities and Sources it owns or is a member of are the owners you can query for ThreatConnect Indicators to send to Microsoft Sentinel.	Yes
   ThreatConnect Secret Key	Enter the ThreatConnect API user account’s Secret Key.	Yes
   Schedule Interval Hours	Enter the interval, in hours, to send Indicators from ThreatConnect to Microsoft Sentinel.	Yes
   TTL Hours - Address	Enter the time to live (TTL), in hours, for Address Indicators in Microsoft Sentinel.	Yes
   TTL Hours - ASN	Enter the time to live (TTL), in hours, for ASN Indicators in Microsoft Sentinel.	Yes
   TTL Hours - CIDR	Enter the time to live (TTL), in hours, for CIDR Indicators in Microsoft Sentinel.	Yes
   TTL Hours - Email Address	Enter the time to live (TTL), in hours, for Email Address Indicators in Microsoft Sentinel.	Yes
   TTL Hours - Email Subject	Enter the time to live (TTL), in hours, for Email Subject Indicators in Microsoft Sentinel.	Yes
   TTL Hours - File	Enter the time to live (TTL), in hours, for File Indicators in Microsoft Sentinel.	Yes
   TTL Hours - Host	Enter the time to live (TTL), in hours, for Host Indicators in Microsoft Sentinel.	Yes
   TTL Hours - Registry Key	Enter the time to live (TTL), in hours, for Registry Key Indicators in Microsoft Sentinel.	Yes
   TTL Hours - URL	Enter the time to live (TTL), in hours, for URL Indicators in Microsoft Sentinel.	Yes

7. Click Save to save the Service.

Microsoft Sentinel UI

After installing the Microsoft Sentinel App in ThreatConnect and configuring a corresponding Service, you can access the Microsoft Sentinel Service user interface (UI), where you can manage the ThreatConnect integration with Microsoft Sentinel.

Follow these steps to access the Microsoft Sentinel Service UI:

1. Log into ThreatConnect with an Organization Administrator account.
2. From the Automation & Feeds dropdown on the top navigation bar, select Services.
3. Locate and turn on the Microsoft Sentinel REST API Service for your Organization.
4. Click the link in the Service’s API Path field.

The following screens are available in the Microsoft Sentinel UI:

• CONFIGURE
• JOBS
• TASKS
• REPORT

CONFIGURE

The CONFIGURE screen (Figure 3) allows you to create and manage the TQL queries that define the sets of Indicators to send from ThreatConnect to Microsoft Sentinel.

Click Edit to access options to add, edit, reorder, and delete TQL queries.

Add TQL Query

Follow these steps to add a TQL query for the Microsoft Sentinel Service:

1. Click Edit on the CONFIGURE screen (Figure 3).
2. Click Add.
3. Fill out the fields on the Add TQL Configuration window (Figure 4) as follows:

   

    

   • Owners to Query: Select the ThreatConnect owners in which to query for Indicators. The owners listed in this dropdown are the Organization the Service is configured for (that is, the Organization that the API user account whose credentials are entered in the Service’s configuration belongs to) and the Communities and Sources the Organization owns or is a member of.
   • Indicator Types to Retrieve: Select the ThreatConnect Indicator types for which to query.
   • TQL: Enter the TQL query that defines the set of Indicators to retrieve.
   • Sort Field: Select the field by which to sort results returned from the TQL query.
   • Sort Direction: Select the sort direction for results returned from the TQL query.
   • Click Submit to add the TQL query.
4. Click Save on the CONFIGURE screen to save the query.

Manage TQL Query Order

The order of TQL queries in the table on the CONFIGURE screen determines how the Microsoft Sentinel Service handles duplicate Indicators. When TQL queries return duplicate Indicators, only the copy of the Indicator returned from the query in the highest position in the table is sent to Microsoft Sentinel. All other copies of the Indicator returned from queries in lower positions in the table are not sent.

Follow these steps to manage TQL query order for the Microsoft Sentinel Service:

1. Click Edit on the CONFIGURE screen (Figure 3).
2. Click the arrows on the left of the Owners column to reorder TQL queries in the table (Figure 5).

    

3. Click Save  to save the TQL query order.

Save Changes

Changes made to TQL queries are not saved automatically. Follow these steps to save changes after you add, edit, reorder, or delete TQL queries:

1. Click Save on the CONFIGURE screen (Figure 5).
2. Select one of the following options on the Save Changes window (Figure 6).

   

    

   • Cancel: Select this option to cancel your changes.
   • Save and Run Delta Update: Select this option to save your changes and send only Indicators modified after the Service’s last run to Microsoft Sentinel during the next scheduled update.
   • Save and Run Full Update: Select this option to save your changes and send all Indicators returned by the TQL queries to Microsoft Sentinel during the next scheduled update.

JOBS

The JOBS screen (Figure 7) breaks down ThreatConnect data queries and data export into Microsoft Sentinel into manageable Job-like tasks.

You can filter Microsoft Sentinel Service Jobs by the following elements:

• Status: Select Job statuses to display on the JOBS screen.
• Request ID: Enter test into this box to search for a request by its Request ID.

TASKS

The TASKS screen (Figure 8) displays all Tasks that may be part of a Job, including Tasks in the ingestion pipeline (downloading data from ThreatConnect and uploading data to Microsoft Sentinel), and Tasks for the Microsoft Sentinel Service, such as the Cleaner.

REPORTS

The REPORTS screen provides an ERRORS view (Figure 9) that displays errors that have occurred for Job requests.

Data Mappings

The data mappings in Table 2 through Table 10 illustrate how data are mapped from the ThreatConnect data model to Microsoft Sentinel Intelligence API endpoints.

IP Address (IPv4 and IPv6)

ThreatConnect object type: Address Indicator

CIDR

ThreatConnect object type: CIDR Indicator

Domain Name

ThreatConnect object type: Host Indicator

File

ThreatConnect object type: File Indicator

URL

ThreatConnect object type: URL Indicator

ASN

ThreatConnect object type: ASN Indicator

Email Address

ThreatConnect object type: Email Address Indicator

Email Subject

ThreatConnect object type: Email Subject Indicator

Registry Key

ThreatConnect object type: Registry Key Indicator

Frequently Asked Questions (FAQ)

How does the Microsoft Sentinel App differ from the Microsoft Security Graph Job App?

As of version 1.0.2, the Microsoft Sentinel App uses the updated Microsoft Sentinel upload indicators API, which supports uploading Indicators in STIX 2.1 format. Previous versions of the Microsoft Sentinel App used the legacy Microsoft Sentinel upload indicators API.

Because the Microsoft Sentinel App is based on the STIX 2.1 format, the variety of threat intelligence data is well normalized, but limited compared with the types of data the Microsoft Security Graph App offers. To address this difference, ThreatConnect publishes more available data than the STIX 2.1 format offers within the Description field in Microsoft Sentinel.

If I have been using the Microsoft Security Graph App, what do I have to do to migrate to the Microsoft Sentinel App?

There are no steps you need to complete to migrate from the Microsoft Security Graph App to the Microsoft Sentinel App. One key benefit of the Microsoft Sentinel App is that it prevents the duplication of Indicators. Even if there are duplicate Indicators across the ThreatConnect owners you are querying, the App will send only one copy of the Indicator to Microsoft Sentinel.

Are there any limitations I should be aware of when using the Microsoft Sentinel App?

Microsoft Sentinel has established upload indicators API throttle limits of 100 Indicators per request and 100 requests per minute. If a Microsoft Sentinel Service reaches either of these limits, it will wait one minute before attempting to send more Indicators to Microsoft Sentinel.

The Microsoft Sentinel Service is most likely to hit this limit when running a full update, which is the initial upload of data from ThreatConnect to Microsoft Sentinel.

Does the Microsoft Sentinel App send Indicators from ThreatConnect to Microsoft Defender?

The Microsoft Sentinel Upload Indicators API only sends Indicators from ThreatConnect to Microsoft Sentinel. As such, you cannot use the Microsoft Sentinel App to send Indicators from ThreatConnect to Microsoft Defender.

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.
STIX™ is a trademark of The MITRE Corporation.

30079-04 EN Rev. A