Aggs: Scripted metric allow list docs (#109635)

* Document new settings
* Mention agg allow list in scripting security doc

Author: alex-spies

docs/reference/modules/indices/search-settings.asciidoc

@@ -33,6 +33,39 @@ a single response. Defaults to 65,536.
 +
 Requests that attempt to return more than this limit will return an error.
 
+[[search-settings-only-allowed-scripts]]
+`search.aggs.only_allowed_metric_scripts`::
+(<<cluster-update-settings,Dynamic>>, boolean)
+Configures whether only explicitly allowed scripts can be used in
+<<search-aggregations-metrics-scripted-metric-aggregation,scripted metrics aggregations>>.
+Defaults to `false`.
++
+Requests using scripts not contained in either
+<<search-settings-allowed-inline-scripts,`search.aggs.allowed_inline_metric_scripts`>>
+or
+<<search-settings-allowed-stored-scripts,`search.aggs.allowed_stored_metric_scripts`>>
+will return an error.
+
+[[search-settings-allowed-inline-scripts]]
+`search.aggs.allowed_inline_metric_scripts`::
+(<<cluster-update-settings,Dynamic>>, list of strings)
+List of inline scripts that can be used in scripted metrics aggregations when
+<<search-settings-only-allowed-scripts,`search.aggs.only_allowed_metric_scripts`>>
+is set to `true`.
+Defaults to an empty list.
++
+Requests using other inline scripts will return an error.
+
+[[search-settings-allowed-stored-scripts]]
+`search.aggs.allowed_stored_metric_scripts`::
+(<<cluster-update-settings,Dynamic>>, list of strings)
+List of ids of stored scripts that can be used in scripted metrics aggregations when
+<<search-settings-only-allowed-scripts,`search.aggs.only_allowed_metric_scripts`>>
+is set to `true`.
+Defaults to an empty list.
++
+Requests using other stored scripts will return an error.
+
 [[indices-query-bool-max-nested-depth]]
 `indices.query.bool.max_nested_depth`::
 (<<static-cluster-setting,Static>>, integer) Maximum nested depth of queries. Defaults to `30`.

docs/reference/scripting/security.asciidoc

@@ -9,31 +9,37 @@ security in a defense in depth strategy for scripting.
 
 The second layer of security is the https://www.oracle.com/java/technologies/javase/seccodeguide.html[Java Security Manager]. As part of its startup
 sequence, {es} enables the Java Security Manager to limit the actions that
-portions of the code can take. <<modules-scripting-painless,Painless>> uses 
-the Java Security Manager as an additional layer of defense to prevent scripts 
+portions of the code can take. <<modules-scripting-painless,Painless>> uses
+the Java Security Manager as an additional layer of defense to prevent scripts
 from doing things like writing files and listening to sockets.
 
 {es} uses
 {wikipedia}/Seccomp[seccomp] in Linux,
 https://www.chromium.org/developers/design-documents/sandbox/osx-sandboxing-design[Seatbelt]
 in macOS, and
 https://msdn.microsoft.com/en-us/library/windows/desktop/ms684147[ActiveProcessLimit]
-on Windows as additional security layers to prevent {es} from forking or 
+on Windows as additional security layers to prevent {es} from forking or
 running other processes.
 
+Finally, scripts used in
+<<search-aggregations-metrics-scripted-metric-aggregation,scripted metrics aggregations>>
+can be restricted to a defined list of scripts, or forbidden altogether.
+This can prevent users from running particularly slow or resource intensive aggregation
+queries.
+
 You can modify the following script settings to restrict the type of scripts
-that are allowed to run, and control the available 
+that are allowed to run, and control the available
 {painless}/painless-contexts.html[contexts] that scripts can run in. To
-implement additional layers in your defense in depth strategy, follow the 
+implement additional layers in your defense in depth strategy, follow the
 <<es-security-principles,{es} security principles>>.
 
 [[allowed-script-types-setting]]
 [discrete]
 === Allowed script types setting
 
-{es} supports two script types: `inline` and `stored`. By default, {es} is 
-configured to run both types of scripts. To limit what type of scripts are run, 
-set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from 
+{es} supports two script types: `inline` and `stored`. By default, {es} is
+configured to run both types of scripts. To limit what type of scripts are run,
+set `script.allowed_types` to `inline` or `stored`. To prevent any scripts from
 running, set `script.allowed_types` to `none`.
 
 IMPORTANT: If you use {kib}, set `script.allowed_types` to both or just `inline`.
@@ -61,3 +67,48 @@ For example, to allow scripts to run only in `scoring` and `update` contexts:
 ----
 script.allowed_contexts: score, update
 ----
+
+[[allowed-script-in-aggs-settings]]
+[discrete]
+=== Allowed scripts in scripted metrics aggregations
+
+By default, all scripts are permitted in
+<<search-aggregations-metrics-scripted-metric-aggregation,scripted metrics aggregations>>.
+To restrict the set of allowed scripts, set
+<<search-settings-only-allowed-scripts,`search.aggs.only_allowed_metric_scripts`>>
+to `true` and provide the allowed scripts using
+<<search-settings-allowed-inline-scripts,`search.aggs.allowed_inline_metric_scripts`>>
+and/or
+<<search-settings-allowed-stored-scripts,`search.aggs.allowed_stored_metric_scripts`>>.
+
+To disallow certain script types, omit the corresponding script list
+(`search.aggs.allowed_inline_metric_scripts` or
+`search.aggs.allowed_stored_metric_scripts`) or set it to an empty array.
+When both script lists are not empty, the given stored scripts and the given inline scripts
+will be allowed.
+
+The following example permits only 4 specific stored scripts to be used, and no inline scripts:
+
+[source,yaml]
+----
+search.aggs.only_allowed_metric_scripts: true
+search.aggs.allowed_inline_metric_scripts: []
+search.aggs.allowed_stored_metric_scripts:
+   - script_id_1
+   - script_id_2
+   - script_id_3
+   - script_id_4
+----
+
+Conversely, the next example allows specific inline scripts but no stored scripts:
+
+[source,yaml]
+----
+search.aggs.only_allowed_metric_scripts: true
+search.aggs.allowed_inline_metric_scripts:
+   - 'state.transactions = []'
+   - 'state.transactions.add(doc.some_field.value)'
+   - 'long sum = 0; for (t in state.transactions) { sum += t } return sum'
+   - 'long sum = 0; for (a in states) { sum += a } return sum'
+search.aggs.allowed_stored_metric_scripts: []
+----