CB Response API

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

Main Interface

To use cbapi with Carbon Black Response, you will be using the CbResponseAPI. The CbResponseAPI object then exposes two main methods to access data on the Carbon Black server: select and create.

class cbapi.response.rest_api.CbResponseAPI(*args, **kwargs)

The main entry point into the Carbon Black Enterprise Response API. Note that calling this will automatically connect to the Carbon Black server in order to verify connectivity and get the server version.

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.
  • url (str) – (optional, discouraged) Instead of using a credential profile, pass URL and API token to the constructor.
  • token (str) – (optional, discouraged) API token
  • ssl_verify (bool) – (optional, discouraged) Enable or disable SSL certificate verification

Usage:

>>> from cbapi import CbEnterpriseResponseAPI
>>> cb = CbEnterpriseResponseAPI(profile="production")
api_json_request(method, uri, **kwargs)

Submit a request to the server.

Args:
method (str): HTTP method to use. uri (str): URI to submit the request to. **kwargs (dict): Additional arguments.
Returns:
object: Result of the operation.
Raises:
ServerError: If there’s an error output from the server.
create(cls, data=None)

Create a new object.

Args:
cls (class): The Model class (only some models can be created, for example, Feed, Notification, …) data (object): The data used to initialize the new object
Returns:
Model: An empty instance of the model class.
Raises:
ApiError: If the Model cannot be created.
create_new_partition()

Create a new Solr time partition for event storage. Available in Cb Response 6.1 and above. This will force roll-over current hot partition into warm partition (by renaming it to a time-stamped name) and create a new hot partition (“writer”).

Returns:

Nothing if successful.

Raises:
  • ApiError – if there was an error creating the new partition.
  • ServerError – if there was an error creating the new partition.
dashboard_statistics()

Retrieve dashboard statistics from the Carbon Black Enterprise Response server.

Returns:Dictionary with information retrieved from the /api/v1/dashboard/statistics API route
Return type:dict
delete_object(uri)

Send a DELETE request to the specified URI.

Args:
uri (str): The URI to send the DELETE request to.
Returns:
object: The return data from the DELETE request.
from_ui(uri)

Retrieve a Carbon Black Enterprise Response object based on URL from the Carbon Black Enterprise Response web user interface.

For example, calling this function with https://server/#/analyze/00000001-0000-0554-01d1-3bc4553b8c9f/1 as the uri argument will return a new :py:class: cbapi.response.models.Process class initialized with the process GUID from the URL.

Parameters:uri (str) – Web browser URL from the Cb web interface
Returns:the appropriate model object for the URL provided
Raises:ApiError – if the URL does not correspond to a recognized model object
get_object(uri, query_parameters=None, default=None)

Submit a GET request to the server and parse the result as JSON before returning.

Args:
uri (str): The URI to send the GET request to. query_parameters (object): Parameters for the query. default (object): What gets returned in the event of an empty response.
Returns:
object: Result of the GET request.
get_raw_data(uri, query_parameters=None, default=None, **kwargs)

Submit a GET request to the server and return the result without parsing it.

Args:
uri (str): The URI to send the GET request to. query_parameters (object): Parameters for the query. default (object): What gets returned in the event of an empty response. **kwargs:
Returns:
object: Result of the GET request.
info()

Retrieve basic version information from the Carbon Black Enterprise Response server.

Returns:Dictionary with information retrieved from the /api/info API route
Return type:dict
license_request()

Retrieve license request block from the Carbon Black Enterprise Response server.

Returns:License request block
Return type:str
post_object(uri, body, **kwargs)

Send a POST request to the specified URI.

Args:
uri (str): The URI to send the POST request to. body (object): The data to be sent in the body of the POST request. **kwargs:
Returns:
object: The return data from the POST request.
put_object(uri, body, **kwargs)

Send a PUT request to the specified URI.

Args:
uri (str): The URI to send the PUT request to. body (object): The data to be sent in the body of the PUT request. **kwargs:
Returns:
object: The return data from the PUT request.
raise_unless_json(ret, expected)

