Devices API

Introduction

We have extended the capabilities of the Devices API by improving the methods of retrieving device information and added functionality to perform actions. You can now more efficiently call an API with a wider range of filterable fields, including policy ID, status, operating system and more. You can also perform actions on individual devices such as quarantine/unquarantine, enable or disable bypass, or upgrade to a new sensor version.

Search Devices

Search devices in your organization.

RBAC Permissions Required

Permission (.notation name) Operation(s)
device READ

Request

POST <psc-hostname>/appservices/v6/orgs/{org_key}/devices/_search

Request Body

{
  "criteria": {
		"status": ["REGISTERED"],
		"policy_id": [43421, 1],
		"target_priority": ["LOW"]
	},
  "rows": 5,
  "start": 0,
  "query": "foo bar",
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ]
}

Body Schema

Field Description Default Required
criteria Map of criteria to filter results on. Allowed values: status, os, last_contact_time, ad_group_id, policy_id, id, target_priority N/A No
rows Maximum number of rows to return 20 No
start What row to begin returning results from 0 No
query Lucene search query Empty No
sort.field Sort Fields. Allowed values: target_priority, policy_name, name, last_contact_time, av_pack_version N/A No
sort.order Sort Order for field. Allowed values: ASC, DESC N/A No
exclusions A list of sensor versions to exclude from the request results N/A No

Response

Code Description Content-Type Content
200 Successful Search Request application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-prod05/appservices/v6/orgs/ASDF12A/devices/_search

Request Body

{
    "criteria": {
        "status": ["REGISTERED"],
        "policy_id": [986390, 453213],
        "target_priority": ["MISSION_CRITICAL"]
      },
    "sort": [
      {
        "field": "av_pack_version",
        "order": "ASC"
      }
    ],
    "rows": 5,
    "start": 0
}

Response

{
    "results": [
        {
            "activation_code": "UW91HU",
            "activation_code_expiry_time": "2019-04-01T21:55:37.843Z",
            "ad_group_id": 0,
            "av_ave_version": "8.3.54.36",
            "av_engine": "4.9.0.264-ave.8.3.54.36:avpack.8.5.0.6:vdf.8.16.15.190:apc.2.10.0.66",
            "av_last_scan_time": null,
            "av_master": false,
            "av_pack_version": "8.5.0.6",
            "av_product_version": "4.9.0.264",
            "av_status": ["AV_ACTIVE", "ONDEMAND_SCAN_DISABLED"],
            "av_update_servers": null,
            "av_vdf_version": "8.16.15.190",
            "current_sensor_policy_name": "default",
            "deregistered_time": null,
            "device_id": 894090,
            "device_meta_data_item_list": [
                {
                    "key_name": "OS_MAJOR_VERSION",
                    "key_value": "Windows",
                    "position": 0
                },
                {
                    "key_name": "SUBNET",
                    "key_value": "192.168.216",
                    "position": 0
                }
            ],
            "device_owner_id": 813393,
            "device_type": "WINDOWS",
            "email": "QALAB\\dev-win",
            "encoded_activation_code": "56312132131312313123",
            "first_name": null,
            "last_contact_time": "2019-07-02T14:52:05.837Z",
            "last_device_policy_changed_time": "2019-07-16T00:38:48.096Z",
            "last_device_policy_requested_time": "2019-07-02T09:09:27.824Z",
            "last_external_ip_address": "104.207.192.98",
            "last_internal_ip_address": "192.168.216.135",
            "last_location": "OFFSITE",
            "last_name": null,
            "last_policy_updated_time": "2019-03-21T13:11:28.557Z",
            "last_reported_time": "2019-07-02T09:09:53.803Z",
            "last_reset_time": null,
            "last_shutdown_time": null,
            "linux_kernel_version": null,
            "login_user_name": null,
            "mac_address": "000000000000",
            "middle_name": null,
            "name": "dev-win81",
            "organization_id": 1,
            "organization_name": "confer.net",
            "os_version": "Windows 8.1 x64",
            "passive_mode": false,
            "policy_id": 986390,
            "policy_name": "test1",
            "policy_override": false,
            "quarantined": false,
            "registered_time": "2019-01-23T20:06:18.049Z",
            "rooted_by_analytics": false,
            "rooted_by_analytics_time": null,
            "rooted_by_sensor": false,
            "scan_last_action_time": null,
            "scan_last_complete_time": null,
            "scan_status": null,
            "sensor_out_of_date": false,
            "sensor_states": ["ACTIVE", "LIVE_RESPONSE_NOT_RUNNING", "LIVE_RESPONSE_NOT_KILLED", "LIVE_RESPONSE_ENABLED"],
            "sensor_version": "3.4.0.820",
            "status": "REGISTERED",
            "target_priority_type": "LOW",
            "uninstall_code": "J8SY4KED",
            "vdi_base_device": null,
            "virtual_machine": false,
            "virtualization_provider": "UNKNOWN",
            "windows_platform": null
        }
    ],
    "num_found": 4
}

