Custom checks (SD Scripts)

The SD Scripts engine gives the user the freedom to create own detection profiles using the monitoring capabilities of eyeInspect. The user defines the checks in an SD Script using the Lua scripting language. An SD Script has access to the network information at several points in the network processing flow.

An SD Script can subscribe to "Event callbacks" to perform its own kind of checks. For example, "Event callbacks" include events for: individual packets, connection events and application-layer protocol events. Depending on the type of "Event callback", the SD Script receives different information such as the MAC and IP addresses of the hosts involved, the application layer message type being sent, the application layer parameter values and much more.

An SD Script can subscribe to different event callbacks and perform its own type of checks.

Application layer checks - An application layer check relies on the eyeInspect protocol parser to process the network traffic. The SD Script can then access the information by implementing the relevant event callbacks. Protocol-specific events can be used to perform checks on the value of a protocol parameter, for example, to verify that for every protocol message A the value of parameter X is not bigger than Y. Currently SD Scripts can provide the message type of monitored message for all parsed protocols via the new l7 pdu event callback. In addition, SD Scripts support specific callbacks for events of the following protocols:
  • BACnet
  • DELTAV IO
  • DNP3
  • EtherNet/IP
  • ExperionCDA
  • HTTP
  • IEC10X (IEC101 and IEC104)
  • LDAP
  • MMS
  • Modbus
  • ROC

In-depth event callbacks for more protocols will be added in future eyeInspect releases.

Network checks - Checks at the network level typically use packet and connection events. For example, to record the observed MAC addresses on the network. The generated list of MAC addresses can be used as basis for whitelisting and detecting new/unknown MAC addresses. Network checks can be combined with application layer checks to create powerful custom detection logic. Consider that the value (opened/closed) of a cabinet door is sent over the network using a protocol such as DNP3. An SD Script can be written that detects when the cabinet door has been opened and a new MAC address is observed on the network shortly after that.

Time-based checks - Using an SD Script it is possible to check for events over time or sequences of events. For example, an SD Script can record how often a specific message type occurs during a day. It is also possible to check whether a message A is followed by a message B within a specific time frame. Alternatively, an SD Script might count how many Alerts (of a given type) are fired in a day. An SD Script can combine checks for multiple events to create a powerful custom detection profile. The SD Script logic determines what happens when an event occurs. The SD Script can fire an Alert, send a message with Syslog, send a message with Apache Kafka or send an SNMP trap. The user can also choose to store a record of the information in the script's persistent data file for later use, as mentioned in the MAC address whitelisting example above or to write an entry to the script report or the script log. User operations on SD Scripts, such as starting, stopping and editing an SD Script are recorded in the User activity logs.

Select one or more SD scripts by selecting the checkbox(es) in the first column, to enable the action menu above the ITL table. You can pause/resume, export, clone/share and remove the SD scripts.

Add a new SD Script

To add a new SD script, click the + icon on the top-right corner above the SD scripts table.

When creating a new script, it must be given a unique name. There is an optional description field that can be used to give a more complete description of the script. The description of existing SD Scripts can be shown by hovering the mouse cursor over the profile name.

SD Scripts can be run in two different interpreter modes. Just like the name and description, the mode selection is stored in the script, and it is persistent when exporting and importing the script.
  • One Interpreter per Thread - This is the default mode for SD Scripts created in eyeInspect currently. It is tuned for optimized performance. In this mode, the global context is not accessible for SD Scripts.
  • Shared Interpreter - This was the default mode for SD Scripts created in eyeInspect earlier. It provides the global context, at the cost of script performance.

It is possible to change any of these settings by using the "Edit" button in the sub-menu. Before changing the interpreter mode of an existing SD Scripts to use one interpreter per thread, please verify that the script does not depend on the global context.

In addition, a unique identifier is assigned to each SD Script by the Sensor when it is added or imported.

View SD Script Details

Open a SD script by clicking the name to view the following SD script details tabs:

  • Status: The status tab shows the the ID of the SD Script as well as the name, description, the interpreter mode, the creation date and the last modification date. In addition it shows the current state of the SD Script.
  • Report: The behavior of the reporting is defined by the event callback get script report(). The get script report() event callback needs to return a string value. This string value is then shown in the "Report" tab.
  • Code: The "Code" tab is where the implementation of event callbacks are. The left side of the page shows the SD Script menu tree, while the right side shows the source code editor and API help panel (when expanded). A syntax validation by the sensor is available from the secondary nav bar option "Check Syntax". The results of this check will be displayed just above the script code field. Note that while editing the script source code, the SD Script is only saved in the browser’s session. Click "Finish" in the menu bar to save the script to the Sensor. Clicking "Reload" reloads the SD Script from the sensor and will overwrite any unsaved changes.
  • Logs: The "Logs" tab shows the log entries the SD Script generated. The user defines the log entry with the function log (log type: enum, message: string). For each log entry the log type, i.e., the severity of the logged information, can be defined as: Informational, Warning, Error and Critical Error. The API help browser offers more details. If no log entry is shown, but an entry is expected, click on "Refresh logs" in the local menu bar below the tabs to reload the logs.
    Note: When an SD Script is in "Error" state, the "Script logs" tab shows the run time error(s) that occurred.
  • Persistent data: The "Persistent data" tab shows the data that has been saved in persistent storage. This data will not be deleted when the SD Script execution is stopped, the script is edited or the Sensor is reset. For example, for MAC address whitelisting the encountered MAC addresses should be saved to persistent storage so that the whitelist is not lost when the script is edited. When the "One Interpreter per Thread" model is used, the "get script data" callback is disabled. It is not possible to have the script write persistent data in this model. All other operations on persistent data are identical between both thread models.

The following options are available in the secondary nav bar in the SD Script page:

Back

Navigate to the previous page.

Finish

Save the script to the sensor and navigate to the previous page.

Edit

Edit the SD script details.

Reload

Reload the SD scripts.

Check syntax

Validate the source code syntax.

Initialize custom roles

Inserts the custom host role initialization snippet into the code.