SEC supports the following pattern types (if <number> is omitted, 1 is assumed):

SubStr[<number>]

pattern is assumed to be a substring that will be searched in last <number> input lines L1, L2, ..., L<number>. The input lines are joined into a single string with the newline character acting as a separator, and the resulting string "L1\nL2\n...\nL<number>" is searched for the substring. (Note that if <number> is 1, the last input line without a terminating newline is searched.) If the substring is found, the pattern matches. The backslash constructs \t, \n, \r, \s, and \0 can be used in the pattern to denote tabulation, newline, carriage return, space character, and empty string, while \\ denotes backslash itself. As an example, consider the following pattern definition: ptype=substr

pattern=Backup done:\tsuccess The pattern matches lines containing "Backup done:<TAB>success".

RegExp[<number>]

pattern is assumed to be a regular expression that last <number> input lines L1, L2, ..., L<number> are compared with. The input lines are joined into a single string with the newline character acting as a separator, and the resulting string "L1\nL2\n...\nL<number>" is compared with the regular expression pattern. (Note that if <number> is 1, the last input line without a terminating newline is compared with the pattern.) If the pattern matches, backreference values will be assigned to the special variables $1, $2, ..., and the special variable $0 will be set to "L1\nL2\n...\nL<number>" (i.e., to the matching input line(s)). These special variables can be used in some other parts of the rule definition. All regular expression constructs that Perl allows are allowed in the pattern (see perlre(1) for more information). As an example, consider the following pattern definition: ptype=regexp

pattern=(?i)(\S+\.mydomain).*printer: toner\/ink low The pattern matches "printer: toner/ink low" messages in a case insensitive manner from printers belonging to .mydomain. Note that the printer hostname is assigned to $1, while the whole message line is assigned to $0. As another example, the following pattern definition ptype=regexp2

pattern=^AAA\nBBB$ produces a match if the last two input lines are AAA and BBB, and sets $0 to "AAA\nBBB".

PerlFunc[<number>]

pattern is assumed to be a Perl function that last <number> input lines L1, L2, ..., L<number> are submitted to. The Perl function is compiled at SEC startup by calling Perl eval() function, and eval() must return a code reference for the pattern to be valid (also see VARIABLES AND EVAL section for more information). In order to check whether the pattern matches, SEC will call the function in list context and pass lines L1, L2, ..., L<number> and the names of corresponding input sources S1, S2, ..., S<number> to the function as parameters: function(L1, L2, ..., L<number>, S1, S2, ..., S<number>) (if the input line has been generated with the event action, its input source name will be set to 'undef'). If the function returns several values or a single value that is TRUE in boolean context, the pattern matches. If the pattern matches, return values will be assigned to the special variables $1, $2, ..., and the special variable $0 will be set to "L1\nL2\n...\nL<number>" (i.e., to the matching input line(s)). These special variables can be used in some other parts of the rule definition. As an example, consider the following pattern definition: ptype=perlfunc2

pattern=sub { return ($_[0] cmp $_[1]); } The pattern compares last two input lines in a stringwise manner ($_[1] holds the last line and $_[0] the preceding one), and matches if the lines are different. Note that the result of the comparison is assigned to $1, while the two input lines are concatenated (with the newline character between them) and assigned to $0. As another example, the following pattern definition ptype=perlfunc

pattern=sub { if ($_[0] =~ /(abc|def)/) { \

return defined($_[1]) ? $_[1] : "SEC"; } return 0; } produces a match if the input line contains either the string "abc" or the string "def", and sets $0 to the matching line and $1 to the name of the input source.

NSubStr[<number>]

like SubStr[<number>], except the result of the match is negated.

NRegExp[<number>]

like RegExp[<number>], except the result of the match is negated.

NPerlFunc[<number>]

like PerlFunc[<number>], except the result of the match is negated.

TValue

pattern is assumed to be a truth value with TRUE and FALSE being legitimate values for the pattern. TRUE always matches an input line while FALSE never matches an input line.

Note that since Pair and PairWithWindow rules have two pattern definitions, special variables $<number> set by the first pattern are shadowed when the second pattern matches and sets the variables. In order to access the shadowed variables, they must be referred to as %<number> (e.g., instead of $1 one has to write %1). Also note that the second pattern of Pair and PairWithWindow rules may contain $<number> variables, if the second pattern is of type SubStr, NSubStr, Regexp, or NRegExp. The variables are substituted at runtime with the values set by the first pattern.

Context expression is a logical expression that consists of context names, Perl miniprograms, and Perl functions as operands; operands are combined with operators ! (logical NOT), && (logical AND), || (logical OR), and parentheses. Context expressions are employed for activating or deactivating rules - the truth value of the rule's context expression must be TRUE for the rule to be applicable.

If the operand contains the arrow (->), the text following the arrow is considered to be a Perl function that will be compiled at SEC startup by calling Perl eval() function, and eval() must return a code reference for the operand to be valid (also see VARIABLES AND EVAL section for more information). If any text precedes the arrow, it is considered to be the list of parameters for the function. Parameters are separated by whitespace and may contain $<number> and %<number> special variables. In order to evaluate the Perl function operand, the function with its parameter list will be called in scalar context. If the return value of the function is TRUE in boolean context, the truth value of the operand is TRUE, otherwise its truth value is FALSE.

