Howto Write a Telegram Alert Endpoint for ntopng

Posted · Add Comment

Telegram is a popular messaging application that many people use daily to do instant messaging and receive notifications. As of ntopng 4.2, it is now possible to deliver alerts to external entities including Slack, email and Discord.

This post will show you how the Telegram alert endpoint has been developed so that readers can learn how to contribute to the ntopng development by coding new integrations. For a complete guide about alert endpoints, please refer to the ntopng user’s guide, whereas the complete telegram endpoint source code can be found here.

We suppose that you have downloaded the ntopng code from github. Done that, go to ntopng/scripts/plugins/endpoints: here you can find the folder where endpoints are stored. Similar to all the other endpoints, you need to create a new folder for your endpoint (e.g. “some_alert_endpoint”): for telegram we created a folder named telegram_endpoint. Then you need to create two files named

  • http_lint.lua
    This file is used to check (this is know as linting) the values of the parameters that will be passed to the endpoint through the ntopng web interface. This file needs to have a single function called script.getAdditionalParameters(http_lint) and has to return the checks needed to be done on the inputs.
  • manifest.lua
    It contains the title, the description and the author of the plugin.

Inside the telegram endpoint you also need to create a templates folder that will contain both the endpoint and recipient html templates. These two templates are used to show the various input arguments, descriptions, ecc. on the GUI
respectively of the recipient and endpoint configuration.

The various template parameters (format, inputs and so on) shown on the GUI, are taken from the locales folder divided according to the respective language file such as en.lua (English), it.lua (Italian) and so on. ntopng will choose the language set in the preferences panel for the ntopng web user.

Furthermore, there is a new directory named alert_endpoint folder, where we’re going to store the endpoint code. In this folder create a file named telegram.lua, and put here all the code necessary to send telegram messages, format the parameters and so on.

The first part of this script is depicted below.

and it defines the HTTP parameters used in the recipient and endpoint forms used by telegram. Inside the XXX_params you need to specify the parameters passed in the input forms: the endpoint_params will be used by the endpoint form template, and the other for the recipient form. Additionally it is required to create a function called telegram.format_recipient_params(recipient_params) responsible to format the output of the recipient parameters.

At this point you can create a function to be called periodically responsible to process the queued alerts (generated by ntopng when specific traffic patterns are detected, e.g. when a host contacts a malware site), dequeue and deliver them to telegram. This function is named telegram.dequeueRecipientAlerts().

In the above code the ntop.recipient_dequeue() function is the one that will dequeue triggered alerts that need to be sent via telegram.

Once notifications have been dequeued, they can be delivered to Telegram via a HTTP POST according to the JSON format specified by the Telegram API.

We’re almost ready: we just need to create an additional function that is used by the ntopng engine when during recipient configuration, the administrator wants to check if the setup is correct by sending a test message.

That’s all. Your telegram endpoint is now completed. As you can see most of the work is required to create the web template and format the message that will be sent via HTTP POST. As most systems now feature a REST API, we believe that integrating additional endpoints should be pretty simple by cloning the telegram endpoint code, renaming telegram to my_endpoint and doing little cosmetic changes. Are you ready to contribute to the ntopng development  by creating a new endpoint?

Enjoy!