Step 3. Event parsing
This is a required step of the Installation Wizard. On the Event parsing tab of the Installation Wizard, select or create a normalizer whose settings will define the rules for converting raw events into normalized events. You can add multiple event parsing rules to the normalizer to implement complex event processing logic. You can test the normalizer using test events.
When creating a new normalizer in the Installation Wizard, by default it is saved in the set of resources for the collector and cannot be used in other collectors. The Save normalizer check box lets you create the normalizer as a separate resource, in which case the normalizer can be selected in other collectors of the tenant.
If, when changing the settings of a collector resource set, you change or delete conversions in a normalizer connected to it, the edits will not be saved, and the normalizer itself may be corrupted. If you need to modify conversions in a normalizer that is already part of a service, the changes must be made directly to the normalizer under Resources → Normalizers in the web interface.
Adding a normalizer
To add an existing normalizer to a resource set:
- Click the Add event parsing button.
This opens the Basic event parsing window with the normalizer settings and the Normalization scheme tab active.
- In the Normalizer drop-down list, select the required normalizer. The drop-down list includes normalizers belonging to the tenant of the collector and the Shared tenant.
The Basic event parsing window displays the settings of the selected normalizer.
If you want to edit the normalizer settings, in the Normalizer drop-down list, click the pencil icon next to the name of the relevant normalizer. This opens the Edit normalizer window with a dark circle. Clicking the dark circle opens the Basic event parsing window where you can edit the normalizer settings.
If you want to edit advanced parsing settings, move the cursor over the dark circle to make a plus icon appear; click the plus icon to open the Advanced event parsing window. For details about configuring advanced event parsing, see below.
- Click OK.
The normalizer is displayed as a dark circle on the Basic event parsing tab of the Installation Wizard. Clicking on the circle will open the normalizer options for viewing.
To create a new normalizer in the collector:
- At the Event parsing step, on the Parsing schemes tab, click the Add event parsing.
This opens the Basic event parsing window with the normalizer settings and the Normalization scheme tab active.
- If you want to save the normalizer as a separate resource, select the Save normalizer check box; this makes the saved normalizer available for use in other collectors of the tenant. This check box is cleared by default.
- In the Name field, enter a unique name for the normalizer. The name must contain 1 to 128 Unicode characters.
- In the Parsing method drop-down list, select the type of events to receive. Depending on your choice, you can use the preconfigured rules for matching event fields or set your own rules. When you select some of the parsing methods, additional settings fields may need to be filled.
Available parsing methods:
- json
This parsing method is used to process JSON data where each object, including its nested objects, occupies a single line in a file.
When processing files with hierarchically structured data, you can reference the fields of nested objects using the dot notation. For example, the username
parameter from the string "user": {"username": "system: node: example-01"}
can be accessed by using the user.username
query.
Files are processed line by line. Multi-line objects with nested structures may be normalized incorrectly.
In complex normalization schemes where additional normalizers are used, all nested objects are processed at the first normalization level, except for cases when the extra normalization conditions are not specified and, therefore, the event being processed is passed to the extra normalizer in its entirety.
You can use \n
and \r\n
as newline characters. Strings must be UTF-8 encoded.
If you want to send the raw event for advanced normalization, at each nesting level in the Advanced event parsing window, select Yes in the Keep raw event drop-down list.
- cef
This parsing method is used to process CEF data.
If you select this parsing method, you can use the predefined rules for converting events to the KUMA format by clicking Apply default mapping.
- regexp
This parsing method is used to create custom rules for processing data in a format using regular expressions.
You must add a regular expression (RE2 syntax) with named capturing groups to the field under Normalization. The name of the capturing group and its value are considered the field and value of the raw event that can be converted to an event field in KUMA format.
To add event handling rules:
- Copy an example of the data you want to process to the Event examples field. This is an optional but recommended step.
- In the field under Normalization, add a RE2 regular expression with named capturing groups, for example,
"(?P<name>regexp)"
. The regular expression added to the field under Normalization must exactly match the event. When designing the regular expression, we recommend using special characters that match the starting and ending positions of the text: ^
, $
.You can add multiple regular expressions or remove regular expressions. To add a regular expression, click Add regular expression. To remove a regular expression, click next to it.
- Click the Copy field names to the mapping table button.
Capture group names are displayed in the KUMA field column of the Mapping table. You can select the corresponding KUMA field in the column opposite each capturing group. If you followed the CEF format when naming the capturing groups, you can use automatic CEF mapping by selecting the Use CEF syntax for normalization check box.
Event handling rules were added.
- syslog
This parsing method is used to process data in syslog format.
If you select this parsing method, you can use the predefined rules for converting events to the KUMA format by clicking Apply default mapping.
To parse events in rfc5424 format with a structured-data
section, you must enable the Keep extra fields option by selecting Yes in the drop-down list. This makes the values from the structured-data
section available in the Extra
fields.
- csv
This parsing method is used to create custom rules for processing CSV data.
If you select this parsing method, you need to specify the delimiter for values in the string in the Delimiter field. Any single-byte ASCII character can be used as a delimiter for values in a string.
- kv
This parsing method is used to process data in key-value pair format. Available parsing method settings are listed in the table below.
Available parsing method settings
Setting
|
Description
|
Pair delimiter
|
The character used to separate key-value pairs. You can specify any single-character (1 byte) value. The specified value must not match the value specified in the Value delimiter field.
|
Value delimiter
|
The character used to separate a key from its value. You can specify any single-character (1 byte) value. The specified value must not match the value specified in the Pair delimiter field.
|
- xml
This parsing method is used to process XML data in which each object, including nested objects, occupies a single line in a file. Files are processed line by line.
If you want to send the raw event for advanced normalization, at each nesting level in the Advanced event parsing window, select Yes in the Keep raw event drop-down list.
If you select this parsing method, under XML attributes, you can specify the key attributes to be extracted from tags. If an XML structure has several attributes with different values in the same tag, you can specify the necessary value by specifying key of the value in the Source column of the Mapping table.
To add key XML attributes:
- Click Add field.
- This opens a window; in that window, specify the path to the attribute.
You can add multiple attributes or remove attributes. To remove an individual attribute, click the X icon next to it. To remove all attributes, click Reset.
If XML key attributes are not specified, then in the course of field mapping the unique path to the XML value will be represented by a sequence of tags.
Tag numbering
Starting with KUMA 2.1.3, you can use the Tag numbering functionality to automatically number tags in XML events. This lets you parse an event with the identical tags or unnamed tags, such as <Data>
.
As an example, we will use the Tag numbering functionality to number the tags of the EventData
attribute of Microsoft Windows PowerShell event ID 800.
<Event xmlns="http://schemas .microsoft.com/win/2004/08/events/event">
<System>
<Provider Name="Microsoft-Windows-ActiveDirectory_DomainService" Guid="{0e8478c5-3605-4e8c-8497-1e730c959516}" EventSourceName="NTDS" />
<EventID Qualifiers="0000">0000</EventID>
<Version>@</Version>
<Level>4</Level>
<Task>15</Task>
<Opcode>0</Opcode>
<Keywords >0x8080000000000000</Keywords>
<TimeCreated SystemTime="2000-01-01T00:00:00.659495900Z" />
<EventRecordID>55647</EventRecordID>
<Correlation />
<Execution ProcessID="1" ThreadID="1" />
<Channel>service</Channel>
<Computer>computer</Computer>
<Security UserID="0000" />
</System>
<EventData>
<Data>583</Data>
<Data>36</Data>
<Data>192.168.0.1:5084</Data>
<Data>level</Data>
<Data>name, lDAPDisplayName</Data>
<Data />
<Data>5545</Data>
<Data>3</Data>
<Data>0</Data>
<Data>0</Data>
<Data>0</Data>
<Data>15</Data>
<Data>none</Data>
</EventData>
</Event>
To parse events with identical tags or unnamed tags, you need to configure tag numbering and data mapping for numbered tags with KUMA event fields.
KUMA 3.0.x supports using XML attributes and Tag numbering functionality at the same time in the same extra normalizer. If an attribute contains unnamed tags or identical tags, we recommend using the Tag numbering functionality. If the attribute contains only named tags, we recommend using the XML attributes functionality.
To use XML attributes and Tag numbering functionality in extra normalizers, you must sequentially enable the Keep raw event setting in each extra normalizer along the path that the event follows to the target extra normalizer, and in the target extra normalizer itself.
For an example of how the Tag numbering functionality works, you can refer to the MicrosoftProducts normalizer. The Keep raw event setting is enabled sequentially in both AD FS and 424 extra normalizers.
To set up the parsing of events with unnamed or identical tags:
- Open an existing normalizer or create a new normalizer.
- In the Basic event parsing window of the normalizer, in the Parsing method drop-down list, select xml.
- In the Tag numbering field, click Add field.
- In the displayed field, enter the full path to the tag to whose elements you want to assign a number, for example,
Event.EventData.Data
. The first tag gets number 0. If the tag is empty, for example, <Data />
, it is also assigned a number. - To configure data mapping, under Mapping, click Add row and do the following:
- In the new row, in the Source field, enter the full path to the tag and the index of the tag. For example, for the Microsoft Windows PowerShell event ID 800 from the example above, the full paths to tags and tag indices are as follows:
Event.EventData.Data.0
Event.EventData.Data.1
Event.EventData.Data.2
and so on.
- In the KUMA field drop-down list, select the field in the KUMA event that will receive the value from the numbered tag after parsing.
- Save changes in one of the following ways:
- If you created a new normalizer, click Save.
- If you edited an existing normalizer, in the collector to which the normalizer is linked, click Update configuration.
Parsing is configured.
- netflow5
This parsing method is used to process data in the NetFlow v5 format.
If you select this parsing method, you can use the predefined rules for converting events to the KUMA format by clicking Apply default mapping. If the netflow5 parsing method is selected for the main parsing, extra normalization is not available.
The default mapping rules for the netflow5 parsing method do not specify the protocol type in KUMA event fields. When parsing data in NetFlow format, on the Enrichment normalizer tab, you must create a constant data enrichment rule that adds the netflow
value to the DeviceProduct
target field.
- netflow9
This parsing method is used to process data in the NetFlow v9 format.
If you select this parsing method, you can use the predefined rules for converting events to the KUMA format by clicking Apply default mapping. If the netflow9 parsing method is selected for the main parsing, extra normalization is not available.
The default mapping rules for the netflow9 parsing method do not specify the protocol type in KUMA event fields. When parsing data in NetFlow format, on the Enrichment normalizer tab, you must create a constant data enrichment rule that adds the netflow
value to the DeviceProduct
target field.
- sflow5
This parsing method is used to process data in sflow5 format.
If you select this parsing method, you can use the predefined rules for converting events to the KUMA format by clicking Apply default mapping. If the sflow5 parsing method is selected for the main parsing, extra normalization is not available.
- ipfix
This parsing method is used to process IPFIX data.
If you select this parsing method, you can use the predefined rules for converting events to the KUMA format by clicking Apply default mapping. If the ipfix parsing method is selected for the main parsing, extra normalization is not available.
The default mapping rules for the ipfix parsing method do not specify the protocol type in KUMA event fields. When parsing data in NetFlow format, on the Enrichment normalizer tab, you must create a constant data enrichment rule that adds the netflow
value to the DeviceProduct
target field.
- sql—this method becomes available only when using a sql type connector.
The normalizer uses this parsing method to process data obtained by making a selection from the database.
- In the Keep raw event drop-down list, specify whether to store the original raw event in the newly created normalized event. Available values:
- Don't save—do not save the raw event. This is the default setting.
- Only errors—save the raw event in the
Raw
field of the normalized event if errors occurred when parsing it. This value is convenient to use when debugging a service. In this case, every time an event has a non-empty Raw
field, you know there was a problem. - Always—always save the raw event in the
Raw
field of the normalized event.
- In the Keep extra fields drop-down list, choose whether you want to store the raw event fields in the normalized event if no mapping rules have been configured for them (see below). The data is stored in the Extra event field. By default, fields are not saved.
- Copy an example of the data you want to process to the Event examples field. This is an optional but recommended step.
- In the Mapping table, configure the mapping of raw event fields to event fields in the KUMA format:
- In the Source column, provide the name of the raw event field that you want to convert into the KUMA event field.
For details about the field format, refer to the Normalized event data model article. For a description of the mapping, refer to the Mapping fields of predefined normalizers article.
Clicking the button next to the field names in the Source column opens the Conversion window, in which you can use the Add conversion button to create rules for modifying the original data before they are written to the KUMA event fields.
Available conversions
Conversions are modifications that are applied to a value before it is written to the event field. You can select one of the following conversion types from the drop-down list:
- entropy is used for converting the value of the source field using the information entropy calculation function and placing the conversion result in the target field of the float type. The result of the conversion is a number. Calculating the information entropy allows detecting DNS tunnels or compromised passwords, for example, when a user enters the password instead of the login and the password gets logged in plain text.
- lower—is used to make all characters of the value lowercase
- upper—is used to make all characters of the value uppercase
- regexp – used to convert a value using a specified RE2 regular expression. When you select this type of conversion, a field is displayed in which you must specify the RE2 regular expression.
- substring is used to extract characters in a specified range of positions. When you select this type of conversion, the Start and End fields are displayed, in which you must specify the range of positions.
- replace—is used to replace specified character sequence with the other character sequence. When you select this type of conversion, the following fields are displayed:
- Replace chars specifies the sequence of characters to be replaced.
- With chars is the character sequence to be used instead of the character sequence being replaced.
- trim removes the specified characters from the beginning and from the end of the event field value. When you select this type of conversion, the Chars field is displayed in which you must specify the characters. For example, if a trim conversion with the
Micromon
value is applied to Microsoft-Windows-Sysmon
, the new value is soft-Windows-Sys
. - append appends the specified characters to the end of the event field value. When you select this type of conversion, the Constant field is displayed in which you must specify the characters.
- prepend prepends the specified characters to the beginning of the event field value. When you select this type of conversion, the Constant field is displayed in which you must specify the characters.
- replace with regexp is used to replace RE2 regular expression results with the specified character sequence. When you select this type of conversion, the following fields are displayed:
- Expression is the RE2 regular expression whose results you want to replace.
- With chars is the character sequence to be used instead of the character sequence being replaced.
- Converting encoded strings to text:
- decodeHexString—used to convert a HEX string to text.
- decodeBase64String—used to convert a Base64 string to text.
- decodeBase64URLString—used to convert a Base64url string to text.
When converting a corrupted string or if conversion error occur, corrupted data may be written to the event field.
During event enrichment, if the length of the encoded string exceeds the size of the field of the normalized event, the string is truncated and is not decoded.
If the length of the decoded string exceeds the size of the event field into which the decoded value is to be written, such a string is truncated to fit the size of the event field.
Conversions when using the extended event schema
Whether or not a conversion can be used depends on the type of extended event schema field being used:
- For an additional field of the "String" type, all types of conversions are available.
- For fields of the "Number" and "Float" types, the following types of conversions are available: regexp, substring, replace, trim, append, prepend, replaceWithRegexp, decodeHexString, decodeBase64String, and decodeBase64URLString.
- For fields of "Array of strings", "Array of numbers", and "Array of floats" types, the following types of conversions are available: append and prepend.
In the Conversion window, you can swap the added rules by dragging them by the icon; you can also delete them using the icon.
- In the KUMA field column, select the required KUMA event field from the drop-down list. You can search for fields by entering their names in the field.
- If the name of the KUMA event field selected at the previous step begins with
DeviceCustom*
or Flex*
, you can add a unique custom label in the Label field.
New table rows can be added by using the Add row button. Rows can be deleted individually using the button or all at once using the Clear all button.
If you want KUMA to enrich events with asset information, and the asset information to be available in the alert card when a correlation rule is triggered, in the Mapping table, configure a mapping of host address and host name fields depending on the purpose of the asset. For example, the mapping can apply to SourceAddress and SourceHostName, or DestinationAddress and DestinationHostName fields. As a result of enrichment, the event card includes a SourceAssetID or DestinationAssetID field, and a link to the asset card. Also, as a result of enrichment, asset information is available in the alert card.
If you have loaded data into the Event examples field, the table will have an Examples column containing examples of values carried over from the raw event field to the KUMA event field.
- Click OK.
The normalizer is displayed as a dark circle on the Event parsing tab of the Installation Wizard. If you want to open the normalizer settings for viewing, click the dark circle. When you hover the mouse over the circle, a plus sign is displayed. Click it to add event parsing rules (see below).
Enriching normalized events with additional data
You can add additional data to newly created normalized events by creating enrichment rules in the normalizer. These enrichment rules are stored in the normalizer where they were created. There can be more than one enrichment rule.
To add enrichment rules to the normalizer:
- Select the main or additional normalization rule to open a window, and in that window, click the Enrichment tab.
- Click the Add enrichment button.
The enrichment rule parameter block appears. You can delete the group of settings using the button.
- Select the enrichment type from the Source kind drop-down list. Depending on the selected type, you may see advanced settings that will also need to be completed.
Available Enrichment rule source types:
- constant
This type of enrichment is used when a constant needs to be added to an event field. Available enrichment type settings are listed in the table below.
Available enrichment type settings
Setting
|
Description
|
Constant
|
The value to be added to the event field. Maximum length of the value: 255 Unicode characters. If you leave this field blank, the existing event field value is removed.
|
Target field
|
The KUMA event field that you want to populate with the data.
|
If you are using the event enrichment functions for extended schema fields of "String", "Number", or "Float" type with a constant, the constant is added to the field.
If you are using the event enrichment functions for extended schema fields of "Array of strings", "Array of numbers", or "Array of floats" type with a constant, the constant is added to the elements of the array.
- dictionary
This type of enrichment is used if you need to add a value from the dictionary of the Dictionary type. Available enrichment type settings are listed in the table below.
Available enrichment type settings
Setting
|
Description
|
Dictionary name
|
The dictionary from which the values are to be taken.
|
Key fields
|
Event fields whose values are to be used for selecting a dictionary entry. To add an event field, click Add field. You can add multiple event fields.
|
If you are using event enrichment with the dictionary type selected as the Source kind setting, and an array field is specified in the Key enrichment fields setting, when an array is passed as the dictionary key, the array is serialized into a string in accordance with the rules of serializing a single value in the TSV format.
Example: The Key fields setting of the enrichment uses the SA.StringArrayOne
extended schema field. The SA.StringArrayOne
extended schema field contains the values "a"
, "b"
, "c"
. The following values are passed to the dictionary as the key: ['a','b','c']
.
If the Key enrichment fields setting uses an array extended schema field and a regular event schema field, the field values are separated by the "|
" character when the dictionary is queried.
Example: The Key enrichment fields setting uses the SA.StringArrayOne
extended schema field and the Code
string field. The SA.StringArrayOne
extended schema field contains the values "a"
, "b"
, "c"
, and the Code
string field contains the myCode
sequence of characters. The following values are passed to the dictionary as the key: ['a','b','c']|myCode
.
- table
This type of enrichment is used if you need to add a value from the dictionary of the Table type. Available enrichment type settings are listed in the table below.
Available enrichment type settings
Setting
|
Description
|
Dictionary name
|
The dictionary from which the values are to be taken.
|
Key fields
|
Event fields whose values are to be used for selecting a dictionary entry. To add an event field, click Add field. You can add multiple event fields.
|
Mapping
|
Event fields for data transfer:
- Dictionary field specifies dictionary fields from which data is to be transmitted. The available fields depend on the selected dictionary resource.
- KUMA field specifies event fields to which data is to be transmitted. For some of the selected fields (
*custom* and *flex* ), in the Label column, you can specify a name for the data written there.
|
The first field in the table (Dictionary field) is taken as the key with which the fields selected from the event as key fields are matched (KUMA field). As the key in the Dictionary field, you must select an indicator of compromise by which the enrichment is to be performed, for example, IP address, URL, or hash. In the rule, you must select the event field that corresponds to the selected indicator of compromise in the dictionary field.
If you want to select multiple key fields, you can specify them using |
as a separator (when specifying in the web interface or importing as a CSV file), for example, <
IP address
>|<
user name
>
.
You can add new table rows or delete table rows. To add a new table row, click Add new element. To delete a row in the table, click the button.
- event
This type of enrichment is used when you need to write a value from another event field to the current event field. Available enrichment type settings are listed in the table below.
Available enrichment type settings
Setting
|
Description
|
Target field
|
The KUMA event field that you want to populate with the data.
|
Source field
|
The event field whose value is written to the target field.
|
Clicking opens the Conversion window, in which you can click Add conversion to create rules for modifying the source data before writing them to the KUMA event fields. You can reorder and delete created rules. To change the position of a rule, click next to it. To delete a rule, click next to it.
Available conversions
Conversions are modifications that are applied to a value before it is written to the event field. You can select one of the following conversion types from the drop-down list:
- entropy is used for converting the value of the source field using the information entropy calculation function and placing the conversion result in the target field of the float type. The result of the conversion is a number. Calculating the information entropy allows detecting DNS tunnels or compromised passwords, for example, when a user enters the password instead of the login and the password gets logged in plain text.
- lower—is used to make all characters of the value lowercase
- upper—is used to make all characters of the value uppercase
- regexp – used to convert a value using a specified RE2 regular expression. When you select this type of conversion, a field is displayed in which you must specify the RE2 regular expression.
- substring is used to extract characters in a specified range of positions. When you select this type of conversion, the Start and End fields are displayed, in which you must specify the range of positions.
- replace—is used to replace specified character sequence with the other character sequence. When you select this type of conversion, the following fields are displayed:
- Replace chars specifies the sequence of characters to be replaced.
- With chars is the character sequence to be used instead of the character sequence being replaced.
- trim removes the specified characters from the beginning and from the end of the event field value. When you select this type of conversion, the Chars field is displayed in which you must specify the characters. For example, if a trim conversion with the
Micromon
value is applied to Microsoft-Windows-Sysmon
, the new value is soft-Windows-Sys
. - append appends the specified characters to the end of the event field value. When you select this type of conversion, the Constant field is displayed in which you must specify the characters.
- prepend prepends the specified characters to the beginning of the event field value. When you select this type of conversion, the Constant field is displayed in which you must specify the characters.
- replace with regexp is used to replace RE2 regular expression results with the specified character sequence. When you select this type of conversion, the following fields are displayed:
- Expression is the RE2 regular expression whose results you want to replace.
- With chars is the character sequence to be used instead of the character sequence being replaced.
- Converting encoded strings to text:
- decodeHexString—used to convert a HEX string to text.
- decodeBase64String—used to convert a Base64 string to text.
- decodeBase64URLString—used to convert a Base64url string to text.
When converting a corrupted string or if conversion error occur, corrupted data may be written to the event field.
During event enrichment, if the length of the encoded string exceeds the size of the field of the normalized event, the string is truncated and is not decoded.
If the length of the decoded string exceeds the size of the event field into which the decoded value is to be written, such a string is truncated to fit the size of the event field.
Conversions when using the extended event schema
Whether or not a conversion can be used depends on the type of extended event schema field being used:
- For an additional field of the "String" type, all types of conversions are available.
- For fields of the "Number" and "Float" types, the following types of conversions are available: regexp, substring, replace, trim, append, prepend, replaceWithRegexp, decodeHexString, decodeBase64String, and decodeBase64URLString.
- For fields of "Array of strings", "Array of numbers", and "Array of floats" types, the following types of conversions are available: append and prepend.
When using enrichment of events that have event selected as the Source kind and the extended event schema fields are used as arguments, the following special considerations apply:
- If the source extended event schema field has the "Array of strings" type, and the target extended event schema field has the "String" type, the values are written to the target extended event schema field in TSV format.
Example: The SA.StringArray
extended event schema field contains values: "string1"
, "string2"
, "string3"
. An event enrichment operation is performed. The result of the event enrichment operation is written to the DeviceCustomString1
extended event schema field. The DeviceCustomString1
extended event schema field contains values: ["string1", "string2", "string3"]
.
- If the source and target extended event schema fields have the "Array of strings" type, values of the source extended event schema field are added to the values of the target extended event schema field, and the "
,
" character is used as the delimiter character.Example: The SA.StringArrayOne
field of the extended event scheme contains the ["string1"
, "string2"
, "string3"]
values, and the SA.StringArrayTwo
field of the extended event scheme contains the ["string4", "string5", "string6"]
values. An event enrichment operation is performed. The result of the event enrichment operation is written to the SA.StringArrayTwo
field of the extended event scheme. The SA.StringArrayTwo
extended event schema field contains values: ["string4", "string5", "string6", "string1", "string2", "string3"]
.
- template
This type of enrichment is used when you need to write the result of processing Go templates into the event field. We recommend matching the value and the size of the field. Available enrichment type settings are listed in the table below.
Available enrichment type settings
Setting
|
Description
|
Template
|
The Go template. Event field names are passed in the {{.EventField}} format, where EventField is the name of the event field from which the value must be passed to the script, for example, {{.DestinationAddress}} attacked from {{.SourceAddress}} .
|
Target field
|
The KUMA event field that you want to populate with the data.
|
If you are using enrichment of events that have template selected as the Source kind, and in which the target field has the "String" type, and the source field is an extended event schema field containing an array of strings, you can use one of the following examples for the template:
To convert the data in an array field in a template into the TSV format, use the toString
function, for example:
template {{toString .SA.StringArray}}
- In the Target field drop-down list, select the KUMA event field to which you want to write the data.
This setting is not available for the enrichment source of the Table type.
- If you want to enable details in the normalizer log, set the Debug toggle switch to enabled. Details are disabled by default.
- Click OK.
Event enrichment rules with the additional data are added to the normalizer, to the selected parsing rule.
Configuring parsing linked to IP addresses
You can direct events from multiple IP addresses, from sources of different types, to the same collector, and the collector will apply the corresponding configured normalizers.
You can use this method for collectors with a connector of the UDP, TCP, or HTTP type. If a UDP, TCP, or HTTP connector is specified in the collector at the Transport step, then at the Event parsing step, you can specify multiple IP addresses on the Parsing settings tab and choose the normalizer that you want to use for events coming from the specified addresses. The following types of normalizers are available: json, cef, regexp, syslog, csv, kv, xml.
In a collector with configured normalizers linked to IP addresses, if you change the connector type to any type other than UDP, TCP, HTTP, the Parsing settings tab disappears and only the first of the previously specified normalizers is specified at the Parsing step. The tab disappears from the web interface immediately, but the changes are applied after the resource is saved. If you want to restore the previous settings, exit the collector installation wizard without saving.
For normalizers of the Syslog and regexp types, you can use a normalizer chain by specifying extra normalization conditions depending on the value of the DeviceProcessName field. The difference from extra normalization is that you can specify shared normalizers.
To configure parsing with linking to IP addresses:
- At the Event parsing step, go to the Parsing settings tab.
- In the IP address(-es) field, specify one or more IP addresses from which events will be received. You can specify multiple IP addresses separated by commas. Available format: IPv4. The length of the address list is unlimited; however, we recommend specifying a reasonable number of addresses to keep the load on the collector balanced. This field is mandatory if you want to apply multiple normalizers in one collector.
Limitation: for each IP+normalizer combination, the IP address must be unique. KUMA checks the uniqueness of addresses, and if you specify the same IP address for different normalizers, the "The field must be unique" message is displayed.
If you want to send all events to the same normalizer without specifying IP addresses, we recommend creating a separate collector. We also recommend creating a separate collector with one normalizer if you want to apply the same normalizer to events from a large number of IP addresses; this helps improve the performance.
- In the Normalizer field, create a normalizer or select an existing normalizer from the drop-down list. The arrow next to the drop-down list takes you to the Parsing schemes tab.
Normalization is triggered if you have a connector type configured: UDP, TCP, HTTP; the event source header must be specified in the HTTP case.
Taking into account the available connectors, the following normalizer types are available for automatic source recognition: json, cef, regexp, syslog, csv, kv, xml.
- If you selected the Syslog or regexp normalizer type, you can Additional condition. Conditional normalization is available if Field mapping for DeviceProcessName is configured in the main normalizer. Under Condition, specify the process name in the DeviceProcessName field and create a normalizer or select an existing normalizer from the drop-down list. You can specify multiple combinations of DeviceProcessName + normalizer, normalization is performed until the first match is achieved.
Parsing with linking to IP addresses is configured.
Creating a structure of event normalization rules
To implement a complex event processing logic, you can add multiple event parsing rules to the normalizer. Events are transmitted between the parsing rules depending on the specified conditions. The sequence of creating parsing rules is important. The event is processed sequentially, and its path is shown using arrows.
To create an additional parsing rule:
- Create a normalizer (see above).
The created normalizer is displayed in the window as a dark circle.
- Hover the mouse over the circle and click the plus sign button that appears.
- In the Additional event parsing window that opens, specify the parameters of the additional event parsing rule:
- Extra normalization conditions tab:
If you want to send a raw event for extra normalization, select Yes in the Keep raw event drop-down list. The default value is No. We recommend passing a raw event to normalizers of json and xml types. If you want to send a raw event for extra normalization to the second, third, etc nesting levels, at each nesting level, select Yes in the Keep raw event drop-down list.
To send only the events with a specific field to the additional normalizer, specify this field in the Field to pass into normalizer field.
On this tab, you can also define other conditions. When these conditions are met, the event is sent for additional parsing.
- Normalization scheme tab:
On this tab, you can configure event processing rules, similar to the main normalizer settings (see above). The Keep raw event setting is not available. The Event examples field displays the values specified when the initial normalizer was created.
- Enrichment tab:
On this tab, you can configure event enrichment rules (see above).
- Click OK.
The additional parsing rule is added to the normalizer. It is displayed as a dark block with the conditions under which this rule is triggered. You can change the settings of the additional parsing rule by clicking it. If you hover the mouse over the additional parsing rule, a plus button appears. You can use this button to create a new additional parsing rule. To delete a normalizer, use the button with the trash icon.
The upper right corner of the window contains a search window where you can search parsing rules by name.
Proceed to the next step of the Installation Wizard.
Page top