From 184aa238bc2bf3d92cc1322d1a06f714700d20ff Mon Sep 17 00:00:00 2001 From: kruskall <99559985+kruskall@users.noreply.github.com> Date: Wed, 12 Jun 2024 23:30:26 +0200 Subject: [PATCH 1/2] fix: remove ndjson.org (#5376) * fix: replace ndjson.org with ndjson spec the original website expired and it's currently serving malicious content. * Removing link * capitalization fix --------- Co-authored-by: nastasha.solomon Co-authored-by: Joe Peeples (cherry picked from commit 5beed294033b8f262ce0b63b4d95bbda21334fe8) # Conflicts: # docs/serverless/investigate/timeline-templates-ui.mdx # docs/serverless/investigate/timelines-ui.mdx --- docs/events/timeline-templates.asciidoc | 3 +- docs/events/timeline-ui-overview.asciidoc | 3 +- docs/getting-started/siem-ui.asciidoc | 3 +- .../investigate/timeline-templates-ui.mdx | 157 ++++++++++++ docs/serverless/investigate/timelines-ui.mdx | 241 ++++++++++++++++++ 5 files changed, 401 insertions(+), 6 deletions(-) create mode 100644 docs/serverless/investigate/timeline-templates-ui.mdx create mode 100644 docs/serverless/investigate/timelines-ui.mdx diff --git a/docs/events/timeline-templates.asciidoc b/docs/events/timeline-templates.asciidoc index 5027c6018a..69019cf2f1 100644 --- a/docs/events/timeline-templates.asciidoc +++ b/docs/events/timeline-templates.asciidoc @@ -136,8 +136,7 @@ NOTE: You cannot delete prebuilt templates. === 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. +from one {kib} space or instance to another. Exported templates are saved in an `ndjson` file. . Go to *Timelines* -> *Templates*. . To export templates, do one of the following: diff --git a/docs/events/timeline-ui-overview.asciidoc b/docs/events/timeline-ui-overview.asciidoc index 27ccc06304..c103caf87d 100644 --- a/docs/events/timeline-ui-overview.asciidoc +++ b/docs/events/timeline-ui-overview.asciidoc @@ -158,8 +158,7 @@ then select an action from the *Bulk actions* menu. == Export and import Timelines You can export and import Timelines, which enables you to share Timelines from one -{kib} space or instance to another. Exported Timelines are saved as -http://ndjson.org[`.ndjson`] files. +{kib} space or instance to another. Exported Timelines are saved as `.ndjson` files. To export Timelines: diff --git a/docs/getting-started/siem-ui.asciidoc b/docs/getting-started/siem-ui.asciidoc index 5c5b024182..6e0657d484 100644 --- a/docs/getting-started/siem-ui.asciidoc +++ b/docs/getting-started/siem-ui.asciidoc @@ -299,8 +299,7 @@ drop area for further introspection. ==== 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. +{kib} space or instance to another. Exported Timelines are saved in an `ndjson` file. . Go to *SIEM* -> *Timelines*. . To export timelines, do one of the following: diff --git a/docs/serverless/investigate/timeline-templates-ui.mdx b/docs/serverless/investigate/timeline-templates-ui.mdx new file mode 100644 index 0000000000..f225630402 --- /dev/null +++ b/docs/serverless/investigate/timeline-templates-ui.mdx @@ -0,0 +1,157 @@ +--- +slug: /serverless/security/timeline-templates-ui +title: Create Timeline templates +description: Attach Timeline templates to detection rules to streamline investigations. +tags: [ 'serverless', 'security', 'how-to', 'analyze', 'manage' ] +status: in review +--- + + +
+ +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 types of filters: + +* **Regular filter**: Like other 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"`. + + +For information on how to add Timeline templates to rules, refer to Create a detection rule. + + +When you load ((elastic-sec)) prebuilt rules, ((elastic-sec)) also loads a selection of prebuilt Timeline templates, which you can attach to detection rules. **Generic** templates use broad KQL queries to retrieve event data, and **Comprehensive** templates use detailed KQL queries to retrieve additional information. The following prebuilt templates appear by default: + +* **Alerts Involving a Single Host Timeline**: Investigate detection alerts involving a single host. +* **Alerts Involving a Single User Timeline**: Investigate detection alerts involving a single user. +* **Generic Endpoint Timeline**: Investigate ((elastic-endpoint)) detection alerts. +* **Generic Network Timeline**: Investigate network-related detection alerts. +* **Generic Process Timeline**: Investigate process-related detection alerts. +* **Generic Threat Match Timeline**: Investigate threat indicator match detection alerts. +* **Comprehensive File Timeline**: Investigate file-related detection alerts. +* **Comprehensive Network Timeline**: Investigate network-related detection alerts. +* **Comprehensive Process Timeline**: Investigate process-related detection alerts. +* **Comprehensive Registry Timeline**: Investigate registry-related detection alerts. + + +You can duplicate prebuilt templates and use them as +a starting point for your own custom templates. + + +
+ +## Timeline template legend + +When you add filters to a Timeline 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 + : Clicking **Convert to template field** changes the filter to a template filter: + + + +Template filter + + : + When you convert a template to a Timeline, template filters with placeholders are disabled: + + + + To enable the filter, either specify a value or change it to a field's existing filter (refer to Edit existing filters). + +
+ +## Create a Timeline template + +1. Choose one of the following: + * Go to **Investigations** → **Timelines**. Click the **Templates** tab, then click **Create new Timeline template**. + * Go to the Timeline bar (which is at the bottom of most pages), click the button, then click **Create new Timeline template**. + * From an open Timeline or Timeline template, click **New** → **New Timeline template**. + +1. Add filters to the new Timeline template. Click **Add field**, and select the required option: + + * **Add field**: Add a regular Timeline filter. + * **Add template field**: Add a template filter with a value placeholder. + + + You can also drag and send items to the template from the **Overview**, **Hosts**, **Network**, and **Alerts** pages. + + + ![An example of a Timeline filter](../images/timeline-templates-ui/-events-create-a-timeline-filter.png) + +1. Click **Save** to give the template a title and description. + +**Example** + +To create a template for process-related alerts on a specific host: + +* Add a regular filter for the host name: + `host.name: "Linux_stafordshire-061"` + +* Add template filter for process names: `process.name: "{process.name}"` + +![](../images/timeline-templates-ui/-events-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. + +
+ +## Manage existing Timeline templates + +You can view, duplicate, export, delete, and create templates from existing Timelines: + +1. Go to **Investigations** → **Timelines** → **Templates**. + + ![](../images/timeline-templates-ui/-events-all-actions-timeline-ui.png) + +1. Click the **All actions** icon in the relevant row, and then select the action: + + * **Create timeline from template** (refer to Create a Timeline template) + * **Duplicate template** + * **Export selected** (refer to Export and import Timeline templates) + * **Delete selected** + * **Create query rule from timeline** (only available if the Timeline contains a KQL query) + * **Create EQL rule from timeline** (only available if the Timeline contains an EQL query) + + +To perform the same action on multiple templates, select templates, then the required action from the **Bulk actions** menu. + + + +You cannot delete prebuilt templates. + + +
+ +## Export and import Timeline templates + +You can import and export Timeline templates, which enables importing templates from one {/*space or (*/}((elastic-sec)) instance to another. Exported templates are saved in an `ndjson` file. + +1. Go to **Investigations** → **Timelines** → **Templates**. +1. 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**. + +1. To import templates, click **Import**, then select or drag and drop the template `ndjson` file. + + + Each template object in the file must be represented in a single line. + Multiple template objects are delimited with newlines. + + + +You cannot export prebuilt templates. + + diff --git a/docs/serverless/investigate/timelines-ui.mdx b/docs/serverless/investigate/timelines-ui.mdx new file mode 100644 index 0000000000..93dc327bea --- /dev/null +++ b/docs/serverless/investigate/timelines-ui.mdx @@ -0,0 +1,241 @@ +--- +slug: /serverless/security/timelines-ui +title: Investigate events in Timeline +description: Investigate events and complex threats in your network. +tags: [ 'serverless', 'security', 'how-to', 'analyze', 'manage' ] +status: in review +--- + + +
+ +Use Timeline as your workspace for investigations and threat hunting. +You can add alerts from multiple indices to a Timeline to facilitate advanced investigations. + +You can drag or send fields of interest to a Timeline to create the desired query. For example, you can add fields from tables and histograms +on the **Overview**, **Alerts**, **Hosts**, and **Network** pages, as well as from +other Timelines. Alternatively, you can add a query directly in Timeline +by expanding the query builder and clicking **+ Add field**. + +![example Timeline with several events](../images/timelines-ui/-events-timeline-ui-updated.png) + +In addition to Timelines, you can create and attach Timeline templates to +detection rules. Timeline templates allow you to +define the source event fields used when you investigate alerts in +Timeline. You can select whether the fields use predefined values or values +retrieved from the alert. For more information, refer to Create Timeline templates. + +
+ +## Create new or open existing Timeline + +To make a new Timeline, choose one of the following: + +* Go to the Timelines page (**Investigations** → **Timelines**), then click **Create new Timeline**. +* Go to the Timeline bar (which is at the bottom of most pages), click the button, then click **Create new Timeline**. +* From an open Timeline or Timeline template, click **New** → **New Timeline**. + +To open an existing Timeline, choose one of the following: +* Go to the Timelines page, then click a Timeline's title. +* Go to the Timeline bar, click the button, then click **Open Timeline**. +* From an open Timeline or Timeline template, click **Open**, then select the appropriate Timeline. + +To avoid losing your changes, you must save the Timeline before moving to a different ((security-app)) page. If you change an existing Timeline, you can use the **Save as new timeline** toggle to make a new copy of the Timeline, without overwriting the original one. + + +Click the star icon () to favorite your Timeline and quickly find it later. + + +
+ +## View and refine Timeline results + +You can select whether Timeline displays detection alerts and other raw events, or just alerts. By default, Timeline displays both raw events and alerts. To hide raw events and display alerts only, click **Data view** to the left of the KQL query bar, then select **Show only detection alerts**. + +
+ +## Inspect an event or alert +To further inspect an event or detection alert, click the **View details** button. A flyout with event or alert details appears. + +
+ +## Configure Timeline event context and display + +Many types of events automatically appear in preconfigured views that provide relevant +contextual information, called **Event Renderers**. You can display and turn them on or off +with the Settings menu in the upper left corner of the results pane: + +![example timeline with the event renderer highlighted](../images/timelines-ui/-events-timeline-ui-renderer.png) + +The example above displays the Flow event renderer, which highlights the movement of +data between its source and destination. If you see a particular part of the rendered event that +interests you, you can drag it up to the drop zone below the query bar for further investigation. + +You can also modify a Timeline's display in other ways: + +* Add, remove, reorder, or resize columns +* Create runtime fields and display them in the Timeline +* View the Timeline in full screen mode +* Add or delete notes on individual events +* Add or delete investigation notes on the entire Timeline +* Pin interesting events to the Timeline + +
+ +## Use the Timeline query builder + +Expand the query builder by clicking the query builder button () to the right of the KQL query bar. Drop in fields to build a query that filters Timeline results. The fields' relative placement specifies their logical relationships: horizontally adjacent filters use `AND`, while vertically adjacent filters use `OR`. + + +Collapse the query builder and provide more space for Timeline results by clicking the query builder button (). + + +
+ +## Edit existing filters + +Click a filter to access additional operations such as **Add filter**, **Clear all**, **Load saved query**, and more: + + + +Here are examples of various types of filters: + +Field with value + : Filters for events with the specified field value: + + + +Field exists + : Filters for events containing the specified field: + + + +Exclude results + : Filters for events that do not contain the specified field value + (`field with value` filter) or the specified field (`field exists` filter): + + + +Temporarily disable + : The filter is not used in the query until it is enabled again: + + + +Filter for field present + : Converts a `field with value` filter to a `field exists` filter. + + +When you convert a Timeline template to a +Timeline, some fields may be disabled. For more information, refer to +Timeline template legend. + + +
+ +## Attach Timeline to a case + +To attach a Timeline to a new or existing case, open it, click **Attach to case** in the upper right corner, +then select either **Attach to new case** or **Attach to existing case**. + +To learn more about cases, refer to Cases. + +
+ +## Manage existing Timelines + +You can view, duplicate, export, delete, and create templates from existing Timelines: + +1. Go to **Investigations** → **Timelines**. +1. Click the **All actions** menu in the desired row, then select an action: + +* **Create template from timeline** (refer to Create Timeline templates) +* **Duplicate timeline** +* **Export selected** (refer to Export and import Timelines) +* **Delete selected** +* **Create query rule from timeline** (only available if the Timeline contains a KQL query) +* **Create EQL rule from timeline** (only available if the Timeline contains an EQL query) + + +To perform an action on multiple Timelines, first select the Timelines, +then select an action from the **Bulk actions** menu. + + +
+ +## Export and import Timelines + +You can export and import Timelines, which enables you to share Timelines from one {/* space or */} ((elastic-sec)) instance to another. Exported Timelines are saved as `.ndjson` files. + +To export Timelines: + +* Go to **Investigations** → **Timelines**. +* Either click the **All actions** menu in the relevant row and select **Export selected**, or select multiple Timelines and then click **Bulk actions** → **Export selected**. + +To import Timelines: + +* Click **Import**, then select or drag and drop the relevant `.ndjson` file. + + + Multiple Timeline objects are delimited with newlines. + + +
+ +## Filter Timeline results with EQL +Use the **Correlation** tab to investigate Timeline results with [EQL queries](((ref))/eql.html). + +When forming EQL queries, you can write a basic query to return a list of events and alerts. Or, you can create sequences of EQL queries to view matched, ordered events across multiple event categories. Sequence queries are useful for identifying and predicting related events. They can also provide a more complete picture of potential adversary behavior in your environment, which you can use to create or update rules and detection alerts. + +The following image shows what matched ordered events look like in the Timeline table. Events that belong to the same sequence are matched together in groups and shaded red or blue. Matched events are also ordered from oldest to newest in each sequence. + +![a Timeline's correlation tab](../images/timelines-ui/-events-correlation-tab-eql-query.png) + +From the **Correlation** tab, you can also do the following: + +* Specify the date and time range that you want to investigate. +* Reorder the columns and choose which fields to display. +* Choose a data view and whether to show detection alerts only. + + +
+ +## Use ((esql)) to investigate events + +The [Elasticsearch Query Language (((esql)))](((ref))/esql.html) provides a powerful way to filter, transform, and analyze event data stored in ((es)). ((esql)) queries use "pipes" to manipulate and transform data in a step-by-step fashion. This approach allows you to compose a series of operations, where the output of one operation becomes the input for the next, enabling complex data transformations and analysis. + +You can use ((esql)) in Timeline by opening the **((esql))** tab. From there, you can: + +- Write an ((esql)) query to explore your events. For example, start with the following query, then iterate on it to tailor your results: + + ```esql + FROM .alerts-security.alerts-default,apm-*-transaction*,auditbeat-*,endgame-*,filebeat-*,logs-*,packetbeat-*,traces-apm*,winlogbeat-*,-*elastic-cloud-logs-* + | LIMIT 10 + | KEEP @timestamp, message, event.category, event.action, host.name, source.ip, destination.ip, user.name + ``` + + This query does the following: + + - It starts by querying documents within the Security alert index (`.alerts-security.alerts-default`) and indices specified in the Security data view. + - Then, the query limits the output to the top 10 results. + - Finally, it keeps the default Timeline fields (`@timestamp`, `message`, `event.category`, `event.action`, `host.name`, `source.ip`, `destination.ip`, and `user.name`) in the output. + + + When querying indices that tend to be large (for example, `logs-*`), performance can be impacted by the number of fields returned in the output. To optimize performance, we recommend using the [`KEEP`](((ref))/esql-commands.html#esql-keep) command to specify fields that you want returned. For example, add the clause `KEEP @timestamp, user.name` to the end of your query to specify that you only want the `@timestamp` and `user.name` fields returned. + + + + An error message displays when the query bar is empty. + + +- Click the help icon () on the far right side of the query editor to open the in-product reference documentation for all ((esql)) commands and functions. +- Visualize query results using Discover functionality. + + + +
+ +## Additional ((esql)) resources + +To get started using ((esql)), read the tutorial for [using ((esql)) in ((kib))](((ref))/esql-kibana.html). Much of the functionality available in ((kib)) is also available in Timeline. + +To find examples of using ((esql)) for threat hunting, check out [our blog](https://www.elastic.co/blog/introduction-to-esql-new-query-language-flexible-iterative-analytics). From 0dbdd4de8ab3d2d2bb894539b67b518da7e96f23 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 12 Jun 2024 21:32:27 +0000 Subject: [PATCH 2/2] Delete docs/serverless directory and its contents --- .../investigate/timeline-templates-ui.mdx | 157 ------------ docs/serverless/investigate/timelines-ui.mdx | 241 ------------------ 2 files changed, 398 deletions(-) delete mode 100644 docs/serverless/investigate/timeline-templates-ui.mdx delete mode 100644 docs/serverless/investigate/timelines-ui.mdx diff --git a/docs/serverless/investigate/timeline-templates-ui.mdx b/docs/serverless/investigate/timeline-templates-ui.mdx deleted file mode 100644 index f225630402..0000000000 --- a/docs/serverless/investigate/timeline-templates-ui.mdx +++ /dev/null @@ -1,157 +0,0 @@ ---- -slug: /serverless/security/timeline-templates-ui -title: Create Timeline templates -description: Attach Timeline templates to detection rules to streamline investigations. -tags: [ 'serverless', 'security', 'how-to', 'analyze', 'manage' ] -status: in review ---- - - -
- -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 types of filters: - -* **Regular filter**: Like other 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"`. - - -For information on how to add Timeline templates to rules, refer to Create a detection rule. - - -When you load ((elastic-sec)) prebuilt rules, ((elastic-sec)) also loads a selection of prebuilt Timeline templates, which you can attach to detection rules. **Generic** templates use broad KQL queries to retrieve event data, and **Comprehensive** templates use detailed KQL queries to retrieve additional information. The following prebuilt templates appear by default: - -* **Alerts Involving a Single Host Timeline**: Investigate detection alerts involving a single host. -* **Alerts Involving a Single User Timeline**: Investigate detection alerts involving a single user. -* **Generic Endpoint Timeline**: Investigate ((elastic-endpoint)) detection alerts. -* **Generic Network Timeline**: Investigate network-related detection alerts. -* **Generic Process Timeline**: Investigate process-related detection alerts. -* **Generic Threat Match Timeline**: Investigate threat indicator match detection alerts. -* **Comprehensive File Timeline**: Investigate file-related detection alerts. -* **Comprehensive Network Timeline**: Investigate network-related detection alerts. -* **Comprehensive Process Timeline**: Investigate process-related detection alerts. -* **Comprehensive Registry Timeline**: Investigate registry-related detection alerts. - - -You can duplicate prebuilt templates and use them as -a starting point for your own custom templates. - - -
- -## Timeline template legend - -When you add filters to a Timeline 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 - : Clicking **Convert to template field** changes the filter to a template filter: - - - -Template filter - - : - When you convert a template to a Timeline, template filters with placeholders are disabled: - - - - To enable the filter, either specify a value or change it to a field's existing filter (refer to Edit existing filters). - -
- -## Create a Timeline template - -1. Choose one of the following: - * Go to **Investigations** → **Timelines**. Click the **Templates** tab, then click **Create new Timeline template**. - * Go to the Timeline bar (which is at the bottom of most pages), click the button, then click **Create new Timeline template**. - * From an open Timeline or Timeline template, click **New** → **New Timeline template**. - -1. Add filters to the new Timeline template. Click **Add field**, and select the required option: - - * **Add field**: Add a regular Timeline filter. - * **Add template field**: Add a template filter with a value placeholder. - - - You can also drag and send items to the template from the **Overview**, **Hosts**, **Network**, and **Alerts** pages. - - - ![An example of a Timeline filter](../images/timeline-templates-ui/-events-create-a-timeline-filter.png) - -1. Click **Save** to give the template a title and description. - -**Example** - -To create a template for process-related alerts on a specific host: - -* Add a regular filter for the host name: - `host.name: "Linux_stafordshire-061"` - -* Add template filter for process names: `process.name: "{process.name}"` - -![](../images/timeline-templates-ui/-events-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. - -
- -## Manage existing Timeline templates - -You can view, duplicate, export, delete, and create templates from existing Timelines: - -1. Go to **Investigations** → **Timelines** → **Templates**. - - ![](../images/timeline-templates-ui/-events-all-actions-timeline-ui.png) - -1. Click the **All actions** icon in the relevant row, and then select the action: - - * **Create timeline from template** (refer to Create a Timeline template) - * **Duplicate template** - * **Export selected** (refer to Export and import Timeline templates) - * **Delete selected** - * **Create query rule from timeline** (only available if the Timeline contains a KQL query) - * **Create EQL rule from timeline** (only available if the Timeline contains an EQL query) - - -To perform the same action on multiple templates, select templates, then the required action from the **Bulk actions** menu. - - - -You cannot delete prebuilt templates. - - -
- -## Export and import Timeline templates - -You can import and export Timeline templates, which enables importing templates from one {/*space or (*/}((elastic-sec)) instance to another. Exported templates are saved in an `ndjson` file. - -1. Go to **Investigations** → **Timelines** → **Templates**. -1. 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**. - -1. To import templates, click **Import**, then select or drag and drop the template `ndjson` file. - - - Each template object in the file must be represented in a single line. - Multiple template objects are delimited with newlines. - - - -You cannot export prebuilt templates. - - diff --git a/docs/serverless/investigate/timelines-ui.mdx b/docs/serverless/investigate/timelines-ui.mdx deleted file mode 100644 index 93dc327bea..0000000000 --- a/docs/serverless/investigate/timelines-ui.mdx +++ /dev/null @@ -1,241 +0,0 @@ ---- -slug: /serverless/security/timelines-ui -title: Investigate events in Timeline -description: Investigate events and complex threats in your network. -tags: [ 'serverless', 'security', 'how-to', 'analyze', 'manage' ] -status: in review ---- - - -
- -Use Timeline as your workspace for investigations and threat hunting. -You can add alerts from multiple indices to a Timeline to facilitate advanced investigations. - -You can drag or send fields of interest to a Timeline to create the desired query. For example, you can add fields from tables and histograms -on the **Overview**, **Alerts**, **Hosts**, and **Network** pages, as well as from -other Timelines. Alternatively, you can add a query directly in Timeline -by expanding the query builder and clicking **+ Add field**. - -![example Timeline with several events](../images/timelines-ui/-events-timeline-ui-updated.png) - -In addition to Timelines, you can create and attach Timeline templates to -detection rules. Timeline templates allow you to -define the source event fields used when you investigate alerts in -Timeline. You can select whether the fields use predefined values or values -retrieved from the alert. For more information, refer to Create Timeline templates. - -
- -## Create new or open existing Timeline - -To make a new Timeline, choose one of the following: - -* Go to the Timelines page (**Investigations** → **Timelines**), then click **Create new Timeline**. -* Go to the Timeline bar (which is at the bottom of most pages), click the button, then click **Create new Timeline**. -* From an open Timeline or Timeline template, click **New** → **New Timeline**. - -To open an existing Timeline, choose one of the following: -* Go to the Timelines page, then click a Timeline's title. -* Go to the Timeline bar, click the button, then click **Open Timeline**. -* From an open Timeline or Timeline template, click **Open**, then select the appropriate Timeline. - -To avoid losing your changes, you must save the Timeline before moving to a different ((security-app)) page. If you change an existing Timeline, you can use the **Save as new timeline** toggle to make a new copy of the Timeline, without overwriting the original one. - - -Click the star icon () to favorite your Timeline and quickly find it later. - - -
- -## View and refine Timeline results - -You can select whether Timeline displays detection alerts and other raw events, or just alerts. By default, Timeline displays both raw events and alerts. To hide raw events and display alerts only, click **Data view** to the left of the KQL query bar, then select **Show only detection alerts**. - -
- -## Inspect an event or alert -To further inspect an event or detection alert, click the **View details** button. A flyout with event or alert details appears. - -
- -## Configure Timeline event context and display - -Many types of events automatically appear in preconfigured views that provide relevant -contextual information, called **Event Renderers**. You can display and turn them on or off -with the Settings menu in the upper left corner of the results pane: - -![example timeline with the event renderer highlighted](../images/timelines-ui/-events-timeline-ui-renderer.png) - -The example above displays the Flow event renderer, which highlights the movement of -data between its source and destination. If you see a particular part of the rendered event that -interests you, you can drag it up to the drop zone below the query bar for further investigation. - -You can also modify a Timeline's display in other ways: - -* Add, remove, reorder, or resize columns -* Create runtime fields and display them in the Timeline -* View the Timeline in full screen mode -* Add or delete notes on individual events -* Add or delete investigation notes on the entire Timeline -* Pin interesting events to the Timeline - -
- -## Use the Timeline query builder - -Expand the query builder by clicking the query builder button () to the right of the KQL query bar. Drop in fields to build a query that filters Timeline results. The fields' relative placement specifies their logical relationships: horizontally adjacent filters use `AND`, while vertically adjacent filters use `OR`. - - -Collapse the query builder and provide more space for Timeline results by clicking the query builder button (). - - -
- -## Edit existing filters - -Click a filter to access additional operations such as **Add filter**, **Clear all**, **Load saved query**, and more: - - - -Here are examples of various types of filters: - -Field with value - : Filters for events with the specified field value: - - - -Field exists - : Filters for events containing the specified field: - - - -Exclude results - : Filters for events that do not contain the specified field value - (`field with value` filter) or the specified field (`field exists` filter): - - - -Temporarily disable - : The filter is not used in the query until it is enabled again: - - - -Filter for field present - : Converts a `field with value` filter to a `field exists` filter. - - -When you convert a Timeline template to a -Timeline, some fields may be disabled. For more information, refer to -Timeline template legend. - - -
- -## Attach Timeline to a case - -To attach a Timeline to a new or existing case, open it, click **Attach to case** in the upper right corner, -then select either **Attach to new case** or **Attach to existing case**. - -To learn more about cases, refer to Cases. - -
- -## Manage existing Timelines - -You can view, duplicate, export, delete, and create templates from existing Timelines: - -1. Go to **Investigations** → **Timelines**. -1. Click the **All actions** menu in the desired row, then select an action: - -* **Create template from timeline** (refer to Create Timeline templates) -* **Duplicate timeline** -* **Export selected** (refer to Export and import Timelines) -* **Delete selected** -* **Create query rule from timeline** (only available if the Timeline contains a KQL query) -* **Create EQL rule from timeline** (only available if the Timeline contains an EQL query) - - -To perform an action on multiple Timelines, first select the Timelines, -then select an action from the **Bulk actions** menu. - - -
- -## Export and import Timelines - -You can export and import Timelines, which enables you to share Timelines from one {/* space or */} ((elastic-sec)) instance to another. Exported Timelines are saved as `.ndjson` files. - -To export Timelines: - -* Go to **Investigations** → **Timelines**. -* Either click the **All actions** menu in the relevant row and select **Export selected**, or select multiple Timelines and then click **Bulk actions** → **Export selected**. - -To import Timelines: - -* Click **Import**, then select or drag and drop the relevant `.ndjson` file. - - - Multiple Timeline objects are delimited with newlines. - - -
- -## Filter Timeline results with EQL -Use the **Correlation** tab to investigate Timeline results with [EQL queries](((ref))/eql.html). - -When forming EQL queries, you can write a basic query to return a list of events and alerts. Or, you can create sequences of EQL queries to view matched, ordered events across multiple event categories. Sequence queries are useful for identifying and predicting related events. They can also provide a more complete picture of potential adversary behavior in your environment, which you can use to create or update rules and detection alerts. - -The following image shows what matched ordered events look like in the Timeline table. Events that belong to the same sequence are matched together in groups and shaded red or blue. Matched events are also ordered from oldest to newest in each sequence. - -![a Timeline's correlation tab](../images/timelines-ui/-events-correlation-tab-eql-query.png) - -From the **Correlation** tab, you can also do the following: - -* Specify the date and time range that you want to investigate. -* Reorder the columns and choose which fields to display. -* Choose a data view and whether to show detection alerts only. - - -
- -## Use ((esql)) to investigate events - -The [Elasticsearch Query Language (((esql)))](((ref))/esql.html) provides a powerful way to filter, transform, and analyze event data stored in ((es)). ((esql)) queries use "pipes" to manipulate and transform data in a step-by-step fashion. This approach allows you to compose a series of operations, where the output of one operation becomes the input for the next, enabling complex data transformations and analysis. - -You can use ((esql)) in Timeline by opening the **((esql))** tab. From there, you can: - -- Write an ((esql)) query to explore your events. For example, start with the following query, then iterate on it to tailor your results: - - ```esql - FROM .alerts-security.alerts-default,apm-*-transaction*,auditbeat-*,endgame-*,filebeat-*,logs-*,packetbeat-*,traces-apm*,winlogbeat-*,-*elastic-cloud-logs-* - | LIMIT 10 - | KEEP @timestamp, message, event.category, event.action, host.name, source.ip, destination.ip, user.name - ``` - - This query does the following: - - - It starts by querying documents within the Security alert index (`.alerts-security.alerts-default`) and indices specified in the Security data view. - - Then, the query limits the output to the top 10 results. - - Finally, it keeps the default Timeline fields (`@timestamp`, `message`, `event.category`, `event.action`, `host.name`, `source.ip`, `destination.ip`, and `user.name`) in the output. - - - When querying indices that tend to be large (for example, `logs-*`), performance can be impacted by the number of fields returned in the output. To optimize performance, we recommend using the [`KEEP`](((ref))/esql-commands.html#esql-keep) command to specify fields that you want returned. For example, add the clause `KEEP @timestamp, user.name` to the end of your query to specify that you only want the `@timestamp` and `user.name` fields returned. - - - - An error message displays when the query bar is empty. - - -- Click the help icon () on the far right side of the query editor to open the in-product reference documentation for all ((esql)) commands and functions. -- Visualize query results using Discover functionality. - - - -
- -## Additional ((esql)) resources - -To get started using ((esql)), read the tutorial for [using ((esql)) in ((kib))](((ref))/esql-kibana.html). Much of the functionality available in ((kib)) is also available in Timeline. - -To find examples of using ((esql)) for threat hunting, check out [our blog](https://www.elastic.co/blog/introduction-to-esql-new-query-language-flexible-iterative-analytics).