Enterprise EDR Package

Auth Events Module

Model and Query Classes for Auth Events

class AuthEvent(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Bases: NewBaseModel

Represents an AuthEvent

Initialize the AuthEvent object.

Required RBAC Permissions:

org.search.events (CREATE, READ)

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) – False to mark the object as not fully initialized.

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> events = cb.select(AuthEvent).where("auth_username:SYSTEM")
>>> print(*events)
static bulk_get_details(cb, alert_id=None, event_ids=None, timeout=0)

Bulk get details

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • alert_id (str) – An alert id to fetch associated events

  • event_ids (list) – A list of event ids to fetch

  • timeout (int) – AuthEvent details request timeout in milliseconds. This can never be greater than the configured default timeout. If this value is 0, the configured default timeout is used.

Returns:

list of Auth Events

Return type:

list

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> bulk_details = AuthEvent.bulk_get_details(cb, event_ids=['example-value'])
>>> print(bulk_details)
Raises:

ApiError – if cb is not instance of CBCloudAPI

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

static get_auth_events_descriptions(cb)

Returns descriptions and status messages of Auth Events.

Parameters:

cb (CBCloudAPI) – A reference to the CBCloudAPI object.

Returns:

Descriptions and status messages of Auth Events as dict objects.

Return type:

dict

Raises:

ApiError – if cb is not instance of CBCloudAPI

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> descriptions = AuthEvent.get_auth_events_descriptions(cb)
>>> print(descriptions)
get_details(timeout=0, async_mode=False)

Requests detailed results.

Parameters:
  • timeout (int) – AuthEvent details request timeout in milliseconds. This can never be greater than the configured default timeout. If this is 0, the configured default timeout is used.

  • async_mode (bool) – True to request details in an asynchronous manner.

Returns:

Auth Events object enriched with the details fields

Return type:

AuthEvent

Note

  • When using asynchronous mode, this method returns a python future. You can call result() on the future object to wait for completion and get the results.

Examples

>>> cb = CBCloudAPI(profile="example_profile")
>>> events = cb.select(AuthEvent).where(process_pid=2000)
>>> print(events[0].get_details())
refresh()

Reload this object from the server.

static search_suggestions(cb, query, count=None)

Returns suggestions for keys and field values that can be used in a search.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • query (str) – A search query to use.

  • count (int) – (optional) Number of suggestions to be returned

Returns:

A list of search suggestions expressed as dict objects.

Return type:

list

Raises:

ApiError – if cb is not instance of CBCloudAPI

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> suggestions = AuthEvent.search_suggestions(cb, 'auth')
>>> print(suggestions)
to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

class AuthEventFacet(cb, model_unique_id, initial_data)

Bases: UnrefreshableModel

Represents an AuthEvent facet retrieved.

Example:
>>> cb = CBCloudAPI(profile="example_profile")
>>> events_facet = cb.select(AuthEventFacet).where("auth_username:SYSTEM").add_facet_field("process_name")
>>> print(events_facet.results)
Parameters:
  • terms – Contains the Auth Event Facet search results

  • ranges – Groupings for search result properties that are ISO 8601 timestamps or numbers

  • contacted – The number of searchers contacted for this query

  • completed – The number of searchers that have reported their results

Initialize the Terms object with initial data.

class Ranges(cb, initial_data)

Bases: UnrefreshableModel

Represents the range (bucketed) facet fields and values associated with an AuthEvent Facet query.

Initialize an AuthEventFacet Ranges object with initial_data.

property facets

Returns the reified AuthEventFacet.Terms._facets for this result.

property fields

Returns the ranges fields for this result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh()

Reload this object from the server.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

class Terms(cb, initial_data)

Bases: UnrefreshableModel

Represents the facet fields and values associated with an AuthEvent Facet query.

Initialize an AuthEventFacet Terms object with initial_data.

property facets

Returns the terms’ facets for this result.

property fields

Returns the terms facets’ fields for this result.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh()

Reload this object from the server.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

property ranges_

Returns the reified AuthEventFacet.Ranges for this result.

refresh()

Reload this object from the server.

property terms_

Returns the reified AuthEventFacet.Terms for this result.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

class AuthEventGroup(cb, initial_data=None)

Bases: object

Represents AuthEventGroup

