Run an Advanced Investigation Query
This topic provides a step by step example of how you can use the API to perform more advanced investigation queries with multiple Elements. We will search for results that meet a number of different indicators:
Machines running Windows 7
Processes identified as shell processes
Connections to external addresses
While this example uses specific indicators, you can easily substitute any Element and its relevant Feature (filter) for your own queries.
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.
In this example we can write this statement: I want to find processes running on Windows 7 machines that have opened connections and the connections are connected to external addresses.
Step 2: Build your queries
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.
Upon initial analysis, you may think that to investigate these Elements from the Investigation screen you need three separate queries for each search parameter: a query to find machines with Windows 7, another to find shell processes, and a third to find external connections. Then, after you run each of these queries, you would correlate the results to find items that had all three of these characteristics.
However, using the query builder logic, you can create one query to search for results that match all of these indicators:
Machine Element
Add filter for the Machine Element for OS type is Windows 7
Process Element
Add filter for the Process Element for Product type is Shell
Connection Element
Add filter for the the Connection Element for Is external is True
This query enables you to search for results where the result is found on a machine running Windows 7, is a process identified as a shell process, AND a process making external connections.
Step 3: Run your queries and copy the request body
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 the API request
Use the relevant cURL command, 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.
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" } ], "connectionFeature": { "elementInstanceType":"Machine", "featureName":"processes" } }, { "requestedType":"Process", "filters":[ { "facetName":"productType", "values":["SHELL"],"filterType":"Equals" } ], "connectionFeature": { "elementInstanceType":"Process", "featureName":"connections" } }, { "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":"Machine", "filters":[ { "facetName":"osVersionType", "values":["Windows_7"], "filterType":"Equals" } ], "connectionFeature": { "elementInstanceType":"Machine", "featureName":"processes" } }, { "requestedType":"Process", "filters":[ { "facetName":"productType", "values":["SHELL"],"filterType":"Equals" } ], "connectionFeature": { "elementInstanceType":"Process", "featureName":"connections" } }, { "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 = "myserver.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" linking_element = "Machine" linking_feature = "processes" query_element_2 = "Process" query_element_2_filter = "productType" query_element_2_filter_value = "SHELL" linking_element_2 = "Process" linking_feature_2 = "connections" query_element_3 = "Connection" query_element_1_filter = "isExternalConnection" query = json.dumps({"queryPath":[{"requestedType":query_element_1,"filters":[{"facetName":query_element_1_filter,"values":[query_element_1_filter_value],"filterType":"Equals"}],"connectionFeature":{"elementInstanceType":linking_element,"featureName":linking_feature}},{"requestedType":query_element_2,"filters":[{"facetName":query_element_2_filter,"values":[query_element_2_filter_value],"filterType":"Equals"}],"connectionFeature":{"elementInstanceType":linking_element_2,"featureName":linking_feature_2}},{"requestedType":query_element_3,"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:
Example
In our example, the platform response includes the following fields:
{ "data": { "resultIdToElementDataMap": { "2111376845.940203405844593155": { "simpleValues": { "portType": { "totalValues": 1, "values": [ "SERVICE_HTTP" ] }, "serverPort": { "totalValues": 1, "values": [ "80" ] }, "direction": { "totalValues": 1, "values": [ "OUTGOING" ] }, "serverAddress": { "totalValues": 1, "values": [ "81.171.14.67" ] }, "calculatedCreationTime": { "totalValues": 1, "values": [ "1526249113604" ] }, "remoteAddressCountryName": { "totalValues": 1, "values": [ "Netherlands" ] }, "elementDisplayName": { "totalValues": 1, "values": [ "10.146.17.91:49728 > 81.171.14.67:80" ] } }, "elementValues": { "ownerMachine": { "totalValues": 1, "elementValues": [ { "elementType": "Machine", "guid": "2111376845.1198775089551518743", "name": "AEP-S1-V71", "hasSuspicions": false, "hasMalops": false } ], "totalSuspicious": 0, "totalMalicious": 0, "guessedTotal": 0 }, "ownerProcess": { "totalValues": 1, "elementValues": [ { "elementType": "Process", "guid": "2111376845.-9120124556509973270", "name": "powershell.exe", "hasSuspicions": false, "hasMalops": false } ], "totalSuspicious": 0, "totalMalicious": 0, "guessedTotal": 0 }, "dnsQuery": { "totalValues": 1, "elementValues": [ { "elementType": "DnsQueryResolvedDomainToIp", "guid": "0.-8296975497790208175", "name": "smartdone.info > 81.171.14.67", "hasSuspicions": false, "hasMalops": false } ], "totalSuspicious": 0, "totalMalicious": 0, "guessedTotal": 0 } }, "suspicions": {}, "filterData": { "sortInGroupValue": "2111376845.940203405844593155", "groupByValue": "IpAddressRuntime:0.-2798964003374872992 address=81.171.14.67 , " }, "isMalicious": false, "suspicionCount": 0, "guidString": "2111376845.940203405844593155", "labelsIds": null, "malopPriority": null, "suspect": false, "malicious": false } }, "suspicionsMap": {}, "evidenceMap": {}, "totalPossibleResults": 48, "guessedPossibleResults": 0, "queryLimits": { "totalResultLimit": 1000, "perGroupLimit": 100, "perFeatureLimit": 100, "groupingFeature": { "elementInstanceType": "Connection", "featureName": "remoteAddress" }, "sortInGroupFeature": null }, "queryTerminated": false, "pathResultCounts": [ { "featureDescriptor": { "elementInstanceType": "Machine", "featureName": null }, "count": 6 }, { "featureDescriptor": { "elementInstanceType": "Machine", "featureName": "processes" }, "count": 38 }, { "featureDescriptor": { "elementInstanceType": "Process", "featureName": "connections" }, "count": 48 } ] }, "status": "SUCCESS", "message": "" }