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 a visualization or the overview tab in the record view are opened.

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

The following diagram shows the scripting architecture:

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

expansion
lens
sampling

For alerting, you can create a watcher script. For more information, see Custom watchers.

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

Creating scripts

Steps

In Siren Investigate, go to the Management app and click Scripts.
Click New.
In the Type field, select custom.
Complete the Title, Description, and Source fields and click Save.

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 variable currentVisualization to represent the visualization that the script is applied to.
When a script is applied to a dashboard, use the variable 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

In Siren Investigate, go to the Management app and click Saved Objects.
Select the dashboard or visualization object that you want to edit.
On the Edit visualization or Edit dashboard screen, specify a script in the scriptIds field and click Save.

After the script is applied, the script will execute every time the dashboard or visualization is opened or when opening the overview tab in the record view.

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

Applying security restrictions

Only administrators have the ability to create and edit scripts. For security reasons, we recommend that an administrator restricts who can execute the scripts.

Scripts execution can be restricted in the following ways:

You can completely disable all scripting functionality for all users. To do this, change the following flag in the investigate.yml file: The default value for this setting is true. This setting change requires an Investigate process restart to take effect.

siren_scripting:
  enabled: false

When scripting is enabled in the yml file it also has to be enabled for each dataspace within the Advanced Settings siren:scripting:enabled setting. The default value for this setting is false. You can enable all user scripts for a particular dataspace by setting the siren:scripting:enabled variable to true. This setting change does not require an Investigate process restart to take effect.

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.

You can disable or enable execution of 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.

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. Currently, the following libraries are supported: Moment.js, Lodash, jQuery, EUI, and React. 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' // or '_'
    - 'jQuery' // or '$'
    - 'moment'
    - 'React'
    - 'EUI'
    - 'axios'

Allowing specific browser APIs or libraries might give script authors access to the application DOM or the ability to perform arbitrary HTTP calls. In some installations, this is a security threat. Administrators should always consider the security requirements when enabling additional APIs and libraries.

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.