Merge pull request #1525 from jertel/jertel/matrix

add new Matrix Hookshot alerter

CHANGELOG.md

@@ -5,6 +5,7 @@
 
 ## New features
 - [MS Power Automate] New Alert Channel with Microsoft Power Automate - [#1505](https://github.com/jertel/elastalert2/pull/1505)  [#1513](https://github.com/jertel/elastalert2/pull/1513) [#1519](https://github.com/jertel/elastalert2/pull/1519) - @marssilva, @jertel
+- [Matrix Hookshot] New Alerter for sending alerts to Matrix via Hookshot - [#1525](https://github.com/jertel/elastalert2/pull/1525) - @jertel
 
 ## Other changes
 - [Indexer] Fixed fields types error on instance indexer_alert_config in schema.yml - [#1499](https://github.com/jertel/elastalert2/pull/1499) - @olehpalanskyi

docs/source/alerts.rst

@@ -33,6 +33,7 @@ or
       - jira
       - lark
       - linenotify
+      - matrixhookshot
       - mattermost
       - ms_teams
       - ms_power_automate
@@ -1424,6 +1425,33 @@ Example usage::
       - "linenotify"
     linenotify_access_token: "Your linenotify access token"
 
+Matrix Hookshot
+~~~~~~~~~~~~~~~
+
+The Matrix Hookshot alerter will send a notification to a Hookshot server that's already setup within the Matrix server. The body of the notification is formatted the same as with other alerters.
+
+See the Hookshot Webhook documentation for more information: https://matrix-org.github.io/matrix-hookshot/latest/setup/webhooks.html#webhook-handling
+
+The alerter requires the following option:
+
+``matrixhookshot_webhook_url``: The webhook URL that was provided to you by the hookshot bot. Ex: https://XXXXX.com/webhook/6de1f483-5c4b-4bb8-784a-f09129f45225. You can also use a list of URLs to send to multiple webhooks.
+
+Optional:
+
+``matrixhookshot_username``: Optional username to prepend to the text body.
+
+``matrixhookshot_text``: Override the default alert text with custom text formatting.
+
+``matrixhookshot_html``: Specify HTML alert content to use instead of the default alert text.
+
+``matrixhookshot_proxy``: By default ElastAlert 2 will not use a network proxy to send notifications to Hookshot. Set this option using ``hostname:port`` if you need to use a proxy. only supports https.
+
+``matrixhookshot_ignore_ssl_errors``: By default ElastAlert 2 will verify SSL certificate. Set this option to ``True`` if you want to ignore SSL errors.
+
+``matrixhookshot_timeout``: You can specify a timeout value, in seconds, for making communicating with Hookshot. The default is 10. If a timeout occurs, the alert will be retried next time ElastAlert 2 cycles.
+
+``matrixhookshot_ca_certs``: Set this option to ``True`` or a path to a CA cert bundle or directory (eg: ``/etc/ssl/certs/ca-certificates.crt``) to validate the SSL certificate.
+
 Mattermost
 ~~~~~~~~~~
 

docs/source/elastalert.rst

@@ -49,6 +49,7 @@ Currently, we have support built in for these alert types:
 - Jira
 - Lark
 - Line Notify
+- Matrix Hookshot
 - Mattermost
 - Microsoft Teams
 - Microsoft Power Automate

elastalert/alerters/matrixhookshot.py

@@ -0,0 +1,81 @@
+import copy
+import json
+import requests
+import warnings
+
+from elastalert.alerts import Alerter, DateTimeEncoder
+from elastalert.util import elastalert_logger, EAException, lookup_es_key
+from requests.exceptions import RequestException
+
+
+class MatrixHookshotAlerter(Alerter):
+    """ Creates a Matrix Hookshot room message for each alert """
+    required_options = frozenset(['matrixhookshot_webhook_url'])
+
+    def __init__(self, rule):
+        super(MatrixHookshotAlerter, self).__init__(rule)
+        self.matrixhookshot_webhook_url = self.rule.get('matrixhookshot_webhook_url', None)
+        if isinstance(self.matrixhookshot_webhook_url, str):
+            self.matrixhookshot_webhook_url = [self.matrixhookshot_webhook_url]
+        self.matrixhookshot_proxy = self.rule.get('matrixhookshot_proxy', None)
+        self.matrixhookshot_username = self.rule.get('matrixhookshot_username', '')
+        self.matrixhookshot_text = self.rule.get('matrixhookshot_text', '')
+        self.matrixhookshot_html = self.rule.get('matrixhookshot_html', '')
+        self.matrixhookshot_ignore_ssl_errors = self.rule.get('matrixhookshot_ignore_ssl_errors', False)
+        self.matrixhookshot_timeout = self.rule.get('matrixhookshot_timeout', 10)
+        self.matrixhookshot_ca_certs = self.rule.get('matrixhookshot_ca_certs')
+
+    def format_body(self, body):
+        # https://matrix-org.github.io/matrix-hookshot/latest/setup/webhooks.html
+        return body
+
+    def get_aggregation_summary_text__maximum_width(self):
+        width = super(MatrixHookshotAlerter, self).get_aggregation_summary_text__maximum_width()
+        # Reduced maximum width for prettier MatrixHookshot display.
+        return min(width, 75)
+
+    def get_aggregation_summary_text(self, matches):
+        text = super(MatrixHookshotAlerter, self).get_aggregation_summary_text(matches)
+        if text:
+            text = '```\n{0}```\n'.format(text)
+        return text
+
+    def alert(self, matches):
+        body = self.create_alert_body(matches)
+
+        body = self.format_body(body)
+        # post to matrixhookshot
+        headers = {'content-type': 'application/json'}
+        # set https proxy, if it was provided
+        proxies = {'https': self.matrixhookshot_proxy} if self.matrixhookshot_proxy else None
+        payload = {
+            'text': body
+        }
+        if self.matrixhookshot_username:
+            payload['username'] = self.matrixhookshot_username
+        if self.matrixhookshot_html:
+            payload['html'] = self.matrixhookshot_html
+        if self.matrixhookshot_text:
+            payload['text'] = self.matrixhookshot_text
+
+        for url in self.matrixhookshot_webhook_url:
+            try:
+                if self.matrixhookshot_ca_certs:
+                    verify = self.matrixhookshot_ca_certs
+                else:
+                    verify = not self.matrixhookshot_ignore_ssl_errors
+                if self.matrixhookshot_ignore_ssl_errors:
+                    requests.packages.urllib3.disable_warnings()
+                response = requests.post(
+                    url, data=json.dumps(payload, cls=DateTimeEncoder),
+                    headers=headers, verify=verify,
+                    proxies=proxies,
+                    timeout=self.matrixhookshot_timeout)
+                warnings.resetwarnings()
+                response.raise_for_status()
+            except RequestException as e:
+                raise EAException("Error posting to matrixhookshot: %s" % e)
+        elastalert_logger.info("Alert '%s' sent to MatrixHookshot" % self.rule['name'])
+
+    def get_info(self):
+        return {'type': 'matrixhookshot' }

elastalert/loaders.py

@@ -44,6 +44,7 @@
 from elastalert.alerters.alertmanager import AlertmanagerAlerter
 from elastalert.alerters.email import EmailAlerter
 from elastalert.alerters.jira import JiraAlerter
+from elastalert.alerters.matrixhookshot import MatrixHookshotAlerter
 from elastalert.alerters.mattermost import MattermostAlerter
 from elastalert.alerters.opsgenie import OpsGenieAlerter
 from elastalert.alerters.pagerduty import PagerDutyAlerter
@@ -141,6 +142,7 @@ class RulesLoader(object):
         'gelf': elastalert.alerters.gelf.GelfAlerter,
         'iris': elastalert.alerters.iris.IrisAlerter,
         'indexer': IndexerAlerter,
+        'matrixhookshot': MatrixHookshotAlerter,
     }
 
     # A partial ordering of alert types. Relative order will be preserved in the resulting alerts list

elastalert/schema.yaml

@@ -642,6 +642,16 @@ properties:
   ### Line Notify
   linenotify_access_token: {type: string}
 
+  ### Matrix Hookshot
+  matrixhookshot_ca_certs: {type: [boolean, string]}
+  matrixhookshot_webhook_url: *arrayOfString
+  matrixhookshot_username: {type: string}
+  matrixhookshot_html: {type: string}
+  matrixhookshot_text: {type: string}
+  matrixhookshot_proxy: {type: string}
+  matrixhookshot_ignore_ssl_errors: {type: boolean}
+  matrixhookshot_timeout: {type: integer}
+
   ### Mattermost
   mattermost_webhook_url: *arrayOfString
   mattermost_proxy: {type: string}