12. Alerts

ntopng includes an alerting engine to report different kind of events. Please read the Basic Concepts section to learn more about this feature.

The Alerts Menu opens a page with the list of alerts that was fired. This icon is hidden if no alerts was triggered or after purge operation. Each row in the Alerts page presents an alert detected by ntopng with information such as Date, Severity, Type and Description.

Alerts Page

The Alerts Page

12.1. Alert Endopints

Generated alerts can also be sent to third-party endpoints. Currently supported endpoints are:

  • Email
  • Slack
  • Syslog
  • Nagios
  • Webhook

Endpoints can be enabled and configured from the ntopng preferences page.

12.1.1. Email

Ntopng only supports sending emails to a SMTP server without authentication. Since ntopng does not authenticate with the SMTP server, the server may reject the email. For this reason, it is suggested to setup a local mail server (e.g. postfix) and use it as the email forwarder to the actual mail server.

It is possible to test the email sending functionality by using the “Send Test Email” button. If an error occurs, an error message will be printed to the ntopng log. It is possible to get a detailed log of the communication between ntopng and the mail server by adding the -v 6 option to the ntopng configuration. After doing this, the email log will be printed in the console. It is advisable to use the grep command (e.g. ntopng -v6 | grep “Utils.cpp”) to only filter out the email log information.

12.1.2. Webhook

Webhooks allow you to subscribe to alerts by configuring a HTTP endpoint. Alerts are encoded in JSON messages and sent to the configured URL where they can be processed or used to trigger automations.

You can add an endpoint by defining the URL and shared secret (optional). The shared secret is a user-defined secret to be validated by the webhook receiver. If the HTTP server requires HTTP authentication, you should also configure username and password.

Webhook Notification Preferences

The Webhook Notification Preferences Page

It is possible to test the endpoint to make sure it is active and reachable by using the “Send Test Message” button. If an error occurs, an error message will be reported.

Example of alert sent to the webhook endpoint:

{version:0.1,sharedsecret:0123456789,alerts:[{"severity":"info","entity_value":"ntopng","ifid":1,"action":"store","tstamp":1536245738,"type":"process_notification","entity_type":"host","message":"[<tstamp>]][Process] Stopped ntopng v.3.7.180906 (CentOS Linux release 7.5.1804 (Core) ) [pid: 4783][options: --interface \"eno1\" --interface \"lo\" --dump-flows \"[hidden]\" --https-port \"4433\" --dont-change-user ]"}]}

12.1.3. Syslog

Alerts are sent to syslog using standard syslog severities as per RFC 5424.

ntopng alert severities are mapped to standard syslog severities as follow:

  • Info becomes syslog LOG_INFO equal to the integer 6
  • Warning becomes syslog LOG_WARNING equal to the integer 4
  • Error becomes syslog LOG_ERR equal to the integer 3

Two formats are available when sending alerts to syslog, namely plaintext and JSON. The format defaults to plaintext and can be toggled from the ntopng preferences page.

Plaintext

Plaintext alerts have the following format:

[tstamp][severity][type][entity][entity value][action] ... and a plain text message...

Fields have the following meaning:

  • [tstamp] is the time at which ntopng detected the alert. This time is not necessarily equal to the time the alert has reached syslog.
  • [severity] is the severity of the alert. Severities are also used when dispatching messages to syslog. Severities are “Warning”, “Error” of “Info”.
  • [type] is a string that indicates the type of alert.
  • [entity] is a class that categorizes the originator of the alert. It can be an “host”, an “interface” and so on.
  • [entity value] is an identifier that uniquely identifies the originator along with the [entity]. For example, entity value for an “host” is its IP address, for an “interface” is its name, for a “device” is its MAC address, and so on.
  • [action] indicates whether this is an engaged alert, an alert that has been released or if it just an alert that has to be stored.

Alert types, entities, and actions are explained in detail in section Alerts.

Examples of alerts sent to syslog are

devel ntopng: [<tstamp>][Info][Device Connection][Device][58:40:4E:CE:28:29] The device Apple_CE:28:29 has connected to the network.
devel ntopng: [<tstamp>][Error][Threshold Cross][Interface][iface_0][Engaged] Minute traffic crossed by interface eno1 [1.08 MB > 2 Bytes]
devel ntopng: [<tstamp>][Warning][Remote to Remote Flow][Flow] Remote client and remote server [Flow: 192.168.1.100:138 192.168.1.255:138] [L4 Protocol: UDP]

JSON

JSON alerts have the following keys that are in common with plaintext alerts, namely [entity], [entity value], [action], [tstamp], [severity] and [type].

The additional keys are:

  • message: is a text message describing the alert.
  • ifid: the id of the monitored ntopng interface
  • alert_key: is a string that, for threshold-based alerts, represents the check interval (e.g., min, 5min, hour) and the type of threshold checked (e.g., bytes, packets).

Examples of JSON alerts sent to syslog are

develv ntopng: {"entity_value":"ntopng","ifid":1,"action":"store","tstamp":1536245738,"type":"process_notification","entity_type":"host","message":"[<tstamp>]][Process] Stopped ntopng v.3.7.180906 (CentOS Linux release 7.5.1804 (Core) ) [pid: 4783][options: --interface \"eno1\" --interface \"lo\" --dump-flows \"[hidden]\" --https-port \"4433\" --dont-change-user ]","severity":"info"}
devel ntopng: {"message":"[<tstamp>][Threshold Cross][Engaged] Minute traffic crossed by interface eno1 [891.58 KB > 1 Byte]","entity_value":"iface_0","ifid":0,"alert_key":"min_bytes","tstamp":1536247320,"type":"threshold_cross","action":"engage","severity":"error","entity_type":"interface"}