LiveResponse - ace-ecosystem/cbinterface2 GitHub Wiki

Live Response

cbinterface has a robust live response interface for managing live response activities. Everything that falls under "Live Response" requires a Carbon Black Live Response session.

Command line interface to live response functions, below. Notice commands that are here that do not categorically fall into a "collection" or "remediation" category, such as, executing a command. Also notice the quarantine/isolation features are here.

$ cbinterface lr -h
usage: cbinterface live-response [-h] [-e EXECUTE_COMMAND]
                                        [-cr CREATE_REGKEY]
                                        [-sr SET_REGKEY_VALUE] [-i] [-q] [-uq]
                                        name_or_id
                                        {put,playbook,pb,play,collect,remediate}
                                        ...

positional arguments:
  name_or_id            the hostname or sensor/device id to go live with.
  {put,playbook,pb,play,collect,remediate}
    put                 Put a file on the device/sensor.
    playbook (pb, play)
                        Execute a live response playbook script.
    collect             Collect artifacts from hosts.
    remediate           Perform remdiation (delete/kill) actions on
                        device/sensor.

optional arguments:
  -h, --help            show this help message and exit
  -e EXECUTE_COMMAND, --execute-command EXECUTE_COMMAND
                        Execute this command on the sensor. NOTE: waits for
                        output.
  -cr CREATE_REGKEY, --create-regkey CREATE_REGKEY
                        Create this regkey.
  -sr SET_REGKEY_VALUE, --set-regkey-value SET_REGKEY_VALUE
                        Set this regkey value.
  -i, --sensor-isolation-toggle
                        Sensor hostname/ID to isolation/unisolate (on/off).
                        (CB Response)
  -q, --quarantine      Quarantine the devices returned by the query. (PSC)
  -uq, --un_quarantine  UN-Quarantine the devices returned by the query. (PSC)

Live Response Commands

Thanks to Carbon Blacks "job" implementation and the functionality to support it that they provide in cbapi, I was able to create all of the live response functions as "commands". Getting a file from an endpoint is an example of a command and implemented via the cbinterface.commands.GetFile command function.

These commands become building blocks for live response "playbooks" and scripts. Collecting browsing history is an example of a playbook. Remediating a NanoCore infection with an example of a script.

from cbinterface.commands import (
    PutFile,
    ProcessListing,
    GetFile,
    ListRegKeyValues,
    RegKeyValue,
    ExecuteCommand,
    ListDirectory,
    WalkDirectory,
    LogicalDrives,
    DeleteFile,
    KillProcessByID,
    KillProcessByName,
    DeleteRegistryKeyValue,
    DeleteRegistryKey,
    SetRegKeyValue,
    CreateRegKey,
    GetSystemMemoryDump,
)

Live Response Collection

Pretty much a one-for-one interface to the available Carbon Black live response functions that fall into the category of artifact "collection".

$ cbinterface lr "theHostgoesHere" collect -h
usage: cbinterface live-response name_or_id collect [-h] [-i] [-p]
                                                           [-f FILE]
                                                           [-lr REGKEYPATH]
                                                           [-r REGKEYVALUE]
                                                           [-ld LIST_DIRECTORY]
                                                           [-wd WALK_DIRECTORY]
                                                           [--drives]
                                                           [--memdump]

optional arguments:
  -h, --help            show this help message and exit
  -i, --sensor-info     print default sensor information
  -p, --process-list    show processes running on sensor
  -f FILE, --file FILE  collect file at this path on sensor
  -lr REGKEYPATH, --regkeypath REGKEYPATH
                        List all registry values from the specified registry
                        key.
  -r REGKEYVALUE, --regkeyvalue REGKEYVALUE
                        Returns the associated value of the specified registry
                        key.
  -ld LIST_DIRECTORY, --list-directory LIST_DIRECTORY
                        List the contents of a directory on the sensor.
  -wd WALK_DIRECTORY, --walk-directory WALK_DIRECTORY
                        List the contents of a directory on the sensor.
  --drives              Get logical drives on this sensor.
  --memdump             Use Cb to dump sensor memory and collect the memdump.

Live Response Remediation

Also a one-for-one interface to the available Carbon Black live response functions that fall into the category of "remediation". Also known as, deleting and destroying malicious things. Make sure to check out the remediation script functionality and notice the --write-template function here for help with creating those remediation scripts.

