Microsoft Sentinel Integration User Guide

Overview

The ThreatConnect^® integration with Microsoft Sentinel™ uses the Upload Indicators API to send Indicators from ThreatConnect to Microsoft Sentinel. Using the Indicators from ThreatConnect, Microsoft Sentinel will then 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

When selecting Indicators to send to Microsoft Sentinel, users can leverage ThreatConnect Query Language (TQL) to filter which Indicators will be sent.

Dependencies

ThreatConnect Dependencies

• Active ThreatConnect Application Programming Interface (API) key

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

Connecting ThreatConnect to Microsoft Sentinel

Before you can use the Microsoft Sentinel App in ThreatConnect, you must connect ThreatConnect to Microsoft Sentinel.

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

   When registering an app in Azure AD, an account type of Single Tenant should be selected and the optional Redirect URI field should be left empty in most cases.
2. Obtain the values for the following items, as they are required when configuring the Microsoft Sentinel App in ThreatConnect:
   1. 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.
   2. Client Secret: The value of the client secret created in Step 1. 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.
   3. Tenant ID: The ID of the Azure AD tenant. To obtain this value, navigate to 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.

Application Setup and Configuration

Follow these steps to install the Microsoft Sentinel App in ThreatConnect and create a corresponding Service for it.

1. Log into ThreatConnect with a System Administrator account.
2. Install the Microsoft Sentinel App via TC Exchange™.
3. After the Microsoft Sentinel App is installed, hover over Playbooks on the top navigation bar and select Services. The Services tab of the Playbooks screen will be displayed
4. Click the + NEW button at the upper-left corner of the screen. The Select screen of the Create Service drawer will be displayed (Figure 1).
   

    

   • Name: Enter a descriptive name for the Service. If you have multiple Microsoft Sentinel instances, include a reference to the intended Microsoft Sentinel instance in the Service's name.
   • Type: Select Service API.
   • Service: Select Microsoft Sentinel v.1.0.0.
   • Click the NEXT button.
5. The Configure screen of the Create Service drawer will be displayed (Figure 2).
   

    

   • Launch Server: Select tc-job.
   • Permissions: Select the Organization(s) that will have access to the Service.
   • Allow all: Select this checkbox to grant all Organizations on the ThreatConnect instance access to the Service.
   • API Path: This field is populated with a default value of ms_sentinel automatically. Use this value unless you have multiple Organizations and multiple API users that will use Microsoft Sentinel. In this scenario, enter a unique API path for the Service.
   • Enable Notifications: Select this 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.
6. The Parameters screen of the Create Service drawer will be displayed (Figure 3).
   

    

   • Fill out all required fields on this screen. For a description of each field, see the “Configuration Parameters” section.
   • Click the SAVE button.
7. The Service will now be displayed on the Services tab of the Playbooks screen (Figure 4). Toggle the REST API 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.

After the Service is activated, you can click the link in the Service’s API Path field to access the ThreatConnect Microsoft Sentinel App user interface (UI). See the “Microsoft Sentinel ThreatConnect App UI” section for more information about the various screens and actions you can perform within this UI.

Configuration Parameters

Parameter Definitions

The parameters defined in Table 1 apply to the configuration parameters available when configuring a Service for the App.

¹ This parameter corresponds to the Source Name field mapped from ThreatConnect to Microsoft Sentinel, as described in the "Data Mappings" section.

Microsoft Sentinel ThreatConnect App UI

After successfully installing the Microsoft Sentinel App and configuring a corresponding Service in ThreatConnect, as described in the “Application Setup and Configuration” section, you can access the ThreatConnect Microsoft Sentinel App UI. This UI allows you to interact with and manage ThreatConnect's Microsoft Sentinel integration.

Follow these steps to access the ThreatConnect Microsoft Sentinel App UI:

1. Log into ThreatConnect with a System Administrator account.
2. On the top navigation bar, hover over Playbooks and select Services. The Services tab of the Playbooks screen will be displayed. 
3. Locate the Service created for the Microsoft Sentinel App and then click the link in the Service’s API Path field. The CONFIGURE screen of the ThreatConnect Microsoft Sentinel App UI will open in a new browser tab.

