Scripting API

Beta feature: It is planned that the APIs described here will become stable and permanent features in the product. Siren will take a best effort approach to fix any issues, but the APIs are not subject to the support SLA of official GA features. Caution should be exercised in their use, as there might be breaking changes to these APIs in a future version.

The Siren scripting API is a set of classes that enable scripting in Siren Investigate.

The scripts are written in Javascript and they are executed by the Web browser when a dashboard or visualization is opened.

The scripts, like the other objects in the application, are stored in the Elasticsearch .siren index.

The following diagram shows the scripting architecture:

image

The following types of script are used by the Graph Browser visualization:

  • contextual

  • expansion

  • lens

  • onGraphUpdate

  • sampling

The watcher script type is used in Alerting.

This section is about the sirenAPI script type, which can be used on other dashboards or visualizations.

Creating scripts

Steps

  1. In Siren Investigate, go to the Management app and click Scripts.

  2. Click New.

  3. In the Type field, select sirenapi.

  4. Complete the Title, Description, and Source fields and click Save.

image

Supported API versions

Currently, only version 1 is supported. Your script must contain the API version constant declaration as its first line.

const version = 1;

If your script does not contain the version declaration or it contains an unsupported version declaration, a warning is displayed.

image

Future versions of Siren API will be backwards compatibile; this means that a script that is written for version 1 will work with Siren API version 2 when it is released.

Using variables

To simplify script writing, the following special variables are available in the script execution context:

  • When a script is applied to a visualization, use the parameter currentVisualization to represent the visualization that the script is applied to.

  • When a script is applied to a dashboard, use the parameter currentDashboard to represent the dashboard that the script is applied to.

Applying scripts to visualizations

Scripts can be applied to any dashboard or visualization independently.

Prerequisites

Before you begin, ensure that you have saved at least one dashboard or visualization.

Steps

  1. In Siren Investigate, go to the Management app and click Saved Objects.

  2. Select the dashboard or visualization object that you want to edit.

  3. On the Edit visualization or Edit dashboard screen, specify a script in the scriptIds field and click Save.

image

After the script is applied, the script will execute every time the dashboard or visualization is opened.

If a script is applied to two objects on the same dashboard, it will be executed twice.

Applying security restrictions

For security reasons, it is recommended that an administrator restricts access to the system scripts.

Access to the scripts can be restricted in the following ways:

  • You can completely disable or enable all scripting functionality for all users. To do this, change the following flag in the investigate.yml file:

siren_scripting:
  enabled: false
  • You can disable or enable all scripts for all users in the UI by setting the siren:scripting:enabled variable to 'false' in Advanced Settings. This method does not require an instance restart.

image

  • You can disable or enable all scripts for a single group of users by revoking read access to sirenapi script objects in the ACL Roles panel. The following screenshot shows that access is blocked to all sirenapi scripts for the group called sirenuser.

image

  • You can disable or enable access to a single script for a single group of users by revoking read access to a particular sirenapi script object in the Saved Objects panel. The following screenshots show that access is blocked to a sirenapi script called My sirenapi script for the group called sirenuser.

image image

Enabling additional APIs

By default, scripts are executed in a new context with no access to browser APIs. To enable a specific API, add it to the browserApiWhitelist property in the investigate.yml configuration file.

For example, you can specify a list of APIs as follows:

siren_scripting:
  enabled: true
  browserApiWhitelist:
    - 'Math'
    - 'setTimeout'
    - 'setInterval'
    - 'document.getElementById'
    - 'document.getElementsByClassName'

In addition to all of the APIs that are available in the browser, you can also expose libraries to the script context. Two libraries are currently supported: Moment and Lodash. To enable a library, add it to the librariesWhitelist property in the investigate.yml configuration file.

For example, specify the libraries as follows:

siren_scripting:
  enabled: true
  librariesWhitelist:
    - 'lodash'
    - 'moment'

Error handling

As scripts can execute arbitrary code it is very important to handle errors correctly.

In general, error that are thrown inside the script should propagate up and be caught and handled by a script manager. However, in certain situations, this will not happen. For example:

click handlers

When using an html element with handler functions:

const button = currentVisualization.getHtmlButtonElement('Find', onClick);

If an error is thrown by the onClick handler, Siren’s scripting API catches it and shows a warning message on top of the script. If you do not want this to happen, you must manage the errors yourself.

Unreturned promises

Errors might not be caught if a script is not returning the main promise.

Many APIs return arrays

To avoid out-of-bounds errors, check the returned array length before trying to assign from the array.