[DOCS] Updating "Manage detection alerts" topic (#666) (#703)

* Updating topic title. * Expanded the section about vieiwing and filtering detection alerts. * Fixed minor typos. * Updated section for customizing the Alerts table and added a section for viewing alert details. * Added float tag before the Customize the Alerts table section and fixed typo in alt text within security-ui file. * Added images and started the view alert details section. * Minor updates to drafted section. * Fixed minor issues. * Commiting drafted changes. Additional changes incoming. * Incorporated additional comments from Ece. * Removed duplicate text in description of Threat Intel tab. * Re-adding feedback from Ece. * Incorporated Ece's latest suggestion. * Adding missing commas. * Incorporating feedback from Janeen, * Minor typos. * Updated screenshot showing Detections page. * Updates to new prebuilt rules integration Co-authored-by: Janeen Mikell-Straughn <[email protected]> Co-authored-by: jmikell821 <[email protected]> Co-authored-by: Janeen Mikell-Straughn <[email protected]> Co-authored-by: jmikell821 <[email protected]>
elastic · May 25, 2021 · 18f5ea8 · 18f5ea8
1 parent 8c1abd3
commit 18f5ea8
Show file tree

Hide file tree

Showing 9 changed files with 84 additions and 18 deletions.
diff --git a/docs/detections/alerts-ui-manage.asciidoc b/docs/detections/alerts-ui-manage.asciidoc
@@ -1,49 +1,117 @@
 [[alerts-ui-manage]]
 [role="xpack"]
-== Managing detection alerts
+== Manage detection alerts
 
 The Detections page displays all <<detection-alert-def, detection alerts>>.
-From the Alerts table, you can change an alert's status, and start
+From the Alerts table, you can filter alerts, change an alert's status, and start
 investigating and analyzing alerts in Timeline.
 
 TIP: From Timeline, you can <<cases-ui-open, create cases>> to track issues and
 share information with colleagues.
 
-To view detection alerts created by a specific rule, you can:
+[float]
+[[download-prebuilt-rules]]
+=== Download latest prebuilt Elastic rules
+
+[beta]
+
+As of {stack} >=7.13.0., you can download the latest version of Elastic prebuilt rules outside of a regular release cycle. This feature ensures you have the latest detection capabilties before upgrading to the latest {stack}.
+
+To download the latest version of prebuilt rules:
+
+. In {kib}, go to *Fleet > Integrations*.
+. Search for "Prebuilt Security Detection Rules."
+. Select the integration, then click *Add Prebuilt Security Detection Rules*. The integration configuration page is displayed.
+. (Optional) If you have an {agent} enrolled and have created an agent policy you want to assign to this integration, select it from the drop-down.
+. Configure the integration settings by entering a name and optional description.
+. Click *Save integration* in the lower right corner.
+
+[role="screenshot"]
+image::images/prebuilt-integration.png[]
+
+[float]
+[[detection-view-and-filter-alerts]]
+=== View and filter detection alerts
+The Detections page offers various ways for you to organize and triage detection alerts as you investigate suspicious events. You can:
 
 * Filter for a specific rule in the KQL bar (for example,
 `signal.rule.name :"SSH (Secure Shell) from the Internet"`).
-* View detection alerts in the *Rule details* page (click
-*Manage detection rules* -> rule name in the *All rules* table).
 
 NOTE: KQL autocomplete for `.siem-signals-*` indices is available on the
 *Detections* and *Rule details* pages, and in Timeline when either `All` or
 `Detection alerts` is selected.
 
-TIP: Use the icons in the upper left corner of the Alerts table to customize
-displayed columns and row renderers, and view the table in full screen mode.
+* Use the date and time filter to select a time range that you’re interested in exploring. By default, this filter is set to search the last 24 hours.
+* View detection alerts generated by a specific rule. To do this, click *Manage detection rules*, then click on a rule name in the All rules table. The *Rules detail page* displays a comprehensive view of the rule's details, and alert details are displayed in the Alerts table beneath the Trend histogram.
+* Use the *Stack by* dropdown in the Trend histogram to select specific parameters by which to visualize the individual counts. For example, if you select `signal.rule.name`, the histogram displays the total counts by alert name.
+* Filter alert results to include building block alerts or to only show alerts from indicator match rules by selecting the *Additional filters* drop-down. By default, building block alerts are excluded from the Alerts table; therefore, including them expands the number of alerts.
+
+NOTE: When updating alert results to also include building block alerts, the Security app searches the `.siem-signals-<Kibana space>` index for the `signal.rule.building_block_type` field. When looking for alerts created from indicator match rules, the app searches the same index for the `signal.rule.threat_mapping` field.
+
+[role="screenshot"]
+image::images/additional-filters.png[Shows multiple ways to filter information]
+
+[float]
+[[customize-the-alerts-table]]
+=== Customize the Alerts table
+Use the buttons in the upper left corner of the Alerts table to customize the columns you want displayed and to view the table in full-screen mode.
+
+[role="screenshot"]
+image::images/alert-table-columns-and-size.gif[width=100%][height=100%][Demo that shows how to select the customize display button and full screen button]
+
+Click the *Customize Event Renderers* button to enable event renderers within the Alerts table. When enabled, event renderers show relevant details that provide more context to the event. For example, if you enable the *Flow* Event Renderer, the Alerts table shows relevant details describing the data flow between a source and destination. These details include information such as hosts, ports, protocol, direction, duration, amount transferred, process, and geographic location.
+
+[role="screenshot"]
+image::images/customize-event-renderer.png[Shows the Event Renderer button, 200]
+
+All event renderers are disabled by default. To switch between event views in the Alerts table, you can enable individual event renderers or click *Enable all*. Closing the *Customize Event Renderers* page saves your configurations.
+
+[role="screenshot"]
+image::images/customize-event-renderer-page.png[Shows the Event Renderer page]
+
+[float]
+[[view-alert-details]]
+=== View alert details
+To further inspect an alert, click the *View details* button from the Alerts table.
+
+[role="screenshot"]
+image::images/view-alert-details.png[Shows the Event Renderer button, 200]
+
+The Alert details flyout appears and offers several options for viewing alert details:
+
+* *Summary*: Shows an aggregated view of alert details. Alerts that have been enriched with `threat.indicator` data also display the *threat summary* section, which is an additional section located beneath the alert summary. In the *threat summary* section, you can view mapped data for the following `threat.indicator` subfields:
+** `matched.field`
+** `matched.type`
+** `source (threat.indicator.provider)`
+** `first_seen`
+** `last_seen`
+
+NOTE: If an alert is linked to more than one threat, `threat.indicator` data is still aggregated under the *threat summary* section, but will be parsed out in the *Threat Intel* tab.
+
+* *Threat Intel*: Shows the number of matched threats and displays them individually. Threats appear in reverse chronological order, with the most recent alerts at the top. The available `threat.indicator` and `source.event` data is displayed for each threat. If the alert has not been enriched with threat data, the *Threat Intel* tab displays the message "No Threat Intel Enrichment Found" and provides a link to Threat Intel module documentation.
+* *Table*: Shows the alert details in table format. Alert details are organized into field value pairs.
+* *JSON View*: Shows the alert details in JSON format.
 
 [float]
 [[detection-alert-status]]
 === Change alert statuses
 
 You can set an alert's status to indicate whether it needs to be investigated
-(`Open`), is under active investigation (`In progress`), or resolved
-(`Closed`). By default, the Alerts table displays open alerts. To view alerts
+(*Open*), is under active investigation (*In progress*), or resolved
+(*Closed*). By default, the Alerts table displays open alerts. To view alerts
 with other statuses, click *In progress* or *Closed*.
 
 To change alert statuses, either:
 
-* In the alert's row, click the *more options* icon, and then select the
-required status (*Mark in progress*, *Close alert*, or *Open alert*).
+* In the alert's row, click the *More actions* button, then select the appropriate status (*Mark in progress*, *Close alert*, or *Open alert*).
 * In the Alerts table, select all the alerts you want to change, and then select
 *Take action* -> *Close selected*, *Open selected*, or *Mark in progress*.
 
 [float]
 [[signals-to-timelines]]
 === Send alerts to Timeline
 
-To view an alert in Timeline, click the *Investigate in timeline* icon.
+To view an alert in Timeline, click the *Investigate in timeline* button.
 
 TIP: When you send an alert generated by a
 <<rules-ui-create, threshold rule>> to Timeline, all matching events are
@@ -52,9 +120,7 @@ example, if you have an alert generated by a threshold rule that detects 10
 failed login attempts, when you send that alert to Timeline all failed login
 attempts detected by the rule are listed.
 
-If the rule that generated the alert uses a Timeline template, when you
-investigate the alert in Timeline, the dropzone query values defined in the
-template are replaced with their corresponding alert values.
+Suppose the rule that generated the alert uses a Timeline template. In this case, when you investigate the alert in Timeline, the dropzone query values defined in the template are replaced with their corresponding alert values.
 
 // * `host.name`
 // * `host.hostname`
@@ -89,7 +155,7 @@ You can add exceptions to the rule that generated the alert directly from the
 Alerts table. Exceptions prevent a rule from generating alerts even when its
 criteria are met.
 
-To add an exception, click the actions icon (three dots) and then select
+To add an exception, click the actions button (three dots) and then select
 _Add exception_.
 
 For information about exceptions and how to use them, see
@@ -100,4 +166,4 @@ For information about exceptions and how to use them, see
 === Visually analyze process relationships
 
 For process events received from the Elastic Endpoint agent, you can open a
-visual mapping of the relationships and hierarchy connecting related processes. For more information see, <<visual-event-analyzer>>.
+visual mapping of the relationships and hierarchy connecting related processes. For more information see, <<visual-event-analyzer>>.
diff --git a/docs/detections/images/additional-filters.png b/docs/detections/images/additional-filters.png
diff --git a/docs/detections/images/alert-table-columns-and-size.gif b/docs/detections/images/alert-table-columns-and-size.gif
diff --git a/docs/detections/images/customize-event-renderer-page.png b/docs/detections/images/customize-event-renderer-page.png
diff --git a/docs/detections/images/customize-event-renderer.png b/docs/detections/images/customize-event-renderer.png
diff --git a/docs/detections/images/prebuilt-integration.png b/docs/detections/images/prebuilt-integration.png
diff --git a/docs/detections/images/view-alert-details.png b/docs/detections/images/view-alert-details.png
diff --git a/docs/events/images/test2.gif b/docs/events/images/test2.gif
diff --git a/docs/getting-started/security-ui.asciidoc b/docs/getting-started/security-ui.asciidoc
@@ -151,7 +151,7 @@ Use your keyboard to navigate through rows, columns, and menu options in the Ela
 * Use the directional arrows to move keyboard focus right, left, up, and down in a table.
 
 [role="screenshot"]
-image::images/timeline-ui-accessiblity-directional-arrows.gif[width=100%][height=100%][Demo that shows how to to move keyboard focus right, left, up, and down in a table]
+image::images/timeline-ui-accessiblity-directional-arrows.gif[width=100%][height=100%][Demo that shows how to move keyboard focus right, left, up, and down in a table]
 
 * Press the `Tab` key to navigate through a table cell with multiple elements, such as buttons, field names, and menus. Pressing the `Tab` key will apply keyboard focus in a sequential manner to each element in the table cell.