Alerting: ESA Annotations

Document created by RSA Information Design and Development Employee on Jul 20, 2016Last modified by RSA Information Design and Development Employee on Apr 26, 2017
Version 2Show Document
  • View in full screen mode

This topic describes two 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 alerts. The @RSAAlert is optional in advanced rules and is useful only with statements that are expected to generate ESA alerts.

Note: This annotation is not needed in all EPL statements, like those that create named windows and so on.

@RSAPersist Annotation

The @RSAPersist annotation is used to mark a named window as a ESA managed window for persistence. By marking the named window as a 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 rules that use enrichments with ESA, all enrichment dependencies 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