A match group (
match-group) is a set of patterns that are used for parsing or modifying one
or more types of events.
A matcher is an entity within a match group that is parsed, for example, EventName, and is paired with the appropriate pattern and group for parsing. Any number of match groups can appear in the extension document.
Table 1: Description Of Match Group Parameters
An integer greater than zero that defines the order in which the match groups are executed. It must be unique within the extension document.
A description for the match group, which can be any string. This information can appear in the logs.
If not specified, this parameter defaults to empty.
Define a different device ID to override the QID. Allows the particular match group to search in the specified device for the event type. It must be a valid log source type ID, represented as an integer. A list of log source type IDs is presented in Log Source Type IDs.
If not specified, this parameter defaults to the log source type of the log source to which the extension is attached.
Match groups can have these entities:
A matcher entity is a field that is parsed, for example, EventName, and is paired with the appropriate pattern and group for parsing.
Matchers have an associated order. If multiple matchers are specified for the same field name, the matchers are run in the order that is presented until a successful parse is found or a failure occurs.
Table 2: Description Of Matcher Parameters
The field to which you want the pattern to apply, for example, EventName, or SourceIp. You can use any of the field names that are listed in the List of valid matcher field names table.
The pattern that you want to use when the field is parsed from the payload. This value must match (including case) the ID parameter of the pattern that is previously defined in a pattern ID parameter (Patterns in Log Source Extension Documents).
The order that you want this pattern to attempt among matchers that are assigned to the same field. If two matchers are assigned to the EventName field, the one with the lowest order is attempted first.
Referenced in the regular expression inside parenthesis ( ).
These captures are indexed starting at one and processed from left
to right in the pattern. The
For example, you can define a single pattern for a source IP address and port; where the SourceIp matcher can use a capture group of 1, and the SourcePort matcher can use a capture group of 2, but only one pattern needs to be defined.
This field has a dual purpose when combined with the
To see an example, review the Extension Document Template.
When you set to
This parameter changes the meaning of the
In another example, a MAC address is separated by colons, but in JSA, MAC addresses are usually hyphen-separated. The syntax to parse and capture the individual portions is shown in the following example:
If no groups are specified in the capture-group when substitutions are enabled, a direct text replacement occurs.
Default is false.
An extra-data parameter that defines any extra field information or formatting that a matcher field can provide in the extension.
The only field that uses this parameter is DeviceTime.
For example, you might have a device that sends events by using a unique time stamp, but you want the event to be reformatted to a standard device time. Use the ext-data parameter included with the DeviceTime field to reformat the date and time stamp of the event. For more information, see the List of valid matcher field names.
The following table lists valid matcher field names.
Table 3: List Of Valid Matcher Field Names
The event name to be retrieved from the QID to identify the event.
Note: This parameter doesn't appear as a field in the Log Activity tab.
An event category for any event with a category not handled by an event-match-single entity or an event-match-multiple entity.
Combined with EventName, EventCategory is used to search for the event in the QID. The fields that are used for QIDmap lookups require an override flag to be set when the devices are already known to JSA, for example,
Note: This parameter doesn't appear as a field in the Log Activity tab.
The source IP address for the message.
The source port for the message.
The source IP address for the message before Network Address Translation (NAT) occurs.
The source IP address for the message after NAT occurs.
The source MAC address for the message.
The source port for the message before NAT occurs.
The source port for the message after NAT occurs.
The destination IP address for the message.
The destination port for the message.
The destination IP address for the message before NAT occurs.
The destination IP address for the message after NAT occurs.
The destination port for the message before NAT occurs.
The destination port for the message after NAT occurs.
The destination MAC address for the message.
The time and format that is used by the device. This date and
time stamp represent the time that the event was sent, according to
the device. This parameter doesn't represent the time that the event
The following list contains examples of date and time stamp
formats that you can use in the
For more information about the possible values for the data and time stamp format, see the Joda-Time web page (http://www.joda.org/joda-time/key_format.html).
DeviceTime is the only event field that uses the ext-data optional parameter.
The protocol for the message; for example, TCP, UDP, or ICMP.
The user name for the message.
The host name for the message. Typically, this field is associated with identity events.
The group name for the message. Typically, this field is associated with identity events.
The identity IP address for the message.
The identity MAC address for the message.
The IPv6 identity IP address for the message.
The NetBIOS name for the message. Typically, this field is associated with identity events.
Any user-specific data for the message. Typically, this field is associated with identity events.
The IPv6 source IP address for the message.
The IPv6 destination IP address for the message.
Multi-event Modifier (event-match-multiple)
The multi-event modifier (
event-match-multiple) matches a range of event types and then modifies them as specified
pattern-id parameter and the
This match is not done against the payload, but is done against the results of the EventName matcher previously parsed out of the payload.
This entity allows mutation of successful events by changing
the device event category, severity, or the method the event
uses to send identity events. The
capture-group-index must be an integer value (substitutions are not supported)
and pattern-ID must reference an existing pattern entity. All other
properties are identical to their counterparts in the single-event
Single-event Modifier (event-match-single)
Single-event modifier (
event-match-single) matches and then modifies exactly one type of event, as specified
by the required, case-sensitive EventName parameter.
This entity allows mutation of successful events by changing the device event category, severity, or the method for sending identity events.
When events that match this event name are parsed, the device category, severity, and identity properties are imposed upon the resulting event.
You must set an
and this attribute value matches the value of the EventName field. In addition, an event-match-single entity consists of these
Table 4: Description Of Single-event Parameters
A new category for searching for a QID for the event. This parameter is an optimizing parameter because some devices have the same category for all events.
The severity of the event. This parameter must be an integer value 1 - 10.
If a severity of less than 1 or greater than 10 is specified, the system defaults to 5.
If not specified, the default is whatever is found in the QID.
Specifies the sending of identity change information from the event. Choose one of the following options: