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.

Authentication

Use the following information for authentication, and see the Carbon Black Cloud Authentication Guide for full instructions.

  • Access Level: Before you create your API Key, you need to create a custom Access Level
    • for the category Device > General Information > “device” allow permissions for “READ”
    • for the category Device > Policy assignment > “device.policy” allow permissions for “UPDATE”
    • for the category Device > Background scan > “device.bg-scan” allow permissions for “EXECUTE”
    • for the category Device > Bypass > “device.bypass” allow permissions for “EXECUTE”
    • for the category Device > Quarantine > “device.quarantine” allow permissions for “EXECUTE”
    • for the category Device > Sensor kits > “org.kits” allow permissions for “EXECUTE”
    • for the category Device > Uninstall > “device.uninstall” allow permissions for “EXECUTE”
    • for the category Device > Deregistered > “device.deregistered” allow permissions for “DELETE”
  • API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL).
  • API Route: /appservices/v6/orgs/{org_key}/devices/_search Note: when you insert your org_key, you must also remove the { } brackets.

Search Devices

Search devices in your organization.

RBAC Permissions Required

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

Request

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/devices/_search

Request Body

{
    "criteria": {
      "status": [ "<string>", "<string>" ],
      "os": [ "<string>", "<string>" ],
      "last_contact_time": {
        "end": "<dateTime>",
        "range": "<string>",
        "start": "<dateTime>"
      },
      "ad_group_id": [ "<long>", "<long>" ],
      "policy_id": [ "<long>", "<long>" ],
      "id": [ "<long>", "<long>" ],
      "target_priority": [ "<string>", "<string>" ],
      "deployment_type": [ "<string>", "<string>" ],
      "vm_uuid": [ "<string>", "<string>" ],
      "vcenter_uuid": [ "<string>", "<string>" ]
    },
    "exclusions": {
      "sensor_version": [
        "<string>"
      ]
    },
    "query": "<string>",
    "sort": [
      {
        "field": "<string>",
        "order": "<string>"
      }
    ],
    "rows": "<long>",
    "start": "<long>"
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object
{
  "os": [
    "WINDOWS"
  ]
}
Supported fields: status, os, last_contact_time, ad_group_id, policy_id, id, target_priority, deployment_type, vm_uuid, vcenter_uuid
exclusions Exclusions is a map that represents values that must not be in the results. Object
{
  "sensor_version": [
    "windows:1.0.0"
  ]
}
Supported Fields: sensor_version

sensor_verion format os:#.#.#.#
query Query in lucene syntax and/or including value searches. String N/A
rows Maximum number of rows to return Integer Default: 20
start What row to begin returning results from Integer Default: 0

Rows + Start can not exceed 10k
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array
[{
  "field": "last_contact_time",
  "order": "asc"
}]
order supports asc or desc

Supported Fields: target_priority, policy_name, name, last_contact_time, av_pack_version, login_user_name, os_version, sensor_version, vm_name, esx_host_name, cluster_name, vm_ip, vulnerability_severity, vulnerability_score

Device APIs support filtering via the last_contact_time field in the criteria object. These time criteria filters can use either the range field or the start and end fields.

  • range can be either all (to indicate all time), or a specific duration specified as -[quantity][unit], where unit is one of:
    • s for seconds
    • m for minutes
    • h for hours
    • d for days
    • w for weeks
    • y for years
  • start and end are specified as ISO-8601 strings. start must be less than end.

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.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_search

Request Body

{
	"criteria": {
        "deployment_type": ["WORKLOAD"],
        "target_priority": ["MEDIUM"],
        "last_contact_time": {
            "start": "2021-01-27T12:43:26.243Z",
            "end": "2021-01-28T12:43:26.243Z"
        }
    },
	"rows": 5,
	"start": 0,
	"sort": [
		{
			"field": "av_pack_version",
			"order": "ASC"
		}
	]
}

Response

{
    "results": [
        {
            "activation_code": null,
            "activation_code_expiry_time": "2017-09-21T15:44:34.757Z",
            "ad_group_id": 1706,
            "appliance_name": null,
            "appliance_uuid": null,
            "av_ave_version": "8.3.62.126",
            "av_engine": "4.13.0.207-ave.8.3.62.126:avpack.8.5.0.92:vdf.8.18.22.172",
            "av_last_scan_time": null,
            "av_master": false,
            "av_pack_version": "8.5.0.92",
            "av_product_version": "4.13.0.207",
            "av_status": [
                "AV_DEREGISTERED"
            ],
            "av_update_servers": null,
            "av_vdf_version": "8.18.22.172",
            "cluster_name": null,
            "current_sensor_policy_name": "default",
            "datacenter_name": null,
            "deployment_type": "WORKLOAD",
            "deregistered_time": "2021-01-28T12:44:25.553Z",
            "device_meta_data_item_list": [
                {
                    "key_name": "SUBNET",
                    "key_value": "10.126.6",
                    "position": 0
                },
                {
                    "key_name": "OS_MAJOR_VERSION",
                    "key_value": "Windows 10",
                    "position": 0
                }
            ],
            "device_owner_id": 70963,
            "email": "Administrator",
            "esx_host_name": null,
            "esx_host_uuid": null,
            "first_name": null,
            "id": 354648,
            "last_contact_time": "2021-01-28T12:43:26.243Z",
            "last_device_policy_changed_time": null,
            "last_device_policy_requested_time": "2021-01-26T17:44:53.274Z",
            "last_external_ip_address": "66.170.99.2",
            "last_internal_ip_address": "10.126.6.201",
            "last_location": "OFFSITE",
            "last_name": null,
            "last_policy_updated_time": "2020-10-22T20:47:17.097Z",
            "last_reported_time": "2021-01-28T19:59:41.537Z",
            "last_reset_time": null,
            "last_shutdown_time": null,
            "linux_kernel_version": null,
            "login_user_name": "WIN-2016-BM\\Administrator",
            "mac_address": "000000000000",
            "middle_name": null,
            "name": "WIN-2016-BM",
            "organization_id": 428,
            "organization_name": "cb-internal-partnersolutions.org",
            "os": "WINDOWS",
            "os_version": "Windows Server 2019 x64",
            "passive_mode": false,
            "policy_id": 2198,
            "policy_name": "default",
            "policy_override": false,
            "quarantined": false,
            "registered_time": "2021-01-26T16:58:56.346Z",
            "scan_last_action_time": null,
            "scan_last_complete_time": null,
            "scan_status": null,
            "sensor_kit_type": "WINDOWS",
            "sensor_out_of_date": false,
            "sensor_pending_update": false,
            "sensor_states": [
                "ACTIVE",
                "LIVE_RESPONSE_NOT_RUNNING",
                "LIVE_RESPONSE_NOT_KILLED",
                "LIVE_RESPONSE_ENABLED"
            ],
            "sensor_version": "3.7.0.503",
            "status": "DEREGISTERED",
            "target_priority": "MEDIUM",
            "uninstall_code": "6EAAJU4R",
            "vcenter_host_url": null,
            "vcenter_name": null,
            "vcenter_uuid": null,
            "vdi_base_device": null,
            "virtual_machine": true,
            "virtualization_provider": "VMW_ESX",
            "vm_ip": null,
            "vm_name": null,
            "vm_uuid": null,
            "vulnerability_score": 0.0,
            "vulnerability_severity": null,
            "windows_platform": null
        }
    ],
    "num_found": 1
}

Export Devices (CSV)

RBAC Permissions Required

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

Request

GET {cbc-hostname}/appservices/v6/orgs/{org_key}/devices/_search/download

Query Schema

Field Definition Data Type Values
status REQUIRED Device statuses to match. String PENDING, REGISTERED, UNINSTALLED, DEREGISTERED, ACTIVE, INACTIVE, ERROR, ALL, BYPASS_ON, BYPASS, QUARANTINE, SENSOR_OUTOFDATE, DELETED, LIVE
ad_group_id Active Directory group ID to match Integer N/A
deployment_type The device’s deployment type, a classification that is determined by its lifecycle management policy String ENDPOINT, WORKLOAD
policy_id Carbon Black Cloud Policy ID to match Integer N/A
query_string Device value search query string String N/A
target_priority Device target priorities to match. String LOW, MEDIUM, HIGH, MISSION_CRITICAL
sort_field Field to sort results by String target_priority, policy_name, name, last_contact_time, av_pack_version, login_user_name, os_version, sensor_version, vm_name, esx_host_name, cluster_name, vm_ip, vulnerability_severity, vulnerability_score

Default: last_contact_time
sort_order Sort order. String ASC, DESC

Default: ASC

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.conferdeploy.net/appservices/v6/orgs/ABCD1234/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 {cbc-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.conferdeploy.net/appservices/v6/orgs/ABCD1234/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,
    "id": 1515068,
    "device_meta_data_item_list": [],
    "device_owner_id": 0,
    "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": "LINUX",
    "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
}

Facet Devices

Executes a device facet search which generates statistics indicating the relative weighting of values for the specified terms.

RBAC Permissions Required

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

Request

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/devices/_facet

Request Body

{
  "criteria": {
    "status": [ "<string>", "<string>" ],
    "os": [ "<string>", "<string>" ],
    "last_contact_time": {
      "end": "<dateTime>",
      "range": "<string>",
      "start": "<dateTime>"
    },
    "ad_group_id": [ "<long>", "<long>" ],
    "policy_id": [ "<long>", "<long>" ],
    "id": [ "<long>", "<long>" ],
    "target_priority": [ "<string>", "<string>" ],
    "deployment_type": [ "<string>", "<string>" ],
    "vm_uuid": [ "<string>", "<string>" ],
    "vcenter_uuid": [ "<string>", "<string>" ]
  },
  "exclusions": {
    "sensor_version": [
      "<string>"
    ]
  },
  "query": "<string>",
  "terms": {
    "fields": [
      "<string>"
    ],
    "rows": "<long>"
  }
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object
{
  "os": [
    "WINDOWS"
  ]
}
Supported fields: status, os, last_contact_time, ad_group_id, policy_id, id, target_priority, deployment_type, vm_uuid, vcenter_uuid
exclusions Exclusions is a map that represents values that must not be in the results. Object
{
  "sensor_version": [
    "windows:1.0.0"
  ]
}
Supported Fields: sensor_version

sensor_verion format os:#.#.#.#
query Query in lucene syntax and/or including value searches. String N/A
terms The events fields to facet and how many of the top entries to return. Object
{
  "fields": [
    "STATUS"
  ],
  "rows": 100
}
Supported Fields: policy_id, status, os, ad_group_id

Time Criteria

Device APIs support filtering via the last_contact_time field in the criteria object. These time criteria filters can use either the range field or the start and end fields.

  • range can be either all (to indicate all time), or a specific duration specified as -[quantity][unit], where unit is one of:
    • s for seconds
    • m for minutes
    • h for hours
    • d for days
    • w for weeks
    • y for years
  • start and end are specified as ISO-8601 strings. start must be less than end.

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.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_facet

Request Body

{
    "criteria": {
        "status": ["REGISTERED"],
        "os": ["WINDOWS"]
    },
    "terms": {
        "fields": [ "policy_id" ]
    }
}

Response

{
    "results": [
        {
            "field": "policy_id",
            "values": [
                {
                    "total": 3,
                    "id": "2198",
                    "name": "2198"
                },
                {
                    "total": 3,
                    "id": "9815",
                    "name": "9815"
                },
                {
                    "total": 1,
                    "id": "2203",
                    "name": "2203"
                },
                {
                    "total": 1,
                    "id": "2297",
                    "name": "2297"
                },
                {
                    "total": 1,
                    "id": "2374",
                    "name": "2374"
                },
                {
                    "total": 1,
                    "id": "30241",
                    "name": "30241"
                },
                {
                    "total": 1,
                    "id": "5365",
                    "name": "5365"
                },
                {
                    "total": 1,
                    "id": "7942",
                    "name": "7942"
                }
            ]
        }
    ]
}

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.uninstall EXECUTE UNINSTALL_SENSOR
device.deregistered DELETE 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 {cbc-hostname}/appservices/v6/orgs/{org_key}/device_actions

Body Schema

Field Definition Data Type Values
action_type REQUIRED Action to perform on selected devices. String BACKGROUND_SCAN, BYPASS, UNINSTALL_SENSOR, DELETE_SENSOR, QUARANTINE, UPDATE_POLICY, UPDATE_SENSOR_VERSION
device_id List of devices to perform action on.

Either device_id or search is required.
List
[
  1467,
  982
]
search A device search. Device actions will be performed on the result set of this search.

Either device_id or search is required.
Object
{
  "criteria": {},
  "exclusions": {},
  "query": ""
}
See Search Devices for more information.
options.policy_id Devices will be updated to this policy ID.

Required if action_type is set to UPDATE_POLICY
Integer N/A
options.sensor_version Devices will be updated to the specified sensor version based on the device’s sensor_kit_type.

Required if action_type is set to UPDATE_SENSOR_VERSION
Object
{
  "RHEL": "2.4.0.3"
}
Supported Types: XP, WINDOWS, MAC, AV_SIG, OTHER, RHEL, UBUNTU, SUSE, AMAZON_LINUX, MAC_OSX
options.toggle Determines whether to enable or disable the action.

Required if action_type is set to QUARANTINE, BYPASS, or BACKGROUND_SCAN.
String ON, OFF

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

Response

Response Code: 204

Quarantine

Not supported on devices of OS type Linux

Request

POST https://defense-prod05.conferdeploy.net/appservices/v6/orgs/ABCD1234/device_actions

Request Body

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

Response

Response Code: 204

Bypass

Request

POST https://defense-prod05.conferdeploy.net/appservices/v6/orgs/ABCD1234/device_actions

Request Body

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

Response

Response Code: 204

Background Scan

Not supported on devices of OS type Linux

Request

POST https://defense-prod05.conferdeploy.net/appservices/v6/orgs/ABCD1234/device_actions

Request Body

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

Response Code: 204

Update Policy

Request

POST https://defense-prod05.conferdeploy.net/appservices/v6/orgs/ABCD1234/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.conferdeploy.net/appservices/v6/orgs/ABCD1234/device_actions

Request Body

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

Uninstall Sensor

Request

POST https://defense-prod05.conferdeploy.net/appservices/v6/orgs/ABCD1234/device_actions

Request Body

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

Response

Response Code: 204

Delete Sensor

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

Request

POST https://defense-prod05.conferdeploy.net/appservices/v6/orgs/ABCD1234/device_actions

Request Body

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

Response

Response Code: 204

Schemas

All fields are returned no matter the deployment type or installation method. If the property does not apply to the configured device then the field will be set to null.

Base Device

These fields can be associated with either deployment type.

Field Definition Data Type Values
current_sensor_policy_name The name of the policy currently configured on the sensor. String N/A
deployment_type Classification that is determined by the lifecycle management policy of the device. If a device is under vcenter, it is marked as WORKLOAD. Other devices are marked as ENDPOINT. String ENDPOINT, WORKLOAD
device_meta_data_item_list A list of attributes that describe the device. List
[{
    "key_name": "string",
    "key_value": "string",
    "position": 0
}]
id The identifier for the device. Integer N/A
last_contact_time The last time the sensor contacted the Carbon Black Cloud. String ISO 8601 timestamp in UTC
last_device_policy_changed_time The last time the sensor changed from one policy to another. String ISO 8601 timestamp in UTC
last_device_policy_requested_time The last time the sensor checked for changes to the policy. String ISO 8601 timestamp in UTC
last_external_ip_address The last IP address of the device according to the Carbon Black Cloud; can differ from last_internal_ip_address due to network proxy or NAT. String Format: IPv4 or IPv6
last_internal_ip_address The last IP address of the device reported by the sensor. String Format: IPv4 or IPv6
last_location The device’s current location relative to the organization’s network, based on the current IP address and the device’s registered DNS domain suffix. String UNKNOWN, ONSITE, OFFSITE
last_policy_updated_time The last time the current policy received an update. String ISO 8601 timestamp in UTC
last_reported_time The last time when the Carbon Black Cloud received one or more events reported by the sensor. String ISO 8601 timestamp in UTC
last_reset_time The last time the device was reset. String ISO 8601 timestamp in UTC
last_shutdown_time The last time the device was shutdown. String ISO 8601 timestamp in UTC
linux_kernel_version Not implemented String N/A
login_user_name The last user logged in on the device.

Requires Windows Carbon Black Cloud sensor
String N/A
mac_address The media access control (MAC) address for the device’s primary interface

Requires Windows CBC sensor version 3.6.0.1941 or later, or macOS CBC sensor
String N/A
name Hostname of the endpoint recorded by the sensor when last initialized. String N/A
organization_id Organization identifier. Integer N/A
organization_name Organization name. String N/A
os Operating System. String WINDOWS, MAC, LINUX, OTHER
os_version The operating system and version of the endpoint. String N/A
passive_mode Whether the device is in bypass. Boolean N/A
policy_id The policy identifier assigned to the device. Integer N/A
policy_name The policy name assigned to the device. May not match current_sensor_policy_name until the sensor checks back in. String N/A
quarantined An indicator that the device is in quarantine mode. Boolean N/A
scan_last_action_time The last time the background scan was started or stopped. String ISO 8601 timestamp in UTC
scan_last_complete_time The time the last background scan completed. String ISO 8601 timestamp in UTC
scan_status The status of the background scan. String NEVER_RUN, STOPPED, IN_PROGRESS, COMPLETED
sensor_kit_type The type of sensor installed on the device. String XP, WINDOWS, MAC, AV_SIG, OTHER, RHEL, UBUNTU, SUSE, AMAZON_LINUX, MAC_OSX
sensor_out_of_date Whether there is a new version available to be installed. Boolean N/A
sensor_pending_update Whether the sensor is marked by the Sensor Update Service for a sensor upgrade. Boolean N/A
sensor_states The states the sensor is in. List
[ "ACTIVE", "LIVE_RESPONSE_ENABLED" ]
ACTIVE, PANICS_DETECTED, LOOP_DETECTED, DB_CORRUPTION_DETECTED, CSR_ACTION, REPUX_ACTION, DRIVER_INIT_ERROR, REMGR_INIT_ERROR, UNSUPPORTED_OS, SENSOR_UPGRADE_IN_PROGRESS, SENSOR_UNREGISTERED, WATCHDOG, SENSOR_RESET_IN_PROGRESS, DRIVER_INIT_REBOOT_REQUIRED, DRIVER_LOAD_NOT_GRANTED, SENSOR_SHUTDOWN, SENSOR_MAINTENANCE, FULL_DISK_ACCESS_NOT_GRANTED, DEBUG_MODE_ENABLED, AUTO_UPDATE_DISABLED, SELF_PROTECT_DISABLED, VDI_MODE_ENABLED, POC_MODE_ENABLED, SECURITY_CENTER_OPTLN_DISABLED, LIVE_RESPONSE_RUNNING, LIVE_RESPONSE_NOT_RUNNING, LIVE_RESPONSE_KILLED, LIVE_RESPONSE_NOT_KILLED, LIVE_RESPONSE_ENABLED, LIVE_RESPONSE_DISABLED, DRIVER_KERNEL, DRIVER_USERSPACE
sensor_version The version of the installed sensor. String Format: #.#.#.#
status The status of the device. String PENDING, REGISTERED, DEREGISTERED, BYPASS

Additional searchable statuses that are not returnable ACTIVE, INACTIVE, ERROR, ALL, BYPASS_ON, LIVE, SENSOR_PENDING_UPDATE
target_priority The “Target value” configured in the policy assigned to the sensor. String LOW, MEDIUM, HIGH, MISSION_CRITICAL
vdi_base_device The identifier of the device from which this device was cloned/re-registered. Integer or null N/A
windows_platform Deprecated for os_version String CLIENT_X86, CLIENT_X64, SERVER_X86, SERVER_X64, CLIENT_ARM64, SERVER_ARM64

Mass Sensor Management

The properties associated with Mass Sensor Management for sensor installation

Field Definition Data Type Values
ad_group_id Active Directory group identifier. Integer N/A
policy_override Whether the policy was manually assigned to override mass sensor management. Boolean N/A

Device Owner Sensor Installation

The properties associated with Device Owner Sensor Installation

Field Definition Data Type Values
activation_code Device activation code to register the sensor with a specific org. String N/A
activation_code_expiry_time When the activation code expires and cannot be used to register a device. String ISO 8601 timestamp in UTC
deregistered_time Time when the deregister request was received. String ISO 8601 timestamp in UTC
device_owner_id The identifier for the device owner associated with the device. Integer N/A
email The email address for the device owner. String N/A
first_name The first name of the device owner. String N/A
encoded_activation_code Encoded activation code String N/A
last_name The last name of the device owner. String N/A
middle_name The middle name of the device owner. String N/A
registered_time When the device was registered with the Carbon Black Cloud. String ISO 8601 timestamp in UTC
uninstall_code The code to enter when uninstalling the sensor. String N/A

Local Scanner

The properties associated with the local scanner feature. Local scanner is a third party local anti virus (AV) engine that we bundle within our sensor that can be configured to periodically scan the device. The local scanner requires a signature pack and is configured via the policy the device is associated with.

Field Definition Data Type Values
av_ave_version AVE version (part of AV Version) String N/A
av_engine Current anti virus (AV) version String Example: 4.3.0.203-ave.8.3.42.106:avpack.8.4.2.36:vdf.8.12.142.100
av_last_scan_time The last time a local scan completed. String ISO 8601 timestamp in UTC
av_master Whether the device is an AV Master Boolean N/A
av_pack_version Pack version (part of AV Version) String N/A
av_product_version Product version (part of AV Version) String N/A
av_status The status of the local scan. List
[ "AV_ACTIVE", "AV_REGISTERED" ]
AV_NOT_REGISTERED, AV_REGISTERED, AV_DEREGISTERED, AV_ACTIVE, AV_BYPASS, SIGNATURE_UPDATE_DISABLED, ONACCESS_SCAN_DISABLED, ONDEMAND_SCAN_DISABLED, PRODUCT_UPDATE_DISABLED
av_update_servers A list of device’s AV servers List
[ "string", "string" ]
av_vdf_version VDF version (part of AV Version) String N/A

Workload

The properties associated with WORKLOAD deployment type devices

Field Definition Data Type Values
appliance_name Name of the Appliance the Virtual Machine (VM) is associated with. String N/A
appliance_uuid The Uuid of the appliance the VM is associated with. String N/A
cluster_name Name of the cluster. A cluster is a group of hosts. String N/A
datacenter_name Name of the underlying datacenter. The datacenter managed object provides the interface to the common container object for hosts, virtual machines, networks, and datastores.  String N/A
esx_host_name Name of the ESX host on which the VM is deployed String N/A
esx_host_uuid Uuid of the ESX host on which VM is deployed String N/A
vcenter_name Name of the vcenter the vm is associated with String N/A
vcenter_uuid 128-bit SMBIOS UUID of a vcenter represented as a hexadecimal string String N/A
virtualization_provider Name of the VM Virtualization Provider String N/A
virtual_machine Whether this device is a Virtual Machine (VMware AppDefense integration)

Deprecated for deployment_type
Boolean N/A
vm_ip VM’s Ip String N/A
vm_name Name of the Virtual Machine that the sensor is deployed on String N/A
vm_uuid 128-bit SMBIOS UUID of a virtual machine represented as a hexadecimal string String Format: 12345678-abcd-1234-cdef-123456789abc
vulnerability_score A score from 0 to 100 indicating the workload’s level of vulnerability with 100 being highly vulnerable Double N/A
vulnerability_severity The severity level indicating the workload’s vulnerability String CRITICAL, MODERATE, IMPORTANT, LOW
Last modified on February 2, 2021