Run a Forensic 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/runForensicTool?dateBefore=<milliseconds_since_epoch>&dateAfter=<milliseconds_since_epoch>
Endpoint URI: forensics/runForensicTool?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: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

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>", 
    "sensorsIds": [
                    "<sensor ID for machine to which to deploy the tool>",
                  ],
    "filters": [
        {
            "fieldName": "<filter>",
            "operator": "<operator>",
            "values": [
                "<value>"
            ]
        }
    ]
}

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 including:

  • toolName: (required) The unique name for the package to execute on all or selected endpoints. This is the unique name for the tool package you retrieved when you retrieve a list of packages. For details on how to retrieve the list of supported packages, see Retrieve a List of Supported Forensics Ingestion Tools.

Use one of the following parameters to select specific endpoints:

  • sensorsIds: (optional) The sensor or sensor IDs on which to run the forensic data package. If you use this sensorsIds parameter, do not use the filters object below.

  • filters (optional) An object to specify a group of sensors. If you use the filters object, do not use the sensorsIds parameter above.

Note

If you add a parameter in the filters object, ensure you use the following syntax: {“fieldName”: “<filter parameter>”, “operator”: “<operator>”, “values”: [“<value>”]}

Field

Type

Description

actionsInProgress

Integer

The number of actions in progress (i.e. Not Resolved) on the machine.

amModeOrigin

String

The source of the value for the Anti-Malware Signatures mode setting.

amStatus

Enum

The Anti-Malware installation status for the sensor. Possible values include:

  • AM_INSTALLED

  • AM_UNINSTALLED

antiExploitStatus

Enum

The status of the Exploit Prevention feature. Possible values include:

  • ENABLED

  • DISABLED

This field returns a value only if you have enabled Exploit Prevention.

This field is applicable for versions 20.1 and higher.

antiMalwareStatus

Enum

The Anti-Malware prevention mode for the sensor. Possible values include:

  • AM_DETECT_DISINFECT

  • AM_DEFAULT

antiMalwareModeOrigin

String

The source of the value for the Anti-Malware setting.

archiveTimeMs

Timestamp

The time (in epoch) when the sensor was archived.

archivedOrUnarchiveComment

String

The comment added when a sensor was archived or unarchived.

avDbVersion

String

The version of the Anti-Malware Signatures database on the machine where the sensor is installed.

avDbLastUpdateTime

Long

The time when the Anti-Malware Signatures database on the machine where the sensor is installed was last updated.

collectionComponents

Enum

Any special collections enabled on the server and/or sensor. Possible values include:

  • DPI

  • Metadata

  • File events

  • Registry events

collectionStatus

Enum

States whether the machine has data collection enabled. Possible values include:

  • ENABLED

  • DISABLED

  • SUSPENDED

collectiveUuid

String

The identifier for the Registration server for the sensor.

compliance

Boolean

Indicates whether the current sensor settings match the policy settings.

consoleVersion

String

The version for the console for your Cybereason environment.

cpuUsage

Float

The amount of CPU used by the machine (expressed as a percentage).

criticalAsset

Boolean

The value assigned for the machine for the CRITICAL ASSET sensor tag.

customTags

String

A list of custom sensor tags assigned to the machine.

deliveryTime

Timestamp

The time (in epoch) when the last policy update was delivered to the sensor

DeletedBy

String

The Cybereason user that removed this sensor from the Sensors screen.

This field is available in versions 22.1.65 and later.

DeletedDate

String

The date the sensor was removed from the Sensors screen.

This field is available in versions 22.1.65 and later.

department

String

The value assigned to the machine for the DEPARTMENT sensor tag.

deviceType

String

The value assigned to the machine for the DEVICE TYPE sensor tag.

deviceModel

String

The model added for a device in the allowed devices section of the Endpoint Controls settings.

disconnected

Boolean

Indicates whether a sensor is currently disconnected.

