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

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.

            {
                "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:

  • 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: 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:

  • 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.


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
}

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
}