Initialize AuthEventGroup object

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • initial_data (dict) – The data to use when initializing the model object.

Notes

The constructed object will have the following data: - group_start_timestamp - group_end_timestamp - group_key - group_value

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> groups = set(cb.select(AuthEvent).where(process_pid=2000).group_results("device_name"))
>>> for group in groups:
>>>     print(group._info)
class AuthEventQuery(doc_class, cb)

Bases: Query

Represents the query logic for an AuthEvent query.

This class specializes Query to handle the particulars of Auth Events querying.

Initialize the AuthEventQuery object.

Parameters:
  • doc_class (class) – The class of the model this query returns.

  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> events = cb.select(AuthEvent).where("auth_username:SYSTEM")
>>> print(*events)
add_criteria(key, newlist)

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

Will overwrite any existing criteria for the specified 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 query object with specified custom criteria.

Example

>>> query = api.select(Alert).add_criteria("type", ["CB_ANALYTIC", "WATCHLIST"])
>>> query = api.select(Alert).add_criteria("type", "CB_ANALYTIC")
add_exclusions(key, newlist)

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

Will overwrite any existing exclusion for the specified 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 query object with specified custom exclusion.

Example

>>> query = api.select(Alert).add_exclusions("type", ["WATCHLIST"])
>>> query = api.select(Alert).add_exclusions("type", "WATCHLIST")
all()

Returns all the items of a query as a list.

Returns:

List of query items

Return type:

list

and_(q=None, **kwargs)

Add a conjunctive filter to this query.

Parameters:
  • q (Any) – Query string or solrq.Q object

  • **kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

batch_size(new_batch_size)

Set the batch size of the paginated query.

Parameters:

new_batch_size (int) – The new batch size.

Returns:

A new query with the updated batch size.

Return type:

PaginatedQuery

execute_async()

Executes the current query in an asynchronous fashion.

Returns:

A future representing the query and its results.

Return type:

Future

first()

Returns the first item that would be returned as the result of a query.

Returns:

First query item

Return type:

obj

group_results(fields, max_events_per_group=None, rows=500, start=None, range_duration=None, range_field=None, range_method=None)

Get group results grouped by provided fields.

Parameters:
  • fields (str / list) – field or fields by which to perform the grouping

  • max_events_per_group (int) – Maximum number of events in a group, if not provided all events will be returned

  • rows (int) – Number of rows to request, can be paginated

  • start (int) – First row to use for pagination

  • ranges (dict) – dict with information about duration, field, method

Returns:

grouped results

Return type:

dict

Examples

>>> cb = CBCloudAPI(profile="example_profile")
>>> groups = set(cb.select(AuthEvent).where(process_pid=2000).group_results("device_name"))
>>> for group in groups:
>>>     print(group._info)
not_(q=None, **kwargs)

Adds a negated filter to this query.

Parameters:
  • q (solrq.Q) – Query object.

  • **kwargs (dict) – Arguments to construct a solrq.Q with.

Returns:

This Query object.

Return type:

Query

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
or_(**kwargs)

or_() criteria are explicitly provided to AuthEvent queries.

This method overrides the base class in order to provide or_() functionality rather than raising an exception.

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> events = cb.select(AuthEvent).where(process_name="chrome.exe").or_(process_name="firefox.exe")
>>> print(*events)
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 to the ‘start search’ API call, determining how many rows to request.

Parameters:

rows (int) – How many rows to request.

Returns:

AuthEventQuery object

Return type:

Query

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> events = cb.select(AuthEvent).where(process_name="chrome.exe").set_rows(5)
>>> print(*events)
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(Process).set_time_range(start="2020-10-20T20:34:07Z").where("query is required")
>>> second_query = api.select(Process).
...     set_time_range(start="2020-10-20T20:34:07Z", end="2020-10-30T20:34:07Z").where("query is required")
>>> third_query = api.select(Process).set_time_range(window='-3d').where("query is required")
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")
timeout(msecs)

Sets the timeout on a Auth Event query.

Parameters:

msecs (int) – Timeout duration, in milliseconds. This value can never be greater than the configured default timeout. If this value is 0, the configured default timeout is used.

Returns:

The Query object with new milliseconds parameter.

Return type:

Query (AuthEventQuery)

Example

