From d5fcda98af092a986ac7a35f5d478f7a98f563f5 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Mon, 30 Oct 2023 16:02:18 -0500 Subject: [PATCH 1/8] Update rest-api.md --- docs/REST API/rest-api.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 0c7cb7738003..22336c523569 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5676,9 +5676,10 @@ Returns the query report specified by ID. #### Parameters -| Name | Type | In | Description | -| ---- | ------- | ---- | ------------------------------------------ | -| id | integer | path | **Required**. The ID of the desired query. | +| Name | Type | In | Description | +| --------- | ------- | ---- | ------------------------------------------ | +| id | integer | path | **Required**. The ID of the desired query. | +| host_id | integer | path | If provided, filters to only include results for the specified host. | #### Example From 6c638fe743d93993a122d16d13e13aa488a16af4 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Tue, 28 Nov 2023 15:30:28 -0600 Subject: [PATCH 2/8] Update rest-api.md --- docs/REST API/rest-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 22336c523569..519f59ba434a 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5676,10 +5676,10 @@ Returns the query report specified by ID. #### Parameters -| Name | Type | In | Description | -| --------- | ------- | ---- | ------------------------------------------ | -| id | integer | path | **Required**. The ID of the desired query. | -| host_id | integer | path | If provided, filters to only include results for the specified host. | +| Name | Type | In | Description | +| --------- | ------- | ----- | ------------------------------------------ | +| id | integer | path | **Required**. The ID of the desired query. | +| host_id | integer | query | If provided, filters to only include results for the specified host. | #### Example From 2aa3cb533c13581fd8a24c22868be0aaed9fbca7 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Wed, 29 Nov 2023 16:57:00 -0600 Subject: [PATCH 3/8] Move per-host query report into its own API endpoint --- docs/REST API/rest-api.md | 68 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 519f59ba434a..21572d320b09 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5491,6 +5491,7 @@ Either `query` or `query_id` must be provided. - [List queries](#list-queries) - [Get query](#get-query) - [Get query report](#get-query-report) +- [Get query report for one host](#get-query-report-for-one-host) - [Create query](#create-query) - [Modify query](#modify-query) - [Delete query by name](#delete-query-by-name) @@ -5679,7 +5680,6 @@ Returns the query report specified by ID. | Name | Type | In | Description | | --------- | ------- | ----- | ------------------------------------------ | | id | integer | path | **Required**. The ID of the desired query. | -| host_id | integer | query | If provided, filters to only include results for the specified host. | #### Example @@ -5753,6 +5753,72 @@ If a query has no results stored, then `results` will be an empty array: > Note: osquery scheduled queries do not return errors, so only non-error results are included in the report. If you suspect a query may be running into errors, you can use the [live query](#run-live-query) endpoint to get diagnostics. +### Get query report for one host + +Returns a query report for a single host. + +`GET /api/v1/fleet/hosts/{id}/query_report/{query_id}` + +#### Parameters + +| Name | Type | In | Description | +| --------- | ------- | ----- | ------------------------------------------ | +| id | integer | path | **Required**. The ID of the desired host. | +| query_id | integer | path | **Required**. The ID of the desired query. | + +#### Example + +`GET /api/v1/fleet/queries/31/report` + +##### Default response + +`Status: 200` + +```json +{ + "query_id": 31, + "host_id": 1, + "host_name": "foo", + "last_fetched": "2021-01-19T17:08:31Z", + "report_clipped": false, + "results": [ + { + "columns": { + "model": "USB 2.0 Hub", + "vendor": "VIA Labs, Inc." + } + }, + { + "columns": { + "model": "USB Keyboard", + "vendor": "VIA Labs, Inc." + } + }, + { + "columns": { + "model": "USB Reciever", + "vendor": "Logitech" + } + } + ] +} +``` + +If a query has no results stored for the specified host, then `results` will be an empty array: + +```json +{ + "query_id": 31, + "host_id": 1, + "host_name": "foo", + "last_fetched": "2021-01-19T17:08:31Z", + "report_clipped": false, + "results": [] +} +``` + +> Note: osquery scheduled queries do not return errors, so only non-error results are included in the report. If you suspect a query may be running into errors, you can use the [live query](#run-live-query) endpoint to get diagnostics. + ### Create query Creates a global query or team query. From e5b1e61a3f52a9eaf249436fb60f568d16d3475e Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Wed, 29 Nov 2023 17:06:41 -0600 Subject: [PATCH 4/8] Update docs/REST API/rest-api.md Co-authored-by: Tim Lee --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 21572d320b09..054df0a8c3d4 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5768,7 +5768,7 @@ Returns a query report for a single host. #### Example -`GET /api/v1/fleet/queries/31/report` +`GET /api/v1/fleet/hosts/123/query_report/31` ##### Default response From 3df8b6cf4f629aac32299506739771ccbedaba6e Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Thu, 30 Nov 2023 11:15:41 -0600 Subject: [PATCH 5/8] Update docs/REST API/rest-api.md --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 054df0a8c3d4..aea1de3c58e9 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5768,7 +5768,7 @@ Returns a query report for a single host. #### Example -`GET /api/v1/fleet/hosts/123/query_report/31` +`GET /api/v1/fleet/hosts/123/queries/31` ##### Default response From 5af090f36ad757ca0e9d79cde8ccc4bbc095babe Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Thu, 30 Nov 2023 11:16:05 -0600 Subject: [PATCH 6/8] Update docs/REST API/rest-api.md --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index aea1de3c58e9..9e1a45ae3000 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5757,7 +5757,7 @@ If a query has no results stored, then `results` will be an empty array: Returns a query report for a single host. -`GET /api/v1/fleet/hosts/{id}/query_report/{query_id}` +`GET /api/v1/fleet/hosts/{id}/queries/{query_id}` #### Parameters From dcd3c1b254a0205f0eafe37f6032513b803e12e8 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Fri, 8 Dec 2023 16:56:36 -0600 Subject: [PATCH 7/8] Update docs/REST API/rest-api.md --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 9e1a45ae3000..f5c40895cf65 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5757,7 +5757,7 @@ If a query has no results stored, then `results` will be an empty array: Returns a query report for a single host. -`GET /api/v1/fleet/hosts/{id}/queries/{query_id}` +`GET /api/v1/fleet/hosts/:id/queries/:query_id` #### Parameters From 1e389245f6e54d946ecfb66b5360faa175c0f86e Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Fri, 8 Dec 2023 16:57:07 -0600 Subject: [PATCH 8/8] Update docs/REST API/rest-api.md --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index f5c40895cf65..6477a31b8e7d 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5808,7 +5808,7 @@ If a query has no results stored for the specified host, then `results` will be ```json { - "query_id": 31, + "query_id": 31, "host_id": 1, "host_name": "foo", "last_fetched": "2021-01-19T17:08:31Z",