[DOCS] Create rule updates - 7.10 (#336)

* Adds EQL and threat-match rule types * updates terminology * adds warning about eql seq exceptions * Update docs/detections/detections-ui-exceptions.asciidoc Co-authored-by: Ryland Herrick <[email protected]> * Testing addition of preview rule. * comitting so I don't lose. * Committing rule updates so I don't lose. * Merging feedback and testing formatting. * Fixing build error, updating image * formatting changes and updates. * Fix build error. * Attempt build error fix. * Fix missing anchor link * small fixes. * merging feedback. * build fix * and...another build fix. * [DOCS] Terminates important admonition block * merging feedback. Co-authored-by: Ben Skelker <[email protected]> Co-authored-by: Nate Archer <[email protected]> Co-authored-by: Ryland Herrick <[email protected]> Co-authored-by: DonNateR <[email protected]> Co-authored-by: lcawl <[email protected]>
elastic · Nov 10, 2020 · 8254566 · 8254566
1 parent 278b13a
commit 8254566
Show file tree

Hide file tree

Showing 11 changed files with 232 additions and 109 deletions.
diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc
@@ -9,9 +9,7 @@ lists, such as a list of IP addresses or host names.
 
 NOTE: Before creating exception items, you must create an exception container.
 
-[IMPORTANT]
-==============
-Endpoint rule exception items cannot use
+IMPORTANT: Endpoint rule exception items cannot use
 <<lists-api-overview, lists>> (the `list` in the `entries` array), and the
 following fields cannot be used in exception queries (as `field` values in the
 `entries` object):
@@ -21,7 +19,6 @@ following fields cannot be used in exception queries (as `field` values in the
 * `process.entity_id`
 * `process.parent.entity_id`
 * `process.ancestry`
-==============
 
 ==== Request URL
 
@@ -61,7 +58,7 @@ Must be the same value as its associated exception container.
 
 |No, defaults to `single`.
 |`tags` |String[] |String array containing words and phrases to help categorize
-exception items. |No 
+exception items. |No
 |`type` |String a|Exception query type, must be `simple`. |Yes
 |`_tags` |String[] a|For endpoint rules only, defines the OS on which the
 exception is implemented. Valid values are:
@@ -106,7 +103,7 @@ Can be:
 * `nested`: Array of `entries` objects. Nested conditions are required for
 excluding some Endpoint fields (<<nested-field-ex-api, see example below>>).
 <<ex-nested-conditions>> lists all Endpoint fields that require the `nested`
-type. 
+type.
 
 |Yes
 
@@ -124,16 +121,12 @@ a|Field value or values:
 
 |==============================================
 
-[IMPORTANT]
-==============
-When you use <<lists-api-create-container, list containers>>
+IMPORTANT: When you use <<lists-api-create-container, list containers>>
 (`"type": "list"`), you cannot use other types in the `entries` array (`match`,
 `match_any`, `exists`, or `nested`).
 
 For endpoint exceptions, you cannot create exception items based on excluded
-values (`"operator": "excluded"`). 
-==============
-
+values (`"operator": "excluded"`).
 
 ===== Example requests
 
@@ -334,9 +327,9 @@ POST api/lists/exception_lists/items
 
 ==== Response code
 
-`200`:: 
+`200`::
     Indicates a successful call.
-    
+
 ==== Response payload
 
 [source,json]

diff --git a/docs/detections/detection-engine-intro.asciidoc b/docs/detections/detection-engine-intro.asciidoc
@@ -88,6 +88,11 @@ Detection rules::
 Background tasks that run periodically and produce alerts when suspicious
 activity is detected.
 
+[[term-sec-indices]]
+{es-sec} indices::
+Indices containing host and network source events (such as
+`packetbeat-*`, `log-*`, and `winlogbeat-*`). When you <<rules-ui-create, create a new rule>>, the default index pattern corresponds to the <<update-sec-indices, values defined>> in the `securitySolution:defaultIndex`.
+
 Endpoint exceptions::
 <<term-exceptions, Exceptions>> added to both rules and Endpoint agents on
 hosts. Endpoint exceptions can only be added when:
@@ -103,6 +108,11 @@ alerts.
 External alerts::
 Alerts {es-sec} receives from external systems, such as Suricata.
 
+Threat indices::
+Indices containing suspect field values. <<create-indicator-rule, Indicator match rules>> use these
+indices to compare their field values with source event values contained in
+<<term-sec-indices, {es-sec} indices>>.
+
 [float]
 [[detections-permissions]]
 == Detections configuration and index privilege prerequisites

diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc
@@ -2,8 +2,14 @@
 [role="xpack"]
 == Rule exceptions and value lists
 
-To prevent the creation of unwanted alerts, you can add exceptions to detection
-rules. Exceptions contain the source event conditions that determine when
+To prevent the creation of unwanted alerts, you can add exceptions to these
+detection rule types:
+
+* Custom query
+* Event Correlation
+* Indicator match
+
+Exceptions contain the source event conditions that determine when
 alerts are not generated. They provide a convenient way of allowing trusted
 processes and network activity to function without producing unnecessary noise.
 
@@ -39,10 +45,8 @@ act as value delimiters.
 NOTE: All values in the file must be of the same {es} type.
 
 . Go to *Security* -> *Detections* -> *Manage detection rules*.
-. Click *Upload value lists*.
+. Click *Upload value lists*. The *Upload value lists* window opens.
 +
-The *Upload value lists* window opens.
-
 [role="screenshot"]
 image::images/upload-lists-ui.png[]
 
@@ -61,15 +65,28 @@ To view, delete, or export existing lists:
 
 [float]
 [[detection-rule-exceptions]]
-=== Add detection exceptions to a rule
+=== Add exceptions to a rule
 
 You can add exceptions to a rule via the Rule details page or the Alerts table.
 When you add an exception, you can also close all alerts that meet the
 exception's criteria.
 
-IMPORTANT: When you select to close all alerts that meet the exception's
-criteria, all matching alerts are closed, *including* alerts generated by other
-rules.
+[IMPORTANT]
+==============
+Be careful when adding exceptions to EQL sequence rules. Exceptions are
+evaluated against every event in the sequence, and when the exception matches any
+event(s) in the sequence, alerts are not generated. To exclude values from a
+specific event in the sequence, update the rule's EQL statement. For example:
+
+[source,eql]
+----
+`sequence
+  [file where file.extension == "exe"
+  and file.name != "app-name.exe"]
+  [process where true
+  and process.name != "process-name.exe"]`
+----
+==============
 
 . To add an exception via the Rule details page:
 .. Go to the Rule details page of the rule to which you want to add the
@@ -86,7 +103,6 @@ The *Add Exception* window opens (via Alerts table).
 +
 [role="screenshot"]
 image::images/add-exception-ui.png[]
-
 . Add conditions that define when the exception prevents alerts. You can define
 multiple conditions with `OR` and `AND` relationships. In the example above,
 the exception prevents the rule from generating alerts when the
@@ -97,25 +113,24 @@ the exception prevents the rule from generating alerts when the
 ============
 You can use nested conditions. However, this is only required for
 <<nested-field-list, these fields>>. For all other fields, nested conditions
-should not be used. 
+should not be used.
 ============
 +
 If you have created value lists, you can use them to exclude or include all
 values in a list with `is in list` and `is not in list` operators:
 +
 [role="screenshot"]
 image::images/exceptions-ui-list.png[]
-
 NOTE: When using a list, all exception statements must use `is in list` and
 `is not in list` operators.
 
 . You can select any of the following:
 
-* _Close this alert_: Closes the alert when the exception is added. This option
+* *Close this alert*: Closes the alert when the exception is added. This option
 is only available when adding exceptions via the Alerts table.
-* _Close all alerts that match this exception, including alerts generated by other rules_:
-Closes all alerts that match the exception's conditions.
-
+* *Close all alerts that match this exception and were generated by this rule*:
+Closes all alerts that match the exception's conditions and were generated only by the current rule.
++
 . Click *Add Exception*.
 
 [float]
@@ -156,7 +171,6 @@ The *Add Endpoint Exception* window opens (via Alerts table).
 +
 [role="screenshot"]
 image::images/endpoint-add-exp.png[]
-
 . If required, modify the conditions.
 +
 NOTE: <<ex-nested-conditions>> describes when nested conditions are required.
@@ -166,7 +180,7 @@ NOTE: <<ex-nested-conditions>> describes when nested conditions are required.
 * _Close this alert_: Closes the alert when the exception is added. This option
 is only available when adding exceptions via the Alerts table.
 * _Close all alerts that match this exception, including alerts generated by other rules_:
-Closes all alerts that match the exception's conditions. 
+Closes all alerts that match the exception's conditions.
 
 . Click *Add Exception*.
 +
@@ -231,7 +245,7 @@ correctly:
 [discrete]
 ==== Nested condition example
 
-Creates an exception that excludes all LFC-signed trusted processes: 
+Creates an exception that excludes all LFC-signed trusted processes:
 
 [role="screenshot"]
-image::images/nested-exp.png[]
+image::images/nested-exp.png[]
diff --git a/docs/detections/images/create-new-rule.png b/docs/detections/images/create-new-rule.png
diff --git a/docs/detections/images/eql-rule-query-example.png b/docs/detections/images/eql-rule-query-example.png
diff --git a/docs/detections/images/indicator-rule-example.png b/docs/detections/images/indicator-rule-example.png
diff --git a/docs/detections/images/preview-rule.png b/docs/detections/images/preview-rule.png
diff --git a/docs/detections/images/threat-math-rule-query-example.png b/docs/detections/images/threat-math-rule-query-example.png