Endpoint Agent Commands

Endpoint Agent commands offer a safe way to interact with a Sensor's host either for investigation, management, or threat mitigation purposes.

Sending Commands

Commands can be sent to Sensors via:

• Manually using the Console of a sensor in the web application.

• Manually using the CLI

• Programmatically in the response action of a Detection & Response rule, via the task action.

• Programmatically using the REST API

Structure

Commands follow typical CLI conventions using a mix of positional arguments and named optional arguments.

Here's dir_list as an example:

dir_list [-h] [-d DEPTH] rootDir fileExp

positional arguments:
    rootDir     the root directory where to begin the listing from
    fileExp     a file name expression supporting basic wildcards like * and ?

optional arguments:
    -h, --help      show this help message and exit
    -d DEPTH, --depth DEPTH     optional maximum depth of the listing, defaults to a single level

The Console in the web application will provide autocompletion hints of possible commands for a sensor and their parameters. For API users, commands and their usage details may be retrieved via the /tasks and /task REST API endpoints.

Investigation IDs

To assist in finding the responses more easily, you may specify an arbitrary investigation_id string with a command. The response will then include that value under routing/investigation_id. Under the hood, this is exactly how the Console view in the web application works.

If an investigation_id is prefixed with __ (double underscore) it will omit the resulting events from being forwarded to Outputs. This is primarily to allow Services to interact with sensors without spamming.

Command Line Format

When issuing commands to sensors as a command line (versus a list of tokens), the quoting and escaping of arguments can be confusing. This is a short explanation:

The command line tasks are parsed as if they were issued to a shell like sh or cmd.exe with a few tweaks to make it easier and more intuitive to use.

Arguments are parsed as separated by spaces, like: dir_list /home/user * is equal to 2 arguments: /home/user and *.

If an argument contains spaces, for example a single directory like /file/my files, you must use either single (') or double (") quotes around the argument, like: dir_list "/files/my files".

A backslash (\), like in Windows file paths does not need to be escaped. It is only interpreted as an escape character when it is followed by a single or double quote.

The difference between single quotes and double quotes is that double quotes support escaping characters within using \, while single quotes never interpret \ as an escape character. For example:

• log_get --file "c:\temp\my dir\" --type json becomes log_get, --file, c:\temp\my dir\, --type, json

• log_get --file 'c:\temp\my dir\' --type json becomes log_get, --file, c:\temp\my dir\, --type, json

• log_get --file 'c:\temp\my dir\' --type json becomes log_get, --file, c:\temp\my dir\, --type, json

• log_get --file "c:\temp\my dir\" --type json becomes log_get, --file, c:\temp\my dir\, --type, json

This means that as a general statement, unless you want to embed quoted strings within specific arguments, it is easier to use single quotes around arguments and not worry about escaping \.