disconnectionTime

Timestamp

Time the machine was disconnected. Returns 0 if this is the first connection time. After the first connection, this is the time it was last connected.

documentProtectionStatus

Enum

The status for the Document Protection mode. Possible options include:

  • DS_UNKNOWN

  • DS_DISABLED

  • DS_DETECT

  • DS_PREVENT

  • DS_QUARANTINE

documentProtectionMode

Enum

The mode set for the Document Protection mode. Possible options include:

  • DM_UNKNOWN

  • DM_CAUTIOUS

  • DM_MODERATE

  • DM_AGGRESSIVE

exitReason

String

The reason the sensor service (minionhost.exe) stopped.

externalIpAddress

String

The machine’s external IP address for the local network.

firstSeenTime

Timestamp

The first time the machine was recognized. Timestamp values are returned in epoch.

fullScanStatus

Enum

The status set for the sensor for the full scan.

fqdn

String

The fully qualified domain name (fqdn) for the machine.

fwStatus

Enum

The status of the Personal Firewall Control feature. Possible options include:

  • DISABLED

  • ENABLED

This field returns a value only if you have enabled Endpoint Controls.

This field is applicable for versions 19.2 and higher.

groupId

String

The identifier the Cybereason platform uses for the group to which the sensor is assigned.

groupName

String

The name for the group to which the sensor is assigned.

groupStickinessLabel

Enum

The method by which the sensor was assigned to the group. Possible options include:

  • Manual

  • Dynamic

groupStickiness

Boolean

Indicates whether this sensor is automatically assigned back to the group based on an assignment rule.

guid

String

The globally unique sensor identifier.

HeartBeatWin

String

The machine serial number.

This field is available from version 21.2.123 and later.

lastStatusAction

String

The last action taken that changed the sensor status.

lastUpgradeResult

Enum

The result of the last upgrade process. Possible options include:

  • None

  • Pending

  • InProgress

  • FailedSending

  • Primed

  • UnknownProbe

  • NotSupported

  • Disconnected

  • TimeoutSending

  • Failed

  • Succeeded

  • Timeout

  • InvalidState

  • UnauthorizedUser

  • partialResponse

  • ChunksRequired

  • Aborted

  • GettingChunks

  • ProbeRemoved

  • FailedSendingToServer

  • Started

  • SendingMsi

  • MsiSendFail

  • MsiFileCorrupted

  • AlreadyUpdated

  • NewerInstalled

lastUpgradeSteps

Enum

A list of step taken in the upgrade process. Possible options include:

  • None

  • Pending

  • InProgress

  • FailedSending

  • Primed

  • UnknownProbe

  • NotSupported

  • Disconnected

  • TimeoutSending

  • Failed

  • Succeeded

  • Timeout

  • InvalidState

  • UnauthorizedUser

  • partialResponse

  • ChunksRequired

  • Aborted

  • GettingChunks

  • ProbeRemoved

  • FailedSendingToServer

  • Started

  • SendingMsi

  • MsiSendFail

  • MsiFileCorrupted

  • AlreadyUpdated

  • NewerInstalled

If there is a failure to upgrade the sensor, this list shows the failure.

internalIpAddress

String

The machine’s internal IP address as identified by the sensor.

isolated

Boolean

States whether the machine is isolated. Returns true if the machine is isolated.

lastFullScheduleScanSuccessTime

Timestamp

The time (in epoch) that the sensor last did a successful full scan.

lastQuickScheduleScanSuccessTime

Timestamp

The time (in epoch) that the sensor last did a successful quick scan.

lastPylumUpdateTimestampMs

Timestamp

The last time (in epoch) the sensor sent a message to the Cybereason server.

location

String

The value assigned for this machine for the LOCATION sensor tag.

machineName

String

The name of the machine.

memoryUsage

Long

The amount of RAM on the hosting computer used by the sensor.

offlineTimeMS

Timestamp

The last time (in epoch) that the sensor was offline.

onlineTimeMS

Timestamp

The last time the sensor was seen online.

organization

String

The organization name for the machine on which the sensor is installed.

organizationalUnit

String

The name of the organization unit taken from the Active Directory on the machine on which the sensor is installed.

osType

Enum

The operating system running on the machine. Possible options include:

  • UNKNOWN_OS

  • WINDOWS

  • OSX

  • LINUX

osVersionType

Enum

Version of operating system for the machine. Possible options include:

  • Windows_20H2

  • Windows_11

  • Windows_10

  • Windows_8_1

  • Windows_8

  • Windows_7

  • Windows_Vista

  • Windows_XP_Professional_x64_Edition

  • Windows_XP

  • Windows_2000

  • Windows_Server_2012_R2

  • Windows_Server_2012

  • Windows_Server_2008_R2

  • Windows_Server_2008

  • Windows_Server_2003_R2

  • Windows_Home_Server

  • Windows_Server_2003

  • Windows_Server_2016

  • Windows_Server_2019

  • Windows_Server_2022

  • Monterey_12

  • Catalina_10_15

  • Big_Sur_11

  • Big_Sur_10__16

  • Mojave_10__14

  • High_Sierra_10__13

  • Sierra_10__12

  • El_Capitan_10__11

  • Yosemite_10__10

  • Maverick_10__9

  • Centos_Linux_6

  • Centos_Linux_7

  • Centos_Linux_8

  • Red_Hat_Enterprise_Linux_6

  • Red_Hat_Enterprise_Linux_7

  • Red_Hat_Enterprise_Linux_8

  • Ubuntu_Linux_12

  • Ubuntu_Linux_14

  • Ubuntu_Linux_16

  • Ubuntu_Linux_17

  • Ubuntu_Linux_18

  • Oracle_Linux_6

  • Oracle_Linux_7

  • Oracle_Linux_8

  • Suse_Linux_12

  • Suse_Linux_15

  • Amazon_Linux_2011__09

  • Amazon_Linux_2012__03

  • Amazon_Linux_2012__09

  • Amazon_Linux_2013__03

  • Amazon_Linux_2013__09

  • Amazon_Linux_2014__03

  • Amazon_Linux_2014__09

  • Amazon_Linux_2015__03

  • Amazon_Linux_2015__09

  • Amazon_Linux_2016__03

  • Amazon_Linux_2016__09

  • Amazon_Linux_2017__03

  • Amazon_Linux_2

  • Debian_Linux_8

  • Debian_Linux_9

  • Debian_Linux_10

outdated

Boolean

States whether or not the sensor version is out of sync with the server version.

pendingActions

Array

An array containing batch numbers for actions pending to run on the sensor.

policyId

String

The unique identifier the Cybereason platform uses for the policy assigned to the sensor.

policyName

String

The name of the policy assigned to this sensor.

powerShellStatus

Enum

The PowerShell Prevention mode. Possible options include:

  • PS_DISABLED

  • PS_ENABLED

  • PS_DEFAULT

preventionError

String

The error received for prevention by the sensor.

preventionStatus

Enum

The Execution Prevention mode. Possible options include:

  • ENABLE

  • DISABLE

  • UNINSTALL

  • UNKNOWN

privateServerIp

String

The private IP address for the Detection server for the sensor.

proxyAddress

String

The address for the Proxy server used by this sensor.

purgedSensors

Boolean

Indicates whether this sensor was removed from the Sensors screen.

pylumID

String

The unique identifier assigned by Cybereason to the sensor.

quickScanStatus

Enum

The status set for the sensor for a quick scan.

ransomwareStatus

Enum

The Anti-Ransomware mode. Possible options include:

  • UNKNOWN

  • DISABLED

  • DETECT_ONLY

  • DETECT_AND_SUSPEND

  • DETECT_SUSPEND_PREVENT

