Endpoint Standard Live Response API Reference

WARNING: This is a legacy document, please view the latest version here.

This API will be deactivated on September 5, 2024.

More information on how to move to the Live Response v6 API can be found here.

Carbon Black Cloud Endpoint Standard is the new name for the product formerly called CB Defense.

Live Response is a feature that’s available across all products on the Carbon Black Cloud. Live Response 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 Endpoint Standard REST APIs. Authentication uses the same AuthToken Header as the Endpoint Standard REST API.

Note: Live Response requires the use of the Live Response Access Level type; any other Access Level type will result in an Unauthorized error when attempting to access any Live Response API routes.

To support integrations using this route, this legacy route continues to be supported with the following authentication:

If using Carbon Black Cloud identity management, choose the Access Level type “LIVE_RESPONSE” when creating the API Key.
If using VMware Cloud Services Platform for identity management, assign the permission _ConnectorType.LIVE_RESPONSEto a custom role and assign that custom role to an OAuth App. Use the OAuth App Id and Secret in place of the API Id and Key values respectively.

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 device. A device 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.

Example

All examples here use a fictional API hostname of api.confer.net – replace this hostname with your organization’s API hostname. If you do not have an API hostname listed in your Carbon Black Cloud console, contact Support for assistance.

Start a new session

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

All CBLR activity requires you first start a session with a device by POSTing to /integrationServices/v3/cblr/session/<device_id> with requested device_id. For example:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: ABCD/1234" \
-d '{"sensor_id": 37191}' https://api.confer.net/integrationServices/v3/cblr/session/37191

{
  "hostname": null,
  "address": null,
  "os_version": null,
  "current_working_directory": null,
  "supported_commands": null,
  "drives": null,
  "id": "1:37191",
  "sensor_id": 37191,
  "check_in_timeout": 900,
  "session_timeout": 900,
  "sensor_check_in_time": null,
  "status": "PENDING",
  "current_command_index": 0,
  "create_time": 1502126352449
}

Note status is PENDING and the session id is 1:37191. Wait a few seconds, then GET status of session 1:37191:

$ curl -H "Content-Type: application/json" -H "X-Auth-Token: ABCD/1234" \
https://api.confer.net/integrationServices/v3/cblr/session/1:37216

{
  "hostname": null,
  "address": null,
  "os_version": null,
  "current_working_directory": "C:\\Windows\\system32",
  "supported_commands": [
    "put file",
    "get file",
    "memdump",
    "create directory",
    "delete file",
    "directory list",
    "reg enum key",
    "reg query value",
    "reg create key",
    "reg delete key",
    "reg delete value",
    "reg set value",
    "process list",
    "kill",
    "create process"
  ],
  "drives": [
    "A:\\",
    "C:\\",
    "D:\\"
  ],
  "id": "1:37191",
  "sensor_id": 37191,
  "check_in_timeout": 900,
  "session_timeout": 900,
  "sensor_check_in_time": 1502126744685,
  "status": "ACTIVE",
  "current_command_index": 0,
  "create_time": 1502126655758
}

Note status is ACTIVE and session object now has context from the endpoint - supported_commands, current_working_directory, etc.

Upload File to Server

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

To upload a file to an endpoint, you can POST the file to /integrationServices/v3/cblr/session/(id)/file which will return a file_id.

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://api.confer.net/integrationServices/v3/cblr/session/1:37191/file -H X-Auth-Token:ABCD/1234 -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).

Issue command

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

Once a session is active, you can create commands by POSTing a command object to the session via /integrationServices/v3/cblr/session/1:37191/command. For example, to get a process list:

$ curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: ABCD/1234" \
-d '{"session_id": "1:37191", "name": "process list"}' https://api.confer.net/integrationServices/v3/cblr/session/1:37191/command

{
  "obj": {
    "name": "process list"
  },
  "id": 0,
  "name": "process list",
  "username": null,
  "creation_time": 1502127102,
  "completion_time": 0,
  "result_code": 0,
  "result_type": null,
  "result_desc": "",
  "status": "pending",
  "processes": []
}

Note status is pending and command id is 0. Wait a few seconds, then GET status of command 0 in session 1:37191:

$ curl -H "Content-Type: application/json" -H "X-Auth-Token: ABCD/1234" \
https://api.confer.net/integrationServices/v3/cblr/session/1:37191/command/0

