Set Application Control Mode
Endpoint URL: https://<your server>/rest/sensors/action/setPreventionMode
Endpoint URI: senors/action/setPreventionMode
Action: POST
Specifies an Application Control mode for all Sensors or a group of filtered Sensors.
You must be assigned the System Admin role and Sensor Admin L1 role (if your Cybereason environment uses sensor grouping) to send requests to this endpoint URL.
Note
Ensure that you have logged into the Cybereason platform. For details, see Log in with the API.
Request Headers
You must add an 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.
{
"sensorsIds": [
"<sensorID>"
],
"filters": [
"<filter values>"
],
"argument": "<arguments>"
}
Request Parameters
URL/URI parameters: none
Request Body Parameters: You must add the REQUIRED argument parameter. Possible values include:
DISABLE
ENABLE
You can use any of the following optional parameters in the filters object:
Note
If you add a parameter in the filters object, ensure you use this 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: Success OK
204: Means that the sensor names are incorrect or the filters are not valid
400 Bad Request: An error message with NO_MATCHING_SENSORS message
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. |
Important Response Fields
Important information is found in these fields:
batchID: The operation identifier for the sensor operation.
actionType: The type of sensor operation. For this request to change the Application Control mode, this should report EnablePrevention.
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.
Response Failure Schema
400 - Bad Request. NO_MATCHING_SENSORS found.
Example: Enable Application Control on all sensors
Request
curl --request POST \
--url https://12.34.56.78/rest/sensors/action/setPreventionMode \
--header 'Content-Type: application/json' \
--data '{
"filters":[],
"argument":"UNINSTALL"
}'
**Response**
{
"batchId": 1248943887,
"actionType": "EnablePrevention",
"actionArguments": null,
"globalStats": {
"stats": {
"FailedSending": 0,
"InvalidState": 0,
"ProbeRemoved": 0,
"TimeoutSending": 0,
"Pending": 0,
"ChunksRequired": 0,
"MsiFileCorrupted": 0,
"SendingMsi": 0,
"NewerInstalled": 0,
"MsiSendFail": 0,
"partialResponse": 0,
"EndedWithSensorTimeout": 0,
"FailedSendingToServer": 0,
"GettingChunks": 0,
"Aborted": 0,
"Started": 0,
"InProgress": 0,
"Disconnected": 0,
"Failed": 0,
"Timeout": 0,
"EndedWithTooManyResults": 0,
"AlreadyUpdated": 0,
"EndedWithTooManySearches": 0,
"Succeeded": 0,
"NotSupported": 0,
"EndedWithUnknownError": 0,
"None": 1,
"Primed": 0,
"EndedWithInvalidParam": 0,
"UnknownProbe": 0,
"AbortTimeout": 0,
"UnauthorizedUser": 0
}
},
"finalState": false,
"totalNumberOfProbes": 1,
"initiatorUser": "[email protected]",
"startTime": 1523874385590,
"aborterUser": null,
"abortTime": 0,
"abortTimeout": false,
"abortHttpStatusCode": null
}
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:
{
"filters": [],
"argument": "UNINSTALL"
}
Response
{
"batchId": 1248943887,
"actionType": "EnablePrevention",
"actionArguments": null,
"globalStats": {
"stats": {
"FailedSending": 0,
"InvalidState": 0,
"ProbeRemoved": 0,
"TimeoutSending": 0,
"Pending": 0,
"ChunksRequired": 0,
"MsiFileCorrupted": 0,
"SendingMsi": 0,
"NewerInstalled": 0,
"MsiSendFail": 0,
"partialResponse": 0,
"EndedWithSensorTimeout": 0,
"FailedSendingToServer": 0,
"GettingChunks": 0,
"Aborted": 0,
"Started": 0,
"InProgress": 0,
"Disconnected": 0,
"Failed": 0,
"Timeout": 0,
"EndedWithTooManyResults": 0,
"AlreadyUpdated": 0,
"EndedWithTooManySearches": 0,
"Succeeded": 0,
"NotSupported": 0,
"EndedWithUnknownError": 0,
"None": 1,
"Primed": 0,
"EndedWithInvalidParam": 0,
"UnknownProbe": 0,
"AbortTimeout": 0,
"UnauthorizedUser": 0
}
},
"finalState": false,
"totalNumberOfProbes": 1,
"initiatorUser": "[email protected]",
"startTime": 1523874385590,
"aborterUser": null,
"abortTime": 0,
"abortTimeout": false,
"abortHttpStatusCode": null
}
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.
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())
# Request URL
endpoint_url = "/rest/sensors/action/setPreventionMode"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
appcontrol_mode = "UNINSTALL"
mode = json.dumps({"filters":[],"argument":appcontrol_mode})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=mode, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
{ "batchId": 1248943887, "actionType": "EnablePrevention", "actionArguments": null, "globalStats": { "stats": { "FailedSending": 0, "InvalidState": 0, "ProbeRemoved": 0, "TimeoutSending": 0, "Pending": 0, "ChunksRequired": 0, "MsiFileCorrupted": 0, "SendingMsi": 0, "NewerInstalled": 0, "MsiSendFail": 0, "partialResponse": 0, "EndedWithSensorTimeout": 0, "FailedSendingToServer": 0, "GettingChunks": 0, "Aborted": 0, "Started": 0, "InProgress": 0, "Disconnected": 0, "Failed": 0, "Timeout": 0, "EndedWithTooManyResults": 0, "AlreadyUpdated": 0, "EndedWithTooManySearches": 0, "Succeeded": 0, "NotSupported": 0, "EndedWithUnknownError": 0, "None": 1, "Primed": 0, "EndedWithInvalidParam": 0, "UnknownProbe": 0, "AbortTimeout": 0, "UnauthorizedUser": 0 } }, "finalState": false, "totalNumberOfProbes": 1, "initiatorUser": "[email protected]", "startTime": 1523874385590, "aborterUser": null, "abortTime": 0, "abortTimeout": false, "abortHttpStatusCode": null }
Example: Enable Application Control on a specific sensor
Request
curl --request POST \
--url https://12.34.56.78/rest/sensors/action/setPreventionMode \
--header 'Content-Type: application/json' \
--data '{
"SensorsIds": ["593aef75e4b0a3eacaf3a185:PYLUMCLIENT_INTERNAL_CYBERSETUP7X64_005056A16DBC”],
"argument": "ENABLE"
}'
**Response**
{
"batchId": 1248943887,
"actionType": "EnablePrevention",
"actionArguments": null,
"globalStats": {
"stats": {
"FailedSending": 0,
"InvalidState": 0,
"ProbeRemoved": 0,
"TimeoutSending": 0,
"Pending": 0,
"ChunksRequired": 0,
"MsiFileCorrupted": 0,
"SendingMsi": 0,
"NewerInstalled": 0,
"MsiSendFail": 0,
"partialResponse": 0,
"EndedWithSensorTimeout": 0,
"FailedSendingToServer": 0,
"GettingChunks": 0,
"Aborted": 0,
"Started": 0,
"InProgress": 0,
"Disconnected": 0,
"Failed": 0,
"Timeout": 0,
"EndedWithTooManyResults": 0,
"AlreadyUpdated": 0,
"EndedWithTooManySearches": 0,
"Succeeded": 0,
"NotSupported": 0,
"EndedWithUnknownError": 0,
"None": 1,
"Primed": 0,
"EndedWithInvalidParam": 0,
"UnknownProbe": 0,
"AbortTimeout": 0,
"UnauthorizedUser": 0
}
},
"finalState": false,
"totalNumberOfProbes": 1,
"initiatorUser": "[email protected]",
"startTime": 1523874385590,
"aborterUser": null,
"abortTime": 0,
"abortTimeout": false,
"abortHttpStatusCode": null
}
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:
{
"sensorsIds": [
"593aef75e4b0a3eacaf3a185:PYLUMCLIENT_INTERNAL_CYBERSETUP7X64_005056A16DBC"
],
"argument": "ENABLE"
}
Response
{
"batchId": 1248943887,
"actionType": "EnablePrevention",
"actionArguments": null,
"globalStats": {
"stats": {
"FailedSending": 0,
"InvalidState": 0,
"ProbeRemoved": 0,
"TimeoutSending": 0,
"Pending": 0,
"ChunksRequired": 0,
"MsiFileCorrupted": 0,
"SendingMsi": 0,
"NewerInstalled": 0,
"MsiSendFail": 0,
"partialResponse": 0,
"EndedWithSensorTimeout": 0,
"FailedSendingToServer": 0,
"GettingChunks": 0,
"Aborted": 0,
"Started": 0,
"InProgress": 0,
"Disconnected": 0,
"Failed": 0,
"Timeout": 0,
"EndedWithTooManyResults": 0,
"AlreadyUpdated": 0,
"EndedWithTooManySearches": 0,
"Succeeded": 0,
"NotSupported": 0,
"EndedWithUnknownError": 0,
"None": 1,
"Primed": 0,
"EndedWithInvalidParam": 0,
"UnknownProbe": 0,
"AbortTimeout": 0,
"UnauthorizedUser": 0
}
},
"finalState": false,
"totalNumberOfProbes": 1,
"initiatorUser": "[email protected]",
"startTime": 1523874385590,
"aborterUser": null,
"abortTime": 0,
"abortTimeout": false,
"abortHttpStatusCode": null
}
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.
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())
# Request URL
endpoint_url = "/rest/sensors/action/setPreventionMode"
api_url = base_url + endpoint_url
# These are the variables that represent different fields in the request.
sensor_id = "58ae74fae4b06dca39c1d4bc:PYLUMCLIENT_INTERNAL_WIN7-64B-DEMO_0050568A3C55"
appcontroL_mode = "ENABLE"
mode = json.dumps({"sensorsIds":[sensor_id],"argument":appcontroL_mode})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=mode, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))s
Response
{ "batchId": 1248943887, "actionType": "EnablePrevention", "actionArguments": null, "globalStats": { "stats": { "FailedSending": 0, "InvalidState": 0, "ProbeRemoved": 0, "TimeoutSending": 0, "Pending": 0, "ChunksRequired": 0, "MsiFileCorrupted": 0, "SendingMsi": 0, "NewerInstalled": 0, "MsiSendFail": 0, "partialResponse": 0, "EndedWithSensorTimeout": 0, "FailedSendingToServer": 0, "GettingChunks": 0, "Aborted": 0, "Started": 0, "InProgress": 0, "Disconnected": 0, "Failed": 0, "Timeout": 0, "EndedWithTooManyResults": 0, "AlreadyUpdated": 0, "EndedWithTooManySearches": 0, "Succeeded": 0, "NotSupported": 0, "EndedWithUnknownError": 0, "None": 1, "Primed": 0, "EndedWithInvalidParam": 0, "UnknownProbe": 0, "AbortTimeout": 0, "UnauthorizedUser": 0 } }, "finalState": false, "totalNumberOfProbes": 1, "initiatorUser": "[email protected]", "startTime": 1523874385590, "aborterUser": null, "abortTime": 0, "abortTimeout": false, "abortHttpStatusCode": null }