1sec(1)                      General Commands Manual                     sec(1)
2
3
4

NAME

6       sec - simple event correlator
7

SYNOPSIS

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

DESCRIPTION

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
60       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
71       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
75       /usr/bin/sec --detach --conf=/etc/sec/syslog.rules \
76                    --input=/var/log/messages
77
78       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
84       /usr/bin/nc -l 8080 | /usr/bin/sec --notail --input=- \
85                                          --conf=/etc/sec/my.conf
86
87       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
91       /usr/bin/sec --conf=/etc/sec/sshd.rules --input=/var/log/secure
92
93       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
97       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
105       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
110       Dec 16 16:24:59 myserver sshd[13685]: Failed password  for  risto  from
111       10.12.2.5 port 41063 ssh2
112
113       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
136       /bin/mail -s 'SSH login alert' root@localhost
137
138       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
147       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
157       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
165       and the event
166
167       Dec  16  16:24:59  myserver sshd[13685]: Failed password for risto from
168       10.12.2.5 port 41063 ssh2
169
170       is the first matching event for the above rule, this event will trigger
171       a new event correlation operation with the ID
172
173       /etc/sec/sshd.rules  |  0 | Three SSH login failures within 1m for user
174       risto
175
176       (0 is the number assigned to the first rule in the file, see EVENT COR‐
177       RELATION OPERATIONS section for more information).
178
179       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
183       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
191       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
202       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
231       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

OPTIONS

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
245       --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
262       --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
274       --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
283       --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
290       --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
295       --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
300       --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
305       --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
315       --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
319       --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
326       --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
331       --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
338       --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
359       --pid=<pidfile>
360              SEC will store its process ID to <pidfile> at startup.
361
362       --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
369       --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
379       --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
386       --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
391       --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
396       --dumpfjson, --nodumpfjson
397              if the --dumpfjson option is specified, dump file is produced in
398              JSON format.  Default is --nodumpfjson.
399
400       --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
409       --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
425       --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
432       --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
439       --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
454       --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
462       --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
474       --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
479       --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
487       --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
494       --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
500       --help, -?
501              SEC will output usage information and exit.
502
503       --version
504              SEC will output version information and exit.
505
506       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

CONFIGURATION FILES

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
526       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
545       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
552       The points-of-continue are defined with continue* fields. Accepted val‐
553       ues for these fields are:
554
555       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
559       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
565       DontCont (default value)
566              after an event has matched the rule, search for  matching  rules
567              ends in the *current* configuration file.
568
569       EndMatch
570              after  an  event has matched the rule, search for matching rules
571              ends for *all* configuration files.
572
573       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
577       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
585       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
593       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
601       label=lastRule
602
603       type=Single
604       ptype=SubStr
605       pattern=DDD
606       desc=Three D characters
607       action=write - three D characters were observed
608
609       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
618       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
622       /usr/bin/sec --input=- \
623                    --conf=/etc/sec/sec1.rules --conf=/etc/sec/sec2.rules
624
625       and  the  configuration file /etc/sec/sec1.rules has the following con‐
626       tent:
627
628       type=Single
629       ptype=SubStr
630       pattern=AAA
631       desc=Three A characters
632       action=write - three A characters were observed
633
634       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
641       Also, suppose the  configuration file /etc/sec/sec2.rules has the  fol‐
642       lowing content:
643
644       type=Single
645       ptype=SubStr
646       pattern=CCC
647       desc=Three C characters
648       action=write - three C characters were observed
649
650       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

PATTERNS, PATTERN TYPES AND MATCH VARIABLES

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
678       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
690              ptype=substr
691              pattern=Backup done:\tsuccess
692
693              The pattern matches lines containing "Backup done:<TAB>success".
694
695              Note that since the SubStr[N] pattern type has been designed for
696              fast matching, it does not support match variables.
697
698       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
707              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
721              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
726              ptype=RegExp
727              pattern=sshd\[\d+\]: Connection from (?<ip>[\d.]+) port (\d+)
728
729              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
734              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
747              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
760              For example, consider the following pattern definition:
761
762              ptype=regexp
763              pattern=(?i)(\S+\.mydomain).*printer: toner\/ink low
764              varmap=printer_toner_or_ink_low; message=0; hostname=1
765
766              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
777              The  following  pattern  definition produces a match if the last
778              two input lines are AAA and BBB:
779
780              ptype=regexp2
781              pattern=^AAA\nBBB$
782              varmap=aaa_bbb
783
784              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
788              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
793       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
803              function(L1, L2, ..., LN, F1, F2, ..., FN)
804
805              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
809              function(L1, L2, ..., LN, F)
810
811              Also note that if the input line is a synthetic event, the input
812              file name is Perl undefined value.
813
814              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
827              ptype=perlfunc2
828              pattern=sub { return ($_[0] cmp $_[1]); }
829
830              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
840              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
846              ptype=perlfunc
847              pattern=sub { return ("abc", "def", "ghi"); }
848
849              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
856              ptype=perlfunc
857              pattern=sub { if (defined($_[1]) && $_[0] =~ /abc|def/) \
858              { return $_[1]; } return 0; }
859              varmap= file=1
860
861              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
869              ptype=perlfunc
870              pattern=sub { my(%hash); \
871              if ($_[0] !~ /three|four/) { return 0; } \
872              $hash{"three"} = 3; $hash{"four"} = 4; return \%hash; }
873
874       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
881              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
886              then the entry "abc_or_def_found"  is  created  in  the  pattern
887              match cache.  Therefore, the pattern
888
889              ptype=cached
890              pattern=abc_or_def_found
891
892              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
896       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
900       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
906       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
912       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
916       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
921       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
931       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
937       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
945       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
955       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
964       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
968       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

