Merge pull request #265 from carbonblack/release-1.3.5

Merge Release 1.3.5 to master

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+-   repo: https://github.com/pycqa/flake8
+    rev: 4.0.1
+    hooks:
+    -   id: flake8
+        additional_dependencies: [flake8-docstrings]
+        args: ["--docstring-convention", "google"]
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+        - id: check-yaml
+        - id: end-of-file-fixer
+        - id: trailing-whitespace

CONTRIBUTING.md

@@ -3,11 +3,14 @@
 We rely on pull requests to keep this project maintained. By participating in this project, you
 agree to abide by the VMware [code of conduct](CODE-OF-CONDUCT.md).
 
+## Setup 
+
 Fork, then clone the repo:
 
     git clone [email protected]:carbonblack/carbon-black-cloud-sdk-python.git
 
-Set up your machine:
+It is recommended to use [virtualenv](https://virtualenv.pypa.io/en/latest/) to set up the project. Once you have that
+you can use it to generate a virtual environment, activate it and install the package.
 
     python3 -m virtualenv ./venv
     source venv/bin/activate
@@ -17,11 +20,21 @@ Make sure the tests pass:
 
     pytest
 
-Make your change. Add tests for your change. Make the tests pass:
+## Developing
 
-    pytest
+Install the dev dependencies and after that it is highly recommended installing `pre-commit`. 
+
+    pip install -r requirements.txt 
+    pre-commit install
+    ...
+
+The `pre-commit` will make sure that you have the right code quality before committing your changes. 
 
-Push to your fork and [submit a pull request](https://github.com/carbonblack/carbon-black-cloud-sdk-python/compare/).
+Make sure to:
+* Write documentation and tests. 
+* Perform all the other tests. 
+* Push to your fork and 
+[submit a pull request](https://github.com/carbonblack/carbon-black-cloud-sdk-python/compare/).
 
 We try to respond to pull requests as quickly as possible. We may suggest
 some changes or improvements or alternatives.
@@ -31,3 +44,4 @@ Some things that will increase the chance that your pull request is accepted:
 * Write tests.
 * Follow [PEP-8](https://www.python.org/dev/peps/pep-0008/), [flake8](https://flake8.pycqa.org/en/latest/), and clean code principles.
 * Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+* Usage of [pre-commit](https://pre-commit.com/)

README.md

@@ -1,8 +1,8 @@
 # VMware Carbon Black Cloud Python SDK
 
-**Latest Version:** 1.3.4
+**Latest Version:** 1.3.5
 <br>
-**Release Date:** October 12, 2021
+**Release Date:** January 26, 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)
@@ -59,6 +59,7 @@ _Note: Support for the latest products such as Containers are planned for early
 - schema
 - solrq
 - validators
+- keyring (for MacOS)
 
 If developing the SDK, you also need:
 
@@ -69,6 +70,7 @@ If developing the SDK, you also need:
 - flake8==3.8.1
 - flake8-colors==0.1.6
 - flake8-docstrings==1.5.0
+- pre-commit>=2.15.0
 
 
 ## Getting Started
@@ -93,7 +95,7 @@ cd carbon-black-cloud-sdk-python
 pip install -r requirements.txt
 ```
 
-If you want to test/execute the eample 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.
+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.
 
 ```
 pip install -e .
@@ -108,11 +110,11 @@ From the parent directory `carbon-black-cloud-sdk-python`, run the command `pyte
 
 ### Building the documentation
 
+#### Locally
 ReadTheDocs hosts [the documentation for the SDK](https://carbon-black-cloud-python-sdk.readthedocs.io/en/latest/). If you make changes to the SDK that require an update to the documentation, first install the documentation packages from pip:
 
 ```
-pip install sphinxcontrib-apidoc
-pip install sphinx_rtd_theme
+pip install sphinxcontrib-apidoc sphinx_rtd_theme sphinx-copybutton
 ```
 
 Then, build the docs locally with the following commands:
@@ -125,6 +127,20 @@ make html
 
 The documentation is built in `docs/_build/html`.
 
+**N.B.:** If your documentation pages appear to generate incorrectly, check to see if you received the warning message
+`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`.
+
+#### Using Docker
+
+Build the documentation by running:
+```shell
+$ docker-compose -f docker/docs/docker-compose.yml up --build docs
+```
+
+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.4
+1.3.5

bin/set-macos-keychain.py

@@ -11,17 +11,15 @@
 # * WARRANTIES OR CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY,
 # * NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE.
 
-__doc__ = """
+"""
 Helper script for adding an entry into macos's keychain.
 
 Use the script by simply invoking it without any system arguments to
 import your configuration from a file or manually by inputs.
 
-Invoke it with system arguments to create an entry without having to type the credentials
-manually.
+Invoke it with system arguments to create an entry without having to type the credentials manually.
 
 Examples:
-
     Using system arguments:
     $ ./set-macos-keychain.py -e CBC_SDK -a default -t <TOKEN> -k <ORG_KEY> -u <URL>
 
@@ -64,8 +62,8 @@ def set_from_input():
     keychain_account_name = input("Keychain Account Name: ")
     url = input("URL to the Carbon Black Cloud API server (do not include '/integrationServices') [https://hostname]: ")
     ssl_verify = True
-    connector_id = input("Connector ID: ")
-    token = input("API key: ")
+    connector_id = input("API ID: ")
+    token = input("API Secret Key: ")
     org_key = input("Org Key: ")
     json_obj = {
         "url": url,

docker/docs/Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.9-slim-buster
+
+ENV PYTHONUNBUFFERED 1
+ENV PYTHONDONTWRITEBYTECODE 1
+
+RUN apt-get update \
+    # dependencies for building Python packages
+    && apt-get install -y build-essential \
+    && apt-get install -y texlive \
+    && apt-get install -y texlive-latex-extra \
+    && apt-get install -y dvipng \
+    && apt-get install -y python3-sphinx \
+    # Translations dependencies
+    && apt-get install -y gettext \
+    # cleaning up unused files
+    && 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 ./docs/start /start-docs
+RUN sed -i 's/\r$//g' /start-docs
+RUN chmod +x /start-docs
+
+WORKDIR /docs

docker/docs/docker-compose.yml

@@ -0,0 +1,13 @@
+version: '3'
+
+services:
+  docs:
+    image: carbon-black-cloud-sdk-python/docs
+    build:
+      context: ..
+      dockerfile: ./docs/Dockerfile
+    volumes:
+        - ../../docs:/app:z
+    ports:
+      - "7000:7000"
+    command: /start-docs

docker/docs/start

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+set -o errexit
+set -o pipefail
+set -o nounset
+
+cd /app
+make livehtml

docs/Makefile

@@ -3,16 +3,22 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
+
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
 BUILDDIR      = _build
+SOURCEDIR     = .
+APP 		  = /docs
 
 # Put it first so that "make" without argument is like "make help".
+.PHONY: help Makefile
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+# Create a live server which will host the documentation with live-reloading.
+.PHONY: livehtml
+livehtml:
+	sphinx-autobuild -b html --host 0.0.0.0 --port 7000 --watch $(APP) -c . $(SOURCEDIR) $(BUILDDIR)/html
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/authentication.rst

@@ -10,7 +10,7 @@ There are a few methods for authentication listed below. Every method requires
 an API Key. See the `Developer Network Authentication Guide`_ to learn how to
 generate an API Key.
 
-The SDK only uses one API Key at a time. It is recommeded to create API Keys for
+The SDK only uses one API Key at a time. It is recommended to create API Keys for
 specific actions, and use them as needed.
 
 For example, if using the
@@ -30,14 +30,14 @@ Store the Key with profile name, and reference the profile name when creating CB
   >>> platform_api = CBCloudAPI(profile='platform')
 
   # search for specific devices with Platform Devices API
-  >>> important_devs = platform_api.select(Device).set_target_priorities("MISSION_CRITICAL")
+  >>> important_devs = platform_api.select(Device).set_target_priorities(["MISSION_CRITICAL"])
 
   # 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()
-  
+
 For more examples on Live Response, check :doc:`live-response`
 
 
@@ -61,6 +61,21 @@ Authentication Methods
     >>> provider = RegistryCredentialProvider()
     >>> cbc_api = CBCloudAPI(credential_provider=provider, profile='default')
 
+:ref:`With macOS's Keychain Access`:
+
+    The Keychain Access which is built into macOS can also be used for authentication.
+
+    >>> provider = KeychainCredentialProvider('CBC API Credentials', 'default')
+    >>> cbc_api = CBCloudAPI(credential_provider=provider)
+
+:ref:`With Amazon Secrets Manger`:
+
+    There is a support for the Amazon Secrets Manager, navigate to the section for further details of how to
+    set it up.
+
+    >>> provider = AWSCredentialProvider(secret_arn='your-secret-arn-string')
+    >>> cbc_api = CBCloudAPI(credential_provider=provider)
+
 :ref:`With an External Credential Provider`:
 
   Credential Providers allow for custom methods of loading API credentials. This
@@ -105,7 +120,7 @@ CBAPI, so older files can continue to be used.  This is an example of a credenti
     ssl_force_tls_1_2=1
     proxy=proxy.example
     ignore_system_proxy=on
-    integration_name=MyScript/0.9.0
+    integration=MyScript/0.9.0
 
     [production]
     url=http://example.com
@@ -117,7 +132,7 @@ CBAPI, so older files can continue to be used.  This is an example of a credenti
     ssl_force_tls_1_2=1
     proxy=proxy.example
     ignore_system_proxy=on
-    integration_name=MyApplication/1.3.1
+    integration=MyApplication/1.3.1
 
 Individual profiles or sections are delimited in the file by placing their name within square brackets: ``[profile_name]``.  Within
 each section, individual credential values are supplied in a ``keyword=value`` format.
@@ -191,7 +206,7 @@ be specified:
 +-------------------------+----------------+---------+
 |``proxy``                | ``REG_SZ``     |         |
 +-------------------------+----------------+---------+
-|``integration_name``     | ``REG_SZ``     |         |
+|``integration``          | ``REG_SZ``     |         |
 +-------------------------+----------------+---------+
 
 Unrecognized named values are ignored.
@@ -286,7 +301,7 @@ You can remove the keys that you won't be using or leave them empty. Reference o
     {
         "url": "<URL>",
         "token" : "<TOKEN>",
-        "org_key": "<ORG_KEY>",A
+        "org_key": "<ORG_KEY>",
         "ssl_verify": true,
         "ssl_verify_hostname": true,
         "ssl_cert_file": "<FILE_PATH>",
@@ -311,13 +326,55 @@ After we've set the entry in the Keychain Access we can now authenticate our SDK
 
 .. code-block:: python
 
-    >>> from cbc_sdk.credential_providers.keychain_credential_provider import KeychainCredentialProvider
+    >>> from cbc_sdk.credential_providers import KeychainCredentialProvider
     >>> provider = KeychainCredentialProvider('CBC API Credentials', 'default')
     >>> cbc_api = CBCloudAPI(credential_provider=provider)
 
 
 You will be prompted to type your password so that python can access the keychain in order to obtain the credentials.
 
+With Amazon Secrets Manger
+--------------------------
+
+Configure the AWS credentials
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A full and comprehensive guide configuring the files and credentials regarding AWS can be found in their `official documentation. <https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html>`_
+
+Adding a secret to the AWS Secrets Manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is an official `guide for creating a secret <https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html>`_ by AWS.
+
+.. note::
+    Add your secrets as a key/value pairs. In the :ref:`Explanation of API Credential Components` you can find full information on required fields and their purpose.
+
+
+Using our credential provider for the SDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After the configuration of the AWS Credentials and storing your secret in the AWS Secret Manager, we can start using
+the credential provider.
+
+    >>> from cbc_sdk.credential_providers import AWSCredentialProvider
+    >>> from cbc_sdk import CBCloudAPI
+    >>> provider = AWSCredentialProvider(secret_arn='your-secret-arn-string')
+    >>> cbc_api = CBCloudAPI(credential_provider=provider)
+
+
+AWS Single Sign-On Provider (SSO)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to set the SSO provider follow this `tutorial <https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#aws-single-sign-on-provider-sso>`_ for setting the config.
+
+Then you can use the ``profile_name`` attribute in the ``AWSCredentialProvider`` like so:
+
+    >>> from cbc_sdk.credential_providers import AWSCredentialProvider
+    >>> from cbc_sdk import CBCloudAPI
+    >>> provider = AWSCredentialProvider(secret_arn='your-secret-arn-string', profile_name="my-sso-profile")
+    >>> cbc_api = CBCloudAPI(credential_provider=provider)
+
+
 Explanation of API Credential Components
 ----------------------------------------
 
@@ -362,7 +419,7 @@ or :ref:`with Windows Registry <With Windows Registry>`, the credentials include
 |``proxy``                | If specified, this is the name of a proxy host to be |         |
 |                         | used in making the connection.                       |         |
 +-------------------------+------------------------------------------------------+---------+
-|``integration_name``     | The name of the integration to use these credentials.|         |
+|``integration``          | The name of the integration to use these credentials.|         |
 |                         | The string may optionally end with a slash character,|         |
 |                         | followed by the integration's version number.  Passed|         |
 |                         | as part of the ``User-Agent:`` HTTP header on all    |         |