$ cbinterface lr "theHostgoesHere" remediate -h
usage: cbinterface live-response name_or_id remediate
       [-h] [-f DELETE_FILE_PATH] [-kpname KILL_PROCESS_NAME]
       [-kpid KILL_PROCESS_ID] [-drv DELETE_REGKEYVALUE]
       [--delete-entire-regkey DELETE_ENTIRE_REGKEY] [-rs REMEDIATION_SCRIPT]
       [--write-template]

optional arguments:
  -h, --help            show this help message and exit
  -f DELETE_FILE_PATH, --delete-file-path DELETE_FILE_PATH
                        delete the file at this path on the sensor
  -kpname KILL_PROCESS_NAME, --kill-process-name KILL_PROCESS_NAME
                        kill all processes with this name
  -kpid KILL_PROCESS_ID, --kill-process-id KILL_PROCESS_ID
                        kill the process with this ID
  -drv DELETE_REGKEYVALUE, --delete-regkeyvalue DELETE_REGKEYVALUE
                        Delete the regkey value.
  --delete-entire-regkey DELETE_ENTIRE_REGKEY
                        Delete the registry key and all values. BE CAREFUL.
  -rs REMEDIATION_SCRIPT, --remediation-script REMEDIATION_SCRIPT
                        Path to a remediaiton script.
  --write-template      write a remediation template.

Live Response Playbooks

You can define Live Response Playbooks to do common tasks.

$ dev-cbinterface.py lr theHost playbook -h
usage: dev-cbinterface.py live-response name_or_id playbook
       [-h] [-f PLAYBOOK_CONFIGPATH]
       [-p {collect_browsing_history,get_user_account_data_NOT_READY,delete_directory,collect_scheduled_tasks,Delete Scheduled Task,delete_service}]
       [-l] [--write-template]

optional arguments:
  -h, --help            show this help message and exit
  -f PLAYBOOK_CONFIGPATH, --playbook-configpath PLAYBOOK_CONFIGPATH
                        Path to a playbook config file to execute.
  -p {collect_browsing_history,get_user_account_data_NOT_READY,delete_directory,collect_scheduled_tasks,Delete Scheduled Task,delete_service}, --playbook-name {collect_browsing_history,get_user_account_data_NOT_READY,delete_directory,collect_scheduled_tasks,Delete Scheduled Task,delete_service}
                        The name of a configured playbook to execute.
  -l, --list-playbooks  List configured playbooks.
  --write-template      write a playbook template file to use as example.

I've includes some playbooks by default.

$ cbinterface lr theHostnameOrDeviceID playbook --list-playbooks 

Configured Playbooks:
	delete_directory : Delete a directory structure.
	Delete Scheduled Task : Delete a scheduled task by name on a windows os.
	collect_scheduled_tasks : Get all scheduled tasks on a windows device
	delete_service : Delete a service from the registry.
	collect_browsing_history : Collect Chrome and Edge browsing history.

Create your own and use the -f to execute them.

You can also save your playbooks by adding them to a global cbinterface config file, /etc/carbonblack/cbinterface.ini or a user specific one ~/.carbonblack/cbinterface.ini Put them under a sections named playbooks. Keys should be unique (the name of the playbook works well) and the value should be the absolute path to the playbook config. Like this:

[playbooks]
collect_browsing_history=/etc/carbonblack/playbooks/collect_browsing_history.ini

Here is the playbook template you can use to create playbooks. Read the comments in the template for guidance.

$ cbinterface lr fakeHostName pb --write-template 
2021-03-12 17:36:24 analysis cbinterface.cli[4837] INFO  + wrote playbook.ini

$ cat playbook.ini 
[overview]
; This overview section is for optionally providing context about a playbook.
; The overview section is the only section that is not treated as-if it's a command.
; name of playbook
name=My cool playbook
; description of playbook
description=This playbook does helpful IDR stuff that enables analysts.
; A comma separated list of arguments this playbook requires
; These required_arguments map to non-standard placeholders (see NOTE2)
required_arguments=

## NOTE1
;# Note on playbooks operations
;# Operations map to CbLR session commands.
;# Operations required.
;# The following operations are supported:
;#    run: execute something
;#    download: download a file to a device 
;#    upload: upload a file from a device
;#
;# These operations should be all you ever need, but if not, let me know.

## NOTE2
;# Note on placeholders:
;# Format strings are used to supply placeholders values before live response
;# job submission. The following placeholders are supplied by default:
;#     HOSTNAME, SENSOR_ID, DEVICE_ID, BASE_DIR
;# Custom placeholders will require that you pass those placeholders when building live 
;# response commands or directly to already built (but not yet submitted) commands.
;# If you supply the placeholders to the required_arguments item in the overview,
;# console users will be prompted to enter values for each one.

[command_example_download]
operation=download
; path to local file
file_path=path/to/file/you/want/to/put/on/the/device
; where to write the file on the client
client_file_path=c:\where\to\write\the\file\on\the\device
; if not a full path, whatever default LR working dir is used.
; so it's okay to not fully qualify client_file_path, if you do not need to.

[command_example_run]
operation=run
; the command to run
command=my_cool_thing.bat
;# other run options. Values are the defaults if the option is not specified.
;wait_for_output=yes
;remote_output_file_name=
;working_directory=
;wait_timeout=30
;wait_for_completion=yes
;print_results=yes
;write_results_path=no

[command_example_upload]
operation=upload
path=File_in_working_dir_on_client_OR_full_path_to_file_on_client
# built-in placeholder HOSTNAME used in example:
write_results_path={HOSTNAME}_Example_FileName

[command_cmd_shell_example]
operation=run
wait_for_output=no
command=cmd.exe /c del my_cool_thing.bat

;# Now you can go on with however many command sections you desire and 
;# in whatever order to accomplish whatever need. Be wise.

Live Response Remediation Scripts

To adequately respond to an infection, you often need to perform multiple remediation actions to achieve your goal. It's always the best case to identify everything that needs remediation and clean it up in one single pass. This type of single pass remediation helps ensure watch dog processes and other persistent mechanisms are cleaned up before a malicious infection can re-gain a persistent foothold. It’s an all out blitz attack on the malicious infection. When you attack on all fronts at, at the same time, you're more likely to be successful.

As mentioned above, in the Live Response Remediation section, you can use the following command to write a remediation template:

$ cbinterface lr deviceNameOrIdHere remediate --write-template 
2021-03-13 18:45:10 analysis cbinterface.cli[32418] INFO  + wrote remediate.ini

The content of remediate.ini file:

## Example remediate routine file.
##  All keys are commented out under their respective sections by default.
# Remediation is performed in the following order:
#  1. Kill running processes
#  2. Delete registry locations
#  3. Delete scheduled tasks
#  4. Delete services
#  5. Delete files
#  6. Delete directories

# Specify full paths to files that you want to delete.
#  ex: file1=c:\programdata\lemontrack installer\winserv.exe
[files]
;file1=
;file2=
;file3=

# Specify processes that you want to kill by name. All processes matching the name will be killed
#  ex: proc1=winserv.exe
[process_names]
;proc1=
;proc2=
;proc3=

# Delete a scheduled task
#  ex: task1=TaskFolder\DHCP Monitor Task
[scheduled_tasks]
;task1=
;task2=

# SC delete services by their name
# Not yet Implemented with CbLR
[services]
;service1=
;service2=
 
# Delete entire directories
#  ex: directory1=C:\ProgramData\LemonTrack Installer
[directories]
;directory1=
;directory2=

# Delete processes by their ID
#  ex: pid1=2664
[pids]
;pid1=
;pid2=

# delete individual registry key-values
#  ex: reg1=HKU\S-1-5-21-1660022851-2357930215-3100199371-1001\Software\Microsoft\Windows\CurrentVersion\Run\LemonTrack
#  This translates to: REG DELETE "HKU\S-1-5-21-1660022851-2357930215-3100199371-1001\Software\Microsoft\Windows\CurrentVersion\Run" /v LemonTrack /f
[registry_values]
;reg1=
;reg2=

# delete all values behing a key
#  ex: reg1=HKLM\Software\Microsoft\Windows\CurrentVersion\Run
#  REG DELETE HKLM\Software\Microsoft\Windows\CurrentVersion\Run /f
[registry_keys]
;reg1=
;reg2=

Endpoint Containment

Under live-response:

  -i, --sensor-isolation-toggle
                        Sensor hostname/ID to isolation/unisolate (on/off).
                        (CB Response)
  -q, --quarantine      Quarantine the devices returned by the query. (PSC)
  -uq, --un_quarantine  UN-Quarantine the devices returned by the query. (PSC)

Response

The following command will "toggle" sensor isolation:

$ cbinterface live-response -i fredLaptop
2021-04-05 11:55:51 analysis cbinterface.response.cli[1976] INFO searching for sensor...
2021-04-05 11:55:51 analysis cbinterface.response.sensor[1976] INFO got 1 sensor results.
2021-04-05 11:55:51 analysis cbinterface.response.cli[1976] INFO sensor 28399:fredLaptop is currently unisolated. Changing state to: isolated

PSC

The following commands will quarantine and un-quarantine a device:

Contain/Quarantine
$ cbinterface live-response -q fredLaptop
2021-04-05 11:53:51 analysis cbinterface.psc.cli[1559] INFO searching for device...
2021-04-05 11:53:51 analysis cbinterface.psc.device[1559] INFO got 1 device results.
2021-04-05 11:53:51 analysis cbinterface.psc.cli[1559] INFO setting quarantine on 1 devices... 👀
2021-04-05 11:53:51 analysis cbinterface.psc.cli[1559] INFO device 37102362:fredLaptop hasn't checked in for: 4:52:36.695453
2021-04-05 11:53:51 analysis cbinterface.psc.cli[1559] WARNING device 37102362:fredLaptop appears offline 💤
2021-04-05 11:53:51 analysis cbinterface.psc.cli[1559] INFO device 37102362:fredLaptop will change quarantine state when it comes online 👌
2021-04-05 11:53:51 analysis cbinterface.psc.cli[1559] INFO Device 37102362:fredLaptop is set to quarantine.
Remove containment/un-quarantine
$ cbinterface live-response -uq fredLaptop
2021-04-05 11:54:19 analysis cbinterface.psc.cli[1620] INFO searching for device...
2021-04-05 11:54:19 analysis cbinterface.psc.device[1620] INFO got 1 device results.
2021-04-05 11:54:19 analysis cbinterface.psc.cli[1620] INFO setting NOT quarantine on 1 devices... 👏
2021-04-05 11:54:19 analysis cbinterface.psc.cli[1620] WARNING device 37102362:fredLaptop is already set to NOT quarantine.
2021-04-05 11:54:19 analysis cbinterface.psc.cli[1620] INFO Device 37102362:fredLaptop is set to NOT quarantine.

Additionally, you can find endpoint containment, also called quarantine, functionality under cbinterface device:

$ cbinterface device -h
usage: cbinterface device [-h] [-nw] [-ad] [-q] [-uq] device_query

positional arguments:
  device_query          the device query you'd like to execute. 'FIELDS' for
                        help.

optional arguments:
  -h, --help            show this help message and exit
  -nw, --no-warnings    Don't warn before printing large query results
  -ad, --all-details    Print all available process info (all fields).
  -q, --quarantine      Quarantine the devices returned by the query.
  -uq, --un_quarantine  UN-Quarantine the devices returned by the query.
More Containment Examples

Note that device queries have different fields from process fields.

Also note that if a device is offline, its' state will continue to show as NOT quarantined but know that the Carbon Black PSC will put the device into quarantine state as soon as the device comes back online.

Just using a value search on a hostname called 'fredLaptop' I can contain the resulting device:

$ cbinterface device 'fredLaptop' -q
2021-04-05 11:44:51 analysis cbinterface.psc.cli[427] INFO searching psc:acme environment for device query: fredLaptop...
2021-04-05 11:44:51 analysis cbinterface.psc.device[427] INFO No field specification passed. Use 'FIELDS' for help.
2021-04-05 11:44:51 analysis cbinterface.psc.device[427] INFO got 1 device results.
2021-04-05 11:44:51 analysis cbinterface.psc.cli[427] INFO setting quarantine on 1 devices... 👀
2021-04-05 11:44:52 analysis cbinterface.psc.cli[427] INFO device 37102362:fredLaptop hasn't checked in for: 4:43:37.389856
2021-04-05 11:44:52 analysis cbinterface.psc.cli[427] WARNING device 37102362:fredLaptop appears offline 💤
2021-04-05 11:44:52 analysis cbinterface.psc.cli[427] INFO device 37102362:fredLaptop will change quarantine state when it comes online 👌

------------------------- PSC DEVICE RESULTS -------------------------

-------------------------------------------------------------------------------
	AD Group ID: 27098
	Current Policy Name: General Policy
	Deployment Type: ENDPOINT
	Device ID: 37102362
	Device Name: fredLaptop
	Device MAC address: 54edaff03760
	Device OS: WINDOWS
	Device OS Version: Windows 10 x64
	Device Owner ID: 5599607
	Device Owner Email: fred
	Device Owner Name: None, None
	Device Quarantined: False
	Device Registration Time: 2021-02-17 15:03:18.573000-0500
	Last Checkin Time: 2021-04-05 07:01:14.748000-0400
	 ↳ Elapsed Time: 4:43:37.691063 - likely offline 💤
	Last Reported Event Time: 2021-03-14 16:57:31.703000-0400
	Last External IP: 87.92.3.14
	Last Internal IP: 192.168.1.116
	Last Location: OFFSITE
	Last Logged In User: fredLaptop\fred
	Sensor status: REGISTERED
	Sensor Version: 3.6.0.1979

