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

4.69.0 doc changes (#28937)

Browse Source
This commit is contained in:
Rachael Shaw
2025-06-14 14:26:45 -05:00
committed by GitHub
parent 524d66775b
commit ac16428f3c
11 changed files with 540 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Configuration/fleet-server-configuration.md
+15 -1
View File
@@ -633,6 +633,20 @@ The key must be at least 32 bytes long. Run `openssl rand -base64 32` in the Ter
## Auth
## auth_sso_session_validity_period
How long an SSO authentication process can take between initiation and callback. Applies to both users logging into the Fleet web UI and end users during MDM enrollment.
> Note: Once logged in, `session_duration` determines how long a user stays logged into Fleet.
- Default value: `5m` (5 minutes)
- Environment variable: `FLEET_AUTH_SSO_SESSION_VALIDITY_PERIOD`
- Config file format:
```yaml
auth:
sso_session_validity_period: 10m
```
### auth_bcrypt_cost
The bcrypt cost to use when hashing user passwords.
@@ -681,7 +695,7 @@ Size of generated app tokens.
How long invite tokens should be valid for.
- Default value: `5 days`
- Default value: `5d` (5 days)
- Environment variable: `FLEET_APP_INVITE_TOKEN_VALIDITY_PERIOD`
- Config file format:
```yaml
docs/Configuration/yaml-files.md
+33 -1
View File
@@ -460,7 +460,12 @@ Currently, for Fleet-maintained apps and App Store (VPP) apps, the `labels_` and
### packages
- `url` specifies the URL at which the software is located. Fleet will download the software and upload it to S3.
- `hash_sha256` specifies the SHA256 hash of the package file. If provided, and if a software package with that hash has already been uploaded to Fleet, the existing package will be used and download will be skipped. If a package with that hash does not yet exist and a URL was provided, Fleet will download the package, then verify that the hash matches, bailing out if it does not match. If a package with that hash does not yet exist and no URL was provided, the GitOps run will fail.
- `hash_sha256` specifies the SHA256 hash of the package file. If provided, and if a software package with that hash has already been uploaded to Fleet, the existing package will be used and download will be skipped. If a package with that hash does not yet exist, Fleet will download the package, then verify that the hash matches, bailing out if it does not match.
> Without specifying a hash, Fleet downloads each installer for each team on each GitOps run.
> You can specify a hash alone to reference a software package that was previously uploaded to Fleet, whether via the UI, API, or the `fleetctl upload-software` command. If a package with that hash isn't already in Fleet and visible to the user performing the GitOps run, the GitOps run will error.
- `pre_install_query.path` is the osquery query Fleet runs before installing the software. Software will be installed only if the [query returns results](https://fleetdm.com/tables).
- `install_script.path` specifies the command Fleet will run on hosts to install software. The [default script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) is dependent on the software type (i.e. .pkg).
- `uninstall_script.path` is the script Fleet will run on hosts to uninstall software. The [default script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) is dependent on the software type (i.e. .pkg).
@@ -472,6 +477,8 @@ Currently, for Fleet-maintained apps and App Store (VPP) apps, the `labels_` and
#### Example
##### With URL
`lib/software-name.package.yml`:
```yaml
@@ -487,6 +494,15 @@ categories:
self_service: true
```
##### With hash
You can get an output similar to that below when `fleetctl upload-software` successfully uploads a software package.
```yaml
# Mozilla Firefox (Firefox 136.0.1.pkg) version 136.0.1
- hash_sha256: fd22528a87f3cfdb81aca981953aa5c8d7084581b9209bb69abf69c09a0afaaf
```
### app_store_apps
- `app_store_id` is the ID of the Apple App Store app. You can find this at the end of the app's App Store URL. For example, "Bear - Markdown Notes" URL is "https://apps.apple.com/us/app/bear-markdown-notes/id1016366447" and the `app_store_id` is `1016366447`.
@@ -907,6 +923,22 @@ org_settings:
Can only be configured for all teams (`org_settings`).
##### end_user_license_agreement
You can require an end user to agree to an end user license agreement (EULA) before they can use their new Mac. `end_user_authentication` must be configured, and `controls.enable_end_user_authentication` must be set to `true`.
- `end_user_license_agreement` is the path to the PDF document.
##### Example
```yaml
org_settings:
mdm:
end_user_license_agreement: ./lib/eula.pdf
```
Can only be configured for all teams (`org_settings`).
##### apple_server_url
Update this URL if you're self-hosting Fleet and you want your hosts to talk to this URL for MDM features. (If not configured, hosts will use the base URL of the Fleet instance.)
docs/Contributing/reference/api-for-contributors.md
+20 -1
View File
@@ -1715,6 +1715,8 @@ NOTE: when updating a policy, team and platform will be ignored.
The fields `critical`, `script_id`, and `software_title_id` are available in Fleet Premium.
Fleet-maintained policies are unaffected by this endpoint.
##### Default response
`Status: 200`
@@ -3415,7 +3417,7 @@ Gets the result of a uninstall performed on a host, viewed from the My device pa
_Available in Fleet Premium_
Lists the policies applied to the current device.
Lists the policies applied to the current device. Omits Fleet-maintained policies.
`GET /api/v1/fleet/device/{token}/policies`
@@ -4344,6 +4346,23 @@ Run a live script and get results back (5 minute timeout). Live scripts only run
```
## Software
### Confirm installer hashes exist
`GET /api/v1/fleet/software/package_hashes`
| Name | Type | In | Description |
|-------------------|---------|------|----------------------------------------------------|
| team_name | string | query | The name of the team to filter the check to. If not supplied, the user must haave global access, and hashes are checked across the entire instance. |
| sha256 | string | query | **Required**. A comma-separated list of SHA256 hashes, (64 hex characters apiece) to check. Endpoint returns 200 if all specified hashes exist, 404 otherwise. |
#### Example
`GET /api/v1/fleet/software/package_hashes?sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`
##### Default response
`200 OK`
### Update software title name
`PATCH /api/v1/fleet/software/titles/:software_title_id/name`
docs/Contributing/reference/audit-logs.md
+9 -3
View File
@@ -69,13 +69,15 @@ Generated when creating policies.
This activity contains the following fields:
- "policy_id": the ID of the created policy.
- "policy_name": the name of the created policy.
- "fleet_maintained": whether the policy is maintained by Fleet (e.g. automatic install/patch).
#### Example
```json
{
"policy_id": 123,
"policy_name": "foo"
"policy_name": "foo",
"fleet_maintained": false
}
```
@@ -86,13 +88,15 @@ Generated when editing policies.
This activity contains the following fields:
- "policy_id": the ID of the edited policy.
- "policy_name": the name of the edited policy.
- "fleet_maintained": whether the policy is maintained by Fleet (e.g. automatic install/patch).
#### Example
```json
{
"policy_id": 123,
"policy_name": "foo"
"policy_name": "foo",
"fleet_maintained": false
}
```
@@ -103,13 +107,15 @@ Generated when deleting policies.
This activity contains the following fields:
- "policy_id": the ID of the deleted policy.
- "policy_name": the name of the deleted policy.
- "fleet_maintained": whether the policy is maintained by Fleet (e.g. automatic install/patch).
#### Example
```json
{
"policy_id": 123,
"policy_name": "foo"
"policy_name": "foo",
"fleet_maintained": false
}
```
docs/Contributing/reference/configuration-for-contributors.md
+14
View File
@@ -181,6 +181,20 @@ Whether Fleet should enforce the host limit of the license, if true, attempting
enforce_host_limit: true
```
### license.enable_analytics
For approved Fleet Premium customers only.
Whether to send anonymous usage statistics. Overrides the value set by `enable_analytics` in the [Modify configuration](https://fleetdm.com/docs/rest-api/rest-api#modify-configuration) API endpoint.
- Default value: `true`
- Environment variable: `FLEET_LICENSE_ENABLE_ANALYTICS`
- Config file format:
```yaml
license:
enable_analytics: false
```
### FLEET_ENABLE_POST_CLIENT_DEBUG_ERRORS
Use this environment variable to allow `fleetd` to report errors to the server using the [endpoint to report an agent error](./API-for-contributors.md#report-an-agent-error). `fleetd` agents will always report vital errors to Fleet.
docs/REST API/rest-api.md
+228 -51
View File
@@ -508,6 +508,7 @@ Returns a list of the activities that have been performed in Fleet. For a compre
"actor_id": 3,
"actor_gravatar": "",
"actor_email": "",
"actor_api_only": false,
"type": "installed_software",
"fleet_initiated": false,
"details": {
@@ -529,6 +530,7 @@ Returns a list of the activities that have been performed in Fleet. For a compre
"actor_id": 1,
"actor_gravatar": "",
"actor_email": "name@example.com",
"actor_api_only": false,
"type": "created_team",
"fleet_initiated": false,
"details": {
@@ -2340,9 +2342,11 @@ the `software` table.
| os_settings | string | query | Filters the hosts by the status of the operating system settings applied to the hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** |
| os_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** |
| populate_software | string | query | If `false` (or omitted), omits installed software details for each host. If `"without_vulnerability_details"`, include a list of installed software for each host, including which CVEs apply to the installed software versions. `true` adds vulnerability description, CVSS score, and other details when using Fleet Premium. See notes below on performance. |
| populate_policies | boolean | query | If `true`, the response will include policy data for each host. |
| populate_policies | boolean | query | If `true`, the response will include policy data for each host, including Fleet-maintained policies. |
| populate_users | boolean | query | If `true`, the response will include user data for each host. |
| populate_labels | boolean | query | If `true`, the response will include labels for each host. |
| profile_uuid | string | query | **Requires `profile_status`**. The UUID of the profile to download. |
| profile_status | string | query | **Requires `profile_uuid`**. Valid options are 'verified', 'verifying', 'pending', or 'failed'. |
> `software_id` is deprecated as of Fleet 4.42. It is maintained for backwards compatibility. Please use the `software_version_id` instead.
@@ -2508,6 +2512,7 @@ If `after` is being used with `created_at` or `updated_at`, the table must be sp
"resolution": "Fix with these steps...",
"platform": "darwin",
"response": "fail",
"fleet_maintained": true,
"critical": false
}
],
@@ -2803,10 +2808,11 @@ Returns the information of the specified host.
#### Parameters
| Name | Type | In | Description |
|------------------|---------|-------|-------------------------------------------------------------------------------------|
| id | integer | path | **Required**. The host's id. |
| exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. |
| Name | Type | In | Description |
|------------------|---------|-------|-----------------------------------------------------------------------------------------|
| id | integer | path | **Required**. The host's id. |
| exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. |
| exclude_fleet_maintained_policies | boolean | query | If `true`, will omit Fleet-maintained policies from the policies list. |
#### Example
@@ -2978,7 +2984,8 @@ Returns the information of the specified host.
"resolution": "fix with these other steps...",
"platform": "darwin",
"response": "fail",
"critical": false
"critical": false,
"fleet_maintained": false
},
{
"id": 3,
@@ -2988,7 +2995,8 @@ Returns the information of the specified host.
"resolution": "",
"platform": "",
"response": "",
"critical": false
"critical": false,
"fleet_maintained": false
},
{
"id": 1,
@@ -2998,7 +3006,8 @@ Returns the information of the specified host.
"resolution": "fix with these steps...",
"platform": "windows,linux",
"response": "pass",
"critical": false
"critical": false,
"fleet_maintained": false
}
],
"software": [
@@ -3080,6 +3089,8 @@ If `hostname` is specified when there is more than one host with the same hostna
| ---------- | ----------------- | ---- | ------------------------------------------------------------------ |
| identifier | string | path | **Required**. The host's `hostname`, `uuid`, or `hardware_serial`. |
| exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. |
| exclude_fleet_maintained_policies | boolean | query | If `true`, will omit Fleet-maintained policies from the policies list. |
#### Example
@@ -3224,7 +3235,8 @@ If `hostname` is specified when there is more than one host with the same hostna
"created_at": "2022-09-02T18:52:19Z",
"updated_at": "2022-09-02T18:52:19Z",
"response": "fail",
"critical": false
"critical": false,
"fleet_maintained": false
}
],
"software": [
@@ -3766,7 +3778,8 @@ This report includes a subset of host vitals, and simplified policy and vulnerab
"id": 123,
"name": "Google Chrome is up to date",
"critical": true, // Fleet Premium only
"resolution": "Follow the Update Google Chrome instructions here: https://support.google.com/chrome/answer/95414?sjid=6534253818042437614-NA"
"resolution": "Follow the Update Google Chrome instructions here: https://support.google.com/chrome/answer/95414?sjid=6534253818042437614-NA",
"fleet_maintained": false
}
],
"vulnerable_software": [
@@ -4017,28 +4030,6 @@ A `team_id` of `0` returns the statistics for hosts that are not part of any tea
}
```
### Resend host's configuration profile
Resends a configuration profile for the specified host.
`POST /api/v1/fleet/hosts/:id/configuration_profiles/:profile_uuid/resend`
#### Parameters
| Name | Type | In | Description |
| ---- | ---- | -- | ----------- |
| id | integer | path | **Required.** The host's ID. |
| profile_uuid | string | path | **Required.** The UUID of the configuration profile to resend to the host. |
#### Example
`POST /api/v1/fleet/hosts/233/configuration_profiles/fc14a20-84a2-42d8-9257-a425f62bb54d/resend`
##### Default response
`Status: 202`
### Get host's software
> **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
@@ -4508,6 +4499,7 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
"actor_id": 12,
"actor_gravatar": "",
"actor_email": "anna@example.com",
"actor_api_only": false,
"type": "installed_software",
"fleet_initiated": false,
"details": {
@@ -4529,6 +4521,7 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
"actor_id": 12,
"actor_gravatar": "",
"actor_email": "anna@example.com",
"actor_api_only": false,
"type": "ran_script",
"fleet_initiated": true,
"details": {
@@ -4578,6 +4571,7 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
"actor_id": 12,
"actor_gravatar": "",
"actor_email": "anna@example.com",
"actor_api_only": false,
"type": "installed_software",
"fleet_initiated": false,
"details": {
@@ -4599,6 +4593,7 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
"actor_id": 1,
"actor_gravatar": "",
"actor_email": "marko@example.com",
"actor_api_only": false,
"type": "ran_script",
"fleet_initiated": false,
"details": {
@@ -4616,6 +4611,7 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
"actor_id": 1,
"actor_gravatar": "",
"actor_email": "rachael@example.com",
"actor_api_only": false,
"type": "ran_script",
"fleet_initiated": false,
"details": {
@@ -4838,7 +4834,8 @@ Add a dynamic or manual label.
| name | string | body | **Required**. The label's name. |
| description | string | body | The label's description. |
| query | string | body | The query in SQL syntax used to filter the hosts. Only one of either `query` (to create a dynamic label) or `hosts` (to create a manual label) can be included in the request. |
| hosts | array | body | The list of host identifiers (`hardware_serial`, `uuid`, or `hostname`) the label will apply to. Only one of either `query` (to create a dynamic label) or `hosts` (to create a manual label) can be included in the request. |
| hosts | array | body | The list of host identifiers (`hardware_serial`, `uuid`, or `hostname`) the label will apply to. Only one of either `query` (to create a dynamic label), `hosts` (to create a manual label), or `host_ids` (to create a manual label) can be included in the request. |
| host_ids | array | body | The list of Fleet host IDs the label will apply to. Only one of either `query` (to create a dynamic label) or `hosts`/`host_ids` (to create a manual label) can be included in the request.
| platform | string | body | The specific platform for the label to target. Provides an additional filter. Choices for platform are `darwin`, `windows`, `ubuntu`, and `centos`. All platforms are included by default and this option is represented by an empty string. |
If both `query` and `hosts` aren't specified, a manual label with no hosts will be created.
@@ -4894,7 +4891,9 @@ Updates the specified label. Note: Label queries and platforms are immutable. To
| id | integer | path | **Required**. The label's id. |
| name | string | body | The label's name. |
| description | string | body | The label's description. |
| hosts | array | body | If updating a manual label: the list of host identifiers (`hardware_serial`, `uuid`, or `hostname`) the label will apply to. The provided list fully replaces the previous list. |
| hosts | array | body | If updating a manual label: the list of host identifiers (`hardware_serial`, `uuid`, or `hostname`) the label will apply to. The provided list fully replaces the previous list. Only one of either `hosts` or `host_ids` can be included in the request. |
| host_ids | array | body | If updating a manual label: the list of Fleet host IDs the label will apply to. The provided list fully replaces the previous list. Only one of either `hosts` or `host_ids` can be included in the request.
#### Example
@@ -5276,7 +5275,10 @@ Deletes the label specified by ID.
- [Delete custom OS setting (configuration profile)](#delete-custom-os-setting-configuration-profile)
- [Update disk encryption enforcement](#update-disk-encryption-enforcement)
- [Get disk encryption statistics](#get-disk-encryption-statistics)
- [Get OS settings status](#get-os-settings-status)
- [Get OS settings summary](#get-os-settings-summary)
- [Get OS setting (configuration profile) status](#get-os-setting-configuration-profile-status)
- [Resend custom OS setting (configuration profile)](resend-custom-os-setting-configuration-profile)
- [Batch-resend custom OS setting (configuration profile)](batch-resend-custom-os-setting-configuration-profile)
### Add custom OS setting (configuration profile)
@@ -5556,6 +5558,65 @@ solely on the response status code returned by this endpoint.
`Status: 200`
### Resend custom OS setting (configuration profile)
Resends a configuration profile for the specified host.
`POST /api/v1/fleet/hosts/:id/configuration_profiles/:profile_uuid/resend`
#### Parameters
| Name | Type | In | Description |
| ---- | ---- | -- | ----------- |
| id | integer | path | **Required.** The host's ID. |
| profile_uuid | string | path | **Required.** The UUID of the configuration profile to resend to the host. |
#### Example
`POST /api/v1/fleet/hosts/233/configuration_profiles/fc14a20-84a2-42d8-9257-a425f62bb54d/resend`
##### Default response
`Status: 202`
### Batch-resend custom OS setting (configuration profile)
`POST /api/v1/fleet/configuration_profiles/resend/batch`
#### Parameters
| Name | Type | In | Description |
| ------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| profile_uuid | integer | body | **Required**. The UUID of the existing configuration profile you'd like to resend.|
| filters | object | body | **Required**. See [filters](#filters) |
##### Filters
| Name | Type | Description |
| -----------------------| ------- | ----------------------------------------------------------------------------------- |
| profile_status | string | Profile status. Currently, `"failed"` is supported. |
#### Example
`POST /api/v1/fleet/configuration_profiles/batch/resend`
##### Request body
```json
{
"profile_uuid": "f663713f-04ee-40f0-a95a-7af428c351a9",
"filters": {
"profile_status": "failed"
}
}
```
##### Default response
`Status: 202`
### Update disk encryption enforcement
@@ -5617,7 +5678,7 @@ The summary can optionally be filtered by team ID.
```
### Get OS settings status
### Get OS settings summary
> [Get macOS settings statistics](https://github.com/fleetdm/fleet/blob/fleet-v4.40.0/docs/REST%20API/rest-api.md#get-macos-settings-statistics) (`GET /api/v1/fleet/mdm/apple/profiles/summary`) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead.
@@ -5653,6 +5714,35 @@ Get aggregate status counts of profiles for to macOS and Windows hosts that are
}
```
### Get OS setting (configuration profile) status
Get status counts of a single OS settings (configuration profile) enforced on hosts.
`GET /api/v1/fleet/configuration_profile/:profile_uuid/status`
#### Parameters
| Name | Type | In | Description |
| ------------------------- | ------ | ----- | ------------------------------------------------------------------------- |
| profile_uuid | string | query | **Required**. The UUID of configuration profile. |
#### Example
`GET /api/v1/fleet/configuration_profile/f663713f-04ee-40f0-a95a-7af428c351a9/status`
##### Default response
`Status: 200`
```json
{
"verified": 123,
"verifying": 123,
"failed": 123,
"pending": 123,
}
```
---
## Setup experience
@@ -6881,7 +6971,8 @@ _Available in Fleet Premium_
"failing_host_count": 300,
"host_count_updated_at": "2023-12-20T15:23:57Z",
"calendar_events_enabled": true,
"conditional_access_enabled": true
"conditional_access_enabled": true,
"fleet_maintained": false,
"labels_include_any": ["Macs on Sonoma"]
},
{
@@ -6903,6 +6994,7 @@ _Available in Fleet Premium_
"host_count_updated_at": "2023-12-20T15:23:57Z",
"calendar_events_enabled": false,
"conditional_access_enabled": false,
"fleet_maintained": false,
"labels_exclude_any": ["Compliance exclusions", "Workstations (Canary)"],
"run_script": {
"name": "Encrypt Windows disk with BitLocker",
@@ -6928,6 +7020,7 @@ _Available in Fleet Premium_
"host_count_updated_at": "2023-12-20T15:23:57Z",
"calendar_events_enabled": false,
"conditional_access_enabled": false,
"fleet_maintained": false,
"install_software": {
"name": "Adobe Acrobat.app",
"software_title_id": 1234
@@ -6987,6 +7080,7 @@ _Available in Fleet Premium_
"host_count_updated_at": "2023-12-20T15:23:57Z",
"calendar_events_enabled": false,
"conditional_access_enabled": false,
"fleet_maintained": false,
"labels_include_any": ["Macs on Sonoma"]
},
{
@@ -7008,6 +7102,7 @@ _Available in Fleet Premium_
"host_count_updated_at": "2023-12-20T15:23:57Z",
"calendar_events_enabled": false,
"conditional_access_enabled": false,
"fleet_maintained": false
},
{
"id": 136,
@@ -7025,7 +7120,8 @@ _Available in Fleet Premium_
"updated_at": "2022-08-30T15:08:26Z",
"passing_host_count": 10,
"failing_host_count": 9,
"host_count_updated_at": "2023-12-20T15:23:57Z"
"host_count_updated_at": "2023-12-20T15:23:57Z",
"fleet_maintained": false
}
]
}
@@ -7173,6 +7269,7 @@ _Available in Fleet Premium_
"host_count_updated_at": null,
"calendar_events_enabled": true,
"conditional_access_enabled": false,
"fleet_maintained": false,
"labels_include_any": ["Macs on Sonoma"],
"install_software": {
"name": "Adobe Acrobat.app",
@@ -7326,6 +7423,7 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
"failing_host_count": 0,
"host_count_updated_at": null,
"calendar_events_enabled": false,
"fleet_maintained": false,
"labels_include_any": ["Macs on Sonoma"],
"install_software": {
"name": "Adobe Acrobat.app",
@@ -7484,6 +7582,7 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
"host_count_updated_at": null,
"calendar_events_enabled": true,
"conditional_access_enabled": false,
"fleet_maintained": false,
"install_software": {
"name": "Adobe Acrobat.app",
"software_title_id": 1234
@@ -8724,6 +8823,7 @@ This allows you to easily configure scheduled queries that will impact a whole t
- [Run script](#run-script)
- [Get script result](#get-script-result)
- [Batch-run script](#batch-run-script)
- [Get batch script summary](#get-batch-script-summary)
- [Add script](#add-script)
- [Modify script](#modify-script)
- [Delete script](#delete-script)
@@ -8808,6 +8908,7 @@ Gets the result of a script that was executed.
> Note: `created_at` is the creation timestamp of the script execution request.
### Batch-run script
Run a script on multiple hosts.
@@ -8821,7 +8922,18 @@ The script will be added to each host's list of upcoming activities.
| Name | Type | In | Description |
| ---- | ------- | ---- | -------------------------------------------- |
| script_id | integer | body | **Required**. The ID of the existing saved script to run. |
| host_ids | array | body | **Required**. List of host IDs. |
| host_ids | array | body | List of host IDs. Required if `filters` not specified. Only one of `host_ids` or `filters` may be included in the request. | |
| filters | object | body | See [filters](#filters3). Required if `host_ids` not specified. Only one of `host_ids` or `filters` may be included in the request. |
##### Filters
| Name | Type | Description |
| --------------------- | ------- | ----------------------------------------------------------------------------------- |
| query | string | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, and `ipv4`. |
| status | string | Host status. Can either be `new`, `online`, `offline`, `mia` or `missing`. |
| label_id | number | ID of a label to filter by. |
| team_id | number | ID of the team to filter by. |
#### Example
@@ -8830,6 +8942,8 @@ The script will be added to each host's list of upcoming activities.
##### Request body
Request (using `host_ids`):
```json
{
"script_id": 123,
@@ -8837,6 +8951,17 @@ The script will be added to each host's list of upcoming activities.
}
```
Request (using `filters`):
```json
{
"script_id": 123,
"filters": {
"status": "online",
"query": "abc"
}
}
```
##### Default response
`Status: 202`
@@ -8848,7 +8973,48 @@ The script will be added to each host's list of upcoming activities.
}
```
### Get batch script summary
Get statuses and host counts for a batch-run script.
`GET /api/v1/fleet/scripts/batch/summary/:batch_execution_id`
#### Parameters
| Name | Type | In | Description |
| ---- | ------- | ---- | -------------------------------------------- |
| batch_execution_id | string | path | **Required**. The ID returned from a batch script run. |
#### Example
`GET /api/v1/fleet/scripts/batch/summary/abc-def`
##### Request body
```json
{
"batch_execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002"
}
```
##### Default response
`Status: 200`
```json
{
"ran": 12345,
"pending": 234,
"errored": 18,
"canceled": 2,
"targeted": 12599,
"script_id": 555,
"script_name": "my-script.sh",
"team_id": 123
}
```
### Add script
@@ -9260,6 +9426,7 @@ Get a list of all software.
{
"id": 343,
"name": "[Install software] Firefox.app",
"fleet_maintained": false
}
],
},
@@ -9380,7 +9547,7 @@ Get a list of all software versions.
```json
{
"counts_updated_at": "2022-01-01 12:32:00",
"count": 1,
"count": 2,
"software": [
{
"id": 1,
@@ -9557,6 +9724,7 @@ Returns information about the specified software. By default, `versions` are sor
{
"id": 343,
"name": "[Install software] Crowdstrike Agent",
"fleet_maintained": false
}
],
"status": {
@@ -9630,19 +9798,14 @@ Returns information about the specified software. By default, `versions` are sor
{
"id": 345,
"name": "[Install software] Logic Pro",
"fleet_maintained": false
}
],
"status": {
"installed": 3,
"pending": 1,
"failed": 2,
},
"automatic_install_policies": [
{
"id": 343,
"name": "[Install software] Logic.app",
}
],
}
},
"source": "apps",
"browser": "",
@@ -9684,6 +9847,7 @@ Returns information about the specified software version.
{
"software": {
"id": 425224,
"software_title_id": 1337,
"name": "Firefox.app",
"version": "117.0",
"bundle_identifier": "org.mozilla.firefox",
@@ -9801,7 +9965,7 @@ Add a package (.pkg, .msi, .exe, .deb, .rpm, .tar.gz) to install on macOS, Windo
| self_service | boolean | form | Self-service software is optional and can be installed by the end user. |
| labels_include_any | array | form | Target hosts that have any label in the array. |
| labels_exclude_any | array | form | Target hosts that don't have any label in the array. |
| automatic_install | boolean | form | Create a policy that triggers a software install only on hosts missing the software. |
| automatic_install | boolean | form | Only supported for macOS apps. Specifies whether to create a policy that triggers a software install only on hosts missing the software. |
Only one of `labels_include_any` or `labels_exclude_any` can be specified. If neither are specified, all hosts are targeted.
@@ -9864,7 +10028,12 @@ Content-Type: application/octet-stream
"url": "",
"automatic_install_policies": null,
"labels_include_any": null,
"labels_exclude_any": null
"labels_exclude_any": null,
"status": {
"installed": 0,
"pending": 0,
"failed": 0
}
}
}
```
@@ -10031,7 +10200,7 @@ Add App Store (VPP) app purchased in Apple Business Manager.
| team_id | integer | body | **Required**. The team ID. Adds VPP software to the specified team. |
| platform | string | body | The platform of the app (`darwin`, `ios`, or `ipados`). Default is `darwin`. |
| self_service | boolean | body | Only supported for macOS apps. Specifies whether the app shows up on the **Fleet Desktop > My device** page and is available for install by the end user. |
| automatic_install | boolean | form | Only supported for macOS apps. Specifies whether to create a policy that triggers a software install only on hosts missing the software. |
| ensure | string | form | For macOS only, if set to "present" (currently the only valid value if set), create a policy that triggers a software install only on hosts missing the software. |
| labels_include_any | array | form | Target hosts that have any label in the array. |
| labels_exclude_any | array | form | Target hosts that don't have any label in the array. |
@@ -10058,6 +10227,11 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
`Status: 200`
```json
{
"software_title_id": 123
}
```
### Modify App Store app
@@ -10125,6 +10299,7 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
{
"id": 345,
"name": "[Install software] Logic Pro",
"fleet_maintained": false
}
],
"status": {
@@ -10272,7 +10447,8 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
```json
{
"fleet_maintained_app_id": 3,
"team_id": 2
"team_id": 2,
"ensure": "present"
}
```
@@ -10572,6 +10748,7 @@ If no vulnerable OS versions or software were found, but Fleet is aware of the v
"software": [
{
"id": 2363,
"software_title_id": 124,
"name": "Docker Desktop",
"version": "4.9.1",
"source": "programs",