Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
6dbccf4
First draft
nastasha-solomon Aug 3, 2022
79ffd0c
Content adjustments
nastasha-solomon Aug 3, 2022
d3ed9b3
Fixed headers
nastasha-solomon Aug 3, 2022
26092d1
Added images and content
nastasha-solomon Aug 4, 2022
f0620cc
Additional content
nastasha-solomon Aug 4, 2022
9962e96
Edits
nastasha-solomon Aug 4, 2022
8d44943
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 5, 2022
d39294b
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 12, 2022
43203f6
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 12, 2022
e1eecaf
Update docs/detections/alerts-run-osquery.asciidoc
nastasha-solomon Aug 12, 2022
e54eb04
Update docs/detections/alerts-run-osquery.asciidoc
nastasha-solomon Aug 12, 2022
e49ea5d
Update docs/detections/alerts-run-osquery.asciidoc
nastasha-solomon Aug 12, 2022
a1d4829
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 16, 2022
36db70c
Revised section about single queries
nastasha-solomon Aug 16, 2022
cc73fa2
Cropped extra space in images
nastasha-solomon Aug 16, 2022
9cb4c26
Update docs/detections/alerts-run-osquery.asciidoc
nastasha-solomon Aug 16, 2022
9479ea2
Updating title
nastasha-solomon Aug 16, 2022
d33e16f
Fixed images
nastasha-solomon Aug 17, 2022
5dc3ed8
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 18, 2022
5d319ae
Update docs/detections/alerts-run-osquery.asciidoc
nastasha-solomon Aug 18, 2022
ed855da
Update docs/detections/alerts-run-osquery.asciidoc
nastasha-solomon Aug 18, 2022
8004624
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 22, 2022
d77613a
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 23, 2022
40d2805
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 23, 2022
9dc9fad
Merge branch 'main' into issue-2231-osquery-packs
nastasha-solomon Aug 23, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 41 additions & 18 deletions docs/detections/alerts-run-osquery.asciidoc
Original file line number Diff line number Diff line change
@@ -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]
Expand All @@ -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.
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/detections/images/lens-button-osquery.png
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.
Binary file added docs/detections/images/pack-query-results.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/detections/images/query-results.png
Binary file not shown.
Binary file modified docs/detections/images/setup-query.png
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.
Binary file modified docs/detections/images/timeline-button-osquery.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.