Investigate Items in a Malop
This topic provides a step by step example of how you can use the API to investigate items (processes, connections, machines, and users) in a Malop. We will search for a number of different items in separate queries:
Processes identified as suspicious
Connections associated with the process
Machines associated with the process
Users associated with the process
Note
For our example, we are investigating items from a Malicious by Code Injection Malop. This Malop contains three malicious processes, two malicious connections opened from these processes, one machine, and two users associated with the process.
In this topic:
Step 1: Build your queries in the Investigation screen
To investigate these items, you click Investigate from the relevant area of the Malop details.
Then, in the Investigation screen, the Cybereason platform automatically creates a query for each investigation item or Element:
Malop Process Element THEN Suspicious processes Element THEN
Malop Process Element THEN Suspicious processes Element THEN Connections Element
Malop Process Element THEN Affected machines Element
Malop Process Element THEN Affected users Element
When you create these queries directly from a Malop by clicking Investigate from the relevant area of the Malop details, the Cybereason platform automatically adds the relevant filter values in the query builder for the processes, connections, and so forth.
Step 2: 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 3: Build the API request
Use the relevant cURL commmand, request body example, or Python script:
Note
To use these requests or scripts in your own environment, update the guidList parameter for a relevant Malop number in your environment. If you would like other fields displayed in the response, update the Features used in the customFields parameter to those Features you find meaningful.
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.
Processes
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":"MalopProcess",
"filters":[],
"guidList":["11.3895241412125985446"],
"connectionFeature": {
"elementInstanceType":"MalopProcess",
"featureName":"suspects"
}
},
{
"requestedType":"Process",
"filters":[],
"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 = "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 = "Process"
malop_id = "11.3895241412125985446"
linking_element_1 = "MalopProcess"
linking_feature_1 = "suspects"
query_element_2 = "Process"
query = json.dumps({"queryPath":[{"requestedType":query_element_1,"filters":[],"guidList":[malop_id],"connectionFeature":{"elementInstanceType":linking_element_1,"featureName":linking_feature_1}},{"requestedType":query_element_2,"filters":[],"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))
Connections
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":"MalopProcess",
"filters":[],
"guidList":["11.3895241412125985446"],
"connectionFeature": {
"elementInstanceType":"MalopProcess",
"featureName":"suspects"
}
},
{
"requestedType":"Process",
"filters":[],
"connectionFeature": {
"elementInstanceType":"Process",
"featureName":"connections"
}
},
{
"requestedType":"Connection",
"filters":[],
"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 = "MalopProcess"
malop_id = "11.3895241412125985446"
linking_element_1 = "MalopProcess"
linking_feature_1 = "suspects"
query_element_2 = "Process"
linking_element_2 = "Process"
linking_feature_2 = "connections"
query_element_3 = "Connection"
query = json.dumps({"queryPath":[{"requestedType":query_element_1,"filters":[],"guidList":[malop_id],"connectionFeature":{"elementInstanceType":linking_element_1,"featureName":linking_feature_1}},{"requestedType":query_element_2,"filters":[],"connectionFeature":{"elementInstanceType":linking_element_2,"featureName":linking_feature_2}},{"requestedType":query_element_3,"filters":[],"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))
Machines
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":"MalopProcess",
"filters":[],
"guidList":["11.3895241412125985446"],
"connectionFeature": {
"elementInstanceType":"MalopProcess",
"featureName":"affectedMachines"
}
},
{
"requestedType":"Machine",
"filters":[],"isResult":true
}
],
"totalResultLimit":1000,
"perGroupLimit":100,
"perFeatureLimit":100,
"templateContext":"SPECIFIC",
"queryTimeout":120000,
"customFields": [
"osVersionType",
"platformArchitecture",
"uptime",
"isActiveProbeConnected",
"lastSeenTimeStamp",
"timeStampSinceLastConnectionTime",
"activeUsers",
"mountPoints",
"processes",
"services",
"elementDisplayName"
]
}'
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 = "MalopProcess"
malop_id = "11.3895241412125985446"
linking_element = "MalopProcess"
linking_feature = "affectedMachines"
query_element_2 = "Machine"
query = json.dumps({"queryPath":[{"requestedType":query_element_1,"filters":[],"guidList":[malop_id],"connectionFeature": {"elementInstanceType":linking_element,"featureName":linking_feature}},{"requestedType":query_element_2,"filters":[],"isResult":True}],"totalResultLimit":1000,"perGroupLimit":100,"perFeatureLimit":100,"templateContext":"SPECIFIC","queryTimeout":120000,"customFields":["osVersionType","platformArchitecture","uptime","isActiveProbeConnected","lastSeenTimeStamp","timeStampSinceLastConnectionTime","activeUsers","mountPoints","processes","services","elementDisplayName"]})
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))
Users
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":"MalopProcess",
"filters":[],
"guidList":["11.3895241412125985446"],
"connectionFeature": {
"elementInstanceType":"MalopProcess",
"featureName":"affectedUsers"
}
},
{
"requestedType":"User",
"filters":[],
"isResult":true
}
],
"totalResultLimit":1000,
"perGroupLimit":100,
"perFeatureLimit":100,
"templateContext":"SPECIFIC",
"queryTimeout":120000,
"customFields": [
"domain",
"ownerMachine",
"ownerOrganization.name",
"isLocalSystem",
"elementDisplayName"
]
}'
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 = "MalopProcess" malop_id = "11.3895241412125985446" linking_element = "MalopProcess" linking_features = "affectedUsers" query_element_2 = "User" query = json.dumps({"queryPath":[{"requestedType":query_element_1,"filters":[],"guidList":[malop_id],"connectionFeature":{"elementInstanceType":linking_element,"featureName":linking_features}},{"requestedType":query_element_2,"filters":[],"isResult":True}],"totalResultLimit":1000,"perGroupLimit":100,"perFeatureLimit":100,"templateContext":"SPECIFIC","queryTimeout":120000,"customFields":["domain","ownerMachine","ownerOrganization.name","isLocalSystem","elementDisplayName"]}) 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 4: 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 5: 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": { "-2125175950.-6747129979956716346": { "simpleValues": { "creationTime": { "totalValues": 1, "values": [ "1527666690044" ] }, "executionPrevented": { "totalValues": 1, "values": [ "false" ] }, "elementDisplayName": { "totalValues": 1, "values": [ "injected (6ee3019283ee80ac408f548adc4232fc.exe > winlogon.exe)" ] } }, "elementValues": { "calculatedUser": { "totalValues": 1, "elementValues": [ { "elementType": "User", "guid": "0.2891911274541128936", "name": "aep-s1-v29\\system", "hasSuspicions": false, "hasMalops": false } ], "totalSuspicious": 0, "totalMalicious": 0, "guessedTotal": 0 }, "ownerMachine": { "totalValues": 1, "elementValues": [ { "elementType": "Machine", "guid": "-2125175950.1198775089551518743", "name": "AEP-S1-V29", "hasSuspicions": false, "hasMalops": false } ], "totalSuspicious": 0, "totalMalicious": 0, "guessedTotal": 0 }, "loadedModules": { "totalValues": 1, "elementValues": null, "totalSuspicious": 0, "totalMalicious": 0, "guessedTotal": 0 }, "parentProcess": { "totalValues": 1, "elementValues": [ { "elementType": "Process", "guid": "-2125175950.-2475218978974974941", "name": "6ee3019283ee80ac408f548adc4232fc.exe", "hasSuspicions": true, "hasMalops": true } ], "totalSuspicious": 1, "totalMalicious": 1, "guessedTotal": 0 }, "imageFile": { "totalValues": 1, "elementValues": [ { "elementType": "File", "guid": "-2125175950.-8282105735216364852", "name": "injected", "hasSuspicions": false, "hasMalops": false } ], "totalSuspicious": 0, "totalMalicious": 0, "guessedTotal": 0 } }, "suspicions": { "privilegeEscalationSuspicion": 1527666910697, "maliciousInjectedCodeSuspicion": 1527667018000 }, "filterData": { "sortInGroupValue": "-2125175950.-6747129979956716346", "groupByValue": "injected (6ee3019283ee80ac408f548adc4232fc.exe > winlogon.exe)" }, "isMalicious": true, "suspicionCount": 2, "guidString": "-2125175950.-6747129979956716346", "labelsIds": null, "malopPriority": null, "suspect": true, "malicious": true } }, "suspicionsMap": { "knownMalwareSuspicion": { "potentialEvidence": [ "malwareEvidence" ], "firstTimestamp": 1549645738368, "totalSuspicions": 1 }, "maliciousInjectingCodeSuspicion": { "potentialEvidence": [ "detectedInjectedEvidence", "detectedInjectingEvidence", "hostingInjectedThreadEvidence" ], "firstTimestamp": 1527667018000, "totalSuspicions": 1 }, "privilegeEscalationSuspicion": { "potentialEvidence": [ "privilegeEscalationEvidence", "detectedInjectedEvidence", "injectedThreadPrivilegeEscalationEvidence", "imageFileUnsignedEvidence" ], "firstTimestamp": 1527666910697, "totalSuspicions": 2 }, "maliciousInjectedCodeSuspicion": { "potentialEvidence": [ "detectedInjectedEvidence" ], "firstTimestamp": 1527667018000, "totalSuspicions": 2 }, "elevatingPrivilegesSuspicion": { "potentialEvidence": [ "elevatingPrivilegesToChildEvidence", "detectedInjectedEvidence", "imageFileUnsignedEvidence" ], "firstTimestamp": 1527666910697, "totalSuspicions": 1 } }, "evidenceMap": {}, "totalPossibleResults": 3, "guessedPossibleResults": 0, "queryLimits": { "totalResultLimit": 1000, "perGroupLimit": 100, "perFeatureLimit": 100, "groupingFeature": { "elementInstanceType": "Process", "featureName": "imageFileHash" }, "sortInGroupFeature": null }, "queryTerminated": false, "pathResultCounts": [ { "featureDescriptor": { "elementInstanceType": "MalopProcess", "featureName": null }, "count": 1 }, { "featureDescriptor": { "elementInstanceType": "MalopProcess", "featureName": "suspects" }, "count": 3 } ] }, "status": "SUCCESS", "message": "" }