Merge pull request #510 from carbonblack/release-1.5.2

CBAPI-5202: Release 1.5.2 merge to master

README.md

@@ -1,8 +1,8 @@
 # VMware Carbon Black Cloud Python SDK
 
-**Latest Version:** 1.5.1
+**Latest Version:** 1.5.2
 <br>
-**Release Date:** January 30, 2024
+**Release Date:** May 1, 2024
 
 [![Coverage Status](https://coveralls.io/repos/github/carbonblack/carbon-black-cloud-sdk-python/badge.svg?t=Id6Baf)](https://coveralls.io/github/carbonblack/carbon-black-cloud-sdk-python)
 [![Codeship Status for carbonblack/carbon-black-cloud-sdk-python](https://app.codeship.com/projects/9e55a370-a772-0138-aae4-129773225755/status?branch=develop)](https://app.codeship.com/projects/402767)

VERSION

@@ -1 +1 @@
-1.5.1
+1.5.2

docs/audit-log.rst

@@ -8,45 +8,58 @@ In the Carbon Black Cloud, *audit logs* are records of various organization-wide
 * Creation of connectors
 * LiveResponse events
 
-The Audit Log API allows these records to be retrieved in JSON format, sorted by time in ascending order
-(oldest records come first). The API call returns only *new* audit log records that have been added since
-the last time the call was made using the same API Key ID. Once records have been returned, they are *cleared*
-and will not be included in future responses.
-
-When reading audit log records using a *new* API key, the queue for reading audit logs will begin three days
-earlier. This may lead to duplicate data if audit log records were previously read with a different API key.
-
-.. note::
-    Future versions of the Carbon Black Cloud and this SDK will support a more flexible API for finding and retrieving
-    audit log records.  This Guide will be rewritten to cover this when it is incorporated into the SDK.
+The Audit Log API allows these records to be retrieved as objects, either by getting the most recent audit logs, or
+through a flexible search API.
 
 API Permissions
 ---------------
 
-To call this API function, use a custom API key created with a role containing the ``READ`` permission on
+To call the Audit Log APIs, use a custom API key created with a role containing the ``READ`` permission on
 ``org.audits``.
 
-Example of API Usage
---------------------
+Retrieving Queued Audit Log Events
+----------------------------------
+
+The Carbon Black Cloud maintains a queue of audit log events for each API key, which is initialized with the last three
+days of audit logs when the API key is created.  This demonstrates how to read audit log events from the queue::
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.platform import AuditLog
+    >>> api = CBCloudAPI(profile='sample')
+    >>> events = AuditLog.get_queued_auditlogs(api)
+    >>> for event in events:
+    ...     print(f"{event.create_time}: {event.actor} {event.description}")
+
+Once audit log events have been retrieved from the queue, they are "cleared" and will not be included in future
+responses to a ``get_queued_auditlogs()`` call.
+
+.. note::
+    Reading queued audit log events using *different* API keys may lead to duplicate data.
+
+Searching for Audit Log Events
+------------------------------
+
+Audit log events may be searched for in a manner similar to other objects within the SDK::
 
-.. code-block:: python
+    # assume "api" contains our CBCloudAPI reference as above
+    >>> query = api.select(AuditLog).where("description:Logged in")
+    >>> query.sort_by("create_time")
+    >>> for event in query:
+    ...     print(f"{event.create_time}: {event.actor} {event.description}")
 
-    import time
-    from cbc_sdk import CBCloudAPI
-    from cbc_sdk.platform import AuditLog
+See also the :ref:`searching-guide` guide page for a more detailed discussion of searching.
 
-    cb = CBCloudAPI(profile='yourprofile')
-    running = True
+Exporting Audit Log Events
+--------------------------
 
-    while running:
-        events_list = AuditLog.get_auditlogs(cb)
-        for event in events_list:
-            print(f"Event {event['eventId']}:")
-            for (k, v) in event.items():
-                print(f"\t{k}: {v}")
-        # omitted: decide whether running should be set to False
-        if running:
-            time.sleep(5)
+Any search query may also be used to export audit log data, in either CSV or JSON format::
 
+    # assume "api" contains our CBCloudAPI reference as above
+    >>> query = api.select(AuditLog).where("description:Logged in")
+    >>> query.sort_by("create_time")
+    >>> job = query.export("csv")
+    >>> result = job.await_completion().result()
+    >>> print(result)
 
-Check out the example script ``audit_log.py`` in the examples/platform directory on `GitHub <https://github.com/carbonblack/carbon-black-cloud-sdk-python>`_.
+Note that the ``export()`` call returns a ``Job`` object, as exports can take some time to complete.  The results may
+be obtained from the ``Job`` when the export process is completed.

docs/authentication.rst

@@ -3,7 +3,6 @@
 Authentication
 ==============
 
-
 Carbon Black Cloud APIs require authentication to secure your data.
 
 There are several methods for authentication listed below. Every method requires
@@ -52,9 +51,6 @@ Store the credential with a profile name, and reference the profile when creatin
 
 For more examples on Live Response, check :doc:`live-response`
 
-
-
-
 Authentication Methods
 ----------------------
 
@@ -117,8 +113,9 @@ Authentication Methods
 With a File
 ^^^^^^^^^^^
 Credentials may be supplied in a file that resembles a Windows ``.INI`` file in structure, which allows for
-multiple "profiles" or sets of credentials to be supplied in a single file.  The file format is backwards compatible with
-CBAPI, so older files can continue to be used.
+multiple "profiles" or sets of credentials to be supplied in a single file.  The file format is backwards compatible
+with CBAPI, so older files can continue to be used.  The file must be encoded as UTF-8, or as UTF-16 using either
+big-endian or little-endian format.
 
 **Example of a credentials file containing two profiles**
 

docs/cbc_sdk.workload.rst

@@ -1,6 +1,14 @@
 Workload Package
 *****************
 
+CIS Benchmarks
+-----------------------------------------
+
+.. automodule:: cbc_sdk.workload.compliance_assessment
+   :members:
+   :inherited-members:
+   :show-inheritance:
+
 NSX Remediation Module
 -----------------------------------------
 

docs/changelog.rst

@@ -1,5 +1,43 @@
 Changelog
 ================================
+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
 -----------------------------------------
 

docs/compliance.rst

@@ -0,0 +1,114 @@
+Compliance Benchmarks
+======
+
+CIS benchmarks are configuration guidelines published by the Center for Internet Security.
+The CIS Benchmark enable configuration and retrieval of Benchmark Sets and Rules in Carbon Black Cloud, and
+retrieval of the results from scans performed using these Rules.
+
+For more information on CIS Benchmarks, see the `Center for Internet Security <https://www.cisecurity.org/cis-benchmarks>`_.
+CIS benchmarks contain over 100 configuration guidelines created by a global community of cybersecurity experts to safeguard
+various systems against attacks targeting configuration vulnerabilities.
+
+You can use all the operations shown in the API, such as retrieving, filtering, reaccessing and enabling/disabling the benchmark rules.
+You can locate the full list of operations and attributes in the  :py:mod:`ComplianceBenchmark() <cbc_sdk.workload.compliance_assessment.ComplianceBenchmark>` class.
+
+Resources
+---------
+* `API Documentation <https://developer.carbonblack.com/reference/carbon-black-cloud/workload-protection/latest/cis-benchmark-api>`_ on Developer Network
+* `User Guide <https://docs.vmware.com/en/VMware-Carbon-Black-Cloud/services/carbon-black-cloud-user-guide/GUID-47645D2C-A093-47C8-B4CA-D6F685392733.html>`_
+
+Retrieve Compliance Benchmarks
+---------------
+
+By using the following the example, you can retrieve the list of supported benchmarks
+
+.. code-block:: python
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.workload import ComplianceBenchmark
+    >>> api = CBCloudAPI(profile='sample')
+    >>> benchmark_query = api.select(ComplianceBenchmark)
+    >>> for benchmark in benchmark_query:
+    >>>     print(benchmark)
+    ComplianceBenchmark object, bound to https://defense-test03.cbdtest.io.
+    -------------------------------------------------------------------------------
+
+            bundle_name: CIS Compliance - Microsoft Windows Server
+            create_time: 2023-03-20T13:44:10.923039Z
+            created_by: emuthu+csr@carbonblack.com
+                enabled: True
+                    id: b7d1b266-d899-4e28-bae6-7619019447ba
+                    name: CIS Windows Server Retail application Prod
+                os_family: WINDOWS_SERVER
+            release_time: 2023-07-10T13:55:59.274881Z
+        supported_os_info: [list:5 items]:
+                        [0]: {'os_metadata_id': '1', 'os_type': 'WINDOWS', '...
+                        [1]: {'os_metadata_id': '2', 'os_type': 'WINDOWS', '...
+                        [2]: {'os_metadata_id': '3', 'os_type': 'WINDOWS', '...
+                        [...]
+                    type: Custom
+            update_time: 2024-04-15T21:24:43.283032Z
+            updated_by:
+                version: 1.0.0.4
+
+
+Modify Compliance Benchmarks Schedule
+---------------
+
+By using the following the example, you can get and set the benchmark assessment schedule
+
+.. code-block:: python
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.workload import ComplianceBenchmark
+    >>> api = CBCloudAPI(profile='sample')
+    >>> ComplianceBenchmark.set_compliance_schedule(api, "RRULE:FREQ=DAILY;BYHOUR=17;BYMINUTE=30;BYSECOND=0", "UTC")
+    >>> schedule = ComplianceBenchmark.get_compliance_schedule(api)
+    >>> print(schedule)
+    {
+        "scan_schedule": "FREQ=WEEKLY;BYDAY=TU;BYHOUR=11;BYMINUTE=30;BYSECOND=0",
+        "scan_timezone": "UTC"
+    }
+
+
+Reassess Compliance Benchmarks
+---------------
+
+By using the following the example, you can reasses a benchmark
+
+.. code-block:: python
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.workload import ComplianceBenchmark
+    >>> api = CBCloudAPI(profile='sample')
+    >>> benchmark = api.select(ComplianceBenchmark).first()
+    >>> # Execute for all devices matching benchmark
+    >>> benchmark.execute_action("REASSESS")
+    >>> # Execute for a specific set of devices
+    >>> benchmark.execute_action("REASSESS", [ 1, 2, 3 ])
+
+
+Device Compliance Summary
+---------------
+
+By using the following the example, you can fetch the compliance percentage for each device assessed by the Compliance Benchmark
+
+.. code-block:: python
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.workload import ComplianceBenchmark
+    >>> api = CBCloudAPI(profile='sample')
+    >>> benchmark = api.select(ComplianceBenchmark).first()
+    >>> summaries = benchmark.get_device_compliances()
+    >>> print(summaries[0])
+    {
+        "device_id": 39074613,
+        "device_name": "Example\\Win2022",
+        "os_version": "Windows Server 2022 x64",
+        "compliance_percentage": 93,
+        "last_assess_time": "2024-04-16T00:00:00.014765Z",
+        "excluded_on": None,
+        "excluded_by": None,
+        "reason": None,
+        "deployment_type": "WORKLOAD"
+    }

docs/conf.py

@@ -19,11 +19,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Carbon Black Cloud Python SDK'
-copyright = '2020-2023 VMware Carbon Black'
+copyright = '2020-2024 VMware Carbon Black'
 author = 'Developer Relations'
 
 # The full version, including alpha/beta/rc tags
-release = '1.5.1'
+release = '1.5.2'
 
 
 # -- General configuration ---------------------------------------------------