Merge pull request #191 from carbonblack/develop

Carbon Black Cloud SDK v1.3.0
carbonblack · Jun 8, 2021 · 5398655 · 5398655
2 parents fecfb58 + dfb167a
commit 5398655
Show file tree

Hide file tree

Showing 95 changed files with 10,747 additions and 4,636 deletions.
diff --git a/.gitignore b/.gitignore
@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/log.txt
 
 # PyBuilder
 target/

diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # VMware Carbon Black Cloud Python SDK
 
-**Latest Version:** 1.2.3
+**Latest Version:** 1.3.0
 <br>
-**Release Date:** 19 April 2021
+**Release Date:** 08 June 2021
 
 [![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)

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-1.2.3
+1.3.0
diff --git a/docs/authentication.rst b/docs/authentication.rst
@@ -16,11 +16,9 @@ specific actions, and use them as needed.
 For example, if using the
 `Platform Devices API <https://developer.carbonblack.com/reference/carbon-black-cloud/platform/latest/devices-api/#search-devices>`_
 to search for mission critical devices, and the
-`Endpoint Standard Live Response API <https://developer.carbonblack.com/reference/carbon-black-cloud/cb-defense/latest/live-response-api/>`_
-to execute commands on those devices, generate two API Keys. The Platform API Key should have the
-Custom Access Level, and the Live Response Key should have the Live Response Access Level.
-Store these Keys with profile names, and reference the profile names when creating
-CBCloudAPI objects.
+`Platform Live Response API <https://developer.carbonblack.com/reference/carbon-black-cloud/platform/latest/live-response-api/>`_
+to execute commands on those devices, generate one API Key with Custom Access Level with appropriate permissions.
+Store the Key with profile name, and reference the profile name when creating CBCloudAPI objects.
 
 ::
 
@@ -31,17 +29,16 @@ CBCloudAPI objects.
   # create Platform API object
   >>> platform_api = CBCloudAPI(profile='platform')
 
-  # create Live Response API object
-  >>> live_response_api = CBCloudAPI(profile='live_response')
-
   # search for specific devices with Platform Devices API
   >>> important_devs = platform_api.select(Device).set_target_priorities("MISSION_CRITICAL")
 
   # execute commands with Live Response API
   >>> for device in important_devs:
-  ...      lr_session = live_response_api.live_response.request_session(device.id)
+  ...      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`
 
 
 

diff --git a/docs/cbc_sdk.platform.rst b/docs/cbc_sdk.platform.rst
@@ -36,6 +36,14 @@ cbc\_sdk.platform.events module
   :undoc-members:
   :show-inheritance:
 
+cbc\_sdk.platform.grants module
+-------------------------------
+
+.. automodule:: cbc_sdk.platform.grants
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
 cbc\_sdk.platform.processes module
 ----------------------------------
 
@@ -52,6 +60,14 @@ cbc\_sdk.platform.reputation module
   :undoc-members:
   :show-inheritance:
 
+cbc\_sdk.platform.users module
+------------------------------
+
+.. automodule:: cbc_sdk.platform.users
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
 Module contents
 ---------------
 

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,5 +1,42 @@
 Changelog
 ================================
+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-v6-migration>`)
+
+  * 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
 --------------------------------------

diff --git a/docs/concepts.rst b/docs/concepts.rst
@@ -18,7 +18,7 @@ then you must use Endpoint Standard Devices and a Live Response API Key.
         Device ID: {device.id}
         Device Name: {device.name}
 
-        '''
+        ''')
   Device ID: 1234
   Device Name: Win10x64
 
@@ -30,9 +30,11 @@ then you must use Endpoint Standard Devices and a Live Response API Key.
   >>> api = CBCloudAPI(profile='live_response')
   >>> endpoint_standard_device = api.select(endpoint_standard.Device, 1234)
   >>> endpoint_standard_device.lr_session()
-  url: /integrationServices/v3/cblr/session/428:1234 -> status: PENDING
+  url: /appservices/v6/orgs/{org_key}/liveresponse/sessions/428:1234 -> status: PENDING
   [...]
 
