Remediate Items
Endpoint URL: https://<your server>/rest/remediate
Endpoint URI: remediate
Action: POST
Remediates a specific process, file, or registry key if remediation is possible.
Note
Ensure that you have logged into the Cybereason platform. For details, see Log in with the API.
Request Headers
You must add an Content-Type:application/json header with the request.
Note
If you are using cURL, add the authorization cookie details or the path to the file with cookie details with every request.
Request Body
Input: JSON
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.
{
"malopId": "<malopID>",
"initiatorUserName": "<user name>",
"actionsByMachine": {
"<machineID>": [
{
"targetId":"<item GUID>",
"actionType": "<action>"
}
]
}
}
Request Parameters
URL/URI parameters: none
Request Body Parameters: You can use the following parameters in the request. Required parameters are noted in bold:
Field |
Type |
Description |
---|---|---|
malopId |
Integer |
The unique ID assigned by the Cybereason platform for the Malop. This ID is found when you retrieve the list of Malops. For details on getting this ID, see, Retrieve All MalOps. You can perform remediation without this malop ID. |
initiatorUserName |
String |
The Cybereason user name for the user performing the remediation. |
actionsByMachine |
Array |
A collection of parameters describing the remediation operation. |
machineId |
Integer |
The unique GUID for the machine. Note this is different from the sensor ID (pylumID) value. |
targetId |
String |
The unique GUID for the process or file to remediate. You can find this GUID in the response when you perform an investigation query for a process.
Note that using the targetId parameter is supported only for processes (the KILL_PROCESS action) and files (the QUARANTINE_FILE or UNQUARANTINE_FILE action). |
actionType |
Enum |
The remediation action to perform. Possible values include:
|
Response Status Codes
This request can return the following status codes:
200: Success OK
Response Success Schema
The response includes the following fields:
Field |
Type |
Description |
---|---|---|
malopID |
Float |
The numerical identifier of the Malop assigned by Cybereason. |
remediationID |
Float |
The numerical identifier of the remediation operation assigned by Cybereason. |
start |
Timestamp |
The time (in epoch) that the remediation operation began. |
end |
Timestamp |
The time (in epoch) the the remediation operation ended. |
initiatingUser |
String |
The Cybereason user name of the user initiating the remediation. |
statusLog |
Array |
An object containing information about the remediation. |
machineID |
Float |
The unique ID for the machine or machines on which the remediation was performed. |
targetID |
String |
The unique identifier for the target item for the remediation operation. |
status |
String |
The status of the remediation request. Possible values include:
|
actionType |
String |
The type of action you attempted to perform. |
timestamp |
Integer |
The time (in epoch) of the status report for the remediation request. |
Response Failure Schema
The response includes the following fields:
Field |
Type |
Description |
---|---|---|
malopID |
Float |
The numerical identifier of the Malop assigned by Cybereason. |
remediationID |
Float |
The numerical identifier the Cybereason platform uses for the remediation operation. |
start |
Timestamp |
The time (in epoch) that the remediation operation began. |
end |
Timestamp |
The time (in epoch) the the remediation operation ended. |
initiatingUser |
String |
The Cybereason user name of the user initiating the remediation. |
statusLog |
Array |
An object containing information about the remediation. |
machineID |
Float |
The unique ID for the machine or machines on which the remediation was performed. |
targetID |
String |
Reports a null value. |
status |
Enum |
The status of the remediation request. Possible values include:
|
actionType |
String |
The type of action you attempted to perform. |
timestamp |
Integer |
The time (in epoch) of the status report for the remediation request. |
error |
Array |
An object containing details of the error. |
message |
String |
A description of the error. |
errorType |
Enum |
The type of error. Possible values include:
|
Important Response Fields
Important information is found in these fields:
remediationId: The unique identifier the Cybereason platform uses to identify the remediation operation. You may need this identifier in future requests to check the status of the remediation.
start and end: These timestamps show the start and end times (in epoch) for the remediation operation.
status: The current status of the remediation operation. Note that the request can succeed with a 200 OK HTTP status code but this field may show a remediation operation failure. This is due to the fact that the HTTP status code does not represent the status of the remediation operation which is performed by your Cybereason servers after the request is successfully processed.
Example: Remediate a process in a Malop
Request
curl --request POST \
--url https://12.34.56.78/rest/remediate \
--header 'Content-Type:application/json' \
--data '{
"malopId": "11.2718161727221199870",
"initiatorUserName": "[email protected]",
"actionsByMachine": {
"-1632138521.1198775089551518743": [
{
"targetId": "-2095200899.6557717220054083334",
"actionType": "KILL_PROCESS"
}
]
}
}'
Response
{
"malopId": "11.2718161727221199870",
"remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664",
"start": 1518604850656,
"end": 1518604850744,
"initiatingUser": "[email protected]",
"statusLog": [
{
"machineId": "-1632138521.1198775089551518743",
"targetId": null,
"status": "SUCCESS",
"actionType": "KILL_PROCESS",
"timestamp": 1518604850714
}
]
}
Request
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:
{
"malopId": "11.2718161727221199870",
"initiatorUserName": "[email protected]",
"actionsByMachine": {
"-1632138521.1198775089551518743": [
{
"targetId": "-2095200899.6557717220054083334",
"actionType": "KILL_PROCESS"
}
]
}
}
Response
{
"malopId": "11.2718161727221199870",
"remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664",
"start": 1518604850656,
"end": 1518604850744,
"initiatingUser": "[email protected]",
"statusLog": [
{
"machineId": "-1632138521.1198775089551518743",
"targetId": null,
"status": "SUCCESS",
"actionType": "KILL_PROCESS",
"timestamp": 1518604850714
}
]
}
Request
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/remediate"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
malop_id = "11.2718161727221199870"
remediation_user = "[email protected]"
machine_name = "-1632138521.1198775089551518743"
remediation_action = "KILL_PROCESS"
target_id = "-2095200899.6557717220054083334"
query = json.dumps({"malopId":malop_id,"initiatorUserName":remediation_user,"actionsByMachine":{machine_name:[{"targetId":target_id,"actionType":remediation_action}]}})
api_response = session.request("POST", api_url, data=query, headers=headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
{ "malopId": "11.2718161727221199870", "remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664", "start": 1518604850656, "end": 1518604850744, "initiatingUser": "[email protected]", "statusLog": [ { "machineId": "-1632138521.1198775089551518743", "targetId": null, "status": "SUCCESS", "actionType": "KILL_PROCESS", "timestamp": 1518604850714 } ] }
Example: Remediate a process not involved in a Malop
Request
curl --request POST \ --url https://12.34.56.78/rest/remediate \ --header 'Content-Type:application/json' \ --data '{ "initiatorUserName": "[email protected]", "actionsByMachine": { "-1632138521.1198775089551518743": [ { "targetId": "-2095200899.6557717220054083334", "actionType": "KILL_PROCESS" } ] } }'
Response
{
"remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664",
"start": 1518604850656,
"end": 1518604850744,
"initiatingUser": "[email protected]",
"statusLog": [
{
"machineId": "-1632138521.1198775089551518743",
"targetId": null,
"status": "SUCCESS",
"actionType": "KILL_PROCESS",
"timestamp": 1518604850714
}
]
}
Request
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:
{ "initiatorUserName": "[email protected]", "actionsByMachine": { "-1632138521.1198775089551518743": [ { "targetId": "-2095200899.6557717220054083334", "actionType": "KILL_PROCESS" } ] } }
Response
{ "remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664", "start": 1518604850656, "end": 1518604850744, "initiatingUser": "[email protected]", "statusLog": [ { "machineId": "-1632138521.1198775089551518743", "targetId": null, "status": "SUCCESS", "actionType": "KILL_PROCESS", "timestamp": 1518604850714 } ] }
Request
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/remediate" api_url = base_url + endpoint_url # These are the variables that represent different fields in the request. remediation_user = "[email protected]" machine_name = "-1632138521.1198775089551518743" target_id = "-2095200899.6557717220054083334" remediation_action = "KILL_PROCESS" query = json.dumps({"initiatorUserName":remediation_user,"actionsByMachine":{machine_name:[{"targetId":target_id,"actionType":remediation_action}]}}) 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))
Response
{ "remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664", "start": 1518604850656, "end": 1518604850744, "initiatingUser": "[email protected]", "statusLog": [ { "machineId": "-1632138521.1198775089551518743", "targetId": null, "status": "SUCCESS", "actionType": "KILL_PROCESS", "timestamp": 1518604850714 } ] }
Example: Remediation failure for a remediation request
Request
curl --request POST \
--url https://12.34.56.78/rest/remediate \
--header 'Content-Type:application/json' \
--data '{
"initiatorUserName": "[email protected]",
"actionsByMachine": {
"laptop-demo-sales": [
{
"targetId": "-2095200899.6557717220054083334",
"actionType": "KILL_PROCESS"
}
]
}
}'
Response
{
"malopId": null,
"remediationId": "1a0771c8-4536-4292-8d3c-109a1472d48d",
"start": 1560795947156,
"end": 1560795947256,
"initiatingUser": "[email protected]",
"statusLog": [
{
"machineId": "laptop-demo-sales",
"targetId": null,
"status": "FAILURE",
"actionType": "KILL_PROCESS",
"error": {
"message": "Server error",
"errorType": "INVALID_ARGUMENT"
},
"timestamp": 1560795947237
}
]
}
Request
Use this request body:
{
"initiatorUserName": "[email protected]",
"actionsByMachine": {
"laptop-demo-sales": [
{
"targetId": "-2095200899.6557717220054083334",
"actionType": "KILL_PROCESS"
}
]
}
}
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.
Response
{
"malopId": null,
"remediationId": "1a0771c8-4536-4292-8d3c-109a1472d48d",
"start": 1560795947156,
"end": 1560795947256,
"initiatingUser": "[email protected]",
"statusLog": [
{
"machineId": "laptop-demo-sales",
"targetId": null,
"status": "FAILURE",
"actionType": "KILL_PROCESS",
"error": {
"message": "Server error",
"errorType": "INVALID_ARGUMENT"
},
"timestamp": 1560795947237
}
]
}
Request
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/remediate"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
remediation_user = "[email protected]"
machine_name = "laptop-demo-sales"
target_id = "-2095200899.6557717220054083334"
remediation_action = "KILL_PROCESS"
query = json.dumps({"initiatorUserName":remediation_user,"actionsByMachine": {machine_name: [{"targetId":target_id,"actionType":remediation_action}]}})
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))
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.
Response
{ "malopId": null, "remediationId": "1a0771c8-4536-4292-8d3c-109a1472d48d", "start": 1560795947156, "end": 1560795947256, "initiatingUser": "[email protected]", "statusLog": [ { "machineId": "laptop-demo-sales", "targetId": null, "status": "FAILURE", "actionType": "KILL_PROCESS", "error": { "message": "Server error", "errorType": "INVALID_ARGUMENT" }, "timestamp": 1560795947237 } ] }
Example: Quarantine a file
Request
curl --request POST \ --url https://12.34.56.78/rest/remediate \ --header 'Content-Type:application/json' \ --data '{ "initiatorUserName": "[email protected]", "actionsByMachine": { "-1632138521.1198775089551518743": [ { "targetId": "-2095200899.6557717220054083334", "actionType": "QUARANTINE_FILE" } ] } }'
Response
{
"remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664",
"start": 1518604850656,
"end": 1518604850744,
"initiatingUser": "[email protected]",
"statusLog": [
{
"machineId": "-1632138521.1198775089551518743",
"targetId": null,
"status": "SUCCESS",
"actionType": "QUARANTINE_FILE",
"timestamp": 1518604850714
}
]
}
Request
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:
{ "initiatorUserName": "[email protected]", "actionsByMachine": { "-1632138521.1198775089551518743":[ { "targetId": "-2095200899.6557717220054083334", "actionType": "QUARANTINE_FILE" } ] } }
Response
{ "remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664", "start": 1518604850656, "end": 1518604850744, "initiatingUser": "[email protected]", "statusLog": [ { "machineId": "-1632138521.1198775089551518743", "targetId": null, "status": "SUCCESS", "actionType": "QUARANTINE_FILE", "timestamp": 1518604850714 } ] }
Request
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/remediate" api_url = base_url + endpoint_url # These are the variables that represent different fields in the request. remediation_user = "[email protected]" machine_name = "laptop-demo-sales" target_id = "-2095200899.6557717220054083334" remediation_action = "QUARANTINE_FILE" query = json.dumps({"initiatorUserName":remediation_user,"actionsByMachine": {machine_name: [{"targetId":target_id,"actionType":remediation_action}]}}) 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))
Response
{ "remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664", "start": 1518604850656, "end": 1518604850744, "initiatingUser": "[email protected]", "statusLog": [ { "machineId": "-1632138521.1198775089551518743", "targetId": null, "status": "SUCCESS", "actionType": "QUARANTINE_FILE", "timestamp": 1518604850714 } ] }
Example: Unquarantine a file
Request
curl --request POST \ --url https://12.34.56.78/rest/remediate \ --header 'Content-Type:application/json' \ --data '{ "initiatorUserName": "[email protected]", "actionsByMachine": { "-1632138521.1198775089551518743": [ { "targetId": "-2095200899.6557717220054083334", "actionType": "UNQUARANTINE_FILE" } ] } }'
Response
{
"remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664",
"start": 1518604850656,
"end": 1518604850744,
"initiatingUser": "[email protected]",
"statusLog": [
{
"machineId": "-1632138521.1198775089551518743",
"targetId": null,
"status": "SUCCESS",
"actionType": "UNQUARANTINE_FILE",
"timestamp": 1518604850714
}
]
}
Request
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:
{ "initiatorUserName": "[email protected]", "actionsByMachine": { "-1632138521.1198775089551518743":[ { "targetId": "-2095200899.6557717220054083334", "actionType": "UNQUARANTINE_FILE" } ] } }
Response
{ "remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664", "start": 1518604850656, "end": 1518604850744, "initiatingUser": "[email protected]", "statusLog": [ { "machineId": "-1632138521.1198775089551518743", "targetId": null, "status": "SUCCESS", "actionType": "UNQUARANTINE_FILE", "timestamp": 1518604850714 } ] }
Request
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/remediate" api_url = base_url + endpoint_url # These are the variables that represent different fields in the request. remediation_user = "[email protected]" machine_name = "-1632138521.1198775089551518743" target_id = "-2095200899.6557717220054083334" remediation_action = "UNQUARANTINE_FILE" query = json.dumps({"initiatorUserName":remediation_user,"actionsByMachine": {machine_name: [{"targetId":target_id,"actionType":remediation_action}]}}) api_response = session.request("POST", api_url, data=query, headers=headers) your_response = json.loads(api_response.content) print(json.dumps(your_response, indent=4, sort_keys=True))
Response
{ "remediationId": "86f3faa1-bac0-4a17-9192-9d106b734664", "start": 1518604850656, "end": 1518604850744, "initiatingUser": "[email protected]", "statusLog": [ { "machineId": "-1632138521.1198775089551518743", "targetId": null, "status": "SUCCESS", "actionType": "UNQUARANTINE_FILE", "timestamp": 1518604850714 } ] }