Merge pull request #306 from carbonblack/develop

Release 1.7.6
Bug Fix: Removed the requirement for an admin token to connect
Bug Fix: Added sensor paginated query
Library update: Updated version of lxml library

README.md

@@ -1,6 +1,6 @@
 # Python bindings for Carbon Black REST API
 
-**Latest Version: 1.7.5**
+**Latest Version: 1.7.6**
 
 _**Notice**:_ 
 * The Carbon Black Cloud portion of CBAPI has moved to https://github.com/carbonblack/carbon-black-cloud-sdk-python. Any future development and bug fixes for Carbon Black Cloud APIs will be made there. Carbon Black EDR and App Control will remain supported at CBAPI

docs/changelog.rst

@@ -2,6 +2,17 @@ CbAPI Changelog
 ===============
 .. top-of-changelog (DO NOT REMOVE THIS COMMENT)
 
+CbAPI 1.7.6 - Release Dec 20, 2021
+------------------------------------
+
+Bug Fixes
+ * Removed the requirement for an admin token to connect
+ * Added sensor paginated query
+
+General
+ * Updated version of lxml library
+
+
 CbAPI 1.7.5 - Released June 16, 2021
 ------------------------------------
 

docs/concepts.rst

@@ -62,9 +62,9 @@ Joining Model Objects
 ---------------------
 
 Many times, there are relationships between different Model Objects. To make navigating these relationships easy,
-cbapi provides special properties to "join" Model Objects together. For example, a :py:mod:`cbapi.response.models.Process`
-Model Object can reference the :py:mod:`cbapi.response.models.Sensor` or :py:mod:`cbapi.response.models.Binary`
-associated with this Process.
+cbapi provides special properties to "join" Model Objects together. For example, a
+:py:mod:`cbapi.response.models.Process` Model Object can reference the :py:mod:`cbapi.response.models.Sensor` or
+:py:mod:`cbapi.response.models.Binary` associated with this Process.
 
 In this case, special "join" properties are provided for you. When you use one of these properties, cbapi will
 automatically retrieve the associated Model Object, if necessary.
@@ -186,8 +186,8 @@ represent these data types can be "created" in cbapi by using the ``create()`` m
 
 If you attempt to create a Model Object that cannot be created, you will receive a :py:mod:`ApiError` exception.
 
-Once a Model Object is created, it's blank (it has no data). You will need to set the required properties and then call the
-``.save()`` method::
+Once a Model Object is created, it's blank (it has no data). You will need to set the required properties and then call
+the ``.save()`` method::
 
     >>> bh = cb.create(BannedHash)
     >>> bh.text = "Banned from API"

docs/conf.py

@@ -61,7 +61,7 @@
 # The short X.Y version.
 version = u'1.7'
 # The full version, including alpha/beta/rc tags.
-release = u'1.7.5'
+release = u'1.7.6'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/defense-api.rst

@@ -1,14 +1,14 @@
 .. _defense_api:
 
-CB Defense API
-==============
+Cloud Endpoint Standard API
+===========================
 
-This page documents the public interfaces exposed by cbapi when communicating with a CB Defense server.
+This page documents the public interfaces exposed by cbapi when communicating with a Cloud Endpoint Standard server.
 
 Main Interface
 --------------
 
-To use cbapi with Carbon Black Defense, you will be using the CBDefenseAPI.
+To use cbapi with VMware Carbon Black Cloud Endpoint Standard, you will be using the CBDefenseAPI.
 The CBDefenseAPI object then exposes two main methods to select data on the Carbon Black server:
 
 .. autoclass:: cbapi.psc.defense.rest_api.CbDefenseAPI

docs/getting-started.rst

@@ -4,7 +4,8 @@ Getting Started
 First, let's make sure that your API authentication tokens have been imported into cbapi. Once that's done, then read
 on for the key concepts that will explain how to interact with Carbon Black APIs via cbapi.
 
