Run a Forensic Data Ingestion Tool with Sensors from a CSV File

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/runForensicToolWithInputFile?dateBefore=<milliseconds_since_epoch>&dateAfter=<milliseconds_since_epoch>
Endpoint URI: forensics/runForensicToolWithInputFile?dateBefore=<milliseconds_since_epoch>&dateAfter=<milliseconds_since_epoch>

Action: POST

Runs a forensic data ingestion tool on a machine or selected group of machines. The tool must already be deployed on the machine to use this request.

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.

Request Headers

You must add a Content-Type:multipart/form-data 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: Form values

Request Parameters

URL/URI parameters: You can add one of the following optional date parameters as part of the request URL:

• dateBefore: The time (in milliseconds) before which to search

• dateAfter: The time (in milliseconds) after which to search

Request Body Parameters: You must add the following REQUIRED parameters:

• toolName: The string with the name of the forensic data package to run. To retrieve a list of supported packages, see Retrieve a List of Supported Forensics Ingestion Tools.

• file: The type for this parameter. Enter a parameter type with a value of File.

  You can retrieve this file in the System > Sensors screen. In the Sensors screen, select the sensors, click Actions and select Export to CSV. This downloads the sensor CSV file from the screen with the sensor details, including the Sensor ID column that is required to run this request.

Response Status Codes

This request can return the following status codes:

• 200: The request succeeded

• 400: Bad request parameters

• 403: Lack of permissions to perform the request / IRTools service is disabled

• 500: Internal error on Perspective Server

• 503: Forensics service is disabled

Response Success Schema

The response includes:

Field	Type	Description
batchID	Integer	The ID for the operation. You may need this number for other operations with the API.
actionType	Enum	The action taken on the sensor. Possible values include: InstallPrevention SetAntiMalwareStatus SetRansomewareMode SetPowerShellProtectionStatus StartCollection StopCollection Restart FetchLog Upgrade Archive Unarchive Abort IRToolsRunIRTool IRToolsDownloadResults IRToolsRunVRCollection
actionArguments	String	The arguments passed for the operation.
globalStats	Array	Collection of items about the operation. For details about this object, see globalStatsObject.
finalState	Boolean	Indicates whether the sensor is in the state indicated by the operation.
totalNumberOfProbes	Integer	How many sensors were affected by the current operation
initiatorUser	String	The user name of the user who performed this operation.
startTime	Timestamp	The start time of the operation.
aborterUser	String	The user name of the user who aborted the operation. This field only exists if the operation was aborted.
abortTime	Timestamp	The time (in epoch) when the operation was aborted. This field only exists if the operation was aborted.
abortTimeout	Boolean	Indicates whether there is a timeout value for timing out the request to abort.
abortHttpStatusCode	String	The code sent by the server to abort the operation. This field only exists if the operation was aborted.

Response Failure Schema

An error code with a description of the error.

Important Response Fields

Important information is found in these fields:

• batchID: The operation identifier for the sensor operation. You can use this batch ID to monitor the execution.

• actionType: The type of sensor operation. For this request to run a forensic package, this should report IRToolsRunVRCollection.

• stats object: This object contains details on the final result of the operation for the sensors included in the batch. View the different fields available in this object and the number of sensors to which this status applied.

• totalNumberOfProbes: The total number of sensors to which this operation applied.

Example: Run an forensic data ingestion tool on endpoints

CURLREST API ClientPython

Request

curl --request POST \
    --url https://12.34.56.78/rest/forensics/runForensicToolWithInputFile \
    --header 'Content-Type: multipart/form-data' \
    --form 'toolName="CustomPrefetchOfflineCollector"' \
    --form 'file=@"/C:/Work/vraptor/CybereasonSensors_2022-02-09_10-01.csv"'

Response

{
    "batchId": 1961747483,
    "actionType": "IRToolsRunVRCollection",
    "actionArguments": {
        "@class": "com.cybereason.configuration.models.irtools.IRToolsRunIRToolParameters",
        "commandLine": "$CMS$IRTOOLS.CustomPrefetchOfflineCollector artifacts collect Custom.Prefetch.Artifact --args PylumID=<pylumId_placeholder> --args Collective=<collectiveHostname_placeholder> --output output.zip",
        "outputDir": "",
        "toolId": "IRTOOLS.CustomPrefetchOfflineCollector"
    },
    "globalStats": {
        "stats": {
            "Succeeded": 0,
            "EndedWithUnsupportedFilter": 0,
            "InvalidState": 0,
            "ChunksRequired": 0,
            "AbortTimeout": 0,
            "SendingMsi": 0,
            "NewerInstalled": 0,
            "TimeoutSending": 0,
            "Timeout": 0,
            "Aborting": 0,
            "None": 1,
            "Aborted": 0,
            "FailedSending": 0,
            "Disconnected": 0,
            "partialResponse": 0,
            "EndedWithTooManySearches": 0,
            "UnauthorizedUser": 0,
            "BadArgument": 0,
            "EndedWithUnknownError": 0,
            "Started": 0,
            "SendingPlatform": 0,
            "Primed": 0,
            "MsiSendFail": 0,
            "EndedWithInvalidParam": 0,
            "EndedWithSensorTimeout": 0,
            "Failed": 0,
            "ProbeRemoved": 0,
            "EndedWithYaraCompileError": 0,
            "EndedWithNoValidFolder": 0,
            "EndedWithTooManyResults": 0,
            "UnknownProbe": 0,
            "InProgress": 0,
            "FailedSendingToServer": 0,
            "GettingChunks": 0,
            "MsiFileCorrupted": 0,
            "NotSupported": 0,
            "Pending": 0,
            "AlreadyUpdated": 0
        }
    },
    "finalState": false,
    "totalNumberOfProbes": 1,
    "initiatorUser": "[email protected]",
    "startTime": 1646551878893,
    "aborterUser": null,
    "abortTime": 0,
    "abortTimeout": false,
    "abortHttpStatusCode": null,
    "creatorUser": "[email protected]"
}