Correlating log messages

• 1: Correlating messages using the grouping-by() parser
• 1.1: Referencing earlier messages of the context
• 1.2: Options of grouping-by parsers

1 - Correlating messages using the grouping-by() parser

The AxoSyslog application can correlate log messages that match a set of filters. This works similarly to SQL GROUP BY statements. Alternatively, you can also correlate log messages using pattern databases. For details, see Correlating log messages using pattern databases.

Log messages are supposed to describe events, but applications often separate information about a single event into different log messages. For example, the Postfix email server logs the sender and recipient addresses into separate log messages, or in case of an unsuccessful login attempt, the OpenSSH server sends a log message about the authentication failure, and the reason of the failure in the next message. Of course, messages that are not so directly related can be correlated as well, for example, login-logout messages, and so on.

To correlate log messages with AxoSyslog, you can add messages into message-groups called contexts. A context consists of a series of log messages that are related to each other in some way, for example, the log messages of an SSH session can belong to the same context. As new messages come in, they may be added to a context. Also, when an incoming message is identified it can trigger actions to be performed, for example, generate a new message that contains all the important information that was stored previously in the context.

How the grouping-by() parser works

The grouping-by() parser has three options that determine if a message is added to a context: scope(), key(), and where().

• The scope() option acts as an early filter, selecting messages sent by the same process (${HOST}${PROGRAM}${PID} is identical), application (${HOST}${PROGRAM} is identical), or host.

• The key() identifies the context the message belongs to. (The value of the key must be the same for every message of the context.)

• To use a filter to further limit the messages that are added to the context, you can use the where() option.

The timeout() option determines how long a context is stored, that is, how long AxoSyslog waits for related messages to arrive. If the group has a specific log message that ends the context (for example, a logout message), you can specify it using the trigger() option.

When the context is closed, and the messages match the filter set in the having() option (or the having() option is not set), AxoSyslog generates and sends the message set in the aggregate() option.

Declaration:

   parser parser_name {
        grouping-by(
            key()
            having()
            aggregate()
            timeout()
        );
    };

For the parser to work, you must set at least the following options: key(), aggregate(), and timeout().

Note the following points about timeout values:

• When a new message is added to a context, AxoSyslog will restart the timeout using the context-timeout set for the new message.

• When calculating if the timeout has already expired or not, AxoSyslog uses the timestamps of the incoming messages, not system time elapsed between receiving the two messages (unless the messages do not include a timestamp, or the keep-timestamp(no) option is set). That way AxoSyslog can be used to process and correlate already existing log messages offline. However, the timestamps of the messages must be in chronological order (that is, a new message cannot be older than the one already processed), and if a message is newer than the current system time (that is, it seems to be coming from the future), AxoSyslog will replace its timestamp with the current system time.

  Example: How AxoSyslog calculates context-timeout

  Consider the following two messages:

      <38>1990-01-01T14:45:25 customhostname program6[1234]: program6 testmessage
      <38>1990-01-01T14:46:25 customhostname program6[1234]: program6 testmessage
  

  If the context-timeout is 10 seconds and AxoSyslog receives the messages within 1 second, the timeout event will occour immediately, because the difference of the two timestamp (60 seconds) is larger than the timeout value (10 seconds).

• Avoid using unnecessarily long timeout values on high-traffic systems, as storing the contexts for many messages can require considerable memory. For example, if two related messages usually arrive within seconds, it is not needed to set the timeout to several hours.

Example: Correlating Linux Audit logs

Linux audit logs tend to be broken into several log messages (generated as a list of lines). Usually, the related lines are close to each other in time, but multiple events can be logged at around the same time, which get mixed up in the output. The example below is the audit log for running ntpdate:

   type=SYSCALL msg=audit(1440927434.124:40347): arch=c000003e syscall=59 success=yes exit=0 a0=7f121cef0b88 a1=7f121cef0c00 a2=7f121e690d98 a3=2 items=2 ppid=4312 pid=4347 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=(none) ses=4294967295 comm="ntpdate" exe="/usr/sbin/ntpdate" key=(null)
    type=EXECVE msg=audit(1440927434.124:40347): argc=3 a0="/usr/sbin/ntpdate" a1="-s" a2="ntp.ubuntu.com"
    type=CWD msg=audit(1440927434.124:40347):  cwd="/"
    type=PATH msg=audit(1440927434.124:40347): item=0 name="/usr/sbin/ntpdate" inode=2006003 dev=08:01 mode=0100755 ouid=0 ogid=0 rdev=00:00 nametype=NORMAL
    type=PATH msg=audit(1440927434.124:40347): item=1 name="/lib64/ld-linux-x86-64.so.2" inode=5243184 dev=08:01 mode=0100755 ouid=0 ogid=0 rdev=00:00 nametype=NORMAL
    type=PROCTITLE msg=audit(1440927434.124:40347): proctitle=2F62696E2F7368002F7573722F7362696E2F6E7470646174652D64656269616E002D73

These lines are connected by their second field: msg=audit(1440927434.124:40347). You can parse such messages using the Linux audit parser of AxoSyslog, and then use the parsed .auditd.msg field to group the messages.

   parser auditd_groupingby {
        grouping-by(
            key("${.auditd.msg}")
            aggregate(
                value("MESSAGE" "$(format-json .auditd.*)")
            )
            timeout(10)
        );
    };

