Carbon-black-cloud-sdk

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

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`.

**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
[Alert Migration Guide](https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/alerts-migration/). 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 [Searching Guide](https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/searching/) 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.

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.

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.

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.