[8.12][ESS] Document Osquery Timeout setting (#4611)

* First draft * Update docs/osquery/alerts-run-osquery.asciidoc * Update docs/osquery/invest-guide-run-osquery.asciidoc * Update docs/osquery/invest-guide-run-osquery.asciidoc * Update docs/osquery/osquery-response-action.asciidoc * Aligning text with Natasa's descrip * Adds timeout to response action fields * Update docs/detections/api/rules/rules-api-create.asciidoc * Ben's input --------- Co-authored-by: natasha-moore-elastic <[email protected]> Co-authored-by: natasha-moore-elastic <[email protected]> (cherry picked from commit 7f0e5f2)
elastic · Jan 16, 2024 · a067b21 · a067b21
1 parent a45e51d
commit a067b21
Show file tree

Hide file tree

Showing 5 changed files with 14 additions and 4 deletions.
diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc
@@ -698,6 +698,7 @@ For Osquery (`.osquery`), use a single query, a saved query, or a query pack:
 * `saved_query_id` (string, optional): To run a saved query, use the `saved_query_id` field and specify the saved query ID. Example: `"saved_query_id":  "processes_elastic"`
 * `packId` (string, optional): To specify a query pack, use the `packId` field. Example: `"packId": "processes_elastic"`
 * `ecs_mapping` (object, required): Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: `"ecs_mapping": {"process.pid": {"field": "pid"}}`
+* `timeout` (number, optional): A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is `60`. The maximum supported value is `900`. Example: `"timeout": 120`.
 
 NOTE: Refer to {kibana-ref}/osquery-manager-live-queries-api-create.html[Create live query API] for more information about running Osquery queries and packs.
 

diff --git a/docs/osquery/alerts-run-osquery.asciidoc b/docs/osquery/alerts-run-osquery.asciidoc
@@ -22,7 +22,9 @@ To run Osquery from an alert:
 NOTE: The host associated with the alert is automatically selected. You can specify additional hosts to 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.
+** *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 set a timeout period for the query, and view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query (optional).
++
+NOTE: Overwriting the query's default timeout period allows you to support queries that take longer to run. The default and minimum supported value for the **Timeout** field is `60`. The maximum supported value is `900`. 
 +
 TIP: Use <<osquery-placeholder-fields,placeholder fields>> to dynamically add existing alert data to your query. 
 

diff --git a/docs/osquery/images/setup-single-query.png b/docs/osquery/images/setup-single-query.png
diff --git a/docs/osquery/invest-guide-run-osquery.asciidoc b/docs/osquery/invest-guide-run-osquery.asciidoc
@@ -27,7 +27,9 @@ NOTE: You can only add Osquery to investigation guides for custom rules because
 +
 TIP: Use <<osquery-placeholder-fields,placeholder fields>> to dynamically add existing alert data to your query. 
 
-.. 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).
+.. Expand the **Advanced** section to set a timeout period for the query, and view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query (optional).
++
+NOTE: Overwriting the query's default timeout period allows you to support queries that take longer to run. The default and minimum supported value for the **Timeout** field is `60`. The maximum supported value is `900`.
 +
 [role="screenshot"]
 image::images/setup-osquery-investigation-guide.png[width=70%][height=70%][Shows results from running a query from an investigation guide]
@@ -41,7 +43,10 @@ image::images/setup-osquery-investigation-guide.png[width=70%][height=70%][Shows
 . 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).
+.. Expand the **Advanced** section to set a timeout period for the query, and view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query (optional).
++
+NOTE: Overwriting the query's default timeout period allows you to support queries that take longer to run. The default and minimum supported value for the **Timeout** field is `60`. The maximum supported value is `900`.
+
 . Click *Submit* to run the query. Query results display in the flyout.
 +
 NOTE: Refer to <<view-osquery-results>> for more information about query results.

diff --git a/docs/osquery/osquery-response-action.asciidoc b/docs/osquery/osquery-response-action.asciidoc
@@ -33,7 +33,9 @@ You can add Osquery Response Actions to new or existing custom query rules. Quer
 + 
 NOTE: If the rule's investigation guide is using an Osquery query, you'll be asked if you want to add the query as an Osquery Response Action. Click *Add* to add the investigation guide's query to the rule's Osquery Response Action. 
 . 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.
+** *Query*: Select a saved query or enter a new one. After you enter the query, you can expand the **Advanced** section to set a timeout period for the query, and view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query (optional). 
++
+NOTE: Overwriting the query's default timeout period allows you to support queries that take longer to run. The default and minimum supported value for the **Timeout** field is `60`. The maximum supported value is `900`.
 +
 TIP: You can use <<osquery-placeholder-fields,placeholder fields>> to dynamically add alert data to your query.