-Feel free to follow along with this document or watch the `Development Environment Setup video <https://developer.carbonblack.com/guide/enterprise-response/development-environment-video/>`_
+Feel free to follow along with this document or watch the
+`Development Environment Setup video <https://developer.carbonblack.com/guide/enterprise-response/development-environment-video/>`_
 on the Developer Network website.
 
 API Authentication
@@ -36,7 +37,8 @@ Alternatively, if you're using Windows (change ``c:\python27`` if Python is inst
 This configuration script will walk you through entering your API credentials and will save them to your current user's
 credential file location, which is located in the ``.carbonblack`` directory in your user's home directory.
 
-If using cbapi-psc, you will also be asked to provide an org key. An org key is required to access the Carbon Black Cloud, and can be found in the console under Settings -> API Keys.
+If using cbapi-psc, you will also be asked to provide an org key. An org key is required to access the Carbon Black
+Cloud, and can be found in the console under Settings -> API Keys.
 
 Your First Query
 ----------------

docs/index.rst

@@ -13,7 +13,7 @@ This library provides a Pythonic layer to access the raw power of the REST APIs
 
    >>> from cbapi.response import CbResponseAPI, Process, Binary, Sensor
    >>> #
-   >>> # Create our CbAPI object
+   >>> # Create our EDR API object
    >>> #
    >>> c = CbResponseAPI()
    >>> #
@@ -43,7 +43,7 @@ If you're a Carbon Black App Control customer (formerly CB Protection), you may
    >>> from cbapi.protection.models import FileInstance
    >>> from cbapi.protection import CbProtectionAPI
    >>> #
-   >>> # Create our CB Protection API object
+   >>> # Create our App Control API object
    >>> #
    >>> p = CbProtectionAPI()
    >>> #