Next, I can un-contain the same device with another query. This time I specify the device ID in my query:

$ cbinterface device 'deviceId:37102362' -u
2021-04-05 11:46:54 analysis cbinterface.psc.cli[641] INFO searching psc:acme environment for device query: deviceId:37102362...
2021-04-05 11:46:54 analysis cbinterface.psc.device[641] INFO got 1 device results.
2021-04-05 11:46:54 analysis cbinterface.psc.cli[641] INFO setting NOT quarantine on 1 devices... 👏
2021-04-05 11:46:54 analysis cbinterface.psc.cli[641] WARNING device 37102362:fredLaptop is already set to NOT quarantine.

------------------------- PSC DEVICE RESULTS -------------------------

-------------------------------------------------------------------------------
	AD Group ID: 27098
	Current Policy Name: General Policy
	Deployment Type: ENDPOINT
	Device ID: 37102362
	Device Name: fredLaptop
	Device MAC address: 54edaff03760
	Device OS: WINDOWS
	Device OS Version: Windows 10 x64
	Device Owner ID: 5599607
	Device Owner Email: fred
	Device Owner Name: None, None
	Device Quarantined: False
	Device Registration Time: 2021-02-17 15:03:18.573000-0500
	Last Checkin Time: 2021-04-05 07:01:14.748000-0400
	 ↳ Elapsed Time: 4:43:37.691063 - likely offline 💤
	Last Reported Event Time: 2021-03-14 16:57:31.703000-0400
	Last External IP: 87.92.3.14
	Last Internal IP: 192.168.1.116
	Last Location: OFFSITE
	Last Logged In User: fredLaptop\fred
	Sensor status: REGISTERED
	Sensor Version: 3.6.0.1979

General Live Response Commands

Live response commands that don't fall into either the collection or remediation category.

Put File

Just put a file on a device.

$ cbinterface lr "theHostgoesHere" put -h
usage: cbinterface live-response name_or_id put [-h]
                                                       local_filepath
                                                       sensor_write_filepath

positional arguments:
  local_filepath        Path to the file.
  sensor_write_filepath
                        Path to write the file on the sensor.

optional arguments:
  -h, --help            show this help message and exit

Execute

Simple command executions on sensors/devices. Check Carbon Black documentation for a detailed explanation of their implementation. For complex tasks, on windows, a batch file is often helpful.

cbinterface lr hostNameGoesHere -e 'command goes here'

Live Response Sessions

You can use the sessions command to interface directly with CbLR server sessions. This is less handy for the PSC as they didn't implement as much functionality as they did for Response, however, it's still useful.

See direct session commands below and notice this is where you can close a problematic session:

$ cbinterface session -h
usage: cbinterface session [-h] [-lss LIST_SENSOR_SESSIONS]
                           [-gsc GET_SESSION_COMMAND_LIST] [-a]
                           [-g GET_SESSION] [-c CLOSE_SESSION]
                           [-gcr GET_COMMAND_RESULT] [-f GET_FILE_CONTENT]

optional arguments:
  -h, --help            show this help message and exit
  -lss LIST_SENSOR_SESSIONS, --list-sensor-sessions LIST_SENSOR_SESSIONS
                        list all CbLR sessions associated to this sensor ID
                        (Response only).
  -gsc GET_SESSION_COMMAND_LIST, --get-session-command-list GET_SESSION_COMMAND_LIST
                        list commands associated to this session
  -a, --list-all-sessions
                        list all CbLR sessions (Response only).
  -g GET_SESSION, --get-session GET_SESSION
                        get live response session by id.
  -c CLOSE_SESSION, --close-session CLOSE_SESSION
                        close live response session by id.
  -gcr GET_COMMAND_RESULT, --get-command-result GET_COMMAND_RESULT
                        get any results for this command.
  -f GET_FILE_CONTENT, --get-file-content GET_FILE_CONTENT
                        byte stream any file content to stdout. (use a pipe)

Note, this session interface could be moved under the live-response command parser, but, it differs from everything in the live-response command section as it doesn't require LR session establishment (and doesn't work with a sensor/device).

Close a Live Response Session

You can use the following command to force close a problematic live response session:

cbinterface session -c 'session id here'