Merge pull request #348 from carbonblack/release-1.4.2

CBAPI-4016: Merge Release 1.4.2 to master
carbonblack · Mar 22, 2023 · a65c283 · a65c283
2 parents 31caa9e + bf01c63
commit a65c283
Show file tree

Hide file tree

Showing 160 changed files with 8,840 additions and 911 deletions.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020-2022 VMware Inc.
+Copyright (c) 2020-2023 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

diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # VMware Carbon Black Cloud Python SDK
 
-**Latest Version:** 1.4.1
+**Latest Version:** 1.4.2
 <br>
-**Release Date:** October 21, 2022
+**Release Date:** March 22, 2023
 
 [![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)
@@ -51,6 +51,7 @@ At least one Carbon Black Cloud product is required to use this SDK:
 - python-dateutil
 - schema
 - solrq
+- jsonschema
 - validators
 - keyring (for MacOS)
 
@@ -126,6 +127,10 @@ The documentation is built in `docs/_build/html`.
 `No module named 'cbc_sdk'`.  If so, set your `PYTHONPATH` to include the `src/` subdirectory of the SDK project
 directory before running `make html`, or the equivalent command `sphinx-build -M html . _build`.
 
+#### Pull-Requests
+
+The webhook with readthedocs will create a build of the branch and report on the status of the build to the GitHub pull request
+
 #### Using Docker
 
 Build the documentation by running:

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-1.4.1
+1.4.2
diff --git a/bin/cbc-sdk-help.py b/bin/cbc-sdk-help.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2023. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *

diff --git a/bin/set-macos-keychain.py b/bin/set-macos-keychain.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2023. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *

diff --git a/bin/set-windows-registry.py b/bin/set-windows-registry.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2023. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *

diff --git a/docker/amazon/Dockerfile b/docker/amazon/Dockerfile
@@ -5,5 +5,7 @@ COPY . /app
 WORKDIR /app
 
 RUN yum -y install python3-devel
+RUN yum -y install python3-pip
+RUN pip3 install setuptools
 RUN pip3 install -r requirements.txt
 RUN pip3 install .
diff --git a/docker/rhel/Dockerfile b/docker/rhel/Dockerfile
@@ -6,5 +6,4 @@ WORKDIR /app
 
 RUN dnf install -y redhat-rpm-config gcc libffi-devel python38-devel openssl-devel
 RUN pip3 install --upgrade pip
-RUN pip3 install -r requirements.txt
-RUN pip3 install .
+RUN pip3 install .[test]
diff --git a/docs/alerts.rst b/docs/alerts.rst
@@ -48,6 +48,15 @@ for more complex searches. The example below will search with a solr query searc
     9d327888-<truncated> WINDOWS WINDOWS-TEST THREAT
     aab3c640-<truncated> WINDOWS WINDOWS-TEST THREAT
 
+.. tip::
+    When filtering by fields that take a list parameter, an empty list will be treated as a wildcard and match everything.
+
+Ex: Returns all types
+
+.. code-block:: python
+
+    >>> alerts = list(cb.select(BaseAlert).set_types([]))
+
 .. tip::
     More information about the ``solrq`` can be found in the
     their `documentation <https://solrq.readthedocs.io/en/latest/index.html>`_.
@@ -68,6 +77,45 @@ You can also filter on different kind of **TTPs** (*Tools Techniques Procedures*
     ...
 
 
+Retrieving Alerts for Multiple Organizations
+--------------------------------------------
+
+With the example below, you can retrieve alerts for multiple organizations.
+
+.. code-block:: python
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.platform import BaseAlert
+    >>> org_list = ["org1", "org2"]
+    >>> for org in org_list:
+    ...     org = ''.join(org)
+    ...     api = CBCloudAPI(profile=org)
+    ...     alerts = api.select(BaseAlert).set_minimum_severity(7)[:5]
+    ...     print('Results for Org {}'.format(org))
+    >>> for alert in alerts:
+    ...     print(alert.id, alert.device_os, alert.device_name, alert.category)
+    ...
+    ...
+
+
+You can also read from a csv file with values that match the profile names in your credentials.cbc file.
+
+    >>> from cbc_sdk import CBCloudAPI
+    >>> from cbc_sdk.platform import BaseAlert
+    >>> import csv
+    >>> file = open ("data.csv", "r", encoding='utf-8-sig')
+    >>> org_list = list(csv.reader(file, delimiter=","))
+    >>> file.close()
+    >>> for org in org_list:
+    ...     org = ''.join(org)
+    ...     api = CBCloudAPI(profile=org)
+    ...     alerts = api.select(BaseAlert).set_minimum_severity(7)[:5]
+    ...     print('Results for Org {}'.format(org))
+    >>> for alert in alerts:
+    ...     print(alert.id, alert.device_os, alert.device_name, alert.category)
+    ...
+    ...
+
 Retrieving of Carbon Black Analytics Alerts (CBAnalyticsAlert)
 --------------------------------------------------------------
 

diff --git a/docs/cbc_sdk.enterprise_edr.rst b/docs/cbc_sdk.enterprise_edr.rst
@@ -4,6 +4,14 @@ Enterprise EDR
 Submodules
 ----------
 
+cbc\_sdk.enterprise\_edr.auth\_events module
+--------------------------------------------
+
+.. automodule:: cbc_sdk.enterprise_edr.auth_events
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 cbc\_sdk.enterprise\_edr.threat\_intelligence module
 ----------------------------------------------------
 

diff --git a/docs/cbc_sdk.platform.rst b/docs/cbc_sdk.platform.rst
@@ -52,6 +52,22 @@ cbc\_sdk.platform.jobs module
    :undoc-members:
    :show-inheritance:
 
+cbc\_sdk.platform.network_threat_metadata module
+------------------------------------------------
+
+.. automodule:: cbc_sdk.platform.network_threat_metadata
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cbc\_sdk.platform.observations module
+-------------------------------------
+
+.. automodule:: cbc_sdk.platform.observations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 cbc\_sdk.platform.policies module
 ----------------------------------
 
@@ -60,6 +76,14 @@ cbc\_sdk.platform.policies module
    :undoc-members:
    :show-inheritance:
 
+cbc\_sdk.platform.policy_ruleconfigs module
+-------------------------------------------
+
+.. automodule:: cbc_sdk.platform.policy_ruleconfigs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 cbc\_sdk.platform.processes module
 ----------------------------------
 

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,5 +1,35 @@
 Changelog
 ================================
+CBC SDK 1.4.2 - Released March 22, 2023
+---------------------------------------
+
+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.
+
 CBC SDK 1.4.1 - Released October 21, 2022
 -----------------------------------------
 
@@ -77,7 +107,7 @@ New Features:
 
 Updates:
 
-* Endpoint Standard specific ``Event``s have been decommissioned and removed.
+* 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:

diff --git a/docs/concepts.rst b/docs/concepts.rst
@@ -513,3 +513,84 @@ Get details for all events per alert
   Category: ['OBSERVED']
   Type: NETWORK
   Alert Id: ['BE084638']
+
+
+Static Methods
+--------------
+
+In version 1.4.2 we introduced static methods on some classes. They handle API requests that are not tied to a specific resource id, thus they cannot be instance methods, instead static helper methods. Because those methods are static, they need a CBCloudAPI object to be passed as the first argument.
+
+Search suggestions
+^^^^^^^^^^^^^^^^^^
+
+::
+
+  # Search Suggestions for Observation
+  >>> from cbc_sdk import CBCloudAPI
+  >>> from cbc_sdk.platform import Observation
+  >>> api = CBCloudAPI(profile='platform')
+  >>> suggestions = Observation.search_suggestions(api, query="device_id", count=2)
+  >>> for suggestion in suggestions:
+  ...     print(suggestion["term"], suggestion["required_skus_all"], suggestion["required_skus_some"])
+  device_id [] ['threathunter', 'defense']
+  netconn_remote_device_id ['xdr'] []
+
+
+::
+
+  # Search Suggestions for Alerts
+  >>> from cbc_sdk import CBCloudAPI
+  >>> from cbc_sdk.platform import BaseAlert
+  >>> api = CBCloudAPI(profile='platform')
+  >>> suggestions = BaseAlert.search_suggestions(api, query="device_id")
+  >>> for suggestion in suggestions:
+  ...     print(suggestion["term"], suggestion["required_skus_some"])
+  device_id ['defense', 'threathunter', 'deviceControl']
+  device_os ['defense', 'threathunter', 'deviceControl']
+  ...
+  workload_name ['kubernetesSecurityRuntimeProtection']
+
+
+Bulk Get Details
+^^^^^^^^^^^^^^^^
+
+::
+
+  # Observations get details per alert id
+  >>> from cbc_sdk import CBCloudAPI
+  >>> from cbc_sdk.platform import Observation
+  >>> api = CBCloudAPI(profile='platform')
+  >>> bulk_details = Observation.bulk_get_details(api, alert_id="4d49d171-0a11-0731-5172-d0963b77d422")
+  >>> for obs in bulk_details:
+  ...     print(
+  ...         f'''
+  ...         Category: {obs.alert_category}
+  ...         Type: {obs.observation_type}
+  ...         Alert Id: {obs.alert_id}
+  ...         ''')
+  Category: ['THREAT']
+  Type: CB_ANALYTICS
+  Alert Id: ['4d49d171-0a11-0731-5172-d0963b77d422']
+
+::
+
+  # Observations get details per observation_ids
+  >>> from cbc_sdk import CBCloudAPI
+  >>> from cbc_sdk.platform import Observation
+  >>> api = CBCloudAPI(profile='platform')
+  >>> bulk_details = Observation.bulk_get_details(api, observation_ids=["13A5F4E5-C4BD-11ED-A7AB-005056A5B601:13a5f4e4-c4bd-11ed-a7ab-005056a5b611", "13A5F4E5-C4BD-11ED-A7AB-005056A5B601:13a5f4e4-c4bd-11ed-a7ab-005056a5b622"])
+  >>> for obs in bulk_details:
+  ...     print(
+  ...         f'''
+  ...         Category: {obs.alert_category}
+  ...         Type: {obs.observation_type}
+  ...         Alert Id: {obs.alert_id}
+  ...         ''')
+  Category: ['THREAT']
+  Type: CB_ANALYTICS
+  Alert Id: ['4d49d171-0a11-0731-5172-d0963b77d422']
+
+  Category: ['THREAT']
+  Type: CB_ANALYTICS
+  Alert Id: ['4d49d171-0a11-0731-5172-d0963b77d411']
+  
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,11 +19,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Carbon Black Cloud Python SDK'
-copyright = '2020-2022, Developer Relations'
+copyright = '2020-2023 VMware Carbon Black'
 author = 'Developer Relations'
 
 # The full version, including alpha/beta/rc tags
-release = '1.4.1'
+release = '1.4.2'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/developing-credential-providers.rst b/docs/developing-credential-providers.rst
@@ -17,7 +17,9 @@ to initialize your credential provider in any desired fashion.
 Using the Credential Provider
 -----------------------------
 Create an instance of your credential provider object and pass it as the keyword parameter
-``credential_provider`` when creating your ``CBCloudAPI`` object.  Example:
+``credential_provider`` when creating your ``CBCloudAPI`` object.
+
+Example:
 
     >>> provider = MyCredentialProvider()
     >>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')

diff --git a/docs/differential-analysis.rst b/docs/differential-analysis.rst
@@ -34,6 +34,8 @@ This example shows the basic result of the ``Differential`` object. The ``.newer
 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.
 
+.. code-block:: python
+
     >>> from cbc_sdk import CBCloudAPI
     >>> from cbc_sdk.audit_remediation import Differential
     >>>

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,3 +2,7 @@
 sphinxcontrib-apidoc
 sphinx-copybutton==0.4.0
 pygments
+
+# Broken dependencies (Need pre-installed to prevent build failure)
+jsonschema
+keyring
diff --git a/env.encrypted b/env.encrypted
@@ -1,2 +1,2 @@
 codeship:v2
-LShMGA33kd7ce5I9QKze/0fXoQaZ2E2dKhQeRAJ0cWckAvpXsS6a7Foz1MvITJGhrXd2mUew3qDet+pHufwL5U01x6ATlMFpTOc9ylThuM2mlgEJNWwiWkBlCim738/lBOuHY/yvaA==
+P6Dnl29DbHpvZH/JBP6CItPiOK4bOoY314TMdGZXV+hoEu35jru3KpdqNs+eJJBQykd4KPVzO3fEdQ7BsyaNwWxZc5QmJVSfeLIb79huhqLFZAGpGRFvuqCzOnMvavRRJz3M21B5wQ==
diff --git a/examples/audit_remediation/manage_run.py b/examples/audit_remediation/manage_run.py
@@ -1,5 +1,5 @@
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2023. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *

diff --git a/examples/endpoint_standard/enriched_events_query.py b/examples/endpoint_standard/enriched_events_query.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2023. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *

diff --git a/examples/endpoint_standard/policy_operations.py b/examples/endpoint_standard/policy_operations.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 # *******************************************************
-# Copyright (c) VMware, Inc. 2020-2022. All Rights Reserved.
+# Copyright (c) VMware, Inc. 2020-2023. All Rights Reserved.
 # SPDX-License-Identifier: MIT
 # *******************************************************
 # *