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. Suppose that after 25 seconds, a similar SSH login failure
126 event for the same user name is observed. In this case, a running oper‐
127 ation will be found for the operation description string Three SSH lo‐
128 gin failures within 1m for user risto, and the occurrence time of the
129 second event is recorded into the operation. If after 30 seconds a
130 third event for the user name risto is observed, the operation has pro‐
131 cessed 3 events within 55 seconds. Since the threshold condition "3
132 events within 60 seconds" (as defined by the thresh and window fields)
133 is now satisfied, SEC will execute the action defined with the action
134 field -- it will fork a command
135 /bin/mail -s 'SSH login alert' root@localhost
137 with a pipe connected to its standard input. Then, SEC writes the oper‐
139 ation description string Three SSH login failures within 1m for user
140 risto (held by the %s special variable) to the standard input of the
141 command through the pipe. In other words, an e-mail warning is sent to
142 the local root-user. Finally, since there are 5 seconds left until the
143 end of the event correlation window, the operation will consume the
144 following SSH login failure events for user risto without any further
145 action, and finish after 5 seconds.
146 The above example illustrates that the desc field of a rule defines the
148 scope of event correlation and influences the number of operations cre‐
149 ated by the rule. For example, if we set the desc field to Three SSH
150 login failures within 1m, the root-user would be also alerted on 3 SSH
151 login failure events for *different* users within 1 minute. In order
152 to avoid clashes between operations started by different rules, opera‐
153 tion ID contains not only the value set by the desc field, but also the
154 rule file name and the rule number inside the file. For example, if
155 the rule file /etc/sec/sshd.rules contains one rule
156 type=SingleWithThreshold
158 ptype=RegExp
159 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
160 desc=Three SSH login failures within 1m for user $1
161 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost
162 window=60
163 thresh=3
164 and the event
166 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
168 10.12.2.5 port 41063 ssh2
169 is the first matching event for the above rule, this event will trigger
171 a new event correlation operation with the ID
172 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
174 risto
175 (0 is the number assigned to the first rule in the file, see EVENT COR‐
177 RELATION OPERATIONS section for more information).
178 The following simple example demonstrates that event correlation
180 schemes can be defined by combining several rules. In this example, two
181 rules harness contexts and synthetic events for achieving their goal:
182 type=SingleWithThreshold
184 ptype=RegExp
185 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
186 desc=Three SSH login failures within 1m for user $1
187 action=event 3_SSH_LOGIN_FAILURES_FOR_$1
188 window=60
189 thresh=3
190 type=EventGroup
192 ptype=RegExp
193 pattern=3_SSH_LOGIN_FAILURES_FOR_(\S+)
194 context=!USER_$1_COUNTED && !COUNTING_OFF
195 count=create USER_$1_COUNTED 60
196 desc=Repeated SSH login failures for 30 distinct users within 1m
197 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost; \
198 create COUNTING_OFF 3600
199 window=60
200 thresh=30
201 The first rule looks almost identical to the rule from the previous ex‐
203 ample, but its action field is different -- after three SSH login fail‐
204 ures have been observed for the same user name within one minute by an
205 event correlation operation, the operation will emit the synthetic
206 event 3_SSH_LOGIN_FAILURES_FOR_<username>. Although synthetic events
207 are created by SEC, they are treated like regular events received from
208 input sources and are matched against rules. The regular expression
209 pattern of the second rule will match the 3_SSH_LOGIN_FAIL‐
210 URES_FOR_<username> event and start a new event correlation operation
211 if no such events have been previously seen. Also, each time a syn‐
212 thetic event for some user name has matched the rule, a context with
213 the lifetime of 1 minute for that user name is created (see the count
214 field). Note that this prevents further matches for the same user
215 name, since a synthetic event for <username> can match the rule only if
216 the context USER_<username>_COUNTED *does not* exist (as requested by
217 the boolean expression in the context field; see CONTEXTS AND CONTEXT
218 EXPRESSIONS section for more information). The operation started by
219 the rule sends an e-mail warning to the local root-user if 30 synthetic
220 events have been observed within 1 minute (see the thresh and window
221 fields). Note that due to the use of the USER_<username>_COUNTED con‐
222 texts, all synthetic events concern different user names. After sending
223 an e-mail warning, the operation will also create the context COUNT‐
224 ING_OFF with the lifetime of 1 hour, and will continue to run until the
225 1 minute event correlation window expires. After the operation has fin‐
226 ished, the presence of the COUNTING_OFF context will keep the second
227 rule disabled (as requested by the boolean expression in the context
228 field). Therefore, at most one e-mail warning per 1 hour is issued by
229 above rules.
230 The above examples have presented the event correlation capabilities of
232 SEC in a very brief fashion. The following sections will provide an
233 in-depth discussion of SEC features.
234
236 --conf=<file_pattern>
237 expand <file_pattern> to filenames (with the Perl glob() func‐
238 tion) and read event correlation rules from every file. Multiple
239 --conf options can be specified at command line. Each time SEC
240 receives a signal that forces a configuration reload, <file_pat‐
241 tern> is re-evaluated. See also INPUT PROCESSING AND TIMING sec‐
242 tion for a discussion on rule processing order for multiple con‐
243 figuration files.
244 --input=<file_pattern>[=<context>]
246 expand <file_pattern> to filenames (with the Perl glob() func‐
247 tion) and use the files as input sources. An input file can be a
248 regular file, named pipe, or standard input if - was specified.
249 Multiple --input options can be specified at command line. Each
250 time SEC receives the SIGHUP or SIGABRT signal, <file_pattern>
251 is re-evaluated. If SEC experiences a system error when reading
252 from an input file, it will close the file (use the --re‐
253 open-timeout option for reopening the file). If <context> is
254 given, SEC will set up the context <context> each time it reads
255 a line from input files that correspond to <file_pattern>. This
256 will help the user to write rules that match data from particu‐
257 lar input source(s) only. When there is an --input option with
258 <context> specified, it will automatically enable the --intcon‐
259 texts option. See INTERNAL EVENTS AND CONTEXTS section for more
260 information.
261 --input-timeout=<input_timeout>, --timeout-script=<timeout_script>
263 if SEC has not observed new data in an input file during <in‐
264 put_timeout> seconds (or the file was closed <input_timeout>
265 seconds ago), <timeout_script> will be executed with command
266 line parameters 1 and <the name of the input file>. If fresh
267 data become available again, <timeout_script> will be executed
268 with command line parameters 0 and <the name of the input file>.
269 Setting <input_timeout> to 0 disables this behavior (this is
270 also the default). Note that --input_timeout and --time‐
271 out_script options can be used as synonyms for --input-timeout
272 and --timeout-script, respectively.
273 --reopen-timeout=<reopen_timeout>
275 if an input file is in the closed state (e.g., SEC fails to open
276 the file at startup, because it has not been created yet), SEC
277 will attempt to reopen the file after every <reopen_timeout>
278 seconds until open succeeds. Setting <reopen_timeout> to 0 dis‐
279 ables this behavior (this is also the default). This option has
280 no meaning when the --notail option is also specified. Note
281 that --reopen_timeout is a synonym for --reopen-timeout.
282 --check-timeout=<check_timeout>
284 if SEC has not observed new data in an input file, the file will
285 not be polled (both for status and data) during the next
286 <check_timeout> seconds. Setting <check_timeout> to 0 disables
287 this behavior (this is also the default). Note that
288 --check_timeout is a synonym for --check-timeout.
289 --poll-timeout=<poll_timeout>
291 a real number that specifies how many seconds SEC will sleep
292 when no new data were read from input files. Default is 0.1 sec‐
293 onds. Note that --poll_timeout is a synonym for --poll-timeout.
294 --socket-timeout=<socket_timeout>
296 if a network connection to a remote peer can't be established
297 within <socket_timeout> seconds, give up. Default is 60 seconds.
298 Note that --socket_timeout is a synonym for --socket-timeout.
299 --blocksize=<io_block_size>
301 the number of bytes SEC will attempt to read at once from an in‐
302 put file. Default is 8192 bytes (i.e., read from input files by
303 8KB blocks).
304 --bufsize=<input_buffer_size>
306 set all input buffers to hold <input_buffer_size> lines. The
307 content of input buffers will be compared with patterns that are
308 part of rule definitions (i.e., no more than <input_buffer_size>
309 lines can be matched by a pattern at a time). If <input_buf‐
310 fer_size> is set to 0, SEC will determine the proper value for
311 <input_buffer_size> by checking event matching patterns of all
312 SEC rules. Default is 0 (i.e., determine the size of input buf‐
313 fers automatically).
314 --evstoresize=<event_store_size>
316 set an upper limit to the number of events in context event
317 stores. Default is 0 which sets no limit.
318 --cleantime=<clean_time>
320 time interval in seconds that specifies how often internal event
321 correlation and context lists are processed, in order to accom‐
322 plish time-related tasks and to remove obsolete elements. See
323 INPUT PROCESSING AND TIMING section for more information. De‐
324 fault is 1 second.
325 --log=<logfile>
327 use <logfile> for logging SEC activities. Note that if the SEC
328 standard error is connected to a terminal, messages will also be
329 logged there, in order to facilitate debugging.
330 --syslog=<facility>
332 use syslog for logging SEC activities. All messages will be
333 logged with the facility <facility>, e.g., local0 (see syslog(3)
334 for possible facility values). Warning: be careful with using
335 this option if SEC is employed for monitoring syslog log files,
336 because message loops might occur.
337 --debug=<debuglevel>
339 set logging verbosity for SEC. Setting debuglevel to <debu‐
340 glevel> means that all messages of level <debuglevel> and lower
341 are logged (e.g., if <debuglevel> is 3, messages from levels 1-3
342 are logged). The following levels are recognized by SEC:
343 1 - critical messages (severe faults that cause SEC to termi‐
344 nate, e.g., a failed system call)
345 2 - error messages (faults that need attention, e.g., an incor‐
346 rect rule definition in a configuration file)
347 3 - warning messages (possible faults, e.g., a command forked
348 from SEC terminated with a non-zero exit code)
349 4 - notification messages (normal system level events and inter‐
350 rupts, e.g., the reception of a signal)
351 5 - informative messages (information about external programs
352 forked from SEC)
353 6 - debug messages (detailed information about all SEC activi‐
354 ties)
355 Default <debuglevel> is 6 (i.e., log everything). See SIGNALS
356 section for information on how to change <debuglevel> at run‐
357 time.
358 --pid=<pidfile>
360 SEC will store its process ID to <pidfile> at startup.
361 --dump=<dumpfile>
363 SEC will use <dumpfile> as its dump file for writing performance
364 and debug data. With the --dumpfts option, a timestamp suffix is
365 appended to the dump file name. With the --dumpfjson option,
366 dump file is produced in JSON format. See SIGNALS section for
367 more information. Default is /tmp/sec.dump.
368 --user=<username>, --group=<groupname>
370 if SEC is started with effective user ID 0, it will drop root
371 privileges by switching to user <username> and group <group‐
372 name>. The --group option can't be used without the --user op‐
373 tion. If the --user option is given without --group, primary
374 group of the user <username> is assumed for <groupname>. If
375 several groups are provided with multiple --group options, SEC
376 switches to the first group with other groups as supplementary
377 groups.
378 --umask=<mode>
380 set file mode creation mask to <mode> at SEC startup, where
381 <mode> is a value from the range 0..0777 (see also umask(2)).
382 Octal, decimal, hexadecimal, and binary values can be specified
383 for <mode> (e.g., octal mask 0027 can also be expressed as 23,
384 0x17, and 0b000010111).
385 --ruleperf, --noruleperf
387 if the --ruleperf option is specified, performance data (e.g.,
388 total consumed CPU time) is collected for each rule and reported
389 in dump file. Default is --noruleperf.
390 --dumpfts, --nodumpfts
392 if the --dumpfts option is specified, a timestamp suffix (sec‐
393 onds since Epoch) is appended to the dump file name that re‐
394 flects the file creation time. Default is --nodumpfts.
395 --dumpfjson, --nodumpfjson
397 if the --dumpfjson option is specified, dump file is produced in
398 JSON format. Default is --nodumpfjson.
399 --quoting, --noquoting
401 if the --quoting option is specified, operation description
402 strings that are supplied to command lines of shellcmd, spawn,
403 and cspawn actions will be put inside single quotes. Each single
404 quote (') that strings originally contain will be masked. This
405 option prevents the shell from interpreting special symbols that
406 operation description strings might contain. Default is --no‐
407 quoting.
408 --tail, --notail
410 if the --notail option is specified, SEC will process all data
411 that are currently available in input files and exit after
412 reaching all EOFs. If all input is received from a pipe and the
413 --notail option is given, SEC terminates when the last writer
414 closes the pipe (EOF condition). Please note that with named
415 pipes --notail should be used with --norwfifo. With the --tail
416 option, SEC will jump to the end of input files and wait for new
417 lines to arrive. Each input file is tracked both by its name
418 and i-node, and input file rotations are handled seamlessly. If
419 the input file is recreated or truncated, SEC will reopen it and
420 process its content from the beginning. If the input file is re‐
421 moved (i.e., there is just an i-node left without a name), SEC
422 will keep the i-node open and wait for the input file recre‐
423 ation. Default is --tail.
424 --fromstart, --nofromstart
426 these flags have no meaning when the --notail option is also
427 specified. When used in combination with --tail (or alone, since
428 --tail is enabled by default), --fromstart will force SEC to
429 read and process input files from the beginning to the end, be‐
430 fore the 'tail' mode is entered. Default is --nofromstart.
431 --detach, --nodetach
433 if the --detach option is specified, SEC will disassociate it‐
434 self from the controlling terminal and become a daemon at
435 startup (note that SEC will close its standard input, standard
436 output, and standard error, and change its working directory to
437 the root directory). Default is --nodetach.
438 --jointbuf, --nojointbuf
440 if the --jointbuf option is specified, SEC uses joint input buf‐
441 fer for all input sources (the size of the buffer is set with
442 the --bufsize option). The --nojointbuf option creates a sepa‐
443 rate input buffer for each input file, and a separate buffer for
444 all synthetic and internal events (the sizes of all buffers are
445 set with the --bufsize option). The --jointbuf option allows
446 multiline patterns to match lines from several input sources,
447 while the --nojointbuf pattern restricts the matching to lines
448 from one input source only. See INPUT PROCESSING AND TIMING
449 section for more information. If the size of input buffer(s) is
450 1 (either explicitly set with --bufsize=1 or automatically de‐
451 termined from SEC rules), --jointbuf option is enabled, other‐
452 wise the default is --nojointbuf.
453 --keepopen, --nokeepopen
455 if the --keepopen option is specified, SEC will keep input files
456 open across soft restarts. When the SIGABRT signal is received,
457 SEC will not reopen input files which have been opened previ‐
458 ously, but will only open input files which are in the closed
459 state. The --nokeepopen option forces SEC to close and (re)open
460 all input files during soft restarts. Default is --keepopen.
461 --rwfifo, --norwfifo
463 if the --norwfifo option is specified, named pipe input files
464 are opened in read-only mode. In this mode, the named pipe has
465 to be reopened when the last writer closes the pipe, in order to
466 clear the EOF condition on the pipe. With the --rwfifo option,
467 named pipe input files are opened in read-write mode, although
468 SEC never writes to the pipes. In this mode, the pipe does not
469 need to be reopened when an external writer closes it, since
470 there is always at least one writer on the pipe and EOF will
471 never appear. Therefore, if the --notail option has been given,
472 --norwfifo should also be specified. Default is --rwfifo.
473 --childterm, --nochildterm
475 if the --childterm option is specified, SEC will send the
476 SIGTERM signal to all its child processes when it terminates or
477 goes through a full restart. Default is --childterm.
478 --intevents, --nointevents
480 SEC will generate internal events when it starts up, when it re‐
481 ceives certain signals, and when it terminates gracefully. Spe‐
482 cific rules can be written to match those internal events, in
483 order to accomplish special tasks at SEC startup, restart, and
484 shutdown. See INTERNAL EVENTS AND CONTEXTS section for more in‐
485 formation. Default is --nointevents.
486 --intcontexts, --nointcontexts
488 SEC will create an internal context when it reads a line from an
489 input file. This will help the user to write rules that match
490 data from particular input source only. See INTERNAL EVENTS AND
491 CONTEXTS section for more information. Default is --nointcon‐
492 texts.
493 --testonly, --notestonly
495 if the --testonly option is specified, SEC will exit immediately
496 after parsing the configuration file(s). If the configuration
497 file(s) contained no faulty rules, SEC will exit with 0, other‐
498 wise with 1. Default is --notestonly.
499 --help, -?
501 SEC will output usage information and exit.
502 --version
504 SEC will output version information and exit.
505 Note that options can be introduced both with the single dash (-) and
507 double dash (--), and both the equal sign (=) and whitespace can be
508 used for separating the option name from the option value. For example,
509 -conf=<file_pattern> and --conf <file_pattern> options are equivalent.
510
512 Each SEC configuration file consists of rule definitions which are sep‐
513 arated by empty lines, whitespace lines and/or comment lines. Each
514 rule definition consists of keyword=value fields, one keyword and value
515 per line. Values are case insensitive only where character case is not
516 important (like the values specifying rule types, e.g., 'Single' and
517 'single' are treated identically). The backslash character (\) may be
518 used at the end of a line to continue the current rule field in the
519 next line. Lines which begin with the number sign (#) are treated as
520 comments and ignored (whitespace characters may precede #). Any comment
521 line, empty line, whitespace line, or end of file will terminate the
522 preceding rule definition. For inserting comments into rule defini‐
523 tions, the rem keyword can be used. For example, the following lines
524 define two rules:
525 type=Single
527 rem=this rule matches any line which contains \
528 three consecutive A characters and writes the string \
529 "three A characters were observed" to standard output
530 ptype=SubStr
531 pattern=AAA
532 desc=Three A characters
533 action=write - three A characters were observed
534 # This comment line ends preceding rule definition.
535 # The following rule works like the previous rule,
536 # but looks for three consecutive B characters and
537 # writes the string "three B characters were observed"
538 # to standard output
539 type=Single
540 ptype=SubStr
541 pattern=BBB
542 desc=Three B characters
543 action=write - three B characters were observed
544 Apart from keywords that are part of rule definitions, label keywords
546 may appear anywhere in the configuration file. The value of each label
547 keyword will be treated as a label that can be referred to in rule def‐
548 initions as a point-of-continue. This allows for continuing event pro‐
549 cessing at a rule that follows the label, after the current rule has
550 matched and processed the event.
551 The points-of-continue are defined with continue* fields. Accepted val‐
553 ues for these fields are:
554 TakeNext
556 after an event has matched the rule, search for matching rules
557 in the configuration file will continue from the next rule.
558 GoTo <label>
560 after an event has matched the rule, search for matching rules
561 will continue from the location of <label> in the configuration
562 file (<label> must be defined with the label keyword anywhere in
563 the configuration file *after* the current rule definition).
564 DontCont (default value)
566 after an event has matched the rule, search for matching rules
567 ends in the *current* configuration file.
568 EndMatch
570 after an event has matched the rule, search for matching rules
571 ends for *all* configuration files.
572 SEC rules from the same configuration file are matched against input in
574 the order they have been given in the file. For example, consider a
575 configuration file which contains the following rule sequence:
576 type=Single
578 ptype=SubStr
579 pattern=AAA
580 rem=after this rule has matched, continue from last rule
581 continue=GoTo lastRule
582 desc=Three A characters
583 action=write - three A characters were observed
584 type=Single
586 ptype=SubStr
587 pattern=BBB
588 rem=after this rule has matched, don't consider following rules, \
589 since 'continue' defaults to 'DontCont'
590 desc=Three B characters
591 action=write - three B characters were observed
592 type=Single
594 ptype=SubStr
595 pattern=CCC
596 rem=after this rule has matched, continue from next rule
597 continue=TakeNext
598 desc=Three C characters
599 action=write - three C characters were observed
600 label=lastRule
602 type=Single
604 ptype=SubStr
605 pattern=DDD
606 desc=Three D characters
607 action=write - three D characters were observed
608 For the input line "AAABBBCCCDDD", this ruleset writes strings "three A
610 characters were observed" and "three D characters were observed" to
611 standard output. If the input line is "BBBCCCDDD", the string "three B
612 characters were observed" is written to standard output. For the input
613 line "CCCDDD", strings "three C characters were observed" and "three D
614 characters were observed" are sent to standard output, while the input
615 line "DDD" produces the output string "three D characters were ob‐
616 served".
617 If there are two or more configuration files, rule sequence from every
619 file is matched against input (unless explicitly specified otherwise).
620 For example, suppose SEC is started with the command line
621 /usr/bin/sec --input=- \
623 --conf=/etc/sec/sec1.rules --conf=/etc/sec/sec2.rules
624 and the configuration file /etc/sec/sec1.rules has the following con‐
626 tent:
627 type=Single
629 ptype=SubStr
630 pattern=AAA
631 desc=Three A characters
632 action=write - three A characters were observed
633 type=Single
635 ptype=SubStr
636 pattern=BBB
637 continue=EndMatch
638 desc=Three B characters
639 action=write - three B characters were observed
640 Also, suppose the configuration file /etc/sec/sec2.rules has the fol‐
642 lowing content:
643 type=Single
645 ptype=SubStr
646 pattern=CCC
647 desc=Three C characters
648 action=write - three C characters were observed
649 If SEC receives the line "AAABBBCCC" from standard input, rules from
651 both configuration files are tried, and as a result, the strings "three
652 A characters were observed" and "three C characters were observed" are
653 written to standard output. Note that rules from /etc/sec/sec1.rules
654 are tried first against the input line, since the option
655 --conf=/etc/sec/sec1.rules is given before --conf=/etc/sec/sec2.rules
656 in the SEC command line (see also INPUT PROCESSING AND TIMING section
657 for a more detailed discussion). If SEC receives the line "BBBCCC"
658 from standard input, the second rule from /etc/sec/sec1.rules produces
659 a match, and the string "three B characters were observed" is written
660 to standard output. Since the rule contains continue=EndMatch state‐
661 ment, the search for matching rules will end for all configuration
662 files, and rules from /etc/sec/sec2.rules will not be not tried. With‐
663 out this statement, the search for matching rules would continue in
664 /etc/sec/sec2.rules, and the first rule would write the string "three C
665 characters were observed" to standard output.
666
668 Patterns and pattern types are defined with pattern* and ptype* rule
669 fields. Many pattern types define the number of lines N which the pat‐
670 tern matches (if N is omitted, 1 is assumed). If N is greater than 1,
671 the scope of matching is set with the --jointbuf and --nojointbuf op‐
672 tions. With --jointbuf, the pattern is used for matching N last input
673 lines taken from the joint input buffer (the lines can come from dif‐
674 ferent input sources). With --nojointbuf, the source of the last input
675 line is identified, and the pattern is matched with N last input lines
676 from the input buffer of the identified source.
677 SubStr[N]
679 pattern is a string that is searched in the last N input lines
680 L1, L2, ..., LN. If N is greater than 1, the input lines are
681 joined into a string "L1<NEWLINE>L2<NEWLINE>...<NEWLINE>LN", and
682 the pattern string will be searched from it. If the pattern
683 string is found in input line(s), the pattern matches. Back‐
684 slash sequences \t, \n, \r, \s, and \0 can be used in the pat‐
685 tern for denoting tabulation, newline, carriage return, space
686 character, and empty string, respectively, while \\ denotes
687 backslash itself. For example, consider the following pattern
688 definition:
689 ptype=substr
691 pattern=Backup done:\tsuccess
692 The pattern matches lines containing "Backup done:<TAB>success".
694 Note that since the SubStr[N] pattern type has been designed for
696 fast matching, it does not support match variables.
697 RegExp[N]
699 pattern is a Perl regular expression (see perlre(1) for more in‐
700 formation) for matching the last N input lines L1, L2, ..., LN.
701 If N is greater than 1, the input lines are joined into a string
702 "L1<NEWLINE>L2<NEWLINE>...<NEWLINE>LN", and the regular expres‐
703 sion is matched with this string. If the regular expression
704 matches, match variables will be set, and these match variables
705 can be used in other parts of the rule definition.
706 In addition to numbered match variables ($1, $2, etc.), SEC sup‐
708 ports named match variables $+{name} and the $0 variable. The $0
709 variable holds the entire string of last N input lines that the
710 regular expression has matched. Named match variables can be
711 created in newer versions of Perl regular expression language,
712 e.g., (?<myvar>AB|CD) sets $+{myvar} to AB or CD. Also, SEC cre‐
713 ates special named match variables $+{_inputsrc} and $+{_intcon‐
714 text}. The $+{_inputsrc} variable holds input file name(s) where
715 matching line(s) came from. The $+{_intcontext} variable holds
716 the name of current internal context (see INTERNAL EVENTS AND
717 CONTEXTS section for more information). If internal context has
718 not been set up for the current input source, the variable is
719 set to Perl undefined value.
720 For example, the following pattern matches the SSH "Connection
722 from" event, and sets $0 to the entire event line, both $1 and
723 $+{ip} to the IP address of the remote node, and $2 to the port
724 number at the remote node:
725 ptype=RegExp
727 pattern=sshd\[\d+\]: Connection from (?<ip>[\d.]+) port (\d+)
728 If the matching event comes from input file /var/log/messages
730 with internal context MSGS, the $+{_inputsrc} and $+{_intcon‐
731 text} variables are set to strings "/var/log/messages" and
732 "MSGS", respectively.
733 Also, SEC allows for match caching and for the creation of addi‐
735 tional named match variables through variable maps which are de‐
736 fined with the varmap* fields. Variable map is a list of
737 name=number mappings separated by semicolons, where name is the
738 name for the named variable and number identifies a numbered
739 match variable that is set by the regular expression. Each name
740 must begin with a letter and consist of letters, digits and un‐
741 derscores. After the regular expression has matched, named vari‐
742 ables specified by the map are created from corresponding num‐
743 bered variables. If the same named variable is set up both from
744 the regular expression and variable map, the map takes prece‐
745 dence.
746 If name is not followed by the equal sign and number in the
748 varmap* field, it is regarded as a common name for all match
749 variables and their values from a successful match. This name
750 is used for caching a successful match by the pattern -- match
751 variables and their values are stored in the memory-based pat‐
752 tern match cache under name. Cached match results can be reused
753 by Cached and NCached patterns. Note that before processing each
754 new input line, previous content of the pattern match cache is
755 cleared. Also note that a successful pattern match is cached
756 even if the subsequent context expression evaluation yields
757 FALSE (see INPUT PROCESSING AND TIMING section for more informa‐
758 tion).
759 For example, consider the following pattern definition:
761 ptype=regexp
763 pattern=(?i)(\S+\.mydomain).*printer: toner\/ink low
764 varmap=printer_toner_or_ink_low; message=0; hostname=1
765 The pattern matches "printer: toner/ink low" messages in a case
767 insensitive manner from printers belonging to .mydomain. Note
768 that the printer hostname is assigned to $1 and $+{hostname},
769 while the whole message line is assigned to $0 and $+{message}.
770 If the message comes from file /var/log/test which does not have
771 an internal context defined, the $+{_inputsrc} variable is set
772 to string "/var/log/test", while $+{_intcontext} is set to Perl
773 undefined value. Also, these variables and their values are
774 stored to the pattern match cache under the name
775 "printer_toner_or_ink_low".
776 The following pattern definition produces a match if the last
778 two input lines are AAA and BBB:
779 ptype=regexp2
781 pattern=^AAA\nBBB$
782 varmap=aaa_bbb
783 Note that with the --nojointbuf option the pattern only matches
785 if the matching lines are coming from the *same* input file,
786 while the --jointbuf option lifts that restriction.
787 In the case of a match, $0 is set to "AAA<NEWLINE>BBB", $+{_in‐
789 putsrc} to file name(s) for matching lines, and $+{_intcontext}
790 to the name of current internal context. Also, these variable-
791 value pairs are cached under the name "aaa_bbb".
792 PerlFunc[N]
794 pattern is a Perl function for matching the last N input lines
795 L1, L2, ..., LN. The Perl function is compiled at SEC startup
796 with the Perl eval() function, and eval() must return a code
797 reference for the pattern to be valid (see also PERL INTEGRATION
798 section). The function is called in Perl list context, and with
799 the --jointbuf option, lines L1, L2, ..., LN and the names of
800 corresponding input files F1, F2, ..., FN are passed to the
801 function as parameters:
802 function(L1, L2, ..., LN, F1, F2, ..., FN)
804 Note that with the --nojointbuf option, the function is called
806 with a single file name parameter F, since lines L1, ..., LN are
807 coming from the same input file:
808 function(L1, L2, ..., LN, F)
810 Also note that if the input line is a synthetic event, the input
812 file name is Perl undefined value.
813 If the function returns several values or a single value that is
815 true in Perl boolean context, the pattern matches. If the func‐
816 tion returns no values or a single value that is false in Perl
817 boolean context (0, empty string or undefined value), the pat‐
818 tern does not match. If the pattern matches, return values will
819 be assigned to numbered match variables ($1, $2, etc.). Like
820 with RegExp patterns, the $0 variable is set to matching input
821 line(s), the $+{_inputsrc} variable is set to input file
822 name(s), the $+{_intcontext} variable is set to the name of cur‐
823 rent internal context, and named match variables can be created
824 from variable maps. For example, consider the following pattern
825 definition:
826 ptype=perlfunc2
828 pattern=sub { return ($_[0] cmp $_[1]); }
829 The pattern compares last two input lines in a stringwise manner
831 ($_[1] holds the last line and $_[0] the preceding one), and
832 matches if the lines are different. Note that the result of the
833 comparison is assigned to $1, while two matching lines are con‐
834 catenated (with the newline character between them) and assigned
835 to $0. If matching lines come from input file /var/log/mylog
836 with internal context TEST, the $+{_inputsrc} and $+{_intcon‐
837 text} variables are set to strings "/var/log/mylog" and "TEST",
838 respectively.
839 The following pattern produces a match for any line, and sets
841 $1, $2 and $3 variables to strings "abc", "def" and "ghi", re‐
842 spectively (also, $0 is set to the whole input line, $+{_input‐
843 src} to the input file name, and $+{_intcontext} to the name of
844 internal context associated with input file $+{_inputsrc}):
845 ptype=perlfunc
847 pattern=sub { return ("abc", "def", "ghi"); }
848 The following pattern definition produces a match if the input
850 line is not a synthetic event and contains either the string
851 "abc" or "def". The $0 variable is set to the matching line. If
852 matching line comes from /var/log/test without an internal con‐
853 text, $+{_intcontext} is set to Perl undefined value, while $1,
854 $+{file} and $+{_inputsrc} are set to string "/var/log/test":
855 ptype=perlfunc
857 pattern=sub { if (defined($_[1]) && $_[0] =~ /abc|def/) \
858 { return $_[1]; } return 0; }
859 varmap= file=1
860 Finally, if a function pattern returns a single value which is a
862 reference to a Perl hash, named match variables are created from
863 key-value pairs in the hash. For example, the following pattern
864 matches a line if it contains either the string "three" or
865 "four". Apart from setting $0, $+{_inputsrc} and $+{_intcon‐
866 text}, the pattern also creates match variables $+{three} and
867 $+{four}, and sets them to 3 and 4, respectively:
868 ptype=perlfunc
870 pattern=sub { my(%hash); \
871 if ($_[0] !~ /three|four/) { return 0; } \
872 $hash{"three"} = 3; $hash{"four"} = 4; return \%hash; }
873 Cached pattern is a name that is searched in the pattern match cache
875 (entries are stored into the cache with the varmap* fields). If
876 an entry with the given name is found in the cache, the pattern
877 matches, and match variables and values are retrieved from the
878 cache. For example, if the input line matches the following
879 pattern
880 ptype=perlfunc
882 pattern=sub { if (defined($_[1]) && $_[0] =~ /abc|def/) \
883 { return $_[1]; } return 0; }
884 varmap=abc_or_def_found; file=1
885 then the entry "abc_or_def_found" is created in the pattern
887 match cache. Therefore, the pattern
888 ptype=cached
890 pattern=abc_or_def_found
891 will also produce a match for this input line, and set the $0,
893 $1, $+{file}, $+{_inputsrc}, and $+{_intcontext} variables to
894 values from the previous match.
895 NSubStr[N]
897 like SubStr[N], except that the result of the match is negated.
898 Note that this pattern type does not support match variables.
899 NRegExp[N]
901 like RegExp[N], except that the result of the match is negated
902 and variable maps are not supported. Note that the only match
903 variables supported by this pattern type are $0, $+{_inputsrc},
904 and $+{_intcontext}.
905 NPerlFunc[N]
907 like PerlFunc[N], except that the result of the match is negated
908 and variable maps are not supported. Note that the only match
909 variables supported by this pattern type are $0, $+{_inputsrc},
910 and $+{_intcontext}.
911 NCached
913 like Cached, except that the result of the match is negated.
914 Note that this pattern type does not support match variables.
915 TValue pattern is a truth value, with TRUE and FALSE being legitimate
917 values. TRUE always matches an input line, while FALSE never
918 matches anything. Note that this pattern type does not support
919 match variables.
920 When match variables are substituted, each "$$" sequence is interpreted
922 as a literal dollar sign ($) which allows for masking match variables.
923 For example, the string "Received $$1" becomes "Received $1" after sub‐
924 stitution, while "Received $$$1" becomes "Received
925 $<value_of_1st_var>". In order to disambiguate numbered match vari‐
926 ables from the following text, variable number must be enclosed in
927 braces. For example, the string "Received ${1}0" becomes "Received
928 <value_of_1st_var>0" after substitution, while the string "Received
929 $10" would become "Received <value_of_10th_var>".
930 If the match variable was not set by the pattern, it is substituted
932 with an empty string (i.e., a zero-width string). Thus the string "Re‐
933 ceived $10!" becomes "Received !" after substitution if the pattern did
934 not set $10. (Note that prior to SEC-2.6, unset variables were *not*
935 substituted.)
936 In the current version of SEC, names of $+{name} match variables must
938 comply with the following naming convention -- the first character can
939 be a letter or underscore, while remaining characters can be letters,
940 digits, underscores and exclamation marks (!). However, when setting
941 named match variables from a pattern, it is recommended to begin the
942 variable name with a letter, since names of special automatically cre‐
943 ated variables begin with an underscore (e.g., $+{_inputsrc}).
944 After the pattern has matched an event and match variables have been
946 set, it is also possible to refer to previously cached match variables
947 with the syntax $:{entryname:varname}, where entryname is the name of
948 the pattern match cache entry, and varname is the name of the variable
949 stored under the entry. For example, if the variable $+{ip} has been
950 previously cached under the entry "SSH", it can be referred as
951 $:{SSH:ip}. For the reasons of efficiency, the $:{entryname:varname}
952 syntax is not supported for fast pattern types which do not set match
953 variables (i.e., SubStr, NSubStr, NCached and TValue).
954 Note that since Pair and PairWithWindow rules have two patterns, match
956 variables of the first pattern are shadowed for some rule fields when
957 the second pattern matches and sets variables. In order to refer to
958 shadowed variables, their names must begin with % instead of $ (e.g.,
959 %1 refers to match variable $1 set by the first pattern). However, the
960 use of the %-prefix is only valid under the following circumstances --
961 *both* pattern types support match variables *and* in the given rule
962 field match variables from *both* patterns can be used.
963 The %-prefixed match variables are masked with the "%%" sequence (like
965 regular match variables with "$$"). Similarly, the braces can be used
966 for disambiguating the %-prefixed variables from the following text.
967 Finally, note that the second pattern of Pair and PairWithWindow rules
969 may contain match variables if the second pattern is of type SubStr,
970 NSubStr, Regexp, or NRegExp. The variables are substituted at runtime
971 with the values set by the first pattern. If the pattern is a regular
972 expression, all special characters inside substituted values are masked
973 with the Perl quotemeta() function and the final expression is checked
974 for correctness.
975
977 A SEC context is a memory based entity which has one or more names, a
978 lifetime, and an event store. Also, an action list can be set up for a
979 context which is executed immediately before the context expires.
980 For example, the action create MYCONTEXT 3600 (report MYCONTEXT
982 /bin/mail root@localhost) creates the context MYCONTEXT which has a
983 lifetime of 3600 seconds and empty event store. Also, immediately be‐
984 fore MYCONTEXT expires and is dropped from memory, the action report
985 MYCONTEXT /bin/mail root@localhost is executed which mails the event
986 store of MYCONTEXT to root@localhost.
987 Contexts can be used for event aggregation and reporting. Suppose the
989 following actions are executed in this order:
990 create MYCONTEXT
992 add MYCONTEXT This is a test
993 alias MYCONTEXT MYALIAS
994 add MYALIAS This is another test
995 report MYCONTEXT /bin/mail root@localhost
996 delete MYALIAS
997 The first action creates the context MYCONTEXT with infinite lifetime
999 and empty event store. The second action appends the string "This is a
1000 test" to the event store of MYCONTEXT. The third action sets up an
1001 alias name MYALIAS for the context (names MYCONTEXT and MYALIAS refer
1002 to the same context data structure). The fourth action appends the
1003 string "This is another test" to the event store of the context. The
1004 fifth action writes the lines
1005 This is a test
1007 This is another test
1008 to the standard input of the /bin/mail root@localhost command. The
1010 sixth action deletes the context data structure from memory and drops
1011 its names MYCONTEXT and MYALIAS.
1012 Since contexts are accessible from all rules and event correlation op‐
1014 erations, they can be used for data sharing and joining several rules
1015 into one event correlation scheme. In order to check for the presence
1016 of contexts from rules, context expressions can be employed.
1017 Context expressions are boolean expressions that are defined with the
1019 context* rule fields. Context expressions can be used for restricting
1020 the matches produced by patterns, since if the expression evaluates
1021 FALSE, the rule will not match an input event.
1022 The context expression accepts context names, Perl miniprograms, Perl
1024 functions, and pattern match cache lookups as operands. These operands
1025 can be combined with the following operators:
1026 ! - logical NOT,
1027 && - short-circuit logical AND,
1028 || - short-circuit logical OR.
1029 In addition, parentheses can be used for grouping purposes.
1030 If the operand does not contain any special operators (such as -> or
1032 :>, see below), it is treated as a context name. Context name operands
1033 may contain match variables, but may not contain whitespace. If the
1034 context name refers to an existing context, the operand evaluates TRUE,
1035 otherwise it evaluates FALSE.
1036 For example, consider the following rule sequence:
1038 type=Single
1040 ptype=RegExp
1041 pattern=Test: (\d+)
1042 desc=test
1043 action=create CONT_$1
1044 type=Single
1046 ptype=RegExp
1047 pattern=Test2: (\d+) (\d+)
1048 context=CONT_$1 && CONT_$2
1049 desc=test
1050 action=write - Both $1 and $2 have been seen in the past
1051 If the following input lines appear in this order
1053 Test: 19
1055 Test: 261
1056 Test2: 19 787
1057 Test: 787
1058 Test2: 787 261
1059 the first input line matches the first rule which creates the context
1061 CONT_19, and similarly, the second input line triggers the creation of
1062 the context CONT_261. The third input line "Test2: 19 787" matches the
1063 regular expression
1064 Test2: (\d+) (\d+)
1066 but does not match the second rule, since the boolean expression
1068 CONT_19 && CONT_787
1070 evaluates FALSE (context CONT_19 exists, but context CONT_787 doesn't).
1072 The fourth input line matches the first rule which creates the context
1073 CONT_787. The fifth input line "Test2: 787 261" matches the second
1074 rule, since the boolean expression
1075 CONT_787 && CONT_261
1077 evaluates TRUE (both context CONT_787 and context CONT_261 exist), and
1079 therefore the string "Both 787 and 261 have been seen in the past" is
1080 written to standard output.
1081 If the context expression operand contains the arrow operator (->), the
1083 text following the arrow must be a valid Perl function definition that
1084 is compiled at SEC startup with the Perl eval() function. The eval()
1085 must return a code reference (see also PERL INTEGRATION section for
1086 more information). If any text precedes the arrow, it is treated as a
1087 list of parameters for the function. Parameters must be separated by
1088 whitespace and may contain match variables. In order to evaluate the
1089 context expression operand, the Perl function is called in the Perl
1090 scalar context. If the return value of the function is true in the Perl
1091 boolean context, the operand evaluates TRUE, otherwise it evaluates
1092 FALSE.
1093 For example, the following rule matches an SSH login failure event if
1095 the login attempt comes from a privileged port of the client host:
1096 type=Single
1098 ptype=RegExp
1099 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port (\d+) ssh2
1100 context=$2 -> ( sub { $_[0] < 1024 } )
1101 desc=SSH login failure for $1 priv port $2
1102 action=write - SSH login failure for user $1 from a privileged port $2
1103 When the following message from SSH daemon appears
1105 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
1107 10.12.2.5 port 41063 ssh2
1108 the regular expression of the rule matches this message, and the value
1110 of the $2 match variable (41063) is passed to the Perl function
1111 sub { $_[0] < 1024 }
1113 This function returns true if its input parameter is less than 1024 and
1115 false otherwise, and therefore the above message will not match the
1116 rule. However, the following message
1117 Dec 16 16:25:17 myserver sshd[13689]: Failed password for risto from
1119 10.12.2.5 port 1023 ssh2
1120 matches the rule, and the string "SSH login failure for user risto from
1122 a privileged port 1023" is written to standard output.
1123 As another example, the following context expression evaluates TRUE if
1125 the /var/log/messages file does not exist or was last modified more
1126 than 1 hour ago (note that the Perl function takes no parameters):
1127 context= -> ( sub { my(@stat) = stat("/var/log/messages"); \
1129 return (!scalar(@stat) || time() - $stat[9] > 3600); } )
1130 If the context expression operand contains the :> operator, the text
1132 that follows :> must be a valid Perl function definition that is com‐
1133 piled at SEC startup with the Perl eval() function. The eval() must re‐
1134 turn a code reference (see also PERL INTEGRATION section for more in‐
1135 formation). If any text precedes the :> operator, it is treated as a
1136 list of parameters for the function. Parameters must be separated by
1137 whitespace and may contain match variables. It is assumed that each
1138 parameter is a name of an entry in the pattern match cache. If an entry
1139 with the given name does not exist, Perl undefined value is passed to
1140 the function. If an entry with the given name exists, a reference to
1141 the entry is passed to the Perl function. Internally, each pattern
1142 match cache entry is implemented as a Perl hash which contains all
1143 match variables for the given entry. In the hash, each key-value pair
1144 represents some variable name and value, e.g., if cached match variable
1145 $+{ip} is holding 10.1.1.1, the hash contains the value 10.1.1.1 with
1146 the key ip. In order to evaluate the context expression operand, the
1147 Perl function is called in the Perl scalar context. If the return value
1148 of the function is true in the Perl boolean context, the operand evalu‐
1149 ates TRUE, otherwise it evaluates FALSE.
1150 For example, consider the following rule sequence:
1152 type=Single
1154 ptype=RegExp
1155 pattern=sshd\[\d+\]: (?<status>Accepted|Failed) .+ \
1156 for (?<invuser>invalid user )?(?<user>\S+) from (?<ip>[\d.]+) \
1157 port (?<port>\d+) ssh2
1158 varmap=SSH
1159 continue=TakeNext
1160 desc=parse SSH login events and pass them to following rules
1161 action=none
1162 type=Single
1164 ptype=Cached
1165 pattern=SSH
1166 context=SSH :> ( sub { $_[0]->{"status"} eq "Failed" && \
1167 $_[0]->{"port"} < 1024 && \
1168 defined($_[0]->{"invuser"}) } )
1169 desc=Probe of invalid user $+{user} from privileged port of $+{ip}
1170 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
1171 The first rule matches and parses SSH login messages, and stores pars‐
1173 ing results to the pattern match cache under the name SSH. The pattern
1174 of the second rule (defined with ptype=Cached and pattern=SSH) matches
1175 any input event for which the entry SSH has been previously created in
1176 the pattern match cache (in other words, the event has been recognized
1177 and parsed as an SSH login message). For each matching event, the sec‐
1178 ond rule passes the reference to the SSH cache entry to the Perl func‐
1179 tion
1180 sub { $_[0]->{"status"} eq "Failed" && \
1182 $_[0]->{"port"} < 1024 && \
1183 defined($_[0]->{"invuser"}) }
1184 The function checks the values of $+{status}, $+{port}, and $+{invuser}
1186 match variables under the SSH entry, and returns true if $+{status}
1187 equals to the string "Failed" (i.e., login attempt failed), the value
1188 of $+{port} is less than 1024, and $+{invuser} holds a defined value
1189 (i.e., user account does not exist). If the function (and thus context
1190 expression) evaluates TRUE, the rule sends a warning e-mail to root@lo‐
1191 calhost that a non-existing user account was probed from a privileged
1192 port of a client host.
1193 If the context expression operand begins with the varset keyword, the
1195 following string is treated as a name of an entry in the pattern match
1196 cache. The operand evaluates TRUE if the given entry exists, and FALSE
1197 otherwise.
1198 For example, the following context expression definition evaluates TRUE
1200 if the pattern match cache entry SSH exists and under this entry, the
1201 value of the match variable $+{user} equals to the string "risto":
1202 context=varset SSH && SSH :> ( sub { $_[0]->{"user"} eq "risto" } )
1204 If the context expression operand begins with the equal sign (=), the
1206 following text must be a Perl miniprogram which is a valid parameter
1207 for the Perl eval() function. The miniprogram may contain match vari‐
1208 ables. In order to evaluate the Perl miniprogram operand, it will be
1209 compiled and executed by calling the Perl eval() function in the Perl
1210 scalar context (see also PERL INTEGRATION section). If the return
1211 value from eval() is true in the Perl boolean context, the operand
1212 evaluates TRUE, otherwise it evaluates FALSE. Please note that unlike
1213 Perl functions of -> and :> operators which are compiled once at SEC
1214 startup, Perl miniprograms are compiled before each execution, and
1215 their evaluation is thus considerably more expensive.
1216 For example, the following context expression evaluates TRUE when nei‐
1218 ther the context C1 nor the context C2 exists and the value of the $1
1219 variable equals to the string "myhost.mydomain":
1220 context=!(C1 || C2) && =("$1" eq "myhost.mydomain")
1222 Since && is a short-circuiting operator, the Perl code
1224 "$1" eq "myhost.mydomain"
1226 is *not* evaluated if either C1 or C2 exists.
1228 Note that since Perl functions and miniprograms may contain strings
1230 that clash with context expression operators (e.g., '!'), it is recom‐
1231 mended to enclose them in parentheses, e.g.,
1232 context=$1 $2 -> ( sub { $_[0] != $_[1] } )
1234 context= =({my($temp) = 0; !$temp;})
1236 Also, if function parameter lists contain such strings, they should be
1238 enclosed in parentheses in the similar way:
1239 context=($1! $2) -> ( sub { $_[0] eq $_[1] } )
1241 If the whole context expression is enclosed in square brackets [],
1243 e.g., [MYCONTEXT1 && !MYCONTEXT2], SEC evaluates the expression *be‐
1244 fore* pattern matching (normally, the pattern is matched with input
1245 line(s) first, so that match variables would be initialized and substi‐
1246 tuted before the expression is evaluated). However, if the expression
1247 does not contain match variables and many input events are known to
1248 match the pattern but not the expression, the []-operator could save
1249 substantial amount of CPU time.
1250
1252 Action lists are defined with the action* rule fields. An action list
1253 consists of action definitions that are separated by semicolons. Each
1254 action definition begins with a keyword specifying the action type.
1255 Depending on the action type, parameters may follow, and non-constant
1256 parameters may contain match variables. For instance, if the $1 and $2
1257 match variables have the values "test1" and "the second test", respec‐
1258 tively, the action create MYCONT_$1 60 creates the context MYCONT_test1
1259 with the lifetime of 60 seconds, while the action write - The names of
1260 tests: $1, $2 writes the string "The names of tests: test1, the second
1261 test" to standard output.
1262 Apart from few exceptions explicitly noted, match variables are substi‐
1264 tuted at the earliest opportunity in action lists. For example, con‐
1265 sider the following rule definition:
1266 type=SingleWithThreshold
1268 ptype=RegExp
1269 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
1270 desc=Three SSH login failures within 1m
1271 action=pipe 'Three SSH login failures, first user is $1' \
1272 /bin/mail -s 'SSH login alert' root@localhost
1273 window=60
1274 thresh=3
1275 When this rule matches an SSH login failure event which starts an event
1277 correlation operation, the operation substitutes the $1 match variable
1278 in the action list definition with the user name from the matching
1279 event, and user names from further events processed by this event cor‐
1280 relation operation are not considered for $1. For example, if the fol‐
1281 lowing events are observed
1282 Dec 16 16:24:52 myserver sshd[13671]: Failed password for root from
1284 10.12.2.5 port 29736 ssh2
1285 Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from
1286 10.12.2.5 port 41063 ssh2
1287 Dec 16 16:25:01 myserver sshd[13689]: Failed password for oracle from
1288 10.12.2.5 port 11204 ssh2
1289 then all events are processed by the same operation, and the message
1291 "Three SSH login failures, first user is root" is mailed to root@local‐
1292 host.
1293 In order to use semicolons inside a non-constant parameter, the parame‐
1295 ter must be enclosed in parentheses (the outermost set of parentheses
1296 will be removed by SEC during configuration file parsing). For exam‐
1297 ple, the following action list consists of delete and shellcmd actions:
1298 action=delete MYCONTEXT; shellcmd (rm /tmp/sec1.tmp; rm /tmp/sec2.tmp)
1300 The delete action deletes the context MYCONTEXT, while the shellcmd ac‐
1302 tion executes the command line rm /tmp/sec1.tmp; rm /tmp/sec2.tmp.
1303 Since the command line contains a semicolon, it has been enclosed in
1304 parentheses, since otherwise the semicolon would be mistakenly consid‐
1305 ered a separator between two actions.
1306 Apart from match variables, SEC supports action list variables in ac‐
1308 tion lists which facilitate data sharing between actions and Perl inte‐
1309 gration. Each action list variable has a name which must begin with a
1310 letter and consist of letters, digits and underscores. Names of built-
1311 in variables usually start with a dot character (.), so that they can
1312 be distinguished from user defined variables. In order to refer to an
1313 action list variable, its name must be prefixed by a percent sign (%).
1314 Unlike match variables, action list variables can only be used in ac‐
1315 tion lists and they are substituted with their values immediately be‐
1316 fore the action list execution. Also, action list variables continue to
1317 exist after the current action list has been executed and can be em‐
1318 ployed in action lists of other rules.
1319 The following action list variables are predefined by SEC:
1321 %s operation description string (the value of the desc field after
1323 match variables have been substituted with their values). Note
1324 that for the action2 field of Pair and PairWithWindow rules, the
1325 %s variable is set by evaluating the desc2 field of the rule.
1326 %t the time in human-readable format, as returned by the Perl lo‐
1328 caltime() function in the Perl scalar context (e.g., Fri Feb 19
1329 17:54:18 2016).
1330 %u the time in seconds since Epoch, as returned by the time(2) sys‐
1332 tem call.
1333 %.sec number of seconds after the minute, in the range 00-59 (the
1335 value consists of two digits and is zero padded on the left).
1336 %.min number of minutes after the hour, in the range 00-59 (the value
1338 consists of two digits and is zero padded on the left).
1339 %.hour number of hours past midnight, in the range 00-23 (the value
1341 consists of two digits and is zero padded on the left).
1342 %.hmsstr
1344 the time in HH:MM:SS format (hours, minutes and seconds sepa‐
1345 rated by colons, e.g., 09:32:04 or 18:06:02).
1346 %.mday day of the month, in the range 01-31 (the value consists of two
1348 digits and is zero padded on the left).
1349 %.mdaystr
1351 day of the month as a string (the value consists of two charac‐
1352 ters and is space padded on the left, e.g., " 1", " 4", " 9", or
1353 "25").
1354 %.mon month, in the range 01-12 (the value consists of two digits and
1356 is zero padded on the left).
1357 %.monstr
1359 abbreviated name of the month according to the current locale,
1360 as returned by the %b specification of the strftime(3) library
1361 call (e.g., Jan, May, or Sep).
1362 %.year year (e.g., 1998 or 2016).
1364 %.wday day of the week, in the range 0-6 (0 denotes Sunday).
1366 %.wdaystr
1368 abbreviated name of the day of the week according to the current
1369 locale, as returned by the %a specification of the strftime(3)
1370 library call (e.g., Mon, Wed, or Sat).
1371 %.tzname
1373 name of the timezone according to the current locale, as re‐
1374 turned by the %Z specification of the strftime(3) library call
1375 (e.g., UTC or EET).
1376 %.tzoff
1378 timezone offset from UTC, as returned by the %z specification of
1379 the strftime(3) library call (e.g., -0500 or +0200).
1380 %.tzoff2
1382 timezone offset from UTC in +hh:mm/-hh:mm format (e.g., -05:00
1383 or +02:00), provided that the %z specification of the strf‐
1384 time(3) library call returns the value in +hhmm/-hhmm format (if
1385 the value does not follow this format, %.tzoff2 is set to an
1386 empty string).
1387 %.nl newline character.
1389 %.cr carriage return character.
1391 %.tab tabulation character.
1393 %.sp space character.
1395 %.chr0, ..., %.chr31
1397 ASCII 0..31 control characters (e.g., %.chr7 is bell and %.chr12
1398 is form feed character).
1399 For example, the following action list assigns the current time in hu‐
1401 man-readable format and the string "This is a test event" to the %text
1402 action list variable, and mails the value of %text to root@localhost:
1403 action=assign %text %t: This is a test event; \
1405 pipe '%text' /bin/mail root@localhost
1406 If the action list is executed at Nov 19 10:58:51 2015, the assign ac‐
1408 tion sets the %text action list variable to the string "Thu Nov 19
1409 10:58:51 2015: This is a test event", while the pipe action mails this
1410 string to root@localhost. Note that unlike match variables, action
1411 list variables have a global scope, and accessing the value of the
1412 %text variable in action lists of other rules will thus yield the
1413 string "Thu Nov 19 10:58:51 2015: This is a test event" (until another
1414 value is assigned to %text).
1415 In order to disambiguate the variable from the following text, the
1417 variable name must be enclosed in braces. For example, the following
1418 action
1419 action=write - %{.year}-%{.mon}-%{.mday}T%{.hmsstr}%{.tzoff2}
1421 writes a timestamp in ISO 8601 format to standard output, e.g.,
1423 2016-02-24T07:34:01+02:00 (replacing %{.mday} with %.mday in the above
1424 action would mistakenly create a reference to %.mdayT variable).
1425 When action list variables are substituted with their values, each se‐
1427 quence "%%" is interpreted as a literal percent sign (%) which allows
1428 for masking the variables. For example, the string "s%%t" becomes "s%t"
1429 after substitution, not "s%<timestamp>".
1430 However, note that if %-prefixed match variables are supported for the
1432 action2 field of the Pair or PairWithWindow rule, the sequence "%%%"
1433 must be used in action2 for masking a variable, since the string goes
1434 through *two* variable substitution rounds (first for %-prefixed match
1435 variables and then for action list variables, e.g., the string "s%%%t"
1436 first becomes "s%%t" and finally "s%t").
1437 Whenever a rule field goes through several substitution rounds, the $
1439 or % characters are masked inside values substituted during earlier
1440 rounds, in order to avoid unwanted side effects during later rounds.
1441 If the action list variable has not been set, it is substituted with an
1443 empty string (i.e., a zero-width string). Thus the string "Value of A
1444 is: %a" becomes "Value of A is: " after substitution if the variable %a
1445 is unset. (Note that prior to SEC-2.6, unset variables were *not* sub‐
1446 stituted.)
1447 Finally, the values are substituted as strings, therefore values of
1449 other types (e.g., references) lose their original meaning, unless ex‐
1450 plicitly noted otherwise (e.g., if a Perl function reference is stored
1451 to an action list variable, the function can later be invoked through
1452 this variable with the call action).
1453 SEC supports the following actions (optional parameters are enclosed in
1455 square brackets):
1456 none No action.
1458 logonly [<string>]
1460 Message <string> is logged to destinations given with the --log
1461 and --syslog options. The level of the log message is set to 4
1462 (see the --debug option for more information on log message lev‐
1463 els). Default value for <string> is %s. For example, consider
1464 the following action list definition:
1465 action=logonly This is a test
1467 The above logonly action logs the message "This is a test" with
1469 level 4.
1470 write <filename> [<string>]
1472 String <string> with a terminating newline is written to the
1473 file <filename> (<filename> may not contain whitespace). File
1474 may be a regular file, named pipe, or standard output (denoted
1475 by -). If the file is a regular file, <string> is appended to
1476 the end of the file. If the file does not exist, it is created
1477 as a regular file before writing. Note that the file will not
1478 be closed after the action completes, and the following write
1479 actions will access an already open file. However, several sig‐
1480 nals cause the file to be closed and reopened, and for rotating
1481 files created with write action, the SIGUSR2 signal can be used
1482 (see SIGNALS section for more information). Default value for
1483 <string> is %s. For example, consider the following action list
1484 definition:
1485 action=write /var/log/test.log %t $0
1487 The above write action prepends human-readable timestamp and
1489 separating space character to the value of the $0 match vari‐
1490 able, and the resulting string is appended to file
1491 /var/log/test.log with terminating newline.
1492 writen <filename> [<string>]
1494 Similar to the write action, except that the string <string> is
1495 written without a terminating newline. Note that write and
1496 writen actions share the same filehandle for accessing the file.
1497 For example, consider the following action list definition:
1498 action=writen - ab; writen - c; writen - %.nl
1500 The above action list writes the string "abc<NEWLINE>" to stan‐
1502 dard output, and is thus identical to write - abc (and also to
1503 writen - abc%.nl).
1504 closef <filename>
1506 Close the file <filename> that has been previously opened by the
1507 write or writen action (<filename> may not contain whitespace).
1508 owritecl <filename> [<string>]
1510 Similar to the write action, except that the file <filename> is
1511 opened and closed at each write. Also, the string <string> is
1512 written without a terminating newline. If the file has already
1513 been opened by a previous write action, owritecl does not use
1514 existing filehandle, but opens and closes the file separately.
1515 For example, consider the following action list definition:
1516 action=owritecl /var/log/test-%{.year}%{.mon}%{.mday} $0%{.nl}
1518 The above owritecl action appends the value of the $0 match
1520 variable with terminating newline to file /var/log/test-YYYYM‐
1521 MDD, where YYYYMMDD reflects the current date (e.g., if the cur‐
1522 rent date is April 1 2018, the file is /var/log/test-20180401).
1523 Since the file is closed after each write, the old file will not
1524 be left open when date changes.
1525 udgram <filename> [<string>]
1527 String <string> is written to the UNIX datagram socket <file‐
1528 name> (<filename> may not contain whitespace). Note that the
1529 socket will not be closed after the action completes, and the
1530 following udgram actions will access an already open socket.
1531 However, several signals cause the socket to be closed and re‐
1532 opened (see SIGNALS section for more information). Default
1533 value for <string> is %s. For example, consider the following
1534 action list definition:
1535 action=udgram /dev/log <30>%.monstr %.mdaystr %.hmsstr sec: This
1537 is a test
1538 The above udgram action sends a syslog message to local syslog
1540 daemon via /dev/log socket, where message priority is 30 (corre‐
1541 sponds to the "daemon" facility and "info" level), syslog tag is
1542 "sec" and message text is "This is a test". Note that message
1543 substring "%.monstr %.mdaystr %.hmsstr" evaluates to timestamp
1544 in BSD syslog format (e.g., Mar 31 15:36:07).
1545 closeudgr <filename>
1547 Close the UNIX datagram socket <filename> that has been previ‐
1548 ously opened by the udgram action (<filename> may not contain
1549 whitespace).
1550 ustream <filename> [<string>]
1552 String <string> is written to the UNIX stream socket <filename>
1553 (<filename> may not contain whitespace). Note that the socket
1554 will not be closed after the action completes, and the following
1555 ustream actions will access an already open socket. However,
1556 several signals cause the socket to be closed and reopened (see
1557 SIGNALS section for more information). Default value for
1558 <string> is %s.
1559 closeustr <filename>
1561 Close the UNIX stream socket <filename> that has been previously
1562 opened by the ustream action (<filename> may not contain white‐
1563 space).
1564 udpsock <host>:<port> [<string>]
1566 String <string> is sent to the UDP port <port> of the host
1567 <host>. Note that the UDP socket which is used for communica‐
1568 tion will not be closed after the action completes, and the fol‐
1569 lowing udpsock actions for the same remote peer will use an al‐
1570 ready existing socket. However, several signals cause the
1571 socket to be closed and recreated (see SIGNALS section for more
1572 information). Default value for <string> is %s. For example,
1573 consider the following action list definition:
1574 action=udpsock mysrv:514 <13>%.monstr %.mdaystr %.hmsstr myhost
1576 test: $0
1577 The above udpsock action sends a BSD syslog message to port
1579 514/udp of remote syslog server mysrv, where message priority is
1580 13 (corresponds to the "user" facility and "notice" level), name
1581 of the local host is "myhost", syslog tag is "test" and message
1582 text is the value if the $0 match variable.
1583 closeudp <host>:<port>
1585 Close the UDP socket for peer <host>:<port> that has been previ‐
1586 ously opened by the udpsock action.
1587 tcpsock <host>:<port> [<string>]
1589 String <string> is sent to the TCP port <port> of the host
1590 <host>. The timeout value given with the --socket-timeout op‐
1591 tion determines for how many seconds SEC will attempt to estab‐
1592 lish a connection to the remote peer. If the connection estab‐
1593 lishment does not succeed immediately, the tcpsock action buf‐
1594 fers <string> in memory for later sending to the remote peer.
1595 Note that the relevant TCP socket will not be closed after
1596 <string> has been transmitted, and the following tcpsock actions
1597 for the same peer will use an already existing socket. However,
1598 several signals cause the socket to be closed and recreated (see
1599 SIGNALS section for more information). Default value for
1600 <string> is %s. For example, consider the following action list
1601 definition:
1602 action=tcpsock grsrv:2003 ssh.login.failures %{num} %{u}%{.nl}
1604 The above tcpsock action sends the value of the action list
1606 variable %{num} to port 2003/tcp of the Graphite server grsrv,
1607 so that the value is recorded under metric path ssh.login.fail‐
1608 ures. Note that the %{u} action list variable evaluates to cur‐
1609 rent time in seconds since Epoch and is used for setting the
1610 timestamp for recorded value.
1611 closetcp <host>:<port>
1613 Close the TCP socket for peer <host>:<port> that has been previ‐
1614 ously opened by the tcpsock action.
1615 shellcmd <cmdline>
1617 Fork a process for executing command line <cmdline>. If <cmd‐
1618 line> contains shell metacharacters, <cmdline> is parsed by
1619 shell. If the --quoting option was specified and <cmdline> con‐
1620 tains %s variables, the value of %s is quoted with single quotes
1621 before substituting it into <cmdline>; if the value of %s con‐
1622 tains single quotes, they are masked with backslashes (e.g., abc
1623 is converted to 'abc' and aa'bb is converted to 'aa'\''bb').
1624 For additional information, see CHILD PROCESSES section. For
1625 example, consider the following action list definition:
1626 action=shellcmd (cat /tmp/report | mail root; rm -f /tmp/re‐
1628 port); \
1629 logonly Report sent to user root
1630 The shellcmd action of this action list executes the command
1632 line
1633 cat /tmp/report | mail root; rm -f /tmp/report
1635 and the logonly action logs the message "Report sent to user
1637 root". Since the command line contains a semicolon which is
1638 used for separating shellcmd and logonly actions, the command
1639 line is enclosed in parentheses.
1640 spawn <cmdline>
1642 Similar to the shellcmd action, except that each line from the
1643 standard output of <cmdline> becomes a synthetic event and will
1644 be treated like a line from input file (see the event action for
1645 more information). If the --intcontexts command line option is
1646 given, internal context _INTERNAL_EVENT is set up before each
1647 synthetic event is processed (see INTERNAL EVENTS AND CONTEXTS
1648 section for more information). For example, consider the fol‐
1649 lowing action list definition:
1650 action=spawn (cat /tmp/events; rm -f /tmp/events)
1652 The above spawn action will generate synthetic events from all
1654 lines in file /tmp/events and remove the file. Since the command
1655 line contains a semicolon which is used for separating actions,
1656 the command line is enclosed in parentheses.
1657 cspawn <name> <cmdline>
1659 Similar to the spawn action, except that if the --intcontexts
1660 command line option is given, internal context <name> is set up
1661 for each synthetic event.
1662 cmdexec <cmdline>
1664 Fork a process for executing command line <cmdline>. Unlike
1665 shellcmd action, <cmdline> is not parsed by shell, but split
1666 into arguments by using whitespace as a separator, and passed to
1667 execvp(3) for execution. Note that splitting into arguments is
1668 done when cmdexec action is loaded from the configuration file
1669 and parsed, not at runtime (e.g., if <cmdline> is /usr/lo‐
1670 cal/bin/mytool $1 $2, the values of $1 and $2 variables are re‐
1671 garded as single arguments even if the values contain white‐
1672 space). For additional information, see CHILD PROCESSES sec‐
1673 tion. For example, consider the following action list defini‐
1674 tion:
1675 action=cmdexec rm /tmp/report*
1677 The above cmdexec action will remove the file /tmp/report* with‐
1679 out treating * as a file pattern character that matches any
1680 string.
1681 spawnexec <cmdline>
1683 Similar to the cmdexec action, except that each line from the
1684 standard output of <cmdline> becomes a synthetic event and will
1685 be treated like a line from input file (see the event action for
1686 more information). If the --intcontexts command line option is
1687 given, internal context _INTERNAL_EVENT is set up before each
1688 synthetic event is processed (see INTERNAL EVENTS AND CONTEXTS
1689 section for more information).
1690 cspawnexec <name> <cmdline>
1692 Similar to the spawnexec action, except that if the --intcon‐
1693 texts command line option is given, internal context <name> is
1694 set up for each synthetic event.
1695 pipe '[<string>]' [<cmdline>]
1697 Fork a process for executing command line <cmdline>. If <cmd‐
1698 line> contains shell metacharacters, <cmdline> is parsed by
1699 shell. The string <string> with a terminating newline is writ‐
1700 ten to the standard input of <cmdline> (single quotes are used
1701 for disambiguating <string> from <cmdline>). If <string> con‐
1702 tains semicolons, <string> must be enclosed in parentheses
1703 (e.g., pipe '($1;$2)' /bin/cat). Default value for <string> is
1704 %s. If <cmdline> is omitted, <string> is written to standard
1705 output. For additional information, see CHILD PROCESSES sec‐
1706 tion. For example, consider the following action list defini‐
1707 tion:
1708 action=pipe 'Offending activities from host $1' /bin/mail
1710 root@localhost
1711 The above pipe action writes the line "Offending activities from
1713 host <hostname>" to the standard input of the /bin/mail root@lo‐
1714 calhost command which sends this line to root@localhost via e-
1715 mail (<hostname> is the value of the $1 match variable).
1716 pipeexec '[<string>]' [<cmdline>]
1718 Similar to the pipe action, except <cmdline> is not parsed by
1719 shell, but split into arguments by using whitespace as a separa‐
1720 tor, and passed to execvp(3) for execution. Note that splitting
1721 into arguments is done when pipeexec action is loaded from the
1722 configuration file and parsed, not at runtime (e.g., if <cmd‐
1723 line> is /usr/local/bin/mytool $1 $2, the values of $1 and $2
1724 variables are regarded as single arguments even if the values
1725 contain whitespace). For example, consider the following action
1726 list definition:
1727 action=pipeexec 'Offending activities from host $1' \
1729 /bin/mail -s SEC%{.sp}alert $2
1730 The above pipeexec action writes the line "Offending activities
1732 from host <hostname>" to the standard input of the /bin/mail -s
1733 <subject> <user> command which sends this line to <user> via e-
1734 mail with subject <subject> (<hostname> is the value of the $1
1735 match variable, while <user> is the value of the $2 match vari‐
1736 able). Note that since <subject> is defined as SEC%{.sp}alert
1737 and does not contain whitespace, it is treated as a single argu‐
1738 ment for the -s flag of the /bin/mail command. However, since
1739 <subject> contains the %.sp action list variable, the string
1740 "SEC alert" will be used for the e-mail subject at runtime.
1741 Also, if the value of the $2 match variable contains shell
1742 metacharacters, they will not be interpreted by the shell.
1743 create [<name> [<time> [<action list>] ] ]
1745 Create a context with the name <name>, lifetime of <time> sec‐
1746 onds, and empty event store. The <name> parameter may not con‐
1747 tain whitespace and defaults to %s. The <time> parameter must
1748 evaluate to an unsigned integer at runtime. Specifying 0 for
1749 <time> or omitting the value means infinite lifetime. If <ac‐
1750 tion list> is given, it will be executed when the context ex‐
1751 pires. If <action list> contains several actions, the list must
1752 be enclosed in parentheses. In <action list>, the internal con‐
1753 text name _THIS may be used for referring to the current context
1754 (see INTERNAL EVENTS AND CONTEXTS section for a detailed discus‐
1755 sion). If an already existing context is recreated with create,
1756 its remaining lifetime is set to <time> seconds, its action list
1757 is reinitialized, and its event store is emptied. For example,
1758 consider the following action list definition:
1759 action=write /var/log/test.log $0; create TIMER 3600 \
1761 ( logonly Closing /var/log/test.log; closef
1762 /var/log/test.log )
1763 The write action from the above action list appends the value of
1765 the $0 match variable to file /var/log/test.log, while the cre‐
1766 ate action creates the context TIMER which will exist for 3600
1767 seconds. Since this context is recreated at each write, the con‐
1768 text can expire only if the action list has not been executed
1769 for more than 3600 seconds (i.e., the action list has last up‐
1770 dated the file more than 1 hour ago). If that is the case, the
1771 action list
1772 logonly Closing /var/log/test.log; closef /var/log/test.log
1774 is executed which logs the message "Closing /var/log/test.log"
1776 with the logonly action and closes /var/log/test.log with the
1777 closef action. When the execution of this action list is com‐
1778 plete, the TIMER context is deleted.
1779 delete [<name>]
1781 Delete the context <name>. The <name> parameter may not contain
1782 whitespace and defaults to %s.
1783 obsolete [<name>]
1785 Similar to the delete action, except that the action list of the
1786 context <name> (if present) is executed before deletion.
1787 set <name> <time> [<action list>]
1789 Change settings for the context <name>. The creation time of the
1790 context is set to the current time, and the lifetime of the con‐
1791 text is set to <time> seconds. If the <action list> parameter
1792 is given, the context action list is set to <action list>, oth‐
1793 erwise the context action list is not changed. The <name> pa‐
1794 rameter may not contain whitespace and defaults to %s. The
1795 <time> parameter must evaluate to an unsigned integer or hyphen
1796 (-) at runtime. Specifying 0 for <time> means infinite life‐
1797 time. If <time> equals to -, the creation time and lifetime of
1798 the context are not changed. If <action list> contains several
1799 actions, the list must be enclosed in parentheses. In <action
1800 list>, the internal context name _THIS may be used for referring
1801 to the current context (see INTERNAL EVENTS AND CONTEXTS section
1802 for a detailed discussion). For example, consider the following
1803 action list definition:
1804 action=set C_$1 30 ( logonly Context C_$1 has expired )
1806 The above set action sets the context C_<suffix> to expire after
1808 30 seconds with a log message about expiration (<suffix> is the
1809 value of the $1 match variable).
1810 alias <name> [<alias>]
1812 Create an alias name <alias> for the context <name>. After cre‐
1813 ation, both <alias> and <name> will point to the same context
1814 data structure, and can thus be used interchangeably for refer‐
1815 ring to the context. The <name> and <alias> parameters may not
1816 contain whitespace, and <alias> defaults to %s. If the context
1817 <name> does not exist, the alias name is not created. If the
1818 delete action is called for one of the context names, the con‐
1819 text data structure is destroyed, and all context names (which
1820 are now pointers to unallocated memory) cease to exist. Also
1821 note that when the context expires, its action list is executed
1822 only once, no matter how many names the context has.
1823 unalias [<alias>]
1825 Drop an existing context name <alias>, so that it can no longer
1826 be used for referring to the given context. The <alias> parame‐
1827 ter may not contain whitespace and defaults to %s. If the name
1828 <alias> is the last reference to the context, the unalias action
1829 is identical to delete.
1830 add <name> [<string>]
1832 String <string> is appended to the end of the event store of the
1833 context <name>. The <name> parameter may not contain white‐
1834 space, and the <string> parameter defaults to %s. If the con‐
1835 text <name> does not exist, the context is created with an infi‐
1836 nite lifetime, empty action list and empty event store (as with
1837 create <name>) before adding the string to event store. If
1838 <string> is a multi-line string (i.e., it contains newlines), it
1839 is split into lines, and each line is appended to the event
1840 store separately. For example, consider the following action
1841 list definition:
1842 action=add EVENTS This is a test; add EVENTS This is a test2
1844 After the execution of this action list, the last two strings in
1846 the event store of the EVENTS context are "This is a test" and
1847 "This is a test2" (in that order).
1848 prepend <name> [<string>]
1850 Similar to the add action, except that the string <string> is
1851 prepended to the beginning of the event store of context <name>.
1852 For example, consider the following action list definition:
1853 action=prepend EVENTS This is a test; prepend EVENTS This is a
1855 test2
1856 After the execution of this action list, the first two strings
1858 in the event store of the EVENTS context are "This is a test2"
1859 and "This is a test" (in that order).
1860 fill <name> [<string>]
1862 Similar to the add action, except that the event store of the
1863 context <name> is emptied before <string> is added.
1864 report <name> [<cmdline>]
1866 Fork a process for executing command line <cmdline>. If <cmd‐
1867 line> contains shell metacharacters, <cmdline> is parsed by
1868 shell. Also, write strings from the event store of the context
1869 <name> to the standard input of <cmdline>. Strings are written
1870 in the order they appear in the event store, with a terminating
1871 newline appended to each string. If the context <name> does not
1872 exist or its event store is empty, <cmdline> is not executed.
1873 The <name> parameter may not contain whitespace, and if <cmd‐
1874 line> is omitted, strings are written to standard output. For
1875 additional information, see CHILD PROCESSES section. For exam‐
1876 ple, consider the following action list definition:
1877 action=create PID_$1 60 ( report PID_$1 /bin/mail root@localhost
1879 ); \
1880 add PID_$1 Beginning of the report
1881 The above action list creates the context PID_<suffix> with the
1883 lifetime of 60 seconds and sets the first string in the context
1884 event store to "Beginning of the report" (<suffix> is the value
1885 of the $1 match variable). When the context expires, all
1886 strings from the event store will be mailed to root@localhost.
1887 reportexec <name> [<cmdline>]
1889 Similar to the report action, except <cmdline> is not parsed by
1890 shell, but split into arguments by using whitespace as a separa‐
1891 tor, and passed to execvp(3) for execution. Note that splitting
1892 into arguments is done when reportexec action is loaded from the
1893 configuration file and parsed, not at runtime (e.g., if <cmd‐
1894 line> is /usr/local/bin/mytool $1 $2, the values of $1 and $2
1895 variables are regarded as single arguments even if the values
1896 contain whitespace).
1897 copy <name> %<var>
1899 Strings s1,...,sn from the event store of the context <name> are
1900 joined into a multi-line string "s1<NEWLINE>...<NEWLINE>sn", and
1901 this string is assigned to the action list variable %<var>. If
1902 the context <name> does not exist, the value of %<var> does not
1903 change.
1904 empty <name> [%<var>]
1906 Similar to the copy action, except that the event store of the
1907 context <name> will be emptied after the assignment. If %<var>
1908 is omitted, the content of the event store is dropped without an
1909 assignment.
1910 pop <name> %<var>
1912 Remove the last string from the event store of context <name>,
1913 and assign it to the action list variable %<var>. If the event
1914 store is empty, %<var> is set to empty string. If the context
1915 <name> does not exist, the value of %<var> does not change.
1916 shift <name> %<var>
1918 Remove the first string from the event store of context <name>,
1919 and assign it to the action list variable %<var>. If the event
1920 store is empty, %<var> is set to empty string. If the context
1921 <name> does not exist, the value of %<var> does not change.
1922 exists %<var> <name>
1924 If the context <name> exists, set the action list variable
1925 %<var> to 1, otherwise set %<var> to 0.
1926 getsize %<var> <name>
1928 Find the number of strings in the event store of context <name>,
1929 and assign this number to the action list variable %<var>. If
1930 the context <name> does not exist, %<var> is set to Perl unde‐
1931 fined value. For example, consider the following action list
1932 definition:
1933 action=fill EVENTS Event1; add EVENTS Event2; add EVENTS Event3;
1935 \
1936 pop EVENTS %temp1; shift EVENTS %temp2; getsize %size
1937 EVENTS
1938 This action list sets the %temp1 action list variable to Event3,
1940 %temp2 action list variable to Event1, and %size action list
1941 variable to 1.
1942 getaliases %<var> <name>
1944 Find all alias names for context <name>, join the names into a
1945 multi-line string "alias1<NEWLINE>...<NEWLINE>aliasn", and as‐
1946 sign this string to the action list variable %<var>. If the
1947 context <name> does not exist, the value of %<var> does not
1948 change.
1949 getltime %<var> <name>
1951 Find the lifetime of context <name>, and assign this number to
1952 the action list variable %<var>. If the context <name> does not
1953 exist, the value of %<var> does not change. For example, con‐
1954 sider the following action list definition:
1955 action=create TEST 10 ( getltime %time TEST; \
1957 logonly Context TEST with %time second lifetime has ex‐
1958 pired )
1959 The above create action configures the context TEST to log its
1961 lifetime when it expires.
1962 setltime <name> [<time>]
1964 Set the lifetime of context <name> to <time>. Specifying 0 for
1965 <time> or omitting the value means infinite lifetime. Note that
1966 unlike the set action, setltime does not adjust the context cre‐
1967 ation time. For example, if context TEST has been created at
1968 12:01:00 with the lifetime of 60 seconds, then after invoking
1969 setltime TEST 30 at 12:01:20 the context would exist until
1970 12:01:30, while invoking setltime TEST 10 would immediately ex‐
1971 pire the context.
1972 getctime %<var> <name>
1974 Find the creation time of context <name>, and assign this time‐
1975 stamp to the action list variable %<var>. The value assigned to
1976 %<var> is measured in seconds since Epoch (as reported by the
1977 time(2) system call). If the context <name> does not exist, the
1978 value of %<var> does not change.
1979 setctime <time> <name>
1981 Set the creation time of context <name> to <time>. The <time>
1982 parameter must evaluate to seconds since Epoch (as reported by
1983 the time(2) system call), and must reflect a time moment between
1984 the previous creation time and the current time (both endpoints
1985 included). For example, if context TEST has been created at
1986 12:43:00 with the lifetime of 60 seconds, then after invoking
1987 setctime %u TEST at 12:43:25 the context would exist until
1988 12:44:25 (the %u action list variable evaluates to current time
1989 in seconds since Epoch).
1990 event [<time>] [<string>]
1992 After <time> seconds, create a synthetic event <string>. If
1993 <string> is a multi-line string (i.e., it contains newlines), it
1994 is split into lines, and from each line a separate synthetic
1995 event is created. SEC will treat each synthetic event like a
1996 line from an input file -- the event will be matched against
1997 rules and it might trigger further actions. If the --intcon‐
1998 texts command line option is given, internal context _INTER‐
1999 NAL_EVENT is set up for synthetic event(s) (see INTERNAL EVENTS
2000 AND CONTEXTS section for more information). The <time> parame‐
2001 ter is an integer constant. Specifying 0 for <time> or omitting
2002 the value means "now". Default value for <string> is %s. For
2003 example, consider the following action list definition:
2004 action=copy EVENTS %events; event %events
2006 The above action list will create a synthetic event from each
2008 string in the event store of the EVENTS context.
2009 tevent <time> [<string>]
2011 Similar to the event action, except that the <time> parameter
2012 may contain variables and must evaluate to an unsigned integer
2013 at runtime.
2014 cevent <name> <time> [<string>]
2016 Similar to the tevent action, except that if the --intcontexts
2017 command line option is given, internal context <name> is set up
2018 for synthetic event(s).
2019 reset [<offset>] [<string>]
2021 Terminate event correlation operation(s) with the operation de‐
2022 scription string <string>. Note that the reset action works only
2023 for operations started from the same configuration file. The
2024 <offset> parameter is used to refer to a specific rule in the
2025 configuration file. If <offset> is given, the operation started
2026 by the given rule is terminated (if it exists). If <offset> is
2027 an unsigned integer N, it refers to the N-th rule in the config‐
2028 uration file. If <offset> is 0, it refers to the current rule.
2029 If <offset> begins with the plus (+) or minus (-) sign, it spec‐
2030 ifies an offset from the current rule (e.g., -1 denotes the pre‐
2031 vious and +1 the next rule). Note that since Options rules are
2032 only processed when configuration files are loaded and they are
2033 not applied at runtime, Options rules are excluded when calcu‐
2034 lating <offset>. If <offset> is not given, SEC checks for each
2035 rule from the current configuration file if an operation with
2036 <string> has been started by this rule, and the operation is
2037 terminated if it exists. Default value for <string> is %s. For
2038 additional information, see EVENT CORRELATION OPERATIONS sec‐
2039 tion. For example, consider the following action list defini‐
2040 tion:
2041 action=reset -1 Ten login failures observed from $1; reset 0
2043 If the above action list is executed by an event correlation op‐
2045 eration, the first reset action will terminate another event
2046 correlation operation which has been started by the previous
2047 rule and has the operation description string "Ten login fail‐
2048 ures observed from <host>" (<host> is the value of the $1 match
2049 variable). The second reset action will terminate the calling
2050 operation itself.
2051 getwpos %<var> <offset> [<string>]
2053 Find the beginning of the event correlation window for an event
2054 correlation operation, and set the action list variable %<var>
2055 to this timestamp. The value assigned to %<var> is measured in
2056 seconds since Epoch (as reported by the time(2) system call). As
2057 with the reset action, the event correlation operation is iden‐
2058 tified by the operation description string <string> and the rule
2059 offset <offset>. If the operation does not exist, the value of
2060 %<var> does not change. Default value for <string> is %s. For
2061 additional information, see EVENT CORRELATION OPERATIONS sec‐
2062 tion. For example, consider the following action list defini‐
2063 tion:
2064 action=getwpos %pos -1 Ten login failures observed from $1
2066 The above getwpos action will find the beginning of the event
2068 correlation window for an event correlation operation which has
2069 been started by the previous rule and has the operation descrip‐
2070 tion string "Ten login failures observed from <host>" (<host> is
2071 the value of the $1 match variable). If the event correlation
2072 window begins at April 6 08:03:53 2018 UTC, the value 1523001833
2073 will be assigned to the %pos action list variable.
2074 setwpos <time> <offset> [<string>]
2076 Set the beginning of the event correlation window to <time> for
2077 an event correlation operation (if it exists). The <time> param‐
2078 eter must evaluate to seconds since Epoch (as reported by the
2079 time(2) system call), and must reflect a time moment between the
2080 previous window position and the current time (both endpoints
2081 included). As with the reset action, the event correlation oper‐
2082 ation is identified by the operation description string <string>
2083 and the rule offset <offset>. Default value for <string> is %s.
2084 For additional information, see EVENT CORRELATION OPERATIONS
2085 section.
2086 assign %<var> [<string>]
2088 Assign string <string> to the action list variable %<var>. De‐
2089 fault value for <string> is %s.
2090 assignsq %<var> [<string>]
2092 Similar to the assign action, except that <string> is quoted
2093 with single quotes before assigning it to %<var>. If <string>
2094 contains single quotes, they are masked with backslashes (e.g.,
2095 if the match variable $1 holds the value abc'123'xyz, the action
2096 assignsq %myvar $1 assigns the value 'abc'\''123'\''xyz' to the
2097 action list variable %myvar). This action is useful for dis‐
2098 abling shell interpretation for the values of action list vari‐
2099 ables that appear in command lines executed by SEC. Default
2100 value for <string> is %s.
2101 free %<var>
2103 Unset the action list variable %<var>.
2104 eval %<var> <code>
2106 The parameter <code> is a Perl miniprogram that is compiled and
2107 executed by calling the Perl eval() function in the Perl list
2108 context. If the miniprogram returns a single value, it is as‐
2109 signed to the action list variable %<var>. If the miniprogram
2110 returns several values s1,...,sn, they are joined into a multi-
2111 line string "s1<NEWLINE>...<NEWLINE>sn", and this string is as‐
2112 signed to %<var>. If no value is returned, %<var> is set to
2113 Perl undefined value. If eval() fails, the value of %<var> does
2114 not change. Since most Perl programs contain semicolons which
2115 are also employed by SEC as action separators, it is recommended
2116 to enclose the <code> parameter in parentheses, in order to mask
2117 the semicolons in <code>. For additional information, see PERL
2118 INTEGRATION section. For example, consider the following action
2119 list definition:
2120 action=assign %div Division error; eval %div ( $1 / $2 )
2122 The assign action sets the %div action list variable to the
2124 string "Division error", while the eval action substitutes the
2125 values of $1 and $2 match variables into the string "$1 / $2".
2126 Resulting string is treated as Perl code which is first compiled
2127 and then executed. For instance, if the values of $1 and $2 are
2128 12 and 4, respectively, the following Perl code is compiled: 12
2129 / 4. Since executing this code yields 3, the eval action assigns
2130 this value to the %div action list variable. Also, if $2 has no
2131 value or its value is 0, resulting code leads to compilation or
2132 execution error, and %div retains its previous value "Division
2133 error".
2134 call %<var> %<ref> [<paramlist>]
2136 Call the precompiled Perl function referenced by the action list
2137 variable %<ref>, and assign the result to the action list vari‐
2138 able %<var>. The %<ref> parameter must be a code reference that
2139 has been previously created with the eval action. The <param‐
2140 list> parameter (if given) is a string which specifies parame‐
2141 ters for the function. The parameters must be separated by
2142 whitespace in the <paramlist> string. If the function returns a
2143 single value, it is assigned to %<var>. If the function returns
2144 several values s1,...,sn, they are joined into a multi-line
2145 string "s1<NEWLINE>...<NEWLINE>sn", and this string is assigned
2146 to %<var>. If no value is returned, %<var> is set to Perl unde‐
2147 fined value. If the function encounters a fatal runtime error
2148 or %<ref> is not a code reference, the value of %<var> does not
2149 change. For additional information, see PERL INTEGRATION sec‐
2150 tion. For example, consider the following action list defini‐
2151 tion:
2152 action=eval %func ( sub { return $_[0] + $_[1] } ); \
2154 call %sum %func $1 $2
2155 Since the Perl code provided to eval action is a definition of
2157 an anonymous function, its compilation yields a code reference
2158 which gets assigned to the %func action list variable (the func‐
2159 tion returns the sum of its two input parameters). The call ac‐
2160 tion will invoke previously compiled function, using the values
2161 of $1 and $2 match variables as function parameters, and assign‐
2162 ing function return value to the %sum action list variable.
2163 Therefore, if the values of $1 and $2 are 2 and 3, respectively,
2164 %sum is set to 5.
2165 lcall %<var> [<paramlist>] -> <code>
2167 lcall %<var> [<paramlist>] :> <code>
2169 Call the precompiled Perl function <code> and assign the result
2170 to the action list variable %<var>. The <code> parameter must
2171 be a valid Perl anonymous function definition that is compiled
2172 at SEC startup with the Perl eval() function, and eval() must
2173 return a code reference. The <paramlist> parameter (if given)
2174 is a string which specifies parameters for the function. The pa‐
2175 rameters must be separated by whitespace in the <paramlist>
2176 string. If <paramlist> is followed by -> operator, parameters
2177 are passed to function as Perl scalar values. If <paramlist> is
2178 followed by :> operator, it is assumed that each parameter is a
2179 name of an entry in the pattern match cache. If an entry with
2180 the given name does not exist, Perl undefined value is passed to
2181 the function. If an entry with the given name exists, a refer‐
2182 ence to the entry is passed to the function. Internally, each
2183 pattern match cache entry is implemented as a Perl hash which
2184 contains all match variables for the given entry. If the func‐
2185 tion returns a single value, it is assigned to %<var>. If the
2186 function returns several values s1,...,sn, they are joined into
2187 a multi-line string "s1<NEWLINE>...<NEWLINE>sn", and this string
2188 is assigned to %<var>. If no value is returned, %<var> is set to
2189 Perl undefined value. If the function encounters a fatal run‐
2190 time error, the value of %<var> does not change. Since most
2191 Perl functions contain semicolons which are also employed by SEC
2192 as action separators, it is recommended to enclose the <code>
2193 parameter in parentheses, in order to mask the semicolons in
2194 <code>. For additional information, see PERL INTEGRATION sec‐
2195 tion. For example, consider the following action list defini‐
2196 tion:
2197 action=lcall %len $1 -> ( sub { return length($_[0]) } )
2199 The above lcall action will take the value of the $1 match vari‐
2201 able and find its length in characters, assigning the length to
2202 the %len action list variable. Note that the function for find‐
2203 ing the length is compiled when SEC loads its configuration, and
2204 all invocations of lcall will execute already compiled code. As
2205 another example, consider the following action list definition:
2206 action=lcall %o SSH :> ( sub { $_[0]->{"failure"} = 1 } )
2208 The above lcall action will assign 1 to the $+{failure} match
2210 variable that has been cached under the SSH entry in the pattern
2211 match cache (variable will be created if it did not exist previ‐
2212 ously).
2213 rewrite <lnum> [<string>]
2215 Replace last <lnum> lines in the input buffer with string
2216 <string>. If the --nojointbuf option was specified and the ac‐
2217 tion is triggered by a matching event, the action modifies the
2218 buffer which holds this event. If the --nojointbuf option was
2219 specified and the action is triggered by the system clock (e.g.,
2220 the action is executed from the Calendar rule), the action modi‐
2221 fies the buffer which holds the last already processed event.
2222 With the --jointbuf option, the content of the joint input buf‐
2223 fer is rewritten. The <lnum> parameter must evaluate to an un‐
2224 signed integer at runtime. If <lnum> evaluates to 0, <lnum> is
2225 reset to the number of lines in <string>. If the value of
2226 <lnum> is greater than the buffer size N, <lnum> is reset to N.
2227 If <string> contains less than <lnum> lines, <string> will be
2228 padded with leading empty lines. If <string> contains more than
2229 <lnum> lines, only leading <lnum> lines from <string> are writ‐
2230 ten into the buffer. Default value for <string> is %s. For ad‐
2231 ditional information, see INPUT PROCESSING AND TIMING section.
2232 addinput <filename> [<offset> [<name>] ]
2234 File <filename> is added to the list of input files and opened,
2235 so that processing starts from file offset <offset>. The <off‐
2236 set> parameter must evaluate to unsigned integer or - (EOF) at
2237 runtime. If <offset> is not specified, it defaults to - (i.e.,
2238 processing starts from the end of file). If opening the file
2239 fails (e.g., the file does not exist), it will stay in the list
2240 of input files (e.g., with the --reopen-timeout command line op‐
2241 tion, SEC will attempt to reopen the file). The <name> parame‐
2242 ter defines the internal context which should be used for <file‐
2243 name> if the --intcontexts command line option is given (if
2244 <name> is omitted but --intcontexts command line option is
2245 present, default internal context will be used). See INTERNAL
2246 EVENTS AND CONTEXTS section for more information. For example,
2247 consider the following action list definition:
2248 action=addinput /var/log/test-%{.year}%{.mon}%{.mday} 0 TESTFILE
2250 The above addinput action adds the file /var/log/test-YYYYMMDD
2252 to the list of input files, where YYYYMMDD reflects the current
2253 date. The addinput action will also attempt to open the file,
2254 and if open succeeds, file will be processed from the beginning.
2255 Also, the internal context TESTFILE will be used for all events
2256 read from the file.
2257 dropinput <filename>
2259 File <filename> is dropped from the list of input files and
2260 closed (if currently open). Note that dropinput action can only
2261 be used for input files which have been previously set up with
2262 addinput action.
2263 sigemul <signal>
2265 Emulates the arrival of signal <signal> and triggers its han‐
2266 dler. The <signal> parameter must evaluate to one of the fol‐
2267 lowing strings: HUP, ABRT, USR1, USR2, INT, or TERM. For exam‐
2268 ple, the action sigemul USR1 triggers the generation of SEC dump
2269 file. See the SIGNALS section for detailed information on sig‐
2270 nals that are handled by SEC.
2271 varset %<var> <entry>
2273 If the pattern match cache entry <entry> exists, set the action
2274 list variable %<var> to 1, otherwise set %<var> to 0. For exam‐
2275 ple, if pattern match cache contains the entry with the name SSH
2276 but not the entry with the name NTP, the action varset %ssh SSH
2277 will set the %ssh action list variable to 1, while the action
2278 varset %ntp NTP will set the %ntp action list variable to 0.
2279 if %<var> ( <action list> ) [ else ( <action list2> ) ]
2281 If the action list variable %<var> evaluates true in the Perl
2282 boolean context (i.e., it holds a defined value which is neither
2283 0 nor empty string), execute the action list <action list>. If
2284 the second action list <action list2> is given with the optional
2285 else-statement, it is executed if %<var> either does not exist
2286 or evaluates false (i.e., %<var> holds 0, empty string or Perl
2287 undefined value). For example, consider the following action
2288 list definition:
2289 action=exists %present REPORT; if %present \
2291 ( report REPORT /bin/mail root@localhost; delete REPORT
2292 ) \
2293 else ( logonly Nothing to report )
2294 If the REPORT context exists, its event store is mailed to
2296 root@localhost and the context is deleted, otherwise the message
2297 "Nothing to report" is logged.
2298 while %<var> ( <action list> )
2300 Execute the action list <action list> repeatedly as long as the
2301 action list variable %<var> evaluates true in the Perl boolean
2302 context (i.e., it holds a defined value which is neither 0 nor
2303 empty string). For example, consider the following action list
2304 definition:
2305 action=create REVERSE; getsize %n TEST; \
2307 while %n ( pop TEST %e; add REVERSE %e; getsize %n TEST
2308 ); \
2309 copy REVERSE %events; fill TEST %events
2310 This action list reverses the order of strings in the event
2312 store of the context TEST, using the context REVERSE as a tempo‐
2313 rary storage. During each iteration of the while-loop, the last
2314 string in the event store of TEST is removed with the pop action
2315 and appended to the event store of REVERSE with the add action.
2316 The loop terminates when all strings have been removed from the
2317 event store of TEST (i.e., the getsize action reports 0 for
2318 event store size). Finally, the event store of REVERSE is as‐
2319 signed to the %events action list variable with the copy action,
2320 and the fill action is used for overwriting the event store of
2321 TEST with the value of %events.
2322 break If used inside a while-loop, terminates its execution; otherwise
2324 terminates the execution of the entire action list.
2325 continue
2327 If used inside a while-loop, starts the next iteration of the
2328 loop; otherwise terminates the execution of the entire action
2329 list.
2330 Examples:
2332 Follow the /var/log/trapd.log file and feed to SEC input all lines that
2334 are appended to the file:
2335 action=spawn /bin/tail -f /var/log/trapd.log
2337 Mail the timestamp and the value of the $0 variable to the local root:
2339 action=pipe '%t: $0' /bin/mail -s "alert message" root@localhost
2341 Add the value of the $0 variable to the event store of the context
2343 ftp_<the value of $1>, and set the context to expire after 30 minutes.
2344 When the context expires, its event store will be mailed to the local
2345 root:
2346 action=add ftp_$1 $0; \
2348 set ftp_$1 1800 (report ftp_$1 /bin/mail root@localhost)
2349 Create a subroutine for weeding out comment lines from the input list,
2351 and use this subroutine for removing comment lines from the event store
2352 of the context C1:
2353 action=eval %funcptr ( sub { my(@buf) = split(/\n/, $_[0]); \
2355 my(@ret) = grep(!/^#/, @buf); return @ret; } ); \
2356 copy C1 %in; call %out %funcptr %in; fill C1 %out
2357 The following action list achieves the same goal as the previous action
2359 list with while and if actions:
2360 action=getsize %size C1; while %size ( shift C1 %event; \
2362 lcall %nocomment %event -> ( sub { $_[0] !~ /^#/ } ); \
2363 if %nocomment ( add C1 %event ); \
2364 lcall %size %size -> ( sub { $_[0]-1; } ) )
2365
2367 As already noted, SEC context expressions and action lists may contain
2368 parentheses which are used for grouping and masking purposes. When SEC
2369 parses its configuration, it checks whether parentheses in context ex‐
2370 pressions and action lists are balanced (i.e., whether each parenthesis
2371 has a counterpart), since unbalanced parentheses introduce ambiguity.
2372 This can cause SEC to reject some legitimate constructs, e.g.,
2373 action=eval %o (print ")";)
2375 is considered an invalid action list (however, note that
2377 action=eval %o (print "()";)
2378 would be passed by SEC, since now parentheses are balanced). In order
2379 to avoid such parsing errors, each parenthesis without a counterpart
2380 must be masked with a backslash (the backslash will be removed by SEC
2381 during configuration file parsing). For example, the above action could
2382 be written as
2383 action=eval %o (print "\)";)
2385
2387 This section provides a detailed discussion of SEC rule types.
2388 SINGLE RULE
2390 The Single rule supports the following fields. Note that match vari‐
2391 ables may be used in context, desc, and action fields.
2392 type fixed to Single (value is case insensitive, so single or sIngLe
2394 can be used instead).
2395 continue (optional)
2397 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2398 bel>, values are case insensitive).
2399 ptype pattern type (value is case insensitive).
2401 pattern
2403 pattern.
2404 varmap (optional)
2406 variable map.
2407 context (optional)
2409 context expression.
2410 desc operation description string.
2412 action action list.
2414 rem (optional, may appear more than once)
2416 remarks and comments.
2417 The Single rule immediately executes an action list when an event has
2419 matched the rule. An event matches the rule if the pattern matches the
2420 event and the context expression (if given) evaluates TRUE.
2421 Note that the Single rule does not start event correlation operations,
2423 and the desc field is merely used for setting the %s action list vari‐
2424 able.
2425 Examples:
2427 type=single
2429 continue=takenext
2430 ptype=regexp
2431 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session opened
2432 desc=ftp session opened for ristov2 pid $1
2433 action=create ftp_$1
2434 type=single
2436 continue=takenext
2437 ptype=regexp
2438 pattern=ftpd\[(\d+)\]:
2439 context=ftp_$1
2440 desc=ftp session event for ristov2 pid $1
2441 action=add ftp_$1 $0; set ftp_$1 1800 \
2442 (report ftp_$1 /bin/mail root@localhost)
2443 type=single
2445 ptype=regexp
2446 pattern=ftpd\[(\d+)\]: \S+ \(ristov2.*FTP session closed
2447 desc=ftp session closed for ristov2 pid $1
2448 action=report ftp_$1 /bin/mail root@localhost; \
2449 delete ftp_$1
2450 This ruleset is created for monitoring the ftpd log file. The first
2452 rule creates the context ftp_<pid> when someone connects from host ris‐
2453 tov2 over FTP and establishes a new ftp session (the session is identi‐
2454 fied by the PID of the process which has been created for handling this
2455 session). The second rule adds all further log file lines for the ses‐
2456 sion <pid> to the event store of the context ftp_<pid> (before adding a
2457 line, the rule checks if the context exists). After adding a line, the
2458 rule extends context's lifetime for 30 minutes and sets the action list
2459 that will be executed when the context expires. The third rule mails
2460 collected log file lines to root@localhost when the session <pid> is
2461 closed. Collected lines will also be mailed when the session <pid> has
2462 been inactive for 30 minutes (no log file lines observed for that ses‐
2463 sion).
2464 Note that the log file line that has matched the first rule is also
2466 matched against the second rule (since the first rule has the continue
2467 field set to TakeNext). Since the second rule always matches this
2468 line, it will become the first line in the event store of ftp_<pid>.
2469 The second rule has also its continue field set to TakeNext, since oth‐
2470 erwise no log file lines would reach the third rule.
2471 SINGLEWITHSCRIPT RULE
2473 The SingleWithScript rule supports the following fields. Note that
2474 match variables may be used in context, script, desc, action, and ac‐
2475 tion2 fields.
2476 type fixed to SingleWithScript (value is case insensitive).
2478 continue (optional)
2480 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2481 bel>, values are case insensitive).
2482 ptype pattern type (value is case insensitive).
2484 pattern
2486 pattern.
2487 varmap (optional)
2489 variable map.
2490 context (optional)
2492 context expression.
2493 script command line of external program.
2495 shell (optional)
2497 Yes or No (values are case insensitive, default is Yes).
2498 desc operation description string.
2500 action action list.
2502 action2 (optional)
2504 action list.
2505 rem (optional, may appear more than once)
2507 remarks and comments.
2508 The SingleWithScript rule forks a process for executing an external
2510 program when an event has matched the rule. The command line of the
2511 external program is defined by the script field.
2512 If the shell field is set to Yes (this is the default), the command
2514 line of the external program will be parsed by shell if the command
2515 line contains shell metacharacters. If the shell field is set to No,
2516 command line is not parsed by shell, but split into arguments by using
2517 whitespace as a separator, and passed to execvp(3) for execution. Note
2518 that splitting into arguments is done when command line is loaded from
2519 the configuration file and parsed, not at runtime (e.g., if command
2520 line is /usr/local/bin/mytool $1 $2, the values of $1 and $2 variables
2521 are regarded as single arguments even if the values contain white‐
2522 space).
2523 The names of all currently existing contexts are written to the stan‐
2525 dard input of the program. After the program has been forked, the rule
2526 matching continues immediately, and the program status will be checked
2527 periodically until the program exits. If the program returns 0 exit
2528 status, the action list defined by the action field is executed; other‐
2529 wise the action list defined by the action2 field is executed (if
2530 given).
2531 Note that the SingleWithScript rule does not start event correlation
2533 operations, and the desc field is merely used for setting the %s action
2534 list variable.
2535 Examples:
2537 type=SingleWithScript
2539 ptype=RegExp
2540 pattern=interface ([\d.]+) down
2541 script=/bin/ping -c 3 -q $1
2542 desc=Check if $1 responds to ping
2543 action=logonly Interface $1 reported down, but is pingable
2544 action2=pipe '%t: Interface $1 is down' /bin/mail root@localhost
2545 When "interface <ipaddress> down" line appears in input, the rule
2547 checks if <ipaddress> responds to ping. If <ipaddress> is pingable, the
2548 message "Interface <ipaddress> reported down, but is pingable" is
2549 logged; otherwise an e-mail warning containing a human-readable time‐
2550 stamp is sent to root@localhost.
2551 SINGLEWITHSUPPRESS RULE
2553 The SingleWithSuppress rule supports the following fields. Note that
2554 match variables may be used in context, desc, and action fields.
2555 type fixed to SingleWithSuppress (value is case insensitive).
2557 continue (optional)
2559 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2560 bel>, values are case insensitive).
2561 ptype pattern type (value is case insensitive).
2563 pattern
2565 pattern.
2566 varmap (optional)
2568 variable map.
2569 context (optional)
2571 context expression.
2572 desc operation description string.
2574 action action list.
2576 window event correlation window size (value is an integer constant).
2578 rem (optional, may appear more than once)
2580 remarks and comments.
2581 The SingleWithSuppress rule runs event correlation operations for fil‐
2583 tering repeated instances of the same event during T seconds. The value
2584 of T is defined by the window field.
2585 When an event has matched the rule, SEC evaluates the operation de‐
2587 scription string given with the desc field. If the operation for the
2588 given string and rule does not exist, SEC will create it with the life‐
2589 time of T seconds, and the operation immediately executes an action
2590 list. If the operation exists, it consumes the matching event without
2591 any action.
2592 Examples:
2594 type=SingleWithSuppress
2596 ptype=RegExp
2597 pattern=(\S+): [fF]ile system full
2598 desc=File system $1 full
2599 action=pipe '%t: %s' /bin/mail root@localhost
2600 window=900
2601 This rule runs event correlation operations for processing "file system
2603 full" syslog messages, e.g.,
2604 Dec 16 14:26:09 test ufs: [ID 845546 kern.notice] NOTICE: alloc: /var:
2606 file system full
2607 When the first message for a file system is observed, an operation is
2609 created which sends an e-mail warning about this file system to
2610 root@localhost. The operation will then run for 900 seconds and
2611 silently consume further messages for the *same* file system. However,
2612 if a message for a different file system is observed, another operation
2613 will be started which sends a warning to root@localhost again (since
2614 the desc field contains the $1 match variable which evaluates to the
2615 file system name).
2616 PAIR RULE
2618 The Pair rule supports the following fields. Note that match variables
2619 may be used in context, desc, action, pattern2, context2, desc2, and
2620 action2 fields.
2621 type fixed to Pair (value is case insensitive).
2623 continue (optional)
2625 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2626 bel>, values are case insensitive). Specifies the point-of-con‐
2627 tinue after a match by pattern and context.
2628 ptype pattern type for pattern (value is case insensitive).
2630 pattern
2632 pattern.
2633 varmap (optional)
2635 variable map for pattern.
2636 context (optional)
2638 context expression, evaluated together with pattern.
2639 desc operation description string.
2641 action action list.
2643 continue2 (optional)
2645 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2646 bel>, values are case insensitive). Specifies the point-of-con‐
2647 tinue after a match by pattern2 and context2.
2648 ptype2 pattern type for pattern2 (value is case insensitive).
2650 pattern2
2652 pattern.
2653 varmap2 (optional)
2655 variable map for pattern2.
2656 context2 (optional)
2658 context expression, evaluated together with pattern2.
2659 desc2 format string that sets the %s variable for action2.
2661 action2
2663 action list.
2664 window (optional)
2666 event correlation window size (value is an integer constant).
2667 rem (optional, may appear more than once)
2669 remarks and comments.
2670 The Pair rule runs event correlation operations for processing event
2672 pairs during T seconds. The value of T is defined by the window field.
2673 Default value is 0 which means infinity.
2674 When an event has matched the conditions defined by the pattern and
2676 context field, SEC evaluates the operation description string given
2677 with the desc field. If the operation for the given string and rule
2678 exists, it consumes the matching event without any action. If the oper‐
2679 ation does not exist, SEC will create it with the lifetime of T sec‐
2680 onds, and the operation immediately executes an action list defined by
2681 the action field. SEC will also copy the match conditions given with
2682 the pattern2 and context2 field into the operation, and substitute
2683 match variables with their values in copied conditions.
2684 If the event does not match conditions defined by the pattern and con‐
2686 text field, SEC will check the match conditions of all operations
2687 started by the given rule. Each matching operation executes the action
2688 list given with the action2 field and finishes.
2689 If match variables are set when the operation matches an event, they
2691 are made available as $-prefixed match variables in context2, desc2,
2692 and action2 fields of the rule definition. For example, if pattern2
2693 field is a regular expression, then $1 in the desc2 field is set by
2694 pattern2. In order to access match variables set by pattern, %-pre‐
2695 fixed match variables have to be used in context2, desc2, and action2
2696 fields. For example, if pattern and pattern2 are regular expressions,
2697 then %1 in the desc2 field refers to the value set by the first capture
2698 group in pattern (i.e., it has the same value as $1 in the desc field).
2699 Examples:
2701 type=Pair
2703 ptype=RegExp
2704 pattern=kernel: nfs: server (\S+) not responding, still trying
2705 desc=Server $1 is not responding
2706 action=pipe '%t: %s' /bin/mail root@localhost
2707 ptype2=SubStr
2708 pattern2=kernel: nfs: server $1 OK
2709 desc2=Server $1 is responding again
2710 action2=logonly
2711 window=3600
2712 This rule runs event correlation operations for processing NFS "server
2714 not responding" and "server OK" syslog messages, e.g.,
2715 Dec 18 22:39:48 test kernel: nfs: server box1 not responding, still
2717 trying
2718 Dec 18 22:42:27 test kernel: nfs: server box1 OK
2719 When the "server not responding" message for an NFS server is observed,
2721 an operation is created for this server which sends an e-mail warning
2722 about the server to root@localhost. The operation will then run for
2723 3600 seconds and silently consume further "server not responding" mes‐
2724 sages for the same server. If this operation observes "server OK" mes‐
2725 sage for the *same* server, it will log the message "Server <server‐
2726 name> is responding again" and finish.
2727 For example, if SEC observes the following event at 22:39:48
2729 Dec 18 22:39:48 test kernel: nfs: server box1 not responding, still
2731 trying
2732 an event correlation operation is created for server box1 which issues
2734 an e-mail warning about this server immediately. After that, the opera‐
2735 tion will run for 3600 seconds (until 23:39:48), waiting for an event
2736 which would contain the substring "kernel: nfs: server box1 OK" (be‐
2737 cause the pattern2 field contains the $1 match variable which evaluates
2738 to the server name).
2739 If any further error messages appear for server box1 during the 3600
2741 second lifetime of the operation, e.g.,
2742 Dec 18 22:40:28 test kernel: nfs: server box1 not responding, still
2744 trying
2745 Dec 18 22:41:09 test kernel: nfs: server box1 not responding, still
2746 trying
2747 these messages will be silently consumed by the operation. If before
2749 its expiration the operation observes an event which contains the sub‐
2750 string "kernel: nfs: server box1 OK", e.g.,
2751 Dec 18 22:42:27 test kernel: nfs: server box1 OK
2753 the operation will log the message "Server box1 is responding again"
2755 and terminate immediately. If no such message appears during the 3600
2756 second lifetime of the operation, the operation will expire without
2757 taking any action. Please note that if the window field would be either
2758 removed from the rule definition or set to 0, the operation would never
2759 silently expire, but would terminate only after observing an event
2760 which contains the substring "kernel: nfs: server box1 OK".
2761 If the above rule is modified in the following way
2763 type=Pair
2765 ptype=RegExp
2766 pattern=^([[:alnum:]: ]+) \S+ kernel: nfs: server (\S+) not responding,
2767 still trying
2768 desc=Server $2 is not responding
2769 action=logonly
2770 ptype2=RegExp
2771 pattern2=^([[:alnum:]: ]+) \S+ kernel: nfs: server $2 OK
2772 desc2=Server %2 was not accessible from %1 to $1
2773 action2=pipe '%s' /bin/mail root@localhost
2774 window=86400
2775 this rule will run event correlation operations which report NFS server
2777 downtime to root@localhost via e-mail, provided that downtime does not
2778 exceed 24 hours (86400 seconds).
2779 For example, if SEC observes the following event
2781 Dec 18 23:01:17 test kernel: nfs: server box.test not responding, still
2783 trying
2784 then the rule matches this event, sets $1 match variable to "Dec 18
2786 23:01:17" and $2 to "box.test", and creates an event correlation opera‐
2787 tion for server box.test. This operation will start its work by log‐
2788 ging the message "Server box.test is not responding", and will then run
2789 for 86400 seconds, waiting for an event which would match the regular
2790 expression
2791 ^([[:alnum:]: ]+) \S+ kernel: nfs: server box\.test OK
2793 Note that this expression was created from the regular expression tem‐
2795 plate in the pattern2 field by substituting the match variable $2 with
2796 its value. However, since the string "box.test" contains the dot (.)
2797 character which is a regular expression metacharacter, the dot is
2798 masked with the backslash in the regular expression.
2799 Suppose SEC will then observe the event
2801 Dec 18 23:09:54 test kernel: nfs: server box.test OK
2803 This event matches the above regular expression which is used by the
2805 operation running for server box.test. Also, the regular expression
2806 match sets the $1 variable to "Dec 18 23:09:54" and unsets the $2 vari‐
2807 able. In order to refer to their original values when the operation was
2808 created, %1 and %2 match variables have to be used in the desc2 field
2809 (%1 equals to "Dec 18 23:01:17" and %2 equals to "box.test"). There‐
2810 fore, the operation will send the e-mail message "Server box.test was
2811 not accessible from Dec 18 23:01:17 to Dec 18 23:09:54" to root@local‐
2812 host, and will terminate immediately.
2813 PAIRWITHWINDOW RULE
2815 The PairWithWindow rule supports the following fields. Note that match
2816 variables may be used in context, desc, action, pattern2, context2,
2817 desc2, and action2 fields.
2818 type fixed to PairWithWindow (value is case insensitive).
2820 continue (optional)
2822 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2823 bel>, values are case insensitive). Specifies the point-of-con‐
2824 tinue after a match by pattern and context.
2825 ptype pattern type for pattern (value is case insensitive).
2827 pattern
2829 pattern.
2830 varmap (optional)
2832 variable map for pattern.
2833 context (optional)
2835 context expression, evaluated together with pattern.
2836 desc operation description string.
2838 action action list.
2840 continue2 (optional)
2842 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2843 bel>, values are case insensitive). Specifies the point-of-con‐
2844 tinue after a match by pattern2 and context2.
2845 ptype2 pattern type for pattern2 (value is case insensitive).
2847 pattern2
2849 pattern.
2850 varmap2 (optional)
2852 variable map for pattern2.
2853 context2 (optional)
2855 context expression, evaluated together with pattern2.
2856 desc2 format string that sets the %s variable for action2.
2858 action2
2860 action list.
2861 window event correlation window size (value is an integer constant).
2863 rem (optional, may appear more than once)
2865 remarks and comments.
2866 The PairWithWindow rule runs event correlation operations for process‐
2868 ing event pairs during T seconds. The value of T is defined by the win‐
2869 dow field.
2870 When an event has matched the conditions defined by the pattern and
2872 context field, SEC evaluates the operation description string given
2873 with the desc field. If the operation for the given string and rule
2874 exists, it consumes the matching event without any action. If the oper‐
2875 ation does not exist, SEC will create it with the lifetime of T sec‐
2876 onds. SEC will also copy the match conditions given with the pattern2
2877 and context2 field into the operation, and substitute match variables
2878 with their values in copied conditions.
2879 If the event does not match conditions defined by the pattern and con‐
2881 text field, SEC will check the match conditions of all operations
2882 started by the given rule. Each matching operation executes the action
2883 list given with the action2 field and finishes. If the operation has
2884 not observed a matching event by the end of its lifetime, it executes
2885 the action list given with the action field before finishing.
2886 If match variables are set when the operation matches an event, they
2888 are made available as $-prefixed match variables in context2, desc2,
2889 and action2 fields of the rule definition. For example, if pattern2
2890 field is a regular expression, then $1 in the desc2 field is set by
2891 pattern2. In order to access match variables set by pattern, %-pre‐
2892 fixed match variables have to be used in context2, desc2, and action2
2893 fields. For example, if pattern and pattern2 are regular expressions,
2894 then %1 in the desc2 field refers to the value set by the first capture
2895 group in pattern (i.e., it has the same value as $1 in the desc field).
2896 Examples:
2898 type=PairWithWindow
2900 ptype=RegExp
2901 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
2902 desc=User $1 has been unable to log in from $2 over SSH during 1 minute
2903 action=pipe '%t: %s' /bin/mail root@localhost
2904 ptype2=RegExp
2905 pattern2=sshd\[\d+\]: Accepted .+ for $1 from $2 port \d+ ssh2
2906 desc2=SSH login successful for %1 from %2 after initial failure
2907 action2=logonly
2908 window=60
2909 This rule runs event correlation operations for processing SSH login
2911 events, e.g.,
2912 Dec 27 19:00:24 test sshd[10526]: Failed password for risto from
2914 10.1.2.7 port 52622 ssh2
2915 Dec 27 19:00:27 test sshd[10526]: Accepted password for risto from
2916 10.1.2.7 port 52622 ssh2
2917 When an SSH login failure is observed for a user name and a source IP
2919 address, an operation is created for this user name and IP address com‐
2920 bination which will expect a successful login for the *same* user name
2921 and *same* IP address during 60 seconds. If the user will not log in
2922 from the same IP address during 60 seconds, the operation will send an
2923 e-mail warning to root@localhost before finishing, otherwise it will
2924 log the message "SSH login successful for <username> from <ipaddress>
2925 after initial failure" and finish.
2926 Suppose the following events are generated by an SSH daemon, and each
2928 event timestamp reflects the time SEC observes the event:
2929 Dec 30 13:02:01 test sshd[30517]: Failed password for risto from
2931 10.1.2.7 port 42172 ssh2
2932 Dec 30 13:02:30 test sshd[30810]: Failed password for root from
2933 192.168.1.104 port 46125 ssh2
2934 Dec 30 13:02:37 test sshd[30517]: Failed password for risto from
2935 10.1.2.7 port 42172 ssh2
2936 Dec 30 13:02:59 test sshd[30810]: Failed password for root from
2937 192.168.1.104 port 46125 ssh2
2938 Dec 30 13:03:04 test sshd[30810]: Accepted password for root from
2939 192.168.1.104 port 46125 ssh2
2940 When the first event is observed at 13:02:01, an operation is started
2942 for user risto and IP address 10.1.2.7 which will expect a successful
2943 login for risto from 10.1.2.7. The operation will run for 60 seconds,
2944 waiting for an event which would match the regular expression
2945 sshd\[\d+\]: Accepted .+ for risto from 10\.1\.2\.7 port \d+ ssh2
2947 Note that this expression was created from the regular expression tem‐
2949 plate in the pattern2 field by substituting match variables $1 and $2
2950 with their values. However, since the value of $2 contains the dot (.)
2951 characters which are regular expression metacharacters, each dot is
2952 masked with the backslash in the regular expression.
2953 When the second event is observed at 13:02:30, another operation is
2955 started for user root and IP address 192.168.1.104 which will expect
2956 root to log in successfully from 192.168.1.104. This operation will run
2957 for 60 seconds, waiting for an event matching the regular expression
2958 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2960 The third event at 13:02:37 represents a second login failure for user
2962 risto and IP address 10.1.2.7, and is silently consumed by the first
2963 operation. Likewise, the fourth event at 13:02:59 is silently consumed
2964 by the second operation. The first operation will run until 13:03:01
2965 and then expire without seeing a successful login for risto from
2966 10.1.2.7. Before terminating, the operation will send an e-mail warning
2967 to root@localhost that user risto has not managed to log in from
2968 10.1.2.7 during one minute. At 13:03:04, the second operation will ob‐
2969 serve an event which matches its regular expression
2970 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2972 After seeing this event, the operation will log the message "SSH login
2974 successful for root from 192.168.1.104 after initial failure" and ter‐
2975 minate immediately. Please note that the match by the regular expres‐
2976 sion
2977 sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2979 sets the $1 match variable to 1 and unsets $2. Therefore, the %1 and %2
2981 match variables have to be used in the desc2 field, in order to refer
2982 to the original values of $1 (root) and $2 (192.168.1.104) when the op‐
2983 eration was created.
2984 SINGLEWITHTHRESHOLD RULE
2986 The SingleWithThreshold rule supports the following fields. Note that
2987 match variables may be used in context, desc, action, and action2
2988 fields.
2989 type fixed to SingleWithThreshold (value is case insensitive).
2991 continue (optional)
2993 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
2994 bel>, values are case insensitive).
2995 ptype pattern type (value is case insensitive).
2997 pattern
2999 pattern.
3000 varmap (optional)
3002 variable map.
3003 context (optional)
3005 context expression.
3006 desc operation description string.
3008 action action list.
3010 action2 (optional)
3012 action list.
3013 window event correlation window size (value is an integer constant).
3015 thresh counting threshold (value is an integer constant).
3017 rem (optional, may appear more than once)
3019 remarks and comments.
3020 The SingleWithThreshold rule runs event correlation operations for
3022 counting repeated instances of the same event during T seconds, and
3023 taking an action if N events are observed. The values of T and N are
3024 defined by the window and thresh field, respectively.
3025 When an event has matched the rule, SEC evaluates the operation de‐
3027 scription string given with the desc field. If the operation for the
3028 given string and rule does not exist, SEC will create it with the life‐
3029 time of T seconds. The operation will memorize the occurrence time of
3030 the event (current time as returned by the time(2) system call), and
3031 compare the number of memorized occurrence times with the threshold N.
3032 If the operation has observed N events, it executes the action list de‐
3033 fined by the action field, and consumes all further matching events
3034 without any action. If the rule has an optional action list defined
3035 with the action2 field, the operation will execute it before finishing,
3036 provided that the action list given with action has been previously ex‐
3037 ecuted by the operation. Note that a sliding window is employed for
3038 event counting -- if the operation has observed less than N events by
3039 the end of its lifetime, it drops occurrence times which are older than
3040 T seconds, and extends its lifetime for T seconds from the earliest re‐
3041 maining occurrence time. If there are no remaining occurrence times,
3042 the operation finishes without executing an action list.
3043 Examples:
3045 type=SingleWithThreshold
3047 ptype=RegExp
3048 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
3049 desc=Three SSH login failures within 1m for user $1
3050 action=pipe '%t: %s' /bin/mail root@localhost
3051 window=60
3052 thresh=3
3053 This rule runs event correlation operations for counting the number of
3055 SSH login failure events. Each operation counts events for one user
3056 name, and if the operation has observed three login failures within 60
3057 seconds, it sends an e-mail warning to root@localhost.
3058 Suppose the following events are generated by an SSH daemon, and each
3060 event timestamp reflects the time SEC observes the event:
3061 Dec 28 01:42:21 test sshd[28132]: Failed password for risto from
3063 10.1.2.7 port 42172 ssh2
3064 Dec 28 01:43:10 test sshd[28132]: Failed password for risto from
3065 10.1.2.7 port 42172 ssh2
3066 Dec 28 01:43:29 test sshd[28132]: Failed password for risto from
3067 10.1.2.7 port 42172 ssh2
3068 Dec 28 01:44:00 test sshd[28149]: Failed password for risto2 from
3069 10.1.2.7 port 42176 ssh2
3070 Dec 28 01:44:03 test sshd[28211]: Failed password for risto from
3071 10.1.2.7 port 42192 ssh2
3072 Dec 28 01:44:07 test sshd[28211]: Failed password for risto from
3073 10.1.2.7 port 42192 ssh2
3074 When the first event is observed at 01:42:21, a counting operation is
3076 started for user risto, with its event correlation window ending at
3077 01:43:21. Since by 01:43:21 two SSH login failures for user risto have
3078 occurred, the threshold condition remains unsatisfied for the opera‐
3079 tion. Therefore, the beginning of its event correlation window will be
3080 moved to 01:43:10 (the occurrence time of the second event), leaving
3081 the first event outside the window. At 01:44:00, another counting op‐
3082 eration is started for user risto2. The threshold condition for the
3083 first operation will become satisfied at 01:44:03 (since the operation
3084 has seen three login failure events for user risto within 60 seconds),
3085 and thus an e-mail warning will be issued. Finally, the event occurring
3086 at 01:44:07 will be consumed silently by the first operation (the oper‐
3087 ation will run until 01:44:10). Since there will be no further login
3088 failure events for user risto2, the second operation will exist until
3089 01:45:00 without taking any action.
3090 SINGLEWITH2THRESHOLDS RULE
3092 The SingleWith2Thresholds rule supports the following fields. Note
3093 that match variables may be used in context, desc, action, desc2, and
3094 action2 fields.
3095 type fixed to SingleWith2Thresholds (value is case insensitive).
3097 continue (optional)
3099 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
3100 bel>, values are case insensitive).
3101 ptype pattern type (value is case insensitive).
3103 pattern
3105 pattern.
3106 varmap (optional)
3108 variable map.
3109 context (optional)
3111 context expression.
3112 desc operation description string.
3114 action action list.
3116 window event correlation window size (value is an integer constant).
3118 thresh counting threshold.
3120 desc2 format string that sets the %s variable for action2.
3122 action2
3124 action list.
3125 window2
3127 event correlation window size (value is an integer constant).
3128 thresh2
3130 counting threshold.
3131 rem (optional, may appear more than once)
3133 remarks and comments.
3134 The SingleWith2Thresholds rule runs event correlation operations which
3136 take action if N1 events have been observed in the window of T1 sec‐
3137 onds, and then at most N2 events will be observed in the window of T2
3138 seconds. The values of T1, N1, T2, and N2 are defined by the window,
3139 thresh, window2, and thresh2 field, respectively.
3140 When an event has matched the rule, SEC evaluates the operation de‐
3142 scription string given with the desc field. If the operation for the
3143 given string and rule does not exist, SEC will create it with the life‐
3144 time of T1 seconds. The operation will memorize the occurrence time of
3145 the event (current time as returned by the time(2) system call), and
3146 compare the number of memorized occurrence times with the threshold N1.
3147 If the operation has observed N1 events, it executes the action list
3148 defined by the action field, and starts another counting round for T2
3149 seconds. If no more than N2 events have been observed by the end of
3150 the window, the operation executes the action list defined by the ac‐
3151 tion2 field and finishes. Note that both windows are sliding -- the
3152 first window slides like the window of the SingleWithThreshold opera‐
3153 tion, while the beginning of the second window is moved to the second
3154 earliest memorized event occurrence time when the threshold N2 is vio‐
3155 lated.
3156 Examples:
3158 type=SingleWith2Thresholds
3160 ptype=RegExp
3161 pattern=(\S+): %SYS-3-CPUHOG
3162 desc=Router $1 CPU overload
3163 action=pipe '%t: %s' /bin/mail root@localhost
3164 window=300
3165 thresh=2
3166 desc2=Router $1 CPU load has been normal for 1h
3167 action2=logonly
3168 window2=3600
3169 thresh2=0
3170 When a SYS-3-CPUHOG syslog message is received from a router, the rule
3172 starts a counting operation for this router which sends an e-mail warn‐
3173 ing to root@localhost if another such message is received from the same
3174 router within 300 seconds. After sending the warning, the operation
3175 will continue to run until no SYS-3-CPUHOG syslog messages have been
3176 received from the router for 3600 seconds. When this condition becomes
3177 satisfied, the operation will log the message "Router <routername> CPU
3178 load has been normal for 1h" and finish.
3179 Suppose the following events are generated by a router, and each event
3181 timestamp reflects the time SEC observes the event:
3182 Dec 30 12:23:25 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3184 Dec 30 12:25:38 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3185 Dec 30 12:28:53 router1.mydomain Router1: %SYS-3-CPUHOG: cpu is hogged
3186 When the first event is observed at 12:23:25, a counting operation is
3188 started for router Router1. The appearance of the second event at
3189 12:25:38 fulfills the threshold condition given with the thresh and
3190 window fields (two events have been observed within 300 seconds).
3191 Therefore, the operation will send an e-mail warning about the CPU
3192 overload of Router1 to root@localhost.
3193 After that, the operation will start another counting round, expecting
3195 to see no SYS-3-CPUHOG events (since thresh2=0) for Router1 during the
3196 following 3600 seconds (the beginning of the operation's event correla‐
3197 tion window will be moved to 12:25:38 for the second counting round).
3198 Since the appearance of the third event at 12:28:53 violates the
3199 threshold condition given with the thresh2 and window2 fields, the be‐
3200 ginning of the event correlation window will be moved to 12:28:53.
3201 Since there will be no further SYS-3-CPUHOG messages for Router1, the
3202 operation will run until 13:28:53 and then expire, logging the message
3203 "Router Router1 CPU load has been normal for 1h" before finishing.
3204 EVENTGROUP RULE
3206 The EventGroup rule supports the following fields. Note that match
3207 variables may be used in context*, count*, desc, action, init, end, and
3208 slide fields.
3209 type EventGroup[N] (value is case insensitive, N defaults to 1).
3211 continue (optional)
3213 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
3214 bel>, values are case insensitive). Specifies the point-of-con‐
3215 tinue after a match by pattern and context.
3216 ptype pattern type for pattern (value is case insensitive).
3218 pattern
3220 pattern.
3221 varmap (optional)
3223 variable map for pattern.
3224 context (optional)
3226 context expression, evaluated together with pattern.
3227 count (optional)
3229 action list for execution after a match by pattern and context.
3230 thresh (optional)
3232 counting threshold for events matched by pattern and context
3233 (value is an integer constant, default is 1).
3234 ...
3236 continueN (optional)
3238 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
3239 bel>, values are case insensitive). Specifies the point-of-con‐
3240 tinue after a match by patternN and contextN.
3241 ptypeN pattern type for patternN (value is case insensitive).
3243 patternN
3245 pattern.
3246 varmapN (optional)
3248 variable map for patternN.
3249 contextN (optional)
3251 context expression, evaluated together with patternN.
3252 countN (optional)
3254 action list for execution after a match by patternN and con‐
3255 textN.
3256 threshN (optional)
3258 counting threshold for events matched by patternN and contextN
3259 (value is an integer constant, default is 1).
3260 desc operation description string.
3262 action action list.
3264 init (optional)
3266 action list.
3267 end (optional)
3269 action list.
3270 slide (optional)
3272 action list.
3273 multact (optional)
3275 Yes or No (values are case insensitive, default is No).
3276 egptype (optional)
3278 SubStr, NSubStr, RegExp, NRegExp, PerlFunc or NPerlFunc (values
3279 are case insensitive). Specifies the pattern type for egpat‐
3280 tern.
3281 egpattern (optional)
3283 event group pattern.
3284 window event correlation window size (value is an integer constant).
3286 rem (optional, may appear more than once)
3288 remarks and comments.
3289 The EventGroup rule runs event correlation operations for counting re‐
3291 peated instances of N different events e1,...,eN during T seconds, and
3292 taking an action if threshold conditions c1,...,cN for *all* events are
3293 satisfied (i.e., for each event eK there are at least cK event in‐
3294 stances in the window). Note that the event correlation window of the
3295 EventGroup operation is sliding like the window of the SingleWith‐
3296 Threshold operation.
3297 Event e1 is described with the pattern and context field, event e2 is
3299 described with the pattern2 and context2 field, etc. The values for N
3300 and T are defined by the type and window field, respectively. The value
3301 for c1 is given with the thresh field, the value for c2 is given with
3302 the thresh2 field, etc. Values for N and c1,...,cN default to 1.
3303 In order to match an event with the rule, pattern and context fields
3305 are evaluated first. If they don't match the event, then pattern2 and
3306 context2 are evaluated, etc. If all N conditions are tried without a
3307 success, the event doesn't match the rule.
3308 When an event has matched the rule, SEC evaluates the operation de‐
3310 scription string given with the desc field. If the operation for the
3311 given string and rule does not exist, SEC will create it with the life‐
3312 time of T seconds. The operation will memorize the occurrence time of
3313 the event (current time as returned by the time(2) system call), and
3314 compare the number of memorized occurrence times for each eK with the
3315 threshold cK (i.e., the number of observed instances of eK is compared
3316 with the threshold cK). If all threshold conditions are satisfied, the
3317 operation executes the action list defined by the action field, and
3318 consumes all further matching events without re-executing the action
3319 list if the multact field is set to No (this is the default). However,
3320 if multact is set to Yes, the operation will re-evaluate the threshold
3321 conditions on every further matching event, re-executing the action
3322 list given with the action field if all conditions are satisfied, and
3323 sliding the event correlation window forward when the window is about
3324 to expire (if no events remain in the window, the operation will fin‐
3325 ish).
3326 For example, consider the following rule:
3328 type=EventGroup2
3330 ptype=SubStr
3331 pattern=EVENT_A
3332 thresh=2
3333 ptype2=SubStr
3334 pattern2=EVENT_B
3335 thresh2=2
3336 desc=Sequence of two or more As and Bs observed within 60 seconds
3337 action=write - %s
3338 window=60
3339 Also, suppose the following events occur, and each event timestamp re‐
3341 flects the time SEC observes the event:
3342 Mar 10 12:03:01 EVENT_A
3344 Mar 10 12:03:04 EVENT_B
3345 Mar 10 12:03:10 EVENT_A
3346 Mar 10 12:03:11 EVENT_A
3347 Mar 10 12:03:27 EVENT_B
3348 Mar 10 12:03:46 EVENT_A
3349 Mar 10 12:03:59 EVENT_A
3350 When these events are observed by the above EventGroup2 rule, the rule
3352 starts an event correlation operation at 12:03:01. Note that although
3353 the first threshold condition thresh=2 is satisfied when the third
3354 event appears at 12:03:10, the second threshold condition thresh2=2 is
3355 not met, and therefore the operation will not execute the action list
3356 given with the action field. When the fifth event appears at 12:03:27,
3357 all threshold conditions are finally satisfied, and the operation will
3358 write the string "Sequence of two or more As and Bs observed within 60
3359 seconds" to standard output with the write action. Finally, the events
3360 occurring at 12:03:46 and 12:03:59 will be consumed silently by the op‐
3361 eration (the operation will run until 12:04:01).
3362 If multact=yes statement is added to the above EventGroup2 rule, the
3364 operation would execute the write action not only at 12:03:27, but also
3365 at 12:03:46 and 12:03:59, since all threshold conditions are still sat‐
3366 isfied when the last two events appear (i.e., the last two events are
3367 no longer silently consumed). Also, with multact=yes the operation will
3368 employ sliding window based event processing even after the write ac‐
3369 tion has been executed at 12:03:27 (therefore, the operation will run
3370 until 12:04:59).
3371 If the rule definition has an optional event group pattern and its type
3373 defined with the egpattern and egptype fields, the event group pattern
3374 is used for matching the event group string. The event group string
3375 consists of positive integers Xi that are separated by a single space
3376 character: "X1 X2 ... XM". M is the number of events a given event
3377 correlation operation has observed within its event correlation window.
3378 Also, if the i-th event that the event correlation operation has ob‐
3379 served is an instance of event eK, then Xi = K. Event group string is
3380 built and matched with event group pattern after all threshold condi‐
3381 tions (given with thresh* fields) have been found satisfied. In other
3382 words, the event group pattern defines an additional condition to nu‐
3383 meric threshold conditions.
3384 Note that the event group pattern and its type are similar to regular
3386 patterns and pattern types that are given with pattern* and ptype*
3387 fields, except the event group pattern is not setting any match vari‐
3388 ables. If the egptype field is set to RegExp or NRegExp, the egpattern
3389 field defines a regular expression, while in the case of SubStr and
3390 NSubStr egpattern provides a string pattern. If the egptype field is
3391 set to PerlFunc or NPerlFunc, event group string is the only parameter
3392 for the Perl function given with the egpattern field, and the function
3393 is called in the Perl scalar context. With egptype=PerlFunc, event
3394 group pattern matches if the return value of the function evaluates
3395 true in the Perl boolean context, while in the case of false the pat‐
3396 tern does not match the event group string. With egptype=NPerlFunc,
3397 the pattern matching works in the opposite way.
3398 For example, consider the following rule:
3400 type=EventGroup2
3402 ptype=SubStr
3403 pattern=EVENT_A
3404 thresh=2
3405 ptype2=SubStr
3406 pattern2=EVENT_B
3407 thresh2=2
3408 desc=Sequence of two or more As and Bs with 'A B' at the end
3409 action=write - %s
3410 egptype=RegExp
3411 egpattern=1 2$
3412 window=60
3413 Also, suppose the following events occur, and each event timestamp re‐
3415 flects the time SEC observes the event:
3416 Mar 10 12:05:31 EVENT_B
3418 Mar 10 12:05:32 EVENT_B
3419 Mar 10 12:05:38 EVENT_A
3420 Mar 10 12:05:39 EVENT_A
3421 Mar 10 12:05:42 EVENT_B
3422 When these events are observed by the above EventGroup2 rule, the rule
3424 starts an event correlation operation at 12:05:31. When the fourth
3425 event appears at 12:05:39, all threshold conditions (thresh=2 and
3426 thresh2=2) become satisfied, and therefore the following event group
3427 string is built from the first four events:
3428 2 2 1 1
3430 However, since this string does not match the regular expression
3432 1 2$
3434 that has been given with the egpattern field, the operation will not
3436 execute the action list given with the action field. When the fifth
3437 event appears at 12:05:42, all threshold conditions are again satis‐
3438 fied, and all observed events produce the following event group string:
3439 2 2 1 1 2
3441 Since this event group string matches the regular expression given with
3443 the egpattern field, the operation will write the string "Sequence of
3444 two or more As and Bs with 'A B' at the end" to standard output with
3445 the write action.
3446 If the rule definition has an optional action list defined with the
3448 countK field for event eK, the operation executes it every time an in‐
3449 stance of eK is observed (even if multact is set to No and the opera‐
3450 tion has already executed the action list given with action). If the
3451 action list contains match variables, they are substituted before
3452 *each* execution with values from matching the current instance of eK.
3453 If the rule definition has an optional action list defined with the
3455 init field, the operation executes it immediately after the operation
3456 has been created.
3457 If the rule definition has an optional action list defined with the end
3459 field, the operation executes it immediately before the operation fin‐
3460 ishes. Note that this action list is *not* executed when the operation
3461 is terminated with the reset action.
3462 If the rule definition has an optional action list defined with the
3464 slide field, the operation executes it immediately after the event cor‐
3465 relation window has slidden forward. However, note that moving the
3466 window with the setwpos action will *not* trigger the execution.
3467 Examples:
3469 The following example rule cross-correlates iptables events, Apache web
3471 server access log messages with 4xx response codes, and SSH login fail‐
3472 ure events:
3473 type=EventGroup3
3475 ptype=RegExp
3476 pattern=sshd\[\d+\]: Failed .+ for (?:invalid user )?\S+ from ([\d.]+)
3477 port \d+ ssh2
3478 thresh=2
3479 ptype2=RegExp
3480 pattern2=^([\d.]+) \S+ \S+ \[.+?\] ".+? HTTP\/[\d.]+" 4\d+
3481 thresh2=3
3482 ptype3=RegExp
3483 pattern3=kernel: iptables:.* SRC=([\d.]+)
3484 thresh3=5
3485 desc=Repeated probing from host $1
3486 action=pipe '%t: %s' /bin/mail root@localhost
3487 window=120
3488 The rule starts an event correlation operation for an IP address if SSH
3490 login failure event, iptables event, or Apache 4xx event is observed
3491 for that IP address. The operation sends an e-mail warning to root@lo‐
3492 calhost if within 120 seconds three threshold conditions are satisfied
3493 for the IP address it tracks -- (1) at least two SSH login failure
3494 events have occurred for this client IP, (2) at least three Apache 4xx
3495 events have occurred for this client IP, (3) at least five iptables
3496 events have been observed for this source IP.
3497 Suppose the following events occur, and each event timestamp reflects
3499 the time SEC observes the event:
3500 192.168.1.104 - - [05/Jan/2014:01:11:22 +0200] "GET /test.html
3502 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3503 Gecko/20100101 Firefox/26.0"
3504 Jan 5 01:12:52 localhost kernel: iptables: IN=eth0 OUT=
3505 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3506 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=48422 DF
3507 PROTO=TCP SPT=46351 DPT=21 WINDOW=29200 RES=0x00 SYN URGP=0
3508 Jan 5 01:12:53 localhost kernel: iptables: IN=eth0 OUT=
3509 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3510 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=48423 DF
3511 PROTO=TCP SPT=46351 DPT=21 WINDOW=29200 RES=0x00 SYN URGP=0
3512 Jan 5 01:13:01 localhost kernel: iptables: IN=eth0 OUT=
3513 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3514 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=20048 DF
3515 PROTO=TCP SPT=44963 DPT=23 WINDOW=29200 RES=0x00 SYN URGP=0
3516 Jan 5 01:13:02 localhost kernel: iptables: IN=eth0 OUT=
3517 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3518 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=20049 DF
3519 PROTO=TCP SPT=44963 DPT=23 WINDOW=29200 RES=0x00 SYN URGP=0
3520 Jan 5 01:13:08 localhost kernel: iptables: IN=eth0 OUT=
3521 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3522 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=36362 DF
3523 PROTO=TCP SPT=56918 DPT=25 WINDOW=29200 RES=0x00 SYN URGP=0
3524 Jan 5 01:13:09 localhost kernel: iptables: IN=eth0 OUT=
3525 MAC=08:00:27:8e:a1:3a:00:1d:e0:7e:89:b1:08:00 SRC=192.168.1.104
3526 DST=192.168.1.107 LEN=60 TOS=0x10 PREC=0x00 TTL=64 ID=36363 DF
3527 PROTO=TCP SPT=56918 DPT=25 WINDOW=29200 RES=0x00 SYN URGP=0
3528 192.168.1.104 - - [05/Jan/2014:01:13:51 +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 192.168.1.104 - - [05/Jan/2014:01:13:54 +0200] "GET /test.html
3532 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3533 Gecko/20100101 Firefox/26.0"
3534 192.168.1.104 - - [05/Jan/2014:01:14:00 +0200] "GET /login.html
3535 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3536 Gecko/20100101 Firefox/26.0"
3537 192.168.1.104 - - [05/Jan/2014:01:14:03 +0200] "GET /login.html
3538 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3539 Gecko/20100101 Firefox/26.0"
3540 192.168.1.104 - - [05/Jan/2014:01:14:03 +0200] "GET /login.html
3541 HTTP/1.1" 404 287 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3542 Gecko/20100101 Firefox/26.0"
3543 Jan 5 01:14:11 localhost sshd[1810]: Failed password for root from
3544 192.168.1.104 port 46125 ssh2
3545 Jan 5 01:14:12 localhost sshd[1810]: Failed password for root from
3546 192.168.1.104 port 46125 ssh2
3547 Jan 5 01:14:18 localhost sshd[1822]: Failed password for root from
3548 192.168.1.104 port 46126 ssh2
3549 Jan 5 01:14:19 localhost sshd[1822]: Failed password for root from
3550 192.168.1.104 port 46126 ssh2
3551 192.168.1.104 - - [05/Jan/2014:01:14:34 +0200] "GET /test.html
3552 HTTP/1.1" 404 286 "-" "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:26.0)
3553 Gecko/20100101 Firefox/26.0"
3554 The Apache 4xx event at 01:11:22 starts an event correlation operation
3556 for 192.168.1.104 which has the event correlation window of 120 sec‐
3557 onds, thus ending at 01:13:22. Between 01:12:52 and 01:13:09, six ipt‐
3558 ables events appear for 192.168.1.104, and the appearance of the fifth
3559 event at 01:13:08 fulfills the third threshold condition (within 120
3560 seconds, at least five iptables events have been observed).
3561 Since by 01:13:22 (the end of the event correlation window) no addi‐
3563 tional events have occurred, the first and second threshold condition
3564 remain unsatisfied. Therefore, the beginning of the event correlation
3565 window will be moved to 01:12:52 (the occurrence time of the earliest
3566 event which is at most 120 seconds old). As a result, the end of the
3567 window will move from 01:13:22 to 01:14:52. The only event which is
3568 left outside the window is the Apache 4xx event at 01:11:22, and thus
3569 the threshold condition for iptables events remains satisfied.
3570 Between 01:13:51 and 01:14:03, five Apache 4xx events occur, and the
3572 appearance of the third event at 01:14:00 fulfills the second threshold
3573 condition (within 120 seconds, at least three Apache 4xx events have
3574 been observed). These events are followed by four SSH login failure
3575 events which occur between 01:14:11 and 01:14:19. The appearance of the
3576 second event at 01:14:12 fulfills the first threshold condition (within
3577 120 seconds, at least two SSH login failure events have been observed).
3578 Since at this particular moment (01:14:12) the other two conditions are
3579 also fulfilled, the operation sends an e-mail warning about
3580 192.168.1.104 to root@localhost. After that, the operation silently
3581 consumes all further matching events for 192.168.1.104 until 01:14:52,
3582 and then terminates.
3583 Please note that if the above rule definition would contain multact=yes
3585 statement, the operation would continue sending e-mails at each match‐
3586 ing event after 01:14:12, provided that all threshold conditions are
3587 satisfied. Therefore, the operation would send three additional e-
3588 mails at 01:14:18, 01:14:19, and 01:14:34. Also, the operation would
3589 not terminate after its window ends at 01:14:52, but would rather slide
3590 the window forward and expect new events. At the occurrence of any
3591 iptables, SSH login failure or Apache 4xx event for 192.168.1.104, the
3592 operation would produce a warning e-mail if all threshold conditions
3593 are fulfilled.
3594 The following example rule cross-correlates iptables events and SSH lo‐
3596 gin events:
3597 type=EventGroup3
3599 ptype=regexp
3600 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
3601 varmap= user=1; ip=2
3602 count=alias OPER_$+{ip} LOGIN_FAILED_$+{user}_$+{ip}
3603 ptype2=regexp
3604 pattern2=sshd\[\d+\]: Accepted .+ for (\S+) from ([\d.]+) port \d+ ssh2
3605 varmap2= user=1; ip=2
3606 context2=LOGIN_FAILED_$+{user}_$+{ip}
3607 ptype3=regexp
3608 pattern3=kernel: iptables:.* SRC=([\d.]+)
3609 varmap3= ip=1
3610 desc=Client $+{ip} accessed a firewalled port and had difficulties with
3611 logging in
3612 action=pipe '%t: %s' /bin/mail root@localhost
3613 init=create OPER_$+{ip}
3614 slide=delete OPER_$+{ip}; reset 0
3615 end=delete OPER_$+{ip}
3616 window=120
3617 The rule starts an event correlation operation for an IP address if SSH
3619 login failure or iptables event was observed for that IP address. The
3620 operation exists for 120 seconds (since when the event correlation win‐
3621 dow slides forward, the operation terminates itself with the reset ac‐
3622 tion as specified with the slide field). The operation sends an e-mail
3623 warning to root@localhost if within 120 seconds three threshold condi‐
3624 tions are satisfied for the IP address it tracks -- (1) at least one
3625 iptables event has been observed for this source IP, (2) at least one
3626 SSH login failure has been observed for this client IP, (3) at least
3627 one successful SSH login has been observed for this client IP and for
3628 some user, provided that the operation has previously observed an SSH
3629 login failure for the same user and same client IP.
3630 Suppose the following events occur, and each event timestamp reflects
3632 the time SEC observes the event:
3633 Dec 27 19:00:06 test kernel: iptables: IN=eth0 OUT=
3635 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
3636 LEN=60 TOS=0x00 PREC=0x00 TTL=62 ID=1881 DF PROTO=TCP SPT=34342 DPT=23
3637 WINDOW=5840 RES=0x00 SYN URGP=0
3638 Dec 27 19:00:14 test sshd[10520]: Accepted password for root from
3639 10.1.2.7 port 52609 ssh2
3640 Dec 27 19:00:24 test sshd[10526]: Failed password for risto from
3641 10.1.2.7 port 52622 ssh2
3642 Dec 27 19:00:27 test sshd[10526]: Accepted password for risto from
3643 10.1.2.7 port 52622 ssh2
3644 The iptables event at 19:00:06 starts an event correlation operation
3646 for 10.1.2.7 which has the event correlation window of 120 seconds.
3647 Immediately after the operation has been started, it creates the con‐
3648 text OPER_10.1.2.7. The second event at 19:00:14 does not match the
3649 rule, since the context LOGIN_FAILED_root_10.1.2.7 does not exist. The
3650 third event at 19:00:24 matches the rule, and the operation which is
3651 running for 10.1.2.7 sets up the alias name LOGIN_FAILED_risto_10.1.2.7
3652 for the context OPER_10.1.2.7. Finally, the fourth event at 19:00:27
3653 matches the rule, since the context LOGIN_FAILED_risto_10.1.2.7 exists,
3654 and the event is therefore processed by the operation (the presence of
3655 the context indicates that the operation has previously observed a lo‐
3656 gin failure for user risto from 10.1.2.7). At this particular moment
3657 (19:00:27), all three threshold conditions for the operation are ful‐
3658 filled, and therefore it sends an e-mail warning about 10.1.2.7 to
3659 root@localhost. After that, the operation silently consumes all further
3660 matching events for 10.1.2.7 until 19:02:06, and then terminates. Im‐
3661 mediately before termination, the operation deletes the context
3662 OPER_10.1.2.7 which also drops its alias name LO‐
3663 GIN_FAILED_risto_10.1.2.7.
3664 SUPPRESS RULE
3666 The Suppress rule supports the following fields. Note that match vari‐
3667 ables may be used in the context field.
3668 type fixed to Suppress (value is case insensitive).
3670 ptype pattern type (value is case insensitive).
3672 pattern
3674 pattern.
3675 varmap (optional)
3677 variable map.
3678 context (optional)
3680 context expression.
3681 desc (optional)
3683 string for describing the rule.
3684 rem (optional, may appear more than once)
3686 remarks and comments.
3687 The Suppress rule takes no action when an event has matched the rule,
3689 and keeps matching events from being processed by later rules in the
3690 configuration file.
3691 Note that the Suppress rule does not start event correlation opera‐
3693 tions, and the optional desc field is merely used for describing the
3694 rule. Also, in order to end event processing, so that no further rules
3695 from any of the configuration files would be tried, use the Jump rule.
3696 Examples:
3698 type=Suppress
3700 ptype=RegExp
3701 pattern=sshd\[\d+\]: Failed .+ for \S+ from ([\d.]+) port \d+ ssh2
3702 context=SUPPRESS_IP_$1
3703 type=SingleWithThreshold
3705 ptype=RegExp
3706 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
3707 desc=Three SSH login failures within 1m for user $1 from $2
3708 action=pipe '%t: %s' /bin/mail root@localhost; \
3709 create SUPPRESS_IP_$2 3600
3710 window=60
3711 thresh=3
3712 The first rule filters out SSH login failure events for an already re‐
3714 ported source IP address, so that they will not be matched against the
3715 second rule during 3600 seconds after sending an e-mail warning.
3716 CALENDAR RULE
3718 The Calendar rule supports the following fields.
3719 type fixed to Calendar (value is case insensitive).
3721 time time specification.
3723 context (optional)
3725 context expression.
3726 desc operation description string.
3728 action action list.
3730 rem (optional, may appear more than once)
3732 remarks and comments.
3733 The Calendar rule was designed for executing actions at specific times.
3735 Unlike all other rules, this rule reacts only to the system clock, ig‐
3736 noring other input. The Calendar rule executes the action list given
3737 with the action field if the current time matches all conditions of the
3738 time specification given with the time field. The action list is exe‐
3739 cuted only once for any matching minute.
3740 The rule employs a time specification which closely resembles the
3742 crontab(1) style, but there are some subtle differences. The time
3743 specification consists of five or six conditions separated by white‐
3744 space. The first condition matches minutes (allowed values are 0-59),
3745 the second condition matches hours (allowed values are 0-23), the third
3746 condition days (allowed values are 0-31, with 0 denoting the last day
3747 of the month), the fourth condition months (allowed values are 1-12),
3748 and the fifth condition weekdays (allowed values are 0-7, with 0 and 7
3749 denoting Sunday). The sixth condition is optional and matches years
3750 (allowed values are 0-99 which denote the last two digits of the year).
3751 Asterisks (*), ranges of numbers (e.g., 8-11), and lists (e.g.,
3753 2,5,7-9) are allowed as conditions. Asterisks and ranges may be aug‐
3754 mented with step values (e.g., 47-55/2 means 47,49,51,53,55).
3755 Note that unlike crontab(1) time specification, the day and weekday
3757 conditions are *not* joined with logical OR, but rather with logical
3758 AND. Therefore, 0 1 25-31 10 7 means 1AM on last Sunday in October.
3759 On the other hand, with crontab(1) the same specification means 1AM in
3760 every last seven days or every Sunday in October.
3761 Also, unlike some versions of cron(8), SEC is not restricted to take
3763 action only during the first second of the current minute. For example,
3764 if SEC is started at the 22th second of a minute, the wildcard condi‐
3765 tion produces a match for this minute. As another example, if the time
3766 specification matches the current minute but the context expression
3767 evaluates FALSE during the first half of the minute, the Calendar rule
3768 will execute the action list in the middle of this minute when the ex‐
3769 pression value becomes TRUE.
3770 Note that the Calendar rule does not start event correlation opera‐
3772 tions, and the desc field is merely used for setting the %s action list
3773 variable.
3774 Examples:
3776 type=Calendar
3778 time=0 2 25-31 3,12 6
3779 desc=Check if backup is done on last Saturday of Q1 and Q4
3780 action=event WAITING_FOR_BACKUP
3781 type=Calendar
3783 time=0 2 24-30 6,9 6
3784 desc=Check if backup is done on last Saturday of Q2 and Q3
3785 action=event WAITING_FOR_BACKUP
3786 type=PairWithWindow
3788 ptype=SubStr
3789 pattern=WAITING_FOR_BACKUP
3790 desc=Quarterly backup not completed on time!
3791 action=pipe '%t: %s' /bin/mail root@localhost
3792 ptype2=SubStr
3793 pattern2=BACKUP READY
3794 desc2=Quarterly backup successfully completed
3795 action2=none
3796 window=1800
3797 The first two rules create a synthetic event WAITING_FOR_BACKUP at 2AM
3799 on last Saturday of March, June, September and December. The third
3800 rule matches this event and starts an event correlation operation which
3801 waits for the BACKUP READY event for 1800 seconds. If this event has
3802 not arrived by 2:30AM, the operation sends an e-mail warning to
3803 root@localhost.
3804 JUMP RULE
3806 The Jump rule supports the following fields. Note that match variables
3807 may be used in the context field. They may also be used in the cfset
3808 field, provided that the constset field is set to No.
3809 type fixed to Jump (value is case insensitive).
3811 continue (optional)
3813 TakeNext, DontCont, EndMatch or GoTo <label> (apart from <la‐
3814 bel>, values are case insensitive).
3815 ptype pattern type (value is case insensitive).
3817 pattern
3819 pattern.
3820 varmap (optional)
3822 variable map.
3823 context (optional)
3825 context expression.
3826 cfset (optional)
3828 configuration file set names that are separated by whitespace.
3829 constset (optional)
3831 Yes or No (values are case insensitive, default is Yes).
3832 desc (optional)
3834 string for describing the rule.
3835 rem (optional, may appear more than once)
3837 remarks and comments.
3838 The Jump rule submits matching events to specific ruleset(s) for fur‐
3840 ther processing. If the event matches the rule, SEC continues the
3841 search for matching rules in configuration file set(s) given with the
3842 cfset field. Rules from every file are tried in the order of their ap‐
3843 pearance in the file. Configuration file sets can be created from Op‐
3844 tions rules with the joincfset field, with each set containing at least
3845 one configuration file. If more that one set name is given with cfset,
3846 sets are processed from left to right; a matching rule in one set
3847 doesn't prevent SEC from processing the following sets. If the constset
3848 field is set to Yes, set names are assumed to be constants and will not
3849 be searched for match variables at runtime.
3850 If the cfset field is not present and the continue field is set to
3852 GoTo, the Jump rule can be used for skipping rules inside the current
3853 configuration file. If both cfset and continue are not present (or con‐
3854 tinue is set to DontCont), Jump is identical to Suppress rule. Fi‐
3855 nally, if cfset is not present and continue is set to EndMatch, pro‐
3856 cessing of the matching event ends (i.e., no further rules from any of
3857 the configuration files will be tried).
3858 Note that the Jump rule does not start event correlation operations,
3860 and the optional desc field is merely used for describing the rule.
3861 Examples:
3863 type=Jump
3865 ptype=RegExp
3866 pattern=sshd\[\d+\]:
3867 cfset=sshd-rules auth-rules
3868 When an sshd syslog message appears in input, rules from configuration
3870 files of the set sshd-rules are first used for matching the message,
3871 and then rules from the configuration file set auth-rules are tried.
3872 OPTIONS RULE
3874 The Options rule supports the following fields.
3875 type fixed to Options (value is case insensitive).
3877 joincfset (optional)
3879 configuration file set names that are separated by whitespace.
3880 procallin (optional)
3882 Yes or No (values are case insensitive, default is Yes).
3883 rem (optional, may appear more than once)
3885 remarks and comments.
3886 The Options rule sets processing options for the ruleset in the current
3888 configuration file. If more than one Options rule is present in the
3889 configuration file, the last instance overrides all previous ones. Note
3890 that the Options rule is only processed when SEC (re)starts and reads
3891 in the configuration file. Since this rule is not applied at runtime,
3892 it can never match events, react to the system clock, or start event
3893 correlation operations.
3894 The joincfset field lists the names of one or more configuration file
3896 sets, and the current configuration file will be added to each set. If
3897 a set doesn't exist, it will be created and the current configuration
3898 file becomes its first member. If the procallin field is set to No,
3899 the rules from the configuration file will be used for matching input
3900 from Jump rules only.
3901 Examples:
3903 The following rule adds the current configuration file to the set
3905 sshd-rules which is used for matching input from Jump rules only:
3906 type=Options
3908 joincfset=sshd-rules
3909 procallin=no
3910 The following rule adds the current configuration file to sets linux
3912 and solaris which are used for matching all input:
3913 type=Options
3915 joincfset=linux solaris
3916
3918 Event correlation operations are dynamic entities created by rules.
3919 After creating an operation, the rule also feeds the operation with
3920 events that need to be correlated. Since each rule can create and feed
3921 many operations which are running simultaneously, each operation needs
3922 a unique ID.
3923 In order to identify event correlation operations, SEC assigns an ID to
3925 every operation that is composed from the configuration file name, the
3926 rule number, and the operation description string (defined by the desc
3927 field of the rule). If there are N rules in the configuration file
3928 (excluding Options rules), the rule numbers belong to the range 0..N-1,
3929 and the number of the k-th rule is k-1. Since each Options rule is
3930 only processed when SEC reads in the configuration file and is not ap‐
3931 plied at runtime, the Options rules will not receive rule numbers.
3932 Note that since the configuration file name and rule number are part of
3933 the operation ID, different rules can have identical desc fields with‐
3934 out a danger of a clash between operations.
3935 For example, if the configuration file /etc/sec/my.conf contains only
3937 one rule
3938 type=SingleWithThreshold
3940 ptype=RegExp
3941 pattern=user (\S+) login failure on (\S+)
3942 desc=Repeated login failures for user $1 on $2
3943 action=pipe '%t: %s' /bin/mail root@localhost
3944 window=60
3945 thresh=3
3946 then the number of this rule is 0. When this rule matches an input
3948 event "user admin login failure on tty1", the desc field yields an op‐
3949 eration description string Repeated login failures for user admin on
3950 tty1, and the event will be directed for further processing to the op‐
3951 eration with the following ID:
3952 /etc/sec/my.conf | 0 | Repeated login failures for user admin on tty1
3954 If the operation for this ID does not exist, the rule will create it.
3956 The newly created operation has its event counter initialized to 1, and
3957 it expects to receive two additional "user admin login failure on tty1"
3958 events from the rule within the following 60 seconds. If the operation
3959 receives such an event, its event counter is incremented, and if the
3960 counter reaches the value of 3, a warning e-mail is sent to root@local‐
3961 host.
3962 By tuning the desc field of the rule, the scope of individual event
3964 correlation operations can be changed. For instance, if the following
3965 events occur within 10 seconds
3966 user admin login failure on tty1
3968 user admin login failure on tty5
3969 user admin login failure on tty2
3970 the above rule starts three event correlation operations. However, if
3972 the desc field of the rule is changed to Repeated login failures for
3973 user $1, these events are processed by the *same* event correlation op‐
3974 eration (the operation sends a warning e-mail to root@localhost when it
3975 receives the third event).
3976 Since rules from the same configuration file are matched against input
3978 in the order they are given, the rule ordering influences the creation
3979 and feeding of event correlation operations. Suppose the configuration
3980 file /etc/sec/my.conf contains the following rules:
3981 type=Suppress
3983 ptype=TValue
3984 pattern=TRUE
3985 context=MYCONTEXT
3986 type=SingleWithThreshold
3988 ptype=RegExp
3989 pattern=user (\S+) login failure on (\S+)
3990 desc=Repeated login failures for user $1 on $2
3991 action=pipe '%t: %s' /bin/mail root@localhost
3992 window=60
3993 thresh=3
3994 The second rule is able to create and feed event correlation operations
3996 as long as the context MYCONTEXT does not exist. However, after MYCON‐
3997 TEXT has been created, no input event will reach the second rule, and
3998 the rule is thus unable to create new operations and feed existing ones
3999 with events.
4000 Note that Pair and PairWithWindow rules can feed the same event to sev‐
4002 eral operations. Suppose the configuration file /etc/sec/my2.conf con‐
4003 tains the following rules:
4004 type=Suppress
4006 ptype=SubStr
4007 pattern=test
4008 type=Pair
4010 ptype=RegExp
4011 pattern=database (\S+) down
4012 desc=Database $1 is down
4013 action=pipe '%t: %s' /bin/mail root@localhost
4014 ptype2=RegExp
4015 pattern2=database $1 up|all databases up
4016 desc2=Database %1 is up
4017 action2=pipe '%t: %s' /bin/mail root@localhost
4018 window=86400
4019 Since the following input events don't contain the substring "test"
4021 database mydb1 down
4023 database mydb2 down
4024 database mydb3 down
4025 they are matched by the second rule of type Pair which creates three
4027 event correlation operations. Each operation is running for one partic‐
4028 ular database name, and the operations have the following IDs:
4029 /etc/sec/my2.conf | 1 | Database mydb1 is down
4031 /etc/sec/my2.conf | 1 | Database mydb2 is down
4032 /etc/sec/my2.conf | 1 | Database mydb3 is down
4033 Each newly created operation sends an e-mail notification to root@lo‐
4035 calhost about the "database down" condition, and will then wait for
4036 86400 seconds (24 hours) for either of the following messages:
4037 (a) "database up" message for the given database,
4038 (b) "all databases up" message.
4039 The operation with the ID
4041 /etc/sec/my2.conf | 1 | Database mydb1 is down
4043 uses the following regular expression for matching expected messages:
4045 database mydb1 up|all databases up
4047 The operation with the ID
4049 /etc/sec/my2.conf | 1 | Database mydb2 is down
4051 employs the following regular expression for matching expected mes‐
4053 sages:
4054 database mydb2 up|all databases up
4056 Finally, the operation with the ID
4058 /etc/sec/my2.conf | 1 | Database mydb3 is down
4060 uses the following regular expression:
4062 database mydb3 up|all databases up
4064 If the following input events appear after 10 minutes
4066 database test up
4068 admin logged in
4069 database mydb3 up
4070 all databases up
4071 the first event "database test up" matches the first rule (Suppress)
4073 which does not pass the event further to the second rule (Pair). How‐
4074 ever, all following events reach the Pair rule. Since the messages
4075 don't match the pattern field of the rule, the rule feeds them to all
4076 currently existing operations it has created, so that the operations
4077 can match these events with their regular expressions. Because regular
4078 expressions of all three operations don't match the event "admin logged
4079 in", the operations will continue to run. In the case of the "database
4080 mydb3 up" event, the regular expression of the operation
4081 /etc/sec/my2.conf | 1 | Database mydb3 is down
4083 produces a match. Therefore, the operation will send the e-mail notifi‐
4085 cation "Database mydb3 is up" to root@localhost and terminate. How‐
4086 ever, the following event "all databases up" matches the regular ex‐
4087 pressions of two remaining operations. As a result, the operations will
4088 send e-mail notifications "Database mydb1 is up" and "Database mydb2 is
4089 up" to root@localhost and terminate.
4090 Each operation has an event correlation window which defines its scope
4092 in time. The size of the window is defined by the window* field, and
4093 the beginning of the window can be obtained with the getwpos action.
4094 SingleWithThreshold, SingleWith2Thresholds and EventGroup operations
4095 can slide its window forward during event processing, while for all op‐
4096 erations the window can also be moved explicitly with the setwpos ac‐
4097 tion. Also, with the reset action event correlation operations can be
4098 terminated. Note that getwpos, setwpos, and reset actions only work for
4099 operations started by the rules from the same configuration file.
4100 For example, consider the configuration file /etc/sec/sshd.rules that
4102 contains the following rules:
4103 type=SingleWithThreshold
4105 ptype=RegExp
4106 pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
4107 desc=Three SSH login failures within 1m for user $1
4108 action=pipe '%t: %s' /bin/mail root@localhost
4109 window=60
4110 thresh=3
4111 type=Single
4113 ptype=RegExp
4114 pattern=sshd\[\d+\]: Accepted .+ for (\S+) from [\d.]+ port \d+ ssh2
4115 desc=SSH login successful for user $1
4116 action=reset -1 Three SSH login failures within 1m for user $1
4117 Suppose the following events are generated by an SSH daemon, and each
4119 event timestamp reflects the time SEC observes the event:
4120 Dec 29 15:00:03 test sshd[14129]: Failed password for risto from
4122 10.1.2.7 port 31312 ssh2
4123 Dec 29 15:00:08 test sshd[14129]: Failed password for risto from
4124 10.1.2.7 port 31312 ssh2
4125 Dec 29 15:00:17 test sshd[14129]: Accepted password for risto from
4126 10.1.2.7 port 31312 ssh2
4127 Dec 29 15:00:52 test sshd[14142]: Failed password for risto from
4128 10.1.1.2 port 17721 ssh2
4129 The first event at 15:00:03 starts an event correlation operation with
4131 the ID
4132 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
4134 risto
4135 However, when the third event occurs at 15:00:17, the second rule
4137 matches it and terminates the operation with the action
4138 reset -1 Three SSH login failures within 1m for user risto
4140 The -1 parameter of reset restricts the action to operations started by
4142 the previous rule (i.e., the first rule that has a number 0), while the
4143 Three SSH login failures within 1m for user risto parameter refers to
4144 the operation description string. Together with the current configura‐
4145 tion file name (/etc/sec/sshd.rules), the parameters yield the opera‐
4146 tion ID
4147 /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user
4149 risto
4150 (If the operation with the given ID would not exist, reset would per‐
4152 form no operation.)
4153 As a consequence, the fourth event at 15:00:52 starts another operation
4155 with the same ID as the terminated operation had. Without the second
4156 rule, the operation that was started at 15:00:03 would not be termi‐
4157 nated, and the appearance of the fourth event would trigger a warning
4158 e-mail from that operation.
4159
4161 SEC processes input data iteratively by reading one line at each itera‐
4162 tion, writing this line into a relevant input buffer, and matching the
4163 content of the updated buffer with rules from configuration files. If
4164 during the matching process an action list is executed which creates
4165 new input events (e.g., through the event action), they are *not* writ‐
4166 ten to buffer(s) immediately, but rather consumed at following itera‐
4167 tions.
4168 Note that when both synthetic events and regular input are available
4170 for processing, synthetic events are always consumed first. When all
4171 synthetic events have been consumed iteratively, SEC will start pro‐
4172 cessing new data from input files.
4173 With the --jointbuf option, SEC employs a joint input buffer for all
4175 input sources which holds N last input lines (the value of N can be set
4176 with the --bufsize option). Updating the input buffer means that the
4177 new line becomes the first element of the buffer, while the last ele‐
4178 ment (the oldest line) is removed from the end of the buffer. With the
4179 --nojointbuf option, SEC maintains a buffer of N lines for each input
4180 file, and if the input line comes from file F, the buffer of F is up‐
4181 dated as described previously. There is also a separate buffer for
4182 synthetic and internal events.
4183 Suppose SEC is started with the following command line
4185 /usr/bin/sec --conf=/etc/sec/test-multiline.conf --jointbuf \
4187 --input=/var/log/prog1.log --input=/var/log/prog2.log
4188 and the configuration file /etc/sec/test-multiline.conf has the follow‐
4190 ing content:
4191 type=Single
4193 rem=this rule matches two consecutive lines where the first \
4194 line contains "test1" and the second line "test2", and \
4195 writes the matching lines to standard output
4196 ptype=RegExp2
4197 pattern=test1.*\n.*test2
4198 desc=two consecutive test lines
4199 action=write - $0
4200 When the following lines appear in input files /var/log/prog1.log and
4202 /var/log/prog2.log
4203 Dec 31 12:33:12 test prog1: test1 (file /var/log/prog1.log)
4205 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
4206 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
4207 Dec 31 12:41:53 test prog2: test2 (file /var/log/prog2.log)
4208 they are stored in a common input buffer. Therefore, rule fires after
4210 the third event has appeared, and writes the following lines to stan‐
4211 dard output:
4212 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
4214 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
4215 However, if SEC is started with the --nojointbuf option, separate input
4217 buffers are set up for /var/log/prog1.log and /var/log/prog2.log.
4218 Therefore, the rule fires after the third event has occurred, and
4219 writes the following lines to standard output:
4220 Dec 31 12:33:12 test prog1: test1 (file /var/log/prog1.log)
4222 Dec 31 12:39:35 test prog1: test2 (file /var/log/prog1.log)
4223 The rule also fires after the fourth event has occurred, producing the
4225 following output:
4226 Dec 31 12:34:09 test prog2: test1 (file /var/log/prog2.log)
4228 Dec 31 12:41:53 test prog2: test2 (file /var/log/prog2.log)
4229 The content of input buffers can be modified with the rewrite action,
4231 and modifications become visible immediately during ongoing event pro‐
4232 cessing iteration. Suppose SEC is started with the following command
4233 line
4234 /usr/bin/sec --conf=/etc/sec/test-rewrite.conf \
4236 --input=- --nojointbuf
4237 and the configuration file /etc/sec/test-rewrite.conf has the following
4239 content:
4240 type=Single
4242 rem=this rule matches two consecutive lines where the first \
4243 line contains "test1" and the second line "test2", and \
4244 joins these lines in the input buffer
4245 ptype=RegExp2
4246 pattern=^(.*test1.*)\n(.*test2.*)$
4247 continue=TakeNext
4248 desc=join two test lines
4249 action=rewrite 2 Joined $1 and $2
4250 type=Single
4252 rem=this rule matches a line which begins with "Joined", \
4253 and writes this line to standard output
4254 ptype=RegExp
4255 pattern=^Joined
4256 desc=output joined lines
4257 action=write - $0
4258 When the following two lines appear in standard input
4260 This is a test1
4262 This is a test2
4263 they are matched by the first rule which uses the rewrite action for
4265 replacing those two lines in the input buffer with a new content. The
4266 last line in the input buffer ("This is a test2") is replaced with
4267 "Joined This is a test1 and This is a test2", while the previous line
4268 in the input buffer ("This is a test1") is replaced with an empty
4269 string. Since the rule contains continue=TakeNext statement, the
4270 matching process will continue from the following rule. This rule
4271 matches the last line in the input buffer if it begins with "Joined",
4272 and writes the line to standard output, producing
4273 Joined This is a test1 and This is a test2
4275 After each event processing iteration, the pattern match cache is
4277 cleared. In other words, if a match is cached with the rule varmap*
4278 field, it is available during ongoing iteration only. Note that re‐
4279 sults from a successful pattern matching are also cached when the sub‐
4280 sequent context expression evaluation yields FALSE. This allows for
4281 reusing results from partial rule matches. For example, the following
4282 rule creates the cache entry "ssh_failed_login" for any SSH failed lo‐
4283 gin event, even if the context ALERTING_ON does not exist:
4284 type=Single
4286 ptype=RegExp
4287 pattern=sshd\[\d+\]: Failed .+ for (\S+) from ([\d.]+) port \d+ ssh2
4288 varmap=ssh_failed_login; user=1; ip=2
4289 context=ALERTING_ON
4290 desc=SSH login failure for user $1 from $2
4291 action=pipe '%s' /bin/mail -s 'SSH login alert' root@localhost
4292 However, provided the context expression does not contain match vari‐
4294 ables, enclosing the expression in square brackets (e.g., [ALERT‐
4295 ING_ON]) forces its evaluation before the pattern matching, and will
4296 thus prevent the matching and the creation of the cache entry if the
4297 evaluation yields FALSE.
4298 Rules from the same configuration file are matched against the buffer
4300 content in the order they are given in that file. When multiple con‐
4301 figuration files have been specified, rule sequences from all files are
4302 matched against the buffer content (unless specified otherwise with Op‐
4303 tions rules). The matching order is determined by the order of config‐
4304 uration files in SEC command line. For example, if the Perl glob()
4305 function returns filenames in ascending ASCII order, and configuration
4306 files /home/risto/A.conf, /home/risto/B.conf2, and /home/risto/C.conf
4307 are specified with --conf=/home/risto/*.conf --conf=/home/risto/*.conf2
4308 in SEC command line, then SEC first matches the input against the rule
4309 sequence from A.conf, then from C.conf, and finally from B.conf2.
4310 Also, note that even if A.conf contains a Suppress rule for a particu‐
4311 lar event, the event is still processed by rulesets in C.conf and
4312 B.conf2. However, note that glob() might return file names in different
4313 order if locale settings change. If you want to enforce a fixed order
4314 for configuration file application in a portable way, it is recommended
4315 to create a unique set for each file with the Options rule, and employ
4316 the Jump rule for defining the processing order for sets, e.g.:
4317 # This rule appears in A.conf
4319 type=Options
4320 joincfset=FileA
4321 procallin=no
4322 # This rule appears in B.conf2
4324 type=Options
4325 joincfset=FileB
4326 procallin=no
4327 # This rule appears in C.conf
4329 type=Options
4330 joincfset=FileC
4331 procallin=no
4332 # This rule appears in main.conf
4334 type=Jump
4335 ptype=TValue
4336 pattern=TRUE
4337 cfset=FileA FileC FileB
4338 After the relevant input buffer has been updated and its content has
4340 been matched by the rules, SEC handles caught signals and checks the
4341 status of child processes. When the timeout specified with the
4342 --cleantime option has expired, SEC also checks the status of contexts
4343 and event correlation operations. Therefore, relatively small values
4344 should be specified with the --cleantime option, in order to retain the
4345 accuracy of the event correlation process. If the --cleantime option
4346 is set to 0, SEC checks event correlation operations and contexts after
4347 processing every input line, but this consumes more CPU time. If the
4348 --poll-timeout option value exceeds the value given with --cleantime,
4349 the --poll-timeout option value takes precedence (i.e., sleeps after
4350 unsuccessful polls will not be shortened).
4351 Finally, note that apart from the sleeps after unsuccessful polls, SEC
4353 measures all time intervals and occurrence times in seconds, and always
4354 uses the time(2) system call for obtaining the current time. Also, for
4355 input event occurrence time SEC always uses the time it observed the
4356 event, *not* the timestamp extracted from the event.
4357
4359 In the action list of a context, the context can also be referred with
4360 the internal context name _THIS. The name _THIS is created and deleted
4361 dynamically by SEC and it points to the context only during its action
4362 list execution. This feature is useful when the context has had sev‐
4363 eral names during its lifetime (created with the alias action), and it
4364 is hard to determine which names exist when the context expires. For
4365 example, if the context is created with create A 60 (report A /bin/mail
4366 root) which is immediately followed by alias A B and unalias A, the re‐
4367 port action will fail since the name A no longer refers to the context.
4368 However, replacing the first action with create A 60 (report _THIS
4369 /bin/mail root) will produce the correct result.
4370 If the --intevents command line option is given, SEC will generate in‐
4372 ternal events when it is started up, when it receives certain signals,
4373 and when it terminates normally. Inside SEC, internal event is treated
4374 as if it was a line that was read from a SEC input file. Specific
4375 rules can be written to match internal events, in order to take some
4376 action (e.g., start an external event correlation module with spawn
4377 when SEC starts up). The following internal events are supported:
4378 SEC_STARTUP - generated when SEC is started (this event will always be
4380 the first event that SEC sees)
4381 SEC_PRE_RESTART - generated before processing of the SIGHUP signal
4383 (this event will be the last event that SEC sees before clearing all
4384 internal data structures and reloading its configuration)
4385 SEC_RESTART - generated after processing of the SIGHUP signal (this
4387 event will be the first event that SEC sees after clearing all internal
4388 data structures and reloading its configuration)
4389 SEC_PRE_SOFTRESTART - generated before processing of the SIGABRT signal
4391 (this event will be the last event that SEC sees before reloading its
4392 configuration)
4393 SEC_SOFTRESTART - generated after processing of the SIGABRT signal
4395 (this event will be the first event that SEC sees after reloading its
4396 configuration)
4397 SEC_PRE_LOGROTATE - generated before processing of the SIGUSR2 signal
4399 (this event will be the last event that SEC sees before reopening its
4400 log file and closing its outputs)
4401 SEC_LOGROTATE - generated after processing of the SIGUSR2 signal (this
4403 event will be the first event that SEC sees after reopening its log
4404 file and closing its outputs)
4405 SEC_SHUTDOWN - generated when SEC receives the SIGTERM signal, or when
4407 SEC reaches all EOFs of input files after being started with the --no‐
4408 tail option. With the --childterm option, SEC sleeps for 3 seconds af‐
4409 ter generating SEC_SHUTDOWN event, and then sends SIGTERM to its child
4410 processes (if a child process was triggered by SEC_SHUTDOWN, this delay
4411 leaves the process enough time for setting a signal handler for
4412 SIGTERM).
4413 Before generating an internal event, SEC sets up a context named
4415 SEC_INTERNAL_EVENT, in order to disambiguate internal events from regu‐
4416 lar input. The SEC_INTERNAL_EVENT context is deleted immediately after
4417 the internal event has been matched against all rules.
4418 If the --intcontexts command line option is given, or there is an --in‐
4420 put option with a context specified, SEC creates an internal context
4421 each time it reads a line from an input file or a synthetic event. The
4422 internal context is deleted immediately after the line has been matched
4423 against all rules. For all input files that have the context name ex‐
4424 plicitly set with --input=<file_pattern>=<context>, the name of the in‐
4425 ternal context is <context>. If the line was read from the input file
4426 <filename> for which there is no context name set, the name of the in‐
4427 ternal context is _FILE_EVENT_<filename>. For synthetic events, the
4428 name of the internal context defaults to _INTERNAL_EVENT, but cspawn
4429 and cevent actions can be used for generating synthetic events with
4430 custom internal context names. This allows for writing rules that match
4431 data from one particular input source only. For example, the rule
4432 type=Suppress
4434 ptype=TValue
4435 pattern=TRUE
4436 context=[!_FILE_EVENT_/dev/logpipe]
4437 passes only the lines that were read from /dev/logpipe, and also syn‐
4439 thetic events that were generated with the _FILE_EVENT_/dev/logpipe in‐
4440 ternal context (e.g., with the action cevent _FILE_EVENT_/dev/logpipe 0
4441 This is a test event). As another example, if SEC has been started
4442 with the command line
4443 /usr/bin/sec --intevents --intcontexts --conf=/etc/sec/my.conf \
4445 --input=/var/log/messages=MESSAGES \
4446 --input=/var/log/secure=SECURE \
4447 --input=/var/log/cron=CRON
4448 and the rule file /etc/sec/my.conf contains the following rules
4450 type=Single
4452 ptype=RegExp
4453 pattern=^(?:SEC_STARTUP|SEC_RESTART)$
4454 context=[SEC_INTERNAL_EVENT]
4455 desc=listen on 10514/tcp for incoming events
4456 action=cspawn MESSAGES /usr/bin/nc -l -k 10514
4457 type=Single
4459 ptype=RegExp
4460 pattern=.
4461 context=[MESSAGES]
4462 desc=echo everything from 10514/tcp and /var/log/messages
4463 action=write - $0
4464 then SEC will receive input lines from the log files /var/log/messages,
4466 /var/log/secure, and /var/log/cron, and will also run /usr/bin/nc for
4467 receiving input lines from the port 10514/tcp. All input lines from
4468 /var/log/messages and 10514/tcp are matched by the second rule and
4469 written to standard output.
4470
4472 The SingleWithScript rule and shellcmd, spawn, cspawn, cmdexec,
4473 spawnexec, cspawnexec, pipe, pipeexec, report, and reportexec actions
4474 fork a child process for executing an external program. For the Sin‐
4475 gleWithScript rule with shell=yes setting and for shellcmd, spawn,
4476 cspawn, pipe, and report actions, the following rule applies -- if the
4477 program command line contains shell metacharacters, the command line is
4478 first parsed by the shell which then starts the program. For the Sin‐
4479 gleWithScript rule with shell=no setting and for cmdexec, spawnexec,
4480 cspawnexec, pipeexec, and reportexec actions, the program command line
4481 is not parsed by shell, even if shell metacharacters are present in the
4482 command line.
4483 Disabling shell parsing for command lines can be useful for avoiding
4485 unwanted side effects. For example, consider the following badly writ‐
4486 ten rule for sending an e-mail to a local user if 10 SSH login failures
4487 have been observed for this user from the same IP address during 300
4488 seconds:
4489 type=SingleWithThreshold
4491 ptype=RegExp
4492 pattern=sshd\[\d+\]: Failed .+ for (.+) from ([\d.]+) port \d+ ssh2
4493 desc=Failed SSH logins for user $1 from $2
4494 action=pipe 'Failed SSH logins from $2' /bin/mail -s alert $1
4495 window=300
4496 thresh=10
4497 Unfortunately, the above rule allows for the execution of arbitrary
4499 command lines with the privileges of the SEC process. For example,
4500 consider the following malicious command line for providing fake input
4501 events for the rule:
4502 logger -p authpriv.info -t sshd -i 'Failed password for `/usr/bin/touch
4504 /tmp/test` from 127.0.0.1 port 12345 ssh2'
4505 When this command line is repeatedly executed, the attacker is able to
4507 trigger the execution of the command line /bin/mail -s alert
4508 `/usr/bin/touch /tmp/test`. However, this command line is parsed by
4509 shell that triggers the execution of the command line specified by the
4510 attacker: /usr/bin/touch /tmp/test. For fixing this issue, the pipe
4511 action can be replaced with pipeexec which will disable the shell pars‐
4512 ing:
4513 action=pipeexec 'Failed SSH logins from $2' /bin/mail -s alert $1
4515 As another workaround, the regular expression pattern of the rule can
4517 be modified to match user names that do not contain shell metacharac‐
4518 ters, for example:
4519 pattern=sshd\[\d+\]: Failed .+ for ([\w.-]+) from ([\d.]+) port \d+
4521 ssh2
4522 SEC communicates with its child processes through pipes (created with
4524 the pipe(2) system call). When the child process is at the read end of
4525 the pipe, data have to be written to the pipe in blocking mode which
4526 ensures reliable data transmission. In order to avoid being blocked,
4527 SEC forks another SEC process for writing data to the pipe reliably.
4528 The newly created SEC process will then fork the child process, manag‐
4529 ing the child process on behalf of the main SEC process (i.e., the main
4530 SEC process is the grandparent process for the child). For example, if
4531 the SEC process that manages the child receives the SIGTERM signal, the
4532 signal will be forwarded to the child process, and when the child
4533 process terminates, its exit code will be reported to the main SEC
4534 process.
4535 After forking an external program, SEC continues immediately, and
4537 checks the program status periodically until the program exits. The
4538 running time of a child process is not limited in any way. With the
4539 --childterm option, SEC sends the SIGTERM signal to all child processes
4540 when it terminates. If some special exit procedures need to be accom‐
4541 plished in the child process (or the child wishes to ignore SIGTERM),
4542 then the child must install a handler for the SIGTERM signal. Note
4543 that if the program command line is parsed by shell, the parsing shell
4544 will run as a child process of SEC and the parent process of the pro‐
4545 gram. Therefore, the SIGTERM signal will be sent to the shell, *not*
4546 the program. In order to avoid this, the shell's builtin exec command
4547 can be used (see sh(1) for more information) which replaces the shell
4548 with the program without forking a new process, e.g.,
4549 action=spawn exec /usr/local/bin/myscript.pl 2>/var/log/myscript.log
4551 Note that if an action list includes two actions which fork external
4553 programs, the execution order these programs is not determined by the
4554 order of actions in the list, since both programs are running asyn‐
4555 chronously. In order to address this issue, the execution order must
4556 be specified explicitly (e.g., instead of writing action=shellcmd cmd1;
4557 shellcmd cmd2, use the shell && operator and write action=shellcmd cmd1
4558 && cmd2).
4559 Sometimes it is desirable to start an external program and provide it
4561 with data from several rules. In order to create such setup, named
4562 pipes can be harnessed. For example, if /var/log/pipe is a named pipe,
4563 then
4564 action=shellcmd /usr/bin/logger -f /var/log/pipe -p user.notice
4566 starts the /usr/bin/logger utility which sends all lines read from
4568 /var/log/pipe to the local syslog daemon with the "user" facility and
4569 "notice" level. In order to feed events to /usr/bin/logger, the write
4570 action can be used (e.g., write /var/log/pipe This is my event). Al‐
4571 though SEC keeps the named pipe open across different write actions,
4572 the pipe will be closed on the reception of SIGHUP, SIGABRT and SIGUSR2
4573 signals. Since many UNIX tools terminate on receiving EOF from stan‐
4574 dard input, they need restarting after such signals have arrived. For
4575 this purpose, the --intevents option and SEC internal events can be
4576 used. For example, the following rule starts the /usr/bin/logger util‐
4577 ity at SEC startup, and also restarts it after the reception of rele‐
4578 vant signals:
4579 type=Single
4581 ptype=RegExp
4582 pattern=^(?:SEC_STARTUP|SEC_RESTART|SEC_SOFTRESTART|SEC_LOGROTATE)$
4583 context=SEC_INTERNAL_EVENT
4584 desc=start the logger tool
4585 action=free %emptystring; owritecl /var/log/pipe %emptystring; \
4586 shellcmd /usr/bin/logger -f /var/log/pipe -p user.notice
4587 Note that if /var/log/pipe is never opened for writing by a write ac‐
4589 tion, /usr/bin/logger will never see EOF and will thus not terminate.
4590 The owritecl action opens and closes /var/log/pipe without writing any
4591 bytes, in order to ensure the presence of EOF in such cases. This al‐
4592 lows any previous /usr/bin/logger process to terminate before the new
4593 process is started.
4594
4596 SEC supports patterns, context expressions, and actions which involve
4597 calls to the Perl eval() function or the execution of precompiled Perl
4598 code. The use of Perl code in SEC patterns and context expressions al‐
4599 lows for creating proper match conditions for scenarios which can't be
4600 handled by a simple regular expression match. For example, consider the
4601 following iptables syslog events:
4602 May 27 10:00:15 box1 kernel: iptables: IN=eth0 OUT=
4604 MAC=08:00:27:be:9e:2f:00:10:db:ff:20:03:08:00 SRC=10.6.4.14
4605 DST=10.1.8.2 LEN=84 TOS=0x00 PREC=0x00 TTL=251 ID=61426 PROTO=ICMP
4606 TYPE=8 CODE=0 ID=11670 SEQ=2
4607 May 27 10:02:22 box1 kernel: iptables: IN=eth0 OUT=
4608 MAC=08:00:27:be:9e:2f:00:10:db:ff:20:03:08:00 SRC=10.6.4.14
4609 DST=10.1.8.2 LEN=52 TOS=0x00 PREC=0x00 TTL=60 ID=61441 DF PROTO=TCP
4610 SPT=53125 DPT=23 WINDOW=49640 RES=0x00 SYN URGP=0
4611 Depending on the protocol and the nature of the traffic, events can
4613 have a wide variety of fields, and parsing out all event data with one
4614 regular expression is infeasible. For addressing this issue, a PerlFunc
4615 pattern can be used which creates match variables from all fields of
4616 the matching event, stores them in one Perl hash, and returns a refer‐
4617 ence to this hash. Outside the PerlFunc pattern, match variables are
4618 initialized from the key-value pairs in the returned hash. Suppose the
4619 following Jump rule with a PerlFunc pattern is defined in the
4620 main.rules rule file:
4621 type=Jump
4623 ptype=PerlFunc
4624 pattern=sub { my(%var); my($line) = $_[0]; \
4625 if ($line !~ /kernel: iptables:/g) { return 0; } \
4626 while ($line =~ /\G\s*([A-Z]+)(?:=(\S*))?/g) { \
4627 $var{$1} = defined($2)?$2:1; \
4628 } return \%var; }
4629 varmap=IPTABLES
4630 desc=parse iptables event
4631 cfset=iptables
4632 For example, if the iptables event contains the fields SRC=10.6.4.14,
4634 DST=10.1.8.2 and SYN, the above PerlFunc pattern sets up match variable
4635 $+{SRC} which holds 10.6.4.14, match variable $+{DST} which holds
4636 10.1.8.2, and match variable $+{SYN} which holds 1. The Jump rule
4637 caches all created match variables under the name IPTABLES, and submits
4638 the matching event to iptables ruleset for further processing. Suppose
4639 the iptables ruleset is defined in the iptables.rules rule file:
4640 type=Options
4642 procallin=no
4643 joincfset=iptables
4644 type=SingleWithThreshold
4646 ptype=Cached
4647 pattern=IPTABLES
4648 context=IPTABLES :> ( sub { return $_[0]->{"PROTO"} eq "ICMP"; } )
4649 desc=ICMP flood type $+{TYPE} code $+{CODE} from host $+{SRC}
4650 action=logonly
4651 window=10
4652 thresh=100
4653 type=SingleWithThreshold
4655 ptype=Cached
4656 pattern=IPTABLES
4657 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
4658 exists($_[0]->{"FIN"}) ; } )
4659 desc=SYN+FIN flood from host $+{SRC}
4660 action=logonly
4661 window=10
4662 thresh=100
4663 The two SingleWithThreshold rules employ Cached patterns for matching
4665 iptables events by looking up the IPTABLES entry in the pattern match
4666 cache (created by the above Jump rule for each iptables event). In or‐
4667 der to narrow down the match to specific iptables events, the rules em‐
4668 ploy precompiled Perl functions in context expressions. The :> opera‐
4669 tor is used for speeding up the matching, providing the function with a
4670 single parameter which refers to the hash of variable name-value pairs
4671 for the IPTABLES cache entry.
4672 The first SingleWithThreshold rule logs a warning message if within 10
4674 seconds 100 iptables events have been observed for ICMP packets with
4675 the same type, code, and source IP address. The second SingleWith‐
4676 Threshold rule logs a warning message if within 10 seconds 100 iptables
4677 events have been observed for TCP packets coming from the same host,
4678 and having both SYN and FIN flag set in each packet.
4679 Apart from using action list variables for data sharing between rules,
4681 Perl variables created in Perl code can be employed for the same pur‐
4682 pose. For example, when SEC has executed the following action
4683 action=eval %a ($b = 1)
4685 the variable $b and its value become visible in the following context
4687 expression
4688 context= =(++$b > 10)
4690 (with that expression one can implement event counting implicitly). In
4692 order to avoid possible clashes with variables inside the SEC code it‐
4693 self, user-defined Perl code is executed in the main::SEC namespace
4694 (i.e., inside the special package main::SEC). By using the main:: pre‐
4695 fix, SEC data structures can be accessed and modified. For example,
4696 the following rules restore and save contexts with names MY_* on SEC
4697 startup and shutdown, using Perl Storable module for saving and restor‐
4698 ing relevant elements of %main::context_list hash (since the following
4699 example does not handle code references with Storable module, it is as‐
4700 sumed that context action lists do not contain lcall actions):
4701 type=Single
4703 ptype=SubStr
4704 pattern=SEC_STARTUP
4705 context=SEC_INTERNAL_EVENT
4706 continue=TakeNext
4707 desc=Load the Storable module and terminate if it is not found
4708 action=eval %ret (require Storable); \
4709 if %ret ( logonly Storable loaded ) else ( eval %o exit(1) )
4710 type=Single
4712 ptype=SubStr
4713 pattern=SEC_STARTUP
4714 context=SEC_INTERNAL_EVENT
4715 desc=Restore contexts MY_* from /var/lib/sec/SEC_CONTEXTS on startup
4716 action=lcall %ret -> ( sub { my($ref, $context); \
4717 $ref = Storable::retrieve("/var/lib/sec/SEC_CONTEXTS"); \
4718 foreach $context (keys %{$ref}) { \
4719 if ($context =~ /^MY_/) \
4720 { $main::context_list{$context} = $ref->{$context}; } } } )
4721 type=Single
4723 ptype=SubStr
4724 pattern=SEC_SHUTDOWN
4725 context=SEC_INTERNAL_EVENT
4726 desc=Save contexts MY_* into /var/lib/sec/SEC_CONTEXTS on shutdown
4727 action=lcall %ret -> ( sub { my($context, %hash); \
4728 foreach $context (keys %main::context_list) { \
4729 if ($context =~ /^MY_/) \
4730 { $hash{$context} = $main::context_list{$context}; } } \
4731 Storable::store(\%hash, "/var/lib/sec/SEC_CONTEXTS"); } )
4732 However, note that modifying data structures within SEC code is recom‐
4734 mended only for advanced users who have carefully studied relevant
4735 parts of the code.
4736 Finally, sometimes larger chunks of Perl code have to be used for event
4738 processing and correlation. However, writing many lines of code di‐
4739 rectly into a rule is cumbersome and may decrease its readability. In
4740 such cases it is recommended to separate the code into a custom Perl
4741 module which is loaded at SEC startup, and use the code through the
4742 module interface (see perlmod(1) for further details):
4743 type=Single
4745 ptype=SubStr
4746 pattern=SEC_STARTUP
4747 context=SEC_INTERNAL_EVENT
4748 desc=Load the SecStuff module
4749 action=eval %ret (require '/usr/local/sec/SecStuff.pm'); \
4750 if %ret ( none ) else ( eval %o exit(1) )
4751 type=Single
4753 ptype=PerlFunc
4754 pattern=sub { return SecStuff::my_match($_[0]); }
4755 desc=event '$0' was matched by my_match()
4756 action=write - %s
4757
4759 Example 1 - a ruleset for Cisco events
4760 This section presents an example rulebase for managing Cisco devices.
4761 It is assumed that the managed devices have syslog logging enabled, and
4762 that all syslog messages are sent to a central host and written to log
4763 file(s) that are monitored by SEC.
4764 # Set up contexts NIGHT and WEEKEND for nights
4766 # and weekends. The context NIGHT has a lifetime
4767 # of 8 hours and the context WEEKEND 2 days
4768 type=Calendar
4770 time=0 23 * * *
4771 desc=NIGHT
4772 action=create %s 28800
4773 type=Calendar
4775 time=0 0 * * 6
4776 desc=WEEKEND
4777 action=create %s 172800
4778 # If a router does not come up within 5 minutes
4780 # after it was rebooted, generate event
4781 # "<router> REBOOT FAILURE". The next rule matches
4782 # this event, checks the router with ping and sends
4783 # a notification if there is no response.
4784 type=PairWithWindow
4786 ptype=RegExp
4787 pattern=\s([\w.-]+) \d+: %SYS-5-RELOAD
4788 desc=$1 REBOOT FAILURE
4789 action=event %s
4790 ptype2=RegExp
4791 pattern2=\s$1 \d+: %SYS-5-RESTART
4792 desc2=%1 successful reboot
4793 action2=logonly
4794 window=300
4795 type=SingleWithScript
4797 ptype=RegExp
4798 pattern=^([\w.-]+) REBOOT FAILURE
4799 script=/bin/ping -c 3 -q $1
4800 desc=$1 did not come up after reboot
4801 action=logonly $1 is pingable after reboot
4802 action2=pipe '%t: %s' /bin/mail root@localhost
4803 # Send a notification if CPU load of a router is too
4805 # high (two CPUHOG messages are received within 5
4806 # minutes); send another notification if the load is
4807 # normal again (no CPUHOG messages within last 15
4808 # minutes). Rule is not active at night or weekend.
4809 type=SingleWith2Thresholds
4811 ptype=RegExp
4812 pattern=\s([\w.-]+) \d+: %SYS-3-CPUHOG
4813 context=!(NIGHT || WEEKEND)
4814 desc=$1 CPU overload
4815 action=pipe '%t: %s' /bin/mail root@localhost
4816 window=300
4817 thresh=2
4818 desc2=$1 CPU load normal
4819 action2=pipe '%t: %s' /bin/mail root@localhost
4820 window2=900
4821 thresh2=0
4822 # If a router interface is in down state for less
4824 # than 15 seconds, generate event
4825 # "<router> INTERFACE <interface> SHORT OUTAGE";
4826 # otherwise generate event
4827 # "<router> INTERFACE <interface> DOWN".
4828 type=PairWithWindow
4830 ptype=RegExp
4831 pattern=\s([\w.-]+) \d+: %LINK-3-UPDOWN: Interface ([\w.-]+), changed
4832 state to down
4833 desc=$1 INTERFACE $2 DOWN
4834 action=event %s
4835 ptype2=RegExp
4836 pattern2=\s$1 \d+: %LINK-3-UPDOWN: Interface $2, changed state to up
4837 desc2=%1 INTERFACE %2 SHORT OUTAGE
4838 action2=event %s
4839 window=15
4840 # If "<router> INTERFACE <interface> DOWN" event is
4842 # received, send a notification and wait for
4843 # "interface up" event from the same router interface
4844 # for the next 24 hours
4845 type=Pair
4847 ptype=RegExp
4848 pattern=^([\w.-]+) INTERFACE ([\w.-]+) DOWN
4849 desc=$1 interface $2 is down
4850 action=pipe '%t: %s' /bin/mail root@localhost
4851 ptype2=RegExp
4852 pattern2=\s$1 \d+: %LINK-3-UPDOWN: Interface $2, changed state to up
4853 desc2=%1 interface %2 is up
4854 action2=pipe '%t: %s' /bin/mail root@localhost
4855 window=86400
4856 # If ten "short outage" events have been observed
4858 # in the window of 6 hours, send a notification
4859 type=SingleWithThreshold
4861 ptype=RegExp
4862 pattern=^([\w.-]+) INTERFACE ([\w.-]+) SHORT OUTAGE
4863 desc=Interface $2 at node $1 is unstable
4864 action=pipe '%t: %s' /bin/mail root@localhost
4865 window=21600
4866 thresh=10
4867 Example 2 - hierarchically organized rulesets for iptables and sshd events
4869 This section presents an example of hierarchically organized rules for
4870 processing Linux iptables events from /var/log/messages and SSH login
4871 events from /var/log/secure. It is assumed that all rule files reside
4872 in the /etc/sec directory and that the rule hierarchy has two levels.
4873 The file /etc/sec/main.rules contains first-level Jump rules for match‐
4874 ing and parsing events from input files and submitting them to proper
4875 rulesets for further processing. All other rule files in the /etc/sec
4876 directory contain second-level rules which receive their input from
4877 first-level Jump rules. Also, the example assumes that SEC is started
4878 with the following command line:
4879 /usr/bin/sec --conf=/etc/sec/*.rules --intcontexts \
4881 --input=/var/log/messages --input=/var/log/secure
4882 #
4884 # the content of /etc/sec/main.rules
4885 #
4886 type=Jump
4888 context=[ _FILE_EVENT_/var/log/messages ]
4889 ptype=PerlFunc
4890 pattern=sub { my(%var); my($line) = $_[0]; \
4891 if ($line !~ /kernel: iptables:/g) { return 0; } \
4892 while ($line =~ /\G\s*([A-Z]+)(?:=(\S*))?/g) { \
4893 $var{$1} = defined($2)?$2:1; \
4894 } return \%var; }
4895 varmap=IPTABLES
4896 desc=parse iptables events and direct to relevant ruleset
4897 cfset=iptables
4898 type=Jump
4900 context=[ _FILE_EVENT_/var/log/secure ]
4901 ptype=RegExp
4902 pattern=sshd\[(?<pid>\d+)\]: (?<status>Accepted|Failed) \
4903 (?<authmethod>[\w-]+) for (?<invuser>invalid user )?\
4904 (?<user>[\w-]+) from (?<srcip>[\d.]+) port (?<srcport>\d+) ssh2$
4905 varmap=SSH_LOGIN
4906 desc=parse SSH login events and direct to relevant ruleset
4907 cfset=ssh-login
4908 type=Jump
4910 context=[ SSH_EVENT ]
4911 ptype=TValue
4912 pattern=True
4913 desc=direct SSH synthetic events to relevant ruleset
4914 cfset=ssh-events
4915 #
4917 # the content of /etc/sec/iptables.rules
4918 #
4919 type=Options
4921 procallin=no
4922 joincfset=iptables
4923 type=SingleWithThreshold
4925 ptype=Cached
4926 pattern=IPTABLES
4927 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
4928 exists($_[0]->{"FIN"}) ; } ) \
4929 && !SUPPRESS_IP_$+{SRC}
4930 desc=SYN+FIN flood from host $+{SRC}
4931 action=pipe '%t: %s' /bin/mail -s 'iptables alert' root@localhost; \
4932 create SUPPRESS_IP_$+{SRC} 3600
4933 window=10
4934 thresh=100
4935 type=SingleWithThreshold
4937 ptype=Cached
4938 pattern=IPTABLES
4939 context=IPTABLES :> ( sub { return exists($_[0]->{"SYN"}) && \
4940 !exists($_[0]->{"ACK"}) ; } ) \
4941 && !SUPPRESS_IP_$+{SRC}
4942 desc=SYN flood from host $+{SRC}
4943 action=pipe '%t: %s' /bin/mail -s 'iptables alert' root@localhost; \
4944 create SUPPRESS_IP_$+{SRC} 3600
4945 window=10
4946 thresh=100
4947 #
4949 # the content of /etc/sec/ssh-login.rules
4950 #
4951 type=Options
4953 procallin=no
4954 joincfset=ssh-login
4955 type=Single
4957 ptype=Cached
4958 pattern=SSH_LOGIN
4959 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed" && \
4960 $_[0]->{"srcport"} < 1024 && \
4961 defined($_[0]->{"invuser"}); } )
4962 continue=TakeNext
4963 desc=Probe of invalid user $+{user} from privileged port of $+{srcip}
4964 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
4965 type=SingleWithThreshold
4967 ptype=Cached
4968 pattern=SSH_LOGIN
4969 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed" && \
4970 defined($_[0]->{"invuser"}); } )
4971 desc=Ten login probes for invalid users from $+{srcip} within 60s
4972 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
4973 thresh=10
4974 window=60
4975 type=PairWithWindow
4977 ptype=Cached
4978 pattern=SSH_LOGIN
4979 context=SSH_LOGIN :> ( sub { return $_[0]->{"status"} eq "Failed"; } )
4980 desc=User $+{user} failed to log in from $+{srcip} within 60s
4981 action=cevent SSH_EVENT 0 %s
4982 ptype2=Cached
4983 pattern2=SSH_LOGIN
4984 context2=SSH_LOGIN :> \
4985 ( sub { return $_[0]->{"status"} eq "Accepted"; } ) && \
4986 $+{user} %+{user} $+{srcip} %+{srcip} -> \
4987 ( sub { return $_[0] eq $_[1] && $_[2] eq $_[3]; } )
4988 desc2=User $+{user} logged in successfully from $+{srcip} within 60s
4989 action2=logonly
4990 window=60
4991 #
4993 # the content of /etc/sec/ssh-events.rules
4994 #
4995 type=Options
4997 procallin=no
4998 joincfset=ssh-events
4999 type=SingleWithThreshold
5001 ptype=RegExp
5002 pattern=User ([\w-]+) failed to log in from [\d.]+ within 60s
5003 desc=Ten login failures for user $1 within 1h
5004 action=pipe '%t: %s' /bin/mail -s 'SSH alert' root@localhost
5005 thresh=10
5006 window=3600
5007
5009 If the SECRC environment variable is set, SEC expects it to contain the
5010 name of its resource file. Resource file lines which are empty or which
5011 begin with the number sign (#) are ignored (whitespace may precede #).
5012 Each remaining line is appended to the argv array of SEC as a *single*
5013 element. Also, the lines are appended to argv in the order they appear
5014 in the resource file. Therefore, if the SEC command line option has a
5015 value, the option name and the value must either be separated by the
5016 equal sign (=) or a newline. Here is a simple resource file example:
5017 # read events from standard input
5019 --input=-
5020 # rules are stored in /etc/sec/test.conf
5022 --conf
5023 /etc/sec/test.conf
5024 Note that although SEC rereads its resource file at the reception of
5026 the SIGHUP or SIGABRT signal, adding an option that specifies a certain
5027 startup procedure (e.g., --pid or --detach) will not produce the de‐
5028 sired effect at runtime. Also note that the resource file content is
5029 *not* parsed by shell, therefore shell metacharacters are passed to SEC
5030 as-is.
5031
5033 SIGHUP full restart -- SEC will reinterpret its command line and re‐
5034 source file options, reopen its log and input files, close its
5035 output files and sockets (these will be reopened on demand),
5036 reload its configuration, and drop *all* event correlation state
5037 (all event correlation operations will be terminated, all con‐
5038 texts will be deleted, all action list variables will be erased,
5039 etc.). With the --childterm option, SEC will also send the
5040 SIGTERM signal to its child processes.
5041 SIGABRT
5043 soft restart -- SEC will reinterpret its command line and re‐
5044 source file options, reopen its log file, and close its output
5045 files and sockets (these will be reopened on demand). If the
5046 --keepopen option is specified, previously opened input files
5047 will remain open across soft restart, otherwise all input files
5048 will be reopened. SEC will (re)load configuration from rule
5049 files which have been modified (file modification time returned
5050 by stat(2) has changed) or created after the previous configura‐
5051 tion load. SEC will also terminate event correlation operations
5052 started from rule files that have been modified or removed after
5053 the previous configuration load. Other operations and previ‐
5054 ously loaded configuration from unmodified rule files will re‐
5055 main intact. Note that on some systems SIGIOT is used in place
5056 of SIGABRT.
5057 SIGUSR1
5059 detailed information about the current state of SEC (performance
5060 and rule matching statistics, running event correlation opera‐
5061 tions, created contexts, etc.) will be written to the SEC dump
5062 file.
5063 SIGUSR2
5065 SEC will reopen its log file (useful for log file rotation), and
5066 also close its output files and sockets which will be reopened
5067 on demand.
5068 SIGINT SEC will increase its logging level by one; if the current level
5070 is 6, the level will be set back to 1. Please note this feature
5071 is available only if SEC is running non-interactively (e.g., in
5072 daemon mode).
5073 SIGTERM
5075 SEC will terminate gracefully. With the --childterm option, all
5076 SEC child processes will receive SIGTERM.
5077
5079 With some locale settings, single quotes (') in this man page might be
5080 displayed incorrectly. As a workaround, set the LANG environment vari‐
5081 able to C when reading this man page (e.g., env LANG=C man sec).
5082
5084 Risto Vaarandi (ristov at users d0t s0urcef0rge d0t net)
5085
5087 The author is grateful to SEB Estonia for supporting this work. The
5088 author also thanks the following people for supplying software patches,
5089 documentation fixes, and suggesting new features: Al Sorrell, Brian
5090 Mielke, David Lang, James Brown, Jon Frazier, Mark D. Nagel, Peter
5091 Eckel, Rick Casey, and William Gertz. Last but not least, the author
5092 expresses his profound gratitude to John P. Rouillard for many great
5093 ideas and creative discussions that have helped to develop SEC.
5094
5096 cron(8), crontab(1), execvp(3), fork(2), mail(1), perl(1), perlmod(1),
5097 perlre(1), pipe(2), sh(1), snmptrap(1), stat(2), strftime(3), sys‐
5098 log(3), time(2), umask(2)
5099SEC 2.9.0 May 2021 sec(1)