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

CURLREST API ClientPython

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