Run a Query

Endpoint URL: https://<your server>/rest/visualsearch/query/simple
Endpoint URI: visualsearch/query/simple

Action: POST

Run invesitgation queries to search for specific indicators and behaviors throughout your environment.

Note

Ensure that you have logged into the Cybereason platform. For details, see Log in with the API.

You must add an Content-Type:application/json header with the request.

Note

If you are using cURL, add the authorization cookie details or the path to the file with cookie details with every request.

When sending this request, there may be a delay in returning a response, depending on how much data and activity is in your system. Ensure you do not send this request multiple times while waiting for a response as this may cause unexpected results and performance in your environment.

Note that this request body syntax contains all the possible values you can use for a query request. Not all these fields are required for each request. See the Request Parameters section for details on required and optional parameters.

Note

You can quickly create the request body by running a query in the Investigation screen. Before you run the query, open the Chrome developer tools window and navigate to the Network tab. In the Network tab, find the Request Body section and copy the JSON found there as the body of your request.

Input: JSON

Request JSON syntax file

Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.

{
              "queryPath": [
                {
                  "requestedType": "<type>",
                  "guidList": [
                    "<GUID ID>",
                    "<GUID ID>",
                    "<GUID ID>"
                  ],
                  "timeRange": {
                    "startFeatureId": "creationTime",
                    "startTime": "<start time>",
                    "endTime": "<end time>"
                  },
                  "filters": [
                    {
                      "facetName": "<value>",
                      "values": [
                        "<value>",
                        "<value>",
                        "<value>"
                      ],
                      "filterType": "<value>"
                    }
                  ],
                  "connectionFeature": {
                    "elementInstanceType": "<value>",
                    "featureName": "<value>"
                  },
                  "isResult": "<Boolean value>",
                  "reversed": "<Boolean value>"
                }
              ],
              "templateContext": "<value>",
              "totalResultLimit": "<limit>",
              "perGroupLimit": "<limit>",
              "perFeatureLimit": "<limit>",
              "queryTimeout": "<value>",
              "customFields": [
                "<field name>",
                "<field name>",
                "<field name>"
              ]
            }

URL/URI parameters none

Request Body Parameters: The request can contain any of these fields. Required fields are shown in bold.

Field	Type	Value
requestedType	String	The Element by which to query. For details on the available Elements, see Query Elements and Features. You must add at least one requestedType parameter.
guidList	Array	The list of GUIDs by which to filter the Element.
timeRange	Array	An object containing the details on time filters. This contains a startFeatureId or endFeatureId field, startTime field, and endTime field.
startFeatureId	String	The name of the time-based Feature for the timeRange object. The time-based fields differ depending on the Element. For details on the available fields for each Element, see Query Elements and Features.
endFeatureId	String	The name of the time-based Feature for the timeRange object. The time-based Features different depending on the Element. For details on the available fields for each Element, see Query Elements and Features
startTime	Integer	The start time (in epoch) of the period during which to search.
endTime	Integer	The end time (in epoch) of the period during which to search.
filters	Array	An object containing the Features to use to filter Elements. For more details on using filters, see Add Filters to a Request.
facetName	String	The name of the Feature for the filter. For details on available features, see Query Elements and Features.
values	String	The values to use for the selected Feature. Note the following: For String type Features, the values are the string or strings by which to search. For Boolean type Features, the values are true or false. For enum type Features, the values are one or more of the possible values available for this Feature. For Long or Integer type Features, the values are the value by which to search. For details on the data type of each Feature, see Query Elements and Features.
filterType	String	The operator to use for the value. The available operators differ depending on the Feature type. For details on the available operators, see the Add Operators to Filters.
connectionFeature	Array	An object describing the relationship with the next Element in the chain. For details, see Build a Query Chain.
elementInstanceType	String	The Element to which the connecting Feature belongs.
featureName	String	The Feature used to connect Elements. For a list of Features available to connect Elements in a chain, see Build a Query Chain.
isResult	Boolean	Specifies the item for which results are shown. Only one item can have a value of true. You must add an isResult parameter to one of the Elements in the query.
isReversed	Boolean	Specifies whether the connecting Feature is defined on the second item in the chain.
templateContext	Enum	The level of detail to provide in the response. Possible values include: OVERVIEW DETAILS SPECIFIC FULL MALOP MALOP_COMMUNICATION For details on what is displayed for each value, see Customize Query Response Fields.
totalResultLimit	Integer	The total number of results to return. Beginning in version 20.1.381 and later, the default value for this field is 100 and the maximum value is 1000.
perGroupLimit	Integer	The maximum number of elements in a group of results. Results are grouped by the Element and Feature set in the groupingFeature object.
perFeatureLimit	Integer	The maximum number of results to return per Feature added in the customFields object. This will limit the number of referenced Features for the Element in the query in response details.
groupingFeature	Array	An object containing details about which Element and Feature to use to group the response details. In this array you specify the elementInstanceType field to specify a specific Element for grouping, and a featureName parameter for the Element Feature. For details on how to add these filters, see the Limit Results in the Response.
queryTimeout	Long	The amount of time, in milliseconds, after which the query will terminate, even if not finished.
customFields	Array	An object containing a list of Features about which to return data for the selected Elements. For a list of multiple items, add commas between each item. For details about the available Features to use in this object, see Query Elements and Features.