Match Groups

field (Required)

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.

pattern-id (Required)

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 (Table 1).

order (Required)

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.

capture-group (Optional)

Referenced in the regular expression inside parenthesis ( ). These captures are indexed starting at one and processed from left to right in the pattern. The capture-group field must be a positive integer less than or equal to the number of capture groups that are contained in the pattern. The default value is zero, which is the entire match.

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 enable-substitutions parameter.

To see an example, review the Extension Document Example for Parsing One Event Type.

enable-substitutions (Optional)

Boolean

When you set to true, a field cannot be adequately represented with a straight group capture. You can combine multiple groups with extra text to form a value.

This parameter changes the meaning of the capture-group parameter. The capture-group parameter creates the new value, and group substitutions are specified by using \x where x is a group number, 1 - 9. You can use groups multiple times, and any free-form text can also be inserted into the value. For example, to form a value out of group 1, followed by an underscore, followed by group 2, an @, and then group 1 again, the appropriate capture-group syntax is shown in the following code:

capture-group=”\1_\2@\1”

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:

capture-group=”\1:\2:\3:\4:\5:\6”

If no groups are specified in the capture-group when substitutions are enabled, a direct text replacement occurs.

Default is false.

ext-data (Optional)

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 currently 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.

EventName (Required)

The event name to be retrieved from the QID to identify the event.

EventCategory

cat (LEEF)

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,

<event-match-single event-name= "Successfully logged in"  force-qidmap-lookup-on-fixup="true"  device-event-category="CiscoNAC"  severity="4" send-identity= "OverrideAndNeverSend" />

The force-qidmap-lookup-on-fixup="true" is the flag override.

SourceIp

src (LEEF)

The source IP address for the message.

SourcePort

srcPort (LEEF)

The source port for the message.

SourceIpPreNAT

srcPreNAT (LEEF)

The source IP address for the message before Network Address Translation (NAT) occurs.

SourceIpPostNAT

srcPostNAT (LEEF)

The source IP address for the message after NAT occurs.

SourceMAC

srcMAC (LEEF)

The source MAC address for the message.

SourcePortPreNAT

srcPreNATPort (LEEF)

The source port for the message before NAT occurs.

SourcePortPostNAT

srcPostNATPort (LEEF)

The source port for the message after NAT occurs.

DestinationIp

dst (LEEF)

The destination IP address for the message.

DestinationPort

dstPort (LEEF)

The destination port for the message.

DestinationIpPreNAT

dstPreNAT (LEEF)

The destination IP address for the message before NAT occurs.

DestinationIpPostNAT

dstPostNAT (LEEF)

The destination IP address for the message after NAT occurs.

DestinationPortPreNAT

dstPreNATPort (LEEF)

The destination port for the message before NAT occurs.

DestinationPortPostNAT

dstPostNATPort (LEEF)

The destination port for the message after NAT occurs.

DestinationMAC

dstMAC (LEEF)

The destination MAC address for the message.

DeviceTime

devTime (LEEF)

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 arrived. The DeviceTime field supports the ability to use a custom date and time stamp for the event by using the ext-data Matcher attribute.

The following list contains examples of date and time stamp formats that you can use in the DeviceTime field:

• ext-data="dd/MMM/YYYY:hh:mm:ss"

  11/Mar/2015:05:26:00

• ext-data="MMM dd YYYY / hh:mm:ss"

  Mar 11 2015 / 05:26:00

• ext-data="hh:mm:ss:dd/MMM/YYYY"

  05:26:00:11/Mar/2015

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.

Protocol

proto (LEEF)

The protocol for the message; for example, TCP, UDP, or ICMP.

UserName

The user name for the message.

HostName

identHostName (LEEF)

The host name for the message. Typically, this field is associated with identity events.

GroupName

identGrpName (LEEF)

The group name for the message. Typically, this field is associated with identity events.

IdentityIp

The identity IP address for the message.

IdentityMac

identMAC (LEEF)

The identity MAC address for the message.

IdentityIpv6

The IPv6 identity IP address for the message.

NetBIOSName

identNetBios (LEEF)

The NetBIOS name for the message. Typically, this field is associated with identity events.

ExtraIdentityData

Any user-specific data for the message. Typically, this field is associated with identity events.

SourceIpv6

The IPv6 source IP address for the message.

DestinationIpv6

The IPv6 destination IP address for the message.

field (Required)

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.

pattern-id (Required)

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 pattern. (Table 1)

order (Required)

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.

The regular regex matchers and JSON matchers are combined into one list. The different types of matchers are attempted based on their orders, and the process stops when one of the matchers is able to parse out data from the payload.

enable-substitutions (Optional)

Boolean

When you set to true, a field cannot be adequately represented with a straight group capture. You can combine multiple groups with extra text to form a value.

Wherever the pattern is in the form of a multi-keypath, set the enable-subtitutions value to '=true' so that each keypath in the pattern and expression is replaced with the value that is found by the payload. For example, if the JSON payload contains the first_name and last_name fields, but no full_name field, you can define an expression that contains multiple keypaths, such as {/"last_name"}, {/"first_name"} . The captured value for this expression is smith, john.

Default is false.

ext-data (Optional)

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 .

EventName (Required)

The event name to be retrieved from the QID to identify the event.

EventCategory

An event category for any event with a category that is 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 the JSA system.

<event-match-single event-name=
"Successfully logged in"
force-qidmap-lookup-on-fixup="true"
device-event-category="CiscoNAC"
severity="4" send-identity=
"OverrideAndNeverSend" />

The force-qidmap-lookup-on-fixup="true" is the flag override.

SourceIp

The source IP address for the message.

SourcePort

The source port for the message.

SourceIpPreNAT