>>> cb = CBCloudAPI(profile="example_profile")
>>> events = cb.select(AuthEvent).where(process_name="chrome.exe").timeout(5000)
>>> print(*events)
update_criteria(key, newlist)

Update the criteria on this query with a custom criteria key.

Parameters:
  • key (str) – The key for the criteria item to be set.

  • newlist (list) – List of values to be set for the criteria item.

Returns:

The query object with specified custom criteria.

Example

>>> query = api.select(Alert).update_criteria("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.

update_exclusions(key, newlist)

Update the exclusion on this query with a custom exclusion key.

Parameters:
  • key (str) – The key for the exclusion item to be set.

  • newlist (list) – List of values to be set for the exclusion item.

Returns:

The query object with specified custom exclusion.

Example

>>> query = api.select(Alert).update_exclusions("my.criteria.key", ["criteria_value"])

Note

Use this method if there is no implemented method for your desired criteria.

where(q=None, **kwargs)

Add a filter to this query.

Parameters:
  • q (Any) – Query string, QueryBuilder, or solrq.Q object

  • **kwargs (dict) – Arguments to construct a solrq.Q with

Returns:

This Query object.

Return type:

Query

Threat Intelligence Module

Model Classes for Enterprise Endpoint Detection and Response

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

Bases: FeedModel

Represents an Enterprise EDR feed’s metadata.

Parameters:
  • 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.

class FeedBuilder(cb, info)

Bases: object

Helper class allowing Feeds to be assembled.

Creates a new FeedBuilder object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • info (dict) – The initial information for the new feed.

add_reports(reports)

Adds new reports to the new feed.

Parameters:

reports (list[Report]) – New reports to be added to the feed.

Returns:

This object.

Return type:

FeedBuilder

build()

Builds the new Feed.

Returns:

The new Feed.

Return type:

Feed

set_alertable(alertable)

Sets the alertable for the new feed. Defaults to true if not specified.

Parameters:

alertable (bool) – Indicator whether the feed supports alerting.

Returns:

This object.

Return type:

FeedBuilder

set_category(category)

Sets the category for the new feed.

Parameters:

category (str) – New category for the feed.

Returns:

This object.

Return type:

FeedBuilder

set_name(name)

Sets the name for the new feed.

Parameters:

name (str) – New name for the feed.

Returns:

This object.

Return type:

FeedBuilder

set_provider_url(provider_url)

Sets the provider URL for the new feed.

Parameters:

provider_url (str) – New provider URL for the feed.

Returns:

This object.

Return type:

FeedBuilder

set_source_label(source_label)

Sets the source label for the new feed.

Parameters:

source_label (str) – New source label for the feed.

Returns:

This object.

Return type:

FeedBuilder

set_summary(summary)

Sets the summary for the new feed.

Parameters:

summary (str) – New summary for the feed.

Returns:

This object.

Return type:

FeedBuilder

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.

append_reports_rawdata(report_data)

Append the given report data, formatted as per the API documentation for reports, to this Feed’s Reports.

Parameters:

report_data (list[dict]) –

Raises:

InvalidObjectError – If id is missing or validation of the data fails.

classmethod create(cb, name, provider_url, summary, category, alertable=True)

Begins creating a new feed by making a FeedBuilder to hold the new feed data.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • name (str) – Name for the new feed.

  • provider_url (str) – Provider URL for the new feed.

  • summary (str) – Summary for the new feed.

  • category (str) – Category for the new feed.

Returns:

The new FeedBuilder object to be used to create the feed.

Return type:

FeedBuilder

delete()

Deletes this feed from the Enterprise EDR server.

Raises:

InvalidObjectError – If id is missing.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:

True if any fields of this object have been changed, False if not.

Return type:

bool

refresh()

Reload this object from the server.

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.

replace_reports_rawdata(report_data)

Replace this Feed’s Reports with the given reports, specified as raw data.

Parameters:

report_data (list[dict]) –

Raises:

InvalidObjectError – If id is missing or validation of the data fails.

property reports

Returns a list of Reports associated with this feed.

Returns:

List of Reports in this Feed.

Return type:

Reports ([Report])

reset()

Undo any changes made to this object’s fields.

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)

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

touch(fulltouch=False)

Force this object to be considered as changed.

update(**kwargs)

Update this feed’s metadata with the given arguments.

Parameters:

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

Raises:

Example

