Skip to content

Commit db285f3

Browse files
jgarmanjgarman
committed
more doc changes
1 parent d1d40c1 commit db285f3

File tree

6 files changed

+111
-14
lines changed

6 files changed

+111
-14
lines changed

‎docs/enterprise-protection.rst

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.. _protection_api:
2+
3+
Carbon Black Protection REST API
4+
================================
5+
6+
This page documents the public interfaces exposed by cbapi when communicating with a Carbon Black Enterprise
7+
Protection server.
8+
9+
Main Interface
10+
--------------
11+
12+
To use cbapi with Carbon Black Protection, you will be using the CbEnterpriseProtectionAPI.
13+
The CbEnterpriseProtectionAPI object then exposes two main methods to select data on the Carbon Black server:
14+
15+
.. autoclass:: cbapi.protection.rest_api.CbEnterpriseProtectionAPI
16+
:members:
17+
:inherited-members:
18+
19+
.. :automethod:: select
20+
.. :automethod:: create
21+
22+
Queries
23+
-------
24+
25+
.. autoclass:: cbapi.protection.rest_api.Query
26+
:members:
27+
28+
29+
Models
30+
------
31+
32+
.. autoclass:: cbapi.protection.models.Computer
33+
:members:
34+
:inherited-members:

‎docs/enterprise-response.rst

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. _api:
1+
.. _response_api:
22

33
Carbon Black Response REST API
44
==============================
@@ -25,13 +25,6 @@ Queries
2525
.. autoclass:: cbapi.response.rest_api.Query
2626
:members:
2727

28-
Exceptions
29-
----------
30-
31-
.. autoexception:: cbapi.errors.ApiError
32-
.. autoexecption:: cbapi.errors.CredentialError
33-
34-
3528
Models
3629
------
3730
.. autoclass:: cbapi.response.models.Feed

‎docs/exceptions.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _exceptions:
2+
3+
Exceptions
4+
==========
5+
6+
If an error occurs, the API attempts to roll the error into an appropriate Exception class.
7+
8+
Exception Classes
9+
-----------------
10+
11+
.. autoexception:: cbapi.errors.ApiError
12+
.. autoexception:: cbapi.errors.CredentialError
13+
.. autoexception:: cbapi.errors.ServerError
14+
.. autoexception:: cbapi.errors.ObjectNotFoundError
15+
.. autoexception:: cbapi.errors.MoreThanOneResultError
16+

‎docs/index.rst

Lines changed: 54 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -69,11 +69,58 @@ Major Features
6969
configuration for connecting to any number of Carbon Black Enterprise Protection or Response servers.
7070

7171

72-
Credentials
73-
-----------
72+
API Credentials
73+
---------------
7474

7575
The new cbapi as of version 0.9.0 enforces the use of credential files.
7676

