JSON keypath expressions

To uniquely identify the fields that you want to extract from a JSON object, your JSON expression must follow specific JSON keypath conventions.

Use the following guidelines for your JSON keypath expressions:
  • A forward slash (/) must be at the start of all JSON keypaths. All paths must start at the beginning of the root JSON object. Subsequent slashes in the keypath indicate access to fields that are nested in the JSON object.
  • Field names must be enclosed in double quotation marks.

    A valid path might look like the following example: 

    /"object"/"nestedObject"/"furtherNestedObject"/"desiredPropertyName"
  • Square brackets indicate the handling of JSON arrays.

    If you do not supply an index in the square brackets, the entire body of the array is extracted. If you supply an index in the square bracket, that index in the array is extracted or nested. Arrays begin at a zero index, where 0 is the first index in the array, 1 is the second index in the array, and so on.

    In the following keypath example, the JSON parser looks into the second index of the "object" JSON array, and then within that array index, looks for a field called "desiredPropertyName".

     /"object"[1]/"desiredPropertyName"
  • Within log source extensions, you can supply and combine together multiple JSON keypaths to give a single result; this convention excludes custom properties. You can also choose to include literal text. Each of the JSON keypaths must be enclosed in curly braces.

    Consider the following example:

    {/"object"/"nestedObject"/"desiredPropertyName1"} {/"object"/"nestedObject"/"desiredPropertyName2"}

    You get a parsed value from the first JSON keypath, a literal text space, and then a parsed value from the second JSON keypath.

Example: The following two examples show how to extract data from a JSON object:
  • Simple case of a JSON object:
    [{"name":"object1","field1":"value1"}, {"name":"object2","field2":"value2"},
 {"name":"object3","field3":"value3"}]

    The following table shows the values that are extractable from the keypaths in that sample object:

    Table 1. Keypaths from the simple JSON object
    Keypaths Description Value
    /[] Extracts the entire JSON array from the root of the JSON object. 
    [{"name":"object1","field1":"value1"},
{"name":"object2","field2":"value2"},
{"name":"object3","field3":"value3"}]
    /[1]/"name" Extracts the value for the attribute called "name" from the JSON object at index 1 in the root JSON array. object2
  • Complex case of a JSON object:
    <13>May 22 10:15:41 log.test.com {"module":"CPHalo","version":"1.0","user_name":"user123",
"event_type":"File integrity scan request created",
"event_category":"File Integrity Scanning Management","srcName":"domain-lab-123",
"timestamp":"2018-12-02T15:36:17.486","user":{"email":"user123@example.com","first_name":"fname",
"last_name":"lname","alias":["alias name","alias1","name"]},"client_ip":"12.12.12.12",
"server_id":"12317412471421274","server_reported_fqdn":"None","actor_country":"USA",
"server_group_name":"Example Server","server_platform":"Linux",
"message":"A file integrity monitoring scan was requested for Linux server domain-lab-123
 (13.13.13.13) by Halo user user123@example.com from IP address 12.12.12.12 (USA).",
"type":"fim_scan_request_created","id":"c2e8bf72-b74f-11e2-9055-870a490fcfb6"}

    The following table shows the values that are extractable from the keypaths in that sample object:

    Table 2. Keypaths from the complex JSON object
    Keypaths Description Value
    /"user_name" Extracts value of the "user_name" attribute from the root of the JSON object. user123
    /"user"/"alias"[] Extracts the entire JSON array called "alias" that is nested under the "user" JSON object. ["alias name","alias1","name"]
    /"user"/"alias"[0] Extracts the value at index 0 within the "alias" JSON array that is nested under the "user" JSON Object. alias name
    /"user"/'first_name" Extracts the value of the property called "first_name" that is nested under the "user" JSON Object. fname
    {/"user"/"first_name"}.{/"user"/"last_name"} Extracts the value of the property called "first_name" that is nested under the "user" JSON object, then inserts a literal '.' character, and then extracts the value of the property called "second_name" that is nested under the "user" JSON object.

    Pertains only to log source extensions and non-custom properties within the DSM Editor. This operation is not possible in custom properties.

    		 fname.lname
    {/"user"/"alias"[1]}@{/"client_ip"} Extracts the value at index 1 of the "alias" JSON array that is nested under the "user' JSON object, inserts a literal '@' character, and then extracts the value of the property called "client_ip" under the root JSON object.

    Pertains only to log source extensions and non-custom properties within the DSM Editor. This operation is not possible in custom properties.

    		 alias1@12.12.12.12