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:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

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:

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

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:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

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_link(link)

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:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

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:

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

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:

MoreThanOneResultError – If the query returns more than one item
ObjectNotFoundError – If the query returns zero items

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