more doc changes

docs/enterprise-protection.rst

@@ -0,0 +1,34 @@
+.. _protection_api:
+
+Carbon Black Protection REST API
+================================
+
+This page documents the public interfaces exposed by cbapi when communicating with a Carbon Black Enterprise
+Protection server.
+
+Main Interface
+--------------
+
+To use cbapi with Carbon Black Protection, you will be using the CbEnterpriseProtectionAPI.
+The CbEnterpriseProtectionAPI object then exposes two main methods to select data on the Carbon Black server:
+
+.. autoclass:: cbapi.protection.rest_api.CbEnterpriseProtectionAPI
+    :members:
+    :inherited-members:
+
+    .. :automethod:: select
+    .. :automethod:: create
+
+Queries
+-------
+
+.. autoclass:: cbapi.protection.rest_api.Query
+    :members:
+
+
+Models
+------
+
+.. autoclass:: cbapi.protection.models.Computer
+    :members:
+    :inherited-members:

docs/enterprise-response.rst

@@ -1,4 +1,4 @@
-.. _api:
+.. _response_api:
 
 Carbon Black Response REST API
 ==============================
@@ -25,13 +25,6 @@ Queries
 .. autoclass:: cbapi.response.rest_api.Query
     :members:
 
-Exceptions
-----------
-
-.. autoexception:: cbapi.errors.ApiError
-.. autoexecption:: cbapi.errors.CredentialError
-
-
 Models
 ------
 .. autoclass:: cbapi.response.models.Feed

docs/exceptions.rst

@@ -0,0 +1,16 @@
+.. _exceptions:
+
+Exceptions
+==========
+
+If an error occurs, the API attempts to roll the error into an appropriate Exception class.
+
+Exception Classes
+-----------------
+
+.. autoexception:: cbapi.errors.ApiError
+.. autoexception:: cbapi.errors.CredentialError
+.. autoexception:: cbapi.errors.ServerError
+.. autoexception:: cbapi.errors.ObjectNotFoundError
+.. autoexception:: cbapi.errors.MoreThanOneResultError
+

docs/index.rst

@@ -69,11 +69,58 @@ Major Features
     configuration for connecting to any number of Carbon Black Enterprise Protection or Response servers.
 
 
-Credentials
------------
+API Credentials
+---------------
 
 The new cbapi as of 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
+`Enterprise Response <http://developer.carbonblack.com/reference/enterprise-response/authentication/>`_ or
+`Enterprise Protection <http://developer.carbonblack.com/reference/enterprise-protection/authentication/>`_.
+
+Once you acquire your API token, place it in one of the default credentials file locations:
+
+* ``/etc/carbonblack/credentials.response`` (or ``.protection`` for Cb Enterprise Protection)
+* ``~/.carbonblack/credentials.response``
+* (current working directory) ``.carbonblack/credentials.response``
+
+Credentials found in a later path will overwrite earlier ones.
+
+The credentials are stored in INI format. The name of each credential profile is enclosed in square brackets, followed
+by comma separated key-value pairs providing the necessary credential information::
+
+    [default]
+    url=https://localhost
+    token=abcdef0123456789abcdef
+    ssl_verify=False
+
+    [prod]
+    url=https://cbserver.prod.corp.com
+    token=aaaaaa
+    ssl_verify=True
+
+    [otheruser]
+    url=https://localhost
+    token=bbbbbb
+    ssl_verify=False
+
+The possible options for each credential profile are:
+
+* **url**: The base URL of the Cb server. This should include the protocol (https) and the hostname, and nothing else.
+* **token**: The API token for the user ID. More than one credential profile can be specified for a given server, with
+  different tokens for each.
+* **ssl_verify**: True or False; controls whether the SSL/TLS certificate presented by the server is validated against
+  the local trusted CA store.
+* **proxy**: A proxy specification that will be used when connecting to the Cb server. The format is:
+  ``http://myusername:mypassword@proxy.company.com:8001/`` where the hostname of the proxy is ``proxy.company.com``, port
+  8001, and using username/password ``myusername`` and ``mypassword`` respectively.
+* **ignore_system_proxy**: If you have a system-wide proxy specified, setting this to True will force cbapi to bypass
+  the proxy and directly connect to the Cb server.
+
+Future versions of cbapi will also provide the ability to "pin" the TLS certificate so as to provide certificate
+verification on self-signed or internal CA signed certificates.
+
 Backwards Compatibility
 -----------------------
 
@@ -87,9 +134,9 @@ Since the old API was not compatible with Python 3, the legacy package is not im
 legacy scripts cannot run under Python 3.
 
 Once cbapi 2.0.0 is released, the old :py:mod:`cbapi.legacy.CbApi` will be deprecated and removed entirely no earlier than January 2017.
-New scripts should use the :py:mod:`cbapi.CbEnterpriseResponseAPI` (for Carbon Black Enterprise Response) and
-:py:mod:`cbapi.CbEnterpriseProtectionAPI` (for Carbon Black Enterprise Protection / former Bit9 Parity) API entry points.
-
+New scripts should use the :py:mod:`cbapi.response.rest_api.CbEnterpriseResponseAPI`
+(for Carbon Black Enterprise Response) and :py:mod:`cbapi.protection.rest_api.CbEnterpriseProtectionAPI`
+(for Carbon Black Enterprise Protection / former Bit9 Parity) API entry points.
 
 
 Contents:
@@ -98,6 +145,8 @@ Contents:
    :maxdepth: 2
 
    enterprise-response
+   enterprise-protection
+   exceptions
 
 
 

src/cbapi/errors.py

@@ -11,6 +11,8 @@ def __str__(self):
 
 
 class ServerError(ApiError):
+    """A ServerError is raised when an HTTP error code is returned from the Carbon Black server."""
+
     def __init__(self, error_code, message, result=None, original_exception=None):
         super(ServerError, self).__init__(message=message, original_exception=original_exception)
 
@@ -30,6 +32,8 @@ def __str__(self):
 
 
 class ObjectNotFoundError(ApiError):
+    """The requested object could not be found in the Carbon Black datastore."""
+
     def __init__(self, uri, message=None, original_exception=None):
         super(ObjectNotFoundError, self).__init__(message=message, original_exception=original_exception)
         self.uri = uri
@@ -84,5 +88,6 @@ class InvalidHashError(Exception):
 
 
 class MoreThanOneResultError(ApiError):
+    """Only one object was requested, but multiple matches were found in the Carbon Black datastore."""
     pass
 

src/cbapi/oldmodels.py

@@ -238,7 +238,7 @@ def __setattr__(self, attrname, val):
             super(MutableModel, self).__setattr__(attrname, val)
 
     def is_dirty(self):
-        """Returns True if this object has unsaved changes. Use :method:`MutableModel.save` to upload the changes to
+        """Returns True if this object has unsaved changes. Use :py:meth:`MutableModel.save` to upload the changes to
         the Carbon Black server."""
         return len(self._dirty_attributes) > 0