Devices API

Overview

Warning: groups is in the process of being renamed to asset_group. The asset group properties id, name. and membership_type in the response will not change only the groups parent name will change to asset_group. If you need to search by an asset group property in the criteria or the query use groups_id or groups_name when the new name is released there will be a short period where both asset_group_id, asset_group_name, groups_id, and groups_name will be supported. The dual support will only last a couple weeks so make the transition quickly. Additional details will be included in the Carbon Black Cloud Release Notes.

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

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

Warning: groups is in the process of being renamed to asset_group. The asset group properties id, name. and membership_type in the response will not change only the groups parent name will change to asset_group. If you need to search by an asset group property in the criteria or the query use groups_id or groups_name when the new name is released there will be a short period where both asset_group_id, asset_group_name, groups_id, and groups_name will be supported. The dual support will only last a couple weeks so make the transition quickly. Additional details will be included in the Carbon Black Cloud Release Notes.

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_distinguished_name": [ "<string>", "<string>" ],
    "ad_domain": [ "<string>", "<string>" ],
    "ad_group_id": [ <long>, <long> ],
    "ad_org_unit": [ "<string>", "<string>" ],
    "auto_scaling_group_name": [ "<string>", "<string>" ],
    "base_device": <boolean>,
    "cloud_provider_account_id": [ "<string>", "<string>" ],
    "cloud_provider_managed_identity": [ "<string>", "<string>" ],
    "cloud_provider_network": [ "<string>", "<string>" ],
    "cloud_provider_resource_group": [ "<string>", "<string>" ],
    "cloud_provider_resource_id": [ "<string>", "<string>" ],
    "cloud_provider_scale_group": [ "<string>", "<string>" ],
    "cloud_provider_tags": [ "<string>", "<string>" ],
    "cluster_name": [ "<string>", "<string>" ],
    "compliance_status": [ "<string>", "<string>" ],
    "datacenter_name": [ "<string>", "<string>" ],
    "deployment_type": [ "<string>", "<string>" ],
    "esx_host_name": [ "<string>", "<string>" ],
    "golden_device_id": [ "<string>", "<string>" ],
    "golden_device_status": [ "<string>", "<string>" ],
    "asset_group_id": [ "<string>", "<string>" ],
    "asset_group_name": [ "<string>", "<string>" ],
    "host_based_firewall_status": [ "<string>", "<string>" ],
    "id": [ <long>, <long> ],
    "infrastructure_provider": [ "<string>", "<string>" ],
    "last_contact_time": {
      "end": "<string>",
      "range": "<string>",
      "start": "<string>"
    },
    "os": [ "<string>", "<string>" ],
    "os_version": [ "<string>", "<string>" ],
    "policy_id": [ <long>, <long> ],
    "sensor_gateway_url": [ "<string>", "<string>" ],
    "sensor_version": [ "<string>", "<string>" ],
    "signature_status": [ "<string>", "<string>" ],
    "status": [ "<string>", "<string>" ],
    "sub_deployment_type": [ "<string>", "<string>" ],
    "subnet": [ "<string>", "<string>" ],
    "target_priority": [ "<string>", "<string>" ],
    "vcenter_host_url": [ "<string>", "<string>" ],
    "vcenter_name": [ "<string>", "<string>" ],
    "vcenter_uuid": [ "<string>", "<string>" ],
    "virtual_private_cloud_id": [ "<string>", "<string>" ],
    "virtualization_provider": [ "<string>", "<string>" ],
    "vm_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.

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_distinguished_name, ad_domain, ad_group_id, ad_org_unit, auto_scaling_group_name, base_device, cloud_provider_account_id, cloud_provider_managed_identity, cloud_provider_network, cloud_provider_resource_group, cloud_provider_resource_id, cloud_provider_scale_group, cloud_provider_tags, cluster_name, compliance_status, datacenter_name, deployment_type, esx_host_name, golden_device_id, golden_device_status, asset_group_id, asset_group_name, host_based_firewall_status, id, infrastructure_provider, last_contact_time, os, os_version, policy_id, sensor_gateway_url, sensor_version, signature_status, status, sub_deployment_type, subnet, target_priority, vcenter_host_url, vcenter_name, vcenter_uuid, virtual_private_cloud_id, virtualization_provider, vm_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
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
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
500 Internal Server Error N/A

Examples

