Script parameters

Apart from the Lua script that provides the implementation of a scriptable protocol, there are a number of parameters that are configurable via different means. These parameters affect diverse aspects of a scriptable protocol such as which protocol it extends and which Guardian versions it is applicable to. Scriptable protocol parameters can be configured in two ways:

  1. JavaScript Object Notation (JSON) object at the end of the conf.user configure probe scriptable-protocol configuration line
  2. Special Lua comments (--nn-) embedded within the Lua script

Configuration line

After the mandatory <protocol_name> and <script_name> arguments in the probe scriptable-protocol configuration line, a JSON object may optionally be provided. This object shall hold the keys / values for all the parameters that need to be configured. For example, if a scriptable protocol is to be allowed to be executed concurrently, then the multithreaded parameter needs to be set to true:

conf.user configure probe scriptable-protocol fast_protocol script.lua { "multithreaded": true }

Embedded as script comments

When a scriptable protocol is not to be loaded via explicit configuration, but as custom user contents (i.e. by storing as .content file in /data/contents/scriptable_protocols), all parameters are provided as special Lua comments at the top of the file. These comments have the --nn- prefix followed by the parameter key and value, separated by the colon (:) character. Using the same example as above, if a scriptable protocol is to be allowed to be executed concurrently, then the multithreaded parameter shall be set to true by adding as comment in the script file the line:

--nn- multithreaded: true

Note that when a scriptable protocol is loaded via an explicit configuration line, then the parameters provided as comments within the file are ignored: only those explicitly provided in the configuration line (as JSON object) are going to be used.

Supported parameters

Name (name)

The name parameter provides the string which is going to used for identifying the scriptable protocol within the system. If the scriptable protocol is a standalone one, then the Protocol identifier (ID) shall consist of the name string only. If the protocol is an extension, then the Protocol ID shall be created by combining the name and extends_protocol parameters.

The name parameter must be provided (as a script comment) when the scriptable protocol is to be loaded as custom user content.

Example:

--nn- name: some_scada_prot

Extends protocol (extends_protocol)

The extends_protocol parameter provides the name of the standalone protocol to be extended, effectively marking the scriptable protocol as an extension. In such a scenario, the scriptable protocol shall be identified in the system by concatenating the extends_protocol and name parameters, using the hash (#) as separator.

For example, if the scriptable protocol is an hypertext transfer protocol (HTTP) extension that e.g. detects invalid tokens then the following script comments could be set:

--nn- name: invalid_token_detector
--nn- extends_protocol: http

If this scriptable protocol is to be explicitly configured, then the following configuration line should be used:

conf.user configure probe scriptable-protocol invalid_token_detector script.lua { "extends_protocol": "http" }

Multithreaded (multithreaded)

The multithreaded parameter dictates whether the scriptable protocol should be allowed to be executed concurrently. If set to true, then the script will be instantiated multiple times and each packet processing thread shall always use one of them. In such a scenario, there is no shared Lua state between the different instances and thus persistent variables written by one instance will not have their values visible by other instances.

The default value for this parameter is false

Examples:

--nn- multithreaded: true
conf.user configure probe scriptable-protocol prot_name script.lua { "multithreaded": true }

N2OS Version (n2os_version)

The n2os_version parameter allow scriptable protocols to be conditionally loaded, based on the version of the currently running intrusion detection system (IDS). This is useful when the same script is to be distributed to Guardians on different software levels and the script is applicable only to some of them.

The value of this parameter consists of comma separated version specifiers. Each version specifier consists of an operator and a version literal. For example. the version specifier >= 20.0.0 would be satisfied by all versions that are greater or equal to 20.0.0. If multiple version specifiers are provided, then they must be all satisfied for the scriptable protocol to be loaded. For example, if the n2os_version parameter is set to >= 20.0.0, != 21.0.0, then the scriptable protocol would be loaded for versions 20.0.0 and 22.0.0, but not for 19.0.0 or 21.0.0.

The operators that are supported are:

  1. ==: Equal
  2. !=: Not equal
  3. >: Greater
  4. >=: Greater or equal
  5. <=: Less or equal
  6. <: Less

For example, if this scriptable protocol is to be loaded for versions that are greater or equal to 20.0.0, but not equal to 21.0.0, then the following comment should be added to the script:

--nn- n2os_version: >= 20.0.0, != 21.0.0

If the configuration is to be explicit, then the following JSON object should be provided:

conf.user configure probe scriptable-protocol prot_name script.lua { "n2os_version": ">= 20.0.0, != 21.0.0" }

This parameter can be provided multiple times, if there are multiple disjoint version sets that could be satisfied. In such a case, the scriptable protocol will be loaded if any of the provided parameter values is satisfied.

For example, if a scriptable protocol should be loaded on any version belonging to the releases with major version 20 or 22, then the following comments should be set in the script:

--nn- n2os_version: >= 20.0.0, < 21.0.0
--nn- n2os_version: >= 22.0.0, < 23.0.0

If the script is going to be loaded via explicit configuration line, then the following JSON object should be provided:

conf.user configure probe scriptable-protocol prot_name script.lua { "n2os_version": [">= 20.0.0, < 21.0.0", ">= 22.0.0, < 23.0.0"] }