Skip to content

Commit

Permalink
[8.15 & Serverless] Update the Security Timeline Documentation in acc…
Browse files Browse the repository at this point in the history
…ordance with new Unified Timeline changes (#5505)

* First draft

* Fix broken image ref

* Runtime fields

* Updated timeline schema

* fixed file ext

* Updates Serverless Timeline docs

* Second batch of Serverless updates

* Fixed typos

* Fixed syntax and image ref

* Made images larger

* One more update to size

* Update docs/serverless/investigate/timelines-ui.mdx

Co-authored-by: Jatin Kathuria <jtn.kathuria@gmail.com>

* Update docs/events/timeline-ui-overview.asciidoc

Co-authored-by: Jatin Kathuria <jtn.kathuria@gmail.com>

* Fixed serverless section

* Minor edits

* More input from dev review

* Updating list in serverless docs

* Updating images for corr tab and temps

* Update docs/events/timeline-ui-overview.asciidoc

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>

* Update docs/events/timeline-ui-overview.asciidoc

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>

* Update docs/events/timeline-ui-overview.asciidoc

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>

* Nat's edits

* Renamed image for timeline template

* Corrected file name one more time

---------

Co-authored-by: Jatin Kathuria <jtn.kathuria@gmail.com>
Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>
(cherry picked from commit 1fe3f9e)

# Conflicts:
#	docs/serverless/explore/runtime-fields.mdx
#	docs/serverless/images/interactive-investigation-guides/-detections-ig-timeline.png
#	docs/serverless/images/timeline-object-schema/-reference-timeline-object-ui.png
#	docs/serverless/images/timelines-ui/-events-correlation-tab-eql-query.png
#	docs/serverless/images/timelines-ui/-events-timeline-ui-filter-options.png
#	docs/serverless/images/timelines-ui/-events-timeline-ui-renderer.png
#	docs/serverless/images/timelines-ui/-events-timeline-ui-updated.png
#	docs/serverless/investigate/timeline-templates-ui.mdx
#	docs/serverless/investigate/timelines-ui.mdx
  • Loading branch information
nastasha-solomon authored and mergify[bot] committed Jul 23, 2024
1 parent 8048133 commit 9c41ade
Show file tree
Hide file tree
Showing 28 changed files with 497 additions and 10 deletions.
Binary file modified docs/detections/images/ig-timeline.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/events/images/add-field-button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/events/images/correlation-tab-eql-query.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/events/images/create-a-timeline-filter.png
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/events/images/customize-event-renderers.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/events/images/remove-field-button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/events/images/timeline-sidebar.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/events/images/timeline-ui-filter-options.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/events/images/timeline-ui-renderer.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/events/images/timeline-ui-updated.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/events/timeline-templates.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ filter (refer to <<pivot>>).
* *Add template field*: Add a template filter with a value placeholder.
+
[role="screenshot"]
image::images/create-a-timeline-filter.png[Shows an example of a Timeline filter]
image::images/create-a-timeline-template-field.png[Shows an example of a Timeline template]
+
TIP: You can also drag and send items to the template from the *Overview*,
*Hosts*, *Network*, and *Alerts* pages.
Expand Down
21 changes: 17 additions & 4 deletions docs/events/timeline-ui-overview.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,7 @@ To further inspect an event or detection alert, click the *View details* button.
== 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:
contextual information, called *Event renderers*. All event renderers are turned off by default. To turn them on, use the **Event renderers** toggle at the top of the results pane. To only turn on specific event renderers, click the gear (image:images/customize-event-renderers.png[The customize event renderer button,20,20]) icon next to the toggle, and select the ones you want enabled. Close the **Customize event renderers** pane when you're done. Your changes are automatically applied to Timeline.

[role="screenshot"]
image::images/timeline-ui-renderer.png[example timeline with the event renderer highlighted]
Expand All @@ -67,13 +66,27 @@ interests you, you can drag it up to the drop zone below the query bar for furth

You can also modify a Timeline's display in other ways:

* Add, remove, reorder, or resize columns
* Create <<runtime-fields,runtime fields>> and display them in the Timeline
* <<add-remove-timeline-fields,Add and remove fields>> from Timeline
* Create <<runtime-fields,runtime fields>> and display them in Timeline
* Reorder and resize columns
* Copy a column name or values to a clipboard
* Change how the name, value, and description of a field are displayed in 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

[discrete]
[[add-remove-timeline-fields]]
== Add and remove fields from Timeline

The Timeline table shows fields that are available for alerts and events in the selected data view. You can modify the table to display fields that interest you. Use the sidebar to search for specific fields or scroll through it to find fields of interest. Fields that you select display as columns in the table.

To add a field from the sidebar, hover over it, and click the **Add field as a column** button (image:images/add-field-button.png[The button that lets you to add a field as a column,20,20]), or drag and drop the field into the table. To remove a field, hover over it, and click the **Remove field as a column** button (image:images/remove-field-button.png[The button that lets you to remove a field as a column,20,20]).

[role="screenshot"]
image::images/timeline-sidebar.png[Shows the sidebar that allows you to configure the columns that display in Timeline]

[discrete]
[[narrow-expand]]
== Use the Timeline query builder
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/reference/images/timeline-object-ui.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
11 changes: 6 additions & 5 deletions docs/reference/runtime-fields.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,17 @@ To create a runtime field:

. Go to a page that lists alerts or events (for example, *Alerts* or *Timelines* -> *_Name of Timeline_*).

. Click the *Fields* toolbar button in the table's upper-left. The *Fields* browser opens.
. Do one of the following:
** In the Alerts table, click the *Fields* toolbar button in the table's upper-left. From the *Fields* browser, click *Create field*. The *Create field* flyout opens.
+
[role="screenshot"]
image::images/fields-browser.png[Fields browser]

. Click *Create field*. The *Create field* flyout opens.
+
** In Timeline, go to the bottom of the sidebar, then click *Add a field*. The *Create field* flyout opens.
+
[role="screenshot"]
image::images/create-field-flyout.png[Create field flyout]

image::images/create-runtime-fields-timeline.png[Create runtime fields button in Timeline]
+
. Enter a *Name* for the new field.

. Select a *Type* for the field's data type.
Expand Down
63 changes: 63 additions & 0 deletions docs/serverless/explore/runtime-fields.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
slug: /serverless/security/runtime-fields
title: Create runtime fields in ((elastic-sec))
description: Create, edit, or delete runtime fields in ((elastic-sec)).
tags: [ 'serverless', 'security', 'how-to', 'manage' ]
status: in review
---

<DocBadge template="technical preview" />
<div id="runtime-fields"></div>

Runtime fields are fields that you can add to documents after you've ingested your data. For example, you could combine two fields and treat them as one, or perform calculations on existing data and use the result as a separate field. Runtime fields are evaluated when a query is run.

You can create a runtime field and add it to your detection alerts or events from any page that lists alerts or events in a data grid table, such as **Alerts**, **Timelines**, **Hosts**, and **Users**. Once created, the new field is added to the current <DocLink slug="/serverless/security/data-views-in-sec">data view</DocLink> and becomes available to all ((elastic-sec)) alerts and events in the data view.

<DocCallOut title="Note">
Runtime fields can impact performance because they're evaluated each time a query runs. Refer to [Runtime fields](((ref))/runtime.html) for more information.
</DocCallOut>

To create a runtime field:

1. Go to a page that lists alerts or events (for example, **Alerts** or **Timelines****_Name of Timeline_**).

1. Do one of the following:

* In the Alerts table, click the **Fields** toolbar button in the table's upper-left. From the **Fields** browser, click **Create field**. The **Create field** flyout opens.

![Fields browser](../images/runtime-fields/-reference-fields-browser.png)

* In Timeline, go to the bottom of the sidebar, then click **Add a field**. The **Create field** flyout opens.

![Create runtime fields button in Timeline](../images/runtime-fields/-reference-create-runtime-fields-timeline.png)

1. Enter a **Name** for the new field.

1. Select a **Type** for the field's data type.

1. Turn on the **Set value** toggle and enter a [Painless script](((ref))/modules-scripting-painless.html) to define the field's value. The script must match the selected **Type**. For more on adding fields and Painless scripting examples, refer to [Explore your data with runtime fields](((kibana-ref))/managing-data-views.html#runtime-fields).

1. Use the **Preview** to help you build the script so it returns the expected field value.

1. Configure other field settings as needed.

<DocCallOut title="Note">
Some runtime field settings, such as custom labels and display formats, might display differently in some areas of the ((elastic-sec)) UI.
</DocCallOut>

1. Click **Save**. The new field appears as a new column in the data grid.

<div id="manage-runtime-fields"></div>

## Manage runtime fields

You can edit or delete existing runtime fields from the **Alerts**, **Timelines**, **Hosts**, and **Users** pages.

1. Click the **Fields** button to open the **Fields** browser, then search for the runtime field you want.

<DocCallOut title="Tip">
Click the **Runtime** column header twice to reorder the fields table with all runtime fields at the top.
</DocCallOut>

1. In the **Actions** column, select an option to edit or delete the runtime field.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
157 changes: 157 additions & 0 deletions docs/serverless/investigate/timeline-templates-ui.mdx
Original file line number Diff line number Diff line change
@@ -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
---

<DocBadge template="technical preview" />
<div id="timeline-templates-ui"></div>

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"`.

<DocCallOut title="Note">
For information on how to add Timeline templates to rules, refer to <DocLink slug="/serverless/security/rules-create">Create a detection rule</DocLink>.
</DocCallOut>

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.

<DocCallOut title="Tip">
You can <DocLink slug="/serverless/security/timeline-templates-ui" section="manage-existing-timeline-templates">duplicate prebuilt templates</DocLink> and use them as
a starting point for your own custom templates.
</DocCallOut>

<div id="template-legend-ui"></div>

## 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:

<DocImage size="m" url="../images/timeline-templates-ui/-events-template-filter-value.png" alt="" />

Template filter

: <DocImage size="m" url="../images/timeline-templates-ui/-events-timeline-template-filter.png" alt="" />
When you <DocLink slug="/serverless/security/timeline-templates-ui" section="manage-existing-timeline-templates">convert a template to a Timeline</DocLink>, template filters with placeholders are disabled:

<DocImage size="m" url="../images/timeline-templates-ui/-events-invalid-filter.png" alt="" />

To enable the filter, either specify a value or change it to a field's existing filter (refer to <DocLink slug="/serverless/security/timelines-ui" section="edit-existing-filters">Edit existing filters</DocLink>).

<div id="create-timeline-template"></div>

## 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 <DocIcon type="plusInCircle" title="New Timeline" /> 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.

<DocCallOut title="Tip">
You can also drag and send items to the template from the **Overview**, **Hosts**, **Network**, and **Alerts** pages.
</DocCallOut>

![An example of a Timeline filter](../images/timeline-templates-ui/-events-create-a-timeline-template-field.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.

<div id="man-templates-ui"></div>

## 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 <DocLink slug="/serverless/security/timeline-templates-ui" section="create-a-timeline-template">Create a Timeline template</DocLink>)
* **Duplicate template**
* **Export selected** (refer to <DocLink slug="/serverless/security/timeline-templates-ui" section="export-and-import-timeline-templates">Export and import Timeline templates</DocLink>)
* **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)

<DocCallOut title="Tip">
To perform the same action on multiple templates, select templates, then the required action from the **Bulk actions** menu.
</DocCallOut>

<DocCallOut title="Note">
You cannot delete prebuilt templates.
</DocCallOut>

<div id="import-export-timeline-templates"></div>

## 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.

<DocCallOut title="Note">
Each template object in the file must be represented in a single line.
Multiple template objects are delimited with newlines.
</DocCallOut>

<DocCallOut title="Note">
You cannot export prebuilt templates.
</DocCallOut>

Loading

0 comments on commit 9c41ade

Please sign in to comment.