Monitor Forensic Data Ingestion Tool Execution
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/getForensicToolRunStatus/:batchId
Endpoint URI: forensics/getForensicToolRunStatus/:batchId
Action: GET
Monitors the execution of a forensic data package (identified by the batch ID number from an execution request). For details on how to run a forensic data package, see Run a Forensic Data Ingestion Tool.
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 containing the cookie details as part of every request.
Request Body
None
Request Parameters
URL/URI parameters: You must add the required batchID string value (taken from the response of the request to run an forensic data package) in the URL.
Request Body Parameters: none
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 contains the following fields:
Sensor: The unique sensor ID for the sensors involved in the forensic data package execution.
Status: The status of the package execution operation.
Note that the request can succeed and the tool process may start on the target machine(s). However, a response of success does not guarantee that the IR tool process runs correctly or collects results from the machine. To verify that the process ran correctly, you can use the Investigation screen and view the details of the tool process.
Error: Any relevant error messages.
Response Failure Schema
An error code with a description of the error.
Important Response Fields
All information contained in the response is important for you to understand if the package ran successfully.
Example: Monitor the status of a forensic data package
Request
curl --request GET \
--url https://12.34.56.78/forensics/getForensicToolRunStatus/1438096773 \
--header 'Content-Type:application/json' \
Response
Sensor,Status,Error
PYLUMCLIENT_IR-15-APRIL_WIN10-X64-19H1_005056A642D0,Succeeded,SEC_SUCCESS
PYLUMCLIENT_IR-15-APRIL_WIN10-X64-20H1_005056A66E2C,Succeeded,SEC_SUCCESS
Request
Response
Sensor,Status,Error
PYLUMCLIENT_IR-15-APRIL_WIN10-X64-19H1_005056A642D0,Succeeded,SEC_SUCCESS
PYLUMCLIENT_IR-15-APRIL_WIN10-X64-20H1_005056A66E2C,Succeeded,SEC_SUCCESS
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 = "mypassword"
server = "yourserver.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=814920&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
batch_id = 1438096773
endpoint_url = "/rest/forensics/getForensicToolRunStatus/"
api_url = base_url + endpoint_url + str(batch_id)
api_response = session.request("GET", api_url, headers=headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
Sensor,Status,Error
PYLUMCLIENT_IR-15-APRIL_WIN10-X64-19H1_005056A642D0,Succeeded,SEC_SUCCESS
PYLUMCLIENT_IR-15-APRIL_WIN10-X64-20H1_005056A66E2C,Succeeded,SEC_SUCCESS