Upload and Deploy a Tool Package
Note
To use the incident response 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/irtools/upload
Endpoint URI: irtools/upload
Action: POST
Enables you to upload a package for a third-party incident response tool to your Cybereason platform or upgrade an existing package that was previously uploaded, and then deploy that package to selected machines.
The maximum file size for a tool package file is 100 MB.
This request is supported for versions 21.1.81 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
None
Request Body
You add the request parameters described below as form-data values.
Request Parameters
URL/URI parameters: none
Request Body Parameters: Use the following available fields in the request. Required parameters are noted in bold.
Field |
Type |
Description |
|---|---|---|
packageName |
String |
The name for the package. You must use a unique name for the package. |
packageInfo |
File |
A multipart octet stream containing the body of the tool’s package file/binary file. |
packageOSInfoList |
Array |
An object containing details on the machine operating system filter for the package. This object contains the osTypeGroup and platform keys. |
osTypeGroup |
Enum |
The operating system type for the deployment. Use one of the following values:
Note The ALL and LINUX_TYPES values are not generally available. You should use this object if you want to deploy the package to all sensors with a general operating system type, such as all Windows or all Linux sensors. If you want to deploy the package to sensors running specific Linux operating systems (such as Centos 6), use the osType, osDistribution, and osMajor keys. Note The osType, osDistribution and osMajor keys are not generally available. |
osTypeGroup |
Enum |
The operating system type for the deployment. Enter WINDOWS_TYPES as the value for this key. Ensure you define the most specific OS specification for the tool you want to upload to ensure that the Cybereason platform does not deploy a tool to an endpoint machine that the machine cannot run. |
platform |
Enum |
The type of operating system, such as 64-bit or 32-bit. Enter one of the following values:
You should use this key only if you enter WINDOWS_TYPES for the osTypeGroup parameter. |
osType |
Enum |
The type of operating system to which to deploy the tool. Use one of the following values:
Note This key/parameter is not generally available. |
osDistribution |
Enum |
The type of Linux operating system to which to deploy the tool. Use one or more of the following values:
If you use this key, you must specify a corresponding value in the osMajor key. Note This key/parameter is not generally available. |
osMajor |
Enum |
The version of a specific type of Linux operating system to which to deploy the tool. Use one or more of the following values:
Note This key/parameter is not generally available. |
packageContentType |
Enum |
The type of content you upload. Enter FILE for this field. |
posixPermissions |
Enum |
The permissions for the tool package you upload. If you deploy the package to Windows machines, enter EXECUTE for this field. If you deploy the package to Linux machines, use READWRITEEXECUTE for this value. Note The Linux-specific values for this key/parameter are not generally available. |
packageRunConfiguration |
JSON |
An object containing details on the run configuration for the tool. This object contains the runCommand and outputDir parameters. If you leave this object empty without either parameter, the sensor adds the output for the tool run to the default directory on the endpoint. For example , on Windows machines, the sensor adds the results in the C:/ProgramData/apv2/IRToolsOutput/IRTOOLS.<packageName>/ folder. |
programNameAndArgs |
String |
The program to use to run a custom script or tool. You enter the framework to use, the script/executable file to run, and any command line arguments to use to run the tool or script. For example, you can enter python to run a Python script. Note If you want to run script files as your tool package, Cybereason recommends that you use this programNameAndArgs key. Using this key ensures that the Cybereason platform loads the correct script interpreter instead of a default system shell. |
runCommand |
String |
An appropriate command for the tool when it runs. This command is used as the default run command for tool execution. You can use other commands in a specific tool execution later as needed. See your tool’s documentation for relevant commands that you can use. Note On Linux endpoints, if you require another program to run the tool package, you must specify the full program path for the other application. For example, if you need Python to run the tool, you add the /usr/bin/python path for Python instead of python. |
outputDir |
String |
The folder to which to send the output from the tool’s execution. This folder is the default value for the output directory for tool executions. You can add other output directories in specific tool executions later as needed. |
description |
String |
A description for the tool. |
Response Status Codes
This request can return the following status codes:
202: Package delivery request accepted
400: Bad params
503: Packages delivery service is disabled
Response Success Schema
The response contains a message IR Tool upload request was submitted successfully.
Response Failure Schema
None
Example: Deploy a tool for all Windows endpoints with a C:/collectorOutDir output directory
Request
curl --request POST \
--url https://12.34.56.78/rest/irtools/upload \
--form 'packageName="deploy-example1"' \
--form 'packageInfo=@"/Users/admin/Documents/IRTools/offline_coolector_fast_results.exe"' \
--form 'packageOSInfoList="[{\"osTypeGroup\":\"WINDOWS_TYPES\"}]"' \
--form 'packageContentType="FILE"' \
--form 'posixPermissions="EXECUTE"' \
--form 'packageRunConfiguration="{\"outputDir\": \"C:/collectorOutDir\"}"' \
--form 'description="IR tool - results in C:/collectorOutDir on the endpoint."'
Response
IR Tool upload request was submitted successfully
Request
Response
IR Tool upload request was submitted successfully
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
endpoint_url = "/rest/irtools/upload"
api_url = base_url + endpoint_url
payload={'packageName':'deploy-example1','packageOSInfoList':'[{"osTypeGroup":"WINDOWS_TYPES"}]','packageContentType':'FILE','posixPermissions':'EXECUTE','packageRunConfiguration':'{"outputDir":"C:/collectorOutDir"}','description':'IR tool - results in C:/collectorOutDir on the endpoint.'}
files=[('packageInfo',('offline_collector_fast_results.exe',open('/Users/admin/Documents/IRTools/offline_coolector_fast_results.exe','rb'),'application/octet-stream'))]
api_headers = {}
api_response = requests.request("POST", api_url, headers=api_headers, data=payload, files=files)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
IR Tool upload request was submitted successfully
Example: Deploy a tool for all Windows endpoints with a specific run command
Request
curl --request POST \
--url https://12.34.56.78/rest/irtools/upload \
--form 'packageName="deploy-example2"' \
--form 'packageInfo=@"/Users/admin/Documents/IRTools/offline_coolector_fast_results.exe"' \
--form 'packageOSInfoList="[{\"osTypeGroup\":\"WINDOWS_TYPES\"}]"' \
--form 'packageContentType="FILE"' \
--form 'posixPermissions="EXECUTE"' \
--form 'packageRunConfiguration="{\"runCommand\": \"client -v\"}"' \
--form 'description="IR tool"'
Response
IR Tool upload request was submitted successfully
Request
Response
IR Tool upload request was submitted successfully
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
endpoint_url = "/rest/irtools/upload"
api_url = base_url + endpoint_url
payload={'packageName':'deploy-example2','packageOSInfoList':'[{"osTypeGroup":"WINDOWS_TYPES","platform":"ARCH_AMD64"}]','packageContentType':'FILE','posixPermissions':'EXECUTE','packageRunConfiguration': '{"runCommand": "client -v"}','description': 'VR client'}
files=[('packageInfo',('vr_client_win64.exe',open('/Users/admin/Documents/IRTools/vr_client_win64.exe','rb'),'application/octet-stream'))]
api_headers = {}
api_response = session.request("POST", api_url, headers=api_headers, data=payload, files=files)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
IR Tool upload request was submitted successfully
Example: Upload a tool for 64-bit Windows endpoints with a specific run command
Request
curl --request POST \
--url https://12.34.56.78/rest/irtools/upload \
form 'packageName="deploy-example3"' \
--form 'packageInfo=@"/Users/admin/Documents/IRTools/offline_coolector_fast_results.exe"' \
--form 'packageOSInfoList="[{\"osTypeGroup\":\"WINDOWS_TYPES\",\"platform\": \"ARCH_AMD64\"}]"' \
--form 'packageContentType="FILE"' \
--form 'posixPermissions="EXECUTE"' \
--form 'packageRunConfiguration="{\"runCommand\": \"client -v\"}"' \
--form 'description="IR tool"'
Response
IR Tool upload request was submitted successfully
Request
Response
IR Tool upload request was submitted successfully
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
endpoint_url = "/rest/irtools/upload"
api_url = base_url + endpoint_url
payload={'packageName':'deploy-example2','packageOSInfoList':'[{"osTypeGroup":"WINDOWS_TYPES","platform":"ARCH_AMD64"}]','packageContentType':'FILE','posixPermissions':'EXECUTE','packageRunConfiguration': '{"runCommand": "client -v"}','description': 'VR client'}
files=[('packageInfo',('vr_client_win64.exe',open('/Users/admin/Documents/IRTools/vr_client_win64.exe','rb'),'application/octet-stream'))]
api_headers = {}
api_response = session.request("POST", api_url, headers=api_headers, data=payload, files=files)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
IR Tool upload request was submitted successfully
Example: Upload a tool for 32-bit Windows endpoints with no configuration
Request
curl --request POST \
--url https://12.34.56.78/rest/irtools/upload \
form 'packageName="deploy-example3"' \
--form 'packageInfo=@"/Users/admin/Documents/IRTools/offline_coolector_fast_results.exe"' \
--form 'packageOSInfoList="[{\"osTypeGroup\":\"WINDOWS_TYPES\",\"platform\": \"ARCH_X86\"}]"' \
--form 'packageContentType="FILE"' \
--form 'posixPermissions="EXECUTE"' \
--form 'description="IR tool"'
Response
IR Tool upload request was submitted successfully
Request
Response
IR Tool upload request was submitted successfully
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
endpoint_url = "/rest/irtools/upload"
api_url = base_url + endpoint_url
payload={'packageName': 'deploy-example3','packageOSInfoList':'[{"osTypeGroup":"WINDOWS_TYPES","platform":"ARCH_X86"}]','packageContentType':'FILE','posixPermissions': 'EXECUTE','description': 'IR tool which results will be created default CR directory'}
files=[('packageInfo',('offline_coolector_fast_results.exe',open('/Users/rina.bruter/Documents/IRTools/offline_coolector_fast_results.exe','rb'),'application/octet-stream'))]
api_headers = {}
api_response = requests.request("POST", url, headers=api_headers, data=payload, files=files)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
IR Tool upload request was submitted successfully
Example: Deploy a tool for all Linux endpoints
Request
curl --request POST \
--url https://12.34.56.78/rest/irtools/upload \
--form 'packageName="deploy-example3"' \
--form 'packageName="Linux IR package"' \
--form 'packageInfo=@"/Users/jeremy.brown/Desktop/linux_ir_response"' \
--form 'packageOSInfoList="[{\"osTypeGroup\": \"LINUX_TYPES\"}]"' \
--form 'packageContentType="FILE"' \
--form 'posixPermissions="READWRITEEXECUTE"' \
--form 'packageRunConfiguration="{\"runCommand\": \"testing\",\"outputDir\": \"C:/VR\"}"' \
--form 'description="Linux IR package for all Linux endpoints"'
Response
IR Tool upload request was submitted successfully
Request
Response
IR Tool upload request was submitted successfully
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
endpoint_url = "/rest/irtools/upload"
api_url = base_url + endpoint_url
payload={'packageName':'Linux IR package','packageOSInfoList':'[{"osTypeGroup": "LINUX_TYPES"}]','packageContentType':'FILE','posixPermissions':'READWRITEEXECUTE',
'packageRunConfiguration':'{"runCommand": "testing","outputDir":"C:/VR"}','description':'Linux IR package for all Linux endpoints'}
files=[('packageInfo',('linux_ir_response',open('/Users/jeremy.brown/Desktop/linux_ir_response','rb'),'application/octet-stream'))]
api_headers = {}
api_response = requests.request("POST", url, headers=api_headers, data=payload, files=files)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
IR Tool upload request was submitted successfully
Example: Deploy a tool for all CentOS 7 endpoints
Request
curl --request POST \
--url https://12.34.56.78/rest/irtools/upload \
--form 'packageName="Linux IR package"' \
--form 'packageInfo=@"/Users/jeremy.brown/Desktop/linux_ir_response"' \
--form 'packageOSInfoList="[{\"osType\": \"LINUX\", \"osDistribution\": \"CENTOS\", \"osMajor\": 7}]"' \
--form 'packageContentType="FILE"' \
--form 'posixPermissions="READWRITEEXECUTE"' \
--form 'packageRunConfiguration="{\"runCommand\": \"testing\",\"outputDir\": \"C:/VR\"}"' \
--form 'description="Linux IR package for all Linux endpoints"'
Response
IR Tool upload request was submitted successfully
Request
Response
IR Tool upload request was submitted successfully
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
endpoint_url = "/rest/irtools/upload"
api_url = base_url + endpoint_url
payload={'packageName':'Linux IR package','packageOSInfoList':'[{"osType": "LINUX","osDistribution":"CENTOS","osMajor": 7}]','packageContentType':'FILE',
'posixPermissions':'READWRITEEXECUTE','packageRunConfiguration':'{"runCommand":"testing","outputDir":"C:/VR"}','description':'Linux IR package for all Linux endpoints'}
files=[('packageInfo',('linux_ir_response',open('/Users/jeremy.brown/Desktop/linux_ir_response','rb'),'application/octet-stream'))]
api_headers = {}
response = requests.request("POST", url, headers=api_headers, data=payload, files=files)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
IR Tool upload request was submitted successfully
Example: Deploy a tool for all Oracle Linux 8 and Amazon Linux 2 endpoints
Request
curl --request POST \
--url https://12.34.56.78/rest/irtools/upload \
--form 'packageName="Linux IR package"' \
--form 'packageInfo=@"/Users/jeremy.brown/Desktop/linux_ir_response"' \
--form 'packageOSInfoList="[{\"osType\": \"LINUX\", \"osDistribution\": \"ORACLE\", \"osMajor\": 8},{\"osType\": \"LINUX\", \"osDistribution\": \"AMAZON\", \"osMajor\": 2}]"' \
--form 'packageContentType="FILE"' \
--form 'posixPermissions="READWRITEEXECUTE"' \
--form 'packageRunConfiguration="{\"runCommand\": \"testing\",\"outputDir\": \"C:/VR\"}"' \
--form 'description="Linux IR package for all Linux endpoints"'
Response
IR Tool upload request was submitted successfully
Request
Response
IR Tool upload request was submitted successfully
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
endpoint_url = "/rest/irtools/upload"
api_url = base_url + endpoint_url
payload={'packageName':'Linux IR package','packageOSInfoList':'[{"osType":"LINUX","osDistribution":"ORACLE","osMajor":8},{"osType": "LINUX","osDistribution":"AMAZON","osMajor":2}]','packageContentType':'FILE','posixPermissions': 'READWRITEEXECUTE','packageRunConfiguration':'{"runCommand":"testing","outputDir":"C:/VR"}','description':'Linux IR package for all Linux endpoints'}
files=[('packageInfo',('linux_ir_response',open('/Users/jeremy.brown/Desktop/linux_ir_response','rb'),'application/octet-stream'))]
api_headers = {}
response = requests.request("POST", url, headers=api_headers, data=payload, files=files)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))