[DOCS] Documents Osquery Timeout setting (elastic#174595)

Contributes to elastic/security-docs#4536 by documenting the new **Timeout** setting and `timeout` API parameter in Osquery docs. --------- Co-authored-by: nastasha.solomon <[email protected]> Co-authored-by: Benjamin Ironside Goldstein <[email protected]>
CoenWarmer · Feb 15, 2024 · 365fedc · 365fedc
1 parent 7da6579
commit 365fedc
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 5 deletions.
diff --git a/docs/api/osquery-manager/live-queries/create.asciidoc b/docs/api/osquery-manager/live-queries/create.asciidoc
@@ -49,6 +49,8 @@ experimental[] Create live queries.
 
 `metadata`:: (Optional, object) Custom metadata object associated to the live query.
 
+`timeout`:: (Optional, number) 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`.
+
 
 [[osquery-manager-live-queries-api-create-request-codes]]
 ==== Response code
@@ -69,13 +71,13 @@ Run a live query on all supported agents:
 $ curl -X POST api/osquery/live_queries \
 {
   "query": "select * from uptime;",
-
   "ecs_mapping": {
     "host.uptime": {
       "field": "total_seconds"
     }
   },
   "agent_all": true,
+  "timeout": 120
 }
 
 --------------------------------------------------
@@ -110,6 +112,7 @@ The API returns the live query object:
         "action_id": "609c4c66-ba3d-43fa-afdd-53e244577aa0", # unique ID of the query, use it when querying the live query API to get the single query results
         "id": "6724a474-cbba-41ef-a1aa-66aebf0879e2", # ID of the query, doesn't have to be unique
         "query": "select * from uptime;",
+        "timeout": 120,
         "ecs_mapping": {
           "host.uptime": {
             "field": "total_seconds"

diff --git a/docs/api/osquery-manager/packs/create.asciidoc b/docs/api/osquery-manager/packs/create.asciidoc
@@ -69,6 +69,7 @@ $ curl -X POST api/osquery/packs \
     "my_query": {
       "query": "SELECT * FROM listening_ports;",
       "interval": 60,
+      "timeout": 120,
       "ecs_mapping": {
         "client.port": {
           "field": "port"

diff --git a/docs/api/osquery-manager/saved-queries/create.asciidoc b/docs/api/osquery-manager/saved-queries/create.asciidoc
@@ -35,10 +35,12 @@ experimental[] Create saved queries.
 
 `version`:: (Optional, string) Uses the Osquery versions greater than or equal to the specified version string.
 
-`interval`:: (Optional, integer) An interval, in seconds, to run the query.
+`interval`:: (Optional, string) An interval, in seconds, on which to run the query.
 
 `ecs_mapping`:: (Optional, object) Maps Osquery results columns or static values to ECS fields.
 
+`timeout`:: (Optional, number) 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`.
+
 
 [[osquery-manager-saved-queries-api-create-request-codes]]
 ==== Response code
@@ -60,6 +62,7 @@ $ curl -X POST api/osquery/saved_queries \
   "description": "Saved query description",
   "query": "select * from uptime;",
   "interval": "60",
+  "timeout": 120,
   "version": "2.8.0",
   "platform": "linux,darwin",
   "ecs_mapping": {

diff --git a/docs/osquery/osquery.asciidoc b/docs/osquery/osquery.asciidoc
@@ -42,15 +42,17 @@ then view the results.
 . Select one or more agents or groups to query. Start typing in the search field,
 and you'll get suggestions for agents by name, ID, platform, and policy.
 . 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 <<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 <<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 require more time to complete. The default and minimum supported value for the **Timeout** field is `60`. The maximum supported value is `900`.
 ** *Pack*: Select from available query packs. After you select a pack, all of the queries in the pack are displayed.
 +
 TIP: Refer to <<osquery-prebuilt-packs,prebuilt packs>> to learn about using and managing Elastic prebuilt packs.
 +
 [role="screenshot"]
 image::images/enter-query.png[Select saved query dropdown name showing query name and description]
 
-. Click **Submit**. Queries will timeout after 5 minutes if there are no responses.
+. Click **Submit**. 
 +
 TIP: To save a single query for future use, click *Save for later* and define the ID, description, and other <<osquery-manage-query,details>>.
 
@@ -104,8 +106,10 @@ NOTE: When defining pack deployment details, you cannot configure the same polic
 
  ** Click *Add query* and then add a saved query or enter a new query.
 Each query must include a unique query ID and the interval at which it should run.
-Optionally, set the minimum Osquery version and platform,
+Optionally, set the minimum Osquery version and platform, specify a timeout period,
 or <<osquery-map-fields,map ECS fields>>. When you add a saved query to a pack, this adds a copy of the query. A connection is not maintained between saved queries and packs.
++
+NOTE: Overwriting the query's default timeout period allows you to support queries that require more time to complete. The default and minimum supported value for the **Timeout** field is `60`. The maximum supported value is `900`.
 
 ** Upload queries from a `.conf` query pack by dragging the pack to the drop zone under the query table. To explore the community packs that Osquery publishes, click *Example packs*.
 
@@ -147,6 +151,8 @@ Once you save a query, you can only edit it from the *Saved queries* tab:
 
 * The SQL query (required). Osquery supports multi-line queries.
 
+* A timeout period (optional). Increase the query's default timeout period to support queries that require more time to complete. The default and minimum supported value for the **Timeout** field is `60`. The maximum supported value is `900`.
+
 * The <<osquery-map-fields,ECS fields>> to populate when the query is run (optional). These fields are also copied in when you add this query to a pack.
 
 * The defaults to set when you add the query to a pack.