From 75be8f09260254bc0a53e5bd710398452f17cae7 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Wed, 10 Jan 2024 13:06:51 +0000 Subject: [PATCH 1/4] Adds timeout API parameter --- docs/api/osquery-manager/live-queries/create.asciidoc | 5 ++++- docs/api/osquery-manager/packs/create.asciidoc | 1 + docs/api/osquery-manager/saved-queries/create.asciidoc | 5 ++++- 3 files changed, 9 insertions(+), 2 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..1f33210e3789c 100644 --- a/docs/api/osquery-manager/saved-queries/create.asciidoc +++ b/docs/api/osquery-manager/saved-queries/create.asciidoc @@ -39,6 +39,8 @@ experimental[] Create saved queries. `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 @@ -59,7 +61,8 @@ $ curl -X POST api/osquery/saved_queries \ "id": "saved_query_id", "description": "Saved query description", "query": "select * from uptime;", - "interval": "60", + "interval": 60, + "timeout": 120, "version": "2.8.0", "platform": "linux,darwin", "ecs_mapping": { From f5e7909782d379df7fcde75d6ab6374157642fc8 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Fri, 12 Jan 2024 18:19:41 -0500 Subject: [PATCH 2/4] Adding UI part --- docs/osquery/osquery.asciidoc | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) 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. From b851c6bd5c3aeb371bb5713a968b4c08519cce25 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Mon, 15 Jan 2024 14:58:15 +0000 Subject: [PATCH 3/4] Updates interval to string --- docs/api/osquery-manager/saved-queries/create.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/osquery-manager/saved-queries/create.asciidoc b/docs/api/osquery-manager/saved-queries/create.asciidoc index 1f33210e3789c..d9d233fa41759 100644 --- a/docs/api/osquery-manager/saved-queries/create.asciidoc +++ b/docs/api/osquery-manager/saved-queries/create.asciidoc @@ -35,7 +35,7 @@ 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, to run the query. `ecs_mapping`:: (Optional, object) Maps Osquery results columns or static values to ECS fields. @@ -61,7 +61,7 @@ $ curl -X POST api/osquery/saved_queries \ "id": "saved_query_id", "description": "Saved query description", "query": "select * from uptime;", - "interval": 60, + "interval": "60", "timeout": 120, "version": "2.8.0", "platform": "linux,darwin", From 380b4a25b337bb700e1a4cf6b0fb409958ee9ecb Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Date: Wed, 17 Jan 2024 10:03:53 +0000 Subject: [PATCH 4/4] Update docs/api/osquery-manager/saved-queries/create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- docs/api/osquery-manager/saved-queries/create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/osquery-manager/saved-queries/create.asciidoc b/docs/api/osquery-manager/saved-queries/create.asciidoc index d9d233fa41759..75b764ded6023 100644 --- a/docs/api/osquery-manager/saved-queries/create.asciidoc +++ b/docs/api/osquery-manager/saved-queries/create.asciidoc @@ -35,7 +35,7 @@ experimental[] Create saved queries. `version`:: (Optional, string) Uses the Osquery versions greater than or equal to the specified version string. -`interval`:: (Optional, string) 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.