Mist Webhook Translator
Mist Webhook Translator is a python web app to publish Mist Webhook messages to Slack or MsTeams channels.
It is providing a Web UI to configure the App, and is automatically configuring the Webhook in Mist and listening for incoming webhooks. From there, it is processing the messages and forward them to Slack / Teams based on the configuration.
This app is using mwtt to process the webhooks. You can use mwtt directly if you don't need the Web UI
The script is also available as a Docker image. It is designed to simplify the deployment, and a script is available to automate the required images deployment.
Menu
MIT LICENSE
Copyright (c) 2022 Thomas Munzer
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Features
- Provides Web UI for configuration (Mist webhook topics, Slack/Teams incoming webhooks)
- Automatically create and delete Webhook configuration in Mist Org (based on the required settings)
- Automatically set the Mist Webhook Secret and check the
X-Signature-v2header in the message - Listen for Webhook messages comming from Mist Cloud
- Send the messages to different slack channels depending on the severity level (can be configured):
- Send the messages to different MS Teams channels depending on the severity level (can be configured):
Supported Webhook Topics
- alarms
- audits
- device-updowns
- device-events
- mxedge-events
Installation
This Reference Application can be used as a standalone Application, or it can be deployed as a Docker Image (recommanded).
Deploy the Docker version (recommanded)
This application is available as a Docker Image. The Dockerfile is also available if you want top build it on your own.
The Docker Image exposes the following ports:
- TCP51361
Run the Docker version
docker create -v <path_to_env_file>:/app/.env:ro --name="<container_name>" -p 51361:80 tmunzer/mist_webhook_translator
Configure the Docker version
Configuration can be done through the environment files/variables. An example of configuration can be found in src/env. Edit it to match your settings and link the env file to /app/.env in you container, or use the environment variables
You can also use environment variables to configure the app:
| Variable Name | Type | Default Value | Comment |
|---|---|---|---|
| FLASK_SECRET | string | Used to sign the session cookies. Can be generated with the command python -c 'import secrets; print(secrets.token_hex())' |
|
| FLASK_DEBUG | boolean | False | Turn debug mode on, allowing to get more logs and error details from the app. Do NOT use it in production |
| FLASK_PORT | integer | 51361 | TCP Port used by Flask to listen to HTTP requests. Do NOT change it if using the Docker version (the image is only exposing TCP51361) |
| WH_HOST | string | FQDN used to configure the Mist Webhooks. Mist Cloud must be able to reach this FQDN | |
| WH_HTTPS | boolean | False | Used to configure the Mist Webhooks to send HTTP POST through HTTPS (True) or HTTP (False). If True, a reverse proxy must be deployed in front of the App to manage HTTPS. |
| WH_PORT | integer | 51361 | Port to configure the Mist Webhooks. Mist Cloud must be able to send HTTP POST on this port. By default it is the same as FLASK_PORT, but can be changed when using a reverse proxy in front of the app |
| MONGO_USER | string | null | If the Mongo server require authentication |
| MONGO_PASSWORD | string | null | If the Mongo server require authentication |
| MONGO_HOST | string | null | Mongo server hostname |
| MONGO_PORT | integer | 27017 | Mongo server port |
| MONGO_DB | string | translator | Mongo Database name |
| MONGO_KEY | string | Used to encrypt data in the DB. Can be generated with python -c 'import secrets; print(secrets.token_hex(16))' |
|
| ABOUT_TOKEN | string | secret_token | used to "hide" server status URL. The URL /status/about/<string:token> is exposing some basic status info about this app |
Deploy the Standalone Application
This Reference APP is built over Python Flask.
Deploy the Application
- Install Python.
- Clone this repo.
- Configure the APP settings, in the
src/.envfile. You will find an example insrc/env. With Docker deployment, all the settings can be configured by using Environment Variables (see above) - Install python packages (
python3 -m pip install -r requirements.txtfrom the project folder). - Start the APP with
python3 ./app.pyfrom thesrcfolder