Device Control

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.

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
  • Cross reference additional external device data after an alert

Requirements

  • Carbon Black Cloud Endpoint Standard
  • Windows 3.6.0.1897 sensor or above
  • All API calls require an API key with appropriate permissions see Authentication

Authentication

  • Access Level: Before you create your API Key, you need to create a “Custom” Access Level:

    • for the category Device Control > Manage Enforcement > “external-device.enforce”, allow permission to UPDATE (or see each call below for individual requirements)

    • for the category Device Control > Manage External Devices > “external-device.manage”, allow permission to CREATE, READ, UPDATE, DELETE (or see each call below for individual requirements)

    • for the category Policies > Policies > “org.policies”, allow permission to CREATE, READ, UPDATE, DELETE (or see each call below for individual requirements)

  • API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.

  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL)

  • API Route: {cbc-hostname}/device_control/v3/orgs/{org_key}/approvals/{id}

Note: when you insert your org_key, you must also remove the { } brackets.

API calls

Approvals

Bulk Create Approvals

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage CREATE

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage READ

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage READ

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage UPDATE

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage DELETE

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

Blocks

Bulk Create Blocks

Creates blocking rules by policy.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.policies UPDATE
external-device.enforce UPDATE

Request

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

Request Body - application/json

[
  {
    "policy_id": "string"
  }
]

Body Schema

Field Definition Data Type Values
policy_id The policy to enable blocking String N/A

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": "6997287"
  }
]

Response

{
  "results": [
    {
      "created_at": "2020-11-12T16:24:46.226Z",
      "id": 55,
      "policy_id": "6997287",
      "updated_at": "2020-11-12T16:24:46.226Z"
    }
  ]
}

Get Block by ID

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.policies READ

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"
}

Get Blocks

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.policies READ

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": [
    {
      "created_at": "2020-11-12T16:24:46.226Z",
      "id": 55,
      "policy_id": "6997287",
      "updated_at": "2020-11-12T16:24:46.226Z"
    }
  ]
}

Delete Block by ID

Deletes a specific block.

RBAC Permissions Required

Permission (.notation name) Operation(s)
org.policies DELETE
external-device.enforce UPDATE

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage READ

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage READ

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage READ

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.

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage READ

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
                }
            ]
        }
    ]
}

Products

Get USB Device Vendors and Products Seen

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

RBAC Permissions Required

Permission (.notation name) Operation(s)
external-device.manage READ

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 November 30, 2020