Get a List of Malops
When you are monitoring security threats in your environment, it is important to regularly view and respond to new or existing Malops. The Cybereason API enables you to obtain a list of Malops and see details about these malicious operations. This topic provides a step by step example of how you can use the API to retrieve Malop information.
In this topic:
Step 1: Plan your query
Before you start assembling your request, consider your specific goals: Do you want to limit the number of Malops displayed? Do you want to obtain Malop information from a specific time period? Write a statement that specifies your goals for the query. For example, your statement might resemble the following statement.
I want to retrieve all Malops that the Cybereason platform has ever found in my current environment.
Step 2: Build the API request
For this example, we will retrieve all Malops in the environment. This may create a very long response, but it will help you see what the potential value is in pulling all the details.
To build this request, you want to define the following:
The totalResultLimit parameter. This parameter limits the total number of Malops returned in the response. If you want to speed up the response time and limit the stress on your Servers, set this limit appropriately.
A perGroupLimit parameter. In some responses, if the response contains a large number of similar responses, these items are grouped accordingly to help you aggregate and view the results in a more efficient way.
A perFeatureLimit parameter. This is the number of responses for a specific feature.
Note
You can also add a time filter for this data by adding a startTime and endTime parameter as part of the request body. Although we are not doing so in this example, this could be useful to use in a request you send on a regular interval.
The remainder of the fields must remain as described in the example below, as these instruct your Cybereason server to return Malops as opposed to other Elements. In this example, we are leaving the totalResultLImit, perGroupLimit, and perFeatureLimit parameters to the default values normally used by the Cybereason UI when retrieving Malops for the Malop Inbox.
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 http://myserver.com/rest/crimes/unified \
--header 'Content-Type:application/json' \
--data '{
"totalResultLimit": 10000,
"perGroupLimit": 10000,
"perFeatureLimit": 100,
"templateContext": "OVERVIEW",
"queryPath": [
{
"requestedType": "MalopProcess",
"result": true,
"filters": null
}
]
}'
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:
{
"totalResultLimit": 10000,
"perGroupLimit": 10000,
"perFeatureLimit": 100,
"templateContext": "OVERVIEW",
"queryPath": [
{
"requestedType": "MalopProcess",
"result": true,
"filters": null
}
]
}
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:
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/crimes/unified"
api_url = base_url + endpoint_url
null = None
query = json.dumps({"totalResultLimit": 10000,"perGroupLimit":10000,"perFeatureLimit":100,"templateContext":"OVERVIEW","queryPath":[{"requestedType": "MalopProcess","result": True,"filters": null}]})
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 3: 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 4: Evaluate the response
When the response is returned for a Malop retrieval request, the data included in the response is quite long and full of different fields. Within this response you should look for a few important fields:
Field |
Type |
Description |
|---|---|---|
<MalopID> |
Decimal |
The unique ID assigned to the specific Malop by your Cybereason server |
decisionFeature |
decisionFeature object |
The Element causing the Malop and the reason the Malop was raised. These decision feature objects are decided using detection rules and internal logic. |
malopActivityTypes |
Enum |
The specific activity occurring that caused the Malops. |
detectionType |
Enum |
The root cause for the Malop. |
creationTime |
Timestamp |
The time when the Malop was first detected. |
rootCauseelementTypes |
Enum |
The Element that caused the Malop. |
rootCauseElementHashes |
Long |
The hash values of the Element that is causing the Malop. You can use this number to investigate and find other occurrences of the Element in your environment. |
managementStatus |
Enum |
The status of the Malop. |
affectedUsers* |
Object |
An object containing details on the affected users for this Malop. View the guid and name for each user in the elementValues object. |
affectedMachines |
Object |
An object containing the details for the machines associated with this Malop. View the guid and name for each machine in the elementValues object. |
Using the fields described above, you can:
List each individual Malop
See why the Malops were raised and the reasons behind them
View the status of the Malop
See users and machines included in this Malop. This information enables you to quickly move and contain any problems raised by this malicious operation.
Example
In our example, the platform response includes the following fields:
{
"data": {
"resultIdToElementDataMap": {
"11.5133381726858807240": {
"simpleValues": {
"hasRansomwareSuspendedProcesses": {
"totalValues": 1,
"values": [
"false"
]
},
"decisionFeature": {
"totalValues": 1,
"values": [
"Process.maliciousByCodeInjection (Malop decision)"
]
},
"rootCauseElementCompanyProduct": {
"totalValues": 0,
"values": null
},
"malopStartTime": {
"totalValues": 1,
"values": [
"1518364187368"
]
},
"detectionType": {
"totalValues": 1,
"values": [
"PROCESS_INJECTION"
]
},
"malopActivityTypes": {
"totalValues": 1,
"values": [
"MALICIOUS_INFECTION"
]
},
"elementDisplayName": {
"totalValues": 1,
"values": [
"MALICIOUS_INFECTION"
]
},
"creationTime": {
"totalValues": 1,
"values": [
"1518364234280"
]
},
"isBlocked": {
"totalValues": 1,
"values": [
"false"
]
},
"rootCauseElementTypes": {
"totalValues": 1,
"values": [
"Process"
]
},
"rootCauseElementNames": {
"totalValues": 1,
"values": [
"iathookdll.dll (malopgenerator.exe > notepad.exe)"
]
},
"malopLastUpdateTime": {
"totalValues": 1,
"values": [
"1518364234280"
]
},
"allRansomwareProcessesSuspended": {
"totalValues": 1,
"values": [
"false"
]
},
"rootCauseElementHashes": {
"totalValues": 1,
"values": [
"7aa61ff36c9c490184c416820c88371be46ab7c0"
]
},
"managementStatus": {
"totalValues": 1,
"values": [
"UNREAD"
]
},
"closeTime": {
"totalValues": 1,
"values": [
null
]
},
"closerName": {
"totalValues": 1,
"values": [
null
]
},
"customClassification": {
"totalValues": 1,
"values": [
"None"
]
}
},
"elementValues": {
"affectedUsers": {
"totalValues": 1,
"elementValues": [
{
"elementType": "User",
"guid": "0.918274811425759625",
"name": "win7-64b-user\\admin",
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
},
"affectedMachines": {
"totalValues": 1,
"elementValues": [
{
"elementType": "Machine",
"guid": "-1304188264.1198775089551518743",
"name": "WIN7-64B-USER",
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
}
},
"suspicions": null,
"filterData": {
"sortInGroupValue": "11.5133381726858807240",
"groupByValue": "MalopProcessRuntime:11.5133381726858807240 "
},
"isMalicious": false,
"suspicionCount": 0,
"guidString": "11.5133381726858807240",
"labelsIds": null,
"malopPriority": null
},
"11.-3698575578138794465": {
"simpleValues": {
"hasRansomwareSuspendedProcesses": {
"totalValues": 1,
"values": [
"false"
]
},
"decisionFeature": {
"totalValues": 1,
"values": [
"Process.maliciousByCodeInjection(Malop decision)"
]
},
"detectionType": {
"totalValues": 1,
"values": [
"PROCESS_INJECTION"
]
},
"malopActivityTypes": {
"totalValues": 1,
"values": [
"MALICIOUS_INFECTION"
]
},
"elementDisplayName": {
"totalValues": 1,
"values": [
"MALICIOUS_INFECTION"
]
},
"creationTime": {
"totalValues": 1,
"values": [
"1500192275252"
]
},
"isBlocked": {
"totalValues": 1,
"values": [
"false"
]
},
"rootCauseElementTypes": {
"totalValues": 1,
"values": [
"Process"
]
},
"malopStartTime": {
"totalValues": 1,
"values": [
"1500192264427"
]
},
"rootCauseElementNames": {
"totalValues": 1,
"values": [
"injected (program.exe > cmd.exe)"
]
},
"malopLastUpdateTime": {
"totalValues": 1,
"values": [
"1500192275253"
]
},
"allRansomwareProcessesSuspended": {
"totalValues": 1,
"values": [
"false"
]
},
"managementStatus": {
"totalValues": 1,
"values": [
"OPEN"
]
},
"closeTime": {
"totalValues": 1,
"values": [
null
]
},
"closerName": {
"totalValues": 1,
"values": [
null
]
},
"customClassification": {
"totalValues": 1,
"values": [
"None"
]
}
},
"elementValues": {
"affectedUsers": {
"totalValues": 1,
"elementValues": [
{
"elementType": "User",
"guid": "0.7211211867331652428",
"name": "test-pc\\test",
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
},
"affectedMachines": {
"totalValues": 1,
"elementValues": [
{
"elementType": "Machine",
"guid": "-1417547681.1198775089551518743",
"name": null,
"hasSuspicions": false,
"hasMalops": false
}
],
"totalSuspicious": 0,
"totalMalicious": 0
}
},
"suspicions": null,
"filterData": {
"sortInGroupValue": "11.-3698575578138794465",
"groupByValue": "MalopProcessRuntime:11.-3698575578138794465 "
},
"isMalicious": false,
"suspicionCount": 0,
"guidString": "11.-3698575578138794465",
"labelsIds": [],
"malopPriority": null
}
},
"suspicionsMap": {},
"evidenceMap": {},
"totalPossibleResults": 188,
"queryLimits": {
"totalResultLimit": 10000,
"perGroupLimit": 10000,
"perFeatureLimit": 100,
"groupingFeature": {
"elementInstanceType": "MalopProcess",
"featureName": "self"
},
"sortInGroupFeature": null
},
"queryTerminated": false,
"pathResultCounts": [
{
"featureDescriptor": {
"elementInstanceType": "MalopProcess",
"featureName": null
},
"count": 188
}
]
},
"status": "SUCCESS",
"message": ""
}