Welcome to the Splunk Microsoft Teams messages publication addon documentation

This application provides alert actions for Microsoft Teams messages publication to allows advanced messages publication from Splunk, including:

• Markdown support
• Defining options globally or on a per alert basis (per alert override)
• Defining comma separated list of fields which will be dynamically used to generated the markdown supported publication
• Choosing icon link for message publication
• Activating potential link action and defining its link

Overview:

About

• Author: Guilhem Marchand, Splunk certified consultant and part of Splunk Professional Services
• First release published in January 2020
• License: Apache License 2.0

Compatibility

Splunk compatibility

Since the version 1.1.x, the application is compatible with Splunk 8.0.x and later only.

The latest release available for Splunk 7.x is the release 1.0.20.

Web Browser compatibility

The application can be used with any of the supported Web Browser by Splunk:

https://docs.splunk.com/Documentation/Splunk/latest/Installation/Systemrequirements

Support & donate

I am supporting my applications for free, for the good of everyone and on my own private time. As you can guess, this is a huge amount of time and efforts.

If you enjoy it, and want to support and encourage me, buy me a coffee (or a Pizza) and you will make me very happy!

This application is community supported.

To get support, use of one the following options:

Splunk Answers

Open a question in Splunk answers for the application:

• https://answers.splunk.com/app/questions/4855.html

Splunk community slack

Contact me on Splunk community slack, and even better, ask the community!

• https://splunk-usergroups.slack.com

Open a issue in Git

To report an issue, request a feature change or improvement, please open an issue in Github:

• https://github.com/guilhemmarchand/TA-ms-teams-alert-action/issues

Email support

• guilhem.marchand@gmail.com

However, previous options are far betters, and will give you all the chances to get a quick support from the community of fellow Splunkers.

Download

The Splunk application can be downloaded from:

Splunk base

• https://splunkbase.splunk.com/app/4855

GitHub

• https://github.com/guilhemmarchand/TA-ms-teams-alert-action

Deployment and configuration:

Deployment & Upgrades

Deployment matrix

Splunk roles	required
Search head	yes
Indexer tiers	no

If Splunk search heads are running in Search Head Cluster (SHC), the Splunk application must be deployed by the SHC deployer.

Dependencies

There are currently no dependencies for the application.

However, if you deploy the Splunk_SA_CIM package, make sure you have declared the cim_modactions index as the Add-on logs would automatically be directed to this index is the SA CIM application is installed on the search heads.

If the Splunk_SA_CIM is not installed, the Add-on logs will be generated in the _internal index. (This is a normal behaviour for Add-on developped with the Splunk Add-on builder that provide adaptive response capabilities)

Initial deployment

The deployment of the Splunk application is very straight forward:

• Using the application manager in Splunk Web (Settings / Manages apps)
• Extracting the content of the tgz archive in the “apps” directory of Splunk
• For SHC configurations (Search Head Cluster), extract the tgz content in the SHC deployer and publish the SHC bundle

Upgrades

Upgrading the Splunk application is pretty much the same operation than the initial deployment.

Configuration and usage

Global configuration

Once the application has been deployed, you can access to the main standard configuration and the app related items by opening the app and accessing to the configuration navigation bar menu:

Configuration home page:

Add-on settings:

Default MS team channel

This defines a default Webhook URL to be used by default for the publication of messages.

The Webhook URL can be defined with or without https://, therefore https is enforced for certification compliance purposes and non SSL traffic is not allowed.

Finally, the default channel Webhook URL can be overridden on a per alert basis, this global configuration is only used if the per alert URL is not set.

This setting is optional and can be let unset in the global app configuration.

Default MS teams image link

In a similar fashion, this defines the icon link to be used by default when publishing to channels, this setting can be overridden on a per alert basis as well.

This setting is optional and and can be let unset in the global app configuration.

URL regex compliancy checker

To avoid allowing the target URL to be set to a free value, and prevent data exflitration, you use this option to define a valid regular expression that will be applied automatically when the alert action triggers.

If the regular expression does not match the target URL, the alert action will be refused and the Python backend will not proceed to the Webhook call.

For instance, you can include a simple litteral expression to match your tenant ID:

https://mydomain.ic365.webhook.office.com/webhookb2/

If an alert is attempting to publish a message that does not comply with the regex check, the Add-on logs will return an error and the publication will not be executed:

SSL certificate validation

If the option is checked, the Python backend will require the SSL certificate to be a valid certificate.

Per alert configuration

When activating the Microsoft Teams channel publication alert action, different options are made available:

Override default Webhook URL

This defines the Webhook URL for the message publication, and will override any existing global configuration.

This item is optional only if the global equivalent has been set (obvious), similarly to global https is automatically enforced.

Message Activity Title

This defines the main title of the message to be published, this setting is required.

Message fields list

This defines a comma separated list of fields which result from the alert, these fields will be automatically extracted and formatted to be part of the published message.

This setting is required, and at least one field needs to be defined.

Override MS teams image link for publication

This defines the icon link to be used for the message publication, and will override any global setting that has been set.

Theme color

Specifies a custom brand color for the card in hexadecimal code format. (optional, defaults to 0076D7)

Potential Action Name and URL

These two items define the action link button and target that can automatically be added when the message is published in Microsoft Teams.

For this option to be activated, both of these items need to be configured, note that the URL can accept dynamic input fields resulting from the search.

A second OopenURI action can be added.

Message example:

HttpPOST Action

