Deploy a Forensics Data Ingestion Tool

Note

To use the data ingestion tool features, you can add the DFIR package to your instance of the Cybereason platform for an additional cost or request an Express IR environment (partners only). Contact your Customer Success representative to request access to this package or for details on how to submit the request, see How to Request a Cybereason Express IR Environment.

Endpoint URL: https://<your server>/rest/forensics/uploadForensicTool
Endpoint URI: forensics/uploadForensicTool

Action: POST

Enables you to deploy forensic data ingestion tools to machines in your Cybereason environment.

This request is supported for versions 21.2.221 and later.

You must have the Responder L2 role assigned for your Cybereason user to run this request.

Note

Ensure that you have logged into the Cybereason platform. For details, see Log in with the API.

You must add a 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 containing the cookie details as part of 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.

{
    "toolName": "<tool name>",
    "toolOSInfoList": [
        {
           "osTypeGroup":"WINDOWS_TYPES", 
           "platform": "<type of OS>"
        }
    ]
}

URL/URI parameters: none

Request Body Parameters: Use the following available fields in the request. Required parameters are noted in bold.

Field	Type	Description
toolName	String	The name for the package. You must use a unique name for the package. For details on how to retrieve a list of packages, see Retrieve a List of Supported Forensics Ingestion Tools.
packageOSInfoList	JSON	An object containing details on the machine operating system filter for the package. This object contains the osTypeGroup and platform parameters.
osTypeGroup	Enum	The operating system type for the deployment. Enter WINDOWS_TYPES for this field. If you need additional operating system types, contact Technical Support. Ensure you define the most specific OS specification for the machines to which to deployto ensure that the Cybereason platform does not deploy the package to an endpoint machine that the machine cannot run.
platform	Enum	The type of operating system, such as 64-bit or 32-bit. Enter one of the following values: ARCH_X86 ARCH_AMD64

This request can return the following status codes:

200: The request succeeded.
400: Bad request parameters
403: Lack of permissions to perform the request
500: Internal error on Perspective Server
503: Forensics/IRTools service is disabled

The response contains a message Forensic tool CustomPrefetchOfflineCollector upload request was submitted successfully.

An error code with a description of the error.

Request

curl --request POST \
  --url https://12.34.56.78/rest/forensics/uploadForensicTool \
  --header 'Content-Type:application/json' \
  --data '{
                "toolName": "<tool name>",
                     "toolOSInfoList": [
                    {
                        "osTypeGroup": "WINDOWS_TYPES"
                    }
                ]
          }'

Response

Forensic tool CustomPrefetchOfflineCollector upload request was submitted successfully

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:
{
 "toolName": "CustomPrefetchOfflineCollector",
 "toolOSInfoList": [
        {
            "osTypeGroup": "WINDOWS_TYPES"
        }
    ]
}
Response

Forensic tool CustomPrefetchOfflineCollector upload request was submitted successfully

Request

Note

Ensure you replace the value of the totpCode parameter in the script example below with your unique TOTP code generated from your app or program.

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

payload='totpCode=369511&Submit=Login'
tfa_headers = {"Content-Type": "application/x-www-form-urlencoded"}

tfa_url = "https://" + server + "/"

tfa_response = session.post(tfa_url, headers=tfa_headers, data=payload, verify=True)

# Request URL

endpoint_url = "/rest/forensics/uploadForensicTool"

api_url = base_url + endpoint_url

# These are the variables that represent different fields in the request.

package_name = "CustomPrefetchOfflineCollector"

query = json.dumps({"toolName":package_name,"toolOSInfoList":[{"osTypeGroup": "WINDOWS_TYPES"}]})

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

Forensic tool CustomPrefetchOfflineCollector upload request was submitted successfully