Advanced Keystroke Action Policy

Policies for Advanced Keystroke Action are different from normal Endpoint Privilege Management for Unix and Linux policies because they have a different function to fulfill. The policy is defined as a JSON object split into a number of separate sections including variables, prerun, complete actions, macros, readonly, and policy. The primary section of the policy is an ordered list of match and action nodes. These match the command line, or other variable, and perform specified actions if the match is successful.

Preamble

The preamble defines the name of the configuration and whether debug can be enabled.

set akadebug 10

{
   "name": "demo",
   "cfg": {
      "debug_enabled": true,
         ….
}

Variables

The variables section allows the configuration of variables that can be used within the policy. These variables, by default are read/write within the policy but may be defined as readonly in the readonly section. All JSON data types are supported, including booleans (true/false), strings, integers, floating point numbers (reals), and arrays of datatypes using the JSON format. These can then be referred to by name using a notation similar to bash. For example, ${varname}" or "${arrayelement[2]}. Some of the variables are special in that they can only hold specific values. For example, editor can only be emacs or vi, and keymap can only hold specific definitions of keys (similar to the NetBSD libedit or GNU readline names.

The variable input is the current command line, and if it is rewritten it will change the command line. If it is set to null, it removes the current input and returns the user to the command line.

"variables": {
   "editor": "emacs",  "prompt": "$ ",  "ro_var": "this variable is readonly",  "remote_prompt":
      "##prompt##:",
   "keymap": [{ "key": "^I",  "value": "ed-complete" }
   ]
},

Key definitions by default are listed below.

In vi input mode, input characters are bound to the following editor commands by default:

All other input characters except the NUL character (Ctrl-@) are bound to ed-insert.

In vi command mode, input characters are bound to the following editor commands by default:

In emacs mode, input characters are bound to the following editor commands by default:

The prompt variable is the prompt that the user will see to type at. The remote_prompt is important in that AKA attempts to wait for the remote prompt before letting the user type at the command line. This should make interaction clearer and more intuitive without mixing input and output characters in the input/output terminal data stream.

Other special variables are:

• runuser: The remote run user
• runhost: The fully qualified domain name of the the remote run host
• runhostname: The simple hostname of the remote run host
• runcmd: The command line passed to pbssh
• argv: The command line array passwd to pbssh
• prompt_wait: The maximum time to wait for remote command to run (in milliseconds)
• history: The number of command line history entries to save for the next session
• input: The submitted command line
• prerun_prompt_wait: The maximum time to wait for remote command to run when executing the pre-run as the user session starts (in milliseconds)
• prerun_slowdown: The delay time added to each prerun command to slow down the prerun (in milliseconds)
• remote_prompt: The remote prompt, used by Advanced Keystroke Action profiles to synchronize the terminal session input and output sequences
• akadebug: Built-in debugging to allow the policy writer to diagnose issues in policy
• pkcert: The value of the pk_cert passed into the Advanced Keystroke Action service
• pkserver: The value of the pk_server passed into the Advanced Keystroke Action service
• pkdomain: The value of the pk_domanit passed into the Advanced Keystroke Action service

For more information, see the NetBSD editline(7) man page.

Prerun

The prerun section is an array of string commands that are submitted to the remote system before any user commands can be submitted. It is recommended, if possible, to define prompts, etc, so they can be waited for using remote_prompt variable. The strings are submitted one after another with a short delay, but with not intelligent processing. If processing is required is recommended that normal policy is used.

"prerun": [   "PS1=##prompt##:",   "unset PROMPT_COMMAND"  ],

Filter

The filter section is an array of strings that are filtered from the session output and are therefore not displayed on the client terminal session.

"filter": [   "Filtered string one",   "Filtered string two"  ],

Login_sequence

The login sequence object details what happens with a successful or unsuccessful login. It details whether the user is allowed any input during the login phase, the successful/unsuccessful messages and strings that are matched to determine whether it was successful:

"login_sequence" : {
   "input_allowed" : true,
   "successful" : "*** Login sequence successful ***",
   "denied" : "*** Failed login sequence – access denied ***",
   "prematch" : [
       {"Last login: " : true },
       {"Access denied" : false }
   ]
},

Completion

Completion is a list of strings that can be used to complete command lines (usually when the ed-complete key is submitted). If more than one string can complete the command, the list will be provided. If only one matches, the current command line is rewritten to the completion string. There are two types of completion value. A line completion, where the who line will be compared up to the cursor, and word completion that simply checks the previous word.

"complete": [  {""value": "compabcd",   "type" : "line" },{"value" : "compadef", "type" : "line"},{"value": "compxyz","type" : "word" } ],

Macros

Macros are an ordered list of regular expression patterns and rewrite strings. It is used to simply rewrite the current command line if patterns match when return is pressed. This should simplify the majority of policy that are simple rewrites.

"macros": [
   { "pattern": "macroa(b)(c)d", "value": "echo macro rewrites to ${1} ${2}" }
],

When the user types macroabcd, it rewrites the command line to echo macro rewrites to b c, and it executes the command on the remote system.

Readonly

The readonly section is a simple list of variables that are readonly and cannot be rewritten. This is useful for constant strings or messages.

"readonly": {
   "ro_var": true
},

Policy

The policy section is an ordered list of matching conditions and actions that are taken if the match is positive. Matching is processed against variables or user input, and can be any normal operation, including regular expressions. Actions can be:

• Accept: Immediately accept the current command line and submit the command line to the remote host to execute.
• Reject: Immediately reject the current command line, optionally displaying a message.
• Restart: Restart processing the policy list from the beginning.
• Readonly: Mark the specified variable readonly for the rest of the session.
• Disable: Execute the current command line, but disable command line processing until either the specified string is matched in the output, or the remote prompt is once again displayed. This allows interactive sessions to be authorized.
• Unset: Unset the specified variable.
• Printf: Display the specified message to the users terminal session, processing specified arguments to make up the message.
• Sendf: Send the specified message to the remote application as if typed, processing specified arguments to make up the input.
• Set: Set the specified variable to a constant or calculated value. Constant values can include any data type, or can reference another variable. Calculated values can be integer or floating point math, shift or logic values, substrings, substituted strings, upper/lower case strings, split or sprint strings. Arguments can be constants or specified variable values, or the arguments matched from the regular expression match.
  • Operators on integers include add(+), subtract (-), divide (/), multiply (*), logical AND (&&), bitwise AND (&), logical OR (||), bitwise OR (|), NOT (!), shift left (<<), shift right (>>), modulo divide (%).
  • Operators on floating point include add(+), subtract (-), divide (/), multiply (*).
  • Operators on strings include concatenation (+), substitute (sub), substring (substr), uppercase (upper), lowercase (lower), split/tokensize string (split) and sprintf to format a string with arguments.
  • Operators on arrays include append/extend (+), remove (-) and index set (=).

The match node consists of a singular expression match, or an array of called and or or which are evaluated to a logical AND or OR of the constituent singular expression matches.

"match": { "op": "=",  "${var}": "var1", "value": 123 }

"match": { "and" = [
   {"op": "=",  "var": "${var1}", "value": 123 },
   { "op": "=",  "var": "${var2}", "value": 678}
   ]}

"match": { "or" = [
   {"op": "=",  "var": "${var1}", "value": 123 },
   { "op": "=",  "var": "${var2}", "value": 678}
   ]}

A Simple Example of Policy

"policy": [
{
   "match": {
   "op": "=~",
   "var": "${input}",
   "value": "PS1=.*"
},
   "actions": [
   {
       "action": "reject",
       "value": "sorry, you cannot reset the prompt"
       }
   ]
}, ….

For more examples, see the demo policy in the default Advanced Keystroke Action database.