Request 
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
        "deployment_type": ["ENDPOINT"],
        "target_priority": ["MEDIUM"],
        "last_contact_time": {
            "start": "2023-10-01T00:00:00.000Z",
            "end": "2023-11-22T00:00:00.000Z"
        }
    },
  "rows": 5,
  "start": 0,
  "sort": [
    {
      "field": "av_pack_version",
      "order": "ASC"
    }
  ]
}
Response Body 
{
    "num_found": 1,
    "results": [
        {
            "activation_code": null,
            "activation_code_expiry_time": "2023-02-16T01:26:40.571Z",
            "ad_domain": null,
            "ad_group_id": 0,
            "ad_org_unit": null,
            "appliance_name": null,
            "appliance_uuid": null,
            "auto_scaling_group_name": null,
            "av_ave_version": "8.3.66.192",
            "av_engine": "4.15.14.50-ave.8.3.66.192:avpack.8.6.2.18:vdf.8.20.12.212:apc.2.11.2.6:vdfdate.20231121",
            "av_last_scan_time": null,
            "av_master": false,
            "av_pack_version": "8.6.2.18",
            "av_product_version": "4.15.14.50",
            "av_status": [
                "AV_ACTIVE",
                "ONDEMAND_SCAN_DISABLED"
            ],
            "av_update_servers": null,
            "av_vdf_version": "8.20.12.212",
            "base_device": null,
            "cloud_provider_account_id": null,
            "cloud_provider_resource_id": null,
            "cloud_provider_tags": [],
            "cloud_provider_resource_group": null,
            "cloud_provider_scale_group": null,
            "cloud_provider_network": null,
            "cloud_provider_managed_identity": null,
            "cluster_name": null,
            "compliance_status": "NOT_ASSESSED",
            "current_sensor_policy_name": "Standard",
            "policy_override": false,
            "quarantined": false,
            "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": "12.345.67.8",
                    "position": 0
                }
            ],
            "device_owner_id": 16941161,
            "email": "",
            "esx_host_name": null,
            "esx_host_uuid": null,
            "first_name": null,
            "golden_device": null,
            "golden_device_id": null,
            "asset_group": [
              {
                "id": "fb32fcc1-3bfe-4945-9b6a-46a5049856cd",
                "name": "test",
                "membership_type": "DYNAMIC"
              }
            ],
            "host_based_firewall_reasons": [],
            "host_based_firewall_status": "NOT_ENABLED",
            "id": 17853586,
            "infrastructure_provider": "NONE",
            "last_contact_time": "2023-11-21T21:19:40.237Z",
            "last_device_policy_changed_time": null,
            "last_device_policy_requested_time": "2023-10-12T15:06:31.509Z",
            "last_external_ip_address": "12.345.56.8",
            "last_internal_ip_address": "12.345.67.89",
            "last_location": "OFFSITE",
            "last_name": null,
            "last_reported_time": "2023-11-21T18:34:06.169Z",
            "last_reset_time": null,
            "last_shutdown_time": null,
            "linux_kernel_version": null,
            "login_user_name": "WIN10\\johndoe",
            "mac_address": "005056a560c7",
            "middle_name": null,
            "name": "Win10",
            "nsx_distributed_firewall_policy": null,
            "nsx_enabled": null,
            "organization_id": 6443217,
            "organization_name": "myorg.com",
            "os": "WINDOWS",
            "os_version": "Windows 10 x64 SP: 0",
            "passive_mode": false,
            "policy_id": 20383608,
            "policy_name": "Standard",
            "registered_time": "2023-02-09T01:45:41.510Z",
            "scan_last_action_time": null,
            "scan_last_complete_time": null,
            "scan_status": null,
            "sensor_gateway_url": null,
            "sensor_gateway_uuid": null,
            "sensor_kit_type": "WINDOWS",
            "sensor_out_of_date": true,
            "sensor_pending_update": false,
            "sensor_states": [
                "ACTIVE",
                "LIVE_RESPONSE_NOT_RUNNING",
                "LIVE_RESPONSE_NOT_KILLED",
                "LIVE_RESPONSE_DISABLED",
                "CB_FIREWALL_INACTIVE"
            ],
            "sensor_version": "3.9.1.2451",
            "status": "REGISTERED",
            "target_priority": "MEDIUM",
            "uninstall_code": "ASKD324A",
            "vcenter_host_url": null,
            "vcenter_name": null,
            "vcenter_uuid": null,
            "vdi_base_device": null,
            "vdi_provider": "NONE",
            "virtual_machine": true,
            "virtual_private_cloud_id": null,
            "virtualization_provider": "VMW_ESX",
            "vm_ip": null,
            "vm_name": null,
            "vm_uuid": null,
            "vulnerability_score": 0,
            "vulnerability_severity": null,
            "windows_platform": null,
            "last_policy_updated_time": "2023-01-27T22:04:59.571Z"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_search \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "deployment_type": ["ENDPOINT"],
    "target_priority": ["MEDIUM"],
    "last_contact_time": {
        "start": "2023-10-01T00:00:00.000Z",
        "end": "2023-11-22T00:00:00.000Z"
    }
  },
  "rows": 5,
  "start": 0,
  "sort": [{
    "field": "av_pack_version",
    "order": "ASC"
  }]
}'
Response Body 
{
    "num_found": 1,
    "results": [
        {
            "activation_code": null,
            "activation_code_expiry_time": "2023-02-16T01:26:40.571Z",
            "ad_domain": null,
            "ad_group_id": 0,
            "ad_org_unit": null,
            "appliance_name": null,
            "appliance_uuid": null,
            "auto_scaling_group_name": null,
            "av_ave_version": "8.3.66.192",
            "av_engine": "4.15.14.50-ave.8.3.66.192:avpack.8.6.2.18:vdf.8.20.12.212:apc.2.11.2.6:vdfdate.20231121",
            "av_last_scan_time": null,
            "av_master": false,
            "av_pack_version": "8.6.2.18",
            "av_product_version": "4.15.14.50",
            "av_status": [
                "AV_ACTIVE",
                "ONDEMAND_SCAN_DISABLED"
            ],
            "av_update_servers": null,
            "av_vdf_version": "8.20.12.212",
            "base_device": null,
            "cloud_provider_account_id": null,
            "cloud_provider_resource_id": null,
            "cloud_provider_tags": [],
            "cloud_provider_resource_group": null,
            "cloud_provider_scale_group": null,
            "cloud_provider_network": null,
            "cloud_provider_managed_identity": null,
            "cluster_name": null,
            "compliance_status": "NOT_ASSESSED",
            "current_sensor_policy_name": "Standard",
            "policy_override": false,
            "quarantined": false,
            "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": "12.345.67.8",
                    "position": 0
                }
            ],
            "device_owner_id": 16941161,
            "email": "",
            "esx_host_name": null,
            "esx_host_uuid": null,
            "first_name": null,
            "golden_device": null,
            "golden_device_id": null,
            "asset_group": [
              {
                "id": "fb32fcc1-3bfe-4945-9b6a-46a5049856cd",
                "name": "test",
                "membership_type": "DYNAMIC"
              }
            ],
            "host_based_firewall_reasons": [],
            "host_based_firewall_status": "NOT_ENABLED",
            "id": 17853586,
            "infrastructure_provider": "NONE",
            "last_contact_time": "2023-11-21T21:19:40.237Z",
            "last_device_policy_changed_time": null,
            "last_device_policy_requested_time": "2023-10-12T15:06:31.509Z",
            "last_external_ip_address": "12.345.56.8",
            "last_internal_ip_address": "12.345.67.89",
            "last_location": "OFFSITE",
            "last_name": null,
            "last_reported_time": "2023-11-21T18:34:06.169Z",
            "last_reset_time": null,
            "last_shutdown_time": null,
            "linux_kernel_version": null,
            "login_user_name": "WIN10\\johndoe",
            "mac_address": "005056a560c7",
            "middle_name": null,
            "name": "Win10",
            "nsx_distributed_firewall_policy": null,
            "nsx_enabled": null,
            "organization_id": 6443217,
            "organization_name": "myorg.com",
            "os": "WINDOWS",
            "os_version": "Windows 10 x64 SP: 0",
            "passive_mode": false,
            "policy_id": 20383608,
            "policy_name": "Standard",
            "registered_time": "2023-02-09T01:45:41.510Z",
            "scan_last_action_time": null,
            "scan_last_complete_time": null,
            "scan_status": null,
            "sensor_gateway_url": null,
            "sensor_gateway_uuid": null,
            "sensor_kit_type": "WINDOWS",
            "sensor_out_of_date": true,
            "sensor_pending_update": false,
            "sensor_states": [
                "ACTIVE",
                "LIVE_RESPONSE_NOT_RUNNING",
                "LIVE_RESPONSE_NOT_KILLED",
                "LIVE_RESPONSE_DISABLED",
                "CB_FIREWALL_INACTIVE"
            ],
            "sensor_version": "3.9.1.2451",
            "status": "REGISTERED",
            "target_priority": "MEDIUM",
            "uninstall_code": "ASKD324A",
            "vcenter_host_url": null,
            "vcenter_name": null,
            "vcenter_uuid": null,
            "vdi_base_device": null,
            "vdi_provider": "NONE",
            "virtual_machine": true,
            "virtual_private_cloud_id": null,
            "virtualization_provider": "VMW_ESX",
            "vm_ip": null,
            "vm_name": null,
            "vm_uuid": null,
            "vulnerability_score": 0,
            "vulnerability_severity": null,
            "windows_platform": null,
            "last_policy_updated_time": "2023-01-27T22:04:59.571Z"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Scroll Devices

Warning: groups is in the process of being renamed to asset_group. The asset group properties id, name. and membership_type in the response will not change only the groups parent name will change to asset_group. If you need to search by an asset group property in the criteria or the query use groups_id or groups_name when the new name is released there will be a short period where both asset_group_id, asset_group_name, groups_id, and groups_name will be supported. The dual support will only last a couple weeks so make the transition quickly. Additional details will be included in the Carbon Black Cloud Release Notes.

Scroll devices in your organization beyond the search limitations.

After requesting the initial results use the search_after from the response and the same search request to paginate the remaining devices. Repeat using the next search_after in the response until num_remaining is 0 indicating all devices have been paginated.

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/_scroll

Request Body 

{
  "criteria": {
    "ad_distinguished_name": [ "<string>", "<string>" ],
    "ad_domain": [ "<string>", "<string>" ],
    "ad_group_id": [ <long>, <long> ],
    "ad_org_unit": [ "<string>", "<string>" ],
    "auto_scaling_group_name": [ "<string>", "<string>" ],
    "base_device": <boolean>,
    "cloud_provider_account_id": [ "<string>", "<string>" ],
    "cloud_provider_managed_identity": [ "<string>", "<string>" ],
    "cloud_provider_network": [ "<string>", "<string>" ],
    "cloud_provider_resource_group": [ "<string>", "<string>" ],
    "cloud_provider_resource_id": [ "<string>", "<string>" ],
    "cloud_provider_scale_group": [ "<string>", "<string>" ],
    "cloud_provider_tags": [ "<string>", "<string>" ],
    "cluster_name": [ "<string>", "<string>" ],
    "compliance_status": [ "<string>", "<string>" ],
    "datacenter_name": [ "<string>", "<string>" ],
    "deployment_type": [ "<string>", "<string>" ],
    "esx_host_name": [ "<string>", "<string>" ],
    "golden_device_id": [ "<string>", "<string>" ],
    "golden_device_status": [ "<string>", "<string>" ],
    "asset_group_id": [ "<string>", "<string>" ],
    "asset_group_name": [ "<string>", "<string>" ],
    "host_based_firewall_status": [ "<string>", "<string>" ],
    "id": [ <long>, <long> ],
    "infrastructure_provider": [ "<string>", "<string>" ],
    "last_contact_time": {
      "end": "<string>",
      "range": "<string>",
      "start": "<string>"
    },
    "os": [ "<string>", "<string>" ],
    "os_version": [ "<string>", "<string>" ],
    "policy_id": [ <long>, <long> ],
    "sensor_gateway_url": [ "<string>", "<string>" ],
    "sensor_version": [ "<string>", "<string>" ],
    "signature_status": [ "<string>", "<string>" ],
    "status": [ "<string>", "<string>" ],
    "sub_deployment_type": [ "<string>", "<string>" ],
    "subnet": [ "<string>", "<string>" ],
    "target_priority": [ "<string>", "<string>" ],
    "vcenter_host_url": [ "<string>", "<string>" ],
    "vcenter_name": [ "<string>", "<string>" ],
    "vcenter_uuid": [ "<string>", "<string>" ],
    "virtual_private_cloud_id": [ "<string>", "<string>" ],
    "virtualization_provider": [ "<string>", "<string>" ],
    "vm_uuid": [ "<string>", "<string>" ]
  },
  "exclusions": {
    "sensor_version": [ "<string>", "<string>" ]
  },
  "query": "<string>",
  "rows": <long>,
  "search_after": "<string>"
}

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_distinguished_name, ad_domain, ad_group_id, ad_org_unit, auto_scaling_group_name, base_device, cloud_provider_account_id, cloud_provider_managed_identity, cloud_provider_network, cloud_provider_resource_group, cloud_provider_resource_id, cloud_provider_scale_group, cloud_provider_tags, cluster_name, compliance_status, datacenter_name, deployment_type, esx_host_name, golden_device_id, golden_device_status, asset_group_id, asset_group_name, host_based_firewall_status, id, infrastructure_provider, last_contact_time, os, os_version, policy_id, sensor_gateway_url, sensor_version, signature_status, status, sub_deployment_type, subnet, target_priority, vcenter_host_url, vcenter_name, vcenter_uuid, virtual_private_cloud_id, virtualization_provider, vm_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
rows Maximum number of rows to return. Integer Default: 20
Max: 10k
search_after The offset to indicate current progress through the results.

Note: search_after only required on subsequent calls to fetch remaining results		 String

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 Scroll 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
500 Internal Server Error N/A

Examples

Request 
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_scroll
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "deployment_type": ["AWS", "AZURE", "GCP"],
    "last_contact_time": {
      "start": "2023-10-01T00:00:00.000Z",
      "end": "2023-11-21T00:00:00.000Z"
    },
    "target_priority": ["MEDIUM", "LOW"]
  },
  "query": "os:WINDOWS",
  "rows": 100
}
Response Body 
{
    "num_found": 12,
    "num_remaining": 0,
    "search_after": "MTk5NjEwMTY=",
    "results": [
        {
            "activation_code": null,
            "activation_code_expiry_time": "2022-03-30T11:06:49.536Z",
            "ad_domain": null,
            "ad_group_id": 0,
            "ad_org_unit": null,
            "appliance_name": null,
            "appliance_uuid": null,
            "auto_scaling_group_name": null,
            "av_ave_version": "8.3.66.52",
            "av_engine": "4.15.1.560-ave.8.3.66.52:avpack.8.5.2.114:vdf.8.19.36.68:vdfdate.20230310",
            "av_last_scan_time": null,
            "av_master": false,
            "av_pack_version": "8.5.2.114",
            "av_product_version": "4.15.1.560",
            "av_status": [
                "AV_BYPASS"
            ],
            "av_update_servers": null,
            "av_vdf_version": "8.19.36.68",
            "base_device": null,
            "cloud_provider_account_id": null,
            "cloud_provider_resource_id": null,
            "cloud_provider_tags": [],
            "cloud_provider_resource_group": null,
            "cloud_provider_scale_group": null,
            "cloud_provider_network": null,
            "cloud_provider_managed_identity": null,
            "cluster_name": null,
            "compliance_status": "NOT_ASSESSED",
            "current_sensor_policy_name": "Standard",
            "policy_override": true,
            "quarantined": false,
            "datacenter_name": null,
            "deployment_type": "AWS",
            "deregistered_time": null,
            "device_meta_data_item_list": [
                {
                    "key_name": "OS_MAJOR_VERSION",
                    "key_value": "Windows 10",
                    "position": 0
                },
                {
                    "key_name": "SUBNET",
                    "key_value": "111.22.33.4",
                    "position": 0
                }
            ],
            "device_owner_id": 15413968,
            "email": "",
            "esx_host_name": null,
            "esx_host_uuid": null,
            "first_name": null,
            "golden_device": null,
            "golden_device_id": null,
            "asset_group": [
              {
                "id": "fb32fcc1-3bfe-4945-9b6a-46a5049856cd",
                "name": "test",
                "membership_type": "DYNAMIC"
              }
            ],
            "host_based_firewall_reasons": [],
            "host_based_firewall_status": null,
            "id": 16554343,
            "infrastructure_provider": "NONE",
            "last_contact_time": "2023-11-20T19:36:57.351Z",
            "last_device_policy_changed_time": "2023-03-10T04:00:51.188Z",
            "last_device_policy_requested_time": "2023-10-26T20:14:33.773Z",
            "last_external_ip_address": "12.34.4.56",
            "last_internal_ip_address": "123.45.67.89",
            "last_location": "OFFSITE",
            "last_name": null,
            "last_reported_time": "2023-11-20T19:27:46.387Z",
            "last_reset_time": null,
            "last_shutdown_time": "2023-04-03T04:03:30.867Z",
            "linux_kernel_version": null,
            "login_user_name": "EC2AMAZ-123456\\Administrator",
            "mac_address": "0a2111f3bd35",
            "middle_name": null,
            "name": "EC2AMAZ-123456",
            "nsx_distributed_firewall_policy": null,
            "nsx_enabled": null,
            "organization_id": 3710476,
            "organization_name": "myorg.com",
            "os": "WINDOWS",
            "os_version": "Windows Server 2019 x64 SP: 0",
            "passive_mode": false,
            "policy_id": 20440908,
            "policy_name": "Standard",
            "registered_time": "2022-05-30T12:23:29.364Z",
            "scan_last_action_time": null,
            "scan_last_complete_time": null,
            "scan_status": null,
            "sensor_gateway_url": null,
            "sensor_gateway_uuid": null,
            "sensor_kit_type": "WINDOWS",
            "sensor_out_of_date": true,
            "sensor_pending_update": false,
            "sensor_states": [
                "ACTIVE",
                "LIVE_RESPONSE_NOT_RUNNING",
                "LIVE_RESPONSE_NOT_KILLED",
                "LIVE_RESPONSE_DISABLED"
            ],
            "sensor_version": "3.8.0.535",
            "status": "REGISTERED",
            "target_priority": "LOW",
            "uninstall_code": "K9PDWRD4",
            "vcenter_host_url": null,
            "vcenter_name": null,
            "vcenter_uuid": null,
            "vdi_base_device": null,
            "vdi_provider": "NONE",
            "virtual_machine": true,
            "virtual_private_cloud_id": null,
            "virtualization_provider": "AWS_EC2",
            "vm_ip": null,
            "vm_name": null,
            "vm_uuid": null,
            "vulnerability_score": 10,
            "vulnerability_severity": "CRITICAL",
            "windows_platform": null,
            "last_policy_updated_time": null
        },
        ... truncated ...
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_scroll \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "deployment_type": ["AWS", "AZURE", "GCP"],
    "last_contact_time": {
      "start": "2023-10-01T00:00:00.000Z",
      "end": "2023-11-21T00:00:00.000Z"
    },
    "target_priority": ["MEDIUM", "LOW"]
  },
  "query": "os:WINDOWS",
  "rows": 100
}'
Response Body 
{
    "num_found": 12,
    "num_remaining": 0,
    "search_after": "MTk5NjEwMTY=",
    "results": [
        {
            "activation_code": null,
            "activation_code_expiry_time": "2022-03-30T11:06:49.536Z",
            "ad_domain": null,
            "ad_group_id": 0,
            "ad_org_unit": null,
            "appliance_name": null,
            "appliance_uuid": null,
            "auto_scaling_group_name": null,
            "av_ave_version": "8.3.66.52",
            "av_engine": "4.15.1.560-ave.8.3.66.52:avpack.8.5.2.114:vdf.8.19.36.68:vdfdate.20230310",
            "av_last_scan_time": null,
            "av_master": false,
            "av_pack_version": "8.5.2.114",
            "av_product_version": "4.15.1.560",
            "av_status": [
                "AV_BYPASS"
            ],
            "av_update_servers": null,
            "av_vdf_version": "8.19.36.68",
            "base_device": null,
            "cloud_provider_account_id": null,
            "cloud_provider_resource_id": null,
            "cloud_provider_tags": [],
            "cloud_provider_resource_group": null,
            "cloud_provider_scale_group": null,
            "cloud_provider_network": null,
            "cloud_provider_managed_identity": null,
            "cluster_name": null,
            "compliance_status": "NOT_ASSESSED",
            "current_sensor_policy_name": "Standard",
            "policy_override": true,
            "quarantined": false,
            "datacenter_name": null,
            "deployment_type": "AWS",
            "deregistered_time": null,
            "device_meta_data_item_list": [
                {
                    "key_name": "OS_MAJOR_VERSION",
                    "key_value": "Windows 10",
                    "position": 0
                },
                {
                    "key_name": "SUBNET",
                    "key_value": "111.22.33.4",
                    "position": 0
                }
            ],
            "device_owner_id": 15413968,
            "email": "",
            "esx_host_name": null,
            "esx_host_uuid": null,
            "first_name": null,
            "golden_device": null,
            "golden_device_id": null,
            "asset_group": [
              {
                "id": "fb32fcc1-3bfe-4945-9b6a-46a5049856cd",
                "name": "test",
                "membership_type": "DYNAMIC"
              }
            ],
            "host_based_firewall_reasons": [],
            "host_based_firewall_status": null,
            "id": 16554343,
            "infrastructure_provider": "NONE",
            "last_contact_time": "2023-11-20T19:36:57.351Z",
            "last_device_policy_changed_time": "2023-03-10T04:00:51.188Z",
            "last_device_policy_requested_time": "2023-10-26T20:14:33.773Z",
            "last_external_ip_address": "12.34.4.56",
            "last_internal_ip_address": "123.45.67.89",
            "last_location": "OFFSITE",
            "last_name": null,
            "last_reported_time": "2023-11-20T19:27:46.387Z",
            "last_reset_time": null,
            "last_shutdown_time": "2023-04-03T04:03:30.867Z",
            "linux_kernel_version": null,
            "login_user_name": "EC2AMAZ-123456\\Administrator",
            "mac_address": "0a2111f3bd35",
            "middle_name": null,
            "name": "EC2AMAZ-123456",
            "nsx_distributed_firewall_policy": null,
            "nsx_enabled": null,
            "organization_id": 3710476,
            "organization_name": "myorg.com",
            "os": "WINDOWS",
            "os_version": "Windows Server 2019 x64 SP: 0",
            "passive_mode": false,
            "policy_id": 20440908,
            "policy_name": "Standard",
            "registered_time": "2022-05-30T12:23:29.364Z",
            "scan_last_action_time": null,
            "scan_last_complete_time": null,
            "scan_status": null,
            "sensor_gateway_url": null,
            "sensor_gateway_uuid": null,
            "sensor_kit_type": "WINDOWS",
            "sensor_out_of_date": true,
            "sensor_pending_update": false,
            "sensor_states": [
                "ACTIVE",
                "LIVE_RESPONSE_NOT_RUNNING",
                "LIVE_RESPONSE_NOT_KILLED",
                "LIVE_RESPONSE_DISABLED"
            ],
            "sensor_version": "3.8.0.535",
            "status": "REGISTERED",
            "target_priority": "LOW",
            "uninstall_code": "K9PDWRD4",
            "vcenter_host_url": null,
            "vcenter_name": null,
            "vcenter_uuid": null,
            "vdi_base_device": null,
            "vdi_provider": "NONE",
            "virtual_machine": true,
            "virtual_private_cloud_id": null,
            "virtualization_provider": "AWS_EC2",
            "vm_ip": null,
            "vm_name": null,
            "vm_uuid": null,
            "vulnerability_score": 10,
            "vulnerability_severity": "CRITICAL",
            "windows_platform": null,
            "last_policy_updated_time": null
        },
        ... truncated ...
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Devices

Warning: groups is in the process of being renamed to asset_group. The asset group properties id, name. and membership_type in the response will not change only the groups parent name will change to asset_group. If you need to search by an asset group property in the criteria or the query use groups_id or groups_name when the new name is released there will be a short period where both asset_group_id, asset_group_name, groups_id, and groups_name will be supported. The dual support will only last a couple weeks so make the transition quickly. Additional details will be included in the Carbon Black Cloud Release Notes.

Warning: The response format will change to a json response as documented however currently it returns a single json string.

Export devices in your organization using the job service.

To receive the actual JSON or CSV results, you need to use the Job Service API. First, use the Get Job Details to get the status of the async job, then Download Job Output call to download the actual content.

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/_export

Request Body 

{
  "criteria": {
    "ad_distinguished_name": [ "<string>", "<string>" ],
    "ad_domain": [ "<string>", "<string>" ],
    "ad_group_id": [ <long>, <long> ],
    "ad_org_unit": [ "<string>", "<string>" ],
    "auto_scaling_group_name": [ "<string>", "<string>" ],
    "base_device": <boolean>,
    "cloud_provider_account_id": [ "<string>", "<string>" ],
    "cloud_provider_managed_identity": [ "<string>", "<string>" ],
    "cloud_provider_network": [ "<string>", "<string>" ],
    "cloud_provider_resource_group": [ "<string>", "<string>" ],
    "cloud_provider_resource_id": [ "<string>", "<string>" ],
    "cloud_provider_scale_group": [ "<string>", "<string>" ],
    "cloud_provider_tags": [ "<string>", "<string>" ],
    "cluster_name": [ "<string>", "<string>" ],
    "compliance_status": [ "<string>", "<string>" ],
    "datacenter_name": [ "<string>", "<string>" ],
    "deployment_type": [ "<string>", "<string>" ],
    "esx_host_name": [ "<string>", "<string>" ],
    "golden_device_id": [ "<string>", "<string>" ],
    "golden_device_status": [ "<string>", "<string>" ],
    "asset_group_id": [ "<string>", "<string>" ],
    "asset_group_name": [ "<string>", "<string>" ],
    "host_based_firewall_status": [ "<string>", "<string>" ],
    "id": [ <long>, <long> ],
    "infrastructure_provider": [ "<string>", "<string>" ],
    "last_contact_time": {
      "end": "<string>",
      "range": "<string>",
      "start": "<string>"
    },
    "os": [ "<string>", "<string>" ],
    "os_version": [ "<string>", "<string>" ],
    "policy_id": [ <long>, <long> ],
    "sensor_gateway_url": [ "<string>", "<string>" ],
    "sensor_version": [ "<string>", "<string>" ],
    "signature_status": [ "<string>", "<string>" ],
    "status": [ "<string>", "<string>" ],
    "sub_deployment_type": [ "<string>", "<string>" ],
    "subnet": [ "<string>", "<string>" ],
    "target_priority": [ "<string>", "<string>" ],
    "vcenter_host_url": [ "<string>", "<string>" ],
    "vcenter_name": [ "<string>", "<string>" ],
    "vcenter_uuid": [ "<string>", "<string>" ],
    "virtual_private_cloud_id": [ "<string>", "<string>" ],
    "virtualization_provider": [ "<string>", "<string>" ],
    "vm_uuid": [ "<string>", "<string>" ]
  },
  "exclusions": {
    "sensor_version": [
      "<string>"
    ]
  },
  "format":  "<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_distinguished_name, ad_domain, ad_group_id, ad_org_unit, auto_scaling_group_name, base_device, cloud_provider_account_id, cloud_provider_managed_identity, cloud_provider_network, cloud_provider_resource_group, cloud_provider_resource_id, cloud_provider_scale_group, cloud_provider_tags, cluster_name, compliance_status, datacenter_name, deployment_type, esx_host_name, golden_device_id, golden_device_status, asset_group_id, asset_group_name, host_based_firewall_status, id, infrastructure_provider, last_contact_time, os, os_version, policy_id, sensor_gateway_url, sensor_version, signature_status, status, sub_deployment_type, subnet, target_priority, vcenter_host_url, vcenter_name, vcenter_uuid, virtual_private_cloud_id, virtualization_provider, vm_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:#.#.#.#
format The format of the export String CSV, or JSON
query Query in lucene syntax and/or including value searches. String
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
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
303 Successful Export 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
500 Internal Server Error N/A

Examples

Request 
POST https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_export
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "deployment_type": ["ENDPOINT"],
    "target_priority": ["MEDIUM"],
    "last_contact_time": {
        "start": "2023-10-01T00:00:00.000Z",
        "end": "2023-11-22T00:00:00.000Z"
      }
  },
  "format": "CSV",
  "rows": 5,
  "start": 0,
  "sort": [
    {
      "field": "av_pack_version",
      "order": "ASC"
    }
  ]
}
Response
Status 
303 See Other
Header 
Location: /jobs/v1/orgs/ABCD1234/jobs/5865983
Body 
{
  "job_id": 5865983
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_export \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "deployment_type": ["ENDPOINT"],
    "target_priority": ["MEDIUM"],
    "last_contact_time": {
        "start": "2023-10-01T00:00:00.000Z",
        "end": "2023-11-22T00:00:00.000Z"
    }
  },
  "rows": 5,
  "start": 0,
  "sort": [{
    "field": "av_pack_version",
    "order": "ASC"
  }]
}'
Response
Status 
303 See Other
Header 
Location: /jobs/v1/orgs/ABCD1234/jobs/5865983
Body 
{
  "job_id": 5865983
}
To download or review the Carbon Black Cloud Postman collection, click here.

