Get a List of Suspicions or Evidence

To see if certain types of activities are detected repeatedly in your environment without having to individually search the suspicions and evidence in each Malop and investigation result, you can retrieve a list of suspicions and evidence currently found on Elements in your environment.

In this scenario, you will see how to retrieve the list of suspicions and evidence for a Process Element. You can repeat this process for most Cybereason Elements to get complete results.

Step 1: Build the request

To build a request to retrieve the list of suspicions and evidence for a Process Element:

1. Add the necessary Element for the query. In our example, you use Process as the value for requestedType key (for requests sent via cURL and a REST API client) or the query_element variable (if you use the Python example).

2. Add the hasSuspicions Feature for the Process Element. In our example, you add hasSuspicions as the value of the facetName key (for requests sent via cURL and a REST API client). In the Python example, this Feature is added as part of the query.

If you want to retrieve evidence and suspicions from a specific time period, add additional filters to limit the results to that time period. For details, see Time filters.

Use the relevant cURL command, request body example, or Python script:

cURLREST API clientPython

curl --request POST \
     --url https://<your server>/rest/visualsearch/query/simple \
     --header 'Content-Type:application/json' \
     --data '{
                  "queryPath":[
                                           {
                                            "requestedType":"Process",
                                            "filters":[
                                                                   {
                                                                    "facetName":"hasSuspicions",
                                                                    "values":[True]
                                                                   }
                                                                  ],
                                            "isResult":True
                                           }
                                          ],
                  "totalResultLimit":10000,
                  "perGroupLimit":100,
                  "perFeatureLimit":100,
                  "templateContext":"DETAILS",
                  "queryTimeout":120000,
                  "customFields":[
                                                  "elementDisplayName",
                                                  "creationTime",
                                                  "endTime"
                                                 ]
                 }'

Step 2: 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 3: Evaluate the response

The response for an investigation query returns a wide variety of information about related Features and Elements, filters, and so forth.

In this scenario, you are looking for two different areas of the response:

• Suspicions: This information is visible in the suspicions object.

• Evidence: This information is visible in the suspicionsMap object.

Note

The provided Python script automatically retrieves these fields from the API and prints them in a command window or console window.

Suspicions

In the individual results instance, search for the suspicions object. This object contains the name of the suspicions as well as the timestamp for when the Cybereason platform detected the suspicion for a particular result instance:

Evidence

To see evidence,search for the suspicionsMap object. This object contains all evidences for suspicions related to your query:

Example scripts

So that you can view only the evidence and suspicion names, both of these example scripts retrieve the suspicion-related and evidence-related fields from the response and print them to a command window or console window in the IDE or command line utility on your machine. You can add lines of code to print this information to a separate file.

Retrieve suspicions

Download Python script

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 = "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 = "Process"

query = json.dumps({"queryPath":[{"requestedType":query_element,"filters":[{"facetName":"hasSuspicions","values":[True]}],"isResult":True}],"totalResultLimit":1000,"perGroupLimit":100,"perFeatureLimit":100,"templateContext":"DETAILS","queryTimeout":120000,"customFields":["elementDisplayName","creationTime","endTime"]})

api_response = session.request("POST", api_url, data=query, headers=headers)

your_response = json.loads(api_response.content)

results_list = your_response['data']['resultIdToElementDataMap'].keys()

def getSuspicionsList(guid_list):

	for x in guid_list:
	    print(x + "- Process name: " + your_response['data']['resultIdToElementDataMap'][x]['simpleValues']['elementDisplayName']['values'][0:] + "- Suspicions: " + your_response['data']['resultIdToElementDataMap'][x]['suspicions'].keys())

getSuspicionsList(results_list)

Retrieve evidence

Download Python script

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 = "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 = "Process"

query = json.dumps({"queryPath":[{"requestedType":query_element,"filters":[{"facetName":"hasSuspicions","values":[True]}],"isResult":True}],"totalResultLimit":1000,"perGroupLimit":100,"perFeatureLimit":100,"templateContext":"DETAILS","queryTimeout":120000,"customFields":["elementDisplayName","creationTime","endTime","commandLine","productType","children","parentProcess","ownerMachine","calculatedUser","imageFile","connections","connectionsToMaliciousDomain","unresolvedDnsQueriesFromDomain","decodedCommandLine","iconBase64","ransomwareAutoRemediationSuspended","executionPrevented","isWhiteListClassification","matchedWhiteListRuleIds","imageFile.sha1String"]})

api_response = session.request("POST", api_url, data=query, headers=headers)

your_response = json.loads(api_response.content)

results_list = your_response['data']['suspicionsMap'].keys()

def getEvidencesList(guid_list):

	for x in guid_list:
	    print(your_response['data']['suspicionsMap'][x]['potentialEvidence'][0:])

getEvidencesList(results_list)

Note

Currently, these fields print the output to a command window or console window in the IDE or command line utility on your machine. You can add additional lines of code to print this information to a separate file.