remoteShellStatus

Enum

Whether or not the Remote Shell utility is enabled for the sensor. Possible options include:

  • AC_DISABLED

  • AC_ENABLED

This field returns a value only if you have enabled Remote Shell for your Cybereason server.

sensorId

String

The unique identifier for a sensor.

sensorArchivedByUser

String

The Cybereason user name for the user who archived the selected sensor.

sensorLastUpdate

Timestamp

The last time (in epoch) that the sensor was updated.

serialNumber

String

The serial number added for a device in the allowed devices section of the Endpoint Controls settings.

serverId

String

The unique identifier for the Detection server for the sensor.

serverIp

String

The IP address for the Detection server for the sensor.

serverName

String

The name of the server for the sensor.

serviceStatus

Enum

Indicates the current value of the Anti-Malware service. Possible options include:

  • DISABLED

  • DETECT

  • PREVENT

  • SET_BY_POLICY

siteName

String

The name of the site for the sensor.

siteId

Long

The identifier for the sensor’s site.

staleTimeMS

Integer

The time (in epoch) when the Sensor was classified as Stale.

staticAnalysisDetectMode

Enum

The value for the Artificial Intelligence Detect mode in the Anti-Malware settings. Possible options include:

  • DISABLED

  • CAUTIOUS

  • MODERATE

  • AGGRESSIVE

  • SET_BY_POLICY

staticAnalysisDetectModeOrigin

Enum

The source of the value for the Artificial Intelligence Detect mode setting. Possible options include:

  • NOT_AVAILBLE

  • SET_BY_POLICY

  • SET_MANUALLY

  • AWAITING_UPDATE

staticAnalysisPreventMode

Enum

The value for the Artificial Intelligence Prevent Mode in the Anti-Malware settings. Possible options include:

  • DISABLED

  • CAUTIOUS

  • MODERATE

  • AGGRESSIVE

staticAnalysisPreventModeOrigin

Enum

The source of the value for the Artificial Intelligence Prevent mode setting. Possible options include:

  • NOT_AVAILBLE

  • SET_BY_POLICY

  • SET_MANUALLY

  • AWAITING_UPDATE

status

Enum

The status of the sensor. Possible options include:

  • Online

  • Offline

  • Stale

  • Archived

statusTimeMS

Timestamp

The last time (in epoch) when the sensor sent a status.

upTime

Long

The time the sensors have been in the UP state.

usbStatus

Enum

The status of the Device Control feature. Possible options include:

  • ENABLED: the Cybereason platform blocks access to all USB devices

  • DISABLED: the Cybereason platform allows access to all USB devices

This field returns a value only if you have enabled Endpoint Controls.

This field is applicable for versions 19.2 and higher.

version

String

The sensor version number.


Operators

Use the following operators with the respective filters object, depending on the parameter you use in the filters object:

  • Equals (for Enum values)

  • NotEquals (for Enum values)

  • ContainsIgnoreCase (for string values)

  • NotContainsIgnoreCase (for string values)

  • LessThan (for integer values)

  • LessOrEqualsTo (for integer values)

  • GreaterThan (for integer values)

  • GreaterOrEqualsTo (for integer values)

  • Between (for integer values)

Add following operators if needed, with the syntax "operator":<value>.


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 data package, this should report IRToolsRunVRCollector.

  • 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 a forensic data ingestion tool on online endpoints

Request

curl --request POST \
    --url https://12.34.56.78/rest/forensics/runForensicTool \
    --header 'Content-Type:application/json' \
    --data '{
                "toolName": "CustomPrefetchOfflineCollector",
                "filters": [
                    {
                        "fieldName": "osType",
                        "operator": "Equals",
                        "values": [
                            "WINDOWS"
                        ]
                    },
                    {
                        "fieldName": "status",
                        "operator": "Equals",
                        "values": [
                            "Online"
                        ]
                    }
                ]
            }'

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