Document toolboxDocument toolbox

Detecting inactivity

Description

A Flow that sends an alert to the specified email(s) when no data is received during a given time rolling window.

The core element of this Flow is the Lookup unit. In our example, this unit will store the different pair values of the serverHost and username columns of the input events and will notify the next unit when there are no events with one of the stored pairs over a specified period of time. This will allow users to detect any period of inactivity or even potential data loss.

Flow configuration

The following table describes the units needed to create this Flow, as well as how to configure and link them.

Unit type and description

Configuration

Unit type and description

Configuration

Devo Source

This unit defines the Devo query that stores the events of our data source. 

Drag a Devo Source unit to the canvas and open its configuration options by double-clicking it.

Add a Name to the unit (in this example, we called it DevoSource), and specify the Query that receives the events of the required data source. In this example, we're using the following query:
from siem.logtrust.web.activity where isnotnull(serverHost) group every 5s by serverHost, username every 5s select last(eventdate) as lasteventdate

Leave the rest of the settings as default and click Apply to save the configuration.
If you have problems saving this unit or running the Flow, switch off the Check DB configuration option.

Map

We will use this unit to generate fake events that will notify the Lookup unit when the data source does not generate any event.

The Lookup unit is a passive unit and needs input events that notify it that there's no activity. If we don't use this unit, the Lookup will not be activated in cases of total inactivity, and we won't get notified.

This unit will be connected to the stall port of the Devo Sink unit. This port sends signal events during inactivity periods of the data source. In these cases, the map will generate a fake event that will be sent to the Lookup. When the Lookup expiration time ends without any activity, the Lookup will fire alerts for every key-value pair it has memorized, and we will get notified that there's no activity.

These fake events will be then discarded by a Filter unit

Drag a Map unit to the canvas and link the stall port of the Devo Source unit to the in port of this unit, as follows:

Then, open the configuration options of the unit by double-clicking it. In the General tab, add a Name to the unit (in this example, we called it FillGaps), and leave the Language as default (Groovy).

In the Fields to add tab, you must add 4 different fields that will define our fake events. Add the following fields by clicking the + button:

The ServerHost column of our fake events:

  • Field name - serverHost

  • Type - String

  • Expression - "stall_source"

The username column of our fake events:

  • Field name - username

  • Type - String

  • Expression - "stall_username"

The field containing a value that will be used to identify the fake events and discard them later:

  • Field name - value

  • Type - String

  • Expression - "stall_source__stall_username"

The lasteventdate column of our fake events:

  • Field name - lasteventdate

  • Type - java.lang.Object

  • Expression - eventdate

Click Apply to save the configuration.

Lookup

This unit keeps a record of the server host and username values in the source data events.

Each time that the unit receives an event with a server host + username combination that has already arrived before, the expiration time set in the unit will start again for that combination. If no events with a specific server host + username arrive within the expiration time, an event will be emitted through the expired port.

We will use these expired events to notify the next unit about any inactivity period.

Drag a Lookup unit to the canvas and link it to the Devo Source and Map units as follows:

Link the init port of the Devo Source unit to the end port of the Lookup unit. We need this link to unblock the lookup since it starts blocked by default.

Link the data port of the Devo Source unit to the update port of the Lookup unit. This will update the content of the lookup when new data from our source arrives.

Finally, link the out port of the Map unit to the update port of the Lookup unit. As explained before, this will activate the Lookup unit when the data source does not send any data.

Then, open the configuration options of the unit by double-clicking it and enter the following values:

  • Name - Add a name to the unit. In this example, we're calling it HoleChecker.

  • Key field(s) -  Input fields that contain key values. In this case, we need the serverHost and username fields.

  • Lookup key field(s) - Name of the lookup fields to be matched with the key fields. In this case, we are using the input query fields serverHost and username.

  • Lookup value field - The values of this field will be added to the lookup when there's a match. In this case, choose the column lasteventdate.

  • Expiration time - Set the required expiration time. When there are no new events containing a specific key value (in this example, server host + username values) after this period finishes, an event will be sent through the expired port of this unit. In this case, we're setting it to 30000 milliseconds.

  • Lookup timestamp field - Timestamp to be used for the events that come from the update port of the unit. Choose the lasteventdate field.

  • Timestamp field - Timestamp to be used for the events that come from the in port of the unit. Choose the lasteventdate field.

Click Apply to save the configuration.

Filter

This unit is used to discard the fake events we used to notify the Lookup unit about total inactivity periods in the data source.

Drag a Filter unit to the canvas and link the expired port of the Lookup unit to the in port of this unit, as follows:

Then, open the configuration options of the unit by double-clicking it. Add a Name to the unit (in this example, we called it FilterStallValue), leave the Language as default (Groovy) and enter the following expression in the Predicate field. This expression will filter out all the fake events we used to notify the Lookup about total inactivity periods:

value != "stall_source__stall_username"

Click Apply to save the configuration.

Map

This unit will extract the expired serverHost and username values sent by the Lookup unit in the key field.

These are sent as an array of values, so we need this unit to extract the required values in their corresponding fields.

Drag a Map unit to the canvas and link the out port of the Filter unit to the in port of this unit, as follows:

Then, open the configuration options of the unit by double-clicking it. In the General tab, add a Name to the unit (in this example, we called it ValueSeparator), and leave the Language as default (Groovy).

In the Fields to add tab, you must add 2 different fields by clicking the + button:

This field will contain the values of the serverHost column:

  • Field name - serverHost

  • Type - String

  • Expression - key[0]

    This field will contain the values of the username column.

  • Field name - username

  • Type - String

  • Expression - key[1]

In the Fields to remove tab, enter the key and value fields

Click Apply to save the configuration.

Email Sink

We will use this unit to send a customized message to the required users and warn them about users' inactivity.

Drag an Email Sink unit to the canvas and link the out port of the Map unit to the in port of this unit, as follows:

Then, open the configuration options of the unit by double-clicking it. In the General tab, add a Name to the unit (in this example, we called it InactivityMail), add a Subject for the emails to be sent (in this example, Inactivity Warning).

Then, in the Message field, you must enter the text to be sent in the mails. For this example, we added the following (where username and serverHost are variable fields that will be automatically replaced by the corresponding values)
The user %%{username} has been inactive for the last 10 seconds in the server %%{serverHost}

Then, click the To recipients tab and add as many email addresses as required by clicking the + icon

Click Apply to save the configuration.

Once you're done, remember to save your Flow so you can start running it. To do it, click the Save button on the Flow toolbar.

Result

Once you have defined the whole Flow and saved it, click the Start button to activate it. If everything is correctly configured, the Flow will send an email to the given addresses every time an inactivity period is detected.

Import this Flow

Download this Flow in JSON format and import it to your domain clicking the Import option at the top of the Flow canvas.