Raise a ServerError unless we got back an HTTP 200 response with JSON containing all the expected values.

Args:
ret (object): Return value to be checked. expected (dict): Expected keys and values that need to be found in the JSON response.
Raises:
ServerError: If the HTTP response is anything but 200, or if the expected values are not found.
select(cls, unique_id=None, *args, **kwargs)

Prepare a query against the Carbon Black data store.

Args:
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 *args: **kwargs:
Returns:
object: An instance of the Model class if a unique_id is provided, otherwise a Query object
update_license(license_block)

Upload new license to the Carbon Black Enterprise Response server.

Parameters:license_block (str) – Licence block provided by Carbon Black support
Raises:ServerError – if the license is not accepted by the Carbon Black server
url

Return the connection URL.

Returns:
str: The connection URL.

Queries

class cbapi.response.query.Query(doc_class, cb, query=None, raw_query=None)

Represents a prepared query to the Carbon Black Enterprise Response server.

This object is returned as part of a CbEnterpriseResponseAPI.select() operation on Process and Binary objects from the Carbon Black Enterprise Response server. 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.

The syntax for query :py:meth:where and :py:meth:sort methods can be found in the Query Reference posted on the Carbon Black Developer Network website.

Examples:

>>> cb = CbEnterpriseResponseAPI()
>>> query = cb.select(Process)                      # returns a Query object matching all Processes
>>> query = query.where("process_name:notepad.exe") # add a filter to this Query
>>> query = query.sort("last_update desc")          # sort by last update time, most recent first
>>> for proc in query:                              # uses the iterator to retrieve all results
>>>     print("{0} {1}".format(proc.username, proc.hostname))
>>> processes = query[:10]                          # retrieve the first ten results
>>> len(query)                                      # retrieve the total count
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_(new_query)

Add a filter to this query. Equivalent to calling where() on this object.

Parameters:new_query (str) –

Query string - see the Query Reference.

Returns:Query object
Return type:Query
facets(*args)

Retrieve a dictionary with the facets for this query.

Parameters:args – Any number of fields to use as facets
Returns:Facet data
Return type:dict
sort(new_sort)

Set the sort order for this query.

Parameters:new_sort (str) –

New sort order - see the Query Reference.

Returns:Query object
Return type:Query
where(new_query)

Add a filter to this query.

Parameters:new_query (str) –

Query string - see the Query Reference.

Returns:Query object
Return type:Query
class cbapi.response.models.ProcessQuery(doc_class, cb, query=None, raw_query=None)
group_by(field_name)

Set the group-by field name for this query. Typically, you will want to set this to ‘id’ if you only want one result per process.

This method is only available for Cb Response servers 6.0 and above. Calling this on a Query object connected to a Cb Response 5.x server will simply result in a no-op.

Parameters:field_name (str) – Field name to group the result set by.
Returns:Query object
Return type:ProcessQuery
max_children(num_children)

Sets the number of children to fetch with the process

This method is only available for Cb Response servers 6.0 and above. Calling this on a Query object connected to a Cb Response 5.x server will simply result in a no-op.

Default:15
Parameters:num_children (int) – Number of children to fetch with process
Returns:Query object
Return type:ProcessQuery
max_last_server_update(v)

Set the maximum last update time (relative to server) for this query. The timestamp can be expressed either as a datetime like object or as an ISO 8601 string formatted timestamp such as 2017-04-29T04:21:18Z. If a datetime like object is provided, it is assumed to be in GMT time zone.

This option will limit the number of Solr cores that need to be searched for events that match the query.

This method is only available for Cb Response servers 6.0 and above. Calling this on a Query object connected to a Cb Response 5.x server will simply result in a no-op.

Parameters:v (str) – Timestamp (either string or datetime object).
Returns:Query object
Return type:ProcessQuery
max_last_update(v)

Set the maximum last update time (relative to sensor) for this query. The timestamp can be expressed either as a datetime like object or as an ISO 8601 string formatted timestamp such as 2017-04-29T04:21:18Z. If a datetime like object is provided, it is assumed to be in GMT time zone.