>>> feed.update(access="private")
validate()

Checks to ensure this feed contains valid data.

Raises:

InvalidObjectError – If the feed contains invalid data.

class FeedModel(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Bases: UnrefreshableModel, CreatableModelMixin, MutableBaseModel

A common base class for models used by the Feed and Watchlist APIs.

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.

delete()

Delete this object.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:

True if any fields of this object have been changed, False if not.

Return type:

bool

refresh()

Reload this object from the server.

reset()

Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:

This object.

Return type:

MutableBaseModel

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

touch(fulltouch=False)

Force this object to be considered as changed.

validate()

Validates this object.

Returns:

True if the object is validated.

Return type:

bool

Raises:

InvalidObjectError – If the object has missing fields.

class FeedQuery(doc_class, cb)

Bases: 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.

all()

Returns all the items of a query as a list.

Returns:

List of query items

Return type:

list

and_(new_query)

Add an additional “where” clause to this query.

Parameters:

new_query (object) – The additional “where” clause, as a string or solrq.Q object.

Returns:

A new query with the extra “where” clause specified.

Return type:

SimpleQuery

first()

Returns the first item that would be returned as the result of a query.

Returns:

First query item

Return type:

obj

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
property results

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

sort(new_sort)

Set the sorting for this query.

Parameters:

new_sort (object) – The new sort criteria for this query.

Returns:

A new query with the sort parameter specified.

Return type:

SimpleQuery

where(**kwargs)

Add kwargs to self._args dictionary.

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

Bases: FeedModel

Represents a collection of categorized IOCs. These objects are officially deprecated and replaced by IOC_V2.

Parameters:
  • 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.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • model_unique_id (str) – Unique ID of this IOC.

  • initial_data (dict) – Initial data used to populate the IOC.

  • report_id (str) – ID of the report this IOC belongs to (if this is a watchlist IOC).

Raises:

ApiError – If initial_data is None.

delete()

Delete this object.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:

True if any fields of this object have been changed, False if not.

Return type:

bool

refresh()

Reload this object from the server.

reset()

Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:

This object.

Return type:

MutableBaseModel

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

touch(fulltouch=False)

Force this object to be considered as changed.

validate()

Checks to ensure this IOC contains valid data.

Raises:

InvalidObjectError – If the IOC contains invalid data.

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

Bases: FeedModel

Represents a collection of IOCs of a particular type, plus matching criteria and metadata.

Parameters:
  • 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.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • model_unique_id (Any) – Unused.

  • initial_data (dict) – Initial data used to populate the IOC.

  • report_id (str) – ID of the report this IOC belongs to (if this is a watchlist IOC).

Raises:

ApiError – If initial_data is None.

classmethod create_equality(cb, iocid, field, *values)

Creates a new “equality” IOC.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • iocid (str) – ID for the new IOC. If this is None, a UUID will be generated for the IOC.

  • field (str) – Name of the field to be matched by this IOC.

  • *values (list(str)) – String values to match against the value of the specified field.

Returns:

New IOC data structure.

Return type:

IOC_V2

Raises:

ApiError – If there is not at least one value to match against.

classmethod create_query(cb, iocid, query)

Creates a new “query” IOC.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • iocid (str) – ID for the new IOC. If this is None, a UUID will be generated for the IOC.

  • query (str) – Query to be incorporated in this IOC.

Returns:

New IOC data structure.

Return type:

IOC_V2

Raises:

ApiError – If the query string is not present.

classmethod create_regex(cb, iocid, field, *values)

Creates a new “regex” IOC.

Parameters:
  • cb (BaseAPI) – Reference to API object used to communicate with the server.

  • iocid (str) – ID for the new IOC. If this is None, a UUID will be generated for the IOC.

  • field (str) – Name of the field to be matched by this IOC.

  • *values (list(str)) – Regular expression values to match against the value of the specified field.

Returns:

New IOC data structure.

Return type:

IOC_V2

Raises:

ApiError – If there is not at least one regular expression to match against.

delete()

Delete this object.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

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.

property ignored

Returns whether or not this IOC is ignored.

Only watchlist IOCs have an ignore status.

Returns:

True if the IOC is ignored, 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()
classmethod ipv6_equality_format(input)

Turns a canonically-formatted IPv6 address into a string suitable for use in an equality IOC.

Parameters:

input (str) – The IPv6 address to be translated.

Returns:

The translated form of IPv6 address.

Return type:

str

Raises:

ApiError – If the string is not in valid format.

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:

True if any fields of this object have been changed, False if not.

Return type:

bool

refresh()

Reload this object from the server.

reset()

Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:

This object.

Return type:

MutableBaseModel

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

touch(fulltouch=False)

Force this object to be considered as changed.

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()

Checks to ensure this IOC contains valid FQDN.

Raises:

InvalidObjectError – If the IOC contains invalid data.

class Report(cb, model_unique_id=None, initial_data=None, feed_id=None, from_watchlist=False)

Bases: FeedModel

Represents reports retrieved from an Enterprise EDR feed.

Parameters:
  • 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 (str) – The ID of the Report (only works for Reports in Watchlists).

  • initial_data (dict) – The initial data for the object.

  • feed_id (str) – The ID of the feed this report is for.

  • from_watchlist (bool) – If the report is in a watchlist

class ReportBuilder(cb, report_body)

Bases: object

Helper class allowing Reports to be assembled.

Initialize a new ReportBuilder.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • report_body (dict) – Partial report body which should be filled in with all “required” fields.

add_ioc(ioc)

Adds an IOC to the new report.

Parameters:

ioc (IOC_V2) – The IOC to be added to the report.

Returns:

This object.

Return type:

ReportBuilder

add_tag(tag)

Adds a tag value to the new report.

Parameters:

tag (str) – The new tag for the object.

Returns:

This object.

Return type:

ReportBuilder

build()

Builds the actual Report from the internal data of the ReportBuilder.

Returns:

The new Report.

Return type:

Report

set_description(description)

Set the description for the new report.

Parameters:

description (str) – New description for the report.

Returns:

This object.

Return type:

ReportBuilder

Set the link for the new report.

Parameters:

link (str) – New link for the report.

Returns:

This object.

Return type:

ReportBuilder

set_severity(severity)

Set the severity for the new report.

Parameters:

severity (int) – New severity for the report.

Returns:

This object.

Return type:

ReportBuilder

set_timestamp(timestamp)

Set the timestamp for the new report.

Parameters:

timestamp (int) – New timestamp for the report.

Returns:

This object.

Return type:

ReportBuilder

set_title(title)

Set the title for the new report.

Parameters:

title (str) – New title for the report.

Returns:

This object.

Return type:

ReportBuilder

set_visibility(visibility)

Set the visibility for the new report.

Parameters:

visibility (str) – New visibility for the report.

Returns:

This object.

Return type:

ReportBuilder

append_iocs(iocs)

Append a list of IOCs to this Report.

Parameters:

iocs (list[IOC_V2]) – List of IOCs to be added.

classmethod create(cb, title, description, severity, timestamp=None, tags=None)

Begin creating a new Report by returning a ReportBuilder.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • title (str) – Title for the new report.

  • description (str) – Description for the new report.

  • severity (int) – Severity value for the new report.

  • timestamp (int) – UNIX-epoch timestamp for the new report. If omitted, current time will be used.

  • tags (list[str]) – Tags to be added to the report. If omitted, there will be none.

Returns:

Reference to the ReportBuilder object.

Return type:

ReportBuilder

property 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()
get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

ignore()

Sets the ignore status on this report.

Raises:

InvalidObjectError – If id is missing or feed ID is missing.

property ignored

Returns the ignore status for this report.

Returns:

True if this Report is ignored, False otherwise.

Return type:

(bool)

Raises:

InvalidObjectError – If id is missing or feed ID is missing.

Example

>>> if report.ignored:
...     report.unignore()
property 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)
is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:

True if any fields of this object have been changed, False if not.

Return type:

bool

refresh()

Reload this object from the server.

remove_iocs(iocs)

Remove a list of IOCs from this Report.

Parameters:

iocs (list[IOC_V2]) – List of IOCs to be removed.

remove_iocs_by_id(ids_list)

Remove IOCs from this report by specifying their IDs.

Parameters:

ids_list (list[str]) – List of IDs of the IOCs to be removed.

reset()

Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:

This object.

Return type:

MutableBaseModel

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.

This method cannot be used to save a report that is already part of a watchlist. Use the update() method instead.

Raises:

InvalidObjectError – If Report.validate() fails.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

touch(fulltouch=False)

Force this object to be considered as changed.

unignore()

Removes the ignore status on this report.

Raises:

InvalidObjectError – If id is missing or feed ID is missing.

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")
validate()

Checks to ensure this report contains valid data.

Raises:

InvalidObjectError – If the report contains invalid data.

class ReportQuery(doc_class, cb)

Bases: SimpleQuery

Represents the logic for a Report query.

Example

>>> cb.select(Report).where(feed_id=id)
>>> cb.select(Report, id)
>>> cb.select(Report, id, from_watchlist=True)

Initialize the ReportQuery object.

Parameters:
  • doc_class (class) – The class of the model this query returns.

  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

