Cb ThreatHunter API¶

This page documents the public interfaces exposed by cbapi when communicating with a Carbon Black PSC ThreatHunter server.

Main Interface¶

To use cbapi with Carbon Black ThreatHunter, you use CbThreatHunterAPI objects. These objects expose two main methods to access data on the ThreatHunter server: select and create.

class cbapi.psc.threathunter.rest_api.CbThreatHunterAPI(*args, **kwargs)¶

The main entry point into the Cb ThreatHunter PSC API.

Parameters:	profile (str) – (optional) Use the credentials in the named profile when connecting to the Carbon Black server. Uses the profile named ‘default’ when not specified.

Usage:

>>> from cbapi.psc.threathunter import CbThreatHunterAPI
>>> cb = CbThreatHunterAPI(profile="production")

create(cls, data=None)¶

Creates a new object.

Parameters:	cls (class) – The Model class (only some models can be created, for example, Feed, Notification, …)
Returns:	An empty instance of the Model class
Raises:	ApiError – if the Model cannot be created

limits()¶

Returns a dictionary containing API limiting information.

Example:

>>> cb.limits()
{u'status_code': 200, u'time_bounds': {u'upper': 1545335070095, u'lower': 1542779216139}}

Returns:	a dict of limiting information
Return type:	dict(str, str)

queries()¶

Retrieves a list of queries, active or complete, known by the ThreatHunter server.

Returns:	a list of query ids
Return type:	list(str)

select(cls, unique_id=None, *args, **kwargs)¶

Prepares a query against the Carbon Black data store.

Parameters:	cls (class) – The Model class (for example, Computer, Process, Binary, FileInstance) to query unique_id – (optional) The unique id of the object to retrieve, to retrieve a single object by ID
Returns:	An instance of the Model class if a unique_id is provided, otherwise a Query object

Queries¶

The ThreatHunter API uses QueryBuilder instances to construct structured or unstructured (i.e., raw string) queries. You can either construct these instances manually, or allow CbThreatHunterAPI.select() to do it for you:

class cbapi.psc.threathunter.query.QueryBuilder(**kwargs)¶

Provides a flexible interface for building prepared queries for the CB ThreatHunter backend.

This object can be instantiated directly, or can be managed implicitly through the CbThreatHunterAPI.select() API.

Examples:

>>> from cbapi.psc.threathunter import QueryBuilder
>>> # build a query with chaining
>>> query = QueryBuilder().where(process_name="malicious.exe").and_(device_name="suspect")
>>> # start with an initial query, and chain another condition to it
>>> query = QueryBuilder(device_os="WINDOWS").or_(process_username="root")

and_(q, **kwargs)¶

Adds a conjunctive filter to a query.

Parameters:	q – string or solrq.Q object kwargs – Arguments to construct a solrq.Q with
Returns:	QueryBuilder object
Return type:	`QueryBuilder`

not_(q, **kwargs)¶

Adds a negative filter to a query.

Parameters:	q – solrq.Q object kwargs – Arguments to construct a solrq.Q with
Returns:	QueryBuilder object
Return type:	`QueryBuilder`

or_(q, **kwargs)¶

Adds a disjunctive filter to a query.

Parameters:	q – solrq.Q object kwargs – Arguments to construct a solrq.Q with
Returns:	QueryBuilder object
Return type:	`QueryBuilder`

where(q, **kwargs)¶

Adds a conjunctive filter to a query.

Parameters:	q – string or solrq.Q object kwargs – Arguments to construct a solrq.Q with
Returns:	QueryBuilder object
Return type:	`QueryBuilder`

class cbapi.psc.threathunter.query.Query(doc_class, cb)¶

Represents a prepared query to the Cb ThreatHunter backend.

This object is returned as part of a CbThreatHunterPI.select() operation on models requested from the Cb ThreatHunter backend. You should not have to create this class yourself.

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

Examples:

>>> from cbapi.psc.threathunter import CbThreatHunterAPI
>>> cb = CbThreatHunterAPI()
>>> query = cb.select(Process)
>>> query = query.where(process_name="notepad.exe")
>>> # alternatively:
>>> query = query.where("process_name:notepad.exe")

Notes:

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

and_(q=None, **kwargs)¶

Add a conjunctive filter to this query.

Parameters:	q – Query string or solrq.Q object kwargs – Arguments to construct a solrq.Q with
Returns:	Query object
Return type:	`Query`

not_(q=None, **kwargs)¶

Adds a negated filter to this query.

Parameters:	q – solrq.Q object kwargs – Arguments to construct a solrq.Q with
Returns:	Query object
Return type:	`Query`

or_(q=None, **kwargs)¶

Add a disjunctive filter to this query.

Parameters:	q – solrq.Q object kwargs – Arguments to construct a solrq.Q with
Returns:	Query object
Return type:	`Query`

where(q=None, **kwargs)¶

Add a filter to this query.

Parameters:	q – Query string, `QueryBuilder`, or solrq.Q object kwargs – Arguments to construct a solrq.Q with
Returns:	Query object
Return type:	`Query`

class cbapi.psc.threathunter.models.AsyncProcessQuery(doc_class, cb)¶

Represents the query logic for an asychronous Process query.

This class specializes Query to handle the particulars of process querying.

timeout(msecs)¶

Sets the timeout on a process query.

Example:

>>> cb.select(Process).where(process_name="foo.exe").timeout(5000)

Param:	msecs: the timeout duration, in milliseconds
Returns:	AsyncProcessQuery object
Return type:	`AsyncProcessQuery`

Models¶

class cbapi.psc.threathunter.models.Process(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)¶

Represents a Process object in the Carbon Black server.

children¶

Returns a list of child processes for this process.

Returns:	Returns a list of process objects
Return type:	list of `Process`

events(**kwargs)¶

Returns a query for events associated with this process’s process GUID.

Parameters:	kwargs – Arguments to filter the event query with.
Returns:	Returns a Query object with the appropriate search parameters for events
Return type:	`cbapi.psc.threathunter.query.Query`

Example:

>>> [print(event) for event in process.events()]
>>> [print(event) for event in process.events(event_type="modload")]

parents¶

Returns a query for parent processes associated with this process.

Returns:	Returns a Query object with the appropriate search parameters for parent processes, or None if the process has no recorded parent
Return type:	`cbapi.psc.threathunter.query.AsyncProcessQuery` or None

process_md5¶

Returns a string representation of the MD5 hash for this process.

Returns:	A string representation of the process’s MD5.
Return type:	str

process_pids¶

Returns a list of PIDs associated with this process.

Returns:	A list of PIDs
Return type:	list of ints

process_sha256¶

Returns a string representation of the SHA256 hash for this process.

Returns:	A string representation of the process’s SHA256.
Return type:	str

tree()¶

Returns a Tree of children (and possibly siblings) associated with this process.

Returns:	Returns a `Tree` object
Return type:	`Tree`

Example:

>>> tree = process.tree()

class cbapi.psc.threathunter.models.Event(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)¶: Represents a Event object in the Carbon Black server.

class cbapi.psc.threathunter.models.Tree(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=True)¶

Represents a Tree object in the Carbon Black server.

children¶

Returns all of the children of the process that this tree is centered around.

Returns:	A list of `Process` instances
Return type:	list of `Process`