This option will limit the number of Solr cores that need to be searched for events that match the query.

This method is only available for Cb Response servers 6.0 and above. Calling this on a Query object connected to a Cb Response 5.x server will simply result in a no-op.

Parameters:v (str) – Timestamp (either string or datetime object).
Returns:Query object
Return type:ProcessQuery
min_last_server_update(v)

Set the minimum last update time (relative to server) for this query. The timestamp can be expressed either as a datetime like object or as an ISO 8601 string formatted timestamp such as 2017-04-29T04:21:18Z. If a datetime like object is provided, it is assumed to be in GMT time zone.

This option will limit the number of Solr cores that need to be searched for events that match the query.

This method is only available for Cb Response servers 6.0 and above. Calling this on a Query object connected to a Cb Response 5.x server will simply result in a no-op.

Parameters:v (str) – Timestamp (either string or datetime object).
Returns:Query object
Return type:ProcessQuery
min_last_update(v)

Set the minimum last update time (relative to sensor) for this query. The timestamp can be expressed either as a datetime like object or as an ISO 8601 string formatted timestamp such as 2017-04-29T04:21:18Z. If a datetime like object is provided, it is assumed to be in GMT time zone.

This option will limit the number of Solr cores that need to be searched for events that match the query.

This method is only available for Cb Response servers 6.0 and above. Calling this on a Query object connected to a Cb Response 5.x server will simply result in a no-op.

Parameters:v (str) – Timestamp (either string or datetime object).
Returns:Query object
Return type:ProcessQuery

Set the comprehensive_search flag on the Process query.

Returns:new Query object
Return type:ProcessQuery
class cbapi.response.models.ThreatReportQuery(doc_class, cb, query=None, raw_query=None)
class cbapi.response.models.AlertQuery(doc_class, cb, query=None, raw_query=None)

Models

class cbapi.response.models.Process(cb, procguid, segment=None, max_children=15, initial_data=None, force_init=False, suppressed_process=False)
all_events

Returns a list of all events associated with this process across all segments, sorted by timestamp

Returns:list of CbEvent objects
all_events_segment

Returns a list of all events associated with this process segment, sorted by timestamp

Returns:list of CbEvent objects
binary

Joins this attribute with the Binary object associated with this Process object

Example:
>>> process_obj = c.select(Process).where('process_name:svch0st.exe')[0]
>>> binary_obj = process_obj.binary
>>> print(binary_obj.signed)
False
childprocs

Generator that returns CbChildProcEvent objects associated with this process

children

Generator that returns CbChildProcEvent objects associated with this process

cmdline
Returns:Returns the command line of the process
Return type:string
comms_ip

Returns ascii representation of the ip address used to communicate with the Cb Response Server

crossprocs

Generator that returns CbCrossProcEvent objects associated with this process

depth

Returns the depth of this process from the “root” system process

Returns:integer representing the depth of the process (0 is the root system process). To prevent infinite recursion, a maximum depth of 500 processes is enforced.
end

Returns the end time of the process (based on the last event received). If the process has not yet exited, “end” will return None.

Returns:datetime object of the last event received for the process, if it has terminated. Otherwise, None.
filemods

Generator that returns CbFileModEvent objects associated with this process

find_file_writes(filename)

Returns a list of file writes with the specified filename

Parameters:filename (str) – filename to match on file writes
Returns:Returns a list of file writes with the specified filename
Return type:list
interface_ip

Returns ascii representation of the ip address of the interface used to communicate with the Cb Response server. If using NAT, this will be the “internal” IP address of the sensor.

last_server_update

Returns a pretty version of when this process last updated

last_update

Returns a pretty version of when this process last updated

max_last_server_update

Returns a pretty version of the latest event in this process segment

max_last_update

Returns a pretty version of the latest event in this process segment

min_last_server_update

Returns a pretty version of the earliest event in this process segment

min_last_update

Returns a pretty version of the earliest event in this process segment