If the operand begins with the equal sign (=), the following text is considered to be a Perl miniprogram. The miniprogram may contain $<number> and %<number> special variables. In order to evaluate the Perl miniprogram operand, it will be executed by calling Perl eval() function in scalar context (also see VARIABLES AND EVAL section for more information). If the return value of the miniprogram is TRUE in boolean context, the truth value of the operand is TRUE, otherwise its truth value is FALSE.

Note that since Perl functions, miniprograms, and parameter lists may contain strings that clash with the operators of the context expression (e.g., '!'), it is strongly recommended to enclose them in parentheses, e.g.,

($1 $2) -> (sub { return ($_[0] != $_[1]); })

=({my($temp) = 0; return !$temp;})

If the operand is not a Perl function or program, it is considered to be a context name. Context name may contain $<number> and %<number> special variables. If the context name refers to an existing context, the truth value of the operand is TRUE, otherwise its truth value is FALSE.

If the whole context expression is enclosed in square brackets [ ], e.g., [MYCONTEXT1 && !MYCONTEXT2], SEC evaluates the expression _before_ pattern matching operation (normally the pattern is compared with input line(s) first, so that $<number> and %<number> variables in the context expression could be replaced with their values). Evaluating context expression first could save CPU time when many of the input lines are known to match the pattern but not the context expression, and the expression does not contain any variables.

As an example, consider the following context expressions:

-> ( sub { my(@stat) = stat("/var/log/messages"); \

return (!scalar(@stat) || time() - $stat[9] > 3600); } )

($1 $2) -> (sub { return ($_[0] != $_[1]); }) && C1

!(C1 || C2) && =("$1" eq "myhost.mydomain")

The first expression is TRUE when the /var/log/messages file does not exist or was last modified more than 1 hour ago. The second expression is TRUE when variables $1 and $2 are numerically not equal and the context C1 exists. The third expression is TRUE when contexts C1 and C2 do not exist and the $1 variable equals to the string "myhost.mydomain". Note that the Perl code of the third expression is compiled each time the expression is evaluated.

Action list consists of action definitions that are separated by semicolons. Each action definition begins with a keyword specifying the action type, followed by additional parameters. Additional parameters that do not have a constant nature may contain $<number> and %<number> special variables. Also, the following variables can be used in non-constant parameters:

%s - event description string (set either by the desc or desc2 parameter of the rule definition).

%t - textual timestamp (as returned by date(1)).

%u - numeric timestamp (as returned by time(2)).

%<alnum_name> - user-defined variables that can be set at SEC runtime with certain actions like assign and eval (<alnum_name> must begin with a letter and may contain letters, digits, and underscores). In order to disambiguate <alnum_name> from the following text, <alnum_name> must be enclosed in braces: %{<alnum_name>}.

In order to use semicolons inside a non-constant parameter, the parameter must be enclosed in parentheses (the outermost set of parentheses will be removed by SEC during configuration file parsing).

The following actions are supported:

none

No action.

logonly

Event description (the value of the %s variable) is logged.

write <filename> [<event text>]

Event string <event text> and terminating newline are written to the file <filename> (<filename> may not contain spaces). File may be a regular file, named pipe, or standard output if - was specified. If the file is a regular file, <event text> is appended to the end of the file. If the file does not exist, it is created as a regular file before writing. If <event text> is omitted, %s is assumed for its value. Though write can also be expressed through the shellcmd action, write does not involve fork(2) like shellcmd does.

shellcmd <shellcmd>

Shell command <shellcmd> is executed. If the -quoting option was specified, %s will be converted to '%s' before supplying it to shell command (see the -quoting and -noquoting options).

spawn <shellcmd>

Identical to the shellcmd action, except the following - every line from the standard output of <shellcmd> is treated like SEC input line and matched against the rules. This is done by applying event 0 <line> to every line from standard output (see the event action). Note that if <shellcmd> outputs a large data set at once, SEC will process it all at once, so if <shellcmd> enters an endless "busy write" loop, it will block SEC from doing anything other than processing its output.

pipe '<event text>' [<shellcmd>]

Event string <event text> and terminating newline are fed to the standard input of shell command <shellcmd> (apostrophes are used to mark the beginning and end of <event text>, in order to distinguish it from <shellcmd>). If <event text> is omitted and there is nothing between apostrophes, %s is assumed for <event text>. If <shellcmd> is omitted, <event text> is written to standard output.

"create [<name> [<time> [<action list>] ] ]

Context with the name <name>, with the lifetime of <time> seconds, and with empty event store is created (<name> may not contain spaces, and <time> is an integer constant). If <name> is omitted, %s is assumed for its value. Specifying 0 as <time> or omitting the value means infinite lifetime. If <action list> is specified, it will be executed when context's lifetime is exceeded. If <action list> is made up of more than one action, semicolons must be used to separate the actions, and the list must be enclosed in parentheses. If already existing context is recreated with create, its lifetime will be extended for <time> seconds and its event store will be emptied.

delete [<name>]

