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