CONTEXTS AND CONTEXT EXPRESSIONS

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
981       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
988       Contexts can be used for event aggregation and reporting.  Suppose  the
989       following actions are executed in this order:
990
991       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
998       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
1006       This is a test
1007       This is another test
1008
1009       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
1013       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
1018       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
1023       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
1031       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
1037       For example, consider the following rule sequence:
1038
1039       type=Single
1040       ptype=RegExp
1041       pattern=Test: (\d+)
1042       desc=test
1043       action=create CONT_$1
1044
1045       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
1052       If the following input lines appear in this order
1053
1054       Test: 19
1055       Test: 261
1056       Test2: 19 787
1057       Test: 787
1058       Test2: 787 261
1059
1060       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
1065       Test2: (\d+) (\d+)
1066
1067       but does not match the second rule, since the boolean expression
1068
1069       CONT_19 && CONT_787
1070
1071       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
1076       CONT_787 && CONT_261
1077
1078       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
1082       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
1094       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
1097       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
1104       When the following message from SSH daemon appears
1105
1106       Dec 16 16:24:59 myserver sshd[13685]: Failed password  for  risto  from
1107       10.12.2.5 port 41063 ssh2
1108
1109       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
1112       sub { $_[0] < 1024 }
1113
1114       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
1118       Dec 16 16:25:17 myserver sshd[13689]: Failed password  for  risto  from
1119       10.12.2.5 port 1023 ssh2
1120
1121       matches the rule, and the string "SSH login failure for user risto from
1122       a privileged port 1023" is written to standard output.
1123
1124       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
1128       context= -> ( sub { my(@stat) = stat("/var/log/messages"); \
1129       return (!scalar(@stat) || time() - $stat[9] > 3600); } )
1130
1131       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
1151       For example, consider the following rule sequence:
1152
1153       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
1163       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
1172       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
1181       sub { $_[0]->{"status"} eq "Failed" && \
1182             $_[0]->{"port"} < 1024 && \
1183             defined($_[0]->{"invuser"}) }
1184
1185       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
1194       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
1199       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
1203       context=varset SSH && SSH :> ( sub { $_[0]->{"user"} eq "risto" } )
1204
1205       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
1217       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
1221       context=!(C1 || C2) && =("$1" eq "myhost.mydomain")
1222
1223       Since && is a short-circuiting operator, the Perl code
1224
1225       "$1" eq "myhost.mydomain"
1226
1227       is *not* evaluated if either C1 or C2 exists.
1228
1229       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
1233       context=$1 $2 -> ( sub { $_[0] != $_[1] } )
1234
1235       context= =({my($temp) = 0; !$temp;})
1236
1237       Also,  if function parameter lists contain such strings, they should be
1238       enclosed in parentheses in the similar way:
1239
1240       context=($1! $2) -> ( sub { $_[0] eq $_[1] } )
1241
1242       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