modloads

Generator that returns :py:class:CbModLoadEvent associated with this process

netconns

Generator that returns CbNetConnEvent objects associated with this process

classmethod new_object(cb, item, max_children=15)

Create a new instance of the object from item data.

Args:
cb (BaseAPI): Reference to the CBAPI object. item (dict): Item data, as retrieved from the server.
Returns:
object: New instance of the object.
parent

Returns the parent Process object if one exists

parent_md5

Workaround since parent_md5 silently disappeared in ~Cb Response 6.x

refresh()

Refresh the object from the Carbon Black server.

regmods

Generator that returns CbRegModEvent objects associated with this process

sensor

Joins this attribute with the Sensor object associated with this Process object

Example:
>>> process_obj = c.select(Process).where('process_name:svch0st.exe')[0]
>>> sensor_obj = process.sensor
>>> print(sensor_obj.computer_dns_name)
hyperv-win7-x86
start

Returns the start time of the process

unsigned_modloads

Returns all unsigned module loads. This is useful to filter out all Microsoft signed DLLs

username

Returns the username of the owner of this process

walk_children(callback, max_depth=0, depth=0)

Walk down the execution chain while calling the specified callback function at each depth.

Example:
>>> def proc_callback(parent_proc, depth):
...     print(parent_proc.cmdline, depth)
>>>
>>> process = c.select(Process).where('process_name:svch0st.exe')[0]
>>> process.walk_children(proc_callback, depth=2)
(u'cmd.exe \c ipconfig', 2)
(u'cmd.exe \\c ipconfig', 2)
(u'cmd.exe /c ipconfig', 2)
(u'ipconfig', 3)
(u'cmd.exe /c ipconfig.exe /all', 2)
(u'cmd.exe \c ipconfig', 2)
(u'cmd.exe \\c ipconfig', 2)
(u'cmd.exe /c ipconfig', 2)
(u'ipconfig', 3)
(u'cmd.exe /c ipconfig.exe /all', 2)
Parameters:
  • callback (func) – Callback function used for execution at each depth. This function is executed with the parent process object and depth as parameters.
  • max_depth (int) – Max number of iterations down the execution chain.
  • depth (int) – Number of iterations down the execution chain
Returns:

None

walk_parents(callback, max_depth=0, depth=0)

Walk up the execution chain while calling the specified callback function at each depth.

Example:
>>> def proc_callback(parent_proc, depth):
...    print(parent_proc.cmdline, depth)
>>>
>>> process = c.select(Process).where('process_name:ipconfig.exe')[0]
>>> process.walk_parents(proc_callback)
(u'cmd.exe /c ipconfig.exe', 0)
(u'c:\windows\carbonblack\cb.exe', 1)
(u'C:\Windows\system32\services.exe', 2)
(u'wininit.exe', 3)
(u'\SystemRoot\System32\smss.exe 00000000 00000040 ', 4)
(u'\SystemRoot\System32\smss.exe', 5)
(u'', 6)
Parameters:
  • callback (func) – Callback function used for execution at each depth. This function is executed with the parent process object and depth as parameters.
  • max_depth (int) – Max number of iterations up the execution chain
  • depth (int) – Number of iterations up the execution chain.
Returns:

None

Returns the Cb Response Web UI link associated with this process

class cbapi.response.models.Binary(cb, md5sum, initial_data=None, force_init=False)
class FrequencyData

Class containing frequency information about a binary

Parameters:
  • computer_count (int) – Number of endpoints this binary resides
  • process_count (int) – Number of executions
  • all_process_count (int) – Number of all process documents
  • module_frequency (int) – process_count / all_process_count

Create new instance of FrequencyData(computer_count, process_count, all_process_count, module_frequency)

class SigningData

Class containing binary signing information

Parameters:
  • result (str) – Signed or Unsigned
  • publisher (str) – Singnature publisher
  • issuer (str) – Signature issuer
  • subject (str) – Signing subject
  • sign_time (str) – Binary signed time
  • program_name (str) – Binary program name