+  For more examples on Live Response, check :doc:`live-response`
+
 USB Devices
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -449,3 +451,53 @@ Modules with support for facet searches
 :mod:`EventFacet <cbc_sdk.platform.base.EventFacet>`
 
 :mod:`EnrichedEventFacet <cbc_sdk.endpoint_standard.base.EnrichedEventFacet>`
+
+
+Enriched Events
+---------------
+
+We can return the details for the enriched event for a specific event or we could return the details for all enriched events per alert.
+
+Get details per event
+^^^^^^^^^^^^^^^^^^^^^
+
+:: 
+
+  >>> query = cb.select(EnrichedEvent).where(alert_category='THREAT')
+  >>> # get the first event returned by the query
+  >>> item = query[0]
+  >>> details = item.get_details()
+  >>> print(
+      f'''
+      Category: {details.alert_category}
+      Type: {details.enriched_event_type}
+      Alert Id: {details.alert_id}
+      ''')
+  Category: ['THREAT'])
+  Type: CREATE_PROCESS
+  Alert Id: ['3F0D00A6']
+
+Get details for all events per alert
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+  # Alert information is accessible with Platform CBAnalyticsAlert
+  >>> api = CBCloudAPI(profile='platform')
+  >>> query = cb.select(CBAnalyticsAlert).set_create_time(range="-4w")
+  >>> # 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}
+        ''')
+  Category: ['OBSERVED']
+  Type: SYSTEM_API_CALL
+  Alert Id: ['BE084638']
+            
+  Category: ['OBSERVED']
+  Type: NETWORK
+  Alert Id: ['BE084638']
diff --git a/docs/conf.py b/docs/conf.py
@@ -23,7 +23,7 @@
 author = 'Developer Relations'
 
 # The full version, including alpha/beta/rc tags
-release = '1.2.3'
+release = '1.3.0'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/guides-and-resources.rst b/docs/guides-and-resources.rst
@@ -17,6 +17,8 @@ Guides
 * :doc:`device-control` - Control the blocking of USB devices on endpoints.
 * :doc:`workload` - Advanced protection purpose-built for securing modern workloads to reduce the attack surface and strengthen security posture.
 * :doc:`reputation-override` - Manage reputation overrides for known applications, IT tools or certs.
+* :doc:`live-response` - Live Response allows security operators to collect information and take action on remote endpoints in real time.
+* :doc:`unified-binary-store` - The unified binary store (UBS) is responsible for storing all binaries and corresponding metadata for those binaries. 
 
 Examples
 --------

diff --git a/docs/live-response-v6-migration.rst b/docs/live-response-v6-migration.rst
@@ -0,0 +1,100 @@
+Migration Guide For Live Response From v3 To v6
+=========================================================
+This guide will help you migrate from Live Response v3 to v6.
+
+Overview
+--------
+Most of the changes from v3 to v6 are on the routes. Thе updated API (v6) includes a more granular approach to roles-based access
+control (RBAC).
+
+Access Permissions
+------------------
+A key wth a Custom Access Level with appropriate permissions needs to be created for the Live Response. The following
+table shows the corresponding permissions that needs to be enabled, based on the existing roles.
+
++---------------------------+-------------------------------------------------------------------------------+------------------------------------+
+|        Permission         |           What it controls (commands)                                         |  Which existing roles have access  |
++===========================+===============================================================================+====================================+
+|     org.liveresponse      | | Permanently disabling the Live Response feature on an individual endpoint:  | | Level 3 Analyst                  |
+|                           | | Disable Live Response on the Endpoints page                                 | | Live Response Admin - Legacy     |
+|                           |                                                                               | | Super Admin                      |
++---------------------------+-------------------------------------------------------------------------------+------------------------------------+
+|  org.liveresponse.files   | | Read, write and/or delete files on the endpoint:                            | | Level 2 Analyst                  |
+|                           | | cd, delete, dir, drives, get, mkdir, put, pwd                               | | Level 3 Analyst                  |
+|                           |                                                                               | | Live Response Admin - Legacy     |
+|                           |                                                                               | | Super Admin                      |
++---------------------------+-------------------------------------------------------------------------------+------------------------------------+
+| org.liveresponse.memdump  | | Dump kernel memory on the endpoint:                                         | | Level 3 Analyst                  |
+|                           | | memdump                                                                     | | Live Response Admin - Legacy     |
+|                           |                                                                               | | Super Admin                      |
++---------------------------+-------------------------------------------------------------------------------+------------------------------------+
+| org.liveresponse.process  | | List, stop and execute  processes on the endpoint:                          | | Level 2 Analyst (cannot execute) |
+|                           | | exec, execfg, kill, ps                                                      | | Level 3 Analyst                  |
+|                           |                                                                               | | Live Response Admin - Legacy     |
+|                           |                                                                               | | Super Admin                      |
++---------------------------+-------------------------------------------------------------------------------+------------------------------------+
+| org.liveresponse.registry | | View, add, edit and delete registry entries:                                | | Level 2 Analyst                  |
+|                           | | reg add, reg delete, reg query, reg set                                     | | Level 3 Analyst                  |
+|                           |                                                                               | | Live Response Admin - Legacy     |
+|                           |                                                                               | | Super Admin                      |
++---------------------------+-------------------------------------------------------------------------------+------------------------------------+
+| org.liveresponse.session  | | Initiate live response sessions, plus:                                      | | Level 2 Analyst                  |
+|                           | | clear, help                                                                 | | Level 3 Analyst                  |
+|                           |                                                                               | | Live Response Admin - Legacy     |
+|                           |                                                                               | | Super Admin                      |
++---------------------------+-------------------------------------------------------------------------------+------------------------------------+
+
+
+Changes in the routes and response codes
+----------------------------------------
+
++-----------------------------------------------------------+---------------------------------------------------------+
+| v3                                                        | v6                                                      |
++===========================================================+=========================================================+
+| /integrationServices/v3/cblr/                             | /appservices/v6/orgs/{org_key}/liveresponse/            |
++-----------------------------------------------------------+---------------------------------------------------------+
+| POST /sessions/{session_id} 200                           | POST /sessions 201                                      |
++-----------------------------------------------------------+---------------------------------------------------------+
+| POST /session/{session_id)/file    200                    | POST /sessions/{session_id)/files 201                   |
++-----------------------------------------------------------+---------------------------------------------------------+
+| POST /session/{session_id}/command                        | POST /sessions/{session_id}/commands                    |
++-----------------------------------------------------------+---------------------------------------------------------+
+| PUT /session {"session_id": "1:37191", "status": "CLOSE"} | DELETE /sessions/{session_id} 204                       |
++-----------------------------------------------------------+---------------------------------------------------------+
+| GET /session/{sessionId}/file/{fileId}/content   200      | GET /sessions/{session_id}/files/{file_id}/content 302  |
++-----------------------------------------------------------+---------------------------------------------------------+
+| DELETE /session/{sessionId}/file/{fileId} 200             | DELETE /sessions/{session_id}/files/{file_id} 204       |
++-----------------------------------------------------------+---------------------------------------------------------+
+
+
+Changes in some of the request/response fields
+----------------------------------------------
+
++----------------------+------------------+------------------+
+| Where is the change? | v3               | v6               |
++======================+==================+==================+
+| All API endpoints    | sensor_id        | device_id        |
++----------------------+------------------+------------------+
+| Process command      | username         | process_username |
++----------------------+------------------+------------------+
+| Process command      | path             | process_path     |
++----------------------+------------------+------------------+
+| Process command      | pid              | process_pid      |
++----------------------+------------------+------------------+
+| Process command      | command_line     | process_cmdline  |
++----------------------+------------------+------------------+
+| Process command      | parent           | parent_pid       |
++----------------------+------------------+------------------+
+| Registry command     | valueType        | value_type       |
++----------------------+------------------+------------------+
+| Registry command     | valueData        | value_data       |
++----------------------+------------------+------------------+
+| Registry command     | valueName        | value_name       |
++----------------------+------------------+------------------+
+
+
+Additional Information
+----------------------
+
+* `(CBC) Live Response API releasing v6: now with granular RBAC! <https://community.carbonblack.com/t5/Developer-Relations/CBC-Live-Response-API-releasing-v6-now-with-granular-RBAC/m-p/102358/thread-id/2595>`_
+* `Live Response Documentation <https://developer.carbonblack.com/reference/carbon-black-cloud/platform/latest/live-response-api/>`_