.. # ******************************************************* # 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. Changelog ========= CBC SDK 1.5.10 - Released March 24, 2026 --------------------------------------- Bug Fixes: * Removed ``backports-datetime-fromisoformat`` C extension dependency. Replaced with a pure-Python fallback for Python < 3.11 that handles the ``Z`` UTC timezone designator. This fixes ``ModuleNotFoundError`` in embedded/vendored environments (e.g. Splunk) where platform-specific compiled extensions are unavailable. CBC SDK 1.5.9 - Released March 20, 2026 -------------------------------------- Updates: * Added Python 3.13 compatibility. * Replaced deprecated ``datetime.utcnow()`` and ``datetime.utcfromtimestamp()`` with timezone-aware equivalents. * Added ``__cbc_version__`` alias for ``__version__`` in ``cbc_sdk.__init__``. * Fixed ``EpochDateTimeFieldDescriptor`` missing ``self.epoch`` initialization. * Added Python 3.13 CI test job; removed EOL Python 3.7 job. Security: * Set minimum ``requests>=2.32.4`` (CVE-2024-47081). * Set minimum ``validators>=0.21.0`` (CVE-2023-45813). * Set minimum ``certifi>=2024.7.4`` (CVE-2024-39689). * Set minimum ``urllib3>=1.26.19`` (CVE-2024-37891). * Upgraded dev dependencies: ``pytest``, ``coverage``, ``flake8``, ``requests-mock``. CBC SDK 1.5.8 - Released June 27, 2025 -------------------------------------- Bug Fixes: * Fix event search_validation bug * Prevent infinite loop when No data available in organization * Fix broken yaml CBC SDK 1.5.7 - Released November 15, 2024 -------------------------------------- Bug Fixes: * Update search_validation to new API * Add additional fetch option for process_sha256 CBC SDK 1.5.6 - Released July 26, 2024 -------------------------------------- Bug Fixes: * Fixed a failure of large file transfers with the Live Response API. CBC SDK 1.5.5 - Released July 11, 2024 -------------------------------------- Bug fixes: * Updated dependencies to ensure ``backports-datetime-fromisoformat`` is installed correctly. CBC SDK 1.5.4 - Released July 10, 2024 -------------------------------------- Bug Fixes: * Fixed dependency on ``backports-datetime-fromisoformat`` for Python 3.11 and later. * Fixed a bug affecting the ability to access alert attributes with array syntax. CBC SDK 1.5.3 - Released June 27, 2024 -------------------------------------- New Features: * Export Alerts in CSV format (``Alert.export()``). Documentation: * Updated code copyright dates and noted the ownership by Broadcom. * Removed the Threat Intelligence example; it's been superseded by the `Carbon Black Cloud Threat Intelligence Connector `_. CBC SDK 1.5.2 - Released May 1, 2024 ------------------------------------ New Features: * Enhanced Audit Log support with search and export capabilities * CIS Benchmarking: * Schedule compliance scans * Search, create, update, and delete benchmark sets * Search and modify benchmark rules within a benchmark set * Search and export device summaries for benchmark sets * Enable, disable, and trigger reassessment on benchmark sets or individual devices * Search benchmark set summaries * Search and export device compliance summaries * Search and export rule compliance summaries * Search rule results for devices * Get and acknowledge compliance bundle version updates, show differences, get rule info Updates: * Added `collapse_field` parameter for process searches * Added an exponential backoff for polling of Job completion status * Added rule configurations for event reporting and sensor operation exclusions Bug Fixes: * Fixed implementation of iterable queries for consistency across the SDK * Fixed parsing of credential files that are encoded in UTF-16 * Fixed processing of Job so that it doesn't rely on an API call that doesn't give proper answers * Fixed missing properties in Process Documentation: * Fixed documentation for Alert and Process to include links to the Developer Network field descriptions * New example script for identifying devices that have checked in but have not sent any events * Added guide page for Devices including searching and actions CBC SDK 1.5.1 - Released January 30, 2024 ----------------------------------------- New Features: * Asset Groups - Added management of asset groups: * Create, delete, and update asset groups (either with manual or dynamic membership) * Retrieve asset groups by ID * Search for asset groups, retrieve list of all asset groups * Add/remove members, get all members in a group * Get statistics for a group * Helper functions for ``Device`` to retrieve and maintain group membership * Preview changes to effective policy for device(s) as a result of a number of different potential changes * Full documentation and new Guide page * Alerts v7 Enhancements - Added additional functionality to Alerts v7 as implemented in version 1.5.0: * Search Grouped Alerts, including faceting and retrieval of all alerts for a group * Get list of watchlists on an alert * Network threat metadata helper function * Full update to Alerts guide in documentation * Command line deobfuscation added to Processes, Alerts, and Observations, allowing visualization of PowerShell command lines that have been deliberately obfuscated by attackers. * New ``scroll()`` method added to Live Query search results. * New helper methods added to ``Policy`` to enable or disable XDR data collection and auth event data collection. * New ``export()`` and ``scroll()`` methods added to ``DeviceSearchQuery``. Updates: * Python 3.7 has been re-added as "unofficially" supported, since certain integrations that use the SDK still use it. * Added ``deployment_type`` as part of the facets available in ``DeviceSearchQuery``. Bug Fixes: * Search jobs that allow setting a timeout now default that timeout to 5 minutes. The timeout may be lowered from that point, but *never* raised beyond it. This eliminates a problem of "hung" searches. Documentation: * ReadTheDocs generation has been improved to show the inherited methods. There are some helper functions on ``SearchQuery`` classes such as ``add_criteria()`` inherited from ``CriteriaBuilderSupportMixin`` and ``first()`` inherited from ``IterableQueryMixin``. CBC SDK 1.5.0 - Released October 24, 2023 ----------------------------------------- **Alerts Update to use V7 API** The new Alerts V7 API will improve alert management and allow for easier management, consumption, and triage of alerts in the Carbon Black Cloud. Alerts v7 API extends the capabilities with improved methods of retrieving alerts and added functionality to manage alert workflow. **N.B.:** This change involves breaking changes to the SDK involving the core Alerts workflow. Please check your existing code carefully before deploying this SDK upgrade. **Breaking Changes:** * Alerts V7: Certain changes are not compatible with code written to the old V6 API. For details, please see the :ref:`Alert Migration Guide `. Breaking changes include: * Default Search Time Period is reduced to two weeks. * For fields that do not exist in the Alerts V7 API, a ``FunctionalityDecommissioned`` exception is raised. * ``get_events()`` method has been removed. * All facet terms match the field names. * Workflow has been rebuilt. * Create Note returns a single ``Note`` instance instead of a list. * Official support for Python 3.7 has been dropped, since that version is now end-of-life. Added explicit testing support for Python version 3.12. **N.B.:** End users should update their Python version to 3.8.x or greater. New Features: * Alerts V7: * Extended alert schema with additional metadata such as process command line and username, parent and child process information, netconn data, additional device fields, MITRE categorization when available, and more * Ability to mark alerts as “In Progress” * Ability to mark alerts as True Positive or False Positive * Additional fields available for both searching and faceting * Enhanced note management with the ability to add notes to both individual alerts and threats (alerts grouped by threat) * Observed Alerts have been removed from the Alerts API as these events are not considered actionable threats. They can now be retrieved via the Observations API. * External Devices: Added External Device Export and External Device Approvals Export. Updates: * Audit log requests have moved from ``CBCloudAPI`` into their own function entry point in the ``platform`` package. The old function has been deprecated. * Process search validation has been changed to use the V2 ``POST`` API rather than the old V1 ``GET`` API. * ``CBCloudAPI.get_notifications()`` and ``CBCloudAPI.notification_listener()`` have been marked as deprecated. Documentation: * Added example script to poll for audit logs. * ``CBCloudAPI`` documentation has been pulled out into its own page. * Authentication, Getting Started, and Guides pages have been updated. * Concepts page has been removed, and the information it contained has moved to other pages. * New :ref:`Searching guide ` added. * Update to left-hand sidebar to allow the Guides sub-listing to be collapsed. * Porting guide has been updated to reflect the latest APIs. * Live Response migration guide has been updated with links. * ``README.md`` has been updated with better instructions for generating docs locally. * ``CBCloudAPI`` and Devices documentation have been updated to better conform to new style guide for docstrings. CBC SDK 1.4.3 - Released June 26, 2023 -------------------------------------- New Features: * Policy Rule Configurations - support for additional rule configuration types: * Host-Based Firewall - addresses the protection of assets based on rules governing network and application behavior. * Data Collection - control over what data is uploaded to the Carbon Black Cloud. Specifically, can enable or disable auth events collection. Updates: * Added an example script for manipulating core prevention rule configuration and data collection status on a policy. * Changed ``pymox`` dependency to the latest version, which eliminates warning messages on unit test and provides compatibility with Python 3.11 and later. * Added specific testing support for Python 3.11. * Added additional UAT tests for authentication events. * Many exception classes now carry a ``uri`` field which holds the URI of the API being accessed that caused the exception to be raised. Bug Fixes: * Fixed link validation for reports and IOCs to accept IPv4 addresses, domain names, or URIs. Documentation: * Documentation has been reorganized for ease of reference; guides have been added to the main menu, the menu has been reordered, and various modules have been renamed. * Fixed typo in workload guide. CBC SDK 1.4.2 - Released March 22, 2023 --------------------------------------- New Features: * Policy Rule Configurations - allows users to make adjustments to Carbon Black-defined rules. * Core Prevention Rule Configurations - controls settings for core prevention rules as supplied by Carbon Black. * Observations - search through all the noteworthy, searchable activity that was reported by your organization’s sensors. * Auth Events - visibility into authentication events on Windows endpoints. Updates: * Remove use of v1 status URL from process search, which now depends entirely on v2 operations. * Vulnerabilities can now be dismissed and undismissed, and have dismissals edited. Bug Fixes: * User creation: raise error if the API object is not passed as the first parameter to ``User.create()``. * Live Response: pass failed session exception back up to the ``WorkItem`` future objects. * Improved query string parameter handling in API calls. Documentation: * New example script showing how to retrieve container alerts. * New example script allows exporting users with grant and role information. * Bug fixed in ``policy_service_crud_operations.py`` example script affecting iteration over rules. * Update clarifying alert filtering by fields that take an empty list. * Sample script added for retrieving alerts for multiple organizations. CBC SDK 1.4.1 - Released October 21, 2022 ----------------------------------------- New Features: * AWS workloads now supported in VM Workloads Search. * Live Query Differential Analysis functionality. Updates: * VM Workloads Search updated to use new v2 APIs * Added the ``alertable`` field to feeds. * Devices API now supports faceting on three additional (public cloud related) fields. * Added a user acceptance test script for the policy function updates. Documentation: * Added information on OAuth authentication to docs. CBC SDK 1.4.0 - Released July 26,2022 ------------------------------------- **Breaking Changes:** * ``Policy`` object has been moved from ``cbc_sdk.endpoint_standard`` to ``cbc_sdk.platform``, as it now uses the new Policy Services API rather than the old APIs through Integration Services. - **N.B.:** This change means that you *must* use a custom API key with permissions under ``org.policies`` to manage policies, rather than an older "API key." - To enable time to update integration logic, the ``cbc_sdk.endpoint_standard Policy`` object may still be imported from the old package, and supports operations that are backwards-compatible with the old one. - When developing a new integration, or updating an existing one cbc_sdk.platform should be used. There is a utility class ``PolicyBuilder``, and as features are added to the Carbon Black Cloud, they will be added to this module. * Official support for Python 3.6 has been dropped, since that version is now end-of-life. Added explicit testing support for Python versions 3.9 and 3.10. **N.B.:** End users should update their Python version to 3.7.x or greater. New Features: * Credentials handler now supports OAuth tokens. * Added support for querying a single ``Report`` from a ``Feed``. * Added support for alert notes (create, delete, get, refresh). Updates: * Removed the (unused) ``revoked`` property from ``Grant`` objects. * Increased the asynchronous query thread pool to 3 threads by default. * Required version of ``lxml`` is now 4.9.1. * Added a user acceptance test script for Alerts. Bug Fixes: * Added ``max_rows`` to USB device query, fixing pagination. * Fixed an off-by-one error in Alerts Search resulting un duplicate alerts showing up in results. * Fixed an error in alert faceting operations due to sending excess input to the server. Documentation: * Watchlists, Feeds, and Reports guide has been updated with additional clarification and examples. * Updated description for some ``Device`` fields that are never populated. * Additional sensor states added to ``Device`` documentation. * Fixed the description of ``BaseAlertSearchQuery.set_types`` so that it mentions all valid alert types. * Threat intelligence example has been deprecated. CBC SDK 1.3.6 - Released April 19, 2022 --------------------------------------- New Features: * Support for Device Facet API. * Dynamic reference of query classes--now you can do ``api.select("Device")`` in addition to ``api.select(Device)``. * Support for Container Runtime Alerts. * NSX Remediation functionality - set the NSX remediation state for workloads which support it. Updates: * Endpoint Standard specific ``Event`` s have been decommissioned and removed. * SDK now uses Watchlist Manager apis ``v3`` instead of ``v2``. ``v2`` APIs are being decommissioned. Documentation: * Added a ``CONTRIBUTING`` link to the ``README.md`` file. * Change to Watchlist/Report documentation to properly reflect how to update a ``Report`` in a ``Watchlist``. * Cleaned up formatting. CBC SDK 1.3.5 - Released January 26, 2022 ----------------------------------------- New Features: * Added asynchronous query support to Live Query. * Added the ability to export query results from Live Query, either synchronously or asynchronously (via the ``Job`` object and the Jobs API). Synchronous exports include full-file export, line-by-line export, and ZIP file export. Asynchronous exports include full-file export and line-by-line export. * Added a ``CredentialProvider`` that uses AWS Secrets Manager to store credential information. Updates: * Added ``WatchlistAlert.get_process()`` method to return the ``Process`` of a ``WatchlistAlert``. * Added several helpers to Live Query support to make it easier to get runs from a template, or results, device summaries, or facets from a run. * Optimized API requests when performing query slicing. * Updated pretty-printing of objects containing ``dict`` members. * ``lxml`` dependency updated to version 4.6.5. Bug Fixes: * ``User.delete()`` now checks for an outstanding access grant on the user, and deletes it first if it exists. * Fixed handling of URL when attaching a new IOC to a ``Feed``. * Getting and setting of ``Report`` ignore status is now supported even if that ``Report`` is part of a ``Feed``. Documentation: * Information added about the target audience for the SDK. * Improper reference to a credential property replaced in the Authentication guide. * Broken example updated in Authentication guide. * Added SDK guides for Vulnerabilities and Live Query APIs. * Updated documentation for ``ProcessFacet`` model to better indicate support for full query string. CBC SDK 1.3.4 - Released October 12, 2021 ----------------------------------------- New Features: * New CredentialProvider supporting Keychain storage of credentials (Mac OS only). * Recommendations API - suggested reputation overrides for policy configuration. Updates: * Improved string representation of objects through ``__str__()`` mechanism. Bug Fixes: * Ensure proper ``TimeoutError`` is raised in several places where the wrong exception was being raised. * Fix to allowed categories when performing alert queries. Documentation Changes: * Added guide page for alerts. * Live Response documentation updated to note use of custom API keys. * Clarified query examples in Concepts. * Note that vulnerability assessment has been moved from ``workload`` to ``platform.`` * Small typo fixes in watchlists, feeds, UBS, and reports guide. CBC SDK 1.3.3 - Released August 10, 2021 ---------------------------------------- Bug Fixes: * Dependency fix on schema library. CBC SDK 1.3.2 - Released August 10, 2021 ---------------------------------------- New Features: * Added asynchronous query options to Live Response APIs. * Added functionality for Watchlists, Reports, and Feeds to simplify developer interaction. Updates: * Added documentation on the mapping between permissions and Live Response commands. Bug Fixes: * Fixed an error using the STIX/TAXII example with Cabby. * Fixed a potential infinite loop in getting detailed search results for enriched events and processes. * Comparison now case-insensitive on UBS download. CBC SDK 1.3.1 - Released June 15, 2021 -------------------------------------- New Features: * Allow the SDK to accept a pre-configured ``Session`` object to be used for access, to get around unusual configuration requirements. Bug Fixes: * Fix functions in ``Grant`` object for adding a new access profile to a user access grant. CBC SDK 1.3.0 - Released June 8, 2021 ------------------------------------- New Features * Add User Management, Grants, Access Profiles, Permitted Roles * Move Vulnerability models to Platform package in preparation for supporting Endpoints and Workloads * Refactor Vulnerability models * ``VulnerabilitySummary.get_org_vulnerability_summary`` static function changed to ``Vulnerability.OrgSummary`` model with query class * ``VulnerabilitySummary`` model moved inside ``Vulnerability`` to ``Vulnerability.AssetView`` sub model * ``OrganizationalVulnerability`` and ``Vulnerability`` consolidated into a single model to include Carbon Black Cloud context and CVE information together * ``Vulnerability(cb, CVE_ID)`` returns Carbon Black Cloud context and CVE information * ``DeviceVulnerability.get_vulnerability_summary_per_device`` static function moved to ``get_vulnerability_summary`` function on ``Device`` model * ``affected_assets(os_product_id)`` function changed to ``get_affected_assets()`` function and no longer requires ``os_product_id`` * Add dashboard export examples * Live Response migrated from v3 to v6 (:doc:`migration guide`) * Live Response uses API Keys of type Custom * Add function to get Enriched Events for Alert Bug Fixes * Fix validate query from dropping sort_by for Query class * Fix the ability to set expiration for binary download URL * Fix bug in helpers read_iocs functionality * Fix install_sensor and bulk_install on ComputeResource to use id instead of uuid * Fix DeviceSearchQuery from duplicating Device due to base index of 1 CBC SDK 1.2.3 - Released April 19, 2021 --------------------------------------- Bug Fixes * Prevent alert query from retrieving past 10k limit CBC SDK 1.2.3 - Released April 19, 2021 --------------------------------------- Bug Fixes * Prevent alert query from retrieving past 10k limit CBC SDK 1.2.2 - Released April 5, 2021 --------------------------------------- Bug Fixes * Add support for full credential property loading through BaseAPI constructor CBC SDK 1.2.1 - Released March 31, 2021 --------------------------------------- New Features * Add `__str__` functions for Process.Tree and Process.Summary * Add `get_details` for Process * Add `set_max_rows` to DeviceQuery Bug Fixes * Modify base class for EnrichedEventQuery to Query from cbc_sdk.base to support entire feature set for searching * Document fixes for changelog and Workload * Fix `_spawn_new_workers` to correctly find active devices for Carbon Black Cloud CBC SDK 1.2.0 - Released March 9, 2021 -------------------------------------- New Features * VMware Carbon Black Cloud Workload support for managing workloads: * Vulnerability Assessment * Sensor Lifecycle Management * VM Workloads Search * Add tutorial for Reputation Override Bug Fixes * Fix to initialization of ReputationOverride objects CBC SDK 1.1.1 - Released February 2, 2021 ----------------------------------------- New Features * Add easy way to add single approvals and blocks * Add Device Control Alerts * Add deployment_type support to the Device model Bug Fixes * Fix error when updating iocs in a Report model * Set max_retries to None to use Connection init logic for retries CBC SDK 1.1.0 - Released January 27, 2021 ----------------------------------------- New Features * Reputation Overrides for Endpoint Standard with Enterprise EDR support coming soon * Device Control for Endpoint Standard * Live Query Templates/Scheduled Runs and Template History * Add set_time_range for Alert query Bug Fixes * Refactored code base to reduce query inheritance complexity * Limit Live Query results to 10k cap to prevent 400 Bad Request * Add missing criteria for Live Query RunHistory to search on template ids * Add missing args.orgkey to get_cb_cloud_object to prevent exception from being thrown * Refactor add and update criteria to use CriteriaBuilderSupportMixin CBC SDK 1.0.1 - Released December 17, 2020 ------------------------------------------ Bug Fixes * Fix readme links * Few ReadTheDocs fixes CBC SDK 1.0.0 - Released December 16, 2020 ------------------------------------------ New Features * Enriched Event searches for Endpoint Standard * Aggregation search added for Enriched Event Query * Add support for fetching additional details for an Enriched Event * Facet query support for Enriched Events, Processes, and Process Events * Addition of Python Futures to support asynchronous calls for customers who want to leverage that feature , while continuing to also provide the simplified experience which hides the multiple calls required. * Added translation support for MISP threat intel to cbc_sdk threat intel example Updates * Improved information and extra calls for Audit and Remediation (Live Query) * Great test coverage – create extensions and submit PRs with confidence * Process and Process Event searches updated to latest APIs and moved to platform package * Flake8 formatting applied to all areas of the code * Converted old docstrings to use google format docstrings * Migrated STIX/TAXII Threat Intel module from cbapi to cbc_sdk examples Bug Fixes * Fixed off by one error for process event pagination * Added support for default profile using CBCloudAPI() * Retry limit to Process Event search to prevent infinite loop