Enterprise EDR

Submodules

cbc_sdk.enterprise_edr.base module

Model Classes for Enterprise Endpoint Detection and Response

class Query(doc_class, cb)

Bases: cbc_sdk.base.PaginatedQuery, cbc_sdk.base.QueryBuilderSupportMixin, cbc_sdk.base.IterableQueryMixin, cbc_sdk.base.AsyncQueryMixin

Represents a prepared query to the Cb Enterprise EDR backend.

This object is returned as part of a CbEnterpriseEDRAPI.select operation on models requested from the Cb Enterprise EDR backend. You should not have to create this class yourself.

The query is not executed on the server until it’s accessed, either as an iterator (where it will generate values on demand as they’re requested) or as a list (where it will retrieve the entire result set and save to a list). You can also call the Python built-in len() on this object to retrieve the total number of items matching the query.

Examples:

>>> from cbc_sdk import CBCloudAPI
>>> from cbc_sdk.enterprise_edr import Report
>>> cb = CBCloudAPI()
>>> query = cb.select(Report)
>>> query = query.where(report_id="ABCDEFG1234")
>>> # alternatively:
>>> query = query.where("report_id:ABCDEFG1234")

Notes

  • The slicing operator only supports start and end parameters, but not step. [1:-1] is legal, but [1:2:-1] is not.
  • You can chain where clauses together to create AND queries; only objects that match all where clauses will be returned.

Initialize the Query object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
add_criteria(key, newlist)

Add to the criteria on this query with a custom criteria key.

Parameters:
  • key (str) – The key for the criteria item to be set.
  • newlist (str or list[str]) – Value or list of values to be set for the criteria item.
Returns:

The ResultQuery with specified custom criteria.

Example

query = api.select(Event).add_criteria(“event_type”, [“filemod”, “scriptload”]) query = api.select(Event).add_criteria(“event_type”, “filemod”)

add_exclusions(key, newlist)

Add to the excluions on this query with a custom exclusion key.

Parameters:
  • key (str) – The key for the exclusion item to be set.
  • newlist (str or list[str]) – Value or list of values to be set for the exclusion item.
Returns:

The ResultQuery with specified custom exclusion.

Example

query = api.select(Event).add_exclusions(“netconn_domain”, [“www.google.com”]) query = api.select(Event).add_exclusions(“netconn_domain”, “www.google.com”)

set_fields(fields)

Sets the fields to be returned with the response.

Parameters:fields (str or list[str]) – Field or list of fields to be returned.
set_rows(rows)

Sets the ‘rows’ query body parameter, determining how many rows of results to request.

Parameters:rows (int) – How many rows to request.
set_start(start)

Sets the ‘start’ query body parameter, determining where to begin retrieving results from.

Parameters:start (int) – Where to start results from.
set_time_range(start=None, end=None, window=None)

Sets the ‘time_range’ query body parameter, determining a time window based on ‘device_timestamp’.

Parameters:
  • start (str in ISO 8601 timestamp) – When to start the result search.
  • end (str in ISO 8601 timestamp) – When to end the result search.
  • window (str) – Time window to execute the result search, ending on the current time. Should be in the form “-2w”, where y=year, w=week, d=day, h=hour, m=minute, s=second.

Note

  • window will take precendent over start and end if provided.

Examples

query = api.select(Event).set_time_range(start=”2020-10-20T20:34:07Z”) second_query = api.select(Event).set_time_range(start=”2020-10-20T20:34:07Z”, end=”2020-10-30T20:34:07Z”) third_query = api.select(Event).set_time_range(window=’-3d’)

sort_by(key, direction='ASC')

Sets the sorting behavior on a query’s results.

Parameters:
  • key (str) – The key in the schema to sort by.
  • direction (str) – The sort order, either “ASC” or “DESC”.
Returns:

The query with sorting parameters.

Return type:

Query

Example:

>>> cb.select(Process).where(process_name="cmd.exe").sort_by("device_timestamp")
log = <Logger cbc_sdk.enterprise_edr.base (WARNING)>

Queries

cbc_sdk.enterprise_edr.threat_intelligence module

Model Classes for Enterprise Endpoint Detection and Response

class Feed(cb, model_unique_id=None, initial_data=None)

Bases: cbc_sdk.enterprise_edr.threat_intelligence.FeedModel

Represents a Feed object in the Carbon Black server.

Variables:
  • name – A human-friendly name for this feed
  • owner – The feed owner’s connector ID
  • provider_url – A URL supplied by the feed’s provider
  • summary – A human-friendly summary for the feed
  • category – The feed’s category
  • source_label – The feed’s source label
  • access – The feed’s access (public or private)
  • id – The feed’s unique ID

Initialize the Feed object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (str) – The unique ID of the feed.
  • initial_data (dict) – The initial data for the object.
access = None
append_reports(reports)

Append the given Reports to this Feed’s current Reports.

Parameters:reports ([Report]) – List of Reports to append to Feed.
Raises:InvalidObjectError – If id is missing.
category = None
delete()

Deletes this feed from the Enterprise EDR server.

Raises:InvalidObjectError – If id is missing.
id = None
name = None
owner = None
primary_key = 'id'
provider_url = None
replace_reports(reports)

Replace this Feed’s Reports with the given Reports.

Parameters:reports ([Report]) – List of Reports to replace existing Reports with.
Raises:InvalidObjectError – If id is missing.
reports

Returns a list of Reports associated with this feed.

Returns:List of Reports in this Feed.
Return type:Reports ([Report])
save(public=False)

Saves this feed on the Enterprise EDR server.

Parameters:public (bool) – Whether to make the feed publicly available.
Returns:The saved Feed.
Return type:Feed (Feed)
source_label = None
summary = None
update(**kwargs)

Update this feed’s metadata with the given arguments.

Parameters:

**kwargs (dict(str, str)) – The fields to update.

Raises:
  • InvalidObjectError – If id is missing or Feed.validate() fails.
  • ApiError – If an invalid field is specified.

Example:

>>> feed.update(access="private")
urlobject = '/threathunter/feedmgr/v2/orgs/{}/feeds'
urlobject_single = '/threathunter/feedmgr/v2/orgs/{}/feeds/{}'
validate()

Validates this feed’s state.