Create new instance of SigningData(result, publisher, issuer, subject, sign_time, program_name)

class VersionInfo

Class containing versioning information about a binary

Parameters:
  • file_desc (str) – File description
  • file_version (str) – File version
  • product_name (str) – Product Name
  • product_version (str) – Product version
  • company_name (str) – Company Name
  • legal_copyright (str) – Copyright
  • original_filename (str) – Original File name of this binary

Create new instance of VersionInfo(file_desc, file_version, product_name, product_version, company_name, legal_copyright, original_filename)

banned

Returns BannedHash object if this Binary’s hash has been whitelisted (Banned), otherwise returns False

digsig_issuer

Returns the Digital Signature Issuer

digsig_prog_name

Returns the Digital Signature Program Name

digsig_publisher

Returns the Digital Signature Publisher

digsig_sign_time

Returns the Digital Signature signing time

digsig_subject

Returns the Digital Signature subject

endpoints

Return a list of endpoints this binary resides

file

Returns a file pointer to this binary

Example:
>>> process_obj = c.select(Process).where("process_name:svch0st.exe").first()
>>> binary_obj = process_obj.binary
>>> print(binary_obj.file.read(2))
MZ
frequency

Returns FrequencyData information about the binary.

Example:
>>> process_obj = c.select(Process).where('process_name:svch0st.exe').first()
>>> binary_obj = process_obj.binary
>>> print(binary_obj.frequency)
FrequencyData(computer_count=1, process_count=5, all_process_count=4429, module_frequency=0.001128923007450892)
icon

Returns the raw icon of this Binary. This data is not encoded.

is_64bit

Returns True if the Binary is an AMD64 or x64 (64-bit) Executable

is_executable_image

Returns True if the Binary is executable

classmethod new_object(cb, item)

Create a new instance of the object from item data.

Args:
cb (BaseAPI): Reference to the CBAPI object. item (dict): Item data, as retrieved from the server.
Returns:
object: New instance of the object.
observed_filenames

Returns a list of all observed file names associated with this Binary

signed

Returns True if the binary is signed.

signing_data

Returns SigningData object which contains: Digital Signature Result, Digital Signature publisher, Issuer, Subject, Signing Time, Program Name

size

Returns the size of the Binary

version_info

Returns a VersionInfo object containing detailed information: File Descritpion, File Version, Product Name, Product Version, Company Name, Legal Copyright, and Original FileName

Returns the Cb Response Web UI link associated with this Binary object

class cbapi.response.models.Sensor(*args, **kwargs)

Represents a Sensor object in the Carbon Black server.

class NetworkAdapter(macaddr, ipaddr)

Create new instance of NetworkAdapter(macaddr, ipaddr)

ipaddr

Alias for field number 1

macaddr

Alias for field number 0

activity_stats

Returns a list of activity statistics from the associated Cb Response Sensor

dns_name

Returns the DNS name associated with this sensor object. This is the same as ‘computer_dns_name’.

flush_events()

Performs a flush of events for this Cb Response Sensor

Warning:This may cause a significant amount of network traffic from this sensor to the Cb Response Server
group
Getter:

Returns the sensor’s group id.

Setter:

Allows access to set the sensor’s group id

hostname

Returns the hostname associated with this sensor object. This is the same as ‘computer_name’

isolate(timeout=None)

Turn on network isolation for this Cb Response Sensor.

This function will block and only return when the isolation is complete, or if a timeout is reached. By default, there is no timeout. You can specify a timeout period (in seconds) in the “timeout” parameter to this function. If a timeout is specified and reached before the sensor is confirmed isolated, then this function will throw a TimeoutError.

Returns:True if sensor is isolated
Raises:TimeoutError – if sensor does not isolate before timeout is reached
lr_session()

Retrieve a Live Response session object for this Sensor.

Returns:Live Response session object
Return type:cbapi.live_response_api.LiveResponseSession
Raises:ApiError – if there is an error establishing a Live Response session for this Sensor
network_interfaces

Returns a list of networks adapters on the sensor