ACTIONS, ACTION LISTS AND ACTION LIST VARIABLES

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
1263       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
1267       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
1276       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
1283       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
1290       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
1294       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
1299       action=delete MYCONTEXT; shellcmd (rm /tmp/sec1.tmp; rm /tmp/sec2.tmp)
1300
1301       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
1307       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
1320       The following action list variables are predefined by SEC:
1321
1322       %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
1327       %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
1331       %u     the time in seconds since Epoch, as returned by the time(2) sys‐
1332              tem call.
1333
1334       %.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
1337       %.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
1340       %.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
1343       %.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
1347       %.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
1350       %.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
1355       %.mon  month,  in the range 01-12 (the value consists of two digits and
1356              is zero padded on the left).
1357
1358       %.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
1363       %.year year (e.g., 1998 or 2016).
1364
1365       %.wday day of the week, in the range 0-6 (0 denotes Sunday).
1366
1367       %.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
1372       %.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
1377       %.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
1381       %.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
1388       %.nl   newline character.
1389
1390       %.cr   carriage return character.
1391
1392       %.tab  tabulation character.
1393
1394       %.sp   space character.
1395
1396       %.chr0, ..., %.chr31
1397              ASCII 0..31 control characters (e.g., %.chr7 is bell and %.chr12
1398              is form feed character).
1399
1400       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
1404       action=assign %text %t: This is a test event; \
1405              pipe '%text' /bin/mail root@localhost
1406
1407       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
1416       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
1420       action=write - %{.year}-%{.mon}-%{.mday}T%{.hmsstr}%{.tzoff2}
1421
1422       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
1426       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
1431       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
1438       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
1442       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
1448       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
1454       SEC supports the following actions (optional parameters are enclosed in
1455       square brackets):
1456
1457       none   No action.
1458
1459       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
1466              action=logonly This is a test
1467
1468              The above logonly action logs the message "This is a test"  with
1469              level 4.
1470
1471       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
1486              action=write /var/log/test.log %t $0
1487
1488              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
1493       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
1499              action=writen - ab; writen - c; writen - %.nl
1500
1501              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
1505       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
1509       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
1517              action=owritecl /var/log/test-%{.year}%{.mon}%{.mday} $0%{.nl}
1518
1519              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
1526       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
1536              action=udgram /dev/log <30>%.monstr %.mdaystr %.hmsstr sec: This
1537              is a test
1538
1539              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
1546       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
1551       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
1560       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
1565       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
1575              action=udpsock mysrv:514 <13>%.monstr %.mdaystr %.hmsstr  myhost
1576              test: $0
1577
1578              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
1584       closeudp <host>:<port>
1585              Close the UDP socket for peer <host>:<port> that has been previ‐
1586              ously opened by the udpsock action.
1587
1588       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
1603              action=tcpsock grsrv:2003 ssh.login.failures %{num} %{u}%{.nl}
1604
1605              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
1612       closetcp <host>:<port>
1613              Close the TCP socket for peer <host>:<port> that has been previ‐
1614              ously opened by the tcpsock action.
1615
1616       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
1627              action=shellcmd (cat /tmp/report | mail  root;  rm  -f  /tmp/re‐
1628              port); \
1629                     logonly Report sent to user root
1630
1631              The  shellcmd  action  of  this action list executes the command
1632              line
1633
1634              cat /tmp/report | mail root; rm -f /tmp/report
1635
1636              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
1641       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
1651              action=spawn (cat /tmp/events; rm -f /tmp/events)
1652
1653              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
1658       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
1663       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
1676              action=cmdexec rm /tmp/report*
1677
1678              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
1682       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
1691       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
1696       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
1709              action=pipe   'Offending  activities  from  host  $1'  /bin/mail
1710              root@localhost
1711
1712              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
1717       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
1728              action=pipeexec 'Offending activities from host $1' \
1729                              /bin/mail -s SEC%{.sp}alert $2
1730
1731              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
1744       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
1760              action=write /var/log/test.log $0; create TIMER 3600 \
1761                     (     logonly     Closing    /var/log/test.log;    closef
1762              /var/log/test.log )
1763
1764              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
1773              logonly Closing /var/log/test.log; closef /var/log/test.log
1774
1775              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
1780       delete [<name>]
1781              Delete the context <name>. The <name> parameter may not  contain
1782              whitespace and defaults to %s.
1783
1784       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
1788       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
1805              action=set C_$1 30 ( logonly Context C_$1 has expired )
1806
1807              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
1811       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
1824       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
1831       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
1843              action=add EVENTS This is a test; add EVENTS This is a test2
1844
1845              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
1849       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
1854              action=prepend  EVENTS  This is a test; prepend EVENTS This is a
1855              test2
1856
1857              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
1861       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
1865       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
1878              action=create PID_$1 60 ( report PID_$1 /bin/mail root@localhost
1879              ); \
1880                     add PID_$1 Beginning of the report
1881
1882              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
1888       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
1898       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
1905       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
1911       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
1917       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
1923       exists %<var> <name>
1924              If the context <name>  exists,  set  the  action  list  variable
1925              %<var> to 1, otherwise set %<var> to 0.
1926
1927       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
1934              action=fill EVENTS Event1; add EVENTS Event2; add EVENTS Event3;
1935              \
1936                     pop EVENTS %temp1; shift  EVENTS  %temp2;  getsize  %size
1937              EVENTS
1938
1939              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
1943       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
1950       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
1956              action=create TEST 10 ( getltime %time TEST; \
1957                     logonly Context TEST with %time second lifetime  has  ex‐
1958              pired )
1959
1960              The  above  create action configures the context TEST to log its
1961              lifetime when it expires.
1962
1963       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
1973       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
1980       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
1991       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
2005              action=copy EVENTS %events; event %events
2006
2007              The above action list will create a synthetic  event  from  each
2008              string in the event store of the EVENTS context.
2009
2010       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
2015       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
2020       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
2042              action=reset -1 Ten login failures observed from $1; reset 0
2043
2044              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
2052       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
2065              action=getwpos %pos -1 Ten login failures observed from $1
2066
2067              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
2075       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
2087       assign %<var> [<string>]
2088              Assign  string <string> to the action list variable %<var>.  De‐
2089              fault value for <string> is %s.
2090
2091       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
2102       free %<var>
2103              Unset the action list variable %<var>.
2104
2105       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
2121              action=assign %div Division error; eval %div ( $1 / $2 )
2122
2123              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
2135       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
2153              action=eval %func ( sub { return $_[0] + $_[1] } ); \
2154                     call %sum %func $1 $2
2155
2156              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
2166       lcall %<var> [<paramlist>] -> <code>
2167
2168       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
2198              action=lcall %len $1 -> ( sub { return length($_[0]) } )
2199
2200              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
2207              action=lcall %o SSH :> ( sub { $_[0]->{"failure"} = 1 } )
2208
2209              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
2214       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
2233       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
2249              action=addinput /var/log/test-%{.year}%{.mon}%{.mday} 0 TESTFILE
2250
2251              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
2258       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
2264       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
2272       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
2280       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
2290              action=exists %present REPORT; if %present \
2291                       ( report REPORT /bin/mail root@localhost; delete REPORT
2292              ) \
2293                       else ( logonly Nothing to report )
2294
2295              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
2299       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
2306              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
2311              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
2323       break  If used inside a while-loop, terminates its execution; otherwise
2324              terminates the execution of the entire action list.
2325
2326       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
2331       Examples:
2332
2333       Follow the /var/log/trapd.log file and feed to SEC input all lines that
2334       are appended to the file:
2335
2336       action=spawn /bin/tail -f /var/log/trapd.log
2337
2338       Mail the timestamp and the value of the $0 variable to the local root:
2339
2340       action=pipe '%t: $0' /bin/mail -s "alert message" root@localhost
2341
2342       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
2347       action=add ftp_$1 $0; \
2348              set ftp_$1 1800 (report ftp_$1 /bin/mail root@localhost)
2349
2350       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
2354       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
2358       The following action list achieves the same goal as the previous action
2359       list with while and if actions:
2360
2361       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

