.. # ******************************************************* # Copyright (c) Broadcom, Inc. 2020-2026. All Rights Reserved. Carbon Black. # SPDX-License-Identifier: MIT # ******************************************************* # * # * DISCLAIMER. THIS PROGRAM IS PROVIDED TO YOU "AS IS" WITHOUT # * WARRANTIES OR CONDITIONS OF ANY KIND, WHETHER ORAL OR WRITTEN, # * EXPRESS OR IMPLIED. THE AUTHOR SPECIFICALLY DISCLAIMS ANY IMPLIED # * WARRANTIES OR CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, # * NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. Device Control ============== Using the Carbon Black Cloud SDK, you can retrieve information about USB devices used in your organization, and manage the blocking of such devices from access by your endpoints. .. note:: ``USBDevice`` is distinct from either the Platform API ``Device`` or the Endpoint Standard ``Device``. Access to USB devices is through the Endpoint Standard package ``from cbc_sdk.endpoint_standard import USBDevice``. Retrieving the List of Known USB Devices ---------------------------------------- Using a query of the ``USBDevice`` object, you can see which USB devices have been used on any endpoint in your organization:: >>> from cbc_sdk import CBCloudAPI >>> api = CBCloudAPI(profile='sample') >>> from cbc_sdk.endpoint_standard import USBDevice >>> query = api.select(USBDevice).where('1') >>> for usb in query: ... print(f"{usb.vendor_name} {usb.product_name} {usb.serial_number} {usb.status}") ... SanDisk Ultra 4C531001331122115172 UNAPPROVED SanDisk Cruzer Dial 4C530000110722114075 UNAPPROVED PNY USB 2.0 FD 07189613DD84E242 UNAPPROVED USB Flash Disk FBI1305031200020 APPROVED Note that individual USB devices may be ``APPROVED`` or ``UNAPPROVED``. USB devices which are ``UNAPPROVED`` cannot be read on any endpoint with a policy that blocks unknown USB devices. A USB device query can also be exported to either CSV or JSON format, for use by other software systems:: >>> from cbc_sdk import CBCloudAPI >>> api = CBCloudAPI(profile='sample') >>> from cbc_sdk.endpoint_standard import USBDevice >>> query = api.select(USBDevice).where('1') >>> job = query.export('CSV') >>> csv_report = job.get_output_as_string() >>> # can also get the output as a file or as enumerated lines of text Approving A Specific Device --------------------------- We can create an approval for a USB device by using the device's ``approve()`` method. First, we'll get a list of all unapproved USB devices:: >>> from cbc_sdk import CBCloudAPI >>> api = CBCloudAPI(profile='sample') >>> from cbc_sdk.endpoint_standard import USBDevice >>> query = api.select(USBDevice).where('1').set_statuses(['UNAPPROVED']) >>> usb_list = list(query) >>> for usb in usb_list: ... print(f"{usb.vendor_name} {usb.product_name} {usb.serial_number}") ... SanDisk Ultra 4C531001331122115172 SanDisk Cruzer Dial 4C530000110722114075 PNY USB 2.0 FD 07189613DD84E242 Now we'll select one of these devices and approve it:: >>> usb = usb_list[1] >>> print(usb.status) UNAPPROVED >>> approval = usb.approve('Test1', 'API Testing') >>> print(approval.approval_name) Test1 >>> print(approval.notes) API Testing >>> print(approval.serial_number) 4C530000110722114075 >>> print(approval.id) 1ffd0a16-28ad-3fba-981d-d1c29c2903da >>> print(usb.status) APPROVED The ``approve()`` method creates a ``USBDeviceApproval`` representing that particular device's approval, and also reloads the ``USBDevice`` so its ``status`` reflects the fact that it's been approved. Removing A Device's Approval ---------------------------- Device approvals may be removed via the API as well. Starting from the end of the previous example:: >>> approval.delete() >>> usb.refresh() True >>> print(usb.status) UNAPPROVED The ``delete()`` method is what causes the approval to be removed. We then use ``refresh()`` on the actual ``USBDevice`` object to allow its ``status`` to be updated. Retrieving the List of Approvals -------------------------------- USB device approvals can also be enumerated directly:: >>> from cbc_sdk import CBCloudAPI >>> api = CBCloudAPI(profile='sample') >>> from cbc_sdk.endpoint_standard import USBDeviceApproval >>> query = api.select(USBDeviceApproval) >>> for approval in query: ... print(f"{approval.id} {approval.approval_name} {approval.serial_number}") ... They can also be exported in a similar manner to USB devices:: >>> from cbc_sdk import CBCloudAPI >>> api = CBCloudAPI(profile='sample') >>> from cbc_sdk.endpoint_standard import USBDeviceApproval >>> query = api.select(USBDeviceApproval) >>> job = query.export('CSV') >>> csv_report = job.get_output_as_string() >>> # can also get the output as a file or as enumerated lines of text Device Control Alerts --------------------- When an endpoint attempts to access a blocked USB device (the endpoint has USB device blocking configured and the USB device is not approved), a ``DeviceControlAlert`` is generated. These alerts may be queried using the standard Platform API components. :: >>> from cbc_sdk import CBCloudAPI >>> api = CBCloudAPI(profile='sample') >>> from cbc_sdk.platform import DeviceControlAlert >>> query = api.select(DeviceControlAlert).where('1') >>> alerts_list = list(query) >>> for alert in alerts_list: ... print(f"{alert.vendor_name} {alert.product_name} {alert.serial_number}") ... USB Flash Disk FBI1305031200020 USB Flash Disk FBI1305031200020 USB Flash Disk FBI1305031200020 USB Flash Disk FBI1305031200020 PNY USB 2.0 FD 07189613DD84E242 PNY USB 2.0 FD 07189613DD84E242 PNY USB 2.0 FD 07189613DD84E242 There are a number of fields supported by ``DeviceControlAlert`` over and above the standard alert fields; see `the developer documentation `_ for details.