Define a Template for ESA Alert Notifications

This topic describes how you can define a template for alert notifications. Event Stream Analysis (ESA) allows you to define useful templates for alerts. You need to have a good understanding of FreeMarker and the ESA data model to define a template. For more information on FreeMarker, see FreeMarker Template Author's Guide.

ESA Data Model

Consider an ESA alert rule as shown below:

@Name('module_144d43f5_f0b4_4cd0_8c6c_5ce65c37e624_Alert')
@Description('Brute Force Login To Same Destination')
@RSAAlert(oneInSeconds=0, identifiers={"ip_dst"})
SELECT* FROMEvent (ec_activity = 'Logon',ec_theme = 'Authentication',ec
outcome = 'Failure',ip_dst IS NOT NULL)
.std:groupwin(ip_dst)
.win:time_length_batch(60 seconds, 2)
GROUPBYip_dst HAVING COUNT(*) = 2;

When a rule like the above is fired, the alert generated has two constituent events, each resembling a NextGen session with multiple meta values. The alert data-object passed to the FreeMarker template evaluator are as follows: 

 

(root)
  |
  +- id = "4e67012f-9c53-4f0b-ac44-753e2c982b79"                    // Unique identifier for each alert
  |
  +- severity = 1                                                    // The severity of the alert
  +- time = 2018-12-31T11:02Z                                        // The alert time (needs a ?datetime for proper rendering)
  |  +- moduleType = "ootb"                                          // The module type
  |
  +- moduleName = "Brute Force Login To Same Destination"            // A description of the module
  |
  +- statement = "module_144d43f5_f0b4_4cd0_8c6c_5ce65c37e624_Alert" // The name of the EPL statement
  |  +- events                                                       // The constituent events - as a sequence of event maps
       |   +- [0]                                                    // offset 0 (i.e. the first constituent event)
       |   |       |   |
       |   +- event_cat_name = "User.Activity.Failed Logins"
       |   +- device_class = "Firewall"                              // event meta (accessible as ${events[0].device_class}$)
       |   |       |   +- event_source_id = "uttam:50002:1703395"    // Investigation URI to the individual session (used by SA)
       |   |
       |   +- ...                                                    // Other meta 
       |   |
       |   +- sessionid = 1703395                                    // NextGen sessionid
       |   |
       |   +- time = 1388487764                                      // event/session time at NextGen source (as a long Unix timestamp)
       |   |
       |   +- user_dst = "user5"
       |
       +- [1]                                                        // offset 1 (i.e. the second consituent event)
           |
           +- device_class = "Firewall"
           |
           +- event_cat_name = "User.Activity.Failed Logins"
           |
           +- event_source_id = "uttam:50002:1703405"
           |
           +- ...                                                    
           |
           +- sessionid = 1703405
           |
           +- time = 1388487766
           |
           +- user_dst = "user5"

There are two types of template variables available in the data model:

  • Alert Meta Data: These hold alert level details like statement name, module name, alert id, alert time, severity, and others. In FreeMarker terminology, these are top level variables associated with the alert instance itself and can be referenced simply by their names like ${moduleName}. The time meta is special because it is of type Date and it needs to be suffixed with a ?datetime to be properly rendered.
  • Constituent Event Meta Data: These include the session meta fields from individual events that constitute the alert. An alert can have multiple constituent events, so there can be more than one such map in the same alert. These show up as a sequence of hashes to the FreeMarker template evaluator and must be referenced. For instance, the alert has two constituent events the event_source_id for the first is available as ${events[0].event_source_id} and the same for the second is accessible as ${events[1].event_source_id.} You also need to be aware of which meta fields are multi-valued because those need be treated as sequences, for example ${events[0].alias_host} will not work because it is a sequence.

Note: The metadata available in the constituent events for a given alert is determined by the EPL SELECT clause. For example, alerts from SELECT sessionid, time FROM ... have only two meta values available (sessionid, time). Constituent events in SELECT * FROM Event ... will carry all meta fields from the Event type with non-null values.

If your template uses meta keys that are not present in all alert output, you should consider using the FreeMarker provisions for default values.

For example, if a template with text Id=${id},ec_outcome=${ec_outcome} is evaluated for an alert which does not include the meta key ec_outcome then the template evaluation fails. In such cases, you can use the missing value placeholder ${ec_outcome!”default”}.