all()

Returns all the items of a query as a list.

Returns:

List of query items

Return type:

list

and_(new_query)

Add an additional “where” clause to this query.

Parameters:

new_query (object) – The additional “where” clause, as a string or solrq.Q object.

Returns:

A new query with the extra “where” clause specified.

Return type:

SimpleQuery

first()

Returns the first item that would be returned as the result of a query.

Returns:

First query item

Return type:

obj

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
property results

Return a list of Report objects

sort(new_sort)

Set the sorting for this query.

Parameters:

new_sort (object) – The new sort criteria for this query.

Returns:

A new query with the sort parameter specified.

Return type:

SimpleQuery

where(**kwargs)

Add kwargs to self._args dictionary.

class ReportSeverity(cb, initial_data=None)

Bases: FeedModel

Represents severity information for a Watchlist Report.

Parameters:
  • 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.

delete()

Delete this object.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:

True if any fields of this object have been changed, False if not.

Return type:

bool

refresh()

Reload this object from the server.

reset()

Undo any changes made to this object’s fields.

save()

Save any changes made to this object’s fields.

Returns:

This object.

Return type:

MutableBaseModel

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

touch(fulltouch=False)

Force this object to be considered as changed.

validate()

Validates this object.

Returns:

True if the object is validated.

Return type:

bool

Raises:

InvalidObjectError – If the object has missing fields.

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

Bases: FeedModel

Represents an Enterprise EDR watchlist.

Parameters:
  • name – A human-friendly name for the watchlist

  • description – A short description of the watchlist

  • id – The watchlist’s unique id

  • tags_enabled – Whether tags are currently enabled

  • alerts_enabled – Whether alerts are currently enabled

  • create_timestamp – When this watchlist was created

  • last_update_timestamp – Report IDs associated with this watchlist

  • report_ids – Report IDs associated with this watchlist

  • classifier – A key, value pair specifying an associated feed

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.

class WatchlistBuilder(cb, name)

Bases: object

Helper class allowing Watchlists to be assembled.

Creates a new WatchlistBuilder object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • name (str) – Name for the new watchlist.

add_report_ids(report_ids)

Adds report IDs to the watchlist.

Parameters:

report_ids (list[str]) – List of report IDs to add to the watchlist.

Returns:

This object.

Return type:

WatchlistBuilder

add_reports(reports)

Adds reports to the watchlist.

Parameters:

reports (list[Report]) – List of reports to be added to the watchlist.

Returns:

This object.

Return type:

WatchlistBuilder

build()

Builds the new Watchlist using information in the builder. The new watchlist must still be saved.

Returns:

The new Watchlist.

Return type:

Watchlist

set_alerts_enabled(flag)

Sets whether alerts will be enabled on the new watchlist.

Parameters:

flag (bool) – True to enable alerts, False to disable them. Default is False.

Returns:

This object.

Return type:

WatchlistBuilder

set_description(description)

Sets the description for the new watchlist.

Parameters:

description (str) – New description for the watchlist.

Returns:

This object.

Return type:

WatchlistBuilder

set_name(name)

Sets the name for the new watchlist.

Parameters:

name (str) – New name for the watchlist.

Returns:

This object.

Return type:

WatchlistBuilder

set_tags_enabled(flag)

Sets whether tags will be enabled on the new watchlist.

Parameters:

flag (bool) – True to enable tags, False to disable them. Default is True.

Returns:

This object.

Return type:

WatchlistBuilder

add_report_ids(report_ids)

Adds new report IDs to the watchlist.

Parameters:

report_ids (list[str]) – List of report IDs to be added to the watchlist.

add_reports(reports)