You can add an HttpPOST action which users can use directly in Microsoft Teams, this is allows interacting with Splunk or an external system directly within the Teams interface.

For more information, please consult the following documentation:

https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference

Status dashboard

An overview dashboard is available as the home page in the application to provide a minimal view over messages successfully published, and failures if any:

Should there be any failures in publishing messages, the related information and logs are made available easily.

In addition, several reports and links provide quick access to the logs location.

Out the box alert for publishing failures detection

For a total operational safety, a builtin Splunk alert is provided which you can enable to get alerted if any messages failed to be published:

Failures for publication can have different causes like network issues, typo or misconfiguration, as always the truth will be in the logs.

Using the alert action for non admin users

For non admin users to be able to use the alert action, the following role is provided out of the box:

• msteams_alert_action

This role needs to be inherited for the users, or your users to be member of this role.

The role provides:

• capability list_storage_passwords
• capability list_settings
• write permission to the resilient KVstore kv_ms_teams_failures_replay

Versions and build history:

Release notes

Version 1.1.3

• Fix - Issue #40 - SHC replication fails, server.conf config missing in package

Version 1.1.2

• Fix - unexpected local.meta was delivered within the tgz release archive

Version 1.1.1

• Fix - Upgrade of Splunk ucc-gen to release 5.5.9 to fix an issue with the notification in configuration UI when an Add-on has no account section

Version 1.1.0

New major release: Migration from AoB framework to splunk-ucc-generator:

• Enhancement - the migration to splunk-ucc-generator provides a better and modern framework for Add-ons
• Change - support is dropped for Splunk 7.x, version 1.1.x only supports Splunk 8.x and Python3
• Change - JQuery migration for the Overview dashboard

Version 1.0.20

• Change - Issue #37 - Add help-link class, open in a new window, and external icon

Version 1.0.19

• Change - Issue #35 - Splunk Python SDK upgrade to 1.6.15

Version 1.0.18

• Feature: Issue #28 - Theme Color as configurable option #28

Version 1.0.17

• Fix: Issue #26 - ensure aob configuration replicates in shc environment #26
• Change: For Splunk Cloud vetting purposes, ensure https check verifies the URI starts by https rather than contains https

Version 1.0.16

• Fix: Splunk Cloud vetting failure due to session token available in debug mode

Version 1.0.15

• Fix: regression introduced in version 1.0.13 with the addition parameter for SSL verification, if a deployment is upgraded from a previous version, the alert would fail until an admin enters the configuration UI and saves the configuration again

Version 1.0.14

• Fix: Issue #20 Provides an option to disable SSL certificate verification (but enabled by default) to avoid failures with environments using SSL interception
• Feature: Issue #17 Provides an option on a per alert basis to allow ordering of the fields in the message by using the fields list ordering rather than alphabetical ordering
• Fix: SLIM error for app vetting due to the introduction of the targetWorkloads in app.manifest which requires version 2.0.0 of the app.manifest schema

Version 1.0.13

• Fix: Issue #20 Provides an option to disable SSL certificate verification (but enabled by default) to avoid failures with environments using SSL interception
• Feature: Issue #17 Provides an option on a per alert basis to allow ordering of the fields in the message by using the fields list ordering rather than alphabetical ordering

Version 1.0.12

• Fix: Default timed out value during REST calls are too short and might lead to false positive failures and duplicated creation of messages

Version 1.0.11

• Change: For Splunk Cloud vetting purposes, enforce https verification in modalert_ms_teams_publish_to_channel_replay_helper.py
• Change: For Splunk Cloud vetting purposes, explicit Python3 mode in restmap.conf handler

Version 1.0.10

• Change: For Splunk Cloud vetting purposes, SSL verification is now enabled for any external communications

Version 1.0.9

• Fix: Provide an embedded role msteams_alert_action that can be inherited for non admin users to be allowed to fire the action and work with the resilient store feature

Version 1.0.8

• unpublished

Version 1.0.7

• Feature: Integration of the resilient store capabilities, which rely on a KVstore to automatically handle and retry temporary message creation failures with resiliency
• Feature: Overview dashboard update to reflect the resilient store integration, news reports and alerts
• Fix: Metadata avoid sharing alerts, reports and views at global level

Version 1.0.6

• Fix: Proxy configuration was not working and not used
• Change: Overview dashboard switched to dark theme
• Change: Configure URL message update

Version 1.0.5

• Fix: Global settings are not properly use and do not define default values to be overridden on a per alert basis, this release fixes these issues
• Fix: Events iteration issue, if one was defining a massive alert with no by key throttling, building the Json object would fail
• Fix: Json escape character protection for OpenURI values (Open URL potential action)

Version 1.0.4

• Fix: Fields resulting from the Splunk search stored in the facts section of the message card were not ordered alphabetically properly, this is now fixed and fields are systematically sorted
• Feature: Allows activating a second openURL potential action per alert
• Feature: Allows defining an HttpPOST potential action in MS Teams per alert
• Fix: Better and shorter explanation of options

Version 1.0.3

• Fix: Order json object alphabetically before post operation to provide ordered fields in message publication.
• Fix: Sourcetype on non CIM deployments within saved searches and overview dashboard.
• Fix: Disable markdown support for text value fields to avoid being wrongly interpreted by Teams, in the context of Splunk we most likely want potentially piece raw block of text.

Version 1.0.2

• Fix: Timechart not working in overview to bad field name

Version 1.0.1

• Fix: avoids publication failure due to json illegal characters

Version 1.0.0

• initial and first public release