The following screens are available in the ThreatConnect Microsoft Sentinel App UI:

• CONFIGURE
• JOBS
• TASKS
• REPORT

CONFIGURE

The CONFIGURE screen (Figure 5) allows you to identify which Indicators to send to Microsoft Sentinel using one or more TQL queries.

Clicking the Edit button at the top right of the CONFIGURE screen will display options for creating, editing, deleting, and reordering TQL queries (Figure 6).

Adding a TQL Query

While the CONFIGURE screen is in an editable state (Figure 6), click the Add button below the table. The Add TQL Configuration window will be displayed (Figure 7).

• Owners to Query: Select one or more ThreatConnect owners in which to query for Indicators.
• Indicator Types to Retrieve: Select one or more ThreatConnect Indicator types for which to query.
• TQL: Enter the desired query written in TQL.
• Sort Field: Select the field by which to sort results returned from the TQL query.
• Sort Direction: Select the direction in which to sort results returned from the TQL query.
• Click the Submit button to add the TQL query.

Editing a TQL Query

While the CONFIGURE screen is in an editable state (Figure 6), click Editin the leftmost column for a TQL query to edit it. A window similar to Figure 7 will be displayed with options to edit the TQL query. Make the desired changes to the query, and then click the Submit button in this window.

Deleting a TQL Query

While the CONFIGURE screen is in an editable state (Figure 6), click Deletein the leftmost column for a TQL query to delete it.

Managing the Order of TQL Queries

The order of TQL queries in the table on the CONFIGURE screen determines how the App handles duplicate Indicators. In this scenario, only the copy of the Indicator returned from the query in the highest position in the table will be sent to Microsoft Sentinel; all other copies of the Indicator returned from queries in lower positions in the table will not be sent.

While the CONFIGURE screen is in an editable state and there are at least two TQL queries listed in the table (Figure 8), use the arrows to the left of the Owners column to adjust the order of the queries.

Saving Changes on the CONFIGURE Screen

While the CONFIGURE screen is in an editable state (Figure 6), Save and Cancel buttons will be displayed at the top right of the screen. You must click the Save button after performing one or more actions on this screen to save your changes (i.e., creating a TQL query, editing a TQL query, deleting a TQL query, and updating the order of TQL queries). After you click the Save button, the Save Changes window will be displayed (Figure 9).

• Save and Run Delta Update: Click this button to save your changes and wait for the next scheduled update to perform a delta update, which sends only the Indicators modified since the last time the App ran to Microsoft Sentinel.
• Save and Run Full Update: Click this button to save your changes and wait for the next scheduled update to perform a full update, which sends all Indicators returned by the TQL queries to Microsoft Sentinel.
• Cancel: Click this button to close the Save Changes window without saving your changes.

To discard the changes made on the CONFIGURE screen, click the Cancel button at the top right of the screen (Figure 2).

JOBS

The JOBS screen (Figure 10) breaks down the ingestion of Microsoft Sentinel data into manageable Job-like tasks.

• Job Type: If desired, select a Job type by which to filter Jobs. Available types include ad-hoc and scheduled. 
• Status:If desired, select a Job status by which to filter Jobs. Available statuses include the following:
  1. Download In Progress
  2. Download Complete
  3. Convert In Progress
  4. Convert Complete
  5. Upload In Progress
  6. Upload Complete
• Request ID: If desired, enter text into this box to search for a specific Job by its request ID.

TASKS

The TASKS screen (Figure 11) is where you can view and manage the Tasks for each Job.

REPORTS

The REPORTS screen provides an ERRORS view (Figure 12) that displays errors for each request in a tabular format. Details provided for each error include the raw contents of the error, the error's message, and the step at which the error occurred.

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)

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 established Upload Indicators API throttle limits of 100 Indicators per request and 100 requests per minute. If the App reaches either of these limits, it will wait one minute before reattempting to send Indicators to Microsoft Sentinel.

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

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

The Microsoft Sentinel App uses the Microsoft Sentinel Upload Indicators API, which supports uploading Indicators in STIX™ 2.1 format.

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.

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-02 EN Rev. A