os

Returns the operating system display string of the sensor

queued_stats

Returns a list of status and size of the queued event logs from the associated Cb Response Sensor

Example:
>>> sensor_obj = c.select(Sensor).where("ip:192.168").first()
>>> pprint.pprint(sensor_obj.queued_stats)
[{u'id': u'355509',
  u'num_eventlog_bytes': u'0',
  u'num_eventlogs': u'0',
  u'num_storefile_bytes': u'0',
  u'num_storefiles': 0,
  u'sensor_id': 1,
  u'timestamp': u'2016-10-17 19:08:09.645294-05:00'}]
resource_status

Returns a list of memory statistics used by the Cb Response Sensor

restart_sensor()

Restarts the Carbon Black sensor (not the underlying endpoint operating system).

This simply sets the flag to ask the sensor to restart the next time it checks into the Cb Response server, it does not wait for the sensor to restart.

sid

Security Identifier being used by the Cb Response Sensor

unisolate(timeout=None)

Turn off network isolation for this Cb Response Sensor.

This function will block and only return when the isolation is removed, or if a timeout is reached. By default, there is no timeout. You can specify a timeout period (in seconds) in the “timeout” parameter to this function. If a timeout is specified and reached before the sensor is confirmed unisolated, then this function will throw a TimeoutError.

Returns:True if sensor is unisolated
Raises:TimeoutError – if sensor does not unisolate before timeout is reached

Returns the Cb Response Web UI link associated with this Sensor