Adds new reports to the watchlist.

Parameters:

reports (list[Report]) – List of reports to be added to the watchlist.

property 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)

classmethod create(cb, name)

Starts creating a new Watchlist by returning a WatchlistBuilder that can be used to set attributes.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • name (str) – Name for the new watchlist.

Returns:

The builder for the new watchlist. Call build() to create the actual Watchlist.

Return type:

WatchlistBuilder

classmethod create_from_feed(feed, name=None, description=None, enable_alerts=False, enable_tags=True)

Creates a new Watchlist that encapsulates a Feed.

Parameters:
  • feed (Feed) – The feed to be encapsulated by this Watchlist.

  • name (str) – Name for the new watchlist. The default is to use the Feed name.

  • description (str) – Description for the new watchlist. The default is to use the Feed summary.

  • enable_alerts (bool) –

  • enable_tags (bool) –

Returns:

A new Watchlist object, which must be saved to the server.

Return type:

Watchlist

delete()

Deletes this watchlist from the Enterprise EDR server.

Raises:

InvalidObjectError – If id is missing.

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.

property feed

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

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

is_dirty()

Returns whether or not any fields of this object have been changed.

Returns:

True if any fields of this object have been changed, False if not.

Return type:

bool

refresh()

Reload this object from the server.

property 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)
reset()

Undo any changes made to this object’s fields.

save()

Saves this watchlist on the Enterprise EDR server.

Returns:

The saved Watchlist.

Return type:

Watchlist (Watchlist)

Raises:

InvalidObjectError – If Watchlist.validate() fails.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

touch(fulltouch=False)

Force this object to be considered as changed.

update(**kwargs)

Updates this watchlist with the given arguments.

Parameters:

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

Raises:

Example

>>> watchlist.update(name="New Name")
validate()

Checks to ensure this watchlist contains valid data.

Raises:

InvalidObjectError – If the watchlist contains invalid data.

class WatchlistQuery(doc_class, cb)

Bases: 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.

all()

Returns all the items of a query as a list.

Returns:

List of query items

Return type:

list

and_(new_query)

Add an additional “where” clause to this query.

Parameters:

new_query (object) – The additional “where” clause, as a string or solrq.Q object.

Returns:

A new query with the extra “where” clause specified.

Return type:

SimpleQuery

first()

Returns the first item that would be returned as the result of a query.

Returns:

First query item

Return type:

obj

one()

Returns the only item that would be returned by a query.

Returns:

Sole query return item

Return type:

obj

Raises:
property results

Return a list of all Watchlist objects.

sort(new_sort)

Set the sorting for this query.

Parameters:

new_sort (object) – The new sort criteria for this query.

Returns:

A new query with the sort parameter specified.

Return type:

SimpleQuery

where(new_query)

Add a “where” clause to this query.

Parameters:

new_query (object) – The “where” clause, as a string or solrq.Q object.

Returns:

A new query with the “where” clause specified.

Return type:

SimpleQuery

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

Models

UBS Module

Model Classes for Enterprise Endpoint Detection and Response

class Binary(cb, model_unique_id)

Bases: UnrefreshableModel

Represents a retrievable binary.

Parameters:
  • 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: UnrefreshableModel

Represents a summary of organization-specific information for a retrievable binary.

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.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh()

Reload this object from the server.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

download_url(expiration_seconds=3600)

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.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh()

Reload this object from the server.

property summary

Returns organization-specific information about this binary.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

class Downloads(cb, shas, expiration_seconds=3600)

Bases: UnrefreshableModel

Represents download information for a list of process hashes.

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: UnrefreshableModel

Represents the download URL and process hash for a successfully located binary.

Initialize the FoundItem object.

Parameters:
  • cb (CBCloudAPI) – A reference to the CBCloudAPI object.

  • item (dict) – The values for a successfully-retrieved item.

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh()

Reload this object from the server.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any

property found

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

get(attrname, default_val=None)

Return an attribute of this object.

Parameters:
  • attrname (str) – Name of the attribute to be returned.

  • default_val (Any) – Default value to be used if the attribute is not set.

Returns:

The returned attribute value, which may be defaulted.

Return type:

Any

refresh()

Reload this object from the server.

to_json()

Return a json object of the response.

Returns:

The response dictionary representation.

Return type:

Any