Merge pull request #285 from carbonblack/release-1.3.6

CBAPI-3698: Release 1.3.6 merge to master

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020-2021 Carbon Black
+Copyright (c) 2020-2022 VMware Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,8 +1,8 @@
 # VMware Carbon Black Cloud Python SDK
 
-**Latest Version:** 1.3.5
+**Latest Version:** 1.3.6
 <br>
-**Release Date:** January 26, 2022
+**Release Date:** April 19, 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)
@@ -44,8 +44,6 @@ At least one Carbon Black Cloud product is required to use this SDK:
 * [Enterprise EDR](https://developer.carbonblack.com/reference/carbon-black-cloud/cb-threathunter/)
 * [Workload](https://developer.carbonblack.com/reference/carbon-black-cloud/workload-protection/)
 
-_Note: Support for the latest products such as Containers are planned for early 2021_
-
 ### Python Packages
 
 - requests
@@ -95,6 +93,8 @@ cd carbon-black-cloud-sdk-python
 pip install -r requirements.txt
 ```
 
+**Note: Before contributing any code please make sure to read the [CONTRIBUTING](CONTRIBUTING.md) page.**
+
 If you want to test/execute the example scripts from the repo then install the SDK with the following command. This will install the SDK in editable mode so changes to the repo modify the installed package.
 
 ```
@@ -135,12 +135,9 @@ directory before running `make html`, or the equivalent command `sphinx-build -M
 
 Build the documentation by running:
 ```shell
-$ docker-compose -f docker/docs/docker-compose.yml up --build docs
+$ docker run -p 7000:7000 -it $(docker build -f ./docker/docs/Dockerfile . -q) make livehtml
 ```
 
-The service will start a local docs server at `:7000`. The server is using `sphinx-autobuild` with the `--watch` option 
-enabled, so you can live edit the documentation. Check the additional options and configs in the compose file.
-
 ### Development Flow
 
 To begin a code change, start by creating a branch off of the develop branch.

VERSION

@@ -1 +1 @@
-1.3.5
+1.3.6

bin/cbc-sdk-help.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2021. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *

bin/set-macos-keychain.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2021. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *

bin/set-windows-registry.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2021. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *

docker/docs/Dockerfile

@@ -16,11 +16,11 @@ RUN apt-get update \
     && apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false \
     && rm -rf /var/lib/apt/lists/*
 
-# All imports needed for autodoc.
-RUN pip install --no-input Sphinx sphinx-autobuild sphinx-rtd-theme
+# Copy the application
+COPY . /app
 
-COPY ./docs/start /start-docs
-RUN sed -i 's/\r$//g' /start-docs
-RUN chmod +x /start-docs
+RUN pip install --no-input Sphinx sphinx-autobuild sphinx-rtd-theme \
+    && pip install -r app/docs/requirements.txt \
+    && pip install /app
 
-WORKDIR /docs
+WORKDIR /app/docs/

docs/alerts.rst

@@ -208,6 +208,14 @@ Device Control Alerts
 
 The Device Control Alerts are explained in the :doc:`device-control` guide.
 
+Container Runtime Alerts
+------------------------
+
+These represent alerts for behavior noticed inside a Kubernetes container, which are based on network traffic and are
+triggered by anomalies from the learned behavior of workloads or applications.  For these events, the ``type`` will be
+``CONTAINER_RUNTIME``, the ``device_id`` will always be 0, and the ``device_name``, ``device_os``,
+``device_os_version``, and ``device_username`` will always be ``None``. Instead, the workload generating the alert will
+be identified by the ``workload_id`` and ``workload_name`` attributes.
 
 Migrating from Notifications to Alerts
 --------------------------------------
@@ -237,4 +245,4 @@ Those settings shown in the screenshot can be replicated with the following code
 Advanced usage of alerts
 ------------------------
 
-If you want near-real-time streaming of an alerts we advice you to referer our `Data Forwarded <https://developer.carbonblack.com/reference/carbon-black-cloud/platform/latest/data-forwarder-config-api/>`_.
+If you want near-real-time streaming of alerts we advise you to refer to our `Data Forwarder <https://developer.carbonblack.com/reference/carbon-black-cloud/platform/latest/data-forwarder-api/>`_.

docs/authentication.rst

@@ -34,9 +34,9 @@ Store the Key with profile name, and reference the profile name when creating CB
 
   # execute commands with Live Response API
   >>> for device in important_devs:
-  ...      lr_session = platform_api.live_response.request_session(device.id)
-  ...      lr_session.create_process(r'cmd.exe /c "ping.exe 192.168.1.1"'))
-  ...      lr_session.close()
+  ...     lr_session = platform_api.live_response.request_session(device.id)
+  ...     lr_session.create_process(r'cmd.exe /c "ping.exe 192.168.1.1"')
+  ...     lr_session.close()
 
 For more examples on Live Response, check :doc:`live-response`
 
@@ -92,8 +92,8 @@ Authentication Methods
   via keyword parameters. This method should be used with caution, taking care to not
   share your API credentials when managing code with source control.
 
-    >>> cbc_api = CBCloudAPI(url='defense.conferdeploy.net', token=ABCD/1234,
-    ...                         org_key='ABCDEFGH')
+    >>> cbc_api = CBCloudAPI(url='https://defense.conferdeploy.net', token='ABCD/1234',
+    ...     org_key='ABCDEFGH')
 
 **Not Recommended**:
 

docs/cbc_sdk.endpoint_standard.rst

@@ -1,6 +1,16 @@
 Endpoint Standard
 =================
 
+Decommissioned Functionality
+----------------------------
+
+The Endpoint Standard events (``cbc_sdk.endpoint_standard.Event``) have been decommissioned and should no longer be
+used.  Any attempt to use them will raise a ``FunctionalityDecommissioned`` exception.  Please use
+``cbc_sdk.endpoint_standard.EnrichedEvent`` instead.  Refer to
+`this migration guide
+<https://community.carbonblack.com/t5/Developer-Relations/Migration-Guide-Carbon-Black-Cloud-Events-API/m-p/95915/thread-id/2519>`_
+on the Carbon Black Developer Network Community for more information.
+
 Submodules
 ----------
 

docs/cbc_sdk.workload.rst

@@ -4,6 +4,14 @@ Workload
 Submodules
 ----------
 
+cbc\_sdk.workload.nsx\_remediation module
+------------------------------------------
+
+.. automodule:: cbc_sdk.workload.nsx_remediation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 cbc\_sdk.workload.sensor\_lifecycle module
 ------------------------------------------
 

docs/changelog.rst

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

docs/concepts.rst

@@ -53,11 +53,10 @@ to USB devices is through the Endpoint Standard package ``from cbc_sdk.endpoint_
   >>> api = CBCloudAPI(profile='endpoint_standard')
   >>> usb_devices = api.select(USBDevice).set_statuses(['APPROVED'])
   >>> for usb in usb_devices:
-  ...   print(f'''
-              USB Device ID: {usb.id}
-              USB Device: {usb.vendor_name} {usb.product_name}
-
-              ''')
+  ...     print(f'''
+  ...         USB Device ID: {usb.id}
+  ...         USB Device: {usb.vendor_name} {usb.product_name}
+  ...         ''')
   USB Device ID: 774
   USB Device: SanDisk Ultra
 
@@ -425,7 +424,6 @@ Create the query:
     >>> print(synchronous_results)
     EventFacet object, bound to https://defense-eap01.conferdeploy.net.
     -------------------------------------------------------------------------------
-
                num_found: 16
       processed_segments: 1
                   ranges: [{'start': '2020-10-16T00:00:00Z', 'end': '2020...
@@ -439,7 +437,6 @@ Create the query:
     >>> print(asynchronous_result)
     EventFacet object, bound to https://defense-eap01.conferdeploy.net.
     -------------------------------------------------------------------------------
-
                num_found: 16
       processed_segments: 1
                   ranges: [{'start': '2020-10-16T00:00:00Z', 'end': '2020...
@@ -481,11 +478,11 @@ Get details per event
   >>> item = query[0]
   >>> details = item.get_details()
   >>> print(
-      f'''
-      Category: {details.alert_category}
-      Type: {details.enriched_event_type}
-      Alert Id: {details.alert_id}
-      ''')
+  ...     f'''
+  ...     Category: {details.alert_category}
+  ...     Type: {details.enriched_event_type}
+  ...     Alert Id: {details.alert_id}
+  ...     ''')
   Category: ['THREAT'])
   Type: CREATE_PROCESS
   Alert Id: ['3F0D00A6']
@@ -503,12 +500,12 @@ Get details for all events per alert
   >>> # get the first alert returned by the query
   >>> alert = query[0]
   >>> for event in alert.get_events():
-  ...   print(
-        f'''
-        Category: {event.alert_category}
-        Type: {event.enriched_event_type}
-        Alert Id: {event.alert_id}
-        ''')
+  ...     print(
+  ...         f'''
+  ...         Category: {event.alert_category}
+  ...         Type: {event.enriched_event_type}
+  ...         Alert Id: {event.alert_id}
+  ...         ''')
   Category: ['OBSERVED']
   Type: SYSTEM_API_CALL
   Alert Id: ['BE084638']

docs/conf.py

@@ -19,11 +19,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Carbon Black Cloud Python SDK'
-copyright = '2020-2021, Developer Relations'
+copyright = '2020-2022, Developer Relations'
 author = 'Developer Relations'
 
 # The full version, including alpha/beta/rc tags
-release = '1.3.5'
+release = '1.3.6'
 
 
 # -- General configuration ---------------------------------------------------
@@ -51,6 +51,8 @@
 # unit titles (such as .. function::).
 add_module_names = False
 
+# Generate unique labels
+autosectionlabel_prefix_document = True
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -130,8 +132,12 @@
 
 autoclass_content = 'both'
 
-# options for sphinx generation
-copybutton_prompt_text = ">>> "
+# options for sphinx generation.
+# use a regular expression to strip standard prompt and continuation when copying an example
+copybutton_prompt_is_regexp = True
+copybutton_remove_prompts = True
+copybutton_prompt_text = r">>> |\.\.\. "
+
 
 def setup(app):
     """Setup Sphinx."""

docs/index.rst

@@ -16,7 +16,10 @@ harness the full power of Carbon Black Cloud APIs.
 Major Features
 --------------
 - Supports the following Carbon Black Cloud Products with extensions for new features and products planned
-    Endpoint Standard, Audit and Remediation, and Enterprise EDR
+    * Endpoint Standard
+    * Audit and Remediation
+    * Enterprise EDR
+    * Workload
 - Reduced Complexity
     The SDK manages the differences among Carbon Black Cloud APIs
     behind a single, consistent Python interface. Spend less time

docs/porting-guide.rst

@@ -49,7 +49,8 @@ Import statements will need to change:
     from cbapi.psc.defense import Device, Event, Policy
 
     # CBC SDK
-    from cbc_sdk.endpoint_standard import Device, Event, Policy
+    # note that the original "Event" has been decommissioned
+    from cbc_sdk.endpoint_standard import Device, EnrichedEvent, Policy
 
 ::
 
@@ -135,7 +136,8 @@ For help beyond import statement changes, check out these resources:
 
 Endpoint Standard
 """""""""""""""""
-Endpoint Standard Events are being replaced with Enriched Events.
+Endpoint Standard Events have been replaced with Enriched Events and the old event functionality has been
+decommissioned.
 
 ::
 
@@ -144,6 +146,9 @@ Endpoint Standard Events are being replaced with Enriched Events.
     # CBAPI
     from cbapi.psc.defense import Event
 
+    # CBC SDK (decommissioned--do not use)
+    from cbc_sdk.endpoint_standard import Event
+
     # CBC SDK
     from cbc_sdk.endpoint_standard import EnrichedEvent
 

docs/unified-binary-store.rst

@@ -41,7 +41,7 @@ We could set expiration period for the download link (in seconds).
 *Note: The download link for the binary will be active for 30 seconds.*
 
 Searching Binaries
------------------
+------------------
 
 Currently searching binaries is not possible, but we could use the following syntax to obtain a single binary.