@@ -65,7 +65,7 @@ As of version 1.2, CBAPI also supports Carbon Black Cloud Endpoint Standard (for
 
    >>> from cbapi.psc.defense import *
    >>> #
-   >>> # Create our CB Defense API object
+   >>> # Create our Cloud Endpoint Standard API object
    >>> #
    >>> p = CbDefenseAPI()
    >>> #
@@ -116,7 +116,7 @@ Major Features
 API Credentials
 ---------------
 
-CBAPI version 0.9.0 enforces the use of credential files. 
+CBAPI version 0.9.0 enforces the use of credential files.
 
 In order to perform any queries via the API, you will need to get the API token for your CB user. See the documentation
 on the Developer Network website on how to acquire the API token for
@@ -130,13 +130,15 @@ Once you acquire your API token, place it in one of the default credentials file
 * ``~/.carbonblack/``
 * ``/current_working_directory/.carbonblack/``
 
-For distinction between credentials of different Carbon Black products, use the following naming convention for your credentials files:
+For distinction between credentials of different Carbon Black products, use the following naming convention for your
+credentials files:
 
 * ``credentials.psc`` for Carbon Black Cloud Endpoint Standard, Audit & Remediation, and Enterprise EDR (CB Defense, CB LiveOps, and CB ThreatHunter)
 * ``credentials.response`` for Carbon Black EDR (CB Response)
 * ``credentials.protection`` for Carbon Black App Control (CB Protection)
 
-For example, if you use a Carbon Black Cloud product, you should have created a credentials file in one of these locations:
+For example, if you use a Carbon Black Cloud product, you should have created a credentials file in one of these
+locations:
 
 * ``/etc/carbonblack/credentials.psc``
 * ``~/.carbonblack/credentials.psc``
@@ -188,8 +190,8 @@ The latest CBAPI for Python supports specifying API credentials in the following
 The `CBAPI_URL` envar holds the FQDN of the target, an EDR (CbR), CBD, or CbD/Carbon Black Cloud server specified just as they are in the
 configuration file format specified above.
 
-The  optional `CBAPI_SSL_VERIFY` envar can be used to control SSL validation(True/False or 0/1), which will default to ON when
-not explicitly set by the user.
+The  optional `CBAPI_SSL_VERIFY` envar can be used to control SSL validation(True/False or 0/1), which will default to
+ON when not explicitly set by the user.
 
 For environments where complex outbound network filters and proxy configurations are used (eg. anything other than
 an unauthenticated or basic password authenticated proxy) a prepared `requests.Session` object may be supplied as a
@@ -239,7 +241,7 @@ API Documentation
 -----------------
 
 Once you have read the User Guide, you can view `examples on GitHub <https://github.com/carbonblack/cbapi-python/tree/master/examples>`_
-or try writing code of your own. You can use the full API documentation below to see all the methods available in CBAPI 
+or try writing code of your own. You can use the full API documentation below to see all the methods available in CBAPI
 and unlock the full functionality of the SDK.
 
 .. toctree::

docs/installation.rst

@@ -39,8 +39,7 @@ https://www.python.org/ftp/python/3.6.4/python-3.6.4-amd64.exe.
    :alt: Windows installation options showing "Add python.exe to path"
    :align: right
 
-Ensure that the "Add Python to PATH" option is
-checked.
+Ensure that the "Add Python to PATH" option is checked.
 
 If for some reason you do not have pip installed, follow the instructions at this
 `handy guide <http://docs.python-guide.org/en/latest/starting/installation/>`_.
@@ -75,4 +74,3 @@ Once you have a copy of the source, you can install it in "development" mode int
 This will link the version of cbapi-python you checked out into your Python site-packages directory. Any changes you
 make to the checked out version of cbapi will be reflected in your local Python installation. This is a good choice
 if you are thinking of changing or developing on cbapi itself.
-

docs/live-response.rst

@@ -1,7 +1,7 @@
 CbAPI and Live Response
 =======================
 
-Working with the CB Live Response REST API directly can be difficult. Thankfully, just like the rest of Carbon
+Working with the Live Response REST API directly can be difficult. Thankfully, just like the rest of Carbon
 Black's REST APIs, cbapi provides Pythonic APIs to make working with the Live Response API much easier.
 
 In addition to easy-to-use APIs to call into Live Response, cbapi also provides a "job-based" interface that allows
@@ -92,4 +92,3 @@ back from the endpoint, and submit the ``.run()`` method to the Live Response Jo
 
 Your script resumes execution immediately after the call to ``.submit_job()``. The job(s) that you've submitted will
 be executed in a set of background threads managed by cbapi.
-

docs/livequery-api.rst

@@ -1,10 +1,9 @@
 .. _livequery_api:
 
 CB LiveQuery API
-===================
+================
 
-This page documents the public interfaces exposed by cbapi when communicating with
-Carbon Black LiveQuery devices.
+This page documents the public interfaces exposed by cbapi when communicating with Carbon Black LiveQuery devices.
 
 Main Interface
 --------------
@@ -20,9 +19,8 @@ The LiveQuery API is used in two stages: run submission and result retrieval.
 Queries
 -------
 
-The LiveQuery API uses QueryBuilder instances to construct structured
-or unstructured (i.e., raw string) queries. You can either construct these
-instances manually, or allow ``CbLiveQueryAPI.select()`` to do it for you:
+The LiveQuery API uses QueryBuilder instances to construct structured or unstructured (i.e., raw string) queries.
+You can either construct these instances manually, or allow ``CbLiveQueryAPI.select()`` to do it for you:
 
 .. autoclass:: cbapi.psc.livequery.query.QueryBuilder
     :members:

docs/livequery-examples.rst

@@ -14,14 +14,14 @@ Now that we've imported the necessary libraries, we can perform some queries on
 Create a Query Run
 ----------------------------------
 
-Let's create a Query Run. First, we specify which profile to use for authentication from our credentials.psc file and create the LiveQuery object.
+Let's create a Query Run. First, we specify which profile to use for authentication from our credentials.psc file and
+create the LiveQuery object.
 
     >>> profile = "default'
     >>> cb = CbLiveQueryAPI(profile=profile)
 
 Now, we specify the SQL query that we want to run, name of the run, device IDs, and device types.
 
-
     >>> sql = 'select * from logged_in_users;'
     >>> name_of_run = 'Selecting all logged in users'
     >>> device_ids = '1234567'
@@ -41,7 +41,8 @@ Finally, we submit the query and print the results.
 
 This query should return all logged in Windows endpoints with a ``device_id`` of ``1234567``.
 
-The same query can be executed with the example script `manage_run.py <https://github.com/carbonblack/cbapi-python/blob/master/examples/livequery/manage_run.py>`_. ::
+The same query can be executed with the example script
+`manage_run.py <https://github.com/carbonblack/cbapi-python/blob/master/examples/livequery/manage_run.py>`_. ::
 
     python manage_run.py --profile default create --sql 'select * from logged_in_users;' --name 'Selecting all logged in users' --device_ids '1234567' --device_types 'WINDOWS'
 
@@ -50,7 +51,8 @@ Other possible arguments to ``manage_run.py`` include ``--notify`` and ``--polic
 Get Query Run Status
 ---------------------
 
-Now that we've created a Query Run, let's check the status. If we haven't already authenticated with a credentials profile, we begin by specifying which profile to authenticate with.
+Now that we've created a Query Run, let's check the status. If we haven't already authenticated with a credentials
+profile, we begin by specifying which profile to authenticate with.
 
     >>> profile = 'default'
     >>> cb = CbLiveQueryAPI(profile=profile)
@@ -61,11 +63,13 @@ Next, we select the run with the unique run ID.
     >>> run = cb.select(Run, run_id)
     >>> print(run)
 
-This can also be accomplished with the example script `manage_run.py <https://github.com/carbonblack/cbapi-python/blob/master/examples/livequery/manage_run.py>`_::
+This can also be accomplished with the example script
+`manage_run.py <https://github.com/carbonblack/cbapi-python/blob/master/examples/livequery/manage_run.py>`_::
 
     python manage_run.py --profile default --id a4oh4fqtmrr8uxrdj6mm0mbjsyhdhhvz
 
-In addition, you can specify which order you want results returned. To change from the default ascending order, use the flag ``-d`` or ``--descending_results``::
+In addition, you can specify which order you want results returned. To change from the default ascending order, use
+the flag ``-d`` or ``--descending_results``::
 
     python manage_run.py --profile default --id a4oh4fqtmrr8uxrdj6mm0mbjsyhdhhvz --descending_results
 
@@ -105,6 +109,7 @@ Finally, we print the results.
     ...     print(result)
 
 
-You can also retrieve run results with the example script `run_search.py <https://github.com/carbonblack/cbapi-python/blob/master/examples/livequery/run_search.py>`_::
+You can also retrieve run results with the example script
+`run_search.py <https://github.com/carbonblack/cbapi-python/blob/master/examples/livequery/run_search.py>`_::
 
     python run_search.py --profile default --id a4oh4fqtmrr8uxrdj6mm0mbjsyhdhhvz --device_ids '1234567' --status 'matched'

docs/protection-api.rst

@@ -3,9 +3,6 @@
 Carbon Black App Control (CB Protection) API
 ===========================================
 
-This page documents the public interfaces exposed by cbapi when communicating with a Carbon Black App Control (Enterprise
-Protection) server.
-
 Main Interface
 --------------
 

docs/psc-api.rst

@@ -1,15 +1,14 @@
 .. _psc_api:
 
-CB PSC API
-==========
+VMware Carbon Black Cloud API
+=============================
 
-This page documents the public interfaces exposed by cbapi when communicating with
-the Carbon Black Predictive Security Cloud (PSC).
+This page documents the public interfaces exposed by cbapi when communicating with the VMware Carbon Black Cloud.
 
 Main Interface
 --------------
 
-To use cbapi with the Carbon Black PSC, you use CbPSCBaseAPI objects.
+To use cbapi with the VMware Carbon Black Cloud, you use CbPSCBaseAPI objects.
 
 .. autoclass:: cbapi.psc.rest_api.CbPSCBaseAPI
     :members:
@@ -18,7 +17,7 @@ To use cbapi with the Carbon Black PSC, you use CbPSCBaseAPI objects.
 Device API
 ----------
 
-The PSC can be used to enumerate devices within your organization, and change their
+The Carbon Black Cloud can be used to enumerate devices within your organization, and change their
 status via a control request.
 
 You can use the select() method on the CbPSCBaseAPI to create a query object for
@@ -45,12 +44,11 @@ Selects all devices running Linux from the current organization.
 Alerts API
 ----------
 
-Using the API, you can search for alerts within your organization, and dismiss or
-undismiss them, either individually or in bulk.
+Using the API, you can search for alerts within your organization, and dismiss or undismiss them, either individually
+or in bulk.
 
-You can use the select() method on the CbPSCBaseAPI to create a query object for
-BaseAlert objects, which can be used to locate a list of alerts.  You can also
-search for more specialized alert types:
+You can use the select() method on the CbPSCBaseAPI to create a query object for BaseAlert objects, which can be used
+to locate a list of alerts.  You can also search for more specialized alert types:
 
 * CBAnalyticsAlert - Alerts from CB Analytics
 * VMwareAlert - Alerts from VMware

docs/response-api.rst

@@ -3,9 +3,6 @@
 EDR (CB Response) API
 ===============
 
-This page documents the public interfaces exposed by cbapi when communicating with a Carbon Black EDR (Enterprise
-Response) server.
-
 Main Interface
 --------------
 
@@ -77,6 +74,3 @@ Process Operations
 .. automethod:: cbapi.live_response_api.CbLRSessionBase.kill_process
 .. automethod:: cbapi.live_response_api.CbLRSessionBase.create_process
 .. automethod:: cbapi.live_response_api.CbLRSessionBase.list_processes
-
-
-

docs/response-examples.rst

@@ -1,10 +1,6 @@
 EDR (CB Response) API Examples
 ==============================
 
-Now that we've covered the basics, let's step through a few examples using the EDR (CB Response) API. In these examples,
-we will assume the following boilerplate code to enable logging and establish a connection to the "default"
-EDR (CB Response) server in our credential file::
-
     >>> import logging
     >>> root = logging.getLogger()
     >>> root.addHandler(logging.StreamHandler())
@@ -246,7 +242,7 @@ the command name ``cmd.exe``. Just add the ``.group_by("id")`` filter to your qu
 Feed and Watchlist Maintenance
 ------------------------------
 
-The cbapi provides several helper functions to assist in creating watchlists and
+The cbapi provides several helper functions to assist in creating watchlists and feeds.
 
 Watchlists are simply saved Queries that are automatically run on the EDR (CB Response) server on a periodic basis. Results
 of the watchlist are tagged in the database and optionally trigger alerts. Therefore, a cbapi Query can easily be
@@ -295,9 +291,10 @@ The cbapi provides helper functions to manage alerts and threat reports in bulk.
 the ThreatReport and Alert Model Objects provide a few bulk operations to help manage large numbers of Threat Reports
 and Alerts, respectively.
 
-To mark a large number of Threat Reports as false positives, create a query that matches the Reports you're interested in.
-For example, if every Report from the Feed named "SOC" that contains the word "FUZZYWOMBAT" in the report title should be
-considered a false positive (and no longer trigger Alerts), you can write the following code to do so::
+To mark a large number of Threat Reports as false positives, create a query that matches the Reports you're
+interested in.  For example, if every Report from the Feed named "SOC" that contains the word "FUZZYWOMBAT" in the
+report title should be considered a false positive (and no longer trigger Alerts), you can write the following code
+to do so::
 
     >>> feed = c.select(Feed).where("name:SOC").one()
     >>> report_query = feed.reports.where("title:FUZZYWOMBAT")
@@ -429,4 +426,3 @@ How about moving a sensor to a new Sensor Group::
     Sending HTTP PUT /api/v1/sensor/3 with {"boot_id": "2", "build_id": 2, "build_version_string": "005.002.000.60922", ...
     HTTP PUT /api/v1/sensor/3 took 0.087s (response 204)
     HTTP GET /api/v1/sensor/3 took 0.030s (response 200)
-