Skip to content

Commit

Permalink
[DOCS] Updates Create Rule API docs for Threshold and Indicator Match…
Browse files Browse the repository at this point in the history
… Rules (elastic#522)

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: elastic/kibana#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: elastic/kibana#90826


##### Indicator Match Rules:

For more details on `threat_filters` see: elastic/kibana#91260
  • Loading branch information
spong committed Mar 9, 2021
1 parent 8e84540 commit 527f093
Showing 1 changed file with 11 additions and 3 deletions.
14 changes: 11 additions & 3 deletions docs/detections/api/rules/rules-api-create.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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]]
Expand Down

0 comments on commit 527f093

Please sign in to comment.