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 routeReturn 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 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 Enterprise Response server.
Returns: Dictionary with information retrieved from the /api/info
API routeReturn 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.
- The slicing operator only supports start and end parameters, but not step.
-
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 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 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 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 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 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 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 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 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
-
use_comprehensive_search
()¶ 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 objectExample: >>> 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 objectExample: >>> 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
-
webui_link
¶ 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
-
webui_link
¶ Returns the Cb Response Web UI link associated with this Binary object
-
class
-
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
-
webui_link
¶ Returns the Cb Response Web UI link associated with this Sensor
-
class
-
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 feedReturn 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 binariesReturn 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 processesReturn 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)
-
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 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.
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.