Version: 7.x-36.0.0

This is a technical preview. Technical preview features are not fully supported, may not be functionally complete, and are not suitable for deployment in production. We encourage you to try them out and provide your feedback, good and bad, on the Search Guard forum. This will help us improve and add any features you might be missing.

Script Conditions

A script condition is a Painless script that has access to the complete execution runtime data and returns a boolean value.

If the script returns false, the execution flow is aborted. If it returns true, the execution flow continues.

As with other condition types, a script condition can be used to control the execution flow of a watch or an action.

If used in a watch, depending on the return value of the script, execution of the watch is either aborted or continued.

If used in an action, depending on the return value of the script, the action is either executed or skipped. A condition in one action does not affect execution of other actions.

A script can be defined as an line script or as a stored script. Inline scripts are added to the condition definition directly, while stored scripts are stored in Elasticsearch and referred to by their id.

Inline scripts

The following condition tests whether the total hits of a search, stored in the execution context under the name mysearch, is higher than zero:

{
  "type": "condition.script",
  "name": "mycondition",
  "source": "data.mysearch.hits.hits.length > 0"
}
Name Description
type condition.script, defines this conditions as script condition. Mandatory.
name name of this condition. Can be chosen freely. Mandatory.
source The script to execute. Mandatory
lang The scripting language to be used. Optional, defaults to painless. Other scripting languages may be provided by Elasticsearch plugins.

Stored scripts

To run a stored script, refer to it by using it’s id:

{
  "type": "condition.script",
  "name": "mycondition",
  "script_id": "mystoredscript"
}
Name Description
type condition.script, defines this conditions as script condition. Mandatory.
name name of this condition. Can be chosen freely. Mandatory.
script_id The ID of the stored script. Mandatory

Note: When using stored scripts, keep in mind that stored scripts are not subject to multi-tenancy or Signals permissions and may be thus changed independently of the watch. Thus, you should review whether the ability to edit scripts is adequately restricted.

Accessing the runtime data

All scripts have full access to the runtime data, gathered for example by Elasticsearch or HTTP inputs.

The runtime data is available via the data prefix.

For example, the following watch runs a query against the serverlogs index to find entries where the statuscode is 500. The target property of the input is configured to be http_error_500; thus the document read by the input is put under this property name into the runtime data. The script condition accesses the data by using the data.http_error_500 prefix and only continues if the total hits is above 10.

{ 
  "trigger":{},
  "checks":[
    {
        "type":"search",
        "name":"server_errors",
        "target":"http_error_500",
        "request":{
            "indices":[ "serverlogs" ],
            "body":{
               "query" : { "match" : { "statuscode" : "500" } }
            }
        }
    },
    {
        "type": "condition.script",
        "name": "error_500_threshold",
        "source": "return data.http_error_500.hits.total.value > 10"
    }
  ],
  "actions":[ ... ]
}

Using script conditions with actions

A script condition can also be used to control the execution of an action. Each action can define it’s own chain of checks, including conditions.

Continuing on the example above, the following snippet will send an email to the administrator if the watch fires.

A second action will send an additional email to a manager if the total number of hits is above 100. This is controlled by the script condition in the action definition:

{ 
  "trigger":{},
  "checks":[],
  "actions":[ 
    {
         "type":"email",
         "name":"standard_admin",
         "account":"it_smtp",
         "to": ["admin@example.com"],
         "subject": "Too many errors detected.",
         "text_body":"Found more that  hits."
    },
    {
         "type":"email",
         "name":"standard_admin",
         "account":"it_smtp",
         "to": ["management@example.com"],
         "subject": "Warning: Critical amount of errors found",
         "text_body":"Found more that  hits.",
         "checks": [
           {
               "type": "condition.script",
               "name": "escalation_level_1",
               "source": "return data.http_error_500.hits.total.value > 100"
           }
         ]
    }    
  ]
}

Not what you were looking for? Try the search.