Customize Query Response Fields

The Cybereason platform collects and reports data about each Element that a query specifies, including characteristics and behaviors of that Element and relationships of that Element to other Elements. For example, for a Process Element, the platform shows characteristics that include the process name, command line, ID, and behaviors. The platform also shows related Elements, such as machines on which the process runs and connections the process opens.

Because of this data model and connections, when you build a query using the API, you can specify Features about the target Element in your query about which you would like to see details in the response. For example, if your query is based on a Process Element, you can view details about any Feature for the Process Element in the response - provided you add the fields in the request body appropriately.

Specifying Features about which to view details in the response is different from the Feature used as a filter for the Element. When you add a Feature filter, you ask the Cybereason platform to return instances which match the Feature. When you add Features about which to view details in the response, you ask the Cybereason platform to return details about the results instance relevant to the Features added. For example, if your query searches for processes named chrome.exe, the Cybereason platform only returns instances of the chrome.exe processes. however, if you add the Features to view the command line of these processses, in the response, you will see details about the command line for all chrome.exe processes returned in the query results/response.

By default, the response for a query request in the API returns data about a specific pre-selected Features of the Element. In some dcases, these Features may not be the Features about which you need to view details.

To instruct Cybereason to return specific data for Features relevant to the target Elements, add Features in the customFields object.

Use customFields to add Features to the response

To view data related to specific Features of the selected Element in the query, add Feature names in the customFields object. This object is found toward the end of the query request.

For a list of available Features for each Element, see Query Elements and Features.

Note

This action corresponds to selecting columns to display in the Investigation screen.

{
  "name": "query",
  "request": {
    "url": "https://<WebApp server address>/rest/visualsearch/query/simple",
    "method": "POST",
    "header": [
      {
        "key": "Content-Type",
        "value": "application/json",
        "description": "<your description>"
      }
    ],
    "body": {
      "queryPath": [
        {
          "requestedType": "<type>"
        }
      ],
      "customFields": [
        "<field name>",
        "<field name>",
        "<field name>"
      ]
    }
  }
}

Use templateContext to specify the level of detail

Use the templateContext field to specify general settings for the level of details that the elementValues object includes. The elementValues object includes details on Elements related to the Element that is the center part of your query.

The templateContext field accepts the following values:

• OVERVIEW

• MALOP

• DETAILS

• MALOP_COMMUNICATION

• CUSTOM

• SPECIFIC

• FULL

To make sure your that query returns the correct level of detail, use one of the following values.

Value	Description
DETAILS	The DETAILS value returns a preconfigured set of Features for the selected Element, as well as the name of the referenced Elements. Referenced Elements are visible in the elementValues object. The number of Elements returned is the limit defined in the perFeatureLimit parameter. The response does not contain the suspicionsMap or evidenceMap object.
CUSTOM	The CUSTOM value enables you to specify the Features that you want to return in the customFields object. You use this value if you assign non-default Element fields for the customFields object. In addition, the elementValues class includes the names of any referenced Elements. To define the number of Elements to return, use the perFeatureLimit parameter. The response does not contain the suspicionsMap or evidenceMap object.
SPECIFIC	When you use the SPECIFIC value, the elementValues object in the response includes the names of any referenced Elements. In addition, the response includes the suspicionsMap object with the Suspicion name and a timestamp (in epoch) for when the Suspicion was first detected.

Note

The templateContext field is also part of the request body to retrieve a list of Malops. You should not modify the default value for the templateContext field when you retrieve Malops as this may cause unexpected behavior.