diff --git a/docs/detections/alerts-run-osquery.asciidoc b/docs/detections/alerts-run-osquery.asciidoc index 95dab04a18..c0bcca7d7d 100644 --- a/docs/detections/alerts-run-osquery.asciidoc +++ b/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 <> for more information about query results. +. Click *Save for later* to save the query for future use (optional). diff --git a/docs/detections/alerts-view-details.asciidoc b/docs/detections/alerts-view-details.asciidoc index 96194f0fe4..1c31fceb74 100644 --- a/docs/detections/alerts-view-details.asciidoc +++ b/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. <> * *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. <> [role="screenshot"] image::images/alert-details-flyout.png[Alert details flyout, 90%] diff --git a/docs/detections/detections-index.asciidoc b/docs/detections/detections-index.asciidoc index e5935dd5cc..54eefb8b2b 100644 --- a/docs/detections/detections-index.asciidoc +++ b/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[] diff --git a/docs/detections/images/available-action-types.png b/docs/detections/images/available-action-types.png index 94f700c7e6..3cdf4e18e1 100644 Binary files a/docs/detections/images/available-action-types.png and b/docs/detections/images/available-action-types.png differ diff --git a/docs/detections/images/available-response-actions.png b/docs/detections/images/available-response-actions.png new file mode 100644 index 0000000000..dcea42be80 Binary files /dev/null and b/docs/detections/images/available-response-actions.png differ diff --git a/docs/detections/images/case-button-osquery.png b/docs/detections/images/case-button-osquery.png new file mode 100644 index 0000000000..9fc908984d Binary files /dev/null and b/docs/detections/images/case-button-osquery.png differ diff --git a/docs/detections/images/osquery-button.png b/docs/detections/images/osquery-button.png new file mode 100644 index 0000000000..bee81e5cd2 Binary files /dev/null and b/docs/detections/images/osquery-button.png differ diff --git a/docs/detections/images/osquery-investigation-guide.png b/docs/detections/images/osquery-investigation-guide.png new file mode 100644 index 0000000000..c4353856c6 Binary files /dev/null and b/docs/detections/images/osquery-investigation-guide.png differ diff --git a/docs/detections/images/osquery-results-tab.png b/docs/detections/images/osquery-results-tab.png new file mode 100644 index 0000000000..1906c33fd7 Binary files /dev/null and b/docs/detections/images/osquery-results-tab.png differ diff --git a/docs/detections/images/pack-query-results.png b/docs/detections/images/pack-query-results.png index b699db2e8c..9338e550cb 100644 Binary files a/docs/detections/images/pack-query-results.png and b/docs/detections/images/pack-query-results.png differ diff --git a/docs/detections/images/rule-actions.png b/docs/detections/images/rule-actions.png index e2f38794ee..c422224490 100644 Binary files a/docs/detections/images/rule-actions.png and b/docs/detections/images/rule-actions.png differ diff --git a/docs/detections/images/run-query-investigation-guide.png b/docs/detections/images/run-query-investigation-guide.png new file mode 100644 index 0000000000..8dcd0547d3 Binary files /dev/null and b/docs/detections/images/run-query-investigation-guide.png differ diff --git a/docs/detections/images/setup-osquery-investigation-guide.png b/docs/detections/images/setup-osquery-investigation-guide.png new file mode 100644 index 0000000000..d244d8e9a0 Binary files /dev/null and b/docs/detections/images/setup-osquery-investigation-guide.png differ diff --git a/docs/detections/images/setup-single-query.png b/docs/detections/images/setup-single-query.png new file mode 100644 index 0000000000..41042ab637 Binary files /dev/null and b/docs/detections/images/setup-single-query.png differ diff --git a/docs/detections/images/single-query-results.png b/docs/detections/images/single-query-results.png index 963efdf438..00d37b6a92 100644 Binary files a/docs/detections/images/single-query-results.png and b/docs/detections/images/single-query-results.png differ diff --git a/docs/detections/invest-guide-run-osquery.asciidoc b/docs/detections/invest-guide-run-osquery.asciidoc new file mode 100644 index 0000000000..defbe3d0cb --- /dev/null +++ b/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 <> 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] diff --git a/docs/detections/osquery-response-action.asciidoc b/docs/detections/osquery-response-action.asciidoc new file mode 100644 index 0000000000..f4f84ac4ba --- /dev/null +++ b/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 <> 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 <> 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] diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index 184dc1f635..36fa62737e 100644 --- a/docs/detections/rules-ui-create.asciidoc +++ b/docs/detections/rules-ui-create.asciidoc @@ -51,6 +51,7 @@ Creating a new rule requires the following steps: . <> . <> . <> +. <> At any step, you can <> 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 <> (optional). +* Continue onto <> and <> (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 <> 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: diff --git a/docs/detections/use-osquery.asciidoc b/docs/detections/use-osquery.asciidoc new file mode 100644 index 0000000000..419dd0058c --- /dev/null +++ b/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}: + +* *<>* - Use Osquery Response Actions to add live queries to custom query rules. +* *<>* - Incorporate live queries into investigation guides to enhance your research capabilities while investigating possible security issues. +* *<>* - Run live queries against an alert's host to learn more about your infrastructure and operating systems. diff --git a/docs/detections/view-osquery-results.asciidoc b/docs/detections/view-osquery-results.asciidoc new file mode 100644 index 0000000000..5d78eeab39 --- /dev/null +++ b/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. diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 440d558502..8d4411e115 100644 --- a/docs/index.asciidoc +++ b/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[]