Devices API
Overview
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.
Guides and Resources
- Carbon Black Cloud User Guide - Inventory
- Carbon Black Cloud Python SDK
- Carbon Black Postman Workspace
Authentication
Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.
Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.
API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
- Device search: {cbc-hostname}/appservices/v6/orgs/{org_key}/devices/
- Device actions: {cbc-hostname}/appservices/v6/orgs/{org_key}/device_actions
Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
- Device > General Information > device, allow permission to
READ
- Device > Policy assignment > device.policy, allow permission to
UPDATE
- Device > Background scan > device.bg-scan, allow permission to
EXECUTE
- Device > Bypass > device.bypass, allow permission to
EXECUTE
- Device > Quarantine > device.quarantine, allow permission to
EXECUTE
- Device > Sensor kits > org.kits, allow permission to
EXECUTE
- Device > Uninstall > device.uninstall, allow permission to
EXECUTE
- Device > Deregistered > device.deregistered, allow permission to
DELETE
API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.
Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).
Environment
Available on
Prod UK
and AWS GovCloud (US)
. Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.
API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
- Device search: {cbc-hostname}/appservices/v6/orgs/{org_key}/devices/
- Device actions: {cbc-hostname}/appservices/v6/orgs/{org_key}/device_actions
Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
- _API.Device:device, allow permission to
READ
- _API.Device:device.Policy, allow permission to
UPDATE
- _API.Device:device.Bg-Scan, allow permission to
EXECUTE
- _API.Device:device.Bypass, allow permission to
EXECUTE
- _API.Device:device.Quarantine, allow permission to
EXECUTE
- _API.Device:org.Kits, allow permission to
EXECUTE
- _API.Device:device.Uninstall, allow permission to
EXECUTE
- _API.Device:device.Deregistered, allow permission to
DELETE
API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.
Search Devices
Search devices in your organization.
Note: Updates have been made to correctly document the use of snake_case for all fields, where previously there were inconsistencies with some documented in camelCase.API Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | device |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Device:device.read |
N/A - included in permission name | Prod UK and AWS GovCloud (US) |
Request
POST {cbc-hostname}/appservices/v6/orgs/{org_key}/devices/_search
Request Body
{
"criteria": {
"ad_group_id": [ <long>, <long> ],
"auto_scaling_group_name": [ "<string>", "<string>" ],
"base_device": <boolean>,
"cloud_provider_account_id": [ "<string>", "<string>" ],
"cloud_provider_resource_id": [ "<string>", "<string>" ],
"cloud_provider_tags": [ "<string>", "<string>" ],
"deployment_type": [ "<string>", "<string>" ],
"golden_device_id": [ "<string>", "<string>" ],
"golden_device_status": [ "<string>", "<string>" ],
"host_based_firewall_status": [ "<string>", "<string>" ],
"host_based_firewall_reason": "<string>",
"id": [ <long>, <long> ],
"infrastructure_provider": [ "<string>", "<string>" ],
"last_contact_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"os": [ "<string>", "<string>" ],
"os_version": [ "<string>", "<string>" ],
"policy_id": [ <long>, <long> ],
"sensor_version": [ "<string>", "<string>" ],
"signature_status": [ "<string>", "<string>" ],
"status": [ "<string>", "<string>" ],
"sub_deployment_type": [ "<string>", "<string>" ],
"target_priority": [ "<string>", "<string>" ],
"vcenter_uuid": [ "<string>", "<string>" ],
"virtual_private_cloud_id": [ "<string>", "<string>" ],
"virtualization_provider": [ "<string>", "<string>" ],
"vm_uuid": [ "<string>", "<string>" ],
"vcenter_host_url": [ "<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.
Warning: A single criteria option should not exceed 1k items. Consider breaking up the list with multiple API calls or using alternative criteria options. |
Object |
ad_group_id , auto_scaling_group_name , base_device , cloud_provider_account_id , cloud_provider_resource_id , cloud_provider_tags , deployment_type , golden_device_id , golden_device_status , host_based_firewall_status , host_based_firewall_reason , id , infrastructure_provider , last_contact_time , os , os_version , policy_id , sensor_version , signature_status , status , sub_deployment_type , target_priority , vcenter_uuid , virtual_private_cloud_id , virtualization_provider , vm_uuid , vcenter_host_url |
exclusions |
Exclusions is a map that represents values that must not be in the results. | Object |
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
Max: 10k; Up to 200k with pagination |
start |
What row to begin returning results from | Integer | Default: 0
Rows + Start should not exceed 10k |
sort |
Sort is a collection of sort parameters that specify a field and order to sort the results. |
Array |
order supports asc or desc
Supported Fields: av_pack_version , cluster_name , esx_host_name , last_contact_time , login_user_name , name , os_version , policy_name , sensor_version , target_priority , vm_ip , vm_name , vulnerability_score , vulnerability_severity |
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 eitherall
(to indicate all time), or a specific duration specified as-[quantity][unit]
, whereunit
is one of:s
for secondsm
for minutesh
for hoursd
for daysw
for weeksy
for years
start
andend
are specified as ISO 8601 UTC strings.start
must be less thanend
.
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": ["ENDPOINT"],
"target_priority": ["MEDIUM"],
"last_contact_time": {
"start": "2022-07-12T22:04:42.993Z",
"end": "2022-07-10T22:04:42.993ZZ"
}
},
"rows": 5,
"start": 0,
"sort": [
{
"field": "av_pack_version",
"order": "ASC"
}
]
}
Response
{
"results": [
{
"activation_code": null,
"activation_code_expiry_time": "2022-07-11T06:53:06.190Z",
"ad_group_id": 0,
"appliance_name": null,
"appliance_uuid": null,
"auto_scaling_group_name": null,
"av_ave_version": "8.3.64.172",
"av_engine": "4.15.1.560-ave.8.3.64.172:avpack.8.5.2.64:vdf.8.19.20.4:vdfdate.20220711",
"av_last_scan_time": null,
"av_master": false,
"av_pack_version": "8.5.2.64",
"av_product_version": "4.15.1.560",
"av_status": [
"AV_ACTIVE",
"ONDEMAND_SCAN_DISABLED"
],
"av_update_servers": null,
"av_vdf_version": "8.19.20.4",
"base_device": null,
"cloud_provider_account_id": null,
"cloud_provider_resource_id": null,
"cloud_provider_tags": null,
"cluster_name": null,
"current_sensor_policy_name": "CB-policy",
"datacenter_name": null,
"deployment_type": "ENDPOINT",
"deregistered_time": null,
"device_meta_data_item_list": [
{
"key_name": "OS_MAJOR_VERSION",
"key_value": "Windows 10",
"position": 0
},
{
"key_name": "SUBNET",
"key_value": "198.18.127",
"position": 0
}
],
"device_owner_id": 854220,
"email": "vagrant",
"esx_host_name": null,
"esx_host_uuid": null,
"first_name": null,
"golden_device": null,
"golden_device_id": null,
"host_based_firewall_failure_reason": null,
"host_based_firewall_status": null,
"id": 5765373,
"last_contact_time": "2022-07-11T22:04:42.993Z",
"last_device_policy_changed_time": "2022-07-04T13:22:15.870Z",
"last_device_policy_requested_time": "2022-07-04T13:46:25.278Z",
"last_external_ip_address": "162.111.555.333",
"last_internal_ip_address": "198.18.127.111",
"last_location": "OFFSITE",
"last_name": null,
"last_policy_updated_time": "2022-05-18T09:33:54.616Z",
"last_reported_time": "2022-07-11T22:04:43.063Z",
"last_reset_time": null,
"last_shutdown_time": "2022-07-04T06:58:55.867Z",
"linux_kernel_version": null,
"login_user_name": "CARBONBLACK\\testuser",
"mac_address": "fa163e92d344",
"middle_name": null,
"name": "carbonblack",
"nsx_distributed_firewall_policy": null,
"nsx_enabled": null,
"organization_id": 1105,
"organization_name": "cb-internal-alliances.com",
"os": "WINDOWS",
"os_version": "Windows 10 x64",
"passive_mode": false,
"policy_id": 87816,
"policy_name": "CB-policy",
"policy_override": true,
"quarantined": false,
"registered_time": "2022-07-04T06:53:06.220Z",
"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.8.0.627",
"status": "REGISTERED",
"target_priority": "MEDIUM",
"uninstall_code": "R6VERVN2",
"vcenter_host_url": null,
"vcenter_name": null,
"vcenter_uuid": null,
"vdi_base_device": null,
"virtual_machine": false,
"virtual_private_cloud_id": null,
"virtualization_provider": "OTHER",
"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)
API Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | device |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Device:device.read |
N/A - included in permission name | Prod UK and AWS GovCloud (US) |
Request
GET {cbc-hostname}/appservices/v6/orgs/{org_key}/devices/_search/download
Query Schema
Field | Definition | Data Type | Values |
---|---|---|---|
ad_group_id |
Sensor Group ID if sensor assigned to a group, 0 otherwise | Integer | N/A |
auto_scaling_group_name |
Public Cloud (AWS) auto scaling group name to match | String | N/A |
av_vdf_version |
Scan engine version to match. | String | N/A |
cloud_provider_account_id |
Public Cloud account id to match | String | N/A |
cloud_provider_resource_id |
Public Cloud Resource Id to match | String | N/A |
cloud_provider_tags |
Public Cloud Tags to match | String | N/A |
deployment_type |
The device’s deployment type, a classification that is determined by its lifecycle management policy | String | ENDPOINT , WORKLOAD , VDI , AWS |
golden_device_status |
Golden device status to match | String | NOT_GOLDEN_DEVICE , GOLDEN_DEVICE |
os |
Operating system to match | String | WINDOWS , CENTOS , RHEL , ORACLE , SLES AMAZON_LINUX , SUSE , UBUNTU |
os_version |
Operating system version to match | String | N/A |
policy_id |
Carbon Black Cloud Policy ID to match | Integer | N/A |
query_string |
Device value search query string | String | N/A |
sensor_verion |
Sensor version to match | String | N/A |
signature_status |
Signature status to match | String | NOT_APPLICABLE , NOT_AVAILABLE , UP_TO_DATE , OUT_OF_DATE |
sort_field |
Field to sort results by | String | av_pack_version , cluster_name , esx_host_name , last_contact_time , login_user_name , name , os_version , policy_name , sensor_version , target_priority , vm_ip , vm_name , vulnerability_score , vulnerability_severity |
sort_order |
Sort order. | String | ASC , DESC
Default: ASC |
status REQUIRED
|
Device statuses to match. | String | PENDING , REGISTERED , UNINSTALLED , DEREGISTERED , ACTIVE , INACTIVE , ERROR , ALL , BYPASS_ON , BYPASS , QUARANTINE , SENSOR_OUTOFDATE , DELETED , LIVE |
sub_deployment_type |
Sub deployment type to match | String | VMWARE_VIRTUAL_MACHINE , AWS_VIRTUAL_MACHINE_EC2 |
target_priority |
Device target priorities to match. | String | LOW , MEDIUM , HIGH , MISSION_CRITICAL |
vcenter_host_url |
vcenter host name to match | String | N/A |
virtual_private_cloud_id |
Virtual private cloud id to match | String | N/A |
virtualization_provider |
Virtualization provider to match | String | VMW_ESX , VMW_WS , VMW_OTHER , HyperV , VirtualBox , AWS_EC2 , OTHER |
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
API Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | device |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Device:device.read |
N/A - included in permission name | Prod UK and AWS GovCloud (US) |
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/5765373
Response
{
"activation_code": null,
"activation_code_expiry_time": "2022-07-11T06:53:06.190Z",
"ad_group_id": 0,
"appliance_name": null,
"appliance_uuid": null,
"auto_scaling_group_name": null,
"av_ave_version": "8.3.64.172",
"av_engine": "4.15.1.560-ave.8.3.64.172:avpack.8.5.2.64:vdf.8.19.20.4:vdfdate.20220711",
"av_last_scan_time": null,
"av_master": false,
"av_pack_version": "8.5.2.64",
"av_product_version": "4.15.1.560",
"av_status": [
"AV_ACTIVE",
"ONDEMAND_SCAN_DISABLED"
],
"av_update_servers": null,
"av_vdf_version": "8.19.20.4",
"base_device": null,
"cloud_provider_account_id": null,
"cloud_provider_resource_id": null,
"cloud_provider_tags": null,
"cluster_name": null,
"current_sensor_policy_name": "CB-policy",
"datacenter_name": null,
"deployment_type": "ENDPOINT",
"deregistered_time": null,
"device_meta_data_item_list": [
{
"key_name": "OS_MAJOR_VERSION",
"key_value": "Windows 10",
"position": 0
},
{
"key_name": "SUBNET",
"key_value": "198.18.127",
"position": 0
}
],
"device_owner_id": 854220,
"email": "vagrant",
"esx_host_name": null,
"esx_host_uuid": null,
"first_name": null,
"golden_device": null,
"golden_device_id": null,
"host_based_firewall_failure_reason": null,
"host_based_firewall_status": null,
"id": 5765373,
"last_contact_time": "2022-07-11T22:04:42.993Z",
"last_device_policy_changed_time": "2022-07-04T13:22:15.870Z",
"last_device_policy_requested_time": "2022-07-04T13:46:25.278Z",
"last_external_ip_address": "162.111.555.333",
"last_internal_ip_address": "198.18.127.111",
"last_location": "OFFSITE",
"last_name": null,
"last_policy_updated_time": "2022-05-18T09:33:54.616Z",
"last_reported_time": "2022-07-11T22:04:43.063Z",
"last_reset_time": null,
"last_shutdown_time": "2022-07-04T06:58:55.867Z",
"linux_kernel_version": null,
"login_user_name": "CARBONBLACK\\testuser",
"mac_address": "fa163e92d344",
"middle_name": null,
"name": "carbonblack",
"nsx_distributed_firewall_policy": null,
"nsx_enabled": null,
"organization_id": 1105,
"organization_name": "cb-internal-alliances.com",
"os": "WINDOWS",
"os_version": "Windows 10 x64",
"passive_mode": false,
"policy_id": 87816,
"policy_name": "CB-policy",
"policy_override": true,
"quarantined": false,
"registered_time": "2022-07-04T06:53:06.220Z",
"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.8.0.627",
"status": "REGISTERED",
"target_priority": "MEDIUM",
"uninstall_code": "R6VERVN2",
"vcenter_host_url": null,
"vcenter_name": null,
"vcenter_uuid": null,
"vdi_base_device": null,
"virtual_machine": false,
"virtual_private_cloud_id": null,
"virtualization_provider": "OTHER",
"vm_ip": null,
"vm_name": null,
"vm_uuid": null,
"vulnerability_score": 0.0,
"vulnerability_severity": null,
"windows_platform": null
}
Facet Devices
Executes a device facet search which generates statistics indicating the relative weighting of values for the specified terms.
Note: Updates have been made to correctly document the use of snake_case for all fields, where previously there were inconsistencies with some documented in camelCase.API Permissions Required
Identity Manager | Permission (.notation name) | Operation(s) | Environment |
---|---|---|---|
Carbon Black Cloud | device |
READ |
Majority of environments |
VMware Cloud Services Platform | _API.Device:device.read |
N/A - included in permission name | Prod UK and AWS GovCloud (US) |
Request
POST {cbc-hostname}/appservices/v6/orgs/{org_key}/devices/_facet
Request Body
{
"criteria": {
"ad_group_id": [ <long>, <long> ],
"auto_scaling_group_name": [ "<string>", "<string>" ],
"base_device": <boolean>,
"cloud_provider_account_id": [ "<string>", "<string>" ],
"cloud_provider_resource_id": [ "<string>", "<string>" ],
"cloud_provider_tags": [ "<string>", "<string>" ],
"deployment_type": [ "<string>", "<string>" ],
"golden_device_id": [ "<string>", "<string>" ],
"golden_device_status": [ "<string>", "<string>" ],
"host_based_firewall_status": [ "<string>", "<string>" ],
"host_based_firewall_reason": "<string>",
"id": [ <long>, <long> ],
"infrastructure_provider": [ "<string>", "<string>" ],
"last_contact_time": {
"end": "<dateTime>",
"range": "<string>",
"start": "<dateTime>"
},
"os": [ "<string>", "<string>" ],
"os_version": [ "<string>", "<string>" ],
"policy_id": [ <long>, <long> ],
"sensor_version": [ "<string>", "<string>" ],
"signature_status": [ "<string>", "<string>" ],
"status": [ "<string>", "<string>" ],
"sub_deployment_type": [ "<string>", "<string>" ],
"target_priority": [ "<string>", "<string>" ],
"vcenter_uuid": [ "<string>", "<string>" ],
"virtual_private_cloud_id": [ "<string>", "<string>" ],
"virtualization_provider": [ "<string>", "<string>" ],
"vm_uuid": [ "<string>", "<string>" ],
"vcenter_host_url": [ "<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.
Warning: A single criteria option should not exceed 1k items. Consider breaking up the list with multiple API calls or using alternative criteria options. |
Object |
ad_group_id , auto_scaling_group_name , base_device , cloud_provider_account_id , cloud_provider_resource_id , cloud_provider_tags , deployment_type , golden_device_id , golden_device_status , host_based_firewall_status , host_based_firewall_reason , id , infrastructure_provider , last_contact_time , os , os_version , policy_id , sensor_version , signature_status , status , sub_deployment_type , target_priority , vcenter_uuid , virtual_private_cloud_id , virtualization_provider , vm_uuid , vcenter_host_url |
exclusions |
Exclusions is a map that represents values that must not be in the results. | Object |
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 |
ad_group_id , auto_scaling_group_name , cloud_provider_account_id , cloud_provider_tags , golden_device_id , golden_device_status , host_based_firewall_status , infrastructure_provider , os , os_version , policy_id , sensor_version , signature_status , status , sub_deployment_type , vcenter_host_url , virtualization_provider , virtual_private_cloud_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 eitherall
(to indicate all time), or a specific duration specified as-[quantity][unit]
, whereunit
is one of:s
for secondsm
for minutesh
for hoursd
for daysw
for weeksy
for years
start
andend
are specified as ISO 8601 UTC strings.start
must be less thanend
.
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
For the environments where identity is managed in Carbon Black Cloud (the majority):
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 |
For the environments where identity is managed in VMware Cloud Services Platform (UK PoP) and AWS GovCloud (US):
Permission (.notation name) | Action Type |
---|---|
_API.Device:device.Quarantine.exceute |
QUARANTINE |
_API.Device:device.Bypass.exceute |
BYPASS |
_API.Device:device.Bg-Scan.exceute |
BACKGROUND_SCAN |
_API.Device:device.Policy.update |
UPDATE_POLICY |
_API.Device:org.Kits.exceute |
UPDATE_SENSOR_VERSION |
_API.Device:device.Uninstall.exceute |
UNINSTALL_SENSOR |
_API.Device: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
Request Body
{
"action_type": "<string>",
"device_id": ["<string>", "<string>"],
"search": {
"criteria": {
"<string>": ["<string>", "<string>"]
},
"exclusions": {
"<string>": ["<string>", "<string>"]
},
"query": "<string>"
},
"options": {
"toggle": "<string>",
"sensor_version": {
"<string>": "<string>"
}
"policy_id": <long>
}
}
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 |
|
search |
A device search. Device actions will be performed on the result set of this search.
Either device_id or search is required.
Warning: A single criteria option should not exceed 1k items. Consider breaking up the list with multiple API calls or using alternative criteria options. |
Object |
|
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 |
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", "12320"],
"options": {
"toggle": "ON"
}
}
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", "1777303"],
"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", "1777303"],
"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
Fields
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 |
|
id |
The identifier for the device. | Integer | N/A |
last_contact_time |
The last time the sensor contacted the Carbon Black Cloud as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
last_device_policy_changed_time |
The last time the sensor changed from one policy to another as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
last_device_policy_requested_time |
The last time the sensor checked for changes to the policy as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
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 as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
last_reported_time |
The last time when the Carbon Black Cloud received one or more events reported by the sensor as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
last_reset_time |
The last time the device was reset as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
last_shutdown_time |
The last time the device was shutdown as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
linux_kernel_version |
Not implemented | String | N/A |
login_user_name |
The last user logged in on the device.
macOS 3.3.2+ versions display the last active user logged in to the device. Windows 3.5+ versions display the last active user logged in every 8 hours; if there is no interactive user logged in within the 8 hour window, a noninteractive user name can appear. Windows 3.7+ versions display the last cached active user logged in. Previous macOS and Windows versions display the user who installed the sensor. Linux versions are intentionally left blank because multiple, simultaneous logged-in users and desktop users are possible. |
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 |
Not Used
Intended for the last time the background scan was started or stopped as an ISO 8601 UTC timestamp. |
String | Example: 2021-04-07T17:49:58.792Z |
scan_last_complete_time |
Not Used
Intended for the time the last background scan completed as an ISO 8601 UTC timestamp. |
String | Example: 2021-04-07T17:49:58.792Z |
scan_status |
Not Used
Intended for 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 , 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 , DRIVER_LOAD_PENDING , OS_VERSION_MISMATCH |
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 |
Sensor Group ID if sensor assigned to a group, 0 otherwise. | 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
Note: The device owner defaults to the user installing the Carbon Black Cloud sensor unless set in the config INI file.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 as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
deregistered_time |
Time when the deregister request was received as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
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 as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
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 as an ISO 8601 UTC timestamp. | String | Example: 2021-04-07T17:49:58.792Z |
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_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 |
|
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 |
golden_device |
Shows if device is Golden VM for any VDI clone | Boolean | N/A |
golden_device_id |
Device Id for golden VM | Integer | N/A |
golden_device_status |
Golden device status to match in a search
Not Returnable |
String | NOT_GOLDEN_DEVICE , GOLDEN_DEVICE |
nsx_distributed_firewall_policy |
The NSX tag assigned to the workload | String | CB-NSX-Quarantine , CB-NSX-Isolate , CB-NSX-Custom , null |
nsx_enabled |
Indicates if the workoad is associated with an appliance that has NSX enabled and connected | Boolean | N/A |
vcenter_host_url |
The URL of the vcenter the vm is associated with | 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 |
vdi_base_device |
Device ID of the base VDI | Integer | N/A |
virtual_machine |
Whether this device is a Virtual Machine (VMware AppDefense integration)
Deprecated for deployment_type |
Boolean | N/A |
virtual_private_cloud_id |
The ID of the virtual cloud provider | String | N/A |
virtualization_provider |
Name of the VM Virtualization Provider | String | VMW_ESX , VMW_WS , VMW_OTHER , HyperV , VirtualBox , AWS_EC2 , OTHER |
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 |
Public Cloud
The properties associated with public cloud WORKLOAD deployments
Field | Definition | Data Type | Values |
---|---|---|---|
auto_scaling_group_name |
Public Cloud (AWS) auto scaling group name | String | N/A |
cloud_provider_account_id |
The ID of the public cloud account associated with the WORKLOAD | String | N/A |
cloud_provider_resource_id |
The ID of the WORKLOAD in the public cloud | String | N/A |
cloud_provider_tags |
The tags associated with the WORKLOAD in the public cloud | Array | N/A |
Give Feedback
Use this form to give us feedback about this site or any of the documentation.
Last modified on March 16, 2023