{
  "obj": {
    "name": "process list"
  },
  "id": 0,
  "name": "process list",
  "username": null,
  "creation_time": 1502127102,
  "completion_time": 1502127102,
  "result_code": 0,
  "result_type": "WinHresult",
  "result_desc": "",
  "status": "complete",
  "processes": [
    {
      "pid": 104,
      "create_time": 1502126665,
      "path": "\\Device\\HarddiskVolume1\\Windows\\System32\\cmd.exe",
      "command_line": "\"C:\\Windows\\system32\\cmd.exe\" ",
      "sid": "S-1-5-21-3754467061-2624221190-3096525165-1002",
      "username": "WIN-IA9NQ1GN8OI\\user",
      "parent": 3624,
      "parent_create_time": 0
    },
    {
      "pid": 1460,
      "create_time": 1502126665,
      "path": "\\Device\\HarddiskVolume1\\Windows\\System32\\conhost.exe",
      "command_line": "\\??\\C:\\Windows\\system32\\conhost.exe 0xffffffff",
      "sid": "S-1-5-21-3754467061-2624221190-3096525165-1002",
      "username": "WIN-IA9NQ1GN8OI\\user",
      "parent": 104,
      "parent_create_time": 0
    },...
  ]
}

Note status is complete and the response includes a processes object that contains the list of currently running processes on sensor_id 37191.

Other commands function broadly the same way. See the documentation below for the command object reference and the python reference implementation for details.

Close a session

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

To close out your session, PUT the CLOSE status back to the session object:

$ curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: ABCD/1234" \
-d '{"session_id": "1:37191", "status": "CLOSE"}' https://api.confer.net/integrationServices/v3/cblr/session

{
  "hostname": null,
  "address": null,
  "os_version": null,
  "current_working_directory": "C:\\Windows\\system32",
  "supported_commands": [
    "put file",
    "get file",
    "memdump",
    "create directory",
    "delete file",
    "directory list",
    "reg enum key",
    "reg query value",
    "reg create key",
    "reg delete key",
    "reg delete value",
    "reg set value",
    "process list",
    "kill",
    "create process"
  ],
  "drives": [
    "A:\\",
    "C:\\",
    "D:\\"
  ],
  "id": "1:37191",
  "sensor_id": 37191,
  "check_in_timeout": 900,
  "session_timeout": 900,
  "sensor_check_in_time": 1502127557842,
  "status": "CLOSE",
  "current_command_index": 1,
  "create_time": 1502126655758
}

Happy hunting!

API Reference

Establish Live Response Session

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

/integrationServices/v3/cblr/session/(session_id)

Supports GET, POST, PUT

GET - with (session ID) - returns a single session object if it exists
POST - starts a new session (given a sensor/device ID), returns a session id
PUT - with a body of set status to CLOSE and PUT to the /integrationServices/v3/cblr/session API route to close an open session

URL Parameters

wait: OPTIONAL True/False - Blocks the response until a session is available.

GET Example

The GET request requires you to have a session_id which will look something like: 213:12312. It is a combination of the session_id:sensor_id.

Example request: GET https://api.confer.net/integrationServices/v3/cblr/session/(session_id)

GET Returns

Returns cblr_sensor session object with the following elements:

id: the current session id
sensor_id: the device id for this session
hostname: the device hostname
os_version: the OS version of the device
status: The current device live response status (“ACTIVE”, “PENDING”, “TIMEOUT”, “INACTIVE”, “CLOSE”). Set status to CLOSE and PUT the object to close out the session
os_version: The current OS version of the device
current_working_directory: The path to the current working directory of the device
drives: An array of the logical drives available on the system
supported_commands: An array listing out the supported commands on the device (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 device to enter live mode (check-in) (default is wait 1200 seconds - 20 minutes)
session_timeout: the timeout (in seconds) that a device should wait between commands. If no command is issued over this timeout the device will quit. By default this is 8 minutes
create_time: the time the session was created (in epoch time).

POST Example

The POST request accepts the following fields in a JSON payload:

sensor_id - the device id to start the session for
checkin_timeout (optional) (see cblr_sensor)
default_command_timeout (optional) (see cblr_sensor)
sensor_wait_timeout (optional) (see cblr_sensor)

Example request: POST https://api.confer.net/integrationServices/v3/cblr/session/(sensor_id)

POST Returns

JSON “cblr_sensor” (see above) Note: only the id will be set in the cblr_sensor until the session has checked in.

PUT Example

The PUT request is used to close a live response session. You will need to provide a JSON payload with:

session_id: It is a combination of the session_id:sensor_id, example: "213:12312".
status: This is case sensitive, example: "CLOSE".

Example request with payload:

PUT https://api.confer.net/integrationServices/v3/cblr/session

JSON Payload: {"session_id": "213:12312", "status": "CLOSE"}

PUT Returns

The JSON body returned will be similar to the GET request, but the status in the body should say CLOSE.

Reset Session Timeout

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

/integrationServices/v3/cblr/session/(session_id)/keepalive

Supports GET

Tells the server to reset the device “sensor_wait_timeout” if no commands have been sent to the device.
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.

Send Command to Endpoint

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

/integrationServices/v3/cblr/session/(id)/command

Supports GET, POST

GET - returns a list of commands in this session
POST - creates a new command for this session

URL Parameters

status: OPTIONAL completed/in progress/canceled - filter results based on command status
count: OPTIONAL int - limit to X results returned

See Command Objects below for command object details.

Get Status of Command

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

/integrationServices/v3/cblr/session/(id)/command/(cmdid)

Supports GET, PUT

GET - with (cmdid) - returns the status for the specified command
PUT - with (cmdid) - cancel the specified command if status is pending

See Command Objects below for command object details.

Get File Metadata

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

/integrationServices/v3/cblr/session/(id)/file/(file_id)

Supports GET, PUT

GET - returns a list of files for this session
GET - with (file_id) - returns the file object for the specified id
PUT - with (file_id) - deletes a file object from the server
DELETE - with (file_id) - deletes a file object from the server

GET returns

Returns a file object with the following fields:

id: the file id
file_name : the (remote) path of the file
size : the size of the file
size_uploaded : the size of the full uploaded (from the device) so far
status: 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 deletion

PUT this object with delete set to true or use the DELETE HTTP verb to delete a file from the server’s store.

Get File Content

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

/integrationServices/v3/cblr/session/(id)/file/(file_id)/content

Supports GET

Return the raw contents of the specified file.

Command Objects

This API is being deactivated.

You may continue to access the documentation below until the `/integrationServices/v3/cblr` API is deactivated. The replacement service is Live Response v6 API available here.

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 command
session_id: the id of the session
sensor_id: the device id for the session
command_timeout: the timeout (in seconds) that the device 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 purposes

Fields present when command completes:

completion_time: the time the command completed or 0 if still in progres

These are present if “error” is set in the status.

result_code: the result/status (0 if successful) or an error code if unsuccessful
result_type: “WinHresult”, “CbError”, etc
result_desc: Optional error string describing the error

The remaining fields are specific to each requested built-in command:

put file

name: “put file”
object: the destination path of the file
file_id: the file id of the file in session storage (use second api to add new files)

get file

name: “get file”
object: the source path of the file
offset: a byte offset to start getting the file. Supports a partial get.
get_count: the number of bytes to grab

Response Object

file_id: the file id of the file (must use second API call to obtain the file)

delete file

name: “delete file”
object: the source path of the object to delete

directory listing

name: “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 format
- last_access_time: in unix time format
- last_write_time: in unix time format
- size: the size of the file
- name: the name of the file
- alt_name: the Windows “alternate name” (short name) of the file

reg enum key

name: “reg enum key”
object: the path of the key to query

Response 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 value
- value_data: the data associated with the registry value
- sub_keys : an array of subkey names (ie { “sub_keys” : [“some_sub_key” , “some_other_sub_key”]}

reg query value

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 key

reg create key

name: “reg create key”
object: the key path to create

reg delete key

name: “reg delete key”
object: the key path to delete

reg delete value

name : “reg delete value”
object: the path of the key + the path of the value

reg set value

name: “reg set value”
object: the path of the key + the path of the value
value_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”)

ps

name: “process list”
object: empty

Response Object

processes: an array of process objects which contain:
pid: process id
create_time: the creation time of the process in unix time
proc_guid: the process guid of the process
path: the execution path of the process
command_line: the command line of the process
sid: the Security Identifier (SID) of the default process token
username: the username of the default process token
parent: the pid (process id ) of the parent
parent_guid: the process guid of the parent process

kill

name: “kill”
object: the pid to kill

execute

name: “create process”
object: the path and command line of the executable
wait: “true” or “false” - An optional parameter to specify whether to wait for the process to complete execution before reporting the result
working_directory: An optional parameter to specify the working directory of the executable
output_file: An option file that STDERR and STDOUT will be redirected to.

Response Object

pid: the pid of the executed process
return_code: the return code of the process (if wait was set to “true”)

memdump

name: “memdump”
object: the path to save the resulting memory dump (on the endpoint)

Response Object

return_code: return code of the memory dump process
complete: boolean flag indicating if memory dump is completed
percentdone: percent of the process completed
dumping: boolean flag indicating if memory dump is in progress

Last modified on August 7, 2017

Carbon Black Cloud

Page Contents

Endpoint Standard Live Response API Reference

Example

Start a new session

Upload File to Server

Issue command

Close a session

API Reference

Establish Live Response Session

Reset Session Timeout

Send Command to Endpoint

Get Status of Command

Get File Metadata

Get File Content

Command Objects

put file

get file

delete file

directory listing

reg enum key

reg query value

reg create key

reg delete key

reg delete value

reg set value

ps

kill

execute

memdump