Sample CSV

Note: If new properties are added they will be suffixed to the end of the row and the new field names will be added to the csv header. For more information on the properties see Fields.

device_id,ad_group_id,ad_org_unit,ad_domain,ad_distinguished_name,subnet,appliance_uuid,auto_scaling_group_name,cloud_provider_scale_group,av_ave_version,av_engine,av_pack_version,av_product_version,av_status,av_vdf_version,av_last_scan_time,av_master,cloud_provider_account_id,cloud_provider_resource_id,cloud_provider_tags,cloud_provider_resource_group,cloud_provider_network,cloud_provider_managed_identity,cluster_name,compliance_status,current_sensor_policy_name,datacenter_name,device_owner_id,deployment_type,email,esx_host_name,esx_host_uuid,name,first_name,middle_name,last_name,golden_device_id,golden_device,asset_group_id,asset_group_name,asset_group_membership_type,host_based_firewall_reasons,host_based_firewall_status,infrastructure_provider,last_external_ip_address,last_internal_ip_address,last_location,login_user_name,mac_address,nsx_distributed_firewall_policy,os,os_version,organization_id,organization_name,policy_id,policy_name,registered_time,scan_status,scan_last_action_time,scan_last_complete_time,sensor_gateway_url,sensor_gateway_uuid,sensor_kit_type,sensor_states,sensor_version,status,sub_deployment_type,target_priority,vcenter_host_url,vcenter_name,vcenter_uuid,vdi_provider,virtual_private_cloud_id,virtualization_provider,vm_ip,vm_name,vm_uuid,vulnerability_severity,vulnerability_score,vdi_base_device,deregistered_time,last_policy_changed_time,last_policy_requested_time,last_reported_time,last_reset_time,last_shutdown_time,last_contact_time,virtual_machine,sensor_out_of_date,sensor_pending_update,policy_override,quarantined,passive_mode,base_device,nsx_enabled,windows_platform
16554343,0,,,,123.45.67.78,,,,8.3.66.52,4.15.1.560-ave.8.3.66.52:avpack.8.5.2.114:vdf.8.19.36.68:vdfdate.20230310,8.5.2.114,4.15.1.560,AV_BYPASS,8.19.36.68,,false,,,,,,,,NOT_ASSESSED,Standard,,15413968,AWS,,,,EC2AMAZ-D6C29FF,,,,,,,,,,,NONE,12.34.56.78,123.45.67.89,OFFSITE,DESKTOP-JOHNDOE\test,0a2111f3bd35,,WINDOWS,Windows Server 2019 x64 SP: 0,3710476,myorg.com,20440908,Standard,2022-05-30T12:23:29.364Z,,,,,,WINDOWS,"ACTIVE,LIVE_RESPONSE_NOT_RUNNING,LIVE_RESPONSE_NOT_KILLED,LIVE_RESPONSE_DISABLED",3.8.0.535,REGISTERED,AWS_VIRTUAL_MACHINE_EC2,LOW,,,,NONE,,AWS_EC2,,,,CRITICAL,10,,,2023-03-10T04:00:51.188Z,2023-10-26T20:14:33.773Z,2023-12-01T22:35:16.549Z,,2023-04-03T04:03:30.867Z,2023-12-01T22:38:55.143Z,true,true,false,true,false,false,,,