PARSING ISSUES

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
2374       action=eval %o (print ")";)
2375
2376       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
2384       action=eval %o (print "\)";)
2385

RULE TYPES

2387       This section provides a detailed discussion of SEC rule types.
2388
2389   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
2393       type   fixed  to Single (value is case insensitive, so single or sIngLe
2394              can be used instead).
2395
2396       continue (optional)
2397              TakeNext, DontCont, EndMatch or GoTo <label>  (apart  from  <la‐
2398              bel>, values are case insensitive).
2399
2400       ptype  pattern type (value is case insensitive).
2401
2402       pattern
2403              pattern.
2404
2405       varmap (optional)
2406              variable map.
2407
2408       context (optional)
2409              context expression.
2410
2411       desc   operation description string.
2412
2413       action action list.
2414
2415       rem (optional, may appear more than once)
2416              remarks and comments.
2417
2418       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
2422       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
2426       Examples:
2427
2428       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
2435       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
2444       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
2451       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
2465       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
2472   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
2477       type   fixed to SingleWithScript (value is case insensitive).
2478
2479       continue (optional)
2480              TakeNext, DontCont, EndMatch or GoTo <label>  (apart  from  <la‐
2481              bel>, values are case insensitive).
2482
2483       ptype  pattern type (value is case insensitive).
2484
2485       pattern
2486              pattern.
2487
2488       varmap (optional)
2489              variable map.
2490
2491       context (optional)
2492              context expression.
2493
2494       script command line of external program.
2495
2496       shell (optional)
2497              Yes or No (values are case insensitive, default is Yes).
2498
2499       desc   operation description string.
2500
2501       action action list.
2502
2503       action2 (optional)
2504              action list.
2505
2506       rem (optional, may appear more than once)
2507              remarks and comments.
2508
2509       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
2513       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
2524       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
2532       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
2536       Examples:
2537
2538       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
2546       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
2552   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
2556       type   fixed to SingleWithSuppress (value is case insensitive).
2557
2558       continue (optional)
2559              TakeNext,  DontCont,  EndMatch  or GoTo <label> (apart from <la‐
2560              bel>, values are case insensitive).
2561
2562       ptype  pattern type (value is case insensitive).
2563
2564       pattern
2565              pattern.
2566
2567       varmap (optional)
2568              variable map.
2569
2570       context (optional)
2571              context expression.
2572
2573       desc   operation description string.
2574
2575       action action list.
2576
2577       window event correlation window size (value is an integer constant).
2578
2579       rem (optional, may appear more than once)
2580              remarks and comments.
2581
2582       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
2586       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
2593       Examples:
2594
2595       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
2602       This rule runs event correlation operations for processing "file system
2603       full" syslog messages, e.g.,
2604
2605       Dec 16 14:26:09 test ufs: [ID 845546 kern.notice] NOTICE: alloc:  /var:
2606       file system full
2607
2608       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
2617   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
2622       type   fixed to Pair (value is case insensitive).
2623
2624       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
2629       ptype  pattern type for pattern (value is case insensitive).
2630
2631       pattern
2632              pattern.
2633
2634       varmap (optional)
2635              variable map for pattern.
2636
2637       context (optional)
2638              context expression, evaluated together with pattern.
2639
2640       desc   operation description string.
2641
2642       action action list.
2643
2644       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
2649       ptype2 pattern type for pattern2 (value is case insensitive).
2650
2651       pattern2
2652              pattern.
2653
2654       varmap2 (optional)
2655              variable map for pattern2.
2656
2657       context2 (optional)
2658              context expression, evaluated together with pattern2.
2659
2660       desc2  format string that sets the %s variable for action2.
2661
2662       action2
2663              action list.
2664
2665       window (optional)
2666              event correlation window size (value is an integer constant).
2667
2668       rem (optional, may appear more than once)
2669              remarks and comments.
2670
2671       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
2675       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
2685       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
2690       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
2700       Examples:
2701
2702       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
2713       This  rule runs event correlation operations for processing NFS "server
2714       not responding" and "server OK" syslog messages, e.g.,
2715
2716       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
2720       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
2728       For example, if SEC observes the following event at 22:39:48
2729
2730       Dec  18  22:39:48  test  kernel: nfs: server box1 not responding, still
2731       trying
2732
2733       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
2740       If  any  further  error messages appear for server box1 during the 3600
2741       second lifetime of the operation, e.g.,
2742
2743       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
2748       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
2752       Dec 18 22:42:27 test kernel: nfs: server box1 OK
2753
2754       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
2762       If the above rule is modified in the following way
2763
2764       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
2776       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
2780       For example, if SEC observes the following event
2781
2782       Dec 18 23:01:17 test kernel: nfs: server box.test not responding, still
2783       trying
2784
2785       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
2792       ^([[:alnum:]: ]+) \S+ kernel: nfs: server box\.test OK
2793
2794       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
2800       Suppose SEC will then observe the event
2801
2802       Dec 18 23:09:54 test kernel: nfs: server box.test OK
2803
2804       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
2814   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
2819       type   fixed to PairWithWindow (value is case insensitive).
2820
2821       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
2826       ptype  pattern type for pattern (value is case insensitive).
2827
2828       pattern
2829              pattern.
2830
2831       varmap (optional)
2832              variable map for pattern.
2833
2834       context (optional)
2835              context expression, evaluated together with pattern.
2836
2837       desc   operation description string.
2838
2839       action action list.
2840
2841       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
2846       ptype2 pattern type for pattern2 (value is case insensitive).
2847
2848       pattern2
2849              pattern.
2850
2851       varmap2 (optional)
2852              variable map for pattern2.
2853
2854       context2 (optional)
2855              context expression, evaluated together with pattern2.
2856
2857       desc2  format string that sets the %s variable for action2.
2858
2859       action2
2860              action list.
2861
2862       window event correlation window size (value is an integer constant).
2863
2864       rem (optional, may appear more than once)
2865              remarks and comments.
2866
2867       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
2871       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
2880       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
2887       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
2897       Examples:
2898
2899       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
2910       This  rule  runs  event correlation operations for processing SSH login
2911       events, e.g.,
2912
2913       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
2918       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
2927       Suppose  the  following events are generated by an SSH daemon, and each
2928       event timestamp reflects the time SEC observes the event:
2929
2930       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
2941       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
2946       sshd\[\d+\]: Accepted .+ for risto from 10\.1\.2\.7 port \d+ ssh2
2947
2948       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
2954       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
2959       sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2960
2961       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
2971       sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2972
2973       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
2978       sshd\[\d+\]: Accepted .+ for root from 192\.168\.1\.104 port \d+ ssh2
2979
2980       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
2985   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
2990       type   fixed to SingleWithThreshold (value is case insensitive).
2991
2992       continue (optional)
2993              TakeNext,  DontCont,  EndMatch  or GoTo <label> (apart from <la‐
2994              bel>, values are case insensitive).
2995
2996       ptype  pattern type (value is case insensitive).
2997
2998       pattern
2999              pattern.
3000
3001       varmap (optional)
3002              variable map.
3003
3004       context (optional)
3005              context expression.
3006
3007       desc   operation description string.
3008
3009       action action list.
3010
3011       action2 (optional)
3012              action list.
3013
3014       window event correlation window size (value is an integer constant).
3015
3016       thresh counting threshold (value is an integer constant).
3017
3018       rem (optional, may appear more than once)
3019              remarks and comments.
3020
3021       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
3026       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
3044       Examples:
3045
3046       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
3054       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
3059       Suppose the following events are generated by an SSH daemon,  and  each
3060       event timestamp reflects the time SEC observes the event:
3061
3062       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
3075       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
3091   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
3096       type   fixed to SingleWith2Thresholds (value is case insensitive).
3097
3098       continue (optional)
3099              TakeNext,  DontCont,  EndMatch  or GoTo <label> (apart from <la‐
3100              bel>, values are case insensitive).
3101
3102       ptype  pattern type (value is case insensitive).
3103
3104       pattern
3105              pattern.
3106
3107       varmap (optional)
3108              variable map.
3109
3110       context (optional)
3111              context expression.
3112
3113       desc   operation description string.
3114
3115       action action list.
3116
3117       window event correlation window size (value is an integer constant).
3118
3119       thresh counting threshold.
3120
3121       desc2  format string that sets the %s variable for action2.
3122
3123       action2
3124              action list.
3125
3126       window2
3127              event correlation window size (value is an integer constant).
3128
3129       thresh2
3130              counting threshold.
3131
3132       rem (optional, may appear more than once)
3133              remarks and comments.
3134
3135       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
3141       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
3157       Examples:
3158
3159       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
3171       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
3180       Suppose  the following events are generated by a router, and each event
3181       timestamp reflects the time SEC observes the event:
3182
3183       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
3187       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
3194       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
3205   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
3210       type   EventGroup[N] (value is case insensitive, N defaults to 1).
3211
3212       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
3217       ptype  pattern type for pattern (value is case insensitive).
3218
3219       pattern
3220              pattern.
3221
3222       varmap (optional)
3223              variable map for pattern.
3224
3225       context (optional)
3226              context expression, evaluated together with pattern.
3227
3228       count (optional)
3229              action list for execution after a match by pattern and context.
3230
3231       thresh (optional)
3232              counting threshold for events matched  by  pattern  and  context
3233              (value is an integer constant, default is 1).
3234
3235       ...
3236
3237       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
3242       ptypeN pattern type for patternN (value is case insensitive).
3243
3244       patternN
3245              pattern.
3246
3247       varmapN (optional)
3248              variable map for patternN.
3249
3250       contextN (optional)
3251              context expression, evaluated together with patternN.
3252
3253       countN (optional)
3254              action  list  for  execution  after a match by patternN and con‐
3255              textN.
3256
3257       threshN (optional)
3258              counting threshold for events matched by patternN  and  contextN
3259              (value is an integer constant, default is 1).
3260
3261       desc   operation description string.
3262
3263       action action list.
3264
3265       init (optional)
3266              action list.
3267
3268       end (optional)
3269              action list.
3270
3271       slide (optional)
3272              action list.
3273
3274       multact (optional)
3275              Yes or No (values are case insensitive, default is No).
3276
3277       egptype (optional)
3278              SubStr,  NSubStr, RegExp, NRegExp, PerlFunc or NPerlFunc (values
3279              are case insensitive).  Specifies the pattern  type  for  egpat‐
3280              tern.
3281
3282       egpattern (optional)
3283              event group pattern.
3284
3285       window event correlation window size (value is an integer constant).
3286
3287       rem (optional, may appear more than once)
3288              remarks and comments.
3289
3290       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
3298       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
3304       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
3309       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
3327       For example, consider the following rule:
3328
3329       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
3340       Also, suppose the following events occur, and each event timestamp  re‐
3341       flects the time SEC observes the event:
3342
3343       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
3351       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
3363       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
3372       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
3385       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
3399       For example, consider the following rule:
3400
3401       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
3414       Also,  suppose the following events occur, and each event timestamp re‐
3415       flects the time SEC observes the event:
3416
3417       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
3423       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
3429       2 2 1 1
3430
3431       However, since this string does not match the regular expression
3432
3433       1 2$
3434
3435       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
3440       2 2 1 1 2
3441
3442       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
3447       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
3454       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
3458       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
3463       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
3468       Examples:
3469
3470       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
3474       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
3489       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
3498       Suppose  the  following events occur, and each event timestamp reflects
3499       the time SEC observes the event:
3500
3501       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
3555       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
3562       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
3571       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
3584       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
3595       The following example rule cross-correlates iptables events and SSH lo‐
3596       gin events:
3597
3598       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
3618       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
3631       Suppose  the  following events occur, and each event timestamp reflects
3632       the time SEC observes the event:
3633
3634       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
3645       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
3665   SUPPRESS RULE
3666       The Suppress rule supports the following fields.  Note that match vari‐
3667       ables may be used in the context field.
3668
3669       type   fixed to Suppress (value is case insensitive).
3670
3671       ptype  pattern type (value is case insensitive).
3672
3673       pattern
3674              pattern.
3675
3676       varmap (optional)
3677              variable map.
3678
3679       context (optional)
3680              context expression.
3681
3682       desc (optional)
3683              string for describing the rule.
3684
3685       rem (optional, may appear more than once)
3686              remarks and comments.
3687
3688       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
3692       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
3697       Examples:
3698
3699       type=Suppress
3700       ptype=RegExp
3701       pattern=sshd\[\d+\]: Failed .+ for \S+ from ([\d.]+) port \d+ ssh2
3702       context=SUPPRESS_IP_$1
3703
3704       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
3713       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
3717   CALENDAR RULE
3718       The Calendar rule supports the following fields.
3719
3720       type   fixed to Calendar (value is case insensitive).
3721
3722       time   time specification.
3723
3724       context (optional)
3725              context expression.
3726
3727       desc   operation description string.
3728
3729       action action list.
3730
3731       rem (optional, may appear more than once)
3732              remarks and comments.
3733
3734       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
3741       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
3752       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
3756       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
3762       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
3771       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
3775       Examples:
3776
3777       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
3782       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
3787       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
3798       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
3805   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
3810       type   fixed to Jump (value is case insensitive).
3811
3812       continue (optional)
3813              TakeNext, DontCont, EndMatch or GoTo <label>  (apart  from  <la‐
3814              bel>, values are case insensitive).
3815
3816       ptype  pattern type (value is case insensitive).
3817
3818       pattern
3819              pattern.
3820
3821       varmap (optional)
3822              variable map.
3823
3824       context (optional)
3825              context expression.
3826
3827       cfset (optional)
3828              configuration file set names that are separated by whitespace.
3829
3830       constset (optional)
3831              Yes or No (values are case insensitive, default is Yes).
3832
3833       desc (optional)
3834              string for describing the rule.
3835
3836       rem (optional, may appear more than once)
3837              remarks and comments.
3838
3839       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
3851       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
3859       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
3862       Examples:
3863
3864       type=Jump
3865       ptype=RegExp
3866       pattern=sshd\[\d+\]:
3867       cfset=sshd-rules auth-rules
3868
3869       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
3873   OPTIONS RULE
3874       The Options rule supports the following fields.
3875
3876       type   fixed to Options (value is case insensitive).
3877
3878       joincfset (optional)
3879              configuration file set names that are separated by whitespace.
3880
3881       procallin (optional)
3882              Yes or No (values are case insensitive, default is Yes).
3883
3884       rem (optional, may appear more than once)
3885              remarks and comments.
3886
3887       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
3895       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
3902       Examples:
3903
3904       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
3907       type=Options
3908       joincfset=sshd-rules
3909       procallin=no
3910
3911       The following rule adds the current configuration file  to  sets  linux
3912       and solaris which are used for matching all input:
3913
3914       type=Options
3915       joincfset=linux solaris
3916

