Alerting: ESA Annotations

Document created by RSA Information Design and Development on Nov 23, 2016Last modified by RSA Information Design and Development on Apr 26, 2017
Version 3Show Document
  • View in full screen mode

This topic describes annotations that Security Analytics provides to use in advanced EPL rules.

@RSAAlert Annotation

The @RSAAlert annotation is used to mark which EPL statements are linked to generating alert notifications. It is designed to work with the alert notification suppression feature in the Rule Builder user interface.

The @RSAAlert annotation can be useful when working with alert notifications, especially if you want to filter notifications, such as sending one notification for each user that triggers an alert.

For example, suppose you want to generate alert notifications for login failures. You could add the following statement:

@RSAAlert select * from event(msg_id=“login_fail")


Event numberMessage IDusernamesrc_IPTime


For the above statement, five alert notifications are generated.

However, suppose you wanted to modify the statement to generate one alert for each separate username. You can use the identifier attribute. For example, the statement @RSAAlert(identifier={”username”}) SELECT* FROM Event(msg_id=”login_fail”) generates one notification for the first alert for “bob” and one for the first alert for “alice." Subsequent alerts for “bob” and “alice” are ignored.

You can further distinguish the users by adding details via the identifier variable. For example, you can distinguish by user and IP address using the following statement: @RSAAlert(identifier={”username”, "src_ip"}) SELECT* FROM Event(msg_id=”login_fail”). Then, you would see notifications generated by user name and IP address (one alert for "alice" at, another alert for "alice" at, and an alert for "bob" at

To Use Identifiers with Alert Notification Suppression:

The @RSAAlert annotation is designed to work with the alert notification suppression feature in the Rule Builder user interface. To do this:

  1. Create a rule in the Rule Builder user interface, and select the alert suppression feature when configuring notifications.

  1. Copy the code from the Rule Builder rule into a new advanced rule.

  2. Configure the advanced rule to include identifiers (as described above) and save the advanced rule.

  3. Delete the original rule builder rule.

@RSAPersist Annotation

The @RSAPersist annotation is used to mark a named window as an ESA managed window for persistence. By marking the named window as an ESA managed window, ESA periodically writes the contents of the window to disk and restores them back if the window is un-deployed and re-deployed. The systems take a snapshot just before the module is un-deployed and the window is removed. Conversely, it restores the window contents from the snapshot just after the module is re-deployed. This ensures that the contents of the window are not lost if the module state is altered or if the ESA service goes down.

For example, consider a named window, DHCPTracker that holds a mapping from IP addresses to each assigned hostname.You can annotate the statement with the @RSAPersist annotation as:

create window DHCPTracker.std:unique(ip_src) as (ip_src string, alias_host string);
insert into DHCPTracker select IP as ip_src, HostName as alias_host from DHCPAssignment(ID=32);

Note: All windows definitions are not suitable for persistence. @RSAPersist annotation must be used with care. If the window has timed-records or if it depends on time based constraints it is very likely that the reverted snapshots will not restore it to the correct state. Also, any changes to the window definition will invalidate the snapshots and reset the window to a blank state. The system does not do any semantic analysis to determine if the changes to the window definition are conflicting or not. Note that other parts of a module (i.e. other than the particular CREATE WINDOW call that defines the window) may change, without invalidating the snapshots.

@UsesEnrichment ( and later)

The @UsesEnrichment can be used in advanced EPL rules to reference enrichments. In order to synchronize enrichments with ESA, all enrichment dependencies in EPL rules must be referenced with the @UsesEnrichment annotation.

The @UsesEnrichment annotation uses the following format:

@UsesEnrichment(name= '<enrichment_name>')

For example, the following EPL references a whitelist enrichment:

@UsesEnrichment(name = 'Whitelist')


SELECT * FROM Event(ip_src NOT IN (SELECT ip_address FROM Whitelist))

You are here
Table of Contents > Add Rules to the Rules Library > Add an Advanced EPL Rule > ESA Annotations