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.

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.

Input: JSON

Download JSON syntax file

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>"
                        }
                    ]
                }
            }

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. For the KILL_PROCESS action, this is the process GUID. For the QUARANTINE_FILE action, this is the file GUID. For the UNQUARANTINE_FILE action, the targetId (GUID) value is different than the GUID of the original file for the QUARANTINE_FILE action. To find this GUID for the quarantined file,run a query with the Quarantine File Element. 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: KILL PROCESS. Use this option to immediately stop the process associated with the root cause of the Malop. DELETE_REGISTRY_KEY. Use this option to remove any registry keys detected as malicious as part of the Malop. QUARANTINE_FILE. Use this option to quarantine the detected malicious file in a secure location. UNQUARANTINE_FILE. Use this option to enable the Cybereason platform to remove a file from quarantine. This option is available in version 20.1.120 and later. BLOCK_FILE. Use this to enable Application Control to block the file(s) associated with the Malop when it they are detected in the future. KILL_PREVENT_UNSUSPEND. Use this option to prevent detected ransomware from running on the machine. UNSUSPEND_PROCESS. Use this option to prevent a file associated with ransomware.

This request can return the following status codes:

200: Success OK

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: SUCCESS PENDING IN_PROGRESS
actionType	String	The type of action you attempted to perform.
timestamp	Integer	The time (in epoch) of the status report for the remediation request.

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: FAILURE ABORTED
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: PROBE_DISCONNECTED: The Sensor is offline. TIMED_OUT_WAITING_FOR_PROBE: The remediation request timed out while waiting for the Sensor to come online. GENERAL_PROBE_FAILURE: There was an unknown error on the Sensor. UNSUPPORTED_VERSION: The Sensor version does not support this remediation action. PROBE_FILE_NOT_FOUND: The Sensor could not find the file for the remediation action. PROBE_ACCESS_IS_DENIED: The Sensor cannot access the requested file for remediation. PROBE_INVALID_PARAMETER: An invalid argument was sent to the Sensor. PROBE_TIMEOUT: There was a Sensor timeout when the Sensor went offline. PROBE_NOT_ENOUGH_SPACE: The Sensor does not have enough space to perform the selected remediation action. PROBE_READ_ONLY_FILE: The file for remediation is a read-only file. PROBE_HELD_BY_ANOTHER_PROCESS: The file for remediation is currently in use by another process. INVALID_ARGUMENT: There is an error in your request. BROADCAST_FAILURE: There was an error reaching the server or the same Sensor ID is found on multiple servers. SERVER_ERROR: There was a general server error.

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.

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

Download JSON syntax file

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

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 = "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
      }
  ]
}

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

Download JSON syntax file

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

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 = "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
      }
  ]
}

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"
                                            }
                                        ]
                                    }
                                }

Download JSON syntax file

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))

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.

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

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

Download JSON syntax file

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

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 = "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
      }
  ]
}

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

Download JSON syntax file

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

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 = "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
      }
  ]
}