Legacy Export Devices (CSV)

Deprecated: This has been replaced by Export Devices

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
auto_scaling_group_name Public Cloud (AWS) auto scaling group name to match. String
av_vdf_version Scan engine version to match. String
cloud_provider_account_id Public Cloud account id to match. String
cloud_provider_resource_id Public Cloud Resource Id to match. String
cloud_provider_tags Public Cloud Tags to match. String
deployment_type The device’s deployment type, a classification that is determined by its lifecycle management policy. String ENDPOINT, WORKLOAD, VDI, AWS, AZURE, GCP
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
policy_id Carbon Black Cloud Policy ID to match. Integer
query_string Device value search query string. String
sensor_verion Sensor version to match. String
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
virtual_private_cloud_id Virtual private cloud id to match. String
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
500 Internal Server Error N/A

Example

Request

GET https://defense-prod05.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_search/download?status=active

Response

name,loginUserName,firstName,lastName,middleName,targetValue,status,registeredTime,deregisteredTime,lastContactTime,lastInternalIpAddress,lastExternalIpAddress,deviceType,policyName,windowsPlatform,osVersion,sensorVersion,avEngine,virtualMachine,virtualizationProvider,subDeploymentType,macAddress,avVdfVersion,vcenterHostName,quarantined,sensorPendingUpdate,sensorOutOfDate,hostBasedFirewallStatus,hostBasedFirewallReasons,sensorGatewayUrl,groupName,deviceId
"DESKTOP-JOHNDOE","DESKTOP-JOHNDOE\test","","","","MEDIUM","REGISTERED","2023-11-03-190500","","2023-11-03-190625","192.168.45.123","","WINDOWS","default","","Windows 11 x64","3.9.2.2698","",true,"VMW_WS","","000c299e25ca","","",false,false,false,"NOT_ENABLED","","","Window Workloads",7521563

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
500 Internal Server Error N/A

