Mattermost¶

ASAB IRIS can send notifications to Mattermost.

Use Mattermost when LogMan.io notifications should appear in a Mattermost channel or be sent directly to a Mattermost user.

Mattermost notifications can be triggered through IRIS over HTTP or by Kafka notifications.

Note

Mattermost output is available in deployments that include ASAB IRIS Mattermost notification support.

Prerequisites¶

Before configuring Mattermost, make sure that:

access to the Mattermost server where notifications will be sent is available
a Mattermost bot account is available for IRIS
a bot access token for that account is available
the bot can post to the target Mattermost channel
the target channel ID is available if notifications should use a default channel
the bot username is available if IRIS should send direct messages
the LogMan.io server can reach the Mattermost server over HTTPS
a secure place is available for storing the Mattermost bot token

Supported destinations¶

IRIS can send Mattermost notifications to:

a configured default channel
a specific Mattermost channel ID
a direct message with a Mattermost user

For direct messages, IRIS must know the username of the Mattermost bot account and the username of the target user.

Required configuration fields¶

Field	Description
`url`	Base URL of the Mattermost server.
`token`	Bot token used by IRIS to call the Mattermost API.

Optional configuration fields¶

Field	Description
`bot_username`	Username of the Mattermost bot account. Required for direct messages.
`security_channel_id`	Default channel ID used when a notification does not provide `channel_id` or `username`.

Configuration sample¶

Edit model.yaml to configure the asab-iris service:

/Site/model.yaml

define:
  type: rc/model

services:
  asab-iris:
    instances:
      - node1
    asab:
      config:
        mattermost:
          url: "https://mattermost.example.com"
          token: "{{MATTERMOST_TOKEN}}"
          bot_username: "logman-iris"
          security_channel_id: "logman-alerts-channel-id"

Mattermost setup¶

Create or choose a Mattermost bot account for IRIS.
Create a bot access token for that account.
Copy the token to mattermost.token.
Copy the Mattermost server URL to mattermost.url, for example https://mattermost.example.com.
If IRIS should send direct messages, set mattermost.bot_username to the bot account username.
If IRIS should use a default channel, copy the channel ID and set it as mattermost.security_channel_id.
Store the Mattermost token in Vault or in the deployment secret store used by the LogMan.io installation.
Update /Site/model.yaml.
Apply the model from the Library, or run the deployment apply command used by the installation.
Send a test Mattermost notification.

Note

security_channel_id is a Mattermost channel ID, not a display name. Use the channel ID from Mattermost administration or from the channel information in Mattermost.

Verify the configuration¶

The configuration is ready when:

ASAB IRIS starts without Mattermost configuration errors
the bot token belongs to the expected Mattermost bot account
a test notification appears in the configured default channel or requested channel
direct messages are delivered, if username delivery is used
the ASAB IRIS service logs do not contain Mattermost API errors

Sending to the default channel¶

If security_channel_id is configured, notifications can omit the destination and IRIS sends them to the default channel.

{
  "body": {
    "template": "/Templates/Mattermost/message.md",
    "params": {
      "name": "LogMan.io",
      "severity": "High",
      "message": "New security notification"
    }
  }
}

Sending to a specific channel¶

Set channel_id to send a notification to a specific Mattermost channel.

{
  "channel_id": "logman-alerts-channel-id",
  "body": {
    "template": "/Templates/Mattermost/message.md",
    "params": {
      "name": "LogMan.io",
      "severity": "High",
      "message": "New security notification"
    }
  }
}

Sending a direct message¶

Set username to send a direct message to a Mattermost user.

{
  "username": "alice",
  "body": {
    "template": "/Templates/Mattermost/message.md",
    "params": {
      "name": "Alice",
      "severity": "High",
      "message": "New security notification"
    }
  }
}

Warning

Do not provide both channel_id and username in the same notification. Use channel_id for a channel message or username for a direct message.

Mattermost props¶

Mattermost notifications can include optional props in the message body. Use props when the Mattermost integration uses structured message metadata or attachments.

String values inside props can use the same template parameters as the message body.

{
  "channel_id": "logman-alerts-channel-id",
  "body": {
    "template": "/Templates/Mattermost/message.md",
    "params": {
      "severity": "High",
      "event_code": "HIP_Sentinel_Fail"
    },
    "props": {
      "attachments": [
        {
          "color": "#d9534f",
          "title": "{{ severity }} notification",
          "text": "Event code: {{ event_code }}"
        }
      ]
    }
  }
}

Mattermost templates¶

Mattermost templates must be stored in the /Templates/Mattermost/ directory in the Library.

Example template:

/Templates/Mattermost/message.md

**{{ severity }} notification**

{{ message }}

Kafka notification example¶

When sending through Kafka, set type to mattermost.

{
  "type": "mattermost",
  "channel_id": "logman-alerts-channel-id",
  "body": {
    "template": "/Templates/Mattermost/message.md",
    "params": {
      "severity": "High",
      "message": "New security notification"
    }
  }
}