EVENT CORRELATION OPERATIONS

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
3924       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
3936       For  example,  if the configuration file /etc/sec/my.conf contains only
3937       one rule
3938
3939       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
3947       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
3953       /etc/sec/my.conf | 0 | Repeated login failures for user admin on tty1
3954
3955       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
3963       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
3967       user admin login failure on tty1
3968       user admin login failure on tty5
3969       user admin login failure on tty2
3970
3971       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
3977       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
3982       type=Suppress
3983       ptype=TValue
3984       pattern=TRUE
3985       context=MYCONTEXT
3986
3987       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
3995       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
4001       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
4005       type=Suppress
4006       ptype=SubStr
4007       pattern=test
4008
4009       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
4020       Since the following input events don't contain the substring "test"
4021
4022       database mydb1 down
4023       database mydb2 down
4024       database mydb3 down
4025
4026       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
4030       /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
4034       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
4040       The operation with the ID
4041
4042       /etc/sec/my2.conf | 1 | Database mydb1 is down
4043
4044       uses the following regular expression for matching expected messages:
4045
4046       database mydb1 up|all databases up
4047
4048       The operation with the ID
4049
4050       /etc/sec/my2.conf | 1 | Database mydb2 is down
4051
4052       employs  the  following  regular  expression for matching expected mes‐
4053       sages:
4054
4055       database mydb2 up|all databases up
4056
4057       Finally, the operation with the ID
4058
4059       /etc/sec/my2.conf | 1 | Database mydb3 is down
4060
4061       uses the following regular expression:
4062
4063       database mydb3 up|all databases up
4064
4065       If the following input events appear after 10 minutes
4066
4067       database test up
4068       admin logged in
4069       database mydb3 up
4070       all databases up
4071
4072       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
4082       /etc/sec/my2.conf | 1 | Database mydb3 is down
4083
4084       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
4091       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
4101       For  example,  consider the configuration file /etc/sec/sshd.rules that
4102       contains the following rules:
4103
4104       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
4112       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
4118       Suppose the following events are generated by an SSH daemon,  and  each
4119       event timestamp reflects the time SEC observes the event:
4120
4121       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
4130       The  first event at 15:00:03 starts an event correlation operation with
4131       the ID
4132
4133       /etc/sec/sshd.rules | 0 | Three SSH login failures within 1m  for  user
4134       risto
4135
4136       However,  when  the  third  event  occurs  at 15:00:17, the second rule
4137       matches it and terminates the operation with the action
4138
4139       reset -1 Three SSH login failures within 1m for user risto
4140
4141       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
4148       /etc/sec/sshd.rules  |  0 | Three SSH login failures within 1m for user
4149       risto
4150
4151       (If the operation with the given ID would not exist, reset  would  per‐
4152       form no operation.)
4153
4154       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

