syslog-ng Store Box 5.3.0 - Administration Guide

Preface Introduction The concepts of SSB The Welcome Wizard and the first login Basic settings User management and access control Managing SSB Configuring message sources Storing messages on SSB Forwarding messages from SSB Log paths: routing and processing messages Configuring syslog-ng options Searching log messages Searching the internal messages of SSB Classifying messages with pattern databases The SSB RPC API Troubleshooting SSB Security checklist for configuring SSB About us Third-party contributions

Replace message parts or create new macros with rewrite rules

SSB can rewrite parts of the messages using rewrite rules. Almost all part (macro) of the message can be rewritten. The rules use a key-value pair format.

The Replace with value completely replaces the old value of the message part. If the message part does not already exist, SSB automatically creates it. If you want to perform search and replace in the text of the log message, see Find and replace the text of the log message instead.

Note that you cannot change the values of hard macros in rewrite rules. For the list of hard macros, see Section Hard vs. soft macros in The syslog-ng Premium Edition 7.0 Administrator Guide.

To replace message parts or create new macros with rewrite rules

  1. Navigate to Log > Paths.

  2. Select the path(s) where you want to use rewrite rules.

  3. In the Rewrites section, click to add a new rewrite rule. Rewrite rules can be applied before filtering, or after filtering.

    The sequence of filtering and rewrite rules depends on how it was specified in the log path. The sequence of the process is the following:

    1. Parse the message as a syslog message (unless message parsing is explicitly disabled for the source).

    2. Classify the message using a pattern database.

    3. Modify the message using rewrite rules (before filtering).

    4. Filter the messages, for example, based on sender hostname or message content. If the message does not match the configured filter, SSB will not send it to the destination.

    5. Parse the text of the message (that is, the ${MESSAGE} part) using a key-value parser or the sudo parser.

    6. Modify the message using rewrite rules (after filtering and other parsing).

    7. SSB sends the message to the destinations set in the log path. The destinations are local, optionally encrypted files on SSB, or remote servers, such as a database server.

    Figure 119: Log > Paths — Modifying messages using rewrite

  4. Enter the part of the message to rewrite into the In Message part field. For example, MESSAGE, HOST, .SDATA.meta.custom. If the specified field does not exist, it is automatically created and set to the Replace with field.

  5. Enter the value of the message part after rewriting into the Replace with field. To use macros, begin with a $ sign and enclose the name of the macro between braces, for example ${MSG}, ${.SDATA.meta.custom}.

    NOTE:
  6. Click Commit.

Find and replace the text of the log message

You can perform search and replace operations on the log messages to rewrite the messages. Almost all part (macro) of the message can be rewritten. You can use PCRE regular expressions.

If you want to completely replace a message part, or create a new one that does not already exist, see Replace message parts or create new macros with rewrite rules instead.

Note that you cannot change the values of hard macros in rewrite rules. For the list of hard macros, see Section Hard vs. soft macros in The syslog-ng Premium Edition 7.0 Administrator Guide.

To find and replace the text of the log message

  1. Navigate to Log > Paths.

  2. Select the path(s) where you want to use rewrite rules.

  3. In the Rewrites section, click to add a new rewrite rule. Rewrite rules can be applied before filtering, or after filtering.

    The sequence of filtering and rewrite rules depends on how it was specified in the log path. The sequence of the process is the following:

    1. Parse the message as a syslog message (unless message parsing is explicitly disabled for the source).

    2. Classify the message using a pattern database.

    3. Modify the message using rewrite rules (before filtering).

    4. Filter the messages, for example, based on sender hostname or message content. If the message does not match the configured filter, SSB will not send it to the destination.

    5. Parse the text of the message (that is, the ${MESSAGE} part) using a key-value parser or the sudo parser.

    6. Modify the message using rewrite rules (after filtering and other parsing).

    7. SSB sends the message to the destinations set in the log path. The destinations are local, optionally encrypted files on SSB, or remote servers, such as a database server.

    The message part you want to modify must already exist — if you want to modify a macro that a parser creates, you must add the rewrite rule into the After filtering section.

    Figure 120: Log > Paths — Find and replace in the text of log messages

  4. Enter the part of the message to modify into the In Message part field. For example, MESSAGE, HOST, .SDATA.meta.custom.

    Note that you cannot change the values of hard macros in rewrite rules. For the list of hard macros, see Section Hard vs. soft macros in The syslog-ng Premium Edition 7.0 Administrator Guide.

  5. Enter the expression you want to find into the Find field. You can use PCRE regular expressions.

  6. Enter the expression that will replace the Find expression into the Replace with field. By default, SSB replaces the first occurrence of the expression. To use macros, begin with a $ sign and enclose the name of the macro between braces, for example ${MSG}, ${.SDATA.meta.custom}.

    You can use matches of the Find expression as well: ${0} stores the entire match, ${1} is the first group of the match (parentheses), and so on. If you use named patterns in the Find expression (?<name>pattern), you can use ${name} as well.

  7. To replace every occurrence of the Find expression, select the Global option.

  8. To make the Find expression case sensitive, select the Match case option.

  9. Click Commit.

Parsing sudo log messages

The sudo parser separates sudo log messages into name-value pairs.

Use this parser to enrich your log message data with details of privilege escalation events, such as who initiated the event, what command was issued, and so on. The parsed values are automatically assigned metadata, which you can then display on the SSB search interface as dynamic columns.

The aim is to enrich log data with semantic value, and consistently apply the same metadata to the same type of log message data. For example, any information about the client where sudo was executed will always be displayed in the dest and src dynamic columns.

