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, like the other objects in the application, are stored in the Elasticsearch
The following diagram shows the scripting architecture:
The following types of script are used by the Graph Browser visualization:
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.
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.
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.
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.
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.
|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
siren_scripting: enabled: false
You can disable or enable all scripts for all users in the UI by setting the
siren:scripting:enabledvariable to 'false' in Advanced Settings. This method does not require an instance restart.
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 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.
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 and jQuery.
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'
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.
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:
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.