1.1 - Referencing earlier messages of the context

When creating the aggregated message, or in the various parameters of the grouping-by() parser, you can also refer to fields and values of earlier messages of the context by adding the @<distance-of-referenced-message-from-the-current> suffix to the macro. For example, if there are three log messages in a context, the ${HOST}@1 expression refers to the host field of the current (third) message in the context, the ${HOST}@2 expression refers to the host field of the previous (second) message in the context, ${PID}@3 to the PID of the first message, and so on. For example, the following message can be created from SSH login/logout messages: An SSH session for ${SSH_USERNAME}@1 from ${SSH_CLIENT_ADDRESS}@2 closed. Session lasted from ${DATE}@2 to ${DATE}.

Example: Referencing values from an earlier message

The following action can be used to log the length of an SSH session (the time difference between a login and a logout message in the context):

   aggregate(
        value('value name="MESSAGE" An SSH session for ${SSH_USERNAME}@1 from ${SSH_CLIENT_ADDRESS}@2 closed. Session lasted from ${DATE}@2 to ${DATE}')
    )

If you do not know in which message of the context contains the information you need, you can use the grep template function. For details, see grep.

Example: Using the grep template function

The following example selects the message of the context that has a username name-value pair with the root value, and returns the value of the auth_method name-value pair.

   $(grep ("${username}" == "root") ${auth_method})

To perform calculations on fields that have numerical values, see Numerical operations.

1.2 - Options of grouping-by parsers

The grouping-by has the following options.

aggregate()

Description: Specifies the message that AxoSyslog generates when the context is closed. This option is mandatory.

Note that the aggregate() option has access to every message of the context, and has the following options:

• inherit-mode: This attribute controls which name-value pairs and tags are propagated to the newly generated message.

  • context: AxoSyslog collects every name-value pair from each message stored in the context, and includes them in the generated message. If a name-value pair appears in multiple messages of the context, the value in the latest message will be used. Note that tags are not merged, the generated message will inherit the tags assigned to the last message of the context.

  • last-message: Only the name-value pairs appearing in the last message are copied. If the context contains only a single message, then it is the message that triggered the action.

  • none: An empty message is created, without inheriting any tags or name-value pairs.

  The default value of inherit-mode() is context. For details on the message context, see Correlating messages using the grouping-by() parser.

• tags: Adds the specified tag to the list of tags.

• value: Adds a name-value pair to the generated message. You can include text, macros, template functions, and you can also reference every message of the context. For details on accessing other messages of the context, see Referencing earlier messages of the context.

having()

Description: Specifies a filter: AxoSyslog generates the aggregate message only if the result of the filter expression is true. Note that the having() filter has access to every message of the context. For details on accessing other messages of the context, see Referencing earlier messages of the context.

inject-mode()

Description: By default, the aggregated message that AxoSyslog generates is injected into the same place where the grouping-by() statement is referenced in the log path. To post the generated message into the internal() source instead, use the inject-mode() option in the definition of the parser.

Example: Sending triggered messages to the internal() source

To send the generated messages to the internal source, use the inject-mode("internal") option:

   parser p_grouping-by {grouping-by(
        ...
        inject-mode("internal")
    );};

To inject the generated messages where the parser is referenced, use the inject-mode("pass-through") option:

   parser p_grouping-by {grouping-by(
        ...
        inject-mode("pass-through")
    );};

You can configure the generated message in the aggregate() option (see aggregate()). You can create an entire message, use macros and values extracted from the original message, and so on.

key()

Description: Specifies the key as a template (that is, the name of a name-value pair) that every message must have to be added to the context. The value of the key must be the same for every message of the context. For example, this can be a session-id parsed from firewall messages, and so on.

This is a mandatory option.

scope()

Description: Specifies which messages belong to the same context. The following values are available:

• process: Only messages that are generated by the same process of a client belong to the same context, that is, messages that have identical ${HOST}, ${PROGRAM} and ${PID} values.
• program: Messages that are generated by the same application of a client belong to the same context, that is, messages that have identical ${HOST} and ${PROGRAM} values.
• host: Every message generated by a client belongs to the same context, only the ${HOST} value of the messages must be identical.
• global: Every message belongs to the same context. This is the default value.

sort-key()

Description: Allows sorting of the elements before they are aggregated into a context. Use this when entries are not received in order. This works similarly to the SQL ORDER BY keyword.

timeout()

Description: Specifies the maximum time to wait for all messages of the context to arrive. If no new message is added to the context during this period, the context is assumed to be complete and AxoSyslog generates and sends the triggered message (specified in the aggregate() option), and clears the context. If a new message is added to the context, the timeout period is restarted.

This option is mandatory, and its value must be equal to or greater than 1.

trigger()

Description: A filter that specifies the final message of the context. If the filter matches the incoming message, AxoSyslog generates and sends the triggered message (specified in the aggregate() option), and clears the context.

where()

Description: Specifies a filter condition. Messages not matching the filter will not be added to the context. Note that the where() filter has access only to the current message.