77+
In order to perform any queries via the API, you will need to get the API token for your Cb user. See the documentation
78+
on the Developer Network website on how to acquire the API token for
79+
`Enterprise Response <http://developer.carbonblack.com/reference/enterprise-response/authentication/>`_ or
80+
`Enterprise Protection <http://developer.carbonblack.com/reference/enterprise-protection/authentication/>`_.
81+
82+
Once you acquire your API token, place it in one of the default credentials file locations:
83+
84+
* ``/etc/carbonblack/credentials.response`` (or ``.protection`` for Cb Enterprise Protection)
85+
* ``~/.carbonblack/credentials.response``
86+
* (current working directory) ``.carbonblack/credentials.response``
87+
88+
Credentials found in a later path will overwrite earlier ones.
89+
90+
The credentials are stored in INI format. The name of each credential profile is enclosed in square brackets, followed
91+
by comma separated key-value pairs providing the necessary credential information::
92+
93+
[default]
94+
url=https://localhost
95+
token=abcdef0123456789abcdef
96+
ssl_verify=False
97+
98+
[prod]
99+
url=https://cbserver.prod.corp.com
100+
token=aaaaaa
101+
ssl_verify=True
102+
103+
[otheruser]
104+
url=https://localhost
105+
token=bbbbbb
106+
ssl_verify=False
107+
108+
The possible options for each credential profile are:
109+
110+
* **url**: The base URL of the Cb server. This should include the protocol (https) and the hostname, and nothing else.
111+
* **token**: The API token for the user ID. More than one credential profile can be specified for a given server, with
112+
different tokens for each.
113+
* **ssl_verify**: True or False; controls whether the SSL/TLS certificate presented by the server is validated against
114+
the local trusted CA store.
115+
* **proxy**: A proxy specification that will be used when connecting to the Cb server. The format is:
116+
``http://myusername:mypassword@proxy.company.com:8001/`` where the hostname of the proxy is ``proxy.company.com``, port
117+
8001, and using username/password ``myusername`` and ``mypassword`` respectively.
118+
* **ignore_system_proxy**: If you have a system-wide proxy specified, setting this to True will force cbapi to bypass
119+
the proxy and directly connect to the Cb server.
120+
121+
Future versions of cbapi will also provide the ability to "pin" the TLS certificate so as to provide certificate
122+
verification on self-signed or internal CA signed certificates.
123+
77124
Backwards Compatibility
78125
-----------------------
79126

@@ -87,9 +134,9 @@ Since the old API was not compatible with Python 3, the legacy package is not im
87134
legacy scripts cannot run under Python 3.
88135

89136
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.
90-
New scripts should use the :py:mod:`cbapi.CbEnterpriseResponseAPI` (for Carbon Black Enterprise Response) and
91-
:py:mod:`cbapi.CbEnterpriseProtectionAPI` (for Carbon Black Enterprise Protection / former Bit9 Parity) API entry points.
92-
137+
New scripts should use the :py:mod:`cbapi.response.rest_api.CbEnterpriseResponseAPI`
138+
(for Carbon Black Enterprise Response) and :py:mod:`cbapi.protection.rest_api.CbEnterpriseProtectionAPI`
139+
(for Carbon Black Enterprise Protection / former Bit9 Parity) API entry points.
93140

94141

95142
Contents:
@@ -98,6 +145,8 @@ Contents:
98145
:maxdepth: 2
99146

100147
enterprise-response
148+
enterprise-protection
149+
exceptions
101150

102151

103152

‎src/cbapi/errors.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ def __str__(self):
1111

1212

1313
class ServerError(ApiError):
14+
"""A ServerError is raised when an HTTP error code is returned from the Carbon Black server."""
15+
1416
def __init__(self, error_code, message, result=None, original_exception=None):
1517
super(ServerError, self).__init__(message=message, original_exception=original_exception)
1618

@@ -30,6 +32,8 @@ def __str__(self):
3032

3133

3234
class ObjectNotFoundError(ApiError):
35+
"""The requested object could not be found in the Carbon Black datastore."""
36+
3337
def __init__(self, uri, message=None, original_exception=None):
3438
super(ObjectNotFoundError, self).__init__(message=message, original_exception=original_exception)
3539
self.uri = uri
@@ -84,5 +88,6 @@ class InvalidHashError(Exception):
8488

8589

8690
class MoreThanOneResultError(ApiError):
91+
"""Only one object was requested, but multiple matches were found in the Carbon Black datastore."""
8792
pass
8893

‎src/cbapi/oldmodels.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ def __setattr__(self, attrname, val):
238238
super(MutableModel, self).__setattr__(attrname, val)
239239

240240
def is_dirty(self):
241-
"""Returns True if this object has unsaved changes. Use :method:`MutableModel.save` to upload the changes to
241+
"""Returns True if this object has unsaved changes. Use :py:meth:`MutableModel.save` to upload the changes to
242242
the Carbon Black server."""
243243
return len(self._dirty_attributes) > 0
244244

0 commit comments

Comments
 (0)