Context with the name <name> is deleted (<name> may not contain spaces). If <name> is omitted, %s is assumed for its value. If non-existing context is deleted, no operation will be performed.

obsolete [<name>]

Behaves like delete, except the action list of the context <name> (if the context has an action list) will be executed before deletion.

"set <name> <time> [<action list>]

Settings for the context with the name <name> will be changed (<name> may not contain spaces, and <time> is an integer constant). New lifetime of the context will be <time> seconds with optional <action list> to be executed when the lifetime is exceeded. Event store of the context will not be changed by set. Specifying 0 as <time> means infinite lifetime. If <action list> is made up of more than one action, semicolons must be used to separate the actions, and the list must be enclosed in parentheses.

alias <name> [<alias>]

An alias name <alias> will be created for the context with the name <name> (<name> and <alias> may not contain spaces). After the name <alias> has been created for a context, the context can be referred to by using both <alias> and <name>. If <alias> is omitted, %s is assumed for its value. If context with the name <name> does not exist, or the name <alias> already exists, the alias will not be created. Internally, SEC does not distinguish in any way between <alias> and <name> - they are both pointers to the same context data structure. Therefore, it makes no difference whether context attributes (like lifetime, event store, etc.) are changed by calling an action (e.g., set or add) for <name> or <alias>. If the delete action is called for one of the context names, the context data structure is destroyed, and all context names (which are now pointers to unallocated memory) are removed from the list of context names. Also note that if the lifetime of the context is exceeded, its action list is executed only once, no matter how many names the context has.

unalias [<alias>]

Context name <alias> is removed from the list of context names, so that the name <alias> can no longer be used to refer to the context it was previously associated with (<alias> may not contain spaces). If <alias> is omitted, %s is assumed for its value. If unalias is called for non-existing context name, no operation will be performed. If the name <alias> was the last reference to a context, the unalias action behaves like delete and the context will be deleted; otherwise the context will continue to exist under another name(s) with its event store and other attributes intact.

add <name> [<event text>]

Event string <event text> is added to the event store of the context <name> (<name> may not contain spaces). Events in the store are ordered by the time they were added, and every add adds event to the end of the store. If <event text> is omitted, %s is assumed for its value. If context <name> does not exist, the context will be created with infinite lifetime, empty action list and empty event store (as with create <name>) before adding the event. If <event text> contains newlines, it will be split into parts using the newline symbol as a delimiter, and each part is added to the event store as a separate event string.

fill <name> [<event text>]

Behaves like add, except the event store of the context <name> will be emptied before <event text> is added.

report <name> [<shellcmd>]

Event store of the context <name> is reported with shell command <shellcmd> (<name> may not contain spaces). Reporting means that events from the store are fed to standard input of <shellcmd> in the order they were added into the store, every event on a separate line. If <shellcmd> is omitted, events from the store are written to standard output.

copy <name> %<alnum_name>

Event store of the context <name> is assigned to a user-defined variable %<alnum_name> (<name> may not contain spaces). Before assignment takes place, lines from the event store are joined into a scalar using the newline character as the separator (as with Perl join("\n", @array)).

empty <name> [%<alnum_name>]

Behaves like copy, except the event store of the context <name> will be emptied after it has been assigned to the variable %<alnum_name>. If %<alnum_name> is omitted, empty simply removes all lines from the event store.

event [<time>] [<event text>]

After <time> seconds a synthetic event <event text> is created (<time> is an integer constant). SEC treats the <event text> string exactly like line(s) read from input - it is inserted into the input buffer in order to compare it with rules. If <event text> is omitted, %s is assumed for its value. Specifying 0 as <time> or omitting the value means now. If <event text> contains newlines, it will be split into parts using the newline symbol as a delimiter, and each part is created as a separate synthetic event.

reset [<rule_number>] [<event text>]

Cancel event correlation operations that are currently detecting the composite event <event text> (<rule_number> is a string constant), i.e., SEC will terminate event correlation operations that have <event text> in their keys as event description string (if such operations exist, see RULES AND EVENT CORRELATION OPERATIONS section for more information). If there are multiple configuration files specified, reset can cancel only those correlation operations that have been started by the rules from the same configuration file where the reset action itself is defined. If <event text> is omitted, %s is assumed for its value. Since correlation operations started by different rules may detect composite events that have identical description strings, rule number can be optionally specified to point to a correlation operation that was started by a specific rule (1 means first rule in the configuration file, 2 means second, etc.; 0 denotes the current rule). If + or - is prepended to <rule_number>, it is considered to be an offset from current rule (e.g., -1 means previous rule and +1 next rule). For example, if a rule definition with the reset action is given in the configuration file named my.conf, then reset 1 Counting linkdown events will terminate the event correlation operation with the key "my.conf | 0 | Counting linkdown events" (note that internally the SEC rule IDs start from zero), while reset Counting linkdown events will terminate event correlation operations with keys "my.conf | X | Counting linkdown events", where X runs from 0 to N-1 and N is the number of rules in the configuration file my.conf. If no operation with a given key exists, reset will take no action.

assign %<alnum_name> [<text>]

Text <text> is assigned to a user-defined variable %<alnum_name>. If <text> is omitted, %s is assumed for its value.

eval %<alnum_name> <code>