Example

Request

GET https://defense-prod05.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/6697317

Response 

{
  "activation_code": null,
  "activation_code_expiry_time": "2023-03-06T23:29:12.836Z",
  "ad_domain": [
      "MYDOMAIN.LOCAL"
  ],
  "ad_group_id": 0,
  "ad_org_unit": null,
  "appliance_name": null,
  "appliance_uuid": null,
  "asset_group": [
      {
          "id": "3b75bf21-b696-45fd-9938-88e69f2e1290",
          "name": "My Example Asset Group",
          "membership_type": "DYNAMIC"
      },
      {
          "id": "34fc5890-caf0-400a-98ba-a81763960f6e",
          "name": "Windows No Policy",
          "membership_type": "DYNAMIC"
      }
  ],
  "auto_scaling_group_name": null,
  "av_ave_version": null,
  "av_engine": null,
  "av_last_scan_time": null,
  "av_master": false,
  "av_pack_version": null,
  "av_product_version": null,
  "av_status": [
      "AV_ACTIVE",
      "SIGNATURE_UPDATE_DISABLED",
      "ONDEMAND_SCAN_DISABLED"
  ],
  "av_update_servers": null,
  "av_vdf_version": null,
  "base_device": null,
  "cloud_provider_account_id": null,
  "cloud_provider_resource_id": null,
  "cloud_provider_tags": [],
  "cloud_provider_resource_group": null,
  "cloud_provider_scale_group": null,
  "cloud_provider_network": null,
  "cloud_provider_managed_identity": null,
  "cluster_name": null,
  "compliance_status": "NOT_ASSESSED",
  "current_sensor_policy_name": "default",
  "policy_override": true,
  "quarantined": false,
  "datacenter_name": null,
  "deployment_type": "AWS",
  "deregistered_time": null,
  "device_meta_data_item_list": [
      {
          "key_name": "OS_MAJOR_VERSION",
          "key_value": "Windows 10",
          "position": 0
      },
      {
          "key_name": "AD_LDAP",
          "key_value": "DC=mydomain,DC=local",
          "position": 0
      },
      {
          "key_name": "SUBNET",
          "key_value": "192.168.14.0",
          "position": 0
      }
  ],
  "device_owner_id": 922791,
  "email": "pepper",
  "esx_host_name": null,
  "esx_host_uuid": null,
  "first_name": null,
  "golden_device": null,
  "golden_device_id": null,
  "host_based_firewall_reasons": [],
  "host_based_firewall_status": null,
  "id": 6697317,
  "infrastructure_provider": "NONE",
  "last_contact_time": "2024-03-11T16:54:59.462Z",
  "last_device_policy_changed_time": "2024-02-01T15:06:32.697Z",
  "last_device_policy_requested_time": "2024-02-26T11:12:05.537Z",
  "last_external_ip_address": "52.53.54.55",
  "last_internal_ip_address": "192.168.14.210",
  "last_location": "OFFSITE",
  "last_name": null,
  "last_reported_time": "2024-03-11T11:40:07.183Z",
  "last_reset_time": null,
  "last_shutdown_time": null,
  "linux_kernel_version": null,
  "login_user_name": "MYDOMAIN\\awsadmin",
  "mac_address": "06fc3cc4dad9",
  "middle_name": null,
  "name": "DOMAIN\\pepper",
  "nsx_distributed_firewall_policy": null,
  "nsx_enabled": null,
  "organization_id": 1105,
  "organization_name": "cb-internal-alliances.com",
  "os": "WINDOWS",
  "os_version": "Windows Server 2019 x64",
  "passive_mode": false,
  "policy_assignment_type": "MANUAL",
  "policy_id": 6525,
  "policy_name": "default",
  "registered_time": "2023-02-27T23:29:12.868Z",
  "scan_last_action_time": null,
  "scan_last_complete_time": null,
  "scan_status": null,
  "sensor_gateway_url": null,
  "sensor_gateway_uuid": null,
  "sensor_kit_type": "WINDOWS",
  "sensor_out_of_date": true,
  "sensor_pending_update": false,
  "sensor_states": [
      "ACTIVE",
      "LIVE_RESPONSE_NOT_RUNNING",
      "LIVE_RESPONSE_NOT_KILLED",
      "LIVE_RESPONSE_ENABLED"
  ],
  "sensor_version": "3.8.0.722",
  "status": "REGISTERED",
  "target_priority": "MEDIUM",
  "uninstall_code": "CJLSKPDME",
  "vcenter_host_url": null,
  "vcenter_name": null,
  "vcenter_uuid": null,
  "vdi_base_device": null,
  "vdi_provider": "NONE",
  "virtual_machine": true,
  "virtual_private_cloud_id": null,
  "virtualization_provider": "AWS_EC2",
  "vm_ip": null,
  "vm_name": null,
  "vm_uuid": null,
  "vulnerability_score": 10,
  "vulnerability_severity": "CRITICAL",
  "windows_platform": null,
  "last_policy_updated_time": "2024-02-26T11:10:53.674Z"
}


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_distinguished_name": [ "<string>", "<string>" ],
    "ad_domain": [ "<string>", "<string>" ],
    "ad_group_id": [ <long>, <long> ],
    "ad_org_unit": [ "<string>", "<string>" ],
    "auto_scaling_group_name": [ "<string>", "<string>" ],
    "base_device": <boolean>,
    "cloud_provider_account_id": [ "<string>", "<string>" ],
    "cloud_provider_managed_identity": [ "<string>", "<string>" ],
    "cloud_provider_network": [ "<string>", "<string>" ],
    "cloud_provider_resource_group": [ "<string>", "<string>" ],
    "cloud_provider_resource_id": [ "<string>", "<string>" ],
    "cloud_provider_scale_group": [ "<string>", "<string>" ],
    "cloud_provider_tags": [ "<string>", "<string>" ],
    "cluster_name": [ "<string>", "<string>" ],
    "compliance_status": [ "<string>", "<string>" ],
    "datacenter_name": [ "<string>", "<string>" ],
    "deployment_type": [ "<string>", "<string>" ],
    "esx_host_name": [ "<string>", "<string>" ],
    "golden_device_id": [ "<string>", "<string>" ],
    "golden_device_status": [ "<string>", "<string>" ],
    "asset_group_id": [ "<string>", "<string>" ],
    "asset_group_name": [ "<string>", "<string>" ],
    "host_based_firewall_status": [ "<string>", "<string>" ],
    "id": [ <long>, <long> ],
    "infrastructure_provider": [ "<string>", "<string>" ],
    "last_contact_time": {
      "end": "<string>",
      "range": "<string>",
      "start": "<string>"
    },
    "os": [ "<string>", "<string>" ],
    "os_version": [ "<string>", "<string>" ],
    "policy_id": [ <long>, <long> ],
    "sensor_gateway_url": [ "<string>", "<string>" ],
    "sensor_version": [ "<string>", "<string>" ],
    "signature_status": [ "<string>", "<string>" ],
    "status": [ "<string>", "<string>" ],
    "sub_deployment_type": [ "<string>", "<string>" ],
    "subnet": [ "<string>", "<string>" ],
    "target_priority": [ "<string>", "<string>" ],
    "vcenter_host_url": [ "<string>", "<string>" ],
    "vcenter_name": [ "<string>", "<string>" ],
    "vcenter_uuid": [ "<string>", "<string>" ],
    "virtual_private_cloud_id": [ "<string>", "<string>" ],
    "virtualization_provider": [ "<string>", "<string>" ],
    "vm_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.

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_distinguished_name, ad_domain, ad_group_id, ad_org_unit, auto_scaling_group_name, base_device, cloud_provider_account_id, cloud_provider_managed_identity, cloud_provider_network, cloud_provider_resource_group, cloud_provider_resource_id, cloud_provider_scale_group, cloud_provider_tags, cluster_name, compliance_status, datacenter_name, deployment_type, esx_host_name, golden_device_id, golden_device_status, asset_group_id, asset_group_name, host_based_firewall_status, id, infrastructure_provider, last_contact_time, os, os_version, policy_id, sensor_gateway_url, sensor_version, signature_status, status, sub_deployment_type, subnet, target_priority, vcenter_host_url, vcenter_name, vcenter_uuid, virtual_private_cloud_id, virtualization_provider, vm_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
terms The events fields to facet and how many of the top entries to return.

