1sec.pl(1) General Commands Manual sec.pl(1)
2
6 sec.pl - simple event correlator
7
9 sec.pl [-conf=<file pattern> ...]
10 [-input=<file pattern>[=<context>] ...]
11 [-input_timeout=<input timeout>]
12 [-timeout_script=<timeout script>]
13 [-reopen_timeout=<reopen timeout>]
14 [-check_timeout=<check timeout>]
15 [-poll_timeout=<poll timeout>]
16 [-blocksize=<io block size>]
17 [-bufsize=<input buffer size>]
18 [-evstoresize=<event store size>]
19 [-cleantime=<clean time>]
20 [-log=<logfile>]
21 [-syslog=<facility>]
22 [-debug=<debuglevel>]
23 [-pid=<pidfile>]
24 [-dump=<dumpfile>]
25 [-quoting | -noquoting]
26 [-tail | -notail]
27 [-fromstart | -nofromstart]
28 [-detach | -nodetach]
29 [-intevents | -nointevents]
30 [-intcontexts | -nointcontexts]
31 [-testonly | -notestonly]
32 [-help] [-?]
33 [-version]
34
36 SEC is a tool that was designed for accomplishing various event corre‐
37 lation tasks in the domains of system monitoring, network and security
38 management, etc. Event correlation is a process where a stream of prim‐
39 itive events is processed in order to detect composite events that cor‐
40 respond to event patterns in the event stream.
41 After startup SEC reads lines from files, named pipes, or standard
43 input, matches the lines with patterns (regular expressions, Perl sub‐
44 routines, etc.) for recognizing input events, and correlates events
45 according to the rules in its configuration file(s). In order to
46 detect a composite event, rules are used sequentially in the same order
47 as they are given in the configuration file. If there are two or more
48 configuration files, rule sequences from different files are used vir‐
49 tually in parallel. SEC can be configured to produce its output by
50 executing user-specified shell commands, and by using utilities like
51 snmptrap(1) or snmpnotify(1), SEC can generate network management
52 events as output. Other options for producing output events are
53 described further in this man page.
54 Following rule types are currently implemented in SEC for detecting
56 composite events:
57 Single - match input event and execute an action immediately.
59 SingleWithScript - match input event and depending on the exit value of
61 an external script, execute an action.
62 SingleWithSuppress - match input event and execute an action immedi‐
64 ately, but ignore following matching events for the next t seconds.
65 Pair - match input event, execute an action immediately, and ignore
67 following matching events until some other input event arrives. On the
68 arrival of the second event execute another action.
69 PairWithWindow - match input event and wait for t seconds for other
71 input event to arrive. If that event is not observed within a given
72 time window, execute an action. If the event arrives on time, execute
73 another action.
74 SingleWithThreshold - count matching input events during t seconds and
76 if a given threshold is exceeded, execute an action and ignore all
77 matching events during the rest of the time window.
78 SingleWith2Thresholds - count matching input events during t1 seconds
80 and if a given threshold is exceeded, execute an action. Then start the
81 counting of matching events again and if their number per t2 seconds
82 drops below the second threshold, execute another action.
83 Suppress - suppress matching input events (used to keep the events from
85 being matched by later rules).
86 Calendar - execute an action at specific times.
88 Jump - submit matching input events to specific ruleset(s) for further
90 processing.
91 Options - set processing options for a ruleset.
93 If a rule defines the correlation of several events in a certain time
95 window, the rule will start an event correlation operation when the
96 first matching event occurs. In order to distinguish between different
97 event correlation operations that have been started by the rules, every
98 operation is assigned a unique key that is generated from the rule ID,
99 the name of the configuration file the rule belongs to, and the textual
100 description of the composite event that the correlation operation is
101 trying to detect (see RULES AND EVENT CORRELATION OPERATIONS section
102 for more information).
103 Rules support not only the execution of shell commands as actions, but
105 also the creation and deletion of contexts that decide whether a par‐
106 ticular rule can be applied at a given moment, the generation of syn‐
107 thetic events that will act as input for other rules, the clearing of
108 correlation operations that have been started by other rules, etc. This
109 makes it possible to combine several rules and form more complex event
110 correlation schemes. Contexts can not only be used for activating or
111 deactivating a particular rule, but they can also serve as event stores
112 (in logsurfer(1) the contexts are used in a similar way). There are
113 actions for adding events to a context, reporting all events associated
114 with a context, etc. By using the features of SEC in an appropriate
115 way, one can accomplish a wide range of event correlation and event
116 consolidation tasks.
117
119 -conf=<file pattern>
120 expand <file pattern> to filenames (with the Perl glob() func‐
121 tion) and read event correlation rules from every file. Multiple
122 -conf options can be specified at command line. Each time SEC
123 receives a signal that forces a configuration reload, <file pat‐
124 tern> is re-evaluated. See also TIMING section for a discussion
125 about the rule processing order when multiple configuration
126 files are involved.
127 -input=<file pattern>[=<context>]
129 expand <file pattern> to filenames (with the Perl glob() func‐
130 tion) and use the files as event sources. An input file can be a
131 regular file, named pipe, or standard input if - was specified.
132 Multiple -input options can be specified at command line. Each
133 time SEC receives a signal that forces it to reopen its input
134 files, <file pattern> is re-evaluated. If SEC experiences a
135 system error when reading from an input file, it will close the
136 file (use the -reopen_timeout option for reopening the file). If
137 <context> is given, SEC will set up the context <context> each
138 time it reads a line from input files that correspond to <file
139 pattern>. This will help the user to write rules that match data
140 from particular input source(s) only. When there is an -input
141 option with <context> specified, it will automatically enable
142 the -intcontexts option. See INTERNAL EVENTS AND CONTEXTS sec‐
143 tion for more information.
144 -input_timeout=<input_timeout>, -timeout_script=<timeout_script>
146 if SEC has not observed new data in an input file during
147 <input_timeout> seconds (or the file was closed <input_timeout>
148 seconds ago), <timeout_script> will be executed with command
149 line parameters 1 and <the name of the input file>. If fresh
150 data become available again, <timeout_script> will be executed
151 with command line parameters 0 and <the name of the input file>.
152 -reopen_timeout=<reopen_timeout>
154 if an input file is in closed state (e.g., because SEC has
155 failed to open it at startup), SEC will attempt to reopen this
156 input file after every <reopen_timeout> seconds until open suc‐
157 ceeds.
158 -check_timeout=<check_timeout>
160 if SEC has not observed new data in an input file, SEC will not
161 poll the file (both for status and data) during the next
162 <check_timeout> seconds.
163 -poll_timeout=<poll_timeout>
165 a real number that specifies how many seconds SEC will sleep
166 when no new data were read from input files. Default is 0.1 sec‐
167 onds.
168 -blocksize=<io_block_size>
170 size of the block in bytes that SEC will attempt to read from
171 input files at once. Default is 1024 (i.e., read from input
172 files by 1KB blocks).
173 -bufsize=<input_buffer_size>
175 set input buffer to hold last <input_buffer_size> lines that
176 have been read from input files. The content of input buffer
177 will be compared with patterns that are part of rule definitions
178 (i.e., no more than <input_buffer_size> lines can be matched by
179 a pattern at a time). Default size is 10 lines.
180 -evstoresize=<event_store_size>
182 set an upper limit to the size of context event stores - if an
183 event store already contains <event_store_size> events, SEC will
184 add no more events to that context, regardless of its configura‐
185 tion file directives.
186 -cleantime=<clean_time>
188 time interval in seconds that specifies how often internal event
189 correlation and context lists are processed, in order to accom‐
190 plish time-related tasks and to remove obsolete elements. See
191 TIMING section for more information. Default is 1 second.
192 -log=<logfile>
194 use <logfile> for logging SEC activities. Note that if the SEC
195 standard error is connected to a terminal, messages will be
196 logged there, in order to facilitate debugging. If the -detach
197 option has also been specified, no logging to standard error
198 will take place.
199 -syslog=<facility>
201 use syslog for logging SEC activities. All messages will be
202 logged with the facility <facility>, e.g., local0 (see syslog(3)
203 for possible facility values). Warning: be careful with this
204 option if you use SEC for monitoring syslog logfiles, because it
205 might create message loops (SEC log messages are written to SEC
206 input files that trigger new log messages).
207 -debug=<debuglevel>
209 set logging verbosity for the SEC logfile. Setting debuglevel to
210 <debuglevel> means that all messages from <debuglevel> and lower
211 levels are logged (e.g., if <debuglevel> is 3, messages from
212 levels 1, 2, and 3 are logged). The following levels are recog‐
213 nized by SEC:
214 1 - critical messages (severe faults that cause SEC to termi‐
215 nate, e.g., a failed system call)
216 2 - error messages (faults that need attention but don't cause
217 SEC to terminate, e.g., an incorrect rule definition in a con‐
218 figuration file)
219 3 - warning messages (possible faults, e.g., a command forked
220 from SEC terminated with a non-zero exit code)
221 4 - notification messages (normal system level events and inter‐
222 rupts, e.g., the reception of a signal)
223 5 - informative messages (information about external commands
224 forked from SEC)
225 6 - debug messages (detailed information about all SEC activi‐
226 ties)
227 Default <debuglevel> is 6 (i.e., log everything). See SIGNALS
228 section for information on how to change <debuglevel> at run‐
229 time.
230 -pid=<pidfile>
232 SEC will store its process ID to <pidfile> at startup.
233 -dump=<dumpfile>
235 SEC will use <dumpfile> as its dumpfile. See SIGNALS section for
236 more information. Default is /tmp/sec.dump.
237 -quoting, -noquoting
239 if the -quoting option is specified, event description strings
240 that are supplied to external shell commands of shellcmd and
241 spawn actions will be put inside apostrophes. All apostrophes '
242 that strings originally contain will be masked. This option pre‐
243 vents the shell from interpreting special symbols that event
244 description strings might contain. Default is -noquoting.
245 -tail, -notail
247 if the -notail option is specified, SEC will process all data
248 that are currently available in input files and exit after
249 reaching all EOFs. Default is -tail - SEC will jump to the end
250 of input files and wait for new lines to arrive. With the -tail
251 option, SEC follows an input file by its name (and not merely by
252 its i-node). If the input file is recreated or truncated, SEC
253 will reopen it and process its content from the start. If the
254 input file is removed (i.e., there is just an i-node left with‐
255 out name), SEC will keep the i-node open and wait for the input
256 file to be recreated.
257 -fromstart, -nofromstart
259 these flags have no meaning when the -notail option is also
260 specified. When used in combination with -tail (or alone, since
261 -tail is enabled by default), -fromstart will force SEC to read
262 and process input files from the beginning to the end, before
263 the 'tail' mode is entered at SEC startup. Default is -nofrom‐
264 start.
265 -detach, -nodetach
267 if the -detach option is specified, SEC will disassociate itself
268 from the controlling terminal and become a daemon at startup
269 (note that SEC will close its standard input, standard output,
270 and standard error, and change its working directory to the root
271 directory). Default is -nodetach.
272 -intevents, -nointevents
274 SEC will generate internal events when it starts up, when it
275 receives certain signals, and when it terminates normally. Spe‐
276 cific rules can be written to match those internal events, in
277 order to take some action at SEC startup, restart, and shutdown.
278 See INTERNAL EVENTS AND CONTEXTS section for more information.
279 Default is -nointevents.
280 -intcontexts, -nointcontexts
282 SEC will create an internal context when it reads a line from an
283 input file. This will help the user to write rules that match
284 data from particular input source only. See INTERNAL EVENTS AND
285 CONTEXTS section for more information. Default is -nointcon‐
286 texts.
287 -testonly, -notestonly
289 if the -testonly option is specified, SEC will exit immediately
290 after parsing the configuration file(s). If the configuration
291 file(s) contained no faulty rules, SEC will exit with 0, other‐
292 wise with 1. Default is -notestonly.
293 -help, -?
295 SEC will output usage information and exit.
296 -version
298 SEC will output version information and exit.
299 Note that one can introduce options both with a single dash (-) and
301 double dash (--), and also use both the equal sign (=) and whitespace
302 as a separator between the option name and the option value, e.g.,
303 -conf=<file pattern> and --conf <file pattern> are equivalent.
304
306 The SEC configuration file consists of rule definitions which are sepa‐
307 rated by empty and comment lines. Each rule definition is made up of
308 keyword=value pairs, one keyword and value per line. Values are case
309 sensitive only where character case is important (like the values spec‐
310 ifying regular expressions). \-symbol may be used at the end of a line
311 to continue the keyword=value pair on the next line. Lines which begin
312 with #-symbol are treated as comments and ignored (whitespace charac‐
313 ters may precede #-symbol). Any comment line, empty line, or end of the
314 file will terminate the preceding rule definition. In order to insert
315 comments into the rule definition, the rem keyword can be used.
316 Apart from keywords that are part of rule definitions, label keywords
318 may appear anywhere in the configuration file. The value of each label
319 keyword will be treated as a label that can be referred to in rule def‐
320 initions as a point-of-continue. This allows to continue event pro‐
321 cessing at a rule that follows the label, after the current rule has
322 matched and processed the event.
323 Before describing each rule type in detail, patterns and pattern types,
325 context expressions, and action lists are discussed, since they are
326 important parts of the rule definition.
327 PATTERNS AND PATTERN TYPES
329 SEC supports the following pattern types (if <number> is omitted, 1 is
330 assumed):
331 SubStr[<number>]
333 pattern is assumed to be a substring that will be searched in
334 last <number> input lines L1, L2, ..., L<number>. The input
335 lines are joined into a single string with the newline character
336 acting as a separator, and the resulting string
337 "L1\nL2\n...\nL<number>" is searched for the substring. (Note
338 that if <number> is 1, the last input line without a terminating
339 newline is searched.) If the substring is found, the pattern
340 matches. The backslash constructs \t, \n, \r, \s, and \0 can be
341 used in the pattern to denote tabulation, newline, carriage
342 return, space character, and empty string, while \\ denotes
343 backslash itself. As an example, consider the following pattern
344 definition:
345 ptype=substr
347 pattern=Backup done:\tsuccess
348 The pattern matches lines containing "Backup done:<TAB>success".
350 RegExp[<number>]
352 pattern is assumed to be a regular expression that last <number>
353 input lines L1, L2, ..., L<number> are compared with. The input
354 lines are joined into a single string with the newline character
355 acting as a separator, and the resulting string
356 "L1\nL2\n...\nL<number>" is compared with the regular expression
357 pattern. (Note that if <number> is 1, the last input line with‐
358 out a terminating newline is compared with the pattern.) If the
359 pattern matches, backreference values will be assigned to the
360 special variables $1, $2, ..., and the special variable $0 will
361 be set to "L1\nL2\n...\nL<number>" (i.e., to the matching input
362 line(s)). These special variables can be used in some other
363 parts of the rule definition. All regular expression constructs
364 that Perl allows are allowed in the pattern (see perlre(1) for
365 more information). As an example, consider the following pattern
366 definition:
367 ptype=regexp
369 pattern=(?i)(\S+\.mydomain).*printer: toner\/ink low
370 The pattern matches "printer: toner/ink low" messages in a case
372 insensitive manner from printers belonging to .mydomain. Note
373 that the printer hostname is assigned to $1, while the whole
374 message line is assigned to $0. As another example, the follow‐
375 ing pattern definition
376 ptype=regexp2
378 pattern=^AAA\nBBB$
379 produces a match if the last two input lines are AAA and BBB,
381 and sets $0 to "AAA\nBBB".
382 PerlFunc[<number>]
384 pattern is assumed to be a Perl function that last <number>
385 input lines L1, L2, ..., L<number> are submitted to. The Perl
386 function is compiled at SEC startup by calling the Perl eval()
387 function, and eval() must return a code reference for the pat‐
388 tern to be valid (also see VARIABLES AND EVAL section for more
389 information). In order to check whether the pattern matches,
390 SEC will call the function in list context and pass lines L1,
391 L2, ..., L<number> and the names of corresponding input sources
392 S1, S2, ..., S<number> to the function as parameters:
393 function(L1, L2, ..., L<number>, S1, S2, ..., S<number>)
395 (if the input line has been generated with the event action, its
397 input source name will be set to 'undef'). If the function
398 returns several values or a single value that is TRUE in boolean
399 context, the pattern matches. If the pattern matches, return
400 values will be assigned to the special variables $1, $2, ...,
401 and the special variable $0 will be set to "L1\nL2\n...\nL<num‐
402 ber>" (i.e., to the matching input line(s)). These special vari‐
403 ables can be used in some other parts of the rule definition. As
404 an example, consider the following pattern definition:
405 ptype=perlfunc2
407 pattern=sub { return ($_[0] cmp $_[1]); }
408 The pattern compares last two input lines in a stringwise manner
410 ($_[1] holds the last line and $_[0] the preceding one), and
411 matches if the lines are different. Note that the result of the
412 comparison is assigned to $1, while the two input lines are con‐
413 catenated (with the newline character between them) and assigned
414 to $0. As another example, the following pattern definition
415 ptype=perlfunc
417 pattern=sub { if ($_[0] =~ /(abc|def)/) { \
418 return defined($_[1]) ? $_[1] : "SEC"; } return 0; }
419 produces a match if the input line contains either the string
421 "abc" or the string "def", and sets $0 to the matching line and
422 $1 to the name of the input source.
423 NSubStr[<number>]
425 like SubStr[<number>], except the result of the match is
426 negated.
427 NRegExp[<number>]
429 like RegExp[<number>], except the result of the match is
430 negated.
431 NPerlFunc[<number>]
433 like PerlFunc[<number>], except the result of the match is
434 negated.
435 TValue pattern is assumed to be a truth value with TRUE and FALSE being
437 legitimate values for the pattern. TRUE always matches an input
438 line while FALSE never matches an input line.
439 Note that since Pair and PairWithWindow rules have two pattern defini‐
441 tions, special variables $<number> set by the first pattern are shad‐
442 owed when the second pattern matches and sets the variables. In order
443 to access the shadowed variables, they must be referred to as %<number>
444 (e.g., instead of $1 one has to write %1). Also note that the second
445 pattern of Pair and PairWithWindow rules may contain $<number> vari‐
446 ables, if the second pattern is of type SubStr, NSubStr, Regexp, or
447 NRegExp. The variables are substituted at runtime with the values set
448 by the first pattern.
449 CONTEXT EXPRESSIONS
451 Context expression is a logical expression that consists of context
452 names, Perl miniprograms, and Perl functions as operands; operands are
453 combined with operators ! (logical NOT), && (short-circuit logical
454 AND), || (short-circuit logical OR), and parentheses. Context expres‐
455 sions are employed for activating or deactivating rules - normally, the
456 context expression is evaluated immediately after the pattern has
457 matched input line(s), and the rule will process the input line(s) only
458 if the expression evaluates TRUE.
459 If the operand contains the arrow (->), the text following the arrow is
461 considered to be a Perl function that will be compiled at SEC startup
462 by calling the Perl eval() function, and eval() must return a code ref‐
463 erence for the operand to be valid (also see VARIABLES AND EVAL section
464 for more information). If any text precedes the arrow, it is consid‐
465 ered to be the list of parameters for the function. Parameters are
466 separated by whitespace and may contain $<number> and %<number> special
467 variables. In order to evaluate the Perl function operand, the function
468 with its parameter list will be called in scalar context. If the return
469 value of the function is TRUE in boolean context, the truth value of
470 the operand is TRUE, otherwise its truth value is FALSE.
471 If the operand begins with the equal sign (=), the following text is
473 considered to be a Perl miniprogram. The miniprogram may contain $<num‐
474 ber> and %<number> special variables. In order to evaluate the Perl
475 miniprogram operand, it will be executed by calling the Perl eval()
476 function in scalar context (also see VARIABLES AND EVAL section for
477 more information). If the return value of the miniprogram is TRUE in
478 boolean context, the truth value of the operand is TRUE, otherwise its
479 truth value is FALSE.
480 Note that since Perl functions, miniprograms, and parameter lists may
482 contain strings that clash with the operators of the context expression
483 (e.g., '!'), it is strongly recommended to enclose them in parentheses,
484 e.g.,
485 ($1 $2) -> (sub { return ($_[0] != $_[1]); })
487 =({my($temp) = 0; return !$temp;})
489 If the operand is not a Perl function or program, it is considered to
491 be a context name. Context name may contain $<number> and %<number>
492 special variables. If the context name refers to an existing context,
493 the truth value of the operand is TRUE, otherwise its truth value is
494 FALSE.
495 If the whole context expression is enclosed in square brackets [ ],
497 e.g., [MYCONTEXT1 && !MYCONTEXT2], SEC evaluates the expression
498 _before_ pattern matching operation (normally the pattern is compared
499 with input line(s) first, so that $<number> and %<number> variables in
500 the context expression could be replaced with their values). Evaluating
501 context expression first could save CPU time when many of the input
502 lines are known to match the pattern but not the context expression,
503 and the expression does not contain any variables.
504 As an example, consider the following context expressions:
506 -> ( sub { my(@stat) = stat("/var/log/messages"); \
508 return (!scalar(@stat) || time() - $stat[9] > 3600); } )
509 ($1 $2) -> (sub { return ($_[0] != $_[1]); }) && C1
511 !(C1 || C2) && =("$1" eq "myhost.mydomain")
513 The first expression is TRUE when the /var/log/messages file does not
515 exist or was last modified more than 1 hour ago. The second expression
516 is TRUE when variables $1 and $2 are numerically not equal and the con‐
517 text C1 exists. The third expression is TRUE when contexts C1 and C2
518 do not exist and the $1 variable equals to the string "myhost.mydo‐
519 main". Note that since && is a short-circuiting operation, the Perl
520 code of the third expression is not evaluated if C1 and/or C2 exist.
521 ACTION LISTS
523 Action list consists of action definitions that are separated by semi‐
524 colons. Each action definition begins with a keyword specifying the
525 action type, followed by additional parameters. Additional parameters
526 that do not have a constant nature may contain $<number> and %<number>
527 special variables. Also, the following variables can be used in non-
528 constant parameters:
529 %s - event description string (set either by the desc or desc2 parame‐
531 ter of the rule definition).
532 %t - textual timestamp (as returned by date(1)).
533 %u - numeric timestamp (as returned by time(2)).
534 %<alnum_name> - user-defined variables that can be set at SEC runtime
535 with certain actions like assign and eval (<alnum_name> must begin with
536 a letter and may contain letters, digits, and underscores). In order to
537 disambiguate <alnum_name> from the following text, <alnum_name> must be
538 enclosed in braces: %{<alnum_name>}.
539 In order to use semicolons inside a non-constant action parameter, the
541 parameter must be enclosed in parentheses (the outermost set of paren‐
542 theses will be removed by SEC during configuration file parsing).
543 The following actions are supported:
545 none No action.
547 logonly [<event text>]
549 Event string <event text> is logged. If <event text> is omit‐
550 ted, %s is assumed for its value.
551 write <filename> [<event text>]
553 Event string <event text> and terminating newline are written to
554 the file <filename> (<filename> may not contain spaces). File
555 may be a regular file, named pipe, or standard output if - was
556 specified. If the file is a regular file, <event text> is
557 appended to the end of the file. If the file does not exist, it
558 is created as a regular file before writing. If <event text> is
559 omitted, %s is assumed for its value. Though write can also be
560 expressed through the shellcmd action, write does not involve
561 fork(2) like shellcmd does.
562 shellcmd <shellcmd>
564 Shell command <shellcmd> is executed. If the -quoting option was
565 specified, %s will be converted to '%s' before supplying it to
566 shell command (see the -quoting and -noquoting options).
567 spawn <shellcmd>
569 Identical to the shellcmd action, except the following - every
570 line from the standard output of <shellcmd> is treated like SEC
571 input line and matched against the rules. This is done by
572 applying event 0 <line> to every line from standard output (see
573 the event action). Note that if <shellcmd> outputs a large data
574 set at once, SEC will process it all at once, so if <shellcmd>
575 enters an endless "busy write" loop, it will block SEC from
576 doing anything other than processing its output.
577 pipe '<event text>' [<shellcmd>]
579 Event string <event text> and terminating newline are fed to the
580 standard input of shell command <shellcmd> (apostrophes are used
581 to mark the beginning and end of <event text>, in order to dis‐
582 tinguish it from <shellcmd>). If <event text> is omitted and
583 there is nothing between apostrophes, %s is assumed for <event
584 text>. If <shellcmd> is omitted, <event text> is written to
585 standard output.
586 create [<name> [<time> [<action list>] ] ]
588 Context with the name <name>, with the lifetime of <time> sec‐
589 onds, and with empty event store is created (<name> may not con‐
590 tain spaces, and <time> must evaluate to an unsigned integer at
591 runtime). If <name> is omitted, %s is assumed for its value.
592 Specifying 0 as <time> or omitting the value means infinite
593 lifetime. If <action list> is specified, it will be executed
594 when the context expires. If <action list> is made up of more
595 than one action, semicolons must be used to separate the
596 actions, and the list must be enclosed in parentheses. In
597 <action list>, the internal context name _THIS may be used for
598 referring to the context <name> (see INTERNAL EVENTS AND CON‐
599 TEXTS section for a detailed discussion). If already existing
600 context is recreated with create, its lifetime will be extended
601 for <time> seconds, its action list will be reinitialized, and
602 its event store will be emptied.
603 delete [<name>]
605 Context with the name <name> is deleted (<name> may not contain
606 spaces). If <name> is omitted, %s is assumed for its value. If
607 non-existing context is deleted, no operation will be performed.
608 obsolete [<name>]
610 Behaves like delete, except the action list of the context
611 <name> (if the context has an action list) will be executed
612 before deletion.
613 set <name> <time> [<action list>]
615 Settings for the context with the name <name> will be changed
616 (<name> may not contain spaces, and <time> must evaluate to an
617 unsigned integer at runtime). New lifetime of the context will
618 be <time> seconds with optional <action list> to be executed
619 when the context expires. If <action list> is omitted, set will
620 not modify the action list of the context (note that prior to
621 SEC 2.5.3, the action list was cleared). Event store of the
622 context will not be altered by set. Specifying 0 as <time>
623 means infinite lifetime. If <action list> is made up of more
624 than one action, semicolons must be used to separate the
625 actions, and the list must be enclosed in parentheses. In
626 <action list>, the internal context name _THIS may be used for
627 referring to the context <name> (see INTERNAL EVENTS AND CON‐
628 TEXTS section for a detailed discussion).
629 alias <name> [<alias>]
631 An alias name <alias> will be created for the context with the
632 name <name> (<name> and <alias> may not contain spaces). After
633 the name <alias> has been created for a context, the context can
634 be referred to by using both <alias> and <name>. If <alias> is
635 omitted, %s is assumed for its value. If context with the name
636 <name> does not exist, or the name <alias> already exists, the
637 alias will not be created. Internally, SEC does not distinguish
638 in any way between <alias> and <name> - they are both pointers
639 to the same context data structure. Therefore, it makes no dif‐
640 ference whether context attributes (like lifetime, event store,
641 etc.) are changed by calling an action (e.g., set or add) for
642 <name> or <alias>. If the delete action is called for one of
643 the context names, the context data structure is destroyed, and
644 all context names (which are now pointers to unallocated memory)
645 are removed from the list of context names. Also note that if
646 the context expires, its action list is executed only once, no
647 matter how many names the context has.
648 unalias [<alias>]
650 Context name <alias> is removed from the list of context names,
651 so that the name <alias> can no longer be used to refer to the
652 context it was previously associated with (<alias> may not con‐
653 tain spaces). If <alias> is omitted, %s is assumed for its
654 value. If unalias is called for non-existing context name, no
655 operation will be performed. If the name <alias> was the last
656 reference to a context, the unalias action behaves like delete
657 and the context will be deleted; otherwise the context will con‐
658 tinue to exist under other name(s) with its event store and
659 other attributes intact.
660 add <name> [<event text>]
662 Event string <event text> is added to the event store of the
663 context <name> (<name> may not contain spaces). Events in the
664 store are ordered by the time they were added, and every add
665 appends event to the end of the store. If <event text> is omit‐
666 ted, %s is assumed for its value. If context <name> does not
667 exist, the context will be created with an infinite lifetime,
668 empty action list and empty event store (as with create <name>)
669 before adding the event. If <event text> contains newlines, it
670 will be split into parts using the newline symbol as a delimiter
671 (as with Perl split(/\n/, $event)), and each part is added to
672 the event store as a separate event string.
673 fill <name> [<event text>]
675 Behaves like add, except the event store of the context <name>
676 will be emptied before <event text> is added.
677 report <name> [<shellcmd>]
679 Event store of the context <name> is reported with shell command
680 <shellcmd> (<name> may not contain spaces). Reporting means that
681 events from the store are fed to standard input of <shellcmd> in
682 the order they were added into the store, every event on a sepa‐
683 rate line. If <shellcmd> is omitted, events from the store are
684 written to standard output.
685 copy <name> %<alnum_name>
687 Event store of the context <name> is assigned to a user-defined
688 variable %<alnum_name> (<name> may not contain spaces). Before
689 the assignment takes place, lines from the event store are
690 joined into a scalar using the newline character as the separa‐
691 tor (as with Perl join("\n", @array)).
692 empty <name> [%<alnum_name>]
694 Behaves like copy, except the event store of the context <name>
695 will be emptied after it has been assigned to the variable
696 %<alnum_name>. If %<alnum_name> is omitted, empty simply removes
697 all lines from the event store.
698 event [<time>] [<event text>]
700 After <time> seconds a synthetic event <event text> is created
701 (<time> is an integer constant). SEC treats the <event text>
702 string exactly like line(s) read from input - it is inserted
703 into the input buffer in order to compare it with rules. If
704 <event text> is omitted, %s is assumed for its value. Specify‐
705 ing 0 as <time> or omitting the value means now. If <event text>
706 contains newlines, it will be split into parts using the newline
707 symbol as a delimiter (as with Perl split(/\n/, $event)), and
708 each part is created as a separate synthetic event.
709 tevent <time> [<event text>]
711 Behaves like event, except <time> may contain variables and must
712 evaluate to an unsigned integer at runtime.
713 reset [<rule_number>] [<event text>]
715 Cancel event correlation operations that are currently detecting
716 the composite event <event text> (<rule_number> is a string con‐
717 stant), i.e., SEC will terminate event correlation operations
718 that have <event text> in their keys as event description string
719 (if such operations exist, see RULES AND EVENT CORRELATION OPER‐
720 ATIONS section for a detailed discussion). If there are multi‐
721 ple configuration files specified, reset can cancel only those
722 correlation operations that have been started by the rules from
723 the same configuration file where the reset action itself is
724 defined. If <event text> is omitted, %s is assumed for its
725 value. Since correlation operations started by different rules
726 may detect composite events that have identical description
727 strings, rule number can be optionally specified to point to a
728 correlation operation that was started by a specific rule (1
729 means the first rule in the configuration file, 2 means the sec‐
730 ond, etc.; 0 denotes the current rule). If + or - is prepended
731 to <rule_number>, it is considered to be an offset from the cur‐
732 rent rule (e.g., -1 means the previous rule and +1 the next
733 rule). For example, if a rule definition with the reset action
734 is given in the configuration file named my.conf, then reset 1
735 Counting linkdown events will terminate the event correlation
736 operation with the key "my.conf | 0 | Counting linkdown events"
737 (note that internally the SEC rule IDs start from zero), while
738 reset Counting linkdown events will terminate event correlation
739 operations with keys "my.conf | X | Counting linkdown events",
740 where X runs from 0 to N-1 and N is the number of rules in the
741 configuration file my.conf. If no operation with a given key
742 exists, reset will take no action.
743 assign %<alnum_name> [<text>]
745 Text <text> is assigned to a user-defined variable
746 %<alnum_name>. If <text> is omitted, %s is assumed for its
747 value.
748 eval %<alnum_name> <code>
750 The parameter <code> is assumed to be a Perl miniprogram that
751 will be executed by calling the Perl eval() function in list
752 context. If the miniprogram returns a single value, it will be
753 assigned to the variable %<alnum_name>. If the miniprogram
754 returns several values, they will be joined into a scalar using
755 the newline character as a separator (as with Perl join("\n",
756 @array)), and the scalar will be assigned to the variable
757 %<alnum_name>. If no value is returned or eval() fails, no
758 assignment will take place. Note that before calling eval(),
759 $<number>, %<number>, and %<alnum_name> variables in the
760 miniprogram are replaced with their values and therefore can't
761 be used as lvalues. Since most Perl programs contain semicolons
762 which are also used by SEC as separators between actions, it is
763 recommended to enclose the <code> parameter in parentheses, in
764 order to avoid the inperpretation of semicolons inside the code
765 by SEC. Also see VARIABLES AND EVAL section for more informa‐
766 tion.
767 call %<alnum_name1> %<alnum_name2> [<parameter list>]
769 The parameter %<alnum_name2> is assumed to be a reference to a
770 Perl function that was created previously with the eval action.
771 The function will be called in list context by passing optional
772 parameter list to the function (parameters are separated by
773 whitespace). If the function returns a single value, it will be
774 assigned to the variable %<alnum_name1>. If the function returns
775 several values, they will be joined into a scalar using the new‐
776 line character as a separator (as with Perl join("\n", @array)),
777 and the scalar will be assigned to the variable %<alnum_name1>.
778 If no value is returned or %<alnum_name2> is not a code refer‐
779 ence, no assignment will take place. Also see VARIABLES AND
780 EVAL section for more information.
781 Examples:
783 spawn /bin/tail -f /var/log/trapd.log
785 Follow the /var/log/trapd.log file and feed to SEC input all lines that
787 are appended to the file.
788 pipe '%t: $0' /bin/mail -s "alert message" root@localhost
790 Mail the timestamp and the value of the $0 variable to the local root.
792 add ftp_$1 $0; set ftp_$1 1800 (report ftp_$1 /bin/mail root@localhost)
794 Add the value of the $0 variable to the event store of the context
796 ftp_<the value of $1>. Also extend the context's lifetime for 30 min‐
797 utes, so that when the context expires, its event store will be mailed
798 to the local root.
799 eval %funcptr ( sub { my(@buf) = split(/\n/, $_[0]); \
801 my(@ret) = grep(!/^#/, @buf); return @ret; } ); \
802 copy C1 %in; call %out %funcptr %in; fill C1 %out
803 Create a subroutine for weeding out comment lines from the input list,
805 and use this subroutine for removing comment lines from the event store
806 of the context C1.
807 OTHER ISSUES
809 As already noted, SEC context expressions and action lists may contain
810 parentheses which are used for grouping and masking purposes. When SEC
811 parses its configuration, it checks whether parentheses in context
812 expressions and action lists are balanced (i.e., whether each parenthe‐
813 sis has a counterpart), since unbalanced parentheses introduce ambigu‐
814 ity. This can cause SEC to reject some otherwise legitimate constructs,
815 e.g.,
816 action=eval %o (print ")";)
818 will be considered an invalid action list (however, note that
820 action=eval %o (print "()";)
822 would be passed by SEC, since now parentheses are balanced). In order
824 to avoid such unwanted behavior, each parenthesis without a counterpart
825 must be masked with a backslash (the backslash will be removed by SEC
826 during configuration file parsing), e.g.,
827 action=eval %o (print "\)";)
829 SINGLE RULE
831 The Single rule was designed for matching input events that require
832 immediate action to be taken. The rule definition has the following
833 parameters:
834 type fixed to Single (value is case insensitive, so single or sIngLe
836 can be used instead).
837 continue (optional)
839 TakeNext, DontCont or GoTo <label> (apart from <label>, values
840 are case insensitive). TakeNext specifies that search for match‐
841 ing rules will continue after the match (i.e., input line(s)
842 that match pattern and context will be passed to the next rule);
843 DontCont will quit the search. GoTo <label> allows to continue
844 the search for matching rules, starting from the location of
845 <label> in the configuration file (<label> must be defined with
846 the label keyword anywhere in the configuration file _after_ the
847 current rule definition). If the continue keyword is missing
848 from the rule definition, DontCont is assumed.
849 ptype pattern type (value is case insensitive).
851 pattern
853 pattern.
854 context (optional)
856 context expression.
857 desc textual description of the detected event.
859 action action list that will be executed when the event is detected.
861 rem (optional, may appear more than once)
863 remarks and comments.
864 Note that context, desc, and action parameters may contain $<number>
866 variables.
867 Examples:
869 type=single
871 continue=takenext
872 ptype=regexp
873 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session opened
874 desc=ftp session opened for ristov2 pid $1
875 action=create ftp_$1
876 type=single
878 continue=takenext
879 ptype=regexp
880 pattern=ftpd\[(\d+)\]:
881 context=ftp_$1
882 desc=ftp session event for ristov2 pid $1
883 action=add ftp_$1 $0; set ftp_$1 1800 \
884 (report ftp_$1 /bin/mail root@localhost)
885 type=single
887 ptype=regexp
888 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session closed
889 desc=ftp session closed for ristov2 pid $1
890 action=report ftp_$1 /bin/mail root@localhost; \
891 delete ftp_$1
892 The first rule creates the context with the name ftp_<pid> when someone
894 connects from host ristov2 with ftp. The second rule adds all logfile
895 lines that are associated with the session <pid> to the event store of
896 the context ftp_<pid> (before adding a line, the rule checks if the
897 context exists). After adding a line, the rule extends context's life‐
898 time for 30 minutes and sets the action list that will be executed when
899 the context expires. The third rule mails collected logfile lines to
900 root@localhost when the session <pid> is closed. Collected lines will
901 also be mailed when the session <pid> has been inactive for 30 minutes
902 (no logfile lines observed for that session).
903 Note that the logfile line that has matched the first rule will be
905 passed to the second rule and will become the first line in the event
906 store (the first rule has the continue parameter set to TakeNext). The
907 second rule has also its continue parameter set to TakeNext, since oth‐
908 erwise no logfile lines would reach the third rule.
909 SINGLEWITHSCRIPT RULE
911 The SingleWithScript rule was designed to integrate external scripts
912 with the SEC event flow. The rule definition is similar to the Single
913 rule, except of the additional script parameter:
914 type fixed to SingleWithScript (value is case insensitive).
916 continue (optional)
918 TakeNext, DontCont or GoTo <label> (apart from <label>, values
919 are case insensitive).
920 ptype pattern type (value is case insensitive).
922 pattern
924 pattern.
925 context (optional)
927 context expression.
928 script script that is executed after pattern and context have matched
930 some input line(s). The names of all existing contexts are fed
931 to the standard input of the script, a name per line. If the
932 script returns zero for its exit value, action will be executed;
933 if the script returns non-zero, action2 will be executed (if
934 given).
935 desc textual description of the detected event.
937 action action list that will be executed when script returns zero for
939 its exit value.
940 action2 (optional)
942 action list that will be executed when script returns non-zero
943 for its exit value.
944 rem (optional, may appear more than once)
946 remarks and comments.
947 Note that context, script, desc, action, and action2 parameters may
949 contain $<number> variables.
950 Also note that since the runtime of the script that is specified by the
952 script parameter is not limited in any way, waiting for that script to
953 complete could freeze the entire event processing for an indefinite
954 amount of time. Therefore, once the pattern and context parameters have
955 matched input line(s), SEC does not wait for the script to complete but
956 rather continues its work. The exit value of the script will be fetched
957 when the script actually terminates, and depending on the exit value,
958 either action or action2 (if it exists) will be executed.
959 Examples:
961 type=SingleWithScript
963 ptype=RegExp
964 pattern=interface (\S+) down
965 script=/usr/local/scripts/ping.sh $1
966 desc=Interface $1 down
967 action=shellcmd /usr/local/scripts/notify.sh "%s"
968 When "interface <ipaddress> down" line appears in input, this rule acts
970 by calling
971 /usr/local/scripts/ping.sh <ipaddress>
973 and if the script returns 0 as its exit value, the rule calls
975 /usr/local/scripts/notify.sh "Interface <ipaddress> down"
977 (note also that SEC feeds the names of all existing contexts to the
979 standard input of the /usr/local/scripts/ping.sh script.)
980 SINGLEWITHSUPPRESS RULE
982 The SingleWithSuppress rule was designed to implement the event corre‐
983 lation operation called compression, where multiple instances of event
984 A are reduced into a single event. The rule definition is similar to
985 the Single rule, except of the additional window parameter:
986 type fixed to SingleWithSuppress (value is case insensitive).
988 continue (optional)
990 TakeNext, DontCont or GoTo <label> (apart from <label>, values
991 are case insensitive).
992 ptype pattern type (value is case insensitive).
994 pattern
996 pattern for detecting event A.
997 context (optional)
999 context expression.
1000 desc textual description of event A.
1002 action action list that will be executed when event A is first
1004 observed. Following instances of event A will be ignored.
1005 window time in seconds that following events A are ignored for.
1007 rem (optional, may appear more than once)
1009 remarks and comments.
1010 Note that context, desc, and action parameters may contain $<number>
1012 variables.
1013 Examples:
1015 type=SingleWithSuppress
1017 ptype=RegExp
1018 pattern=(\S+): [fF]ile system full
1019 desc=File system $1 full
1020 action=shellcmd notify.sh "%s"
1021 window=900
1022 When "/usr: file system full" line appears in input, this rule starts a
1024 correlation operation that calls
1025 notify.sh "File system /usr full"
1027 and ignores following such lines during the next 15 minutes.
1029 Note that line "/tmp: file system full" would not be ignored, since SEC
1031 identifies correlation operations by a key that contains event descrip‐
1032 tion string of the composite event (given by the desc parameter). Since
1033 strings "/usr: file system full" and "/tmp: file system full" differ,
1034 SEC will start another correlation operation for the latter (see RULES
1035 AND EVENT CORRELATION OPERATIONS section for more information).
1036 PAIR RULE
1038 The Pair rule was designed to implement one of the basic forms of the
1039 temporal relationship event correlation operation, where two or more
1040 events A and B are reduced into event pair (A, B) inside a given time
1041 window. The rule definition has the following parameters:
1042 type fixed to Pair (value is case insensitive).
1044 continue (optional)
1046 TakeNext, DontCont or GoTo <label> (apart from <label>, values
1047 are case insensitive). Specifies if input line(s) that match
1048 pattern and context will be passed to the following rules.
1049 ptype pattern type (value is case insensitive).
1051 pattern
1053 pattern for detecting event A.
1054 context (optional)
1056 context expression.
1057 desc textual description of event A.
1059 action action list that will be executed when event A is first
1061 observed. Following instances of event A will be ignored.
1062 continue2 (optional)
1064 TakeNext, DontCont or GoTo <label> (apart from <label>, values
1065 are case insensitive). Specifies if input line(s) that match
1066 pattern2 and context2 will be passed to the following rules.
1067 ptype2 pattern type (value is case insensitive).
1069 pattern2
1071 pattern for detecting event B.
1072 context2 (optional)
1074 context expression.
1075 desc2 textual description of event B.
1077 action2
1079 action list that will be executed when event B is observed.
1080 After executing action2 the event correlation operation termi‐
1081 nates.
1082 window (optional)
1084 time t in seconds that is allowed to elapse between the first
1085 instance of event A and event B. If event B does not appear dur‐
1086 ing t seconds, then the correlation operation started by this
1087 rule terminates. Specifying 0 as value or omitting the window
1088 parameter means setting t to infinity (i.e., if event B does not
1089 appear, event A will be ignored forever).
1090 rem (optional, may appear more than once)
1092 remarks and comments.
1093 Note that context, desc, action, context2, desc2, and action2 parame‐
1095 ters may contain $<number> variables. The pattern2 parameter may con‐
1096 tain $<number> variables if ptype2 supports variable substitutions at
1097 runtime. If pattern2 shadows the $<number> variables of pattern, then
1098 context2, desc2, and action2 parameters may contain %<number> vari‐
1099 ables.
1100 Examples:
1102 type=Pair
1104 ptype=RegExp
1105 pattern=NFS server (\S+) not responding
1106 desc=$1 is not responding
1107 action=shellcmd notify.sh "%s"
1108 ptype2=substr
1109 pattern2=NFS server $1 ok
1110 desc2=$1 OK
1111 action2=shellcmd notify.sh "%s"
1112 window=3600
1113 When "NFS server fserv is not responding" line appears in input, the
1115 correlation operation started by this rule calls
1116 notify.sh "fserv is not responding"
1118 and waits for the line "NFS server fserv ok" for 1 hour, ignoring all
1120 "NFS server fserv is not responding" lines. When the line "NFS server
1121 fserv ok" appears, the correlation operation executes the shell command
1122 notify.sh "fserv OK"
1124 and terminates. If time (1 hour) runs out, the correlation operation
1126 will terminate without doing anything.
1127 PAIRWITHWINDOW RULE
1129 The PairWithWindow rule was designed to implement another variant of
1130 the temporal relationship event correlation operation that checks if
1131 event A will be followed by event B inside a given time window. The
1132 rule definition has the following parameters:
1133 type fixed to PairWithWindow (value is case insensitive).
1135 continue (optional)
1137 TakeNext, DontCont or GoTo <label> (apart from <label>, values
1138 are case insensitive). Specifies if input line(s) that match
1139 pattern and context will be passed to the following rules.
1140 ptype pattern type (value is case insensitive).
1142 pattern
1144 pattern for detecting event A.
1145 context (optional)
1147 context expression.
1148 desc textual description of event A.
1150 action action list that is executed after event A was observed and
1152 event B did not appear within the given time window.
1153 continue2 (optional)
1155 TakeNext, DontCont or GoTo <label> (apart from <label>, values
1156 are case insensitive). Specifies if input line(s) that match
1157 pattern2 and context2 will be passed to the following rules.
1158 ptype2 pattern type (value is case insensitive).
1160 pattern2
1162 pattern for detecting event B.
1163 context2 (optional)
1165 context expression.
1166 desc2 textual description of event B.
1168 action2
1170 action list that is executed after event A was observed and
1171 event B appeared within the given time window. After executing
1172 action2 the event correlation operation terminates.
1173 window size of the time window in seconds.
1175 rem (optional, may appear more than once)
1177 remarks and comments.
1178 Note that context, desc, action, context2, desc2, and action2 parame‐
1180 ters may contain $<number> variables. The pattern2 parameter may con‐
1181 tain $<number> variables if ptype2 supports variable substitutions at
1182 runtime. If pattern2 shadows the $<number> variables of pattern, then
1183 context2, desc2, and action2 parameters may contain %<number> vari‐
1184 ables.
1185 Examples:
1187 type=PairWithWindow
1189 ptype=RegExp
1190 pattern=node (\S+) interface (\S+) down
1191 desc=$1 if $2 is down
1192 action=shellcmd notify.sh "%s"
1193 ptype2=SubStr
1194 pattern2=node $1 interface $2 up
1195 desc2=$1 if $2 short outage
1196 action2=event
1197 window=600
1198 When "node fserv interface 192.168.1.1 down" line appears in input,
1200 this rule starts a correlation operation that waits 10 minutes for
1201 "node fserv interface 192.168.1.1 up" line, and if that line does not
1202 arrive on time, the correlation operation executes the shell command
1203 notify.sh "fserv if 192.168.1.1 is down"
1205 and terminates. If the line arrives on time, the operation generates
1207 event "fserv if 192.168.1.1 short outage" and terminates.
1208 SINGLEWITHTHRESHOLD RULE
1210 The SingleWithThreshold rule was designed to implement the counting
1211 event correlation operation, where instances of event A are counted
1212 inside a given time window and the number of events is compared with a
1213 threshold value, in order to detect a composite event B. The rule def‐
1214 inition has the following parameters:
1215 type fixed to SingleWithThreshold (value is case insensitive).
1217 continue (optional)
1219 TakeNext, DontCont or GoTo <label> (apart from <label>, values
1220 are case insensitive).
1221 ptype pattern type (value is case insensitive).
1223 pattern
1225 pattern for detecting event A.
1226 context (optional)
1228 context expression.
1229 desc textual description of event B.
1231 action action list that is executed when thresh instances of event A
1233 have been observed within the given time window. After that all
1234 events A will be ignored during the rest of the time window.
1235 action2 (optional)
1237 action list that is executed when the event correlation opera‐
1238 tion terminates, if action has been previously executed by the
1239 operation.
1240 window size of the time window in seconds. The window is sliding - if
1242 event A has been observed less than thresh times at the end of
1243 the window, the beginning of the window is moved to the occur‐
1244 rence time of the second instance of event A, and the counting
1245 operation will continue. If there is no second instance of
1246 event A (i.e., the event has been observed only once), the cor‐
1247 relation operation will terminate.
1248 thresh threshold value.
1250 rem (optional, may appear more than once)
1252 remarks and comments.
1253 Note that context, desc, and action parameters may contain $<number>
1255 variables.
1256 Examples:
1258 type=SingleWithThreshold
1260 ptype=RegExp
1261 pattern=user (\S+) login failure on (\S+)
1262 desc=Repeated login failures for user $1 on $2
1263 action=shellcmd notify.sh "%s"
1264 window=60
1265 thresh=3
1266 When line "user dbadmin login failure on tty1" is observed, the rule
1268 starts a correlation operation that executes the shell command
1269 notify.sh "Repeated login failures for user dbadmin on tty1"
1271 if additional two such lines are observed within 1 minute. Following
1273 "user dbadmin login failure on tty1" lines will be ignored by this rule
1274 until 60 seconds have elapsed since the arrival of first line.
1275 After changing the action parameter in the rule definition to
1277 action=shellcmd notify.sh "%s"; reset 0 %s
1279 the correlation operation will terminate itself after calling
1281 notify.sh, and the next matching line will start a new counting opera‐
1282 tion.
1283 SINGLEWITH2THRESHOLDS RULE
1285 The SingleWith2Thresholds rule was designed to implement another vari‐
1286 ant of the counting event correlation operation, where instances of
1287 event A are counted twice - first for checking if the threshold value
1288 is exceeded (in order to detect a composite event B), and then for
1289 checking if the number of instances will stay below the second thresh‐
1290 old value (in order to detect a composite event C). The rule defini‐
1291 tion has the following parameters:
1292 type fixed to SingleWith2Thresholds (value is case insensitive).
1294 continue (optional)
1296 TakeNext, DontCont or GoTo <label> (apart from <label>, values
1297 are case insensitive).
1298 ptype pattern type (value is case insensitive).
1300 pattern
1302 pattern for detecting event A.
1303 context (optional)
1305 context expression.
1306 desc textual description of event B.
1308 action action list that is executed when thresh instances of event A
1310 have been observed within the time window window. After that
1311 event counting continues with the threshold value thresh2 and
1312 time window window2.
1313 window size of the first time window in seconds. The window is sliding.
1315 thresh the first threshold value.
1317 desc2 textual description of event C.
1319 action2
1321 action list that is executed if no more than thresh2 instances
1322 of event A have been observed during the last window2 seconds.
1323 After executing action2 the event correlation operation termi‐
1324 nates.
1325 window2
1327 size of the second time window in seconds. The window is slid‐
1328 ing.
1329 thresh2
1331 the second threshold value.
1332 rem (optional, may appear more than once)
1334 remarks and comments.
1335 Note that context, desc, action, desc2, and action2 parameters may con‐
1337 tain $<number> variables.
1338 Examples:
1340 type=SingleWith2Thresholds
1342 ptype=RegExp
1343 pattern=(\S+): %SYS-3-CPUHOG
1344 desc=router $1 CPU overload
1345 action=shellcmd notify.sh "%s"
1346 window=300
1347 thresh=2
1348 desc2=router $1 CPU load normal
1349 action2=shellcmd notify.sh "%s"
1350 window2=3600
1351 thresh2=0
1352 When SYS-3-CPUHOG syslog message is received from a router, the rule
1354 starts a counting operation that executes the shell command
1355 notify.sh "router <routername> CPU overload"
1357 if additional SYS-3-CPUHOG syslog message is received from the router
1359 within 5 minutes. After that the correlation operation waits until no
1360 SYS-3-CPUHOG syslog messages have been received from the router during
1361 the last 1 hour, and then executes
1362 notify.sh "router <routername> CPU load normal"
1364 SUPPRESS RULE
1366 The Suppress rule was designed to implement event suppression and fil‐
1367 tering, where matching events are kept from being processed by later
1368 rules in the same configuration file. The rule definition has the fol‐
1369 lowing parameters:
1370 type fixed to Suppress (value is case insensitive).
1372 ptype pattern type (value is case insensitive).
1374 pattern
1376 pattern for detecting event A (or its subclass) that must be
1377 suppressed (or filtered out).
1378 context (optional)
1380 context expression.
1381 desc (optional)
1383 textual description of this rule.
1384 rem (optional, may appear more than once)
1386 remarks and comments.
1387 Note that the context parameter may contain $<number> variables.
1389 Examples:
1391 type=Suppress
1393 ptype=RegExp
1394 pattern=[Ff]ile system full
1395 context=mycontext
1396 type=Suppress
1398 ptype=RegExp
1399 pattern=/dev/vg01/\S+: [Ff]ile system full
1400 The first rule suppresses all "file system full" events if the context
1402 mycontext is present. The second rule filters out all "file system
1403 full" events that concern the volume group vg01.
1404 CALENDAR RULE
1406 The Calendar rule was designed for executing actions at specific times.
1407 Unlike all other rules, this rule reacts only to the system clock,
1408 ignoring other input. The rule definition has the following parameters:
1409 type fixed to Calendar (value is case insensitive).
1411 time crontab-style time specification (see crontab(1) for more infor‐
1413 mation). Time specification consists of five fields separated by
1414 whitespace characters. First field denotes minutes (allowed val‐
1415 ues 0-59), second field hours (allowed values 0-23), third field
1416 days (allowed values 0-31, 0 denotes the last day of the month),
1417 fourth field months (allowed values 1-12), and fifth field week‐
1418 days (allowed values 0-7, 0 and 7 denote Sunday). Asterisks (*),
1419 ranges of numbers (e.g., 8-11), and lists (e.g., 2,5,7-9) are
1420 allowed as field values. Asterisks and ranges may be augmented
1421 with step values (e.g., 47-55/2 means 47,49,51,53,55). There is
1422 one important difference from crontab-style time specification -
1423 the day and weekday field must always both match the current
1424 time for the action to be executed.
1425 context (optional)
1427 context expression.
1428 desc event description string.
1430 action action list to be executed.
1432 rem (optional, may appear more than once)
1434 remarks and comments.
1435 Examples:
1437 type=Calendar
1439 time=0 23 * * *
1440 desc=NightContext
1441 action=create %s 32400
1442 This rule creates the context NightContext every day at 11PM. Context
1444 has a lifetime of 9 hours.
1445 type=Calendar
1447 time=0 1 25-31 10 7
1448 desc=end of DST
1449 action=shellcmd dstend.sh
1450 This rule executes dstend.sh on last Sunday in October, 1 AM.
1452 JUMP RULE
1454 The Jump rule was designed for submitting matching events to specific
1455 ruleset(s) for further processing. This rule works as follows - if the
1456 input buffer matches the rule, SEC continues the search for matching
1457 rules in configuration file set(s) given with the cfset parameter.
1458 Rules from one file are tried sequentially in the order of their
1459 appearance; rule sequences from different files are used virtually in
1460 parallel. The rule definition has the following parameters:
1461 type fixed to Jump (value is case insensitive).
1463 continue (optional)
1465 TakeNext, DontCont or GoTo <label> (apart from <label>, values
1466 are case insensitive).
1467 ptype pattern type (value is case insensitive).
1469 pattern
1471 pattern for detecting events that are submitted for further pro‐
1472 cessing.
1473 context (optional)
1475 context expression.
1476 cfset (optional)
1478 configuration file set names that are separated by whitespace.
1479 Configuration file sets can be created with the Options rule
1480 (see its joincfset parameter), with each set containing at least
1481 one configuration file. If more that one set name is given,
1482 sets are processed from left to right; a matching rule in one
1483 set doesn't prevent SEC from processing the following sets.
1484 constset (optional)
1486 Yes or No (values are case insensitive). Yes means that the set
1487 names given with the cfset parameter are constants; No means
1488 that SEC will search the names for $<number> special variables
1489 after a match and substitute them with their current values. If
1490 the constset parameter is missing from the rule definition, Yes
1491 is assumed.
1492 desc (optional)
1494 textual description of this rule.
1495 rem (optional, may appear more than once)
1497 remarks and comments.
1498 Note that context and cfset parameters may contain $<number> variables
1500 (in the latter case, the variables will be replaced with their values
1501 only if constset is set to No). If the cfset parameter is omitted and
1502 continue is set to GoTo, the Jump rule can be used for skipping rules
1503 inside the current configuration file; if both cfset and continue are
1504 omitted, Jump is identical to Suppress.
1505 Examples:
1507 type=Jump
1509 ptype=RegExp
1510 pattern=sshd\[\d+\]:
1511 cfset=sshd-rules auth-rules
1512 When an sshd syslog message appears in input, rules from configuration
1514 files of the set sshd-rules are first used for matching the message,
1515 and then rules from the configuration file set auth-rules are tried.
1516 OPTIONS RULE
1518 The Options rule was designed for setting processing options for the
1519 ruleset in the current configuration file. If more than one Options
1520 rule is present in the configuration file, the last instance overrides
1521 all previous instances. Note that the Options rule is only processed
1522 when SEC (re)starts and reads in the configuration file. Since this
1523 rule is not applied at runtime, it can never match events, react to the
1524 system clock, or start event correlation operations. The rule defini‐
1525 tion has the following parameters:
1526 type fixed to Options (value is case insensitive).
1528 joincfset (optional)
1530 configuration file set names that are separated by whitespace.
1531 The ruleset in the current configuration file is added to every
1532 set in the list of names. If a set doesn't exist, it will be
1533 created and the current configuration file becomes its first
1534 member.
1535 procallin (optional)
1537 Yes or No (values are case insensitive). Yes means that the
1538 ruleset in the current configuration file is used for processing
1539 all input; No means that the ruleset in the current configura‐
1540 tion file is used for processing input from Jump rules only. If
1541 the Options rule is not present in the configuration file or the
1542 procallin parameter is missing from the rule definition, Yes is
1543 assumed.
1544 rem (optional, may appear more than once)
1546 remarks and comments.
1547 Examples:
1549 type=Options
1551 joincfset=sshd-rules
1552 procallin=no
1553 type=Options
1555 joincfset=linux solaris
1556 The first rule adds the current configuration file to the set sshd-
1558 rules which is used for matching input from Jump rules only. The sec‐
1559 ond rule adds the current configuration file to sets linux and solaris
1560 which are used for matching all input. Note that if these two rules
1561 appear in the same configuration file, the second rule will override
1562 the first.
1563
1565 Although each event correlation operation is started by a SEC rule,
1566 there is no one-to-one relationship between rules and event correlation
1567 operations, since one rule could start several event correlation opera‐
1568 tions that run simultaneously. In order to distinguish one event corre‐
1569 lation operation from another, SEC assigns a key to every operation
1570 that is composed from the rule file name, the rule ID, and the event
1571 description string that is derived from the desc parameter of the rule
1572 definition (by replacing variables with their values).
1573 Suppose you have a configuration file my.conf with one rule in it:
1575 type=SingleWithThreshold
1577 ptype=RegExp
1578 pattern=user (\S+) login failure on (\S+)
1579 desc=Repeated login failures for user $1 on $2
1580 action=shellcmd notify.sh "%s"
1581 window=60
1582 thresh=3
1583 Suppose that SEC observes an input line "user admin login failure on
1585 tty1". This matches the pattern 'user (\S+) login failure on (\S+)',
1586 and after replacing $1 and $2 with their values, the desc parameter
1587 will yield "Repeated login failures for user admin on tty1". SEC will
1588 then form a key for the event correlation operation, using the configu‐
1589 ration file name, the rule ID, and the event description string:
1590 my.conf | 0 | Repeated login failures for user admin on tty1
1592 Since the rule was the first one in the configuration file, its ID is
1594 0. The ID for the second rule would be 1, for the third rule 2, etc.
1595 Note that because the configuration file name and the rule ID are
1596 present in the keys, event correlation operations started by different
1597 rules will not clash, even if the rules have identical values for the
1598 desc parameter.
1599 After calculating the key, SEC will check if there already is an event
1601 correlation operation with that key. If such operation exists, the
1602 input line will be correlated by the existing operation. Otherwise, a
1603 new event correlation operation will be started.
1604 By using appropriate event description string definitions, you can
1606 change the scope of individual event correlation operations. For
1607 instance, if you use "Repeated login failures for user $1" for the desc
1608 parameter in the above rule definition, the following three lines will
1609 now be correlated by the same event correlation operation:
1610 user admin login failure on tty1
1612 user admin login failure on tty5
1613 user admin login failure on tty2
1614 In other words, SEC will now just count login failures for different
1616 users, disregarding terminal names.
1617 Finally, it should be noted that Single, SingleWithScript, Suppress,
1619 Calendar, and Jump rules never start event correlation operations,
1620 since they don't involve the matching of several events over a certain
1621 time window (i.e., their design allows them to complete their work
1622 almost immediately without starting an event correlation operation).
1623 Therefore, the desc parameter of these rules does not influence the
1624 number and the scope of event correlation operations.
1625
1627 There are several kinds of events that SEC reacts to - changes in input
1628 files (e.g., appearance of new data), reception of a signal, status
1629 change of a child process, and time related events (e.g., context expi‐
1630 ration).
1631 When new data appear in SEC input files, only one line will be read at
1633 a time (even when more lines are available), after which the input buf‐
1634 fer is updated with the line that was read. Input buffer contains the
1635 last N lines from the SEC input, in the order they were read (the value
1636 of N can be set with the -bufsize option). Updating the input buffer
1637 means that the last element (the oldest line) is removed from the end
1638 of the buffer, while the new line becomes the first element of the buf‐
1639 fer. Note that when synthetic events have been created with the event
1640 action and new input data are also available in input files, synthetic
1641 events are always read first by SEC. After no more such events are
1642 available for reading, SEC will read new data from input files.
1643 After the buffer has been updated (every update always adds only one
1645 and removes only one line), the rules from configuration files are pro‐
1646 cessed, matching the rules against the new content of the input buffer.
1647 Even when a rule matches and its action list suggests an immediate
1648 change in the buffer (e.g., through the event action), the input buffer
1649 will _not_ be updated until all the rules have been compared with the
1650 current content of the buffer.
1651 Rules from the same configuration file are compared with the input buf‐
1653 fer in the order they were given in that file. When multiple configu‐
1654 ration files have been specified, each file containing a distinct rule‐
1655 set, events are processed virtually in parallel - the buffer is always
1656 processed by all rulesets. However, the order the rulesets are applied
1657 during event processing is determined by the order the files were given
1658 at SEC command line. If a -conf option specifies a pattern, SEC uses
1659 the Perl glob() function to expand the pattern, and the resulting file
1660 list is applied by SEC in the order returned by glob(). E.g., if
1661 glob() returns filenames in ascending ASCII order, you have specified
1662 -conf options in the following way:
1663 -conf=/home/risto/*.conf -conf=/home/risto/*.conf2
1665 and directory /home/risto contains files A.conf, B.conf2, and C.conf,
1667 then SEC applies these ruleset files in the following order: A.conf,
1668 C.conf, and B.conf2. Also, note that even if A.conf contains a Suppress
1669 rule for a particular event, the event is still processed by rulesets
1670 in C.conf and B.conf2. However, if you want to enforce a fixed order
1671 for ruleset file application in a portable way, it is recommended to
1672 create a unique set for each file with the Options rule, and employ the
1673 Jump rule for defining the processing order for sets, e.g.:
1674 # This rule appears in A.conf
1676 type=Options
1677 joincfset=FileA
1678 procallin=no
1679 # This rule appears in B.conf2
1681 type=Options
1682 joincfset=FileB
1683 procallin=no
1684 # This rule appears in C.conf
1686 type=Options
1687 joincfset=FileC
1688 procallin=no
1689 # This rule appears in main.conf
1691 type=Jump
1692 ptype=TValue
1693 pattern=TRUE
1694 cfset=FileA FileC FileB
1695 After the input buffer has been updated and its content has been pro‐
1697 cessed by the rules, SEC handles the signals that have been received
1698 since the last check, and also reads possible output from its child
1699 processes. When the timeout specified with the -cleantime option has
1700 expired, SEC also checks the contexts and the event correlation opera‐
1701 tions that have timers associated with them (e.g., SingleWithSuppress
1702 and PairWithWindow rules). This means that the value of -cleantime
1703 should be relatively small, in order to keep the event correlation
1704 operations accurate. By setting the -cleantime option value to 0, SEC
1705 will check the event correlation timers after processing every line,
1706 but this will consume more CPU time. The higher the value, the less CPU
1707 time will be consumed, so the value of the -cleantime option depends on
1708 your requirements. Note that if the -poll_timeout option value exceeds
1709 the value given with -cleantime, the -poll_timeout option value takes
1710 precedence (i.e., sleeps after unsuccessful polls will not be short‐
1711 ened).
1712
1714 In the action list of a context, the context can also be referred with
1715 the internal context name _THIS. The name _THIS is created and deleted
1716 dynamically by SEC and it points to the context only during its action
1717 list execution. This feature is useful when the context has had sev‐
1718 eral names during its lifetime (created with the alias action), and it
1719 is hard to determine which names exist when the context expires. For
1720 example, if the context is created with create A 60 (report A /bin/mail
1721 root) which is immediately followed by alias A B and unalias A, the
1722 report action will fail since the name A no longer refers to the con‐
1723 text. However, replacing the first action with create A 60 (report
1724 _THIS /bin/mail root) will produce the correct result.
1725 If the -intevents command line option is given, SEC will generate
1727 internal events when it is started up, when it receives certain sig‐
1728 nals, and when it terminates normally. Inside SEC, internal event is
1729 treated as if it was a line that was read from a SEC input file. Spe‐
1730 cific rules can be written to match internal events, in order to take
1731 some action (e.g., start an external event correlation module with
1732 spawn when SEC starts up). The following internal events are supported:
1733 SEC_STARTUP - generated when SEC is started (once the -intevents option
1735 has been given, this event will always be the first event that SEC
1736 observes)
1737 SEC_RESTART - generated after SEC has received the SIGHUP signal and
1739 all internal data structures have been cleared (this event will be the
1740 first event that SEC observes after reloading its configuration)
1741 SEC_SOFTRESTART - generated after SEC has received the SIGABRT signal
1743 (this event will be the first event that SEC observes after reloading
1744 its configuration)
1745 SEC_SHUTDOWN - generated when SEC receives the SIGTERM signal, or when
1747 SEC reaches all EOFs of input files after being started with the
1748 -notail option. After generating SEC_SHUTDOWN event, SEC will sleep for
1749 3 seconds before sending SIGTERM to its child processes (if there are
1750 any child processes that were started by SEC_SHUTDOWN, the processes
1751 will have enough time to set a signal handler for SIGTERM if needed).
1752 Right before generating an internal event, SEC will also set up a con‐
1754 text named SEC_INTERNAL_EVENT, in order to distinguish between true
1755 internal events and coincidents that look like internal events. The
1756 SEC_INTERNAL_EVENT context will be deleted immediately after the inter‐
1757 nal event has been processed by all rules.
1758 If the -intcontexts command line option is given, or there is an -input
1760 option with a context specified, SEC will create an internal context
1761 each time a line is read from an input file, or a line is read that was
1762 created with the event action. The internal context will be deleted
1763 immediately after the line has been matched against all rules. For all
1764 input files that have the context name explicitly set with -input=<file
1765 pattern>=<context>, the name of the internal context is <context>. If
1766 the line was read from the input file <filename> for which there is no
1767 context name set, the name of the internal context is
1768 _FILE_EVENT_<filename>. If the line was created with the event action,
1769 the name of the internal context is _INTERNAL_EVENT. This will help the
1770 end user to write rules that will match data from one particular input
1771 source only, e.g., the rule
1772 type=Suppress
1774 ptype=TValue
1775 pattern=TRUE
1776 context=[!_FILE_EVENT_/dev/logpipe]
1777 will pass to the following rules only those lines that were read from
1779 /dev/logpipe.
1780
1782 The shellcmd, spawn, pipe, and report actions involve the creation of a
1783 child process. The communication between SEC and its child processes
1784 takes place through pipes (created with Perl pipe opens like open(FH,
1785 "| mycommand") or pipe(2) system call). Note that the running time of
1786 children is not limited in any way, so long-running processes can be
1787 started from SEC. For instance, one could start a SEC agent with the
1788 spawn action that runs forever and provides SEC with additional input
1789 events. However, note that SEC sends the SIGTERM signal to all its
1790 children before termination. If some special exit procedures need to
1791 be carried out in the child process (or the child wishes to ignore
1792 SIGTERM), then the child must install a handler for the SIGTERM signal.
1793 Note that if a rule definition includes two shellcmd actions (or other
1795 actions that call external scripts or programs), the order that these
1796 scripts or programs are executed is not determined. For instance, with
1797 the following action definition
1798 action=shellcmd cmd1; shellcmd cmd2
1800 cmd2 could well terminate before cmd1, or cmd2 could well start before
1802 cmd1 (e.g., when cmd1 is a complex command line and cmd2 is relatively
1803 simple, it takes more time from the shell to process and start cmd1
1804 than cmd2).
1805
1807 There are two kinds of variables that can be used in SEC rule defini‐
1808 tions - $<number> and %<number> variables that are set during pattern
1809 matching, and %<alnum_name> variables (like %s, %t, and %u) that have
1810 been designed for use in action lists. All $<number> and %<number>
1811 variables will be substituted with their values immediately after input
1812 line(s) have matched the rule, even when they are part of the action
1813 list definition and this action list is going to be executed at a later
1814 time. %<alnum_name> variables, in turn, will be substituted with their
1815 values right before the action list is actually executed. If a vari‐
1816 able does not have a value (e.g., $4 when the pattern returned just two
1817 values), it will be left intact, i.e., it is not replaced with an empty
1818 string. Also, the values are substituted as strings, therefore substi‐
1819 tuting values of other types (e.g., references) will not work, unless
1820 explicitly noted otherwise (e.g., the function reference in the call
1821 action).
1822 In order to mask the variables, an extra $ or % must be prepended to
1824 them, e.g., $$1 yields $1, and not a dollar sign followed by the first
1825 value returned by the pattern. Also, all occurrences of $$ will be con‐
1826 verted to $ when $<number> variables are substituted, and all occur‐
1827 rences of %% will be converted to % when %<number> or %<alnum_name>
1828 variables are substituted, so that one could use $ or % together with
1829 variable names (e.g., $$$1 will yield a dollar sign that is followed by
1830 the first value returned by the pattern).
1831 Please note the following caveat for Pair and PairWithWindow rules when
1833 the second pattern shadows the $<number> variables of the first pattern
1834 - since both %<number> and %<alnum_name> variables may be used in the
1835 second action list and %<number> variables are substituted first (at
1836 the moment when the first pattern matches input line(s) and the event
1837 correlation operation is started), all occurrences of %% in the second
1838 action list have already been replaced with a single percent sign by
1839 the time when %<alnum_name> variables are finally substituted. (E.g.,
1840 in order to express %%t in the second action list, one must actually
1841 write it as %%%%t or %%%t, since after %% to % conversion they both
1842 yield %%t.)
1843 SEC allows the user to define patterns, context expressions, and
1845 actions which involve calls to the Perl eval() function. In addition to
1846 explicitly using %<alnum_name> variables that are global across the
1847 rules, the user can implicitly employ Perl variables created with
1848 eval() for the same purpose. E.g., when SEC has executed the following
1849 action
1850 action=eval %a ($b = 1)
1852 the variable $b and its value will become visible in the following con‐
1854 text expression
1855 context= =(++$b > 10)
1857 (with that expression one can implement event counting implicitly). In
1859 order to avoid possible clashes with the variables inside the SEC code
1860 itself, all calls for eval() are made in the main::SEC namespace (i.e.,
1861 inside the special package main::SEC). This still leaves the user with
1862 an opportunity to set the variables within the SEC code (e.g., by using
1863 the main:: prefix), and thus to alter the behavior of SEC, but this is
1864 only recommended for advanced users who have studied the code thor‐
1865 oughly and know what they are doing.
1866
1868 Example 1
1869 Consider the following rules:
1870 type=single
1872 continue=takenext
1873 ptype=regexp
1874 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session opened
1875 desc=ftp session opened for ristov2 pid $1
1876 action=create ftp_$1
1877 type=single
1879 continue=takenext
1880 ptype=regexp
1881 pattern=ftpd\[(\d+)\]:
1882 context=ftp_$1
1883 desc=ftp session event for ristov2 pid $1
1884 action=add ftp_$1 $0; set ftp_$1 1800 \
1885 (report ftp_$1 /bin/mail root@localhost)
1886 type=single
1888 ptype=regexp
1889 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session closed
1890 desc=ftp session closed for ristov2 pid $1
1891 action=report ftp_$1 /bin/mail root@localhost; \
1892 delete ftp_$1
1893 The first rule creates the context with the name ftp_<pid> when someone
1895 connects from host ristov2 with ftp. The second rule adds all logfile
1896 lines that are associated with the session <pid> to the event store of
1897 the context ftp_<pid> (before adding a line, the rule checks if the
1898 context exists). After adding a line, the rule extends context's life‐
1899 time for 30 minutes and sets the action list that will be executed when
1900 the context expires. The third rule mails collected logfile lines to
1901 root@localhost when the session <pid> is closed. Collected lines will
1902 also be mailed when the session <pid> has been inactive for 30 minutes
1903 (no logfile lines observed for that session).
1904 Note that the logfile line that has matched the first rule will be
1906 passed to the second rule and will become the first line in the event
1907 store (the first rule has the continue parameter set to TakeNext). The
1908 second rule has also its continue parameter set to TakeNext, since oth‐
1909 erwise no logfile lines would reach the third rule.
1910 Example 2
1912 Suppose there is a backup job in your system that runs at 2AM every
1913 night and logs "BACKUP READY" message when it has completed its work.
1914 You want to send an SNMP trap if there is no message in the log by
1915 2:15AM.
1916 type=Calendar
1918 time=59 1 * * *
1919 desc=WAITING FOR BACKUP
1920 action=event %s
1921 type=PairWithWindow
1923 ptype=SubStr
1924 pattern=WAITING FOR BACKUP
1925 desc=Backup not ready!
1926 action=shellcmd sendtrap.sh "%s"
1927 ptype2=SubStr
1928 pattern2=BACKUP READY
1929 desc2=Backup ready
1930 action2=none
1931 window=960
1932 The first rule generates "WAITING FOR BACKUP" event every night at
1934 1:59AM. This event is matched by the second rule, which starts a cor‐
1935 relation operation that will wait for "BACKUP READY" event for the next
1936 16 minutes. If the event arrives on time, no action is executed, oth‐
1937 erwise
1938 sendtrap.sh "Backup not ready!"
1940 is called.
1942 Example 3
1944 Consider the following rules:
1945 type=SingleWithScript
1947 ptype=RegExp
1948 pattern=node (\S+) interface (\S+) down
1949 script=not_resp.sh $2
1950 desc=NODE $1 IF $2 DOWN
1951 action=event %s
1952 type=Pair
1954 ptype=RegExp
1955 pattern=NODE (\S+) IF (\S+) DOWN
1956 desc=Interface $2 is down at node $1
1957 action=shellcmd notify.sh "%s"
1958 ptype2=SubStr
1959 pattern2=node $1 interface $2 up
1960 desc2=Interface $2 is up at node $1
1961 action2=shellcmd notify.sh "%s"
1962 window=86400
1963 If "node <node> interface <interface> down" event is observed, the
1965 interface is checked with the not_resp.sh script. If the interface is
1966 found to be down (not_resp.sh returns 0 as its exit code), event "NODE
1967 <node> IF <interface> DOWN" is generated which will be matched by the
1968 second rule. The second rule starts a correlation operation that calls
1969 notify.sh "Interface <interface> is down at node <node>"
1971 and then waits for the "node <node> interface <interface> up" event for
1973 the next 24 hours. When that event is observed, the correlation opera‐
1974 tion calls
1975 notify.sh "Interface <interface> is up at node <node>"
1977 and terminates.
1979 Example 4
1981 Suppose you have a disk box that logs following error messages:
1982 Description of Error:
1984 Disk drive (CRU: A1) has failed and can no longer be accessed. (SP
1986 Event Code 0xA07)
1987 Probable Cause / Recommended Action:
1989 Replace the disk module (CRU: A1).
1991 You would like to receive an e-mail message if something happens to the
1993 disk box. You would like to use different e-mail address at night-time
1994 and also receive a report of all night events. The problem here is that
1995 useful information is scattered over 7 lines and needs to be consoli‐
1996 dated into a single event. Consider the following rules for accomplish‐
1997 ing this task:
1998 type=Calendar
2000 time=0 22 * * *
2001 desc=night
2002 action=create %s 36000 \
2003 (report %s /bin/mail root@localhost)
2004 type=Single
2006 ptype=RegExp7
2007 pattern=Description of Error:\n.*\n(.+)\n.*\n.*\n.*\n(.+)
2008 context=night
2009 desc=Error=$1 Recmnd=$2
2010 action=shellcmd nightalarm.sh "%s"; add night %s
2011 type=Single
2013 ptype=RegExp7
2014 pattern=Description of Error:\n.*\n(.+)\n.*\n.*\n.*\n(.+)
2015 desc=Error=$1 Recmnd=$2
2016 action=shellcmd alarm.sh "%s"
2017 The first rule creates the context night with the lifetime of 10 hours
2019 every day at 10PM. The second rule specifies that the script nighta‐
2020 larm.sh must be used for sending alert messages at nights, otherwise
2021 the script alarm.sh should be used. Every night-time event is added to
2022 the context night, and collected events will be mailed to root@local‐
2023 host at 8AM.
2024 Example 5
2026 This section presents an example rulebase for managing Cisco devices.
2027 It is assumed that the managed devices have syslog(3)-style logging
2028 enabled, and that all syslog messages are sent to a central host and
2029 written to logfile(s) that are monitored by SEC.
2030 # Set up contexts NIGHT and WEEKEND for nights
2032 # and weekends. The context NIGHT has a lifetime
2033 # of 8 hours and the context WEEKEND 2 days
2034 type=Calendar
2036 time=0 23 * * *
2037 desc=NIGHT
2038 action=create %s 28800
2039 type=Calendar
2041 time=0 0 * * 6
2042 desc=WEEKEND
2043 action=create %s 172800
2044 # If a router does not come up within 5 minutes
2046 # after it was rebooted, generate event
2047 # "<router> REBOOT FAILURE". The next rule matches
2048 # this event, checks the router with ping and sends
2049 # a notification if there is no response.
2050 type=PairWithWindow
2052 ptype=RegExp
2053 pattern=(\S+) \d+: %SYS-5-RELOAD
2054 desc=$1 REBOOT FAILURE
2055 action=event %s
2056 ptype2=RegExp
2057 pattern2=($1) \d+: %SYS-5-RESTART
2058 desc2=$1 successful reboot
2059 action2=logonly
2060 window=300
2061 type=SingleWithScript
2063 ptype=RegExp
2064 pattern=(\S+) REBOOT FAILURE
2065 script=not_responding.sh $1
2066 desc=$1 did not come up after reboot
2067 action=shellcmd notify.sh "%s"
2068 # Send a notification if CPU load of a router is too
2070 # high (two CPUHOG messages are received within 5
2071 # minutes); send another notification if the load is
2072 # normal again (no CPUHOG messages within last 15
2073 # minutes). Rule is not applied at night or weekend.
2074 type=SingleWith2Thresholds
2076 ptype=RegExp
2077 pattern=(\S+) \d+: %SYS-3-CPUHOG
2078 context=!(NIGHT || WEEKEND)
2079 desc=$1 CPU overload
2080 action=shellcmd notify.sh "%s"
2081 window=300
2082 thresh=2
2083 desc2=$1 CPU load normal
2084 action2=shellcmd notify.sh "%s"
2085 window2=900
2086 thresh2=0
2087 # If a router interface is in down state for less
2089 # than 15 seconds, generate event
2090 # "<router> INTERFACE <interface> SHORT OUTAGE";
2091 # otherwise generate event
2092 # "<router> INTERFACE <interface> DOWN".
2093 type=PairWithWindow
2095 ptype=RegExp
2096 pattern=(\S+) \d+: %LINK-3-UPDOWN: Interface (.+), changed state to
2097 down
2098 desc=$1 INTERFACE $2 DOWN
2099 action=event %s
2100 ptype2=RegExp
2101 pattern2=($1) \d+: %LINK-3-UPDOWN: Interface ($2), changed state to up
2102 desc2=$1 INTERFACE $2 SHORT OUTAGE
2103 action2=event %s
2104 window=15
2105 # If "<router> INTERFACE <interface> DOWN" event is
2107 # received from the previous rule, send a notification and
2108 # wait for "interface up" event for the next 24 hours
2109 type=Pair
2111 ptype=RegExp
2112 pattern=(\S+) INTERFACE (\S+) DOWN
2113 desc=$1 interface $2 is down
2114 action=shellcmd notify.sh "%s"
2115 ptype2=RegExp
2116 pattern2=($1) \d+: %LINK-3-UPDOWN: Interface ($2), changed state to up
2117 desc2=$1 interface $2 is up
2118 action2=shellcmd notify.sh "%s"
2119 window=86400
2120 # If ten "short outage" events have been observed
2122 # in the window of 6 hours, send a notification
2123 type=SingleWithThreshold
2125 ptype=RegExp
2126 pattern=(\S+) INTERFACE (\S+) SHORT OUTAGE
2127 desc=Interface $2 at node $1 is unstable
2128 action=shellcmd notify.sh "%s"
2129 window=21600
2130 thresh=10
2131
2133 If the SECRC environment variable is set, SEC expects it to contain the
2134 name of its resource file. Resource file lines which are empty or which
2135 begin with # (whitespace may precede #) are ignored; other lines must
2136 contain SEC command line options, with each option on a separate line
2137 and the equal sign (=) as a separator between the option name and the
2138 option value. When SEC reads the resource file, each non-empty and
2139 non-comment line is considered a single option and is pushed into the
2140 @ARGV array as a single element. Note that although SEC re-reads its
2141 resource file at the reception of the SIGHUP or SIGABRT signal, adding
2142 an option that specifies a certain startup procedure (e.g., -pid or
2143 -detach) will not produce the desired effect at runtime.
2144
2146 SIGHUP SEC will reopen its log and input files, reload its configura‐
2147 tion, and reset internal lists that contain correlation informa‐
2148 tion (i.e., all active event correlation operations will be can‐
2149 celled, all contexts will be deleted, and all user-defined vari‐
2150 ables will lose their values). SEC will also send the SIGTERM
2151 signal to its child processes.
2152 SIGABRT
2154 SEC will reopen its log and input files, and load its configura‐
2155 tion from rule files which have been modified (file modification
2156 time returned by stat(2) has changed) or created after the pre‐
2157 vious configuration load. SEC will also cancel event correla‐
2158 tion operations started from rule files that have been modified
2159 or removed after the previous configuration load. Other opera‐
2160 tions and other event correlation entities (contexts, variables,
2161 child processes, etc.) will remain intact. Note that on some
2162 systems SIGIOT is used in place of SIGABRT.
2163 SIGUSR1
2165 some information about the current state of SEC (content of
2166 internal lists, rule usage statistics, etc.) will be written to
2167 the SEC dumpfile.
2168 SIGUSR2
2170 SEC will reopen its logfile (useful for logfile rotation).
2171 SIGINT SEC will increase its logging level by one; if the current level
2173 is 6, the level will be set back to 1. Please note this feature
2174 is available only if SEC standard input is not connected to a
2175 terminal (e.g., in daemon mode).
2176 SIGTERM
2178 SEC will terminate gracefully (all SEC child processes will
2179 receive SIGTERM).
2180
2182 Risto Vaarandi (ristov at users d0t s0urcef0rge d0t net)
2183
2185 crontab(1), date(1), fork(2), logsurfer(1), perl(1), perlre(1),
2186 pipe(2), snmpnotify(1), snmptrap(1), stat(2), syslog(3), time(2)
2187SEC 2.5.3 December 2009 sec.pl(1)