The source IP address for the message before Network Address Translation (NAT) occurs.

SourceIpPostNAT

The source IP address for the message after NAT occurs.

SourceMAC

The source MAC address for the message.

SourcePortPreNAT

The source port for the message before NAT occurs.

SourcePortPostNAT

The source port for the message after NAT occurs.

DestinationIp

The destination IP address for the message.

DestinationPort

The destination port for the message.

DestinationIpPreNAT

The destination IP address for the message before NAT occurs.

DestinationIpPostNAT

The destination IP address for the message after NAT occurs.

DestinationPortPreNAT

The destination port for the message before NAT occurs.

DestinationPortPostNAT

The destination port for the message after NAT occurs.

DestinationMAC

The destination MAC address for the message.

DeviceTime

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 arrived. The DeviceTime field supports the ability to use a custom date and time stamp for the event by using the ext-data Matcher attribute.

The following list contains examples of date and time stamp formats that you can use in the DeviceTime field:

• ext-data="dd/MMM/YYYY:hh:mm:ss"

  11/Mar/2015:05:26:00

• ext-data="MMM dd YYYY / hh:mm:ss"

  Mar 11 2015 / 05:26:00

• ext-data="hh:mm:ss:dd/MMM/YYYY"

  05:26:00:11/Mar/2015

For more information about the possible values for the data and time stamp format, see the Java SimpleDateFormat web page (https://docs.oracle.com/ javase/8/docs/api/java/text/SimpleDateFormat.html).

DeviceTime is the only event field that uses the ext-data optional parameter.

Protocol

The protocol for the message; for example, TCP, UDP, or ICMP.

UserName

The user name for the message.

HostName

The host name for the message. Typically, this field is associated with identity events.

GroupName

The group name for the message. Typically, this field is associated with identity events.

IdentityIp

The identity IP address for the message.

IdentityMac

The identity MAC address for the message.

NetBIOSName

The NetBIOS name for the message. Typically, this field is associated with identity events.

ExtraIdentityData

Any user-specific data for the message. Typically, this field is associated with identity events.

SourceIpv6

The IPv6 source IP address for the message.

DestinationIpv6

The IPv6 destination IP address for the message.

field (Required)

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.

pattern-id (Required)

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 pattern. (Table 1)

order (Required)

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.

The regular regex, JSON, LEEF, and CEF matchers are combined into one list. The different types of matchers are attempted based on their orders, and the process stops when one of the matchers is able to parse out data from the payload.

enable-substitutions (Optional)

Boolean

When you set to true, a field cannot be adequately represented with a straight group capture. You can combine multiple groups with extra text to form a value.

Default is false.

ext-data (Optional)

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 .

field (Required)

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.

pattern-id (Required)

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 pattern. (Table 1)

order (Required)

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.

The regular regex, JSON, LEEF, and CEF matchers are combined into one list. The different types of matchers are attempted based on their orders, and the process stops when one of the matchers is able to parse out data from the payload.

enable-substitutions (Optional)

Boolean

When you set to true, a field cannot be adequately represented with a straight group capture. You can combine multiple groups with extra text to form a value.

Default is false.

ext-data (Optional)

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 .

field (Required)

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 Table 3.

pattern-id (Required)

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 an already defined pattern. (Table 1)

order (Required)

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.

The regular regex, JSON, LEEF, and CEF matchers are combined into one list. The different types of matchers are attempted based on their orders, and the process stops when one of the matchers is able to parse out data from the payload.

enable-substitutions (Optional)

Boolean

When set to true, a field cannot be adequately represented with a straight group capture. You can combine multiple groups with extra text to form a value.

Default is false.

ext-data (Optional)

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 currently 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 Table 3.

delimiter-pair (Optional)

The delimiter between each value in a NameValuePair payload.

delimiter-namevalue (Optional)

The delimiter between the name and value in each pair.

field (Required)

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 Table 3.

pattern-id (Required)

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 an already defined pattern. (Table 1)

order (Required)

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.

The regular regex, JSON, LEEF, and CEF matchers are combined into one list. The different types of matchers are attempted based on their orders, and the process stops when one of the matchers is able to parse out data from the payload.

enable-substitutions (Optional)

Boolean

When set to true, a field cannot be adequately represented with a straight group capture. You can combine multiple groups with extra text to form a value.

Default is false.

ext-data (Optional)

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 currently 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 extdata parameter included with the DeviceTime field to reformat the date and time stamp of the event. For more information, see the Table 3.

delimiter (Optional)

The delimiter between each value in a GenericList payload.

field (Required)

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 Table 3.

pattern-id (Required)

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 an already defined pattern. (Table 1)

order (Required)

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.

enable-substitutions (Optional)

Boolean

When set to true, a field cannot be adequately represented with a straight group capture. You can combine multiple groups with extra text to form a value.

Default is false.

ext-data (Optional)

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 currently 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 extdata parameter included with the DeviceTime field to reformat the date and time stamp of the event. For more information, see the Table 3.

device-event-category

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.

severity

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.

send-identity

Specifies the sending of identity change information from the event. Choose one of the following options:

• UseDSMResults - If the DSM returns an identity event, the event is passed on. If the DSM does not return an identity event, the extension does not create or modify the identity information.

  This option is the default value if no value is specified.

• SendIfAbsent - If the DSM creates identity information, the identity event is passed through unaffected. If no identity event is produced by the DSM, but there is enough information in the event to create an identity event, an event is generated with all the relevant fields set.

• OverrideAndAlwaysSend - Ignores any identity event that is returned by the DSM and creates a new identity event, if there is enough information.

• OverrideAndNeverSend - Suppress any identity information that is returned by the DSM. Suggested option unless you are processing events that you want to go into asset updates.