From 86a31db057c5b66291dcd5e27adafa2899e82224 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Date: Wed, 17 Jan 2024 15:29:23 +0000 Subject: [PATCH] [DOCS] Documents Osquery Timeout setting (#174595) Contributes to https://github.com/elastic/security-docs/issues/4536 by documenting the new **Timeout** setting and `timeout` API parameter in Osquery docs. --------- Co-authored-by: nastasha.solomon Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- .../api/osquery-manager/live-queries/create.asciidoc | 5 ++++- docs/api/osquery-manager/packs/create.asciidoc | 1 + .../osquery-manager/saved-queries/create.asciidoc | 5 ++++- docs/osquery/osquery.asciidoc | 12 +++++++++--- 4 files changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/api/osquery-manager/live-queries/create.asciidoc b/docs/api/osquery-manager/live-queries/create.asciidoc index 16fbade0eb061..c080cfe08a903 100644 --- 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 index 280f6a1d9fe75..84e8c3e71eb5c 100644 --- 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 index 61f415845a5aa..75b764ded6023 100644 --- 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 index 2f6e0657b42af..4f0859ac21b19 100644 --- a/docs/osquery/osquery.asciidoc +++ b/docs/osquery/osquery.asciidoc @@ -42,7 +42,9 @@ 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 <> 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 <> 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 <> to learn about using and managing Elastic prebuilt packs. @@ -50,7 +52,7 @@ TIP: Refer to <> to learn about using and [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 <>. @@ -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 <>. 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 <> 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.