diff --git a/docs/1-Using-Fleet/3-REST-API.md b/docs/1-Using-Fleet/3-REST-API.md index 7f47210c6f..ee62f26950 100644 --- a/docs/1-Using-Fleet/3-REST-API.md +++ b/docs/1-Using-Fleet/3-REST-API.md @@ -21,6 +21,18 @@ - [Create a user account with an invitation](#create-a-user-account-with-an-invitation) - [Create a user account without an invitation](#create-a-user-account-without-an-invitation) - [Get user information](#get-user-information) +- [Queries](#queries) + - [Get query](#get-query) + - [List queries](#list-queries) + - [Create query](#create-query) + - [Modify query](#modify-query) + - [Delete query](#delete-query) + - [Delete query by ID](#delete-query-by-id) + - [Get queries specs](#get-quieries-specs) + - [Get query spec](#get-query-spec) + - [Apply queries specs](#apply-quieries-specs) + - [Run live query](#run-live-query) + - [Run live query by query name](#run-live-query-by-query-name) - [Fleet configuration](#fleet-configuration) - [Get certificate](#get-certificate) - [Get configuration](#get-configuration) @@ -796,9 +808,9 @@ Returns the information of the host specified using the `uuid`, `osquery_host_id ### Delete host -Deletes the specified host from Fleet. +Deletes the specified host from Fleet. Note that a deleted host will fail authentication with the previous node key, and in most osquery configurations will attempt to re-enroll automatically. If the host still has a valid enroll secret, it will re-enroll successfully. -`DELELTE /api/v1/kolide/hosts/{id}` +`DELETE /api/v1/kolide/hosts/{id}` #### Parameters @@ -808,7 +820,7 @@ Deletes the specified host from Fleet. #### Example -`DELELTE /api/v1/kolide/hosts/121` +`DELETE /api/v1/kolide/hosts/121` ##### Default response @@ -1155,6 +1167,556 @@ Returns all information about a specific user. --- +## Queries + +### Get query + +Returns the query specified by ID. + +`GET /api/v1/kolide/queries/{id}` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| id | integer | path | **Required**. The id of the desired query. | + +#### Example + +`GET /api/v1/kolide/queries/31` + + +##### Default response + +`Status: 200` + +``` +{ + "query": { + "created_at": "2021-01-19T17:08:24Z", + "updated_at": "2021-01-19T17:08:24Z", + "id": 31, + "name": "centos_hosts", + "description": "", + "query": "select 1 from os_version where platform = \"centos\";", + "saved": true, + "author_id": 1, + "author_name": "John", + "packs": [ + { + "created_at": "2021-01-19T17:08:31Z", + "updated_at": "2021-01-19T17:08:31Z", + "id": 14, + "name": "test_pack", + "description": "", + "platform": "", + "disabled": false + } + ] + } +} +``` + +### List queries + +Returns a list of all queries in the Fleet instance. + +`GET /api/v1/kolide/queries` + +#### Parameters + +None. + +#### Example + +`GET /api/v1/kolide/queries` + + +##### Default response + +`Status: 200` + +``` +{ +"queries": [ + { + "created_at": "2021-01-04T21:19:57Z", + "updated_at": "2021-01-04T21:19:57Z", + "id": 1, + "name": "query1", + "description": "query", + "query": "SELECT * FROM osquery_info", + "saved": true, + "author_id": 1, + "author_name": "noah", + "packs": [ + { + "created_at": "2021-01-05T21:13:04Z", + "updated_at": "2021-01-07T19:12:54Z", + "id": 1, + "name": "Pack", + "description": "Pack", + "platform": "", + "disabled": true + } + ] + }, + { + "created_at": "2021-01-19T17:08:24Z", + "updated_at": "2021-01-19T17:08:24Z", + "id": 2, + "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;", + "saved": true, + "author_id": 1, + "author_name": "noah", + "packs": [ + { + "created_at": "2021-01-19T17:08:31Z", + "updated_at": "2021-01-19T17:08:31Z", + "id": 14, + "name": "test_pack", + "description": "", + "platform": "", + "disabled": false + }, + { + "created_at": "2021-01-19T17:08:31Z", + "updated_at": "2021-01-19T17:08:31Z", + "id": 14, + "name": "test_pack", + "description": "", + "platform": "", + "disabled": false + } + ] + }, + { + "created_at": "2021-01-19T17:08:24Z", + "updated_at": "2021-01-19T17:08:24Z", + "id": 3, + "name": "osquery_schedule", + "description": "Report performance stats for each file in the query schedule.", + "query": "select name, interval, executions, output_size, wall_time, (user_time/executions) as avg_user_time, (system_time/executions) as avg_system_time, average_memory, last_executed from osquery_schedule;", + "saved": true, + "author_id": 1, + "author_name": "noah", + "packs": [ + { + "created_at": "2021-01-19T17:08:31Z", + "updated_at": "2021-01-19T17:08:31Z", + "id": 14, + "name": "test_pack", + "description": "", + "platform": "", + "disabled": false + } + ] + }, +] +``` + +### Create query + +`POST /api/v1/kolide/queries` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| name | string | body | **Required**. The name of the query. | +| query | string | body | **Required**. The query in SQL syntax. | +| description | string | body | The query's description. | + +#### Example + +`POST /api/v1/kolide/queries` + +##### Request body + +``` +{ + "description": "This is a new query." + "name": "new_query" + "query": "SELECT * FROM osquery_info" +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "query": { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "id": 288, + "name": "new_query", + "description": "This is a new query.", + "query": "SELECT * FROM osquery_info", + "saved": true, + "author_id": 1, + "author_name": "", + "packs": [] + } +} +``` + +### Modify query + +Returns the query specified by ID. + +`PATCH /api/v1/kolide/queries/{id}` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| id | integer | path | **Required.** The ID of the query. | +| name | string | body | The name of the query. | +| query | string | body | The query in SQL syntax. | +| description | string | body | The query's description. | + +#### Example + +`PATCH /api/v1/kolide/queries/2` + +##### Request body + +``` +{ + "name": "new_title_for_my_query" +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "query": { + "created_at": "2021-01-22T17:23:27Z", + "updated_at": "2021-01-22T17:23:27Z", + "id": 288, + "name": "new_title_for_my_query", + "description": "This is a new query.", + "query": "SELECT * FROM osquery_info", + "saved": true, + "author_id": 1, + "author_name": "noah", + "packs": [] + } +} +``` + +### Delete query + +Deletes the query specified by name. + +`DELETE /api/v1/kolide/queries/{name}` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| name | string | path | **Required.** The name of the query. | + +#### Example + +`DELETE /api/v1/kolide/queries/{name}` + +##### Default response + +`Status: 200` + +``` +{} +``` + +### Delete query by ID + +Deletes the query specified by ID. + +`DELETE /api/v1/kolide/queries/id/{id}` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| id | integer | path | **Required.** The ID of the query. | + +#### Example + +`DELETE /api/v1/kolide/queries/id/28` + +##### Default response + +`Status: 200` + +``` +{} +``` + +### Get queries specs + +Returns a list of all queries in the Fleet instance. Each item returned includes the name, description, and SQL of the query. + +`GET /api/v1/kolide/spec/queries` + +#### Parameters + +None. + +#### Example + +`GET /api/v1/kolide/spec/queries` + +##### Default response + +`Status: 200` + +``` +{ + "specs": [ + { + "name": "query1", + "description": "query", + "query": "SELECT * FROM osquery_info" + }, + { + "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;" + }, + { + "name": "osquery_schedule", + "description": "Report performance stats for each file in the query schedule.", + "query": "select name, interval, executions, output_size, wall_time, (user_time/executions) as avg_user_time, (system_time/executions) as avg_system_time, average_memory, last_executed from osquery_schedule;" + }, + ] +} +``` + +### Get query spec + +Returns the name, description, and SQL of the query specified by name. + +`GET /api/v1/kolide/spec/queries/{name}` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| name | string | path | **Required.** The name of the query. | + +#### Example + +`GET /api/v1/kolide/spec/queries/query1` + +##### Default response + +`Status: 200` + +``` +{ + "specs": { + "name": "query1", + "description": "query", + "query": "SELECT * FROM osquery_info" + } +} +``` + +### Apply queries specs + +Creates and/or modifies the queries included in the specs list. To modify an existing query, the name of the query included in `specs` must already be used by an existing query. If a query with the specified name doesn't exist in Fleet, a new query will be created. + +`POST /api/v1/kolide/spec/queries` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| specs | list | body | **Required.** The list of the queries to be created or modified. | + +#### Example + +`POST /api/v1/kolide/spec/queries` + +##### Request body + +``` +{ + "specs": [ + { + "name": "new_query", + "description": "This will be a new query because a query with the name 'new_query' doesn't exist in Fleet.", + "query": "SELECT * FROM osquery_info" + }, + { + "name": "osquery_version", + "description": "Only this queries description will be modified because a query with the name 'osquery_version' exists in Fleet.", + "query": "select launcher.version, osquery.version from kolide_launcher_info launcher, osquery_info osquery;" + }, + { + "name": "osquery_schedule", + "description": "This queries description and SQL will be modified because a query with the name 'osquery_schedule' exists in Fleet.", + "query": "SELECT * FROM osquery_info" + } + ] +} +``` + +##### Default response + +`Status: 200` + +``` +{} +``` + +### Run live query + +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 ID. Groups of hosts are specified by label ID. + +`POST /api/v1/kolide/spec/queries/run` + +#### Parameters + +| 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 | + +#### Example with one host targeted by ID + +`POST /api/v1/kolide/spec/queries/run` + +##### Request body + +``` +{ + "query": "select instance_id from system_info;" + "selected": { "hosts": [171], "labels": []} +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "campaign": { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "Metrics": { + "TotalHosts": 1, + "OnlineHosts": 0, + "OfflineHosts": 1, + "MissingInActionHosts": 0, + "NewHosts": 1 + }, + "id": 273, + "query_id": 293, + "status": 0, + "user_id": 1 + } +} +``` + +#### Example with multiple hosts targeted by label ID + +`POST /api/v1/kolide/spec/queries/run` + +##### Request body + +``` +{ + "query": "select instance_id from system_info;" + "selected": { "hosts": [171], "labels": []} +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "campaign": { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "Metrics": { + "TotalHosts": 1, + "OnlineHosts": 0, + "OfflineHosts": 1, + "MissingInActionHosts": 0, + "NewHosts": 1 + }, + "id": 273, + "query_id": 293, + "status": 0, + "user_id": 1 + } +} +``` + +### Run live query by query 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. + +`POST /api/v1/kolide/spec/queries/run` + +#### Parameters + +| 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. | + +#### Example with one host targeted + +`POST /api/v1/kolide/spec/queries/run` + +##### Request body + +``` +{ + "name": "instance_id" + "selected": { "hosts": [171], "labels": [] } +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "campaign": { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "Metrics": { + "TotalHosts": 1, + "OnlineHosts": 0, + "OfflineHosts": 1, + "MissingInActionHosts": 0, + "NewHosts": 1 + }, + "id": 275, + "query_id": 295, + "status": 0, + "user_id": 1 + } +} +``` + +--- + ## Fleet configuration The Fleet server exposes a handful of API endpoints that handle the configuration of Fleet as well as endpoints that manage invitation and enroll secret operations. All the following endpoints require prior authentication meaning you must first log in successfully before calling any of the endpoints documented below. @@ -1303,7 +1865,6 @@ Modifies the Fleet's configuration with the supplied information. } ``` - ##### Default response `Status: 200` @@ -1620,7 +2181,7 @@ Verify the specified invite. ### Get osquery options spec -Returns to osquery options configuration set in Fleet. +Retrieve the osquery options configured via Fleet. `GET /api/v1/kolide/spec/osquery_options`