Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Custom Property Definitions in the DSM Editor

 

You can define a custom property and reuse the same property in a separate DSM. Use these properties in searches, rules, and to allow specific user-defined behavior for parsing values into those fields.

Where relevant, each custom property has a set of configuration options that includes selectivity and data parsing. Each custom property definition within a DSM configuration is an ordered group of expressions that consists of regular expressions, a capture group, an optional selectivity configuration, and an enabled or disabled toggle button. You can't modify the Name, Field type, Description, optimize fields, or any advanced options for a custom property on the Properties tab in the DSM Editor.

A custom property is shared across all DSMs, while specific implementations for reading values from payloads are at the DSM level.

Selectivity is specified when you configure an expression to run only when certain conditions are met.

Note

The Capture Group field of a custom property cannot be assigned a value greater than the number of capture groups in the regex.

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.

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

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.

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 enabled, JSA attempts to extract the property from events immediately as they enter the system. 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 enhances performance when the property is retrieved, but can have a negative impact on performance during the event collection process, as well as an impact to storage.

Note: For Custom Properties to be used in rule tests or for search indexing, this option must be checked, because indexing and rule evaluation occurs before events are written to disk.

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 that displays.

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 timestamp 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 recognize '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 won't recognize it as a valid date.

  1. To add a custom property, click the Add (+) icon on the Properties tab in the DSM Editor.
  2. To create a new custom property definition, use the following steps:
    1. Select Create New on the Choose a Custom Property Definition to Express page.

    2. On the Create a new Custom Property Definition page, enter values for the name, field type and description fields.

      Note

      When you select Number or Date from the Field Type list, extra fields display.

    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.

  4. To configure a custom property, use the following steps:
    1. Locate and select the custom property on the Properties tab. Custom properties have the word Custom next to them, to differentiate them from system properties.

    2. Select an expression type (Regex or JSON) from the Expression Type list.

    3. Define a valid expression for the custom property based on the expression type selected in step b.

      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>" to capture sub-fields if any.

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

    5. Optional: 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.

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

    7. From the Expression window, click Ok.

  5. To add multiple expressions and reorder them, follow these steps:
    1. Click the Add (+) icon at the top of the expressions list.

    2. Drag and drop expressions in the order that you want them to run.