MENU
    Endpoint Agent Commands
    • 01 Nov 2024
    • 3 Minutes to read
    • Contributors

    Endpoint Agent Commands


    Article summary

    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:

    Sensor REPort/REPly Events

    Regardless of which you choose, sent commands will be acknowledged immediately with an empty response, followed by a CLOUD_NOTIFICATION event being sent by the sensor. The content of command outputs are delivered as sensor events suffixed with _REP, depending on the command.

    Please ensure that you have enabled the appropriate response event(s) in Event Collection to ensure that you will receive the Sensor response.

    This non-blocking approach makes responses accessible via the event streams passing through Detection & Response rules and Outputs.

    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
    Plain text

    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 \.


    Was this article helpful?