Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

Document the device-authenticated endpoints in API for Contributors (#6406)

Browse Source
This commit is contained in:
Martin Angers
2022-06-29 08:12:20 -04:00
committed by GitHub
parent 3da9f6cb38
commit b9930930f5
3 changed files with 321 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
changes/issue-4904-document-device-endpoints
+1
View File
@@ -0,0 +1 @@
* Documented the device-authenticated endpoints in the API for Contributors document.
docs/Contributing/API-for-contributors.md
+314 -2
View File
@@ -2,7 +2,7 @@
This document includes the Fleet API routes that are helpful when developing or contributing to Fleet.
Unlike the [Fleet REST API documentation](../Using-Fleet/REST-API.md), only the Fleet UI, and fleetctl clients use the API routes in this document:
Unlike the [Fleet REST API documentation](../Using-Fleet/REST-API.md), only the Fleet UI, Fleet Desktop and `fleetctl` clients use the API routes in this document:
- [Get queries spec](#get-queries-spec)
- [Get query spec](#get-query-spec)
@@ -24,6 +24,14 @@ Unlike the [Fleet REST API documentation](../Using-Fleet/REST-API.md), only the
- [Retrieve live query results (SockJS)](#retrieve-live-query-results-sock-js)
- [Run live query by name](#run-live-query-by-name)
- [Apply policies spec](#apply-policies-spec)
- [Device-authenticated routes](#device-authenticated-routes)
- [Get device's host](#get-devices-host)
- [Refetch device's host](#refetch-devices-host)
- [Get device's Google Chrome profiles](#get-devices-google-chrome-profiles)
- [Get device's mobile device management (MDM) and Munki information](#get-devices-mobile-device-management-mdm-and-munki-information)
- [Get device's policies](#get-devices-policies)
- [Get device's API features](#get-devices-api-features)
- [Get device's transparency URL](#get-devices-transparency-url)
### Get queries spec
@@ -1390,7 +1398,7 @@ NOTE: when updating a policy, team and platform will be ignored.
"query": "SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT “” AND filevault_status = ‘on’ LIMIT 1;",
"description": "Checks to make sure that the FileVault feature is enabled on macOS devices.",
"resolution": "Choose Apple menu > System Preferences, then click Security & Privacy. Click the FileVault tab. Click the Lock icon, then enter an administrator name and password. Click Turn On FileVault.",
"platform": "darwin"
"platform": "darwin"
}
]
}
@@ -1400,4 +1408,308 @@ NOTE: when updating a policy, team and platform will be ignored.
`Status: 200`
### Device-authenticated routes
Device-authenticated routes are routes used by the Fleet Desktop application. Unlike most other routes, they are not authenticated with a Fleet user's API token, they use a device-specific token.
#### Get device's host
Returns the host information about the device that makes the request.
`GET /api/v1/fleet/device/{token}`
##### Parameters
| Name | Type | In | Description |
| --------------- | ------ | ----- | ---------------------------------------------------|
| token | string | path | The device's authentication token. |
##### Example
`GET /api/v1/fleet/device/abcdef012456789`
##### Default response
`Status: 200`
```json
{
"host": {
"created_at": "2021-08-19T02:02:22Z",
"updated_at": "2021-08-19T21:14:58Z",
"software": [
{
"id": 408,
"name": "osquery",
"version": "4.5.1",
"source": "rpm_packages",
"generated_cpe": "",
"vulnerabilities": null
},
{
"id": 1146,
"name": "tar",
"version": "1.30",
"source": "rpm_packages",
"generated_cpe": "",
"vulnerabilities": null
},
{
"id": 321,
"name": "SomeApp.app",
"version": "1.0",
"source": "apps",
"bundle_identifier": "com.some.app",
"last_opened_at": "2021-08-18T21:14:00Z",
"generated_cpe": "",
"vulnerabilities": null
}
],
"id": 1,
"detail_updated_at": "2021-08-19T21:07:53Z",
"label_updated_at": "2021-08-19T21:07:53Z",
"last_enrolled_at": "2021-08-19T02:02:22Z",
"seen_time": "2021-08-19T21:14:58Z",
"refetch_requested": false,
"hostname": "23cfc9caacf0",
"uuid": "309a4b7d-0000-0000-8e7f-26ae0815ede8",
"platform": "rhel",
"osquery_version": "4.5.1",
"os_version": "CentOS Linux 8.3.2011",
"build": "",
"platform_like": "rhel",
"code_name": "",
"uptime": 210671000000000,
"memory": 16788398080,
"cpu_type": "x86_64",
"cpu_subtype": "158",
"cpu_brand": "Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz",
"cpu_physical_cores": 12,
"cpu_logical_cores": 12,
"hardware_vendor": "",
"hardware_model": "",
"hardware_version": "",
"hardware_serial": "",
"computer_name": "23cfc9caacf0",
"public_ip": "",
"primary_ip": "172.27.0.6",
"primary_mac": "02:42:ac:1b:00:06",
"distributed_interval": 10,
"config_tls_refresh": 10,
"logger_tls_period": 10,
"team_id": null,
"pack_stats": null,
"team_name": null,
"additional": {},
"gigs_disk_space_available": 46.1,
"percent_disk_space_available": 73,
"users": [
{
"uid": 0,
"username": "root",
"type": "",
"groupname": "root",
"shell": "/bin/bash"
},
{
"uid": 1,
"username": "bin",
"type": "",
"groupname": "bin",
"shell": "/sbin/nologin"
}
],
"labels": [
{
"created_at": "2021-08-19T02:02:17Z",
"updated_at": "2021-08-19T02:02:17Z",
"id": 6,
"name": "All Hosts",
"description": "All hosts which have enrolled in Fleet",
"query": "SELECT 1;",
"platform": "",
"label_type": "builtin",
"label_membership_type": "dynamic"
},
{
"created_at": "2021-08-19T02:02:17Z",
"updated_at": "2021-08-19T02:02:17Z",
"id": 9,
"name": "CentOS Linux",
"description": "All CentOS hosts",
"query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'",
"platform": "",
"label_type": "builtin",
"label_membership_type": "dynamic"
},
{
"created_at": "2021-08-19T02:02:17Z",
"updated_at": "2021-08-19T02:02:17Z",
"id": 12,
"name": "All Linux",
"description": "All Linux distributions",
"query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';",
"platform": "",
"label_type": "builtin",
"label_membership_type": "dynamic"
}
],
"packs": [],
"status": "online",
"display_text": "23cfc9caacf0",
"batteries": [
{
"cycle_count": 999,
"health": "Good"
}
]
},
"org_logo_url": "https://example.com/logo.jpg",
"license": {
"tier": "free",
"expiration": "2031-01-01T00:00:00Z"
}
}
```
#### Refetch device's host
Same as [Refetch host route](../Using-Fleet/REST-API.md#refetch-host) for the current device.
`POST /api/v1/fleet/device/{token}/refetch`
##### Parameters
| Name | Type | In | Description |
| --------------- | ------ | ----- | ---------------------------------------|
| token | string | path | The device's authentication token. |
#### Get device's Google Chrome profiles
Same as [Get host's Google Chrome profiles](../Using-Fleet/REST-API.md#get-hosts-google-chrome-profiles) for the current device.
`GET /api/v1/fleet/device/{token}/device_mapping`
##### Parameters
| Name | Type | In | Description |
| --------------- | ------ | ----- | ---------------------------------------|
| token | string | path | The device's authentication token. |
#### Get device's mobile device management (MDM) and Munki information
Same as [Get host's mobile device management and Munki information](../Using-Fleet/REST-API.md#get-hosts-mobile-device-management-mdm-and-munki-information) for the current device.
`GET /api/v1/fleet/device/{token}/macadmins`
##### Parameters
| Name | Type | In | Description |
| --------------- | ------ | ----- | ---------------------------------------|
| token | string | path | The device's authentication token. |
#### Get device's policies
_Available in Fleet Premium_
Lists the policies applied to the current device.
`GET /api/v1/fleet/device/{token}/policies`
##### Parameters
| Name | Type | In | Description |
| --------------- | ------ | ----- | ---------------------------------------|
| token | string | path | The device's authentication token. |
##### Example
`GET /api/v1/fleet/device/abcdef012456789/policies`
##### Default response
`Status: 200`
```json
{
"policies": [
{
"id": 1,
"name": "SomeQuery",
"query": "SELECT * FROM foo;",
"description": "this is a query",
"resolution": "fix with these steps...",
"platform": "windows,linux",
"response": "pass"
},
{
"id": 2,
"name": "SomeQuery2",
"query": "SELECT * FROM bar;",
"description": "this is another query",
"resolution": "fix with these other steps...",
"platform": "darwin",
"response": "fail"
},
{
"id": 3,
"name": "SomeQuery3",
"query": "SELECT * FROM baz;",
"description": "",
"resolution": "",
"platform": "",
"response": ""
}
]
}
```
#### Get device's API features
Supports the dynamic discovery of API features supported by the server for device-authenticated routes. This allows supporting different versions of Fleet Desktop and Fleet server instances (either can be older or newer) while supporting evolution of the API features. With this mechanism, an older Fleet Desktop can ignore features it doesn't know about, and a newer one can avoid requesting features that the server doesn't know about.
`GET /api/v1/fleet/device/{token}/api_features`
##### Parameters
| Name | Type | In | Description |
| --------------- | ------ | ----- | ---------------------------------------|
| token | string | path | The device's authentication token. |
##### Example
`GET /api/v1/fleet/device/abcdef012456789/api_features`
##### Default response
`Status: 200`
```json
{
"features": {}
}
```
#### Get device's transparency URL
Returns the URL to open when clicking the "Transparency" menu item in Fleet Desktop. Note that _Fleet Premium_ is required to configure a custom transparency URL.
`GET /api/v1/fleet/device/{token}/transparency`
##### Parameters
| Name | Type | In | Description |
| --------------- | ------ | ----- | ---------------------------------------|
| token | string | path | The device's authentication token. |
##### Example
`GET /api/v1/fleet/device/abcdef012456789/transparency`
##### Default response
`Status: 307`
Redirects to the transparency URL.
<meta name="pageOrderInSection" value="800">
server/service/devices.go
+6 -6
View File
@@ -112,7 +112,7 @@ func refetchDeviceHostEndpoint(ctx context.Context, request interface{}, svc fle
host, ok := hostctx.FromContext(ctx)
if !ok {
err := ctxerr.Wrap(ctx, fleet.NewAuthRequiredError("internal error: missing host from request context"))
return getHostResponse{Err: err}, nil
return refetchHostResponse{Err: err}, nil
}
err := svc.RefetchHost(ctx, host.ID)
@@ -138,7 +138,7 @@ func listDeviceHostDeviceMappingEndpoint(ctx context.Context, request interface{
host, ok := hostctx.FromContext(ctx)
if !ok {
err := ctxerr.Wrap(ctx, fleet.NewAuthRequiredError("internal error: missing host from request context"))
return getHostResponse{Err: err}, nil
return listHostDeviceMappingResponse{Err: err}, nil
}
dms, err := svc.ListHostDeviceMapping(ctx, host.ID)
@@ -164,7 +164,7 @@ func getDeviceMacadminsDataEndpoint(ctx context.Context, request interface{}, sv
host, ok := hostctx.FromContext(ctx)
if !ok {
err := ctxerr.Wrap(ctx, fleet.NewAuthRequiredError("internal error: missing host from request context"))
return getHostResponse{Err: err}, nil
return getMacadminsDataResponse{Err: err}, nil
}
data, err := svc.MacadminsData(ctx, host.ID)
@@ -197,7 +197,7 @@ func listDevicePoliciesEndpoint(ctx context.Context, request interface{}, svc fl
host, ok := hostctx.FromContext(ctx)
if !ok {
err := ctxerr.Wrap(ctx, fleet.NewAuthRequiredError("internal error: missing host from request context"))
return getHostResponse{Err: err}, nil
return listDevicePoliciesResponse{Err: err}, nil
}
data, err := svc.ListDevicePolicies(ctx, host)
@@ -229,8 +229,8 @@ func (r *deviceAPIFeaturesRequest) deviceAuthToken() string {
}
type deviceAPIFeaturesResponse struct {
Err error `json:"error,omitempty"`
Features fleet.DeviceAPIFeatures
Err error `json:"error,omitempty"`
Features fleet.DeviceAPIFeatures `json:"features"`
}
func (r deviceAPIFeaturesResponse) error() error { return r.Err }