Interactive investigation guides

docs/experimental-features/experimental-features-intro.asciidoc

@@ -7,3 +7,4 @@ The features in this section are experimental and may be changed or removed comp
 include::host-risk-score.asciidoc[]
 include::user-risk-score.asciidoc[]
 include::beaconing-detection.asciidoc[]
+include::investigation-guide-actions.asciidoc[]

docs/experimental-features/investigation-guide-actions.asciidoc

@@ -0,0 +1,82 @@
+[[interactive-investigation-guides]]
+== Interactive investigation guides
+
+NOTE: This feature is available for {stack} versions 8.6.0 and newer.
+
+Detection rule investigation guides suggest steps for triaging, analyzing, and responding to potential security issues. For custom rules, you can create an interactive investigation guide that includes buttons for launching runtime queries in <<timelines-ui,Timeline>>, using alert data and hard-coded literal values. This allows you to start detailed Timeline investigations directly from an alert using relevant data. 
+
+[role="screenshot"]
+image::images/ig-alert-flyout.png[Alert details flyout with interactive investigation guide,550]
+
+Each query button displays in parentheses the number of documents found. Click the button to automatically create the query in Timeline based on settings specified in the investigation guide.
+
+[role="screenshot"]
+image::images/ig-timeline.png[Timeline with query pre-loaded from investigation guide action]
+
+[discrete]
+[[add-ig-actions-rule]]
+=== Add investigation guide actions to a rule
+
+NOTE: You can only create interactive investigation guides with custom rules because Elastic prebuilt rules can't be edited. However, you can duplicate a prebuilt rule, then configure the investigation guide for the duplicated rule.
+
+You can configure an interactive investigation guide when you <<rules-ui-create,create a new rule>> or <<edit-rules-settings,edit an existing rule>>. When configuring the rule's settings (the *About rule* step for a new rule, or the *About* tab for an existing rule), expand the *Advanced settings*, then scroll down to the *Investigation guide* field.
+
+[role="screenshot"]
+image::images/ig-investigation-guide-editor.png[Investigation guide editor field]
+
+Add the following syntax to the *Investigation guide* Markdown editor to configure a query. The syntax will appear as a clickable button in the investigation guide.
+
+[width="100%",options="header"]
+|===
+|Field |Description
+
+|`!{insight{ }}` |The container object holding all the configuration attributes for the button and the query.
+|`label` |Text to identify the button.
+|`description` |Additional text to include on the button.
+|`providers` a|A two-level nested array that defines the query you want to run in Timeline. Similar to the structure of queries in Timeline, items in the outer level are joined by an `OR` relationship, and items in the inner level are joined by an `AND` relationship.
+
+Each item in `providers` is defined by these attributes:
+
+* `field`: The name of a field to query.
+* `value`: The value to search for. Either a hard-coded literal value, or the name of the field on the alert whose value you want to use as a query parameter.
+* `type`: Either `literal` or `parameter`.
+|===
+
+NOTE: Some characters must be escaped with a backslash, such as `\"` for a quotation mark and `\\` for a literal backslash. Windows paths must be divided with double backslashes (for example, `C:\\Windows\\explorer.exe`), and paths that already include double backslashes might require four backslashes for each divider. A clickable error icon (image:images/ig-error-icon.png[Error icon,19,18]) displays below the Markdown editor if there are any syntax errors.
+
+[discrete]
+==== Example syntax
+
+[source,json]
+----
+!{insight{
+    "label": "Test action",
+    "description": "Click to investigate",
+    "providers": [
+      [     
+        {"field": "event.id", "value": "kibana.alert.original_event.id", "type": "parameter"}
+      ],
+      [  
+        {"field": "event.action", "value": "rename", "type": "literal"},
+        {"field": "process.pid", "value": "process.pid", "type": "parameter"}
+      ]
+    ]
+}}
+----
+
+This example creates the following Timeline query, as illustrated below:
+
+`(event.id : <alert value>)` +
+`OR (event.action : "rename" AND process.pid : <alert value>)`
+
+[role="screenshot"]
+image::images/ig-timeline-query.png[Timeline query,500]
+
+[discrete]
+==== Timeline template fields
+
+When viewing an interactive investigation guide in contexts unconnected to a specific alert (such a rule's details page), queries open as <<timeline-templates-ui,Timeline templates>>, and `parameter` fields are treated as Timeline template fields.
+
+[role="screenshot"]
+image::images/ig-timeline-template-fields.png[Timeline template,500]
+