Carbon Black EDR (Endpoint Detection and Response) is the new name for the product formerly called CB Response.
The EDR Live Response feature allows security operators to collect information and take action on remote endpoints in real time. These actions include the ability to upload, download, and remove files, retrieve and remove registry entries, dump contents of physical memory, execute and terminate processes.
The Live Response API is a subset of the broader EDR REST APIs.
Authentication uses the same
AuthToken Header as the EDR REST API.
The Live Response API is asynchronous; calling an API to execute a command on the remote endpoint, for example, will return immediately with a command ID. You can then poll the API using the command ID until a result status is returned.
Before any commands can be sent to an endpoint, you must first establish a “session” with a sensor. A sensor with an active session will keep an open connection to the Carbon Black server for as long as the session is active. Sessions are kept alive for a timeout period and then recycled once the timeout period has expired. All Live Response command APIs require a valid session id; an error is returned if the session has not been established or has timed out.
Note: To use the Live Response API, you must enable Live Response in your EDR server by editing the
/etc/cb/cb.conf
file by setting CbLREnabled=True
. Live Response is disabled by default.
If you attempt to use the Live Response API without first enabling it in the cb.conf
file and
restarting the cb-enterprise
services, you will receive an HTTP 412 error code.
For cloud instances, please contact support to have it enabled.
To view all current sessions, use a GET
command to https://<hostname>/api/v1/cblr/session
.
The following request will retrieve a list of currently active or recently closed sessions.
Note: If you just created a session, it might show up as status: pending
, this will transition to status: active
once the session is ready.
Request
$ curl -H "Content-Type: application/json" -H "X-Auth-Token: d91b00774b2b903b49d8d9caa57ce9fcde16973a" \ http://127.0.0.1/api/v1/cblr/session
Response
[
{
"status": "close",
"sensor_id": 1,
"supported_commands": [
"delete file",
"put file",
"directory list",
"get file",
"kill",
"create process",
"process list",
"create directory"
],
"drives": [],
"storage_size": "46636",
"create_time": 1531841454.61905,
"sensor_wait_timeout": 120,
"address": "144.121.3.50",
"check_in_timeout": 1200,
"id": 2,
"close_time": 1531845314.237512,
"hostname": "devr-test",
"storage_ttl": 7,
"os_version": "",
"session_timeout": 300,
"current_working_directory": "/opt/cbsensor"
},
{
"status": "pending",
"sensor_id": 1,
"supported_commands": [],
"drives": [],
"storage_size": 0,
"create_time": 1531849564.118052,
"sensor_wait_timeout": 120,
"address": null,
"check_in_timeout": 1200,
"id": 3,
"hostname": "devr-test",
"storage_ttl": 7,
"os_version": "",
"session_timeout": 300,
"current_working_directory": ""
},
{
"status": "active",
"sensor_id": 2,
"supported_commands": [
"delete file",
"put file",
"directory list",
"get file",
"kill",
"create process",
"process list",
"create directory"
],
"drives": [],
"storage_size": "46858",
"create_time": 1531849564.118052,
"sensor_wait_timeout": 120,
"address": "144.121.3.50",
"check_in_timeout": 1200,
"id": 3,
"hostname": "devr-test",
"storage_ttl": 7,
"os_version": "",
"session_timeout": 300,
"current_working_directory": "/opt/cbsensor"
}
]
New to EDR 6.3
To view all active CB live response sessions, use a GET
command with the parameter ?active_only=true
to https://<hostname>/api/v1/cblr/session
.
The following request will retrieve a list of currently active sessions. This feature was added to reduce the size of the response when there are a large number of closed sessions.
Note: If you just created a session, it might show up as status: pending
, this will transition to status: active
once the session is ready.
If you don’t use a parameter, or use set active_only=false
, it will default to View Current Sessions
Request
$ curl -H "Content-Type: application/json" -H "X-Auth-Token: d91b00774b2b903b49d8d9caa57ce9fcde16973a" \ http://127.0.0.1/api/v1/cblr/session?active_only=true
Response
[
{
"status": "active",
"sensor_id": 2,
"supported_commands": [
"delete file",
"put file",
"directory list",
"get file",
"kill",
"create process",
"process list",
"create directory"
],
"drives": [],
"storage_size": "46858",
"create_time": 1531849564.118052,
"sensor_wait_timeout": 120,
"address": "144.121.3.50",
"check_in_timeout": 1200,
"id": 3,
"hostname": "devr-test",
"storage_ttl": 7,
"os_version": "",
"session_timeout": 300,
"current_working_directory": "/opt/cbsensor"
}
]
All CBLR activity requires you first start a session with a sensor by POST
ing to /api/v1/cblr/session
with requested sensor_id.
Note: a live response session can be created from the CbR UI as well.
Request
$ curl -H "Content-Type: application/json" -H "X-Auth-Token: d91b00774b2b903b49d8d9caa57ce9fcde16973a" \ -d '{"sensor_id": 10}' http://127.0.0.1/api/v1/cblr/session
Response
{
"status": "pending",
"sensor_id": 10,
"supported_commands": [],
"drives": [],
"storage_size": 0,
"create_time": 1418247933.634789,
"sensor_wait_timeout": 120,
"address": null,
"check_in_timeout": 1200,
"id": 2,
"hostname": "WIN-EP7RMLTCLAJ",
"storage_ttl": 7,
"os_version": "",
"session_timeout": 300,
"current_working_directory": ""
}
Note status
is pending and the session id is 2. Wait a few seconds, then GET
status of session 2:
Request
$ curl -H "Content-Type: application/json" -H "X-Auth-Token: d91b00774b2b903b49d8d9caa57ce9fcde16973a" \
http://127.0.0.1/api/v1/cblr/session/2
Response
{
"status": "active",
"sensor_id": 10,
"supported_commands": [
"delete file",
"put file",
"reg delete key",
"directory list",
"reg create key",
"get file",
"reg enum key",
"reg query value",
"kill",
"create process",
"process list",
"reg delete value",
"reg set value",
"create directory"
],
"drives": ["A:\\", "C:\\", "D:\\"],
"storage_size": 0,
"create_time": 1418247933.634789,
"sensor_wait_timeout": 120,
"address": "::ffff:192.168.206.128",
"check_in_timeout": 1200,
"id": 2,
"hostname": "WIN-EP7RMLTCLAJ",
"storage_ttl": 7,
"os_version": "",
"session_timeout": 300,
"current_working_directory": "C:\\Windows\\CarbonBlack"
}
Note status
is active and session object now has context from the endpoint - supported_commands
, current_working_directory
, etc.
Once a session is active, you can create commands by POST
ing a command object to the session via /api/v1/cblr/session/2/command
. For example, to get a process list:
Request
$ curl -H "Content-Type: application/json" -H "X-Auth-Token: d91b00774b2b903b49d8d9caa57ce9fcde16973a" \ -d '{"session_id": 2, "name": "process list"}' http://127.0.0.1/api/v1/cblr/session/2/command
Response
{
"status": "pending",
"username": "admin",
"sensor_id": 10,
"create_time": 1418248098.5540111,
"name": "process list",
"object": null,
"id": 1,
"session_id": 2
}
Note status
is pending and command id is 1. Wait a few seconds, then GET
status of command 1 in session 2:
Request
$ curl -H "Content-Type: application/json" -H "X-Auth-Token: d91b00774b2b903b49d8d9caa57ce9fcde16973a" \ http://127.0.0.1/api/v1/cblr/session/2/command/1
Response
{
"status": "complete",
"username": "admin",
"sensor_id": 10,
"object": null,
"create_time": 1418248098.5540111,
"id": 1,
"completion": 1418248098.5710759,
"processes": [
{
"username": "NT AUTHORITY\\SYSTEM",
"create_time": 1418247141,
"parent_guid": "0000000a-0000-0000-0000-000000000000",
"parent": 0,
"sid": "s-1-5-18",
"path": "",
"command_line": "",
"pid": 4,
"proc_guid": "0000000a-0000-0004-01d0-14c0c80ce18b"
},
{
"username": "NT AUTHORITY\\SYSTEM",
"create_time": 1418247141,
"parent_guid": "0000000a-0000-0004-01d0-14c0c80ce18b",
"parent": 4,
"sid": "s-1-5-18",
"path": "c:\\windows\\system32\\smss.exe",
"command_line": "\\systemroot\\system32\\smss.exe",
"pid": 276,
"proc_guid": "0000000a-0000-0114-01d0-14c0c80f42ec"
}, ...
]
}
Note status
is complete and the response includes a processes
object that contains the list of currently running processes on sensor_id 10 WIN-EP7RMLTCLAJ.
Other commands function broadly the same way. See the documentation below and the python reference implementation for details. Happy hunting!
To close a running session, you will need the session_id
of the session you would like to close.
Request
curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: d91b00774b2b903b49d8d9caa57ce9fcde16973a" -d '{"status": "close"}' http://127.0.0.1/api/v1/cblr/session/5
Response
{
"status": "active",
"sensor_id": 1,
"supported_commands": [
"delete file",
"put file",
"directory list",
"get file",
"kill",
"create process",
"process list",
"create directory"
],
"drives": [],
"storage_size": "81012",
"create_time": 1531853425.390842,
"sensor_wait_timeout": 120,
"address": "144.121.3.50",
"check_in_timeout": 1200,
"id": 5,
"close_time": 1531854097.192009,
"hostname": "devr-test",
"storage_ttl": 7,
"os_version": "",
"session_timeout": 300,
"current_working_directory": "/opt/cbsensor"
}
Note: Status is still active, but if you request the status of the session using GET http://127.0.0.1/api/v1/cblr/session/5
after a few seconds, you should receive a new response.
New Response
{
"status": "close",
"sensor_id": 1,
"supported_commands": [
"delete file",
"put file",
"directory list",
"get file",
"kill",
"create process",
"process list",
"create directory"
],
"drives": [],
"storage_size": "81012",
"create_time": 1531853425.390842,
"sensor_wait_timeout": 120,
"address": "144.121.3.50",
"check_in_timeout": 1200,
"id": 5,
"close_time": 1531854097.192009,
"hostname": "devr-test",
"storage_ttl": 7,
"os_version": "",
"session_timeout": 300,
"current_working_directory": "/opt/cbsensor"
}
Note: status is now closed.
/api/v1/cblr/session/(id)
Supports GET
, POST
GET
- returns a list of all current session objectsGET
- with (id) - returns a single session object if it existsPOST
- starts a new session (given a sensor id), returns a session idURL Parameters
wait
: OPTIONAL True/False - Blocks the response until a session is available.GET returns
Returns cblr_sensor
session object with the following elements:
id
: the current session idsensor_id
: the sensor id for this sessionstatus
: The current sensor live response status (“active”, “pending”, “timeout”, “inactive”, “close”) - Set status to close and PUT the object to close out the sessionos_version
: The current OS version of the sensorcurrent_working_directory
: The path to the current working directory of the sensordrives
: An array of the logical drives available on the systemsupported_commands
: An array listing out the supported commands on the sensor (for when we support multiple commands across different architectures. (Note: These are 1:1 mapped with the name in the JSON command object (below))check_in_timeout
: the timeout (in seconds) - how long should the CB server wait for the sensor to enter live mode (check-in) (default is wait 1200 seconds - 20 minutes)session_timeout
: the timeout (in seconds) that a sensor should wait between commands. If no command is issued over this timeout the sensor will quit. By default this is 8 minutesPOST accepts
The POST request accepts the following fields in a JSON payload:
sensor_id
- the sensor id to start the session forcheckin_timeout
(optional) (see cblr_sensor)default_command_timeout
(optional) (see cblr_sensor)sensor_wait_timeout
(optional) (see cblr_sensor)POST returns
JSON “cblr_sensor” (see above) Note: only the id will be set in the cblr_sensor until the session has checked in.
/api/v1/cblr/session/(id)/keepalive
Supports GET
Tells the server to reset the sensor “sensor_wait_timeout” if no commands have been sent to the sensor.
This should be leveraged by interactive processes to keep a session alive when there is no command activity past the
“sensor_wait_timeout” period. A request to the endpoint should be made in a time period less than the
sensor_wait_timeout time.
/api/v1/cblr/session/(id)/archive
Supports GET
Returns a compressed archive of all the session contents: log of all commands, their results, contents of all files, etc.
/api/v1/cblr/session/(id)/file
Supports POST
POST
- uploads a file to the EDR server, so it can be pushed to the sensor using the put file
command (below).Use a standard multipart/form-data
file upload (such as used by curl’s -F
command line option) to upload the file to the server with the file contents included in the file
form field.
Example
To upload the file /tmp/blah.txt
to the EDR server so that it can be uploaded to a remote endpoint through Live Response’s put file
command:
$ curl -X POST https://127.0.0.1/api/v1/cblr/session/18/file -H X-Auth-Token:d91b00774b2b903b49d8d9caa57ce9fcde16973a -F file=@/tmp/blah.txt
{"status": 0, "file_name": "blah.txt", "size_uploaded": 15, "size": 15, "id": 5, "delete": false}
The file ID is now 5, which you can pass into the put file
command (below).
/api/v1/cblr/session/(id)/file/(file_id)/contents
Supports GET
GET
- downloads the file contents specified by the file_id
Example
The following command will download the contents of file ID 5 (from above)
$ curl https://127.0.0.1/api/v1/cblr/session/18/file/5/content -H X-Auth-Token:d91b00774b2b903b49d8d9caa57ce9fcde16973a
/api/v1/cblr/session/(id)/command
Supports GET
, POST
GET
- returns a list of commands in this sessionPOST
- creates a new command for this sessionURL Parameters
status
: OPTIONAL completed/in progress/canceled - filter results based on command statuscount
: OPTIONAL int - limit to X results returnedSee Command Objects below for command object details.
/api/v1/cblr/session/(id)/command/(cmdid)
Supports GET
, PUT
GET
- with (cmdid) - returns the status for the specified commandPUT
- with (cmdid) - cancel the specified command if status is pending
See Command Objects below for command object details.
/api/v1/cblr/session/(id)/file/(file_id)
Supports GET
, PUT
GET
- returns a list of files for this sessionGET
- with (file_id) - returns the file
object for the specified idPUT
- with (file_id) - deletes a file object from the serverDELETE
- with (file_id) - deletes a file object from the serverGET returns
Returns a file
object with the following fields:
id
: the file idfile_name
: the (remote) path of the filesize
: the size of the filesize_uploaded
: the size of the full uploaded (from the sensor) so farstatus
: A status code, result for the file request. 0 for success or non-zero for error.delete
: By default this is “false”, (on PUT) set to “true” to force file deletionPUT
this object with delete
set to true or use the DELETE HTTP verb to delete a file from the server’s store.
/api/v1/cblr/session/(id)/file/(file_id)/content
Supports GET
Return the raw contents of the specified file.
The contents of the command request object will vary based on the command requested and the context. Fields present in all command objects:
id
: id of this commandsession_id
: the id of the sessionsensor_id
: the sensor id for the sessioncommand_timeout
: the timeout (in seconds) that the sensor is willing to wait until the command completes.status
: One of the following: “in progress”, “complete”, “cancel”, “error”name
: The name of the command (ie “reg set”, “reg query”, “get file”….)object
: the object the command operates on. This is specific to the command but has meaning in a generic way for logging, and display purposesFields present when command completes:
completion_time
: the time the command completed or 0 if still in progresThese are present if “error” is set in the status.
result_code
: the result/status (0 if successful) or an error code if unsuccessfulresult_type
: “WinHresult”, “CbError”, etcresult_desc
: Optional error string describing the errorThe remaining fields are specific to each requested built-in command:
name
: “put file”object
: the destination path of the filefile_id
: the file id of the file in session storage (use second api to add new files)name
: “get file”object
: the source path of the fileoffset
: a byte offset to start getting the file. Supports a partial get.get_count
: the number of bytes to grabResponse Object
file_id
: the file id of the file (must use second API call to obtain the file)name
: “delete file”object
: the source path of the object to deletename
: “directory list”object
: the directory listing filter (or path)Response Object
files
: an array of file list objects, which contain:
attributes
: an array of attribute strings representations of windows file attributes, with the FILE_ATfTRIBUTE_ part removed (ie DEVICE, DIRECTORY, HIDDEN, …..)create_time
: in unix time formatlast_access_time
: in unix time formatlast_write_time
: in unix time formatsize
: the size of the filename
: the name of the filealt_name
: the Windows “alternate name” (short name) of the filename
: “reg enum key”object
: the path of the key to queryResponse Object
values
: an array of registry values which contain:
value_type
: the string representation of the registry value type (ie REG_DWORD, REG_QWORD, ….)value_name
: the name of the registry valuevalue_data
: the data associated with the registry valuesub_keys
: an array of subkey names (ie { “sub_keys” : [“some_sub_key” , “some_other_sub_key”]}name
: “reg query value”object
: the path of the key + the path of the value (ie HKEY_LOCAL_MACHINE\blah\key\value
)Response Object
value
: See the values object returned in the “values” field of reg enum keyname
: “reg create key”object
: the key path to createname
: “reg delete key”object
: the key path to deletename
: “reg delete value”object
: the path of the key + the path of the valuename
: “reg set value”object
: the path of the key + the path of the valuevalue_data
: the data to set for the value. Note if value_data is for type REG_MULTI_SZ then value_data should be an array of strings. ie “value_data” : [“string1”, “string2”, “string3”],value_type
: one of common reg value types (in string form). Ie REG_DWORD, REG_QWORD, REG_SZ, …..overwrite
: “true” or “false”. An optional parameter to specify whether to overwrite the value if it already exists (default value is “false”)name
: “process list”object
: emptyResponse Object
processes
: an array of process objects which contain:pid
: process idcreate_time
: the creation time of the process in unix timeproc_guid
: the process guid of the processpath
: the execution path of the processcommand_line
: the command line of the processsid
: the Security Identifier (SID) of the default process tokenusername
: the username of the default process tokenparent
: the pid (process id ) of the parentparent_guid
: the process guid of the parent processname
: “kill”object
: the pid to killname
: “create process”object
: the path and command line of the executablewait
: “true” or “false” - An optional parameter to specify whether to wait for the process to complete execution before reporting the resultworking_directory
: An optional parameter to specify the working directory of the executableoutput_file
: An option file that STDERR and STDOUT will be redirected to.Response Object
pid
: the pid of the executed processreturn_code
: the return code of the process (if wait was set to “true”)Note: Only available on EDR Server versions 5.1 and above, and requires that the target endpoint is running a sensor version 5.1 and above as well.
name
: “memdump”object
: the path to save the resulting memory dump (on the endpoint)Response Object
return_code
: return code of the memory dump processcomplete
: boolean flag indicating if memory dump is completedpercentdone
: percent of the process completeddumping
: boolean flag indicating if memory dump is in progressLive Response settings can be configured on your EDR Server by editing your /etc/cb/cb.conf
file. For cloud instances, please contact support to have these settings changed.
Enable/Disable CBLR functionality. Disabled by default
CbLREnabled=False
Note:: EDR Global administrators can enable or disable Live Response on the Advanced Settings page (in the UI), but only if CbLREnabled is removed from cb.conf or commented out. If CbLREnabled is present in cb.conf, global administrators cannot change its state on the Advanced Settings page.
Timeout (in seconds) to wait for sensor to initialize cblr session (20 minutes).On expiration, cblr session is discarded.
CbLRCheckinTimeout=1200
Max time (in seconds) for sensor to wait for a cblr command (5 minutes)
CbLRSessionTimeout=300
Long poll duration (in seconds) of the sensor command query before returning keepalive
CbLRSensorWaitTimeout=120
Max disk space (in megabytes) usable by cblr functionality. When exceeded, all requests that could possibly require more disk space will be rejected. 0 indicates unlimited.
CbLRMaxStoreSizeMB=0
Default time-to-live (in days) for session data. Unless overwritten through the API, session data will be deleted CbLrDefaultSessionTTLDays following the close of the session.
New to EDR 6.3+: Floating point values may be specified for CbLrDefaultSessionTTLDays (e.g. CbLrDefaultSessionTTLDays=0.01). Note that the thread that deletes the session data only runs hourly, so you may still need to wait up to one hour past the specified time interval for the deletion to occur.
CbLrDefaultSessionTTLDays=7
cb-liveresponse will not allow more than CbLRMaxActiveSessions concurrent active sessions. Requests to create more than CbLRMaxActiveSessions will be rejected.
CbLRMaxActiveSessions=10