Note: asset_group_name may return a facet value of None which identifies Devices that are not in an asset group.		 Object 
{
  "fields": [
    "STATUS"
  ],
  "rows": 100
}
Supported Fields: ad_distinguished_name, ad_domain, ad_org_unit, ad_group_id, asset_group_id, asset_group_name, auto_scaling_group_name, cloud_provider_account_id, cloud_provider_tags, cloud_provider_scale_group, cloud_provider_managed_identity, cloud_provider_resource_id, cloud_provider_resource_group, cloud_provider_network, compliance_status, cluster_name, datacenter_name, esx_host_name, golden_device_id, golden_device_status, host_based_firewall_status, infrastructure_provider, os, os_version, policy_id, sensor_gateway_url, sensor_version, signature_status, status, sub_deployment_type, subnet, vcenter_name, vcenter_host_url, vcenter_uuid, 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
500 Internal Server Error 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",
                    "asset_group_name" ]
    }
}

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"
                }
            ]
        },
        {
            "field": "asset_group_name",
            "values": [
                {
                "total": 2,
                "id": "demo_asset_group",
                "name": "demo_asset_group"
                },
                {
                "total": 5,
                "id": "Domain Controllers",
                "name": "Domain Controllers"
                },
                {
                "total": 3,
                "id": "another_example_group",
                "name": "another_example_group"
                },
                {
                "total": 2,
                "id": "None",
                "name": "None"
                }
            ]
        }
    ]
}


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.execute QUARANTINE
_API.Device:device.Bypass.execute BYPASS
_API.Device:device.Bg-Scan.execute BACKGROUND_SCAN
_API.Device:device.Policy.update UPDATE_POLICY
_API.Device:org.Kits.execute UPDATE_SENSOR_VERSION
_API.Device:device.Uninstall.execute 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 have a manual override to this policy ID.

