JSON matcher (json-matcher)

A JSON-matcher (json-matcher) entity is a field that is parsed and is paired with the appropriate pattern and group for parsing. This entity is new in IBM® QRadar® V7.3.1.

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.

Table 1. Description of JSON matcher parameters
Parameter	Description
`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 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 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 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 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 JSON matcher field names.

The following table lists valid JSON matcher field names.

Table 2. List of valid JSON matcher field names
Field name	Description
EventName (Required)	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.
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 QRadar system, 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. Note: This parameter doesn't appear as a field in the Log Activity tab.
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 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.
IdentityIpv6	The IPv6 identity IP 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.