Export Devices (CSV)

RBAC Permissions Required

Permission (.notation name) Operation(s)
device READ

Request

GET <psc-hostname>/appservices/v6/orgs/{org_key}/devices/_search/download

Parameters

Field Description Default Required
status Device statuses to match. Allowed values: PENDING, REGISTERED, UNINSTALLED, DEREGISTERED, ACTIVE, INACTIVE, ERROR, ALL, BYPASS_ON, BYPASS, QUARANTINE, SENSOR_OUTOFDATE, DELETED, LIVE N/A Yes
ad_group_id Active Directory group IDs to match N/A No
policy_id Carbon Black Cloud Policy IDs to match All Policy IDs No
query_string Device query string N/A No
target_priority Device target priorities to match. Allowed values: LOW, MEDIUM, HIGH, MISSION_CRITICAL N/A No
sort_field Field to sort results by N/A No
sort_order Sort order. Allowed values:ASC, DESC N/A No

Response

Code Description Content-Type Content
200 Successful Request application/csv View example response below
400 Invalid request N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-prod05/appservices/v6/orgs/ASDF12A/devices/_search/download?status=active

Response

name,email,firstName,lastName,middleName,targetValue,status,registeredTime,deregisteredTime,lastContactTime,lastInternalIpAddress,lastExternalIpAddress,deviceType,policyName,windowsPlatform,osVersion,sensorVersion,avEngine,virtualMachine,virtualizationProvider,macAddress,groupName
"bsmith-sles","","","","",MISSION_CRITICAL,REGISTERED,2019-04-05-180040,"",2019-06-29-044603,"",97.120.23.84,LINUX,"default","",SLES 12 SP3,2.3.0.124,"",false,"","",""
"

Specific Device Information

RBAC Permissions Required

Permission (.notation name) Operation(s)
device READ

Request

GET <psc-hostname>/appservices/v6/orgs/{org_key}/devices/{device_id}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Invalid request N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-prod05/appservices/v6/orgs/ASDF12A/devices/1515068

Response

{
    "activation_code": null,
    "activation_code_expiry_time": null,
    "ad_group_id": 0,
    "av_ave_version": null,
    "av_engine": "",
    "av_last_scan_time": null,
    "av_master": false,
    "av_pack_version": null,
    "av_product_version": null,
    "av_status": null,
    "av_update_servers": null,
    "av_vdf_version": null,
    "current_sensor_policy_name": "default",
    "deregistered_time": null,
    "device_id": 1515068,
    "device_meta_data_item_list": [],
    "device_owner_id": 0,
    "device_type": "LINUX",
    "email": null,
    "first_name": null,
    "last_contact_time": "2019-07-25T01:53:14.132Z",
    "last_device_policy_changed_time": null,
    "last_device_policy_requested_time": null,
    "last_external_ip_address": "144.121.3.50",
    "last_internal_ip_address": null,
    "last_location": "UNKNOWN",
    "last_name": null,
    "last_policy_updated_time": null,
    "last_reported_time": "2019-07-25T01:52:27.655Z",
    "last_reset_time": null,
    "last_shutdown_time": null,
    "linux_kernel_version": null,
    "login_user_name": null,
    "mac_address": null,
    "middle_name": null,
    "name": "ar-opensuse15",
    "organization_id": 1,
    "organization_name": "confer.net",
    "os_version": "OpenSUSE Leap 15.1",
    "passive_mode": false,
    "policy_id": 1,
    "policy_name": "default",
    "policy_override": false,
    "quarantined": false,
    "registered_time": "2019-06-04T16:04:58.981Z",
    "rooted_by_analytics": false,
    "rooted_by_analytics_time": null,
    "rooted_by_sensor": false,
    "scan_last_action_time": null,
    "scan_last_complete_time": null,
    "scan_status": null,
    "sensor_out_of_date": false,
    "sensor_states": ["LIVE_RESPONSE_NOT_KILLED", "LIVE_RESPONSE_ENABLED", "ACTIVE"],
    "sensor_version": "2.5.0.240",
    "status": "REGISTERED",
    "target_priority_type": "MISSION_CRITICAL",
    "uninstall_code": "RHIAY5AM",
    "vdi_base_device": null,
    "virtual_machine": false,
    "virtualization_provider": null,
    "windows_platform": null
}

