diff --git a/docs/siem/images/timeline-ui.png b/docs/siem/images/timeline-ui.png index 2af46b3060..55a8875d22 100644 Binary files a/docs/siem/images/timeline-ui.png and b/docs/siem/images/timeline-ui.png differ diff --git a/docs/siem/index.asciidoc b/docs/siem/index.asciidoc index 6354a20cff..182dc9b6e1 100644 --- a/docs/siem/index.asciidoc +++ b/docs/siem/index.asciidoc @@ -14,4 +14,8 @@ include::detections/machine-learning/ml-index.asciidoc[] include::detections/detections-index.asciidoc[] +include::timeline/timeline-ui-overview.asciidoc[] + +include::timeline/timeline-templates.asciidoc[] + include::cases/cases-index.asciidoc[] diff --git a/docs/siem/siem-ui.asciidoc b/docs/siem/siem-ui.asciidoc index 050c9ae5f6..f756597e4f 100644 --- a/docs/siem/siem-ui.asciidoc +++ b/docs/siem/siem-ui.asciidoc @@ -233,7 +233,6 @@ The Cases page is used to open and track security issues directly in the image::images/cases-ui-home.png[] [float] -[[timelines-ui]] == Timelines Use Timeline as your workspace for alert investigations or threat hunting. @@ -260,7 +259,6 @@ can also link to timelines from Cases and external ticketing systems. [discrete] -[[raw]] ==== Focus on signals or raw events Many security events in Timeline are presented in an easy-to-follow rendered @@ -272,7 +270,6 @@ You can click and expand events from within Timeline to see the underlying event data, either in tabular form, as as {es} JSON. [discrete] -[[narrow-expand]] ==== Narrow or expand your query You can specify logical `AND` and `OR` operations with an item's placement in @@ -281,7 +278,6 @@ sets are `OR`-ed together. As you hover the item over the drop area, you can see whether your placement is on target to create an `AND` or `OR` filters. [discrete] -[[pivot]] ==== Pivot on a data point Click a filter to access additional operations such as exclude, temporarily @@ -290,7 +286,6 @@ item so that it is excluded. [discrete] [[row-renderer]] -==== Get more context for each event As you build and modify your queries, you can see the results of your interactions in the details pane below. @@ -301,7 +296,6 @@ event. If you see a particular item that interests you, you can drag it to the drop area for further introspection. [discrete] -[[import-export-timelines]] ==== Export and import timelines You can import and export timelines, which enables importing timelines from one @@ -320,7 +314,6 @@ then select _Export selected_. the timeline `ndjson` file. [discrete] -[[other]] ==== Other actions The Timeline is flexible and highly interactive. As you would expect, the diff --git a/docs/siem/timeline/images/all-actions-timeline-ui.png b/docs/siem/timeline/images/all-actions-timeline-ui.png new file mode 100644 index 0000000000..ddc3328211 Binary files /dev/null and b/docs/siem/timeline/images/all-actions-timeline-ui.png differ diff --git a/docs/siem/timeline/images/create-template-ui.png b/docs/siem/timeline/images/create-template-ui.png new file mode 100644 index 0000000000..cb0c40f675 Binary files /dev/null and b/docs/siem/timeline/images/create-template-ui.png differ diff --git a/docs/siem/timeline/images/invalid-filter.png b/docs/siem/timeline/images/invalid-filter.png new file mode 100644 index 0000000000..ff0e5fba26 Binary files /dev/null and b/docs/siem/timeline/images/invalid-filter.png differ diff --git a/docs/siem/timeline/images/template-filter-value.png b/docs/siem/timeline/images/template-filter-value.png new file mode 100644 index 0000000000..1a9c7c1241 Binary files /dev/null and b/docs/siem/timeline/images/template-filter-value.png differ diff --git a/docs/siem/timeline/images/template-query-example.png b/docs/siem/timeline/images/template-query-example.png new file mode 100644 index 0000000000..80b305487a Binary files /dev/null and b/docs/siem/timeline/images/template-query-example.png differ diff --git a/docs/siem/timeline/images/timeline-disable-filter.png b/docs/siem/timeline/images/timeline-disable-filter.png new file mode 100644 index 0000000000..9a73b5b87c Binary files /dev/null and b/docs/siem/timeline/images/timeline-disable-filter.png differ diff --git a/docs/siem/timeline/images/timeline-field-exists.png b/docs/siem/timeline/images/timeline-field-exists.png new file mode 100644 index 0000000000..c78c054156 Binary files /dev/null and b/docs/siem/timeline/images/timeline-field-exists.png differ diff --git a/docs/siem/timeline/images/timeline-filter-exclude.png b/docs/siem/timeline/images/timeline-filter-exclude.png new file mode 100644 index 0000000000..8df9ee8512 Binary files /dev/null and b/docs/siem/timeline/images/timeline-filter-exclude.png differ diff --git a/docs/siem/timeline/images/timeline-filter-value.png b/docs/siem/timeline/images/timeline-filter-value.png new file mode 100644 index 0000000000..7e51f9041a Binary files /dev/null and b/docs/siem/timeline/images/timeline-filter-value.png differ diff --git a/docs/siem/timeline/images/timeline-template-filter.png b/docs/siem/timeline/images/timeline-template-filter.png new file mode 100644 index 0000000000..0bf39ffa8a Binary files /dev/null and b/docs/siem/timeline/images/timeline-template-filter.png differ diff --git a/docs/siem/timeline/images/timeline-ui-filter-options.png b/docs/siem/timeline/images/timeline-ui-filter-options.png new file mode 100644 index 0000000000..8cea433fd7 Binary files /dev/null and b/docs/siem/timeline/images/timeline-ui-filter-options.png differ diff --git a/docs/siem/timeline/images/timeline-ui-renderer.png b/docs/siem/timeline/images/timeline-ui-renderer.png new file mode 100644 index 0000000000..d256ea54b6 Binary files /dev/null and b/docs/siem/timeline/images/timeline-ui-renderer.png differ diff --git a/docs/siem/timeline/images/timeline-ui.png b/docs/siem/timeline/images/timeline-ui.png new file mode 100644 index 0000000000..55a8875d22 Binary files /dev/null and b/docs/siem/timeline/images/timeline-ui.png differ diff --git a/docs/siem/timeline/timeline-templates.asciidoc b/docs/siem/timeline/timeline-templates.asciidoc new file mode 100644 index 0000000000..54bb22a08b --- /dev/null +++ b/docs/siem/timeline/timeline-templates.asciidoc @@ -0,0 +1,146 @@ +[[timeline-templates-ui]] +== About Timeline templates + +You can attach Timeline templates to detection rules. When attached, the rule's +alerts use the template when they are investigated in Timeline. This enables +immediately viewing the alert's most interesting fields when you start an +investigation. + +Templates can include two type of filters: + +* *'Regular' filter*: Like other {kib} KQL filters, defines both the source +event field and its value. For example: `host.name : "win-server"`. +* *Template filter*: Only defines the event field, and uses a placeholder +for the field's value. When you investigate an alert in Timeline, the field's +value is taken from the alert. + +For example, if you define the `host.name: "{host.name}"` template filter, when +alerts generated by the rule are investigated in Timeline, the alert's +`host.name` value is used in the filter. If the alert's `host.name` value is +`Linux_stafordshire-061`, the Timeline filter is: +`host.name: "Linux_stafordshire-061"`. + +NOTE: For information on how to add Timeline templates to rules, see +<>. + +When you load {es-sec} prebuilt rules, some prebuilt Timeline templates are +also loaded. You can attach these templates to detection rules. The following +templates are loaded: + +* `Generic Endpoint Timeline`: Useful for investigating Elastic Endpoint +security alerts. +* `Generic Process Timeline`: Useful for investigating process-related alerts. +* `Generic Network Timeline`: Useful for investigating network-related alerts. + +TIP: You can <> and use them as +a starting point for your own custom templates. + +[discrete] +[[template-legend-ui]] +=== Timeline template legend + +When you add filters to a Timelime template, the items are color coded to +indicate which type of filter is added. Additionally, you change Timeline +filters to template filters as you build your template. + +'Regular' Timeline filter:: +Click `Convert to template field` changes the filter to a template filter: ++ +[role="screenshot"] +image::images/template-filter-value.png[width=30%] + +Template filter:: ++ +[role="screenshot"] +image::images/timeline-template-filter.png[width=30%] + +When you <>, template +filters with placeholders are disabled: + +[role="screenshot"] +image::images/invalid-filter.png[width=30%] + +To enable the filter, either specify a value or change it to a field exists +filter (see <>). + + +[discrete] +=== Create a Timeline template + +. Go to *Security* -> *Timelines*. +. Click the *Templates* tab, and then *Create new timeline template*. ++ +[role="screenshot"] +image::images/create-template-ui.png[] + +. Give the template a title. +. Optionally, add a description and notes. +. To add filters, click *Add field*, and then select the required option: + +* _Add field_: Add a `regular` Timeline filter. +* _Add template field_: Add a template filter with a value placeholder. + +TIP: You can also drag and send items to the template from the *Overview*, +*Hosts*, *Network*, and *Detections* pages. + +*Example* + +To create a template for process-related alerts on a specific host: + +* Add an 'ordinary' filter for the host name: +`host.name: "Linux_stafordshire-061"` +* Add template filter for process names: `process.name: "{process.name}"` + +[role="screenshot"] +image::images/template-query-example.png[] + +When alerts generated by rules associated with this template are investigated +in Timeline, the host name is `Linux_stafordshire-061`, whereas the process name +value is retrieved from the alert's `process.name` field. + +[discrete] +[[man-templates-ui]] +=== Manage existing Timeline templates + +You can view, duplicate, delete, and create templates from existing Timelines: + +. Go to *Security* -> *Timelines*. +. Click the *Templates* tab. ++ +[role="screenshot"] +image::images/all-actions-timeline-ui.png[] + +. Click the *All actions* icon in the relevant row, and then select the action: + +* _Create timeline from template_ +* _Duplicate template_ +* _Delete template_ + +TIP: To perform the same action on multiple templates, select templates and +then the required action from the _Bulk actions_ menu. + +NOTE: You cannot delete prebuilt templates. + +[discrete] +=== Export and import Timeline templates + +You can import and export Timeline templates, which enables importing templates +from one {kib} space or instance to another. Exported templates are saved in an +http://ndjson.org[`ndjson`] file. + +. Go to *Security* -> *Timelines*. +. Click the *Templates* tab. +. To export templates, do one of the following: + +* To export one template, click the *All actions* icon in the relevant row and +then select _Export selected_. +* To export multiple templates, select all the required templates and then click +*Bulk actions* -> _Export selected_. + +. To import templates, click *Import Timeline* and then select or drap-and-drop +the template `ndjson` file. ++ +NOTE: Each template object in the file must be represented in a single line. +Multiple template objects are delimited with newlines. + +NOTE: You cannot export prebuilt templates. \ No newline at end of file diff --git a/docs/siem/timeline/timeline-ui-overview.asciidoc b/docs/siem/timeline/timeline-ui-overview.asciidoc new file mode 100644 index 0000000000..c85e186a81 --- /dev/null +++ b/docs/siem/timeline/timeline-ui-overview.asciidoc @@ -0,0 +1,165 @@ +[[timelines-ui]] +[role="xpack"] += Investigating events in Timeline + +Use Timeline as your workspace for investigations and threat hunting. +Data from multiple indices can be added to a Timeline, which enables +investigating complex threats. + +You can drag or send items of interest to Timeline to create the query you need +to investigate an alert or event. You can add items from tables and histograms +on the *Overview*, *Detections*, *Hosts* and *Network* pages, as well as from +within a Timeline itself. Additionally, you can add a query directly in Timeline +(click `+ Add field`). + +[role="screenshot"] +image::images/timeline-ui.png[] + +Timelines are responsive, and they persist as you move through the {es-sec-app} +collecting data. Auto-saving ensures that the results of your investigation are +available for review by other analysts and incident response teams. To record +and share your findings with others, attach your Timeline to a +<>. + +TIP: An untitled Timeline is saved as a draft. To attach a Timeline to a +<>, you must give it a title. + +In addition to Timelines, you can create and attach Timeline templates to +<>. Timeline templates allow you to +define the source event fields used when you investigate a detections alert in +Timeline. You can select whether the fields use predefined values or values +retrieved from the alert. For more information, see <>. + + +[discrete] +[[refine-timeline-results]] +== View and refine Timeline results + +Using the drop-down options +by the KQL bar, you can select whether <>, +other raw events, or both are displayed in the Timeline. + +[discrete] +[[conf-timeline-display]] +== Configure Timeline event context and display + +Many events in Timeline are presented in easy-to-follow rendered views that +include relevant contextual information. These views are called +*Event Renderers*, and they can be configured via the Settings icon in the upper +left corner of the result's pane: + +[role="screenshot"] +image::images/timeline-ui-renderer.png[] + +The example above displays a flow event renderer. If you see a particular item +that interests you, you can drag it to the dropzone for further investigation. + +Other display options include: + +* View in full screen mode +* Add, remove, reorder, and resize columns +* Add notes to individual events +* Add investigation notes for the entire Timeline +* Pin interesting events in the Timeline + +[discrete] +[[narrow-expand]] +== Narrow or expand your query + +You can specify logical `AND` and `OR` operations with an item's placement in +the drop area. Multiple horizontal filters use `AND` logic, vertical filters use +`OR`. + +[discrete] +[[pivot]] +== Edit existing filters + +Click a filter to access additional operations such as exclude, temporarily +disable, or delete items from the query: + +[role="screenshot"] +image::images/timeline-ui-filter-options.png[width=30%] + +This is how the filters appear in the UI: + +Field with value:: +Filters for events with the specified field value: ++ +[role="screenshot"] +image::images/timeline-filter-value.png[width=30%] + +Field exists:: +Filters for events containing the specified field: ++ +[role="screenshot"] +image::images/timeline-field-exists.png[width=30%] + +Exclude results:: +Filters for events that do not contain the specified field value +(`field with value` filter) or the specified field (`field exists` filter): ++ +[role="screenshot"] +image::images/timeline-filter-exclude.png[width=30%] + +Temporarily disable:: +The filter is not used in the query until it is enabled again: ++ +[role="screenshot"] +image::images/timeline-disable-filter.png[width=30%] + +Filter for field present:: +Converts a `field with value` filter to a `field exists` filter. + +NOTE: When you convert a <> to a +Timeline, some fields may be disabled. For more information, see +<>. + +[discrete] +[[timeline-to-cases-ui]] +== Attach Timeline to a case + +To attach a Timeline to a new or existing case, click the Settings in the upper +right corner, and then select one of these: + +* _Attach timeline to new case_ +* _Attach timeline to existing case_ + +For more information about cases, see <>. + +[discrete] +[[manage-timelines-ui]] +== Manage existing Timelines + +You can view, duplicate, delete, and create templates from existing Timelines: + +. Go to *Security* -> *Timelines*. +. Click the *All actions* icon in the relevant row, and then select the action: + +* _Create template from timeline_ (see <>) +* _Duplicate timeline_ +* _Delete timeline_ + +TIP: To perform the same action on multiple Timelines, select Timelines and +then the required action from the _Bulk actions_ menu. + +[discrete] +[[import-export-timelines]] +== Export and import Timelines + +You can import and export Timelines, which enables importing Timelines from one +{kib} space or instance to another. Exported Timelines are saved in an +http://ndjson.org[`ndjson`] file. + +. Go to *Security* -> *Timelines*. +. To export Timelines, do one of the following: + +* To export one Timeline, click the *All actions* icon in the relevant row and +then select _Export selected_. +* To export multiple Timelines, select all the required Timelines and then click +*Bulk actions* -> _Export selected_. + +. To import Timelines, click *Import Timeline* and then select or drap-and-drop +the Timeline `ndjson` file. ++ +NOTE: Each Timeline object in the file must be represented in a single line. +Multiple Timeline objects are delimited with newlines.