Interactive investigation guidesedit

This feature is available for Elastic 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 Timeline, using alert data and hard-coded literal values. This allows you to start detailed Timeline investigations directly from an alert using relevant data.

Alert details flyout with interactive investigation guide

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.

Timeline with query pre-loaded from investigation guide action

Add investigation guide actions to a ruleedit

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 create a new rule or 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.

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.

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

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 (Error icon) displays below the Markdown editor if there are any syntax errors.

Example syntaxedit

!{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>)

Timeline query

Timeline template fieldsedit

When viewing an interactive investigation guide in contexts unconnected to a specific alert (such a rule’s details page), queries open as Timeline templates, and parameter fields are treated as Timeline template fields.

Timeline template