[DOCS] Osquery features in 8.5

docs/detections/alerts-run-osquery.asciidoc

@@ -1,20 +1,16 @@
 [[alerts-run-osquery]]
-== 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.
+== Run Osquery from alerts
+Run live queries on hosts associated with alerts 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 inform your investigation and alert triage efforts.
 
-[IMPORTANT]
-============
+.Requirements
+[sidebar]
+--
+* The {kibana-ref}/manage-osquery-integration.html[Osquery manager integration] must be installed.
+* {agent}'s {fleet-guide}/view-elastic-agent-status.html[status] must be `Healthy`. Refer to {fleet-guide}/fleet-troubleshooting.html[{fleet} Troubleshooting] if it isn't.
+* Your role must have {kibana-ref}/osquery.html[Osquery feature privileges].
+--
 
-You must complete the following to access Osquery and run searches against your hosts:
-
-* Enable the {kibana-ref}/manage-osquery-integration.html[Osquery manager integration] on the host associated with the alert.
-* Update your {kibana-ref}/osquery.html[role's privileges] to allow access to Osquery.
-* 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
+To run Osquery from an alert:
 
 . 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*.
@@ -27,48 +23,14 @@ NOTE: The host associated with the alert is automatically selected. You can spec
 
 . 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.
+** *Pack*: Select from available query packs. 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 a single query]
 
-. Click **Submit**. Queries will timeout after 5 minutes if there are no responses.
+. Click **Submit**. Queries will time out after 5 minutes if there are no responses. Otherwise, query results display within the flyout.
 +
