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.

— Click to open this image in fullscreen mode

Under the Investigation section, click Show investigation guide to open the Investigation tab in the left panel of the alert details flyout.

— Click to open this image in fullscreen mode

The Investigation tab displays query buttons, and each query button displays the number of event documents found. Click the query button to automatically load the query in Timeline, based on configuration settings in the investigation guide.

— Click to open this image in fullscreen mode

Add investigation guide actions to a rule

You can configure an interactive investigation guide when you create a new rule or edit an existing rule.

1. 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 Markdown editor.

   

   — Click to open this image in fullscreen mode

2. Place the editor cursor where you want to add the query button in the investigation guide, then select the Investigate icon in the toolbar. The Add investigation query builder form appears.

   

   — Click to open this image in fullscreen mode

3. Complete the query builder form to create an investigation query:

   1. Label: Enter the text to appear on the query button.

   2. Description: (Optional) Enter additional text to include with the button.

   3. Filters: Select fields, operators, and values to build the query. Click OR or AND to create multiple filters and define their relationships.

      To use a field value from the alert as a query parameter, enter the field name surrounded by double curly brackets — such as {{kibana.alert.example}} — as a custom option for the filter value.

      

      — Click to open this image in fullscreen mode

   4. Relative time range: (Optional) Select a time range to limit the query, relative to the alert's creation time.

4. Click Save changes. The syntax is added to the investigation guide editor.

   Note

   If you need to change the query button's configuration, you can either edit the syntax directly in the editor (refer to the syntax reference below), or delete the syntax and use the query builder form to recreate the query.

5. Save and enable the rule.

Query button syntax

The following syntax defines a query button in an interactive investigation guide.

Example syntax

!{investigate{
  "label": "Test action",
  "description": "Click to investigate.",
  "providers": [
    [
      {"field": "event.id", "excluded": false, "queryType": "phrase", "value": "{{event.id}}", "valueType": "string"}
    ],
    [
      {"field": "event.action", "excluded": false, "queryType": "phrase", "value": "rename", "valueType": "string"},
      {"field": "process.pid", "excluded": false, "queryType": "phrase", "value": "{{process.pid}}", "valueType": "string"}
    ]
  ],
  "relativeFrom": "now-15m",
  "relativeTo": "now"
}}

This example creates the following Timeline query, as illustrated below:

(event.id : <alert value>) OR (event.action : "rename" AND process.pid : <alert value>)

— Click to open this image in fullscreen mode

Timeline template fields

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.

— Click to open this image in fullscreen mode