The parameter <code> is assumed to be a Perl miniprogram that will be executed by calling Perl eval() function in list context. If the miniprogram returns a single value, it will be assigned to the variable %<alnum_name>. If the miniprogram returns several values, they will be joined into a scalar using the newline character as a separator (as with Perl join("\n", @array)), and the scalar will be assigned to the variable %<alnum_name>. If no value is returned or eval() fails, no assignment will take place. Note that before calling eval(), $<number>, %<number>, and %<alnum_name> variables in the miniprogram are replaced with their values and therefore can't be used as lvalues. Since most Perl programs contain semicolons which are also used by SEC as separators between actions, it is recommended to enclose the <code> parameter in parentheses, in order to avoid the inperpretation of semicolons inside the code by SEC. Also see VARIABLES AND EVAL section for more information.

call %<alnum_name1> %<alnum_name2> [<parameter list>]

The parameter %<alnum_name2> is assumed to be a reference to a Perl function that was created previously with the eval action. The function will be called in list context by passing optional parameter list to the function (parameters are separated by whitespace). If the function returns a single value, it will be assigned to the variable %<alnum_name1>. If the function returns several values, they will be joined into a scalar using the newline character as a separator (as with Perl join("\n", @array)), and the scalar will be assigned to the variable %<alnum_name1>. If no value is returned or %<alnum_name2> is not a code reference, no assignment will take place. Also see VARIABLES AND EVAL section for more information.

Examples:

spawn /bin/tail -f /var/log/trapd.log

Follow the /var/log/trapd.log file and feed to SEC input all lines that are appended to the file.

pipe '%t: $0' /bin/mail -s "alert message" root@localhost

Mail the timestamp and the value of the $0 variable to the local root.

add ftp_$1 $0; set ftp_$1 1800 (report ftp_$1 /bin/mail root@localhost)

Add the value of the $0 variable to the event store of the context ftp_<the value of $1>. Also extend the context's lifetime for 30 minutes, so that when the context's lifetime is exceeded, its event store will be mailed to the local root.

