Command Line Engines

With command engines administrators can run engines to integrate arbitrary shell commands.

When creating and enabling a command engine on a public instance, you must be careful to avoid leaking private data. The easiest solution is to limit the access by setting tokens as described in section Private Engines (tokens).

The engine base is flexible. Only your imagination can limit the power of this engine (and maybe security concerns). The following options are available:

command:

A comma separated list of the elements of the command. A special token {{QUERY}} tells where to put the search terms of the user. Example:

['ls', '-l', '-h', '{{QUERY}}']
delimiter:

A mapping containing a delimiter char and the titles of each element in keys.

parse_regex:

A dict containing the regular expressions for each result key.

query_type:

The expected type of user search terms. Possible values: path and enum.

path:

Checks if the user provided path is inside the working directory. If not, the query is not executed.

enum:

Is a list of allowed search terms. If the user submits something which is not included in the list, the query returns an error.

query_enum:

A list containing allowed search terms if query_type is set to enum.

working_dir:

The directory where the command has to be executed. Default: ./

result_separator:

The character that separates results. Default: \n

The example engine below can be used to find files with a specific name in the configured working directory:

- name: find
  engine: command
  command: ['find', '.', '-name', '{{QUERY}}']
  query_type: path
  shortcut: fnd
  delimiter:
      chars: ' '
      keys: ['line']

Acknowledgment

This development was sponsored by Search and Discovery Fund of NLnet Foundation.