INPUT PROCESSING AND TIMING

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
4169       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
4174       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
4184       Suppose SEC is started with the following command line
4185
4186       /usr/bin/sec --conf=/etc/sec/test-multiline.conf --jointbuf \
4187                    --input=/var/log/prog1.log --input=/var/log/prog2.log
4188
4189       and the configuration file /etc/sec/test-multiline.conf has the follow‐
4190       ing content:
4191
4192       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
4201       When  the  following lines appear in input files /var/log/prog1.log and
4202       /var/log/prog2.log
4203
4204       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
4209       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
4213       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
4216       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
4221       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
4224       The  rule also fires after the fourth event has occurred, producing the
4225       following output:
4226
4227       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
4230       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
4235       /usr/bin/sec --conf=/etc/sec/test-rewrite.conf \
4236                    --input=- --nojointbuf
4237
4238       and the configuration file /etc/sec/test-rewrite.conf has the following
4239       content:
4240
4241       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
4251       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
4259       When the following two lines appear in standard input
4260
4261       This is a test1
4262       This is a test2
4263
4264       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
4274       Joined This is a test1 and This is a test2
4275
4276       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
4285       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
4293       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
4299       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
4318       # This rule appears in A.conf
4319       type=Options
4320       joincfset=FileA
4321       procallin=no
4322
4323       # This rule appears in B.conf2
4324       type=Options
4325       joincfset=FileB
4326       procallin=no
4327
4328       # This rule appears in C.conf
4329       type=Options
4330       joincfset=FileC
4331       procallin=no
4332
4333       # This rule appears in main.conf
4334       type=Jump
4335       ptype=TValue
4336       pattern=TRUE
4337       cfset=FileA FileC FileB
4338
4339       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
4352       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

