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
For example, consider the following sequence of simplified events:
@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:
@RSAPersist
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 (10.6.1.1 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')
@RSAAlert
SELECT * FROM Event(ip_src NOT IN (SELECT ip_address FROM Whitelist))
@Name
The @Name is the statement name defined in ESA advanced rules. It is used to dynamically generate statement names in ESA alerts. The statement name of only an alert triggering statement is displayed. This annotation has meta keys enclosed in curly brackets.
The @Name annotation uses the following format:
@Name("<static_part_of_statement_name> {meta_key1} {meta_key2}…")
For example, the following EPL references meta keys ip_src and user_name whose values will be dynamically generated.
@Name(“Login Event to {ip_src} by {user_name}”)
Note: You can specify any number of meta keys in the statement for dynamic statement name generation.
The length of individual meta key is limited to 64, after which the value is truncated and appended with “…”.
The length of the dynamic generation of statement name is limited to 128, after which the value is truncated to 128 and appended with “…”. All the remaining values post truncation will be treated as static values.
