Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Defining Custom Properties by Using Custom Property Expressions

Define a custom property for an event payload by using a custom property expression. Because JSON parsing begins when a valid JSON object is detected, the entire event does not need to be in JSON format. Similarly, LEEF and CEF parsing begins only when a valid LEEF/CEF message is detected within the event. Regex parsing runs through the entire payload.

JSA supports the following custom property expression types:

  • Regex

  • JSON

  • LEEF

  • CEF

  • Name Value Pair

  • Generic List

  • XML

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.

  1. Log in to JSA and click the Admin tab.
  2. From the Data Sources section, click Custom Event Properties, and then click Add.
  3. In the Property Type Selection section, select Extraction Based.
  4. In the Test Field, enter the event payload that you want to use to test your custom property.
  5. In the Property Definition section, complete the following steps:

    1. If you're adding an expression to an existing property, select Existing Property and select a property from the list.

    2. If you're defining a new property, select New Property and enter the name of the property.

    3. To use the property for rules, reports and searches, select the Parse in advance for rules, reports, and searches check box.

      You must select this check box to use the property for rules and indexes. Selecting the check box increases the efficiency of reports and searches, but you don't need to select it to use the property for reports and searches. When you select the check box, properties are parsed when the event is initially received and before it is stored. As a result, the loads are put on the event collection service.

    4. Select a Field Type for the property.

      If you choose IP as the type for your custom property, JSA supports only IPv4.

    5. Optional: Enter a description for the property.

  6. In the Property Expression Definition section, complete the following steps:

    1. Keep the Enabled check box selected; otherwise, clear the check box to disable the property.

    2. From the Log Source Type list, select a log source type for the property.

    3. If the expression is only evaluated against events for a specific log source, select the log source from the Log Source list. If you want it to be evaluated against all log sources, don't select.

    4. If the expression is only evaluated against events with a specific event name or QID, click the Event Name and browse for a QID to associate the expression with.

    5. If the expression is evaluated against any event with a specific low-level category, select Category, and select the High Level Category and then Low Level Category for the event.

      Note:

      If the expression is evaluated for all events of the selected log source type and log source, ensure that you set the Low Level Category and High Level Category to Any.

    6. From the Extraction using field, select the extraction method to use for the property.

      Table 1: Property Extraction Methods

      Extraction Method

      Valid Expression Form

      Example

      Regex

      Enter the regex and the capture group number.

      		  

      JSON Keypath

      A valid JSON expression is in the form:

      /"<name of top-level field>"

      For an event in a nested JSON format, a valid JSON expression is in the form:

      /"<name of top-level field>"/"<name of sub-level field>"..../"<name of sub-level field_n>"

      To extract the 'user' field, type /"user" in the JsonKeypath field.

      To extract just the 'last_name' value from the 'user' subobject, type this expression:

      /"user"/"last_name"

      The following example is a simple case of an event for a flat JSON record:

      {"action": "login", "user": "Firstname Lastname"}

      The following example is a complex case of an event for a JSON record with nested objects:

      { "action": "login", "user": { "first_name": "Firstname", "last_name": "Lastname" } }

      LEEF Key

      Valid LEEF expressions are in the form of either a single key reference, or a special LEEF header field reference.

      To extract the 'usrName' property, type usrName in the LEEF Key field.

      The possible keys that can be extracted in these examples are:

      1. - devTimeFormat

      2. - devTime

      3. - usrName

      4. - name

      5. - authType

      6. - src

      To extract a header key property, type the key in the following format in the LEEF Key field:

      $eventid$

      The LEEF header values can be extracted by using the following expressions:

      1. - $leefversion$

      2. - $vendor$

      3. - $product$

      4. - $version$

      5. - $eventid$

      The following example is a simple case of an event that is formatted in LEEF V1.0:

      LEEF:1.0|ABC Company|SystemDefender |1.13|console_login|devTimeFormat =yyyy-MM-dd’T’HH:mm:ss. SSSZ devTime=2017-10-18T11:26:03.060+0200 usrName=flastname name= Firstname Lastname authType =interactive Password src=192.168.0.1

      The following example is a simple case of an event that is formatted in LEEF V2.0 with the caret (^) separator character, and contains the same keys as the LEEF V1.0 example:

      LEEF:2.0|ABC Company|SystemDefender|1.13| console_login|^|devTimeFormat =yyyy-MMdd’T’HH:mm:ss.SSSZ^ devTime=2017-10-18T11:26:03.060+0200 ^usrName=flastname^name= Firstname Lastname ^authType =interactive Password^src=192.168.0.1

      CEF Key

      Valid CEF expressions are in the form of either a single key reference, or a special CEF header field reference.

      To extract the 'cs1' property, type cs1 in the CEF Key field.

      The possible keys that can be extracted in the example are:

      1. - start

      2. - duser

      3. - cs1

      4. - cs1Label

      5. - cs2

      6. - cs2Label

      7. - src

      To extract a header key property, type the key in the following format in the CEF Key field:

      $id$

      The CEF header values can be extracted by using the following expressions:

      1. - $cefversion$

      2. - $vendor$

      3. - $product$

      4. - $version$

      5. - $id$

      6. - $name$

      7. - $severity$

      The following example shows an event that is in CEF format:

      CEF:0|ABC Company| SystemDefender|1.13| console_login| Console Login|1|start=Oct 18 2017 11:26:03 duser=flastname cs1=Firstname Lastname cs1Label=Person Name cs2=interactivePassword cs2Label=authType src=192.168.0.1

      Name Value Pair Key

      Valid Name Value Pair expressions are in the form of a single key reference.

      The following example shows an event that is in Name Value Pair format:

      Company=ABC Company;Product=SystemDefender; Version=1.13;EventID=console_login; Username=jsmith;Name=John Smith;authType=interactivePassword;

      Generic List Keypath

      Valid Generic List expressions are in the form of a $<number>notation. For example, $0 represents the first property in the list, $1 is the second property, and so on.

      The following example shows an event that is in Generic List format:

      ABC Company;1.13;console_login;jsmith; John Smith;interactivePassword;

      XML Key

      Valid XML expressions are in the form of a single key reference.

      Enter the path to the XML field that you want to use to populate the property's value. An XML key path must begin with a forward slash (/) to indicate the root of the XML object, and be followed by one or more XML field names within double quotation marks.

      The following example shows an event that is in XML format:

      <EPOEvent><MachineInfo> <MachineName>NEPTUNE< /MachineName><MachineName >VALUE23</MachineName> <AgentGUID>9B-B5-A6-A8-37-B3< / AgentGUID><IPAddress someattrib ="someattribvalue">192.0.2.0 </IPAddress><OSName>Windows 7</ OSName> <UserName>I am a test user <UserName></MachineInfo> </EPOEvent>

    7. If you chose the Numeric Field Type in the Property Definition section, select a number format in the Extracted Number Format field in the Format section to define any digit group separators for the locale of the custom property.

    8. If you chose the Date/Time Field Type in the Property Definition section, enter a format in the Extracted Date/Time Format and Locale fields in the Format section to define the date and time for the locale of the custom property.

    9. Click Test to test the property expression definition.

  7. Click Save.

Related Documentation