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.
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.
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.ymlfile: 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:enabledsetting. The default value for this setting is
false. You can enable all user scripts for a particular dataspace by setting the
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.
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.