Command processor

Command processor

Introduction

The following daemon components have an embedded command processor to let users use toolbox features:

• DNS server
• Mail server
• Serial port communicator
• Telnet server
• Telegram chat-bot
• Web service invoke toolbox features in a form
• Web service Twilio telephone/SMS hook
• Web service Microsoft bot hook

To use toolbox feature via a daemon, the following events take place:

1. Input a command. For example, HTML form submission collected via web server, and mail content including a command reaches to mail server.
2. Filter command through PINAndShortcuts mechanism - match access password (PIN) and translate shortcut entries.
3. Filter it further through TranslateSequences mechanism - replace sequence of characters by another sequence.
4. Execute toolbox feature identified by the prefix name, and give the parameters to the toolbox feature as context. Once done, the result is presented in an easy-to-read text.
5. Filter the result through LintText mechanism - compact and clean result text when necessary.
6. If result is empty, inform user by replacing it to EMPTY OUTPUT.
7. Notify user the command input and result via Email

Configuration

Construct the following objects under JSON key (e.g. HTTPFilters, MailFilters) named by individual daemon - you may find them in daemon's usage manual.

Mandatory PINAndShortcuts - define access password and shortcut command entries:

Property	Type	Meaning
PIN	string	Access to toolbox is granted only after this strong password PIN is matched at the beginning of command input. See "Usage" for more information.
Shortcuts	{"shortcut1":"command1"...}	Without requiring PIN input, these shortcuts are directly translated into the commands and executed.

Optional TranslateSequences - translate sequence of command characters to a different sequence:

Property	Type	Meaning
Sequences	[["seq1", "replacement1"]...]	One after another, character sequences from input command are replaced by the replacements.

Mandatory LintText - compact and clean command result:

Property	Type	Meaning
CompressSpaces	true/false	Compress consecutive space characters into a single space character.
CompressToSingleLine	true/false	Connect all lines by semi-colon(;) character
KeepVisible7BitCharOnly	true/false	Only keep Latin letters/digits/symbols and discard letters from other languages.
TrimSpaces	true/false	Remove leading and trailing space characters.
MaxLength	integer	Only keep this many characters in the result, discard the remaining ones.

Optional NotifyViaEmail - send notification Email for the command input and result:

Property	Type	Meaning
Recipients	array of strings	Email addresses that will receive the notification.

To enable Email notification, please also follow outgoing mail configuration to construct configuration for sending Email responses.

Configuration example

Here is an example configuration for web server, used by both HTML toolbox form and Twilio telephone/SMS hook:

{
    ...

    "HTTPFilters": {
        "PINAndShortcuts": {
            "PIN": "VerySecretPassword",
            "Shortcuts": {
                "watsup": ".eruntime",
                "EmergencyStop": ".estop",
                "EmergencyLock": ".elock"
            }
        },
        "TranslateSequences": {
            "Sequences": [
                ["#/", "|"]
            ]
        },
        "LintText": {
            "CompressSpaces": true,
            "CompressToSingleLine": true,
            "KeepVisible7BitCharOnly": true,
            "MaxLength": 160,
            "TrimSpaces": true
        },
        "NotifyViaEmail": {
            "Recipients": ["me@example.com", "me2@hotmail.com"]
        }
    },

    ...
}

In the example:

• For SMS, LintText compacts result and limits length to 160 characters.
• PINAndShortcuts has a strong password and three shortcut commands.
• Some dumb phones cannot enter | pipe character in SMS, TranslateSequences helps them to enter the character via #/ instead.

Usage

A command issued to toolbox feature looks like this:

PIN .feature_prefix parameter1 parameter2 parameter3 ...

Where:

• .feature_prefix tells which toolbox feature is to be executed. Pay attention to the leading . dot.
• parameters are passed on to the feature for execution.

The following prefixes are accepted, see individual feature manual for their usage:

• .2 - Two factor authentication code generator
• .a - Find text in AES-encrypted files
• .c - Contact information of public institutions
• .bp - Interactive web browser (PhantomJS)
• .bs - Interactive web browser (SlimerJS)
• .e - Inspect system and program environment
• .g - Text search
• .i - Read Emails
• .j - Wild joke
• .m - Send Emails
• .p - Call friends and send texts
• .r - RSS reader
• .s - Run system commands
• .t - Read and post tweets
• .w - WolframAlpha

The special "PLT" command

"PLT" is a special command prepended to an ordinary command, in order to seek to position among result output, and temporarily modify max length and timeout restriction. The usage is:

PIN .plt <SKIP> <MAX LENGTH> <TIMEOUT SECONDS> .feature_prefix parameter1 parameter 2 parameter 3 ...

Where:

• <SKIP> is the number of characters to discard from beginning of the result output.
• <MAX LENGTH> is the number of characters to respond. It overrides MaxLength of LintText.
• <TIMEOUT SECONDS> is the number of seconds toolbox feature may run without being aborted. It overrides usual timeout limit configured in daemon.

Take an example - command MY_TOOLBOX_PIN .il work-mail 0 10(list 10 Email subjects) is issued to Telegram bot that gives it 30 seconds to run and restricts output to 76 characters, resulting in the following response:

1 me@example.com Project roadmap
2 me@example.com Holiday greetings
3

Due to combination of MaxLength restriction and possible timeout condition, we did not see the remaining 7 Email subjects. Let us try PLT to retrieve the full output - skip the 2 Emails we have already seen, override MaxLength to 10000 and timeout to 60 seconds:

.plt 75 10000 60 MY_TOOLBOX_PIN .il work-mail 0 10

And we will get the desirable result:

3 me@example.com Test subject 3
4 me@example.com Test subject 4
5 me@example.com Test subject 5
6 me@example.com Test subject 6
7 me@example.com Test subject 7
8 me@example.com Test subject 8
9 me@example.com Test subject 9
10 me@example.com Test subject 10

Tips

Regarding password PIN:

• It must be at least 7 characters long.
• Do not use space character in the password; otherwise the space characters will cause most features to misbehave.
• Use a strong password to protect access to toolbox features.
• Every daemon that has a command processor also has a rate limit mechanism (e.g. PerIPLimit configuration), avoid setting rate limit too high or password may be prone to brute-force attack.
• Incorrect password entry does not result in an Email notification, however, the attempts are logged in warnings and can be inspected via environment inspection or program health report.

Regarding toolbox usage via SMS/telephone:

• Telephone and mobile networks are prone to attacks, they can eavesdrop your password PIN and toolbox feature conversations easily. Use them only as a last resort.
• The Twilio SMS/telephone hook runs in the web server daemon, therefore the corresponding command processor configuration is in JSON key HTTPFilters. Check out the feature's manual for techniques of command entry via telephone number pad.
• To avoid a high SMS bill, consider turning on all LintText flags to compact SMS replies, and restrict MaxLength to 160 - maximum length of a single SMS text.
• Some mobile phones using pre-2007 design cannot input the pipe character | that is commonly used in system commands. To work around the issue, configure a TranslateSequences such as ["#/", "|"].

Regarding mail notification and logging: the input of 2FA code generator and AES-encrypted content search are concealed from all mail notifications and log messages in order to protect their encryption key. However their command output will still appear as-is.