Slack Plugin for Graylog

This plugin is for Graylog 3.1 and above. If you are looking for older Graylog plugin, please checkout https://github.com/KongZ/graylog-plugin-slack

Note: The plugin ownership was transferred from https://github.com/omise to https://github.com/KongZ

Migration to 4.1

Since Graylog 4.1 was released with a built-in Slack integration with same ID slack-notification-v1 with this plugin. So I have decided to rename this plugin ID to graylog-plugin-slack-notification

The error showing on Graylog 4.1 when you installing the plugin

1) [Guice/DuplicateMapKey]: Duplicate key "slack-notification-v1" found in Map<String, EventNotification$Factory>.

You need to run the following command on Mongodb before installing a new plugin in order to migrate current configuration to a new plugin version

graylog:PRIMARY> use graylog
graylog:PRIMARY> db.auth('graylog', 'your-graylog-mongodb-password');
graylog:PRIMARY> db.event_notifications.updateMany({"config.type":"slack-notification-v1"},{$set: { "config.type": "graylog-plugin-slack-notification"}})

Version Compatibility

Plugin Version	Graylog Version
4.2.x	4.2.x
4.1.x	4.1.x
4.0.x	4.0.x
3.3.x	3.3.x
3.1.x	3.1.x
2.x.x	2.x.x

Features

Notification

Send notification messages to Slack when alert was raised.

The screenshot below shows a sample of Slack notification.

• Send message directly to user or channel
• Support Slack attachment short mode
• Mention users or channels when alert. Users can be mentioned by field variables
• Provide link back to event times
• Support event timestamp in footer text
• Support proxy
• Support custom fields in Slack attachment
• Support acknowledge buttons. Required Slack app's token
• Support pre-formatted text in backlog item
• Support event definition fields
• Support JMTE in backlog fields and footer

The screenshot below shows a pre-formatted text with acknowledgement buttons

Mention users or channels when alert

This feature requires Slack Token. The webhook does not allow to tag or mention users. To setup a Slack App and get Token, please see https://api.slack.com/slack-apps You need the following permissions If you are using Slack Bot Token. Token starts with xoxb

• users:read for lookup Slack user ID from display name
• chat:write for sending message If you are using Slack User Token. Token starts with xoxp
• users:read for lookup Slack user ID from display name
• chat:write, chat.write:user, chat:write:bot for sending message
• chat:write.customize for setting sender name and icon

Acknowledgment buttons

The acknowledgment buttons also requires Slack Token. You cannot use Slack Incoming Webhook to creates buttons. See Slack Interactive Message for detail of Slack API.

The screenshot below shows an acknowledgement buttons

The screenshot below shows a result of acknowledged

Installation

1. You can Download the plugin and place the .jar file in your Graylog plugin directory. The plugin directory is the plugins/ folder relative from your graylog-server directory by default and can be configured in your graylog.conf file.

2. Remove all previous version of Graylog plugin Slack .jar files. in plugins directory.

3. Restart a graylog server. Plugin will automatically migrate all your configured data to a new version.

Usage

For Slack:

Step 1: Create Slack Incoming Webhook (If you just want to send only message)

Create a new Slack Incoming Webhook (https://<organization>.slack.com/services/new/incoming-webhook) and copy the URL it will present to you. It will ask you to select a Slack channel but you can override it in the plugin configuration later.

Step 2: Create Slack App (If you want to mention someone when send notifications to Slack or use interactive buttons)

Create a new Slack App https://api.slack.com/apps?new_app=1 and copy the Slack Token into plugin configuration.

The screenshot below shows a sample configuration screen. The sample here use extractor to extract and create fields for SSH login name (ssh_login_from) and IP (ssh_login_ip) from logs. The configure Notify User to mention people who SSH to the server with Acknowledge button.

Troubleshooting

HTTPS connection fails

If the Java runtime environment and the included SSL certificate trust store is too old, HTTPS connections to Slack might fail with the following error message:

Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

In this case, add the Slack SSL certificate manually to Java's trust store similar to the process described in the Graylog documentation.

Error occurred when clicks a Slack button.

Slack App required HTTPS connection between your Graylog server and Slack server. You need to configure your Graylog server with a valid certificate file. Make sure your Graylog server open a firewall allow Slack server to communicate with.

Most common errors and describe will be send to you by Slack's bot when you click a button. If trouble persists, you can turn a debug log on Graylog server to see more detail on log files.

Please see more information on Slack aps here https://api.slack.com/slack-apps

Build

This project is using Maven and requires Java 8 or higher.

You can build a plugin (JAR) with mvn package.