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 op‐
116 eration 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 al‐
119 ready exists an event correlation operation identified with this string
120 and triggered by the same rule. If the operation is not found, SEC
121 will create a new operation for the user name risto, and the occurrence
122 time of the input event will be recorded into the operation. Note that
123 for event occurrence time SEC always uses the current time as returned
124 by the time(2) system call, *not* the timestamp extracted from the
125 event.
126 Suppose that after 25 seconds, a similar SSH login failure event for
128 the same user name is observed. In this case, a running operation will
129 be found for the operation description string Three SSH login failures
130 within 1m for user risto, and the occurrence time of the second event
131 is recorded into the operation. If after 30 seconds a third event for
132 the user name risto is observed, the operation has processed 3 events
133 within 55 seconds. Since the threshold condition "3 events within 60
134 seconds" (as defined by the thresh and window fields) is now satisfied,
135 SEC will execute the action defined with the action field -- it will
136 fork a command
137 /bin/mail -s 'SSH login alert' root@localhost
139 with a pipe connected to its standard input. Then, SEC writes the oper‐
141 ation description string Three SSH login failures within 1m for user
142 risto (held by the %s special variable) to the standard input of the
143 command through the pipe. In other words, an e-mail warning is sent to
144 the local root-user. Finally, since there are 5 seconds left until the
145 end of the event correlation window, the operation will consume the
146 following SSH login failure events for user risto without any further
147 action, and finish after 5 seconds.
148 The above example illustrates that the desc field of a rule defines the
150 scope of event correlation and influences the number of operations cre‐
151 ated by the rule. For example, if we set the desc field to Three SSH
152 login failures within 1m, the root-user would be also alerted on 3 SSH
153 login failure events for *different* users within 1 minute. In order
154 to avoid clashes between operations started by different rules, opera‐
155 tion ID contains not only the value set by the desc field, but also the
156 rule file name and the rule number inside the file. For example, if
157 the rule file /etc/sec/sshd.rules contains one rule
158 type=SingleWithThreshold
160 ptype=RegExp
161 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
162 desc=Three SSH login failures within 1m for user $1
163 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost
164 window=60
165 thresh=3
166 and the event
168 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
170 10.12.2.5 port 41063 ssh2
171 is the first matching event for the above rule, this event will trigger
173 a new event correlation operation with the ID
174 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
176 risto
177 (0 is the number assigned to the first rule in the file, see EVENT COR‐
179 RELATION OPERATIONS section for more information).
180 The following simple example demonstrates that event correlation
182 schemes can be defined by combining several rules. In this example, two
183 rules harness contexts and synthetic events for achieving their goal:
184 type=SingleWithThreshold
186 ptype=RegExp
187 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
188 desc=Three SSH login failures within 1m for user $1
189 action=event 3_SSH_LOGIN_FAILURES_FOR_$1
190 window=60
191 thresh=3
192 type=EventGroup
194 ptype=RegExp
195 pattern=3_SSH_LOGIN_FAILURES_FOR_(\S+)
196 context=!USER_$1_COUNTED && !COUNTING_OFF
197 count=create USER_$1_COUNTED 60
198 desc=Repeated SSH login failures for 30 distinct users within 1m
199 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost; \
200 create COUNTING_OFF 3600
201 window=60
202 thresh=30
203 The first rule looks almost identical to the rule from the previous ex‐
205 ample, but its action field is different -- after three SSH login fail‐
206 ures have been observed for the same user name within one minute by an
207 event correlation operation, the operation will emit the synthetic
208 event 3_SSH_LOGIN_FAILURES_FOR_<username>. Although synthetic events
209 are created by SEC, they are treated like regular events received from
210 input sources and are matched against rules.
211 The regular expression pattern of the second rule will match the
213 3_SSH_LOGIN_FAILURES_FOR_<username> event and start a new event corre‐
214 lation operation if no such events have been previously seen. Also,
215 each time a synthetic event for some user name has matched the rule, a
216 context with the lifetime of 1 minute for that user name is created
217 (see the count field). Note that this prevents further matches for the
218 same user name, since a synthetic event for <username> can match the
219 rule only if the context USER_<username>_COUNTED *does not* exist (as
220 requested by the boolean expression in the context field; see CONTEXTS
221 AND CONTEXT EXPRESSIONS section for more information).
222 The operation started by the second rule sends an e-mail warning to the
224 local root-user if 30 synthetic events have been observed within 1
225 minute (see the thresh and window fields). Note that due to the use of
226 the USER_<username>_COUNTED contexts, all synthetic events concern dif‐
227 ferent user names. After sending an e-mail warning, the operation will
228 also create the context COUNTING_OFF with the lifetime of 1 hour, and
229 will continue to run until the 1 minute event correlation window ex‐
230 pires. After the operation has finished, the presence of the COUNT‐
231 ING_OFF context will keep the second rule disabled (as requested by the
232 boolean expression in the context field). Therefore, at most one e-mail
233 warning per 1 hour is issued by above rules.
234 The above examples have presented the event correlation capabilities of
236 SEC in a very brief fashion. The following sections will provide an
237 in-depth discussion of SEC features.
238
240 --conf=<file_pattern>
241 expand <file_pattern> to filenames (with the Perl glob() func‐
242 tion) and read event correlation rules from every file. Multiple
243 --conf options can be specified at command line. Each time SEC
244 receives a signal that forces a configuration reload, <file_pat‐
245 tern> is re-evaluated. See also INPUT PROCESSING AND TIMING sec‐
246 tion for a discussion on rule processing order for multiple con‐
247 figuration files.
248 --input=<file_pattern>[=<context>]
250 expand <file_pattern> to filenames (with the Perl glob() func‐
251 tion) and use the files as input sources. An input file can be a
252 regular file, named pipe, or standard input if - was specified.
253 Multiple --input options can be specified at command line. Each
254 time SEC receives the SIGHUP or SIGABRT signal, <file_pattern>
255 is re-evaluated. If SEC experiences a system error when reading
256 from an input file, it will close the file (use the --re‐
257 open-timeout option for reopening the file). If <context> is
258 given, SEC will set up the context <context> each time it reads
259 a line from input files that correspond to <file_pattern>. This
260 will help the user to write rules that match data from particu‐
261 lar input source(s) only. When there is an --input option with
262 <context> specified, it will automatically enable the --intcon‐
263 texts option. See INTERNAL EVENTS AND CONTEXTS section for more
264 information.
265 --input-timeout=<input_timeout>, --timeout-script=<timeout_script>
267 if SEC has not observed new data in an input file during <in‐
268 put_timeout> seconds (or the file was closed <input_timeout>
269 seconds ago), <timeout_script> will be executed with command
270 line parameters 1 and <the name of the input file>. If fresh
271 data become available again, <timeout_script> will be executed
272 with command line parameters 0 and <the name of the input file>.
273 Setting <input_timeout> to 0 disables this behavior (this is
274 also the default). Note that --input_timeout and --time‐
275 out_script options can be used as synonyms for --input-timeout
276 and --timeout-script, respectively.
277 --reopen-timeout=<reopen_timeout>
279 if an input file is in the closed state (e.g., SEC fails to open
280 the file at startup, because it has not been created yet), SEC
281 will attempt to reopen the file after every <reopen_timeout>
282 seconds until open succeeds. Setting <reopen_timeout> to 0 dis‐
283 ables this behavior (this is also the default). This option has
284 no meaning when the --notail option is also specified. Note
285 that --reopen_timeout is a synonym for --reopen-timeout.
286 --check-timeout=<check_timeout>
288 if SEC has not observed new data in an input file, the file will
289 not be polled (both for status and data) during the next
290 <check_timeout> seconds. Setting <check_timeout> to 0 disables
291 this behavior (this is also the default). Note that
292 --check_timeout is a synonym for --check-timeout.
293 --poll-timeout=<poll_timeout>
295 a real number that specifies how many seconds SEC will sleep
296 when no new data were read from input files. Default is 0.1 sec‐
297 onds. Note that --poll_timeout is a synonym for --poll-timeout.
298 --socket-timeout=<socket_timeout>
300 if a network connection to a remote peer can't be established
301 within <socket_timeout> seconds, give up. Default is 60 seconds.
302 Note that --socket_timeout is a synonym for --socket-timeout.
303 --blocksize=<io_block_size>
305 the number of bytes SEC will attempt to read at once from an in‐
306 put file. Default is 8192 bytes (i.e., read from input files by
307 8KB blocks).
308 --bufsize=<input_buffer_size>
310 set all input buffers to hold <input_buffer_size> lines. The
311 content of input buffers will be compared with patterns that are
312 part of rule definitions (i.e., no more than <input_buffer_size>
313 lines can be matched by a pattern at a time). If <input_buf‐
314 fer_size> is set to 0, SEC will determine the proper value for
315 <input_buffer_size> by checking event matching patterns of all
316 SEC rules. Default is 0 (i.e., determine the size of input buf‐
317 fers automatically).
318 --evstoresize=<event_store_size>
320 set an upper limit to the number of events in context event
321 stores. Default is 0 which sets no limit.
322 --cleantime=<clean_time>
324 time interval in seconds that specifies how often internal event
325 correlation and context lists are processed, in order to accom‐
326 plish time-related tasks and to remove obsolete elements. See
327 INPUT PROCESSING AND TIMING section for more information. De‐
328 fault is 1 second.
329 --log=<logfile>
331 use <logfile> for logging SEC activities. Note that if the SEC
332 standard error is connected to a terminal, messages will also be
333 logged there, in order to facilitate debugging.
334 --syslog=<facility>
336 use syslog for logging SEC activities. All messages will be
337 logged with the facility <facility>, e.g., local0 (see syslog(3)
338 for possible facility values). Warning: be careful with using
339 this option if SEC is employed for monitoring syslog log files,
340 because message loops might occur.
341 --debug=<debuglevel>
343 set logging verbosity for SEC. Setting debuglevel to <debu‐
344 glevel> means that all messages of level <debuglevel> and lower
345 are logged (e.g., if <debuglevel> is 3, messages from levels 1-3
346 are logged). The following levels are recognized by SEC:
347 1 - critical messages (severe faults that cause SEC to termi‐
348 nate, e.g., a failed system call)
349 2 - error messages (faults that need attention, e.g., an incor‐
350 rect rule definition in a configuration file)
351 3 - warning messages (possible faults, e.g., a command forked
352 from SEC terminated with a non-zero exit code)
353 4 - notification messages (normal system level events and inter‐
354 rupts, e.g., the reception of a signal)
355 5 - informative messages (information about external programs
356 forked from SEC)
357 6 - debug messages (detailed information about all SEC activi‐
358 ties)
359 Default <debuglevel> is 6 (i.e., log everything). See SIGNALS
360 section for information on how to change <debuglevel> at run‐
361 time.
362 --pid=<pidfile>
364 SEC will store its process ID to <pidfile> at startup.
365 --dump=<dumpfile>
367 SEC will use <dumpfile> as its dump file for writing performance
368 and debug data. With the --dumpfts option, a timestamp suffix is
369 appended to the dump file name. With the --dumpfjson option,
370 dump file is produced in JSON format. See SIGNALS section for
371 more information. Default is /tmp/sec.dump.
372 --user=<username>, --group=<groupname>
374 if SEC is started with effective user ID 0, it will drop root
375 privileges by switching to user <username> and group <group‐
376 name>. The --group option can't be used without the --user op‐
377 tion. If the --user option is given without --group, primary
378 group of the user <username> is assumed for <groupname>. If
379 several groups are provided with multiple --group options, SEC
380 switches to the first group with other groups as supplementary
381 groups.
382 --umask=<mode>
384 set file mode creation mask to <mode> at SEC startup, where
385 <mode> is a value from the range 0..0777 (see also umask(2)).
386 Octal, decimal, hexadecimal, and binary values can be specified
387 for <mode> (e.g., octal mask 0027 can also be expressed as 23,
388 0x17, and 0b000010111).
389 --ruleperf, --noruleperf
391 if the --ruleperf option is specified, performance data (e.g.,
392 total consumed CPU time) is collected for each rule and reported
393 in dump file. Default is --noruleperf.
394 --dumpfts, --nodumpfts
396 if the --dumpfts option is specified, a timestamp suffix (sec‐
397 onds since Epoch) is appended to the dump file name that re‐
398 flects the file creation time. Default is --nodumpfts.
399 --dumpfjson, --nodumpfjson
401 if the --dumpfjson option is specified, dump file is produced in
402 JSON format. Default is --nodumpfjson.
403 --quoting, --noquoting
405 if the --quoting option is specified, operation description
406 strings that are supplied to command lines of shellcmd, spawn,
407 and cspawn actions will be put inside single quotes. Each single
408 quote (') that strings originally contain will be masked. This
409 option prevents the shell from interpreting special symbols that
410 operation description strings might contain. Default is --no‐
411 quoting.
412 --tail, --notail
414 if the --notail option is specified, SEC will process all data
415 that are currently available in input files and exit after
416 reaching all EOFs. If all input is received from a pipe and the
417 --notail option is given, SEC terminates when the last writer
418 closes the pipe (EOF condition). Please note that with named
419 pipes --notail should be used with --norwfifo. With the --tail
420 option, SEC will jump to the end of input files and wait for new
421 lines to arrive. Each input file is tracked both by its name
422 and i-node, and input file rotations are handled seamlessly. If
423 the input file is recreated or truncated, SEC will reopen it and
424 process its content from the beginning. If the input file is re‐
425 moved (i.e., there is just an i-node left without a name), SEC
426 will keep the i-node open and wait for the input file recre‐
427 ation. Default is --tail.
428 --fromstart, --nofromstart
430 these flags have no meaning when the --notail option is also
431 specified. When used in combination with --tail (or alone, since
432 --tail is enabled by default), --fromstart will force SEC to
433 read and process input files from the beginning to the end, be‐
434 fore the 'tail' mode is entered. Default is --nofromstart.
435 --detach, --nodetach
437 if the --detach option is specified, SEC will disassociate it‐
438 self from the controlling terminal and become a daemon at
439 startup (note that SEC will close its standard input, standard
440 output, and standard error, and change its working directory to
441 the root directory). Default is --nodetach.
442 --jointbuf, --nojointbuf
444 if the --jointbuf option is specified, SEC uses joint input buf‐
445 fer for all input sources (the size of the buffer is set with
446 the --bufsize option). The --nojointbuf option creates a sepa‐
447 rate input buffer for each input file, and a separate buffer for
448 all synthetic and internal events (the sizes of all buffers are
449 set with the --bufsize option). The --jointbuf option allows
450 multiline patterns to match lines from several input sources,
451 while the --nojointbuf pattern restricts the matching to lines
452 from one input source only. See INPUT PROCESSING AND TIMING
453 section for more information. If the size of input buffer(s) is
454 1 (either explicitly set with --bufsize=1 or automatically de‐
455 termined from SEC rules), --jointbuf option is enabled, other‐
456 wise the default is --nojointbuf.
457 --keepopen, --nokeepopen
459 if the --keepopen option is specified, SEC will keep input files
460 open across soft restarts. When the SIGABRT signal is received,
461 SEC will not reopen input files which have been opened previ‐
462 ously, but will only open input files which are in the closed
463 state. The --nokeepopen option forces SEC to close and (re)open
464 all input files during soft restarts. Default is --keepopen.
465 --rwfifo, --norwfifo
467 if the --norwfifo option is specified, named pipe input files
468 are opened in read-only mode. In this mode, the named pipe has
469 to be reopened when the last writer closes the pipe, in order to
470 clear the EOF condition on the pipe. With the --rwfifo option,
471 named pipe input files are opened in read-write mode, although
472 SEC never writes to the pipes. In this mode, the pipe does not
473 need to be reopened when an external writer closes it, since
474 there is always at least one writer on the pipe and EOF will
475 never appear. Therefore, if the --notail option has been given,
476 --norwfifo should also be specified. Default is --rwfifo.
477 --childterm, --nochildterm
479 if the --childterm option is specified, SEC will send the
480 SIGTERM signal to all its child processes when it terminates or
481 goes through a full restart. Default is --childterm.
482 --intevents, --nointevents
484 SEC will generate internal events when it starts up, when it re‐
485 ceives certain signals, and when it terminates gracefully. Spe‐
486 cific rules can be written to match those internal events, in
487 order to accomplish special tasks at SEC startup, restart, and
488 shutdown. See INTERNAL EVENTS AND CONTEXTS section for more in‐
489 formation. Default is --nointevents.
490 --intcontexts, --nointcontexts
492 SEC will create an internal context when it reads a line from an
493 input file. This will help the user to write rules that match
494 data from particular input source only. See INTERNAL EVENTS AND
495 CONTEXTS section for more information. Default is --nointcon‐
496 texts.
497 --testonly, --notestonly
499 if the --testonly option is specified, SEC will exit immediately
500 after parsing the configuration file(s). If the configuration
501 file(s) contained no faulty rules, SEC will exit with 0, other‐
502 wise with 1. Default is --notestonly.
503 --help, -?
505 SEC will output usage information and exit.
506 --version
508 SEC will output version information and exit.
509 Note that options can be introduced both with the single dash (-) and
511 double dash (--), and both the equal sign (=) and whitespace can be
512 used for separating the option name from the option value. For example,
513 -conf=<file_pattern> and --conf <file_pattern> options are equivalent.
514
516 Each SEC configuration file consists of rule definitions which are sep‐
517 arated by empty lines, whitespace lines and/or comment lines. Each
518 rule definition consists of keyword=value fields, one keyword and value
519 per line. Values are case insensitive only where character case is not
520 important (like the values specifying rule types, e.g., 'Single' and
521 'single' are treated identically). The backslash character (\) may be
522 used at the end of a line to continue the current rule field in the
523 next line. Lines which begin with the number sign (#) are treated as
524 comments and ignored (whitespace characters may precede #). Any comment
525 line, empty line, whitespace line, or end of file will terminate the
526 preceding rule definition. For inserting comments into rule defini‐
527 tions, the rem keyword can be used. For example, the following lines
528 define two rules:
529 type=Single
531 rem=this rule matches any line which contains \
532 three consecutive A characters and writes the string \
533 "three A characters were observed" to standard output
534 ptype=SubStr
535 pattern=AAA
536 desc=Three A characters
537 action=write - three A characters were observed
538 # This comment line ends preceding rule definition.
539 # The following rule works like the previous rule,
540 # but looks for three consecutive B characters and
541 # writes the string "three B characters were observed"
542 # to standard output
543 type=Single
544 ptype=SubStr
545 pattern=BBB
546 desc=Three B characters
547 action=write - three B characters were observed
548 Apart from keywords that are part of rule definitions, label keywords
550 may appear anywhere in the configuration file. The value of each label
551 keyword will be treated as a label that can be referred to in rule def‐
552 initions as a point-of-continue. This allows for continuing event pro‐
553 cessing at a rule that follows the label, after the current rule has
554 matched and processed the event.
555 The points-of-continue are defined with continue* fields. Accepted val‐
557 ues for these fields are:
558 TakeNext
560 after an event has matched the rule, search for matching rules
561 in the configuration file will continue from the next rule.
562 GoTo <label>
564 after an event has matched the rule, search for matching rules
565 will continue from the location of <label> in the configuration
566 file (<label> must be defined with the label keyword anywhere in
567 the configuration file *after* the current rule definition).
568 DontCont (default value)
570 after an event has matched the rule, search for matching rules
571 ends in the *current* configuration file.
572 EndMatch
574 after an event has matched the rule, search for matching rules
575 ends for *all* configuration files.
576 SEC rules from the same configuration file are matched against input in
578 the order they have been given in the file. For example, consider a
579 configuration file which contains the following rule sequence:
580 type=Single
582 ptype=SubStr
583 pattern=AAA
584 rem=after this rule has matched, continue from last rule
585 continue=GoTo lastRule
586 desc=Three A characters
587 action=write - three A characters were observed
588 type=Single
590 ptype=SubStr
591 pattern=BBB
592 rem=after this rule has matched, don't consider following rules, \
593 since 'continue' defaults to 'DontCont'
594 desc=Three B characters
595 action=write - three B characters were observed
596 type=Single
598 ptype=SubStr
599 pattern=CCC
600 rem=after this rule has matched, continue from next rule
601 continue=TakeNext
602 desc=Three C characters
603 action=write - three C characters were observed
604 label=lastRule
606 type=Single
608 ptype=SubStr
609 pattern=DDD
610 desc=Three D characters
611 action=write - three D characters were observed
612 For the input line "AAABBBCCCDDD", this ruleset writes strings "three A
614 characters were observed" and "three D characters were observed" to
615 standard output. If the input line is "BBBCCCDDD", the string "three B
616 characters were observed" is written to standard output. For the input
617 line "CCCDDD", strings "three C characters were observed" and "three D
618 characters were observed" are sent to standard output, while the input
619 line "DDD" produces the output string "three D characters were ob‐
620 served".
621 If there are two or more configuration files, rule sequence from every
623 file is matched against input (unless explicitly specified otherwise).
624 For example, suppose SEC is started with the command line
625 /usr/bin/sec --input=- \
627 --conf=/etc/sec/sec1.rules --conf=/etc/sec/sec2.rules
628 and the configuration file /etc/sec/sec1.rules has the following con‐
630 tent:
631 type=Single
633 ptype=SubStr
634 pattern=AAA
635 desc=Three A characters
636 action=write - three A characters were observed
637 type=Single
639 ptype=SubStr
640 pattern=BBB
641 continue=EndMatch
642 desc=Three B characters
643 action=write - three B characters were observed
644 Also, suppose the configuration file /etc/sec/sec2.rules has the fol‐
646 lowing content:
647 type=Single
649 ptype=SubStr
650 pattern=CCC
651 desc=Three C characters
652 action=write - three C characters were observed
653 If SEC receives the line "AAABBBCCC" from standard input, rules from
655 both configuration files are tried, and as a result, the strings "three
656 A characters were observed" and "three C characters were observed" are
657 written to standard output. Note that rules from /etc/sec/sec1.rules
658 are tried first against the input line, since the option
659 --conf=/etc/sec/sec1.rules is given before --conf=/etc/sec/sec2.rules
660 in the SEC command line (see also INPUT PROCESSING AND TIMING section
661 for a more detailed discussion). If SEC receives the line "BBBCCC"
662 from standard input, the second rule from /etc/sec/sec1.rules produces
663 a match, and the string "three B characters were observed" is written
664 to standard output. Since the rule contains continue=EndMatch state‐
665 ment, the search for matching rules will end for all configuration
666 files, and rules from /etc/sec/sec2.rules will not be not tried. With‐
667 out this statement, the search for matching rules would continue in
668 /etc/sec/sec2.rules, and the first rule would write the string "three C
669 characters were observed" to standard output.
670
672 Patterns and pattern types are defined with pattern* and ptype* rule
673 fields. Many pattern types define the number of lines N which the pat‐
674 tern matches (if N is omitted, 1 is assumed). If N is greater than 1,
675 the scope of matching is set with the --jointbuf and --nojointbuf op‐
676 tions. With --jointbuf, the pattern is used for matching N last input
677 lines taken from the joint input buffer (the lines can come from dif‐
678 ferent input sources). With --nojointbuf, the source of the last input
679 line is identified, and the pattern is matched with N last input lines
680 from the input buffer of the identified source.
681 SubStr[N]
683 pattern is a string that is searched in the last N input lines
684 L1, L2, ..., LN. If N is greater than 1, the input lines are
685 joined into a string "L1<NEWLINE>L2<NEWLINE>...<NEWLINE>LN", and
686 the pattern string will be searched from it. If the pattern
687 string is found in input line(s), the pattern matches. Back‐
688 slash sequences \t, \n, \r, \s, and \0 can be used in the pat‐
689 tern for denoting tabulation, newline, carriage return, space
690 character, and empty string, respectively, while \\ denotes
691 backslash itself. For example, consider the following pattern
692 definition:
693 ptype=substr
695 pattern=Backup done:\tsuccess
696 The pattern matches lines containing "Backup done:<TAB>success".
698 Note that since the SubStr[N] pattern type has been designed for
700 fast matching, it does not support match variables.
701 RegExp[N]
703 pattern is a Perl regular expression (see perlre(1) for more in‐
704 formation) for matching the last N input lines L1, L2, ..., LN.
705 If N is greater than 1, the input lines are joined into a string
706 "L1<NEWLINE>L2<NEWLINE>...<NEWLINE>LN", and the regular expres‐
707 sion is matched with this string. If the regular expression
708 matches, match variables will be set, and these match variables
709 can be used in other parts of the rule definition.
710 In addition to numbered match variables ($1, $2, etc.), SEC sup‐
712 ports named match variables $+{name} and the $0 variable. The $0
713 variable holds the entire string of last N input lines that the
714 regular expression has matched. Named match variables can be
715 created in newer versions of Perl regular expression language,
716 e.g., (?<myvar>AB|CD) sets $+{myvar} to AB or CD. Also, SEC cre‐
717 ates special named match variables $+{_inputsrc} and $+{_intcon‐
718 text}. The $+{_inputsrc} variable holds input file name(s) where
719 matching line(s) came from. The $+{_intcontext} variable holds
720 the name of current internal context (see INTERNAL EVENTS AND
721 CONTEXTS section for more information). If internal context has
722 not been set up for the current input source, the variable is
723 set to Perl undefined value.
724 For example, the following pattern matches the SSH "Connection
726 from" event, and sets $0 to the entire event line, both $1 and
727 $+{ip} to the IP address of the remote node, and $2 to the port
728 number at the remote node:
729 ptype=RegExp
731 pattern=sshd\[\d+\]: Connection from (?<ip>[\d.]+) port (\d+)
732 If the matching event comes from input file /var/log/messages
734 with internal context MSGS, the $+{_inputsrc} and $+{_intcon‐
735 text} variables are set to strings "/var/log/messages" and
736 "MSGS", respectively.
737 Also, SEC allows for match caching and for the creation of addi‐
739 tional named match variables through variable maps which are de‐
740 fined with the varmap* fields. Variable map is a list of
741 name=number mappings separated by semicolons, where name is the
742 name for the named variable and number identifies a numbered
743 match variable that is set by the regular expression. Each name
744 must begin with a letter and consist of letters, digits and un‐
745 derscores. After the regular expression has matched, named vari‐
746 ables specified by the map are created from corresponding num‐
747 bered variables. If the same named variable is set up both from
748 the regular expression and variable map, the map takes prece‐
749 dence.
750 If name is not followed by the equal sign and number in the
752 varmap* field, it is regarded as a common name for all match
753 variables and their values from a successful match. This name
754 is used for caching a successful match by the pattern -- match
755 variables and their values are stored in the memory-based pat‐
756 tern match cache under name. Cached match results can be reused
757 by Cached and NCached patterns. Note that before processing each
758 new input line, previous content of the pattern match cache is
759 cleared. Also note that a successful pattern match is cached
760 even if the subsequent context expression evaluation yields
761 FALSE (see INPUT PROCESSING AND TIMING section for more informa‐
762 tion).
763 For example, consider the following pattern definition:
765 ptype=regexp
767 pattern=(?i)(\S+\.mydomain).*printer: toner\/ink low
768 varmap=printer_toner_or_ink_low; message=0; hostname=1
769 The pattern matches "printer: toner/ink low" messages in a case
771 insensitive manner from printers belonging to .mydomain. Note
772 that the printer hostname is assigned to $1 and $+{hostname},
773 while the whole message line is assigned to $0 and $+{message}.
774 If the message comes from file /var/log/test which does not have
775 an internal context defined, the $+{_inputsrc} variable is set
776 to string "/var/log/test", while $+{_intcontext} is set to Perl
777 undefined value. Also, these variables and their values are
778 stored to the pattern match cache under the name
779 "printer_toner_or_ink_low".
780 The following pattern definition produces a match if the last
782 two input lines are AAA and BBB:
783 ptype=regexp2
785 pattern=^AAA\nBBB$
786 varmap=aaa_bbb
787 Note that with the --nojointbuf option the pattern only matches
789 if the matching lines are coming from the *same* input file,
790 while the --jointbuf option lifts that restriction.
791 In the case of a match, $0 is set to "AAA<NEWLINE>BBB", $+{_in‐
793 putsrc} to file name(s) for matching lines, and $+{_intcontext}
794 to the name of current internal context. Also, these variable-
795 value pairs are cached under the name "aaa_bbb".
796 PerlFunc[N]
798 pattern is a Perl function for matching the last N input lines
799 L1, L2, ..., LN. The Perl function is compiled at SEC startup
800 with the Perl eval() function, and eval() must return a code
801 reference for the pattern to be valid (see also PERL INTEGRATION
802 section). The function is called in Perl list context, and with
803 the --jointbuf option, lines L1, L2, ..., LN and the names of
804 corresponding input files F1, F2, ..., FN are passed to the
805 function as parameters:
806 function(L1, L2, ..., LN, F1, F2, ..., FN)
808 Note that with the --nojointbuf option, the function is called
810 with a single file name parameter F, since lines L1, ..., LN are
811 coming from the same input file:
812 function(L1, L2, ..., LN, F)
814 Also note that if the input line is a synthetic event, the input
816 file name is Perl undefined value.
817 If the function returns several values or a single value that is
819 true in Perl boolean context, the pattern matches. If the func‐
820 tion returns no values or a single value that is false in Perl
821 boolean context (0, empty string or undefined value), the pat‐
822 tern does not match. If the pattern matches, return values will
823 be assigned to numbered match variables ($1, $2, etc.). Like
824 with RegExp patterns, the $0 variable is set to matching input
825 line(s), the $+{_inputsrc} variable is set to input file
826 name(s), the $+{_intcontext} variable is set to the name of cur‐
827 rent internal context, and named match variables can be created
828 from variable maps. For example, consider the following pattern
829 definition:
830 ptype=perlfunc2
832 pattern=sub { return ($_[0] cmp $_[1]); }
833 The pattern compares last two input lines in a stringwise manner
835 ($_[1] holds the last line and $_[0] the preceding one), and
836 matches if the lines are different. Note that the result of the
837 comparison is assigned to $1, while two matching lines are con‐
838 catenated (with the newline character between them) and assigned
839 to $0. If matching lines come from input file /var/log/mylog
840 with internal context TEST, the $+{_inputsrc} and $+{_intcon‐
841 text} variables are set to strings "/var/log/mylog" and "TEST",
842 respectively.
843 The following pattern produces a match for any line, and sets
845 $1, $2 and $3 variables to strings "abc", "def" and "ghi", re‐
846 spectively (also, $0 is set to the whole input line, $+{_input‐
847 src} to the input file name, and $+{_intcontext} to the name of
848 internal context associated with input file $+{_inputsrc}):
849 ptype=perlfunc
851 pattern=sub { return ("abc", "def", "ghi"); }
852 The following pattern definition produces a match if the input
854 line is not a synthetic event and contains either the string
855 "abc" or "def". The $0 variable is set to the matching line. If
856 matching line comes from /var/log/test without an internal con‐
857 text, $+{_intcontext} is set to Perl undefined value, while $1,
858 $+{file} and $+{_inputsrc} are set to string "/var/log/test":
859 ptype=perlfunc
861 pattern=sub { if (defined($_[1]) && $_[0] =~ /abc|def/) \
862 { return $_[1]; } return 0; }
863 varmap= file=1
864 Finally, if a function pattern returns a single value which is a
866 reference to a Perl hash, named match variables are created from
867 key-value pairs in the hash. For example, the following pattern
868 matches a line if it contains either the string "three" or
869 "four". Apart from setting $0, $+{_inputsrc} and $+{_intcon‐
870 text}, the pattern also creates match variables $+{three} and
871 $+{four}, and sets them to 3 and 4, respectively:
872 ptype=perlfunc
874 pattern=sub { my(%hash); \
875 if ($_[0] !~ /three|four/) { return 0; } \
876 $hash{"three"} = 3; $hash{"four"} = 4; return \%hash; }
877 Cached pattern is a name that is searched in the pattern match cache
879 (entries are stored into the cache with the varmap* fields). If
880 an entry with the given name is found in the cache, the pattern
881 matches, and match variables and values are retrieved from the
882 cache. For example, if the input line matches the following
883 pattern
884 ptype=perlfunc
886 pattern=sub { if (defined($_[1]) && $_[0] =~ /abc|def/) \
887 { return $_[1]; } return 0; }
888 varmap=abc_or_def_found; file=1
889 then the entry "abc_or_def_found" is created in the pattern
891 match cache. Therefore, the pattern
892 ptype=cached
894 pattern=abc_or_def_found
895 will also produce a match for this input line, and set the $0,
897 $1, $+{file}, $+{_inputsrc}, and $+{_intcontext} variables to
898 values from the previous match.
899 NSubStr[N]
901 like SubStr[N], except that the result of the match is negated.
902 Note that this pattern type does not support match variables.
903 NRegExp[N]
905 like RegExp[N], except that the result of the match is negated
906 and variable maps are not supported. Note that the only match
907 variables supported by this pattern type are $0, $+{_inputsrc},
908 and $+{_intcontext}.
909 NPerlFunc[N]
911 like PerlFunc[N], except that the result of the match is negated
912 and variable maps are not supported. Note that the only match
913 variables supported by this pattern type are $0, $+{_inputsrc},
914 and $+{_intcontext}.
915 NCached
917 like Cached, except that the result of the match is negated.
918 Note that this pattern type does not support match variables.
919 TValue pattern is a truth value, with TRUE and FALSE being legitimate
921 values. TRUE always matches an input line, while FALSE never
922 matches anything. Note that this pattern type does not support
923 match variables.
924 When match variables are substituted, each "$$" sequence is interpreted
926 as a literal dollar sign ($) which allows for masking match variables.
927 For example, the string "Received $$1" becomes "Received $1" after sub‐
928 stitution, while "Received $$$1" becomes "Received
929 $<value_of_1st_var>". In order to disambiguate numbered match vari‐
930 ables from the following text, variable number must be enclosed in
931 braces. For example, the string "Received ${1}0" becomes "Received
932 <value_of_1st_var>0" after substitution, while the string "Received
933 $10" would become "Received <value_of_10th_var>".
934 If the match variable was not set by the pattern, it is substituted
936 with an empty string (i.e., a zero-width string). Thus the string "Re‐
937 ceived $10!" becomes "Received !" after substitution if the pattern did
938 not set $10. (Note that prior to SEC-2.6, unset variables were *not*
939 substituted.)
940 In the current version of SEC, names of $+{name} match variables must
942 comply with the following naming convention -- the first character can
943 be a letter or underscore, while remaining characters can be letters,
944 digits, underscores and exclamation marks (!). However, when setting
945 named match variables from a pattern, it is recommended to begin the
946 variable name with a letter, since names of special automatically cre‐
947 ated variables begin with an underscore (e.g., $+{_inputsrc}).
948 After the pattern has matched an event and match variables have been
950 set, it is also possible to refer to previously cached match variables
951 with the syntax $:{entryname:varname}, where entryname is the name of
952 the pattern match cache entry, and varname is the name of the variable
953 stored under the entry. For example, if the variable $+{ip} has been
954 previously cached under the entry "SSH", it can be referred as
955 $:{SSH:ip}. For the reasons of efficiency, the $:{entryname:varname}
956 syntax is not supported for fast pattern types which do not set match
957 variables (i.e., SubStr, NSubStr, NCached and TValue).
958 Note that since Pair and PairWithWindow rules have two patterns, match
960 variables of the first pattern are shadowed for some rule fields when
961 the second pattern matches and sets variables. In order to refer to
962 shadowed variables, their names must begin with % instead of $ (e.g.,
963 %1 refers to match variable $1 set by the first pattern). However, the
964 use of the %-prefix is only valid under the following circumstances --
965 *both* pattern types support match variables *and* in the given rule
966 field match variables from *both* patterns can be used.
967 The %-prefixed match variables are masked with the "%%" sequence (like
969 regular match variables with "$$"). Similarly, the braces can be used
970 for disambiguating the %-prefixed variables from the following text.
971 Finally, note that the second pattern of Pair and PairWithWindow rules
973 may contain match variables if the second pattern is of type SubStr,
974 NSubStr, Regexp, or NRegExp. The variables are substituted at runtime
975 with the values set by the first pattern. If the pattern is a regular
976 expression, all special characters inside substituted values are masked
977 with the Perl quotemeta() function and the final expression is checked
978 for correctness.
979
981 A SEC context is a memory based entity which has one or more names, a
982 lifetime, and an event store. Also, an action list can be set up for a
983 context which is executed immediately before the context expires.
984 For example, the action create MYCONTEXT 3600 (report MYCONTEXT
986 /bin/mail root@localhost) creates the context MYCONTEXT which has a
987 lifetime of 3600 seconds and empty event store. Also, immediately be‐
988 fore MYCONTEXT expires and is dropped from memory, the action report
989 MYCONTEXT /bin/mail root@localhost is executed which mails the event
990 store of MYCONTEXT to root@localhost.
991 Contexts can be used for event aggregation and reporting. Suppose the
993 following actions are executed in this order:
994 create MYCONTEXT
996 add MYCONTEXT This is a test
997 alias MYCONTEXT MYALIAS
998 add MYALIAS This is another test
999 report MYCONTEXT /bin/mail root@localhost
1000 delete MYALIAS
1001 The first action creates the context MYCONTEXT with infinite lifetime
1003 and empty event store. The second action appends the string "This is a
1004 test" to the event store of MYCONTEXT. The third action sets up an
1005 alias name MYALIAS for the context (names MYCONTEXT and MYALIAS refer
1006 to the same context data structure). The fourth action appends the
1007 string "This is another test" to the event store of the context. The
1008 fifth action writes the lines
1009 This is a test
1011 This is another test
1012 to the standard input of the /bin/mail root@localhost command. The
1014 sixth action deletes the context data structure from memory and drops
1015 its names MYCONTEXT and MYALIAS.
1016 Since contexts are accessible from all rules and event correlation op‐
1018 erations, they can be used for data sharing and joining several rules
1019 into one event correlation scheme. In order to check for the presence
1020 of contexts from rules, context expressions can be employed.
1021 Context expressions are boolean expressions that are defined with the
1023 context* rule fields. Context expressions can be used for restricting
1024 the matches produced by patterns, since if the expression evaluates
1025 FALSE, the rule will not match an input event.
1026 The context expression accepts context names, Perl miniprograms, Perl
1028 functions, and pattern match cache lookups as operands. These operands
1029 can be combined with the following operators:
1030 ! - logical NOT,
1031 && - short-circuit logical AND,
1032 || - short-circuit logical OR.
1033 In addition, parentheses can be used for grouping purposes.
1034 If the operand does not contain any special operators (such as -> or
1036 :>, see below), it is treated as a context name. Context name operands
1037 may contain match variables, but may not contain whitespace. If the
1038 context name refers to an existing context, the operand evaluates TRUE,
1039 otherwise it evaluates FALSE.
1040 For example, consider the following rule sequence:
1042 type=Single
1044 ptype=RegExp
1045 pattern=Test: (\d+)
1046 desc=test
1047 action=create CONT_$1
1048 type=Single
1050 ptype=RegExp
1051 pattern=Test2: (\d+) (\d+)
1052 context=CONT_$1 && CONT_$2
1053 desc=test
1054 action=write - Both $1 and $2 have been seen in the past
1055 If the following input lines appear in this order
1057 Test: 19
1059 Test: 261
1060 Test2: 19 787
1061 Test: 787
1062 Test2: 787 261
1063 the first input line matches the first rule which creates the context
1065 CONT_19, and similarly, the second input line triggers the creation of
1066 the context CONT_261. The third input line "Test2: 19 787" matches the
1067 regular expression
1068 Test2: (\d+) (\d+)
1070 but does not match the second rule, since the boolean expression
1072 CONT_19 && CONT_787
1074 evaluates FALSE (context CONT_19 exists, but context CONT_787 doesn't).
1076 The fourth input line matches the first rule which creates the context
1077 CONT_787. The fifth input line "Test2: 787 261" matches the second
1078 rule, since the boolean expression
1079 CONT_787 && CONT_261
1081 evaluates TRUE (both context CONT_787 and context CONT_261 exist), and
1083 therefore the string "Both 787 and 261 have been seen in the past" is
1084 written to standard output.
1085 If the context expression operand contains the arrow operator (->), the
1087 text following the arrow must be a valid Perl function definition that
1088 is compiled at SEC startup with the Perl eval() function. The eval()
1089 must return a code reference (see also PERL INTEGRATION section for
1090 more information). If any text precedes the arrow, it is treated as a
1091 list of parameters for the function. Parameters must be separated by
1092 whitespace and may contain match variables. In order to evaluate the
1093 context expression operand, the Perl function is called in the Perl
1094 scalar context. If the return value of the function is true in the Perl
1095 boolean context, the operand evaluates TRUE, otherwise it evaluates
1096 FALSE.
1097 For example, the following rule matches an SSH login failure event if
1099 the login attempt comes from a privileged port of the client host:
1100 type=Single
1102 ptype=RegExp
1103 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port (\d+) ssh2
1104 context=$2 -> ( sub { $_[0] < 1024 } )
1105 desc=SSH login failure for $1 priv port $2
1106 action=write - SSH login failure for user $1 from a privileged port $2
1107 When the following message from SSH daemon appears
1109 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
1111 10.12.2.5 port 41063 ssh2
1112 the regular expression of the rule matches this message, and the value
1114 of the $2 match variable (41063) is passed to the Perl function
1115 sub { $_[0] < 1024 }
1117 This function returns true if its input parameter is less than 1024 and
1119 false otherwise, and therefore the above message will not match the
1120 rule. However, the following message
1121 Dec 16 16:25:17 myserver sshd[13689]: Failed password for risto from
1123 10.12.2.5 port 1023 ssh2
1124 matches the rule, and the string "SSH login failure for user risto from
1126 a privileged port 1023" is written to standard output.
1127 As another example, the following context expression evaluates TRUE if
1129 the /var/log/messages file does not exist or was last modified more
1130 than 1 hour ago (note that the Perl function takes no parameters):
1131 context= -> ( sub { my(@stat) = stat("/var/log/messages"); \
1133 return (!scalar(@stat) || time() - $stat[9] > 3600); } )
1134 If the context expression operand contains the :> operator, the text
1136 that follows :> must be a valid Perl function definition that is com‐
1137 piled at SEC startup with the Perl eval() function. The eval() must re‐
1138 turn a code reference (see also PERL INTEGRATION section for more in‐
1139 formation). If any text precedes the :> operator, it is treated as a
1140 list of parameters for the function. Parameters must be separated by
1141 whitespace and may contain match variables. It is assumed that each
1142 parameter is a name of an entry in the pattern match cache. If an entry
1143 with the given name does not exist, Perl undefined value is passed to
1144 the function. If an entry with the given name exists, a reference to
1145 the entry is passed to the Perl function. Internally, each pattern
1146 match cache entry is implemented as a Perl hash which contains all
1147 match variables for the given entry. In the hash, each key-value pair
1148 represents some variable name and value, e.g., if cached match variable
1149 $+{ip} is holding 10.1.1.1, the hash contains the value 10.1.1.1 with
1150 the key ip. In order to evaluate the context expression operand, the
1151 Perl function is called in the Perl scalar context. If the return value
1152 of the function is true in the Perl boolean context, the operand evalu‐
1153 ates TRUE, otherwise it evaluates FALSE.
1154 For example, consider the following rule sequence:
1156 type=Single
1158 ptype=RegExp
1159 pattern=sshd\[\d+\]: (?<status>Accepted|Failed) .+ \
1160 for (?<invuser>invalid user )?(?<user>\S+) from (?<ip>[\d.]+) \
1161 port (?<port>\d+) ssh2
1162 varmap=SSH
1163 continue=TakeNext
1164 desc=parse SSH login events and pass them to following rules
1165 action=none
1166 type=Single
1168 ptype=Cached
1169 pattern=SSH
1170 context=SSH :> ( sub { $_[0]->{"status"} eq "Failed" && \
1171 $_[0]->{"port"} < 1024 && \
1172 defined($_[0]->{"invuser"}) } )
1173 desc=Probe of invalid user $+{user} from privileged port of $+{ip}
1174 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
1175 The first rule matches and parses SSH login messages, and stores pars‐
1177 ing results to the pattern match cache under the name SSH. The pattern
1178 of the second rule (defined with ptype=Cached and pattern=SSH) matches
1179 any input event for which the entry SSH has been previously created in
1180 the pattern match cache (in other words, the event has been recognized
1181 and parsed as an SSH login message). For each matching event, the sec‐
1182 ond rule passes the reference to the SSH cache entry to the Perl func‐
1183 tion
1184 sub { $_[0]->{"status"} eq "Failed" && \
1186 $_[0]->{"port"} < 1024 && \
1187 defined($_[0]->{"invuser"}) }
1188 The function checks the values of $+{status}, $+{port}, and $+{invuser}
1190 match variables under the SSH entry, and returns true if $+{status}
1191 equals to the string "Failed" (i.e., login attempt failed), the value
1192 of $+{port} is less than 1024, and $+{invuser} holds a defined value
1193 (i.e., user account does not exist). If the function (and thus context
1194 expression) evaluates TRUE, the rule sends a warning e-mail to root@lo‐
1195 calhost that a non-existing user account was probed from a privileged
1196 port of a client host.
1197 If the context expression operand begins with the varset keyword, the
1199 following string is treated as a name of an entry in the pattern match
1200 cache. The operand evaluates TRUE if the given entry exists, and FALSE
1201 otherwise.
1202 For example, the following context expression definition evaluates TRUE
1204 if the pattern match cache entry SSH exists and under this entry, the
1205 value of the match variable $+{user} equals to the string "risto":
1206 context=varset SSH && SSH :> ( sub { $_[0]->{"user"} eq "risto" } )
1208 If the context expression operand begins with the equal sign (=), the
1210 following text must be a Perl miniprogram which is a valid parameter
1211 for the Perl eval() function. The miniprogram may contain match vari‐
1212 ables. In order to evaluate the Perl miniprogram operand, it will be
1213 compiled and executed by calling the Perl eval() function in the Perl
1214 scalar context (see also PERL INTEGRATION section). If the return
1215 value from eval() is true in the Perl boolean context, the operand
1216 evaluates TRUE, otherwise it evaluates FALSE. Please note that unlike
1217 Perl functions of -> and :> operators which are compiled once at SEC
1218 startup, Perl miniprograms are compiled before each execution, and
1219 their evaluation is thus considerably more expensive.
1220 For example, the following context expression evaluates TRUE when nei‐
1222 ther the context C1 nor the context C2 exists and the value of the $1
1223 variable equals to the string "myhost.mydomain":
1224 context=!(C1 || C2) && =("$1" eq "myhost.mydomain")
1226 Since && is a short-circuiting operator, the Perl code
1228 "$1" eq "myhost.mydomain"
1230 is *not* evaluated if either C1 or C2 exists.
1232 Note that since Perl functions and miniprograms may contain strings
1234 that clash with context expression operators (e.g., '!'), it is recom‐
1235 mended to enclose them in parentheses, e.g.,
1236 context=$1 $2 -> ( sub { $_[0] != $_[1] } )
1238 context= =({my($temp) = 0; !$temp;})
1240 Also, if function parameter lists contain such strings, they should be
1242 enclosed in parentheses in the similar way:
1243 context=($1! $2) -> ( sub { $_[0] eq $_[1] } )
1245 If the whole context expression is enclosed in square brackets [],
1247 e.g., [MYCONTEXT1 && !MYCONTEXT2], SEC evaluates the expression *be‐
1248 fore* pattern matching (normally, the pattern is matched with input
1249 line(s) first, so that match variables would be initialized and substi‐
1250 tuted before the expression is evaluated). However, if the expression
1251 does not contain match variables and many input events are known to
1252 match the pattern but not the expression, the []-operator could save
1253 substantial amount of CPU time.
1254
1256 Action lists are defined with the action* rule fields. An action list
1257 consists of action definitions that are separated by semicolons. Each
1258 action definition begins with a keyword specifying the action type.
1259 Depending on the action type, parameters may follow, and non-constant
1260 parameters may contain match variables. For instance, if the $1 and $2
1261 match variables have the values "test1" and "the second test", respec‐
1262 tively, the action create MYCONT_$1 60 creates the context MYCONT_test1
1263 with the lifetime of 60 seconds, while the action write - The names of
1264 tests: $1, $2 writes the string "The names of tests: test1, the second
1265 test" to standard output.
1266 Apart from few exceptions explicitly noted, match variables are substi‐
1268 tuted at the earliest opportunity in action lists. For example, con‐
1269 sider the following rule definition:
1270 type=SingleWithThreshold
1272 ptype=RegExp
1273 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
1274 desc=Three SSH login failures within 1m
1275 action=pipe 'Three SSH login failures, first user is $1' \
1276 /bin/mail -s 'SSH login alert' root@localhost
1277 window=60
1278 thresh=3
1279 When this rule matches an SSH login failure event which starts an event
1281 correlation operation, the operation substitutes the $1 match variable
1282 in the action list definition with the user name from the matching
1283 event, and user names from further events processed by this event cor‐
1284 relation operation are not considered for $1. For example, if the fol‐
1285 lowing events are observed
1286 Dec 16 16:24:52 myserver sshd[13671]: Failed password for root from
1288 10.12.2.5 port 29736 ssh2
1289 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
1290 10.12.2.5 port 41063 ssh2
1291 Dec 16 16:25:01 myserver sshd[13689]: Failed password for oracle from
1292 10.12.2.5 port 11204 ssh2
1293 then all events are processed by the same operation, and the message
1295 "Three SSH login failures, first user is root" is mailed to root@local‐
1296 host.
1297 In order to use semicolons inside a non-constant parameter, the parame‐
1299 ter must be enclosed in parentheses (the outermost set of parentheses
1300 will be removed by SEC during configuration file parsing). For exam‐
1301 ple, the following action list consists of delete and shellcmd actions:
1302 action=delete MYCONTEXT; shellcmd (rm /tmp/sec1.tmp; rm /tmp/sec2.tmp)
1304 The delete action deletes the context MYCONTEXT, while the shellcmd ac‐
1306 tion executes the command line rm /tmp/sec1.tmp; rm /tmp/sec2.tmp.
1307 Since the command line contains a semicolon, it has been enclosed in
1308 parentheses, since otherwise the semicolon would be mistakenly consid‐
1309 ered a separator between two actions.
1310 Apart from match variables, SEC supports action list variables in ac‐
1312 tion lists which facilitate data sharing between actions and Perl inte‐
1313 gration. Each action list variable has a name which must begin with a
1314 letter and consist of letters, digits and underscores. Names of built-
1315 in variables usually start with a dot character (.), so that they can
1316 be distinguished from user defined variables. In order to refer to an
1317 action list variable, its name must be prefixed by a percent sign (%).
1318 Unlike match variables, action list variables can only be used in ac‐
1319 tion lists and they are substituted with their values immediately be‐
1320 fore the action list execution. Also, action list variables continue to
1321 exist after the current action list has been executed and can be em‐
1322 ployed in action lists of other rules.
1323 The following action list variables are predefined by SEC:
1325 %s operation description string (the value of the desc field after
1327 match variables have been substituted with their values). Note
1328 that for the action2 field of Pair and PairWithWindow rules, the
1329 %s variable is set by evaluating the desc2 field of the rule.
1330 %t the time in human-readable format, as returned by the Perl lo‐
1332 caltime() function in the Perl scalar context (e.g., Fri Feb 19
1333 17:54:18 2016).
1334 %u the time in seconds since Epoch, as returned by the time(2) sys‐
1336 tem call.
1337 %.sec number of seconds after the minute, in the range 00-59 (the
1339 value consists of two digits and is zero padded on the left).
1340 %.min number of minutes after the hour, in the range 00-59 (the value
1342 consists of two digits and is zero padded on the left).
1343 %.hour number of hours past midnight, in the range 00-23 (the value
1345 consists of two digits and is zero padded on the left).
1346 %.hmsstr
1348 the time in HH:MM:SS format (hours, minutes and seconds sepa‐
1349 rated by colons, e.g., 09:32:04 or 18:06:02).
1350 %.mday day of the month, in the range 01-31 (the value consists of two
1352 digits and is zero padded on the left).
1353 %.mdaystr
1355 day of the month as a string (the value consists of two charac‐
1356 ters and is space padded on the left, e.g., " 1", " 4", " 9", or
1357 "25").
1358 %.mon month, in the range 01-12 (the value consists of two digits and
1360 is zero padded on the left).
1361 %.monstr
1363 abbreviated name of the month according to the current locale,
1364 as returned by the %b specification of the strftime(3) library
1365 call (e.g., Jan, May, or Sep).
1366 %.year year (e.g., 1998 or 2016).
1368 %.wday day of the week, in the range 0-6 (0 denotes Sunday).
1370 %.wdaystr
1372 abbreviated name of the day of the week according to the current
1373 locale, as returned by the %a specification of the strftime(3)
1374 library call (e.g., Mon, Wed, or Sat).
1375 %.tzname
1377 name of the timezone according to the current locale, as re‐
1378 turned by the %Z specification of the strftime(3) library call
1379 (e.g., UTC or EET).
1380 %.tzoff
1382 timezone offset from UTC, as returned by the %z specification of
1383 the strftime(3) library call (e.g., -0500 or +0200).
1384 %.tzoff2
1386 timezone offset from UTC in +hh:mm/-hh:mm format (e.g., -05:00
1387 or +02:00), provided that the %z specification of the strf‐
1388 time(3) library call returns the value in +hhmm/-hhmm format (if
1389 the value does not follow this format, %.tzoff2 is set to an
1390 empty string).
1391 %.nl newline character.
1393 %.cr carriage return character.
1395 %.tab tabulation character.
1397 %.sp space character.
1399 %.chr0, ..., %.chr31
1401 ASCII 0..31 control characters (e.g., %.chr7 is bell and %.chr12
1402 is form feed character).
1403 For example, the following action list assigns the current time in hu‐
1405 man-readable format and the string "This is a test event" to the %text
1406 action list variable, and mails the value of %text to root@localhost:
1407 action=assign %text %t: This is a test event; \
1409 pipe '%text' /bin/mail root@localhost
1410 If the action list is executed at Nov 19 10:58:51 2015, the assign ac‐
1412 tion sets the %text action list variable to the string "Thu Nov 19
1413 10:58:51 2015: This is a test event", while the pipe action mails this
1414 string to root@localhost. Note that unlike match variables, action
1415 list variables have a global scope, and accessing the value of the
1416 %text variable in action lists of other rules will thus yield the
1417 string "Thu Nov 19 10:58:51 2015: This is a test event" (until another
1418 value is assigned to %text).
1419 In order to disambiguate the variable from the following text, the
1421 variable name must be enclosed in braces. For example, the following
1422 action
1423 action=write - %{.year}-%{.mon}-%{.mday}T%{.hmsstr}%{.tzoff2}
1425 writes a timestamp in ISO 8601 format to standard output, e.g.,
1427 2016-02-24T07:34:01+02:00 (replacing %{.mday} with %.mday in the above
1428 action would mistakenly create a reference to %.mdayT variable).
1429 When action list variables are substituted with their values, each se‐
1431 quence "%%" is interpreted as a literal percent sign (%) which allows
1432 for masking the variables. For example, the string "s%%t" becomes "s%t"
1433 after substitution, not "s%<timestamp>".
1434 However, note that if %-prefixed match variables are supported for the
1436 action2 field of the Pair or PairWithWindow rule, the sequence "%%%"
1437 must be used in action2 for masking a variable, since the string goes
1438 through *two* variable substitution rounds (first for %-prefixed match
1439 variables and then for action list variables, e.g., the string "s%%%t"
1440 first becomes "s%%t" and finally "s%t").
1441 Whenever a rule field goes through several substitution rounds, the $
1443 or % characters are masked inside values substituted during earlier
1444 rounds, in order to avoid unwanted side effects during later rounds.
1445 If the action list variable has not been set, it is substituted with an
1447 empty string (i.e., a zero-width string). Thus the string "Value of A
1448 is: %a" becomes "Value of A is: " after substitution if the variable %a
1449 is unset. (Note that prior to SEC-2.6, unset variables were *not* sub‐
1450 stituted.)
1451 Finally, the values are substituted as strings, therefore values of
1453 other types (e.g., references) lose their original meaning, unless ex‐
1454 plicitly noted otherwise (e.g., if a Perl function reference is stored
1455 to an action list variable, the function can later be invoked through
1456 this variable with the call action).
1457 SEC supports the following actions (optional parameters are enclosed in
1459 square brackets):
1460 none No action.
1462 logonly [<string>]
1464 Message <string> is logged to destinations given with the --log
1465 and --syslog options. The level of the log message is set to 4
1466 (see the --debug option for more information on log message lev‐
1467 els). Default value for <string> is %s. For example, consider
1468 the following action list definition:
1469 action=logonly This is a test
1471 The above logonly action logs the message "This is a test" with
1473 level 4.
1474 write <filename> [<string>]
1476 String <string> with a terminating newline is written to the
1477 file <filename> (<filename> may not contain whitespace). File
1478 may be a regular file, named pipe, or standard output (denoted
1479 by -). If the file is a regular file, <string> is appended to
1480 the end of the file. If the file does not exist, it is created
1481 as a regular file before writing. Note that the file will not
1482 be closed after the action completes, and the following write
1483 actions will access an already open file. However, several sig‐
1484 nals cause the file to be closed and reopened, and for rotating
1485 files created with write action, the SIGUSR2 signal can be used
1486 (see SIGNALS section for more information). Default value for
1487 <string> is %s. For example, consider the following action list
1488 definition:
1489 action=write /var/log/test.log %t $0
1491 The above write action prepends human-readable timestamp and
1493 separating space character to the value of the $0 match vari‐
1494 able, and the resulting string is appended to file
1495 /var/log/test.log with terminating newline.
1496 writen <filename> [<string>]
1498 Similar to the write action, except that the string <string> is
1499 written without a terminating newline. Note that write and
1500 writen actions share the same filehandle for accessing the file.
1501 For example, consider the following action list definition:
1502 action=writen - ab; writen - c; writen - %.nl
1504 The above action list writes the string "abc<NEWLINE>" to stan‐
1506 dard output, and is thus identical to write - abc (and also to
1507 writen - abc%.nl).
1508 closef <filename>
1510 Close the file <filename> that has been previously opened by the
1511 write or writen action (<filename> may not contain whitespace).
1512 owritecl <filename> [<string>]
1514 Similar to the write action, except that the file <filename> is
1515 opened and closed at each write. Also, the string <string> is
1516 written without a terminating newline. If the file has already
1517 been opened by a previous write action, owritecl does not use
1518 existing filehandle, but opens and closes the file separately.
1519 For example, consider the following action list definition:
1520 action=owritecl /var/log/test-%{.year}%{.mon}%{.mday} $0%{.nl}
1522 The above owritecl action appends the value of the $0 match
1524 variable with terminating newline to file /var/log/test-YYYYM‐
1525 MDD, where YYYYMMDD reflects the current date (e.g., if the cur‐
1526 rent date is April 1 2018, the file is /var/log/test-20180401).
1527 Since the file is closed after each write, the old file will not
1528 be left open when date changes.
1529 udgram <filename> [<string>]
1531 String <string> is written to the UNIX datagram socket <file‐
1532 name> (<filename> may not contain whitespace). Note that the
1533 socket will not be closed after the action completes, and the
1534 following udgram actions will access an already open socket.
1535 However, several signals cause the socket to be closed and re‐
1536 opened (see SIGNALS section for more information). Default
1537 value for <string> is %s. For example, consider the following
1538 action list definition:
1539 action=udgram /dev/log <30>%.monstr %.mdaystr %.hmsstr sec: This
1541 is a test
1542 The above udgram action sends a syslog message to local syslog
1544 daemon via /dev/log socket, where message priority is 30 (corre‐
1545 sponds to the "daemon" facility and "info" level), syslog tag is
1546 "sec" and message text is "This is a test". Note that message
1547 substring "%.monstr %.mdaystr %.hmsstr" evaluates to timestamp
1548 in BSD syslog format (e.g., Mar 31 15:36:07).
1549 closeudgr <filename>
1551 Close the UNIX datagram socket <filename> that has been previ‐
1552 ously opened by the udgram action (<filename> may not contain
1553 whitespace).
1554 ustream <filename> [<string>]
1556 String <string> is written to the UNIX stream socket <filename>
1557 (<filename> may not contain whitespace). Note that the socket
1558 will not be closed after the action completes, and the following
1559 ustream actions will access an already open socket. However,
1560 several signals cause the socket to be closed and reopened (see
1561 SIGNALS section for more information). Default value for
1562 <string> is %s.
1563 closeustr <filename>
1565 Close the UNIX stream socket <filename> that has been previously
1566 opened by the ustream action (<filename> may not contain white‐
1567 space).
1568 udpsock <host>:<port> [<string>]
1570 String <string> is sent to the UDP port <port> of the host
1571 <host>. Note that the UDP socket which is used for communica‐
1572 tion will not be closed after the action completes, and the fol‐
1573 lowing udpsock actions for the same remote peer will use an al‐
1574 ready existing socket. However, several signals cause the
1575 socket to be closed and recreated (see SIGNALS section for more
1576 information). Default value for <string> is %s. For example,
1577 consider the following action list definition:
1578 action=udpsock mysrv:514 <13>%.monstr %.mdaystr %.hmsstr myhost
1580 test: $0
1581 The above udpsock action sends a BSD syslog message to port
1583 514/udp of remote syslog server mysrv, where message priority is
1584 13 (corresponds to the "user" facility and "notice" level), name
1585 of the local host is "myhost", syslog tag is "test" and message
1586 text is the value if the $0 match variable.
1587 closeudp <host>:<port>
1589 Close the UDP socket for peer <host>:<port> that has been previ‐
1590 ously opened by the udpsock action.
1591 tcpsock <host>:<port> [<string>]
1593 String <string> is sent to the TCP port <port> of the host
1594 <host>. The timeout value given with the --socket-timeout op‐
1595 tion determines for how many seconds SEC will attempt to estab‐
1596 lish a connection to the remote peer. If the connection estab‐
1597 lishment does not succeed immediately, the tcpsock action buf‐
1598 fers <string> in memory for later sending to the remote peer.
1599 Note that the relevant TCP socket will not be closed after
1600 <string> has been transmitted, and the following tcpsock actions
1601 for the same peer will use an already existing socket. However,
1602 several signals cause the socket to be closed and recreated (see
1603 SIGNALS section for more information). Default value for
1604 <string> is %s. For example, consider the following action list
1605 definition:
1606 action=tcpsock grsrv:2003 ssh.login.failures %{num} %{u}%{.nl}
1608 The above tcpsock action sends the value of the action list
1610 variable %{num} to port 2003/tcp of the Graphite server grsrv,
1611 so that the value is recorded under metric path ssh.login.fail‐
1612 ures. Note that the %{u} action list variable evaluates to cur‐
1613 rent time in seconds since Epoch and is used for setting the
1614 timestamp for recorded value.
1615 closetcp <host>:<port>
1617 Close the TCP socket for peer <host>:<port> that has been previ‐
1618 ously opened by the tcpsock action.
1619 shellcmd <cmdline>
1621 Fork a process for executing command line <cmdline>. If <cmd‐
1622 line> contains shell metacharacters, <cmdline> is parsed by
1623 shell. If the --quoting option was specified and <cmdline> con‐
1624 tains %s variables, the value of %s is quoted with single quotes
1625 before substituting it into <cmdline>; if the value of %s con‐
1626 tains single quotes, they are masked with backslashes (e.g., abc
1627 is converted to 'abc' and aa'bb is converted to 'aa'\''bb').
1628 For additional information, see CHILD PROCESSES section. For
1629 example, consider the following action list definition:
1630 action=shellcmd (cat /tmp/report | mail root; rm -f /tmp/re‐
1632 port); \
1633 logonly Report sent to user root
1634 The shellcmd action of this action list executes the command
1636 line
1637 cat /tmp/report | mail root; rm -f /tmp/report
1639 and the logonly action logs the message "Report sent to user
1641 root". Since the command line contains a semicolon which is
1642 used for separating shellcmd and logonly actions, the command
1643 line is enclosed in parentheses.
1644 spawn <cmdline>
1646 Similar to the shellcmd action, except that each line from the
1647 standard output of <cmdline> becomes a synthetic event and will
1648 be treated like a line from input file (see the event action for
1649 more information). If the --intcontexts command line option is
1650 given, internal context _INTERNAL_EVENT is set up before each
1651 synthetic event is processed (see INTERNAL EVENTS AND CONTEXTS
1652 section for more information). For example, consider the fol‐
1653 lowing action list definition:
1654 action=spawn (cat /tmp/events; rm -f /tmp/events)
1656 The above spawn action will generate synthetic events from all
1658 lines in file /tmp/events and remove the file. Since the command
1659 line contains a semicolon which is used for separating actions,
1660 the command line is enclosed in parentheses.
1661 cspawn <name> <cmdline>
1663 Similar to the spawn action, except that if the --intcontexts
1664 command line option is given, internal context <name> is set up
1665 for each synthetic event.
1666 cmdexec <cmdline>
1668 Fork a process for executing command line <cmdline>. Unlike
1669 shellcmd action, <cmdline> is not parsed by shell, but split
1670 into arguments by using whitespace as a separator, and passed to
1671 execvp(3) for execution. Note that splitting into arguments is
1672 done when cmdexec action is loaded from the configuration file
1673 and parsed, not at runtime (e.g., if <cmdline> is /usr/lo‐
1674 cal/bin/mytool $1 $2, the values of $1 and $2 variables are re‐
1675 garded as single arguments even if the values contain white‐
1676 space). For additional information, see CHILD PROCESSES sec‐
1677 tion. For example, consider the following action list defini‐
1678 tion:
1679 action=cmdexec rm /tmp/report*
1681 The above cmdexec action will remove the file /tmp/report* with‐
1683 out treating * as a file pattern character that matches any
1684 string.
1685 spawnexec <cmdline>
1687 Similar to the cmdexec action, except that each line from the
1688 standard output of <cmdline> becomes a synthetic event and will
1689 be treated like a line from input file (see the event action for
1690 more information). If the --intcontexts command line option is
1691 given, internal context _INTERNAL_EVENT is set up before each
1692 synthetic event is processed (see INTERNAL EVENTS AND CONTEXTS
1693 section for more information).
1694 cspawnexec <name> <cmdline>
1696 Similar to the spawnexec action, except that if the --intcon‐
1697 texts command line option is given, internal context <name> is
1698 set up for each synthetic event.
1699 pipe '[<string>]' [<cmdline>]
1701 Fork a process for executing command line <cmdline>. If <cmd‐
1702 line> contains shell metacharacters, <cmdline> is parsed by
1703 shell. The string <string> with a terminating newline is writ‐
1704 ten to the standard input of <cmdline> (single quotes are used
1705 for disambiguating <string> from <cmdline>). If <string> con‐
1706 tains semicolons, <string> must be enclosed in parentheses
1707 (e.g., pipe '($1;$2)' /bin/cat). Default value for <string> is
1708 %s. If <cmdline> is omitted, <string> is written to standard
1709 output. For additional information, see CHILD PROCESSES sec‐
1710 tion. For example, consider the following action list defini‐
1711 tion:
1712 action=pipe 'Offending activities from host $1' /bin/mail
1714 root@localhost
1715 The above pipe action writes the line "Offending activities from
1717 host <hostname>" to the standard input of the /bin/mail root@lo‐
1718 calhost command which sends this line to root@localhost via e-
1719 mail (<hostname> is the value of the $1 match variable).
1720 pipeexec '[<string>]' [<cmdline>]
1722 Similar to the pipe action, except <cmdline> is not parsed by
1723 shell, but split into arguments by using whitespace as a separa‐
1724 tor, and passed to execvp(3) for execution. Note that splitting
1725 into arguments is done when pipeexec action is loaded from the
1726 configuration file and parsed, not at runtime (e.g., if <cmd‐
1727 line> is /usr/local/bin/mytool $1 $2, the values of $1 and $2
1728 variables are regarded as single arguments even if the values
1729 contain whitespace). For example, consider the following action
1730 list definition:
1731 action=pipeexec 'Offending activities from host $1' \
1733 /bin/mail -s SEC%{.sp}alert $2
1734 The above pipeexec action writes the line "Offending activities
1736 from host <hostname>" to the standard input of the /bin/mail -s
1737 <subject> <user> command which sends this line to <user> via e-
1738 mail with subject <subject> (<hostname> is the value of the $1
1739 match variable, while <user> is the value of the $2 match vari‐
1740 able). Note that since <subject> is defined as SEC%{.sp}alert
1741 and does not contain whitespace, it is treated as a single argu‐
1742 ment for the -s flag of the /bin/mail command. However, since
1743 <subject> contains the %.sp action list variable, the string
1744 "SEC alert" will be used for the e-mail subject at runtime.
1745 Also, if the value of the $2 match variable contains shell
1746 metacharacters, they will not be interpreted by the shell.
1747 create [<name> [<time> [<action list>] ] ]
1749 Create a context with the name <name>, lifetime of <time> sec‐
1750 onds, and empty event store. The <name> parameter may not con‐
1751 tain whitespace and defaults to %s. The <time> parameter must
1752 evaluate to an unsigned integer at runtime. Specifying 0 for
1753 <time> or omitting the value means infinite lifetime. If <ac‐
1754 tion list> is given, it will be executed when the context ex‐
1755 pires. If <action list> contains several actions, the list must
1756 be enclosed in parentheses. In <action list>, the internal con‐
1757 text name _THIS may be used for referring to the current context
1758 (see INTERNAL EVENTS AND CONTEXTS section for a detailed discus‐
1759 sion). If an already existing context is recreated with create,
1760 its remaining lifetime is set to <time> seconds, its action list
1761 is reinitialized, and its event store is emptied. For example,
1762 consider the following action list definition:
1763 action=write /var/log/test.log $0; create TIMER 3600 \
1765 ( logonly Closing /var/log/test.log; closef
1766 /var/log/test.log )
1767 The write action from the above action list appends the value of
1769 the $0 match variable to file /var/log/test.log, while the cre‐
1770 ate action creates the context TIMER which will exist for 3600
1771 seconds. Since this context is recreated at each write, the con‐
1772 text can expire only if the action list has not been executed
1773 for more than 3600 seconds (i.e., the action list has last up‐
1774 dated the file more than 1 hour ago). If that is the case, the
1775 action list
1776 logonly Closing /var/log/test.log; closef /var/log/test.log
1778 is executed which logs the message "Closing /var/log/test.log"
1780 with the logonly action and closes /var/log/test.log with the
1781 closef action. When the execution of this action list is com‐
1782 plete, the TIMER context is deleted.
1783 delete [<name>]
1785 Delete the context <name>. The <name> parameter may not contain
1786 whitespace and defaults to %s.
1787 obsolete [<name>]
1789 Similar to the delete action, except that the action list of the
1790 context <name> (if present) is executed before deletion.
1791 set <name> <time> [<action list>]
1793 Change settings for the context <name>. The creation time of the
1794 context is set to the current time, and the lifetime of the con‐
1795 text is set to <time> seconds. If the <action list> parameter
1796 is given, the context action list is set to <action list>, oth‐
1797 erwise the context action list is not changed. The <name> pa‐
1798 rameter may not contain whitespace and defaults to %s. The
1799 <time> parameter must evaluate to an unsigned integer or hyphen
1800 (-) at runtime. Specifying 0 for <time> means infinite life‐
1801 time. If <time> equals to -, the creation time and lifetime of
1802 the context are not changed. If <action list> contains several
1803 actions, the list must be enclosed in parentheses. In <action
1804 list>, the internal context name _THIS may be used for referring
1805 to the current context (see INTERNAL EVENTS AND CONTEXTS section
1806 for a detailed discussion). For example, consider the following
1807 action list definition:
1808 action=set C_$1 30 ( logonly Context C_$1 has expired )
1810 The above set action sets the context C_<suffix> to expire after
1812 30 seconds with a log message about expiration (<suffix> is the
1813 value of the $1 match variable).
1814 alias <name> [<alias>]
1816 Create an alias name <alias> for the context <name>. After cre‐
1817 ation, both <alias> and <name> will point to the same context
1818 data structure, and can thus be used interchangeably for refer‐
1819 ring to the context. The <name> and <alias> parameters may not
1820 contain whitespace, and <alias> defaults to %s. If the context
1821 <name> does not exist, the alias name is not created. If the
1822 delete action is called for one of the context names, the con‐
1823 text data structure is destroyed, and all context names (which
1824 are now pointers to unallocated memory) cease to exist. Also
1825 note that when the context expires, its action list is executed
1826 only once, no matter how many names the context has.
1827 unalias [<alias>]
1829 Drop an existing context name <alias>, so that it can no longer
1830 be used for referring to the given context. The <alias> parame‐
1831 ter may not contain whitespace and defaults to %s. If the name
1832 <alias> is the last reference to the context, the unalias action
1833 is identical to delete.
1834 add <name> [<string>]
1836 String <string> is appended to the end of the event store of the
1837 context <name>. The <name> parameter may not contain white‐
1838 space, and the <string> parameter defaults to %s. If the con‐
1839 text <name> does not exist, the context is created with an infi‐
1840 nite lifetime, empty action list and empty event store (as with
1841 create <name>) before adding the string to event store. If
1842 <string> is a multi-line string (i.e., it contains newlines), it
1843 is split into lines, and each line is appended to the event
1844 store separately. For example, consider the following action
1845 list definition:
1846 action=add EVENTS This is a test; add EVENTS This is a test2
1848 After the execution of this action list, the last two strings in
1850 the event store of the EVENTS context are "This is a test" and
1851 "This is a test2" (in that order).
1852 prepend <name> [<string>]
1854 Similar to the add action, except that the string <string> is
1855 prepended to the beginning of the event store of context <name>.
1856 For example, consider the following action list definition:
1857 action=prepend EVENTS This is a test; prepend EVENTS This is a
1859 test2
1860 After the execution of this action list, the first two strings
1862 in the event store of the EVENTS context are "This is a test2"
1863 and "This is a test" (in that order).
1864 fill <name> [<string>]
1866 Similar to the add action, except that the event store of the
1867 context <name> is emptied before <string> is added.
1868 report <name> [<cmdline>]
1870 Fork a process for executing command line <cmdline>. If <cmd‐
1871 line> contains shell metacharacters, <cmdline> is parsed by
1872 shell. Also, write strings from the event store of the context
1873 <name> to the standard input of <cmdline>. Strings are written
1874 in the order they appear in the event store, with a terminating
1875 newline appended to each string. If the context <name> does not
1876 exist or its event store is empty, <cmdline> is not executed.
1877 The <name> parameter may not contain whitespace, and if <cmd‐
1878 line> is omitted, strings are written to standard output. For
1879 additional information, see CHILD PROCESSES section. For exam‐
1880 ple, consider the following action list definition:
1881 action=create PID_$1 60 ( report PID_$1 /bin/mail root@localhost
1883 ); \
1884 add PID_$1 Beginning of the report
1885 The above action list creates the context PID_<suffix> with the
1887 lifetime of 60 seconds and sets the first string in the context
1888 event store to "Beginning of the report" (<suffix> is the value
1889 of the $1 match variable). When the context expires, all
1890 strings from the event store will be mailed to root@localhost.
1891 reportexec <name> [<cmdline>]
1893 Similar to the report action, except <cmdline> is not parsed by
1894 shell, but split into arguments by using whitespace as a separa‐
1895 tor, and passed to execvp(3) for execution. Note that splitting
1896 into arguments is done when reportexec action is loaded from the
1897 configuration file and parsed, not at runtime (e.g., if <cmd‐
1898 line> is /usr/local/bin/mytool $1 $2, the values of $1 and $2
1899 variables are regarded as single arguments even if the values
1900 contain whitespace).
1901 copy <name> %<var>
1903 Strings s1,...,sn from the event store of the context <name> are
1904 joined into a multi-line string "s1<NEWLINE>...<NEWLINE>sn", and
1905 this string is assigned to the action list variable %<var>. If
1906 the context <name> does not exist, the value of %<var> does not
1907 change.
1908 empty <name> [%<var>]
1910 Similar to the copy action, except that the event store of the
1911 context <name> will be emptied after the assignment. If %<var>
1912 is omitted, the content of the event store is dropped without an
1913 assignment.
1914 pop <name> %<var>
1916 Remove the last string from the event store of context <name>,
1917 and assign it to the action list variable %<var>. If the event
1918 store is empty, %<var> is set to empty string. If the context
1919 <name> does not exist, the value of %<var> does not change.
1920 shift <name> %<var>
1922 Remove the first string from the event store of context <name>,
1923 and assign it to the action list variable %<var>. If the event
1924 store is empty, %<var> is set to empty string. If the context
1925 <name> does not exist, the value of %<var> does not change.
1926 exists %<var> <name>
1928 If the context <name> exists, set the action list variable
1929 %<var> to 1, otherwise set %<var> to 0.
1930 getsize %<var> <name>
1932 Find the number of strings in the event store of context <name>,
1933 and assign this number to the action list variable %<var>. If
1934 the context <name> does not exist, %<var> is set to Perl unde‐
1935 fined value. For example, consider the following action list
1936 definition:
1937 action=fill EVENTS Event1; add EVENTS Event2; add EVENTS Event3;
1939 \
1940 pop EVENTS %temp1; shift EVENTS %temp2; getsize %size
1941 EVENTS
1942 This action list sets the %temp1 action list variable to Event3,
1944 %temp2 action list variable to Event1, and %size action list
1945 variable to 1.
1946 getaliases %<var> <name>
1948 Find all alias names for context <name>, join the names into a
1949 multi-line string "alias1<NEWLINE>...<NEWLINE>aliasn", and as‐
1950 sign this string to the action list variable %<var>. If the
1951 context <name> does not exist, the value of %<var> does not
1952 change.
1953 getltime %<var> <name>
1955 Find the lifetime of context <name>, and assign this number to
1956 the action list variable %<var>. If the context <name> does not
1957 exist, the value of %<var> does not change. For example, con‐
1958 sider the following action list definition:
1959 action=create TEST 10 ( getltime %time TEST; \
1961 logonly Context TEST with %time second lifetime has ex‐
1962 pired )
1963 The above create action configures the context TEST to log its
1965 lifetime when it expires.
1966 setltime <name> [<time>]
1968 Set the lifetime of context <name> to <time>. Specifying 0 for
1969 <time> or omitting the value means infinite lifetime. Note that
1970 unlike the set action, setltime does not adjust the context cre‐
1971 ation time. For example, if context TEST has been created at
1972 12:01:00 with the lifetime of 60 seconds, then after invoking
1973 setltime TEST 30 at 12:01:20 the context would exist until
1974 12:01:30, while invoking setltime TEST 10 would immediately ex‐
1975 pire the context.
1976 getctime %<var> <name>
1978 Find the creation time of context <name>, and assign this time‐
1979 stamp to the action list variable %<var>. The value assigned to
1980 %<var> is measured in seconds since Epoch (as reported by the
1981 time(2) system call). If the context <name> does not exist, the
1982 value of %<var> does not change.
1983 setctime <time> <name>
1985 Set the creation time of context <name> to <time>. The <time>
1986 parameter must evaluate to seconds since Epoch (as reported by
1987 the time(2) system call), and must reflect a time moment between
1988 the previous creation time and the current time (both endpoints
1989 included). For example, if context TEST has been created at
1990 12:43:00 with the lifetime of 60 seconds, then after invoking
1991 setctime %u TEST at 12:43:25 the context would exist until
1992 12:44:25 (the %u action list variable evaluates to current time
1993 in seconds since Epoch).
1994 event [<time>] [<string>]
1996 After <time> seconds, create a synthetic event <string>. If
1997 <string> is a multi-line string (i.e., it contains newlines), it
1998 is split into lines, and from each line a separate synthetic
1999 event is created. SEC will treat each synthetic event like a
2000 line from an input file -- the event will be matched against
2001 rules and it might trigger further actions. If the --intcon‐
2002 texts command line option is given, internal context _INTER‐
2003 NAL_EVENT is set up for synthetic event(s) (see INTERNAL EVENTS
2004 AND CONTEXTS section for more information). The <time> parame‐
2005 ter is an integer constant. Specifying 0 for <time> or omitting
2006 the value means "now". Default value for <string> is %s. For
2007 example, consider the following action list definition:
2008 action=copy EVENTS %events; event %events
2010 The above action list will create a synthetic event from each
2012 string in the event store of the EVENTS context.
2013 tevent <time> [<string>]
2015 Similar to the event action, except that the <time> parameter
2016 may contain variables and must evaluate to an unsigned integer
2017 at runtime.
2018 cevent <name> <time> [<string>]
2020 Similar to the tevent action, except that if the --intcontexts
2021 command line option is given, internal context <name> is set up
2022 for synthetic event(s).
2023 reset [<offset>] [<string>]
2025 Terminate event correlation operation(s) with the operation de‐
2026 scription string <string>. Note that the reset action works only
2027 for operations started from the same configuration file. The
2028 <offset> parameter is used to refer to a specific rule in the
2029 configuration file. If <offset> is given, the operation started
2030 by the given rule is terminated (if it exists). If <offset> is
2031 an unsigned integer N, it refers to the N-th rule in the config‐
2032 uration file. If <offset> is 0, it refers to the current rule.
2033 If <offset> begins with the plus (+) or minus (-) sign, it spec‐
2034 ifies an offset from the current rule (e.g., -1 denotes the pre‐
2035 vious and +1 the next rule). Note that since Options rules are
2036 only processed when configuration files are loaded and they are
2037 not applied at runtime, Options rules are excluded when calcu‐
2038 lating <offset>. If <offset> is not given, SEC checks for each
2039 rule from the current configuration file if an operation with
2040 <string> has been started by this rule, and the operation is
2041 terminated if it exists. Default value for <string> is %s. For
2042 additional information, see EVENT CORRELATION OPERATIONS sec‐
2043 tion. For example, consider the following action list defini‐
2044 tion:
2045 action=reset -1 Ten login failures observed from $1; reset 0
2047 If the above action list is executed by an event correlation op‐
2049 eration, the first reset action will terminate another event
2050 correlation operation which has been started by the previous
2051 rule and has the operation description string "Ten login fail‐
2052 ures observed from <host>" (<host> is the value of the $1 match
2053 variable). The second reset action will terminate the calling
2054 operation itself.
2055 getwpos %<var> <offset> [<string>]
2057 Find the beginning of the event correlation window for an event
2058 correlation operation, and set the action list variable %<var>
2059 to this timestamp. The value assigned to %<var> is measured in
2060 seconds since Epoch (as reported by the time(2) system call). As
2061 with the reset action, the event correlation operation is iden‐
2062 tified by the operation description string <string> and the rule
2063 offset <offset>. If the operation does not exist, the value of
2064 %<var> does not change. Default value for <string> is %s. For
2065 additional information, see EVENT CORRELATION OPERATIONS sec‐
2066 tion. For example, consider the following action list defini‐
2067 tion:
2068 action=getwpos %pos -1 Ten login failures observed from $1
2070 The above getwpos action will find the beginning of the event
2072 correlation window for an event correlation operation which has
2073 been started by the previous rule and has the operation descrip‐
2074 tion string "Ten login failures observed from <host>" (<host> is
2075 the value of the $1 match variable). If the event correlation
2076 window begins at April 6 08:03:53 2018 UTC, the value 1523001833
2077 will be assigned to the %pos action list variable.
2078 setwpos <time> <offset> [<string>]
2080 Set the beginning of the event correlation window to <time> for
2081 an event correlation operation (if it exists). The <time> param‐
2082 eter must evaluate to seconds since Epoch (as reported by the
2083 time(2) system call), and must reflect a time moment between the
2084 previous window position and the current time (both endpoints
2085 included). As with the reset action, the event correlation oper‐
2086 ation is identified by the operation description string <string>
2087 and the rule offset <offset>. Default value for <string> is %s.
2088 For additional information, see EVENT CORRELATION OPERATIONS
2089 section.
2090 assign %<var> [<string>]
2092 Assign string <string> to the action list variable %<var>. De‐
2093 fault value for <string> is %s.
2094 assignsq %<var> [<string>]
2096 Similar to the assign action, except that <string> is quoted
2097 with single quotes before assigning it to %<var>. If <string>
2098 contains single quotes, they are masked with backslashes (e.g.,
2099 if the match variable $1 holds the value abc'123'xyz, the action
2100 assignsq %myvar $1 assigns the value 'abc'\''123'\''xyz' to the
2101 action list variable %myvar). This action is useful for dis‐
2102 abling shell interpretation for the values of action list vari‐
2103 ables that appear in command lines executed by SEC. Default
2104 value for <string> is %s.
2105 free %<var>
2107 Unset the action list variable %<var>.
2108 eval %<var> <code>
2110 The parameter <code> is a Perl miniprogram that is compiled and
2111 executed by calling the Perl eval() function in the Perl list
2112 context. If the miniprogram returns a single value, it is as‐
2113 signed to the action list variable %<var>. If the miniprogram
2114 returns several values s1,...,sn, they are joined into a multi-
2115 line string "s1<NEWLINE>...<NEWLINE>sn", and this string is as‐
2116 signed to %<var>. If no value is returned, %<var> is set to
2117 Perl undefined value. If eval() fails, the value of %<var> does
2118 not change. Since most Perl programs contain semicolons which
2119 are also employed by SEC as action separators, it is recommended
2120 to enclose the <code> parameter in parentheses, in order to mask
2121 the semicolons in <code>. For additional information, see PERL
2122 INTEGRATION section. For example, consider the following action
2123 list definition:
2124 action=assign %div Division error; eval %div ( $1 / $2 )
2126 The assign action sets the %div action list variable to the
2128 string "Division error", while the eval action substitutes the
2129 values of $1 and $2 match variables into the string "$1 / $2".
2130 Resulting string is treated as Perl code which is first compiled
2131 and then executed. For instance, if the values of $1 and $2 are
2132 12 and 4, respectively, the following Perl code is compiled: 12
2133 / 4. Since executing this code yields 3, the eval action assigns
2134 this value to the %div action list variable. Also, if $2 has no
2135 value or its value is 0, resulting code leads to compilation or
2136 execution error, and %div retains its previous value "Division
2137 error".
2138 call %<var> %<ref> [<paramlist>]
2140 Call the precompiled Perl function referenced by the action list
2141 variable %<ref>, and assign the result to the action list vari‐
2142 able %<var>. The %<ref> parameter must be a code reference that
2143 has been previously created with the eval action. The <param‐
2144 list> parameter (if given) is a string which specifies parame‐
2145 ters for the function. The parameters must be separated by
2146 whitespace in the <paramlist> string. If the function returns a
2147 single value, it is assigned to %<var>. If the function returns
2148 several values s1,...,sn, they are joined into a multi-line
2149 string "s1<NEWLINE>...<NEWLINE>sn", and this string is assigned
2150 to %<var>. If no value is returned, %<var> is set to Perl unde‐
2151 fined value. If the function encounters a fatal runtime error
2152 or %<ref> is not a code reference, the value of %<var> does not
2153 change. For additional information, see PERL INTEGRATION sec‐
2154 tion. For example, consider the following action list defini‐
2155 tion:
2156 action=eval %func ( sub { return $_[0] + $_[1] } ); \
2158 call %sum %func $1 $2
2159 Since the Perl code provided to eval action is a definition of
2161 an anonymous function, its compilation yields a code reference
2162 which gets assigned to the %func action list variable (the func‐
2163 tion returns the sum of its two input parameters). The call ac‐
2164 tion will invoke previously compiled function, using the values
2165 of $1 and $2 match variables as function parameters, and assign‐
2166 ing function return value to the %sum action list variable.
2167 Therefore, if the values of $1 and $2 are 2 and 3, respectively,
2168 %sum is set to 5.
2169 lcall %<var> [<paramlist>] -> <code>
2171 lcall %<var> [<paramlist>] :> <code>
2173 Call the precompiled Perl function <code> and assign the result
2174 to the action list variable %<var>. The <code> parameter must
2175 be a valid Perl anonymous function definition that is compiled
2176 at SEC startup with the Perl eval() function, and eval() must
2177 return a code reference. The <paramlist> parameter (if given)
2178 is a string which specifies parameters for the function. The pa‐
2179 rameters must be separated by whitespace in the <paramlist>
2180 string. If <paramlist> is followed by -> operator, parameters
2181 are passed to function as Perl scalar values. If <paramlist> is
2182 followed by :> operator, it is assumed that each parameter is a
2183 name of an entry in the pattern match cache. If an entry with
2184 the given name does not exist, Perl undefined value is passed to
2185 the function. If an entry with the given name exists, a refer‐
2186 ence to the entry is passed to the function. Internally, each
2187 pattern match cache entry is implemented as a Perl hash which
2188 contains all match variables for the given entry. If the func‐
2189 tion returns a single value, it is assigned to %<var>. If the
2190 function returns several values s1,...,sn, they are joined into
2191 a multi-line string "s1<NEWLINE>...<NEWLINE>sn", and this string
2192 is assigned to %<var>. If no value is returned, %<var> is set to
2193 Perl undefined value. If the function encounters a fatal run‐
2194 time error, the value of %<var> does not change. Since most
2195 Perl functions contain semicolons which are also employed by SEC
2196 as action separators, it is recommended to enclose the <code>
2197 parameter in parentheses, in order to mask the semicolons in
2198 <code>. For additional information, see PERL INTEGRATION sec‐
2199 tion. For example, consider the following action list defini‐
2200 tion:
2201 action=lcall %len $1 -> ( sub { return length($_[0]) } )
2203 The above lcall action will take the value of the $1 match vari‐
2205 able and find its length in characters, assigning the length to
2206 the %len action list variable. Note that the function for find‐
2207 ing the length is compiled when SEC loads its configuration, and
2208 all invocations of lcall will execute already compiled code. As
2209 another example, consider the following action list definition:
2210 action=lcall %o SSH :> ( sub { $_[0]->{"failure"} = 1 } )
2212 The above lcall action will assign 1 to the $+{failure} match
2214 variable that has been cached under the SSH entry in the pattern
2215 match cache (variable will be created if it did not exist previ‐
2216 ously).
2217 rewrite <lnum> [<string>]
2219 Replace last <lnum> lines in the input buffer with string
2220 <string>. If the --nojointbuf option was specified and the ac‐
2221 tion is triggered by a matching event, the action modifies the
2222 buffer which holds this event. If the --nojointbuf option was
2223 specified and the action is triggered by the system clock (e.g.,
2224 the action is executed from the Calendar rule), the action modi‐
2225 fies the buffer which holds the last already processed event.
2226 With the --jointbuf option, the content of the joint input buf‐
2227 fer is rewritten. The <lnum> parameter must evaluate to an un‐
2228 signed integer at runtime. If <lnum> evaluates to 0, <lnum> is
2229 reset to the number of lines in <string>. If the value of
2230 <lnum> is greater than the buffer size N, <lnum> is reset to N.
2231 If <string> contains less than <lnum> lines, <string> will be
2232 padded with leading empty lines. If <string> contains more than
2233 <lnum> lines, only leading <lnum> lines from <string> are writ‐
2234 ten into the buffer. Default value for <string> is %s. For ad‐
2235 ditional information, see INPUT PROCESSING AND TIMING section.
2236 addinput <filename> [<offset> [<name>] ]
2238 File <filename> is added to the list of input files and opened,
2239 so that processing starts from file offset <offset>. The <off‐
2240 set> parameter must evaluate to unsigned integer or - (EOF) at
2241 runtime. If <offset> is not specified, it defaults to - (i.e.,
2242 processing starts from the end of file). If opening the file
2243 fails (e.g., the file does not exist), it will stay in the list
2244 of input files (e.g., with the --reopen-timeout command line op‐
2245 tion, SEC will attempt to reopen the file). The <name> parame‐
2246 ter defines the internal context which should be used for <file‐
2247 name> if the --intcontexts command line option is given (if
2248 <name> is omitted but --intcontexts command line option is
2249 present, default internal context will be used). See INTERNAL
2250 EVENTS AND CONTEXTS section for more information. For example,
2251 consider the following action list definition:
2252 action=addinput /var/log/test-%{.year}%{.mon}%{.mday} 0 TESTFILE
2254 The above addinput action adds the file /var/log/test-YYYYMMDD
2256 to the list of input files, where YYYYMMDD reflects the current
2257 date. The addinput action will also attempt to open the file,
2258 and if open succeeds, file will be processed from the beginning.
2259 Also, the internal context TESTFILE will be used for all events
2260 read from the file.
2261 dropinput <filename>
2263 File <filename> is dropped from the list of input files and
2264 closed (if currently open). Note that dropinput action can only
2265 be used for input files which have been previously set up with
2266 addinput action.
2267 sigemul <signal>
2269 Emulates the arrival of signal <signal> and triggers its han‐
2270 dler. The <signal> parameter must evaluate to one of the fol‐
2271 lowing strings: HUP, ABRT, USR1, USR2, INT, or TERM. For exam‐
2272 ple, the action sigemul USR1 triggers the generation of SEC dump
2273 file. See the SIGNALS section for detailed information on sig‐
2274 nals that are handled by SEC.
2275 varset %<var> <entry>
2277 If the pattern match cache entry <entry> exists, set the action
2278 list variable %<var> to 1, otherwise set %<var> to 0. For exam‐
2279 ple, if pattern match cache contains the entry with the name SSH
2280 but not the entry with the name NTP, the action varset %ssh SSH
2281 will set the %ssh action list variable to 1, while the action
2282 varset %ntp NTP will set the %ntp action list variable to 0.
2283 if %<var> ( <action list> ) [ else ( <action list2> ) ]
2285 If the action list variable %<var> evaluates true in the Perl
2286 boolean context (i.e., it holds a defined value which is neither
2287 0 nor empty string), execute the action list <action list>. If
2288 the second action list <action list2> is given with the optional
2289 else-statement, it is executed if %<var> either does not exist
2290 or evaluates false (i.e., %<var> holds 0, empty string or Perl
2291 undefined value). For example, consider the following action
2292 list definition:
2293 action=exists %present REPORT; if %present \
2295 ( report REPORT /bin/mail root@localhost; delete REPORT
2296 ) \
2297 else ( logonly Nothing to report )
2298 If the REPORT context exists, its event store is mailed to
2300 root@localhost and the context is deleted, otherwise the message
2301 "Nothing to report" is logged.
2302 while %<var> ( <action list> )
2304 Execute the action list <action list> repeatedly as long as the
2305 action list variable %<var> evaluates true in the Perl boolean
2306 context (i.e., it holds a defined value which is neither 0 nor
2307 empty string). For example, consider the following action list
2308 definition:
2309 action=create REVERSE; getsize %n TEST; \
2311 while %n ( pop TEST %e; add REVERSE %e; getsize %n TEST
2312 ); \
2313 copy REVERSE %events; fill TEST %events
2314 This action list reverses the order of strings in the event
2316 store of the context TEST, using the context REVERSE as a tempo‐
2317 rary storage. During each iteration of the while-loop, the last
2318 string in the event store of TEST is removed with the pop action
2319 and appended to the event store of REVERSE with the add action.
2320 The loop terminates when all strings have been removed from the
2321 event store of TEST (i.e., the getsize action reports 0 for
2322 event store size). Finally, the event store of REVERSE is as‐
2323 signed to the %events action list variable with the copy action,
2324 and the fill action is used for overwriting the event store of
2325 TEST with the value of %events.
2326 break If used inside a while-loop, terminates its execution; otherwise
2328 terminates the execution of the entire action list.
2329 continue
2331 If used inside a while-loop, starts the next iteration of the
2332 loop; otherwise terminates the execution of the entire action
2333 list.
2334 Examples:
2336 Follow the /var/log/trapd.log file and feed to SEC input all lines that
2338 are appended to the file:
2339 action=spawn /bin/tail -f /var/log/trapd.log
2341 Mail the timestamp and the value of the $0 variable to the local root:
2343 action=pipe '%t: $0' /bin/mail -s "alert message" root@localhost
2345 Add the value of the $0 variable to the event store of the context
2347 ftp_<the value of $1>, and set the context to expire after 30 minutes.
2348 When the context expires, its event store will be mailed to the local
2349 root:
2350 action=add ftp_$1 $0; \
2352 set ftp_$1 1800 (report ftp_$1 /bin/mail root@localhost)
2353 Create a subroutine for weeding out comment lines from the input list,
2355 and use this subroutine for removing comment lines from the event store
2356 of the context C1:
2357 action=eval %funcptr ( sub { my(@buf) = split(/\n/, $_[0]); \
2359 my(@ret) = grep(!/^#/, @buf); return @ret; } ); \
2360 copy C1 %in; call %out %funcptr %in; fill C1 %out
2361 The following action list achieves the same goal as the previous action
2363 list with while and if actions:
2364 action=getsize %size C1; while %size ( shift C1 %event; \
2366 lcall %nocomment %event -> ( sub { $_[0] !~ /^#/ } ); \
2367 if %nocomment ( add C1 %event ); \
2368 lcall %size %size -> ( sub { $_[0]-1; } ) )
2369
2371 As already noted, SEC context expressions and action lists may contain
2372 parentheses which are used for grouping and masking purposes. When SEC
2373 parses its configuration, it checks whether parentheses in context ex‐
2374 pressions and action lists are balanced (i.e., whether each parenthesis
2375 has a counterpart), since unbalanced parentheses introduce ambiguity.
2376 This can cause SEC to reject some legitimate constructs, e.g.,
2377 action=eval %o (print ")";)
2379 is considered an invalid action list (however, note that
2381 action=eval %o (print "()";)
2382 would be passed by SEC, since now parentheses are balanced). In order
2383 to avoid such parsing errors, each parenthesis without a counterpart
2384 must be masked with a backslash (the backslash will be removed by SEC
2385 during configuration file parsing). For example, the above action could
2386 be written as
2387 action=eval %o (print "\)";)
2389
2391 This section provides a detailed discussion of SEC rule types.
2392 SINGLE RULE
2394 The Single rule supports the following fields. Note that match vari‐
2395 ables may be used in context, desc, and action fields.
2396 type fixed to Single (value is case insensitive, so single or sIngLe
2398 can be used instead).
2399 continue (optional)
2401 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2402 bel>, values are case insensitive).
2403 ptype pattern type (value is case insensitive).
2405 pattern
2407 pattern.
2408 varmap (optional)
2410 variable map.
2411 context (optional)
2413 context expression.
2414 desc operation description string.
2416 action action list.
2418 rem (optional, may appear more than once)
2420 remarks and comments.
2421 The Single rule immediately executes an action list when an event has
2423 matched the rule. An event matches the rule if the pattern matches the
2424 event and the context expression (if given) evaluates TRUE.
2425 Note that the Single rule does not start event correlation operations,
2427 and the desc field is merely used for setting the %s action list vari‐
2428 able.
2429 Examples:
2431 type=single
2433 continue=takenext
2434 ptype=regexp
2435 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session opened
2436 desc=ftp session opened for ristov2 pid $1
2437 action=create ftp_$1
2438 type=single
2440 continue=takenext
2441 ptype=regexp
2442 pattern=ftpd\[(\d+)\]:
2443 context=ftp_$1
2444 desc=ftp session event for ristov2 pid $1
2445 action=add ftp_$1 $0; set ftp_$1 1800 \
2446 (report ftp_$1 /bin/mail root@localhost)
2447 type=single
2449 ptype=regexp
2450 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session closed
2451 desc=ftp session closed for ristov2 pid $1
2452 action=report ftp_$1 /bin/mail root@localhost; \
2453 delete ftp_$1
2454 This ruleset is created for monitoring the ftpd log file. The first
2456 rule creates the context ftp_<pid> when someone connects from host ris‐
2457 tov2 over FTP and establishes a new ftp session (the session is identi‐
2458 fied by the PID of the process which has been created for handling this
2459 session). The second rule adds all further log file lines for the ses‐
2460 sion <pid> to the event store of the context ftp_<pid> (before adding a
2461 line, the rule checks if the context exists). After adding a line, the
2462 rule extends context's lifetime for 30 minutes and sets the action list
2463 that will be executed when the context expires. The third rule mails
2464 collected log file lines to root@localhost when the session <pid> is
2465 closed. Collected lines will also be mailed when the session <pid> has
2466 been inactive for 30 minutes (no log file lines observed for that ses‐
2467 sion).
2468 Note that the log file line that has matched the first rule is also
2470 matched against the second rule (since the first rule has the continue
2471 field set to TakeNext). Since the second rule always matches this
2472 line, it will become the first line in the event store of ftp_<pid>.
2473 The second rule has also its continue field set to TakeNext, since oth‐
2474 erwise no log file lines would reach the third rule.
2475 SINGLEWITHSCRIPT RULE
2477 The SingleWithScript rule supports the following fields. Note that
2478 match variables may be used in context, script, desc, action, and ac‐
2479 tion2 fields.
2480 type fixed to SingleWithScript (value is case insensitive).
2482 continue (optional)
2484 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2485 bel>, values are case insensitive).
2486 ptype pattern type (value is case insensitive).
2488 pattern
2490 pattern.
2491 varmap (optional)
2493 variable map.
2494 context (optional)
2496 context expression.
2497 script command line of external program.
2499 shell (optional)
2501 Yes or No (values are case insensitive, default is Yes).
2502 desc operation description string.
2504 action action list.
2506 action2 (optional)
2508 action list.
2509 rem (optional, may appear more than once)
2511 remarks and comments.
2512 The SingleWithScript rule forks a process for executing an external
2514 program when an event has matched the rule. The command line of the
2515 external program is defined by the script field.
2516 If the shell field is set to Yes (this is the default), the command
2518 line of the external program will be parsed by shell if the command
2519 line contains shell metacharacters. If the shell field is set to No,
2520 command line is not parsed by shell, but split into arguments by using
2521 whitespace as a separator, and passed to execvp(3) for execution. Note
2522 that splitting into arguments is done when command line is loaded from
2523 the configuration file and parsed, not at runtime (e.g., if command
2524 line is /usr/local/bin/mytool $1 $2, the values of $1 and $2 variables
2525 are regarded as single arguments even if the values contain white‐
2526 space).
2527 The names of all currently existing contexts are written to the stan‐
2529 dard input of the program. After the program has been forked, the rule
2530 matching continues immediately, and the program status will be checked
2531 periodically until the program exits. If the program returns 0 exit
2532 status, the action list defined by the action field is executed; other‐
2533 wise the action list defined by the action2 field is executed (if
2534 given).
2535 Note that the SingleWithScript rule does not start event correlation
2537 operations, and the desc field is merely used for setting the %s action
2538 list variable.
2539 Examples:
2541 type=SingleWithScript
2543 ptype=RegExp
2544 pattern=interface ([\d.]+) down
2545 script=/bin/ping -c 3 -q $1
2546 desc=Check if $1 responds to ping
2547 action=logonly Interface $1 reported down, but is pingable
2548 action2=pipe '%t: Interface $1 is down' /bin/mail root@localhost
2549 When "interface <ipaddress> down" line appears in input, the rule
2551 checks if <ipaddress> responds to ping. If <ipaddress> is pingable, the
2552 message "Interface <ipaddress> reported down, but is pingable" is
2553 logged; otherwise an e-mail warning containing a human-readable time‐
2554 stamp is sent to root@localhost.
2555 SINGLEWITHSUPPRESS RULE
2557 The SingleWithSuppress rule supports the following fields. Note that
2558 match variables may be used in context, desc, and action fields.
2559 type fixed to SingleWithSuppress (value is case insensitive).
2561 continue (optional)
2563 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2564 bel>, values are case insensitive).
2565 ptype pattern type (value is case insensitive).
2567 pattern
2569 pattern.
2570 varmap (optional)
2572 variable map.
2573 context (optional)
2575 context expression.
2576 desc operation description string.
2578 action action list.
2580 window event correlation window size (value is an integer constant).
2582 rem (optional, may appear more than once)
2584 remarks and comments.
2585 The SingleWithSuppress rule runs event correlation operations for fil‐
2587 tering repeated instances of the same event during T seconds. The value
2588 of T is defined by the window field.
2589 When an event has matched the rule, SEC evaluates the operation de‐
2591 scription string given with the desc field. If the operation for the
2592 given string and rule does not exist, SEC will create it with the life‐
2593 time of T seconds, and the operation immediately executes an action
2594 list. If the operation exists, it consumes the matching event without
2595 any action.
2596 Examples:
2598 type=SingleWithSuppress
2600 ptype=RegExp
2601 pattern=(\S+): [fF]ile system full
2602 desc=File system $1 full
2603 action=pipe '%t: %s' /bin/mail root@localhost
2604 window=900
2605 This rule runs event correlation operations for processing "file system
2607 full" syslog messages, e.g.,
2608 Dec 16 14:26:09 test ufs: [ID 845546 kern.notice] NOTICE: alloc: /var:
2610 file system full
2611 When the first message for a file system is observed, an operation is
2613 created which sends an e-mail warning about this file system to
2614 root@localhost. The operation will then run for 900 seconds and
2615 silently consume further messages for the *same* file system. However,
2616 if a message for a different file system is observed, another operation
2617 will be started which sends a warning to root@localhost again (since
2618 the desc field contains the $1 match variable which evaluates to the
2619 file system name).
2620 PAIR RULE
2622 The Pair rule supports the following fields. Note that match variables
2623 may be used in context, desc, action, pattern2, context2, desc2, and
2624 action2 fields.
2625 type fixed to Pair (value is case insensitive).
2627 continue (optional)
2629 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2630 bel>, values are case insensitive). Specifies the point-of-con‐
2631 tinue after a match by pattern and context.
2632 ptype pattern type for pattern (value is case insensitive).
2634 pattern
2636 pattern.
2637 varmap (optional)
2639 variable map for pattern.
2640 context (optional)
2642 context expression, evaluated together with pattern.
2643 desc operation description string.
2645 action action list.
2647 continue2 (optional)
2649 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2650 bel>, values are case insensitive). Specifies the point-of-con‐
2651 tinue after a match by pattern2 and context2.
2652 ptype2 pattern type for pattern2 (value is case insensitive).
2654 pattern2
2656 pattern.
2657 varmap2 (optional)
2659 variable map for pattern2.
2660 context2 (optional)
2662 context expression, evaluated together with pattern2.
2663 desc2 format string that sets the %s variable for action2.
2665 action2
2667 action list.
2668 window (optional)
2670 event correlation window size (value is an integer constant).
2671 rem (optional, may appear more than once)
2673 remarks and comments.
2674 The Pair rule runs event correlation operations for processing event
2676 pairs during T seconds. The value of T is defined by the window field.
2677 Default value is 0 which means infinity.
2678 When an event has matched the conditions defined by the pattern and
2680 context field, SEC evaluates the operation description string given
2681 with the desc field. If the operation for the given string and rule
2682 exists, it consumes the matching event without any action. If the oper‐
2683 ation does not exist, SEC will create it with the lifetime of T sec‐
2684 onds, and the operation immediately executes an action list defined by
2685 the action field. SEC will also copy the match conditions given with
2686 the pattern2 and context2 field into the operation, and substitute
2687 match variables with their values in copied conditions.
2688 If the event does not match conditions defined by the pattern and con‐
2690 text field, SEC will check the match conditions of all operations
2691 started by the given rule. Each matching operation executes the action
2692 list given with the action2 field and finishes.
2693 If match variables are set when the operation matches an event, they
2695 are made available as $-prefixed match variables in context2, desc2,
2696 and action2 fields of the rule definition. For example, if pattern2
2697 field is a regular expression, then $1 in the desc2 field is set by
2698 pattern2. In order to access match variables set by pattern, %-pre‐
2699 fixed match variables have to be used in context2, desc2, and action2
2700 fields. For example, if pattern and pattern2 are regular expressions,
2701 then %1 in the desc2 field refers to the value set by the first capture
2702 group in pattern (i.e., it has the same value as $1 in the desc field).
2703 Examples:
2705 type=Pair
2707 ptype=RegExp
2708 pattern=kernel: nfs: server (\S+) not responding, still trying
2709 desc=Server $1 is not responding
2710 action=pipe '%t: %s' /bin/mail root@localhost
2711 ptype2=SubStr
2712 pattern2=kernel: nfs: server $1 OK
2713 desc2=Server $1 is responding again
2714 action2=logonly
2715 window=3600
2716 This rule runs event correlation operations for processing NFS "server
2718 not responding" and "server OK" syslog messages, e.g.,
2719 Dec 18 22:39:48 test kernel: nfs: server box1 not responding, still
2721 trying
2722 Dec 18 22:42:27 test kernel: nfs: server box1 OK
2723 When the "server not responding" message for an NFS server is observed,
2725 an operation is created for this server which sends an e-mail warning
2726 about the server to root@localhost. The operation will then run for
2727 3600 seconds and silently consume further "server not responding" mes‐
2728 sages for the same server. If this operation observes "server OK" mes‐
2729 sage for the *same* server, it will log the message "Server <server‐
2730 name> is responding again" and finish.
2731 For example, if SEC observes the following event at 22:39:48
2733 Dec 18 22:39:48 test kernel: nfs: server box1 not responding, still
2735 trying
2736 an event correlation operation is created for server box1 which issues
2738 an e-mail warning about this server immediately. After that, the opera‐
2739 tion will run for 3600 seconds (until 23:39:48), waiting for an event
2740 which would contain the substring "kernel: nfs: server box1 OK" (be‐
2741 cause the pattern2 field contains the $1 match variable which evaluates
2742 to the server name).
2743 If any further error messages appear for server box1 during the 3600
2745 second lifetime of the operation, e.g.,
2746 Dec 18 22:40:28 test kernel: nfs: server box1 not responding, still
2748 trying
2749 Dec 18 22:41:09 test kernel: nfs: server box1 not responding, still
2750 trying
2751 these messages will be silently consumed by the operation. If before
2753 its expiration the operation observes an event which contains the sub‐
2754 string "kernel: nfs: server box1 OK", e.g.,
2755 Dec 18 22:42:27 test kernel: nfs: server box1 OK
2757 the operation will log the message "Server box1 is responding again"
2759 and terminate immediately. If no such message appears during the 3600
2760 second lifetime of the operation, the operation will expire without
2761 taking any action. Please note that if the window field would be either
2762 removed from the rule definition or set to 0, the operation would never
2763 silently expire, but would terminate only after observing an event
2764 which contains the substring "kernel: nfs: server box1 OK".
2765 If the above rule is modified in the following way
2767 type=Pair
2769 ptype=RegExp
2770 pattern=^([[:alnum:]: ]+) \S+ kernel: nfs: server (\S+) not responding,
2771 still trying
2772 desc=Server $2 is not responding
2773 action=logonly
2774 ptype2=RegExp
2775 pattern2=^([[:alnum:]: ]+) \S+ kernel: nfs: server $2 OK
2776 desc2=Server %2 was not accessible from %1 to $1
2777 action2=pipe '%s' /bin/mail root@localhost
2778 window=86400
2779 this rule will run event correlation operations which report NFS server
2781 downtime to root@localhost via e-mail, provided that downtime does not
2782 exceed 24 hours (86400 seconds).
2783 For example, if SEC observes the following event
2785 Dec 18 23:01:17 test kernel: nfs: server box.test not responding, still
2787 trying
2788 then the rule matches this event, sets $1 match variable to "Dec 18
2790 23:01:17" and $2 to "box.test", and creates an event correlation opera‐
2791 tion for server box.test. This operation will start its work by log‐
2792 ging the message "Server box.test is not responding", and will then run
2793 for 86400 seconds, waiting for an event which would match the regular
2794 expression
2795 ^([[:alnum:]: ]+) \S+ kernel: nfs: server box\.test OK
2797 Note that this expression was created from the regular expression tem‐
2799 plate in the pattern2 field by substituting the match variable $2 with
2800 its value. However, since the string "box.test" contains the dot (.)
2801 character which is a regular expression metacharacter, the dot is
2802 masked with the backslash in the regular expression.
2803 Suppose SEC will then observe the event
2805 Dec 18 23:09:54 test kernel: nfs: server box.test OK
2807 This event matches the above regular expression which is used by the
2809 operation running for server box.test. Also, the regular expression
2810 match sets the $1 variable to "Dec 18 23:09:54" and unsets the $2 vari‐
2811 able. In order to refer to their original values when the operation was
2812 created, %1 and %2 match variables have to be used in the desc2 field
2813 (%1 equals to "Dec 18 23:01:17" and %2 equals to "box.test"). There‐
2814 fore, the operation will send the e-mail message "Server box.test was
2815 not accessible from Dec 18 23:01:17 to Dec 18 23:09:54" to root@local‐
2816 host, and will terminate immediately.
2817 PAIRWITHWINDOW RULE
2819 The PairWithWindow rule supports the following fields. Note that match
2820 variables may be used in context, desc, action, pattern2, context2,
2821 desc2, and action2 fields.
2822 type fixed to PairWithWindow (value is case insensitive).
2824 continue (optional)
2826 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2827 bel>, values are case insensitive). Specifies the point-of-con‐
2828 tinue after a match by pattern and context.
2829 ptype pattern type for pattern (value is case insensitive).
2831 pattern
2833 pattern.
2834 varmap (optional)
2836 variable map for pattern.
2837 context (optional)
2839 context expression, evaluated together with pattern.
2840 desc operation description string.
2842 action action list.
2844 continue2 (optional)
2846 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2847 bel>, values are case insensitive). Specifies the point-of-con‐
2848 tinue after a match by pattern2 and context2.
2849 ptype2 pattern type for pattern2 (value is case insensitive).
2851 pattern2
2853 pattern.
2854 varmap2 (optional)
2856 variable map for pattern2.
2857 context2 (optional)
2859 context expression, evaluated together with pattern2.
2860 desc2 format string that sets the %s variable for action2.
2862 action2
2864 action list.
2865 window event correlation window size (value is an integer constant).
2867 rem (optional, may appear more than once)
2869 remarks and comments.
2870 The PairWithWindow rule runs event correlation operations for process‐
2872 ing event pairs during T seconds. The value of T is defined by the win‐
2873 dow field.
2874 When an event has matched the conditions defined by the pattern and
2876 context field, SEC evaluates the operation description string given
2877 with the desc field. If the operation for the given string and rule
2878 exists, it consumes the matching event without any action. If the oper‐
2879 ation does not exist, SEC will create it with the lifetime of T sec‐
2880 onds. SEC will also copy the match conditions given with the pattern2
2881 and context2 field into the operation, and substitute match variables
2882 with their values in copied conditions.
2883 If the event does not match conditions defined by the pattern and con‐
2885 text field, SEC will check the match conditions of all operations
2886 started by the given rule. Each matching operation executes the action
2887 list given with the action2 field and finishes. If the operation has
2888 not observed a matching event by the end of its lifetime, it executes
2889 the action list given with the action field before finishing.
2890 If match variables are set when the operation matches an event, they
2892 are made available as $-prefixed match variables in context2, desc2,
2893 and action2 fields of the rule definition. For example, if pattern2
2894 field is a regular expression, then $1 in the desc2 field is set by
2895 pattern2. In order to access match variables set by pattern, %-pre‐
2896 fixed match variables have to be used in context2, desc2, and action2
2897 fields. For example, if pattern and pattern2 are regular expressions,
2898 then %1 in the desc2 field refers to the value set by the first capture
2899 group in pattern (i.e., it has the same value as $1 in the desc field).
2900 Examples:
2902 type=PairWithWindow
2904 ptype=RegExp
2905 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
2906 desc=User $1 has been unable to log in from $2 over SSH during 1 minute
2907 action=pipe '%t: %s' /bin/mail root@localhost
2908 ptype2=RegExp
2909 pattern2=sshd\[\d+\]: Accepted .+ for $1 from $2 port \d+ ssh2
2910 desc2=SSH login successful for %1 from %2 after initial failure
2911 action2=logonly
2912 window=60
2913 This rule runs event correlation operations for processing SSH login
2915 events, e.g.,
2916 Dec 27 19:00:24 test sshd[10526]: Failed password for risto from
2918 10.1.2.7 port 52622 ssh2
2919 Dec 27 19:00:27 test sshd[10526]: Accepted password for risto from
2920 10.1.2.7 port 52622 ssh2
2921 When an SSH login failure is observed for a user name and a source IP
2923 address, an operation is created for this user name and IP address com‐
2924 bination which will expect a successful login for the *same* user name
2925 and *same* IP address during 60 seconds. If the user will not log in
2926 from the same IP address during 60 seconds, the operation will send an
2927 e-mail warning to root@localhost before finishing, otherwise it will
2928 log the message "SSH login successful for <username> from <ipaddress>
2929 after initial failure" and finish.
2930 Suppose the following events are generated by an SSH daemon, and each
2932 event timestamp reflects the time SEC observes the event:
2933 Dec 30 13:02:01 test sshd[30517]: Failed password for risto from
2935 10.1.2.7 port 42172 ssh2
2936 Dec 30 13:02:30 test sshd[30810]: Failed password for root from
2937 192.168.1.104 port 46125 ssh2
2938 Dec 30 13:02:37 test sshd[30517]: Failed password for risto from
2939 10.1.2.7 port 42172 ssh2
2940 Dec 30 13:02:59 test sshd[30810]: Failed password for root from
2941 192.168.1.104 port 46125 ssh2
2942 Dec 30 13:03:04 test sshd[30810]: Accepted password for root from
2943 192.168.1.104 port 46125 ssh2
2944 When the first event is observed at 13:02:01, an operation is started
2946 for user risto and IP address 10.1.2.7 which will expect a successful
2947 login for risto from 10.1.2.7. The operation will run for 60 seconds,
2948 waiting for an event which would match the regular expression
2949 sshd\[\d+\]: Accepted .+ for risto from 10\.1\.2\.7 port \d+ ssh2
2951 Note that this expression was created from the regular expression tem‐
2953 plate in the pattern2 field by substituting match variables $1 and $2
2954 with their values. However, since the value of $2 contains the dot (.)
2955 characters which are regular expression metacharacters, each dot is
2956 masked with the backslash in the regular expression.
2957 When the second event is observed at 13:02:30, another operation is
2959 started for user root and IP address 192.168.1.104 which will expect
2960 root to log in successfully from 192.168.1.104. This operation will run
2961 for 60 seconds, waiting for an event matching the regular expression
2962 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2964 The third event at 13:02:37 represents a second login failure for user
2966 risto and IP address 10.1.2.7, and is silently consumed by the first
2967 operation. Likewise, the fourth event at 13:02:59 is silently consumed
2968 by the second operation. The first operation will run until 13:03:01
2969 and then expire without seeing a successful login for risto from
2970 10.1.2.7. Before terminating, the operation will send an e-mail warning
2971 to root@localhost that user risto has not managed to log in from
2972 10.1.2.7 during one minute. At 13:03:04, the second operation will ob‐
2973 serve an event which matches its regular expression
2974 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2976 After seeing this event, the operation will log the message "SSH login
2978 successful for root from 192.168.1.104 after initial failure" and ter‐
2979 minate immediately. Please note that the match by the regular expres‐
2980 sion
2981 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2983 sets the $1 match variable to 1 and unsets $2. Therefore, the %1 and %2
2985 match variables have to be used in the desc2 field, in order to refer
2986 to the original values of $1 (root) and $2 (192.168.1.104) when the op‐
2987 eration was created.
2988 SINGLEWITHTHRESHOLD RULE
2990 The SingleWithThreshold rule supports the following fields. Note that
2991 match variables may be used in context, desc, action, and action2
2992 fields.
2993 type fixed to SingleWithThreshold (value is case insensitive).
2995 continue (optional)
2997 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2998 bel>, values are case insensitive).
2999 ptype pattern type (value is case insensitive).
3001 pattern
3003 pattern.
3004 varmap (optional)
3006 variable map.
3007 context (optional)
3009 context expression.
3010 desc operation description string.
3012 action action list.
3014 action2 (optional)
3016 action list.
3017 window event correlation window size (value is an integer constant).
3019 thresh counting threshold (value is an integer constant).
3021 rem (optional, may appear more than once)
3023 remarks and comments.
3024 The SingleWithThreshold rule runs event correlation operations for
3026 counting repeated instances of the same event during T seconds, and
3027 taking an action if N events are observed. The values of T and N are
3028 defined by the window and thresh field, respectively.
3029 When an event has matched the rule, SEC evaluates the operation de‐
3031 scription string given with the desc field. If the operation for the
3032 given string and rule does not exist, SEC will create it with the life‐
3033 time of T seconds. The operation will memorize the occurrence time of
3034 the event (current time as returned by the time(2) system call), and
3035 compare the number of memorized occurrence times with the threshold N.
3036 If the operation has observed N events, it executes the action list de‐
3037 fined by the action field, and consumes all further matching events
3038 without any action. If the rule has an optional action list defined
3039 with the action2 field, the operation will execute it before finishing,
3040 provided that the action list given with action has been previously ex‐
3041 ecuted by the operation. Note that a sliding window is employed for
3042 event counting -- if the operation has observed less than N events by
3043 the end of its lifetime, it drops occurrence times which are older than
3044 T seconds, and extends its lifetime for T seconds from the earliest re‐
3045 maining occurrence time. If there are no remaining occurrence times,
3046 the operation finishes without executing an action list.
3047 Examples:
3049 type=SingleWithThreshold
3051 ptype=RegExp
3052 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
3053 desc=Three SSH login failures within 1m for user $1
3054 action=pipe '%t: %s' /bin/mail root@localhost
3055 window=60
3056 thresh=3
3057 This rule runs event correlation operations for counting the number of
3059 SSH login failure events. Each operation counts events for one user
3060 name, and if the operation has observed three login failures within 60
3061 seconds, it sends an e-mail warning to root@localhost.
3062 Suppose the following events are generated by an SSH daemon, and each
3064 event timestamp reflects the time SEC observes the event:
3065 Dec 28 01:42:21 test sshd[28132]: Failed password for risto from
3067 10.1.2.7 port 42172 ssh2
3068 Dec 28 01:43:10 test sshd[28132]: Failed password for risto from
3069 10.1.2.7 port 42172 ssh2
3070 Dec 28 01:43:29 test sshd[28132]: Failed password for risto from
3071 10.1.2.7 port 42172 ssh2
3072 Dec 28 01:44:00 test sshd[28149]: Failed password for risto2 from
3073 10.1.2.7 port 42176 ssh2
3074 Dec 28 01:44:03 test sshd[28211]: Failed password for risto from
3075 10.1.2.7 port 42192 ssh2
3076 Dec 28 01:44:07 test sshd[28211]: Failed password for risto from
3077 10.1.2.7 port 42192 ssh2
3078 When the first event is observed at 01:42:21, a counting operation is
3080 started for user risto, with its event correlation window ending at
3081 01:43:21. Since by 01:43:21 two SSH login failures for user risto have
3082 occurred, the threshold condition remains unsatisfied for the opera‐
3083 tion. Therefore, the beginning of its event correlation window will be
3084 moved to 01:43:10 (the occurrence time of the second event), leaving
3085 the first event outside the window. At 01:44:00, another counting op‐
3086 eration is started for user risto2. The threshold condition for the
3087 first operation will become satisfied at 01:44:03 (since the operation
3088 has seen three login failure events for user risto within 60 seconds),
3089 and thus an e-mail warning will be issued. Finally, the event occurring
3090 at 01:44:07 will be consumed silently by the first operation (the oper‐
3091 ation will run until 01:44:10). Since there will be no further login
3092 failure events for user risto2, the second operation will exist until
3093 01:45:00 without taking any action.
3094 SINGLEWITH2THRESHOLDS RULE
3096 The SingleWith2Thresholds rule supports the following fields. Note
3097 that match variables may be used in context, desc, action, desc2, and
3098 action2 fields.
3099 type fixed to SingleWith2Thresholds (value is case insensitive).
3101 continue (optional)
3103 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
3104 bel>, values are case insensitive).
3105 ptype pattern type (value is case insensitive).
3107 pattern
3109 pattern.
3110 varmap (optional)
3112 variable map.
3113 context (optional)
3115 context expression.
3116 desc operation description string.
3118 action action list.
3120 window event correlation window size (value is an integer constant).
3122 thresh counting threshold.
3124 desc2 format string that sets the %s variable for action2.
3126 action2
3128 action list.
3129 window2
3131 event correlation window size (value is an integer constant).
3132 thresh2
3134 counting threshold.
3135 rem (optional, may appear more than once)
3137 remarks and comments.
3138 The SingleWith2Thresholds rule runs event correlation operations which
3140 take action if N1 events have been observed in the window of T1 sec‐
3141 onds, and then at most N2 events will be observed in the window of T2
3142 seconds. The values of T1, N1, T2, and N2 are defined by the window,
3143 thresh, window2, and thresh2 field, respectively.
3144 When an event has matched the rule, SEC evaluates the operation de‐
3146 scription string given with the desc field. If the operation for the
3147 given string and rule does not exist, SEC will create it with the life‐
3148 time of T1 seconds. The operation will memorize the occurrence time of
3149 the event (current time as returned by the time(2) system call), and
3150 compare the number of memorized occurrence times with the threshold N1.
3151 If the operation has observed N1 events, it executes the action list
3152 defined by the action field, and starts another counting round for T2
3153 seconds. If no more than N2 events have been observed by the end of
3154 the window, the operation executes the action list defined by the ac‐
3155 tion2 field and finishes. Note that both windows are sliding -- the
3156 first window slides like the window of the SingleWithThreshold opera‐
3157 tion, while the beginning of the second window is moved to the second
3158 earliest memorized event occurrence time when the threshold N2 is vio‐
3159 lated.
3160 Examples:
3162 type=SingleWith2Thresholds
3164 ptype=RegExp
3165 pattern=(\S+): %SYS-3-CPUHOG
3166 desc=Router $1 CPU overload
3167 action=pipe '%t: %s' /bin/mail root@localhost
3168 window=300
3169 thresh=2
3170 desc2=Router $1 CPU load has been normal for 1h
3171 action2=logonly
3172 window2=3600
3173 thresh2=0
3174 When a SYS-3-CPUHOG syslog message is received from a router, the rule
3176 starts a counting operation for this router which sends an e-mail warn‐
3177 ing to root@localhost if another such message is received from the same
3178 router within 300 seconds. After sending the warning, the operation
3179 will continue to run until no SYS-3-CPUHOG syslog messages have been
3180 received from the router for 3600 seconds. When this condition becomes
3181 satisfied, the operation will log the message "Router <routername> CPU
3182 load has been normal for 1h" and finish.
3183 Suppose the following events are generated by a router, and each event
3185 timestamp reflects the time SEC observes the event:
3186 Dec 30 12:23:25 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3188 Dec 30 12:25:38 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3189 Dec 30 12:28:53 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3190 When the first event is observed at 12:23:25, a counting operation is
3192 started for router Router1. The appearance of the second event at
3193 12:25:38 fulfills the threshold condition given with the thresh and
3194 window fields (two events have been observed within 300 seconds).
3195 Therefore, the operation will send an e-mail warning about the CPU
3196 overload of Router1 to root@localhost.
3197 After that, the operation will start another counting round, expecting
3199 to see no SYS-3-CPUHOG events (since thresh2=0) for Router1 during the
3200 following 3600 seconds (the beginning of the operation's event correla‐
3201 tion window will be moved to 12:25:38 for the second counting round).
3202 Since the appearance of the third event at 12:28:53 violates the
3203 threshold condition given with the thresh2 and window2 fields, the be‐
3204 ginning of the event correlation window will be moved to 12:28:53.
3205 Since there will be no further SYS-3-CPUHOG messages for Router1, the
3206 operation will run until 13:28:53 and then expire, logging the message
3207 "Router Router1 CPU load has been normal for 1h" before finishing.
3208 EVENTGROUP RULE
3210 The EventGroup rule supports the following fields. Note that match
3211 variables may be used in context*, count*, egtoken*, desc, action,
3212 init, end, and slide fields.
3213 type EventGroup[N] (value is case insensitive, N defaults to 1).
3215 continue (optional)
3217 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
3218 bel>, values are case insensitive). Specifies the point-of-con‐
3219 tinue after a match by pattern and context.
3220 ptype pattern type for pattern (value is case insensitive).
3222 pattern
3224 pattern.
3225 varmap (optional)
3227 variable map for pattern.
3228 context (optional)
3230 context expression, evaluated together with pattern.
3231 count (optional)
3233 action list for execution after a match by pattern and context.
3234 thresh (optional)
3236 counting threshold for events matched by pattern and context
3237 (value is an integer constant, default is 1).
3238 egtoken (optional)
3240 token for building the event group string that is matched with
3241 egpattern (default value is 1).
3242 ...
3244 continueN (optional)
3246 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
3247 bel>, values are case insensitive). Specifies the point-of-con‐
3248 tinue after a match by patternN and contextN.
3249 ptypeN pattern type for patternN (value is case insensitive).
3251 patternN
3253 pattern.
3254 varmapN (optional)
3256 variable map for patternN.
3257 contextN (optional)
3259 context expression, evaluated together with patternN.
3260 countN (optional)
3262 action list for execution after a match by patternN and con‐
3263 textN.
3264 threshN (optional)
3266 counting threshold for events matched by patternN and contextN
3267 (value is an integer constant, default is 1).
3268 egtokenN (optional)
3270 token for building the event group string that is matched with
3271 egpattern (default value is N).
3272 desc operation description string.
3274 action action list.
3276 init (optional)
3278 action list.
3279 end (optional)
3281 action list.
3282 slide (optional)
3284 action list.
3285 multact (optional)
3287 Yes or No (values are case insensitive, default is No).
3288 egptype (optional)
3290 SubStr, NSubStr, RegExp, NRegExp, PerlFunc or NPerlFunc (values
3291 are case insensitive). Specifies the pattern type for egpat‐
3292 tern.
3293 egpattern (optional)
3295 event group pattern.
3296 window event correlation window size (value is an integer constant).
3298 rem (optional, may appear more than once)
3300 remarks and comments.
3301 The EventGroup rule runs event correlation operations for counting re‐
3303 peated instances of N different events e1,...,eN during T seconds, and
3304 taking an action if threshold conditions c1,...,cN for *all* events are
3305 satisfied (i.e., for each event eK there are at least cK event in‐
3306 stances in the window). Note that the event correlation window of the
3307 EventGroup operation is sliding like the window of the SingleWith‐
3308 Threshold operation.
3309 Event e1 is described with the pattern and context field, event e2 is
3311 described with the pattern2 and context2 field, etc. The values for N
3312 and T are defined by the type and window field, respectively. The value
3313 for c1 is given with the thresh field, the value for c2 is given with
3314 the thresh2 field, etc. Values for N and c1,...,cN default to 1.
3315 In order to match an event with the rule, pattern and context fields
3317 are evaluated first. If they don't match the event, then pattern2 and
3318 context2 are evaluated, etc. If all N conditions are tried without a
3319 success, the event doesn't match the rule.
3320 When an event has matched the rule, SEC evaluates the operation de‐
3322 scription string given with the desc field. If the operation for the
3323 given string and rule does not exist, SEC will create it with the life‐
3324 time of T seconds. The operation will memorize the occurrence time of
3325 the event (current time as returned by the time(2) system call), and
3326 compare the number of memorized occurrence times for each eK with the
3327 threshold cK (i.e., the number of observed instances of eK is compared
3328 with the threshold cK). If all threshold conditions are satisfied, the
3329 operation executes the action list defined by the action field, and
3330 consumes all further matching events without re-executing the action
3331 list if the multact field is set to No (this is the default). However,
3332 if multact is set to Yes, the operation will re-evaluate the threshold
3333 conditions on every further matching event, re-executing the action
3334 list given with the action field if all conditions are satisfied, and
3335 sliding the event correlation window forward when the window is about
3336 to expire (if no events remain in the window, the operation will fin‐
3337 ish).
3338 For example, consider the following rule:
3340 type=EventGroup2
3342 ptype=SubStr
3343 pattern=EVENT_A
3344 thresh=2
3345 ptype2=SubStr
3346 pattern2=EVENT_B
3347 thresh2=2
3348 desc=Sequence of two or more As and Bs observed within 60 seconds
3349 action=write - %s
3350 window=60
3351 Also, suppose the following events occur, and each event timestamp re‐
3353 flects the time SEC observes the event:
3354 Mar 10 12:03:01 EVENT_A
3356 Mar 10 12:03:04 EVENT_B
3357 Mar 10 12:03:10 EVENT_A
3358 Mar 10 12:03:11 EVENT_A
3359 Mar 10 12:03:27 EVENT_B
3360 Mar 10 12:03:46 EVENT_A
3361 Mar 10 12:03:59 EVENT_A
3362 When these events are observed by the above EventGroup2 rule, the rule
3364 starts an event correlation operation at 12:03:01. Note that although
3365 the first threshold condition thresh=2 is satisfied when the third
3366 event appears at 12:03:10, the second threshold condition thresh2=2 is
3367 not met, and therefore the operation will not execute the action list
3368 given with the action field. When the fifth event appears at 12:03:27,
3369 all threshold conditions are finally satisfied, and the operation will
3370 write the string "Sequence of two or more As and Bs observed within 60
3371 seconds" to standard output with the write action. Finally, the events
3372 occurring at 12:03:46 and 12:03:59 will be consumed silently by the op‐
3373 eration (the operation will run until 12:04:01).
3374 If multact=yes statement is added to the above EventGroup2 rule, the
3376 operation would execute the write action not only at 12:03:27, but also
3377 at 12:03:46 and 12:03:59, since all threshold conditions are still sat‐
3378 isfied when the last two events appear (i.e., the last two events are
3379 no longer silently consumed). Also, with multact=yes the operation will
3380 employ sliding window based event processing even after the write ac‐
3381 tion has been executed at 12:03:27 (therefore, the operation will run
3382 until 12:04:59).
3383 If the rule definition has an optional event group pattern and its type
3385 defined with the egpattern and egptype fields, the event group pattern
3386 is used for matching the event group string. The event group string
3387 consists of tokens Xi that are separated by a single space character:
3388 "X1 X2 ... XM". M is the number of events a given event correlation
3389 operation has observed within its event correlation window.
3390 If the i-th event that the event correlation operation has observed is
3392 an instance of event eK, then Xi is set as follows. If the rule defini‐
3393 tion has a token defined with the egtokenK field for event eK, Xi is
3394 set to that token (the token definition may contain match variables
3395 that are substituted with values from matching the current instance of
3396 eK). If the rule does not have the egtokenK field, then Xi = K (note
3397 that K is a positive integer).
3398 Event group string is built and matched with event group pattern after
3400 all threshold conditions (given with thresh* fields) have been found
3401 satisfied. In other words, the event group pattern defines an addi‐
3402 tional condition to numeric threshold conditions.
3403 Note that the event group pattern and its type are similar to regular
3405 patterns and pattern types that are given with pattern* and ptype*
3406 fields, except the event group pattern is not setting any match vari‐
3407 ables. If the egptype field is set to RegExp or NRegExp, the egpattern
3408 field defines a regular expression, while in the case of SubStr and
3409 NSubStr egpattern provides a string pattern.
3410 If the egptype field is set to PerlFunc or NPerlFunc, the Perl function
3412 given with the egpattern field is called in the Perl scalar context,
3413 with the function having two parameters: the event group string, and
3414 the reference to the list of tokens from the event group string. With
3415 egptype=PerlFunc, event group pattern matches if the return value of
3416 the function evaluates true in the Perl boolean context, while in the
3417 case of false the pattern does not match the event group string. With
3418 egptype=NPerlFunc, the pattern matching works in the opposite way.
3419 For example, consider the following rule:
3421 type=EventGroup2
3423 ptype=SubStr
3424 pattern=EVENT_A
3425 thresh=2
3426 ptype2=SubStr
3427 pattern2=EVENT_B
3428 thresh2=2
3429 desc=Sequence of two or more As and Bs with 'A B' at the end
3430 action=write - %s
3431 egptype=RegExp
3432 egpattern=1 2$
3433 window=60
3434 Also, suppose the following events occur, and each event timestamp re‐
3436 flects the time SEC observes the event:
3437 Mar 10 12:05:31 EVENT_B
3439 Mar 10 12:05:32 EVENT_B
3440 Mar 10 12:05:38 EVENT_A
3441 Mar 10 12:05:39 EVENT_A
3442 Mar 10 12:05:42 EVENT_B
3443 When these events are observed by the above EventGroup2 rule, the rule
3445 starts an event correlation operation at 12:05:31. When the fourth
3446 event appears at 12:05:39, all threshold conditions (thresh=2 and
3447 thresh2=2) become satisfied, and therefore the following event group
3448 string is built from the first four events:
3449 2 2 1 1
3451 However, since this string does not match the regular expression
3453 1 2$
3455 that has been given with the egpattern field, the operation will not
3457 execute the action list given with the action field. When the fifth
3458 event appears at 12:05:42, all threshold conditions are again satis‐
3459 fied, and all observed events produce the following event group string:
3460 2 2 1 1 2
3462 Since this event group string matches the regular expression given with
3464 the egpattern field, the operation will write the string "Sequence of
3465 two or more As and Bs with 'A B' at the end" to standard output with
3466 the write action.
3467 If the rule definition has an optional action list defined with the
3469 countK field for event eK, the operation executes it every time an in‐
3470 stance of eK is observed (even if multact is set to No and the opera‐
3471 tion has already executed the action list given with action). If the
3472 action list contains match variables, they are substituted before
3473 *each* execution with values from matching the current instance of eK.
3474 If the rule definition has an optional action list defined with the
3476 init field, the operation executes it immediately after the operation
3477 has been created.
3478 If the rule definition has an optional action list defined with the end
3480 field, the operation executes it immediately before the operation fin‐
3481 ishes. Note that this action list is *not* executed when the operation
3482 is terminated with the reset action.
3483 If the rule definition has an optional action list defined with the
3485 slide field, the operation executes it immediately after the event cor‐
3486 relation window has slidden forward. However, note that moving the
3487 window with the setwpos action will *not* trigger the execution.
3488 Also note that when the event correlation window slides forward, the
3490 event group pattern (given with the egpattern field) and numeric
3491 threshold conditions (given with thresh* fields) will *not* be evalu‐
3492 ated for checking if the action list given with the action field should
3493 be executed.
3494 Examples:
3496 The following example rule cross-correlates iptables events, Apache web
3498 server access log messages with 4xx response codes, and SSH login fail‐
3499 ure events:
3500 type=EventGroup3
3502 ptype=RegExp
3503 pattern=sshd\[\d+\]: Failed .+ for (?:invalid user )?\S+ from ([\d.]+)
3504 port \d+ ssh2
3505 thresh=2
3506 ptype2=RegExp
3507 pattern2=^([\d.]+) \S+ \S+ \[.+?\] ".+? HTTP\/[\d.]+" 4\d+
3508 thresh2=3
3509 ptype3=RegExp
3510 pattern3=kernel: iptables:.* SRC=([\d.]+)
3511 thresh3=5
3512 desc=Repeated probing from host $1
3513 action=pipe '%t: %s' /bin/mail root@localhost
3514 window=120
3515 The rule starts an event correlation operation for an IP address if SSH
3517 login failure event, iptables event, or Apache 4xx event is observed
3518 for that IP address. The operation sends an e-mail warning to root@lo‐
3519 calhost if within 120 seconds three threshold conditions are satisfied
3520 for the IP address it tracks -- (1) at least two SSH login failure
3521 events have occurred for this client IP, (2) at least three Apache 4xx
3522 events have occurred for this client IP, (3) at least five iptables
3523 events have been observed for this source IP.
3524 Suppose the following events occur, and each event timestamp reflects
3526 the time SEC observes the event:
3527 192.168.1.104 - - [05/Jan/2014:01:11:22 +0200] "GET /test.html
3529 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3530 Gecko/20100101 Firefox/26.0"
3531 Jan 5 01:12:52 localhost kernel: iptables: IN=eth0 OUT=
3532 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3533 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=48422 DF
3534 PROTO=TCP SPT=46351 DPT=21 WINDOW=29200 RES=0x00 SYN URGP=0
3535 Jan 5 01:12:53 localhost kernel: iptables: IN=eth0 OUT=
3536 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3537 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=48423 DF
3538 PROTO=TCP SPT=46351 DPT=21 WINDOW=29200 RES=0x00 SYN URGP=0
3539 Jan 5 01:13:01 localhost kernel: iptables: IN=eth0 OUT=
3540 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3541 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=20048 DF
3542 PROTO=TCP SPT=44963 DPT=23 WINDOW=29200 RES=0x00 SYN URGP=0
3543 Jan 5 01:13:02 localhost kernel: iptables: IN=eth0 OUT=
3544 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3545 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=20049 DF
3546 PROTO=TCP SPT=44963 DPT=23 WINDOW=29200 RES=0x00 SYN URGP=0
3547 Jan 5 01:13:08 localhost kernel: iptables: IN=eth0 OUT=
3548 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3549 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=36362 DF
3550 PROTO=TCP SPT=56918 DPT=25 WINDOW=29200 RES=0x00 SYN URGP=0
3551 Jan 5 01:13:09 localhost kernel: iptables: IN=eth0 OUT=
3552 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3553 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=36363 DF
3554 PROTO=TCP SPT=56918 DPT=25 WINDOW=29200 RES=0x00 SYN URGP=0
3555 192.168.1.104 - - [05/Jan/2014:01:13:51 +0200] "GET /test.html
3556 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3557 Gecko/20100101 Firefox/26.0"
3558 192.168.1.104 - - [05/Jan/2014:01:13:54 +0200] "GET /test.html
3559 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3560 Gecko/20100101 Firefox/26.0"
3561 192.168.1.104 - - [05/Jan/2014:01:14:00 +0200] "GET /login.html
3562 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3563 Gecko/20100101 Firefox/26.0"
3564 192.168.1.104 - - [05/Jan/2014:01:14:03 +0200] "GET /login.html
3565 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3566 Gecko/20100101 Firefox/26.0"
3567 192.168.1.104 - - [05/Jan/2014:01:14:03 +0200] "GET /login.html
3568 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3569 Gecko/20100101 Firefox/26.0"
3570 Jan 5 01:14:11 localhost sshd[1810]: Failed password for root from
3571 192.168.1.104 port 46125 ssh2
3572 Jan 5 01:14:12 localhost sshd[1810]: Failed password for root from
3573 192.168.1.104 port 46125 ssh2
3574 Jan 5 01:14:18 localhost sshd[1822]: Failed password for root from
3575 192.168.1.104 port 46126 ssh2
3576 Jan 5 01:14:19 localhost sshd[1822]: Failed password for root from
3577 192.168.1.104 port 46126 ssh2
3578 192.168.1.104 - - [05/Jan/2014:01:14:34 +0200] "GET /test.html
3579 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3580 Gecko/20100101 Firefox/26.0"
3581 The Apache 4xx event at 01:11:22 starts an event correlation operation
3583 for 192.168.1.104 which has the event correlation window of 120 sec‐
3584 onds, thus ending at 01:13:22. Between 01:12:52 and 01:13:09, six ipt‐
3585 ables events appear for 192.168.1.104, and the appearance of the fifth
3586 event at 01:13:08 fulfills the third threshold condition (within 120
3587 seconds, at least five iptables events have been observed).
3588 Since by 01:13:22 (the end of the event correlation window) no addi‐
3590 tional events have occurred, the first and second threshold condition
3591 remain unsatisfied. Therefore, the beginning of the event correlation
3592 window will be moved to 01:12:52 (the occurrence time of the earliest
3593 event which is at most 120 seconds old). As a result, the end of the
3594 window will move from 01:13:22 to 01:14:52. The only event which is
3595 left outside the window is the Apache 4xx event at 01:11:22, and thus
3596 the threshold condition for iptables events remains satisfied.
3597 Between 01:13:51 and 01:14:03, five Apache 4xx events occur, and the
3599 appearance of the third event at 01:14:00 fulfills the second threshold
3600 condition (within 120 seconds, at least three Apache 4xx events have
3601 been observed). These events are followed by four SSH login failure
3602 events which occur between 01:14:11 and 01:14:19. The appearance of the
3603 second event at 01:14:12 fulfills the first threshold condition (within
3604 120 seconds, at least two SSH login failure events have been observed).
3605 Since at this particular moment (01:14:12) the other two conditions are
3606 also fulfilled, the operation sends an e-mail warning about
3607 192.168.1.104 to root@localhost. After that, the operation silently
3608 consumes all further matching events for 192.168.1.104 until 01:14:52,
3609 and then terminates.
3610 Please note that if the above rule definition would contain multact=yes
3612 statement, the operation would continue sending e-mails at each match‐
3613 ing event after 01:14:12, provided that all threshold conditions are
3614 satisfied. Therefore, the operation would send three additional e-
3615 mails at 01:14:18, 01:14:19, and 01:14:34. Also, the operation would
3616 not terminate after its window ends at 01:14:52, but would rather slide
3617 the window forward and expect new events. At the occurrence of any
3618 iptables, SSH login failure or Apache 4xx event for 192.168.1.104, the
3619 operation would produce a warning e-mail if all threshold conditions
3620 are fulfilled.
3621 The following example rule cross-correlates iptables events and SSH lo‐
3623 gin events:
3624 type=EventGroup3
3626 ptype=regexp
3627 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
3628 varmap= user=1; ip=2
3629 count=alias OPER_$+{ip} LOGIN_FAILED_$+{user}_$+{ip}
3630 ptype2=regexp
3631 pattern2=sshd\[\d+\]: Accepted .+ for (\S+) from ([\d.]+) port \d+ ssh2
3632 varmap2= user=1; ip=2
3633 context2=LOGIN_FAILED_$+{user}_$+{ip}
3634 ptype3=regexp
3635 pattern3=kernel: iptables:.* SRC=([\d.]+)
3636 varmap3= ip=1
3637 desc=Client $+{ip} accessed a firewalled port and had difficulties with
3638 logging in
3639 action=pipe '%t: %s' /bin/mail root@localhost
3640 init=create OPER_$+{ip}
3641 slide=delete OPER_$+{ip}; reset 0
3642 end=delete OPER_$+{ip}
3643 window=120
3644 The rule starts an event correlation operation for an IP address if SSH
3646 login failure or iptables event was observed for that IP address. The
3647 operation exists for 120 seconds (since when the event correlation win‐
3648 dow slides forward, the operation terminates itself with the reset ac‐
3649 tion as specified with the slide field). The operation sends an e-mail
3650 warning to root@localhost if within 120 seconds three threshold condi‐
3651 tions are satisfied for the IP address it tracks -- (1) at least one
3652 iptables event has been observed for this source IP, (2) at least one
3653 SSH login failure has been observed for this client IP, (3) at least
3654 one successful SSH login has been observed for this client IP and for
3655 some user, provided that the operation has previously observed an SSH
3656 login failure for the same user and same client IP.
3657 Suppose the following events occur, and each event timestamp reflects
3659 the time SEC observes the event:
3660 Dec 27 19:00:06 test kernel: iptables: IN=eth0 OUT=
3662 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
3663 LEN=60 TOS=0x00 PREC=0x00 TTL=62 ID=1881 DF PROTO=TCP SPT=34342 DPT=23
3664 WINDOW=5840 RES=0x00 SYN URGP=0
3665 Dec 27 19:00:14 test sshd[10520]: Accepted password for root from
3666 10.1.2.7 port 52609 ssh2
3667 Dec 27 19:00:24 test sshd[10526]: Failed password for risto from
3668 10.1.2.7 port 52622 ssh2
3669 Dec 27 19:00:27 test sshd[10526]: Accepted password for risto from
3670 10.1.2.7 port 52622 ssh2
3671 The iptables event at 19:00:06 starts an event correlation operation
3673 for 10.1.2.7 which has the event correlation window of 120 seconds.
3674 Immediately after the operation has been started, it creates the con‐
3675 text OPER_10.1.2.7. The second event at 19:00:14 does not match the
3676 rule, since the context LOGIN_FAILED_root_10.1.2.7 does not exist. The
3677 third event at 19:00:24 matches the rule, and the operation which is
3678 running for 10.1.2.7 sets up the alias name LOGIN_FAILED_risto_10.1.2.7
3679 for the context OPER_10.1.2.7. Finally, the fourth event at 19:00:27
3680 matches the rule, since the context LOGIN_FAILED_risto_10.1.2.7 exists,
3681 and the event is therefore processed by the operation (the presence of
3682 the context indicates that the operation has previously observed a lo‐
3683 gin failure for user risto from 10.1.2.7). At this particular moment
3684 (19:00:27), all three threshold conditions for the operation are ful‐
3685 filled, and therefore it sends an e-mail warning about 10.1.2.7 to
3686 root@localhost. After that, the operation silently consumes all further
3687 matching events for 10.1.2.7 until 19:02:06, and then terminates. Im‐
3688 mediately before termination, the operation deletes the context
3689 OPER_10.1.2.7 which also drops its alias name LO‐
3690 GIN_FAILED_risto_10.1.2.7.
3691 The following example rule correlates SSH login failure events:
3693 type=EventGroup
3695 ptype=RegExp
3696 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
3697 desc=SSH login failures from three different hosts within 1m for user
3698 $1
3699 egtoken=$2
3700 egptype=PerlFunc
3701 egpattern=sub { my(%hosts) = map { $_ => 1 } @{$_[1]}; \
3702 return scalar(keys %hosts) >= 3; }
3703 action=pipe '%t: %s' /bin/mail root@localhost
3704 window=60
3705 thresh=3
3706 The rule runs event correlation operations for counting the number of
3708 SSH login failure events. Each operation counts events for one user
3709 name, and if the operation has observed login failures from three dif‐
3710 ferent hosts within 60 seconds, it sends an e-mail warning to root@lo‐
3711 calhost. For verifying that hosts are different, the egtoken field
3712 configures the use of host IP addresses as tokens for building the
3713 event group string. Also, the Perl function provided with the egpattern
3714 field checks if the list of tokens contains at least three unique IP
3715 addresses. Note that the list of tokens is referenced by the second
3716 input parameter ($_[1]) of the function, while the first input parame‐
3717 ter ($_[0]) holds the event group string (the above Perl function only
3718 processes the list of tokens).
3719 Suppose the following events are generated by an SSH daemon, and each
3721 event timestamp reflects the time SEC observes the event:
3722 Apr 4 23:04:00 test sshd[21137]: Failed password for risto from
3724 10.1.1.7 port 32182 ssh2
3725 Apr 4 23:04:03 test sshd[21145]: Failed password for risto from
3726 10.1.1.9 port 42176 ssh2
3727 Apr 4 23:04:04 test sshd[21212]: Failed password for risto from
3728 10.1.1.7 port 34191 ssh2
3729 Apr 4 23:04:07 test sshd[21226]: Failed password for risto from
3730 10.1.1.2 port 18999 ssh2
3731 When the first event is observed at 23:04:00, a counting operation is
3733 started for user risto. Since at 23:04:04 the operation observes the
3734 third event, the threshold condition given with the thresh field be‐
3735 comes satisfied, and thus the event group pattern given with the egpat‐
3736 tern field is evaluated. However, the list of tokens (10.1.1.7,
3737 10.1.1.9, 10.1.1.7) contains only two unique elements, and therefore
3738 the event group pattern does not match. When the fourth event occurs
3739 at 23:04:07, event group pattern is evaluated again, and since the list
3740 of tokens (10.1.1.7, 10.1.1.9, 10.1.1.7, 10.1.1.2) contains three
3741 unique elements now, the event group pattern matches and the operation
3742 will send an e-mail warning to root@localhost.
3743 SUPPRESS RULE
3745 The Suppress rule supports the following fields. Note that match vari‐
3746 ables may be used in the context field.
3747 type fixed to Suppress (value is case insensitive).
3749 ptype pattern type (value is case insensitive).
3751 pattern
3753 pattern.
3754 varmap (optional)
3756 variable map.
3757 context (optional)
3759 context expression.
3760 desc (optional)
3762 string for describing the rule.
3763 rem (optional, may appear more than once)
3765 remarks and comments.
3766 The Suppress rule takes no action when an event has matched the rule,
3768 and keeps matching events from being processed by later rules in the
3769 configuration file.
3770 Note that the Suppress rule does not start event correlation opera‐
3772 tions, and the optional desc field is merely used for describing the
3773 rule. Also, in order to end event processing, so that no further rules
3774 from any of the configuration files would be tried, use the Jump rule.
3775 Examples:
3777 type=Suppress
3779 ptype=RegExp
3780 pattern=sshd\[\d+\]: Failed .+ for \S+ from ([\d.]+) port \d+ ssh2
3781 context=SUPPRESS_IP_$1
3782 type=SingleWithThreshold
3784 ptype=RegExp
3785 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
3786 desc=Three SSH login failures within 1m for user $1 from $2
3787 action=pipe '%t: %s' /bin/mail root@localhost; \
3788 create SUPPRESS_IP_$2 3600
3789 window=60
3790 thresh=3
3791 The first rule filters out SSH login failure events for an already re‐
3793 ported source IP address, so that they will not be matched against the
3794 second rule during 3600 seconds after sending an e-mail warning.
3795 CALENDAR RULE
3797 The Calendar rule supports the following fields.
3798 type fixed to Calendar (value is case insensitive).
3800 time time specification.
3802 context (optional)
3804 context expression.
3805 desc operation description string.
3807 action action list.
3809 rem (optional, may appear more than once)
3811 remarks and comments.
3812 The Calendar rule was designed for executing actions at specific times.
3814 Unlike all other rules, this rule reacts only to the system clock, ig‐
3815 noring other input. The Calendar rule executes the action list given
3816 with the action field if the current time matches all conditions of the
3817 time specification given with the time field. The action list is exe‐
3818 cuted only once for any matching minute.
3819 The rule employs a time specification which closely resembles the
3821 crontab(1) style, but there are some subtle differences. The time
3822 specification consists of five or six conditions separated by white‐
3823 space. The first condition matches minutes (allowed values are 0-59),
3824 the second condition matches hours (allowed values are 0-23), the third
3825 condition days (allowed values are 0-31, with 0 denoting the last day
3826 of the month), the fourth condition months (allowed values are 1-12),
3827 and the fifth condition weekdays (allowed values are 0-7, with 0 and 7
3828 denoting Sunday). The sixth condition is optional and matches years
3829 (allowed values are 0-99 which denote the last two digits of the year).
3830 Asterisks (*), ranges of numbers (e.g., 8-11), and lists (e.g.,
3832 2,5,7-9) are allowed as conditions. Asterisks and ranges may be aug‐
3833 mented with step values (e.g., 47-55/2 means 47,49,51,53,55).
3834 Note that unlike crontab(1) time specification, the day and weekday
3836 conditions are *not* joined with logical OR, but rather with logical
3837 AND. Therefore, 0 1 25-31 10 7 means 1AM on last Sunday in October.
3838 On the other hand, with crontab(1) the same specification means 1AM in
3839 every last seven days or every Sunday in October.
3840 Also, unlike some versions of cron(8), SEC is not restricted to take
3842 action only during the first second of the current minute. For example,
3843 if SEC is started at the 22th second of a minute, the wildcard condi‐
3844 tion produces a match for this minute. As another example, if the time
3845 specification matches the current minute but the context expression
3846 evaluates FALSE during the first half of the minute, the Calendar rule
3847 will execute the action list in the middle of this minute when the ex‐
3848 pression value becomes TRUE.
3849 Note that the Calendar rule does not start event correlation opera‐
3851 tions, and the desc field is merely used for setting the %s action list
3852 variable.
3853 Examples:
3855 type=Calendar
3857 time=0 2 25-31 3,12 6
3858 desc=Check if backup is done on last Saturday of Q1 and Q4
3859 action=event WAITING_FOR_BACKUP
3860 type=Calendar
3862 time=0 2 24-30 6,9 6
3863 desc=Check if backup is done on last Saturday of Q2 and Q3
3864 action=event WAITING_FOR_BACKUP
3865 type=PairWithWindow
3867 ptype=SubStr
3868 pattern=WAITING_FOR_BACKUP
3869 desc=Quarterly backup not completed on time!
3870 action=pipe '%t: %s' /bin/mail root@localhost
3871 ptype2=SubStr
3872 pattern2=BACKUP READY
3873 desc2=Quarterly backup successfully completed
3874 action2=none
3875 window=1800
3876 The first two rules create a synthetic event WAITING_FOR_BACKUP at 2AM
3878 on last Saturday of March, June, September and December. The third
3879 rule matches this event and starts an event correlation operation which
3880 waits for the BACKUP READY event for 1800 seconds. If this event has
3881 not arrived by 2:30AM, the operation sends an e-mail warning to
3882 root@localhost.
3883 JUMP RULE
3885 The Jump rule supports the following fields. Note that match variables
3886 may be used in the context field. They may also be used in the cfset
3887 field, provided that the constset field is set to No.
3888 type fixed to Jump (value is case insensitive).
3890 continue (optional)
3892 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
3893 bel>, values are case insensitive).
3894 ptype pattern type (value is case insensitive).
3896 pattern
3898 pattern.
3899 varmap (optional)
3901 variable map.
3902 context (optional)
3904 context expression.
3905 cfset (optional)
3907 configuration file set names that are separated by whitespace.
3908 constset (optional)
3910 Yes or No (values are case insensitive, default is Yes).
3911 desc (optional)
3913 string for describing the rule.
3914 rem (optional, may appear more than once)
3916 remarks and comments.
3917 The Jump rule submits matching events to specific ruleset(s) for fur‐
3919 ther processing. If the event matches the rule, SEC continues the
3920 search for matching rules in configuration file set(s) given with the
3921 cfset field. Rules from every file are tried in the order of their ap‐
3922 pearance in the file. Configuration file sets can be created from Op‐
3923 tions rules with the joincfset field, with each set containing at least
3924 one configuration file. If more that one set name is given with cfset,
3925 sets are processed from left to right; a matching rule in one set
3926 doesn't prevent SEC from processing the following sets. If the constset
3927 field is set to Yes, set names are assumed to be constants and will not
3928 be searched for match variables at runtime.
3929 If the cfset field is not present and the continue field is set to
3931 GoTo, the Jump rule can be used for skipping rules inside the current
3932 configuration file. If both cfset and continue are not present (or con‐
3933 tinue is set to DontCont), Jump is identical to Suppress rule. Fi‐
3934 nally, if cfset is not present and continue is set to EndMatch, pro‐
3935 cessing of the matching event ends (i.e., no further rules from any of
3936 the configuration files will be tried).
3937 Note that the Jump rule does not start event correlation operations,
3939 and the optional desc field is merely used for describing the rule.
3940 Examples:
3942 type=Jump
3944 ptype=RegExp
3945 pattern=sshd\[\d+\]:
3946 cfset=sshd-rules auth-rules
3947 When an sshd syslog message appears in input, rules from configuration
3949 files of the set sshd-rules are first used for matching the message,
3950 and then rules from the configuration file set auth-rules are tried.
3951 OPTIONS RULE
3953 The Options rule supports the following fields.
3954 type fixed to Options (value is case insensitive).
3956 joincfset (optional)
3958 configuration file set names that are separated by whitespace.
3959 procallin (optional)
3961 Yes or No (values are case insensitive, default is Yes).
3962 rem (optional, may appear more than once)
3964 remarks and comments.
3965 The Options rule sets processing options for the ruleset in the current
3967 configuration file. If more than one Options rule is present in the
3968 configuration file, the last instance overrides all previous ones. Note
3969 that the Options rule is only processed when SEC (re)starts and reads
3970 in the configuration file. Since this rule is not applied at runtime,
3971 it can never match events, react to the system clock, or start event
3972 correlation operations.
3973 The joincfset field lists the names of one or more configuration file
3975 sets, and the current configuration file will be added to each set. If
3976 a set doesn't exist, it will be created and the current configuration
3977 file becomes its first member. If the procallin field is set to No,
3978 the rules from the configuration file will be used for matching input
3979 from Jump rules only.
3980 Examples:
3982 The following rule adds the current configuration file to the set
3984 sshd-rules which is used for matching input from Jump rules only:
3985 type=Options
3987 joincfset=sshd-rules
3988 procallin=no
3989 The following rule adds the current configuration file to sets linux
3991 and solaris which are used for matching all input:
3992 type=Options
3994 joincfset=linux solaris
3995
3997 Event correlation operations are dynamic entities created by rules.
3998 After creating an operation, the rule also feeds the operation with
3999 events that need to be correlated. Since each rule can create and feed
4000 many operations which are running simultaneously, each operation needs
4001 a unique ID.
4002 In order to identify event correlation operations, SEC assigns an ID to
4004 every operation that is composed from the configuration file name, the
4005 rule number, and the operation description string (defined by the desc
4006 field of the rule). If there are N rules in the configuration file
4007 (excluding Options rules), the rule numbers belong to the range 0..N-1,
4008 and the number of the k-th rule is k-1. Since each Options rule is
4009 only processed when SEC reads in the configuration file and is not ap‐
4010 plied at runtime, the Options rules will not receive rule numbers.
4011 Note that since the configuration file name and rule number are part of
4012 the operation ID, different rules can have identical desc fields with‐
4013 out a danger of a clash between operations.
4014 For example, if the configuration file /etc/sec/my.conf contains only
4016 one rule
4017 type=SingleWithThreshold
4019 ptype=RegExp
4020 pattern=user (\S+) login failure on (\S+)
4021 desc=Repeated login failures for user $1 on $2
4022 action=pipe '%t: %s' /bin/mail root@localhost
4023 window=60
4024 thresh=3
4025 then the number of this rule is 0. When this rule matches an input
4027 event "user admin login failure on tty1", the desc field yields an op‐
4028 eration description string Repeated login failures for user admin on
4029 tty1, and the event will be directed for further processing to the op‐
4030 eration with the following ID:
4031 /etc/sec/my.conf | 0 | Repeated login failures for user admin on tty1
4033 If the operation for this ID does not exist, the rule will create it.
4035 The newly created operation has its event counter initialized to 1, and
4036 it expects to receive two additional "user admin login failure on tty1"
4037 events from the rule within the following 60 seconds. If the operation
4038 receives such an event, its event counter is incremented, and if the
4039 counter reaches the value of 3, a warning e-mail is sent to root@local‐
4040 host.
4041 By tuning the desc field of the rule, the scope of individual event
4043 correlation operations can be changed. For instance, if the following
4044 events occur within 10 seconds
4045 user admin login failure on tty1
4047 user admin login failure on tty5
4048 user admin login failure on tty2
4049 the above rule starts three event correlation operations. However, if
4051 the desc field of the rule is changed to Repeated login failures for
4052 user $1, these events are processed by the *same* event correlation op‐
4053 eration (the operation sends a warning e-mail to root@localhost when it
4054 receives the third event).
4055 Since rules from the same configuration file are matched against input
4057 in the order they are given, the rule ordering influences the creation
4058 and feeding of event correlation operations. Suppose the configuration
4059 file /etc/sec/my.conf contains the following rules:
4060 type=Suppress
4062 ptype=TValue
4063 pattern=TRUE
4064 context=MYCONTEXT
4065 type=SingleWithThreshold
4067 ptype=RegExp
4068 pattern=user (\S+) login failure on (\S+)
4069 desc=Repeated login failures for user $1 on $2
4070 action=pipe '%t: %s' /bin/mail root@localhost
4071 window=60
4072 thresh=3
4073 The second rule is able to create and feed event correlation operations
4075 as long as the context MYCONTEXT does not exist. However, after MYCON‐
4076 TEXT has been created, no input event will reach the second rule, and
4077 the rule is thus unable to create new operations and feed existing ones
4078 with events.
4079 Note that Pair and PairWithWindow rules can feed the same event to sev‐
4081 eral operations. Suppose the configuration file /etc/sec/my2.conf con‐
4082 tains the following rules:
4083 type=Suppress
4085 ptype=SubStr
4086 pattern=test
4087 type=Pair
4089 ptype=RegExp
4090 pattern=database (\S+) down
4091 desc=Database $1 is down
4092 action=pipe '%t: %s' /bin/mail root@localhost
4093 ptype2=RegExp
4094 pattern2=database $1 up|all databases up
4095 desc2=Database %1 is up
4096 action2=pipe '%t: %s' /bin/mail root@localhost
4097 window=86400
4098 Since the following input events don't contain the substring "test"
4100 database mydb1 down
4102 database mydb2 down
4103 database mydb3 down
4104 they are matched by the second rule of type Pair which creates three
4106 event correlation operations. Each operation is running for one partic‐
4107 ular database name, and the operations have the following IDs:
4108 /etc/sec/my2.conf | 1 | Database mydb1 is down
4110 /etc/sec/my2.conf | 1 | Database mydb2 is down
4111 /etc/sec/my2.conf | 1 | Database mydb3 is down
4112 Each newly created operation sends an e-mail notification to root@lo‐
4114 calhost about the "database down" condition, and will then wait for
4115 86400 seconds (24 hours) for either of the following messages:
4116 (a) "database up" message for the given database,
4117 (b) "all databases up" message.
4118 The operation with the ID
4120 /etc/sec/my2.conf | 1 | Database mydb1 is down
4122 uses the following regular expression for matching expected messages:
4124 database mydb1 up|all databases up
4126 The operation with the ID
4128 /etc/sec/my2.conf | 1 | Database mydb2 is down
4130 employs the following regular expression for matching expected mes‐
4132 sages:
4133 database mydb2 up|all databases up
4135 Finally, the operation with the ID
4137 /etc/sec/my2.conf | 1 | Database mydb3 is down
4139 uses the following regular expression:
4141 database mydb3 up|all databases up
4143 If the following input events appear after 10 minutes
4145 database test up
4147 admin logged in
4148 database mydb3 up
4149 all databases up
4150 the first event "database test up" matches the first rule (Suppress)
4152 which does not pass the event further to the second rule (Pair). How‐
4153 ever, all following events reach the Pair rule. Since the messages
4154 don't match the pattern field of the rule, the rule feeds them to all
4155 currently existing operations it has created, so that the operations
4156 can match these events with their regular expressions. Because regular
4157 expressions of all three operations don't match the event "admin logged
4158 in", the operations will continue to run. In the case of the "database
4159 mydb3 up" event, the regular expression of the operation
4160 /etc/sec/my2.conf | 1 | Database mydb3 is down
4162 produces a match. Therefore, the operation will send the e-mail notifi‐
4164 cation "Database mydb3 is up" to root@localhost and terminate. How‐
4165 ever, the following event "all databases up" matches the regular ex‐
4166 pressions of two remaining operations. As a result, the operations will
4167 send e-mail notifications "Database mydb1 is up" and "Database mydb2 is
4168 up" to root@localhost and terminate.
4169 Each operation has an event correlation window which defines its scope
4171 in time. The size of the window is defined by the window* field, and
4172 the beginning of the window can be obtained with the getwpos action.
4173 SingleWithThreshold, SingleWith2Thresholds and EventGroup operations
4174 can slide its window forward during event processing, while for all op‐
4175 erations the window can also be moved explicitly with the setwpos ac‐
4176 tion. Also, with the reset action event correlation operations can be
4177 terminated. Note that getwpos, setwpos, and reset actions only work for
4178 operations started by the rules from the same configuration file.
4179 For example, consider the configuration file /etc/sec/sshd.rules that
4181 contains the following rules:
4182 type=SingleWithThreshold
4184 ptype=RegExp
4185 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
4186 desc=Three SSH login failures within 1m for user $1
4187 action=pipe '%t: %s' /bin/mail root@localhost
4188 window=60
4189 thresh=3
4190 type=Single
4192 ptype=RegExp
4193 pattern=sshd\[\d+\]: Accepted .+ for (\S+) from [\d.]+ port \d+ ssh2
4194 desc=SSH login successful for user $1
4195 action=reset -1 Three SSH login failures within 1m for user $1
4196 Suppose the following events are generated by an SSH daemon, and each
4198 event timestamp reflects the time SEC observes the event:
4199 Dec 29 15:00:03 test sshd[14129]: Failed password for risto from
4201 10.1.2.7 port 31312 ssh2
4202 Dec 29 15:00:08 test sshd[14129]: Failed password for risto from
4203 10.1.2.7 port 31312 ssh2
4204 Dec 29 15:00:17 test sshd[14129]: Accepted password for risto from
4205 10.1.2.7 port 31312 ssh2
4206 Dec 29 15:00:52 test sshd[14142]: Failed password for risto from
4207 10.1.1.2 port 17721 ssh2
4208 The first event at 15:00:03 starts an event correlation operation with
4210 the ID
4211 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
4213 risto
4214 However, when the third event occurs at 15:00:17, the second rule
4216 matches it and terminates the operation with the action
4217 reset -1 Three SSH login failures within 1m for user risto
4219 The -1 parameter of reset restricts the action to operations started by
4221 the previous rule (i.e., the first rule that has a number 0), while the
4222 Three SSH login failures within 1m for user risto parameter refers to
4223 the operation description string. Together with the current configura‐
4224 tion file name (/etc/sec/sshd.rules), the parameters yield the opera‐
4225 tion ID
4226 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
4228 risto
4229 (If the operation with the given ID would not exist, reset would per‐
4231 form no operation.)
4232 As a consequence, the fourth event at 15:00:52 starts another operation
4234 with the same ID as the terminated operation had. Without the second
4235 rule, the operation that was started at 15:00:03 would not be termi‐
4236 nated, and the appearance of the fourth event would trigger a warning
4237 e-mail from that operation.
4238
4240 SEC processes input data iteratively by reading one line at each itera‐
4241 tion, writing this line into a relevant input buffer, and matching the
4242 content of the updated buffer with rules from configuration files. If
4243 during the matching process an action list is executed which creates
4244 new input events (e.g., through the event action), they are *not* writ‐
4245 ten to buffer(s) immediately, but rather consumed at following itera‐
4246 tions.
4247 Note that when both synthetic events and regular input are available
4249 for processing, synthetic events are always consumed first. When all
4250 synthetic events have been consumed iteratively, SEC will start pro‐
4251 cessing new data from input files.
4252 With the --jointbuf option, SEC employs a joint input buffer for all
4254 input sources which holds N last input lines (the value of N can be set
4255 with the --bufsize option). Updating the input buffer means that the
4256 new line becomes the first element of the buffer, while the last ele‐
4257 ment (the oldest line) is removed from the end of the buffer. With the
4258 --nojointbuf option, SEC maintains a buffer of N lines for each input
4259 file, and if the input line comes from file F, the buffer of F is up‐
4260 dated as described previously. There is also a separate buffer for
4261 synthetic and internal events.
4262 Suppose SEC is started with the following command line
4264 /usr/bin/sec --conf=/etc/sec/test-multiline.conf --jointbuf \
4266 --input=/var/log/prog1.log --input=/var/log/prog2.log
4267 and the configuration file /etc/sec/test-multiline.conf has the follow‐
4269 ing content:
4270 type=Single
4272 rem=this rule matches two consecutive lines where the first \
4273 line contains "test1" and the second line "test2", and \
4274 writes the matching lines to standard output
4275 ptype=RegExp2
4276 pattern=test1.*\n.*test2
4277 desc=two consecutive test lines
4278 action=write - $0
4279 When the following lines appear in input files /var/log/prog1.log and
4281 /var/log/prog2.log
4282 Dec 31 12:33:12 test prog1: test1 (file /var/log/prog1.log)
4284 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
4285 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
4286 Dec 31 12:41:53 test prog2: test2 (file /var/log/prog2.log)
4287 they are stored in a common input buffer. Therefore, rule fires after
4289 the third event has appeared, and writes the following lines to stan‐
4290 dard output:
4291 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
4293 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
4294 However, if SEC is started with the --nojointbuf option, separate input
4296 buffers are set up for /var/log/prog1.log and /var/log/prog2.log.
4297 Therefore, the rule fires after the third event has occurred, and
4298 writes the following lines to standard output:
4299 Dec 31 12:33:12 test prog1: test1 (file /var/log/prog1.log)
4301 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
4302 The rule also fires after the fourth event has occurred, producing the
4304 following output:
4305 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
4307 Dec 31 12:41:53 test prog2: test2 (file /var/log/prog2.log)
4308 The content of input buffers can be modified with the rewrite action,
4310 and modifications become visible immediately during ongoing event pro‐
4311 cessing iteration. Suppose SEC is started with the following command
4312 line
4313 /usr/bin/sec --conf=/etc/sec/test-rewrite.conf \
4315 --input=- --nojointbuf
4316 and the configuration file /etc/sec/test-rewrite.conf has the following
4318 content:
4319 type=Single
4321 rem=this rule matches two consecutive lines where the first \
4322 line contains "test1" and the second line "test2", and \
4323 joins these lines in the input buffer
4324 ptype=RegExp2
4325 pattern=^(.*test1.*)\n(.*test2.*)$
4326 continue=TakeNext
4327 desc=join two test lines
4328 action=rewrite 2 Joined $1 and $2
4329 type=Single
4331 rem=this rule matches a line which begins with "Joined", \
4332 and writes this line to standard output
4333 ptype=RegExp
4334 pattern=^Joined
4335 desc=output joined lines
4336 action=write - $0
4337 When the following two lines appear in standard input
4339 This is a test1
4341 This is a test2
4342 they are matched by the first rule which uses the rewrite action for
4344 replacing those two lines in the input buffer with a new content. The
4345 last line in the input buffer ("This is a test2") is replaced with
4346 "Joined This is a test1 and This is a test2", while the previous line
4347 in the input buffer ("This is a test1") is replaced with an empty
4348 string. Since the rule contains continue=TakeNext statement, the
4349 matching process will continue from the following rule. This rule
4350 matches the last line in the input buffer if it begins with "Joined",
4351 and writes the line to standard output, producing
4352 Joined This is a test1 and This is a test2
4354 After each event processing iteration, the pattern match cache is
4356 cleared. In other words, if a match is cached with the rule varmap*
4357 field, it is available during ongoing iteration only. Note that re‐
4358 sults from a successful pattern matching are also cached when the sub‐
4359 sequent context expression evaluation yields FALSE. This allows for
4360 reusing results from partial rule matches. For example, the following
4361 rule creates the cache entry "ssh_failed_login" for any SSH failed lo‐
4362 gin event, even if the context ALERTING_ON does not exist:
4363 type=Single
4365 ptype=RegExp
4366 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
4367 varmap=ssh_failed_login; user=1; ip=2
4368 context=ALERTING_ON
4369 desc=SSH login failure for user $1 from $2
4370 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost
4371 However, provided the context expression does not contain match vari‐
4373 ables, enclosing the expression in square brackets (e.g., [ALERT‐
4374 ING_ON]) forces its evaluation before the pattern matching, and will
4375 thus prevent the matching and the creation of the cache entry if the
4376 evaluation yields FALSE.
4377 Rules from the same configuration file are matched against the buffer
4379 content in the order they are given in that file. When multiple con‐
4380 figuration files have been specified, rule sequences from all files are
4381 matched against the buffer content (unless specified otherwise with Op‐
4382 tions rules). The matching order is determined by the order of config‐
4383 uration files in SEC command line. For example, if the Perl glob()
4384 function returns filenames in ascending ASCII order, and configuration
4385 files /home/risto/A.conf, /home/risto/B.conf2, and /home/risto/C.conf
4386 are specified with --conf=/home/risto/*.conf --conf=/home/risto/*.conf2
4387 in SEC command line, then SEC first matches the input against the rule
4388 sequence from A.conf, then from C.conf, and finally from B.conf2.
4389 Also, note that even if A.conf contains a Suppress rule for a particu‐
4390 lar event, the event is still processed by rulesets in C.conf and
4391 B.conf2. However, note that glob() might return file names in different
4392 order if locale settings change. If you want to enforce a fixed order
4393 for configuration file application in a portable way, it is recommended
4394 to create a unique set for each file with the Options rule, and employ
4395 the Jump rule for defining the processing order for sets, e.g.:
4396 # This rule appears in A.conf
4398 type=Options
4399 joincfset=FileA
4400 procallin=no
4401 # This rule appears in B.conf2
4403 type=Options
4404 joincfset=FileB
4405 procallin=no
4406 # This rule appears in C.conf
4408 type=Options
4409 joincfset=FileC
4410 procallin=no
4411 # This rule appears in main.conf
4413 type=Jump
4414 ptype=TValue
4415 pattern=TRUE
4416 cfset=FileA FileC FileB
4417 After the relevant input buffer has been updated and its content has
4419 been matched by the rules, SEC handles caught signals and checks the
4420 status of child processes. When the timeout specified with the
4421 --cleantime option has expired, SEC also checks the status of contexts
4422 and event correlation operations. Therefore, relatively small values
4423 should be specified with the --cleantime option, in order to retain the
4424 accuracy of the event correlation process. If the --cleantime option
4425 is set to 0, SEC checks event correlation operations and contexts after
4426 processing every input line, but this consumes more CPU time. If the
4427 --poll-timeout option value exceeds the value given with --cleantime,
4428 the --poll-timeout option value takes precedence (i.e., sleeps after
4429 unsuccessful polls will not be shortened).
4430 Finally, note that apart from the sleeps after unsuccessful polls, SEC
4432 measures all time intervals and occurrence times in seconds, and always
4433 uses the time(2) system call for obtaining the current time. Also, for
4434 input event occurrence time SEC always uses the time it observed the
4435 event, *not* the timestamp extracted from the event.
4436
4438 In the action list of a context, the context can also be referred with
4439 the internal context name _THIS. The name _THIS is created and deleted
4440 dynamically by SEC and it points to the context only during its action
4441 list execution. This feature is useful when the context has had sev‐
4442 eral names during its lifetime (created with the alias action), and it
4443 is hard to determine which names exist when the context expires. For
4444 example, if the context is created with create A 60 (report A /bin/mail
4445 root) which is immediately followed by alias A B and unalias A, the re‐
4446 port action will fail since the name A no longer refers to the context.
4447 However, replacing the first action with create A 60 (report _THIS
4448 /bin/mail root) will produce the correct result.
4449 If the --intevents command line option is given, SEC will generate in‐
4451 ternal events when it is started up, when it receives certain signals,
4452 and when it terminates normally. Inside SEC, internal event is treated
4453 as if it was a line that was read from a SEC input file. Specific
4454 rules can be written to match internal events, in order to take some
4455 action (e.g., start an external event correlation module with spawn
4456 when SEC starts up). The following internal events are supported:
4457 SEC_STARTUP - generated when SEC is started (this event will always be
4459 the first event that SEC sees)
4460 SEC_PRE_RESTART - generated before processing of the SIGHUP signal
4462 (this event will be the last event that SEC sees before clearing all
4463 internal data structures and reloading its configuration)
4464 SEC_RESTART - generated after processing of the SIGHUP signal (this
4466 event will be the first event that SEC sees after clearing all internal
4467 data structures and reloading its configuration)
4468 SEC_PRE_SOFTRESTART - generated before processing of the SIGABRT signal
4470 (this event will be the last event that SEC sees before reloading its
4471 configuration)
4472 SEC_SOFTRESTART - generated after processing of the SIGABRT signal
4474 (this event will be the first event that SEC sees after reloading its
4475 configuration)
4476 SEC_PRE_LOGROTATE - generated before processing of the SIGUSR2 signal
4478 (this event will be the last event that SEC sees before reopening its
4479 log file and closing its outputs)
4480 SEC_LOGROTATE - generated after processing of the SIGUSR2 signal (this
4482 event will be the first event that SEC sees after reopening its log
4483 file and closing its outputs)
4484 SEC_SHUTDOWN - generated when SEC receives the SIGTERM signal, or when
4486 SEC reaches all EOFs of input files after being started with the --no‐
4487 tail option. With the --childterm option, SEC sleeps for 3 seconds af‐
4488 ter generating SEC_SHUTDOWN event, and then sends SIGTERM to its child
4489 processes (if a child process was triggered by SEC_SHUTDOWN, this delay
4490 leaves the process enough time for setting a signal handler for
4491 SIGTERM).
4492 Before generating an internal event, SEC sets up a context named
4494 SEC_INTERNAL_EVENT, in order to disambiguate internal events from regu‐
4495 lar input. The SEC_INTERNAL_EVENT context is deleted immediately after
4496 the internal event has been matched against all rules.
4497 If the --intcontexts command line option is given, or there is an --in‐
4499 put option with a context specified, SEC creates an internal context
4500 each time it reads a line from an input file or a synthetic event. The
4501 internal context is deleted immediately after the line has been matched
4502 against all rules. For all input files that have the context name ex‐
4503 plicitly set with --input=<file_pattern>=<context>, the name of the in‐
4504 ternal context is <context>. If the line was read from the input file
4505 <filename> for which there is no context name set, the name of the in‐
4506 ternal context is _FILE_EVENT_<filename>. For synthetic events, the
4507 name of the internal context defaults to _INTERNAL_EVENT, but cspawn
4508 and cevent actions can be used for generating synthetic events with
4509 custom internal context names. This allows for writing rules that match
4510 data from one particular input source only. For example, the rule
4511 type=Suppress
4513 ptype=TValue
4514 pattern=TRUE
4515 context=[!_FILE_EVENT_/dev/logpipe]
4516 passes only the lines that were read from /dev/logpipe, and also syn‐
4518 thetic events that were generated with the _FILE_EVENT_/dev/logpipe in‐
4519 ternal context (e.g., with the action cevent _FILE_EVENT_/dev/logpipe 0
4520 This is a test event). As another example, if SEC has been started
4521 with the command line
4522 /usr/bin/sec --intevents --intcontexts --conf=/etc/sec/my.conf \
4524 --input=/var/log/messages=MESSAGES \
4525 --input=/var/log/secure=SECURE \
4526 --input=/var/log/cron=CRON
4527 and the rule file /etc/sec/my.conf contains the following rules
4529 type=Single
4531 ptype=RegExp
4532 pattern=^(?:SEC_STARTUP|SEC_RESTART)$
4533 context=[SEC_INTERNAL_EVENT]
4534 desc=listen on 10514/tcp for incoming events
4535 action=cspawn MESSAGES /usr/bin/nc -l -k 10514
4536 type=Single
4538 ptype=RegExp
4539 pattern=.
4540 context=[MESSAGES]
4541 desc=echo everything from 10514/tcp and /var/log/messages
4542 action=write - $0
4543 then SEC will receive input lines from the log files /var/log/messages,
4545 /var/log/secure, and /var/log/cron, and will also run /usr/bin/nc for
4546 receiving input lines from the port 10514/tcp. All input lines from
4547 /var/log/messages and 10514/tcp are matched by the second rule and
4548 written to standard output.
4549
4551 The SingleWithScript rule and shellcmd, spawn, cspawn, cmdexec,
4552 spawnexec, cspawnexec, pipe, pipeexec, report, and reportexec actions
4553 fork a child process for executing an external program. For the Sin‐
4554 gleWithScript rule with shell=yes setting and for shellcmd, spawn,
4555 cspawn, pipe, and report actions, the following rule applies -- if the
4556 program command line contains shell metacharacters, the command line is
4557 first parsed by the shell which then starts the program. For the Sin‐
4558 gleWithScript rule with shell=no setting and for cmdexec, spawnexec,
4559 cspawnexec, pipeexec, and reportexec actions, the program command line
4560 is not parsed by shell, even if shell metacharacters are present in the
4561 command line.
4562 Disabling shell parsing for command lines can be useful for avoiding
4564 unwanted side effects. For example, consider the following badly writ‐
4565 ten rule for sending an e-mail to a local user if 10 SSH login failures
4566 have been observed for this user from the same IP address during 300
4567 seconds:
4568 type=SingleWithThreshold
4570 ptype=RegExp
4571 pattern=sshd\[\d+\]: Failed .+ for (.+) from ([\d.]+) port \d+ ssh2
4572 desc=Failed SSH logins for user $1 from $2
4573 action=pipe 'Failed SSH logins from $2' /bin/mail -s alert $1
4574 window=300
4575 thresh=10
4576 Unfortunately, the above rule allows for the execution of arbitrary
4578 command lines with the privileges of the SEC process. For example,
4579 consider the following malicious command line for providing fake input
4580 events for the rule:
4581 logger -p authpriv.info -t sshd -i 'Failed password for `/usr/bin/touch
4583 /tmp/test` from 127.0.0.1 port 12345 ssh2'
4584 When this command line is repeatedly executed, the attacker is able to
4586 trigger the execution of the command line /bin/mail -s alert
4587 `/usr/bin/touch /tmp/test`. However, this command line is parsed by
4588 shell that triggers the execution of the command line specified by the
4589 attacker: /usr/bin/touch /tmp/test. For fixing this issue, the pipe
4590 action can be replaced with pipeexec which will disable the shell pars‐
4591 ing:
4592 action=pipeexec 'Failed SSH logins from $2' /bin/mail -s alert $1
4594 As another workaround, the regular expression pattern of the rule can
4596 be modified to match user names that do not contain shell metacharac‐
4597 ters, for example:
4598 pattern=sshd\[\d+\]: Failed .+ for ([\w.-]+) from ([\d.]+) port \d+
4600 ssh2
4601 SEC communicates with its child processes through pipes (created with
4603 the pipe(2) system call). When the child process is at the read end of
4604 the pipe, data have to be written to the pipe in blocking mode which
4605 ensures reliable data transmission. In order to avoid being blocked,
4606 SEC forks another SEC process for writing data to the pipe reliably.
4607 The newly created SEC process will then fork the child process, manag‐
4608 ing the child process on behalf of the main SEC process (i.e., the main
4609 SEC process is the grandparent process for the child). For example, if
4610 the SEC process that manages the child receives the SIGTERM signal, the
4611 signal will be forwarded to the child process, and when the child
4612 process terminates, its exit code will be reported to the main SEC
4613 process.
4614 After forking an external program, SEC continues immediately, and
4616 checks the program status periodically until the program exits. The
4617 running time of a child process is not limited in any way. With the
4618 --childterm option, SEC sends the SIGTERM signal to all child processes
4619 when it terminates. If some special exit procedures need to be accom‐
4620 plished in the child process (or the child wishes to ignore SIGTERM),
4621 then the child must install a handler for the SIGTERM signal. Note
4622 that if the program command line is parsed by shell, the parsing shell
4623 will run as a child process of SEC and the parent process of the pro‐
4624 gram. Therefore, the SIGTERM signal will be sent to the shell, *not*
4625 the program. In order to avoid this, the shell's builtin exec command
4626 can be used (see sh(1) for more information) which replaces the shell
4627 with the program without forking a new process, e.g.,
4628 action=spawn exec /usr/local/bin/myscript.pl 2>/var/log/myscript.log
4630 Note that if an action list includes two actions which fork external
4632 programs, the execution order these programs is not determined by the
4633 order of actions in the list, since both programs are running asyn‐
4634 chronously. In order to address this issue, the execution order must
4635 be specified explicitly (e.g., instead of writing action=shellcmd cmd1;
4636 shellcmd cmd2, use the shell && operator and write action=shellcmd cmd1
4637 && cmd2).
4638 Sometimes it is desirable to start an external program and provide it
4640 with data from several rules. In order to create such setup, named
4641 pipes can be harnessed. For example, if /var/log/pipe is a named pipe,
4642 then
4643 action=shellcmd /usr/bin/logger -f /var/log/pipe -p user.notice
4645 starts the /usr/bin/logger utility which sends all lines read from
4647 /var/log/pipe to the local syslog daemon with the "user" facility and
4648 "notice" level. In order to feed events to /usr/bin/logger, the write
4649 action can be used (e.g., write /var/log/pipe This is my event). Al‐
4650 though SEC keeps the named pipe open across different write actions,
4651 the pipe will be closed on the reception of SIGHUP, SIGABRT and SIGUSR2
4652 signals. Since many UNIX tools terminate on receiving EOF from stan‐
4653 dard input, they need restarting after such signals have arrived. For
4654 this purpose, the --intevents option and SEC internal events can be
4655 used. For example, the following rule starts the /usr/bin/logger util‐
4656 ity at SEC startup, and also restarts it after the reception of rele‐
4657 vant signals:
4658 type=Single
4660 ptype=RegExp
4661 pattern=^(?:SEC_STARTUP|SEC_RESTART|SEC_SOFTRESTART|SEC_LOGROTATE)$
4662 context=SEC_INTERNAL_EVENT
4663 desc=start the logger tool
4664 action=free %emptystring; owritecl /var/log/pipe %emptystring; \
4665 shellcmd /usr/bin/logger -f /var/log/pipe -p user.notice
4666 Note that if /var/log/pipe is never opened for writing by a write ac‐
4668 tion, /usr/bin/logger will never see EOF and will thus not terminate.
4669 The owritecl action opens and closes /var/log/pipe without writing any
4670 bytes, in order to ensure the presence of EOF in such cases. This al‐
4671 lows any previous /usr/bin/logger process to terminate before the new
4672 process is started.
4673
4675 SEC supports patterns, context expressions, and actions which involve
4676 calls to the Perl eval() function or the execution of precompiled Perl
4677 code. The use of Perl code in SEC patterns and context expressions al‐
4678 lows for creating proper match conditions for scenarios which can't be
4679 handled by a simple regular expression match. For example, consider the
4680 following iptables syslog events:
4681 May 27 10:00:15 box1 kernel: iptables: IN=eth0 OUT=
4683 MAC=08:00:27:be:9e:2f:00:10:db:ff:20:03:08:00 SRC=10.6.4.14
4684 DST=10.1.8.2 LEN=84 TOS=0x00 PREC=0x00 TTL=251 ID=61426 PROTO=ICMP
4685 TYPE=8 CODE=0 ID=11670 SEQ=2
4686 May 27 10:02:22 box1 kernel: iptables: IN=eth0 OUT=
4687 MAC=08:00:27:be:9e:2f:00:10:db:ff:20:03:08:00 SRC=10.6.4.14
4688 DST=10.1.8.2 LEN=52 TOS=0x00 PREC=0x00 TTL=60 ID=61441 DF PROTO=TCP
4689 SPT=53125 DPT=23 WINDOW=49640 RES=0x00 SYN URGP=0
4690 Depending on the protocol and the nature of the traffic, events can
4692 have a wide variety of fields, and parsing out all event data with one
4693 regular expression is infeasible. For addressing this issue, a PerlFunc
4694 pattern can be used which creates match variables from all fields of
4695 the matching event, stores them in one Perl hash, and returns a refer‐
4696 ence to this hash. Outside the PerlFunc pattern, match variables are
4697 initialized from the key-value pairs in the returned hash. Suppose the
4698 following Jump rule with a PerlFunc pattern is defined in the
4699 main.rules rule file:
4700 type=Jump
4702 ptype=PerlFunc
4703 pattern=sub { my(%var); my($line) = $_[0]; \
4704 if ($line !~ /kernel: iptables:/g) { return 0; } \
4705 while ($line =~ /\G\s*([A-Z]+)(?:=(\S*))?/g) { \
4706 $var{$1} = defined($2)?$2:1; \
4707 } return \%var; }
4708 varmap=IPTABLES
4709 desc=parse iptables event
4710 cfset=iptables
4711 For example, if the iptables event contains the fields SRC=10.6.4.14,
4713 DST=10.1.8.2 and SYN, the above PerlFunc pattern sets up match variable
4714 $+{SRC} which holds 10.6.4.14, match variable $+{DST} which holds
4715 10.1.8.2, and match variable $+{SYN} which holds 1. The Jump rule
4716 caches all created match variables under the name IPTABLES, and submits
4717 the matching event to iptables ruleset for further processing. Suppose
4718 the iptables ruleset is defined in the iptables.rules rule file:
4719 type=Options
4721 procallin=no
4722 joincfset=iptables
4723 type=SingleWithThreshold
4725 ptype=Cached
4726 pattern=IPTABLES
4727 context=IPTABLES :> ( sub { return $_[0]->{"PROTO"} eq "ICMP"; } )
4728 desc=ICMP flood type $+{TYPE} code $+{CODE} from host $+{SRC}
4729 action=logonly
4730 window=10
4731 thresh=100
4732 type=SingleWithThreshold
4734 ptype=Cached
4735 pattern=IPTABLES
4736 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
4737 exists($_[0]->{"FIN"}) ; } )
4738 desc=SYN+FIN flood from host $+{SRC}
4739 action=logonly
4740 window=10
4741 thresh=100
4742 The two SingleWithThreshold rules employ Cached patterns for matching
4744 iptables events by looking up the IPTABLES entry in the pattern match
4745 cache (created by the above Jump rule for each iptables event). In or‐
4746 der to narrow down the match to specific iptables events, the rules em‐
4747 ploy precompiled Perl functions in context expressions. The :> opera‐
4748 tor is used for speeding up the matching, providing the function with a
4749 single parameter which refers to the hash of variable name-value pairs
4750 for the IPTABLES cache entry.
4751 The first SingleWithThreshold rule logs a warning message if within 10
4753 seconds 100 iptables events have been observed for ICMP packets with
4754 the same type, code, and source IP address. The second SingleWith‐
4755 Threshold rule logs a warning message if within 10 seconds 100 iptables
4756 events have been observed for TCP packets coming from the same host,
4757 and having both SYN and FIN flag set in each packet.
4758 Apart from using action list variables for data sharing between rules,
4760 Perl variables created in Perl code can be employed for the same pur‐
4761 pose. For example, when SEC has executed the following action
4762 action=eval %a ($b = 1)
4764 the variable $b and its value become visible in the following context
4766 expression
4767 context= =(++$b > 10)
4769 (with that expression one can implement event counting implicitly). In
4771 order to avoid possible clashes with variables inside the SEC code it‐
4772 self, user-defined Perl code is executed in the main::SEC namespace
4773 (i.e., inside the special package main::SEC). By using the main:: pre‐
4774 fix, SEC data structures can be accessed and modified. For example,
4775 the following rules restore and save contexts with names MY_* on SEC
4776 startup and shutdown, using Perl Storable module for saving and restor‐
4777 ing relevant elements of %main::context_list hash (since the following
4778 example does not handle code references with Storable module, it is as‐
4779 sumed that context action lists do not contain lcall actions):
4780 type=Single
4782 ptype=SubStr
4783 pattern=SEC_STARTUP
4784 context=SEC_INTERNAL_EVENT
4785 continue=TakeNext
4786 desc=Load the Storable module and terminate if it is not found
4787 action=eval %ret (require Storable); \
4788 if %ret ( logonly Storable loaded ) else ( eval %o exit(1) )
4789 type=Single
4791 ptype=SubStr
4792 pattern=SEC_STARTUP
4793 context=SEC_INTERNAL_EVENT
4794 desc=Restore contexts MY_* from /var/lib/sec/SEC_CONTEXTS on startup
4795 action=lcall %ret -> ( sub { my($ref, $context); \
4796 $ref = Storable::retrieve("/var/lib/sec/SEC_CONTEXTS"); \
4797 foreach $context (keys %{$ref}) { \
4798 if ($context =~ /^MY_/) \
4799 { $main::context_list{$context} = $ref->{$context}; } } } )
4800 type=Single
4802 ptype=SubStr
4803 pattern=SEC_SHUTDOWN
4804 context=SEC_INTERNAL_EVENT
4805 desc=Save contexts MY_* into /var/lib/sec/SEC_CONTEXTS on shutdown
4806 action=lcall %ret -> ( sub { my($context, %hash); \
4807 foreach $context (keys %main::context_list) { \
4808 if ($context =~ /^MY_/) \
4809 { $hash{$context} = $main::context_list{$context}; } } \
4810 Storable::store(\%hash, "/var/lib/sec/SEC_CONTEXTS"); } )
4811 However, note that modifying data structures within SEC code is recom‐
4813 mended only for advanced users who have carefully studied relevant
4814 parts of the code.
4815 Finally, sometimes larger chunks of Perl code have to be used for event
4817 processing and correlation. However, writing many lines of code di‐
4818 rectly into a rule is cumbersome and may decrease its readability. In
4819 such cases it is recommended to separate the code into a custom Perl
4820 module which is loaded at SEC startup, and use the code through the
4821 module interface (see perlmod(1) for further details):
4822 type=Single
4824 ptype=SubStr
4825 pattern=SEC_STARTUP
4826 context=SEC_INTERNAL_EVENT
4827 desc=Load the SecStuff module
4828 action=eval %ret (require '/usr/local/sec/SecStuff.pm'); \
4829 if %ret ( none ) else ( eval %o exit(1) )
4830 type=Single
4832 ptype=PerlFunc
4833 pattern=sub { return SecStuff::my_match($_[0]); }
4834 desc=event '$0' was matched by my_match()
4835 action=write - %s
4836
4838 Example 1 - a ruleset for Cisco events
4839 This section presents an example rulebase for managing Cisco devices.
4840 It is assumed that the managed devices have syslog logging enabled, and
4841 that all syslog messages are sent to a central host and written to log
4842 file(s) that are monitored by SEC.
4843 # Set up contexts NIGHT and WEEKEND for nights
4845 # and weekends. The context NIGHT has a lifetime
4846 # of 8 hours and the context WEEKEND 2 days
4847 type=Calendar
4849 time=0 23 * * *
4850 desc=NIGHT
4851 action=create %s 28800
4852 type=Calendar
4854 time=0 0 * * 6
4855 desc=WEEKEND
4856 action=create %s 172800
4857 # If a router does not come up within 5 minutes
4859 # after it was rebooted, generate event
4860 # "<router> REBOOT FAILURE". The next rule matches
4861 # this event, checks the router with ping and sends
4862 # a notification if there is no response.
4863 type=PairWithWindow
4865 ptype=RegExp
4866 pattern=\s([\w.-]+) \d+: %SYS-5-RELOAD
4867 desc=$1 REBOOT FAILURE
4868 action=event %s
4869 ptype2=RegExp
4870 pattern2=\s$1 \d+: %SYS-5-RESTART
4871 desc2=%1 successful reboot
4872 action2=logonly
4873 window=300
4874 type=SingleWithScript
4876 ptype=RegExp
4877 pattern=^([\w.-]+) REBOOT FAILURE
4878 script=/bin/ping -c 3 -q $1
4879 desc=$1 did not come up after reboot
4880 action=logonly $1 is pingable after reboot
4881 action2=pipe '%t: %s' /bin/mail root@localhost
4882 # Send a notification if CPU load of a router is too
4884 # high (two CPUHOG messages are received within 5
4885 # minutes); send another notification if the load is
4886 # normal again (no CPUHOG messages within last 15
4887 # minutes). Rule is not active at night or weekend.
4888 type=SingleWith2Thresholds
4890 ptype=RegExp
4891 pattern=\s([\w.-]+) \d+: %SYS-3-CPUHOG
4892 context=!(NIGHT || WEEKEND)
4893 desc=$1 CPU overload
4894 action=pipe '%t: %s' /bin/mail root@localhost
4895 window=300
4896 thresh=2
4897 desc2=$1 CPU load normal
4898 action2=pipe '%t: %s' /bin/mail root@localhost
4899 window2=900
4900 thresh2=0
4901 # If a router interface is in down state for less
4903 # than 15 seconds, generate event
4904 # "<router> INTERFACE <interface> SHORT OUTAGE";
4905 # otherwise generate event
4906 # "<router> INTERFACE <interface> DOWN".
4907 type=PairWithWindow
4909 ptype=RegExp
4910 pattern=\s([\w.-]+) \d+: %LINK-3-UPDOWN: Interface ([\w.-]+), changed
4911 state to down
4912 desc=$1 INTERFACE $2 DOWN
4913 action=event %s
4914 ptype2=RegExp
4915 pattern2=\s$1 \d+: %LINK-3-UPDOWN: Interface $2, changed state to up
4916 desc2=%1 INTERFACE %2 SHORT OUTAGE
4917 action2=event %s
4918 window=15
4919 # If "<router> INTERFACE <interface> DOWN" event is
4921 # received, send a notification and wait for
4922 # "interface up" event from the same router interface
4923 # for the next 24 hours
4924 type=Pair
4926 ptype=RegExp
4927 pattern=^([\w.-]+) INTERFACE ([\w.-]+) DOWN
4928 desc=$1 interface $2 is down
4929 action=pipe '%t: %s' /bin/mail root@localhost
4930 ptype2=RegExp
4931 pattern2=\s$1 \d+: %LINK-3-UPDOWN: Interface $2, changed state to up
4932 desc2=%1 interface %2 is up
4933 action2=pipe '%t: %s' /bin/mail root@localhost
4934 window=86400
4935 # If ten "short outage" events have been observed
4937 # in the window of 6 hours, send a notification
4938 type=SingleWithThreshold
4940 ptype=RegExp
4941 pattern=^([\w.-]+) INTERFACE ([\w.-]+) SHORT OUTAGE
4942 desc=Interface $2 at node $1 is unstable
4943 action=pipe '%t: %s' /bin/mail root@localhost
4944 window=21600
4945 thresh=10
4946 Example 2 - hierarchically organized rulesets for iptables and sshd events
4948 This section presents an example of hierarchically organized rules for
4949 processing Linux iptables events from /var/log/messages and SSH login
4950 events from /var/log/secure. It is assumed that all rule files reside
4951 in the /etc/sec directory and that the rule hierarchy has two levels.
4952 The file /etc/sec/main.rules contains first-level Jump rules for match‐
4953 ing and parsing events from input files and submitting them to proper
4954 rulesets for further processing. All other rule files in the /etc/sec
4955 directory contain second-level rules which receive their input from
4956 first-level Jump rules. Also, the example assumes that SEC is started
4957 with the following command line:
4958 /usr/bin/sec --conf=/etc/sec/*.rules --intcontexts \
4960 --input=/var/log/messages --input=/var/log/secure
4961 #
4963 # the content of /etc/sec/main.rules
4964 #
4965 type=Jump
4967 context=[ _FILE_EVENT_/var/log/messages ]
4968 ptype=PerlFunc
4969 pattern=sub { my(%var); my($line) = $_[0]; \
4970 if ($line !~ /kernel: iptables:/g) { return 0; } \
4971 while ($line =~ /\G\s*([A-Z]+)(?:=(\S*))?/g) { \
4972 $var{$1} = defined($2)?$2:1; \
4973 } return \%var; }
4974 varmap=IPTABLES
4975 desc=parse iptables events and direct to relevant ruleset
4976 cfset=iptables
4977 type=Jump
4979 context=[ _FILE_EVENT_/var/log/secure ]
4980 ptype=RegExp
4981 pattern=sshd\[(?<pid>\d+)\]: (?<status>Accepted|Failed) \
4982 (?<authmethod>[\w-]+) for (?<invuser>invalid user )?\
4983 (?<user>[\w-]+) from (?<srcip>[\d.]+) port (?<srcport>\d+) ssh2$
4984 varmap=SSH_LOGIN
4985 desc=parse SSH login events and direct to relevant ruleset
4986 cfset=ssh-login
4987 type=Jump
4989 context=[ SSH_EVENT ]
4990 ptype=TValue
4991 pattern=True
4992 desc=direct SSH synthetic events to relevant ruleset
4993 cfset=ssh-events
4994 #
4996 # the content of /etc/sec/iptables.rules
4997 #
4998 type=Options
5000 procallin=no
5001 joincfset=iptables
5002 type=SingleWithThreshold
5004 ptype=Cached
5005 pattern=IPTABLES
5006 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
5007 exists($_[0]->{"FIN"}) ; } ) \
5008 && !SUPPRESS_IP_$+{SRC}
5009 desc=SYN+FIN flood from host $+{SRC}
5010 action=pipe '%t: %s' /bin/mail -s 'iptables alert' root@localhost; \
5011 create SUPPRESS_IP_$+{SRC} 3600
5012 window=10
5013 thresh=100
5014 type=SingleWithThreshold
5016 ptype=Cached
5017 pattern=IPTABLES
5018 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
5019 !exists($_[0]->{"ACK"}) ; } ) \
5020 && !SUPPRESS_IP_$+{SRC}
5021 desc=SYN flood from host $+{SRC}
5022 action=pipe '%t: %s' /bin/mail -s 'iptables alert' root@localhost; \
5023 create SUPPRESS_IP_$+{SRC} 3600
5024 window=10
5025 thresh=100
5026 #
5028 # the content of /etc/sec/ssh-login.rules
5029 #
5030 type=Options
5032 procallin=no
5033 joincfset=ssh-login
5034 type=Single
5036 ptype=Cached
5037 pattern=SSH_LOGIN
5038 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed" && \
5039 $_[0]->{"srcport"} < 1024 && \
5040 defined($_[0]->{"invuser"}); } )
5041 continue=TakeNext
5042 desc=Probe of invalid user $+{user} from privileged port of $+{srcip}
5043 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
5044 type=SingleWithThreshold
5046 ptype=Cached
5047 pattern=SSH_LOGIN
5048 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed" && \
5049 defined($_[0]->{"invuser"}); } )
5050 desc=Ten login probes for invalid users from $+{srcip} within 60s
5051 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
5052 thresh=10
5053 window=60
5054 type=PairWithWindow
5056 ptype=Cached
5057 pattern=SSH_LOGIN
5058 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed"; } )
5059 desc=User $+{user} failed to log in from $+{srcip} within 60s
5060 action=cevent SSH_EVENT 0 %s
5061 ptype2=Cached
5062 pattern2=SSH_LOGIN
5063 context2=SSH_LOGIN :> \
5064 ( sub { return $_[0]->{"status"} eq "Accepted"; } ) && \
5065 $+{user} %+{user} $+{srcip} %+{srcip} -> \
5066 ( sub { return $_[0] eq $_[1] && $_[2] eq $_[3]; } )
5067 desc2=User $+{user} logged in successfully from $+{srcip} within 60s
5068 action2=logonly
5069 window=60
5070 #
5072 # the content of /etc/sec/ssh-events.rules
5073 #
5074 type=Options
5076 procallin=no
5077 joincfset=ssh-events
5078 type=SingleWithThreshold
5080 ptype=RegExp
5081 pattern=User ([\w-]+) failed to log in from [\d.]+ within 60s
5082 desc=Ten login failures for user $1 within 1h
5083 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
5084 thresh=10
5085 window=3600
5086
5088 If the SECRC environment variable is set, SEC expects it to contain the
5089 name of its resource file. Resource file lines which are empty or which
5090 begin with the number sign (#) are ignored (whitespace may precede #).
5091 Each remaining line is appended to the argv array of SEC as a *single*
5092 element. Also, the lines are appended to argv in the order they appear
5093 in the resource file. Therefore, if the SEC command line option has a
5094 value, the option name and the value must either be separated by the
5095 equal sign (=) or a newline. Here is a simple resource file example:
5096 # read events from standard input
5098 --input=-
5099 # rules are stored in /etc/sec/test.conf
5101 --conf
5102 /etc/sec/test.conf
5103 Note that although SEC rereads its resource file at the reception of
5105 the SIGHUP or SIGABRT signal, adding an option that specifies a certain
5106 startup procedure (e.g., --pid or --detach) will not produce the de‐
5107 sired effect at runtime. Also note that the resource file content is
5108 *not* parsed by shell, therefore shell metacharacters are passed to SEC
5109 as-is.
5110
5112 SIGHUP full restart -- SEC will reinterpret its command line and re‐
5113 source file options, reopen its log and input files, close its
5114 output files and sockets (these will be reopened on demand),
5115 reload its configuration, and drop *all* event correlation state
5116 (all event correlation operations will be terminated, all con‐
5117 texts will be deleted, all action list variables will be erased,
5118 etc.). With the --childterm option, SEC will also send the
5119 SIGTERM signal to its child processes.
5120 SIGABRT
5122 soft restart -- SEC will reinterpret its command line and re‐
5123 source file options, reopen its log file, and close its output
5124 files and sockets (these will be reopened on demand). If the
5125 --keepopen option is specified, previously opened input files
5126 will remain open across soft restart, otherwise all input files
5127 will be reopened. SEC will (re)load configuration from rule
5128 files which have been modified (file modification time returned
5129 by stat(2) has changed) or created after the previous configura‐
5130 tion load. SEC will also terminate event correlation operations
5131 started from rule files that have been modified or removed after
5132 the previous configuration load. Other operations and previ‐
5133 ously loaded configuration from unmodified rule files will re‐
5134 main intact. Note that on some systems SIGIOT is used in place
5135 of SIGABRT.
5136 SIGUSR1
5138 detailed information about the current state of SEC (performance
5139 and rule matching statistics, running event correlation opera‐
5140 tions, created contexts, etc.) will be written to the SEC dump
5141 file.
5142 SIGUSR2
5144 SEC will reopen its log file (useful for log file rotation), and
5145 also close its output files and sockets which will be reopened
5146 on demand.
5147 SIGINT SEC will increase its logging level by one; if the current level
5149 is 6, the level will be set back to 1. Please note this feature
5150 is available only if SEC is running non-interactively (e.g., in
5151 daemon mode).
5152 SIGTERM
5154 SEC will terminate gracefully. With the --childterm option, all
5155 SEC child processes will receive SIGTERM.
5156
5158 With some locale settings, single quotes (') in this man page might be
5159 displayed incorrectly. As a workaround, set the LANG environment vari‐
5160 able to C when reading this man page (e.g., env LANG=C man sec).
5161
5163 Risto Vaarandi (ristov at users d0t s0urcef0rge d0t net)
5164
5166 The author is grateful to SEB Estonia for supporting this work. The
5167 author also thanks the following people for supplying software patches,
5168 documentation fixes, and suggesting new features: Al Sorrell, Brian
5169 Mielke, David Lang, James Brown, Jon Frazier, Mark D. Nagel, Peter
5170 Eckel, Rick Casey, and William Gertz. Last but not least, the author
5171 expresses his profound gratitude to John P. Rouillard for many great
5172 ideas and creative discussions that have helped to develop SEC.
5173
5175 cron(8), crontab(1), execvp(3), fork(2), mail(1), perl(1), perlmod(1),
5176 perlre(1), pipe(2), sh(1), snmptrap(1), stat(2), strftime(3), sys‐
5177 log(3), time(2), umask(2)
5178SEC 2.9.1 May 2022 sec(1)