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.
Request Headers
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.
Request Body
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
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>"
]
}
Request Parameters
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 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:
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. |
For step by step details on building a request, see Build a Query Request.
Response Status Codes
This request can return the following status codes:
200: Success OK
Response Schema
The response contains these fields:
For step by step details on using the response, see View the Query Response.
Example
For a list of examples, see Use-case Examples.