From 06dc4c53f7b4fb12c3c65d5a72f3708bce420144 Mon Sep 17 00:00:00 2001 From: noahtalerman <47070608+noahtalerman@users.noreply.github.com> Date: Tue, 9 Mar 2021 15:41:10 -0800 Subject: [PATCH] Remove support property from fleetctl docs. Edit run queries by name endpoint in api docs (#429) This PR includes two documentation fixes. 1. Remove the support property from the osquery queries spec in the fleetctl docs. The support property is not a feature of osquery or Fleet. 2. Edit the api/v1/fleet/queries/run_by_names with accurate examples. This endpoint sends query targets (hosts and labels) by name (hostname and label name). Contrast this with the api/v1/fleet/queries/run which sends query targets by id (host id and label id) Resolves #409 --- docs/1-Using-Fleet/2-fleetctl-CLI.md | 8 --- docs/1-Using-Fleet/3-REST-API.md | 83 ++++++++++++++++++++++------ 2 files changed, 66 insertions(+), 25 deletions(-) diff --git a/docs/1-Using-Fleet/2-fleetctl-CLI.md b/docs/1-Using-Fleet/2-fleetctl-CLI.md index 555a5eb8de..07fe1111b7 100644 --- a/docs/1-Using-Fleet/2-fleetctl-CLI.md +++ b/docs/1-Using-Fleet/2-fleetctl-CLI.md @@ -275,11 +275,6 @@ spec: name: docker_processes description: The docker containers processes that are running on a system. query: select * from docker_container_processes; - support: - osquery: 2.9.0 - platforms: - - linux - - darwin ``` To define multiple queries in a file, concatenate multiple `query` resources together in a single file with `---`. For example, consider a file that you might store at `queries/osquery_monitoring.yml`: @@ -291,9 +286,6 @@ spec: name: osquery_version description: The version of the Launcher and Osquery process query: select launcher.version, osquery.version from kolide_launcher_info launcher, osquery_info osquery; - support: - launcher: 0.3.0 - osquery: 2.9.0 --- apiVersion: v1 kind: query diff --git a/docs/1-Using-Fleet/3-REST-API.md b/docs/1-Using-Fleet/3-REST-API.md index e363e5ceb7..8f081bcf89 100644 --- a/docs/1-Using-Fleet/3-REST-API.md +++ b/docs/1-Using-Fleet/3-REST-API.md @@ -2378,7 +2378,7 @@ Runs the specified query as a live query on the specified hosts or group of host | Name | Type | In | Description | | ---------- | ------- | ---- | ------------------------------------------------ | | query | string | body | **Required.** The SQL of the query | -| selected | object | body | **Required.** The desired targets for the query. This object must contain `hosts` and `labels` properties. See example below | +| selected | object | body | **Required.** The desired targets for the query specified by ID. This object can contain `hosts` and/or `labels` properties. See examples below. | #### Example with one host targeted by ID @@ -2389,7 +2389,9 @@ Runs the specified query as a live query on the specified hosts or group of host ``` { "query": "select instance_id from system_info;", - "selected": { "hosts": [171], "labels": []} + "selected": { + "hosts": [171] + } } ``` @@ -2409,8 +2411,8 @@ Runs the specified query as a live query on the specified hosts or group of host "MissingInActionHosts": 0, "NewHosts": 1 }, - "id": 273, - "query_id": 293, + "id": 1, + "query_id": 3, "status": 0, "user_id": 1 } @@ -2426,7 +2428,9 @@ Runs the specified query as a live query on the specified hosts or group of host ``` { "query": "select instance_id from system_info;", - "selected": { "hosts": [171], "labels": []} + "selected": { + "labels": [7] + } } ``` @@ -2440,23 +2444,23 @@ Runs the specified query as a live query on the specified hosts or group of host "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "Metrics": { - "TotalHosts": 1, + "TotalHosts": 102, "OnlineHosts": 0, - "OfflineHosts": 1, + "OfflineHosts": 24, "MissingInActionHosts": 0, - "NewHosts": 1 + "NewHosts": 0 }, - "id": 273, - "query_id": 293, + "id": 2, + "query_id": 3, "status": 0, "user_id": 1 } } ``` -### Run live query by query name +### Run live query by name -Runs the specified query by name as a live query on the specified hosts or group of hosts. Returns a new live query campaign. Individual hosts must be specified with the host's ID. Groups of hosts are specified by label. +Runs the specified query as a live query on the specified hosts or group of hosts. Returns a new live query campaign. Individual hosts must be specified with the host's hostname. Groups of hosts are specified by label name. `POST /api/v1/fleet/queries/run_by_names` @@ -2465,9 +2469,9 @@ Runs the specified query by name as a live query on the specified hosts or group | Name | Type | In | Description | | ---------- | ------- | ---- | ------------------------------------------------ | | name | string | body | **Required.** The name of the query. | -| selected | object | body | **Required.** The desired targets for the query. This object must contain `hosts` and `labels` properties. See example below. | +| selected | object | body | **Required.** The desired targets for the query specified by name. This object can contain `hosts` and/or `labels` properties. See examples below. | -#### Example with one host targeted +#### Example with one host targeted by hostname `POST /api/v1/fleet/queries/run_by_names` @@ -2476,7 +2480,11 @@ Runs the specified query by name as a live query on the specified hosts or group ``` { "name": "instance_id", - "selected": { "hosts": [171], "labels": [] } + "selected": { + "hosts": [ + "macbook-pro.local", + ] + } } ``` @@ -2496,8 +2504,49 @@ Runs the specified query by name as a live query on the specified hosts or group "MissingInActionHosts": 0, "NewHosts": 1 }, - "id": 275, - "query_id": 295, + "id": 1, + "query_id": 3, + "status": 0, + "user_id": 1 + } +} +``` + +#### Example with multiple hosts targeted by label name + +`POST /api/v1/fleet/queries/run_by_names` + +##### Request body + +``` +{ + "name": "instance_id", + "selected": { + "labels": [ + "All Hosts" + ] + } +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "campaign": { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "Metrics": { + "TotalHosts": 102, + "OnlineHosts": 0, + "OfflineHosts": 24, + "MissingInActionHosts": 0, + "NewHosts": 1 + }, + "id": 2, + "query_id": 3, "status": 0, "user_id": 1 }