EDR (CB Response) API
Main Interface
To use cbapi with Carbon Black EDR (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 EDR 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 CbResponseAPI >>> cb = CbResponseAPI(profile="production")
Initialize the base API information.
- 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 Carbon Black EDR 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 EDR 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 EDR object based on URL from the Carbon Black EDR web user interface.
For example, calling this function with
https://server/#/analyze/00000001-0000-0554-01d1-3bc4553b8c9f/1
as theuri
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 DER 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 EDR 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 EDR 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
- property 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 EDR server.
This object is returned as part of a
CbResponseAPI.select()
operation on Process and Binary objects from the Carbon Black EDR 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 = CbResponseAPI() >>> 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:
- 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:
- where(new_query)
Add a filter to this query.
- Parameters:
new_query (str) –
Query string - see the Query Reference.
- Returns:
Query object
- Return type:
- 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 EDR servers 6.0 and above. Calling this on a Query object connected to a EDR 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:
- max_children(num_children)
Sets the number of children to fetch with the process
This method is only available for EDR servers 6.0 and above. Calling this on a Query object connected to a EDR 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:
- 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 adatetime
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 EDR servers 6.0 and above. Calling this on a Query object connected to a EDR 5.x server will simply result in a no-op.
- Parameters:
v (str) – Timestamp (either string or datetime object).
- Returns:
Query object
- Return type:
- 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 adatetime
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 EDR servers 6.0 and above. Calling this on a Query object connected to a EDR 5.x server will simply result in a no-op.
- Parameters:
v (str) – Timestamp (either string or datetime object).
- Returns:
Query object
- Return type:
- 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 adatetime
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 EDR servers 6.0 and above. Calling this on a Query object connected to a EDR 5.x server will simply result in a no-op.
- Parameters:
v (str) – Timestamp (either string or datetime object).
- Returns:
Query object
- Return type:
- 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 adatetime
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 EDR servers 6.0 and above. Calling this on a Query object connected to a EDR 5.x server will simply result in a no-op.
- Parameters:
v (str) – Timestamp (either string or datetime object).
- Returns:
Query object
- Return type:
- use_comprehensive_search()
Set the comprehensive_search flag on the Process query.
- Returns:
new Query object
- Return type:
- class cbapi.response.models.ThreatReportQuery(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)
Initialize the BaseModel object.
- Args:
cb (BaseAPI): Reference to the CBAPI object. model_unique_id (object): Unique ID for the model object. initial_data (dict): Initial data for the model object. force_init (bool): True to force the object to be re-initialized from the server.
- property all_events
Returns a list of all events associated with this process across all segments, sorted by timestamp
- Returns:
list of CbEvent objects
- property all_events_segment
Returns a list of all events associated with this process segment, sorted by timestamp
- Returns:
list of CbEvent objects
- property 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
- property childprocs
Generator that returns
CbChildProcEvent
objects associated with this process
- property children
Generator that returns
CbChildProcEvent
objects associated with this process
- property cmdline
- Returns:
Returns the command line of the process
- Return type:
string
- property comms_ip
Returns ascii representation of the ip address used to communicate with the EDR Server
- property crossprocs
Generator that returns
CbCrossProcEvent
objects associated with this process
- property 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.
- property 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.
- property 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
- property interface_ip
Returns ascii representation of the ip address of the interface used to communicate with the EDR server. If using NAT, this will be the “internal” IP address of the sensor.
- property last_server_update
Returns a pretty version of when this process last updated
- property last_update
Returns a pretty version of when this process last updated
- property max_last_server_update
Returns a pretty version of the latest event in this process segment
- property max_last_update
Returns a pretty version of the latest event in this process segment
- property min_last_server_update
Returns a pretty version of the earliest event in this process segment
- property min_last_update
Returns a pretty version of the earliest event in this process segment
- property modloads
Generator that returns :py:class:CbModLoadEvent associated with this process
- property 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.
- property parent
Returns the parent Process object if one exists
- property parent_md5
Workaround since parent_md5 silently disappeared in EDR 6.x
- property processblocks
Generator that returns
CbProcessBlockEvent
objects associated with this process
- refresh()
Refresh the object from the Carbon Black server.
- property regmods
Generator that returns
CbRegModEvent
objects associated with this process
- property 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
- property start
Returns the start time of the process
- property unsigned_modloads
Returns all unsigned module loads. This is useful to filter out all Microsoft signed DLLs
- property 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
- property webui_link
Returns the Carbon Black EDR Web UI link associated with this process
- class cbapi.response.models.Binary(cb, md5sum, initial_data=None, force_init=False)
Initialize the BaseModel object.
- Args:
cb (BaseAPI): Reference to the CBAPI object. model_unique_id (object): Unique ID for the model object. initial_data (dict): Initial data for the model object. force_init (bool): True to force the object to be re-initialized from the server.
- class FrequencyData(computer_count, process_count, all_process_count, module_frequency)
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(result, publisher, issuer, subject, sign_time, program_name)
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(file_desc, file_version, product_name, product_version, company_name, legal_copyright, original_filename)
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)
- property banned
Returns BannedHash object if this Binary’s hash has been banned, otherwise returns False
- property digsig_issuer
Returns the Digital Signature Issuer
- property digsig_prog_name
Returns the Digital Signature Program Name
- property digsig_publisher
Returns the Digital Signature Publisher
- property digsig_sign_time
Returns the Digital Signature signing time
- property digsig_subject
Returns the Digital Signature subject
- property endpoints
Return a list of endpoints this binary resides
- property 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
- property 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)
- property icon
Returns the raw icon of this Binary. This data is not encoded.
- property is_64bit
Returns True if the Binary is an AMD64 or x64 (64-bit) Executable
- property 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.
- property observed_filenames
Returns a list of all observed file names associated with this Binary
- property signed
Returns True if the binary is signed.
- property signing_data
Returns
SigningData
object which contains: Digital Signature Result, Digital Signature publisher, Issuer, Subject, Signing Time, Program Name
- property size
Returns the size of the Binary
- property version_info
Returns a
VersionInfo
object containing detailed information: File Descritpion, File Version, Product Name, Product Version, Company Name, Legal Copyright, and Original FileName
- property webui_link
Returns the Carbon Black EDR Web UI link associated with this Binary object
- class cbapi.response.models.Sensor(*args, **kwargs)
Represents a Sensor 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:
- class NetworkAdapter(macaddr, ipaddr)
Create new instance of NetworkAdapter(macaddr, ipaddr)
- ipaddr
Alias for field number 1
- macaddr
Alias for field number 0
- property activity_stats
Returns a list of activity statistics from the associated EDR Sensor
- property 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 EDR Sensor
- Warning:
This may cause a significant amount of network traffic from this sensor to the EDR Server
- property group
- Getter:
Returns the sensor’s group id.
- Setter:
Allows access to set the sensor’s group id
- property 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 EDR 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
- property network_interfaces
Returns a list of networks adapters on the sensor
- property os
Returns the operating system display string of the sensor
- property queued_stats
Returns a list of status and size of the queued event logs from the associated EDR 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'}]
- property resource_status
Returns a list of memory statistics used by the EDR 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 EDR server, it does not wait for the sensor to restart.
- property sid
Security Identifier being used by the EDR Sensor
- unisolate(timeout=None)
Turn off network isolation for this EDR 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
- property webui_link
Returns the Carbon Black EDR 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:
- property 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 appropriatesearch 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:
- 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)
Base model for :param cb: :param model_unique_id: :param initial_data: :param force_init: :param full_doc: :return:
- property facets
Returns facets from the search associated with the watchlist query
- Returns:
dictionary of facets as keys
- Return type:
dict
- property 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 Binaryresponse.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.
Base model for :param cb: :param model_unique_id: :param initial_data: :param force_init: :param full_doc: :return:
- set_ignored(ignored_flag=True, status='False Positive')
Ignore all future Alerts from the Report that triggered this Alert.
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.