CbAPI Changelog¶
CbAPI 1.3.3 - Released September 1, 2017¶
This release includes security improvements and bugfixes.
Security changes:
- CbAPI enforces the use of HTTPS when connecting to on-premise Cb Response servers.
- CbAPI can optionally require TLSv1.2 when connecting to Carbon Black servers.
- Note that some versions of Python and OpenSSL, notably the version of OpenSSL packaged with Mac OS X, do not support TLSv1.2. This will cause CbAPI to fail to connect to Cb Response 6.1+ servers which require TLSv1.2 cipher suites.
- A new command,
cbapi check-tls
, will report the TLS version supported by your platform. - To enforce the use of TLSv1.2 when connecting to a server, add
ssl_force_tls_1_2=True
to that server’s credential profile.
- 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
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. - When using this option with on-premise Cb Response servers, you may also have to set
ssl_verify_hostname=False
as the hostname in the certificate generated at install time islocalhost
and will not match the server’s hostname or IP address. This option will still validate that the server’s certificate is valid and matches the copy in thessl_cert_file
option.
- You can now force TLS certificate verification on self-signed, on-premise installations of Cb Response or Protection
through the
Changes for Cb Protection:
- The API now sets the appropriate “GET” query fields when changing fields such as the
debugFlags
on the Computer object. - The
.template
attribute on the Computer model object has been renamed.templateComputer
. - Remove AppCatalog and AppTemplate model objects.
Changes for Cb Response:
- Added
.webui_link
property to Cb Response Query objects. - Added
ban_hash.py
example.
Bug Fixes:
- Error handling is improved on Python 3. Live Response auto-reconnect functionality is now fixed on Python 3 as a result.
- Workaround implemented for Cb Response 6.1 where segment_ids are truncated on Alerts. The
.process
attribute on an Alert now ignores thesegment_id
and links to the first Process segment. - Fixed issue with
Binary.signed
andCbModLoadEvent.is_signed
.
CbAPI 1.3.2 - Released August 10, 2017¶
This release introduces the Policy API for Cb Defense. A sample policy_operations.py
script is now included
in the examples
directory for Cb Defense.
Other changes:
- Cb Response
- Bugfixes to the
User
Model Object. - New
user_operations.py
example script to manage users & teams. - Additional
Team
Model Object to add/remove/modify user teams. - New
check_datasharing.py
example script to check if third party data sharing is enabled for binaries on any sensor groups. - Documentation fix for the
User
Model Object. - Fix to the
watchlist_operations.py
example script.
- Bugfixes to the
CbAPI 1.3.1 - Released August 3, 2017¶
This is a bugfix release with minor changes:
- Cb Response
- Add
partition_operations.py
script to demonstrate the use of the StoragePartition model object. - Fix errors when accessing the
.start
attribute of child processes. - Fix errors generated by the
walk_children.py
example script. The output has been changed as well to indicate the process lifetime, console UI link, and command lines. - Add an
.end
attribute to the Process model object. This attribute reports back eitherNone
if the process is still executing, or the last event time associated with the process if it has exited. See thewalk_children.py
script for an example of how to calculate process lifetime. - Fix errors when using the
.parents
attribute of a Process. - Add
wait_for_completion
flag tocreate_process
Live Response method, and default toTrue
. Thecreate_process
method will now wait for the target process to complete before returning.
- Add
- Cb Defense
- Add
wait_for_completion
flag tocreate_process
Live Response method, and default toTrue
. Thecreate_process
method will now wait for the target process to complete before returning.
- Add
CbAPI 1.3.0 - Released July 27, 2017¶
This release introduces the Live Response API for Cb Defense. A sample cblr_cli.py
script is now included in the
examples
directory for both Cb Response and Cb Defense.
Other changes:
- Cb Protection
- You can now create new
FileRule
andPolicy
model objects in cbapi.
- You can now create new
- Cb Response
- Added
watchlist_exporter.py
andwatchlist_importer.py
scripts to the Cb Response examples directory. These scripts allow you to export Watchlist data in a human- and machine-readable JSON format and then re-import them into another Cb Response server. - The
Sensor
Model Object now uses the non-paginated (v1) API by default. This fixes any issues encountered when iterating over all the sensors and receiving duplicate and/or missing sensors. - Fix off-by-one error in
CbCrossProcess
object. - Fix issue iterating through
Process
Model Objects when accessing processes generated from a 5.2 server after upgrading to 6.1. - Reduce number of API requests required when accessing sibling information (parents, children, and siblings) from the
Process
Model Object. - Retrieve all events for a process when using
segment
ID of zero on a Cb Response 6.1 server. - Behavior of
Process.children
attribute has changed:- Only one entry is present per child (before there were up to two; one for the spawn event, one for the terminate event)
- The timestamp is derived from the start time of the process, not the timestamp from the spawn event. the two timestamps will be off by a few microseconds.
- The old behavior is still available by using the
Process.childprocs
attribute instead. This incurs a performance penalty as another API call will have to be made to collect the childproc information.
Binary
Model Object now returns False for.is_signed
attribute if it is set to(Unknown)
.
- Added
- Moved the
six
Python module into cbapi and removed the external dependency.
CbAPI 1.2.0 - Released June 22, 2017¶
This release introduces compatibility with our new product, Cb Defense, as well as adding new Model Objects introduced in the Cb Protection 8.0 APIs.
Other changes:
- Cb Response
- New method
synchronize()
added to theFeed
Model Object
- New method
- Bug fixes and documentation improvements
CbAPI 1.1.1 - Released June 2, 2017¶
This release includes compatibility fixes for Cb Response 6.1. Changes from 1.0.1 include:
- Substantial changes to the
Process
Model Object for Cb Response 6.1. See details below. - New
StoragePartition
Model Object to control Solr core loading/unloading in Cb Response 6.1. - New
IngressFilter
Model Object to control ingress filter settings in Cb Response 6.1. - Fix issues with
event_export.py
example script. - Add
.all_events
property to theProcess
Model Object to expose a list of all events across all segments. - Add example script to perform auto-banning based on watchlist hits from Cb Event Forwarder S3 output files.
- Add bulk operations to the
ThreatReport
andAlert
Query objects:- You can now call
.set_ignored()
,.assign()
, and.change_status()
on anAlert
Query object to change the respective fields for every Alert that matches the query. - You can now call
.set_ignored()
on aThreatReport
Query object to set or clear the ignored flag for every ThreatReport that matches the query.
- You can now call
Changes to Process
Model Object for Cb Response 6.1¶
Cb Response 6.1 uses a new way of recording process events that greatly increases the speed and scale of collection, allowing you to store and search data for more endpoints on the same hardware. Details on the new database format can be found on the Developer Network website at the Process API Changes for Cb Response 6.0 page.
The Process
Model Object traditionally referred to a single “segment” of events in the Cb Response database. In
Cb Response versions prior to 6.0, a single segment will include up to 10,000 individual endpoint events, enough to
handle over 95% of the typical event activity for a given process. Therefore, even though a Process
Model Object
technically refers to a single segment in a process, since most processes had less than 10,000 events and therefore
were only comprised of a single segment, this distinction wasn’t necessary.
However, now that processes are split across many segments, a better way of handling this is necessary. Therefore,
Cb Response 6.0 introduces the new .group_by()
method. This method is new in cbapi 1.1.0 and is part of five
new query filters available when communicating with a Cb Response 6.1 server. These filters are accessible via methods
on the Process
Query object. These new methods are:
.group_by()
- Group the result set by a field in the response. Typically you will want to group byid
, which will ensure that the result set only has one result per process rather than one result per event segment. For more information on processes, process segments, and how segments are stored in Cb Response 6.0, see the Process API Changes for Cb Response 6.0 page on the Developer Network website..min_last_update()
- Only return processes that have events after a given date/time stamp (relative to the individual sensor’s clock).max_last_update()
- Only return processes that have events before a given date/time stamp (relative to the individual sensor’s clock).min_last_server_update()
- Only return processes that have events after a given date/time stamp (relative to the Cb Response server’s clock).max_last_server_update()
- Only return processes that have events before a given date/time stamp (relative to the Cb Response server’s clock)
Examples for new Filters¶
Let’s take a look at an example:
>>> from datetime import datetime, timedelta
>>> yesterday = datetime.utcnow() - timedelta(days=1) # Get "yesterday" in GMT
>>> for proc in c.select(Process).where("process_name:cmd.exe").min_last_update(yesterday):
... print proc.id, proc.segment
DEBUG:cbapi.connection:HTTP GET /api/v1/process?cb.min_last_update=2017-05-21T18%3A41%3A58Z&cb.urlver=1&facet=false&q=process_name%3Acmd.exe&rows=100&sort=last_update+desc&start=0 took 2.164s (response 200)
00000001-0000-0e48-01d2-c2a397f4cfe0 1495465643405
00000001-0000-0e48-01d2-c2a397f4cfe0 1495465407157
00000001-0000-0e48-01d2-c2a397f4cfe0 1495463680155
00000001-0000-0e48-01d2-c2a397f4cfe0 1495463807694
00000001-0000-0e48-01d2-c2a397f4cfe0 1495463543944
00000001-0000-0e48-01d2-c2a397f4cfe0 1495463176570
00000001-0000-0e48-01d2-c2a397f4cfe0 1495463243492
Notice that the “same” process ID is returned seven times, but with seven different segment IDs. Cb Response will
return every process event segment that matches a given query, in this case, any event segment that contains the
process command name cmd.exe
.
That is, however, most likely not what you wanted. Instead, you’d like a list of the unique processes associated with
the command name cmd.exe
. Just add the .group_by("id")
filter to your query:
>>> for proc in c.select(Process).where("process_name:cmd.exe").min_last_update(yesterday).group_by("id"):
... print proc.id, proc.segment
DEBUG:cbapi.connection:HTTP GET /api/v1/process?cb.group=id&cb.min_last_update=2017-05-21T18%3A41%3A58Z&cb.urlver=1&facet=false&q=process_name%3Acmd.exe&rows=100&sort=last_update+desc&start=0 took 2.163s (response 200)
00000001-0000-0e48-01d2-c2a397f4cfe0 1495465643405