Check and Upgrade Sensors

If your organization contains many Sensors, management of these Sensors could be a time-consuming job. You have to maintain, track, and ensure that Sensors have the correct versions and settings, and make sure that the Sensors are functioning properly. The Cybereason API contains an API to help you manage many of these tasks. For example, you can query all Sensors and view details about Sensors, including versions and settings. This topic provides a step by step example of how you can use the API to check Sensor versions and upgrade to the newest version.

In this topic:

Step 1: Plan your request
Step 2: Build your API request
Step 3: Run your request and generate the response
Step 4: Evaluate the response
Step 5: Upgrade the necessary Sensors

Step 1: Plan your request

Before you begin, ask yourself the following questions:

What is the specific Sensor version you want?
How do you want to search for Sensor versions? Do you want to return a list of all Sensors and then parse the version field in the response, or filter for a specific Sensor version? Returning a list of all Sensors for all your Sensors - particularly if you are managing thousands of Sensors - could be a very time consuming process.

Step 2: Build your API request

For the purposes of this example, we will filter by version instead of returning all Sensors. We will search for Sensors running Sensor version 17.5.0.

To construct the request, you will need to provide the following values:

The limit parameter. An integer value that instructs the server how many Sensors to include in the response.
The offset parameter. An integer value. Set this value to 0 for this case.
The sortDirection parameter. This enum value tells the Sensor to return the values in ascending ASC or descending DESC order.
The filter object. This parameter is an array which includes other fields. In this example, we will use the version field in the filter object.

Add the information for these parameters and create the relevant cURL command, request body example, or Python script. In this example, we are using a stand-in address for a Cybereason server (myserver.com). If you use this request, replace this address with your actual server address.

All Python examples are formatted for Python version 3.0 and higher, up to the latest Python version. If you are using versions of Python earlier than 3.0, ensure you manually remove parentheses for the print statements in this sample. For example, the print (response.content) statement updates to print response.content.

Request

curl --request POST \
  --url https://myserver.com/rest/sensors/query \
  --header 'Content-Type: application/json' \
  --data '{
            "mode": "raw",
            "raw":"{\"limit\":1000,\"offset\":0, \"filters\":[{\"fieldName\":\"version\",\"operator\":\"Equals\",\"values\":[\"17.5.0\"]}]}"
          }'

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.

Use this request body:

{
                "limit": 1000,
                "offset": 0,
                "filters": [
                  {
                    "fieldName": "version",
                    "operator": "Equals",
                    "values": [
                      "17.5.0"
                    ]
                  }
                ]
            }

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.

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/query"

api_url = base_url + endpoint_url

# These are the variables that represent different fields in the request.

sensor_filter_1 = "version"
sensor_filter_1_value = "17.5.0"

query = json.dumps({"limit": 1000,"offset":0,"filters": [{"fieldName":sensor_filter_1,"operator":"Equals","values":[sensor_filter_1_value]}]})

api_headers = {'Content-Type':'application/json'}

api_response = session.request("POST", api_url, data=query, headers=api_headers)

your_response = json.loads(api_response.content)

print(json.dumps(your_response, indent=4, sort_keys=True))

Step 3: Run your request and generate the response

In the command line, REST API client, or IDE, run the command or script that contains the request. After a few seconds, the Cybereason API returns a response.

Step 4: Evaluate the response

When your Server searches connected Sensors, it will return details on all Sensors that meet the filters. This response contains a separate entry for each Sensor, including details for that specific Sensor’s settings. Note the version parameter in the JSON schema above.

In addition, the response returns a summary, including the totalResults parameter and sensorsStatus object. These give details on how many Sensors are contained in the response.

In our example, the platform response includes the following fields:

{
  "sensors": [
    {
      "sensorId": "5ad31a2ce4b0e623bab9b9ae:PYLUMCLIENT_DEMO_DEMO1WIN7X64_005056AAA5F2",
      "pylumId": "PYLUMCLIENT_DEMO_DEMO1WIN7X64_005056AAA5F2",
      "guid": "-1869914237.1198775089551518743",
      "fqdn": "demo1win7x64",
      "machineName": "DEMO1WIN7X64",
      "internalIpAddress": "1.1.1.1",
      "externalIpAddress": "11.1.11.11",
      "siteName": null,
      "siteId": null,
      "ransomwareStatus": "DISABLED",
      "preventionStatus": "NOT_INSTALLED",
      "isolated": false,
      "disconnectionTime": 1523872923530,
      "lastPylumInfoMsgUpdateTime": 1523873136274,
      "status": "Online",
      "onlineTimeMS": 1523872959216,
      "offlineTimeMS": 1523872924216,
      "staleTimeMS": 0,
      "archiveTimeMs": 0,
      "statusTimeMS": 1523872959216,
      "lastStatusAction": "None",
      "archivedOrUnarchiveComment": "",
      "sensorArchivedByUser": "",
      "serverName": "123.456.789.012",
      "serverId": "5ad31a2ce4b0e623bab9b9ae",
      "osType": "WINDOWS",
      "osVersionType": "Windows_7",
      "collectionStatus": "ENABLED",
      "version": "17.5.0",
      "firstSeenTime": 1523872390812,
      "upTime": 184928,
      "cpuUsage": 0.016614608,
      "memoryUsage": 47464448,
      "outdated": false,
      "amStatus": "AM_UNINSTALLED",
      "powerShellStatus": "PS_DISABLED",
      "antiMalwareStatus": "AM_DISABLED",
      "organization": "demo",
      "proxyAddress": null,
      "preventionError": null,
      "exitReason": "STOP_REQUEST_FROM_PYLUM",
      "actionsInProgress": 0,
      "pendingActions": null,
      "lastUpgradeResult": null,
      "lastUpgradeSteps": null,
      "disconnected": false,
      "sensorLastUpdate": 1523873139215,
      "fullScanStatus": "UNKNOWN",
      "quickScanStatus": "UNKNOWN",
      "lastFullScheduleScanSuccessTime": 0,
      "lastQuickScheduleScanSuccessTime": 0
    }
  ],
  "totalResults": 1040,
  "hasMoreResults": false,
  "sensorsStatus": {
    "onlineCount": 1000,
    "offlineCount": 7,
    "staleCount": 3,
    "archivedCount": 30
  }
}

Step 5: Upgrade the necessary Sensors

Now that you know how many Sensors and what Sensors you need to upgrade, create a new request send to the Sensor API Upgrade endpoint.

Add the information for these parameters and create the relevant cURL command, request body example, or Python script. In this example, we are using a stand-in address for a Cybereason server (myserver.com). If you use this request, replace this address with your actual server address.

curl --request POST \
  --url https://myserver.com/rest/sensors/action/upgradeToLatest \
  --header 'Content-Type: application/json' \
  --data '{
            "mode": "raw",
            "raw":"{ \"filters\":[{\"fieldName\":\"version\",\"operator\":\"Equals\",\"values\":[\"17.5.0\"]}]}"
          }'

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.

Use this request body:

{
                "filters": [
                  {
                    "fieldName": "version",
                    "operator": "Equals",
                    "values": [
                      "17.5.0"
                    ]
                  }
                ]
            }

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.

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())

query = '{\"filters\": [{\"fieldName\": \"version\",\"operator\": \"Equals\",\"values\": [\"17.5.0"]}]}'

# Request URL

endpoint_url = "rest/sensors/action/upgradeToLatest"

api_url = base_url + endpoint_url

# These are the variables that represent different fields in the request.

sensor_filter = "version"
sensor_filter_value = "17.5.0"

query = json.dumps({"filters":[{"fieldName":sensor_filter,"operator":"Equals","values": [sensor_filter_value]}]})

api_headers = {'Content-Type':'application/json'}

api_response = session.request("POST", api_url, data=query, headers=api_headers)

your_response = json.loads(api_response.content)

print(json.dumps(your_response, indent=4, sort_keys=True))

This request does not include the limit and offset parameters included in the Sensor query request.

Once you have sent this request, your Sensors should be automatically upgraded, and you can see the progress of this action in the System > Sensors screen of the Cybereason UI.