class cbapi.response.models.Feed(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Represents a Feed object in the Carbon Black server.

Base model for :param cb: :param model_unique_id: :param initial_data: :param force_init: :param full_doc: :return:

actions
Returns:Returns all FeedAction objects associated with this feed
Return type:response.rest_api.Query
search_binaries(min_score=None, max_score=None)

Perform a Binary search within this feed that satisfies min_score and max_score :param min_score: minimum feed score :param max_score: maximum feed score :return: Returns a response.rest_api.Query object within the appropriate

search parameters for binaries
Return type:response.rest_api.Query
search_processes(min_score=None, max_score=None)

Perform a Process search within this feed that satisfies min_score and max_score

Parameters:
  • min_score – minimum feed score
  • max_score – maximum feed score
Returns:

Returns a response.rest_api.Query object with the appropriate search parameters for processes

Return type:

response.rest_api.Query

class cbapi.response.models.BannedHash(cb, model_unique_id=None, initial_data=None, force_init=False, full_doc=False)

Represents a BannedHash object in the Carbon Black server.

Base model for :param cb: :param model_unique_id: :param initial_data: :param force_init: :param full_doc: :return:

binary

Joins this attribute with the Binary object associated with this Banned Hash object

class cbapi.response.models.Watchlist(*args, **kwargs)

Represents a Watchlist object in the Carbon Black server.

Variables:
  • description – A description of the watchlist.
  • search_query – URL encoded search query associated with this watchlist.
  • index_type – Index to search for this watchlist. Must be either ‘events’ (Processes) or ‘modules’ (Binaries)
facets

Returns facets from the search associated with the watchlist query

Returns:dictionary of facets as keys
Return type:dict
query
Getter:

Returns the query associated with this watchlist.

Setter:

Allows access to set the query associated with this watchlist

search()

Creates a search based on the watchlist’s search parameter

Returns:a Process response.rest_api.Query or Binary response.rest_api.Query
Return type:response.rest_api.Query
class cbapi.response.models.Alert(cb, alert_id, initial_data=None)

Represents a Alert object in the Carbon Black server.

Live Response

class cbapi.live_response_api.CbLRSessionBase(cblr_manager, session_id, sensor_id, session_data=None)

A Live Response session that interacts with a remote machine.

Initialize the CbLRSessionBase.

Args:
cblr_manager (CbLRManagerBase): The Live Response manager governing this session. session_id (str): The ID of this session. sensor_id (int): The ID of the sensor (remote machine) we’re connected to. session_data (dict): Additional session data.

File Operations

CbLRSessionBase.get_file(file_name, timeout=None, delay=None)

Retrieve contents of the specified file on the remote machine.

Args:
file_name (str): Name of the file to be retrieved. timeout (int): Timeout for the operation. delay (float): TBD
Returns:
str: Contents of the specified file.
CbLRSessionBase.delete_file(filename)

Delete the specified file name on the remote machine.

Args:
filename (str): Name of the file to be deleted.
CbLRSessionBase.put_file(infp, remote_filename)

Create a new file on the remote machine with the specified data.

Example: >>> with c.select(Sensor, 1).lr_session() as lr_session: … lr_session.put_file(open(“test.txt”, “rb”), r”c:test.txt”)

Args:
infp (object): Python file-like containing data to upload to the remote endpoint. remote_filename (str): File name to create on the remote endpoint.
CbLRSessionBase.list_directory(dir_name)

List the contents of a directory on the remote machine.

Example: >>> with c.select(Sensor, 1).lr_session() as lr_session: … pprint.pprint(lr_session.list_directory(‘C:\temp\’)) [{u’attributes’: [u’DIRECTORY’],

u’create_time’: 1471897244, u’filename’: u’.’, u’last_access_time’: 1476390670, u’last_write_time’: 1476390670, u’size’: 0},
{u’attributes’: [u’DIRECTORY’],
u’create_time’: 1471897244, u’filename’: u’..’, u’last_access_time’: 1476390670, u’last_write_time’: 1476390670, u’size’: 0},
{u’attributes’: [u’ARCHIVE’],
u’create_time’: 1476390668, u’filename’: u’test.txt’, u’last_access_time’: 1476390668, u’last_write_time’: 1476390668, u’size’: 0}]
Args:
dir_name (str): Directory to list. This parameter should end with the path separator.
Returns:
list: A list of dicts, each one describing a directory entry.
CbLRSessionBase.create_directory(dir_name)

Create a directory on the remote machine.

Args:
dir_name (str): The new directory name.
CbLRSessionBase.walk(top, topdown=True, onerror=None, followlinks=False)

Perform a full directory walk with recursion into subdirectories on the remote machine.

Example: >>> with c.select(Sensor, 1).lr_session() as lr_session: … for entry in lr_session.walk(directory_name): … print(entry) (‘C:\temp', [u’dir1’, u’dir2’], [u’file1.txt’])

Args:

top (str): Directory to recurse on. topdown (bool): If True, start output from top level directory. onerror (func): Callback if an error occurs. This function is called with one argument (the exception

that occurred).

followlinks (bool): True to follow symbolic links.

Returns:
list: List of tuples containing directory name, subdirectory names, file names.

Registry Operations

CbLRSessionBase.get_registry_value(regkey)

Return the associated value of the specified registry key on the remote machine.

Example: >>> with c.select(Sensor, 1).lr_session() as lr_session: >>> pprint.pprint(lr_session.get_registry_value(‘HKLM\SYSTEM\CurrentControlSet\services\ACPI\Start’)) {u’value_data’: 0, u’value_name’: u’Start’, u’value_type’: u’REG_DWORD’}

Args:
regkey (str): The registry key to retrieve.
Returns:
dict: A dictionary with keys of: value_data, value_name, value_type.
CbLRSessionBase.set_registry_value(regkey, value, overwrite=True, value_type=None)

Set a registry value on the specified registry key on the remote machine.

Example: >>> with c.select(Sensor, 1).lr_session() as lr_session: … lr_session.set_registry_value(‘HKLM\SYSTEM\CurrentControlSet\services\ACPI\testvalue’, 1)

Args:
regkey (str): The registry key to set. value (object): The value data. overwrite (bool): If True, any existing value will be overwritten. value_type (str): The type of value. Examples: REG_DWORD, REG_MULTI_SZ, REG_SZ
CbLRSessionBase.delete_registry_value(regkey)

Delete a registry value on the remote machine.

Args:
regkey (str): The registry value to delete.
CbLRSessionBase.create_registry_key(regkey)

Create a new registry key on the remote machine.

Args:
regkey (str): The registry key to create.
CbLRSessionBase.delete_registry_key(regkey)

Delete a registry key on the remote machine.

Args:
regkey (str): The registry key to delete.
CbLRSessionBase.list_registry_keys_and_values(regkey)

Enumerate subkeys and values of the specified registry key on the remote machine.

Example: >>> with c.select(Sensor, 1).lr_session() as lr_session: >>> pprint.pprint(lr_session.list_registry_keys_and_values(‘HKLM\SYSTEM\CurrentControlSet\services\ACPI’)) {‘sub_keys’: [u’Parameters’, u’Enum’],

‘values’: [{u’value_data’: 0,
u’value_name’: u’Start’, u’value_type’: u’REG_DWORD’},
{u’value_data’: 1,
u’value_name’: u’Type’, u’value_type’: u’REG_DWORD’},
{u’value_data’: 3,
u’value_name’: u’ErrorControl’, u’value_type’: u’REG_DWORD’},
{u’value_data’: u’system32\drivers\ACPI.sys’,
u’value_name’: u’ImagePath’, u’value_type’: u’REG_EXPAND_SZ’},
{u’value_data’: u’Microsoft ACPI Driver’,
u’value_name’: u’DisplayName’, u’value_type’: u’REG_SZ’},
{u’value_data’: u’Boot Bus Extender’,
u’value_name’: u’Group’, u’value_type’: u’REG_SZ’},
{u’value_data’: u’acpi.inf_x86_neutral_ddd3c514822f1b21’,
u’value_name’: u’DriverPackageId’, u’value_type’: u’REG_SZ’},
{u’value_data’: 1,
u’value_name’: u’Tag’, u’value_type’: u’REG_DWORD’}]}
Args:
regkey (str): The registry key to enumerate.
Returns:
dict: A dictionary with two keys, ‘sub_keys’ (a list of subkey names) and ‘values’ (a list of dicts
containing value data, name, and type).
CbLRSessionBase.list_registry_keys(regkey)

Enumerate all registry values from the specified registry key on the remote machine.

Args:
regkey (str): The registry key to enumerate.
Returns:
list: List of values for the registry key.

Process Operations

CbLRSessionBase.kill_process(pid)

Terminate a process on the remote machine.

Args:
pid (int): Process ID to be terminated.
Returns:
bool: True if success, False if failure.
CbLRSessionBase.create_process(command_string, wait_for_output=True, remote_output_file_name=None, working_directory=None, wait_timeout=30, wait_for_completion=True)

Create a new process on the remote machine with the specified command string.

Example: >>> with c.select(Sensor, 1).lr_session() as lr_session: … print(lr_session.create_process(r’cmd.exe /c “ping.exe 192.168.1.1”’)) Pinging 192.168.1.1 with 32 bytes of data: Reply from 192.168.1.1: bytes=32 time<1ms TTL=64

Args:

command_string (str): Command string used for the create process operation. wait_for_output (bool): True to block on output from the new process (execute in foreground).

This will also set wait_for_completion (below).

remote_output_file_name (str): The remote output file name used for process output. working_directory (str): The working directory of the create process operation. wait_timeout (int): Timeout used for this command. wait_for_completion (bool): True to wait until the process is completed before returning.

Returns:
str: The output of the process.
CbLRSessionBase.list_processes()

List currently running processes on the remote machine.

Example: >>> with c.select(Sensor, 1).lr_session() as lr_session: … print(lr_session.list_processes()[0]) {u’command_line’: u’‘,

u’create_time’: 1476260500, u’parent’: 0, u’parent_guid’: u‘00000001-0000-0000-0000-000000000000’, u’path’: u’‘, u’pid’: 4, u’proc_guid’: u‘00000001-0000-0004-01d2-2461a85e4546’, u’sid’: u’s-1-5-18’, u’username’: u’NT AUTHORITY\SYSTEM’}
Returns:
list: A list of dicts describing the processes.