diff --git a/docs/detections/alerts-run-osquery.asciidoc b/docs/detections/alerts-run-osquery.asciidoc index 8d9bd1a447..95dab04a18 100644 --- a/docs/detections/alerts-run-osquery.asciidoc +++ b/docs/detections/alerts-run-osquery.asciidoc @@ -1,5 +1,5 @@ [[alerts-run-osquery]] -=== Run Osquery from a detection alert +== Run Osquery from a detection alert {kibana-ref}/osquery.html[Osquery] allows you to run live queries against an alert's host to learn more about your infrastructure and operating systems. For example, with Osquery, you can search your system for indicators of compromise that might have contributed to the alert. You can then use this data to form your investigation and alert triage efforts. [IMPORTANT] @@ -12,40 +12,63 @@ You must complete the following to access Osquery and run searches against your * Verify that {fleet-guide}/view-elastic-agent-status.html[{agent}'s status] is *Healthy*. Refer to {fleet-guide}/fleet-troubleshooting.html[{fleet} Troubleshooting] if it is not. ============ +[float] +[[osquery-alert-action]] +=== Run live queries . Do one of the following from the Alerts table: ** Click the *View details* button to open the Alert details flyout, then click *Take action -> Run Osquery*. ** Select the *More actions* menu (*...*), then select *Run Osquery*. +. Choose to run a single query or a query pack. . Select one or more {agent}s or groups to query. Start typing in the search field to get suggestions for {agent}s by name, ID, platform, and policy. + NOTE: The host associated with the alert is automatically selected. You can specify additional hosts to query. -+ - -. Enter a new query or select a saved query. +. Specify the query or pack to run: +** *Query*: Select a saved query or enter a new one in the text box. After you enter the query, you can expand the **Advanced** section to view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query. Mapping ECS fields is optional. +** *Pack*: Select from query packs that have been loaded and activated. After you select a pack, all of the queries in the pack are displayed. ++ +TIP: Refer to {kibana-ref}/osquery.html#osquery-prebuilt-packs-queries[prebuilt packs] to learn about using and managing Elastic prebuilt packs. + - [role="screenshot"] -image::images/setup-query.png[width=80%][height=80%][Shows how to set up the query] - -. (Optional) Expand the **Advanced** section to view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query. -. Click **Submit**. +image::images/setup-query.png[width=80%][height=80%][Shows how to set up a single query] +. Click **Submit**. Queries will timeout after 5 minutes if there are no responses. + TIP: To save the query for future use, click *Save for later* and define the ID, description, and other {kibana-ref}/osquery.html#osquery-manage-query[details]. -. Review the results in the table. You can also: -** Navigate to *Discover* to dive deeper into the response. -** Use the drag-and-drop *Lens* editor to create visualizations. -** Click the *Timeline* button (image:images/timeline-button-osquery.png[Click markdown icon,20,20]) to investigate a single query result in Timeline or *Add to timeline investigation* to investigate all results. +[float] +[[osquery-results-single]] +=== Review single query results + +Results for single queries appear in the *Results* tab. When you run a query, the number of agents queried and query status temporarily display in a status bar above the results table. Agent responses can be `Sucessful`, `Not yet responded` (pending), and `Failed`. + +[role="screenshot"] +image::images/single-query-results.png[width=80%][height=80%][Shows query results] + +[float] +[[osquery-results-pack]] +=== Review query pack results + +Results for each query in the pack appear in the *Results* tab. Click the expand button (image:images/pack-expand-button-osquery.png[Click markdown icon,20,20]) at the far right of each query row to display query results. The number of agents that were queried and their responses are shown for each query. Agent responses are color-coded. Green is `Sucessful`, `Not yet responded` (pending) is gray, and `Failed` is red. + +[role="screenshot"] +image::images/pack-query-results.png[width=80%][height=80%][Shows query results] + +[float] +[[osquery-investigate]] +=== Investigate query results + +From the results table, you can: + +* Click the *View in Discover* button (image:images/discover-button-osquery.png[Click markdown icon,20,20]) to explore the results in Discover. +* Click the *View in Lens* button (image:images/lens-button-osquery.png[Click markdown icon,20,20]) to navigate to Lens, where you can use the drag-and-drop *Lens* editor to create visualizations. +* Click the *Timeline* button (image:images/timeline-button-osquery.png[Click markdown icon,20,20]) to investigate a single query result in Timeline or *Add to timeline investigation* to investigate all results. This option is only available for single query results. + -TIP: An `action_ID` is generated when you run an Osquery query. The `action_ID` field and value pair is passed to the Timeline's KQL filter when you select the option to open all results in Timeline. +When you open all results in Timeline, the events in Timeline are filtered based on the `action_ID` generated by the Osquery query. + -. To view more information about the request, such as failures, open the *Status* tab in the results table. -+ -[role="screenshot"] -image::images/query-results.png[width=80%][height=80%][Shows query results] +* View more information about the request, such as failures, by opening the *Status* tab. diff --git a/docs/detections/images/discover-button-osquery.png b/docs/detections/images/discover-button-osquery.png new file mode 100644 index 0000000000..599f3f3578 Binary files /dev/null and b/docs/detections/images/discover-button-osquery.png differ diff --git a/docs/detections/images/lens-button-osquery.png b/docs/detections/images/lens-button-osquery.png new file mode 100644 index 0000000000..92c79f0f20 Binary files /dev/null and b/docs/detections/images/lens-button-osquery.png differ diff --git a/docs/detections/images/pack-expand-button-osquery.png b/docs/detections/images/pack-expand-button-osquery.png new file mode 100644 index 0000000000..11e2015640 Binary files /dev/null and b/docs/detections/images/pack-expand-button-osquery.png differ diff --git a/docs/detections/images/pack-query-results.png b/docs/detections/images/pack-query-results.png new file mode 100644 index 0000000000..b699db2e8c Binary files /dev/null and b/docs/detections/images/pack-query-results.png differ diff --git a/docs/detections/images/query-results.png b/docs/detections/images/query-results.png deleted file mode 100644 index d8db7723f7..0000000000 Binary files a/docs/detections/images/query-results.png and /dev/null differ diff --git a/docs/detections/images/setup-query.png b/docs/detections/images/setup-query.png index 19d34f63e9..b4c8b1c4da 100644 Binary files a/docs/detections/images/setup-query.png and b/docs/detections/images/setup-query.png differ diff --git a/docs/detections/images/single-query-results.png b/docs/detections/images/single-query-results.png new file mode 100644 index 0000000000..963efdf438 Binary files /dev/null and b/docs/detections/images/single-query-results.png differ diff --git a/docs/detections/images/timeline-button-osquery.png b/docs/detections/images/timeline-button-osquery.png index 280d98dc6f..61186c09eb 100644 Binary files a/docs/detections/images/timeline-button-osquery.png and b/docs/detections/images/timeline-button-osquery.png differ