Skip to content

Updated product names in documentation sections #300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kebringer-cb merged 2 commits into from
Dec 15, 2021
Merged

Updated product names in documentation sections #300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b3f9e07
Updated product names in 'docs' directory
kebringer-cb Dec 10, 2021
71fbc04
Small updates from review.
kebringer-cb Dec 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 24 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,25 @@

**Latest Version: 1.7.5**

_**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_
_**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
* Carbon Black EDR (Endpoint Detection and Response) is the new name for the product formerly called CB Response.
* Carbon Black App Control is the new name for the product formerly called CB Protection.

These are the Python bindings for the Carbon Black Enterprise Response and Enterprise Protection REST APIs.
These are the Python bindings for the Carbon Black EDR and App Control REST APIs.
To learn more about the REST APIs, visit the Carbon Black Developer Network Website at https://developer.carbonblack.com.

Please visit https://cbapi.readthedocs.io for detailed documentation on this API. Additionally, we have a slideshow
available at https://developer.carbonblack.com/2016/07/presentation-on-the-new-carbon-black-python-api/ that provides
an overview of the concepts that underly this API binding.
Please visit https://cbapi.readthedocs.io for detailed documentation on this API.

## Support

1. View all API and integration offerings on the [Developer Network](https://developer.carbonblack.com/) along with reference documentation, video tutorials, and how-to guides.
2. Use the [Developer Community Forum](https://community.carbonblack.com/t5/Developer-Relations/bd-p/developer-relations) to discuss issues and get answers from other API developers in the Carbon Black Community.
3. Report bugs and change requests to [Carbon Black Support](http://carbonblack.com/resources/support/).
3. Report bugs and change requests to [Carbon Black Support](https://www.vmware.com/support/services.html).

## Requirements

The new cbapi is designed to work on Python 2.6.6 and above (including 3.x). If you're just starting out,
The cbapi package is designed to work on Python 2.6.6 and above (including 3.x). If you're just starting out,
we recommend using the latest version of Python 3.6.x or above.

All requirements are installed as part of `pip install`.
Expand All @@ -28,11 +29,10 @@ The legacy cbapi (`cbapi.CbApi`) and legacy bit9api (`cbapi.bit9Api`) are still
## Backwards Compatibility

Backwards compatibility with old scripts is maintained through the `cbapi.legacy` module. Old scripts that import
`cbapi.CbApi` directly will continue to work. Once cbapi 2.0.0 is released, the old `CbApi` will be deprecated and
removed entirely no earlier than January 2017.
`cbapi.CbApi` directly will continue to work.

New scripts should use the `cbapi.CbResponseAPI` (for CB Response) and
`cbapi.CbProtectionAPI` (for CB Protection / former Bit9) API entry points.
New scripts should use the `cbapi.CbResponseAPI` (for EDR (CB Response)) and
`cbapi.CbProtectionAPI` (for App Control (CB Protection)) API entry points.

## Getting Started

Expand All @@ -49,10 +49,10 @@ Clone this repository, cd into `cbapi-python` then run setup.py with the `develo

### Sample Code

There are several examples in the `examples` directory for both Carbon Black Enterprise Response and Protection. We
will be adding more samples over time. For a quick start, see the following code snippets:
There are several examples in the `examples` directory for both EDR and App Control.
For a quick start, see the following code snippets:

**Carbon Black Enterprise Response**
**Carbon Black EDR**

from cbapi.response.models import Process, Binary, Sensor, Feed, Watchlist, Investigation
from cbapi.response.rest_api import CbEnterpriseResponseAPI
Expand All @@ -78,7 +78,7 @@ will be adding more samples over time. For a quick start, see the following code
s.save()


**Carbon Black Enterprise Protection**
**Carbon Black App Control**

from cbapi.protection.models import *
from cbapi.protection.rest_api import CbEnterpriseProtectionAPI
Expand All @@ -100,9 +100,8 @@ will be adding more samples over time. For a quick start, see the following code

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
[CB Response](http://developer.carbonblack.com/reference/enterprise-response/authentication/),
[CB Protection](http://developer.carbonblack.com/reference/enterprise-protection/authentication/), or
[CB Defense](http://developer.carbonblack.com/reference/cb-defense/authentication/).
[CB Response](http://developer.carbonblack.com/reference/enterprise-response/authentication/) or
[CB 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:

Expand All @@ -112,15 +111,14 @@ Once you acquire your API token, place it in one of the default credentials file

For distinction between credentials of different Carbon Black products, use the following naming convention for your credentials files:

* ``credentials.psc`` for CB Defense, CB ThreatHunter, and CB LiveOps
* ``credentials.response`` for CB Response
* ``credentials.protection`` for CB Protection
* ``credentials.response`` for EDR (CB Response)
* ``credentials.protection`` for 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:

* ``/etc/carbonblack/credentials.psc``
* ``~/.carbonblack/credentials.psc``
* ``/current_working_directory/.carbonblack/credentials.psc``
* ``/etc/carbonblack/credentials.response``
* ``~/.carbonblack/credentials.response``
* ``/current_working_directory/.carbonblack/credentials.response``

Credentials found in a later path will overwrite earlier ones.

Expand All @@ -144,7 +142,7 @@ by key-value pairs providing the necessary credential information::

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.
* **url**: The base URL of the Carbon Black 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
Expand All @@ -156,5 +154,5 @@ The possible options for each credential profile are:
* **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
Future versions of cbapi may provide the ability to "pin" the TLS certificate so as to provide certificate
verification on self-signed or internal CA signed certificates.
14 changes: 7 additions & 7 deletions docs/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ CbAPI 1.7.5 - Released June 16, 2021
Updates

* General
* Allow the CbAPI to accept a pre-configured Session object to be used for access, to get around unusual configuration requirements.
* Allow the CbAPI to accept a pre-configured Session object to be used for access, to get around unusual configuration requirements.

CbAPI 1.7.4 - Released April 7, 2021
------------------------------------
Expand All @@ -17,7 +17,7 @@ Updates

* General
* Fix example code in the documentation for Facets
* CB Response
* EDR (CB Response)
* Add missing fields for SensorGroup class and fix example script to properly create SensorGroup
* Fix example script sensor_group_operations.py to list groups without ipaddresses
* Fix alert.save()
Expand All @@ -38,7 +38,7 @@ Updates
* CB Threathunter
* Fix typo in process query
* Bump lxml from 4.4.1 to 4.6.2 for Threat Intelligence example
* CB Response
* EDR (CB Response)
* Add Sensor Builds
* Alert.set_ignored() and AlertQuery.set_ignored():
* Added a docstring to specify what happens with this method
Expand All @@ -65,7 +65,7 @@ Updates
* Documentation updates to indicate changed product names
* Carbon Black Cloud
* Process Search v2 rows defaults to 10k to match UI behavior
* CB Response
* EDR (CB Response)
* Add support for fetching alert by ID


Expand Down Expand Up @@ -358,7 +358,7 @@ CB Response:
You can also use the special segment "0" to retrieve process events across all segments.
* Fix ``cmdline_filters`` in the ``IngressFilter`` model object.

CB Protection:
App Control (CB Protection):

* Tamper Protection can now be set and cleared in the ``Computer`` model object.

Expand All @@ -378,7 +378,7 @@ Security fix:
Bug fixes:

* Add rule filename parameter to CB Defense ``policy_operations.py`` script's ``add-rule`` command.
* Add support for ``tamperProtectionActive`` attribute to CB Protection's ``Computer`` object.
* Add support for ``tamperProtectionActive`` attribute to App Control's (CB Protection) ``Computer`` object.
* Work around CB Response issue- the ``/api/v1/sensor`` route incorrectly returns an HTTP 500 if no sensors match the
provided query. CbAPI now catches this exception and will instead return an empty set back to the caller.

Expand All @@ -401,7 +401,7 @@ Security changes:

* Add the ability to "pin" a specific server certificate to a credential profile.

* You can now force TLS certificate verification on self-signed, on-premise installations of CB Response or Protection
* You can now force TLS certificate verification on self-signed, on-premise installations of EDR (CB Response) or App Control (Protection)
through the ``ssl_cert_file`` option in the credential profile.
* To "pin" a server certificate, save the PEM-formatted server certificate to a file, and put the full path to that
PEM file in the ``ssl_cert_file`` option of that server's credential profile.
Expand Down
26 changes: 13 additions & 13 deletions docs/concepts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ There are a few critical concepts that will make understanding and using the cba
explained below, and also covered in a slide deck presented at the Carbon Black regional User Exchanges in 2016.
You can see the slide deck `here <https://speakerdeck.com/cbdevnet/carbon-black-python-api-summer-2016>`_.

At a high level, the cbapi tries to represent data in CB Response or CB Protection as Python objects. If you've worked
At a high level, the cbapi tries to represent data in EDR (CB Response) or App Control (CB Protection) as Python objects. If you've worked
with SQL Object-relational Mapping (ORM) frameworks before, then this structure may seem familiar -- cbapi was
designed to operate much like an ORM such as SQLAlchemy or Ruby's ActiveRecord. If you haven't worked with one of these
libraries, don't worry! The concepts will become clear after a little practice.
Expand All @@ -14,9 +14,9 @@ Model Objects
-------------

Everything in cbapi is represented in terms of "Model Objects". A Model Object in cbapi represents a single instance
of a specific type of data in CB Response or Protection. For example, a process document from CB Response (as seen
of a specific type of data in EEDR (CB Response) or App Control (CB Protection). For example, a process document from EDR (as seen
on an Analyze Process page in the Web UI) is represented as a :py:mod:`cbapi.response.models.Process` Model Object.
Similarly, a file instance in CB Protection is represented as a :py:mod:`cbapi.protection.models.FileInstance`
Similarly, a file instance in App Control (CB Protection) is represented as a :py:mod:`cbapi.protection.models.FileInstance`
Model Object.

Once you have an instance of a Model Object, you can access all of the data contained within as Python properties.
Expand All @@ -27,7 +27,7 @@ in the ``cmdline`` property), you would write the code::

This would automatically retrieve the ``cmdline`` attribute of the process and print it out to your screen.

The data in CB Response and Protection may change rapidly, and so a comprehensive list of valid properties is difficult
The data in EDR (CB Response) or App Control (CB Protection) may change rapidly, and so a comprehensive list of valid properties is difficult
to keep up-to-date. Therefore, if you are curious what properties are available on a specific Model Object, you can
print that Model Object to the screen. It will dump all of the available properties and their current values. For
example::
Expand Down Expand Up @@ -56,7 +56,7 @@ method to retrieve the property, and return a default value if the property does

In summary, Model Objects contain all the data associated with a specific type of API call. In this example, the
:py:mod:`cbapi.response.models.Binary` Model Object reflects all the data available via the
``/api/v1/binary`` API route on a CB Response server.
``/api/v1/binary`` API route on an EDR (CB Response) server.

Joining Model Objects
---------------------
Expand Down Expand Up @@ -90,13 +90,13 @@ Queries

Now that we've covered how to get data out of a specific Model Object, we now need to learn how to obtain Model
Objects in the first place! To do this, we have to create and execute a Query. cbapi Queries use the same query
syntax accepted by CB Response or Protection's APIs, and add a few little helpful features along the way.
syntax accepted by EDR (CB Response) or App Control (CB Protection) APIs, and add a few little helpful features along the way.

To create a query in cbapi, use the ``.select()`` method on the CbResponseAPI or CbProtectionAPI object. Pass the
Model Object type as a parameter to the ``.select()`` call and optionally add filtering criteria with ``.where()``
clauses.

Let's start with a simple query for CB Response::
Let's start with a simple query for EDR (CB Response)::

>>> from cbapi.response import *
>>> cb = CbResponseAPI()
Expand Down Expand Up @@ -152,15 +152,15 @@ will throw a :py:mod:`MoreThanOneResultError` exception if there are zero or mor
second method is ``.first()``, which will return the first result from the result set, or None if there are no results.

Every time you access a Query object, it will perform a REST API query to the Carbon Black server. For large result
sets, the results are retrieved in batches- by default, 100 results per API request on CB Response and 1,000 results
per API request on CB Protection. The search queries themselves are not cached, but the resulting Model Objects are.
sets, the results are retrieved in batches- by default, 100 results per API request on EDR (CB Response) and 1,000 results
per API request on App Control (CB Protection). The search queries themselves are not cached, but the resulting Model Objects are.

Retrieving Objects by ID
------------------------

Every Model Object (and in fact any object addressable via the REST API) has a unique ID associated with it. If you
already have a unique ID for a given Model Object, for example, a Process GUID for CB Response, or a Computer ID
for CB Protection, you can ask cbapi to give you the associated Model Object for that ID by passing that ID to the
for App Control (CB Protection), you can ask cbapi to give you the associated Model Object for that ID by passing that ID to the
``.select()`` call. For example::

>>> binary = cb.select(Binary, "CA4FAFFA957C71C006B59E29DFE3EB8B")
Expand All @@ -178,8 +178,8 @@ object and if it does not exist, cbapi will throw a :py:mod:`ObjectNotFoundError
Creating New Objects
--------------------

The CB Response and Protection REST APIs provide the ability to insert new data under certain circumstances. For
example, the CB Response REST API allows you to insert a new banned hash into its database. Model Objects that
The EDR (CB Response) and App Control (CB Protection) REST APIs provide the ability to insert new data under certain circumstances. For
example, the EDR REST API allows you to insert a new banned hash into its database. Model Objects that
represent these data types can be "created" in cbapi by using the ``create()`` method::

>>> bh = cb.create(BannedHash)
Expand All @@ -199,7 +199,7 @@ exception with a list of the properties that are required and not currently set.

Once the ``.save()`` method is called, the appropriate REST API call is made to create the object. The Model Object
is then updated to the current state returned by the API, which may include additional data properties initialized
by CB Response or Protection.
by EDR (CB Response) or App Control (CB Protection).

Modifying Existing Objects
--------------------------
Expand Down
8 changes: 4 additions & 4 deletions docs/getting-started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,18 @@ on the Developer Network website.
API Authentication
------------------

CB Response and CB Protection use a per-user API secret token to authenticate requests via the API. The API token
EDR (CB Response) and App Control (CB Protection) use a per-user API secret token to authenticate requests via the API. The API token
confers the same permissions and authorization as the user it is associated with, so protect the API token with the
same care as a password.

To learn how to obtain the API token for a user, see the Developer Network website: there you will find instructions
for obtaining an API token for `CB Response <https://developer.carbonblack.com/reference/enterprise-response/authentication/>`_
and `CB Protection <https://developer.carbonblack.com/reference/enterprise-protection/authentication/>`_.
for obtaining an API token for `EDR (CB Response) <https://developer.carbonblack.com/reference/enterprise-response/authentication/>`_
and `App Control (CB Protection) <https://developer.carbonblack.com/reference/enterprise-protection/authentication/>`_.

Once you have the API token, cbapi helps keep your credentials secret by enforcing the use of a credential file. To
encourage sharing of scripts across the community while at the same time protecting the security of our customers,
cbapi strongly discourages embedding credentials in individual scripts. Instead, you can place credentials for several
CB Response or CB Protection servers inside the API credential file and select which "profile" you would like to use
EDR (CB Response) or App Control (CB Protection) servers inside the API credential file and select which "profile" you would like to use
at runtime.

To create the initial credential file, a simple-to-use script is provided. Just run the ``cbapi-response``,
Expand Down
Loading