Post-8.10 mini-refresh (#143)

* Add alert suppression clarification note

Per /pull/3879

* Clarify note in new terms rule create

Per /pull/3943

* Update images for QA bugs

Per /pull/3946

* Add new terms rule type to create rule API docs

Per /pull/3914

* Add new terms rule type to *update* rule API docs

Per /pull/3914

alerts/alert-suppression.mdx

@@ -33,15 +33,20 @@ Alert suppression is not available for Elastic prebuilt rules. However, if you w
 
 You can configure alert suppression when you create or edit a custom query rule. Refer to <DocLink id="serverlessSecurityRulesUiCreate" section="create-a-custom-query-rule">Create a custom query rule</DocLink> for detailed instructions.
 
-1. When configuring the rule type (the **Define rule** step for a new rule, or the **Definition** tab for an existing rule), enter one or more field names in **Suppress alerts by**. 
+1. When configuring the rule type (the **Define rule** step for a new rule, or the **Definition** tab for an existing rule), enter one or more field names in **Suppress alerts by**.
+
+    <DocCallOut title="Note">  
+    If you specify a field with multiple values, an alert grouping is created for each value. For example, if you suppress alerts by `destination.ip` of `[127.0.0.1, 127.0.0.2, 127.0.0.3]`, alerts will be suppressed separately for each matching value of `127.0.0.1`, `127.0.0.2`, and `127.0.0.3`.
+    </DocCallOut>
+
 1. Select how often to create alerts for duplicate events:
 
     * **Per rule execution**: Create an alert each time the rule runs and matches one or more events.
     * **Per time period**: Create one alert for all matching events within a specified time window, beginning when the rule first matches an event and creates the alert.
 
-    For example, if a rule runs every 5 minutes but you don't need alerts that frequently, you can set the suppression time period to a longer time, such as 1 hour. If the rule matches an event, it creates an alert at that time, and for the next hour, it'll suppress any subsequent matches.
+        For example, if a rule runs every 5 minutes but you don't need alerts that frequently, you can set the suppression time period to a longer time, such as 1 hour. If the rule matches an event, it creates an alert at that time, and for the next hour, it'll suppress any subsequent matches.
 
-    <DocImage size="l" url="../images/alert-suppression/-detections-alert-suppression-options.png" alt="Alert suppression options" />
+        <DocImage size="l" url="../images/alert-suppression/-detections-alert-suppression-options.png" alt="Alert suppression options" />
 
 1. Under **If a suppression field is missing**, choose how to handle events with missing suppression fields (events in which one or more of the **Suppress alerts by** fields don't exist):
     * **Suppress and group alerts for events with missing fields**: Create one alert for each group of events with missing fields. Missing fields get a `null` value, which is used to group and suppress alerts. 

api/detections-api/rules-api-create.mdx

@@ -47,6 +47,8 @@ You can create the following types of rules:
 * **((ml-cap)) rules**: Creates an alert when a ((ml)) job discovers an anomaly above
     the defined threshold (see \<\<machine-learning>>).
 
+* **New terms**: Generates an alert for each new term detected in source documents within a specified time range.
+
 <DocCallOut title="Important" color="warning">
 To create ((ml)) rules, you must have the
 [appropriate license](https://www.elastic.co/subscriptions) or use a
@@ -116,6 +118,7 @@ A JSON object that defines the rule's values:
 * <DocLink id="serverlessSecurityRulesApiCreate" section="required-field-for-event-correlation-rules">Required field for event correlation rules</DocLink>
 * <DocLink id="serverlessSecurityRulesApiCreate" section="required-fields-for-machine-learning-rules">Required fields for machine learning rules</DocLink>
 * <DocLink id="serverlessSecurityRulesApiCreate" section="required-fields-for-indicator-match-rules">Required fields for indicator match rules</DocLink>
+* <DocLink id="serverlessSecurityRulesApiCreate" section="req-fields-new-terms">Required fields for new terms rules</DocLink>
 * <DocLink id="serverlessSecurityRulesApiCreate" section="optional-fields-for-all-rule-types">Optional fields for all rule types</DocLink>
 * <DocLink id="serverlessSecurityRulesApiCreate" section="optional-fields-for-query-indicator-match-and-event-correlation-rules">Optional fields for query, indicator match, and event correlation rules</DocLink>
 * <DocLink id="serverlessSecurityRulesApiCreate" section="optional-fields-for-indicator-match-rules">Optional fields for indicator match rules</DocLink>
@@ -205,19 +208,16 @@ A JSON object that defines the rule's values:
       * `machine_learning`: rule based on a ((ml)) job's anomaly scores.
       * `threat_match`: rule that matches event values with values in the specified
           ((es)) index.
-
       * `threshold`: rule based on the number of times a `query` matches the
           specified field.
-
-
-
+      * `new_terms`: rule that alerts on values that have not been seen before.   
     </DocCell>
   </DocRow>
 </DocTable>
 
 <div id="req-fields-query-threshold"></div>
 
-### Required field for query, indicator match and threshold rules
+### Required field for query, indicator match, threshold, and new terms rules
 
 <DocTable columns={[
   {
@@ -378,6 +378,23 @@ A JSON object that defines the rule's values:
   </DocRow>
 </DocTable>
 
+<div id="req-fields-new-terms"></div>
+
+### Required fields for new terms rules
+
+<DocTable columns={[{ "title": "Name" }, { "title": "Type" }, { "title": "Description" }]}>
+  <DocRow>
+    <DocCell>new_terms_fields</DocCell>
+    <DocCell>String[]</DocCell>
+    <DocCell>Fields to monitor for new values. Must contain 1–3 field names.</DocCell>
+  </DocRow>
+  <DocRow>
+    <DocCell>history_window_start</DocCell>
+    <DocCell>String</DocCell>
+    <DocCell>Start date to use when checking if a term has been seen before. Supports relative dates – for example, `now-30d` will search the last 30 days of data when checking if a term is new. We do not recommend using absolute dates, which can cause issues with rule performance due to querying increasing amounts of data over time.</DocCell>
+  </DocRow>
+</DocTable>
+
 <div id="opt-fields-all"></div>
 
 ### Optional fields for all rule types
@@ -596,7 +613,7 @@ A JSON object that defines the rule's values:
 
 <div id="opt-fields-query-eql"></div>
 
-### Optional fields for query, indicator match, and event correlation rules
+### Optional fields for query, indicator match, event correlation, and new terms rules
 
 <DocTable columns={[
   {
@@ -646,15 +663,15 @@ A JSON object that defines the rule's values:
 
 <div id="opt-fields-query-threshold"></div>
 
-### Optional fields for query, indicator match, and threshold rules
+### Optional fields for query, indicator match, threshold, and new terms rules
 
 | Name | Type | Description |
 |---|---|---|
 | language | String | Determines the query language, which must be `kuery` or `lucene`. Defaults to `kuery`. |
 
 <div id="opt-fields-eql-query-threshold"></div>
 
-### Optional fields for event correlation, query, and threshold rules
+### Optional fields for event correlation, query, threshold, and new terms rules
 
 <DocTable columns={[
   {
@@ -1409,6 +1426,27 @@ logic. In this example, both the event's `destination.ip` and
 [^4]: Sibling `entries` are evaluated using `or` logic. An alert is generated when
 at least one `entries` object evaluates to `true`.
 
+**Example 6**
+
+New terms rule that creates alerts a new IP address is detected for a user:
+
+{/* KIBANA */}
+```console
+POST api/detection_engine/rules
+{
+  "risk_score": 21,
+  "description": "Detects a user associated with a new IP address",
+  "name": "New User IP Detected",
+  "severity": "medium",
+  "type": "new_terms",
+  "language": "kuery",
+  "query": "*",
+  "new_terms_fields": ["user.id", "source.ip"],
+  "history_window_start": "now-30d",
+  "index": ["auditbeat*"]
+}
+```
+
 ## Response code
 
 `200` 
@@ -1721,3 +1759,47 @@ Example response for an indicator match rule:
 }
 ```
 [^1]: <DocBadge template="in development" />  These fields are under development and their usage may change: `related_integrations`, `required_fields`, and `setup`.
+
+Example response for a new terms rule:
+
+```json
+{
+  "author": [],
+  "created_at": "2020-10-06T07:07:58.227Z",
+  "updated_at": "2020-10-06T07:07:58.237Z",
+  "created_by": "elastic",
+  "description": "Detects a user associated with a new IP address",
+  "enabled": true,
+  "false_positives": [],
+  "from": "now-6m",
+  "id": "eb7225c0-566b-11ee-8b4f-bbf3afdeb9f4",
+  "immutable": false,
+  "interval": "5m",
+  "rule_id": "c6f5d0bc-7be9-47d4-b2f3-073d22641e30",
+  "max_signals": 100,
+  "risk_score": 21,
+  "risk_score_mapping": [],
+  "name": "New User IP Detected",
+  "references": [],
+  "severity": "medium",
+  "severity_mapping": [],
+  "updated_by": "elastic",
+  "tags": [],
+  "to": "now",
+  "type": "new_terms",
+  "threat": [],
+  "version": 1,
+  "exceptions_list": [],
+  "index": [
+    "auditbeat*"
+  ],
+  "query": "*",
+  "language": "kuery",
+  "new_terms_fields": ["user.id", "source.ip"],
+  "history_window_start": "now-30d",
+  "related_integrations": [],       [^1]
+  "required_fields": [],            [^1]
+  "setup": ""                       [^1]
+}
+```
+[^1]: <DocBadge template="in development" />  These fields are under development and their usage may change: `related_integrations`, `required_fields`, and `setup`.

api/detections-api/rules-api-update.mdx

@@ -126,17 +126,14 @@ some fields are required.
       * `machine_learning`: rule based on a ((ml)) job's anomaly scores.
       * `threat_match`: rule that matches event values with values in the specified
           ((es)) index.
-
       * `threshold`: rule based on the number of times a `query` matches the
           specified field.
-
-
-
+      * `new_terms`: rule that alerts on values that have not been seen before.
     </DocCell>
   </DocRow>
 </DocTable>
 
-### Field required for query, threat-match and threshold rules `PUT` calls
+### Field required for query, threat-match, threshold, and new terms rules `PUT` calls
 
 <DocTable columns={[
   {
@@ -287,6 +284,21 @@ some fields are required.
   </DocRow>
 </DocTable>
 
+### Fields required for new terms rules `PUT` calls
+
+<DocTable columns={[{ "title": "Name" }, { "title": "Type" }, { "title": "Description" }]}>
+  <DocRow>
+    <DocCell>new_terms_fields</DocCell>
+    <DocCell>String[]</DocCell>
+    <DocCell>Fields to monitor for new values. Must contain 1–3 field names.</DocCell>
+  </DocRow>
+  <DocRow>
+    <DocCell>history_window_start</DocCell>
+    <DocCell>String</DocCell>
+    <DocCell>Start date to use when checking if a term has been seen before. Supports relative dates – for example, `now-30d` will search the last 30 days of data when checking if a term is new. We do not recommend using absolute dates, which can cause issues with rule performance due to querying increasing amounts of data over time.</DocCell>
+  </DocRow>
+</DocTable>
+
 ### Optional fields for all rule types
 
 <DocTable columns={[
@@ -492,7 +504,7 @@ some fields are required.
   </DocRow>
 </DocTable>
 
-### Optional fields for query, threat-match and EQL rules
+### Optional fields for query, threat-match, EQL, and new terms rules
 
 <DocTable columns={[
   {
@@ -538,13 +550,13 @@ some fields are required.
 | threat_filters | Object[] | [Query and filter context](((ref))/query-filter-context.html) 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`. |
 
-### Optional fields for query, threat-match and threshold rules
+### Optional fields for query, threat-match, threshold, and new terms rules
 
 | Name | Type | Description |
 |---|---|---|
 | language | String | Determines the query language, which must be `kuery` or `lucene`. Defaults to `kuery`. |
 
-### Optional fields for EQL, query and threshold rules
+### Optional fields for EQL, query, threshold, and new terms rules
 
 <DocTable columns={[
   {

rules/rules-ui-create.mdx

@@ -100,6 +100,10 @@ role, and the selected ((ml)) job must be running for the rule to function corre
 
     1. Enter a field name to group matching source events by the field's unique values; only one alert will be created for each group of events. You can also enter multiple fields to group events by unique combinations of values.
 
+        <DocCallOut title="Note">  
+        If you specify a field with multiple values, an alert grouping is created for each value. For example, if you suppress alerts by `destination.ip` of `[127.0.0.1, 127.0.0.2, 127.0.0.3]`, alerts will be suppressed separately for each matching value of `127.0.0.1`, `127.0.0.2`, and `127.0.0.3`.
+        </DocCallOut>
+
     1. Select how often to create alerts for duplicate events:
 
         * **Per rule execution**: Create an alert each time the rule runs and matches duplicate events.
@@ -291,6 +295,9 @@ You uploaded a value list of known ransomware domains, and you want to be notifi
 
         <DocCallOut title="Important" color="warning">
         When checking multiple fields, full results can be produced only for documents with no more than 100 unique combinations of values in these fields. If you expect your data to produce more than 100 unique new terms combinations per document, consider checking other fields to narrow down the search.
+
+
+        When checking multiple fields, each unique combination of values from those fields is evaluated separately. For example, a document with `host.name: ["host-1", "host-2", "host-3"]` and `user.name: ["user-1", "user-2", "user-3"]` has 9 (3x3) unique combinations of `host.name` and `user.name`. A document with 11 values in `host.name` and 10 values in `user.name` has 110 (11x10) unique combinations. The new terms rule only evaluates 100 unique combinations per document, so selecting fields with large arrays of values might cause incorrect results.
         </DocCallOut>
 
     1. Use the **History Window Size** menu to specify the time range to search in minutes, hours, or days to determine if a term is new. The history window size must be larger than the rule interval plus additional look-back time, because the rule will look for terms where the only time(s) the term appears within the history window is _also_ within the rule interval and additional look-back time.