AlienVault® USM Anywhere™

Plugins Description: Syntax and Logic

USM Anywhere Sensor uses plugins to extract and normalize data received from different data sources. These plugins have a description and a parsing logic, which depend on the type of plugin. This page gives you a general description for all of them about the structure of the plugin file. This file is a JSON file that defines the method of chomping input into a usable form and then how to take those pieces and store them into the specific tags of a normalized packet. This is a generic example of a JSON file plugin:

{ "name": "", "type": "", "version": "", "enrichmentScript": "", "device": "", "vendor": "", "deviceType": "", "family": "", "parentName": "", "parentVersion": "", "app": "", "hints" : [ ], "highlight_fields": "properties" : { "separator.pair" : "a", "separator.groupings" : "b" }, "dictionaries": { "main": { "load": "main-dictionary-0.1.json" }, "additional": { "contents": { "val1": [ 'a', 'b', 'c' ], "val2": [ 'a', 'b', 'c' ], "val3": [ 'a', 'b', 'c' ], "val4": [ 'a', 'b', 'c' ] } } }, "tags": { "field1": [ "map('key1') == '' ? map('key2') : map('key1')" ], "field2": [ "dict('main', map('howdy'), 1)", "regexp(/(d+)(.*)/, dict('additional', map('howdy'), 1), 1)" ], "field3": [ "split(dict('additional', tag('field2')), ',', 2)" ] } }

This is a generic example of a regular expression (regex) plugin file:

{ "name": "Test Regex plugin", "version": "0.1", "type": "regex", "hints": [ { "typeName": "tag.equals", "value": "test" } ], "rules": [ { "name": "Rule test 1" "regex": "test (\\S+)", "tags": { "event_name": "concat('test 1')", "customfield_0": "map(1)" } }, { "name": "Rule test 2" "contains": ["test2"], "regex": "test2 (?<src>\\S+) (?<dst>\\S+)", "tags": { "event_description": "concat('test 2')", "source_username": "map('src')", "destination_username": "map('dst')" } } ] }

This table includes each field and its description on a plugin file:

Fields and its Description on a Plugin File
Field Description
name Name of the plugin.
type Plugin type. The value depends on the log format for the specific data source. Some valid values are these: regex, CEF, CLF, CSV, GELF, JSON, keyvalue, LEEF, split, w3c, XML.
version Plugin version.
enrichmentScript Specify the Lua script used to process a log line.
device Data source that is sending the logs.
vendor Data source vendor.
deviceType Data source type, for example: firewall, router, and so on.
parentName If a parentName is declared for the plugin, a copy of the parent plugin will be made and the child plugin will just overwrite that copy.
parentVersion Version of the parent plugin.
hints References to unique information within a syslog message that identify the data source sending the logs. Plugins that contain hints will process the message when the information in the log message matches the criteria set within the plugin. If hints are not present within the plugin, then to use this plugin you need to specify which asset is going to be sending data for that plugin.
highlight_fields The most important fields that are shown in the principal event view.
properties This field describes the different properties of the plugin, depending on the type.
dictionaries For each declared dictionary, you can either call out to an external file by name (with the assumption that the path is relative to the plugin file) or you can declare the contents of the dictionary inline. Every entry in the dictionary is defined as a key and a series of values.
tags For each tag, you can define a series of code-like statements that will take the data that is created by the chomper, and manipulate it into the fields of the NormalizedPacket. For each tag that is defined, the system begins by evaluating the first code line. If the first code line returns a value, the field in the NormalizedPacket will be populated with that value. Otherwise, it continues to evaluate the additional code lines until one returns a non-null value.

For regex type plugins, there is a set of rules with the these fields:

  • name: name of the rule
  • contains: pre-match filter
  • regex: regular expression
  • tags: tags to capture