INTERNAL EVENTS AND CONTEXTS

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
4371       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
4379       SEC_STARTUP  - generated when SEC is started (this event will always be
4380       the first event that SEC sees)
4381
4382       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
4386       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
4390       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
4394       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
4398       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
4402       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
4406       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
4414       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
4419       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
4433       type=Suppress
4434       ptype=TValue
4435       pattern=TRUE
4436       context=[!_FILE_EVENT_/dev/logpipe]
4437
4438       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
4444       /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
4449       and the rule file /etc/sec/my.conf contains the following rules
4450
4451       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
4458       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
4465       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

CHILD PROCESSES

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
4484       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
4490       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
4498       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
4503       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
4506       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
4514       action=pipeexec 'Failed SSH logins from $2' /bin/mail -s alert $1
4515
4516       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
4520       pattern=sshd\[\d+\]:  Failed  .+  for  ([\w.-]+) from ([\d.]+) port \d+
4521       ssh2
4522
4523       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
4536       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
4550       action=spawn exec /usr/local/bin/myscript.pl 2>/var/log/myscript.log
4551
4552       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
4560       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
4565       action=shellcmd /usr/bin/logger -f /var/log/pipe -p user.notice
4566
4567       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
4580       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
4588       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

PERL INTEGRATION

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
4603       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
4612       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
4622       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
4633       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
4641       type=Options
4642       procallin=no
4643       joincfset=iptables
4644
4645       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
4654       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
4664       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
4673       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
4680       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
4684       action=eval %a ($b = 1)
4685
4686       the  variable  $b and its value become visible in the following context
4687       expression
4688
4689       context= =(++$b > 10)
4690
4691       (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
4702       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
4711       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
4722       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
4733       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
4737       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
4744       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
4752       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

EXAMPLES

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
4765       # 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
4769       type=Calendar
4770       time=0 23 * * *
4771       desc=NIGHT
4772       action=create %s 28800
4773
4774       type=Calendar
4775       time=0 0 * * 6
4776       desc=WEEKEND
4777       action=create %s 172800
4778
4779       # 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
4785       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
4796       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
4804       # 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
4810       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
4823       # 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
4829       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
4841       # 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
4846       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
4857       # If ten "short outage" events have been observed
4858       # in the window of 6 hours, send a notification
4859
4860       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
4868   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
4880       /usr/bin/sec --conf=/etc/sec/*.rules --intcontexts \
4881                    --input=/var/log/messages --input=/var/log/secure
4882
4883       #
4884       # the content of /etc/sec/main.rules
4885       #
4886
4887       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
4899       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
4909       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
4916       #
4917       # the content of /etc/sec/iptables.rules
4918       #
4919
4920       type=Options
4921       procallin=no
4922       joincfset=iptables
4923
4924       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
4936       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
4948       #
4949       # the content of /etc/sec/ssh-login.rules
4950       #
4951
4952       type=Options
4953       procallin=no
4954       joincfset=ssh-login
4955
4956       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
4966       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
4976       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
4992       #
4993       # the content of /etc/sec/ssh-events.rules
4994       #
4995
4996       type=Options
4997       procallin=no
4998       joincfset=ssh-events
4999
5000       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

ENVIRONMENT

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
5018       # read events from standard input
5019       --input=-
5020
5021       # rules are stored in /etc/sec/test.conf
5022       --conf
5023       /etc/sec/test.conf
5024
5025       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

SIGNALS

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
5042       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
5058       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
5064       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
5069       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
5074       SIGTERM
5075              SEC  will terminate gracefully. With the --childterm option, all
5076              SEC child processes will receive SIGTERM.
5077

BUGS

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

AUTHOR

5084       Risto Vaarandi (ristov at users d0t s0urcef0rge d0t net)
5085

ACKNOWLEDGMENTS

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

SEE ALSO

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)
5099
5100
5101
5102SEC 2.9.0                          May 2021                             sec(1)
Impressum