This is an older version of Search Guard. Switch to Latest version
Scripting in Signals
Scripts are used in many parts of Signals. Examples are conditions, transformations, severity mappings. These scripts are typically implemented using the Painless language. Mustache templates which are used for generating text content, for example in e-mail actions, are technically speaking also scripts and share the same runtime environment.
Stored scripts are not supported by Signals because the owner semantics of stored scripts don’t integrate well with the owner semantics of Signals watches.
Supported Scripting Languages
Elasticsearch comes out of the box with support for the scripting languages Painless and Mustache. You can get support for more scripting languages using Elasticsearch plugins.
In many cases, Signals allows using the
lang attribute to choose the language to be used. Examples are conditions and transformations. In some cases, however, changing the language is not supported. This includes text templates in actions such as email or slack.
All scripts share the same runtime environment. However, some attributes in these environments might be only available in certain situations or features.
To have a look at the actual attribute values during the execution of a watch, you can use the Execute Watch REST API with
show_all_runtime_attributes set to
data attribute is available in all scripts. Its structure is freely definable by the checks of a watch.
Checks defined inside an action can also modify this attribute. These modifications are however scoped to the single action. They won’t become visible to other actions.
watch attribute contains some meta data about the watch which is currently executing. It has these attributes:
watch.id: The id of the currently executing watch. This does not include the tenant name.
watch.tenant: The name of the tenant the watch belongs to.
Availability: anywhere, exempt are watches executed via the REST API
trigger attribute contains information about the trigger schedule of the watch. It is thus only available if the watch was triggered via its schedule.
The information in the
trigger attribute is particularly useful for defining time windows for queries. For the time windows, the attributes
previous_scheduled_time should be preferred over
triggered_time, as these allow the definition of precise, non-overlapping time windows.
The attributes of the
trigger attribute in detail:
trigger.scheduled_time: The time the watch was scheduled to be triggered at. Type: JodaCompatibleZonedDateTime
trigger.triggered_time: The time the watch was actually triggered. This will be slightly after
scheduled_time. The difference might get larger if there are lots of long running watches for a tenant, which cause congestion in the thread pool. Type: JodaCompatibleZonedDateTime
trigger.previous_scheduled_time: The time the watch was scheduled to run before this run. Type: JodaCompatibleZonedDateTime
trigger.next_scheduled_time: The time the watch is scheduled to run at after this run. Type: JodaCompatibleZonedDateTime
Availability: In actions when a watch uses a severity mapping.
severity attribute contains information about the current severity level of a watch. It is therefore only available after the severity level has been determined, i.e., only in actions and in the checks defined in these actions.
It has these attributes:
severity.level.id: The ID of the severity level. One of
severity.level.level: An ordinal number identifying the severity level. The level
none corresponds to
0, the level
severity.level.name: A human-readable name of the severity level.
severity.value: The value determined by the
value expression configured in the severity mapping. This is always a number.
severity.threshold: The threshold that was passed by
value so that the current severity level was reached.
The time the watch started executing. This is similar to
execution_time is also set when watches are executed via API.
Availability: Inside resolve actions
resolved attribute is only available for resolve actions. It contains a snapshot of all the runtime data of the time when the watch entered the severity level which is not being resolved.
It has these attributes:
resolved.data: A snapshot of the
data attribute at the time the watch entered the resolved severity level. See data for details.
resolved.trigger: The trigger times when the watch entered the severity level which is now resolved. See trigger for details.
resolved.severity: A snapshot of the
severity attribute at the time the watch entered the severity level which is now resolved. See severity for details.
Availability: Only inside actions with the
This is only relevant for the
foreach functionality of actions, which allows the execution of the action for all the elements of a collection. In this case, the
item attribute will be set to the element of the collection the action is executed for right now.
data attribute, checks defined inside the action can modify this attribute. These modifications are however scoped to the single action. They won’t become visible to other actions.