Raises:InvalidObjectError – If the Feed’s state is invalid.
class FeedModel(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Bases: cbc_sdk.base.UnrefreshableModel, cbc_sdk.base.CreatableModelMixin, cbc_sdk.base.MutableBaseModel

Represents a FeedModel object in the Carbon Black server.

Initialize the NewBaseModel object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (Any) – The unique ID for this particular instance of the model object.
  • initial_data (dict) – The data to use when initializing the model object.
  • force_init (bool) – True to force object initialization.
  • full_doc (bool) – True to mark the object as fully initialized.
class FeedQuery(doc_class, cb)

Bases: cbc_sdk.base.SimpleQuery

Represents the logic for a Feed query.

>>> cb.select(Feed)
>>> cb.select(Feed, id)
>>> cb.select(Feed).where(include_public=True)

Initialize the FeedQuery object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
results

Return a list of Feed objects matching self._args parameters.

where(**kwargs)

Add kwargs to self._args dictionary.

class IOC(cb, model_unique_id=None, initial_data=None, report_id=None)

Bases: cbc_sdk.enterprise_edr.threat_intelligence.FeedModel

Represents a IOC object in the Carbon Black server.

Variables:
  • md5 – A list of MD5 checksums
  • ipv4 – A list of IPv4 addresses
  • ipv6 – A list of IPv6 addresses
  • dns – A list of domain names
  • query – A list of dicts, each containing an IOC query

Creates a new IOC instance.

Raises:ApiError – If initial_data is None.
dns = []
ipv4 = []
ipv6 = []
md5 = []
query = []
validate()

Validates this IOC structure’s state.

Raises:InvalidObjectError – If the IOC structure’s state is invalid.
class IOC_V2(cb, model_unique_id=None, initial_data=None, report_id=None)

Bases: cbc_sdk.enterprise_edr.threat_intelligence.FeedModel

Represents a IOC_V2 object in the Carbon Black server.

Variables:
  • id – The IOC_V2’s unique ID
  • match_type – How IOCs in this IOC_V2 are matched
  • values – A list of IOCs
  • field – The kind of IOCs contained in this IOC_V2
  • link – A URL for some reference for this IOC_V2

Creates a new IOC_V2 instance.

Raises:ApiError – If initial_data is None.
field = None
id = None
ignore()

Sets the ignore status on this IOC.

Only watchlist IOCs have an ignore status.

Raises:InvalidObjectError – If id is missing or this IOC is not from a Watchlist.
ignored

Returns whether or not this IOC is ignored

Returns:True if the IOC is ignore, False otherwise.
Return type:(bool)
Raises:InvalidObjectError – If this IOC is missing an id or is not a Watchlist IOC.

Example:

>>> if ioc.ignored:
...     ioc.unignore()
match_type = None
primary_key = 'id'
unignore()

Removes the ignore status on this IOC.

Only watchlist IOCs have an ignore status.

Raises:InvalidObjectError – If id is missing or this IOC is not from a Watchlist.
validate()

Validates this IOC_V2’s state.

Raises:InvalidObjectError – If the IOC_V2’s state is invalid.
values = []
class Report(cb, model_unique_id=None, initial_data=None, feed_id=None, from_watchlist=False)

Bases: cbc_sdk.enterprise_edr.threat_intelligence.FeedModel

Represents a Report object in the Carbon Black server.

Variables:
  • id – The report’s unique ID
  • timestamp – When this report was created
  • title – A human-friendly title for this report
  • description – A human-friendly description for this report
  • severity – The severity of the IOCs within this report
  • link – A URL for some reference for this report
  • tags – A list of tags for this report
  • iocs_v2 – A list of IOC_V2 dicts associated with this report
  • visibility – The visibility of this report

Initialize the ReportSeverity object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (Any) – Unused.
  • initial_data (dict) – The initial data for the object.
  • feed_id (str) – The ID of the feed this report is for.
  • from_watchlist (str) – The ID of the watchlist this report is for.
custom_severity

Returns the custom severity for this report.

Returns:
The custom severity for this Report,
if it exists.
Return type:ReportSeverity (ReportSeverity)
Raises:InvalidObjectError – If id ismissing or this Report is from a Watchlist.
delete()

Deletes this report from the Enterprise EDR server.

Raises:InvalidObjectError – If id is missing, or feed_id is missing and this report is a Feed Report.

Example:

>>> report.delete()
description = None
id = None
ignore()

Sets the ignore status on this report.

Only watchlist reports have an ignore status.

Raises:InvalidObjectError – If id is missing or this Report is not from a Watchlist.
ignored

Returns the ignore status for this report.

Only watchlist reports have an ignore status.

Returns:True if this Report is ignored, False otherwise.
Return type:(bool)
Raises:InvalidObjectError – If id is missing or this Report is not from a Watchlist.

Example:

>>> if report.ignored:
...     report.unignore()
iocs = {}
iocs_

Returns a list of IOC_V2’s associated with this report.

Returns:List of IOC_V2’s for associated with the Report.
Return type:IOC_V2 ([IOC_V2])

Example:

>>> for ioc in report.iocs_:
...     print(ioc.values)
iocs_v2 = []
primary_key = 'id'
save_watchlist()

Saves this report as a watchlist report.

Note

This method cannot be used to save a feed report. To save feed reports, create them with cb.create and use Feed.replace.

Raises:InvalidObjectError – If Report.validate() fails.
severity = None
tags = []
timestamp = None
title = None
unignore()

Removes the ignore status on this report.

Only watchlist reports have an ignore status.

Raises:InvalidObjectError – If id is missing or this Report is not from a Watchlist.
update(**kwargs)

Update this Report with the given arguments.

Parameters:**kwargs (dict(str, str)) – The Report fields to update.
Returns:The updated Report.
Return type:Report (Report)
Raises:InvalidObjectError – If id is missing, or feed_id is missing and this report is a Feed Report, or Report.validate() fails.

Note

The report’s timestamp is always updated, regardless of whether passed explicitly.

>>> report.update(title="My new report title")
urlobject = '/threathunter/feedmgr/v2/orgs/{}/feeds/{}/reports'
validate()

Validates this report’s state.

Raises:InvalidObjectError – If the report’s state is invalid
visibility = None
class ReportQuery(doc_class, cb)

Bases: cbc_sdk.base.SimpleQuery

Represents the logic for a Report query.

Note

Only feed reports can be queried. Watchlist reports should be interacted
with via Watchlist.reports().

Example: >>> cb.select(Report).where(feed_id=id)

Initialize the ReportQuery object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
results

Return a list of Report objects matching self._args[‘feed_id’].

where(**kwargs)

Add kwargs to self._args dictionary.

class ReportSeverity(cb, initial_data=None)

Bases: cbc_sdk.enterprise_edr.threat_intelligence.FeedModel

Represents a ReportSeverity object in the Carbon Black server.

Variables:
  • report_id – The unique ID for the corresponding report
  • severity – The severity level

Initialize the ReportSeverity object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • initial_data (dict) – The initial data for the object.
primary_key = 'report_id'
report_id = None
severity = None
class Watchlist(cb, model_unique_id=None, initial_data=None)

Bases: cbc_sdk.enterprise_edr.threat_intelligence.FeedModel

Represents a Watchlist object in the Carbon Black server.

Variables:

Initialize the Watchlist object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (str) – The unique ID of the watch list.
  • initial_data (dict) – The initial data for the object.
alerts_enabled = None
classifier = {}
classifier_

Returns the classifier key and value, if any, for this watchlist.

Returns:Watchlist’s classifier key and value. None: If there is no classifier key and value.
Return type:tuple(str, str)
create_timestamp = None
delete()

Deletes this watchlist from the Enterprise EDR server.

Raises:InvalidObjectError – If id is missing.
description = None
disable_alerts()

Disable alerts for this watchlist.

Raises:InvalidObjectError – If id is missing.
disable_tags()

Disable tagging for this watchlist.

Raises:InvalidObjectError – if id is missing.
enable_alerts()

Enable alerts for this watchlist. Alerts are not retroactive.

Raises:InvalidObjectError – If id is missing.
enable_tags()

Enable tagging for this watchlist.

Raises:InvalidObjectError – If id is missing.
feed

Returns the Feed linked to this Watchlist, if there is one.

id = None
last_update_timestamp = None
name = None
report_ids = []
reports

Returns a list of Report objects associated with this watchlist.

Returns:List of Reports associated with the watchlist.
Return type:Reports ([Report])

Note

If this Watchlist is a classifier (i.e. feed-linked) Watchlist, reports will be empty. To get the reports associated with the linked Feed, use feed like:

>>> for report in watchlist.feed.reports:
...     print(report.title)
save()

Saves this watchlist on the Enterprise EDR server.

Returns:The saved Watchlist.
Return type:Watchlist (Watchlist)
Raises:InvalidObjectError – If Watchlist.validate() fails.
tags_enabled = None
update(**kwargs)

Updates this watchlist with the given arguments.

Parameters:

**kwargs (dict(str, str)) – The fields to update.

Raises:
  • InvalidObjectError – If id is missing or Watchlist.validate() fails.
  • ApiError – If report_ids is given and is empty.

Example:

>>> watchlist.update(name="New Name")
urlobject = '/threathunter/watchlistmgr/v2/watchlist'
urlobject_single = '/threathunter/watchlistmgr/v2/watchlist/{}'
validate()

Validates this watchlist’s state.

Raises:InvalidObjectError – If the Watchlist’s state is invalid.
class WatchlistQuery(doc_class, cb)

Bases: cbc_sdk.base.SimpleQuery

Represents the logic for a Watchlist query.

>>> cb.select(Watchlist)

Initialize the WatchlistQuery object.

Parameters:
  • doc_class (class) – The class of the model this query returns.
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
results

Return a list of all Watchlist objects.

log = <Logger cbc_sdk.enterprise_edr.threat_intelligence (WARNING)>

Models

cbc_sdk.enterprise_edr.ubs module

Model Classes for Enterprise Endpoint Detection and Response

class Binary(cb, model_unique_id)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Binary object in the Carbon Black server.

Variables:
  • sha256 – The SHA-256 hash of the file
  • md5 – The MD5 hash of the file
  • file_available – If true, the file is available for download
  • available_file_size – The size of the file available for download
  • file_size – The size of the actual file (represented by the hash)
  • os_type – The OS that this file is designed for
  • architecture – The set of architectures that this file was compiled for
  • lang_id – The Language ID value for the Windows VERSIONINFO resource
  • charset_id – The Character set ID value for the Windows VERSIONINFO resource
  • internal_name – The internal name from FileVersionInformation
  • product_name – The product name from FileVersionInformation
  • company_name – The company name from FileVersionInformation
  • trademark – The trademark from FileVersionInformation
  • file_description – The file description from FileVersionInformation
  • file_version – The file version from FileVersionInformation
  • comments – Comments from FileVersionInformation
  • original_filename – The original filename from FileVersionInformation
  • product_description – The product description from FileVersionInformation
  • product_version – The product version from FileVersionInformation
  • private_build – The private build from FileVersionInformation
  • special_build – The special build from FileVersionInformation

Initialize the Binary object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (str) – The SHA-256 of the binary being retrieved.
class Summary(cb, model_unique_id)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Summary object in the Carbon Black server.

Initialize the Summary object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • model_unique_id (str) – The SHA-256 of the binary being retrieved.
primary_key = 'sha256'
urlobject_single = '/ubs/v1/orgs/{}/sha256/{}/summary/device'
architecture = []
available_file_size = None
charset_id = None
comments = None
company_name = None
download_url

Returns a URL that can be used to download the file for this binary. Returns None if no download found.

Parameters:expiration_seconds (int) – How long the download should be valid for.
Returns:A pre-signed AWS download URL. None: If no download is found.
Return type:URL (str)
Raises:InvalidObjectError – If the URL retrieval should be retried.
file_available = None
file_description = None
file_size = None
file_version = None
internal_name = None
lang_id = None
md5 = None
original_filename = None
os_type = None
primary_key = 'sha256'
private_build = None
product_description = None
product_name = None
product_version = None
sha256 = None
special_build = None
summary

Returns organization-specific information about this binary.

trademark = None
urlobject_single = '/ubs/v1/orgs/{}/sha256/{}/metadata'
class Downloads(cb, shas, expiration_seconds=3600)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a Downloads object in the Carbon Black server.

Initialize the Downloads object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • shas (list) – A list of SHA hash values for binaries.
  • expiration_seconds (int) – Number of seconds until this request expires.
class FoundItem(cb, item)

Bases: cbc_sdk.base.UnrefreshableModel

Represents a FoundItem object in the Carbon Black server.

Initialize the FoundItem object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.
  • item (dict) – The values for a successfully-retrieved item.
primary_key = 'sha256'
found

Returns a list of Downloads.FoundItem, one for each binary found in the binary store.

urlobject = '/ubs/v1/orgs/{}/file/_download'

Module contents