Merge pull request #315 from carbonblack/release-1.4.1

CBAPI-4196: Release 1.4.1 Merge to Master

README.md

@@ -1,8 +1,8 @@
 # VMware Carbon Black Cloud Python SDK
 
-**Latest Version:** 1.4.0
+**Latest Version:** 1.4.1
 <br>
-**Release Date:** July 26, 2022
+**Release Date:** October 21, 2022
 
 [![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.4.0
+1.4.1

docs/cbc_sdk.audit_remediation.rst

@@ -12,6 +12,14 @@ cbc\_sdk.audit\_remediation.base module
    :undoc-members:
    :show-inheritance:
 
+cbc\_sdk.audit\_remediation.differential module
+-----------------------------------------------
+
+.. automodule:: cbc_sdk.audit_remediation.differential
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 

docs/changelog.rst

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

docs/conf.py

@@ -23,7 +23,7 @@
 author = 'Developer Relations'
 
 # The full version, including alpha/beta/rc tags
-release = '1.4.0'
+release = '1.4.1'
 
 
 # -- General configuration ---------------------------------------------------

docs/differential-analysis.rst

@@ -0,0 +1,147 @@
+Differential Analysis
+=====================
+
+Differential Analysis provides the ability to compare and understand the changes between two
+`Live Query <https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/cbc_sdk.audit_remediation/#cbc_sdk.audit_remediation.base.Run>`_ runs.
+The differential is calculated based on point-in-time snapshots. These features answer the question, “What changed on endpoints, and when?”.
+
+Overview
+--------
+This guide follows the steps for comparing two “point-in-time snapshots” of endpoints using a few different options and downloading the results using the Differential object.
+This example aims to understand what Firefox add-ons were added or removed between the two Live Query snapshot intervals.
+
+**1. Prerequisites**
+
+To perform a Differential Analysis, create the "point-in-time" snapshots of your endpoints with Live Query or use existing ones.
+You can find a step-by-step Live Query API guide `here <https://developer.carbonblack.com/reference/carbon-black-cloud/cb-liveops/latest/livequery-api/#quick-start>`_ and
+a version for the CBC Python SDK `here <https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/live-query/>`_.
+The example Live Query runs look for added or removed Firefox add-ons.
+
+**2. Query Comparison**
+
+Start a Query Comparison with the ID's you received from step 1. If the supplied ``newer_run_id`` is from a recurring Live Query run,
+the ``older_run_id`` is not required - the backend will automatically compare it to previous to the supplied one.
+The backend will throw a specific error if you provide a query id from a single Live Query run.
+You can read more about it `here <https://developer.carbonblack.com/reference/carbon-black-cloud/cb-liveops/latest/differential-analysis-api/#query-comparison>`_.
+
+Query Comparison
+----------------
+
+Basic Query
+###########
+
+This example shows the basic result of the ``Differential`` object. The ``.newer_run_id()`` method is required - it accepts the
+run id that you want to mark as the starting point-in-time snapshot. By default, only the number of changes between the two runs are returned.
+To receive the actual differential data, use the ``.count_only()`` method, as featured in the Actual Changes example.
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.audit_remediation import Differential
+    >>>
+    >>> cb = CBCloudAPI(profile='sample')
+    >>>
+    >>> query = cb.select(Differential).newer_run_id('jcdqsju4utpaayj5dh5r2llzffeolg0u').older_run_id('yhbg3wcea9y1l4asiltky5tupkgauzas')
+    >>> run = query.submit()
+    >>> print(run)
+    Differential object, bound to https://defense-dev01.cbdtest.io.
+    -------------------------------------------------------------------------------
+
+                    diff_processed_time: 0.037
+                           diff_results: [list:1 item]:
+                                         [0]: {'device_id': 11412673, 'change_count': 19, 'ad...
+                  newer_run_create_time: 2022-10-19T13:29:34.429Z
+                           newer_run_id: n6cv24lh3pnh4zbciotahl82tm4tsuo7
+        newer_run_not_responded_devices: [list:1 item]:
+                                         [0]: 17331059
+                  older_run_create_time: 2022-10-19T13:19:49.812Z
+                           older_run_id: olquodvqz8kekxug2o2jsxcdnltak9hu
+        older_run_not_responded_devices: [list:1 item]:
+                                         [0]: 17331059
+
+You can also access a dictionary representation of the response with the ``._info`` property.
+
+    >>> print(run._info)
+    {'diff_processed_time': 0.037,
+     'diff_results': [{'added_count': 1,
+                       'change_count': 1,
+                       'changes': None,
+                       'device_id': 12345,
+                       'newer_run_row_count': 21,
+                       'older_run_row_count': 20,
+                       'removed_count': 0}],
+     'newer_run_create_time': '2022-08-10T13:07:44.194Z',
+     'newer_run_id': 'jcdqsju4utpaayj5dh5r2llzffeolg0u',
+     'newer_run_not_responded_devices': [],
+     'older_run_create_time': '2022-08-10T12:57:03.872Z',
+     'older_run_id': 'yhbg3wcea9y1l4asiltky5tupkgauzas',
+     'older_run_not_responded_devices': []}
+
+
+Actual Changes
+##############
+
+Using the ``.count_only()`` method with a value of ``False`` will allow you to see the actual changes between the two snapshots.
+To use this method, append it to the rest of the Differential object query. The actual changes will be in the ``changes`` property, under ``diff_results``.
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.audit_remediation import Differential
+    >>>
+    >>> cb = CBCloudAPI(profile='sample')
+    >>>
+    >>> query = cb.select(Differential).newer_run_id('jcdqsju4utpaayj5dh5r2llzffeolg0u').older_run_id('yhbg3wcea9y1l4asiltky5tupkgauzas').count_only(False)
+    >>> actual_changes = query.submit()
+    >>> print(actual_changes.diff_results)
+    [{'device_id': 11412673, 'change_count': 19, 'added_count': 19, 'removed_count': 0, 'changes': [{'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Visionary – Soft'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Activist – Balanced'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Visionary – Balanced'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Innovator – Soft'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Activist – Bold'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Dreamer – Soft'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Dreamer – Balanced'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Expressionist – Bold'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Innovator – Bold'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'AdGuard AdBlocker'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Expressionist – Balanced'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Visionary – Bold'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Playmaker – Soft'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Innovator – Balanced'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Expressionist – Soft'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Playmaker – Balanced'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Playmaker – Bold'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Activist – Soft'}]}, {'action': 'ADDED', 'fields': [{'key': 'name', 'value': 'Dreamer – Bold'}]}], 'older_run_row_count': 26, 'newer_run_row_count': 45}]
+
+In the example response you can see that 19 items were added between the two snapshot intervals.
+
+
+Filter Devices
+##############
+
+Using the ``.set_device_ids()`` you can narrow down the query to a specific devices only. The method accepts an array of integers.
+To use this method, append it to the rest of the Differential object query or combine it with any of the other methods.
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.audit_remediation import Differential
+    >>>
+    >>> cb = CBCloudAPI(profile='sample')
+    >>>
+    >>> query = cb.select(Differential).newer_run_id('jcdqsju4utpaayj5dh5r2llzffeolg0u').older_run_id('yhbg3wcea9y1l4asiltky5tupkgauzas')
+    >>> actual_changes = query.count_only(False).set_device_ids([12345])
+    >>> run = actual_changes.submit()
+    >>> print(run._info)
+        {'diff_processed_time': 0.039,
+         'diff_results': [{'added_count': 1,
+                           'change_count': 1,
+                           'changes': [{'action': 'ADDED',
+                                        'fields': [{'key': 'name',
+                                                    'value': 'AdBlocker Ultimate'}]}],
+                           'device_id': 12345,
+                           'newer_run_row_count': 21,
+                           'older_run_row_count': 20,
+                           'removed_count': 0}],
+         'newer_run_create_time': '2022-08-10T13:07:44.194Z',
+         'newer_run_id': 'jcdqsju4utpaayj5dh5r2llzffeolg0u',
+         'newer_run_not_responded_devices': [],
+         'older_run_create_time': '2022-08-10T12:57:03.872Z',
+         'older_run_id': 'yhbg3wcea9y1l4asiltky5tupkgauzas',
+         'older_run_not_responded_devices': []}
+
+
+
+Export Results
+##############
+
+Using the ``.async_export()`` you can create an asynchronous job that exports the results from the run.
+To use this method, append it to the rest of the Differential object query or combine it with any of the other methods.
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.audit_remediation import Differential
+    >>>
+    >>> cb = CBCloudAPI(profile='sample')
+    >>>
+    >>> query = cb.select(Differential).newer_run_id('jcdqsju4utpaayj5dh5r2llzffeolg0u').older_run_id('yhbg3wcea9y1l4asiltky5tupkgauzas')
+    >>> export = query.count_only(False).set_device_ids([12345]).async_export()
+    >>> export.await_completion()
+    >>> # write the results to a file
+    >>> export.get_output_as_file("example_data.json")

docs/getting-started.rst

@@ -19,8 +19,10 @@ See also the :doc:`installation` section of this documentation for more informat
 
 Authentication
 --------------
-In order to make use of the API, you will need an *API token,* which you will get from the Carbon Black Cloud UI.
-For the purposes of our example, we will need a custom key with the ability to list devices.
+To make use of APIs, you will need an *API token,* in case you are using Carbon Black Cloud to manage your
+identity and authentication, or if you are using VMware Cloud Services Platform, an *OAuth App with Bearer* or a *Personal API Token*.
+For our example, we will use a custom CBC-managed key with the ability to list devices.
+To learn more about the different authentication methods, click `here <https://developer.carbonblack.com/reference/carbon-black-cloud/authentication/>`_.
 
 Log into the Carbon Black Cloud UI and go to ``Settings > API Access``.  Start by selecting ``Access Levels`` at the
 top of the screen and press ``Add Access Level``.  Fill in a name and description for your sample access level, keep

docs/guides-and-resources.rst

@@ -28,6 +28,7 @@ Guides
 
 * :doc:`alerts` - Work and manage different types of alerts such as CB Analytics Alert, Watchlist Alerts and Device Control Alerts.
 * :doc:`device-control` - Control the blocking of USB devices on endpoints.
+* :doc:`differential-analysis` - Provides the ability to compare and understand the changes between two Live Query runs
 * :doc:`live-query` - Live Query allows operators to ask questions of endpoints
 * :doc:`live-response` - Live Response allows security operators to collect information and take action on remote endpoints in real time.
 * :doc:`recommendations` - Work with Endpoint Standard recommendations for reputation override.

docs/index.rst

@@ -19,6 +19,7 @@ Major Features
     * Endpoint Standard
     * Audit and Remediation
     * Enterprise EDR
+    * Platform
     * Workload
 - Reduced Complexity
     The SDK manages the differences among Carbon Black Cloud APIs
@@ -44,7 +45,8 @@ API Credentials
 ---------------
 
 To use the SDK and access data in Carbon Black Cloud, you must set up API keys with
-the correct permissions. Different APIs have different permission requirements for use,
+the correct permissions if you are using the X-Auth-Token authentication method, or create an access token
+if you are using Bearer or Personal API Token. Different APIs have different permission requirements for use,
 which is explained in the `Developer Network Authentication Guide
 <https://developer.carbonblack.com/reference/carbon-black-cloud/authentication/>`_.