Find Indicators of Suspicious Behavior
This topic provides a step by step example of how you can use the API to perform investigation queries for indicators of suspicion behaviors. In this example, we will search for specific file hashes, which is a known way of finding malware or ransomware. In addition, you can update the file hash value as the threat intelligence on malware or ransomware changes due to attackers modifying their values.
While this example uses specific indicators, you can easily substitute any Element and its relevant Feature (filter) for your own queries. For example, if you want to search for a known behavior of a specific process, you would update the Element in the example query to Process and add the relevant Features (filters) for the process name and known behavior. Likewise, if you wanted to find examples of a known malicious IP address, you would update the Element to Connection/IP Address and add the IP address location as the Feature (filter) for the Element.
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 want to search for a single hash value for a fictitious file on our environments, called myfile.docx. This file has a file hash value of abcc2c3655dd42083477b49e0d2ac65f77e575c1.
Based on this, we can write the following statement: I want to find examples of a malicious file in my environment identified by the hash value abcc2c3655dd42083477b49e0d2ac65f77e575c1.
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.
In this example, you build this query:
File Element
Add filter for SHA1 Signature is abcc2c3655dd42083477b49e0d2ac65f77e575c1.
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 commmand, request body example, or Python script.
In this example, we are using a stand-in address for a Cybereason server (myserver.com). If you use this request, replace this address with your actual server address.
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://myserver.com/rest/visualsearch/query/simple \
--header 'Content-Type: application/json' \
--data '{
"queryPath":[
{
"requestedType":"File",
"filters":[
{
"facetName":"sha1String",
"values":["abcc2c3655dd42083477b49e0d2ac65f77e575c1"],
"filterType":"ContainsIgnoreCase"
}
],
"isResult":true
}
],
"totalResultLimit":1000,
"perGroupLimit":100,
"perFeatureLimit":100,
"templateContext":"SPECIFIC",
"queryTimeout":120000,
"customFields": [
"elementDisplayName",
"ownerMachine",
"sha1String",
"createdTime",
"modifiedTime",
"size",
"productName",
"companyName",
"productVersion",
]
}'
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 request body:
{
"queryPath": [
{
"requestedType": "File",
"filters": [
{
"facetName": "sha1String",
"values": [
"abcc2c3655dd42083477b49e0d2ac65f77e575c1"
],
"filterType": "ContainsIgnoreCase"
}
],
"isResult": true
}
],
"totalResultLimit": 1000,
"perGroupLimit": 100,
"perFeatureLimit": 100,
"templateContext": "SPECIFIC",
"queryTimeout": 120000,
"customFields": [
"elementDisplayName",
"ownerMachine",
"sha1String",
"createdTime",
"modifiedTime",
"size",
"productName",
"companyName",
"productVersion"
]
}
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 = "File"
query_element_1_filter_1 = "sha1String"
query_element_1_filter_1_value = "abcc2c3655dd42083477b49e0d2ac65f77e575c1"
query = json.dumps({"queryPath":[{"requestedType":query_element_1, "filters":[{"facetName":query_element_1_filter_1,"values":[query_element_1_filter_1_value], "filterType":"ContainsIgnoreCase"}],"isResult":True}],"totalResultLimit":1000,"perGroupLimit":100,"perFeatureLimit":100,"templateContext":"SPECIFIC","queryTimeout":120000,"customFields": ["elementDisplayName","ownerMachine","sha1String","createdTime","modifiedTime","size","productName","companyName","productVersion"]})
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: View the response details
The response contains a large number fields. Focus on these fields for meaningful information:
Example
{
"data": {
"resultIdToElementDataMap": {
"923810613.-3599489590504944098": {
"simpleValues": {
"sha1String": {
"totalValues": 1,
"values": [
"abcc2c3655dd42083477b49e0d2ac65f77e575c1"
]
},
"createdTime": {
"totalValues": 1,
"values": [
"1506331798071"
]
},
"endTime": {
"totalValues": 1,
"values": [
"1516331798071"
]
},
"size": {
"totalValues": 1,
"values": [
"1.5 MB"
]
},
"productName": {
"totalValues": 1,
"values": [
"Microsoft Word"
]
},
"companyName": {
"totalValues": 1,
"values": [
"Microsoft"
]
},
"productVersion": {
"totalValues": 1,
"values": [
"2016"
]
},
"elementDisplayName": {
"totalValues": 1,
"values": [
"powershell.exe"
]
}
},
"elementValues": {
"ownerMachine": {
"totalValues": 1,
"elementValues": [
{
"elementType": "Machine",
"guid": "923810613.-3086126652240771255",
"name": null,
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
}
},
"suspicions": {},
"isMalicious": false,
"suspicionCount": 0,
"guidString": "923810613.-3599489590504944098",
"labelsIds": null,
"malopPriority": null
}
},
"suspicionsMap": {},
"evidenceMap": {},
"totalPossibleResults": 3,
"queryLimits": {
"totalResultLimit": 100,
"perGroupLimit": 10,
"perFeatureLimit": 10,
"groupingFeature": {
"elementInstanceType": "File",
"featureName": "fileHash"
},
"sortInGroupFeature": null
},
"queryTerminated": false,
"pathResultCounts": [
{
"featureDescriptor": {
"elementInstanceType": "File",
"featureName": null
},
"count": 3
}
]
},
"status": "SUCCESS",
"message": ""
}