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

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 
{
  "os": [
    "WINDOWS"
  ]
}
Supported fields: 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": [
    "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
Max: 10k
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 
[{
  "field": "last_contact_time",
  "order": "asc"
}]
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 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 UTC 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": ["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 True, False
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 
{
  "os": [
    "WINDOWS"
  ]
}
Supported fields: 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": [
    "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: 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 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 UTC 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

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

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 
{
  "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", "12320"],
    "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", "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 
[{
    "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 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", "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, 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_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
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
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
Last modified on March 16, 2023