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
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:
|
antiExploitStatus |
Enum |
The status of the Exploit Prevention feature. Possible values include:
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:
|
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:
|
collectionStatus |
Enum |
States whether the machine has data collection enabled. Possible values include:
|
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:
|
documentProtectionMode |
Enum |
The mode set for the Document Protection mode. Possible options include:
|
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:
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:
|
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:
|
lastUpgradeSteps |
Enum |
A list of step taken in the upgrade process. Possible options include:
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:
|
osVersionType |
Enum |
Version of operating system for the machine. Possible options include:
|
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:
|
preventionError |
String |
The error received for prevention by the sensor. |
preventionStatus |
Enum |
The Execution Prevention mode. Possible options include:
|
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:
|
remoteShellStatus |
Enum |
Whether or not the Remote Shell utility is enabled for the sensor. Possible options include:
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:
|
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:
|
staticAnalysisDetectModeOrigin |
Enum |
The source of the value for the Artificial Intelligence Detect mode setting. Possible options include:
|
staticAnalysisPreventMode |
Enum |
The value for the Artificial Intelligence Prevent Mode in the Anti-Malware settings. Possible options include:
|
staticAnalysisPreventModeOrigin |
Enum |
The source of the value for the Artificial Intelligence Prevent mode setting. Possible options include:
|
status |
Enum |
The status of the sensor. Possible options include:
|
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:
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:
|
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]"
}
Request
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",
"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]"
}
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.
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=526681&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/runForensicTool"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
package_name = "CustomPrefetchOfflineCollector"
filter_1_type = "osType"
filter_1_value = "WINDOWS"
filter_2_type = "status"
filter_2_value = "Online"
query = json.dumps({"toolName":package_name,"filters":[{"fieldName":filter_1_type,"operator":"Equals","values":[filter_1_value]},{"fieldName":filter_2_type,"operator":"Equals","values":[filter_2_value]}]})
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
{
"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]"
}