Device Control API


Overview

The Device Control API lets you view, manage, approve and implement blocking policies across your organization for external USB storage devices. This gives IT and Security Operations administrators direct access to the external devices in their environment to change how those devices can operate.

The initial implementation of Device Control blocks ALL operations on any external device. In December 2023 it as enhanced to separate read, write and execute permissions on Windows endpoints. Users can determine whether a device should be approved for read-only, read and write, read and execute, or read and write and execute.

Use Cases

  • Retrieve an inventory of external devices and their associated metadata within an organization
  • Search for a specific external device and its associated metadata
  • Create an approval for an external device, set of devices, or for specific vendor and product models
  • Modify the the combination of read, write and execute actions an approved device can perform per policy
  • Cross reference additional external device data after an alert

Requirements

  • Carbon Black Cloud Endpoint Standard
  • Windows 3.6.0.1897 sensor or above
    • Block All (Read, write and execute) actions
  • Windows 3.9.2 sensor or above
    • Granular control of Write and Execute permissions (read and/or write and/or execute). All approved devices have permission to Readg
  • Mac 3.5.3.82 sensor or above
    • Storage device mounts are able to be blocked
  • All API calls require an API key with appropriate permissions see Authentication

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.
  • Approvals: {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/
  • Blocks: {cbc-hostname}/device_control/v3/orgs/{org_key}/blocks/
  • USB Devices: {cbc-hostname}/device_control/v3/orgs/{org_key}/devices/

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Device Control > Manage Enforcement > external-device.enforce, allow permission to UPDATE
  • Device Control > Manage External Devices > external-device.manage, allow permission to CREATE, READ, UPDATE, DELETE
  • Policies > Policies > org.policies, allow permission to CREATE, READ, UPDATE, 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.
  • Approvals: {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/
  • Blocks: {cbc-hostname}/device_control/v3/orgs/{org_key}/blocks/
  • USB Devices: {cbc-hostname}/device_control/v3/orgs/{org_key}/devices/

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.Control:external-Device.Enforce, allow permission to UPDATE
  • _API.Device.Control:external-Device.Manage, allow permission to CREATE, READ, UPDATE, DELETE
  • _API.Policies:org.Policies, allow permission to CREATE, READ, UPDATE, 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.

API calls

Approvals

Bulk Create Approvals

Create multiple USB device approvals. Supports either JSON or CSV.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage CREATE Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:create N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/_bulk

Request Body - application/json 

[
  {
    "approval_name": "string",
    "notes": "string",
    "product_id": "string",
    "serial_number": "string",
    "vendor_id": "string"
  }
]

Request Body - text/csv 

vendor_id,product_id,serial_number,approval_name,notes
string,string,string,string,string

Body Schema

Field Definition Data Type Values
approval_name The name of the approval String Max length: 150
notes Additional information that is associated with the approval String Max length: 500
product_id The hexadecimal product id of the USB device to approve String 0x5581
serial_number The serial number of the USB to approve String N/A
vendor_id The hexadecimal vendor id of the USB to approve String 0x0781

Response

Code Description Content-Type Content
200 Successfully create approvals application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/approvals/_bulk

Request_Body 

[
  {
    "vendor_id": "0x0781",
    "product_id": "0x5581",
    "serial_number": "4C531001331122115172",
    "notes": "A few notes",
    "approval_name": "Example Approval"
  }
]

Response 

{
    "results": [
        {
            "id": "10373",
            "vendor_id": "0x0781",
            "vendor_name": "SanDisk",
            "product_id": "0x5581",
            "product_name": "Ultra",
            "serial_number": "4C531001331122115172",
            "created_at": "2020-11-05T23:51:56.396425Z",
            "updated_at": "2020-11-11T23:05:42.048625Z",
            "notes": "A few notes",
            "approval_name": "Example Approval"
        }
    ]
}

Get Approval by ID

Returns a specific approval.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/{id}

Response

Code Description Content-Type Content
200 Successfully return approval application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/approvals/10373

Response 

{
    "id": "10373",
    "vendor_id": "0x0781",
    "vendor_name": "SanDisk",
    "product_id": "0x5581",
    "product_name": "Ultra",
    "serial_number": "4C531001331122115172",
    "created_at": "2020-11-05T23:51:56.396425Z",
    "updated_at": "2020-11-05T23:51:56.396425Z",
    "updated_by": "jdoe@carbonblack.com",
    "notes": "",
    "approval_name": ""
}

Search Approvals

Search for approvals using a set of criteria.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/_search

Request Body 

{
  "criteria": {
    "device.id": [
      "string"
    ],
    "product_name": [
      "string"
    ],
    "vendor_name": [
      "string"
    ]
  },
  "query": "string",
  "rows": 0,
  "start": 0
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results Object 
{
  "vendor_name": [
    "SanDisk"
  ]
}
Supported fields: device.id, vendor_name, product_name
query A plaintext value search String
rows Total records to be retrieved Integer Default: 0
start Number of records to skip before starting to return records Integer Default: 0

Response

Code Description Content-Type Content
200 Successfully return approval application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/approvals/_search

Request_Body 

{
  "criteria": {
    "vendor_name": [
      "SanDisk"
    ]
  },
  "rows": 50,
  "start": 0
}

Response 

{
    "num_found": 1,
    "num_available": 1,
    "results": [
        {
            "id": "10373",
            "vendor_id": "0x0781",
            "vendor_name": "SanDisk",
            "product_id": "0x5581",
            "product_name": "Ultra",
            "serial_number": "4C531001331122115172",
            "created_at": "2020-11-05T23:51:56.396425Z",
            "updated_at": "2020-11-11T23:05:42.048625Z",
            "notes": "A few notes",
            "approval_name": "Example Approval"
        }
    ]
}

Update Approval

Update an existing approval for a single USB device.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage UPDATE Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:update N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
PUT {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/{id}

Request Body 

{
  "approval_name": "string",
  "created_at": "string",
  "id": "string",
  "notes": "string",
  "product_id": "string",
  "product_name": "string",
  "serial_number": "string",
  "updated_at": "string",
  "updated_by": "string",
  "vendor_id": "string",
  "vendor_name": "string"
}

Body Schema

Note: These are the only mutable properties.
Field Definition Data Type Values
approval_name The name of the approval String N/A
notes Additional information that is associated with the approval String Max length: 500
product_id The hexadecimal product id of the USB device to approve String 0x5581
serial_number The serial number of the USB to approve String N/A
vendor_id The hexadecimal vendor id of the USB to approve String 0x0781

Response

Code Description Content-Type Content
200 Successfully return approval application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
409 An object exists with the serial number, vendor id, and product id combination N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/approvals/10373

Request_Body 

{
    "id": "10373",
    "vendor_id": "0x0781",
    "vendor_name": "SanDisk",
    "product_id": "0x5581",
    "product_name": "Ultra",
    "serial_number": "4C531001331122115172",
    "created_at": "2020-11-05T23:51:56.396425Z",
    "updated_at": "2020-11-05T23:51:56.396425Z",
    "updated_by": "jdoe@carbonblack.com",
    "notes": "New notes",
    "approval_name": ""
}

Response 

{
    "id": "10373",
    "vendor_id": "0x0781",
    "vendor_name": "SanDisk",
    "product_id": "0x5581",
    "product_name": "Ultra",
    "serial_number": "4C531001331122115172",
    "created_at": "2020-11-05T23:51:56.396425Z",
    "updated_at": "2020-11-05T23:51:56.396425Z",
    "updated_by": "jdoe@carbonblack.com",
    "notes": "New notes",
    "approval_name": ""
}

Delete Approval by ID

Deletes a specific approval.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage DELETE Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:delete N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
DELETE {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/{id}

Response

Code Description Content-Type Content
204 Successfully delete approval application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/approvals/10373

Response No Content


Export USB Devices Approval

Extract USB device approval data programmatically in csv or json format.

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 external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/_export

Request Body 

{
  "criteria": {
    "device.id": [
      "<string>"
    ],
    "product_name": [
      "<string>"
    ],
    "vendor_name": [
      "<string>"
    ]
  },
  "query": "<string>",
  "rows": <integer>,
  "start": <integer>,
  "format": "<string>"
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results Object 
{
  "vendor_name": [
    "SanDisk"
  ]
}
Supported fields: device.id, vendor_name, product_name
query A plaintext value search String
rows Total records to be retrieved Integer Default: 0
start Number of records to skip before starting to return records Integer Default: 0
format REQUIRED specify the desired file format for the downloaded content String json, csv

Response

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

Example

Request

POST https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/approvals/_export

Request_Body 

{
  "criteria": {
    "vendor_name": [
      "SanDisk"
    ]
  },
  "rows": 50,
  "start": 0,
  "format": ""
}

Response 

{
  "job_id": 12345
}

Blocks

Bulk Create Blocks

Creates blocking rules by policy.

In December 2023 granular control of Write and Execute permissions were added when using Windows sensor 3.9.2 or above.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies UPDATE Majority of environments
Carbon Black Cloud external-device.enforce UPDATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:update N/A - included in permission name Prod UK and AWS GovCloud (US)
VMware Cloud Services Platform _API.Device.Control:external-Device.Enforce:update N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/device_control/v3/orgs/{org_key}/blocks/_bulk

Request Body - application/json 

[
  {
    "policy_id": "<string>",
    "windows": {
      "approved_devices": {
        "allow_write": boolean,
        "allow_execute": boolean
      }
    }
  }
]

Body Schema

Field Definition Data Type Values
policy_id The policy to enable blocking String N/A
windows Windows is an object that defines whether external devices that are approved based on the specified policy have permission to write and/or execute. All approved devices have permission to Read. Object 
{
  "approved_devices": {
    "allow_write": boolean,
    "allow_execute": boolean 
  }
}

Response

Code Description Content-Type Content
200 Successfully create blocks application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/blocks/_bulk

Request_Body 

[
  {
  "policy_id": "12345678",
    "windows": {
      "approved_devices": {
        "allow_write": false,
        "allow_execute": false
      }
    }
  }
]

Response 

{
  "results": 
    [
      {
        "id": "07b64fc9-633b-39b4-a905-16eb021f376a",
        "policy_id": "12345678",
        "created_at": "2023-12-11T21:49:00Z",
        "updated_at": "2023-12-11T22:22:02Z",
        "windows": {
          "approved_devices": {
          "allow_write": false,
          "allow_execute": true
        }
      }
    }
  ]
}

Get Block by ID

Returns a specific policy_id where blocking is enabled, requested using the ID of the block.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies READ Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/device_control/v3/orgs/{org_key}/blocks/{id}

Response

Code Description Content-Type Content
200 Successfully return block application/json View example response below
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/blocks/55

Response 

{
  "created_at": "2020-11-12T16:24:46.226Z",
  "id": 55,
  "policy_id": "6997287",
  "updated_at": "2020-11-12T16:24:46.226Z",
  "windows": {
    "approved_devices": {
      "allow_write": false,
      "allow_execute": true
    }
  }
}

Get Blocks

Returns all policy_ids where Device Control Blocking is enabled, for a specific org.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies READ Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:read N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/device_control/v3/orgs/{org_key}/blocks

Response

Code Description Content-Type Content
200 Successfully returns blocks application/json View example response below
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/blocks

Response 

{
  "results": [
    {
      "id": "09f690a5-0ec2-33e6-9109-06832497363e",
      "policy_id": "21797494",
      "created_at": "2023-08-29T05:15:47Z",
      "updated_at": "2023-11-07T09:31:01Z",
      "windows": {
        "approved_devices": {
          "allow_write": false,
          "allow_execute": false
        }
      }
    }
  ]
}

Update Block by Id

Modifies a specific approval rule.

This endpoint was added in December 2023 to support the addition of granular control of Write and Execute permissions when using Windows sensor 3.9.2 or above. You can not modify the policy assigned to the block. If you want to modify the policy then delete and create a new block.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies UPDATE Majority of environments
Carbon Black Cloud external-device.enforce UPDATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:update N/A - included in permission name Prod UK and AWS GovCloud (US)
VMware Cloud Services Platform _API.Device.Control:external-Device.Enforce:update N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
PUT {cbc-hostname}/device_control/v3/orgs/{org_key}/blocks/{cb_device_control_id}

Request Body - application/json 

 {
    "id": "string",
    "windows": {
        "approved_devices": {
            "allow_write": boolean,
            "allow_execute": boolean
        }
    }
}

Body Schema

Field Definition Data Type Values
id The block rule to change String N/A
windows Windows is an object that defines whether external devices that are approved based on the specified policy have permission to write and/or execute. All approved devices have permission to Read. Object 
{
  "approved_devices": {
    "allow_write": boolean,
    "allow_execute": boolean
  }
}

Response

Code Description Content-Type Content
200 Successfully updated the block application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/blocks/07b64fc9-633b-39b4-a905-16eb021f376a

Request_Body 

{
  "id": "07b64fc9-633b-39b4-a905-16eb021f376a",
  "windows": {
    "approved_devices": {
      "allow_write": true,
      "allow_execute": false
    }
  }
}

Response 

{
  "id": "07b64fc9-633b-39b4-a905-16eb021f376a",
  "policy_id": "12345678",
  "created_at": "2023-12-11T21:49:00Z",
  "updated_at": "2023-12-11T23:49:41Z",
  "windows": {
    "approved_devices": {
      "allow_write": true,
      "allow_execute": false
    }
  }
}

Delete Block by ID

Deletes a specific block.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies DELETE Majority of environments
Carbon Black Cloud external-device.enforce UPDATE Majority of environments
VMware Cloud Services Platform _API.Policies:org.Policies:delete N/A - included in permission name Prod UK and AWS GovCloud (US)
VMware Cloud Services Platform _API.Device.Control:external-Device.Enforce:update N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
DELETE {cbc-hostname}/device_control/v3/orgs/{org_key}/blocks/{id}

Response

Code Description Content-Type Content
204 Successfully delete block No Content View example response below
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/blocks/55

Response 

No Content

USB Devices

Get USB Device by ID

Returns a specific USB device.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/device_control/v3/orgs/{org_key}/devices/{id}

Response

Code Description Content-Type Content
200 Successfully return USB device application/json View example response below
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/devices/774

Response 

{
    "id": "774",
    "first_seen": "2020-10-20T19:47:02Z",
    "last_seen": "2020-10-21T18:00:59Z",
    "vendor_name": "SanDisk",
    "vendor_id": "0x0781",
    "product_name": "Ultra",
    "product_id": "0x5581",
    "serial_number": "4C531001331122115172",
    "last_endpoint_name": "DESKTOP-IL2ON7C",
    "last_endpoint_id": 7590378,
    "last_policy_id": 6997287,
    "endpoint_count": 2,
    "device_friendly_name": "SanDisk Ultra USB Device",
    "device_name": "\\Device\\HarddiskVolume30",
    "created_at": "2020-10-20T19:59:06Z",
    "updated_at": "2020-10-21T18:00:59Z",
    "status": "APPROVED"
}

Get Endpoints associated with a USB device

Returns endpoints associated with a USB device.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/device_control/v3/orgs/{org_key}/devices/{id}/endpoints

Response

Code Description Content-Type Content
200 Successfully return endpoints associated with a USB device application/json View example response below
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/devices/774/endpoints

Response 

{
    "results": [
        {
            "id": "53",
            "first_seen": "2020-10-21T16:50:28Z",
            "last_seen": "2020-10-21T18:00:59Z",
            "endpoint_name": "DESKTOP-IL2ON7C",
            "endpoint_id": 7590378,
            "policy_name": "Standard",
            "policy_id": 6997287,
            "created_at": "2020-10-21T16:50:28Z",
            "updated_at": "2020-10-21T18:00:59Z"
        },
        {
            "id": "50",
            "first_seen": "2020-10-20T19:47:02Z",
            "last_seen": "2020-10-21T16:36:01Z",
            "endpoint_name": "DESKTOP-IL2ON7C",
            "endpoint_id": 7579317,
            "policy_name": "Standard",
            "policy_id": 6997287,
            "created_at": "2020-10-20T19:47:02Z",
            "updated_at": "2020-10-21T16:36:01Z"
        }
    ]
}

Search USB Devices

Search USB devices your organization has seen.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/device_control/v3/orgs/{org_key}/devices/_search

Request Body - application/json 

{
  "criteria": {
    "endpoint.endpoint_name": [ "<string>" ],
    "product_name": [ "<string>" ],
    "serial_number": [ "<string>" ],
    "status": [ "<string>" ],
    "vendor_name": [ "<string>" ]
  },
  "query": "<string>",
  "rows": 0,
  "start": 0,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results Object 
{
  "vendor_name": [
    "SanDisk"
  ]
}
Supported fields: endpoint.endpoint_name, vendor_name, product_name, serial_number, status
query A plaintext value search String
rows Total records to be retrieved Integer Default: 0
start Number of records to skip before starting to return records Integer Default: 0
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "",
  "order": "ASC"
}]
order supports asc or desc

Supported fields: last_seen, vendor_name, product_name, serial_number

Response

Code Description Content-Type Content
200 Successfully search devices application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/devices/_search

Request_Body 

{
  "criteria": {
    "product_name": ["Ultra"]
  },
  "start": 0,
  "rows": 50,
  "sort": [
    {
      "field": "last_seen",
      "order": "asc"
    }
  ]
}

Response 

{
    "num_found": 1,
    "num_available": 1,
    "results": [
        {
            "id": "774",
            "first_seen": "2020-10-20T19:47:02Z",
            "last_seen": "2020-10-21T18:00:59Z",
            "vendor_name": "SanDisk",
            "vendor_id": "0x0781",
            "product_name": "Ultra",
            "product_id": "0x5581",
            "serial_number": "4C531001331122115172",
            "last_endpoint_name": "DESKTOP-IL2ON7C",
            "last_endpoint_id": 7590378,
            "last_policy_id": 6997287,
            "endpoint_count": 2,
            "device_friendly_name": "SanDisk Ultra USB Device",
            "device_name": "\\Device\\HarddiskVolume30",
            "created_at": "2020-10-20T19:59:06Z",
            "updated_at": "2020-10-21T18:00:59Z",
            "status": "APPROVED"
        }
    ]
}

Facet USB Devices

Facet USB devices your organization has seen.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/device_control/v3/orgs/{org_key}/devices/_facet

Request Body - application/json 

{
  "criteria": {
    "endpoint.endpoint_name": [ "<string>" ],
    "product_name": [ "<string>" ],
    "serial_number": [ "<string>" ],
    "status": [ "<string>" ],
    "vendor_name": [ "<string>" ]
  },
  "query": "<string>",
  "terms": {
    "fields": [ "<string>" ],
    "rows": 0
  }
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results Object 
{
  "vendor_name": [
    "SanDisk"
  ]
}
Supported fields: endpoint.endpoint_name, vendor_name, product_name, serial_number, status
query A plaintext value search String
terms The USB device fields to facet and how many of the top entries to return. Object 
{
  "fields": [
    "status"
  ],
  "rows": 100
}
Supported fields: vendor_name, product_name, endpoint.endpoint_name, status

Response

Code Description Content-Type Content
200 Successfully facet devices application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value application/json N/A
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/devices/_facet

Request_Body 

{
	"terms": {
		"fields": [
        "product_name"
		]
	}
}

Response 

{
    "terms": [
        {
            "field": "product_name",
            "values": [
                {
                    "id": "Cruzer Dial",
                    "name": "Cruzer Dial",
                    "total": 1
                },
                {
                    "id": "Cruzer Glide",
                    "name": "Cruzer Glide",
                    "total": 1
                },
                {
                    "id": "U3 Cruzer Micro",
                    "name": "U3 Cruzer Micro",
                    "total": 1
                },
                {
                    "id": "Ultra",
                    "name": "Ultra",
                    "total": 1
                },
                {
                    "id": "Ultra USB 3.0",
                    "name": "Ultra USB 3.0",
                    "total": 1
                }
            ]
        }
    ]
}

Export USB Devices Inventory

Export device data from the specified organization in a specified format.

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 external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/device_control/v3/orgs/{org_key}/devices/_export

Request Body - application/json

{
  "criteria": {
    "endpoint.endpoint_name": [ "<string>" ],
    "product_name": [ "<string>" ],
    "serial_number": [ "<string>" ],
    "status": [ "<string>" ],
    "vendor_name": [ "<string>" ]
  },
  "query": "<string>",
  "rows": <integer>,
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "start": <integer>,
  "format": "<string>"
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results Object 
{
  "vendor_name": [
    "SanDisk"
  ]
}
Supported fields: endpoint.endpoint_name, vendor_name, product_name, serial_number, status
query A plaintext value search String N/A
rows Total records to be retrieved Integer Default: 0
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "",
  "order": "ASC"
}]
order supports asc or desc
Supported fields: status, last_seen, vendor_name, product_name, serial_number, endpoint_name
start Number of records to skip before starting to return records Integer Default: 0
format A string representing the desired format of the exported data String CSV, JSON

Response

Code Description Content-Type Content
200 Successfully created Job application/json View example response below
400 Bad Request N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
POST https://defense.conferdeploy.net/device_control/v3/orgs/ABCD1234/devices/_export
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "vendor_name": [
      "SanDisk"
    ]
  },
  "format": "CSV"
}
Response Body 
{
  "job_id": 123456
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/device_control/v3/orgs/ABCD1234/devices/_export \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
-d '{
  "criteria": {
    "vendor_name": [
      "SanDisk"
    ]
  },
  "format": "CSV"
}'
Response Body 
{
  "job_id": 123456
}
To download or review the Carbon Black Cloud Postman collection, click here.

Products

Get USB Device Vendors and Products Seen

Returns all vendors and products that have been seen for the organization.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud external-device.manage READ Majority of environments
VMware Cloud Services Platform _API.Device.Control:external-Device.Manage:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/device_control/v3/orgs/{org_key}/products

Response

Code Description Content-Type Content
200 Successfully return products and vendors application/json View example response below
404 The resource does not exist N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/device_control/v3/orgs/ABCD1234/products

Response 

{
    "results": [
        {
            "vendor_id": "0x0781",
            "vendor_name": "SanDisk",
            "devices_count": 5,
            "products": [
                {
                    "product_id": "0x5406",
                    "product_name": "U3 Cruzer Micro",
                    "devices_count": 1
                },
                {
                    "product_id": "0x5575",
                    "product_name": "Cruzer Glide",
                    "devices_count": 1
                },
                {
                    "product_id": "0x5581",
                    "product_name": "Ultra",
                    "devices_count": 1
                },
                {
                    "product_id": "0x5595",
                    "product_name": "Ultra USB 3.0",
                    "devices_count": 1
                },
                {
                    "product_id": "0x5599",
                    "product_name": "Cruzer Dial",
                    "devices_count": 1
                }
            ]
        }
    ]
}


Last modified on December 11, 2023