The sudo parser maps the contents of log messages to the dynamic columns listed in Mapping sudo log message contents to dynamic columns.

Example log message:

2016-08-12T06:57:12+02:00 mail sudo: johndoe : TTY=tty ; PWD=pwd ; USER=usr ; GROUP=grp ; TSID=000001 ; ENV=PATH=/usr/local/bin ; COMMAND=cmd -w 20 -c 40

Table 8: Mapping sudo log message contents to dynamic columns
Dynamic column Parsed value Description
action success

The action performed on the resource.

Possible values: success

app sudo The application where the command was issued. Currently, the value of this column is always sudo.
dest mail The IP address or hostname of the entity that validates the authentication request.
src mail The IP address or hostname of the entity that sends the authentication request.
src_user johndoe The user identifier showing which user executed sudo.
tty tty The terminal device name where sudo was executed.
pwd pwd The working directory where sudo was issued.
user usr The user identifier showing who the new user is after executing sudo.
group grp The sudo group target (if present).
tsid 000001 The sudo terminal session (log) identifier (if present).
env PATH=/usr/local/bin The sudo environment variable (if present).
command cmd -w 20 -c 40 The command that was issued by the src_user as a superuser.
tags

authentication

privileged

The metadata to flag the message as a sudo log message.

You can also use the enriched metadata generated from the parsed values in statistics and custom reports.

To use the sudo parser in a specific log path

  1. Navigate to Log > Paths.

  2. Select the path where you want to use the parser.

  3. In the Parser field, Predefined group, select sudo_parser from the drop-down list.

    Figure 121: Log > Paths — Using the sudo_parser in the log path

  4. Click Commit.

Parsing key-value pairs

SSB can separate a message consisting of key-value pairs (for example, Postfix log messages) into name-value pairs. The parsed values are automatically added to the metadata about the message, and you can display them on the SSB search interface as dynamic columns. You can specify the separator character to parse different log messages, for example, colon (:) to parse MySQL log messages, or the equal sign (=) for firewall logs. For details on when the key-value parser is executed related to other message processing operations, see the following list.

Caution:

If the names of keys in the message is the same as the names of SSB soft macros, the value from the parsed message will overwrite the value of the macro. For example, the PROGRAM=value1, MESSAGE=value2 content will overwrite the ${PROGRAM} and ${MESSAGE} macros. To avoid overwriting such macros, use the prefix() option.

Hard macros cannot be modified, so they will not be overwritten. For details on the macro types, see Section Hard vs. soft macros in The syslog-ng Premium Edition 7.0 Administrator Guide.

The parser discards message sections that are not key=value pairs, even if they appear between key=value pairs that can be parsed.

  1. Parse the message as a syslog message (unless message parsing is explicitly disabled for the source).

  2. Classify the message using a pattern database.

  3. Modify the message using rewrite rules (before filtering).

  4. Filter the messages, for example, based on sender hostname or message content. If the message does not match the configured filter, SSB will not send it to the destination.

  5. Parse the text of the message (that is, the ${MESSAGE} part) using a key-value parser or the sudo parser.

  6. Modify the message using rewrite rules (after filtering and other parsing).

  7. SSB sends the message to the destinations set in the log path. The destinations are local, optionally encrypted files on SSB, or remote servers, such as a database server.

NOTE:

If a log message contains the same key multiple times (for example, key1=value1, key2=value2, key1=value3, key3=value4, key1=value5), then SSB stores only the last (rightmost) value for the key. Using the previous example, SSB will store the following pairs: key1=value5, key2=value2, key3=value4..

NOTE:

The names of the keys can contain only the following characters: numbers (0-9), letters (a-z,A-Z), underscore (_), dot (.), hyphen (-). Other special characters are not permitted.

To configure parsing key-value pairs

  1. Navigate to Log > Parsers and select . A new parser is added to the list of parsers.

    Figure 122: Log > Parsers — Creating a key=value parser

  2. Enter a name for the parser.

  3. Enter the character that separates the keys from the values in the incoming messages into the Value separator character field. For example, if your messages look like key1:value1, key2:value2, key3:value3, enter :.

  4. Enter the character or string that separates the key-value pairs from each other into the Pair separator string field. For example, if your messages look like key1:value1, key2:value2, key3:value3, enter ,. If you use a string, it can be a maximum of 20 characters long.
  5. Enter a prefix before the key part of the parsed key-value pairs to help further processing into the Namespace field. For example, to insert the my-parsed-data prefix, enter my-parsed-data. Note the following points:

    • SSB automatically adds the .SDATA. prefix before the value you enter into the Namespace field. That way these values are automatically included in the structured data (SDATA) part of the log message if you forward the message using the IETF-syslog protocol.

    • SSB automatically adds a dot (.) character as a separator between the namespace and the key parsed from the message.

    For example, if you entered my-parsed-data as the namespace, and the keys in the message are key1, key2, and so on, then the full name of the macro that contains the parsed values is ${.SDATA.my-parsed-data.key1}, ${.SDATA.my-parsed-data.key2}, and so on. The parsed values are also automatically available as dynamic columns in the SSB search interface (the name of the column is the name of the macro).

  6. Click Commit.

  7. Navigate to Log > Paths.

  8. Select the path where you want to use the parser.

  9. In the Parser field, Custom group, select the parser you want to use in this log path.

    Figure 123: Log > Paths — Using a key=value parser in the log path

  10. Click Commit.

Related Documents