Run a Simple Investigation Query
In this tutorial, we will explain, step-by-step, how to create a simple investigation query (with a single Element and Feature) with the Cybereason API.
For the purposes of this tutorial, we will use the scenario where you search for processes downloaded from the Internet. In the Investigation screen, this would be the query:
You must have the Analyst L1, Analyst L2, or Analyst L3 role to perform this request.
When performing investigations, if you are frequently running the same investigation query on a regular basis, it may be more efficient for you to automate the running of a query and analysis of the results. The Cybereason API can help you automate the running on investigation queries.
In this topic:
Build the request body
Note
The request body is the same regardless of how you run the request (such as a cURL command, in a REST API client, or Python script).
In your REST API client, open a new/tab file.
In the relevant field, enter the URL for the request:
https://<your server address>/rest/visualsearch/query/simple
For example, in Postman, you enter the URL here:
Ensure that the method for the request is set to POST. (This may be the default for your REST API client, but if not, ensure that you select it.)
For the Headers, in the Key column, add a Content-Type header.
In the Value column, add the value application/json.
For example, in Postman, your header will look like this:
Navigate to the section to add your request body. In Postman, for example, this is the Body tab.
In the Body tab, ensure that you have set your client editor to enable you to add raw JSON content. In Postman, for example, ensure that Raw is selected.
In the request body edit area, enter an open and closed bracket {}. This is the standard syntax for JSON.
Inside the bracket, add this template request body:
{ "queryPath": [ { "requestedType": "<type>", "filters": [ { "facetName": "<value>", "values": [ "<value>", ], "filterType": "<value>" } ], "isResult": "<Boolean value>", } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "<field name>", "<field name>", "<field name>" ] }
In this requeset body, you will need to provide a number of fields, including the Element name and the Feature by which to filter.
For this request, you enter the Element and Feature by which to filter in the queryPath object in the request body. As we mentioned previously, you are going to create a query to find processes downloaded from the internet. Therefore, you need to add the Process Element in the queryPath object.
In the API, each Element has a unique name. Sometimes, these Element names are the same as the Element name in the Investigation screen. For the Process Element (the target Element of this example query), in the API, the Process Element uses the name Process. For a full list of of all Elements and their names in the API, see Query Elements and Features.
In the request body, in the queryPath object, in the requestedType key, update the <type> placeholder value with Process:
{ "queryPath": [ { "requestedType": "**Process**", "filters": [ { "facetName": "<value>", "values": [ "<value>", ], "filterType": "<value>" } ], "isResult": "<Boolean value>", } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "<field name>", "<field name>", "<field name>" ] }
In addition, for each Element, you have a number of Features with which you can filter results. These Features represent different characteristics or behaviors for the Element.
Like Elements, each Feature has a unique name. For the sample query, you will use the Downloaded from Internet Feature. In the API, this Feature has the name isDownloadedFromInternet.
For a full list of all Features you can use for any Eleent, see Query Elements and Features and expand the list of Features for your Element.
In the queryPath object, for the facetName key, replace the <value> placeholder value with isDownloadedFromInternet.
{ "queryPath": [ { "requestedType": "Process", "filters": [ { "facetName": "**isDownloadedFromInternet**", "values": [ "<value>", ], "filterType": "<value>" } ], "isResult": "<Boolean value>", } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "<field name>", "<field name>", "<field name>" ] }
For each Feature (filter), you need to specify an operator. Because the isDownloadedFromInternet Feature is a boolean type, you must use an operator relevant for a boolean value. For this tutorial, you want to use the operator Equals (which is equivalent to Is in the Investigation screen).
You can see the type for each Feature in the Query Elements and Features topic. For the available operators for each type of Feature, see Apply Operators in Filters.
In the queryPath object, for the filterType key, replace the <value> placeholder value with Equals.
{ "queryPath": [ { "requestedType": "Process", "filters": [ { "facetName": "isDownloadedFromInternet", "values": [ "<value>", ], "filterType": "**Equals**" } ], "isResult": "<Boolean value>", } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "<field name>", "<field name>", "<field name>" ] }
Lastly, you must provide a value by which to filter for each Feature. The value you use dependds on the type for the Feature. Because the Feature for this query is a boolean type, you will need to enter a true or false value.
You can see the possible/required values for each Feature in the Query Elements and Features topic.
In the queryPath object, in the values array, replace the <value> placeholder values with true (without quotes).
{ "queryPath": [ { "requestedType": "Process", "filters": [ { "facetName": "isDownloadedFromInternet", "values": [ true, ], "filterType": "Equals" } ], "isResult": "<Boolean value>", } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "<field name>", "<field name>", "<field name>" ] }
For each query, you must specify which query is the target Element for the query. Specifying the target Element helps the Cybereason platfrom return relevant details in the response for the selected Element.
In the querytPath object, for the isResult key, update the <value> placeholder value to true (without quotes).
{ "queryPath": [ { "requestedType": "Process", "filters": [ { "facetName": "isDownloadedFromInternet", "values": [ true, ], "filterType": "Equals" } ], "isResult": true, } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "<field name>", "<field name>", "<field name>" ] }
For the customFields object, for the <fieldName> placeholder values, add the following:
elementDisplayName
calculatedName
commandLine
{ "queryPath": [ { "requestedType": "Process", "filters": [ { "facetName": "isDownloadedFromInternet", "values": [ true, ], "filterType": "Equals" } ], "isResult": true, } ], "templateContext": "SPECIFIC", "totalResultLimit": "1000", "perGroupLimit": "100", "perFeatureLimit": "100", "queryTimeout": "120000", "customFields": [ "**elementDisplayName**", "**calculatedName**", "**commandLine**" ] }
Run the query
In your client machine, run the request.
The response will return instances for each instance of a process that the Cybereason platform detected was downloaded from the Internet.
The response contains a large number of fields:
{
"data": {
"resultIdToElementDataMap": {
"-2046359355.-446319856563366924": {
"simpleValues": {
"elementDisplayName": {
"totalValues": 1,
"values": [
"Chrome"
]
},
"calculatedName": {
"totalValues": 1,
"values": [
"chrome.exe"
]
},
"commandLine": {
"totalValues": 1,
"values": [
"null"
]
}
},
"elementValues": {
"calculatedUser": {
"totalValues": 1,
"elementValues": [
{
"elementType": "User",
"guid": "0.-6313743191401684913",
"name": "mydomain\\mark",
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
},
"parentProcess": {
"totalValues": 1,
"elementValues": [
{
"elementType": "Process",
"guid": "-2046359355.-7870067516287985870",
"name": "cmd.exe",
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
}
},
"suspicions": {
"blackListFileSuspicion": 1512300804528
},
"filterData": {
"sortInGroupValue": "-2046359355.-446319856563366924",
"groupByValue": "ransomfreetest.exe"
},
"isMalicious": true,
"suspicionCount": 1,
"guidString": "-2046359355.-446319856563366924",
"labelsIds": null,
"malopPriority": null
}
},
"suspicionsMap": {
"dualExtensionSuspicion": {
"potentialEvidence": [
"dualExtensionNameEvidence",
"hiddenFileExtensionEvidence",
"rightToLeftFileExtensionEvidence",
"masqueradingAsMovieEvidence"
],
"firstTimestamp": 1516033781024,
"totalSuspicions": 1
},
"blackListModuleSuspicion": {
"potentialEvidence": [
"blackListModuleEvidence"
],
"firstTimestamp": 1512314218832,
"totalSuspicions": 1
},
"ransomwareByCanaryFilesSuspicion": {
"potentialEvidence": [
"ransomwareByCanaryFilesEvidence"
],
"firstTimestamp": 1512313571594,
"totalSuspicions": 1
},
"connectingToBadReputationAddressSuspicion": {
"potentialEvidence": [
"hasMaliciousConnectionEvidence"
],
"firstTimestamp": 1516033781024,
"totalSuspicions": 1
}
},
"evidenceMap": {},
"totalPossibleResults": 13,
"queryLimits": {
"totalResultLimit": 1000,
"perGroupLimit": 100,
"perFeatureLimit": 100,
"groupingFeature": {
"elementInstanceType": "Process",
"featureName": "imageFileHash"
},
"sortInGroupFeature": null
},
"queryTerminated": false,
"pathResultCounts": [
{
"featureDescriptor": {
"elementInstanceType": "Process",
"featureName": null
},
"count": 13
}
]
},
"status": "SUCCESS",
"message": ""
}
Each of these fields will provide useful information. You should review the fields in the response to learn more.
For a tutorial on how to analyze the query result, see TBD.
Next steps
Now that you understand how a basic investigation query is built using the API, you can begin building queries, design scripts to run the queries and analyze the results on a regular basis using automation frameworks.