From 65491c06e23350c1018946eecb77a1bd026c3f34 Mon Sep 17 00:00:00 2001 From: Garrett Spong Date: Tue, 9 Mar 2021 08:54:08 -0700 Subject: [PATCH] [DOCS] Updates Create Rule API docs for Threshold and Indicator Match Rules (#522) (#539) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is a rough pass at updating the [Create Rule API docs](https://www.elastic.co/guide/en/security/current/rules-api-create.html#_request_body) for the recent changes surrounding `Threshold` and `Indicator Match` rules. @madirey and @rylnd if you could verify these changes and if any additional fields should be documented that would be greatly appreciated. 🙂 Resolves: https://github.com/elastic/kibana/issues/91965 Note: The grouping of optional fields per rule type makes these docs difficult to maintain (for me at least 😅), as you need to cross reference each optional field from each type, plus I'd bargain our users might find it useful to be able to look at all fields per each rule type independently. Something to verify with users/discuss, but would be a nice add for maintaining these docs (outside of writing scripts to generate the groupings). ##### Threshold Rules: For more details on `cardinality_field` and `cardinality_value` see: https://github.com/elastic/kibana/pull/90826 ##### Indicator Match Rules: For more details on `threat_filters` see: https://github.com/elastic/kibana/pull/91260 --- .../detections/api/rules/rules-api-create.asciidoc | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index bcc5185950..619a7f0d20 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -160,8 +160,13 @@ whether an alert is generated. |threshold |Object a|Defines the field and threshold value for when alerts are generated, where: -* `field` (string, required): The field on which the threshold is applied. If -you specify an empty field (`""`), alerts are generated when the query returns +* `cardinality` (Array of length 1): The field on which the cardinality is applied. +* `cardinality.field` (string, required): The field on which to calculate and compare the +cardinality. +* `cardinality.value` (integer, required): The threshold value from which an alert is +generated based on unique number of values of `cardinality.field`. +* `field` (string or string[], required): The field on which the threshold is applied. If +you specify an empty array (`[]`), alerts are generated when the query returns at least the number of results specified in the `value` field. * `value` (integer, required): The threshold value from which an alert is generated. @@ -336,9 +341,12 @@ a detection rule exception (`detection`) or an endpoint exception (`endpoint`). |============================================== |Name |Type |Description -|threat_filter |Object[] +|threat_filters |Object[] |{ref}/query-filter-context.html[Query and filter context] array used to filter documents from the {es} index containing the threat values. + +|threat_indicator_path |String +|Much like an ingest processor, users can use this field to define where their threat indicator can be found on their indicator documents. Defaults to `threatintel.indicator`. |============================================== [[opt-fields-query-threshold]]