Either options.policy_id or options.auto_assign is required if action_type is set to UPDATE_POLICY		 Integer
options.auto_assign When true, Devices will be automatically assigned to the policy configured with their associated Asset Group or use the default policy if no Asset Group is associated. Auto assignment will remove any existing manual override.

Note: Auto assign will be set to false when a manual override is used to apply a policy.

Either options.policy_id or options.auto_assign is required if action_type is set to UPDATE_POLICY		 Boolean
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
500 Internal Server Error N/A

Response

Response Code: 204

Quarantine

Note: Linux sensor supported on version 2.13 or later. MacOS and Windows supported on all versions.

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
deployment_type Classification that is determined by the lifecycle management policy of the device. String ENDPOINT, WORKLOAD, VDI, AWS, AZURE, GCP
device_meta_data_item_list A list of attributes that describe the device. List 
[{
    "key_name": "string",
    "key_value": "string",
    "position": 0
}]
asset_group The asset groups the device has been assigned. Array 
[
    {
        "id": "e6a9471f-2150-4c29-9634-b0763a4dd71d",
        "name": "MyGroup",
        "membership_type": "DYNAMIC"
    }
]
host_based_firewall_reasons The list of host based firewall errors or warnings Array
host_based_firewall_status The last reported status of the host based firewall on the device. String ACTIVE, ERRORS, NOT_ENABLED, WARNING
id The identifier for the device. Integer
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 any of metadata of the device is changed - e.g. name, email, status, etc. 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
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
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
name Hostname of the endpoint recorded by the sensor when last initialized. String
organization_id Organization identifier. Integer
organization_name Organization name. String
os Operating System. String WINDOWS, MAC, LINUX, OTHER
os_version The operating system and version of the endpoint. String
passive_mode Whether the device is in bypass. Boolean
policy_id The policy identifier assigned to the device. Integer
policy_name The policy name assigned to the device. May not match current_sensor_policy_name until the sensor checks back in. String
quarantined An indicator that the device is in quarantine mode. Boolean
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
sensor_pending_update Whether the sensor is marked by the Sensor Update Service for a sensor upgrade. Boolean
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
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_domain The list of Active Directory domain components Array
ad_group_id Sensor Group ID if sensor assigned to a group, 0 otherwise. Integer
ad_org_unit The list of organizational units in Active Directory Array
policy_override Whether the policy was manually assigned to override mass sensor management. Boolean

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
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
email The email address for the device owner. String
first_name The first name of the device owner. String
encoded_activation_code Encoded activation code. String
last_name The last name of the device owner. String
middle_name The middle name of the device owner. String
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

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
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
av_pack_version Pack version (part of AV Version) String
av_product_version Product version (part of AV Version) String
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

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
appliance_uuid The Uuid of the appliance the VM is associated with. String
base_device Indicates if the device is a base device for other clones. Boolean
cluster_name Name of the cluster. A cluster is a group of hosts. String
compliance_status Indicates whether WORKLOAD has been assessed for compliance. String ASSESSED, NOT_ASSESSED
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
esx_host_name Name of the ESX host on which the VM is deployed. String
esx_host_uuid Uuid of the ESX host on which VM is deployed. String
golden_device Shows if device is Golden VM for any VDI clone. Boolean
golden_device_id Device Id for golden VM. Integer
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
sensor_gateway_url The sensor gateway url assigned to the WORKLOAD. String
sensor_gateway_uuid The sensor gateway uuid assigned to the WORKLOAD. String
vcenter_host_url The URL of the vcenter the vm is associated with String
vcenter_name Name of the vcenter the vm is associated with. String
vcenter_uuid 128-bit SMBIOS UUID of a vcenter represented as a hexadecimal string. String
vdi_base_device The identifier of the device from which this device was cloned/re-registered. Integer
vdi_provider The provider that hosts the VDI. String HORIZON, CITRIX, NONE
virtual_machine Whether this device is a Virtual Machine (VMware AppDefense integration)

Deprecated for deployment_type		 Boolean
virtual_private_cloud_id The ID of the virtual cloud provider. String
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
vm_name Name of the Virtual Machine that the sensor is deployed on. String
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
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. Deprecated: Use cloud_provider_scale_group String
cloud_provider_account_id The ID of the public cloud account associated with the WORKLOAD. String
cloud_provider_resource_id The ID of the WORKLOAD in the public cloud. String
cloud_provider_tags The tags associated with the WORKLOAD in the public cloud Array
cloud_provider_resource_group The resource group associated with the WORKLOAD. String
cloud_provider_scale_group The scaling group name associated with the WORKLOAD. String
cloud_provider_network The network name associated with the WORKLOAD. String
cloud_provider_managed_identity The managed identity associated with the WORKLOAD. String
infrastructure_provider The cloud infrastructure that hosts the WORKLOAD. String AWS, AZURE, GCP, None

Give Feedback

New survey coming soon!


Last modified on March 25, 2024