Plugin Fundamentals

All plugin configuration files must include a header.

# Plugin {{ plugin_name }} id:{{ plugin_id }} version: -

# Last modification: {{ LAST_MODIFICATION_DATE }}

#

# Plugin Selection Info:

# {{vendor}}:{{model}}:{{version}}:{{per_asset}}

#

# END-HEADER

#

# Accepted products:

#

# Description

The Plugin Selection Info section includes relevant vendor, product, version, and per asset information.

• Product and Vendor Information — Express the product name and vendor information for the plugin, using the following format: Fortinet:Fortigate. In this example, Fortigate is the product and Fortinet is the vendor of that product.

• Version Information — The version information allows you to select the right plugin when multiple plugins exist for any one version, or when there are multiple plugins, based on log format or intended output.

  All plugins set version information to "-" out of the box, because not all applications use versions. Should this be the case for your plugin, you can just maintain the default setting of the version field. When customizing or creating new plugins, verify whether or not your plugin is versioned and, if so, add the version information.

• Per Asset Information — Some plugins must be activated for each asset in your network. If Per Assets is not set, USM Appliance defaults to "Yes" (Y) and activates the plugin on each asset.

  If your plugin should not be activated per asset (the LevelBlue HIDS plugin, for example), Per Asset must read "No" (N).

The [DEFAULT] section of the plugin configuration file specifies the plugin_id, which is a unique ID for the plugin data source. For example, plugin_id=4003 is a plugin for OpenSSH. The plugin ID is also used when referring to plugins in correlation rules, and when defining policies in USM Appliance.

Users can use the range of 9001 to 2147483647 as plugin IDs, except for the following values, which are reserved

90003, 90005, 90007, 90008, 10002, 12001, 19004, 19005, 19006, 20505

The [config] section of the plugin configuration file specifies the basic settings for this plugin. For example

• type — specifies the plugin type, detector, for example.
• enable — specifies whether the plugin is enabled or not.
• source — identifies the plugin source, using the following keywords
  • log — Text log file (for example: SSH, Apache)
  • mssql — Microsoft SQL Server database (for example: panda-se)
  • mysql — MySQL database (for example: moodle)
  • wmi — Windows Management Instrumentation (wmi-system-logger)
• location — specifies the name and location of the log file the plugin is reading from, for example, location=/var/log/file.log. The rsyslog rules define the location of log files used to store incoming logs from different data sources.

Note: Location is present only in plugins that use a log as a source. Plugins that use other sources contain other plugin-specific information (for example, how to connect to a MySQL database).

The [translation] section translate token values of a source log and assign them to a normalized event field. Translations are useful when you have similar log messages that describe different events, such as when the difference between messages is only in the value of a token and not the structure of the message itself. In this situation, you can use only one rule to parse different messages and use translations to translate (non-numeric)values from messages to numeric values that can be used as plugin_sid (event type ID) values.

Translations consist of two parts

• Translation table — Defines the mapping between values in log messages and values in normalized event.
• translate() function — Translates values from tokens into values in normalized event fields by following the translation table.

In the sample configuration file (shown in the ssh.cfg illustration), the “sid” token in the log message can take the following non-numeric values: none, opened, publickey, version, throughput, closed, and password. Different values of the sid token indicate different log messages. Values of the sid token are translated into numeric values as defined by the translation table, and then used as the plugin_sid value for individual events. Translations can also be defined to convert other text values to numbers as well.

The rest of the plugin configuration file belongs to the rules section. It contains rules that define the format of each event and how data extracted by a regular expression for each event will be normalized into standard event fields. Each rule in a plugin is defined with a name and the event type, which is defined using the event_type=event line in the plugin configuration file.

The regexp field contains the regular expression that defines the format of the events, and extracts the information to normalize it. The regular expressions are written using Python regular expression syntax.

[0000 - Failed password]
event_type=event
regexp=(?P<date>\w{3}\s+\d{1,2}\s\d\d:\d\d:\d\d)\s+(?P<dst>\S+) sshd\[\d+\]: Failed password for\s(?P<info>invalid user\s)?(?P<user>\S+)\sfrom\s(?P<src>\S+)\sport\s(?P<sport>\d{1,5})
date={normalize_date($date)}
plugin_sid=1src_ip={resolv($src)}
dst_ip={resolv($dst)}src_port={$sport}
username={$user}
userdata1={$info}
userdata2={$dst}
device={resolv($dst)}

Event Database Field Mapping

In addition to the regular expression, each rule must specify how to map extracted information from a log into a normalized SIEM database event. The following figure shows the event fields into which you can map information extracted from a log using the regular expression defined for a specific rule.

In the figure

• Fields that are shown in italics are mandatory in each normalized event.
• Fields that are shown in blue (★) include values that always have to be defined in the plugin file.
• Fields that are shown in green (♦) include values that will be filled automatically in case the values are not found in the log (for example, source IP address is set to 0.0.0.0, and source and destination ports are set to 0, if not found in the log).
• Fields that are shown in grey (ᴑ) are optional and can be left empty if the values are not found in the log.

Order of Rules Processing

Plugin rules are loaded in sequential order and the rule name of the plugin file is mandatory. Once a log matches one of the regular expressions of one rule, the USM Appliance Sensor stops processing the event.

It is recommended that specific rules be defined with a low numerical value in the name and general rules be defined with a large numerical value in the name. Naming specific rules with lower values allows them to be processed before the general rules, which are defined to catch all events that were not previously matched.

For example

[0001 - Specific rule]

[0002 - Specific rule]

[9999 - General rule]