Device Actions

RBAC Permissions Required

Permission (.notation name) Operation(s) Action Type
device.quarantine EXECUTE QUARANTINE
device.bypass EXECUTE BYPASS
device.bg-scan EXECUTE BACKGROUND_SCAN
device.policy UPDATE UPDATE_POLICY
org.kits EXECUTE UPDATE_SENSOR_VERSION
device.deregistered DELETE DEREGISTER_SENSOR
device.uninstall EXECUTE DELETE_SENSOR

The device actions endpoint allows you to create and execute an action on devices.

  • API request is common for all device actions.
  • POST request body will change for each device action.

Common Request

POST <psc-hostname>/appservices/v6/orgs/{org_key}/device_actions

Request Body Schema

Field Description Default Required
action_type Action to perform on selected devices. Allowed values: BACKGROUND_SCAN, BYPASS, DELETE_SENSOR, DEREGISTER_SENSOR, QUARANTINE, UPDATE_POLICY, UPDATE_SENSOR_VERSION N/A Yes
device_id List of devices to perform action on N/A Yes - either device_id or search
search A device search. Device actions will be performed on the result set of this search N/A Yes - either device_id or search
options.policy_id Devices will be updated to this policy ID N/A Required if action_type is set to UPDATE_POLICY
options.sensor_version Devices will be updated to this sensor version N/A Required if action_type is set to UPDATE_SENSOR_VERSION
options.toggle Determines whether to toggle action ON or OFF. Allowed values: ON, OFF N/A Required if action_type is set to QUARANTINE, BYPASS, or BACKGROUND_SCAN.

Common Responses

Code Description Content-Type Content
200 Successful Request application/json View example response below
204 Successful device action creation application/json View example response below
400 Invalid request N/A N/A
500 Internal Server Error N/A N/A

Background Scan

Request

POST https://defense-prod05/appservices/v6/orgs/ASDF12A/device_actions

Request Body

{
    "action_type": "BACKGROUND_SCAN",
    "device_id": ["12312"],
    "options": {
        "toggle": "ON"
    }
}
Response

Response Code: 204

Bypass

Request

POST https://defense-prod05/appservices/v6/orgs/ASDF12A/device_actions

Request Body

{
    "action_type": "BYPASS",
    "device_id": ["12131", "12132"],
    "options": {
        "toggle": "OFF"
    }
}

Response

Response Code: 204

Delete Sensor

This request will only work on devices in states deregistered and uninstalled.

Request

POST https://defense-prod05/appservices/v6/orgs/ASDF12A/device_actions

Request Body

{
    "action_type": "DELETE_SENSOR",
    "device_id": ["12131", "12132"]
}

Response

Response Code: 204

De-register Sensor

Request

POST https://defense-prod05/appservices/v6/orgs/ASDF12A/device_actions

Request Body

{
    "action_type": "DEREGISTER_SENSOR",
    "device_id": ["12131", "12132"]
}

Response

Response Code: 204

Quarantine

Request

POST https://defense-prod05/appservices/v6/orgs/ASDF12A/device_actions

Request Body

{
    "action_type": "QUARANTINE",
    "device_id": ["12131", "12132"],
    "options": {
        "toggle": "ON"
    }
}

Response

Response Code: 204

Update Policy

Request

POST https://defense-prod05/appservices/v6/orgs/ASDF12A/device_actions

Request Body

{
    "action_type": "UPDATE_POLICY",
    "device_id": ["1777009"],
    "options": {
        "policy_id": "12436"
    }
}

Response

Response Code: 204

Update Sensor Version

Request

POST https://defense-prod05/appservices/v6/orgs/ASDF12A/device_actions

Request Body

{
    "action_type": "UPDATE_SENSOR_VERSION",
    "device_id": ["1777009"],
    "options": {
        "sensor_version": {
            "RHEL": "2.4.0.3"
        }
    }
}

Response

Response Code: 204

Last modified on September 17, 2019