1sec(1) General Commands Manual sec(1)
2
6 sec - simple event correlator
7
9 sec [--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 [--socket-timeout=<socket timeout>]
17 [--blocksize=<io block size>]
18 [--bufsize=<input buffer size>]
19 [--evstoresize=<event store size>]
20 [--cleantime=<clean time>]
21 [--log=<logfile>]
22 [--syslog=<facility>]
23 [--debug=<debuglevel>]
24 [--pid=<pidfile>]
25 [--dump=<dumpfile>]
26 [--user=<username>]
27 [--group=<groupname> ...]
28 [--umask=<mode>]
29 [--dumpfts | --nodumpfts]
30 [--dumpfjson | --nodumpfjson]
31 [--quoting | --noquoting]
32 [--tail | --notail]
33 [--fromstart | --nofromstart]
34 [--detach | --nodetach]
35 [--jointbuf | --nojointbuf]
36 [--keepopen | --nokeepopen]
37 [--rwfifo | --norwfifo]
38 [--childterm | --nochildterm]
39 [--intevents | --nointevents]
40 [--intcontexts | --nointcontexts]
41 [--testonly | --notestonly]
42 [--help] [-?]
43 [--version]
44
46 SEC is an event correlation tool for advanced event processing which
47 can be harnessed for event log monitoring, for network and security
48 management, for fraud detection, and for any other task which involves
49 event correlation. Event correlation is a procedure where a stream of
50 events is processed, in order to detect (and act on) certain event
51 groups that occur within predefined time windows. Unlike many other
52 event correlation products which are heavyweight solutions, SEC is a
53 lightweight and platform-independent event correlator which runs as a
54 single process. The user can start it as a daemon, employ it in shell
55 pipelines, execute it interactively in a terminal, run many SEC pro‐
56 cesses simultaneously for different tasks, and use it in a wide variety
57 of other ways.
58 SEC reads lines from files, named pipes, or standard input, matches the
60 lines with patterns (regular expressions, Perl subroutines, etc.) for
61 recognizing input events, and correlates events according to the rules
62 in its configuration file(s). Rules are matched against input in the
63 order they are given in the configuration file. If there are two or
64 more configuration files, rule sequence from every file is matched
65 against input (unless explicitly specified otherwise). SEC can produce
66 output by executing external programs (e.g., snmptrap(1) or mail(1)),
67 by writing to files, by sending data to TCP and UDP based servers, by
68 calling precompiled Perl subroutines, etc.
69 SEC can be run in various ways. For example, the following command line
71 starts it as a daemon, in order to monitor events appended to the
72 /var/log/messages syslog file with rules from /etc/sec/syslog.rules:
73 /usr/bin/sec --detach --conf=/etc/sec/syslog.rules \
75 --input=/var/log/messages
76 Each time /var/log/messages is rotated, a new instance of /var/log/mes‐
78 sages is opened and processed from the beginning. The following command
79 line runs SEC in a shell pipeline, configuring it to process lines from
80 standard input, and to exit when the /usr/bin/nc tool closes its stan‐
81 dard output and exits:
82 /usr/bin/nc -l 8080 | /usr/bin/sec --notail --input=- \
84 --conf=/etc/sec/my.conf
85 Some SEC rules start event correlation operations, while other rules
87 react immediately to input events or system clock. For example, suppose
88 that SEC has been started with the following command line
89 /usr/bin/sec --conf=/etc/sec/sshd.rules --input=/var/log/secure
91 in order to monitor the /var/log/secure syslog file for sshd events.
93 Also, suppose that the /etc/sec/sshd.rules configuration file contains
94 the following rule for correlating SSH failed login syslog events:
95 type=SingleWithThreshold
97 ptype=RegExp
98 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
99 desc=Three SSH login failures within 1m for user $1
100 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost
101 window=60
102 thresh=3
103 The pattern field of the rule defines the pattern for recognizing input
105 events, while the ptype field defines its type (regular expression).
106 Suppose that user risto fails to log in over SSH and the following mes‐
107 sage is logged to /var/log/secure:
108 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
110 10.12.2.5 port 41063 ssh2
111 This input message will match the regular expression pattern of the
113 above rule, and the match variable $1 will be set to the string risto
114 (see perlre(1) for details). After a match, SEC will evaluate the
115 operation description string given with the desc field. This is done by
116 substituting $1 with its current value which yields Three SSH login
117 failures within 1m for user risto. SEC will then check if there
118 already exists an event correlation operation identified with this
119 string and triggered by the same rule. If the operation is not found,
120 SEC will create a new operation for the user name risto, and the occur‐
121 rence time of the input event will be recorded into the operation.
122 Note that for event occurrence time SEC always uses the current time as
123 returned by the time(2) system call, *not* the timestamp extracted from
124 the event. Suppose that after 25 seconds, a similar SSH login failure
125 event for the same user name is observed. In this case, a running oper‐
126 ation will be found for the operation description string Three SSH
127 login failures within 1m for user risto, and the occurrence time of the
128 second event is recorded into the operation. If after 30 seconds a
129 third event for the user name risto is observed, the operation has pro‐
130 cessed 3 events within 55 seconds. Since the threshold condition "3
131 events within 60 seconds" (as defined by the thresh and window fields)
132 is now satisfied, SEC will execute the action defined with the action
133 field -- it will fork a command
134 /bin/mail -s 'SSH login alert' root@localhost
136 with a pipe connected to its standard input. Then, SEC writes the oper‐
138 ation description string Three SSH login failures within 1m for user
139 risto (held by the %s special variable) to the standard input of the
140 command through the pipe. In other words, an e-mail warning is sent to
141 the local root-user. Finally, since there are 5 seconds left until the
142 end of the event correlation window, the operation will consume the
143 following SSH login failure events for user risto without any further
144 action, and finish after 5 seconds.
145 The above example illustrates that the desc field of a rule defines the
147 scope of event correlation and influences the number of operations cre‐
148 ated by the rule. For example, if we set the desc field to Three SSH
149 login failures within 1m, the root-user would be also alerted on 3 SSH
150 login failure events for *different* users within 1 minute. In order
151 to avoid clashes between operations started by different rules, opera‐
152 tion ID contains not only the value set by the desc field, but also the
153 rule file name and the rule number inside the file. For example, if
154 the rule file /etc/sec/sshd.rules contains one rule
155 type=SingleWithThreshold
157 ptype=RegExp
158 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
159 desc=Three SSH login failures within 1m for user $1
160 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost
161 window=60
162 thresh=3
163 and the event
165 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
167 10.12.2.5 port 41063 ssh2
168 is the first matching event for the above rule, this event will trigger
170 a new event correlation operation with the ID
171 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
173 risto
174 (0 is the number assigned to the first rule in the file, see EVENT COR‐
176 RELATION OPERATIONS section for more information).
177 The following simple example demonstrates that event correlation
179 schemes can be defined by combining several rules. In this example, two
180 rules harness contexts and synthetic events for achieving their goal:
181 type=SingleWithThreshold
183 ptype=RegExp
184 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
185 desc=Three SSH login failures within 1m for user $1
186 action=event 3_SSH_LOGIN_FAILURES_FOR_$1
187 window=60
188 thresh=3
189 type=EventGroup
191 ptype=RegExp
192 pattern=3_SSH_LOGIN_FAILURES_FOR_(\S+)
193 context=!USER_$1_COUNTED && !COUNTING_OFF
194 count=create USER_$1_COUNTED 60
195 desc=Repeated SSH login failures for 30 distinct users within 1m
196 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost; \
197 create COUNTING_OFF 3600
198 window=60
199 thresh=30
200 The first rule looks almost identical to the rule from the previous
202 example, but its action field is different -- after three SSH login
203 failures have been observed for the same user name within one minute by
204 an event correlation operation, the operation will emit the synthetic
205 event 3_SSH_LOGIN_FAILURES_FOR_<username>. Although synthetic events
206 are created by SEC, they are treated like regular events received from
207 input sources and are matched against rules. The regular expression
208 pattern of the second rule will match the 3_SSH_LOGIN_FAIL‐
209 URES_FOR_<username> event and start a new event correlation operation
210 if no such events have been previously seen. Also, each time a syn‐
211 thetic event for some user name has matched the rule, a context with
212 the lifetime of 1 minute for that user name is created (see the count
213 field). Note that this prevents further matches for the same user
214 name, since a synthetic event for <username> can match the rule only if
215 the context USER_<username>_COUNTED *does not* exist (as requested by
216 the boolean expression in the context field; see CONTEXTS AND CONTEXT
217 EXPRESSIONS section for more information). The operation started by
218 the rule sends an e-mail warning to the local root-user if 30 synthetic
219 events have been observed within 1 minute (see the thresh and window
220 fields). Note that due to the use of the USER_<username>_COUNTED con‐
221 texts, all synthetic events concern different user names. After sending
222 an e-mail warning, the operation will also create the context COUNT‐
223 ING_OFF with the lifetime of 1 hour, and will continue to run until the
224 1 minute event correlation window expires. After the operation has fin‐
225 ished, the presence of the COUNTING_OFF context will keep the second
226 rule disabled (as requested by the boolean expression in the context
227 field). Therefore, at most one e-mail warning per 1 hour is issued by
228 above rules.
229 The above examples have presented the event correlation capabilities of
231 SEC in a very brief fashion. The following sections will provide an
232 in-depth discussion of SEC features.
233
235 --conf=<file_pattern>
236 expand <file_pattern> to filenames (with the Perl glob() func‐
237 tion) and read event correlation rules from every file. Multiple
238 --conf options can be specified at command line. Each time SEC
239 receives a signal that forces a configuration reload, <file_pat‐
240 tern> is re-evaluated. See also INPUT PROCESSING AND TIMING sec‐
241 tion for a discussion on rule processing order for multiple con‐
242 figuration files.
243 --input=<file_pattern>[=<context>]
245 expand <file_pattern> to filenames (with the Perl glob() func‐
246 tion) and use the files as input sources. An input file can be a
247 regular file, named pipe, or standard input if - was specified.
248 Multiple --input options can be specified at command line. Each
249 time SEC receives the SIGHUP or SIGABRT signal, <file_pattern>
250 is re-evaluated. If SEC experiences a system error when reading
251 from an input file, it will close the file (use the
252 --reopen-timeout option for reopening the file). If <context> is
253 given, SEC will set up the context <context> each time it reads
254 a line from input files that correspond to <file_pattern>. This
255 will help the user to write rules that match data from particu‐
256 lar input source(s) only. When there is an --input option with
257 <context> specified, it will automatically enable the --intcon‐
258 texts option. See INTERNAL EVENTS AND CONTEXTS section for more
259 information.
260 --input-timeout=<input_timeout>, --timeout-script=<timeout_script>
262 if SEC has not observed new data in an input file during
263 <input_timeout> seconds (or the file was closed <input_timeout>
264 seconds ago), <timeout_script> will be executed with command
265 line parameters 1 and <the name of the input file>. If fresh
266 data become available again, <timeout_script> will be executed
267 with command line parameters 0 and <the name of the input file>.
268 Setting <input_timeout> to 0 disables this behavior (this is
269 also the default). Note that --input_timeout and --time‐
270 out_script options can be used as synonyms for --input-timeout
271 and --timeout-script, respectively.
272 --reopen-timeout=<reopen_timeout>
274 if an input file is in the closed state (e.g., SEC fails to open
275 the file at startup, because it has not been created yet), SEC
276 will attempt to reopen the file after every <reopen_timeout>
277 seconds until open succeeds. Setting <reopen_timeout> to 0 dis‐
278 ables this behavior (this is also the default). This option has
279 no meaning when the --notail option is also specified. Note
280 that --reopen_timeout is a synonym for --reopen-timeout.
281 --check-timeout=<check_timeout>
283 if SEC has not observed new data in an input file, the file will
284 not be polled (both for status and data) during the next
285 <check_timeout> seconds. Setting <check_timeout> to 0 disables
286 this behavior (this is also the default). Note that
287 --check_timeout is a synonym for --check-timeout.
288 --poll-timeout=<poll_timeout>
290 a real number that specifies how many seconds SEC will sleep
291 when no new data were read from input files. Default is 0.1 sec‐
292 onds. Note that --poll_timeout is a synonym for --poll-timeout.
293 --socket-timeout=<socket_timeout>
295 if a network connection to a remote peer can't be established
296 within <socket_timeout> seconds, give up. Default is 60 seconds.
297 Note that --socket_timeout is a synonym for --socket-timeout.
298 --blocksize=<io_block_size>
300 the number of bytes SEC will attempt to read at once from an
301 input file. Default is 8192 bytes (i.e., read from input files
302 by 8KB blocks).
303 --bufsize=<input_buffer_size>
305 set all input buffers to hold <input_buffer_size> lines. The
306 content of input buffers will be compared with patterns that are
307 part of rule definitions (i.e., no more than <input_buffer_size>
308 lines can be matched by a pattern at a time). If <input_buf‐
309 fer_size> is set to 0, SEC will determine the proper value for
310 <input_buffer_size> by checking event matching patterns of all
311 SEC rules. Default is 0 (i.e., determine the size of input buf‐
312 fers automatically).
313 --evstoresize=<event_store_size>
315 set an upper limit to the number of events in context event
316 stores. Default is 0 which sets no limit.
317 --cleantime=<clean_time>
319 time interval in seconds that specifies how often internal event
320 correlation and context lists are processed, in order to accom‐
321 plish time-related tasks and to remove obsolete elements. See
322 INPUT PROCESSING AND TIMING section for more information.
323 Default is 1 second.
324 --log=<logfile>
326 use <logfile> for logging SEC activities. Note that if the SEC
327 standard error is connected to a terminal, messages will also be
328 logged there, in order to facilitate debugging.
329 --syslog=<facility>
331 use syslog for logging SEC activities. All messages will be
332 logged with the facility <facility>, e.g., local0 (see syslog(3)
333 for possible facility values). Warning: be careful with using
334 this option if SEC is employed for monitoring syslog log files,
335 because message loops might occur.
336 --debug=<debuglevel>
338 set logging verbosity for SEC. Setting debuglevel to <debu‐
339 glevel> means that all messages of level <debuglevel> and lower
340 are logged (e.g., if <debuglevel> is 3, messages from levels 1-3
341 are logged). The following levels are recognized by SEC:
342 1 - critical messages (severe faults that cause SEC to termi‐
343 nate, e.g., a failed system call)
344 2 - error messages (faults that need attention, e.g., an incor‐
345 rect rule definition in a configuration file)
346 3 - warning messages (possible faults, e.g., a command forked
347 from SEC terminated with a non-zero exit code)
348 4 - notification messages (normal system level events and inter‐
349 rupts, e.g., the reception of a signal)
350 5 - informative messages (information about external programs
351 forked from SEC)
352 6 - debug messages (detailed information about all SEC activi‐
353 ties)
354 Default <debuglevel> is 6 (i.e., log everything). See SIGNALS
355 section for information on how to change <debuglevel> at run‐
356 time.
357 --pid=<pidfile>
359 SEC will store its process ID to <pidfile> at startup.
360 --dump=<dumpfile>
362 SEC will use <dumpfile> as its dump file for writing performance
363 and debug data. With the --dumpfts option, a timestamp suffix is
364 appended to the dump file name. With the --dumpfjson option,
365 dump file is produced in JSON format. See SIGNALS section for
366 more information. Default is /tmp/sec.dump.
367 --user=<username>, --group=<groupname>
369 if SEC is started with effective user ID 0, it will drop root
370 privileges by switching to user <username> and group <group‐
371 name>. The --group option can't be used without the --user
372 option. If the --user option is given without --group, primary
373 group of the user <username> is assumed for <groupname>. If
374 several groups are provided with multiple --group options, SEC
375 switches to the first group with other groups as supplementary
376 groups.
377 --umask=<mode>
379 set file mode creation mask to <mode> at SEC startup, where
380 <mode> is a value from the range 0..0777 (see also umask(2)).
381 Octal, decimal, hexadecimal, and binary values can be specified
382 for <mode> (e.g., octal mask 0027 can also be expressed as 23,
383 0x17, and 0b000010111).
384 --dumpfts, --nodumpfts
386 if the --dumpfts option is specified, a timestamp suffix (sec‐
387 onds since Epoch) is appended to the dump file name that
388 reflects the file creation time. Default is --nodumpfts.
389 --dumpfjson, --nodumpfjson
391 if the --dumpfjson option is specified, dump file is produced in
392 JSON format. Note that this option requires the presence of
393 Perl JSON module. Default is --nodumpfjson.
394 --quoting, --noquoting
396 if the --quoting option is specified, operation description
397 strings that are supplied to command lines of shellcmd, spawn,
398 and cspawn actions will be put inside single quotes. Each single
399 quote (') that strings originally contain will be masked. This
400 option prevents the shell from interpreting special symbols that
401 operation description strings might contain. Default is
402 --noquoting.
403 --tail, --notail
405 if the --notail option is specified, SEC will process all data
406 that are currently available in input files and exit after
407 reaching all EOFs. If all input is received from a pipe and the
408 --notail option is given, SEC terminates when the last writer
409 closes the pipe (EOF condition). Please note that with named
410 pipes --notail should be used with --norwfifo. With the --tail
411 option, SEC will jump to the end of input files and wait for new
412 lines to arrive. Each input file is tracked both by its name
413 and i-node, and input file rotations are handled seamlessly. If
414 the input file is recreated or truncated, SEC will reopen it and
415 process its content from the beginning. If the input file is
416 removed (i.e., there is just an i-node left without a name), SEC
417 will keep the i-node open and wait for the input file recre‐
418 ation. Default is --tail.
419 --fromstart, --nofromstart
421 these flags have no meaning when the --notail option is also
422 specified. When used in combination with --tail (or alone, since
423 --tail is enabled by default), --fromstart will force SEC to
424 read and process input files from the beginning to the end,
425 before the 'tail' mode is entered. Default is --nofromstart.
426 --detach, --nodetach
428 if the --detach option is specified, SEC will disassociate
429 itself from the controlling terminal and become a daemon at
430 startup (note that SEC will close its standard input, standard
431 output, and standard error, and change its working directory to
432 the root directory). Default is --nodetach.
433 --jointbuf, --nojointbuf
435 if the --jointbuf option is specified, SEC uses joint input buf‐
436 fer for all input sources (the size of the buffer is set with
437 the --bufsize option). The --nojointbuf option creates a sepa‐
438 rate input buffer for each input file, and a separate buffer for
439 all synthetic and internal events (the sizes of all buffers are
440 set with the --bufsize option). The --jointbuf option allows
441 multiline patterns to match lines from several input sources,
442 while the --nojointbuf pattern restricts the matching to lines
443 from one input source only. See INPUT PROCESSING AND TIMING
444 section for more information. If the size of input buffer(s) is
445 1 (either explicitly set with --bufsize=1 or automatically
446 determined from SEC rules), --jointbuf option is enabled, other‐
447 wise the default is --nojointbuf.
448 --keepopen, --nokeepopen
450 if the --keepopen option is specified, SEC will keep input files
451 open across soft restarts. When the SIGABRT signal is received,
452 SEC will not reopen input files which have been opened previ‐
453 ously, but will only open input files which are in the closed
454 state. The --nokeepopen option forces SEC to close and (re)open
455 all input files during soft restarts. Default is --keepopen.
456 --rwfifo, --norwfifo
458 if the --norwfifo option is specified, named pipe input files
459 are opened in read-only mode. In this mode, the named pipe has
460 to be reopened when the last writer closes the pipe, in order to
461 clear the EOF condition on the pipe. With the --rwfifo option,
462 named pipe input files are opened in read-write mode, although
463 SEC never writes to the pipes. In this mode, the pipe does not
464 need to be reopened when an external writer closes it, since
465 there is always at least one writer on the pipe and EOF will
466 never appear. Therefore, if the --notail option has been given,
467 --norwfifo should also be specified. Default is --rwfifo.
468 --childterm, --nochildterm
470 if the --childterm option is specified, SEC will send the
471 SIGTERM signal to all its child processes when it terminates or
472 goes through a full restart. Default is --childterm.
473 --intevents, --nointevents
475 SEC will generate internal events when it starts up, when it
476 receives certain signals, and when it terminates gracefully.
477 Specific rules can be written to match those internal events, in
478 order to accomplish special tasks at SEC startup, restart, and
479 shutdown. See INTERNAL EVENTS AND CONTEXTS section for more
480 information. Default is --nointevents.
481 --intcontexts, --nointcontexts
483 SEC will create an internal context when it reads a line from an
484 input file. This will help the user to write rules that match
485 data from particular input source only. See INTERNAL EVENTS AND
486 CONTEXTS section for more information. Default is --nointcon‐
487 texts.
488 --testonly, --notestonly
490 if the --testonly option is specified, SEC will exit immediately
491 after parsing the configuration file(s). If the configuration
492 file(s) contained no faulty rules, SEC will exit with 0, other‐
493 wise with 1. Default is --notestonly.
494 --help, -?
496 SEC will output usage information and exit.
497 --version
499 SEC will output version information and exit.
500 Note that options can be introduced both with the single dash (-) and
502 double dash (--), and both the equal sign (=) and whitespace can be
503 used for separating the option name from the option value. For example,
504 -conf=<file_pattern> and --conf <file_pattern> options are equivalent.
505
507 Each SEC configuration file consists of rule definitions which are sep‐
508 arated by empty lines, whitespace lines and/or comment lines. Each
509 rule definition consists of keyword=value fields, one keyword and value
510 per line. Values are case insensitive only where character case is not
511 important (like the values specifying rule types, e.g., 'Single' and
512 'single' are treated identically). The backslash character (\) may be
513 used at the end of a line to continue the current rule field in the
514 next line. Lines which begin with the number sign (#) are treated as
515 comments and ignored (whitespace characters may precede #). Any comment
516 line, empty line, whitespace line, or end of file will terminate the
517 preceding rule definition. For inserting comments into rule defini‐
518 tions, the rem keyword can be used. For example, the following lines
519 define two rules:
520 type=Single
522 rem=this rule matches any line which contains \
523 three consecutive A characters and writes the string \
524 "three A characters were observed" to standard output
525 ptype=SubStr
526 pattern=AAA
527 desc=Three A characters
528 action=write - three A characters were observed
529 # This comment line ends preceding rule definition.
530 # The following rule works like the previous rule,
531 # but looks for three consecutive B characters and
532 # writes the string "three B characters were observed"
533 # to standard output
534 type=Single
535 ptype=SubStr
536 pattern=BBB
537 desc=Three B characters
538 action=write - three B characters were observed
539 Apart from keywords that are part of rule definitions, label keywords
541 may appear anywhere in the configuration file. The value of each label
542 keyword will be treated as a label that can be referred to in rule def‐
543 initions as a point-of-continue. This allows for continuing event pro‐
544 cessing at a rule that follows the label, after the current rule has
545 matched and processed the event.
546 The points-of-continue are defined with continue* fields. Accepted val‐
548 ues for these fields are:
549 TakeNext
551 after an event has matched the rule, search for matching rules
552 in the configuration file will continue from the next rule.
553 GoTo <label>
555 after an event has matched the rule, search for matching rules
556 will continue from the location of <label> in the configuration
557 file (<label> must be defined with the label keyword anywhere in
558 the configuration file *after* the current rule definition).
559 DontCont (default value)
561 after an event has matched the rule, search for matching rules
562 ends in the *current* configuration file.
563 EndMatch
565 after an event has matched the rule, search for matching rules
566 ends for *all* configuration files.
567 SEC rules from the same configuration file are matched against input in
569 the order they have been given in the file. For example, consider a
570 configuration file which contains the following rule sequence:
571 type=Single
573 ptype=SubStr
574 pattern=AAA
575 rem=after this rule has matched, continue from last rule
576 continue=GoTo lastRule
577 desc=Three A characters
578 action=write - three A characters were observed
579 type=Single
581 ptype=SubStr
582 pattern=BBB
583 rem=after this rule has matched, don't consider following rules, \
584 since 'continue' defaults to 'DontCont'
585 desc=Three B characters
586 action=write - three B characters were observed
587 type=Single
589 ptype=SubStr
590 pattern=CCC
591 rem=after this rule has matched, continue from next rule
592 continue=TakeNext
593 desc=Three C characters
594 action=write - three C characters were observed
595 label=lastRule
597 type=Single
599 ptype=SubStr
600 pattern=DDD
601 desc=Three D characters
602 action=write - three D characters were observed
603 For the input line "AAABBBCCCDDD", this ruleset writes strings "three A
605 characters were observed" and "three D characters were observed" to
606 standard output. If the input line is "BBBCCCDDD", the string "three B
607 characters were observed" is written to standard output. For the input
608 line "CCCDDD", strings "three C characters were observed" and "three D
609 characters were observed" are sent to standard output, while the input
610 line "DDD" produces the output string "three D characters were
611 observed".
612 If there are two or more configuration files, rule sequence from every
614 file is matched against input (unless explicitly specified otherwise).
615 For example, suppose SEC is started with the command line
616 /usr/bin/sec --input=- \
618 --conf=/etc/sec/sec1.rules --conf=/etc/sec/sec2.rules
619 and the configuration file /etc/sec/sec1.rules has the following con‐
621 tent:
622 type=Single
624 ptype=SubStr
625 pattern=AAA
626 desc=Three A characters
627 action=write - three A characters were observed
628 type=Single
630 ptype=SubStr
631 pattern=BBB
632 continue=EndMatch
633 desc=Three B characters
634 action=write - three B characters were observed
635 Also, suppose the configuration file /etc/sec/sec2.rules has the fol‐
637 lowing content:
638 type=Single
640 ptype=SubStr
641 pattern=CCC
642 desc=Three C characters
643 action=write - three C characters were observed
644 If SEC receives the line "AAABBBCCC" from standard input, rules from
646 both configuration files are tried, and as a result, the strings "three
647 A characters were observed" and "three C characters were observed" are
648 written to standard output. Note that rules from /etc/sec/sec1.rules
649 are tried first against the input line, since the option
650 --conf=/etc/sec/sec1.rules is given before --conf=/etc/sec/sec2.rules
651 in the SEC command line (see also INPUT PROCESSING AND TIMING section
652 for a more detailed discussion). If SEC receives the line "BBBCCC"
653 from standard input, the second rule from /etc/sec/sec1.rules produces
654 a match, and the string "three B characters were observed" is written
655 to standard output. Since the rule contains continue=EndMatch state‐
656 ment, the search for matching rules will end for all configuration
657 files, and rules from /etc/sec/sec2.rules will not be not tried. With‐
658 out this statement, the search for matching rules would continue in
659 /etc/sec/sec2.rules, and the first rule would write the string "three C
660 characters were observed" to standard output.
661
663 Patterns and pattern types are defined with pattern* and ptype* rule
664 fields. Many pattern types define the number of lines N which the pat‐
665 tern matches (if N is omitted, 1 is assumed). If N is greater than 1,
666 the scope of matching is set with the --jointbuf and --nojointbuf
667 options. With --jointbuf, the pattern is used for matching N last
668 input lines taken from the joint input buffer (the lines can come from
669 different input sources). With --nojointbuf, the source of the last
670 input line is identified, and the pattern is matched with N last input
671 lines from the input buffer of the identified source.
672 SubStr[N]
674 pattern is a string that is searched in the last N input lines
675 L1, L2, ..., LN. If N is greater than 1, the input lines are
676 joined into a string "L1<NEWLINE>L2<NEWLINE>...<NEWLINE>LN", and
677 the pattern string will be searched from it. If the pattern
678 string is found in input line(s), the pattern matches. Back‐
679 slash sequences \t, \n, \r, \s, and \0 can be used in the pat‐
680 tern for denoting tabulation, newline, carriage return, space
681 character, and empty string, respectively, while \\ denotes
682 backslash itself. For example, consider the following pattern
683 definition:
684 ptype=substr
686 pattern=Backup done:\tsuccess
687 The pattern matches lines containing "Backup done:<TAB>success".
689 Note that since the SubStr[N] pattern type has been designed for
691 fast matching, it does not support match variables.
692 RegExp[N]
694 pattern is a Perl regular expression (see perlre(1) for more
695 information) for matching the last N input lines L1, L2, ...,
696 LN. If N is greater than 1, the input lines are joined into a
697 string "L1<NEWLINE>L2<NEWLINE>...<NEWLINE>LN", and the regular
698 expression is matched with this string. If the regular expres‐
699 sion matches, match variables will be set, and these match vari‐
700 ables can be used in other parts of the rule definition.
701 In addition to numbered match variables ($1, $2, etc.), SEC sup‐
703 ports named match variables $+{name} and the $0 variable. The $0
704 variable holds the entire string of last N input lines that the
705 regular expression has matched. Named match variables can be
706 created in newer versions of Perl regular expression language,
707 e.g., (?<myvar>AB|CD) sets $+{myvar} to AB or CD. Also, SEC cre‐
708 ates special named match variables $+{_inputsrc} and $+{_intcon‐
709 text}. The $+{_inputsrc} variable holds input file name(s) where
710 matching line(s) came from. The $+{_intcontext} variable holds
711 the name of current internal context (see INTERNAL EVENTS AND
712 CONTEXTS section for more information). If internal context has
713 not been set up for the current input source, the variable is
714 set to Perl undefined value.
715 For example, the following pattern matches the SSH "Connection
717 from" event, and sets $0 to the entire event line, both $1 and
718 $+{ip} to the IP address of the remote node, and $2 to the port
719 number at the remote node:
720 ptype=RegExp
722 pattern=sshd\[\d+\]: Connection from (?<ip>[\d.]+) port (\d+)
723 If the matching event comes from input file /var/log/messages
725 with internal context MSGS, the $+{_inputsrc} and $+{_intcon‐
726 text} variables are set to strings "/var/log/messages" and
727 "MSGS", respectively.
728 Also, SEC allows for match caching and for the creation of addi‐
730 tional named match variables through variable maps which are
731 defined with the varmap* fields. Variable map is a list of
732 name=number mappings separated by semicolons, where name is the
733 name for the named variable and number identifies a numbered
734 match variable that is set by the regular expression. Each name
735 must begin with a letter and consist of letters, digits and
736 underscores. After the regular expression has matched, named
737 variables specified by the map are created from corresponding
738 numbered variables. If the same named variable is set up both
739 from the regular expression and variable map, the map takes
740 precedence.
741 If name is not followed by the equal sign and number in the
743 varmap* field, it is regarded as a common name for all match
744 variables and their values from a successful match. This name
745 is used for caching a successful match by the pattern -- match
746 variables and their values are stored in the memory-based pat‐
747 tern match cache under name. Cached match results can be reused
748 by Cached and NCached patterns. Note that before processing each
749 new input line, previous content of the pattern match cache is
750 cleared. Also note that a successful pattern match is cached
751 even if the subsequent context expression evaluation yields
752 FALSE (see INPUT PROCESSING AND TIMING section for more informa‐
753 tion).
754 For example, consider the following pattern definition:
756 ptype=regexp
758 pattern=(?i)(\S+\.mydomain).*printer: toner\/ink low
759 varmap=printer_toner_or_ink_low; message=0; hostname=1
760 The pattern matches "printer: toner/ink low" messages in a case
762 insensitive manner from printers belonging to .mydomain. Note
763 that the printer hostname is assigned to $1 and $+{hostname},
764 while the whole message line is assigned to $0 and $+{message}.
765 If the message comes from file /var/log/test which does not have
766 an internal context defined, the $+{_inputsrc} variable is set
767 to string "/var/log/test", while $+{_intcontext} is set to Perl
768 undefined value. Also, these variables and their values are
769 stored to the pattern match cache under the name
770 "printer_toner_or_ink_low".
771 The following pattern definition produces a match if the last
773 two input lines are AAA and BBB:
774 ptype=regexp2
776 pattern=^AAA\nBBB$
777 varmap=aaa_bbb
778 Note that with the --nojointbuf option the pattern only matches
780 if the matching lines are coming from the *same* input file,
781 while the --jointbuf option lifts that restriction.
782 In the case of a match, $0 is set to "AAA<NEWLINE>BBB",
784 $+{_inputsrc} to file name(s) for matching lines, and $+{_int‐
785 context} to the name of current internal context. Also, these
786 variable-value pairs are cached under the name "aaa_bbb".
787 PerlFunc[N]
789 pattern is a Perl function for matching the last N input lines
790 L1, L2, ..., LN. The Perl function is compiled at SEC startup
791 with the Perl eval() function, and eval() must return a code
792 reference for the pattern to be valid (see also PERL INTEGRATION
793 section). The function is called in Perl list context, and with
794 the --jointbuf option, lines L1, L2, ..., LN and the names of
795 corresponding input files F1, F2, ..., FN are passed to the
796 function as parameters:
797 function(L1, L2, ..., LN, F1, F2, ..., FN)
799 Note that with the --nojointbuf option, the function is called
801 with a single file name parameter F, since lines L1, ..., LN are
802 coming from the same input file:
803 function(L1, L2, ..., LN, F)
805 Also note that if the input line is a synthetic event, the input
807 file name is Perl undefined value.
808 If the function returns several values or a single value that is
810 true in Perl boolean context, the pattern matches. If the func‐
811 tion returns no values or a single value that is false in Perl
812 boolean context (0, empty string or undefined value), the pat‐
813 tern does not match. If the pattern matches, return values will
814 be assigned to numbered match variables ($1, $2, etc.). Like
815 with RegExp patterns, the $0 variable is set to matching input
816 line(s), the $+{_inputsrc} variable is set to input file
817 name(s), the $+{_intcontext} variable is set to the name of cur‐
818 rent internal context, and named match variables can be created
819 from variable maps. For example, consider the following pattern
820 definition:
821 ptype=perlfunc2
823 pattern=sub { return ($_[0] cmp $_[1]); }
824 The pattern compares last two input lines in a stringwise manner
826 ($_[1] holds the last line and $_[0] the preceding one), and
827 matches if the lines are different. Note that the result of the
828 comparison is assigned to $1, while two matching lines are con‐
829 catenated (with the newline character between them) and assigned
830 to $0. If matching lines come from input file /var/log/mylog
831 with internal context TEST, the $+{_inputsrc} and $+{_intcon‐
832 text} variables are set to strings "/var/log/mylog" and "TEST",
833 respectively.
834 The following pattern produces a match for any line, and sets
836 $1, $2 and $3 variables to strings "abc", "def" and "ghi",
837 respectively (also, $0 is set to the whole input line,
838 $+{_inputsrc} to the input file name, and $+{_intcontext} to the
839 name of internal context associated with input file $+{_input‐
840 src}):
841 ptype=perlfunc
843 pattern=sub { return ("abc", "def", "ghi"); }
844 The following pattern definition produces a match if the input
846 line is not a synthetic event and contains either the string
847 "abc" or "def". The $0 variable is set to the matching line. If
848 matching line comes from /var/log/test without an internal con‐
849 text, $+{_intcontext} is set to Perl undefined value, while $1,
850 $+{file} and $+{_inputsrc} are set to string "/var/log/test":
851 ptype=perlfunc
853 pattern=sub { if (defined($_[1]) && $_[0] =~ /abc|def/) \
854 { return $_[1]; } return 0; }
855 varmap= file=1
856 Finally, if a function pattern returns a single value which is a
858 reference to a Perl hash, named match variables are created from
859 key-value pairs in the hash. For example, the following pattern
860 matches a line if it contains either the string "three" or
861 "four". Apart from setting $0, $+{_inputsrc} and $+{_intcon‐
862 text}, the pattern also creates match variables $+{three} and
863 $+{four}, and sets them to 3 and 4, respectively:
864 ptype=perlfunc
866 pattern=sub { my(%hash); \
867 if ($_[0] !~ /three|four/) { return 0; } \
868 $hash{"three"} = 3; $hash{"four"} = 4; return \%hash; }
869 Cached pattern is a name that is searched in the pattern match cache
871 (entries are stored into the cache with the varmap* fields). If
872 an entry with the given name is found in the cache, the pattern
873 matches, and match variables and values are retrieved from the
874 cache. For example, if the input line matches the following
875 pattern
876 ptype=perlfunc
878 pattern=sub { if (defined($_[1]) && $_[0] =~ /abc|def/) \
879 { return $_[1]; } return 0; }
880 varmap=abc_or_def_found; file=1
881 then the entry "abc_or_def_found" is created in the pattern
883 match cache. Therefore, the pattern
884 ptype=cached
886 pattern=abc_or_def_found
887 will also produce a match for this input line, and set the $0,
889 $1, $+{file}, $+{_inputsrc}, and $+{_intcontext} variables to
890 values from the previous match.
891 NSubStr[N]
893 like SubStr[N], except that the result of the match is negated.
894 Note that this pattern type does not support match variables.
895 NRegExp[N]
897 like RegExp[N], except that the result of the match is negated
898 and variable maps are not supported. Note that the only match
899 variables supported by this pattern type are $0, $+{_inputsrc},
900 and $+{_intcontext}.
901 NPerlFunc[N]
903 like PerlFunc[N], except that the result of the match is negated
904 and variable maps are not supported. Note that the only match
905 variables supported by this pattern type are $0, $+{_inputsrc},
906 and $+{_intcontext}.
907 NCached
909 like Cached, except that the result of the match is negated.
910 Note that this pattern type does not support match variables.
911 TValue pattern is a truth value, with TRUE and FALSE being legitimate
913 values. TRUE always matches an input line, while FALSE never
914 matches anything. Note that this pattern type does not support
915 match variables.
916 When match variables are substituted, each "$$" sequence is interpreted
918 as a literal dollar sign ($) which allows for masking match variables.
919 For example, the string "Received $$1" becomes "Received $1" after sub‐
920 stitution, while "Received $$$1" becomes "Received
921 $<value_of_1st_var>". In order to disambiguate numbered match vari‐
922 ables from the following text, variable number must be enclosed in
923 braces. For example, the string "Received ${1}0" becomes "Received
924 <value_of_1st_var>0" after substitution, while the string "Received
925 $10" would become "Received <value_of_10th_var>".
926 If the match variable was not set by the pattern, it is substituted
928 with an empty string (i.e., a zero-width string). Thus the string
929 "Received $10!" becomes "Received !" after substitution if the pattern
930 did not set $10. (Note that prior to SEC-2.6, unset variables were
931 *not* substituted.)
932 In the current version of SEC, names of $+{name} match variables must
934 comply with the following naming convention -- the first character can
935 be a letter or underscore, while remaining characters can be letters,
936 digits, underscores and exclamation marks (!). However, when setting
937 named match variables from a pattern, it is recommended to begin the
938 variable name with a letter, since names of special automatically cre‐
939 ated variables begin with an underscore (e.g., $+{_inputsrc}).
940 After the pattern has matched an event and match variables have been
942 set, it is also possible to refer to previously cached match variables
943 with the syntax $:{entryname:varname}, where entryname is the name of
944 the pattern match cache entry, and varname is the name of the variable
945 stored under the entry. For example, if the variable $+{ip} has been
946 previously cached under the entry "SSH", it can be referred as
947 $:{SSH:ip}. For the reasons of efficiency, the $:{entryname:varname}
948 syntax is not supported for fast pattern types which do not set match
949 variables (i.e., SubStr, NSubStr, NCached and TValue).
950 Note that since Pair and PairWithWindow rules have two patterns, match
952 variables of the first pattern are shadowed for some rule fields when
953 the second pattern matches and sets variables. In order to refer to
954 shadowed variables, their names must begin with % instead of $ (e.g.,
955 %1 refers to match variable $1 set by the first pattern). However, the
956 use of the %-prefix is only valid under the following circumstances --
957 *both* pattern types support match variables *and* in the given rule
958 field match variables from *both* patterns can be used.
959 The %-prefixed match variables are masked with the "%%" sequence (like
961 regular match variables with "$$"). Similarly, the braces can be used
962 for disambiguating the %-prefixed variables from the following text.
963 Finally, note that the second pattern of Pair and PairWithWindow rules
965 may contain match variables if the second pattern is of type SubStr,
966 NSubStr, Regexp, or NRegExp. The variables are substituted at runtime
967 with the values set by the first pattern. If the pattern is a regular
968 expression, all special characters inside substituted values are masked
969 with the Perl quotemeta() function and the final expression is checked
970 for correctness.
971
973 A SEC context is a memory based entity which has one or more names, a
974 lifetime, and an event store. Also, an action list can be set up for a
975 context which is executed immediately before the context expires.
976 For example, the action create MYCONTEXT 3600 (report MYCONTEXT
978 /bin/mail root@localhost) creates the context MYCONTEXT which has a
979 lifetime of 3600 seconds and empty event store. Also, immediately
980 before MYCONTEXT expires and is dropped from memory, the action report
981 MYCONTEXT /bin/mail root@localhost is executed which mails the event
982 store of MYCONTEXT to root@localhost.
983 Contexts can be used for event aggregation and reporting. Suppose the
985 following actions are executed in this order:
986 create MYCONTEXT
988 add MYCONTEXT This is a test
989 alias MYCONTEXT MYALIAS
990 add MYALIAS This is another test
991 report MYCONTEXT /bin/mail root@localhost
992 delete MYALIAS
993 The first action creates the context MYCONTEXT with infinite lifetime
995 and empty event store. The second action appends the string "This is a
996 test" to the event store of MYCONTEXT. The third action sets up an
997 alias name MYALIAS for the context (names MYCONTEXT and MYALIAS refer
998 to the same context data structure). The fourth action appends the
999 string "This is another test" to the event store of the context. The
1000 fifth action writes the lines
1001 This is a test
1003 This is another test
1004 to the standard input of the /bin/mail root@localhost command. The
1006 sixth action deletes the context data structure from memory and drops
1007 its names MYCONTEXT and MYALIAS.
1008 Since contexts are accessible from all rules and event correlation
1010 operations, they can be used for data sharing and joining several rules
1011 into one event correlation scheme. In order to check for the presence
1012 of contexts from rules, context expressions can be employed.
1013 Context expressions are boolean expressions that are defined with the
1015 context* rule fields. Context expressions can be used for restricting
1016 the matches produced by patterns, since if the expression evaluates
1017 FALSE, the rule will not match an input event.
1018 The context expression accepts context names, Perl miniprograms, Perl
1020 functions, and pattern match cache lookups as operands. These operands
1021 can be combined with the following operators:
1022 ! - logical NOT,
1023 && - short-circuit logical AND,
1024 || - short-circuit logical OR.
1025 In addition, parentheses can be used for grouping purposes.
1026 If the operand does not contain any special operators (such as -> or
1028 :>, see below), it is treated as a context name. Context name operands
1029 may contain match variables, but may not contain whitespace. If the
1030 context name refers to an existing context, the operand evaluates TRUE,
1031 otherwise it evaluates FALSE.
1032 For example, consider the following rule sequence:
1034 type=Single
1036 ptype=RegExp
1037 pattern=Test: (\d+)
1038 desc=test
1039 action=create CONT_$1
1040 type=Single
1042 ptype=RegExp
1043 pattern=Test2: (\d+) (\d+)
1044 context=CONT_$1 && CONT_$2
1045 desc=test
1046 action=write - Both $1 and $2 have been seen in the past
1047 If the following input lines appear in this order
1049 Test: 19
1051 Test: 261
1052 Test2: 19 787
1053 Test: 787
1054 Test2: 787 261
1055 the first input line matches the first rule which creates the context
1057 CONT_19, and similarly, the second input line triggers the creation of
1058 the context CONT_261. The third input line "Test2: 19 787" matches the
1059 regular expression
1060 Test2: (\d+) (\d+)
1062 but does not match the second rule, since the boolean expression
1064 CONT_19 && CONT_787
1066 evaluates FALSE (context CONT_19 exists, but context CONT_787 doesn't).
1068 The fourth input line matches the first rule which creates the context
1069 CONT_787. The fifth input line "Test2: 787 261" matches the second
1070 rule, since the boolean expression
1071 CONT_787 && CONT_261
1073 evaluates TRUE (both context CONT_787 and context CONT_261 exist), and
1075 therefore the string "Both 787 and 261 have been seen in the past" is
1076 written to standard output.
1077 If the context expression operand contains the arrow operator (->), the
1079 text following the arrow must be a valid Perl function definition that
1080 is compiled at SEC startup with the Perl eval() function. The eval()
1081 must return a code reference (see also PERL INTEGRATION section for
1082 more information). If any text precedes the arrow, it is treated as a
1083 list of parameters for the function. Parameters must be separated by
1084 whitespace and may contain match variables. In order to evaluate the
1085 context expression operand, the Perl function is called in the Perl
1086 scalar context. If the return value of the function is true in the Perl
1087 boolean context, the operand evaluates TRUE, otherwise it evaluates
1088 FALSE.
1089 For example, the following rule matches an SSH login failure event if
1091 the login attempt comes from a privileged port of the client host:
1092 type=Single
1094 ptype=RegExp
1095 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port (\d+) ssh2
1096 context=$2 -> ( sub { $_[0] < 1024 } )
1097 desc=SSH login failure for $1 priv port $2
1098 action=write - SSH login failure for user $1 from a privileged port $2
1099 When the following message from SSH daemon appears
1101 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
1103 10.12.2.5 port 41063 ssh2
1104 the regular expression of the rule matches this message, and the value
1106 of the $2 match variable (41063) is passed to the Perl function
1107 sub { $_[0] < 1024 }
1109 This function returns true if its input parameter is less than 1024 and
1111 false otherwise, and therefore the above message will not match the
1112 rule. However, the following message
1113 Dec 16 16:25:17 myserver sshd[13689]: Failed password for risto from
1115 10.12.2.5 port 1023 ssh2
1116 matches the rule, and the string "SSH login failure for user risto from
1118 a privileged port 1023" is written to standard output.
1119 As another example, the following context expression evaluates TRUE if
1121 the /var/log/messages file does not exist or was last modified more
1122 than 1 hour ago (note that the Perl function takes no parameters):
1123 context= -> ( sub { my(@stat) = stat("/var/log/messages"); \
1125 return (!scalar(@stat) || time() - $stat[9] > 3600); } )
1126 If the context expression operand contains the :> operator, the text
1128 that follows :> must be a valid Perl function definition that is com‐
1129 piled at SEC startup with the Perl eval() function. The eval() must
1130 return a code reference (see also PERL INTEGRATION section for more
1131 information). If any text precedes the :> operator, it is treated as a
1132 list of parameters for the function. Parameters must be separated by
1133 whitespace and may contain match variables. It is assumed that each
1134 parameter is a name of an entry in the pattern match cache. If an entry
1135 with the given name does not exist, Perl undefined value is passed to
1136 the function. If an entry with the given name exists, a reference to
1137 the entry is passed to the Perl function. Internally, each pattern
1138 match cache entry is implemented as a Perl hash which contains all
1139 match variables for the given entry. In the hash, each key-value pair
1140 represents some variable name and value, e.g., if cached match variable
1141 $+{ip} is holding 10.1.1.1, the hash contains the value 10.1.1.1 with
1142 the key ip. In order to evaluate the context expression operand, the
1143 Perl function is called in the Perl scalar context. If the return value
1144 of the function is true in the Perl boolean context, the operand evalu‐
1145 ates TRUE, otherwise it evaluates FALSE.
1146 For example, consider the following rule sequence:
1148 type=Single
1150 ptype=RegExp
1151 pattern=sshd\[\d+\]: (?<status>Accepted|Failed) .+ \
1152 for (?<invuser>invalid user )?(?<user>\S+) from (?<ip>[\d.]+) \
1153 port (?<port>\d+) ssh2
1154 varmap=SSH
1155 continue=TakeNext
1156 desc=parse SSH login events and pass them to following rules
1157 action=none
1158 type=Single
1160 ptype=Cached
1161 pattern=SSH
1162 context=SSH :> ( sub { $_[0]->{"status"} eq "Failed" && \
1163 $_[0]->{"port"} < 1024 && \
1164 defined($_[0]->{"invuser"}) } )
1165 desc=Probe of invalid user $+{user} from privileged port of $+{ip}
1166 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
1167 The first rule matches and parses SSH login messages, and stores pars‐
1169 ing results to the pattern match cache under the name SSH. The pattern
1170 of the second rule (defined with ptype=Cached and pattern=SSH) matches
1171 any input event for which the entry SSH has been previously created in
1172 the pattern match cache (in other words, the event has been recognized
1173 and parsed as an SSH login message). For each matching event, the sec‐
1174 ond rule passes the reference to the SSH cache entry to the Perl func‐
1175 tion
1176 sub { $_[0]->{"status"} eq "Failed" && \
1178 $_[0]->{"port"} < 1024 && \
1179 defined($_[0]->{"invuser"}) }
1180 The function checks the values of $+{status}, $+{port}, and $+{invuser}
1182 match variables under the SSH entry, and returns true if $+{status}
1183 equals to the string "Failed" (i.e., login attempt failed), the value
1184 of $+{port} is less than 1024, and $+{invuser} holds a defined value
1185 (i.e., user account does not exist). If the function (and thus context
1186 expression) evaluates TRUE, the rule sends a warning e-mail to
1187 root@localhost that a non-existing user account was probed from a priv‐
1188 ileged port of a client host.
1189 If the context expression operand begins with the varset keyword, the
1191 following string is treated as a name of an entry in the pattern match
1192 cache. The operand evaluates TRUE if the given entry exists, and FALSE
1193 otherwise.
1194 For example, the following context expression definition evaluates TRUE
1196 if the pattern match cache entry SSH exists and under this entry, the
1197 value of the match variable $+{user} equals to the string "risto":
1198 context=varset SSH && SSH :> ( sub { $_[0]->{"user"} eq "risto" } )
1200 If the context expression operand begins with the equal sign (=), the
1202 following text must be a Perl miniprogram which is a valid parameter
1203 for the Perl eval() function. The miniprogram may contain match vari‐
1204 ables. In order to evaluate the Perl miniprogram operand, it will be
1205 compiled and executed by calling the Perl eval() function in the Perl
1206 scalar context (see also PERL INTEGRATION section). If the return
1207 value from eval() is true in the Perl boolean context, the operand
1208 evaluates TRUE, otherwise it evaluates FALSE. Please note that unlike
1209 Perl functions of -> and :> operators which are compiled once at SEC
1210 startup, Perl miniprograms are compiled before each execution, and
1211 their evaluation is thus considerably more expensive.
1212 For example, the following context expression evaluates TRUE when nei‐
1214 ther the context C1 nor the context C2 exists and the value of the $1
1215 variable equals to the string "myhost.mydomain":
1216 context=!(C1 || C2) && =("$1" eq "myhost.mydomain")
1218 Since && is a short-circuiting operator, the Perl code
1220 "$1" eq "myhost.mydomain"
1222 is *not* evaluated if either C1 or C2 exists.
1224 Note that since Perl functions and miniprograms may contain strings
1226 that clash with context expression operators (e.g., '!'), it is recom‐
1227 mended to enclose them in parentheses, e.g.,
1228 context=$1 $2 -> ( sub { $_[0] != $_[1] } )
1230 context= =({my($temp) = 0; !$temp;})
1232 Also, if function parameter lists contain such strings, they should be
1234 enclosed in parentheses in the similar way:
1235 context=($1! $2) -> ( sub { $_[0] eq $_[1] } )
1237 If the whole context expression is enclosed in square brackets [],
1239 e.g., [MYCONTEXT1 && !MYCONTEXT2], SEC evaluates the expression
1240 *before* pattern matching (normally, the pattern is matched with input
1241 line(s) first, so that match variables would be initialized and substi‐
1242 tuted before the expression is evaluated). However, if the expression
1243 does not contain match variables and many input events are known to
1244 match the pattern but not the expression, the []-operator could save
1245 substantial amount of CPU time.
1246
1248 Action lists are defined with the action* rule fields. An action list
1249 consists of action definitions that are separated by semicolons. Each
1250 action definition begins with a keyword specifying the action type.
1251 Depending on the action type, parameters may follow, and non-constant
1252 parameters may contain match variables. For instance, if the $1 and $2
1253 match variables have the values "test1" and "the second test", respec‐
1254 tively, the action create MYCONT_$1 60 creates the context MYCONT_test1
1255 with the lifetime of 60 seconds, while the action write - The names of
1256 tests: $1, $2 writes the string "The names of tests: test1, the second
1257 test" to standard output.
1258 Apart from few exceptions explicitly noted, match variables are substi‐
1260 tuted at the earliest opportunity in action lists. For example, con‐
1261 sider the following rule definition:
1262 type=SingleWithThreshold
1264 ptype=RegExp
1265 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
1266 desc=Three SSH login failures within 1m
1267 action=pipe 'Three SSH login failures, first user is $1' \
1268 /bin/mail -s 'SSH login alert' root@localhost
1269 window=60
1270 thresh=3
1271 When this rule matches an SSH login failure event which starts an event
1273 correlation operation, the operation substitutes the $1 match variable
1274 in the action list definition with the user name from the matching
1275 event, and user names from further events processed by this event cor‐
1276 relation operation are not considered for $1. For example, if the fol‐
1277 lowing events are observed
1278 Dec 16 16:24:52 myserver sshd[13671]: Failed password for root from
1280 10.12.2.5 port 29736 ssh2
1281 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
1282 10.12.2.5 port 41063 ssh2
1283 Dec 16 16:25:01 myserver sshd[13689]: Failed password for oracle from
1284 10.12.2.5 port 11204 ssh2
1285 then all events are processed by the same operation, and the message
1287 "Three SSH login failures, first user is root" is mailed to root@local‐
1288 host.
1289 In order to use semicolons inside a non-constant parameter, the parame‐
1291 ter must be enclosed in parentheses (the outermost set of parentheses
1292 will be removed by SEC during configuration file parsing). For exam‐
1293 ple, the following action list consists of delete and shellcmd actions:
1294 action=delete MYCONTEXT; shellcmd (rm /tmp/sec1.tmp; rm /tmp/sec2.tmp)
1296 The delete action deletes the context MYCONTEXT, while the shellcmd
1298 action executes the command line rm /tmp/sec1.tmp; rm /tmp/sec2.tmp.
1299 Since the command line contains a semicolon, it has been enclosed in
1300 parentheses, since otherwise the semicolon would be mistakenly consid‐
1301 ered a separator between two actions.
1302 Apart from match variables, SEC supports action list variables in
1304 action lists which facilitate data sharing between actions and Perl
1305 integration. Each action list variable has a name which must begin with
1306 a letter and consist of letters, digits and underscores. Names of
1307 built-in variables usually start with a punctuation mark (.), so that
1308 they can be distinguished from user defined variables. In order to
1309 refer to an action list variable, its name must be prefixed by a per‐
1310 cent sign (%). Unlike match variables, action list variables can only
1311 be used in action lists and they are substituted with their values
1312 immediately before the action list execution. Also, action list vari‐
1313 ables continue to exist after the current action list has been executed
1314 and can be employed in action lists of other rules.
1315 The following action list variables are predefined by SEC:
1317 %s operation description string (the value of the desc field after
1319 match variables have been substituted with their values). Note
1320 that for the action2 field of Pair and PairWithWindow rules, the
1321 %s variable is set by evaluating the desc2 field of the rule.
1322 %t the time in human-readable format, as returned by the Perl
1324 localtime() function in the Perl scalar context (e.g., Fri Feb
1325 19 17:54:18 2016).
1326 %u the time in seconds since Epoch, as returned by the time(2) sys‐
1328 tem call.
1329 %.sec number of seconds after the minute, in the range 00-59 (the
1331 value consists of two digits and is zero padded on the left).
1332 %.min number of minutes after the hour, in the range 00-59 (the value
1334 consists of two digits and is zero padded on the left).
1335 %.hour number of hours past midnight, in the range 00-23 (the value
1337 consists of two digits and is zero padded on the left).
1338 %.hmsstr
1340 the time in HH:MM:SS format (hours, minutes and seconds sepa‐
1341 rated by colons, e.g., 09:32:04 or 18:06:02).
1342 %.mday day of the month, in the range 01-31 (the value consists of two
1344 digits and is zero padded on the left).
1345 %.mdaystr
1347 day of the month as a string (the value consists of two charac‐
1348 ters and is space padded on the left, e.g., " 1", " 4", " 9", or
1349 "25").
1350 %.mon month, in the range 01-12 (the value consists of two digits and
1352 is zero padded on the left).
1353 %.monstr
1355 abbreviated name of the month according to the current locale,
1356 as returned by the %b specification of the strftime(3) library
1357 call (e.g., Jan, May, or Sep).
1358 %.year year (e.g., 1998 or 2016).
1360 %.wday day of the week, in the range 0-6 (0 denotes Sunday).
1362 %.wdaystr
1364 abbreviated name of the day of the week according to the current
1365 locale, as returned by the %a specification of the strftime(3)
1366 library call (e.g., Mon, Wed, or Sat).
1367 %.tzname
1369 name of the timezone according to the current locale, as
1370 returned by the %Z specification of the strftime(3) library call
1371 (e.g., UTC or EET).
1372 %.tzoff
1374 timezone offset from UTC, as returned by the %z specification of
1375 the strftime(3) library call (e.g., -0500 or +0200).
1376 %.tzoff2
1378 timezone offset from UTC in +hh:mm/-hh:mm format (e.g., -05:00
1379 or +02:00), provided that the %z specification of the strf‐
1380 time(3) library call returns the value in +hhmm/-hhmm format (if
1381 the value does not follow this format, %.tzoff2 is set to an
1382 empty string).
1383 %.nl newline character.
1385 %.cr carriage return character.
1387 %.tab tabulation character.
1389 %.chr0, ..., %.chr31
1391 ASCII 0..31 control characters (e.g., %.chr7 is bell and %.chr12
1392 is form feed character).
1393 For example, the following action list assigns the current time in
1395 human-readable format and the string "This is a test event" to the
1396 %text action list variable, and mails the value of %text to root@local‐
1397 host:
1398 action=assign %text %t: This is a test event; \
1400 pipe '%text' /bin/mail root@localhost
1401 If the action list is executed at Nov 19 10:58:51 2015, the assign
1403 action sets the %text action list variable to the string "Thu Nov 19
1404 10:58:51 2015: This is a test event", while the pipe action mails this
1405 string to root@localhost. Note that unlike match variables, action
1406 list variables have a global scope, and accessing the value of the
1407 %text variable in action lists of other rules will thus yield the
1408 string "Thu Nov 19 10:58:51 2015: This is a test event" (until another
1409 value is assigned to %text).
1410 In order to disambiguate the variable from the following text, the
1412 variable name must be enclosed in braces. For example, the following
1413 action
1414 action=write - %{.year}-%{.mon}-%{.mday}T%{.hmsstr}%{.tzoff2}
1416 writes a timestamp in ISO 8601 format to standard output, e.g.,
1418 2016-02-24T07:34:01+02:00 (replacing %{.mday} with %.mday in the above
1419 action would mistakenly create a reference to %.mdayT variable).
1420 When action list variables are substituted with their values, each
1422 sequence "%%" is interpreted as a literal percent sign (%) which allows
1423 for masking the variables. For example, the string "s%%t" becomes "s%t"
1424 after substitution, not "s%<timestamp>".
1425 However, note that if %-prefixed match variables are supported for the
1427 action2 field of the Pair or PairWithWindow rule, the sequence "%%%"
1428 must be used in action2 for masking a variable, since the string goes
1429 through *two* variable substitution rounds (first for %-prefixed match
1430 variables and then for action list variables, e.g., the string "s%%%t"
1431 first becomes "s%%t" and finally "s%t").
1432 Whenever a rule field goes through several substitution rounds, the $
1434 or % characters are masked inside values substituted during earlier
1435 rounds, in order to avoid unwanted side effects during later rounds.
1436 If the action list variable has not been set, it is substituted with an
1438 empty string (i.e., a zero-width string). Thus the string "Value of A
1439 is: %a" becomes "Value of A is: " after substitution if the variable %a
1440 is unset. (Note that prior to SEC-2.6, unset variables were *not* sub‐
1441 stituted.)
1442 Finally, the values are substituted as strings, therefore values of
1444 other types (e.g., references) lose their original meaning, unless
1445 explicitly noted otherwise (e.g., if a Perl function reference is
1446 stored to an action list variable, the function can later be invoked
1447 through this variable with the call action).
1448 SEC supports the following actions (optional parameters are enclosed in
1450 square brackets):
1451 none No action.
1453 logonly [<string>]
1455 Message <string> is logged to destinations given with the --log
1456 and --syslog options. The level of the log message is set to 4
1457 (see the --debug option for more information on log message lev‐
1458 els). Default value for <string> is %s. For example, consider
1459 the following action list definition:
1460 action=logonly This is a test
1462 The above logonly action logs the message "This is a test" with
1464 level 4.
1465 write <filename> [<string>]
1467 String <string> with a terminating newline is written to the
1468 file <filename> (<filename> may not contain whitespace). File
1469 may be a regular file, named pipe, or standard output (denoted
1470 by -). If the file is a regular file, <string> is appended to
1471 the end of the file. If the file does not exist, it is created
1472 as a regular file before writing. Note that the file will not
1473 be closed after the action completes, and the following write
1474 actions will access an already open file. However, several sig‐
1475 nals cause the file to be closed and reopened, and for rotating
1476 files created with write action, the SIGUSR2 signal can be used
1477 (see SIGNALS section for more information). Default value for
1478 <string> is %s. For example, consider the following action list
1479 definition:
1480 action=write /var/log/test.log %t $0
1482 The above write action prepends human-readable timestamp and
1484 separating space character to the value of the $0 match vari‐
1485 able, and the resulting string is appended to file
1486 /var/log/test.log with terminating newline.
1487 writen <filename> [<string>]
1489 Similar to the write action, except that the string <string> is
1490 written without a terminating newline. Note that write and
1491 writen actions share the same filehandle for accessing the file.
1492 For example, consider the following action list definition:
1493 action=writen - ab; writen - c; writen - %.nl
1495 The above action list writes the string "abc<NEWLINE>" to stan‐
1497 dard output, and is thus identical to write - abc (and also to
1498 writen - abc%.nl).
1499 closef <filename>
1501 Close the file <filename> that has been previously opened by the
1502 write or writen action (<filename> may not contain whitespace).
1503 owritecl <filename> [<string>]
1505 Similar to the write action, except that the file <filename> is
1506 opened and closed at each write. Also, the string <string> is
1507 written without a terminating newline. If the file has already
1508 been opened by a previous write action, owritecl does not use
1509 existing filehandle, but opens and closes the file separately.
1510 For example, consider the following action list definition:
1511 action=owritecl /var/log/test-%{.year}%{.mon}%{.mday} $0%{.nl}
1513 The above owritecl action appends the value of the $0 match
1515 variable with terminating newline to file /var/log/test-YYYYM‐
1516 MDD, where YYYYMMDD reflects the current date (e.g., if the cur‐
1517 rent date is April 1 2018, the file is /var/log/test-20180401).
1518 Since the file is closed after each write, the old file will not
1519 be left open when date changes.
1520 udgram <filename> [<string>]
1522 String <string> is written to the UNIX datagram socket <file‐
1523 name> (<filename> may not contain whitespace). Note that the
1524 socket will not be closed after the action completes, and the
1525 following udgram actions will access an already open socket.
1526 However, several signals cause the socket to be closed and
1527 reopened (see SIGNALS section for more information). Default
1528 value for <string> is %s. For example, consider the following
1529 action list definition:
1530 action=udgram /dev/log <30>%.monstr %.mdaystr %.hmsstr sec: This
1532 is a test
1533 The above udgram action sends a syslog message to local syslog
1535 daemon via /dev/log socket, where message priority is 30 (corre‐
1536 sponds to the "daemon" facility and "info" level), syslog tag is
1537 "sec" and message text is "This is a test". Note that message
1538 substring "%.monstr %.mdaystr %.hmsstr" evaluates to timestamp
1539 in BSD syslog format (e.g., Mar 31 15:36:07).
1540 closeudgr <filename>
1542 Close the UNIX datagram socket <filename> that has been previ‐
1543 ously opened by the udgram action (<filename> may not contain
1544 whitespace).
1545 ustream <filename> [<string>]
1547 String <string> is written to the UNIX stream socket <filename>
1548 (<filename> may not contain whitespace). Note that the socket
1549 will not be closed after the action completes, and the following
1550 ustream actions will access an already open socket. However,
1551 several signals cause the socket to be closed and reopened (see
1552 SIGNALS section for more information). Default value for
1553 <string> is %s.
1554 closeustr <filename>
1556 Close the UNIX stream socket <filename> that has been previously
1557 opened by the ustream action (<filename> may not contain white‐
1558 space).
1559 udpsock <host>:<port> [<string>]
1561 String <string> is sent to the UDP port <port> of the host
1562 <host>. Note that the UDP socket which is used for communica‐
1563 tion will not be closed after the action completes, and the fol‐
1564 lowing udpsock actions for the same remote peer will use an
1565 already existing socket. However, several signals cause the
1566 socket to be closed and recreated (see SIGNALS section for more
1567 information). Default value for <string> is %s. For example,
1568 consider the following action list definition:
1569 action=udpsock mysrv:514 <13>%.monstr %.mdaystr %.hmsstr myhost
1571 test: $0
1572 The above udpsock action sends a BSD syslog message to port
1574 514/udp of remote syslog server mysrv, where message priority is
1575 13 (corresponds to the "user" facility and "notice" level), name
1576 of the local host is "myhost", syslog tag is "test" and message
1577 text is the value if the $0 match variable.
1578 closeudp <host>:<port>
1580 Close the UDP socket for peer <host>:<port> that has been previ‐
1581 ously opened by the udpsock action.
1582 tcpsock <host>:<port> [<string>]
1584 String <string> is sent to the TCP port <port> of the host
1585 <host>. The timeout value given with the --socket-timeout
1586 option determines for how many seconds SEC will attempt to
1587 establish a connection to the remote peer. If the connection
1588 establishment does not succeed immediately, the tcpsock action
1589 buffers <string> in memory for later sending to the remote peer.
1590 Note that the relevant TCP socket will not be closed after
1591 <string> has been transmitted, and the following tcpsock actions
1592 for the same peer will use an already existing socket. However,
1593 several signals cause the socket to be closed and recreated (see
1594 SIGNALS section for more information). Default value for
1595 <string> is %s. For example, consider the following action list
1596 definition:
1597 action=tcpsock grsrv:2003 ssh.login.failures %{num} %{u}%{.nl}
1599 The above tcpsock action sends the value of the action list
1601 variable %{num} to port 2003/tcp of the Graphite server grsrv,
1602 so that the value is recorded under metric path ssh.login.fail‐
1603 ures. Note that the %{u} action list variable evaluates to cur‐
1604 rent time in seconds since Epoch and is used for setting the
1605 timestamp for recorded value.
1606 closetcp <host>:<port>
1608 Close the TCP socket for peer <host>:<port> that has been previ‐
1609 ously opened by the tcpsock action.
1610 shellcmd <cmdline>
1612 Fork a process for executing command line <cmdline>. If the
1613 --quoting option was specified and <cmdline> contains %s vari‐
1614 ables, the value of %s is quoted with single quotes before sub‐
1615 stituting it into <cmdline>; if the value of %s contains single
1616 quotes, they are masked with backslashes (e.g., abc is converted
1617 to 'abc' and aa'bb is converted to 'aa'\''bb'). For additional
1618 information, see INTERPROCESS COMMUNICATION section. For exam‐
1619 ple, consider the following action list definition:
1620 action=shellcmd (cat /tmp/report | mail root; rm -f
1622 /tmp/report); \
1623 logonly Report sent to user root
1624 The shellcmd action of this action list executes the command
1626 line
1627 cat /tmp/report | mail root; rm -f /tmp/report
1629 and the logonly action logs the message "Report sent to user
1631 root". Since the command line contains a semicolon which is
1632 used for separating shellcmd and logonly actions, the command
1633 line is enclosed in parentheses.
1634 spawn <cmdline>
1636 Similar to the shellcmd action, except that each line from the
1637 standard output of <cmdline> becomes a synthetic event and will
1638 be treated like a line from input file (see the event action for
1639 more information). If the --intcontexts command line option is
1640 given, internal context _INTERNAL_EVENT is set up before each
1641 synthetic event is processed (see INTERNAL EVENTS AND CONTEXTS
1642 section for more information). For example, consider the fol‐
1643 lowing action list definition:
1644 action=spawn (cat /tmp/events; rm -f /tmp/events)
1646 The above spawn action will generate synthetic events from all
1648 lines in file /tmp/events and remove the file. Since the command
1649 line contains a semicolon which is used for separating actions,
1650 the command line is enclosed in parentheses.
1651 cspawn <name> <cmdline>
1653 Similar to the spawn action, except that if the --intcontexts
1654 command line option is given, internal context <name> is set up
1655 for each synthetic event.
1656 pipe '[<string>]' [<cmdline>]
1658 Fork a process for executing command line <cmdline>. The string
1659 <string> with a terminating newline is written to the standard
1660 input of <cmdline> (single quotes are used for disambiguating
1661 <string> from <cmdline>). If <string> contains semicolons,
1662 <string> must be enclosed in parentheses (e.g., pipe '($1;$2)'
1663 /bin/cat). Default value for <string> is %s. If <cmdline> is
1664 omitted, <string> is written to standard output. For additional
1665 information, see INTERPROCESS COMMUNICATION section. For exam‐
1666 ple, consider the following action list definition:
1667 action=pipe 'Offending activities from host $1' /bin/mail
1669 root@localhost
1670 The above pipe action writes the line "Offending activities from
1672 host <hostname>" to the standard input of the /bin/mail
1673 root@localhost command which sends this line to root@localhost
1674 via e-mail (<hostname> is the value of the $1 match variable).
1675 create [<name> [<time> [<action list>] ] ]
1677 Create a context with the name <name>, lifetime of <time> sec‐
1678 onds, and empty event store. The <name> parameter may not con‐
1679 tain whitespace and defaults to %s. The <time> parameter must
1680 evaluate to an unsigned integer at runtime. Specifying 0 for
1681 <time> or omitting the value means infinite lifetime. If
1682 <action list> is given, it will be executed when the context
1683 expires. If <action list> contains several actions, the list
1684 must be enclosed in parentheses. In <action list>, the internal
1685 context name _THIS may be used for referring to the current con‐
1686 text (see INTERNAL EVENTS AND CONTEXTS section for a detailed
1687 discussion). If an already existing context is recreated with
1688 create, its remaining lifetime is set to <time> seconds, its
1689 action list is reinitialized, and its event store is emptied.
1690 For example, consider the following action list definition:
1691 action=write /var/log/test.log $0; create TIMER 3600 \
1693 ( logonly Closing /var/log/test.log; closef
1694 /var/log/test.log )
1695 The write action from the above action list appends the value of
1697 the $0 match variable to file /var/log/test.log, while the cre‐
1698 ate action creates the context TIMER which will exist for 3600
1699 seconds. Since this context is recreated at each write, the con‐
1700 text can expire only if the action list has not been executed
1701 for more than 3600 seconds (i.e., the action list has last
1702 updated the file more than 1 hour ago). If that is the case, the
1703 action list
1704 logonly Closing /var/log/test.log; closef /var/log/test.log
1706 is executed which logs the message "Closing /var/log/test.log"
1708 with the logonly action and closes /var/log/test.log with the
1709 closef action. When the execution of this action list is com‐
1710 plete, the TIMER context is deleted.
1711 delete [<name>]
1713 Delete the context <name>. The <name> parameter may not contain
1714 whitespace and defaults to %s.
1715 obsolete [<name>]
1717 Similar to the delete action, except that the action list of the
1718 context <name> (if present) is executed before deletion.
1719 set <name> <time> [<action list>]
1721 Change settings for the context <name>. The creation time of the
1722 context is set to the current time, and the lifetime of the con‐
1723 text is set to <time> seconds. If the <action list> parameter
1724 is given, the context action list is set to <action list>, oth‐
1725 erwise the context action list is not changed. The <name>
1726 parameter may not contain whitespace and defaults to %s. The
1727 <time> parameter must evaluate to an unsigned integer or hyphen
1728 (-) at runtime. Specifying 0 for <time> means infinite life‐
1729 time. If <time> equals to -, the creation time and lifetime of
1730 the context are not changed. If <action list> contains several
1731 actions, the list must be enclosed in parentheses. In <action
1732 list>, the internal context name _THIS may be used for referring
1733 to the current context (see INTERNAL EVENTS AND CONTEXTS section
1734 for a detailed discussion). For example, consider the following
1735 action list definition:
1736 action=set C_$1 30 ( logonly Context C_$1 has expired )
1738 The above set action sets the context C_<suffix> to expire after
1740 30 seconds with a log message about expiration (<suffix> is the
1741 value of the $1 match variable).
1742 alias <name> [<alias>]
1744 Create an alias name <alias> for the context <name>. After cre‐
1745 ation, both <alias> and <name> will point to the same context
1746 data structure, and can thus be used interchangeably for refer‐
1747 ring to the context. The <name> and <alias> parameters may not
1748 contain whitespace, and <alias> defaults to %s. If the context
1749 <name> does not exist, the alias name is not created. If the
1750 delete action is called for one of the context names, the con‐
1751 text data structure is destroyed, and all context names (which
1752 are now pointers to unallocated memory) cease to exist. Also
1753 note that when the context expires, its action list is executed
1754 only once, no matter how many names the context has.
1755 unalias [<alias>]
1757 Drop an existing context name <alias>, so that it can no longer
1758 be used for referring to the given context. The <alias> parame‐
1759 ter may not contain whitespace and defaults to %s. If the name
1760 <alias> is the last reference to the context, the unalias action
1761 is identical to delete.
1762 add <name> [<string>]
1764 String <string> is appended to the end of the event store of the
1765 context <name>. The <name> parameter may not contain white‐
1766 space, and the <string> parameter defaults to %s. If the con‐
1767 text <name> does not exist, the context is created with an infi‐
1768 nite lifetime, empty action list and empty event store (as with
1769 create <name>) before adding the string to event store. If
1770 <string> is a multi-line string (i.e., it contains newlines), it
1771 is split into lines, and each line is appended to the event
1772 store separately. For example, consider the following action
1773 list definition:
1774 action=add EVENTS This is a test; add EVENTS This is a test2
1776 After the execution of this action list, the last two strings in
1778 the event store of the EVENTS context are "This is a test" and
1779 "This is a test2" (in that order).
1780 prepend <name> [<string>]
1782 Similar to the add action, except that the string <string> is
1783 prepended to the beginning of the event store of context <name>.
1784 For example, consider the following action list definition:
1785 action=prepend EVENTS This is a test; prepend EVENTS This is a
1787 test2
1788 After the execution of this action list, the first two strings
1790 in the event store of the EVENTS context are "This is a test2"
1791 and "This is a test" (in that order).
1792 fill <name> [<string>]
1794 Similar to the add action, except that the event store of the
1795 context <name> is emptied before <string> is added.
1796 report <name> [<cmdline>]
1798 Fork a process for executing command line <cmdline>, and write
1799 strings from the event store of the context <name> to the stan‐
1800 dard input of <cmdline>. Strings are written in the order they
1801 appear in the event store, with a terminating newline appended
1802 to each string. If the context <name> does not exist or its
1803 event store is empty, <cmdline> is not executed. The <name>
1804 parameter may not contain whitespace, and if <cmdline> is omit‐
1805 ted, strings are written to standard output. For additional
1806 information, see INTERPROCESS COMMUNICATION section. For exam‐
1807 ple, consider the following action list definition:
1808 action=create PID_$1 60 ( report PID_$1 /bin/mail root@localhost
1810 ); \
1811 add PID_$1 Beginning of the report
1812 The above action list creates the context PID_<suffix> with the
1814 lifetime of 60 seconds and sets the first string in the context
1815 event store to "Beginning of the report" (<suffix> is the value
1816 of the $1 match variable). When the context expires, all
1817 strings from the event store will be mailed to root@localhost.
1818 copy <name> %<var>
1820 Strings s1,...,sn from the event store of the context <name> are
1821 joined into a multi-line string "s1<NEWLINE>...<NEWLINE>sn", and
1822 this string is assigned to the action list variable %<var>. If
1823 the context <name> does not exist, the value of %<var> does not
1824 change.
1825 empty <name> [%<var>]
1827 Similar to the copy action, except that the event store of the
1828 context <name> will be emptied after the assignment. If %<var>
1829 is omitted, the content of the event store is dropped without an
1830 assignment.
1831 pop <name> %<var>
1833 Remove the last string from the event store of context <name>,
1834 and assign it to the action list variable %<var>. If the event
1835 store is empty, %<var> is set to empty string. If the context
1836 <name> does not exist, the value of %<var> does not change.
1837 shift <name> %<var>
1839 Remove the first string from the event store of context <name>,
1840 and assign it to the action list variable %<var>. If the event
1841 store is empty, %<var> is set to empty string. If the context
1842 <name> does not exist, the value of %<var> does not change.
1843 exists %<var> <name>
1845 If the context <name> exists, set the action list variable
1846 %<var> to 1, otherwise set %<var> to 0.
1847 getsize %<var> <name>
1849 Find the number of strings in the event store of context <name>,
1850 and assign this number to the action list variable %<var>. If
1851 the context <name> does not exist, %<var> is set to Perl unde‐
1852 fined value. For example, consider the following action list
1853 definition:
1854 action=fill EVENTS Event1; add EVENTS Event2; add EVENTS Event3;
1856 \
1857 pop EVENTS %temp1; shift EVENTS %temp2; getsize %size
1858 EVENTS
1859 This action list sets the %temp1 action list variable to Event3,
1861 %temp2 action list variable to Event1, and %size action list
1862 variable to 1.
1863 getaliases %<var> <name>
1865 Find all alias names for context <name>, join the names into a
1866 multi-line string "alias1<NEWLINE>...<NEWLINE>aliasn", and
1867 assign this string to the action list variable %<var>. If the
1868 context <name> does not exist, the value of %<var> does not
1869 change.
1870 getltime %<var> <name>
1872 Find the lifetime of context <name>, and assign this number to
1873 the action list variable %<var>. If the context <name> does not
1874 exist, the value of %<var> does not change. For example, con‐
1875 sider the following action list definition:
1876 action=create TEST 10 ( getltime %time TEST; \
1878 logonly Context TEST with %time second lifetime has
1879 expired )
1880 The above create action configures the context TEST to log its
1882 lifetime when it expires.
1883 setltime <name> [<time>]
1885 Set the lifetime of context <name> to <time>. Specifying 0 for
1886 <time> or omitting the value means infinite lifetime. Note that
1887 unlike the set action, setltime does not adjust the context cre‐
1888 ation time. For example, if context TEST has been created at
1889 12:01:00 with the lifetime of 60 seconds, then after invoking
1890 setltime TEST 30 at 12:01:20 the context would exist until
1891 12:01:30, while invoking setltime TEST 10 would immediately
1892 expire the context.
1893 getctime %<var> <name>
1895 Find the creation time of context <name>, and assign this time‐
1896 stamp to the action list variable %<var>. The value assigned to
1897 %<var> is measured in seconds since Epoch (as reported by the
1898 time(2) system call). If the context <name> does not exist, the
1899 value of %<var> does not change.
1900 setctime <time> <name>
1902 Set the creation time of context <name> to <time>. The <time>
1903 parameter must evaluate to seconds since Epoch (as reported by
1904 the time(2) system call), and must reflect a time moment between
1905 the previous creation time and the current time (both endpoints
1906 included). For example, if context TEST has been created at
1907 12:43:00 with the lifetime of 60 seconds, then after invoking
1908 setctime %u TEST at 12:43:25 the context would exist until
1909 12:44:25 (the %u action list variable evaluates to current time
1910 in seconds since Epoch).
1911 event [<time>] [<string>]
1913 After <time> seconds, create a synthetic event <string>. If
1914 <string> is a multi-line string (i.e., it contains newlines), it
1915 is split into lines, and from each line a separate synthetic
1916 event is created. SEC will treat each synthetic event like a
1917 line from an input file -- the event will be matched against
1918 rules and it might trigger further actions. If the --intcon‐
1919 texts command line option is given, internal context _INTER‐
1920 NAL_EVENT is set up for synthetic event(s) (see INTERNAL EVENTS
1921 AND CONTEXTS section for more information). The <time> parame‐
1922 ter is an integer constant. Specifying 0 for <time> or omitting
1923 the value means "now". Default value for <string> is %s. For
1924 example, consider the following action list definition:
1925 action=copy EVENTS %events; event %events
1927 The above action list will create a synthetic event from each
1929 string in the event store of the EVENTS context.
1930 tevent <time> [<string>]
1932 Similar to the event action, except that the <time> parameter
1933 may contain variables and must evaluate to an unsigned integer
1934 at runtime.
1935 cevent <name> <time> [<string>]
1937 Similar to the tevent action, except that if the --intcontexts
1938 command line option is given, internal context <name> is set up
1939 for synthetic event(s).
1940 reset [<offset>] [<string>]
1942 Terminate event correlation operation(s) with the operation
1943 description string <string>. Note that the reset action works
1944 only for operations started from the same configuration file.
1945 The <offset> parameter is used to refer to a specific rule in
1946 the configuration file. If <offset> is given, the operation
1947 started by the given rule is terminated (if it exists). If
1948 <offset> is an unsigned integer N, it refers to the N-th rule in
1949 the configuration file. If <offset> is 0, it refers to the cur‐
1950 rent rule. If <offset> begins with the plus (+) or minus (-)
1951 sign, it specifies an offset from the current rule (e.g., -1
1952 denotes the previous and +1 the next rule). Note that since
1953 Options rules are only processed when configuration files are
1954 loaded and they are not applied at runtime, Options rules are
1955 excluded when calculating <offset>. If <offset> is not given,
1956 SEC checks for each rule from the current configuration file if
1957 an operation with <string> has been started by this rule, and
1958 the operation is terminated if it exists. Default value for
1959 <string> is %s. For additional information, see EVENT CORRELA‐
1960 TION OPERATIONS section. For example, consider the following
1961 action list definition:
1962 action=reset -1 Ten login failures observed from $1; reset 0
1964 If the above action list is executed by an event correlation
1966 operation, the first reset action will terminate another event
1967 correlation operation which has been started by the previous
1968 rule and has the operation description string "Ten login fail‐
1969 ures observed from <host>" (<host> is the value of the $1 match
1970 variable). The second reset action will terminate the calling
1971 operation itself.
1972 getwpos %<var> <offset> [<string>]
1974 Find the beginning of the event correlation window for an event
1975 correlation operation, and set the action list variable %<var>
1976 to this timestamp. The value assigned to %<var> is measured in
1977 seconds since Epoch (as reported by the time(2) system call). As
1978 with the reset action, the event correlation operation is iden‐
1979 tified by the operation description string <string> and the rule
1980 offset <offset>. If the operation does not exist, the value of
1981 %<var> does not change. Default value for <string> is %s. For
1982 additional information, see EVENT CORRELATION OPERATIONS sec‐
1983 tion. For example, consider the following action list defini‐
1984 tion:
1985 action=getwpos %pos -1 Ten login failures observed from $1
1987 The above getwpos action will find the beginning of the event
1989 correlation window for an event correlation operation which has
1990 been started by the previous rule and has the operation descrip‐
1991 tion string "Ten login failures observed from <host>" (<host> is
1992 the value of the $1 match variable). If the event correlation
1993 window begins at April 6 08:03:53 2018 UTC, the value 1523001833
1994 will be assigned to the %pos action list variable.
1995 setwpos <time> <offset> [<string>]
1997 Set the beginning of the event correlation window to <time> for
1998 an event correlation operation (if it exists). The <time> param‐
1999 eter must evaluate to seconds since Epoch (as reported by the
2000 time(2) system call), and must reflect a time moment between the
2001 previous window position and the current time (both endpoints
2002 included). As with the reset action, the event correlation oper‐
2003 ation is identified by the operation description string <string>
2004 and the rule offset <offset>. Default value for <string> is %s.
2005 For additional information, see EVENT CORRELATION OPERATIONS
2006 section.
2007 assign %<var> [<string>]
2009 Assign string <string> to the action list variable %<var>.
2010 Default value for <string> is %s.
2011 assignsq %<var> [<string>]
2013 Similar to the assign action, except that <string> is quoted
2014 with single quotes before assigning it to %<var>. If <string>
2015 contains single quotes, they are masked with backslashes (e.g.,
2016 if the match variable $1 holds the value abc'123'xyz, the action
2017 assignsq %myvar $1 assigns the value 'abc'\''123'\''xyz' to the
2018 action list variable %myvar). This action is useful for dis‐
2019 abling shell intepretation for the values of action list vari‐
2020 ables that appear in command lines executed by SEC. Default
2021 value for <string> is %s.
2022 free %<var>
2024 Unset the action list variable %<var>.
2025 eval %<var> <code>
2027 The parameter <code> is a Perl miniprogram that is compiled and
2028 executed by calling the Perl eval() function in the Perl list
2029 context. If the miniprogram returns a single value, it is
2030 assigned to the action list variable %<var>. If the miniprogram
2031 returns several values s1,...,sn, they are joined into a multi-
2032 line string "s1<NEWLINE>...<NEWLINE>sn", and this string is
2033 assigned to %<var>. If no value is returned, %<var> is set to
2034 Perl undefined value. If eval() fails, the value of %<var> does
2035 not change. Since most Perl programs contain semicolons which
2036 are also employed by SEC as action separators, it is recommended
2037 to enclose the <code> parameter in parentheses, in order to mask
2038 the semicolons in <code>. For additional information, see PERL
2039 INTEGRATION section. For example, consider the following action
2040 list definition:
2041 action=assign %div Division error; eval %div ( $1 / $2 )
2043 The assign action sets the %div action list variable to the
2045 string "Division error", while the eval action substitutes the
2046 values of $1 and $2 match variables into the string "$1 / $2".
2047 Resulting string is treated as Perl code which is first compiled
2048 and then executed. For instance, if the values of $1 and $2 are
2049 12 and 4, respectively, the following Perl code is compiled: 12
2050 / 4. Since executing this code yields 3, the eval action assigns
2051 this value to the %div action list variable. Also, if $2 has no
2052 value or its value is 0, resulting code leads to compilation or
2053 execution error, and %div retains its previous value "Division
2054 error".
2055 call %<var> %<ref> [<paramlist>]
2057 Call the precompiled Perl function referenced by the action list
2058 variable %<ref>, and assign the result to the action list vari‐
2059 able %<var>. The %<ref> parameter must be a code reference that
2060 has been previously created with the eval action. The <param‐
2061 list> parameter (if given) is a string which specifies parame‐
2062 ters for the function. The parameters must be separated by
2063 whitespace in the <paramlist> string. If the function returns a
2064 single value, it is assigned to %<var>. If the function returns
2065 several values s1,...,sn, they are joined into a multi-line
2066 string "s1<NEWLINE>...<NEWLINE>sn", and this string is assigned
2067 to %<var>. If no value is returned, %<var> is set to Perl unde‐
2068 fined value. If the function encounters a fatal runtime error
2069 or %<ref> is not a code reference, the value of %<var> does not
2070 change. For additional information, see PERL INTEGRATION sec‐
2071 tion. For example, consider the following action list defini‐
2072 tion:
2073 action=eval %func ( sub { return $_[0] + $_[1] } ); \
2075 call %sum %func $1 $2
2076 Since the Perl code provided to eval action is a definition of
2078 an anonymous function, its compilation yields a code reference
2079 which gets assigned to the %func action list variable (the func‐
2080 tion returns the sum of its two input parameters). The call
2081 action will invoke previously compiled function, using the val‐
2082 ues of $1 and $2 match variables as function parameters, and
2083 assigning function return value to the %sum action list vari‐
2084 able. Therefore, if the values of $1 and $2 are 2 and 3, respec‐
2085 tively, %sum is set to 5.
2086 lcall %<var> [<paramlist>] -> <code>
2088 lcall %<var> [<paramlist>] :> <code>
2090 Call the precompiled Perl function <code> and assign the result
2091 to the action list variable %<var>. The <code> parameter must
2092 be a valid Perl anonymous function definition that is compiled
2093 at SEC startup with the Perl eval() function, and eval() must
2094 return a code reference. The <paramlist> parameter (if given)
2095 is a string which specifies parameters for the function. The
2096 parameters must be separated by whitespace in the <paramlist>
2097 string. If <paramlist> is followed by -> operator, parameters
2098 are passed to function as Perl scalar values. If <paramlist> is
2099 followed by :> operator, it is assumed that each parameter is a
2100 name of an entry in the pattern match cache. If an entry with
2101 the given name does not exist, Perl undefined value is passed to
2102 the function. If an entry with the given name exists, a refer‐
2103 ence to the entry is passed to the function. Internally, each
2104 pattern match cache entry is implemented as a Perl hash which
2105 contains all match variables for the given entry. If the func‐
2106 tion returns a single value, it is assigned to %<var>. If the
2107 function returns several values s1,...,sn, they are joined into
2108 a multi-line string "s1<NEWLINE>...<NEWLINE>sn", and this string
2109 is assigned to %<var>. If no value is returned, %<var> is set to
2110 Perl undefined value. If the function encounters a fatal run‐
2111 time error, the value of %<var> does not change. Since most
2112 Perl functions contain semicolons which are also employed by SEC
2113 as action separators, it is recommended to enclose the <code>
2114 parameter in parentheses, in order to mask the semicolons in
2115 <code>. For additional information, see PERL INTEGRATION sec‐
2116 tion. For example, consider the following action list defini‐
2117 tion:
2118 action=lcall %len $1 -> ( sub { return length($_[0]) } )
2120 The above lcall action will take the value of the $1 match vari‐
2122 able and find its length in characters, assigning the length to
2123 the %len action list variable. Note that the function for find‐
2124 ing the length is compiled when SEC loads its configuration, and
2125 all invocations of lcall will execute already compiled code. As
2126 another example, consider the following action list definition:
2127 action=lcall %o SSH :> ( sub { $_[0]->{"failure"} = 1 } )
2129 The above lcall action will assign 1 to the $+{failure} match
2131 variable that has been cached under the SSH entry in the pattern
2132 match cache (variable will be created if it did not exist previ‐
2133 ously).
2134 rewrite <lnum> [<string>]
2136 Replace last <lnum> lines in the input buffer with string
2137 <string>. If the --nojointbuf option was specified and the
2138 action is triggered by a matching event, the action modifies the
2139 buffer which holds this event. If the --nojointbuf option was
2140 specified and the action is triggered by the system clock (e.g.,
2141 the action is executed from the Calendar rule), the action modi‐
2142 fies the buffer which holds the last already processed event.
2143 With the --jointbuf option, the content of the joint input buf‐
2144 fer is rewritten. The <lnum> parameter must evaluate to an
2145 unsigned integer at runtime. If <lnum> evaluates to 0, <lnum> is
2146 reset to the number of lines in <string>. If the value of
2147 <lnum> is greater than the buffer size N, <lnum> is reset to N.
2148 If <string> contains less than <lnum> lines, <string> will be
2149 padded with leading empty lines. If <string> contains more than
2150 <lnum> lines, only leading <lnum> lines from <string> are writ‐
2151 ten into the buffer. Default value for <string> is %s. For
2152 additional information, see INPUT PROCESSING AND TIMING section.
2153 addinput <filename> [<offset> [<name>] ]
2155 File <filename> is added to the list of input files and opened,
2156 so that processing starts from file offset <offset>. The <off‐
2157 set> parameter must evaluate to unsigned integer or - (EOF) at
2158 runtime. If <offset> is not specified, it defaults to - (i.e.,
2159 processing starts from the end of file). If opening the file
2160 fails (e.g., the file does not exist), it will stay in the list
2161 of input files (e.g., with the --reopen-timeout command line
2162 option, SEC will attempt to reopen the file). The <name> param‐
2163 eter defines the internal context which should be used for
2164 <filename> if the --intcontexts command line option is given (if
2165 <name> is omitted but --intcontexts command line option is
2166 present, default internal context will be used). See INTERNAL
2167 EVENTS AND CONTEXTS section for more information. For example,
2168 consider the following action list definition:
2169 action=addinput /var/log/test-%{.year}%{.mon}%{.mday} 0 TESTFILE
2171 The above addinput action adds the file /var/log/test-YYYYMMDD
2173 to the list of input files, where YYYYMMDD reflects the current
2174 date. The addinput action will also attempt to open the file,
2175 and if open succeeds, file will be processed from the beginning.
2176 Also, the internal context TESTFILE will be used for all events
2177 read from the file.
2178 dropinput <filename>
2180 File <filename> is dropped from the list of input files and
2181 closed (if currently open). Note that dropinput action can only
2182 be used for input files which have been previously set up with
2183 addinput action.
2184 sigemul <signal>
2186 Emulates the arrival of signal <signal> and triggers its han‐
2187 dler. The <signal> parameter must evaluate to one of the fol‐
2188 lowing strings: HUP, ABRT, USR1, USR2, INT, or TERM. For exam‐
2189 ple, the action sigemul USR1 triggers the generation of SEC dump
2190 file. See the SIGNALS section for detailed information on sig‐
2191 nals that are handled by SEC.
2192 varset %<var> <entry>
2194 If the pattern match cache entry <entry> exists, set the action
2195 list variable %<var> to 1, otherwise set %<var> to 0. For exam‐
2196 ple, if pattern match cache contains the entry with the name SSH
2197 but not the entry with the name NTP, the action varset %ssh SSH
2198 will set the %ssh action list variable to 1, while the action
2199 varset %ntp NTP will set the %ntp action list variable to 0.
2200 if %<var> ( <action list> ) [ else ( <action list2> ) ]
2202 If the action list variable %<var> evaluates true in the Perl
2203 boolean context (i.e., it holds a defined value which is neither
2204 0 nor empty string), execute the action list <action list>. If
2205 the second action list <action list2> is given with the optional
2206 else-statement, it is executed if %<var> either does not exist
2207 or evaluates false (i.e., %<var> holds 0, empty string or Perl
2208 undefined value). For example, consider the following action
2209 list definition:
2210 action=exists %present REPORT; if %present \
2212 ( report REPORT /bin/mail root@localhost; delete REPORT
2213 ) \
2214 else ( logonly Nothing to report )
2215 If the REPORT context exists, its event store is mailed to
2217 root@localhost and the context is deleted, otherwise the message
2218 "Nothing to report" is logged.
2219 while %<var> ( <action list> )
2221 Execute the action list <action list> repeatedly as long as the
2222 action list variable %<var> evaluates true in the Perl boolean
2223 context (i.e., it holds a defined value which is neither 0 nor
2224 empty string). For example, consider the following action list
2225 definition:
2226 action=create REVERSE; getsize %n TEST; \
2228 while %n ( pop TEST %e; add REVERSE %e; getsize %n TEST
2229 ); \
2230 copy REVERSE %events; fill TEST %events
2231 This action list reverses the order of strings in the event
2233 store of the context TEST, using the context REVERSE as a tempo‐
2234 rary storage. During each iteration of the while-loop, the last
2235 string in the event store of TEST is removed with the pop action
2236 and appended to the event store of REVERSE with the add action.
2237 The loop terminates when all strings have been removed from the
2238 event store of TEST (i.e., the getsize action reports 0 for
2239 event store size). Finally, the event store of REVERSE is
2240 assigned to the %events action list variable with the copy
2241 action, and the fill action is used for overwriting the event
2242 store of TEST with the value of %events.
2243 break If used inside a while-loop, terminates its execution; otherwise
2245 terminates the execution of the entire action list.
2246 continue
2248 If used inside a while-loop, starts the next iteration of the
2249 loop; otherwise terminates the execution of the entire action
2250 list.
2251 Examples:
2253 Follow the /var/log/trapd.log file and feed to SEC input all lines that
2255 are appended to the file:
2256 action=spawn /bin/tail -f /var/log/trapd.log
2258 Mail the timestamp and the value of the $0 variable to the local root:
2260 action=pipe '%t: $0' /bin/mail -s "alert message" root@localhost
2262 Add the value of the $0 variable to the event store of the context
2264 ftp_<the value of $1>, and set the context to expire after 30 minutes.
2265 When the context expires, its event store will be mailed to the local
2266 root:
2267 action=add ftp_$1 $0; \
2269 set ftp_$1 1800 (report ftp_$1 /bin/mail root@localhost)
2270 Create a subroutine for weeding out comment lines from the input list,
2272 and use this subroutine for removing comment lines from the event store
2273 of the context C1:
2274 action=eval %funcptr ( sub { my(@buf) = split(/\n/, $_[0]); \
2276 my(@ret) = grep(!/^#/, @buf); return @ret; } ); \
2277 copy C1 %in; call %out %funcptr %in; fill C1 %out
2278 The following action list achieves the same goal as the previous action
2280 list with while and if actions:
2281 action=getsize %size C1; while %size ( shift C1 %event; \
2283 lcall %nocomment %event -> ( sub { $_[0] !~ /^#/ } ); \
2284 if %nocomment ( add C1 %event ); \
2285 lcall %size %size -> ( sub { $_[0]-1; } ) )
2286
2288 As already noted, SEC context expressions and action lists may contain
2289 parentheses which are used for grouping and masking purposes. When SEC
2290 parses its configuration, it checks whether parentheses in context
2291 expressions and action lists are balanced (i.e., whether each parenthe‐
2292 sis has a counterpart), since unbalanced parentheses introduce ambigu‐
2293 ity. This can cause SEC to reject some legitimate constructs, e.g.,
2294 action=eval %o (print ")";)
2296 is considered an invalid action list (however, note that
2298 action=eval %o (print "()";)
2299 would be passed by SEC, since now parentheses are balanced). In order
2300 to avoid such parsing errors, each parenthesis without a counterpart
2301 must be masked with a backslash (the backslash will be removed by SEC
2302 during configuration file parsing). For example, the above action could
2303 be written as
2304 action=eval %o (print "\)";)
2306
2308 This section provides a detailed discussion of SEC rule types.
2309 SINGLE RULE
2311 The Single rule immediately executes an action list when an event has
2312 matched the rule. An event matches the rule if the pattern matches the
2313 event and the context expression (if given) evaluates TRUE.
2314 The Single rule supports the following fields:
2316 type fixed to Single (value is case insensitive, so single or sIngLe
2318 can be used instead).
2319 continue (optional)
2321 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
2322 <label>, values are case insensitive).
2323 ptype pattern type (value is case insensitive).
2325 pattern
2327 pattern.
2328 varmap (optional)
2330 variable map.
2331 context (optional)
2333 context expression.
2334 desc operation description string.
2336 action action list.
2338 rem (optional, may appear more than once)
2340 remarks and comments.
2341 Note that match variables may be used in context, desc, and action
2343 fields. Also note that this rule does not start an event correlation
2344 operation, and the desc field is merely used for setting the %s action
2345 list variable.
2346 Examples:
2348 type=single
2350 continue=takenext
2351 ptype=regexp
2352 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session opened
2353 desc=ftp session opened for ristov2 pid $1
2354 action=create ftp_$1
2355 type=single
2357 continue=takenext
2358 ptype=regexp
2359 pattern=ftpd\[(\d+)\]:
2360 context=ftp_$1
2361 desc=ftp session event for ristov2 pid $1
2362 action=add ftp_$1 $0; set ftp_$1 1800 \
2363 (report ftp_$1 /bin/mail root@localhost)
2364 type=single
2366 ptype=regexp
2367 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session closed
2368 desc=ftp session closed for ristov2 pid $1
2369 action=report ftp_$1 /bin/mail root@localhost; \
2370 delete ftp_$1
2371 This ruleset is created for monitoring the ftpd log file. The first
2373 rule creates the context ftp_<pid> when someone connects from host ris‐
2374 tov2 over FTP and establishes a new ftp session (the session is identi‐
2375 fied by the PID of the process which has been created for handling this
2376 session). The second rule adds all further log file lines for the ses‐
2377 sion <pid> to the event store of the context ftp_<pid> (before adding a
2378 line, the rule checks if the context exists). After adding a line, the
2379 rule extends context's lifetime for 30 minutes and sets the action list
2380 that will be executed when the context expires. The third rule mails
2381 collected log file lines to root@localhost when the session <pid> is
2382 closed. Collected lines will also be mailed when the session <pid> has
2383 been inactive for 30 minutes (no log file lines observed for that ses‐
2384 sion).
2385 Note that the log file line that has matched the first rule is also
2387 matched against the second rule (since the first rule has the continue
2388 field set to TakeNext). Since the second rule always matches this
2389 line, it will become the first line in the event store of ftp_<pid>.
2390 The second rule has also its continue field set to TakeNext, since oth‐
2391 erwise no log file lines would reach the third rule.
2392 SINGLEWITHSCRIPT RULE
2394 The SingleWithScript rule forks a process for executing an external
2395 program when an event has matched the rule. The names of all currently
2396 existing contexts are written to the standard input of the program.
2397 After the program has been forked, the rule matching continues immedi‐
2398 ately, and the program status will be checked periodically until the
2399 program exits. If the program returns 0 exit status, the action list
2400 defined by the action field is executed; otherwise the action list
2401 defined by the action2 field is executed (if given).
2402 The SingleWithScript rule supports the following fields:
2404 type fixed to SingleWithScript (value is case insensitive).
2406 continue (optional)
2408 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
2409 <label>, values are case insensitive).
2410 ptype pattern type (value is case insensitive).
2412 pattern
2414 pattern.
2415 varmap (optional)
2417 variable map.
2418 context (optional)
2420 context expression.
2421 script an external program.
2423 desc operation description string.
2425 action action list.
2427 action2 (optional)
2429 action list.
2430 rem (optional, may appear more than once)
2432 remarks and comments.
2433 Note that match variables may be used in context, script, desc, action,
2435 and action2 fields. Also note that this rule does not start an event
2436 correlation operation, and the desc field is merely used for setting
2437 the %s action list variable.
2438 Examples:
2440 type=SingleWithScript
2442 ptype=RegExp
2443 pattern=interface ([\d.]+) down
2444 script=/bin/ping -c 3 -q $1
2445 desc=Check if $1 responds to ping
2446 action=logonly Interface $1 reported down, but is pingable
2447 action2=pipe '%t: Interface $1 is down' /bin/mail root@localhost
2448 When "interface <ipaddress> down" line appears in input, the rule
2450 checks if <ipaddress> responds to ping. If <ipaddress> is pingable, the
2451 message "Interface <ipaddress> reported down, but is pingable" is
2452 logged; otherwise an e-mail warning containing a human-readable time‐
2453 stamp is sent to root@localhost.
2454 SINGLEWITHSUPPRESS RULE
2456 The SingleWithSuppress rule runs event correlation operations for fil‐
2457 tering repeated instances of the same event during T seconds. The value
2458 of T is defined by the window field.
2459 When an event has matched the rule, SEC evaluates the operation
2461 description string given with the desc field. If the operation for the
2462 given string and rule does not exist, SEC will create it with the life‐
2463 time of T seconds, and the operation immediately executes an action
2464 list. If the operation exists, it consumes the matching event without
2465 any action.
2466 The SingleWithSuppress rule supports the following fields:
2468 type fixed to SingleWithSuppress (value is case insensitive).
2470 continue (optional)
2472 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
2473 <label>, values are case insensitive).
2474 ptype pattern type (value is case insensitive).
2476 pattern
2478 pattern.
2479 varmap (optional)
2481 variable map.
2482 context (optional)
2484 context expression.
2485 desc operation description string.
2487 action action list.
2489 window event correlation window size (value is an integer constant).
2491 rem (optional, may appear more than once)
2493 remarks and comments.
2494 Note that match variables may be used in context, desc, and action
2496 fields.
2497 Examples:
2499 type=SingleWithSuppress
2501 ptype=RegExp
2502 pattern=(\S+): [fF]ile system full
2503 desc=File system $1 full
2504 action=pipe '%t: %s' /bin/mail root@localhost
2505 window=900
2506 This rule runs event correlation operations for processing "file system
2508 full" syslog messages, e.g.,
2509 Dec 16 14:26:09 test ufs: [ID 845546 kern.notice] NOTICE: alloc: /var:
2511 file system full
2512 When the first message for a file system is observed, an operation is
2514 created which sends an e-mail warning about this file system to
2515 root@localhost. The operation will then run for 900 seconds and
2516 silently consume further messages for the *same* file system. However,
2517 if a message for a different file system is observed, another operation
2518 will be started which sends a warning to root@localhost again (since
2519 the desc field contains the $1 match variable which evaluates to the
2520 file system name).
2521 PAIR RULE
2523 The Pair rule runs event correlation operations for processing event
2524 pairs during T seconds. The value of T is defined by the window field.
2525 Default value is 0 which means infinity.
2526 When an event has matched the conditions defined by the pattern and
2528 context field, SEC evaluates the operation description string given
2529 with the desc field. If the operation for the given string and rule
2530 exists, it consumes the matching event without any action. If the oper‐
2531 ation does not exist, SEC will create it with the lifetime of T sec‐
2532 onds, and the operation immediately executes an action list defined by
2533 the action field. SEC will also copy the match conditions given with
2534 the pattern2 and context2 field into the operation, and substitute
2535 match variables with their values in copied conditions.
2536 If the event does not match conditions defined by the pattern and con‐
2538 text field, SEC will check the match conditions of all operations
2539 started by the given rule. Each matching operation executes the action
2540 list given with the action2 field and finishes.
2541 If match variables are set when the operation matches an event, they
2543 are made available as $-prefixed match variables in context2, desc2,
2544 and action2 fields of the rule definition. For example, if pattern2
2545 field is a regular expression, then $1 in the desc2 field is set by
2546 pattern2. In order to access match variables set by pattern, %-pre‐
2547 fixed match variables have to be used in context2, desc2, and action2
2548 fields. For example, if pattern and pattern2 are regular expressions,
2549 then %1 in the desc2 field refers to the value set by the first capture
2550 group in pattern (i.e., it has the same value as $1 in the desc field).
2551 The Pair rule supports the following fields:
2553 type fixed to Pair (value is case insensitive).
2555 continue (optional)
2557 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
2558 <label>, values are case insensitive). Specifies the point-of-
2559 continue after a match by pattern and context.
2560 ptype pattern type for pattern (value is case insensitive).
2562 pattern
2564 pattern.
2565 varmap (optional)
2567 variable map for pattern.
2568 context (optional)
2570 context expression, evaluated together with pattern.
2571 desc operation description string.
2573 action action list.
2575 continue2 (optional)
2577 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
2578 <label>, values are case insensitive). Specifies the point-of-
2579 continue after a match by pattern2 and context2.
2580 ptype2 pattern type for pattern2 (value is case insensitive).
2582 pattern2
2584 pattern.
2585 varmap2 (optional)
2587 variable map for pattern2.
2588 context2 (optional)
2590 context expression, evaluated together with pattern2.
2591 desc2 format string that sets the %s variable for action2.
2593 action2
2595 action list.
2596 window (optional)
2598 event correlation window size (value is an integer constant).
2599 rem (optional, may appear more than once)
2601 remarks and comments.
2602 Note that match variables may be used in context, desc, action, pat‐
2604 tern2, context2, desc2, and action2 fields.
2605 Examples:
2607 type=Pair
2609 ptype=RegExp
2610 pattern=kernel: nfs: server (\S+) not responding, still trying
2611 desc=Server $1 is not responding
2612 action=pipe '%t: %s' /bin/mail root@localhost
2613 ptype2=SubStr
2614 pattern2=kernel: nfs: server $1 OK
2615 desc2=Server $1 is responding again
2616 action2=logonly
2617 window=3600
2618 This rule runs event correlation operations for processing NFS "server
2620 not responding" and "server OK" syslog messages, e.g.,
2621 Dec 18 22:39:48 test kernel: nfs: server box1 not responding, still
2623 trying
2624 Dec 18 22:42:27 test kernel: nfs: server box1 OK
2625 When the "server not responding" message for an NFS server is observed,
2627 an operation is created for this server which sends an e-mail warning
2628 about the server to root@localhost. The operation will then run for
2629 3600 seconds and silently consume further "server not responding" mes‐
2630 sages for the same server. If this operation observes "server OK" mes‐
2631 sage for the *same* server, it will log the message "Server <server‐
2632 name> is responding again" and finish.
2633 For example, if SEC observes the following event at 22:39:48
2635 Dec 18 22:39:48 test kernel: nfs: server box1 not responding, still
2637 trying
2638 an event correlation operation is created for server box1 which issues
2640 an e-mail warning about this server immediately. After that, the opera‐
2641 tion will run for 3600 seconds (until 23:39:48), waiting for an event
2642 which would contain the substring "kernel: nfs: server box1 OK"
2643 (because the pattern2 field contains the $1 match variable which evalu‐
2644 ates to the server name).
2645 If any further error messages appear for server box1 during the 3600
2647 second lifetime of the operation, e.g.,
2648 Dec 18 22:40:28 test kernel: nfs: server box1 not responding, still
2650 trying
2651 Dec 18 22:41:09 test kernel: nfs: server box1 not responding, still
2652 trying
2653 these messages will be silently consumed by the operation. If before
2655 its expiration the operation observes an event which contains the sub‐
2656 string "kernel: nfs: server box1 OK", e.g.,
2657 Dec 18 22:42:27 test kernel: nfs: server box1 OK
2659 the operation will log the message "Server box1 is responding again"
2661 and terminate immediately. If no such message appears during the 3600
2662 second lifetime of the operation, the operation will expire without
2663 taking any action. Please note that if the window field would be either
2664 removed from the rule definition or set to 0, the operation would never
2665 silently expire, but would terminate only after observing an event
2666 which contains the substring "kernel: nfs: server box1 OK".
2667 If the above rule is modified in the following way
2669 type=Pair
2671 ptype=RegExp
2672 pattern=^([[:alnum:]: ]+) \S+ kernel: nfs: server (\S+) not responding,
2673 still trying
2674 desc=Server $2 is not responding
2675 action=logonly
2676 ptype2=RegExp
2677 pattern2=^([[:alnum:]: ]+) \S+ kernel: nfs: server $2 OK
2678 desc2=Server %2 was not accessible from %1 to $1
2679 action2=pipe '%s' /bin/mail root@localhost
2680 window=86400
2681 this rule will run event correlation operations which report NFS server
2683 downtime to root@localhost via e-mail, provided that downtime does not
2684 exceed 24 hours (86400 seconds).
2685 For example, if SEC observes the following event
2687 Dec 18 23:01:17 test kernel: nfs: server box.test not responding, still
2689 trying
2690 then the rule matches this event, sets $1 match variable to "Dec 18
2692 23:01:17" and $2 to "box.test", and creates an event correlation opera‐
2693 tion for server box.test. This operation will start its work by log‐
2694 ging the message "Server box.test is not responding", and will then run
2695 for 86400 seconds, waiting for an event which would match the regular
2696 expression
2697 ^([[:alnum:]: ]+) \S+ kernel: nfs: server box\.test OK
2699 Note that this expression was created from the regular expression tem‐
2701 plate in the pattern2 field by substituting the match variable $2 with
2702 its value. However, since the string "box.test" contains the dot (.)
2703 character which is a regular expression metacharacter, the dot is
2704 masked with the backslash in the regular expression.
2705 Suppose SEC will then observe the event
2707 Dec 18 23:09:54 test kernel: nfs: server box.test OK
2709 This event matches the above regular expression which is used by the
2711 operation running for server box.test. Also, the regular expression
2712 match sets the $1 variable to "Dec 18 23:09:54" and unsets the $2 vari‐
2713 able. In order to refer to their original values when the operation was
2714 created, %1 and %2 match variables have to be used in the desc2 field
2715 (%1 equals to "Dec 18 23:01:17" and %2 equals to "box.test"). There‐
2716 fore, the operation will send the e-mail message "Server box.test was
2717 not accessible from Dec 18 23:01:17 to Dec 18 23:09:54" to root@local‐
2718 host, and will terminate immediately.
2719 PAIRWITHWINDOW RULE
2721 The PairWithWindow rule runs event correlation operations for process‐
2722 ing event pairs during T seconds. The value of T is defined by the win‐
2723 dow field.
2724 When an event has matched the conditions defined by the pattern and
2726 context field, SEC evaluates the operation description string given
2727 with the desc field. If the operation for the given string and rule
2728 exists, it consumes the matching event without any action. If the oper‐
2729 ation does not exist, SEC will create it with the lifetime of T sec‐
2730 onds. SEC will also copy the match conditions given with the pattern2
2731 and context2 field into the operation, and substitute match variables
2732 with their values in copied conditions.
2733 If the event does not match conditions defined by the pattern and con‐
2735 text field, SEC will check the match conditions of all operations
2736 started by the given rule. Each matching operation executes the action
2737 list given with the action2 field and finishes. If the operation has
2738 not observed a matching event by the end of its lifetime, it executes
2739 the action list given with the action field before finishing.
2740 If match variables are set when the operation matches an event, they
2742 are made available as $-prefixed match variables in context2, desc2,
2743 and action2 fields of the rule definition. For example, if pattern2
2744 field is a regular expression, then $1 in the desc2 field is set by
2745 pattern2. In order to access match variables set by pattern, %-pre‐
2746 fixed match variables have to be used in context2, desc2, and action2
2747 fields. For example, if pattern and pattern2 are regular expressions,
2748 then %1 in the desc2 field refers to the value set by the first capture
2749 group in pattern (i.e., it has the same value as $1 in the desc field).
2750 The PairWithWindow rule supports the following fields:
2752 type fixed to PairWithWindow (value is case insensitive).
2754 continue (optional)
2756 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
2757 <label>, values are case insensitive). Specifies the point-of-
2758 continue after a match by pattern and context.
2759 ptype pattern type for pattern (value is case insensitive).
2761 pattern
2763 pattern.
2764 varmap (optional)
2766 variable map for pattern.
2767 context (optional)
2769 context expression, evaluated together with pattern.
2770 desc operation description string.
2772 action action list.
2774 continue2 (optional)
2776 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
2777 <label>, values are case insensitive). Specifies the point-of-
2778 continue after a match by pattern2 and context2.
2779 ptype2 pattern type for pattern2 (value is case insensitive).
2781 pattern2
2783 pattern.
2784 varmap2 (optional)
2786 variable map for pattern2.
2787 context2 (optional)
2789 context expression, evaluated together with pattern2.
2790 desc2 format string that sets the %s variable for action2.
2792 action2
2794 action list.
2795 window event correlation window size (value is an integer constant).
2797 rem (optional, may appear more than once)
2799 remarks and comments.
2800 Note that match variables may be used in context, desc, action, pat‐
2802 tern2, context2, desc2, and action2 fields.
2803 Examples:
2805 type=PairWithWindow
2807 ptype=RegExp
2808 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
2809 desc=User $1 has been unable to log in from $2 over SSH during 1 minute
2810 action=pipe '%t: %s' /bin/mail root@localhost
2811 ptype2=RegExp
2812 pattern2=sshd\[\d+\]: Accepted .+ for $1 from $2 port \d+ ssh2
2813 desc2=SSH login successful for %1 from %2 after initial failure
2814 action2=logonly
2815 window=60
2816 This rule runs event correlation operations for processing SSH login
2818 events, e.g.,
2819 Dec 27 19:00:24 test sshd[10526]: Failed password for risto from
2821 10.1.2.7 port 52622 ssh2
2822 Dec 27 19:00:27 test sshd[10526]: Accepted password for risto from
2823 10.1.2.7 port 52622 ssh2
2824 When an SSH login failure is observed for a user name and a source IP
2826 address, an operation is created for this user name and IP address com‐
2827 bination which will expect a successful login for the *same* user name
2828 and *same* IP address during 60 seconds. If the user will not log in
2829 from the same IP address during 60 seconds, the operation will send an
2830 e-mail warning to root@localhost before finishing, otherwise it will
2831 log the message "SSH login successful for <username> from <ipaddress>
2832 after initial failure" and finish.
2833 Suppose the following events are generated by an SSH daemon, and each
2835 event timestamp reflects the time SEC observes the event:
2836 Dec 30 13:02:01 test sshd[30517]: Failed password for risto from
2838 10.1.2.7 port 42172 ssh2
2839 Dec 30 13:02:30 test sshd[30810]: Failed password for root from
2840 192.168.1.104 port 46125 ssh2
2841 Dec 30 13:02:37 test sshd[30517]: Failed password for risto from
2842 10.1.2.7 port 42172 ssh2
2843 Dec 30 13:02:59 test sshd[30810]: Failed password for root from
2844 192.168.1.104 port 46125 ssh2
2845 Dec 30 13:03:04 test sshd[30810]: Accepted password for root from
2846 192.168.1.104 port 46125 ssh2
2847 When the first event is observed at 13:02:01, an operation is started
2849 for user risto and IP address 10.1.2.7 which will expect a successful
2850 login for risto from 10.1.2.7. The operation will run for 60 seconds,
2851 waiting for an event which would match the regular expression
2852 sshd\[\d+\]: Accepted .+ for risto from 10\.1\.2\.7 port \d+ ssh2
2854 Note that this expression was created from the regular expression tem‐
2856 plate in the pattern2 field by substituting match variables $1 and $2
2857 with their values. However, since the value of $2 contains the dot (.)
2858 characters which are regular expression metacharacters, each dot is
2859 masked with the backslash in the regular expression.
2860 When the second event is observed at 13:02:30, another operation is
2862 started for user root and IP address 192.168.1.104 which will expect
2863 root to log in successfully from 192.168.1.104. This operation will run
2864 for 60 seconds, waiting for an event matching the regular expression
2865 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2867 The third event at 13:02:37 represents a second login failure for user
2869 risto and IP address 10.1.2.7, and is silently consumed by the first
2870 operation. Likewise, the fourth event at 13:02:59 is silently consumed
2871 by the second operation. The first operation will run until 13:03:01
2872 and then expire without seeing a successful login for risto from
2873 10.1.2.7. Before terminating, the operation will send an e-mail warning
2874 to root@localhost that user risto has not managed to log in from
2875 10.1.2.7 during one minute. At 13:03:04, the second operation will
2876 observe an event which matches its regular expression
2877 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2879 After seeing this event, the operation will log the message "SSH login
2881 successful for root from 192.168.1.104 after initial failure" and ter‐
2882 minate immediately. Please note that the match by the regular expres‐
2883 sion
2884 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2886 sets the $1 match variable to 1 and unsets $2. Therefore, the %1 and %2
2888 match variables have to be used in the desc2 field, in order to refer
2889 to the original values of $1 (root) and $2 (192.168.1.104) when the
2890 operation was created.
2891 SINGLEWITHTHRESHOLD RULE
2893 The SingleWithThreshold rule runs event correlation operations for
2894 counting repeated instances of the same event during T seconds, and
2895 taking an action if N events are observed. The values of T and N are
2896 defined by the window and thresh field, respectively.
2897 When an event has matched the rule, SEC evaluates the operation
2899 description string given with the desc field. If the operation for the
2900 given string and rule does not exist, SEC will create it with the life‐
2901 time of T seconds. The operation will memorize the occurrence time of
2902 the event (current time as returned by the time(2) system call), and
2903 compare the number of memorized occurrence times with the threshold N.
2904 If the operation has observed N events, it executes the action list
2905 defined by the action field, and consumes all further matching events
2906 without any action. If the rule has an optional action list defined
2907 with the action2 field, the operation will execute it before finishing,
2908 provided that the action list given with action has been previously
2909 executed by the operation. Note that a sliding window is employed for
2910 event counting -- if the operation has observed less than N events by
2911 the end of its lifetime, it drops occurrence times which are older than
2912 T seconds, and extends its lifetime for T seconds from the earliest
2913 remaining occurrence time. If there are no remaining occurrence times,
2914 the operation finishes without executing an action list.
2915 The SingleWithThreshold rule supports the following fields:
2917 type fixed to SingleWithThreshold (value is case insensitive).
2919 continue (optional)
2921 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
2922 <label>, values are case insensitive).
2923 ptype pattern type (value is case insensitive).
2925 pattern
2927 pattern.
2928 varmap (optional)
2930 variable map.
2931 context (optional)
2933 context expression.
2934 desc operation description string.
2936 action action list.
2938 action2 (optional)
2940 action list.
2941 window event correlation window size (value is an integer constant).
2943 thresh counting threshold (value is an integer constant).
2945 rem (optional, may appear more than once)
2947 remarks and comments.
2948 Note that match variables may be used in context, desc, action, and
2950 action2 fields.
2951 Examples:
2953 type=SingleWithThreshold
2955 ptype=RegExp
2956 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
2957 desc=Three SSH login failures within 1m for user $1
2958 action=pipe '%t: %s' /bin/mail root@localhost
2959 window=60
2960 thresh=3
2961 This rule runs event correlation operations for counting the number of
2963 SSH login failure events. Each operation counts events for one user
2964 name, and if the operation has observed three login failures within 60
2965 seconds, it sends an e-mail warning to root@localhost.
2966 Suppose the following events are generated by an SSH daemon, and each
2968 event timestamp reflects the time SEC observes the event:
2969 Dec 28 01:42:21 test sshd[28132]: Failed password for risto from
2971 10.1.2.7 port 42172 ssh2
2972 Dec 28 01:43:10 test sshd[28132]: Failed password for risto from
2973 10.1.2.7 port 42172 ssh2
2974 Dec 28 01:43:29 test sshd[28132]: Failed password for risto from
2975 10.1.2.7 port 42172 ssh2
2976 Dec 28 01:44:00 test sshd[28149]: Failed password for risto2 from
2977 10.1.2.7 port 42176 ssh2
2978 Dec 28 01:44:03 test sshd[28211]: Failed password for risto from
2979 10.1.2.7 port 42192 ssh2
2980 Dec 28 01:44:07 test sshd[28211]: Failed password for risto from
2981 10.1.2.7 port 42192 ssh2
2982 When the first event is observed at 01:42:21, a counting operation is
2984 started for user risto, with its event correlation window ending at
2985 01:43:21. Since by 01:43:21 two SSH login failures for user risto have
2986 occurred, the threshold condition remains unsatisfied for the opera‐
2987 tion. Therefore, the beginning of its event correlation window will be
2988 moved to 01:43:10 (the occurrence time of the second event), leaving
2989 the first event outside the window. At 01:44:00, another counting
2990 operation is started for user risto2. The threshold condition for the
2991 first operation will become satisfied at 01:44:03 (since the operation
2992 has seen three login failure events for user risto within 60 seconds),
2993 and thus an e-mail warning will be issued. Finally, the event occurring
2994 at 01:44:07 will be consumed silently by the first operation (the oper‐
2995 ation will run until 01:44:10). Since there will be no further login
2996 failure events for user risto2, the second operation will exist until
2997 01:45:00 without taking any action.
2998 SINGLEWITH2THRESHOLDS RULE
3000 The SingleWith2Thresholds rule runs event correlation operations which
3001 take action if N1 events have been observed in the window of T1 sec‐
3002 onds, and then at most N2 events will be observed in the window of T2
3003 seconds. The values of T1, N1, T2, and N2 are defined by the window,
3004 thresh, window2, and thresh2 field, respectively.
3005 When an event has matched the rule, SEC evaluates the operation
3007 description string given with the desc field. If the operation for the
3008 given string and rule does not exist, SEC will create it with the life‐
3009 time of T1 seconds. The operation will memorize the occurrence time of
3010 the event (current time as returned by the time(2) system call), and
3011 compare the number of memorized occurrence times with the threshold N1.
3012 If the operation has observed N1 events, it executes the action list
3013 defined by the action field, and starts another counting round for T2
3014 seconds. If no more than N2 events have been observed by the end of
3015 the window, the operation executes the action list defined by the
3016 action2 field and finishes. Note that both windows are sliding -- the
3017 first window slides like the window of the SingleWithThreshold opera‐
3018 tion, while the beginning of the second window is moved to the second
3019 earliest memorized event occurrence time when the threshold N2 is vio‐
3020 lated.
3021 The SingleWith2Thresholds rule supports the following fields:
3023 type fixed to SingleWith2Thresholds (value is case insensitive).
3025 continue (optional)
3027 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
3028 <label>, values are case insensitive).
3029 ptype pattern type (value is case insensitive).
3031 pattern
3033 pattern.
3034 varmap (optional)
3036 variable map.
3037 context (optional)
3039 context expression.
3040 desc operation description string.
3042 action action list.
3044 window event correlation window size (value is an integer constant).
3046 thresh counting threshold.
3048 desc2 format string that sets the %s variable for action2.
3050 action2
3052 action list.
3053 window2
3055 event correlation window size (value is an integer constant).
3056 thresh2
3058 counting threshold.
3059 rem (optional, may appear more than once)
3061 remarks and comments.
3062 Note that match variables may be used in context, desc, action, desc2,
3064 and action2 fields.
3065 Examples:
3067 type=SingleWith2Thresholds
3069 ptype=RegExp
3070 pattern=(\S+): %SYS-3-CPUHOG
3071 desc=Router $1 CPU overload
3072 action=pipe '%t: %s' /bin/mail root@localhost
3073 window=300
3074 thresh=2
3075 desc2=Router $1 CPU load has been normal for 1h
3076 action2=logonly
3077 window2=3600
3078 thresh2=0
3079 When a SYS-3-CPUHOG syslog message is received from a router, the rule
3081 starts a counting operation for this router which sends an e-mail warn‐
3082 ing to root@localhost if another such message is received from the same
3083 router within 300 seconds. After sending the warning, the operation
3084 will continue to run until no SYS-3-CPUHOG syslog messages have been
3085 received from the router for 3600 seconds. When this condition becomes
3086 satisfied, the operation will log the message "Router <routername> CPU
3087 load has been normal for 1h" and finish.
3088 Suppose the following events are generated by a router, and each event
3090 timestamp reflects the time SEC observes the event:
3091 Dec 30 12:23:25 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3093 Dec 30 12:25:38 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3094 Dec 30 12:28:53 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3095 When the first event is observed at 12:23:25, a counting operation is
3097 started for router Router1. The appearance of the second event at
3098 12:25:38 fulfills the threshold condition given with the thresh and
3099 window fields (two events have been observed within 300 seconds).
3100 Therefore, the operation will send an e-mail warning about the CPU
3101 overload of Router1 to root@localhost.
3102 After that, the operation will start another counting round, expecting
3104 to see no SYS-3-CPUHOG events (since thresh2=0) for Router1 during the
3105 following 3600 seconds (the beginning of the operation's event correla‐
3106 tion window will be moved to 12:25:38 for the second counting round).
3107 Since the appearance of the third event at 12:28:53 violates the
3108 threshold condition given with the thresh2 and window2 fields, the
3109 beginning of the event correlation window will be moved to 12:28:53.
3110 Since there will be no further SYS-3-CPUHOG messages for Router1, the
3111 operation will run until 13:28:53 and then expire, logging the message
3112 "Router Router1 CPU load has been normal for 1h" before finishing.
3113 EVENTGROUP RULE
3115 The EventGroup rule runs event correlation operations for counting
3116 repeated instances of N different events e1,...,eN during T seconds,
3117 and taking an action if threshold conditions c1,...,cN for *all* events
3118 are satisfied (i.e., for each event eK there are at least cK event
3119 instances in the window). Note that the event correlation window of
3120 the EventGroup operation is sliding like the window of the SingleWith‐
3121 Threshold operation.
3122 Event e1 is described with the pattern and context field, event e2 is
3124 described with the pattern2 and context2 field, etc. The values for N
3125 and T are defined by the type and window field, respectively. The value
3126 for c1 is given with the thresh field, the value for c2 is given with
3127 the thresh2 field, etc. Values for N and c1,...,cN default to 1.
3128 In order to match an event with the rule, pattern and context fields
3130 are evaluated first. If they don't match the event, then pattern2 and
3131 context2 are evaluated, etc. If all N conditions are tried without a
3132 success, the event doesn't match the rule.
3133 When an event has matched the rule, SEC evaluates the operation
3135 description string given with the desc field. If the operation for the
3136 given string and rule does not exist, SEC will create it with the life‐
3137 time of T seconds. The operation will memorize the occurrence time of
3138 the event (current time as returned by the time(2) system call), and
3139 compare the number of memorized occurrence times for each eK with the
3140 threshold cK (i.e., the number of observed instances of eK is compared
3141 with the threshold cK). If all threshold confitions are satisfied, the
3142 operation executes the action list defined by the action field, and
3143 consumes all further matching events without re-executing the action
3144 list if the multact field is set to No (this is the default). However,
3145 if multact is set to Yes, the operation will re-evaluate the threshold
3146 conditions on every further matching event, re-executing the action
3147 list given with the action field if all conditions are satisfied, and
3148 sliding the event correlation window forward when the window is about
3149 to expire (if no events remain in the window, the operation will fin‐
3150 ish).
3151 If the rule definition has an optional action list defined with the
3153 countK field for event eK, the operation executes it every time an
3154 instance of eK is observed (even if multact is set to No and the opera‐
3155 tion has already executed the action list given with action). If the
3156 action list contains match variables, they are substituted before
3157 *each* execution with values from matching the current instance of eK.
3158 If the rule definition has an optional action list defined with the
3160 init field, the operation executes it immediately after the operation
3161 has been created.
3162 If the rule definition has an optional action list defined with the end
3164 field, the operation executes it immediately before the operation fin‐
3165 ishes. Note that this action list is *not* executed when the operation
3166 is terminated with the reset action.
3167 If the rule definition has an optional action list defined with the
3169 slide field, the operation executes it immediately after the event cor‐
3170 relation window has slidden forward. However, note that moving the
3171 window with the setwpos action will *not* trigger the execution.
3172 The EventGroup rule supports the following fields:
3174 type EventGroup[N] (value is case insensitive, N defaults to 1).
3176 continue (optional)
3178 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
3179 <label>, values are case insensitive). Specifies the point-of-
3180 continue after a match by pattern and context.
3181 ptype pattern type for pattern (value is case insensitive).
3183 pattern
3185 pattern.
3186 varmap (optional)
3188 variable map for pattern.
3189 context (optional)
3191 context expression, evaluated together with pattern.
3192 count (optional)
3194 action list for execution after a match by pattern and context.
3195 thresh (optional)
3197 counting threshold for events matched by pattern and context
3198 (value is an integer constant, default is 1).
3199 ...
3201 continueN (optional)
3203 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
3204 <label>, values are case insensitive). Specifies the point-of-
3205 continue after a match by patternN and contextN.
3206 ptypeN pattern type for patternN (value is case insensitive).
3208 patternN
3210 pattern.
3211 varmapN (optional)
3213 variable map for patternN.
3214 contextN (optional)
3216 context expression, evaluated together with patternN.
3217 countN (optional)
3219 action list for execution after a match by patternN and con‐
3220 textN.
3221 threshN (optional)
3223 counting threshold for events matched by patternN and contextN
3224 (value is an integer constant, default is 1).
3225 desc operation description string.
3227 action action list.
3229 init (optional)
3231 action list.
3232 end (optional)
3234 action list.
3235 slide (optional)
3237 action list.
3238 multact (optional)
3240 Yes or No (values are case insensitive, default is No).
3241 window event correlation window size (value is an integer constant).
3243 rem (optional, may appear more than once)
3245 remarks and comments.
3246 Note that match variables may be used in context*, count*, desc,
3248 action, init, end, and slide fields.
3249 Examples:
3251 The following example rule cross-correlates iptables events, Apache web
3253 server access log messages with 4xx response codes, and SSH login fail‐
3254 ure events:
3255 type=EventGroup3
3257 ptype=RegExp
3258 pattern=sshd\[\d+\]: Failed .+ for (?:invalid user )?\S+ from ([\d.]+)
3259 port \d+ ssh2
3260 thresh=2
3261 ptype2=RegExp
3262 pattern2=^([\d.]+) \S+ \S+ \[.+?\] ".+? HTTP\/[\d.]+" 4\d+
3263 thresh2=3
3264 ptype3=RegExp
3265 pattern3=kernel: iptables:.* SRC=([\d.]+)
3266 thresh3=5
3267 desc=Repeated probing from host $1
3268 action=pipe '%t: %s' /bin/mail root@localhost
3269 window=120
3270 The rule starts an event correlation operation for an IP address if SSH
3272 login failure event, iptables event, or Apache 4xx event is observed
3273 for that IP address. The operation sends an e-mail warning to
3274 root@localhost if within 120 seconds three threshold conditions are
3275 satisfied for the IP address it tracks -- (1) at least two SSH login
3276 failure events have occurred for this client IP, (2) at least three
3277 Apache 4xx events have occured for this client IP, (3) at least five
3278 iptables events have been observed for this source IP.
3279 Suppose the following events occur, and each event timestamp reflects
3281 the time SEC observes the event:
3282 192.168.1.104 - - [05/Jan/2014:01:11:22 +0200] "GET /test.html
3284 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3285 Gecko/20100101 Firefox/26.0"
3286 Jan 5 01:12:52 localhost kernel: iptables: IN=eth0 OUT=
3287 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3288 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=48422 DF
3289 PROTO=TCP SPT=46351 DPT=21 WINDOW=29200 RES=0x00 SYN URGP=0
3290 Jan 5 01:12:53 localhost kernel: iptables: IN=eth0 OUT=
3291 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3292 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=48423 DF
3293 PROTO=TCP SPT=46351 DPT=21 WINDOW=29200 RES=0x00 SYN URGP=0
3294 Jan 5 01:13:01 localhost kernel: iptables: IN=eth0 OUT=
3295 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3296 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=20048 DF
3297 PROTO=TCP SPT=44963 DPT=23 WINDOW=29200 RES=0x00 SYN URGP=0
3298 Jan 5 01:13:02 localhost kernel: iptables: IN=eth0 OUT=
3299 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3300 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=20049 DF
3301 PROTO=TCP SPT=44963 DPT=23 WINDOW=29200 RES=0x00 SYN URGP=0
3302 Jan 5 01:13:08 localhost kernel: iptables: IN=eth0 OUT=
3303 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3304 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=36362 DF
3305 PROTO=TCP SPT=56918 DPT=25 WINDOW=29200 RES=0x00 SYN URGP=0
3306 Jan 5 01:13:09 localhost kernel: iptables: IN=eth0 OUT=
3307 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3308 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=36363 DF
3309 PROTO=TCP SPT=56918 DPT=25 WINDOW=29200 RES=0x00 SYN URGP=0
3310 192.168.1.104 - - [05/Jan/2014:01:13:51 +0200] "GET /test.html
3311 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3312 Gecko/20100101 Firefox/26.0"
3313 192.168.1.104 - - [05/Jan/2014:01:13:54 +0200] "GET /test.html
3314 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3315 Gecko/20100101 Firefox/26.0"
3316 192.168.1.104 - - [05/Jan/2014:01:14:00 +0200] "GET /login.html
3317 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3318 Gecko/20100101 Firefox/26.0"
3319 192.168.1.104 - - [05/Jan/2014:01:14:03 +0200] "GET /login.html
3320 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3321 Gecko/20100101 Firefox/26.0"
3322 192.168.1.104 - - [05/Jan/2014:01:14:03 +0200] "GET /login.html
3323 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3324 Gecko/20100101 Firefox/26.0"
3325 Jan 5 01:14:11 localhost sshd[1810]: Failed password for root from
3326 192.168.1.104 port 46125 ssh2
3327 Jan 5 01:14:12 localhost sshd[1810]: Failed password for root from
3328 192.168.1.104 port 46125 ssh2
3329 Jan 5 01:14:18 localhost sshd[1822]: Failed password for root from
3330 192.168.1.104 port 46126 ssh2
3331 Jan 5 01:14:19 localhost sshd[1822]: Failed password for root from
3332 192.168.1.104 port 46126 ssh2
3333 192.168.1.104 - - [05/Jan/2014:01:14:34 +0200] "GET /test.html
3334 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3335 Gecko/20100101 Firefox/26.0"
3336 The Apache 4xx event at 01:11:22 starts an event correlation operation
3338 for 192.168.1.104 which has the event correlation window of 120 sec‐
3339 onds, thus ending at 01:13:22. Between 01:12:52 and 01:13:09, six ipt‐
3340 ables events appear for 192.168.1.104, and the appearance of the fifth
3341 event at 01:13:08 fulfills the third threshold condition (within 120
3342 seconds, at least five iptables events have been observed).
3343 Since by 01:13:22 (the end of the event correlation window) no addi‐
3345 tional events have occurred, the first and second threshold condition
3346 remain unsatisfied. Therefore, the beginning of the event correlation
3347 window will be moved to 01:12:52 (the occurrence time of the earliest
3348 event which is at most 120 seconds old). As a result, the end of the
3349 window will move from 01:13:22 to 01:14:52. The only event which is
3350 left outside the window is the Apache 4xx event at 01:11:22, and thus
3351 the threshold condition for iptables events remains satisfied.
3352 Between 01:13:51 and 01:14:03, five Apache 4xx events occur, and the
3354 appearance of the third event at 01:14:00 fulfills the second threshold
3355 condition (within 120 seconds, at least three Apache 4xx events have
3356 been observed). These events are followed by four SSH login failure
3357 events which occur between 01:14:11 and 01:14:19. The appearance of the
3358 second event at 01:14:12 fulfills the first threshold condition (within
3359 120 seconds, at least two SSH login failure events have been observed).
3360 Since at this particular moment (01:14:12) the other two conditions are
3361 also fulfilled, the operation sends an e-mail warning about
3362 192.168.1.104 to root@localhost. After that, the operation silently
3363 consumes all further matching events for 192.168.1.104 until 01:14:52,
3364 and then terminates.
3365 Please note that if the above rule definition would contain multact=yes
3367 statement, the operation would continue sending e-mails at each match‐
3368 ing event after 01:14:12, provided that all threshold conditions are
3369 satisfied. Therefore, the operation would send three additional e-
3370 mails at 01:14:18, 01:14:19, and 01:14:34. Also, the operation would
3371 not terminate after its window ends at 01:14:52, but would rather slide
3372 the window forward and expect new events. At the occurence of any ipt‐
3373 ables, SSH login failure or Apache 4xx event for 192.168.1.104, the
3374 operation would produce a warning e-mail if all threshold conditions
3375 are fulfilled.
3376 The following example rule cross-correlates iptables events and SSH
3378 login events:
3379 type=EventGroup3
3381 ptype=regexp
3382 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
3383 varmap= user=1; ip=2
3384 count=alias OPER_$+{ip} LOGIN_FAILED_$+{user}_$+{ip}
3385 ptype2=regexp
3386 pattern2=sshd\[\d+\]: Accepted .+ for (\S+) from ([\d.]+) port \d+ ssh2
3387 varmap2= user=1; ip=2
3388 context2=LOGIN_FAILED_$+{user}_$+{ip}
3389 ptype3=regexp
3390 pattern3=kernel: iptables:.* SRC=([\d.]+)
3391 varmap3= ip=1
3392 desc=Client $+{ip} accessed a firewalled port and had difficulties with
3393 logging in
3394 action=pipe '%t: %s' /bin/mail root@localhost
3395 init=create OPER_$+{ip}
3396 slide=delete OPER_$+{ip}; reset 0
3397 end=delete OPER_$+{ip}
3398 window=120
3399 The rule starts an event correlation operation for an IP address if SSH
3401 login failure or iptables event was observed for that IP address. The
3402 operation exists for 120 seconds (since when the event correlation win‐
3403 dow slides forward, the operation terminates itself with the reset
3404 action as specified with the slide field). The operation sends an e-
3405 mail warning to root@localhost if within 120 seconds three threshold
3406 conditions are satisfied for the IP address it tracks -- (1) at least
3407 one iptables event has been observed for this source IP, (2) at least
3408 one SSH login failure has been observed for this client IP, (3) at
3409 least one successful SSH login has been observed for this client IP and
3410 for some user, provided that the operation has previously observed an
3411 SSH login failure for the same user and same client IP.
3412 Suppose the following events occur, and each event timestamp reflects
3414 the time SEC observes the event:
3415 Dec 27 19:00:06 test kernel: iptables: IN=eth0 OUT=
3417 MAC=00:13:72:8a:83:d2:00:1b:25:07:e2:1b:08:00 SRC=10.1.2.7 DST=10.2.5.5
3418 LEN=60 TOS=0x00 PREC=0x00 TTL=62 ID=1881 DF PROTO=TCP SPT=34342 DPT=23
3419 WINDOW=5840 RES=0x00 SYN URGP=0
3420 Dec 27 19:00:14 test sshd[10520]: Accepted password for root from
3421 10.1.2.7 port 52609 ssh2
3422 Dec 27 19:00:24 test sshd[10526]: Failed password for risto from
3423 10.1.2.7 port 52622 ssh2
3424 Dec 27 19:00:27 test sshd[10526]: Accepted password for risto from
3425 10.1.2.7 port 52622 ssh2
3426 The iptables event at 19:00:06 starts an event correlation operation
3428 for 10.1.2.7 which has the event correlation window of 120 seconds.
3429 Immediately after the operation has been started, it creates the con‐
3430 text OPER_10.1.2.7. The second event at 19:00:14 does not match the
3431 rule, since the context LOGIN_FAILED_root_10.1.2.7 does not exist. The
3432 third event at 19:00:24 matches the rule, and the operation which is
3433 running for 10.1.2.7 sets up the alias name LOGIN_FAILED_risto_10.1.2.7
3434 for the context OPER_10.1.2.7. Finally, the fourth event at 19:00:27
3435 matches the rule, since the context LOGIN_FAILED_risto_10.1.2.7 exists,
3436 and the event is therefore processed by the operation (the presence of
3437 the context indicates that the operation has previously observed a
3438 login failure for user risto from 10.1.2.7). At this particular moment
3439 (19:00:27), all three threshold conditions for the operation are ful‐
3440 filled, and therefore it sends an e-mail warning about 10.1.2.7 to
3441 root@localhost. After that, the operation silently consumes all further
3442 matching events for 10.1.2.7 until 19:02:06, and then terminates.
3443 Immediately before termination, the operation deletes the context
3444 OPER_10.1.2.7 which also drops its alias name
3445 LOGIN_FAILED_risto_10.1.2.7.
3446 SUPPRESS RULE
3448 The Suppress rule takes no action when an event has matched the rule,
3449 and keeps matching events from being processed by later rules in the
3450 configuration file.
3451 The Suppress rule supports the following fields:
3453 type fixed to Suppress (value is case insensitive).
3455 ptype pattern type (value is case insensitive).
3457 pattern
3459 pattern.
3460 varmap (optional)
3462 variable map.
3463 context (optional)
3465 context expression.
3466 desc (optional)
3468 string for describing the rule.
3469 rem (optional, may appear more than once)
3471 remarks and comments.
3472 Note that match variables may be used in the context field. Also note
3474 that this rule does not start an event correlation operation, and the
3475 optional desc field is merely used for describing the rule. Finally,
3476 in order to end event processing, so that no further rules from any of
3477 the configuration files would be tried, use the Jump rule.
3478 Examples:
3480 type=Suppress
3482 ptype=RegExp
3483 pattern=sshd\[\d+\]: Failed .+ for \S+ from ([\d.]+) port \d+ ssh2
3484 context=SUPPRESS_IP_$1
3485 type=SingleWithThreshold
3487 ptype=RegExp
3488 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
3489 desc=Three SSH login failures within 1m for user $1 from $2
3490 action=pipe '%t: %s' /bin/mail root@localhost; \
3491 create SUPPRESS_IP_$2 3600
3492 window=60
3493 thresh=3
3494 The first rule filters out SSH login failure events for an already
3496 reported source IP address, so that they will not be matched against
3497 the second rule during 3600 seconds after sending an e-mail warning.
3498 CALENDAR RULE
3500 The Calendar rule was designed for executing actions at specific times.
3501 Unlike all other rules, this rule reacts only to the system clock,
3502 ignoring other input. The Calendar rule executes the action list given
3503 with the action field if the current time matches all conditions of the
3504 time specification given with the time field. The action list is exe‐
3505 cuted only once for any matching minute.
3506 The rule employs a time specification which closely resembles the
3508 crontab(1) style, but there are some subtle differences. The time
3509 specification consists of five or six conditions separated by white‐
3510 space. The first condition matches minutes (allowed values are 0-59),
3511 the second condition matches hours (allowed values are 0-23), the third
3512 condition days (allowed values are 0-31, with 0 denoting the last day
3513 of the month), the fourth condition months (allowed values are 1-12),
3514 and the fifth condition weekdays (allowed values are 0-7, with 0 and 7
3515 denoting Sunday). The sixth condition is optional and matches years
3516 (allowed values are 0-99 which denote the last two digits of the year).
3517 Asterisks (*), ranges of numbers (e.g., 8-11), and lists (e.g.,
3519 2,5,7-9) are allowed as conditions. Asterisks and ranges may be aug‐
3520 mented with step values (e.g., 47-55/2 means 47,49,51,53,55).
3521 Note that unlike crontab(1) time specification, the day and weekday
3523 conditions are *not* joined with logical OR, but rather with logical
3524 AND. Therefore, 0 1 25-31 10 7 means 1AM on last Sunday in October.
3525 On the other hand, with crontab(1) the same specification means 1AM in
3526 every last seven days or every Sunday in October.
3527 Also, unlike some versions of cron(8), SEC is not restricted to take
3529 action only during the first second of the current minute. For example,
3530 if SEC is started at the 22th second of a minute, the wildcard condi‐
3531 tion produces a match for this minute. As another example, if the time
3532 specification matches the current minute but the context expression
3533 evaluates FALSE during the first half of the minute, the Calendar rule
3534 will execute the action list in the middle of this minute when the
3535 expression value becomes TRUE.
3536 The Calendar rule supports the following fields:
3538 type fixed to Calendar (value is case insensitive).
3540 time time specification.
3542 context (optional)
3544 context expression.
3545 desc operation description string.
3547 action action list.
3549 rem (optional, may appear more than once)
3551 remarks and comments.
3552 Note that this rule does not start event correlation operation, and the
3554 desc field is merely used for setting the %s action list variable.
3555 Examples:
3557 type=Calendar
3559 time=0 2 25-31 3,12 6
3560 desc=Check if backup is done on last Saturday of Q1 and Q4
3561 action=event WAITING_FOR_BACKUP
3562 type=Calendar
3564 time=0 2 24-30 6,9 6
3565 desc=Check if backup is done on last Saturday of Q2 and Q3
3566 action=event WAITING_FOR_BACKUP
3567 type=PairWithWindow
3569 ptype=SubStr
3570 pattern=WAITING_FOR_BACKUP
3571 desc=Quarterly backup not completed on time!
3572 action=pipe '%t: %s' /bin/mail root@localhost
3573 ptype2=SubStr
3574 pattern2=BACKUP READY
3575 desc2=Quarterly backup successfully completed
3576 action2=none
3577 window=1800
3578 The first two rules create a synthetic event WAITING_FOR_BACKUP at 2AM
3580 on last Saturday of March, June, September and December. The third
3581 rule matches this event and starts an event correlation operation which
3582 waits for the BACKUP READY event for 1800 seconds. If this event has
3583 not arrived by 2:30AM, the operation sends an e-mail warning to
3584 root@localhost.
3585 JUMP RULE
3587 The Jump rule submits matching events to specific ruleset(s) for fur‐
3588 ther processing. If the event matches the rule, SEC continues the
3589 search for matching rules in configuration file set(s) given with the
3590 cfset field. Rules from every file are tried in the order of their
3591 appearance in the file. Configuration file sets can be created from
3592 Options rules with the joincfset field, with each set containing at
3593 least one configuration file. If more that one set name is given with
3594 cfset, sets are processed from left to right; a matching rule in one
3595 set doesn't prevent SEC from processing the following sets. If the con‐
3596 stset field is set to Yes, set names are assumed to be constants and
3597 will not be searched for match variables at runtime.
3598 If the cfset field is not present and the continue field is set to
3600 GoTo, the Jump rule can be used for skipping rules inside the current
3601 configuration file. If both cfset and continue are not present (or con‐
3602 tinue is set to DontCont), Jump is identical to Suppress rule.
3603 Finally, if cfset is not present and continue is set to EndMatch, pro‐
3604 cessing of the matching event ends (i.e., no further rules from any of
3605 the configuration files will be tried).
3606 The Jump rule supports the following fields:
3608 type fixed to Jump (value is case insensitive).
3610 continue (optional)
3612 TakeNext, DontCont, EndMatch or GoTo <label> (apart from
3613 <label>, values are case insensitive).
3614 ptype pattern type (value is case insensitive).
3616 pattern
3618 pattern.
3619 varmap (optional)
3621 variable map.
3622 context (optional)
3624 context expression.
3625 cfset (optional)
3627 configuration file set names that are separated by whitespace.
3628 constset (optional)
3630 Yes or No (values are case insensitive, default is Yes).
3631 desc (optional)
3633 string for describing the rule.
3634 rem (optional, may appear more than once)
3636 remarks and comments.
3637 Note that match variables may be used in the context field. They may
3639 also be used in the cfset field, provided that the constset field is
3640 set to No. Also note that this rule does not start event correlation
3641 operations, and the optional desc field is merely used for describing
3642 the rule.
3643 Examples:
3645 type=Jump
3647 ptype=RegExp
3648 pattern=sshd\[\d+\]:
3649 cfset=sshd-rules auth-rules
3650 When an sshd syslog message appears in input, rules from configuration
3652 files of the set sshd-rules are first used for matching the message,
3653 and then rules from the configuration file set auth-rules are tried.
3654 OPTIONS RULE
3656 The Options rule sets processing options for the ruleset in the current
3657 configuration file. If more than one Options rule is present in the
3658 configuration file, the last instance overrides all previous ones. Note
3659 that the Options rule is only processed when SEC (re)starts and reads
3660 in the configuration file. Since this rule is not applied at runtime,
3661 it can never match events, react to the system clock, or start event
3662 correlation operations.
3663 The joincfset field lists the names of one or more configuration file
3665 sets, and the current configuration file will be added to each set. If
3666 a set doesn't exist, it will be created and the current configuration
3667 file becomes its first member. If the procallin field is set to No,
3668 the rules from the configuration file will be used for matching input
3669 from Jump rules only.
3670 The Options rule supports the following fields:
3672 type fixed to Options (value is case insensitive).
3674 joincfset (optional)
3676 configuration file set names that are separated by whitespace.
3677 procallin (optional)
3679 Yes or No (values are case insensitive, default is Yes).
3680 rem (optional, may appear more than once)
3682 remarks and comments.
3683 Examples:
3685 The following rule adds the current configuration file to the set
3687 sshd-rules which is used for matching input from Jump rules only:
3688 type=Options
3690 joincfset=sshd-rules
3691 procallin=no
3692 The following rule adds the current configuration file to sets linux
3694 and solaris which are used for matching all input:
3695 type=Options
3697 joincfset=linux solaris
3698
3700 Event correlation operations are dynamic entities created by rules.
3701 After creating an operation, the rule also feeds the operation with
3702 events that need to be correlated. Since each rule can create and feed
3703 many operations which are running simultaneously, each operation needs
3704 a unique ID.
3705 In order to identify event correlation operations, SEC assigns an ID to
3707 every operation that is composed from the configuration file name, the
3708 rule number, and the operation description string (defined by the desc
3709 field of the rule). If there are N rules in the configuration file
3710 (excluding Options rules), the rule numbers belong to the range 0..N-1,
3711 and the number of the k-th rule is k-1. Since each Options rule is
3712 only processed when SEC reads in the configuration file and is not
3713 applied at runtime, the Options rules will not receive rule numbers.
3714 Note that since the configuration file name and rule number are part of
3715 the operation ID, different rules can have identical desc fields with‐
3716 out a danger of a clash between operations.
3717 For example, if the configuration file /etc/sec/my.conf contains only
3719 one rule
3720 type=SingleWithThreshold
3722 ptype=RegExp
3723 pattern=user (\S+) login failure on (\S+)
3724 desc=Repeated login failures for user $1 on $2
3725 action=pipe '%t: %s' /bin/mail root@localhost
3726 window=60
3727 thresh=3
3728 then the number of this rule is 0. When this rule matches an input
3730 event "user admin login failure on tty1", the desc field yields an
3731 operation description string Repeated login failures for user admin on
3732 tty1, and the event will be directed for further processing to the
3733 operation with the following ID:
3734 /etc/sec/my.conf | 0 | Repeated login failures for user admin on tty1
3736 If the operation for this ID does not exist, the rule will create it.
3738 The newly created operation has its event counter initialized to 1, and
3739 it expects to receive two additional "user admin login failure on tty1"
3740 events from the rule within the following 60 seconds. If the operation
3741 receives such an event, its event counter is incremented, and if the
3742 counter reaches the value of 3, a warning e-mail is sent to root@local‐
3743 host.
3744 By tuning the desc field of the rule, the scope of individual event
3746 correlation operations can be changed. For instance, if the following
3747 events occur within 10 seconds
3748 user admin login failure on tty1
3750 user admin login failure on tty5
3751 user admin login failure on tty2
3752 the above rule starts three event correlation operations. However, if
3754 the desc field of the rule is changed to Repeated login failures for
3755 user $1, these events are processed by the *same* event correlation
3756 operation (the operation sends a warning e-mail to root@localhost when
3757 it receives the third event).
3758 Since rules from the same configuration file are matched against input
3760 in the order they are given, the rule ordering influences the creation
3761 and feeding of event correlation operations. Suppose the configuration
3762 file /etc/sec/my.conf contains the following rules:
3763 type=Suppress
3765 ptype=TValue
3766 pattern=TRUE
3767 context=MYCONTEXT
3768 type=SingleWithThreshold
3770 ptype=RegExp
3771 pattern=user (\S+) login failure on (\S+)
3772 desc=Repeated login failures for user $1 on $2
3773 action=pipe '%t: %s' /bin/mail root@localhost
3774 window=60
3775 thresh=3
3776 The second rule is able to create and feed event correlation operations
3778 as long as the context MYCONTEXT does not exist. However, after MYCON‐
3779 TEXT has been created, no input event will reach the second rule, and
3780 the rule is thus unable to create new operations and feed existing ones
3781 with events.
3782 Note that Pair and PairWithWindow rules can feed the same event to sev‐
3784 eral operations. Suppose the configuration file /etc/sec/my2.conf con‐
3785 tains the following rules:
3786 type=Suppress
3788 ptype=SubStr
3789 pattern=test
3790 type=Pair
3792 ptype=RegExp
3793 pattern=database (\S+) down
3794 desc=Database $1 is down
3795 action=pipe '%t: %s' /bin/mail root@localhost
3796 ptype2=RegExp
3797 pattern2=database $1 up|all databases up
3798 desc2=Database %1 is up
3799 action2=pipe '%t: %s' /bin/mail root@localhost
3800 window=86400
3801 Since the following input events don't contain the substring "test"
3803 database mydb1 down
3805 database mydb2 down
3806 database mydb3 down
3807 they are matched by the second rule of type Pair which creates three
3809 event correlation operations. Each operation is running for one partic‐
3810 ular database name, and the operations have the following IDs:
3811 /etc/sec/my2.conf | 1 | Database mydb1 is down
3813 /etc/sec/my2.conf | 1 | Database mydb2 is down
3814 /etc/sec/my2.conf | 1 | Database mydb3 is down
3815 Each newly created operation sends an e-mail notification to
3817 root@localhost about the "database down" condition, and will then wait
3818 for 86400 seconds (24 hours) for either of the following messages:
3819 (a) "database up" message for the given database,
3820 (b) "all databases up" message.
3821 The operation with the ID
3823 /etc/sec/my2.conf | 1 | Database mydb1 is down
3825 uses the following regular expression for matching expected messages:
3827 database mydb1 up|all databases up
3829 The operation with the ID
3831 /etc/sec/my2.conf | 1 | Database mydb2 is down
3833 employs the following regular expression for matching expected mes‐
3835 sages:
3836 database mydb2 up|all databases up
3838 Finally, the operation with the ID
3840 /etc/sec/my2.conf | 1 | Database mydb3 is down
3842 uses the following regular expression:
3844 database mydb3 up|all databases up
3846 If the following input events appear after 10 minutes
3848 database test up
3850 admin logged in
3851 database mydb3 up
3852 all databases up
3853 the first event "database test up" matches the first rule (Suppress)
3855 which does not pass the event further to the second rule (Pair). How‐
3856 ever, all following events reach the Pair rule. Since the messages
3857 don't match the pattern field of the rule, the rule feeds them to all
3858 currently existing operations it has created, so that the operations
3859 can match these events with their regular expressions. Because regular
3860 expressions of all three operations don't match the event "admin logged
3861 in", the operations will continue to run. In the case of the "database
3862 mydb3 up" event, the regular expression of the operation
3863 /etc/sec/my2.conf | 1 | Database mydb3 is down
3865 produces a match. Therefore, the operation will send the e-mail notifi‐
3867 cation "Database mydb3 is up" to root@localhost and terminate. How‐
3868 ever, the following event "all databases up" matches the regular
3869 expressions of two remaining operations. As a result, the operations
3870 will send e-mail notifications "Database mydb1 is up" and "Database
3871 mydb2 is up" to root@localhost and terminate.
3872 Each operation has an event correlation window which defines its scope
3874 in time. The size of the window is defined by the window* field, and
3875 the beginning of the window can be obtained with the getwpos action.
3876 SingleWithThreshold, SingleWith2Thresholds and EventGroup operations
3877 can slide its window forward during event processing, while for all
3878 operations the window can also be moved explicitly with the setwpos
3879 action. Also, with the reset action event correlation operations can be
3880 terminated. Note that getwpos, setwpos, and reset actions only work for
3881 operations started by the rules from the same configuration file.
3882 For example, consider the configuration file /etc/sec/sshd.rules that
3884 contains the following rules:
3885 type=SingleWithThreshold
3887 ptype=RegExp
3888 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
3889 desc=Three SSH login failures within 1m for user $1
3890 action=pipe '%t: %s' /bin/mail root@localhost
3891 window=60
3892 thresh=3
3893 type=Single
3895 ptype=RegExp
3896 pattern=sshd\[\d+\]: Accepted .+ for (\S+) from [\d.]+ port \d+ ssh2
3897 desc=SSH login successful for user $1
3898 action=reset -1 Three SSH login failures within 1m for user $1
3899 Suppose the following events are generated by an SSH daemon, and each
3901 event timestamp reflects the time SEC observes the event:
3902 Dec 29 15:00:03 test sshd[14129]: Failed password for risto from
3904 10.1.2.7 port 31312 ssh2
3905 Dec 29 15:00:08 test sshd[14129]: Failed password for risto from
3906 10.1.2.7 port 31312 ssh2
3907 Dec 29 15:00:17 test sshd[14129]: Accepted password for risto from
3908 10.1.2.7 port 31312 ssh2
3909 Dec 29 15:00:52 test sshd[14142]: Failed password for risto from
3910 10.1.1.2 port 17721 ssh2
3911 The first event at 15:00:03 starts an event correlation operation with
3913 the ID
3914 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
3916 risto
3917 However, when the third event occurs at 15:00:17, the second rule
3919 matches it and terminates the operation with the action
3920 reset -1 Three SSH login failures within 1m for user risto
3922 The -1 parameter of reset restricts the action to operations started by
3924 the previous rule (i.e., the first rule that has a number 0), while the
3925 Three SSH login failures within 1m for user risto parameter refers to
3926 the operation description string. Together with the current configura‐
3927 tion file name (/etc/sec/sshd.rules), the parameters yield the opera‐
3928 tion ID
3929 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
3931 risto
3932 (If the operation with the given ID would not exist, reset would per‐
3934 form no operation.)
3935 As a consequence, the fourth event at 15:00:52 starts another operation
3937 with the same ID as the terminated operation had. Without the second
3938 rule, the operation that was started at 15:00:03 would not be termi‐
3939 nated, and the appearance of the fourth event would trigger a warning
3940 e-mail from that operation.
3941
3943 SEC processes input data iteratively by reading one line at each itera‐
3944 tion, writing this line into a relevant input buffer, and matching the
3945 content of the updated buffer with rules from configuration files. If
3946 during the matching process an action list is executed which creates
3947 new input events (e.g., through the event action), they are *not* writ‐
3948 ten to buffer(s) immediately, but rather consumed at following itera‐
3949 tions.
3950 Note that when both synthetic events and regular input are available
3952 for processing, synthetic events are always consumed first. When all
3953 synthetic events have been consumed iteratively, SEC will start pro‐
3954 cessing new data from input files.
3955 With the --jointbuf option, SEC employs a joint input buffer for all
3957 input sources which holds N last input lines (the value of N can be set
3958 with the --bufsize option). Updating the input buffer means that the
3959 new line becomes the first element of the buffer, while the last ele‐
3960 ment (the oldest line) is removed from the end of the buffer. With the
3961 --nojointbuf option, SEC maintains a buffer of N lines for each input
3962 file, and if the input line comes from file F, the buffer of F is
3963 updated as described previously. There is also a separate buffer for
3964 synthetic and internal events.
3965 Suppose SEC is started with the following command line
3967 /usr/bin/sec --conf=/etc/sec/test-multiline.conf --jointbuf \
3969 --input=/var/log/prog1.log --input=/var/log/prog2.log
3970 and the configuration file /etc/sec/test-multiline.conf has the follow‐
3972 ing content:
3973 type=Single
3975 rem=this rule matches two consecutive lines where the first \
3976 line contains "test1" and the second line "test2", and \
3977 writes the matching lines to standard output
3978 ptype=RegExp2
3979 pattern=test1.*\n.*test2
3980 desc=two consecutive test lines
3981 action=write - $0
3982 When the following lines appear in input files /var/log/prog1.log and
3984 /var/log/prog2.log
3985 Dec 31 12:33:12 test prog1: test1 (file /var/log/prog1.log)
3987 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
3988 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
3989 Dec 31 12:41:53 test prog2: test2 (file /var/log/prog2.log)
3990 they are stored in a common input buffer. Therefore, rule fires after
3992 the third event has appeared, and writes the following lines to stan‐
3993 dard output:
3994 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
3996 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
3997 However, if SEC is started with the --nojointbuf option, separate input
3999 buffers are set up for /var/log/prog1.log and /var/log/prog2.log.
4000 Therefore, the rule fires after the third event has occurred, and
4001 writes the following lines to standard output:
4002 Dec 31 12:33:12 test prog1: test1 (file /var/log/prog1.log)
4004 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
4005 The rule also fires after the fourth event has occurred, producing the
4007 following output:
4008 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
4010 Dec 31 12:41:53 test prog2: test2 (file /var/log/prog2.log)
4011 The content of input buffers can be modified with the rewrite action,
4013 and modifications become visible immediately during ongoing event pro‐
4014 cessing iteration. Suppose SEC is started with the following command
4015 line
4016 /usr/bin/sec --conf=/etc/sec/test-rewrite.conf \
4018 --input=- --nojointbuf
4019 and the configuration file /etc/sec/test-rewrite.conf has the following
4021 content:
4022 type=Single
4024 rem=this rule matches two consecutive lines where the first \
4025 line contains "test1" and the second line "test2", and \
4026 joins these lines in the input buffer
4027 ptype=RegExp2
4028 pattern=^(.*test1.*)\n(.*test2.*)$
4029 continue=TakeNext
4030 desc=join two test lines
4031 action=rewrite 2 Joined $1 and $2
4032 type=Single
4034 rem=this rule matches a line which begins with "Joined", \
4035 and writes this line to standard output
4036 ptype=RegExp
4037 pattern=^Joined
4038 desc=output joined lines
4039 action=write - $0
4040 When the following two lines appear in standard input
4042 This is a test1
4044 This is a test2
4045 they are matched by the first rule which uses the rewrite action for
4047 replacing those two lines in the input buffer with a new content. The
4048 last line in the input buffer ("This is a test2") is replaced with
4049 "Joined This is a test1 and This is a test2", while the previous line
4050 in the input buffer ("This is a test1") is replaced with an empty
4051 string. Since the rule contains continue=TakeNext statement, the
4052 matching process will continue from the following rule. This rule
4053 matches the last line in the input buffer if it begins with "Joined",
4054 and writes the line to standard output, producing
4055 Joined This is a test1 and This is a test2
4057 After each event processing iteration, the pattern match cache is
4059 cleared. In other words, if a match is cached with the rule varmap*
4060 field, it is available during ongoing iteration only. Note that
4061 results from a successful pattern matching are also cached when the
4062 subsequent context expression evaluation yields FALSE. This allows for
4063 reusing results from partial rule matches. For example, the following
4064 rule creates the cache entry "ssh_failed_login" for any SSH failed
4065 login event, even if the context ALERTING_ON does not exist:
4066 type=Single
4068 ptype=RegExp
4069 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
4070 varmap=ssh_failed_login; user=1; ip=2
4071 context=ALERTING_ON
4072 desc=SSH login failure for user $1 from $2
4073 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost
4074 However, provided the context expression does not contain match vari‐
4076 ables, enclosing the expression in square brackets (e.g., [ALERT‐
4077 ING_ON]) forces its evaluation before the pattern matching, and will
4078 thus prevent the matching and the creation of the cache entry if the
4079 evaluation yields FALSE.
4080 Rules from the same configuration file are matched against the buffer
4082 content in the order they are given in that file. When multiple con‐
4083 figuration files have been specified, rule sequences from all files are
4084 matched against the buffer content (unless specified otherwise with
4085 Options rules). The matching order is determined by the order of con‐
4086 figuration files in SEC command line. For example, if the Perl glob()
4087 function returns filenames in ascending ASCII order, and configuration
4088 files /home/risto/A.conf, /home/risto/B.conf2, and /home/risto/C.conf
4089 are specified with --conf=/home/risto/*.conf --conf=/home/risto/*.conf2
4090 in SEC command line, then SEC first matches the input against the rule
4091 sequence from A.conf, then from C.conf, and finally from B.conf2.
4092 Also, note that even if A.conf contains a Suppress rule for a particu‐
4093 lar event, the event is still processed by rulesets in C.conf and
4094 B.conf2. However, note that glob() might return file names in different
4095 order if locale settings change. If you want to enforce a fixed order
4096 for configuration file application in a portable way, it is recommended
4097 to create a unique set for each file with the Options rule, and employ
4098 the Jump rule for defining the processing order for sets, e.g.:
4099 # This rule appears in A.conf
4101 type=Options
4102 joincfset=FileA
4103 procallin=no
4104 # This rule appears in B.conf2
4106 type=Options
4107 joincfset=FileB
4108 procallin=no
4109 # This rule appears in C.conf
4111 type=Options
4112 joincfset=FileC
4113 procallin=no
4114 # This rule appears in main.conf
4116 type=Jump
4117 ptype=TValue
4118 pattern=TRUE
4119 cfset=FileA FileC FileB
4120 After the relevant input buffer has been updated and its content has
4122 been matched by the rules, SEC handles caught signals and checks the
4123 status of child processes. When the timeout specified with the
4124 --cleantime option has expired, SEC also checks the status of contexts
4125 and event correlation operations. Therefore, relatively small values
4126 should be specified with the --cleantime option, in order to retain the
4127 accuracy of the event correlation process. If the --cleantime option
4128 is set to 0, SEC checks event correlation operations and contexts after
4129 processing every input line, but this consumes more CPU time. If the
4130 --poll-timeout option value exceeds the value given with --cleantime,
4131 the --poll-timeout option value takes precedence (i.e., sleeps after
4132 unsuccessful polls will not be shortened).
4133 Finally, note that apart from the sleeps after unsuccessful polls, SEC
4135 measures all time intervals and occurrence times in seconds, and always
4136 uses the time(2) system call for obtaining the current time. Also, for
4137 input event occurrence time SEC always uses the time it observed the
4138 event, *not* the timestamp extracted from the event.
4139
4141 In the action list of a context, the context can also be referred with
4142 the internal context name _THIS. The name _THIS is created and deleted
4143 dynamically by SEC and it points to the context only during its action
4144 list execution. This feature is useful when the context has had sev‐
4145 eral names during its lifetime (created with the alias action), and it
4146 is hard to determine which names exist when the context expires. For
4147 example, if the context is created with create A 60 (report A /bin/mail
4148 root) which is immediately followed by alias A B and unalias A, the
4149 report action will fail since the name A no longer refers to the con‐
4150 text. However, replacing the first action with create A 60 (report
4151 _THIS /bin/mail root) will produce the correct result.
4152 If the --intevents command line option is given, SEC will generate
4154 internal events when it is started up, when it receives certain sig‐
4155 nals, and when it terminates normally. Inside SEC, internal event is
4156 treated as if it was a line that was read from a SEC input file. Spe‐
4157 cific rules can be written to match internal events, in order to take
4158 some action (e.g., start an external event correlation module with
4159 spawn when SEC starts up). The following internal events are supported:
4160 SEC_STARTUP - generated when SEC is started (this event will always be
4162 the first event that SEC sees)
4163 SEC_PRE_RESTART - generated before processing of the SIGHUP signal
4165 (this event will be the last event that SEC sees before clearing all
4166 internal data structures and reloading its configuration)
4167 SEC_RESTART - generated after processing of the SIGHUP signal (this
4169 event will be the first event that SEC sees after clearing all internal
4170 data structures and reloading its configuration)
4171 SEC_PRE_SOFTRESTART - generated before processing of the SIGABRT signal
4173 (this event will be the last event that SEC sees before reloading its
4174 configuration)
4175 SEC_SOFTRESTART - generated after processing of the SIGABRT signal
4177 (this event will be the first event that SEC sees after reloading its
4178 configuration)
4179 SEC_PRE_LOGROTATE - generated before processing of the SIGUSR2 signal
4181 (this event will be the last event that SEC sees before reopening its
4182 log file and closing its outputs)
4183 SEC_LOGROTATE - generated after processing of the SIGUSR2 signal (this
4185 event will be the first event that SEC sees after reopening its log
4186 file and closing its outputs)
4187 SEC_SHUTDOWN - generated when SEC receives the SIGTERM signal, or when
4189 SEC reaches all EOFs of input files after being started with the
4190 --notail option. With the --childterm option, SEC sleeps for 3 seconds
4191 after generating SEC_SHUTDOWN event, and then sends SIGTERM to its
4192 child processes (if a child process was triggered by SEC_SHUTDOWN, this
4193 delay leaves the process enough time for setting a signal handler for
4194 SIGTERM).
4195 Before generating an internal event, SEC sets up a context named
4197 SEC_INTERNAL_EVENT, in order to disambiguate internal events from regu‐
4198 lar input. The SEC_INTERNAL_EVENT context is deleted immediately after
4199 the internal event has been matched against all rules.
4200 If the --intcontexts command line option is given, or there is an
4202 --input option with a context specified, SEC creates an internal con‐
4203 text each time it reads a line from an input file or a synthetic event.
4204 The internal context is deleted immediately after the line has been
4205 matched against all rules. For all input files that have the context
4206 name explicitly set with --input=<file_pattern>=<context>, the name of
4207 the internal context is <context>. If the line was read from the input
4208 file <filename> for which there is no context name set, the name of the
4209 internal context is _FILE_EVENT_<filename>. For synthetic events, the
4210 name of the internal context defaults to _INTERNAL_EVENT, but cspawn
4211 and cevent actions can be used for generating synthetic events with
4212 custom internal context names. This allows for writing rules that match
4213 data from one particular input source only. For example, the rule
4214 type=Suppress
4216 ptype=TValue
4217 pattern=TRUE
4218 context=[!_FILE_EVENT_/dev/logpipe]
4219 passes only the lines that were read from /dev/logpipe, and also syn‐
4221 thetic events that were generated with the _FILE_EVENT_/dev/logpipe
4222 internal context (e.g., with the action cevent _FILE_EVENT_/dev/logpipe
4223 0 This is a test event). As another example, if SEC has been started
4224 with the command line
4225 /usr/bin/sec --intevents --intcontexts --conf=/etc/sec/my.conf \
4227 --input=/var/log/messages=MESSAGES \
4228 --input=/var/log/secure=SECURE \
4229 --input=/var/log/cron=CRON
4230 and the rule file /etc/sec/my.conf contains the following rules
4232 type=Single
4234 ptype=RegExp
4235 pattern=^(?:SEC_STARTUP|SEC_RESTART)$
4236 context=[SEC_INTERNAL_EVENT]
4237 desc=listen on 10514/tcp for incoming events
4238 action=cspawn MESSAGES /usr/bin/nc -l -k 10514
4239 type=Single
4241 ptype=RegExp
4242 pattern=.
4243 context=[MESSAGES]
4244 desc=echo everything from 10514/tcp and /var/log/messages
4245 action=write - $0
4246 then SEC will receive input lines from the log files /var/log/messages,
4248 /var/log/secure, and /var/log/cron, and will also run /usr/bin/nc for
4249 receiving input lines from the port 10514/tcp. All input lines from
4250 /var/log/messages and 10514/tcp are matched by the second rule and
4251 written to standard output.
4252
4254 The SingleWithScript rule and shellcmd, spawn, cspawn, pipe, and report
4255 actions fork a child process for executing an external program. If the
4256 program command line contains shell metacharacters, the command line is
4257 first parsed by the shell which then starts the program. SEC communi‐
4258 cates with its child processes through pipes (created with the pipe(2)
4259 system call). When the child process is at the read end of the pipe,
4260 data have to be written to the pipe in blocking mode which ensures
4261 reliable data transmission. In order to avoid being blocked, SEC forks
4262 another child process for writing data to the pipe reliably.
4263 After forking an external program, SEC continues immediately, and
4265 checks the program status periodically until the program exits. The
4266 running time of a child process is not limited in any way. With the
4267 --childterm option, SEC sends the SIGTERM signal to all child processes
4268 when it terminates. If some special exit procedures need to be accom‐
4269 plished in the child process (or the child wishes to ignore SIGTERM),
4270 then the child must install a handler for the SIGTERM signal. Note
4271 that if the program command line contains shell metacharacters, the
4272 parsing shell will run as a child process of SEC and the parent process
4273 of the program. Therefore, the SIGTERM signal will be sent to the
4274 shell, *not* the program. In order to avoid this, the shell's builtin
4275 exec command can be used (see sh(1) for more information) which
4276 replaces the shell with the program without forking a new process,
4277 e.g.,
4278 action=spawn exec /usr/local/bin/myscript.pl 2>/var/log/myscript.log
4280 Note that if an action list includes two actions which fork external
4282 programs, the execution order these programs is not determined by the
4283 order of actions in the list, since both programs are running asyn‐
4284 chronously. In order to address this issue, the execution order must
4285 be specified explicitly (e.g., instead of writing action=shellcmd cmd1;
4286 shellcmd cmd2, use the shell && operator and write action=shellcmd cmd1
4287 && cmd2).
4288 Sometimes it is desireable to start an external program and provide it
4290 with data from several rules. In order to create such setup, named
4291 pipes can be harnessed. For example, if /var/log/pipe is a named pipe,
4292 then
4293 action=shellcmd /usr/bin/logger -f /var/log/pipe -p user.notice
4295 starts the /usr/bin/logger utility which sends all lines read from
4297 /var/log/pipe to the local syslog daemon with the "user" facility and
4298 "notice" level. In order to feed events to /usr/bin/logger, the write
4299 action can be used (e.g., write /var/log/pipe This is my event).
4300 Although SEC keeps the named pipe open across different write actions,
4301 the pipe will be closed on the reception of SIGHUP, SIGABRT and SIGUSR2
4302 signals. Since many UNIX tools terminate on receiving EOF from stan‐
4303 dard input, they need restarting after such signals have arrived. For
4304 this purpose, the --intevents option and SEC internal events can be
4305 used. For example, the following rule starts the /usr/bin/logger util‐
4306 ity at SEC startup, and also restarts it after the reception of rele‐
4307 vant signals:
4308 type=Single
4310 ptype=RegExp
4311 pattern=^(?:SEC_STARTUP|SEC_RESTART|SEC_SOFTRESTART|SEC_LOGROTATE)$
4312 context=SEC_INTERNAL_EVENT
4313 desc=start the logger tool
4314 action=free %emptystring; owritecl /var/log/pipe %emptystring; \
4315 shellcmd /usr/bin/logger -f /var/log/pipe -p user.notice
4316 Note that if /var/log/pipe is never opened for writing by a write
4318 action, /usr/bin/logger will never see EOF and will thus not terminate.
4319 The owritecl action opens and closes /var/log/pipe without writing any
4320 bytes, in order to ensure the presence of EOF in such cases. This
4321 allows any previous /usr/bin/logger process to terminate before the new
4322 process is started.
4323
4325 SEC supports patterns, context expressions, and actions which involve
4326 calls to the Perl eval() function or the execution of precompiled Perl
4327 code. The use of Perl code in SEC patterns and context expressions
4328 allows for creating proper match conditions for scenarios which can't
4329 be handled by a simple regular expression match. For example, consider
4330 the following iptables syslog events:
4331 May 27 10:00:15 box1 kernel: iptables: IN=eth0 OUT=
4333 MAC=08:00:27:be:9e:2f:00:10:db:ff:20:03:08:00 SRC=10.6.4.14
4334 DST=10.1.8.2 LEN=84 TOS=0x00 PREC=0x00 TTL=251 ID=61426 PROTO=ICMP
4335 TYPE=8 CODE=0 ID=11670 SEQ=2
4336 May 27 10:02:22 box1 kernel: iptables: IN=eth0 OUT=
4337 MAC=08:00:27:be:9e:2f:00:10:db:ff:20:03:08:00 SRC=10.6.4.14
4338 DST=10.1.8.2 LEN=52 TOS=0x00 PREC=0x00 TTL=60 ID=61441 DF PROTO=TCP
4339 SPT=53125 DPT=23 WINDOW=49640 RES=0x00 SYN URGP=0
4340 Depending on the protocol and the nature of the traffic, events can
4342 have a wide variety of fields, and parsing out all event data with one
4343 regular expression is infeasible. For addressing this issue, a PerlFunc
4344 pattern can be used which creates match variables from all fields of
4345 the matching event, stores them in one Perl hash, and returns a refer‐
4346 ence to this hash. Outside the PerlFunc pattern, match variables are
4347 initialized from the key-value pairs in the returned hash. Suppose the
4348 following Jump rule with a PerlFunc pattern is defined in the
4349 main.rules rule file:
4350 type=Jump
4352 ptype=PerlFunc
4353 pattern=sub { my(%var); my($line) = $_[0]; \
4354 if ($line !~ /kernel: iptables:/g) { return 0; } \
4355 while ($line =~ /\G\s*([A-Z]+)(?:=(\S*))?/g) { \
4356 $var{$1} = defined($2)?$2:1; \
4357 } return \%var; }
4358 varmap=IPTABLES
4359 desc=parse iptables event
4360 cfset=iptables
4361 For example, if the iptables event contains the fields SRC=10.6.4.14,
4363 DST=10.1.8.2 and SYN, the above PerlFunc pattern sets up match variable
4364 $+{SRC} which holds 10.6.4.14, match variable $+{DST} which holds
4365 10.1.8.2, and match variable $+{SYN} which holds 1. The Jump rule
4366 caches all created match variables under the name IPTABLES, and submits
4367 the matching event to iptables ruleset for further processing. Suppose
4368 the iptables ruleset is defined in the iptables.rules rule file:
4369 type=Options
4371 procallin=no
4372 joincfset=iptables
4373 type=SingleWithThreshold
4375 ptype=Cached
4376 pattern=IPTABLES
4377 context=IPTABLES :> ( sub { return $_[0]->{"PROTO"} eq "ICMP"; } )
4378 desc=ICMP flood type $+{TYPE} code $+{CODE} from host $+{SRC}
4379 action=logonly
4380 window=10
4381 thresh=100
4382 type=SingleWithThreshold
4384 ptype=Cached
4385 pattern=IPTABLES
4386 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
4387 exists($_[0]->{"FIN"}) ; } )
4388 desc=SYN+FIN flood from host $+{SRC}
4389 action=logonly
4390 window=10
4391 thresh=100
4392 The two SingleWithThreshold rules employ Cached patterns for matching
4394 iptables events by looking up the IPTABLES entry in the pattern match
4395 cache (created by the above Jump rule for each iptables event). In
4396 order to narrow down the match to specific iptables events, the rules
4397 employ precompiled Perl functions in context expressions. The :> oper‐
4398 ator is used for speeding up the matching, providing the function with
4399 a single parameter which refers to the hash of variable name-value
4400 pairs for the IPTABLES cache entry.
4401 The first SingleWithThreshold rule logs a warning message if within 10
4403 seconds 100 iptables events have been observed for ICMP packets with
4404 the same type, code, and source IP address. The second SingleWith‐
4405 Threshold rule logs a warning message if within 10 seconds 100 iptables
4406 events have been observed for TCP packets coming from the same host,
4407 and having both SYN and FIN flag set in each packet.
4408 Apart from using action list variables for data sharing between rules,
4410 Perl variables created in Perl code can be employed for the same pur‐
4411 pose. For example, when SEC has executed the following action
4412 action=eval %a ($b = 1)
4414 the variable $b and its value become visible in the following context
4416 expression
4417 context= =(++$b > 10)
4419 (with that expression one can implement event counting implicitly). In
4421 order to avoid possible clashes with variables inside the SEC code
4422 itself, user-defined Perl code is executed in the main::SEC namespace
4423 (i.e., inside the special package main::SEC). By using the main:: pre‐
4424 fix, SEC data structures can be accessed and modified. For example,
4425 the following rules restore and save contexts with names MY_* on SEC
4426 startup and shutdown, using Perl Storable module for saving and restor‐
4427 ing relevant elements of %main::context_list hash (since code refer‐
4428 ences can't be saved/restored with Storable, the following example
4429 assumes that context action lists do not contain lcall actions):
4430 type=Single
4432 ptype=SubStr
4433 pattern=SEC_STARTUP
4434 context=SEC_INTERNAL_EVENT
4435 continue=TakeNext
4436 desc=Load the Storable module and terminate if it is not found
4437 action=eval %ret (require Storable); \
4438 if %ret ( logonly Storable loaded ) else ( eval %o exit(1) )
4439 type=Single
4441 ptype=SubStr
4442 pattern=SEC_STARTUP
4443 context=SEC_INTERNAL_EVENT
4444 desc=Restore contexts MY_* from /var/lib/sec/SEC_CONTEXTS on startup
4445 action=lcall %ret -> ( sub { my($ref, $context); \
4446 $ref = Storable::retrieve("/var/lib/sec/SEC_CONTEXTS"); \
4447 foreach $context (keys %{$ref}) { \
4448 if ($context =~ /^MY_/) \
4449 { $main::context_list{$context} = $ref->{$context}; } } } )
4450 type=Single
4452 ptype=SubStr
4453 pattern=SEC_SHUTDOWN
4454 context=SEC_INTERNAL_EVENT
4455 desc=Save contexts MY_* into /var/lib/sec/SEC_CONTEXTS on shutdown
4456 action=lcall %ret -> ( sub { my($context, %hash); \
4457 foreach $context (keys %main::context_list) { \
4458 if ($context =~ /^MY_/) \
4459 { $hash{$context} = $main::context_list{$context}; } } \
4460 Storable::store(\%hash, "/var/lib/sec/SEC_CONTEXTS"); } )
4461 However, note that modifying data structures within SEC code is recom‐
4463 mended only for advanced users who have carefully studied relevant
4464 parts of the code.
4465 Finally, sometimes larger chunks of Perl code have to be used for event
4467 processing and correlation. However, writing many lines of code
4468 directly into a rule is cumbersome and may decrease its readability. In
4469 such cases it is recommended to separate the code into a custom Perl
4470 module which is loaded at SEC startup, and use the code through the
4471 module interface (see perlmod(1) for further details):
4472 type=Single
4474 ptype=SubStr
4475 pattern=SEC_STARTUP
4476 context=SEC_INTERNAL_EVENT
4477 desc=Load the SecStuff module
4478 action=eval %ret (require '/usr/local/sec/SecStuff.pm'); \
4479 if %ret ( none ) else ( eval %o exit(1) )
4480 type=Single
4482 ptype=PerlFunc
4483 pattern=sub { return SecStuff::my_match($_[0]); }
4484 desc=event '$0' was matched by my_match()
4485 action=write - %s
4486
4488 Example 1 - a ruleset for Cisco events
4489 This section presents an example rulebase for managing Cisco devices.
4490 It is assumed that the managed devices have syslog logging enabled, and
4491 that all syslog messages are sent to a central host and written to log
4492 file(s) that are monitored by SEC.
4493 # Set up contexts NIGHT and WEEKEND for nights
4495 # and weekends. The context NIGHT has a lifetime
4496 # of 8 hours and the context WEEKEND 2 days
4497 type=Calendar
4499 time=0 23 * * *
4500 desc=NIGHT
4501 action=create %s 28800
4502 type=Calendar
4504 time=0 0 * * 6
4505 desc=WEEKEND
4506 action=create %s 172800
4507 # If a router does not come up within 5 minutes
4509 # after it was rebooted, generate event
4510 # "<router> REBOOT FAILURE". The next rule matches
4511 # this event, checks the router with ping and sends
4512 # a notification if there is no response.
4513 type=PairWithWindow
4515 ptype=RegExp
4516 pattern=\s([\w.-]+) \d+: %SYS-5-RELOAD
4517 desc=$1 REBOOT FAILURE
4518 action=event %s
4519 ptype2=RegExp
4520 pattern2=\s$1 \d+: %SYS-5-RESTART
4521 desc2=%1 successful reboot
4522 action2=logonly
4523 window=300
4524 type=SingleWithScript
4526 ptype=RegExp
4527 pattern=^([\w.-]+) REBOOT FAILURE
4528 script=/bin/ping -c 3 -q $1
4529 desc=$1 did not come up after reboot
4530 action=logonly $1 is pingable after reboot
4531 action2=pipe '%t: %s' /bin/mail root@localhost
4532 # Send a notification if CPU load of a router is too
4534 # high (two CPUHOG messages are received within 5
4535 # minutes); send another notification if the load is
4536 # normal again (no CPUHOG messages within last 15
4537 # minutes). Rule is not active at night or weekend.
4538 type=SingleWith2Thresholds
4540 ptype=RegExp
4541 pattern=\s([\w.-]+) \d+: %SYS-3-CPUHOG
4542 context=!(NIGHT || WEEKEND)
4543 desc=$1 CPU overload
4544 action=pipe '%t: %s' /bin/mail root@localhost
4545 window=300
4546 thresh=2
4547 desc2=$1 CPU load normal
4548 action2=pipe '%t: %s' /bin/mail root@localhost
4549 window2=900
4550 thresh2=0
4551 # If a router interface is in down state for less
4553 # than 15 seconds, generate event
4554 # "<router> INTERFACE <interface> SHORT OUTAGE";
4555 # otherwise generate event
4556 # "<router> INTERFACE <interface> DOWN".
4557 type=PairWithWindow
4559 ptype=RegExp
4560 pattern=\s([\w.-]+) \d+: %LINK-3-UPDOWN: Interface ([\w.-]+), changed
4561 state to down
4562 desc=$1 INTERFACE $2 DOWN
4563 action=event %s
4564 ptype2=RegExp
4565 pattern2=\s$1 \d+: %LINK-3-UPDOWN: Interface $2, changed state to up
4566 desc2=%1 INTERFACE %2 SHORT OUTAGE
4567 action2=event %s
4568 window=15
4569 # If "<router> INTERFACE <interface> DOWN" event is
4571 # received, send a notification and wait for
4572 # "interface up" event from the same router interface
4573 # for the next 24 hours
4574 type=Pair
4576 ptype=RegExp
4577 pattern=^([\w.-]+) INTERFACE ([\w.-]+) DOWN
4578 desc=$1 interface $2 is down
4579 action=pipe '%t: %s' /bin/mail root@localhost
4580 ptype2=RegExp
4581 pattern2=\s$1 \d+: %LINK-3-UPDOWN: Interface $2, changed state to up
4582 desc2=%1 interface %2 is up
4583 action2=pipe '%t: %s' /bin/mail root@localhost
4584 window=86400
4585 # If ten "short outage" events have been observed
4587 # in the window of 6 hours, send a notification
4588 type=SingleWithThreshold
4590 ptype=RegExp
4591 pattern=^([\w.-]+) INTERFACE ([\w.-]+) SHORT OUTAGE
4592 desc=Interface $2 at node $1 is unstable
4593 action=pipe '%t: %s' /bin/mail root@localhost
4594 window=21600
4595 thresh=10
4596 Example 2 - hierarchically organized rulesets for iptables and sshd events
4598 This section presents an example of hierarchically organized rules for
4599 processing Linux iptables events from /var/log/messages and SSH login
4600 events from /var/log/secure. It is assumed that all rule files reside
4601 in the /etc/sec directory and that the rule hierarchy has two levels.
4602 The file /etc/sec/main.rules contains first-level Jump rules for match‐
4603 ing and parsing events from input files and submitting them to proper
4604 rulesets for further processing. All other rule files in the /etc/sec
4605 directory contain second-level rules which receive their input from
4606 first-level Jump rules. Also, the example assumes that SEC is started
4607 with the following command line:
4608 /usr/bin/sec --conf=/etc/sec/*.rules --intcontexts \
4610 --input=/var/log/messages --input=/var/log/secure
4611 #
4613 # the content of /etc/sec/main.rules
4614 #
4615 type=Jump
4617 context=[ _FILE_EVENT_/var/log/messages ]
4618 ptype=PerlFunc
4619 pattern=sub { my(%var); my($line) = $_[0]; \
4620 if ($line !~ /kernel: iptables:/g) { return 0; } \
4621 while ($line =~ /\G\s*([A-Z]+)(?:=(\S*))?/g) { \
4622 $var{$1} = defined($2)?$2:1; \
4623 } return \%var; }
4624 varmap=IPTABLES
4625 desc=parse iptables events and direct to relevant ruleset
4626 cfset=iptables
4627 type=Jump
4629 context=[ _FILE_EVENT_/var/log/secure ]
4630 ptype=RegExp
4631 pattern=sshd\[(?<pid>\d+)\]: (?<status>Accepted|Failed) \
4632 (?<authmethod>[\w-]+) for (?<invuser>invalid user )?\
4633 (?<user>[\w-]+) from (?<srcip>[\d.]+) port (?<srcport>\d+) ssh2$
4634 varmap=SSH_LOGIN
4635 desc=parse SSH login events and direct to relevant ruleset
4636 cfset=ssh-login
4637 type=Jump
4639 context=[ SSH_EVENT ]
4640 ptype=TValue
4641 pattern=True
4642 desc=direct SSH synthetic events to relevant ruleset
4643 cfset=ssh-events
4644 #
4646 # the content of /etc/sec/iptables.rules
4647 #
4648 type=Options
4650 procallin=no
4651 joincfset=iptables
4652 type=SingleWithThreshold
4654 ptype=Cached
4655 pattern=IPTABLES
4656 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
4657 exists($_[0]->{"FIN"}) ; } ) \
4658 && !SUPPRESS_IP_$+{SRC}
4659 desc=SYN+FIN flood from host $+{SRC}
4660 action=pipe '%t: %s' /bin/mail -s 'iptables alert' root@localhost; \
4661 create SUPPRESS_IP_$+{SRC} 3600
4662 window=10
4663 thresh=100
4664 type=SingleWithThreshold
4666 ptype=Cached
4667 pattern=IPTABLES
4668 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
4669 !exists($_[0]->{"ACK"}) ; } ) \
4670 && !SUPPRESS_IP_$+{SRC}
4671 desc=SYN flood from host $+{SRC}
4672 action=pipe '%t: %s' /bin/mail -s 'iptables alert' root@localhost; \
4673 create SUPPRESS_IP_$+{SRC} 3600
4674 window=10
4675 thresh=100
4676 #
4678 # the content of /etc/sec/ssh-login.rules
4679 #
4680 type=Options
4682 procallin=no
4683 joincfset=ssh-login
4684 type=Single
4686 ptype=Cached
4687 pattern=SSH_LOGIN
4688 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed" && \
4689 $_[0]->{"srcport"} < 1024 && \
4690 defined($_[0]->{"invuser"}); } )
4691 continue=TakeNext
4692 desc=Probe of invalid user $+{user} from privileged port of $+{srcip}
4693 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
4694 type=SingleWithThreshold
4696 ptype=Cached
4697 pattern=SSH_LOGIN
4698 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed" && \
4699 defined($_[0]->{"invuser"}); } )
4700 desc=Ten login probes for invalid users from $+{srcip} within 60s
4701 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
4702 thresh=10
4703 window=60
4704 type=PairWithWindow
4706 ptype=Cached
4707 pattern=SSH_LOGIN
4708 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed"; } )
4709 desc=User $+{user} failed to log in from $+{srcip} within 60s
4710 action=cevent SSH_EVENT 0 %s
4711 ptype2=Cached
4712 pattern2=SSH_LOGIN
4713 context2=SSH_LOGIN :> \
4714 ( sub { return $_[0]->{"status"} eq "Accepted"; } ) && \
4715 $+{user} %+{user} $+{srcip} %+{srcip} -> \
4716 ( sub { return $_[0] eq $_[1] && $_[2] eq $_[3]; } )
4717 desc2=User $+{user} logged in successfully from $+{srcip} within 60s
4718 action2=logonly
4719 window=60
4720 #
4722 # the content of /etc/sec/ssh-events.rules
4723 #
4724 type=Options
4726 procallin=no
4727 joincfset=ssh-events
4728 type=SingleWithThreshold
4730 ptype=RegExp
4731 pattern=User ([\w-]+) failed to log in from [\d.]+ within 60s
4732 desc=Ten login failures for user $1 within 1h
4733 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
4734 thresh=10
4735 window=3600
4736
4738 If the SECRC environment variable is set, SEC expects it to contain the
4739 name of its resource file. Resource file lines which are empty or which
4740 begin with the number sign (#) are ignored (whitespace may precede #).
4741 Each remaining line is appended to the argv array of SEC as a *single*
4742 element. Also, the lines are appended to argv in the order they appear
4743 in the resource file. Therefore, if the SEC command line option has a
4744 value, the option name and the value must either be separated by the
4745 equal sign (=) or a newline. Here is a simple resource file example:
4746 # read events from standard input
4748 --input=-
4749 # rules are stored in /etc/sec/test.conf
4751 --conf
4752 /etc/sec/test.conf
4753 Note that although SEC rereads its resource file at the reception of
4755 the SIGHUP or SIGABRT signal, adding an option that specifies a certain
4756 startup procedure (e.g., --pid or --detach) will not produce the
4757 desired effect at runtime. Also note that the resource file content is
4758 *not* parsed by shell, therefore shell metacharacters are passed to SEC
4759 as-is.
4760
4762 SIGHUP full restart -- SEC will reinterpret its command line and
4763 resource file options, reopen its log and input files, close its
4764 output files and sockets (these will be reopened on demand),
4765 reload its configuration, and drop *all* event correlation state
4766 (all event correlation operations will be terminated, all con‐
4767 texts will be deleted, all action list variables will be erased,
4768 etc.). With the --childterm option, SEC will also send the
4769 SIGTERM signal to its child processes.
4770 SIGABRT
4772 soft restart -- SEC will reinterpret its command line and
4773 resource file options, reopen its log file, and close its output
4774 files and sockets (these will be reopened on demand). If the
4775 --keepopen option is specified, previously opened input files
4776 will remain open across soft restart, otherwise all input files
4777 will be reopened. SEC will (re)load configuration from rule
4778 files which have been modified (file modification time returned
4779 by stat(2) has changed) or created after the previous configura‐
4780 tion load. SEC will also terminate event correlation operations
4781 started from rule files that have been modified or removed after
4782 the previous configuration load. Other operations and previ‐
4783 ously loaded configuration from unmodified rule files will
4784 remain intact. Note that on some systems SIGIOT is used in
4785 place of SIGABRT.
4786 SIGUSR1
4788 detailed information about the current state of SEC (performance
4789 and rule matching statistics, running event correlation opera‐
4790 tions, created contexts, etc.) will be written to the SEC dump
4791 file.
4792 SIGUSR2
4794 SEC will reopen its log file (useful for log file rotation), and
4795 also close its output files and sockets which will be reopened
4796 on demand.
4797 SIGINT SEC will increase its logging level by one; if the current level
4799 is 6, the level will be set back to 1. Please note this feature
4800 is available only if SEC is running non-interactively (e.g., in
4801 daemon mode).
4802 SIGTERM
4804 SEC will terminate gracefully. With the --childterm option, all
4805 SEC child processes will receive SIGTERM.
4806
4808 With some locale settings, single quotes (') in this man page might be
4809 displayed incorrectly. As a workaround, set the LANG environment vari‐
4810 able to C when reading this man page (e.g., env LANG=C man sec).
4811
4813 Risto Vaarandi (ristov at users d0t s0urcef0rge d0t net)
4814
4816 The author is grateful to SEB Estonia for supporting this work. The
4817 author also thanks the following people for supplying software patches,
4818 documentation fixes, and suggesting new features: Al Sorrell, Brian
4819 Mielke, David Lang, James Brown, Jon Frazier, Mark D. Nagel, Peter
4820 Eckel, Rick Casey, and William Gertz. Last but not least, the author
4821 expresses his profound gratitute to John P. Rouillard for many great
4822 ideas and creative discussions that have helped to develop SEC.
4823
4825 cron(8), crontab(1), fork(2), mail(1), perl(1), perlmod(1), perlre(1),
4826 pipe(2), sh(1), snmptrap(1), stat(2), strftime(3), syslog(3), time(2),
4827 umask(2)
4828SEC 2.8.2 June 2019 sec(1)