Custom Property Definitions in the DSM Editor

Selectivity

In the DSM Editor, you can restrict running a custom property to certain criteria for better performance.

The following are the types of restrictions:

• By high-level category and low-level category -- A property is evaluated only when the high-level and low-level categories match a specific combination. For example, a property is evaluated only when the event is known to have a high-level category of Authentication and a low-level category of Admin Logout.

• By specific QID -- A property is evaluated only when the event that is seen maps to a specific QID. For example, when the event maps to a QID of Login Failed, the property is evaluated.

Creating a Custom Property

In the DSM Editor, you can define a custom property for one or more log sources, whose events do not fit into the JSA normalized event model. For example, a system property might fail to capture data from some applications, operation systems, databases, and other systems.

You can create custom property for data that does not fit into JSA system properties. Use the custom properties in searches and test against them in rules.

1. On the Properties tab in the DSM Editor, click the Add (+).

2. To create a new custom property definition, use the following steps:

   1. On the Choose a Custom Property Definition to Express page, select Create New.

   2. On the Create a new Custom Property Definition page, configure the parameters in the following table.

      Table 1: Custom Property Parameters

      Parameter	Description
      Name	A descriptive name for the custom property that you create.
      Field Type	The default is Text. Note: When you select Number or Date from the Field Type list, extra fields are displayed.
      Enable this Property for use in Rules and Search Indexing	When this option is enabled, during the parsing stage of the event pipeline, JSA attempts to extract the property from events immediately as they enter the system. Other components downstream in the pipeline such as rules, forwarding profiles and indexing can use the extracted values. Property information is persisted along with the rest of the event record and doesn't need to be extracted again when it is retrieved as part of a search or report. This option enhances performance when the property is retrieved, but can have a negative impact on performance during the event parsing process, and impacts storage. When this option is not enabled, JSA extracts the property from the events only when they are retrieved or viewed. Note: To use Custom Properties in rule tests, forwarding profiles, or for search indexing, make sure that this checkbox is selected. Rule evaluation, event forwarding, and indexing occur before events are written to disk, so the values must be extracted at the parsing stage.
      Use number format from a Locale	This field displays when you select Number from the Field Type list. If you select the Use number format from a Locale check box, you must select an Extracted Number Format from the list.
      Extracted Date/Time Format	This field displays when you select Date from the Field Type list. You must provide a datetime pattern that matches how the datetime appears in the original event. For example, 'MMM dd YYYY HH:mm:ss' is a valid datetime pattern for a time stamp like 'Apr 17 2017 11:29:00'.
      Locale	This field displays when you select Date from the Field Type list. You must select the locale of the event. For example, if the locale is English, it will recognizes 'Apr' as a short form of the month 'April'. But if the event is presented in French and the month token is 'Avr' (for Avril), then set the locale to a French one, or the code does not recognize it as a valid date.

   3. If you want to extract the property from events as they enter the system, select the Enable this property for use in Rules and Search indexing check box.

   4. Click Save.

3. To use an existing custom property, use the following steps:

   1. On the Choose a Custom Property Definition to Express page, search for an existing custom property from the Filter Definitions field.

   2. Click Select to add the custom property.

Expressions

You can define expressions for custom properties in the DSM Editor. Expressions are the mechanism that defines the behavior of a property. The main component of an expression is a valid regex or JSON. The data that makes up an expression depends on the property type.

For a custom property, you can choose only one capture group from the regex.

Configuring a custom property expression

You can use different expressions to capture various custom properties for the same event. You can also use a combination of expression types to capture the same custom property if that property can be captured from multiple event formats.

JSA supports the following custom property expression types:

• Regex

• JSON

• LEEF

• CEF

• Name Value Pair

• Generic List

• XML

1. On the Properties tab, locate and select the custom property. Custom properties display the word Custom next to them to differentiate them from system properties.

2. Select an expression type from the Expression Type list and define a valid expression for it.

   Note:

   • For Regex, the expression must be a valid java-compatible regular expression. Case-insensitive matching is supported only by using the (?i) token at the beginning of the expression. The (?i) token is saved in the log source extension .xml file. To use other expressions, such as (?s), manually edit the log source extension .xml file.

   • For JSON, the expression must be a path in the format of /"<name of top-level field>" with additional /"<name of sub-field>" subobjects to capture subfields if any.

   • To capture the value of a key-value pair for LEEF and CEF, set the expression to the key.

   • To capture the value of a header field, set the expression to the corresponding reserved word for that header field.

3. If the expression type is Regex, select a capture group.

4. To limit an expression to run against a specific category, click Edit to add selectivity to the custom property, and select a High Level Category and a Low Level Category.

5. To limit an expression to run against a specific event or QID, click Choose Event to search for a specific QID.

6. In the Expression window, click Ok.

7. To add multiple expressions and reorder them, follow these steps:

   • Click Add (+) in the expressions list.

   • Drag expressions in the order that you want them to run.

Deleting a custom property expression

You can delete a custom property expression in the DSM Editor. If you delete a custom property expression, only the expression is deleted. The custom property is not deleted.

1. On the Admin tab, click DSM Editor.

2. In the Select Log Source Type window, choose a log source type and click Select.

3. In the Log Source Type pane, select the custom property with the expression that you want to delete.

4. In the Property Configuration section, select the expression that you want to delete and click the delete icon

   .

5. Click Delete.