Microsoft Teams

Overview

This document will help you set up InsightConnect for use with MicrosoftTeams.

There are a few things you need before you get started:

  1. Have an existing user account. If needed create a new user or service account: https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/add-users-azure-active-directory
  2. Create an Azure Application with the correct permissions: https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal

Permissions for each are listed below in two sections, Send / Receive and Teams Management.

The InsightConnect Teams Plugin uses delegated permissions to talk to your Teams instance through Microsoft Graph API. This will require both a user account that’s authorized to send and receive messages on the channel(s) you will be monitoring and an application with the correct permissions to act on behalf of that user.

The application permissions are listed below and must be delegated to act on behalf of a user.

The user must be included in the Teams team or Azure group that this application will monitor.

Permissions

The permissions here are split into two sections. If your workflow only needs to send and receive messages, then the permissions needed are minimal. However, if you’d like to manage your teams through the application, elevated permissions will be needed as the application will be performing administrative tasks.

Send and Receive

Minimum application permissions needed for send/receive:

  • Chat.ReadWrite (Delegated)
  • Group.ReadWrite.All (Delegated)

Reference

User Permissions for send/receive:

The user simply needs to be a part of the Team that the plugin will send and receive messages.

Teams Management

Minimum application permissions needed for Teams management:

  • Directory.ReadWrite.All
  • Group.ReadWrite.All

Reference

User Permissions for Teams Management:

The user used in this instance will need to have elevated permissions as well, as the application is working on their behalf. To enable the following actions for your user, include them in the specified administrative group in Azure.

  • Create Team Enabled Group: Global Administrators - Team enablement requires changing the properties on a group, that can only be done by a Global Admin.
  • All other actions: User Administrators - Add and remove users from a group, create channel, and remove can be done by a User Administrator

Configure the connection in InsightConnect:

The Teams plugin in InsightConnect will require the following information:

For the Application ID and Directory ID go to your application registration in Azure and check the overview.

For the Application Secret, go to “Certificates and secrets” in the left menu.

The username in InsightConnect must be fully qualified. For example @ or *joey@rapid7.onmicrosoft.com

Create a new secret using the “New client secret” button.

NOTE: The client secret will only be available when you first create the secret. After you leave this screen it will be hidden. Be sure to save it someplace safe.

Automatically Extract Indicators from a Microsoft Teams Message

Instead of constantly switching contexts in different tools, you can configure your chat solutions within InsightConnect to listen for message commands that will kick-off workflows. Plus, we support message threading in Slack and Microsoft Teams so you can conveniently organize your chat communications. Additionally, InsightConnect maintains a growing library of prebuilt workflow templates that trigger functionality from Slack and Microsoft teams that can be imported with one click.

Our Microsoft Teams plugin automatically extracts commands and common network or security indicators from your messages. You can use these variables to configure additional workflow actions without having to worry about configuring potentially complex regex or pattern match steps.

To configure a workflow to kick-off from a Microsoft Teams message, update the Microsoft Teams trigger (the first step in your workflow) with the channel name to monitor your Microsoft Teams environment. Then, to run your workflow, send a message to the specified Microsoft Teams channel.

Each of your Microsoft Teams messages follows the same format: [command] [indicator]. An example command might look like this: !block-host 1.1.1.1. We automatically extract and capture commands, like block-host in this case, in a variable called $first_word.

When your command is followed by a commonly used network or security indicator, our chatbot detects the format of the indicator, extracts it automatically, and stores it in an output variable.

These are the commonly used network and security indicator types we capture and store:

  • IP addresses (IPv4 and IPv6)
  • MD5 hashes
  • SHA1 hashes
  • SHA256 hashes
  • MAC addresses
  • Email addresses
  • Domain names
  • URLs An artifact card displays the contents of the indicator variables, parsed from a message that contained a multitude of indicators

You can use these output variables later in your workflow to easily configure further actions. For example, add a hash to a denylist, enrich a URL or domain with a threat intelligence plugin, delete an email from user inboxes, or block an IP address, all without having to parse these indicators out of your chat messages manually.

Appendix

InsightConnect Test App Setup:

Other helpful information:

Get access on behalf of a user

Delegated permissions

Graph Permissions Reference

User Permissions