eval %funcptr ( sub { my(@buf) = split(/\n/, $_[0]); \

my(@ret) = grep(!/^#/, @buf); return @ret; } ); \

copy C1 %in; call %out %funcptr %in; fill C1 %out

Create a subroutine for weeding out comment lines from the input list, and use this subroutine for removing comment lines from the event store of the context C1.

As already noted, SEC context expressions and action lists may contain parentheses which are used for grouping and masking purposes. When SEC parses its configuration, it checks whether parentheses in context expressions and action lists are balanced (i.e., whether each parenthesis has a counterpart), since unbalanced parentheses introduce ambiguity. This can cause SEC to reject some otherwise legitimate constructs, e.g.,

action=eval %o (print ")";)

will be considered an invalid action list (however, note that

action=eval %o (print "()";)

would be passed by SEC, since now parentheses are balanced). In order to avoid such unwanted behavior, each parenthesis without a counterpart must be masked with a backslash (the backslash will be removed by SEC during configuration file parsing), e.g.,

action=eval %o (print "\)";)

The Single rule was designed for matching input events that require immediate action to be taken. Its rule definition has the following parameters:

type

fixed to Single (value is case insensitive, so single or sIngLe can be used instead).

continue (optional)

TakeNext or DontCont (values are case insensitive). The first specifies that search for matching rules will continue after the match (i.e., input line(s) that match pattern and context will be passed to the next rule), the second will quit the search. If continue keyword is missing from the rule definition, DontCont is assumed.

ptype

pattern type (value is case insensitive).

pattern

pattern.

context (optional)

context expression.

desc

textual description of detected event.

action

action list that will be executed when event is detected.

Note that context, desc, and action parameters may contain $<number> variables.

Examples:

type=single

continue=takenext

ptype=regexp

pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session opened

desc=ftp session opened for ristov2 pid $1

action=create ftp_$1

type=single

continue=takenext

ptype=regexp

pattern=ftpd\[(\d+)\]:

context=ftp_$1

desc=ftp session event for ristov2 pid $1

action=add ftp_$1 $0; set ftp_$1 1800 \ (report ftp_$1 /bin/mail root@localhost)

type=single

ptype=regexp

pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session closed

desc=ftp session closed for ristov2 pid $1

action=report ftp_$1 /bin/mail root@localhost; \ delete ftp_$1

First rule creates context with the name ftp_<pid> when someone connects from host ristov2 with ftp. The second rule adds all logfile lines that are associated with the session <pid> to the event store of the context ftp_<pid> (before adding a line, the rule checks if the context exists). After adding a line, the rule extends context's lifetime for 30 minutes and sets the action list that will be executed when context times out. The third rule mails collected logfile lines to root@localhost when the session <pid> is closed. Collected lines will also be mailed when the session <pid> has been inactive for 30 minutes (no logfile lines observed for that session).

Note that the logfile line that has matched the first rule will be passed to the second rule and will become the first line in the event store (the first rule has continue parameter set to TakeNext). The second rule has also continue parameter set to TakeNext, since otherwise no logfile lines would reach the third rule.

The SingleWithScript rule was designed to integrate external scripts with SEC event flow. Its rule definition is similar to the Single rule, except of additional script parameter:

type

fixed to SingleWithScript (value is case insensitive).

continue (optional)

TakeNext or DontCont (values are case insensitive).

ptype

pattern type (value is case insensitive).

pattern

pattern.

context (optional)

context expression.

script

script that is executed after pattern and context have matched some input line(s). The names of all existing contexts are fed to the standard input of the script, a name per line. If the script returns zero for its exit value, action will be executed; if the script returns non-zero, action2 will be executed (if given).

desc

textual description of detected event.

action

action list that will be executed when script returns zero for its exit value.

action2 (optional)

action list that will be executed when script returns non-zero for its exit value.

Note that context, script, desc, action, and action2 parameters may contain $<number> variables.

Also note that since the runtime of the script that is specified by the script parameter is not limited in any way, waiting for that script to complete could freeze the entire event processing for an indefinite amount of time. Therefore, once the pattern and context parameters have matched input line(s), SEC does not wait for the script to complete but rather continues its work. The exit value of the script will be fetched when the script actually terminates, and depending on the exit value, either action or action2 (if it exists) will be executed.

Examples:

type=SingleWithScript

ptype=RegExp

pattern=interface (\S+) down

script=/usr/local/scripts/ping.sh $1

desc=Interface $1 down

action=shellcmd /usr/local/scripts/notify.sh "%s"

When "interface <ipaddress> down" line appears in input, this rule acts by calling

/usr/local/scripts/ping.sh <ipaddress>

and if the script returns 0 as its exit value, the rule calls

/usr/local/scripts/notify.sh "Interface <ipaddress> down"

(note also that SEC feeds the names of all existing contexts to the standard input of the /usr/local/scripts/ping.sh script.)

The SingleWithSuppress rule was designed to implement the event correlation operation called compression, where multiple instances of event A are reduced into single event. Its rule definition is similar to the Single rule, except of additional window parameter:

type

fixed to SingleWithSuppress (value is case insensitive).

continue (optional)

TakeNext or DontCont (values are case insensitive).

ptype

pattern type (value is case insensitive).

pattern

pattern for detecting event A.

context (optional)

context expression.

desc

textual description of event A.

action

action list that will be executed when event A is first observed. Following instances of event A will be ignored.

window

time in seconds that following events A are ignored for.

Note that context, desc, and action parameters may contain $<number> variables.

Examples:

type=SingleWithSuppress

ptype=RegExp

pattern=(\S+): [fF]ile system full

desc=File system $1 full

action=shellcmd notify.sh "%s"

window=900

When "/usr: file system full" line appears in input, this rule starts a correlation operation that calls

notify.sh "File system /usr full"

and ignores following such lines during next 15 minutes.

Note that line "/tmp: file system full" would not be ignored, since SEC identifies correlation operations by a key that contains event description string of the composite event (given by the desc parameter). Since strings "/usr: file system full" and "/tmp: file system full" differ, SEC will start another correlation operation for the latter (see RULES AND EVENT CORRELATION OPERATIONS section for more information).

The Pair rule was designed to implement one of the basic forms of the temporal relationship event correlation operation, where two or more events A and B are reduced into event pair (A, B) inside a given time window. Its rule definition has the following parameters:

type

fixed to Pair (value is case insensitive).

continue (optional)

TakeNext or DontCont (values are case insensitive). Specifies if input line(s) that match pattern and context will be passed to the next rule.

ptype

pattern type (value is case insensitive).

pattern

pattern for detecting event A.

context (optional)

context expression.

desc

textual description of event A.

action

action list that will be executed when event A is first observed. Following instances of event A will be ignored.

continue2 (optional)

TakeNext or DontCont (values are case insensitive). Specifies if input line(s) that match pattern2 and context2 will be passed to the next rule.

ptype2

pattern type (value is case insensitive).

pattern2

pattern for detecting event B.

context2 (optional)

context expression.

desc2

textual description of event B.

action2

action list that will be executed when event B is observed. After executing action2 the event correlation operation terminates.

window (optional)

time t in seconds that is allowed to elapse between first instance of event A and event B. If event B does not appear during t seconds, then the correlation operation started by this rule terminates. Specifying 0 as value or omitting window parameter means setting t to infinity (i.e., if event B does not appear, event A will be ignored forever).

Note that context, desc, action, context2, desc2, and action2 parameters may contain $<number> variables. The pattern2 parameter may contain $<number> variables if ptype2 supports variable substitutions at runtime. If pattern2 shadows the $<number> variables of pattern, then context2, desc2, and action2 parameters may contain %<number> variables.

Examples:

type=Pair

ptype=RegExp

pattern=NFS server (\S+) not responding

desc=$1 is not responding

action=shellcmd notify.sh "%s"

ptype2=substr

pattern2=NFS server $1 ok

desc2=$1 OK

action2=shellcmd notify.sh "%s"

window=3600

When "NFS server fserv is not responding" line appears in input, the correlation operation started by this rule calls

notify.sh "fserv is not responding"

and waits for the line "NFS server fserv ok" for 1 hour, ignoring all "NFS server fserv is not responding" lines. When the line "NFS server fserv ok" appears, the correlation operation executes shell command

notify.sh "fserv OK"

and terminates. If time (1 hour) runs out, the correlation operation will terminate without doing anything.

The PairWithWindow rule was designed to implement another variant of the temporal relationship event correlation operation that checks if event A will be followed by event B inside a given time window. Its rule definition has the following parameters:

type

fixed to PairWithWindow (value is case insensitive).

continue (optional)

TakeNext or DontCont (values are case insensitive). Specifies if input line(s) that match pattern and context will be passed to the next rule.

ptype

pattern type (value is case insensitive).

pattern

pattern for detecting event A.

context (optional)

context expression.

desc

textual description of event A.

action

action list that is executed after event A was observed and event B did not appear within the given time window.

continue2 (optional)

TakeNext or DontCont (values are case insensitive). Specifies if input line(s) that match pattern2 and context2 will be passed to the next rule.

ptype2

pattern type (value is case insensitive).

pattern2

pattern for detecting event B.

context2 (optional)

context expression.

desc2

textual description of event B.

action2

action list that is executed after event A was observed and event B appeared within the given time window. After executing action2 the event correlation operation terminates.

window

size of the time window in seconds.

Note that context, desc, action, context2, desc2, and action2 parameters may contain $<number> variables. The pattern2 parameter may contain $<number> variables if ptype2 supports variable substitutions at runtime. If pattern2 shadows the $<number> variables of pattern, then context2, desc2, and action2 parameters may contain %<number> variables.

Examples:

type=PairWithWindow

ptype=RegExp

pattern=node (\S+) interface (\S+) down

desc=$1 if $2 is down

action=shellcmd notify.sh "%s"

ptype2=SubStr

pattern2=node $1 interface $2 up

desc2=$1 if $2 short outage

action2=event

window=600

When "node fserv interface 192.168.1.1 down" line appears in input, this rule starts a correlation operation that waits 10 minutes for "node fserv interface 192.168.1.1 up" line, and if that line does not arrive on time, the correlation operation executes shell command

notify.sh "fserv if 192.168.1.1 is down"

and terminates. If the line arrives on time, the operation generates event "fserv if 192.168.1.1 short outage" and terminates.

The SingleWithThreshold rule was designed to implement the counting event correlation operation, where instances of event A are counted inside a given time window and the number of events is compared with a threshold value, in order to detect a composite event B. Its rule definition has the following parameters:

type

fixed to SingleWithThreshold (value is case insensitive).

continue (optional)

TakeNext or DontCont (values are case insensitive).

ptype

pattern type (value is case insensitive).

pattern

pattern for detecting event A.

context (optional)

context expression.

desc

textual description of event B.

action

action list that is executed when thresh instances of event A have been observed within the given time window. After that all events A will be ignored during the rest of the time window.

window

size of the time window in seconds. The window is sliding - if event A has been observed less than thresh times at the end of the window, the beginning of the window is moved to the occurrence time of the second instance of event A, and the counting operation will continue. If there is no second instance of event A (i.e., event has been observed only once), the correlation operation will terminate.

thresh

threshold value.

Note that context, desc, and action parameters may contain $<number> variables.

Examples:

type=SingleWithThreshold

ptype=RegExp

pattern=user (\S+) login failure on (\S+)

desc=Repeated login failures for user $1 on $2

action=shellcmd notify.sh "%s"

window=60

thresh=3

When line "user dbadmin login failure on tty1" is observed, the rule starts a correlation operation that executes shell command

notify.sh "Repeated login failures for user dbadmin on tty1"

if additional two such lines are observed within 1 minute. Following "user dbadmin login failure on tty1" lines will be ignored by this rule until 60 seconds have elapsed since the arrival of first line.

After changing the action parameter in the rule definition to

action=shellcmd notify.sh "%s"; reset 0 %s

the correlation operation will terminate itself after calling notify.sh, and the next matching line will always start a new counting operation.

The SingleWith2Thresholds rule was designed to implement another variant of the counting event correlation operation, where instances of event A are counted twice - first for checking if the threshold value is exceeded (in order to detect a composite event B), and then for checking if the number of instances will stay below the second threshold value (in order to detect a composite event C). Its rule definition has the following parameters:

type

fixed to SingleWith2Thresholds (value is case insensitive).

continue (optional)

TakeNext or DontCont (values are case insensitive).

ptype

pattern type (value is case insensitive).

pattern

pattern for detecting event A.

context (optional)

context expression.

desc

textual description of event B.

action

action list that is executed when thresh instances of event A have been observed within time window window. After that event counting is started again with threshold value thresh2 and time window window2.

window

size of the first time window in seconds. The window is sliding.

thresh

first threshold value.

desc2

textual description of event C.

action2

action list that is executed if no more than thresh2 instances of event A have been observed within last window2 seconds. After executing action2 the event correlation operation terminates.

window2

size of the second time window in seconds. The window is sliding.

thresh2

second threshold value.

Note that context, desc, action, desc2, and action2 parameters may contain $<number> variables.

Examples:

type=SingleWith2Thresholds

ptype=RegExp

pattern=(\S+): %SYS-3-CPUHOG

desc=router $1 CPU overload

action=shellcmd notify.sh "%s"

window=300

thresh=2

desc2=router $1 CPU load normal

action2=shellcmd notify.sh "%s"

window2=3600

thresh2=0

When SYS-3-CPUHOG syslog message is received from a router, the rule starts a counting operation that executes shell command

notify.sh "router <routername> CPU overload"

if additional SYS-3-CPUHOG syslog message is received from the router within next 5 minutes. After that the correlation operation waits until no SYS-3-CPUHOG syslog messages have been received from the router during last 1 hour, and then executes

notify.sh "router <routername> CPU load normal"

The Suppress rule was designed to implement event suppression and filtering, where event A is suppressed or filtered out if certain context is present or if the event parameters match the pattern specified. Its rule definition has the following parameters:

type

fixed to Suppress (value is case insensitive).

ptype

pattern type (value is case insensitive).

pattern

pattern for detecting event A (or its subclass) that must be suppressed (or filtered out).

context (optional)

context expression.

desc (optional)

textual description of this rule.

Note that the context parameter may contain $<number> variables.

Examples:

type=Suppress

ptype=RegExp

pattern=[Ff]ile system full

context=mycontext

type=Suppress

ptype=RegExp

pattern=/dev/vg01/\S+: [Ff]ile system full

First rule suppresses all "file system full" events if context mycontext is present. Second rule filters out all "file system full" events that concern volume group vg01.

The Calendar rule was designed for executing actions at specific times. Unlike all other rules, this rule reacts only to the system clock, ignoring other input. Its rule definition has the following parameters:

type

fixed to Calendar (value is case insensitive).

time

crontab-style time specification (see crontab(1) for more information). Time specification consists of five fields separated by whitespace characters. First field denotes minutes (allowed values 0-59), second field hours (allowed values 0-23), third field days (allowed values 0-31, 0 denotes the last day of the month), fourth field months (allowed values 1-12), and fifth field weekdays (allowed values 0-7, 0 and 7 denote Sunday). Asterisks (*), ranges of numbers (e.g., 8-11), and lists (e.g., 2,5,7-9) are allowed as field values.

context (optional)

context expression.

desc

event description string.

action

action list to be executed.

Examples:

type=Calendar

time=0 23 * * *

desc=NightContext

action=create %s 32400

This rule creates the context NightContext every day at 11PM. Context has a lifetime of 9 hours.

Consider the following rules:

type=single

continue=takenext

ptype=regexp

pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session opened

desc=ftp session opened for ristov2 pid $1

action=create ftp_$1

type=single

continue=takenext

ptype=regexp

pattern=ftpd\[(\d+)\]:

context=ftp_$1

desc=ftp session event for ristov2 pid $1

action=add ftp_$1 $0; set ftp_$1 1800 \ (report ftp_$1 /bin/mail root@localhost)

type=single

ptype=regexp

pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session closed

desc=ftp session closed for ristov2 pid $1

action=report ftp_$1 /bin/mail root@localhost; \ delete ftp_$1

First rule creates context with the name ftp_<pid> when someone connects from host ristov2 with ftp. The second rule adds all logfile lines that are associated with the session <pid> to the event store of the context ftp_<pid> (before adding a line, the rule checks if the context exists). After adding a line, the rule extends context's lifetime for 30 minutes and sets the action list that will be executed when context times out. The third rule mails collected logfile lines to root@localhost when the session <pid> is closed. Collected lines will also be mailed when the session <pid> has been inactive for 30 minutes (no logfile lines observed for that session).

Note that the logfile line that has matched the first rule will be passed to the second rule and will become the first line in the event store (the first rule has continue parameter set to TakeNext). The second rule has also continue parameter set to TakeNext, since otherwise no logfile lines would reach the third rule.

Suppose there is a backup job in your system that runs at 2AM every night and logs "BACKUP READY" message when it has completed its work. You want to send SNMP trap if there is no message in the log by 2:15AM.

type=Calendar

time=59 1 * * *

desc=WAITING FOR BACKUP

action=event %s

type=PairWithWindow

ptype=SubStr

pattern=WAITING FOR BACKUP

desc=Backup not ready!

action=shellcmd sendtrap.sh "%s"

ptype2=SubStr

pattern2=BACKUP READY

desc2=Backup ready

action2=none

window=960

The first rule generates "WAITING FOR BACKUP" event every night at 1:59AM. This event is matched by the second rule, which starts a correlation operation that will wait for "BACKUP READY" event for the next 16 minutes. If the event arrives on time, no action is executed, otherwise

sendtrap.sh "Backup not ready!"

is called.

Consider the following rules:

type=SingleWithScript

ptype=RegExp

pattern=node (\S+) interface (\S+) down

script=not_resp.sh $2

desc=NODE $1 IF $2 DOWN

action=event %s

type=Pair

ptype=RegExp

pattern=NODE (\S+) IF (\S+) DOWN

desc=Interface $2 is down at node $1

action=shellcmd notify.sh "%s"

ptype2=SubStr

pattern2=node $1 interface $2 up

desc2=Interface $2 is up at node $1

action2=shellcmd notify.sh "%s"

window=86400

If "node <node> interface <interface> down" event is observed, the interface is checked with not_resp.sh script. If the interface is found to be down (not_resp.sh returns 0 as its exit code), event "NODE <node> IF <interface> DOWN" is generated, which will be matched by the second rule. The second rule starts a correlation operation that calls

notify.sh "Interface <interface> is down at node <node>"

and then waits for the "node <node> interface <interface> up" event for the next 24 hours. When that event is observed, the correlation operation calls

notify.sh "Interface <interface> is up at node <node>"

and terminates.

Suppose you have a disk box that logs following error messages:

Description of Error:

Disk drive (CRU: A1) has failed and can no longer be accessed. (SP Event Code 0xA07)

Probable Cause / Recommended Action:

Replace the disk module (CRU: A1).

You would like to receive an e-mail message if something happens to the disk box. You would like to use different e-mail address at night-time and also receive a report of all night events. The problem here is that useful information is scattered over 7 lines and needs to be consolidated into single event. Consider the following rules to accomplish this task:

type=Calendar

time=0 22 * * *

desc=night

action=create %s 36000 \ (report %s /bin/mail root@localhost)

type=Single

ptype=RegExp7

pattern=Description of Error:\n.*\n(.+)\n.*\n.*\n.*\n(.+)

context=night

desc=Error=$1 Recmnd=$2

action=shellcmd nightalarm.sh "%s"; add night %s

type=Single

ptype=RegExp7

pattern=Description of Error:\n.*\n(.+)\n.*\n.*\n.*\n(.+)

desc=Error=$1 Recmnd=$2

action=shellcmd alarm.sh "%s"

First rule creates context night with the lifetime of 10 hours every day at 10PM. The second rule specifies that script nightalarm.sh must be used for sending alert messages at nights, otherwise script alarm.sh should be used. Every night-time event is added to context night, and collected events will be mailed to root@localhost at 8AM.

This section presents an example rulebase for managing Cisco devices. It is assumed that the managed devices have syslog(3)-style logging enabled, and that all syslog messages are sent to a central host and written to logfile(s) that are monitored by SEC.

# Set up contexts NIGHT and WEEKEND for nights

# and weekends. Context NIGHT has a lifetime

# of 8 hours and context WEEKEND 2 days

type=Calendar

time=0 23 * * *

desc=NIGHT

action=create %s 28800

type=Calendar

time=0 0 * * 6

desc=WEEKEND

action=create %s 172800

# If a router does not come up within 5 minutes

# after it was rebooted, generate event

# "<router> REBOOT FAILURE". The next rule matches

# this event, checks the router with ping and sends

# a notification if there is no response.

type=PairWithWindow

ptype=RegExp

pattern=(\S+) \d+: %SYS-5-RELOAD

desc=$1 REBOOT FAILURE

action=event %s

ptype2=RegExp

pattern2=($1) \d+: %SYS-5-RESTART

desc2=$1 successful reboot

action2=logonly

window=300

type=SingleWithScript

ptype=RegExp

pattern=(\S+) REBOOT FAILURE

script=not_responding.sh $1

desc=$1 did not come up after reboot

action=shellcmd notify.sh "%s"

# Send a notification if CPU load of a router is too

# high (two CPUHOG messages are received within 5

# minutes); send another notification if the load is

# normal again (no CPUHOG messages within last 15

# minutes). Rule is not applied at night or weekend.

type=SingleWith2Thresholds

ptype=RegExp

pattern=(\S+) \d+: %SYS-3-CPUHOG

context=!(NIGHT || WEEKEND)

desc=$1 CPU overload

action=shellcmd notify.sh "%s"

window=300

thresh=2

desc2=$1 CPU load normal

action2=shellcmd notify.sh "%s"

window2=900

thresh2=0

# If a router interface is in down state for less

# than 15 seconds, generate event

# "<router> INTERFACE <interface> SHORT OUTAGE";

# otherwise generate event

# "<router> INTERFACE <interface> DOWN".

type=PairWithWindow

ptype=RegExp

pattern=(\S+) \d+: %LINK-3-UPDOWN: Interface (.+), changed state to down

desc=$1 INTERFACE $2 DOWN

action=event %s

ptype2=RegExp

pattern2=($1) \d+: %LINK-3-UPDOWN: Interface ($2), changed state to up

desc2=$1 INTERFACE $2 SHORT OUTAGE

action2=event %s

window=15

# If "<router> INTERFACE <interface> DOWN" event is

# received from previous rule, send a notification and

# wait for "interface up" event for the next 24 hours

type=Pair

ptype=RegExp

pattern=(\S+) INTERFACE (\S+) DOWN

desc=$1 interface $2 is down

action=shellcmd notify.sh "%s"

ptype2=RegExp

pattern2=($1) \d+: %LINK-3-UPDOWN: Interface ($2), changed state to up

desc2=$1 interface $2 is up

action2=shellcmd notify.sh "%s"

window=86400

# If ten "short outage" events have been observed

# in the window of 6 hours, send a notification

type=SingleWithThreshold

ptype=RegExp

pattern=(\S+) INTERFACE (\S+) SHORT OUTAGE

desc=Interface $2 at node $1 is unstable

action=shellcmd notify.sh "%s"

window=21600

thresh=10