Run a Simple Investigation Query
This topic provides a step by step example of how you can use the API to run a simple query. We will search for a number of different items in separate queries:
Machines running Windows 7
Shell processes
Connections to external locations
While the queries are not necessarily searches for malicious behavior or security problems, the process described in this topic shows you how to construct queries for the most common Cybereason Elements.
In this topic:
Step 1: Plan your queries
To create queries that return meaningful results, you must plan your queries carefully:
Enumerate in a general way what you want to find, such as computers or processes.
Determine the indicators you will use to identify your target, such as a specific operating system. Write an explicit statement of your query.
For detailed documentation on planning and building your queries, see the Hunting and Investigation documentation in the Cybereason core documentation.
For our example queries, we can write the following statements:
I want to find machines with the operating system Windows 7.
I want to find processes with a product type of Shell.
I want to find connections to an external address.
With these statements we can build the queries in the Investigation screen.
Step 2: Build your queries in the Investigation screen
A query in the Investigation screen has two parts:
Elements are the objects you want to find, or the computing component parts of the your statement.
Features, or filters, are the indicators that identify the target.
You build these queries:
Query 1: I want to find a list of machines with the operating system Windows 7. The Element in the query is Machine and the Feature/filter is OS version is Windows 7.
Query 2: I want to find processes with a type of SHELL. The Element in the query is Process and the Feature/filter is Product type is Shell
Query 3: I want to find connections that make connections to an external address. The Element in this query is Connection and the Feature/filter is Is external.
Step 3: Run your queries and generate the API request body
To generate the request body for the API request:
In Chrome, open Chrome DevTools.
In the Cybereason Investigation screen, click Get results.
After the query has finished running, select the Network tab in Chrome DevTools, and then select the relevant request.
In the Request Payload section in the lower part of the window, copy the entire request payload. You will use this in the request body for API request.
Step 4: Build and send the API request
Use the relevant cURL commmand, request body example, or Python script:
All Python examples are formatted for Python version 3.0 and higher, up to the latest Python version. If you are using versions of Python earlier than 3.0, ensure you manually remove parentheses for the print statements in this sample. For example, the print (response.content) statement updates to print response.content.
Query 1: Machines running Windows 7
Use the relevant API request/script depending on your preferred method:
curl --request POST \
--url https://<your server>/rest/visualsearch/query/simple \
--header 'Content-Type:application/json' \
--data '{
"queryPath": [
{
"requestedType": "Machine",
"filters": [
{
"facetName": "osVersionType",
"values": [
"Windows_7"
],
"filterType": "Equals"
}
]
}
],
"totalResultLimit": 1000,
"perGroupLimit": 100,
"perFeatureLimit": 100,
"templateContext": "SPECIFIC",
"queryTimeout": 120000,
"customFields": [
"elementDisplayName",
"creationTime",
"endTime",
"commandLine",
"productType",
"children",
"parentProcess",
"ownerMachine",
"calculatedUser",
"imageFile",
"loadedModules",
"iconBase64",
"ransomwareAutoRemediationSuspended",
"executionPrevented",
"isWhiteListClassification",
"matchedWhiteListRuleIds"
]
}'
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.
Use this as the request body:
{
"queryPath": [
{
"requestedType": "Machine",
"filters": [
{
"facetName": "osVersionType",
"values": [
"Windows_7"
],
"filterType": "Equals"
}
],
"isResult":true,
}
],
"totalResultLimit": 1000,
"perGroupLimit": 100,
"perFeatureLimit": 100,
"templateContext": "SPECIFIC",
"queryTimeout": 120000,
"customFields": [
"elementDisplayName",
"creationTime",
"endTime",
"commandLine",
"productType",
"children",
"parentProcess",
"ownerMachine",
"calculatedUser",
"imageFile",
"loadedModules",
"iconBase64",
"ransomwareAutoRemediationSuspended",
"executionPrevented",
"isWhiteListClassification",
"matchedWhiteListRuleIds"
]
}
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.
import requests import json # Login information username = "[email protected]" password = "password" server = "yourserver.com" port = "443" data = { "username": username, "password": password } headers = {"Content-Type": "application/json"} base_url = "https://" + server + ":" + port login_url = base_url + "/login.html" session = requests.session() login_response = session.post(login_url, data=data, verify=True) print (login_response.status_code) print (session.cookies.items()) # Request URL endpoint_url = "/rest/visualsearch/query/simple" api_url = base_url + endpoint_url # These are the variables that represent different fields in the request. query_element_1 = "Machine" query_element_1_filter = "osVersionType" query_element_1_filter_value = "Windows_7" query = json.dumps({"queryPath":[{"requestedType":query_element_1,"filters":[{"facetName":query_element_1_filter,"values":[query_element_1_filter_value],"filterType":"Equals"}],"isResult":True}],"totalResultLimit":1000,"perGroupLimit":100,"perFeatureLimit":100,"templateContext":"SPECIFIC","queryTimeout":120000,"customFields": ["elementDisplayName","creationTime","endTime","commandLine","productType","children","parentProcess","ownerMachine","calculatedUser","imageFile","loadedModules","iconBase64","ransomwareAutoRemediationSuspended","executionPrevented","isWhiteListClassification","matchedWhiteListRuleIds"]}) api_headers = {'Content-Type':'application/json'} api_response = session.request("POST", api_url, data=query, headers=api_headers) your_response = json.loads(api_response.content) print(json.dumps(your_response, indent=4, sort_keys=True))
Query 2: Product Type is Shell
curl --request POST \
--url https://<your server>/rest/visualsearch/query/simple \
--header 'Content-Type:application/json' \
--data '{
"queryPath":[
{
"requestedType":"Process",
"filters":[
{
"facetName":"productType",
"values":["SHELL"],
"filterType":"Equals"
}
],
"isResult":true
}
],
"totalResultLimit":1000,
"perGroupLimit":100,
"perFeatureLimit":100,
"templateContext":"SPECIFIC",
"queryTimeout":120000,
"customFields":[
"elementDisplayName",
"creationTime",
"endTime",
"commandLine",
"productType",
"children",
"parentProcess",
"ownerMachine",
"calculatedUser",
"imageFile",
"loadedModules",
"iconBase64",
"ransomwareAutoRemediationSuspended",
"executionPrevented",
"isWhiteListClassification",
"matchedWhiteListRuleIds"
]
}'
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.
Use this as the request body:
{
"queryPath":[
{
"requestedType":"Process",
"filters":[
{
"facetName":"productType",
"values":["SHELL"],
"filterType":"Equals"
}
],
"isResult":true
}
],
"totalResultLimit":1000,
"perGroupLimit":100,
"perFeatureLimit":100,
"templateContext":"SPECIFIC",
"queryTimeout":120000,
"customFields": [
"elementDisplayName",
"creationTime",
"endTime",
"commandLine",
"productType",
"children",
"parentProcess",
"ownerMachine",
"calculatedUser",
"imageFile",
"loadedModules",
"iconBase64",
"ransomwareAutoRemediationSuspended",
"executionPrevented",
"isWhiteListClassification",
"matchedWhiteListRuleIds"
]
}
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.
Use this as the request body:
import requests
import json
# Login information
username = "[email protected]"
password = "password"
server = "yourserver.com"
port = "443"
data = {
"username": username,
"password": password
}
headers = {"Content-Type": "application/json"}
base_url = "https://" + server + ":" + port
login_url = base_url + "/login.html"
session = requests.session()
login_response = session.post(login_url, data=data, verify=True)
print (login_response.status_code)
print (session.cookies.items())
# Request URL
endpoint_url = "/rest/visualsearch/query/simple"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
query_element_1 = "Process"
query_element_1_filter = "productType"
query_element_1_filter_value = "SHELL"
query = json.dumps({"queryPath":[{"requestedType":query_element_1,"filters":[{"facetName":query_element_1_filter,"values":[query_element_1_filter_value],"filterType":"Equals"}],"isResult":True}],"totalResultLimit":1000,"perGroupLimit":100,"perFeatureLimit":100,"templateContext":"SPECIFIC","queryTimeout":120000,"customFields":["elementDisplayName","creationTime","endTime","commandLine","productType","children","parentProcess","ownerMachine","calculatedUser","imageFile","loadedModules","iconBase64","ransomwareAutoRemediationSuspended","executionPrevented","isWhiteListClassification","matchedWhiteListRuleIds"]})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=query, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Query 3: Connections to External Address
curl --request POST \
--url https://<your server>/rest/visualsearch/query/simple \
--header 'Content-Type:application/json' \
--data '{
"queryPath":[
{
"requestedType":"Connection",
"filters":[
{
"facetName":"isExternalConnection",
"values":[true]
}
],
"isResult":true
}
],
"totalResultLimit":1000,
"perGroupLimit":100,
"perFeatureLimit":100,
"templateContext":"SPECIFIC",
"queryTimeout":120000,
"customFields":[
"elementDisplayName",
"direction",
"ownerMachine",
"ownerProcess",
"serverPort",
"serverAddress",
"portType",
"aggregatedReceivedBytesCount",
"aggregatedTransmittedBytesCount",
"remoteAddressCountryName",
"dnsQuery",
"accessedByMalwareEvidence",
"calculatedCreationTime","endTime"
]
}'
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.
Use this as the request body:
{
"queryPath":[
{
"requestedType":"Connection",
"filters":[
{
"facetName":"isExternalConnection",
"values":[true]
}
],
"isResult":true
}
],
"totalResultLimit":1000,
"perGroupLimit":100,
"perFeatureLimit":100,
"templateContext":"SPECIFIC",
"queryTimeout":120000,
"customFields":[
"elementDisplayName",
"direction",
"ownerMachine",
"ownerProcess",
"serverPort",
"serverAddress",
"portType",
"aggregatedReceivedBytesCount",
"aggregatedTransmittedBytesCount",
"remoteAddressCountryName",
"dnsQuery",
"accessedByMalwareEvidence",
"calculatedCreationTime","endTime"
]
}
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.
import requests import json # Login information username = "[email protected]" password = "mypassword" server = "yourserver.com" port = "443" data = { "username": username, "password": password } headers = {"Content-Type": "application/json"} base_url = "https://" + server + ":" + port login_url = base_url + "/login.html" session = requests.session() login_response = session.post(login_url, data=data, verify=True) print (login_response.status_code) print (session.cookies.items()) # Request URL endpoint_url = "/rest/visualsearch/query/simple" api_url = base_url + endpoint_url # These are the variables that represent different fields in the request. query_element_1 = "Connection" query_element_1_filter = "isExternalConnection" query = json.dumps({"queryPath":[{"requestedType":query_element_1,"filters":[{"facetName":query_element_1_filter,"values":[True]}],"isResult":True}],"totalResultLimit":1000,"perGroupLimit":100,"perFeatureLimit":100,"templateContext":"SPECIFIC","queryTimeout":120000,"customFields":["elementDisplayName","direction","ownerMachine","ownerProcess","serverPort","serverAddress","portType","aggregatedReceivedBytesCount","aggregatedTransmittedBytesCount","remoteAddressCountryName","dnsQuery","accessedByMalwareEvidence","calculatedCreationTime","endTime"]}) api_headers = {'Content-Type':'application/json'} api_response = session.request("POST", api_url, data=query, headers=api_headers) your_response = json.loads(api_response.content) print(json.dumps(your_response, indent=4, sort_keys=True))
Step 5: Run your request and generate the response
In the command line, REST API client, or IDE, run the command or script that contains the request. After a few seconds, the Cybereason API returns a response.
Step 6: Evaluate the response
The response contains a large number fields. Focus on these fields for meaningful information:
Object Name |
Description |
---|---|
simpleValues |
Contains separate entries for every feature in the query. (This is the equivalent of adding columns in the Investigation screen.) For each Feature name, such as creationTime, analyze the values in the totalValues field. |
elementValues |
Contains separate entries for every Element in the query. For each Element name, analyze the values in the elementValues field. |
suspicionsMap |
Contains a list of Suspicions. |
evidenceMap |
Contains a list of Evidence. |
In the results included in these fields, you may want to analyze the results in a number of different ways:
Look for values that are unexpected or outside the norm for your organization.
Look for values that only occur once. Repeated instances of a process or a connection may be normal for your organization, such as the use of a specific application or mail server address by all employees. However, a single instance of something may warrant further analysis on your part.