-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].
-
-[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.
-
-+
-When you open all results in Timeline, the events in Timeline are filtered based on the `action_ID` generated by the Osquery query.
-+
-
-* View more information about the request, such as failures, by opening the *Status* tab.
+NOTE: Refer to <<view-osquery-results>> for more information about query results.
+. Click *Save for later* to save the query for future use (optional).

docs/detections/alerts-view-details.asciidoc

@@ -12,6 +12,7 @@ The alert details flyout contains these informational tabs:
 * *Threat Intel*: A list of individual threats matching the alert. <<alert-details-threat-intel, Learn more.>>
 * *Table*: The alert data in table format. Data is organized into field-value pairs.
 * *JSON*: The alert data in JSON format.
+* *Osquery Results*: Results from queries attached to rules display on the *Osquery Results* tab. <<add-osquery-response-action,Learn more.>>
 
 [role="screenshot"]
 image::images/alert-details-flyout.png[Alert details flyout, 90%]

docs/detections/detections-index.asciidoc

@@ -22,8 +22,6 @@ include::alerts-view-details.asciidoc[leveloffset=+1]
 
 include::alerts-add-to-cases.asciidoc[leveloffset=+1]
 
-include::alerts-run-osquery.asciidoc[]
-
 include::visual-event-analyzer.asciidoc[]
 
 include::session-view.asciidoc[]

docs/detections/invest-guide-run-osquery.asciidoc

@@ -0,0 +1,48 @@
+[[invest-guide-run-osquery]]
+== Run Osquery from investigation guides
+Detection rule investigation guides suggest steps for triaging, analyzing, and responding to potential security issues. When you build a custom rule, you can also set up an investigation guide that incorporates Osquery. This allows you to run live queries from a rule's investigation guide as you analyze alerts produced by the rule.
+
+.Requirements
+[sidebar]
+--
+* The {kibana-ref}/manage-osquery-integration.html[Osquery manager integration] must be installed.
+* {agent}'s {fleet-guide}/view-elastic-agent-status.html[status] must be `Healthy`. Refer to {fleet-guide}/fleet-troubleshooting.html[{fleet} Troubleshooting] if it isn't.
+* Your role must have {kibana-ref}/osquery.html[Osquery feature privileges].
+--
+
+[role="screenshot"]
+image::images/osquery-investigation-guide.png[Shows a live query in an investigation guide]
+
+[float]
+[[add-live-queries-ig]]
+=== Add live queries to an investigation guide
+
+NOTE: You can only add Osquery to investigation guides for custom rules because prebuilt rules cannot be edited.
+
+. Go to *Manage* -> *Rules*, select a rule, then click *Edit rule settings* on the rule details page.
+. Select the *About* tab, then expand the rule's advanced settings.
+. Scroll down to the Investigation guide section. In the toolbar, click the *Osquery* button (image:images/osquery-button.png[Click the Osquery button,20,20]).
+.. Add a descriptive label for the query; for example, `Search for executables`.
+.. Select a saved query or enter a new one.
+.. 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 (optional).
++
+[role="screenshot"]
+image::images/setup-osquery-investigation-guide.png[width=70%][height=70%][Shows results from running a query from an investigation guide]
+. Click *Save changes* to add the query to the rule's investigation guide.
+
+[float]
+[[run-live-queries-ig]]
+=== Run live queries from an investigation guide
+
+. Go to *Manage* -> *Rules*, then select a rule to open its details.
+. Go to the About section of the rule details page and click *Investigation guide*.
+. Click the query. The Run Osquery pane displays with the *Query* field autofilled. Do the following:
+.. 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.
+.. Expand the **Advanced** section to view or set the {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] which are included in the live query's results (optional).
+. Click *Submit* to run the query. Query results display in the flyout.
++
+NOTE: Refer to <<view-osquery-results>> for more information about query results.
+. Click *Save for later* to save the query for future use (optional).
++
+[role="screenshot"]
+image::images/run-query-investigation-guide.png[width=80%][height=80%][Shows results from running a query from an investigation guide]

docs/detections/osquery-response-action.asciidoc

@@ -0,0 +1,62 @@
+[[osquery-response-action]]
+== Add Osquery Response Actions
+preview::[]
+
+Osquery Response Actions allow you to add live queries to custom query rules so you can automatically collect data on systems the rule is monitoring. Use this data to support your alert triage and investigation efforts.
+
+.Requirements
+[sidebar]
+--
+* Osquery Response Actions require a https://www.elastic.co/pricing[Platinum or Enterprise subscription].
+* The {kibana-ref}/manage-osquery-integration.html[Osquery manager integration] must be installed.
+* {agent}'s {fleet-guide}/view-elastic-agent-status.html[status] must be `Healthy`. Refer to {fleet-guide}/fleet-troubleshooting.html[{fleet} Troubleshooting] if it isn't.
+* Your role must have {kibana-ref}/osquery.html[Osquery feature privileges].
+--
+
+[role="screenshot"]
+image::images/available-response-actions.png[Available response actions]
+
+[float]
+[[add-osquery-response-action]]
+=== Add Osquery Response Actions to rules
+
+You can add Osquery Response Actions to new or existing custom query rules. Queries run every time the rule executes.
+
+. Choose one of the following:
+** *New rule*: When you are on the last step of <<create-custom-rule,custom query rule>> creation, go to the Response Actions section and click the *osquery* icon.
+** *Existing rule*: Edit the rule's settings, then go to the *Actions* tab. In the tab, click the *osquery* icon under the Response Actions section.
+. Specify whether you want to set up a single live query or a pack:
+** *Query*: Select a saved query or enter a new one. 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 available query packs. 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-single-query.png[Shows how to set up a single query]
++
+
+. Click the *osquery* icon to add more live queries (optional).
+. Click **Create & enable rule** (for a new rule) or **Save changes** (for existing rules) to finish adding the queries.
+
+[float]
+[[edit-osquery-response-action]]
+=== Edit Osquery Response Actions
+
+If you want to choose a different query or query pack for the Osquery Response Action to use, edit the rule to update the Response Action.
+
+IMPORTANT: If you edited a saved query or query pack that an Osquery Response Action is using, you must reselect the saved query or query pack on the related Osquery Response Action. Query changes are not automatically applied to Osquery Response Actions.
+
+. Edit the rule's settings, then go to the *Actions* tab.
+. Modify the settings for Osquery Response Actions you've added.
+. Click *Save changes*.
+
+[float]
+[[find-osquery-response-action-results]]
+=== Find query results
+
+When an alert is generated, Osquery automatically collects data on the system related to the alert. Query results are displayed within the *Osquery Results* tab in the Alert details flyout. The number next to the *Osquery Results* tab represents the number of queries attached to the rule.
+
+NOTE: Refer to <<view-osquery-results>> for more information about query results.
+
+[role="screenshot"]
+image::images/osquery-results-tab.png[width=80%][height=80%][Shows how to set up a single query]

docs/detections/rules-ui-create.asciidoc

@@ -51,6 +51,7 @@ Creating a new rule requires the following steps:
 . <<rule-ui-advanced-params>>
 . <<rule-schedule>>
 . <<rule-notifications>>
+. <<rule-response-action>>
 
 At any step, you can <<preview-rules,preview the rule>> before saving it to see what kind of results you can expect.
 
@@ -442,9 +443,9 @@ run exactly at its scheduled time.
 [role="screenshot"]
 image::images/rule-actions.png[]
 
-. Do *one* of the following:
+. Do either of the following:
 
-* Continue with <<rule-notifications, setting up alert notifications>> (optional).
+* Continue onto <<rule-notifications, setting up alert notifications>> and <<rule-response-action, Response Actions>> (optional).
 * Create the rule (with or without activation).
 
 [float]
@@ -577,9 +578,21 @@ Example using the mustache "current element" notation `{{.}}` to output all the
 {{#signal.rule.references}} {{.}} {{/signal.rule.references}}
 --------------------------------------------------
 
+[float]
+[[rule-response-action]]
+=== Set up response actions (optional)
+Use Response Actions to set up additional functionality that will run whenever a rule executes.
+
+preview::[]
+
+The Osquery Response Action allows you to include live Osquery queries with a custom query rule. When an alert is generated, Osquery automatically collects data on the system related to the alert. Refer to <<osquery-response-action>> to learn more.
+
+[role="screenshot"]
+image::images/available-response-actions.png[Shows available response actions]
+
 [float]
 [[indicator-value-lists]]
-==== Use value lists with indicator match rules
+=== Use value lists with indicator match rules
 
 While there are numerous ways you can add data into indicator indices, you can use value lists as the indicator match index in an indicator match rule. Take the following scenario, for example:
 

docs/detections/use-osquery.asciidoc

@@ -0,0 +1,10 @@
+[[use-osquery]]
+= Osquery
+
+Osquery is an open source tool that lets you use SQL to query operating systems like a database. When you add the {kibana-ref}/manage-osquery-integration.html[Osquery manager integration] to an {agent} policy, Osquery is deployed to all agents assigned to that policy. After completing this setup, you can {kibana-ref}/osquery.html[run live queries and schedule recurring queries] for agents and begin gathering data from your entire environment.
+
+Osquery is supported for Linux, macOS, and Windows. You can use it with {elastic-sec} to perform real-time incident response, threat hunting, and monitoring to detect vulnerability or compliance issues. The following Osquery features are available from {elastic-sec}:
+
+* *<<osquery-response-action,Osquery Response Actions>>* - Use Osquery Response Actions to add live queries to custom query rules.
+* *<<invest-guide-run-osquery,Live queries from investigation guides>>* - Incorporate live queries into investigation guides to enhance your research capabilities while investigating possible security issues.
+* *<<alerts-run-osquery,Live queries from alerts>>* - Run live queries against an alert's host to learn more about your infrastructure and operating systems.

docs/detections/view-osquery-results.asciidoc

@@ -0,0 +1,52 @@
+[[view-osquery-results]]
+== Examine Osquery results
+Osquery provides relevant, timely data that you can use to better understand and monitor your environment. When you run queries, results are indexed and displayed the Results table, which you can filter, sort, and interact with.
+
+[float]
+[[osquery-result-types]]
+=== Results table
+The Results table displays results from single queries and query packs.
+
+[float]
+[[review-single-osquery-results]]
+==== Single query results
+
+Results for single queries appear on 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]
+[[review-pack-osquery-results]]
+==== Query pack results
+
+Results for each query in the pack appear in the *Results* tab. Click the expand icon (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]
+[[investigate-osquery-results]]
+=== Investigate query results
+
+From the results table, you can:
+
+* Click *View in Discover* (image:images/discover-button-osquery.png[Click the View in Discover button,20,20]) to explore the results in Discover.
+* Click *View in Lens* (image:images/lens-button-osquery.png[Click the View in Lens button,20,20]) to navigate to Lens, where you can use the drag-and-drop *Lens* editor to create visualizations.
+* Click *Timeline* (image:images/timeline-button-osquery.png[Click Timeline button,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.
+
++
+When you open all results in Timeline, the events in Timeline are filtered based on the `action_ID` generated by the Osquery query.
++
+
+* Click *Add to Case* (image:images/case-button-osquery.png[Click Add to Case button,20,20]) to add the query results to a new or existing case.
++
+[NOTE]
+=====
+
+If you add the results to a _new_ case, you are prompted to specify the solution that you want the create the case within. Ensure you select the correct solution. From {elastic-sec}, you cannot access cases created in {observability} or Stack Management.
+
+If you add the results to an _existing case_, you can select from cases that were created in any solution ({elastic-sec}, {observability}, and {stack}).
+=====
+
+* View more information about the request, such as failures, by opening the *Status* tab.

docs/index.asciidoc

@@ -39,6 +39,16 @@ include::events/index.asciidoc[]
 
 include::cases/cases-index.asciidoc[]
 
+include::detections/use-osquery.asciidoc[]
+
+include::detections/osquery-response-action.asciidoc[][leveloffset=+1]
+
+include::detections/invest-guide-run-osquery.asciidoc[][leveloffset=+1]
+
+include::detections/alerts-run-osquery.asciidoc[][leveloffset=+1]
+
+include::detections/view-osquery-results.asciidoc[][leveloffset=+1]
+
 include::management/manage-intro.asciidoc[]
 
 include::siem-apis.asciidoc[]