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

Reorganize Fleet documentation (#12871)

Browse Source 
Closes: #12611

Changes:
- Added three new documentation sections `/docs/get-started/`,
`/docs/configuration` and `/docs/rest api/`
- Updated folder names: `/docs/Using-Fleet/` » `/docs/Using Fleet` and
`/docs/deploying` » `/docs/deploy/`
- Moved `/docs/using-fleet/process-events.md` to `/articles` and updated
the meta tags to change it into a guide.
- Added support for a new meta tag: `navSection`. This meta tag is used
to organize pages in the sidebar navigation on fleetdm.com/docs
- Moved `docs/using-fleet/application-security.md` and
`docs/using-fleet/security-audits.md` to the security handbook.
- Moved `docs/deploying/load-testing.md` and
`docs/deploying/debugging.md` to the engineering handbook.
- Moved the following files/folders:
- `docs/using-fleet/configuration-files/` »
`docs/configuration/configuration-files/`
- `docs/deploying/configuration.md` »
`docs/configuration/fleet-server-configuration.md`
    -  `docs/using-fleet/rest-api.md` » `docs/rest-api/rest-api.md`
- `docs/using-fleet/monitoring-fleet.md` » `docs/deploy/rest-api.md`
- Updated filenames:
- `docs/using-fleet/permissions.md` »
`docs/using-fleet/manage-access.md`
- `docs/using-fleet/adding-hosts.md` »
`docs/using-fleet/enroll-hosts.md`
    -  `docs/using-fleet/teams.md` » `docs/using-fleet/segment-hosts.md`
- `docs/using-fleet/fleet-ctl-agent-updates.md` »
`docs/using-fleet/update-agents.md`
- `docs/using-fleet/chromeos.md` »
`docs/using-fleet/enroll-chromebooks.md`
- Updated the generated markdown in `server/fleet/gen_activity_doc.go`
and `server/service/osquery_utils/gen_queries_doc.go`
- Updated the navigation sidebar and mobile dropdown links on docs pages
to group pages by their `navSection` meta tag.
- Updated fleetdm.com/docs not to show pages in the `docs/contributing/`
folder in the sidebar navigation
- Added redirects for docs pages that have moved.

.

---------

Co-authored-by: Mike Thomas <mthomas@fleetdm.com>
Co-authored-by: Rachael Shaw <r@rachael.wtf>
This commit is contained in:
Eric
2023-07-27 17:40:01 -05:00
committed by GitHub
co-authored by Mike Thomas Rachael Shaw
parent 51b750a34c
commit 8fb22579ea
74 changed files with 870 additions and 608 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Using Fleet/Audit-logs.md
+845
View File
@@ -0,0 +1,845 @@
<!-- DO NOT EDIT. This document is automatically generated. -->
# Audit logs
Fleet logs the following information for administrative actions (in JSON):
- `created_at`: Timestamp of the event.
- `id`: Unique ID of the generated event in Fleet.
- `actor_full_name`: Author user name (missing if the user was deleted).
- `actor_id`: Unique ID of the author in Fleet (missing if the user was deleted).
- `actor_gravatar`: Gravatar URL of the author (missing if the user was deleted).
- `actor_email`: E-mail of the author (missing if the user was deleted).
- `type`: Type of the activity (see all types below).
- `details`: Specific details depending on the type of activity (see details for each activity type below).
Example:
```json
{
"created_at": "2022-12-20T14:54:17Z",
"id": 6,
"actor_full_name": "Gandalf",
"actor_id": 2,
"actor_gravatar": "foo@example.com",
"actor_email": "foo@example.com",
"type": "edited_saved_query",
"details":{
"query_id": 42,
"query_name": "Some query name"
}
}
```
## List of activities and their specific details
### Type `created_pack`
Generated when creating scheduled query packs.
This activity contains the following fields:
- "pack_id": the id of the created pack.
- "pack_name": the name of the created pack.
#### Example
```json
{
"pack_id": 123,
"pack_name": "foo"
}
```
### Type `edited_pack`
Generated when editing scheduled query packs.
This activity contains the following fields:
- "pack_id": the id of the edited pack.
- "pack_name": the name of the edited pack.
#### Example
```json
{
"pack_id": 123,
"pack_name": "foo"
}
```
### Type `deleted_pack`
Generated when deleting scheduled query packs.
This activity contains the following fields:
- "pack_name": the name of the created pack.
#### Example
```json
{
"pack_name": "foo"
}
```
### Type `applied_spec_pack`
Generated when applying a scheduled query pack spec.
This activity does not contain any detail fields.
### Type `created_policy`
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.
#### Example
```json
{
"policy_id": 123,
"policy_name": "foo"
}
```
### Type `edited_policy`
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.
#### Example
```json
{
"policy_id": 123,
"policy_name": "foo"
}
```
### Type `deleted_policy`
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.
#### Example
```json
{
"policy_id": 123,
"policy_name": "foo"
}
```
### Type `applied_spec_policy`
Generated when applying policy specs.
This activity contains a field "policies" where each item is a policy spec with the following fields:
- "name": Name of the applied policy.
- "query": SQL query of the policy.
- "description": Description of the policy.
- "critical": Marks the policy as high impact.
- "resolution": Describes how to solve a failing policy.
- "team": Name of the team this policy belongs to.
- "platform": Comma-separated string to indicate the target platforms.
#### Example
```json
{
"policies": [
{
"name":"Gatekeeper enabled (macOS)",
"query":"SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"critical":false,
"platform":"darwin",
"resolution":"To enable Gatekeeper, on the failing device [...]",
"description":"Checks to make sure that the Gatekeeper feature is [...]"
},
{
"name":"Full disk encryption enabled (Windows)",
"query":"SELECT 1 FROM bitlocker_info WHERE drive_letter='C:' AND protection_status=1;",
"critical":false,
"platform":"windows",
"resolution":"To get additional information, run the following osquery [...]",
"description":"Checks to make sure that full disk encryption is enabled on Windows devices."
}
]
}
```
### Type `created_saved_query`
Generated when creating a new query.
This activity contains the following fields:
- "query_id": the ID of the created query.
- "query_name": the name of the created query.
#### Example
```json
{
"query_id": 123,
"query_name": "foo"
}
```
### Type `edited_saved_query`
Generated when editing a saved query.
This activity contains the following fields:
- "query_id": the ID of the query being edited.
- "query_name": the name of the query being edited.
#### Example
```json
{
"query_id": 123,
"query_name": "foo"
}
```
### Type `deleted_saved_query`
Generated when deleting a saved query.
This activity contains the following fields:
- "query_name": the name of the query being deleted.
#### Example
```json
{
"query_name": "foo"
}
```
### Type `deleted_multiple_saved_query`
Generated when deleting multiple saved queries.
This activity contains the following fields:
- "query_ids": list of IDs of the deleted saved queries.
#### Example
```json
{
"query_ids": [1, 42, 100]
}
```
### Type `applied_spec_saved_query`
Generated when applying a query spec.
This activity contains a field "specs" where each item is a query spec with the following fields:
- "name": Name of the query.
- "description": Description of the query.
- "query": SQL query.
#### Example
```json
{
"specs": [
{
"name":"Get OpenSSL versions",
"query":"SELECT name AS name, version AS version, 'deb_packages' AS source FROM [...]",
"description":"Retrieves the OpenSSL version."
}
]
}
```
### Type `created_team`
Generated when creating teams.
This activity contains the following fields:
- "team_id": unique ID of the created team.
- "team_name": the name of the created team.
#### Example
```json
{
"team_id": 123,
"team_name": "foo"
}
```
### Type `deleted_team`
Generated when deleting teams.
This activity contains the following fields:
- "team_id": unique ID of the deleted team.
- "team_name": the name of the deleted team.
#### Example
```json
{
"team_id": 123,
"team_name": "foo"
}
```
### Type `applied_spec_team`
Generated when applying team specs.
This activity contains a field "teams" where each item contains the team details with the following fields:
- "id": Unique ID of the team.
- "name": Name of the team.
#### Example
```json
{
"teams": [
{
"id": 123,
"name": "foo"
}
]
}
```
### Type `transferred_hosts`
Generated when a user transfers a host (or multiple hosts) to a team (or no team).
This activity contains the following fields:
- "team_id": The ID of the team that the hosts were transferred to, `null` if transferred to no team.
- "team_name": The name of the team that the hosts were transferred to, `null` if transferred to no team.
- "host_ids": The list of identifiers of the hosts that were transferred.
- "host_display_names": The list of display names of the hosts that were transferred (in the same order as the "host_ids").
#### Example
```json
{
"team_id": 123,
"team_name": "Workstations",
"host_ids": [1, 2, 3],
"host_display_names": ["alice-macbook-air", "bob-macbook-pro", "linux-server"]
}
```
### Type `edited_agent_options`
Generated when agent options are edited (either globally or for a team).
This activity contains the following fields:
- "global": "true" if the user updated the global agent options, "false" if the agent options of a team were updated.
- "team_id": unique ID of the team for which the agent options were updated (`null` if global is true).
- "team_name": the name of the team for which the agent options were updated (`null` if global is true).
#### Example
```json
{
"team_id": 123,
"team_name": "foo",
"global": false
}
```
### Type `live_query`
Generated when running live queries.
This activity contains the following fields:
- "targets_count": Number of hosts where the live query was targeted to run.
- "query_sql": The SQL query to run on hosts.
- "query_name": Name of the query (this field is not set if this was not a saved query).
#### Example
```json
{
"targets_count": 5000,
"query_sql": "SELECT * from osquery_info;",
"query_name": "foo"
}
```
### Type `user_added_by_sso`
Generated when new users are added via SSO JIT provisioning
This activity does not contain any detail fields.
### Type `user_logged_in`
Generated when users successfully log in to Fleet.
This activity contains the following fields:
- "public_ip": Public IP of the login request.
#### Example
```json
{
"public_ip": "168.226.215.82"
}
```
### Type `user_failed_login`
Generated when users try to log in to Fleet and fail.
This activity contains the following fields:
- "email": The email used in the login request.
- "public_ip": Public IP of the login request.
#### Example
```json
{
"email": "foo@example.com",
"public_ip": "168.226.215.82"
}
```
### Type `created_user`
Generated when a user is created.
This activity contains the following fields:
- "user_id": Unique ID of the created user in Fleet.
- "user_name": Name of the created user.
- "user_email": E-mail of the created user.
#### Example
```json
{
"user_id": 42,
"user_name": "Foo",
"user_email": "foo@example.com"
}
```
### Type `deleted_user`
Generated when a user is deleted.
This activity contains the following fields:
- "user_id": Unique ID of the deleted user in Fleet.
- "user_name": Name of the deleted user.
- "user_email": E-mail of the deleted user.
#### Example
```json
{
"user_id": 42,
"user_name": "Foo",
"user_email": "foo@example.com"
}
```
### Type `changed_user_global_role`
Generated when user global roles are changed.
This activity contains the following fields:
- "user_id": Unique ID of the edited user in Fleet.
- "user_name": Name of the edited user.
- "user_email": E-mail of the edited user.
- "role": New global role of the edited user.
#### Example
```json
{
"user_id": 42,
"user_name": "Foo",
"user_email": "foo@example.com",
"role": "Observer"
}
```
### Type `deleted_user_global_role`
Generated when user global roles are deleted.
This activity contains the following fields:
- "user_id": Unique ID of the edited user in Fleet.
- "user_name": Name of the edited user.
- "user_email": E-mail of the edited user.
- "role": Deleted global role of the edited user.
#### Example
```json
{
"user_id": 43,
"user_name": "Foo",
"user_email": "foo@example.com",
"role": "Maintainer"
}
```
### Type `changed_user_team_role`
Generated when user team roles are changed.
This activity contains the following fields:
- "user_id": Unique ID of the edited user in Fleet.
- "user_name": Name of the edited user.
- "user_email": E-mail of the edited user.
- "role": Team role set to the edited user.
- "team_id": Unique ID of the team of the changed role.
- "team_name": Name of the team of the changed role.
#### Example
```json
{
"user_id": 43,
"user_name": "Foo",
"user_email": "foo@example.com",
"role": "Maintainer",
"team_id": 5,
"team_name": "Bar"
}
```
### Type `deleted_user_team_role`
Generated when user team roles are deleted.
This activity contains the following fields:
- "user_id": Unique ID of the edited user in Fleet.
- "user_name": Name of the edited user.
- "user_email": E-mail of the edited user.
- "role": Team role deleted from the edited user.
- "team_id": Unique ID of the team of the deleted role.
- "team_name": Name of the team of the deleted role.
#### Example
```json
{
"user_id": 44,
"user_name": "Foo",
"user_email": "foo@example.com",
"role": "Observer",
"team_id": 2,
"team_name": "Zoo"
}
```
### Type `mdm_enrolled`
Generated when a host is enrolled in Fleet's MDM.
This activity contains the following fields:
- "host_serial": Serial number of the host.
- "host_display_name": Display name of the host.
- "installed_from_dep": Whether the host was enrolled via DEP.
- "mdm_platform": Used to distinguish between Apple and Microsoft enrollments. Can be "apple", "microsoft" or not present. If missing, this value is treated as "apple" for backwards compatibility.
#### Example
```json
{
"host_serial": "C08VQ2AXHT96",
"host_display_name": "MacBookPro16,1 (C08VQ2AXHT96)",
"installed_from_dep": true,
"mdm_platform": "apple"
}
```
### Type `mdm_unenrolled`
Generated when a host is unenrolled from Fleet's MDM.
This activity contains the following fields:
- "host_serial": Serial number of the host.
- "host_display_name": Display name of the host.
- "installed_from_dep": Whether the host was enrolled via DEP.
#### Example
```json
{
"host_serial": "C08VQ2AXHT96",
"host_display_name": "MacBookPro16,1 (C08VQ2AXHT96)",
"installed_from_dep": true
}
```
### Type `edited_macos_min_version`
Generated when the minimum required macOS version or deadline is modified.
This activity contains the following fields:
- "team_id": The ID of the team that the minimum macOS version applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that the minimum macOS version applies to, `null` if it applies to devices that are not in a team.
- "minimum_version": The minimum macOS version required, empty if the requirement was removed.
- "deadline": The deadline by which the minimum version requirement must be applied, empty if the requirement was removed.
#### Example
```json
{
"team_id": 3,
"team_name": "Workstations",
"minimum_version": "13.0.1",
"deadline": "2023-06-01"
}
```
### Type `read_host_disk_encryption_key`
Generated when a user reads the disk encryption key for a host.
This activity contains the following fields:
- "host_id": ID of the host.
- "host_display_name": Display name of the host.
#### Example
```json
{
"host_id": 1,
"host_display_name": "Anna's MacBook Pro",
}
```
### Type `created_macos_profile`
Generated when a user adds a new macOS profile to a team (or no team).
This activity contains the following fields:
- "profile_name": Name of the profile.
- "profile_identifier": Identifier of the profile.
- "team_id": The ID of the team that the profile applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that the profile applies to, `null` if it applies to devices that are not in a team.
#### Example
```json
{
"profile_name": "Custom settings 1",
"profile_identifier": "com.my.profile",
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `deleted_macos_profile`
Generated when a user deletes a macOS profile from a team (or no team).
This activity contains the following fields:
- "profile_name": Name of the deleted profile.
- "profile_identifier": Identifier of deleted the profile.
- "team_id": The ID of the team that the profile applied to, `null` if it applied to devices that are not in a team.
- "team_name": The name of the team that the profile applied to, `null` if it applied to devices that are not in a team.
#### Example
```json
{
"profile_name": "Custom settings 1",
"profile_identifier": "com.my.profile",
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `edited_macos_profile`
Generated when a user edits the macOS profiles of a team (or no team) via the fleetctl CLI.
This activity contains the following fields:
- "team_id": The ID of the team that the profiles apply to, `null` if they apply to devices that are not in a team.
- "team_name": The name of the team that the profiles apply to, `null` if they apply to devices that are not in a team.
#### Example
```json
{
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `changed_macos_setup_assistant`
Generated when a user sets the macOS setup assistant for a team (or no team).
This activity contains the following fields:
- "name": Name of the macOS setup assistant file.
- "team_id": The ID of the team that the setup assistant applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that the setup assistant applies to, `null` if it applies to devices that are not in a team.
#### Example
```json
{
"name": "dep_profile.json",
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `deleted_macos_setup_assistant`
Generated when a user deletes the macOS setup assistant for a team (or no team).
This activity contains the following fields:
- "name": Name of the deleted macOS setup assistant file.
- "team_id": The ID of the team that the setup assistant applied to, `null` if it applied to devices that are not in a team.
- "team_name": The name of the team that the setup assistant applied to, `null` if it applied to devices that are not in a team.
#### Example
```json
{
"name": "dep_profile.json",
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `enabled_macos_disk_encryption`
Generated when a user turns on macOS disk encryption for a team (or no team).
This activity contains the following fields:
- "team_id": The ID of the team that disk encryption applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that disk encryption applies to, `null` if it applies to devices that are not in a team.
#### Example
```json
{
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `disabled_macos_disk_encryption`
Generated when a user turns off macOS disk encryption for a team (or no team).
This activity contains the following fields:
- "team_id": The ID of the team that disk encryption applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that disk encryption applies to, `null` if it applies to devices that are not in a team.
#### Example
```json
{
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `added_bootstrap_package`
Generated when a user adds a new bootstrap package to a team (or no team).
This activity contains the following fields:
- "package_name": Name of the package.
- "team_id": The ID of the team that the package applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that the package applies to, `null` if it applies to devices that are not in a team.
#### Example
```json
{
"bootstrap_package_name": "bootstrap-package.pkg",
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `deleted_bootstrap_package`
Generated when a user deletes a bootstrap package from a team (or no team).
This activity contains the following fields:
- "package_name": Name of the package.
- "team_id": The ID of the team that the package applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that the package applies to, `null` if it applies to devices that are not in a team.
#### Example
```json
{
"package_name": "bootstrap-package.pkg",
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `enabled_macos_setup_end_user_auth`
Generated when a user turns on end user authentication for macOS hosts that automatically enroll to a team (or no team).
This activity contains the following fields:
- "team_id": The ID of the team that end user authentication applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that end user authentication applies to, `null` if it applies to devices that are not in a team.
#### Example
```json
{
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `disabled_macos_setup_end_user_auth`
Generated when a user turns off end user authentication for macOS hosts that automatically enroll to a team (or no team).
This activity contains the following fields:
- "team_id": The ID of the team that end user authentication applies to, `null` if it applies to devices that are not in a team.
- "team_name": The name of the team that end user authentication applies to, `null` if it applies to devices that are not in a team.
#### Example
```json
{
"team_id": 123,
"team_name": "Workstations"
}
```
### Type `enabled_windows_mdm`
Windows MDM features are not ready for production and are currently in development. These features are disabled by default. Generated when a user turns on MDM features for all Windows hosts (servers excluded).
This activity does not contain any detail fields.
### Type `disabled_windows_mdm`
Windows MDM features are not ready for production and are currently in development. These features are disabled by default. Generated when a user turns off MDM features for all Windows hosts.
This activity does not contain any detail fields.
<meta name="title" value="Audit logs">
<meta name="pageOrderInSection" value="1400">
<meta name="description" value="Learn how Fleet logs administrative actions in JSON format.">
<meta name="navSection" value="Dig deeper">
docs/Using Fleet/Automations.md
+165
View File
@@ -0,0 +1,165 @@
# Automations
You can configure Fleet to trigger an automation if a certain condition is met. Automations in Fleet can be configured to send a webhook request to a specified URL or to create a ticket in Jira or Zendesk.
[Vulnerability automations](#vulnerability-automations) are triggered if a new vulnerability (CVE) is
detected on at least one host.
[Policy automations](#policy-automations) are triggered if a policy is newly failing on at
least one host.
[Host status automations](#host-status-automations) are triggered if a configured
percentage of hosts have not checked in to Fleet for a configured number of days.
## Vulnerability automations
Vulnerability automations are triggered if Fleet detects a new vulnerability (CVE) on at least one host.
> Note that a CVE is treated as "new" by Fleet if it was published to the national vulnerability database (NVD) within the preceding 30 days by default. This setting can be changed through the [`recent_vulnerabilities_max_age` configuration option](https://fleetdm.com/docs/deploying/configuration#recent-vulnerability-max-age).
Fleet can be configured either to send a webhook request or to create a ticket in Jira or Zendesk. Fleet checks whether to trigger vulnerability automations once per hour by default. This period can be changed through the [`vulnerabilities_periodicity` configuration option](https://fleetdm.com/docs/deploying/configuration#periodicity).
Once a CVE has been detected on any host, automations are not triggered if the CVE is detected on other hosts in subsequent periods. If the CVE has been remediated on all hosts, an automation may be triggered if the CVE is detected subsequently so long as the CVE is treated as "new" by Fleet.
For webhook automations, if a new CVE is detected on more than one host during the same period that the initial detection occurred, a separate webhook request is triggered for each host by default. This behavior can be configured instead to group hosts into batched webhook requests through the [`host_batch_size` configuration option](https://fleetdm.com/docs/using-fleet/configuration-files#webhook-settings-vulnerabilities-webhook-host-batch-size).
Example webhook payload:
```
POST https://server.com/example
```
```json
{
"timestamp": "0000-00-00T00:00:00Z",
"vulnerability": {
"cve": "CVE-2014-9471",
"details_link": "https://nvd.nist.gov/vuln/detail/CVE-2014-9471",
"epss_probability": 0.7, // Premium feature only
"cvss_score": 5.7, // Premium feature only
"cisa_known_exploit": true, // Premium feature only
"cve_published": "2020-10-28T00:00:00Z", // Premium feature only
"hosts_affected": [
{
"id": 1,
"hostname": "macbook-1",
"url": "https://fleet.example.com/hosts/1",
"software_installed_paths": ["/usr/lib/some-path"],
},
{
"id": 2,
"hostname": "macbook-2",
"url": "https://fleet.example.com/hosts/2"
}
]
}
}
```
For ticket automations, one ticket is created per CVE regardless of the number of hosts on which such CVE is detected.
Follow the steps below to configure Jira or Zendesk as a ticket destination:
1. In the top bar of the Fleet UI, select your avatar and then **Settings**.
2. Select **Integrations > Add integration**.
3. Under **Ticket destination** select **Jira** or select **Zendesk**.
4. Enter your ticket destination's credentials.
5. In the top bar, select **Software > Manage automations**.
6. Select **Enable vulnerability automations** and choose **Ticket**.
7. Under **Ticket destination**, select your ticket destination and select **Save**.
The Jira and Zendesk ticket automations are currently in beta.
## Policy automations
Policy automations are triggered if a policy is newly failing on at least one host. Policy automations are triggered separately for each failing policy.
> Note that a policy is "newly failing" if a host updated its response from "no response" to "failing" or from "passing" to "failing."
Fleet can be configured either to send a webhook request or to create a ticket in Jira or Zendesk. Fleet checks whether to trigger policy automations once per day by default. This interval can be updated with the `webhook_settings.interval` configuration option using the [`config` YAML document](https://fleetdm.com/docs/using-fleet/configuration-files#organization-settings) and the `fleetctl apply` command. Note that this interval currently configures both host status and failing policy automations. This interval applies to both creating tickets for failing policies as well as webhooks requests.
For webhooks automations, if a policy is newly failing on more than one host during the same period, a separate webhook request is triggered for each host by default. This behavior can be configured instead to group hosts into batched webhook requests through the [`host_batch_size` configuration option](https://fleetdm.com/docs/using-fleet/configuration-files#webhook-settings-failing-policies-webhook-host-batch-size).
Example webhook payload:
```
POST https://server.com/example
```
```json
{
"timestamp": "0000-00-00T00:00:00Z",
"policy": {
"id": 1,
"name": "Is Gatekeeper enabled?",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices.",
"author_id": 1,
"author_name": "John",
"author_email": "john@example.com",
"resolution": "Turn on Gatekeeper feature in System Preferences.",
"passing_host_count": 2000,
"failing_host_count": 300
},
"hosts": [
{
"id": 1,
"hostname": "macbook-1",
"url": "https://fleet.example.com/hosts/1"
},
{
"id": 2,
"hostname": "macbbook-2",
"url": "https://fleet.example.com/hosts/2"
}
]
}
```
For ticket automations, a single ticket is created per newly failed policy (i.e., multiple tickets are not created if a policy is newly failing on more than one host during the same period).
Follow the steps below to configure Jira or Zendesk as a ticket destination:
1. In the top bar of the Fleet UI, select your avatar and then **Settings**.
2. Select **Integrations > Add integration**.
3. Under **Ticket destination** select **Jira** or select **Zendesk**.
4. Enter your ticket destination's credentials.
5. In the top bar, select **Policies > Manage automations**.
6. Select **Enable policy automations**, check the policies you'd like to listen to, and choose **Ticket**.
7. Under **Ticket destination**, select your ticket destination and select **Save**.
The Jira and Zendesk ticket destinations are currently in beta.
## Host status automations
Host status automations send a webhook request if a configured percentage of hosts have not checked in to Fleet for a configured number of days.
Fleet sends these webhook requests once per day by default. This interval can be updated with the `webhook_settings.interval` configuration option using the [`config` YAML document](https://fleetdm.com/docs/using-fleet/configuration-files#organization-settings) and the `fleetctl apply` command. Note that this interval currently configures both host status and failing policy automations.
Example webhook payload:
```
POST https://server.com/example
```
```json
{
"text": "More than X% of your hosts have not checked into Fleet
for more than X days. You’ve been sent this message
because the Host status webhook is enabeld in your Fleet
instance.",
"data": {
"unseen_hosts": 1,
"total_hosts": 2,
"days_unseen": 3,
}
}
```
To enable and configure host status automations, navigate to **Settings > Organization settings > Host
status webhook** in the Fleet UI.
<meta name="pageOrderInSection" value="1300">
<meta name="description" value="Configure Fleet automations to trigger webhooks or create tickets in Jira and Zendesk for vulnerability, policy, and host status events.">
<meta name="navSection" value="Vuln management">
docs/Using Fleet/CIS-Benchmarks.md
+264
View File
@@ -0,0 +1,264 @@
# CIS Benchmarks
> Available in Fleet Premium
## Overview
CIS Benchmarks represent the consensus-based effort of cybersecurity experts globally to help you protect your systems against threats more confidently.
For more information about CIS Benchmarks check out [Center for Internet Security](https://www.cisecurity.org/cis-benchmarks)'s website.
Fleet has implemented native support for CIS Benchmarks for the following platforms:
- macOS 13.0 Ventura (96 checks)
- Windows 10 Enterprise (496 checks)
[Where possible](#limitations), each CIS Benchmark is implemented with a [policy query](./REST-API.md#policies) in Fleet.
## Requirements
Following are the requirements to use the CIS Benchmarks in Fleet:
- To use these policies, Fleet must have an up-to-date paid license (≥Fleet Premium).
- Devices must be running [`fleetd`](https://fleetdm.com/docs/using-fleet/orbit), the lightweight agent that bundles the latest osqueryd.
- Some CIS Benchmarks explicitly involve verifying MDM-based controls, so devices must be enrolled to an MDM solution. (Any MDM solution works, it doesn't have to be Fleet.)
- On macOS, the orbit executable in Fleetd must have "Full Disk Access", see [Grant Full Disk Access to Osquery on macOS](./Adding-hosts.md#grant-full-disk-access-to-osquery-on-macos).
### MDM required
Some of the policies created by Fleet use the [managed_policies](https://www.fleetdm.com/tables/managed_policies) table. This checks whether an MDM solution has turned on the setting to enforce the policy.
Using MDM is the recommended way to manage and enforce CIS Benchmarks. To learn how to set up MDM in Fleet, visit [here](/docs/using-fleet/mdm-setup).
### Fleetd required
Fleet's CIS Benchmarks require our [osquery manager, Fleetd](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer). This is because Fleetd includes tables which are not part of vanilla osquery in order to accomplish auditing the benchmarks.
## How to add CIS Benchmarks
All CIS policies are stored under our restricted licensed folder `ee/cis/`.
How to import them to Fleet:
```sh
# Download policy queries from Fleet's repository
# macOS 13
wget https://raw.githubusercontent.com/fleetdm/fleet/main/ee/cis/macos-13/cis-policy-queries.yml
# Windows 10 (note the same file name. Rename as needed.)
wget https://raw.githubusercontent.com/fleetdm/fleet/main/ee/cis/win-10/cis-policy-queries.yml
# Apply the downloaded policies to Fleet for both files.
fleetctl apply --context <context> -f <path-to-macOS-13-policies> --policies-team <team-name>
fleetctl apply --context <context> -f <path-to-windows-10-policies> --policies-team <team-name>
```
To apply the policies on a specific team use the `--policies-team` flag:
```sh
fleetctl apply --policies-team "Workstations" -f cis-policy-queries.yml
```
## Limitations
Fleet's current set of benchmarks only implements benchmark *auditing* steps that can be *automated*.
In practice, Fleet is able to cover a large majority of benchmarks:
* macOS 13 Ventura - 96 of 104
* Windows 10 Enterprise - All CIS items (496)
For a list of specific checks which are not covered by Fleet, please visit the section devoted to each benchmark.
### Audit vs. remediation
Each benchmark has two elements:
1. Audit - how to find out whether the host is in compliance with the benchmark
2. Remediation - if the host is out of compliance with the benchmark, how to fix it
Since Fleetd is currently read-only without the ability to execute actions on the host, Fleet does not implement the remediation portions of CIS benchmarks.
To implement automated remediation, you can install a separate agent such as Munki, Chef, Puppet, etc. which has write functionality.
### Manual vs. automated
For both the audit and remediation elements of a CIS Benchmark, there are two types:
1. Automated - the element can be audited or remediated without human intervention
2. Manual - the element requires human intervention to be audited or remediated
Fleet only implements automated audit checks. Manual checks require administrators to implement other processes to conduct the check.
* macOS 13 Ventura - 96 of 104 are automated
* Windows 10 Enterprise - All CIS items (496) are automated
## Levels 1 and 2
CIS designates various benchmarks as Level 1 or Level 2 to describe the level of thoroughness and burden that each benchmark represents.
### Level 1
Items in this profile intend to:
- be practical and prudent;
- provide a clear security benefit; and
- not inhibit the utility of the technology beyond acceptable means.
### Level 2
This profile extends the "Level 1" profile. Items in this profile exhibit one or more of the following characteristics:
- are intended for environments or use cases where security is paramount or acts as defense in depth measure
- may negatively inhibit the utility or performance of the technology.
## macOS 13.0 Ventura benchmark
Fleet's policies have been written against v1.0 of the benchmark. Please refer to the "CIS Apple macOS 13.0 Ventura Benchmark v1.0.0 - 11-14-2022" PDF from the CIS website for full details.
### Checks that require customer decision
CIS has left the parameters of the following checks up to the benchmark implementer. CIS recommends that an organization make a conscious decision for these benchmarks, but does not make a specific recommendation.
Fleet has provided both an "enabled" and "disabled" version of these benchmarks. When both policies are added, at least one will fail. Once your organization has made a decision, you can delete one or the other policy query.
The policy will be appended with a `-enabled` or `-disabled` label, such as `2.1.1.1-enabled`.
- 2.1.1.1 Audit iCloud Keychain
- 2.1.1.2 Audit iCloud Drive
- 2.5.1 Audit Siri
- 2.8.1 Audit Universal Control
Furthermore, CIS has decided to not require the following password complexity settings:
- 5.2.3 Ensure Complex Password Must Contain Alphabetic Characters Is Configured
- 5.2.4 Ensure Complex Password Must Contain Numeric Character Is Configured
- 5.2.5 Ensure Complex Password Must Contain Special Character Is Configured
- 5.2.6 Ensure Complex Password Must Contain Uppercase and Lowercase Characters Is Configured
However, Fleet has provided these as policies. If your organization declines to implement these, simply delete the corresponding policy.
### macOS 13.0 Ventura manual checks
The following CIS benchmark checks cannot be automated and must be addressed manually:
- 2.1.2 Audit App Store Password Settings
- 2.3.3.12 Ensure Computer Name Does Not Contain PII or Protected Organizational Information
- 2.6.6 Audit Lockdown Mode
- 2.11.2 Audit Touch ID and Wallet & Apple Pay Settings
- 2.13.1 Audit Passwords System Preference Setting
- 2.14.1 Audit Notification & Focus Settings
- 3.7 Audit Software Inventory
- 6.2.1 Ensure Protect Mail Activity in Mail Is Enabled
## Windows 10 Enterprise benchmark
Fleet's policies have been written against v1.12.0 of the benchmark. You can refer to the [CIS website](https://www.cisecurity.org/cis-benchmarks) for full details about this version.
### Checks that require a Group Policy Template
38 items require Group Policy Template in place in order to audit them.
These items are tagged with the label `CIS_group_policy_template_required` in the YAML file, and details about the required Group Policy templates can be found in each item's `resolution`.
```
18.3.1 CIS - Ensure 'Apply UAC restrictions to local accounts on network logons' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MS Security Guide\Apply UAC restrictions to local accounts on network logons'
18.3.2 CIS - Ensure 'Configure SMB v1 client driver' is set to 'Enabled: Disable driver (recommended)'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MS Security Guide\Configure SMB v1 client driver'
18.3.3 CIS - Ensure 'Configure SMB v1 server' is set to 'Disabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MS Security Guide\Configure SMB v1 server'
18.3.4 CIS - Ensure 'Enable Structured Exception Handling Overwrite Protection (SEHOP)' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MS Security Guide\Enable Structured Exception Handling Overwrite Protection (SEHOP)'
18.3.5 CIS - Ensure 'Limits print driver installation to Administrators' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MS Security Guide\Limits print driver installation to Administrators'
18.3.6 CIS - Ensure 'NetBT NodeType configuration' is set to 'Enabled: P-node (recommended)'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MS Security Guide\NetBT NodeType configuration'
18.3.7 CIS - Ensure 'WDigest Authentication' is set to 'Disabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MS Security Guide\WDigest Authentication (disabling may require KB2871997)'
18.4.1 CIS - Ensure 'MSS: (AutoAdminLogon) Enable Automatic Logon (not recommended)' is set to 'Disabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (AutoAdminLogon) Enable Automatic Logon (not recommended)'
18.4.2 CIS - Ensure 'MSS: (DisableIPSourceRouting IPv6) IP source routing protection level (protects against packet spoofing)' is set to 'Enabled: Highest protection, source routing is completely disabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (DisableIPSourceRouting IPv6) IP source routing protection level (protects against packet spoofing)'
18.4.3 CIS - Ensure 'MSS: (DisableIPSourceRouting) IP source routing protection level (protects against packet spoofing)' is set to 'Enabled: Highest protection, source routing is completely disabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (DisableIPSourceRouting) IP source routing protection level (protects against packet spoofing)'
18.4.4 CIS - Ensure 'MSS: (DisableSavePassword) Prevent the dial-up password from being saved' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS:(DisableSavePassword) Prevent the dial-up password from being saved'
18.4.5 CIS - Ensure 'MSS: (EnableICMPRedirect) Allow ICMP redirects to override OSPF generated routes' is set to 'Disabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (EnableICMPRedirect) Allow ICMP redirects to override OSPF generated routes'
18.4.6 CIS - Ensure 'MSS: (KeepAliveTime) How often keep-alive packets are sent in milliseconds' is set to 'Enabled: 300,000 or 5 minutes'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (KeepAliveTime) How often keep-alive packets are sent in milliseconds'
18.4.7 CIS - Ensure 'MSS: (NoNameReleaseOnDemand) Allow the computer to ignore NetBIOS name release requests except from WINS servers' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (NoNameReleaseOnDemand) Allow the computer to ignore NetBIOS name release requests except from WINS servers'
18.4.8 CIS - Ensure 'MSS: (PerformRouterDiscovery) Allow IRDP to detect and configure Default Gateway addresses (could lead to DoS)' is set to 'Disabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (PerformRouterDiscovery) Allow IRDP to detect and configure Default Gateway addresses (could lead to DoS)'
18.4.9 CIS - Ensure 'MSS: (SafeDllSearchMode) Enable Safe DLL search mode (recommended)' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (SafeDllSearchMode) Enable Safe DLL search mode (recommended)'
18.4.10 CIS - Ensure 'MSS: (ScreenSaverGracePeriod) The time in seconds before the screen saver grace period expires (0 recommended)' is set to 'Enabled: 5 or fewer seconds'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (ScreenSaverGracePeriod) The time in seconds before the screen saver grace period expires (0 recommended)'
18.4.11 CIS - Ensure 'MSS: (TcpMaxDataRetransmissions IPv6) How many times unacknowledged data is retransmitted' is set to 'Enabled: 3'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS:(TcpMaxDataRetransmissions IPv6) How many times unacknowledged data is retransmitted'
18.4.12 CIS - Ensure 'MSS: (TcpMaxDataRetransmissions) How many times unacknowledged data is retransmitted' is set to 'Enabled: 3'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS:(TcpMaxDataRetransmissions) How many times unacknowledged data is retransmitted'
18.4.13 CIS - Ensure 'MSS: (WarningLevel) Percentage threshold for the security event log at which the system will generate a warning' is set to 'Enabled: 90% or less'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\MSS (Legacy)\MSS: (WarningLevel) Percentage threshold for the security event log at which the system will generate a warning'
18.8.21.2 CIS - Ensure 'Configure registry policy processing: Do not apply during periodic background processing' is set to 'Enabled: FALSE'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Group Policy\Configure registry policy processing'
18.8.22.1.1 CIS - Ensure 'Turn off access to the Store' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off access to the Store'
18.8.22.1.2 CIS - Ensure 'Turn off downloading of print drivers over HTTP' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off downloading of print drivers over HTTP'
18.8.22.1.3 CIS - Ensure 'Turn off handwriting personalization data sharing' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off handwriting personalization data sharing'
18.8.22.1.4 CIS - Ensure 'Turn off handwriting recognition error reporting' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off handwriting recognition error reporting'
18.8.22.1.5 CIS - Ensure 'Turn off Internet Connection Wizard if URL connection is referring to Microsoft.com' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off Internet Connection Wizard if URL connection is referring to Microsoft.com'
18.8.22.1.6 CIS - Ensure 'Turn off Internet download for Web publishing and online ordering wizards' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off Internet download for Web publishing and online ordering wizards'
18.8.22.1.7 CIS - Ensure 'Turn off printing over HTTP' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off printing over HTTP'
18.8.22.1.8 CIS - Ensure 'Turn off Registration if URL connection is referring to Microsoft.com' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off Registration if URL connection is referring to Microsoft.com'
18.8.22.1.9 CIS - Ensure 'Turn off Search Companion content file updates' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off Search Companion content file updates'
18.8.22.1.10 CIS - Ensure 'Turn off the "Order Prints" picture task' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task'
18.8.22.1.11 CIS - Ensure 'Turn off the "Publish to Web" task for files and folders' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off the "Publish to Web" task for files and folders'
18.8.22.1.12 CIS - Ensure 'Turn off the Windows Messenger Customer Experience Improvement Program' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off the Windows Messenger Customer Experience Improvement Program'
18.8.22.1.13 CIS - Ensure 'Turn off Windows Customer Experience Improvement Program' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off Windows Customer Experience Improvement Program'
18.8.22.1.14 CIS - Ensure 'Turn off Windows Error Reporting' is set to 'Enabled'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Internet Communication Management\Internet Communication settings\Turn off Windows Error Reporting'
18.8.25.1 CIS - Ensure 'Support device authentication using certificate' is set to 'Enabled: Automatic'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Kerberos\Support device authentication using certificate'
18.8.26.1 CIS - Ensure 'Enumeration policy for external devices incompatible with Kernel DMA Protection' is set to 'Enabled: Block All'
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Kernel DMA Protection\Enumeration policy for external devices incompatible with Kernel DMA Protection'
18.8.27.1 CIS - Ensure 'Disallow copying of user input methods to the system account for sign-in' is set to 'Enabled' (Automated)
Requires this GPO in place: 'Computer Configuration\Policies\Administrative Templates\System\Locale Services\Disallow copying of user input methods to the system account for sign-in'
```
<meta name="pageOrderInSection" value="1700">
<meta name="title" value="CIS Benchmarks">
<meta name="description" value="Read about how Fleet's implementation of CIS Benchmarks offers consensus-based cybersecurity guidance, covering macOS 13.0 Ventura & Windows 10 Enterprise.">
<meta name="navSection" value="Security compliance">
docs/Using Fleet/Fleet-UI.md
+103
View File
@@ -0,0 +1,103 @@
# Fleet UI
- [Creating a query](#create-a-query)
- [Running a query](#run-a-query)
- [Scheduling a query](#schedule-a-query)
- [Update agent options](#update-agent-options)
<div purpose="embedded-content">
<iframe src="https://www.youtube.com/embed/1VNvg3_drow" allowfullscreen></iframe>
</div>
## Create a query
Queries in Fleet allow you to ask a multitude of questions to help you manage, monitor, and identify threats on your devices.
If you're unsure of what to ask, head to Fleet's [query library](https://fleetdm.com/queries). There you'll find common queries that have been tested by members of our community.
How to create a query:
1. In the top navigation, select **Queries**.
2. Select **Create new query** to navigate to the query console.
3. In the **Query** field, enter your query. Remember, you can find common queries in [Fleet's library](https://fleetdm.com/queries).
4. Select **Save**, enter a name and description for your query, and select **Save query**.
## Run a query
Run a live query to get answers for all of your online hosts.
> Offline hosts won’t respond to a live query because they may be shut down, asleep, or not connected to the internet.
How to run a query:
1. In the top navigation, select **Queries**.
2. In the **Queries** table, find the query you'd like to run and select the query's name to navigate to the query console.
3. Select **Run query** to navigate to the target picker. Select **All hosts** and select **Run**. This will run the query against all your hosts.
The query may take several seconds to complete because Fleet has to wait for the hosts to respond with results.
> Fleet's query response time is inherently variable because of osquery's heartbeat response time. This helps prevent performance issues on hosts.
## Schedule a query
Fleet allows you to schedule queries. Scheduled queries will send data to your log destination automatically.
The default log destination, **filesystem**, is good to start. With this set, data is sent to the `/var/log/osquery/osqueryd.snapshots.log` file on each host’s filesystem. To see which log destinations are available in Fleet, head to the [log destinations page](https://fleetdm.com/docs/using-fleet/log-destinations).
How to schedule a query:
1. In the top navigation, select **Schedule**.
2. Select **Schedule a query**.
3. Select the **Select query** dropdown and choose the query that you'd like to run on a schedule.
4. Select the **Frequency** dropdown and choose how often you'd like the query to run and send results to your log destination. **Every hour** is a good frequency to start. You can change this later.
5. Select **Schedule**.
With Fleet Premium, you can schedule queries for groups of hosts using [the teams feature](https://fleetdm.com/docs/using-fleet/teams). This allows you to collect different data for each group.
> In Fleet Premium, groups of hosts are called "teams."
How to use teams to schedule queries for a group of hosts:
1. If you haven't already, first [create a team](https://fleetdm.com/docs/using-fleet/teams#create-a-team) and [transfer hosts](https://fleetdm.com/docs/using-fleet/teams#transfer-hosts-to-a-team) to the team.
2. In the **Teams** dropdown below the top navigation, select the team.
3. Follow the "How to schedule a query" instructions above.
## Update agent options
<!-- Heading is kept so that the link from the Fleet UI still works -->
<span id="configuring-agent-options" name="configuring-agent-options"></span>
Fleet allows you to update the settings of the agent installed on all your hosts at once. In Fleet, these settings are called "agent options."
The default agent options are good to start.
How to update agent options:
1. In the top navigation, select your avatar and select **Settings**. Only users with the [admin role](https://fleetdm.com/docs/using-fleet/permissions) can access the pages in **Settings**.
2. On the Organization settings page, select **Agent options** on the left side of the page.
3. Use Fleet's YAML editor to configure your osquery options, decorators, or set command line flags.
To see all agent options, head to the [agent options documentation](https://fleetdm.com/docs/using-fleet/configuration-files#agent-options).
4. Place your new setting one level below the `options` key. The new setting's key should be below and one tab to the right of `options`.
5. Select **Save**.
The agents may take several seconds to update because Fleet has to wait for the hosts to check in. Additionally, hosts enrolled with removed enroll secrets must properly rotate their secret to have the new changes take effect.
<meta name="title" value="Fleet UI">
<meta name="pageOrderInSection" value="200">
<meta name="description" value="Learn how to create, run, and schedule queries, as well as update agent options in the Fleet user interface.">
<meta name="navSection" value="The basics">
docs/Using Fleet/Fleet-desktop.md
+66
View File
@@ -0,0 +1,66 @@
# Fleet Desktop
- [Installing Fleet Desktop](#installing-fleet-desktop)
- [Upgrading Fleet Desktop](#upgrading-fleet-desktop)
- [Custom Transparency Link](#custom-transparency-link)
- [Securing Fleet Desktop](#securing-fleet-desktop)
Fleet Desktop is a menu bar icon available on macOS, Windows, and Linux.
At its core, Fleet Desktop gives your end users visibility into the security posture of their machine. This unlocks two key benefits:
* Self-remediation: end users can see which policies they are failing and resolution steps, reducing the need for IT and security teams to intervene
* Scope Transparency: end users can see what the Fleet agent can do on their machines, eliminating ambiguity between end users and their IT and security teams
> Self-remediation is only available for users with Fleet Premium
<div purpose="embedded-content">
<iframe src="https://www.youtube.com/embed/cI2vDG3PbVo" allowfullscreen></iframe>
</div>
## OS support
Fleet Desktop is supported on macOS 12+.
## Installing Fleet Desktop
For information on how to install Fleet Desktop, visit: [Adding Hosts](https://fleetdm.com/docs/using-fleet/adding-hosts#fleet-desktop).
## Upgrading Fleet Desktop
Once installed, Fleet Desktop will be automatically updated via Fleetd. To learn more, visit: [Self-managed agent updates](https://fleetdm.com/docs/deploying/fleetctl-agent-updates#self-managed-agent-updates).
## Custom transparency link
For organizations with complex security postures, they can direct end users to a resource of their choice to serve custom content.
> The custom transparency link is only available for users with Fleet Premium
To turn on the custom transparency link in the Fleet GUI, click on your profile in the top right and select "Settings."
On the settings page, go to "Organization Settings" and select "Fleet Desktop." Use the "Custom transparency URL" text input to specify the custom URL.
For information on how to set the custom transparency link via a YAML configuration file, see the [configuration files](https://fleetdm.com/docs/configuration/fleet-server-configuration#fleet-desktop-settings) documentation.
## Securing Fleet Desktop
Requests sent by Fleet Desktop and the web page that opens when clicking on the "My Device" tray item use a [Random (Version 4) UUID](https://www.rfc-editor.org/rfc/rfc4122.html#section-4.4) token to uniquely identify each host.
The server uses this token to authenticate requests that give host information. Fleet uses the following methods to secure access to this information.
**Rate Limiting**
To prevent brute-forcing, Fleet rate-limits the endpoints used by Fleet Desktop on a per-IP basis. If an IP requests more than 720 invalid UUIDs in a one-hour interval, Fleet will return HTTP error code 429.
**Token Rotation**
```
ℹ️ In Fleet v4.22.0, token rotation for Fleet Desktop was introduced.
```
Starting with Fleet v4.22.0, the server will reject any token older than one hour since it was issued. This helps Fleet protect against unintentionally leaked or brute-forced tokens.
As a consequence, Fleet Desktop will issue a new token if the current token is:
- Rejected by the server
- Older than one hour
This change is imperceptible to users, as clicking on the "My Device" tray item always uses a valid token. If a user visits an address with an expired token, they will get a message instructing them to click on the tray item again.
<meta name="title" value="Fleet Desktop">
<meta name="pageOrderInSection" value="450">
<meta name="description" value="Learn about Fleet Desktop's features for self-remediation and transparency.">
<meta name="navSection" value="The basics">
docs/Using Fleet/Learn-how-to-use-Fleet.md
+58
View File
@@ -0,0 +1,58 @@
# Learn how to use Fleet
- [How to add your device to Fleet](#how-to-add-your-device-to-fleet)
- [How to ask questions about your device](#how-to-ask-questions-about-your-device)
### Overview
In this guide, we'll cover the following concepts:
- How to add your device to Fleet
- How to ask questions about your device
### How to add your device to Fleet
Once you log into Fleet, you are presented with the **Home** page.
To add your device:
1. Select **Add hosts**. In Fleet, devices are referred to as "hosts."
2. Select your device's platform.
3. Select **Download** to download your Fleet osquery installer. The download may take several seconds.
4. Open the Fleet osquery installer and follow the installation steps.
> It may take several seconds for Fleet osquery to send your device's data to Fleet.
In the background, Fleet ran several checks to assess the security hygiene of your device.
> In Fleet, these checks are referred to as "policies."
### How to ask questions about your device
With Fleet, you can ask a multitude of questions to help you manage, monitor, and identify threats on your devices, but if you are just starting out, and unsure of what to ask, Fleet comes baked in with a [query library](https://fleetdm.com/queries) of common questions.
So, let's start by asking the following question about your device:
* What operating system is installed on my device and what is its version?
This question can easily be answered by running this simple query: "Get operating system information."
To run this query on your device:
1. Select **Queries** in the top navigation.
2. Select **Create new query** (or browse your organization's queries for "operating system information" in the search bar).
3. Type the query you would like to run, `SELECT * FROM os_version;`.
4. Select **Run query**, then select **All hosts** (your device may be the only host added to Fleet), and finally select **Run** to execute the query.
The query may take several seconds to complete, because Fleet has to wait for the osquery agents to respond with results. Only online hosts will respond with results to a live query.
> Fleet's query response time is inherently variable because of osquery's heartbeat response time. This helps prevent performance issues on hosts.
When the query has finished, you should see several columns in the "Results" table:
- The "name" column answers: "What operating system is installed on my device?"
- The "version" column answers: "What version of the installed operating system is on my device?"
<meta name="pageOrderInSection" value="100">
<meta name="description" value="Get started with using Fleet by learning how to enroll your device into a Fleet instance and run queries to ask questions about it.">
<meta name="navSection" value="hidden">
docs/Using Fleet/Log-destinations.md
+147
View File
@@ -0,0 +1,147 @@
# Log destinations
- [Log destinations](#log-destinations)
- [Amazon Kinesis Data Firehose](#amazon-kinesis-data-firehose)
- [Snowflake](#snowflake)
- [Splunk](#splunk)
- [Amazon Kinesis Data Streams](#amazon-kinesis-data-streams)
- [AWS Lambda](#aws-lambda)
- [Google Cloud Pub/Sub](#google-cloud-pubsub)
- [Apache Kafka](#apache-kafka)
- [Stdout](#stdout)
- [Filesystem](#filesystem)
- [Sending logs outside of Fleet](#sending-logs-outside-of-fleet)
This document provides a list of the supported log destinations in Fleet.
Log destinations can be used in Fleet to log:
- Osquery [status logs](https://osquery.readthedocs.io/en/stable/deployment/logging/#status-logs).
- Osquery [schedule query result logs](https://osquery.readthedocs.io/en/stable/deployment/logging/#results-logs).
- Fleet audit logs.
To configure each log destination, you must set the correct logging configuration options in Fleet.
Check out the reference documentation for:
- [Osquery status logging configuration options](https://fleetdm.com/docs/deploying/configuration#osquery-status-log-plugin).
- [Osquery result logging configuration options](https://fleetdm.com/docs/deploying/configuration#osquery-result-log-plugin).
- [Activity audit logging configuration options](https://fleetdm.com/docs/deploying/configuration#activity_audit_log_plugin).
## Amazon Kinesis Data Firehose
Logs are written to [Amazon Kinesis Data Firehose (Firehose)](https://aws.amazon.com/kinesis/data-firehose/).
- Plugin name: `firehose`
- Flag namespace: [firehose](https://fleetdm.com/docs/deploying/configuration#firehose)
This is a very good method for aggregating osquery logs into [Amazon S3](https://aws.amazon.com/s3/).
Note that Firehose logging has limits [discussed in the documentation](https://docs.aws.amazon.com/firehose/latest/dev/limits.html). When Fleet encounters logs that are too big for Firehose, notifications will be output in the Fleet logs and those logs _will not_ be sent to Firehose.
## Snowflake
To send logs to Snowflake, you must first configure Fleet to send logs to [Amazon Kinesis Data Firehose (Firehose)](#amazon-kinesis-data-firehose). This is because you'll use the Snowflake Snowpipe integration to direct logs to Snowflake.
If you're using Fleet's [terraform reference architecture](https://github.com/fleetdm/fleet/blob/main/infrastructure/dogfood/terraform/aws/firehose.tf), Firehose is already configured as your log destination.
With Fleet configured to send logs to Firehose, you then want to load the data from Firehose into a Snowflake database. AWS provides instructions on how to direct logs to a Snowflake database [here in the AWS documentation](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-data-stream-ingestion-into-a-snowflake-database-by-using-snowflake-snowpipe-amazon-s3-amazon-sns-and-amazon-kinesis-data-firehose.html)
Snowflake provides instructions on setting up the destination tables and IAM roles required in AWS [here in the Snowflake docs](https://docs.snowflake.com/en/user-guide/data-load-snowpipe-auto-s3.html#prerequisite-create-an-amazon-sns-topic-and-subscription).
## Splunk
To send logs to Splunk, you must first configure Fleet to send logs to [Amazon Kinesis Data Firehose (Firehose)](#amazon-kinesis-data-firehose). This is because you'll enable Firehose to forward logs directly to Splunk.
With Fleet configured to send logs to Firehose, you then want to load the data from Firehose into Splunk. AWS provides instructions on how to enable Firehose to forward directly to Splunk [here in the AWS documentation](https://docs.aws.amazon.com/firehose/latest/dev/create-destination.html#create-destination-splunk).
If you're using Fleet's [terraform reference architecture](https://github.com/fleetdm/fleet/blob/main/infrastructure/dogfood/terraform/aws), you want to replace the S3 destination with a Splunk destination. Hashicorp provides instructions on how to send Firehose data to Splunk [here in the Terraform documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kinesis_firehose_delivery_stream#splunk-destination).
Splunk provides instructions on how to prepare the Splunk platform for Firehose data [here in the Splunk documentation](https://docs.splunk.com/Documentation/AddOns/latest/Firehose/ConfigureFirehose).
## Amazon Kinesis Data Streams
Logs are written to [Amazon Kinesis Data Streams (Kinesis)](https://aws.amazon.com/kinesis/data-streams).
- Plugin name: `kinesis`
- Flag namespace: [kinesis](https://fleetdm.com/docs/deploying/configuration#kinesis)
Note that Kinesis logging has limits [discussed in the
documentation](https://docs.aws.amazon.com/kinesis/latest/dev/limits.html).
When Fleet encounters logs that are too big for Kinesis, notifications appear
in the Fleet server logs. Those logs **will not** be sent to Kinesis.
## AWS Lambda
Logs are written to [AWS Lambda (Lambda)](https://aws.amazon.com/lambda/).
- Plugin name: `lambda`
- Flag namespace: [lambda](https://fleetdm.com/docs/deploying/configuration#lambda)
Lambda processes logs from Fleet synchronously, so the Lambda function used must not take enough processing time that the osquery client times out while writing logs. If there is heavy processing to be done, use Lambda to store the logs in another datastore/queue before performing the long-running process.
Note that Lambda logging has limits [discussed in the
documentation](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html). The maximum size of a log sent to Lambda is 6MB.
When Fleet encounters logs that are too big for Lambda, notifications will be
output in the Fleet logs and those logs _will not_ be sent to Lambda.
Lambda is executed once per log line. As a result, queries with `differential` result logging might result in a higher number of Lambda invocations.
> Queries are assigned `differential` result logging by default in Fleet. `differential` logs have two format options, single (event) and batched. [Check out the osquery documentation](https://osquery.readthedocs.io/en/stable/deployment/logging/#differential-logs) for more information on `differential` logs.
Keep this in mind when using Lambda, as you're charged based on the number of requests for your functions and the duration, the time it takes for your code to execute.
## Google Cloud Pub/Sub
Logs are written to [Google Cloud Pub/Sub (Pub/Sub)](https://cloud.google.com/pubsub).
- Plugin name: `pubsub`
- Flag namespace: [pubsub](https://fleetdm.com/docs/deploying/configuration#pubsub)
Messages over 10MB will be dropped, with a notification sent to the Fleet logs, as these can never be processed by Pub/Sub.
## Apache Kafka
Logs are written to [Apache Kafka (Kafka)](https://kafka.apache.org/) using the [Kafka REST proxy](https://github.com/confluentinc/kafka-rest).
- Plugin name: `kafkarest`
- Flag namespace: [kafka](https://fleetdm.com/docs/deploying/configuration#kafka)
Note that the REST proxy must be in place in order to send osquery logs to Kafka topics.
## Stdout
Logs are written to stdout.
- Plugin name: `stdout`
- Flag namespace: [stdout](https://fleetdm.com/docs/deploying/configuration#stdout)
With the stdout plugin, logs are written to stdout
on the Fleet server. This is typically used for debugging or with a log
forwarding setup that will capture and forward stdout logs into a logging
pipeline.
Note that if multiple load-balanced Fleet servers are used, the logs
will be load-balanced across those servers (not duplicated).
## Filesystem
Logs are written to the local Fleet server filesystem.
The default log destination.
- Plugin name: `filesystem`
- Flag namespace: [filesystem](https://fleetdm.com/docs/deploying/configuration#filesystem)
With the filesystem plugin, logs are written to the local filesystem on the Fleet server. This is typically used with a log forwarding agent on the Fleet server that will push the logs into a logging pipeline.
Note that if multiple load-balanced Fleet servers are used, the logs will be load-balanced across those servers (not duplicated).
## Sending logs outside of Fleet
Osquery agents are typically configured to send logs to the Fleet server (`--logger_plugin=tls`). This is not a requirement, and any other logger plugin can be used even when osquery clients are connecting to the Fleet server to retrieve configuration or run live queries.
See the [osquery logging documentation](https://osquery.readthedocs.io/en/stable/deployment/logging/) for more about configuring logging on the agent.
If `--logger_plugin=tls` is used with osquery clients, the following configuration can be applied on the Fleet server for handling the incoming logs.
<meta name="pageOrderInSection" value="600">
<meta name="description" value="Learn about supported log destinations in Fleet, including Amazon Kinesis, AWS Lambda Snowflake, Splunk, and more.">
<meta name="navSection" value="Security compliance">
docs/Using Fleet/MDM-commands.md
+122
View File
@@ -0,0 +1,122 @@
# Commands
In Fleet you can run MDM commands to take some action on your macOS hosts, like restart the host, remotely.
If a host is offline when you run a command, the host will run the command the next time it comes online.
## Custom commands
You can run custom commands and view a specific command's results using the `fleetctl` command-line interface.
To run a custom command, we will do the following steps:
1. Create a `.xml` with the request payload
2. Choose a target host
3. Run the command using `fleetctl`
4. View our command's results using `fleetctl`
### Step 1: create a `.xml` file
You can run any command supported by Apple's MDM protocol as a custom command in Fleet. To see the list of possible commands, head to [Apple's Commands and Queries documentation](https://developer.apple.com/documentation/devicemanagement/commands_and_queries).
> The "Erase a device" and "Lock a device" commands are only available in Fleet Premium
Each command has example request payloads in XML format. For example, if we want to restart a host, we'll use the "Restart a Device" request payload documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/restart_a_device#3384428).
To run the "Restart a device" command, we'll need to create a `restart-device.xml` file locally and copy and paste the request payload into this `.xml` file:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Command</key>
<dict>
<key>RequestType</key>
<string>RestartDevice</string>
</dict>
<key>CommandUUID</key>
<string>0001_RestartDevice</string>
</dict>
</plist>
```
### Step 2: choose a target host
To run a command, we need to specify a target host by hostname. Commands can only be run on a single host in Fleet.
To find a host's hostname, choose the "Fleet UI" or "fleetctl" method and follow the steps below.
Fleet UI:
1. Head to the **Hosts** page in Fleet and find your target host.
2. Make sure the **Hostname** column is visible (select **Edit columns** if not) and find your host's hostname. You'll need this hostname to run the command.
> A host must be enrolled to Fleet and have MDM turned on to run a command against it.
`fleetctl` CLI:
1. Run the `fleetctl get hosts --mdm` command to get a list of hosts that are enrolled to Fleet and have MDM turned on.
2. Find your host's hostname. You'll need this hostname to run the command.
### Step 3: run the command
1. Run the `fleetctl mdm run-command --payload=restart-device.xml --host=hostname `
> Replace the --payload and --host flags with your `.xml` file and hostname respectively.
2. Look at the on-screen information. In the output you'll see the command required to see results. Be sure to copy this command. If you don't, it will be difficult to view command results later.
### Step 4: View the command's results
1. Run the `fleetctl get mdm-command-results --id=<insert-command-id>`
2. Look at the on-screen information.
Example output:
```
$ fleetctl get mdm-command-results -id 333af7f8-b9a4-4f62-bfb2-f7488fbade21
+--------------------------------------+----------------------+----------------+--------------+---------------------+---------------------------------------------------------+
| ID | TIME | TYPE | STATUS | HOSTNAME | RESULTS |
+--------------------------------------+----------------------+----------------+--------------+---------------------+---------------------------------------------------------+
| 333af7f8-b9a4-4f62-bfb2-f7488fbade21 | 2023-04-04T21:29:29Z | RestartDevice | Acknowledged | xyz-macbook-air.lan | <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE |
| | | | | | plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" |
| | | | | | "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> |
| | | | | | <plist version="1.0"> <dict> <key>CommandUUID</key> |
| | | | | | <string>333af7f8-b9a4-4f62-bfb2-f7488fbade21</string> |
| | | | | | <key>Status</key> |
| | | | | | <string>Acknowledged</string> <key>UDID</key> |
| | | | | | <string>3A529CD6-2154-55EA-9AB7-EB13A43D9F5E</string> |
| | | | | | </dict> </plist> |
+--------------------------------------+----------------------+----------------+--------------+---------------------+---------------------------------------------------------+
```
## List recent commands
You can view the list of the 1,000 latest commands using "fleetctl":
1. Run `fleetctl get mdm-commands`
2. View the list of latest commands, most recent first, along with the timestamp, targeted hostname, command type, execution status and command ID.
Example output:
```
$ fleetctl get mdm-commands
+--------------------------------------+----------------------+--------------------------+--------------+------------------------+
| ID | TIME | TYPE | STATUS | HOSTNAME |
+--------------------------------------+----------------------+--------------------------+--------------+------------------------+
| 024fb3b9-cd8a-40a6-8dd7-6c155f488fd1 | 2023-04-12T18:19:10Z | RestartDevice | Acknowledged | iMac-Pro.local |
+--------------------------------------+----------------------+--------------------------+--------------+------------------------+
| 87dc6325-8bc0-4fc8-9a2f-3901c535456e | 2023-04-12T18:15:01Z | DeviceLock | Acknowledged | iMac-Pro.local |
+--------------------------------------+----------------------+--------------------------+--------------+------------------------+
```
The command ID can be used to view command results as documented in [step 4 of the previous section](#step-4-view-the-commands-results). The possible status values are:
* Pending: the command has yet to run on the host. The host will run the command the next time it comes online.
* Acknowledged: the host responded with "Acknowledged" status via the MDM protocol: the host processed the command successfully.
* Error: the host responded with "Error" status via the MDM protocol: an error occurred. Run the `fleetctl get mdm-command-results --id=<insert-command-id` to view the error.
* CommandFormatError: the host responded with "CommandFormatError" status via the MDM protocol: a protocol error occurred, which can result from a malformed command. Run the `fleetctl get mdm-command-results --id=<insert-command-id` to view the error.
<meta name="pageOrderInSection" value="1506">
<meta name="title" value="MDM commands">
<meta name="description" value="Learn how to run custom MDM commands on macOS hosts using Fleet.">
<meta name="navSection" value="Device management">
docs/Using Fleet/MDM-custom-macOS-settings.md
+105
View File
@@ -0,0 +1,105 @@
# Custom macOS settings
In Fleet you can enforce custom settings on your macOS hosts using configuration profiles.
## Enforce custom settings
To enforce custom settings, we will do the following steps:
1. Create a configuration profile with iMazing Profile editor
2. Upload the profiles to Fleet
3. Confirm the setting is enforced
### Step 1: create a configuration profile
How to create a configuration profile with iMazing Profile Creator:
1. Download and install [iMazing Profile Creator](https://imazing.com/profile-editor).
2. Open iMazing Profile Creator and select macOS in the top bar.
3. Find and choose the settings you'd like to enforce on your macOS hosts. Fleet recommends limiting the scope of the settings a single profile: only include settings from one tab in iMazing Profile Creator (ex. **Restrictions** tab). To enforce more settings, you can create and add additional profiles.
4. In iMazing Profile Creator, select the **General** tab. Enter a descriptive name in the **Name** field. When you add this profile to Fleet, Fleet will display this name in the Fleet UI.
5. In your top menu bar select **File** > **Save As...** and save your configuration profile. Make sure the file is saved as .mobileconfig.
### Step 2: upload configuration profile to Fleet
In Fleet, you can upload configuration profiles using the Fleet UI or fleetctl command-line tool.
The Fleet UI method is a good start if you're just getting familiar with Fleet.
The fleetctl CLI method enables managing configuration profiles in a Git repository. This way you can enforce code review and benefit from Git's change history.
Fleet UI:
1. In the Fleet UI, head to the **Controls > macOS settings > Custom settings** page.
2. Choose which team you want to add the configuration profile to by selecting the desired team in the teams dropdown in the upper left corner. Teams are available in Fleet Premium.
3. Select **Upload** and choose your configuration profile. After your configuration profile is uploaded to Fleet, Fleet will apply the profile to all macOS hosts in the selected team. Thereafter, the profile will be applied to new macOS hosts that enroll to that team.
fleetctl CLI:
1. Choose which team you want to add the configuration profile to.
In this example, we'll add a configuration profile to the "Workstations (canary)" team so that the setting only gets enforced on hosts assigned to this team.
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_settings:
custom_settings:
- /path/to/configuration_profile.mobileconfig
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
To enforce settings on hosts that aren't assigned to a team ("No team"), we'll need to create an `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_settings:
custom_settings:
- /path/to/configuration_profile.mobileconfig
...
```
Learn more about configuration options for hosts that aren't assigned to a team [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_settings.custom_settings` key to your YAML document. This key accepts an array of paths to your configuration profiles.
4. Run the `fleetctl apply -f workstations-canary-config.yml` command to upload the configuration profiles to Fleet. Note that this will override any configuration profiles added using the Fleet UI method.
### Step 3: confirm the setting is enforced
1. In the Fleet UI, head to the **Controls > macOS settings** tab.
2. In the top box, with "Verified," "Verifying," "Pending," and "Failed" statuses, click each status to view a list of hosts:
* Verified: hosts that installed all configuration profiles. Fleet has verified with osquery.
* Latest: hosts that have acknowledged all MDM commands to install configuration profiles. Fleet is verifying the profiles are installed with osquery.
* Verifying: hosts that will receive MDM commands to install configuration profiles when the hosts come online.
* Failed: hosts that failed to install configuration profiles.
3. In the list of hosts, click on an individual host and click the **macOS settings** item to see the status for a specific setting.
<meta name="pageOrderInSection" value="1504">
<meta name="title" value="MDM custom macOS settings">
<meta name="description" value="Learn how to enforce custom settings on macOS hosts using Fleet's configuration profiles.">
<meta name="navSection" value="Device management">
docs/Using Fleet/MDM-disk-encryption.md
+120
View File
@@ -0,0 +1,120 @@
# Disk encryption
_Available in Fleet Premium_
In Fleet, you can enforce disk encryption on your macOS hosts. Apple calls this [FileVault](https://support.apple.com/en-us/HT204837). If turned on, hosts’ disk encryption keys will be stored in Fleet.
You can also enforce custom macOS settings. Learn how [here](./MDM-custom-macOS-settings.md).
## Enforce disk encryption
To enforce disk encryption and have Fleet collect the disk encryption key, we will do the following steps:
1. Enforce disk encryption
2. Share migrations with end users
2. Confirm disk encryption is enforced and Fleet is storing the disk encryption key
### Step 1: enforce disk encryption
To enforce disk encryption, choose the "Fleet UI" or "fleetctl" method and follow the steps below.
Fleet UI:
1. In the Fleet UI, head to the **Controls > macOS settings > Disk encryption** page. Users with the maintainer and admin roles can access the settings pages.
2. Choose which team you want to enforce disk encryption on by selecting the desired team in the teams dropdown in the upper left corner. Teams are available in Fleet Premium.
3. Check the box next to **Turn on** and select **Save**.
`fleetctl` CLI:
1. Choose which team you want to enforce disk encryption on.
In this example, we'll enforce disk encryption on the "Workstations (canary)" team so that disk encryption only gets enforced on hosts assigned to this team.
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_settings:
enable_disk_encryption: true
...
```
To enforce settings on hosts that aren't assigned to a team ("No team"), we'll need to create an `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_settings:
enable_disk_encryption: true
...
```
Learn more about configuration options for hosts that aren't assigned to a team [here](./configuration-files/README.md#organization-settings).
3. Set the `mdm.macos_settings.enable_disk_encryption` configuration option to `true`.
4. Run the `fleetctl apply -f workstations-canary-config.yml` command.
### Step 2: share migration instructions with your end users
In order to complete the process of encrypting the hard drive and escrowing the key in Fleet, your end users must take action. If the host already had disk encryption turned on, the user will need to input their password. If the host did not already have disk encryption turned on, the user will need to log out or restart their computer.
Share [these guided instructions](./MDM-migration-guide.md#how-to-turn-on-disk-encryption) with your end users.
### Step 3: confirm disk encryption is enforced and Fleet is storing the disk encryption key
In the Fleet UI, head to the **Controls > macOS settings > Disk encryption** tab. You will see a table that shows the status of disk encryption on your hosts.
* Applied: disk encryption is turned on and key stored in Fleet. See instructions for viewing the disk encryption key [here](#view-disk-encryption-key).
* Action required (pending): the end user must take action to turn disk encryption on or reset their disk encryption key.
* Enforcing (pending): disk encryption will be enforced and the disk encryption key will be sent to Fleet when the hosts come online.
> It may take up to one hour for Fleet to collect and store the disk encryption keys from all hosts.
* Removing enforcement (pending): disk encryption enforcement will be removed when the hosts come online.
* Failed: hosts that are failed to enforce disk encryption.
You can click each status to view the list of hosts for that status.
## View disk encryption key
The disk encryption key allows you to reset a macOS host's password if you don't know it. This way, if you plan to prepare a host for a new employee, you can login to it and erase all its content and settings.
The key can be accessed by Fleet admin, maintainers, and observers. An event is tracked in the activity feed when a user views the key in Fleet.
How to view the disk encryption key:
1. Select a host on the **Hosts** page.
2. On the **Host details** page, select **Actions > Show disk encryption key**.
> Whenever a disk encryption key is viewed, an activity will be logged. To view activity in the Fleet UI, click on the Fleet icon in the top navigation bar and make sure **All teams** is selected in the teams dropdown.
## Reset a macOS host's password using the disk encryption key
How to reset a macOS host's password using the disk encryption key:
1. Restart the host. If you just unlocked a host that was locked remotely, the host will automatically restart.
2. On the Mac's login screen, enter the incorrect password three times. After the third failed login attempt, the Mac will display a prompt below the password field with the following message: "If you forgot your password, you can reset it using your Recovery Key." Select the right facing arrow at the end of this prompt.
3. Enter the disk encryption key. Note that Apple calls this "Recovery key." Learn how to find a host's disk encryption key [here](#view-disk-encryption-key).
4. The Mac will display a prompt to reset the password. Reset the password and save this password somewhere safe. If you plan to prepare this Mac for a new employee, you'll need this password to erase all content and settings on the Mac.
<meta name="pageOrderInSection" value="1503">
<meta name="title" value="MDM disk encryption">
<meta name="description" value="Learn how to enforce disk encryption on macOS hosts and manage encryption keys with Fleet Premium.">
<meta name="navSection" value="Device management">
docs/Using Fleet/MDM-macOS-setup.md
+234
View File
@@ -0,0 +1,234 @@
# macOS setup
_Available in Fleet Premium_
In Fleet, you can customize the out-of-the-box macOS setup experience for your end users:
* Require end users to authenticate with your identity provider (IdP) and agree to an end user license agreement (EULA) before they can use their new Mac.
* Customize the macOS Setup Assistant by choosing to show or hide specific panes.
* Install a bootstrap package to gain full control over the setup experience by installing tools like Puppet, Munki, DEP notify, custom scrips, and more.
In addition to the customization above, Fleet automatically installs the fleetd agent during out-of-the-box macOS setup. This agent is responsible for reporting host vitals to Fleet and presenting Fleet Desktop to the end user.
MacOS setup features require connecting Fleet to Apple Business Manager (ABM). Learn how [here](./MDM-setup.md#apple-business-manager-abm).
## End user authentication
> This feature is currently in development.
## Bootstrap package
Fleet supports installing a bootstrap package on macOS hosts that automatically enroll to Fleet.
This enables installing tools like [Puppet](https://www.puppet.com/), [Munki](https://www.munki.org/munki/), or [Chef](https://www.chef.io/products/chef-infra) for configuration management and/or running custom scrips and installing tools like [DEP notify](https://gitlab.com/Mactroll/DEPNotify) to customize the setup experience for you end users.
The following are examples of what some organizations deploy using a bootstrap package:
* Munki client to install and keep software up to date on your Macs
* Puppet agent to run custom scripts on your Macs
* Custom scripts and several packages bundled into one bootstrap package using a tool like [InstallApplications](https://github.com/macadmins/installapplications) to install a base set of applications, set the Mac's background, and install the latest macOS update for the end user.
To add a bootstrap package to Fleet, we will do the following steps:
1. Download or generate a package
2. Sign the package
3. Upload the package to Fleet
4. Confirm package is uploaded
### Step 1: download or generate a package
Whether you have to download or generate a package depends on what you want to deploy using your bootstrap package:
* A single client or agent, like Munki or Puppet, can usually be downloaded from the tool's GitHub repository or website. For example, you can download Munki, the Munki client on their [releases page on GitHub](https://github.com/munki/munki/releases).
* To deploy custom scripts, you need to generate a package. The [munkipkg tool](https://github.com/munki/munki-pkg) is a popular tool for generating packages.
Apple requires that your package is a distribution package. Verify that the package is a distribution package:
1. Run the following commands to expand you package and look at the files in the expanded folder:
```bash
$ pkgutil --expand package.pkg expanded-package
$ ls expanded-package
```
If your package is a distribution package should see a `Distribution` file.
2. If you don't see a `Distribution` file, run the following command to convert your package into a distribution package.
```bash
$ productbuild --package package.pkg distrbution-package.pkg
```
Make sure your package is a `.pkg` file.
### Step 2: sign the package
To sign the package we need a valid Developer ID Installer certificate:
1. Login to your [Apple Developer account](https://developer.apple.com/account).
2. Follow Apple's instructions to create a Developer ID Installer certificate [here](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates).
> During step 3 in Apple's instructions, make sure you choose "Developer ID Installer." You'll need this kind of certificate to sign the package.
Confirm that certificate is installed on your Mac by opening the **Keychain Access** application. You should see your certificate in the **Certificates** tab.
3. Run the following command in the **Terminal** application to sign your package with your Developer ID certificate:
```bash
$ productsign --sign "Developer ID Installer: Your name (Serial number)" /path/to/package.pkg /path/to/signed-package.pkg
```
You might be prompted to enter the password for your local account.
Confirm that your package is signed by running the following command:
```bash
$ pkgutil --check-signature /path/to/signed-package.pkg
```
In the output you should see that package has a "signed" status.
### Step 3: upload the package to Fleet
1. Upload the package to a storage location (ex. S3 or GitHub). During step 4, Fleet will retrieve the package from this storage location and host it for deloyment.
> The URL must be accessible by the computer that uploads the package to Fleet.
> * This could be your local computer or the computer that runs your CI/CD workflow.
2. Choose which team you want to add the bootstrap package to.
In this example, we'll add a bootstrap package to the "Workstations (canary)" team so that the package only gets installed on hosts that automatically enroll to this team.
3. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to install the package on hosts that automatically enroll to "No team," we'll need to create an `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.bootstrap_package` key to your YAML document. This key accepts the URL for the storage location of the bootstrap package.
4. Run the fleetctl `apply -f workstations-canary-config.yml` command to upload your bootstrap package to Fleet.
### Step 4: confirm package is uploaded
Confirm that your bootstrap package was uploaded to Fleet:
If you uploaded the package to a team, run `fleetctl get teams --name=Workstations --yaml`.
If you uploaded the package to "No team," run `fleetctl get config`.
You should see the URL for your bootstrap package as the value for `mdm.macos_setup.bootstrap_package`.
## macOS Setup Assistant
When an end user unboxes their new Mac, or starts up a freshly wiped Mac, they're presented with the macOS Setup Assistant. Here they see panes that allow them to configure accessibility, appearance, and more.
In Fleet, you can customize the macOS Setup Assistant by using an automatic enrollment profile.
To customize the macOS Setup Assistant, we will do the following steps:
1. Create an automatic enrollment profile
2. Upload the profile to Fleet
3. Test the custom macOS Setup Assistant
### Step 1: create an automatic enrollment profile
1. Download Fleet's example automatic enrollment profile by navigating to the example [here on GitHub](https://github.com/fleetdm/fleet/blob/main/mdm_profiles/setup_assistant.json) and clicking the download icon.
2. Open the automatic enrollment profile and replace the `profile_name` key with your organization's name.
3. View the the list of macOS Setup Assistant properties (panes) [here in Apple's Device Management documentation](https://developer.apple.com/documentation/devicemanagement/skipkeys) and choose which panes to hide from your end users.
4. In your automatic enrollment profile, edit the `skip_setup_items` array so that it includes the panes you want to hide.
> You can modify properties other than `skip_setup_items`. These are documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/profile).
### Step 2: upload the profile to Fleet
1. Choose which team you want to add the automatic enrollment profile to.
In this example, let's assume you have a "Workstations" team as your [default team](./MDM-setup.md#step-6-optional-set-the-default-team-for-hosts-enrolled-via-abm) in Fleet and you want to test your profile before it's used in production.
To do this, we'll create a new "Workstations (canary)" team and add the automatic enrollment profile to it. Only hosts that automatically enroll to this team will see the custom macOS Setup Assistant.
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to customize the macOS Setup Assistant for hosts that automatically enroll to "No team," we'll need to create a `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
Learn more about configuration options for hosts that aren't assigned to a team [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.macos_setup_assistant` key to your YAML document. This key accepts a path to your automatic enrollment profile.
4. Run the `fleetctl apply -f workstations-canary-config.yml` command to upload the automatic enrollment profile to Fleet.
### Step 3: test the custom macOS Setup Assistant
Testing requires a test Mac that is present in your Apple Business Manager (ABM) account. We will wipe this Mac and use it to test the custom macOS Setup Assistant.
1. Wipe the test Mac by selecting the Apple icon in top left corner of the screen, selecting **System Settings** or **System Preference**, and searching for "Erase all content and settings." Select **Erase All Content and Settings**.
2. In Fleet, navigate to the Hosts page and find your Mac. Make sure that the host's **MDM status** is set to "Pending."
> New Macs purchased through Apple Business Manager appear in Fleet with MDM status set to "Pending." Learn more about these hosts [here](./MDM-setup.md#pending-hosts).
3. Transfer this host to the "Workstations (canary)" team by selecting the checkbox to the left of the host and selecting **Transfer** at the top of the table. In the modal, choose the Workstations (canary) team and select **Transfer**.
4. Boot up your test Mac and complete the custom out-of-the-box setup experience.
<meta name="pageOrderInSection" value="1505">
<meta name="title" value="MDM macOS setup">
<meta name="description" value="Customize your macOS setup experience with Fleet Premium by managing user authentication, Setup Assistant panes, and installing bootstrap packages.">
<meta name="navSection" value="Device management">
docs/Using Fleet/MDM-macOS-updates.md
+164
View File
@@ -0,0 +1,164 @@
# macOS updates
## End user macOS update reminders via Nudge
_Available in Fleet Premium_
End users can be reminded and encouraged to update macOS (via [Nudge](https://github.com/macadmins/nudge)).
![Nudge window](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/nudge-window.png)
A Fleet admin can set a minimum version and deadline for Fleet-enrolled hosts. If an end user's machine is below the minimum version, the Nudge window above will periodically appear to encourage them to upgrade. The end user has the option to defer the update, but as the deadline approaches, the Nudge window appears more frequently.
When the end user machine is below the minimum version, Nudge applies the following behavior:
| | > 1 day before deadline | < 1 day before deadline | past deadline |
| ------------------------------------ | ----------------------- | ----------------------- | --------------------- |
| Nudge window frequency | Once a day at 8pm GMT | Once every 2 hours | Immediately on login |
| End user can defer | ✅ | ✅ | ❌ |
| Nudge window is dismissable | ✅ | ✅ | ❌ |
### How to set up
To set the macOS updates settings in the UI, visit the **Controls** section and then select the **macOS updates** tab.
To set the macOS updates settings via CLI, use the configurations listed [here](https://fleetdm.com/docs/using-fleet/configuration-files#mdm-macos-updates).
### Requirements
- Fleet Premium or Ultimate
- [Fleetd](https://fleetdm.com/docs/using-fleet/fleetd) with Fleet Desktop enabled
### End user experience
After the user clicks "update" in the Nudge window, they will be taken to the standard Apple software update screen:
![Apple software update screen on macOS 12](https://user-images.githubusercontent.com/5359586/228936740-2e8acf2e-6523-4710-9b3f-8243398bd98e.png)
Here, the user would follow Apple's standard two-step process for macOS updates:
1. Download the macOS update. This occurs in the background and does not interrupt the end user's work.
2. Initiate the update which does prevent the end user from using the host for a time.
On Intel Macs, Fleet triggers step 1 (downloading the macOS update) programmatically when a new version is available. This way, when the user arrives on the software update screen, they only need to initiate step 2.
> On Macs with Apple Silicon (e.g. M1), downloading the macOS update may require end user action. Apple doesn't support downloading the update programmatically on Macs with Apple silicon.
Step 2 (installing the update) always requires end user action.
### Known issues
#### Apple Rapid Security Responses (RSRs)
Currently, end user macOS update reminders via Nudge don't support RSR versions (ex. "13.4.1 (a)").
You can use custom MDM commands in Fleet to trigger built-in macOS update reminders for RSRs. Learn how [here](#end-user-macos-update-via-built-in-macos-notifications).
#### Mac is up to date
Sometimes after the end user clicks "update" on the Nudge window, the end user's Mac will say that macOS is up to date when it isn't. This known issue can create a frustrating experience for the end user. Ask the end user to follow the steps below to troubleshoot:
1. From the Apple menu in the top left corner of your screen, select **System Settings** or **System Preferences**.
2. In the search bar, type "Software Update." Select **Software Update**.
3. Type "Command (⌘)-R" to check for updates. If you see an available update, select **Restart Now** to update.
4. If you still don't see an available update, from the Apple menu in the top left corner of your screen, select **Restart...** to restart your Mac.
5. After your Mac restarts, from the Apple menu in the top left corner of your screen, select **System Settings** or **System Preferences**.
6. In the search bar, type "Software Update." Select **Software Update** and select **Restart Now** to update.
## End user macOS update via built-in macOS notifications
Built-in macOS update reminders are available in Fleet Free and Fleet Premium.
To trigger these reminders, we will do the following steps:
1. Force a macOS update scan
2. List available macOS updates
3. Trigger macOS update reminder
### Step 1: force a macOS update scan
Use the request payload below when running a custom MDM command with Fleet. Documentation on how to run a custom command is [here](./MDM-commands#custom-commands).
Request payload:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Command</key>
<dict>
<key>ForceUpdateScan</key>
<true/>
<key>RequestType</key>
<string>ScheduleOSUpdateScan</string>
</dict>
</dict>
</plist>
```
### Step 2: list available macOS updates
1. Run another custom MDM command using the request payload below.
Request payload:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Command</key>
<dict>
<key>RequestType</key>
<string>AvailableOSUpdates</string>
</dict>
</dict>
</plist>
```
2. Copy the `ProductKey` from the command's results. Documentation on how to view a command's results is [here](./MDM-commands#step-4-view-the-commands-results).
Example product key: `MSU_UPDATE_22F770820d_patch_13.4.1_rsr`
### Step 3: trigger macOS update reminder
Run another custom MDM command using the request payload below. Replace the product key with your product key.
> This payload will trigger the "Install ASAP" behavior which displays a macOS notification with a 60 seconds timer before the Mac automatically restarts. The end user can dismiss the timer. To trigger different behavior, update the `InstallAction`. Options are documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/scheduleosupdatecommand/command/updatesitem).
Request payload:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Command</key>
<dict>
<key>RequestType</key>
<string>ScheduleOSUpdate</string>
<key>Updates</key>
<array>
<dict>
<key>InstallAction</key>
<string>InstallASAP</string>
<key>ProductKey</key>
<string>MSU_UPDATE_22F770820d_patch_13.4.1_rsr</string>
</dict>
</array>
</dict>
</dict>
</plist>
```
<meta name="pageOrderInSection" value="1502">
<meta name="title" value="MDM macOS updates">
<meta name="description" value="Learn how to manage macOS updates and set up end user reminders with Fleet MDM.">
<meta name="navSection" value="Device management">
docs/Using Fleet/MDM-migration-guide.md
+121
View File
@@ -0,0 +1,121 @@
# Migration
This section provides instructions for migrating your hosts away from your old MDM solution to Fleet.
## Requirements
1. A [deployed Fleet instance](../Deploying/Introduction.md)
2. [Fleet connected to Apple](./MDM-setup.md)
## Preparing to migrate manually enrolled hosts
1. [Enroll](./Adding-hosts.md) your hosts to Fleet with [Fleetd and Fleet Desktop](https://fleetdm.com/docs/using-fleet/adding-hosts#including-fleet-desktop)
2. Ensure your end users have access to an admin account on their Mac. End users won't be able to migrate on their own if they have a standard account.
3. In your old MDM solution, unenroll the hosts to be migrated. MacOS does not allow multiple MDMs to be installed at once.
4. Send [these guided instructions](#instructions-for-end-users) to your end users to complete the final few steps via Fleet Desktop.
* Note that there will be a gap in MDM coverage between when the host is unenrolled from the old MDM and when the host turns on MDM in Fleet.
## Preparing to migrate automatically enrolled (DEP) hosts
> Automatic enrollment is available in Fleet Premium or Ultimate
1. Connect Fleet to Apple Business Manager (ABM). Learn how [here](./MDM-setup.md#apple-business-manager-abm).
2. [Enroll](./Adding-hosts.md) your hosts to Fleet with [Fleetd and Fleet Desktop](https://fleetdm.com/docs/using-fleet/adding-hosts#including-fleet-desktop)
3. Ensure your end users have access to an admin account on their Mac. End users won't be able to migrate on their own if they have a standard account.
4. Migrate your hosts to Fleet in ABM:
1. In ABM, unassign the existing hosts' MDM server from the old MDM solution: In ABM, select **Devices** and then select **All Devices**. Then, select **Edit** next to **Edit MDM Server**, select **Unassign from the current MDM**, and select **Continue**.
2. In ABM, assign these hosts' MDM server to Fleet: In ABM, select **Devices** and then select **All Devices**. Then, select **Edit** next to **Edit MDM Server**, select **Assign to the following MDM:**, select your Fleet server in the dropdown, and select **Continue**.
5. In your old MDM solution, unenroll the hosts to be migrated. MacOS does not allow multiple MDMs to be installed at once.
6. Send [these guided instructions](#instructions-for-end-users) to your end users to complete the final few steps via Fleet Desktop.
* Note that there will be a gap in MDM coverage between when the host is unenrolled from the old MDM and when the host turns on MDM in Fleet.
## FileVault recovery keys
_Available in Fleet Premium_
When migrating from a previous MDM, end users need to take action to escrow FileVault keys to Fleet. The **My device** page in Fleet Desktop will present users with instructions to reset their key.
To start, enforce FileVault (disk encryption) and escrow in Fleet. Learn how [here](./MDM-disk-encryption.md).
After turning on disk encryption in Fleet, share [these guided instructions](#how-to-turn-on-disk-encryption) with your end users.
If your old MDM solution did not enforce disk encryption, the end user will need to restart or log out of the host.
If your old MDM solution did enforce disk encryption, the end user will need to reset their disk encryption key by following the prompt on the My device page and inputting their password.
## Activation Lock Bypass codes
In Fleet, the [Activation Lock](https://support.apple.com/en-us/HT208987) feature is disabled by default for automatically enrolled (DEP) hosts.
If a host under the old MDM solution has Activation Lock enabled, we recommend asking the end user to follow these instructions to disable Activation Lock before migrating this host to Fleet: https://support.apple.com/en-us/HT208987.
This is because if the Activation Lock is enabled, you will need the Activation Lock bypass code to successfully wipe and reuse the Mac.
However, Activation Lock bypass codes can only be retrieved from the Mac up to 30 days after the device is enrolled. This means that when migrating from your old MDM solution, it’s likely that you’ll be unable to retrieve the Activation Lock bypass code.
## Migrating settings
To enforce the same settings on your macOS hosts in Fleet as you did using your old MDM solution, you can migrate these settings to Fleet to reduce manual work.
If your old MDM solution enforces FileVault, follow [these instructions](./MDM-disk-encryption.md) to enforce FileVault (disk encryption) using Fleet.
For all other settings:
1. Check if your old MDM solution is able to export settings as .mobileconfig files. If it does, download these files.
* If it does not export settings, you will need to re-create the configuration profiles. Learn how to do that [here](./MDM-custom-macOS-settings.md#step-1-create-a-configuration-profile)
2. Create [teams](https://fleetdm.com/docs/using-fleet/teams) according to the needs of your organization
3. Follow the instructions to add configuration profiles to Fleet [here](./MDM-custom-macOS-settings.md#step-2-upload-configuration-profile-to-fleet).
## Instructions for end users
Your organization uses Fleet to check if all devices meet its security policies.
Fleet includes device management features (called “MDM”) that allow your IT team to change settings remotely on your Mac. This lets your organization keep your Mac up to date so you don’t have to.
Want to know what your organization can see? Read about [transparency](https://fleetdm.com/transparency).
### How to turn on MDM:
1. Select the Fleet icon in your menu bar and select **My device**.
![Fleet icon in menu bar](https://raw.githubusercontent.com/fleetdm/fleet/main/website/assets/images/articles/fleet-desktop-says-hello-world-cover-1600x900@2x.jpg)
2. On your **My device** page, select **Turn on MDM** the button in the yellow banner and follow the instructions.
- If you don’t see the yellow banner or the **Turn on MDM** button, select the purple **Refetch** button at the top of the page.
- If you still don't see the **Turn on MDM** button or the **My device** page presents you with an error, please contact your IT administrator.
<img width="1400" alt="My device page - turn on MDM" src="https://user-images.githubusercontent.com/5359586/229950406-98343bf7-9653-4117-a8f5-c03359ba0d86.png">
#### Automatic Enrollment (ADE)
1. If your device is enrolled in Apple Business Manager (ABM) and assigned to the Fleet server, the end user will receive a "Device Enrollment: &lt;organization&gt; can automatically configure your Mac." system notification within the macOS Notifications Center.
2. After the end user clicks on the system notification, macOS will open the "Profiles" System Setting and ask the user to "Allow Device Enrollment: &lt;organization&gt; can automatically configure your Mac based on settings provided by your System Administrator."
3. If the end user does not Allow the setting, the system notification will continue to nag the end user until the setting has been allowed.
4. Once this setting has been approved, the MDM enrollment profile cannot be removed by the end user.
#### Manual Enrollment
1. If your device is not enrolled in Apple Business Manager (ABM), the end user will be given the option to manually download the MDM enrollment profile.
2. Once downloaded, the user will receive a system notification that the Device Enrollment profile has been needs to be installed in the System Settings &gt; Profiles section.
2. After installation, the MDM enrollment profile can be removed by the end user at any time.
### How to turn on disk encryption
1. Select the Fleet icon in your menu bar and select **My device**.
![Fleet icon in menu bar](https://raw.githubusercontent.com/fleetdm/fleet/main/website/assets/images/articles/fleet-desktop-says-hello-world-cover-1600x900@2x.jpg)
2. On your **My device** page, follow the disk encryption instructions in the yellow banner.
- If you don’t see the yellow banner, select the purple **Refetch** button at the top of the page.
- If you still don't see the yellow banner after a couple minutes or if the **My device** page presents you with an error, please contact your IT administrator.
<img width="1399" alt="My device page - turn on disk encryption" src="https://user-images.githubusercontent.com/5359586/229950451-cfcd2314-a993-48db-aecf-11aac576d297.png">
<meta name="pageOrderInSection" value="1501">
<meta name="title" value="MDM migration guide">
<meta name="description" value="Instructions for migrating hosts away from an old MDM solution to Fleet.">
<meta name="navSection" value="Device management">
docs/Using Fleet/MDM-setup.md
+286
View File
@@ -0,0 +1,286 @@
# MDM setup
## Supported macOS versions
macOS 12 (Monterey) and higher.
## Overview
MDM features require Apple's Push Notification service (APNs) to control and secure Apple devices. This guide will walk you through how to generate and upload a valid APNs certificate to Fleet in order to use Fleet's MDM features.
[Automated Device Enrollment](https://support.apple.com/en-us/HT204142) allows Macs to automatically enroll to Fleet when they are first set up. This guide will also walk you through how to connect Apple Business Manager (ABM) to Fleet.
> **Note** you are only required to connect Apple Business Manager (ABM) to Fleet if you are using Automated Device Enrollment AKA Device Enrollment Program (DEP) AKA "Zero-touch."
## Requirements
To use Fleet's MDM features you need to have:
- A [deployed Fleet instance](../Deploying/Introduction.md).
- A Fleet user with the admin role.
## Apple Push Notification service (APNs)
Apple uses APNs to authenticate and manage interactions between Fleet and the host.
This section will show you how to:
1. Generate the files to connect Fleet to APNs.
2. Generate an APNs certificate from Apple Push Certificates Portal.
3. Configure Fleet with the required files.
### Step 1: generate the required files
For the MDM protocol to function, we need to generate the four following files:
- APNs certificate
- APNs private key
- Simple Certificate Enrollment Protocol (SCEP) certificate
- SCEP private key
The APNs certificates serve as authentication between Fleet and Apple, while the SCEP certificates serve as authentication between Fleet and hosts.
Use either of the following methods to generate the necessary files:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Under **Apple Push Certificates Portal**, select **Request**, then fill out the form. This should generate three files and send an email to you with an attached CSR file.
#### Fleetctl CLI
Run the following command to download three files and send an email to you with an attached CSR file.
```
fleetctl generate mdm-apple --email <email> --org <org>
```
### Step 2: generate an APNs certificate
1. Log in to or enroll in [Apple Push Certificates Portal](https://identity.apple.com).
2. Select **Create a Certificate**.
3. Upload your CSR and input a friendly name, such as "Fleet."
4. Download the APNs certificate.
> **Important** Take note of the Apple ID you use to sign into Apple Push Certificates Portal. You'll need to use the same Apple ID when renewing your APNs certificate.
### Step 3: configure Fleet with the generated files
Restart the Fleet server with the contents of the APNs certificate, APNs private key, SCEP certificate, and SCEP private key in the following environment variables:
* [FLEET_MDM_APPLE_APNS_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-cert-bytes)
* [FLEET_MDM_APPLE_APNS_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-key-bytes)
* [FLEET_MDM_APPLE_SCEP_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-cert-bytes)
* [FLEET_MDM_APPLE_SCEP_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-key-bytes)
> You do not need to provide the APNs CSR which was emailed to you.
### Step 4: confirm that Fleet is set up correctly
Use either of the following methods to confirm that Fleet is set up. You should see information about the APNs certificate such as serial number and renewal date.
#### Fleet UI
Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
#### Fleetctl CLI
```
fleetctl get mdm-apple
```
## Renewing APNs
> **Important** Apple requires that APNs certificates are renewed anually.
> - If your certificate expires, you will have to turn MDM off and back on for all macOS hosts.
> - Be sure to use the same Apple ID from year-to-year. If you don't, you will have to turn MDM off and back on for all macOS hosts.
This section will guide you through how to:
1. Generate the files required to renew your APNs certificate.
2. Renew your APNs certificate in Apple Push Certificates Portal.
3. Configure Fleet with the required files.
4. Confirm that Fleet is set up correctly.
Use either of the following methods to see your APNs certificate's renewal date and other important information:
#### Fleet UI
Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
#### Fleetctl CLI
```
fleetctl get mdm-apple
```
### Step 1: generate the required files
- A new APNs certificate.
- A new APNs private key.
Run the following command in `fleetctl`. This will download three files and send an email to you with an attached CSR file. You may ignore the SCEP certificate and SCEP key as you do not need these to renew APNs.
```
fleetctl generate mdm-apple --email <email> --org <org>
```
### Step 2: renew APNs certificate
1. Log in to or enroll in [Apple Push Certificates Portal](https://identity.apple.com) using the same Apple ID you used to get your original APNs certificate.
2. Click **Renew** next to the expired certificate.
3. Upload your CSR.
4. Download the new APNs certificate.
### Step 3: configure Fleet with the generated files
Restart the Fleet server with the contents of the APNs certificate and APNs private key in following environment variables:
* [FLEET_MDM_APPLE_APNS_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-cert-bytes)
* [FLEET_MDM_APPLE_APNS_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-key-bytes)
> You do not need to provide the APNs CSR which was emailed to you.
### Step 4: confirm that Fleet is set up correctly
Use either of the following methods to confirm that Fleet is set up:
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Follow the on-screen instructions in the **Apple Push Certificates Portal** section.
#### Fleetctl CLI:
Run the following command. You should see information about the new APNs certificate such as serial number and renewal date.
```
fleetctl get mdm-apple
```
## Renewing SCEP
The SCEP certificates generated by Fleet and uploaded to the environment variables expire every 10 years. To renew them, regenerate the keys and update the relevant environment variables.
## Apple Business Manager (ABM)
> Available in Fleet Premium
By connecting Fleet to ABM, Macs purchased through Apple or an authorized reseller can automatically enroll to Fleet when they’re first unboxed and set up by your end user.
This section will guide you through how to:
1. Generate certificate and private key for ABM
2. Create a new MDM server record for Fleet in ABM
3. Download the MDM server token from ABM
4. Upload the server token, certificate, and private key to the Fleet server
5. Set the new MDM server as the auto-enrollment server for Macs in ABM
### Step 1: generate the required certificate and private key
User either of the following methods to generate a certificate and private key pair. This pair is how Fleet authenticates itself to ABM:
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Under **Apple Business Manager**, click the "Download" button
#### Fleetctl CLI:
```
fleetctl generate mdm-apple-bm
```
### Step 2: create a new MDM server in ABM
Create an MDM server record in ABM which represents Fleet:
1. Log in to or enroll in [ABM](https://business.apple.com)
2. Click your name at the bottom left of the screen
3. Click **Preferences**
4. Click **MDM Server Assignment**
5. Click the **Add** button at the top
6. Enter a name for the server such as "Fleet"
7. Upload the certificate generated in Step 1
### Step 3: download the server token
In the details page of the newly created server, click **Download Token** at the top. You should receive a `.p7m` file.
### Step 4: upload server token, certificate, and private key to Fleet
With the three generated files, we now give them to the Fleet server so that it can authenticate itself to ABM.
Restart the Fleet server with the contents of the server token, certificate, and private key in following environment variables:
* [FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-server-token-bytes)
* [FLEET_MDM_APPLE_BM_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-cert-bytes)
* [FLEET_MDM_APPLE_BM_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-key-bytes)
### Step 3: confirm that Fleet is set up correctly
Use either of the following methods to confirm that Fleet is set up correctly. You should see information about the ABM server token such as organization name and renewal date.
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Navigate to the **Apple Business Manager** section.
#### Fleetctl CLI:
```
fleetctl get mdm-apple
```
### Step 5: set Fleet to be the MDM server for Macs in ABM
Set Fleet to be the MDM for all future Macs purchased via Apple or an authorized reseller:
1. Log in to [Apple Business Manager](https://business.apple.com)
2. Click your profile icon in the bottom left
3. Click **Preferences**
4. Click **MDM Server Assignment**
5. Switch Macs to the new Fleet instance.
### Step 6 (optional): set the default team for hosts enrolled via ABM
All automatically-enrolled hosts will be assigned to a default team of your choosing after they are unboxed and set up. The host will receive the configurations and behaviors set for that team. If no default team is set, then the host will be placed in "No Teams".
> A host can be transferred to a new (not default) team before it enrolls. Learn how [here](./Teams.md#transfer-hosts-to-a-team). Transferring a host will automatically enforce the new team's settings when it enrolls.
Use either of the following methods to change the default team:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. In the Apple Business Manager section, select the **Edit team** button next to **Default team**.
3. Choose a team and select **Save**.
#### Fleetctl CLI
1. Create a `config` YAML document if you don't have one already. Learn how [here](./configuration-files/README.md#organization-settings). This document is used to change settings in Fleet.
2. Set the `mdm.apple_bm_default_team` configuration option to the desired team's name.
3. Run the `fleetctl apply -f <your-YAML-file-here>` command.
### Pending hosts
Some time after you purchase a Mac through Apple or an authorized reseller, but before it has been set up, the Mac will appear in ABM as in transit. When the Mac appears in ABM, it will also appear in Fleet with **MDM status** set to "Pending." After the new host is set up, the **MDM Status** will change to "On" and the host will be assigned to the default team.
## Renewing ABM
> Apple expires ABM server tokens certificates once every year or whenever the account that downloaded the token has their password changed.
Use either of the following methods to see your ABM renewal date and other important information:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Look at the **Apple Business Manager** section.
#### Fleetctl CLI
```
fleetctl get mdm-apple
```
If you have configured Fleet with an Apple Business Manager server token for mobile device management (a Fleet Premium feature), you will eventually need to renew that token. [As documented in the Apple Business Manager User Guide](https://support.apple.com/en-ca/guide/apple-business-manager/axme0f8659ec/web), the token expires after a year or whenever the account that downloaded the token has their password changed.
To renew the token:
1. Log in to [business.apple.com](https://business.apple.com)
2. Select Fleet's MDM server record
3. Download a new token for that server record
4. In your Fleet server, update the environment variable [FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-server-token-bytes)
5. Restart the Fleet server
<meta name="pageOrderInSection" value="1500">
<meta name="title" value="MDM setup">
<meta name="description" value="Learn how to configure Fleet to use Apple's Push Notification service and connect to Apple Business Manager.">
<meta name="navSection" value="Device management">
docs/Using Fleet/Osquery-process.md
+30
View File
@@ -0,0 +1,30 @@
# Osquery children processes
Osquery will run a watcher process to keep track of any child process and any managed extensions. What follows is a description of what happens during the watcher REPL and under what circumstances the child process and/or managed extensions are terminated.
As a first step, the watcher checks the state of the child worker process, which could be either `Alive` or `Non-existent`. If the process is `Alive`, we make sure the process is within its assigned resource quota, by checking:
1. That the maximum CPU utilization limit is not exceeded (which is controlled by osquery's `--watchdog_latency_limit` flag).
2. The maximum memory limit is not exceeded (which is controlled by osquery's `--watchdog_memory_limit` flag).
If the child process is within the resource limits, then it is deemed alive and well. Otherwise, we terminate the process by following these steps:
1. We send a `SIGUSR1` to the child process.
2. We send a `SIGTERM` to the child process.
3. After a delay (configured by osquery's `--watchdog_forced_shutdown_delay` flag) we send a `SIGKILL` to the child process.
If the child process is `Non-existent`, either because it didn't exist in the first place or because it was terminated, the watcher will try to spawn a new child process. But first, it will check whether the maximum number of allowed process re-spawns was reached. If it was, then the osquery process shutdowns.
After checking the state of the child worker, we check the state of every managed extension, which could be `Alive` or `Non-existent`.
If the managed extension is `Alive`, the watcher will check both the CPU utilization and memory consumption (the same checks we perform for the child process). If the managed extension is deemed unstable, we terminate the extension by following these steps:
1. We send a `SIGTERM` to the managed extension.
2. After a delay (configured by osquery's `--watchdog_forced_shutdown_delay` flag), we send a `SIGKILL` to the managed extension.
If the managed extension is `Non-existent` (either because it was `Non-existent` in the first place or because it was terminated due to resource contention), the watcher will try to 'launch' the managed extension. But first, it will check the respawn limit. If the respawn limit was reached or if for some reason the extension could be spawned, then the osquery process is shut down.
Lastly, we check the state of the watcher process itself. If it is deemed unhealthy because of resource contention, then the osquery process is shut down.
<meta name="pageOrderInSection" value="700">
<meta name="description" value="Learn about how osquery process manages child processes and managed extensions in Fleet.">
<meta name="navSection" value="Osquery management">
docs/Using Fleet/README.md
+16
View File
@@ -0,0 +1,16 @@
# Using Fleet
### [Fleet UI](./Fleet-UI.md)
Provides documentation about running and scheduling queries from within the Fleet UI
### [fleetctl CLI](./fleetctl-CLI.md)
Includes resources for setting up and configuring Fleet via the fleetctl CLI
### [Enroll hosts](./enroll-hosts.md)
Provides resources for enrolling your hosts to Fleet
### [Log destinations](./Log-destinations.md)
Includes documentation on the log destinations for sending with osquery logs
### [Osquery processes](./Osquery-process.md)
Includes documentation about osquery children processes and under which conditions they are terminated
docs/Using Fleet/Supported-browsers.md
+28
View File
@@ -0,0 +1,28 @@
# Supported browsers
Fleet supports the latest, stable releases of all major browsers and platforms. Specific minimum supported browser information is provided below.
We test each browser on Windows whenever possible, because our engineering team primarily uses macOS.
**Note:** This information also applies to [fleetdm.com](https://www.fleetdm.com).
### Desktop
- Chrome 29
- Firefox 52
- Edge 16
- Safari 13.x (macOS only)
### Mobile
- Mobile Safari on iOS 10
- Mobile Chrome on Android 6
### Note
> - Mobile web is not yet supported in the Fleet product.
> - The Fleet user interface [may not be fully supported](https://github.com/fleetdm/fleet/issues/969) in Google Chrome when the browser is running on ChromeOS
<meta name="pageOrderInSection" value="1200">
<meta name="description" value="Learn what browser versions are compatible with Fleet.">
<meta name="navSection" value="The basics">
docs/Using Fleet/Supported-host-operating-systems.md
+31
View File
@@ -0,0 +1,31 @@
# Supported host operating systems
The following operating system versions are supported by the osquery agent.
| OS | Supported version(s) |
| :------ | :------------------------------------- |
| MacOS | 10.12+ |
| Windows | 10+ |
| Linux | CentOS 7.1+, Ubuntu 16.04+ |
## Some notes on compatibility
### Tables
Not all osquery tables are available for every OS. Please check out the [osquery schema](https://fleetdm.com/tables) for detailed information.
If a table is not available for your host, Fleet will generally handle things behind the scenes for you.
### M1 Macs
The osquery installer generated for MacOS by `fleetctl package` does not include native support for M1 Macs. Some values returned may reflect the information returned by Rosetta rather than the system. For example, a CPU will show up as `i486`.
### Linux
The osquery installer will run on Linux distributions where `glibc` is >= 2.2 (there is ongoing work to make osquery work with `glibc` 2.12+).
If you aren't sure what version of `glibc` your distribution is using, [DistroWatch](https://distrowatch.com/) is a great resource.
<meta name="pageOrderInSection" value="1200">
<meta name="description" value="This page contains information about operating systems that are compatible with the osquery agent.">
<meta name="navSection" value="The basics">
docs/Using Fleet/Troubleshooting-live-queries.md
+142
View File
@@ -0,0 +1,142 @@
# Troubleshooting live queries
## How do live queries work?
Following is the lifecycle of a live query in Fleet. (For simplicity we'll assume two Fleet instances (0 and 1) and two devices (0 and 1).
```mermaid
sequenceDiagram
participant browser as Browser/fleetctl;
participant fleet as Fleet 0;
participant fleet2 as Fleet 1;
participant mysql as MySQL;
participant redis as Redis;
participant device0 as Device 0;
participant device1 as Device 1;
# Start live query campaign (stage 1)
browser-->>fleet: POST /api/latest/fleet/queries/run<br>query: "SELECT version from osquery_info#59;"<br>targets: Device A, Device B;
fleet-->>mysql: Create live query campaign;
mysql-->>fleet: Created campaign with ID 42;
fleet-->>redis: Store query: "SELECT version from osquery_info#59;"<br>targets: Device A, Device B;
fleet-->>browser: Campaign created with ID 42;
# Subscribe for live query campaign (stage 2)
browser-->>fleet: GET /api/latest/fleet/results<br>campaign with ID 42 (Upgrade websocket);
fleet-->>browser: Upgraded: websocket;
fleet-->>redis: Subscribe to live query campaign 42;
# Device0 checks in, run query and send results back (stage 3)
device0-->>fleet: distributed/read (check in);
fleet-->>redis: Get live queries for device 0;
redis-->>fleet: Return "SELECT version from osquery_info#59;";
fleet-->>device0: "SELECT version from osquery_info#59;";
note right of device0: Execute<br>"SELECT version from osquery_info#59;";
device0-->>fleet: distributed/write results=[{"version": "5.8.2"}];
fleet-->>redis: Store results<br>[{"version": "5.8.2"}] for device 0, campaign 42;
redis-->>fleet: Receive results<br>[{"version": "5.8.2"}] of device 0 from subscription, campaign 42;
fleet-->browser: Stream websocket message with results<br>[{"version": "5.8.2"}] for device 0;
note left of browser: Render results<br>[{"version": "5.8.2"}] for device 0;
# Device1 checks in, run query and send results back (stage 3)
device1-->>fleet2: distributed/read (check in);
fleet2-->>redis: Get live queries for device 1;
redis-->>fleet2: Return "SELECT version from osquery_info#59;";
fleet2-->>device1: "SELECT version from osquery_info#59;";
note right of device1: Execute<br>"SELECT version from osquery_info#59;";
device1-->>fleet2: distributed/write results=[{"version": "5.7.0"}];
fleet2-->>redis: Store results<br>[{"version": "5.7.0"}] for device 1, campaign 42;
redis-->>fleet: Receive results<br>[{"version": "5.7.0"}] of device 1 from subscription, campaign 42;
fleet-->browser: Stream websocket message with results<br>[{"version": "5.7.0"}] for device 1;
note left of browser: Render results<br>[{"version": "5.7.0"}] for device 1;
```
Notes:
- Multiple fleet instances collect results from devices and store them in Redis, but when retrieving results via websockets, the browser or fleetctl is connected to one Fleet instance.
## Troubleshooting
From diagram above we can see that live queries have a lot of moving parts.
Below we'll look at things that can fail when attempting to run live queries on thousands of devices.
## 1. Redis
Redis is used to store the results of live queries, thus if live queries are not working as expected, the first thing to check is Redis.
1. Check CPU and memory of the Redis instances during a live query campaign.
2. Fleet connects to Redis as a pubsub client to retrieve query results. The results are buffered in Redis up to a limit, default value for such limit is `client-output-buffer-limit pubsub 32mb 8mb 60`.
Change that setting in Redis to `client-output-buffer-limit pubsub 0 0 0` to remove the limits (see https://redis.io/docs/management/config-file/).
PD: AWS Elasticache Redis has a different name for these settings: `client-output-buffer-limit-pubsub-hard-limit`, `client-output-buffer-limit-pubsub-soft-limit` and `client-output-buffer-limit-pubsub-soft-seconds`.
## 2. Fleet
Check CPU and memory of the Fleet instances during a live query campaign.
You might need to scale Fleet vertically or horizontally if your device count is high.
## 3. Network
When it comes to live queries, there are multiple network connections to check:
- Target devices connecting to Fleet.
- Fleet connection to Redis.
- Fleet connection to MySQL.
- Browser websocket connection to Fleet.
A way to verify all these connections are working as expected, run the following dummy query:
```sql
SELECT 1 WHERE 1 = 0;
```
Such query will return no results but if you see "(100% responded)" then that confirms that all connections seem to be working nominally.
### 3.1 Websockets
Live queries use websockets to stream results back to the browser.
If the dummy query above didn't work, then your infrastructure may not be allowing websocket connections.
A way to rule this out is to use the synchronous live query API.
The synchronous API a simplified implementation of live queries that does not use websockets. (It's not designed to run live queries on thousands of devices.)
```sh
curl \
-X GET \
-H "Authorization: Bearer $API_TOKEN" \
https://fleet.example.com/api/latest/fleet/queries/run \
-d '{"query_ids": [340], "host_ids": [375]}'
```
This API will wait for ~100 seconds by default and collect results for the hosts that checked in and successfully ran the query.
## 4. Problematic query
If the infrastructure is working correctly but the query is hanging or crashing osquery in devices, then results may never reach Fleet.
To rule this out, you should also try out the dummy query `SELECT 1 WHERE 1 = 0;`.
If you see "(100% responded)" with the dummy query but not with your query, then this might be an issue with:
- the query crashing osquery on some devices (watchdog killing the osquery process).
- the query hanging or taking too long to run on some devices.
- the query returning too many results (that may reach network limits). Try reducing the number of results by using `LIMIT N;` on the query.
To troubleshoot hangs or crashes you should take a look at the Fleetd/osquery logs on the devices.
## 5. Settings
An important setting when it comes to live query campaign duration is the `distributed_interval`. This value indicates how often devices check in to Fleet to run queries.
If this value is too high, then your live query might time out before getting all results.
PS: At Fleet we recommend this setting to be between 10 and 30 seconds (It's a sweet spot to allow for quick live query responses and not overload the infrastructure.)
## 6. Try fleetctl or another browser
Try running the same live query with fleetctl (from the same device):
```sh
fleetctl query \
--query "SELECT version from osquery_info;" \
--hosts "device0,device1" \
--exit
```
If this works and the browser is not working then it might be a rendering issue on the browser.
You should also try running the live query on different browsers.
<meta name="pageOrderInSection" value="1800">
<meta name="description" value="An overview of live queries in Fleet and steps for troubleshooting.">
<meta name="navSection" value="The basics">
docs/Using Fleet/Understanding-host-vitals.md
+790
View File
@@ -0,0 +1,790 @@
<!-- DO NOT EDIT. This document is automatically generated. -->
# Understanding host vitals
Following is a summary of the detail queries hardcoded in Fleet used to populate the device details:
## battery
- Platforms: darwin
- Query:
```sql
SELECT serial_number, cycle_count, health FROM battery;
```
## chromeos_profile_user_info
- Platforms: chrome
- Query:
```sql
SELECT email FROM users
```
## disk_encryption_darwin
- Platforms: darwin
- Query:
```sql
SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT "" AND filevault_status = 'on' LIMIT 1
```
## disk_encryption_linux
- Platforms: linux, ubuntu, debian, rhel, centos, sles, kali, gentoo, amzn, pop, arch, linuxmint, void, nixos, endeavouros, manjaro, opensuse-leap, opensuse-tumbleweed
- Query:
```sql
SELECT de.encrypted, m.path FROM disk_encryption de JOIN mounts m ON m.device_alias = de.name;
```
## disk_encryption_windows
- Platforms: windows
- Query:
```sql
SELECT 1 FROM bitlocker_info WHERE drive_letter = 'C:' AND protection_status = 1;
```
## disk_space_unix
- Platforms: linux, ubuntu, debian, rhel, centos, sles, kali, gentoo, amzn, pop, arch, linuxmint, void, nixos, endeavouros, manjaro, opensuse-leap, opensuse-tumbleweed, darwin
- Query:
```sql
SELECT (blocks_available * 100 / blocks) AS percent_disk_space_available,
round((blocks_available * blocks_size *10e-10),2) AS gigs_disk_space_available
FROM mounts WHERE path = '/' LIMIT 1;
```
## disk_space_windows
- Platforms: windows
- Query:
```sql
SELECT ROUND((sum(free_space) * 100 * 10e-10) / (sum(size) * 10e-10)) AS percent_disk_space_available,
ROUND(sum(free_space) * 10e-10) AS gigs_disk_space_available
FROM logical_drives WHERE file_system = 'NTFS' LIMIT 1;
```
## google_chrome_profiles
- Platforms: all
- Discovery query:
```sql
SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'google_chrome_profiles';
```
- Query:
```sql
SELECT email FROM google_chrome_profiles WHERE NOT ephemeral AND email <> ''
```
## kubequery_info
- Platforms: all
- Discovery query:
```sql
SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'kubernetes_info';
```
- Query:
```sql
SELECT * from kubernetes_info
```
## mdm
- Platforms: darwin
- Discovery query:
```sql
SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'mdm';
```
- Query:
```sql
select enrolled, server_url, installed_from_dep, payload_identifier from mdm;
```
## mdm_config_profiles_darwin
- Platforms: darwin
- Discovery query:
```sql
SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'macos_profiles';
```
- Query:
```sql
SELECT display_name, identifier, install_date FROM macos_profiles where type = "Configuration";
```
## mdm_disk_encryption_key_file_darwin
- Platforms: darwin
- Discovery query:
```sql
SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'filevault_prk';
```
- Query:
```sql
WITH
de AS (SELECT IFNULL((SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT "" AND filevault_status = 'on' LIMIT 1), 0) as encrypted),
fv AS (SELECT base64_encrypted as filevault_key FROM filevault_prk)
SELECT encrypted, filevault_key FROM de LEFT JOIN fv;
```
## mdm_disk_encryption_key_file_lines_darwin
- Platforms: darwin
- Discovery query:
```sql
SELECT 1 WHERE EXISTS (SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'file_lines') AND NOT EXISTS (SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'filevault_prk');
```
- Query:
```sql
WITH
de AS (SELECT IFNULL((SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT "" AND filevault_status = 'on' LIMIT 1), 0) as encrypted),
fl AS (SELECT line FROM file_lines WHERE path = '/var/db/FileVaultPRK.dat')
SELECT encrypted, hex(line) as hex_line FROM de LEFT JOIN fl;
```
## mdm_windows
- Platforms: windows
- Query:
```sql
SELECT * FROM (
SELECT "provider_id" AS "key", data as "value" FROM registry
WHERE path LIKE 'HKEY_LOCAL_MACHINE\Software\Microsoft\Enrollments\%\ProviderID'
LIMIT 1
)
UNION ALL
SELECT * FROM (
SELECT "discovery_service_url" AS "key", data as "value" FROM registry
WHERE path LIKE 'HKEY_LOCAL_MACHINE\Software\Microsoft\Enrollments\%\DiscoveryServiceFullURL'
LIMIT 1
)
UNION ALL
SELECT * FROM (
SELECT "is_federated" AS "key", data as "value" FROM registry
WHERE path LIKE 'HKEY_LOCAL_MACHINE\Software\Microsoft\Enrollments\%\IsFederated'
LIMIT 1
)
UNION ALL
SELECT * FROM (
SELECT "installation_type" AS "key", data as "value" FROM registry
WHERE path = 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\InstallationType'
LIMIT 1
)
;
```
## munki_info
- Platforms: darwin
- Discovery query:
```sql
SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'munki_info';
```
- Query:
```sql
select version, errors, warnings from munki_info;
```
## network_interface_chrome
- Platforms: chrome
- Query:
```sql
SELECT ipv4 AS address, mac FROM network_interfaces LIMIT 1
```
## network_interface_unix
- Platforms: linux, ubuntu, debian, rhel, centos, sles, kali, gentoo, amzn, pop, arch, linuxmint, void, nixos, endeavouros, manjaro, opensuse-leap, opensuse-tumbleweed, darwin
- Query:
```sql
SELECT
ia.address,
id.mac
FROM
interface_addresses ia
JOIN interface_details id ON id.interface = ia.interface
-- On Unix ia.interface is the name of the interface,
-- whereas on Windows ia.interface is the IP of the interface.
JOIN routes r ON r.interface = ia.interface
WHERE
-- Destination 0.0.0.0/0 is the default route on route tables.
r.destination = '0.0.0.0' AND r.netmask = 0
-- Type of route is "gateway" for Unix, "remote" for Windows.
AND r.type = 'gateway'
-- We are only interested on private IPs (some devices have their Public IP as Primary IP too).
AND (
-- Private IPv4 addresses.
inet_aton(ia.address) IS NOT NULL AND (
split(ia.address, '.', 0) = '10'
OR (split(ia.address, '.', 0) = '172' AND (CAST(split(ia.address, '.', 1) AS INTEGER) & 0xf0) = 16)
OR (split(ia.address, '.', 0) = '192' AND split(ia.address, '.', 1) = '168')
)
-- Private IPv6 addresses start with 'fc' or 'fd'.
OR (inet_aton(ia.address) IS NULL AND regex_match(lower(ia.address), '^f[cd][0-9a-f][0-9a-f]:[0-9a-f:]+', 0) IS NOT NULL)
)
ORDER BY
r.metric ASC,
-- Prefer IPv4 addresses over IPv6 addresses if their route have the same metric.
inet_aton(ia.address) IS NOT NULL DESC
LIMIT 1;
```
## network_interface_windows
- Platforms: windows
- Query:
```sql
SELECT
ia.address,
id.mac
FROM
interface_addresses ia
JOIN interface_details id ON id.interface = ia.interface
-- On Unix ia.interface is the name of the interface,
-- whereas on Windows ia.interface is the IP of the interface.
JOIN routes r ON r.interface = ia.address
WHERE
-- Destination 0.0.0.0/0 is the default route on route tables.
r.destination = '0.0.0.0' AND r.netmask = 0
-- Type of route is "gateway" for Unix, "remote" for Windows.
AND r.type = 'remote'
-- We are only interested on private IPs (some devices have their Public IP as Primary IP too).
AND (
-- Private IPv4 addresses.
inet_aton(ia.address) IS NOT NULL AND (
split(ia.address, '.', 0) = '10'
OR (split(ia.address, '.', 0) = '172' AND (CAST(split(ia.address, '.', 1) AS INTEGER) & 0xf0) = 16)
OR (split(ia.address, '.', 0) = '192' AND split(ia.address, '.', 1) = '168')
)
-- Private IPv6 addresses start with 'fc' or 'fd'.
OR (inet_aton(ia.address) IS NULL AND regex_match(lower(ia.address), '^f[cd][0-9a-f][0-9a-f]:[0-9a-f:]+', 0) IS NOT NULL)
)
ORDER BY
r.metric ASC,
-- Prefer IPv4 addresses over IPv6 addresses if their route have the same metric.
inet_aton(ia.address) IS NOT NULL DESC
LIMIT 1;
```
## orbit_info
- Platforms: all
- Discovery query:
```sql
SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'orbit_info';
```
- Query:
```sql
SELECT version FROM orbit_info
```
## os_chrome
- Platforms: chrome
- Query:
```sql
SELECT
os.name,
os.major,
os.minor,
os.patch,
os.build,
os.arch,
os.platform,
os.version AS version,
os.version AS kernel_version
FROM
os_version os
```
## os_unix_like
- Platforms: linux, ubuntu, debian, rhel, centos, sles, kali, gentoo, amzn, pop, arch, linuxmint, void, nixos, endeavouros, manjaro, opensuse-leap, opensuse-tumbleweed, darwin
- Query:
```sql
SELECT
os.name,
os.major,
os.minor,
os.patch,
os.build,
os.arch,
os.platform,
os.version AS version,
k.version AS kernel_version
FROM
os_version os,
kernel_info k
```
## os_version
- Platforms: all
- Query:
```sql
SELECT * FROM os_version LIMIT 1
```
## os_version_windows
- Platforms: windows
- Query:
```sql
SELECT
os.name,
os.version
FROM
os_version os
```
## os_windows
- Platforms: windows
- Query:
```sql
SELECT
os.name,
os.platform,
os.arch,
k.version as kernel_version,
os.version
FROM
os_version os,
kernel_info k
```
## osquery_flags
- Platforms: all
- Query:
```sql
select name, value from osquery_flags where name in ("distributed_interval", "config_tls_refresh", "config_refresh", "logger_tls_period")
```
## osquery_info
- Platforms: all
- Query:
```sql
select * from osquery_info limit 1
```
## scheduled_query_stats
- Platforms: all
- Query:
```sql
SELECT *,
(SELECT value from osquery_flags where name = 'pack_delimiter') AS delimiter
FROM osquery_schedule
```
## software_chrome
- Platforms: chrome
- Query:
```sql
SELECT
name AS name,
version AS version,
'Browser plugin (Chrome)' AS type,
'chrome_extensions' AS source,
'' AS vendor,
path AS installed_path
FROM chrome_extensions
```
## software_linux
- Platforms: linux, ubuntu, debian, rhel, centos, sles, kali, gentoo, amzn, pop, arch, linuxmint, void, nixos, endeavouros, manjaro, opensuse-leap, opensuse-tumbleweed
- Query:
```sql
WITH cached_users AS (WITH cached_groups AS (select * from groups)
SELECT uid, username, type, groupname, shell
FROM users LEFT JOIN cached_groups USING (gid)
WHERE type <> 'special' AND shell NOT LIKE '%/false' AND shell NOT LIKE '%/nologin' AND shell NOT LIKE '%/shutdown' AND shell NOT LIKE '%/halt' AND username NOT LIKE '%$' AND username NOT LIKE '\_%' ESCAPE '\' AND NOT (username = 'sync' AND shell ='/bin/sync' AND directory <> ''))
SELECT
name AS name,
version AS version,
'Package (deb)' AS type,
'deb_packages' AS source,
'' AS release,
'' AS vendor,
'' AS arch,
'' AS installed_path
FROM deb_packages
WHERE status = 'install ok installed'
UNION
SELECT
package AS name,
version AS version,
'Package (Portage)' AS type,
'portage_packages' AS source,
'' AS release,
'' AS vendor,
'' AS arch,
'' AS installed_path
FROM portage_packages
UNION
SELECT
name AS name,
version AS version,
'Package (RPM)' AS type,
'rpm_packages' AS source,
release AS release,
vendor AS vendor,
arch AS arch,
'' AS installed_path
FROM rpm_packages
UNION
SELECT
name AS name,
version AS version,
'Package (NPM)' AS type,
'npm_packages' AS source,
'' AS release,
'' AS vendor,
'' AS arch,
path AS installed_path
FROM npm_packages
UNION
SELECT
name AS name,
version AS version,
'Browser plugin (Chrome)' AS type,
'chrome_extensions' AS source,
'' AS release,
'' AS vendor,
'' AS arch,
path AS installed_path
FROM cached_users CROSS JOIN chrome_extensions USING (uid)
UNION
SELECT
name AS name,
version AS version,
'Browser plugin (Firefox)' AS type,
'firefox_addons' AS source,
'' AS release,
'' AS vendor,
'' AS arch,
path AS installed_path
FROM cached_users CROSS JOIN firefox_addons USING (uid)
UNION
SELECT
name AS name,
version AS version,
'Package (Atom)' AS type,
'atom_packages' AS source,
'' AS release,
'' AS vendor,
'' AS arch,
path AS installed_path
FROM cached_users CROSS JOIN atom_packages USING (uid)
UNION
SELECT
name AS name,
version AS version,
'Package (Python)' AS type,
'python_packages' AS source,
'' AS release,
'' AS vendor,
'' AS arch,
path AS installed_path
FROM python_packages;
```
## software_macos
- Platforms: darwin
- Query:
```sql
WITH cached_users AS (WITH cached_groups AS (select * from groups)
SELECT uid, username, type, groupname, shell
FROM users LEFT JOIN cached_groups USING (gid)
WHERE type <> 'special' AND shell NOT LIKE '%/false' AND shell NOT LIKE '%/nologin' AND shell NOT LIKE '%/shutdown' AND shell NOT LIKE '%/halt' AND username NOT LIKE '%$' AND username NOT LIKE '\_%' ESCAPE '\' AND NOT (username = 'sync' AND shell ='/bin/sync' AND directory <> ''))
SELECT
name AS name,
COALESCE(NULLIF(bundle_short_version, ''), bundle_version) AS version,
'Application (macOS)' AS type,
bundle_identifier AS bundle_identifier,
'apps' AS source,
last_opened_time AS last_opened_at,
path AS installed_path
FROM apps
UNION
SELECT
name AS name,
version AS version,
'Package (Python)' AS type,
'' AS bundle_identifier,
'python_packages' AS source,
0 AS last_opened_at,
path AS installed_path
FROM python_packages
UNION
SELECT
name AS name,
version AS version,
'Browser plugin (Chrome)' AS type,
'' AS bundle_identifier,
'chrome_extensions' AS source,
0 AS last_opened_at,
path AS installed_path
FROM cached_users CROSS JOIN chrome_extensions USING (uid)
UNION
SELECT
name AS name,
version AS version,
'Browser plugin (Firefox)' AS type,
'' AS bundle_identifier,
'firefox_addons' AS source,
0 AS last_opened_at,
path AS installed_path
FROM cached_users CROSS JOIN firefox_addons USING (uid)
UNION
SELECT
name As name,
version AS version,
'Browser plugin (Safari)' AS type,
'' AS bundle_identifier,
'safari_extensions' AS source,
0 AS last_opened_at,
path AS installed_path
FROM cached_users CROSS JOIN safari_extensions USING (uid)
UNION
SELECT
name AS name,
version AS version,
'Package (Atom)' AS type,
'' AS bundle_identifier,
'atom_packages' AS source,
0 AS last_opened_at,
path AS installed_path
FROM cached_users CROSS JOIN atom_packages USING (uid)
UNION
SELECT
name AS name,
version AS version,
'Package (Homebrew)' AS type,
'' AS bundle_identifier,
'homebrew_packages' AS source,
0 AS last_opened_at,
path AS installed_path
FROM homebrew_packages;
```
## software_windows
- Platforms: windows
- Query:
```sql
WITH cached_users AS (WITH cached_groups AS (select * from groups)
SELECT uid, username, type, groupname, shell
FROM users LEFT JOIN cached_groups USING (gid)
WHERE type <> 'special' AND shell NOT LIKE '%/false' AND shell NOT LIKE '%/nologin' AND shell NOT LIKE '%/shutdown' AND shell NOT LIKE '%/halt' AND username NOT LIKE '%$' AND username NOT LIKE '\_%' ESCAPE '\' AND NOT (username = 'sync' AND shell ='/bin/sync' AND directory <> ''))
SELECT
name AS name,
version AS version,
'Program (Windows)' AS type,
'programs' AS source,
publisher AS vendor,
install_location AS installed_path
FROM programs
UNION
SELECT
name AS name,
version AS version,
'Package (Python)' AS type,
'python_packages' AS source,
'' AS vendor,
path AS installed_path
FROM python_packages
UNION
SELECT
name AS name,
version AS version,
'Browser plugin (IE)' AS type,
'ie_extensions' AS source,
'' AS vendor,
path AS installed_path
FROM ie_extensions
UNION
SELECT
name AS name,
version AS version,
'Browser plugin (Chrome)' AS type,
'chrome_extensions' AS source,
'' AS vendor,
path AS installed_path
FROM cached_users CROSS JOIN chrome_extensions USING (uid)
UNION
SELECT
name AS name,
version AS version,
'Browser plugin (Firefox)' AS type,
'firefox_addons' AS source,
'' AS vendor,
path AS installed_path
FROM cached_users CROSS JOIN firefox_addons USING (uid)
UNION
SELECT
name AS name,
version AS version,
'Package (Chocolatey)' AS type,
'chocolatey_packages' AS source,
'' AS vendor,
path AS installed_path
FROM chocolatey_packages
UNION
SELECT
name AS name,
version AS version,
'Package (Atom)' AS type,
'atom_packages' AS source,
'' AS vendor,
path AS installed_path
FROM cached_users CROSS JOIN atom_packages USING (uid);
```
## system_info
- Platforms: all
- Query:
```sql
select * from system_info limit 1
```
## uptime
- Platforms: all
- Query:
```sql
select * from uptime limit 1
```
## users
- Platforms: linux, darwin, windows
- Query:
```sql
WITH cached_groups AS (select * from groups)
SELECT uid, username, type, groupname, shell
FROM users LEFT JOIN cached_groups USING (gid)
WHERE type <> 'special' AND shell NOT LIKE '%/false' AND shell NOT LIKE '%/nologin' AND shell NOT LIKE '%/shutdown' AND shell NOT LIKE '%/halt' AND username NOT LIKE '%$' AND username NOT LIKE '\_%' ESCAPE '\' AND NOT (username = 'sync' AND shell ='/bin/sync' AND directory <> '')
```
## users_chrome
- Platforms: chrome
- Query:
```sql
SELECT uid, username, email FROM users
```
## windows_update_history
- Platforms: windows
- Discovery query:
```sql
SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'windows_update_history';
```
- Query:
```sql
SELECT date, title FROM windows_update_history WHERE result_code = 'Succeeded'
```
<meta name="title" value="Understanding host vitals">
<meta name="navSection" value="Dig deeper">
<meta name="pageOrderInSection" value="1600">
docs/Using Fleet/Usage-statistics.md
+131
View File
@@ -0,0 +1,131 @@
# Usage statistics
```
ℹ️ In Fleet 4.0, Usage statistics were introduced.
```
Fleet Device Management Inc. periodically collects information about your instance.
## What is included in usage statistics in Fleet?
Below is the JSON payload that is sent to Fleet Device Management Inc:
```json
{
"anonymousIdentifier": "9pnzNmrES3mQG66UQtd29cYTiX2+fZ4CYxDvh495720=",
"fleetVersion": "x.x.x",
"licenseTier": "free",
"organization": "Fleet",
"numHostsEnrolled": 999,
"numUsers": 999,
"numTeams": 999,
"numPolicies": 999,
"numLabels": 999,
"softwareInventoryEnabled": true,
"vulnDetectionEnabled": true,
"systemUsersEnabled": true,
"hostStatusWebhookEnabled": true,
"numWeeklyActiveUsers": 999,
"numWeeklyPolicyViolationDaysActual": 999,
"numWeeklyPolicyViolationDaysPossible": 999,
"hostsEnrolledByOperatingSystem": {
"darwin": [
{
"version": "macOS 12.3.1",
"numEnrolled": 999
},
...
],
"windows": [
{
"version": "Microsoft Windows 10, version 21H2 (W)",
"numEnrolled": 999
},
...
],
"ubuntu": [
{
"version": "Ubuntu 22.04 'Jammy Jellyfish' (LTS)",
"numEnrolled": 999
},
...
],
"rhel": [
{
"version": "Red Hat Enterprise Linux 8.4.0",
"numEnrolled": 999
},
...
],
"debian": [
{
"version": "Debian GNU/Linux 9.0.0",
"numEnrolled": 999
},
...
],
"amzn": [
{
"version": "Amazon Linux 2.0.0",
"numEnrolled": 999
},
...
]
},
"hostsEnrolledByOrbitVersion": [
{
"version": "1.1.0",
"numHosts": 999
},
...
],
"hostsEnrolledByOsqueryVersion": [
{
"version": "4.9.0",
"numHosts": 999
},
...
],
"storedErrors": [
{
"count": 3,
"loc": [
"github.com/fleetdm/fleet/v4/server/example.example:12",
"github.com/fleetdm/fleet/v4/server/example.example:130",
]
},
...
],
"numHostsNotResponding": 9
}
```
Statistics contain no personal information about any particular device or person.
For Fleet Free instances, usage statistics are anonymous. The "organization" property is reported as "unknown."
Sending Usage statistics from your Fleet instance is optional and can be disabled.
## Why should we enable usage statistics?
Help make Fleet better! Fleet has wide adoption, but limited avenues for quantifying this. We need a way of measuring whether the enhancements and new features we ship are actually working.
Every time we ship a Fleet release without usage statistics, it's like launching a shiny, expensive new rocket into space without any way to find out what happens to it. Up until now, we've relied heavily on talking to users and working closely with customers and other community members. That's helped a lot! But it doesn't give us visibility into the problems other users might be having.
Insights about Fleet version adoption helps the team be more efficient when planning upgrade guides, release notes, and future security notices for users running vulnerable software versions.
## Disable usage statistics
Users with the Admin role can disable usage statistics.
To disable usage statistics:
1. In the top navigation, navigate to **Settings > Organization settings**.
2. Scroll to the "Usage statistics" section.
3. Uncheck the "Enable usage statistics" checkbox and then select "Update settings."
<meta name="pageOrderInSection" value="1100">
<meta name="description" value="Learn about Fleet's usage statistics and what information is collected.">
<meta name="navSection" value="Dig deeper">
docs/Using Fleet/Vulnerability-Processing.md
+413
View File
@@ -0,0 +1,413 @@
# Vulnerability processing
- [What to expect](#what-to-expect)
- [Coverage](#coverage)
- [Configuration](#configuration)
- [Performance](#performance)
- [Detection pipeline](#detection-pipeline)
## What to expect
Vulnerability processing in Fleet detects vulnerable software installed on your hosts. To see what software vulnerability processing covers, check out the [Coverage section on the Vulnerability processing doc](#coverage).
<div purpose="embedded-content">
<iframe src="https://www.youtube.com/embed/amJFecMWyvI" allowfullscreen></iframe>
</div>
Vulnerable software can have one or more vulnerabilities (CVEs).
For Fleet Premium users, each CVE includes its CVSS base score (reported by the [National Vulnerability Database](https://nvd.nist.gov/)), probability of exploit (reported by [FIRST](https://www.first.org/epss/)), and whether or not there is a known exploit in the wild (reported by the [Cybersecurity & Infrastructure Security Agency](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)).
Fleet's strategy for detecting vulnerabilities (CVEs) varies according to the host's platform and
the software in question. For macOS and Windows hosts, in general,
CVEs are detected using the National Vulnerability Database (NVD) except for MacOffice applications,
for which we use the release notes published by Microsoft. For Linux hosts,
CVEs are detected using the official OVAL definitions maintained by the different publishers (Canonical, Red Hat etc.).
### Windows/MacOS hosts using the NVD dataset
First, Fleet retrieves the installed software for each host using osquery queries. Then, Fleet
translates each installed software into [Common Platform Enumeration (CPE)](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) names.
Then, using the CPEs, Fleet searches the list of [Common Vulnerabilities and Exposure
(CVE)](https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures) identifiers listed in the NVD
to detect the CVEs that match the defined CPEs.
If matches are found, they are exposed on each host's
**Host details** page and on the **Home** page in the Fleet UI. The CVEs are also exposed in the
`fleetctl get software` command and the `GET api/v1/fleet/hosts/{id}` and `GET
api/v1/fleet/software` API routes.
Vulnerability processing happens on the Fleet instance and not on the host machine. Because of this,
detected vulnerabilities cannot be used in the same way you would use an osquery query (e.g. you wouldn't
be able write a query to retrieve all CVEs).
### MacOffice release notes
We periodically parse the Mac Office release notes posted at
https://learn.microsoft.com/en-us/officeupdates/release-notes-office-for-mac and for each release
note we extract the version
information and what vulnerabilities were patched with the release, we then examine all installed
macOS apps and if an Office app is found we compare its version with the release notes metadata
and report back any vulnerabilities to which the software is susceptible.
### Linux hosts
First, we determine what Linux distributions are part of your fleet (keep in mind that there will
be a small delay between the time a new Linux hosts is added and the time the host is 'detected'). We then
use
that information to determine what OVAL definitions need to be downloaded and parsed - you can find
a list of all the OVAL definitions we use
[here](https://github.com/fleetdm/nvd/blob/master/oval_sources.json). OVAL definitions will be
refreshed on a daily basis.
Finally, we look at the software inventory of each host and execute the assertions contained in the
corresponding OVAL file - any match is reported using the same channels as with Windows/Mac OS vulnerabilities
## Coverage
For Windows/Mac OS Fleet attempts to detect vulnerabilities for installed software that falls into the following categories (types):
### Apps
- macOS
- Windows
### Browser plugins
- macOS, Windows
- Chrome extensions
- Firefox extensions
### Packages
- macOS
- Python
- Packages installed using Homebrew
- Windows
- Python
- Atom
- Packages installed using Chocolatey
For Linux, we adhere to whatever is defined in the OVAL definitions, except for:
- Kernel vulnerabilities.
- Vulnerabilities involving configuration files.
As of right now, the following distributions are supported:
- Ubuntu
- RHEL based distros (Red Hat, CentOS, Fedora, and Amazon Linux)
As of right now, only app names with all ASCII characters are supported. Apps with names featuring non-ASCII characters, such as Cyrillic, will not generate matches.
The ingestion of software varies per platform. For each platform, we run an [osquery query](#ingesting-software-lists-from-hosts) to ingest software.
## Configuration
When upgrading to Fleet 4.7.0 or later, vulnerability processing is automatically enabled if
vulnerability processing and software inventory are not explicitly disabled.
If you explicitly disabled vulnerability processing, and now would like to enable this feature, first enable the software inventory feature by setting the following app config:
```
---
apiVersion: v1
kind: config
spec:
features:
enable_software_inventory: true
```
Then, enable vulnerability processing by specifying a path where Fleet will download the different
data feeds. This can be done by setting the following app config:
```
---
apiVersion: v1
kind: config
spec:
vulnerabilities:
databases_path: /some/path
```
Or through environment variables:
```
FLEET_VULNERABILITIES_DATABASES_PATH=/some/path
```
The path specified needs to exist and Fleet needs to be able to read and write to and from it. This is the only mandatory
configuration needed for vulnerability processing to work. Additional options, like vulnerability check frequency, can be
found in the [configuration documentation](https://fleetdm.com/docs/deploying/configuration#vulnerabilities).
You'll need to restart the Fleet instances after changing these settings.
### Advanced Configuration
Fleet runs vulnerability downloading and processing via internal scheduled cron job. This internal mechanism is very useful
for frictionless deployments and is well suited for most use cases. However, in larger deployments,
where there can be dozens of Fleet server replicas sitting behind a load balancer, it is desirable to manage vulnerability processing externally.
The reasons for this are as follows:
- lower resource requirements across the entire Fleet server deployment (as vulnerability processing requires considerably more resources than just running Fleet server alone)
- more control over scheduling constraints (only process during windows of low utilization, etc.)
It is possible to limit vulnerability processing to a single [dedicated host](https://fleetdm.com/docs/deploying/configuration#current-instance-checks), by setting
`current_instance_checks` to `no` but still run one Fleet server as `yes`, but the drawback here is still having to dedicate resources
for this single host 24/7. The Fleet binary has a command which handles the same vulnerability processing, but will exit (successfully with 0) on completion. Using this sub-command we can delegate vulnerability processing
to external systems such as:
- [ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/scheduling_tasks.html)
- [K8S](https://kubernetes.io/docs/tasks/job/automated-tasks-with-cron-jobs/)
- [GCP](https://cloud.google.com/run/docs/triggering/using-scheduler#create_job)
- [Plain old cron](https://en.wikipedia.org/wiki/Cron)
To opt into this functionality, be sure to configure your Fleet server deployment with
```
FLEET_VULNERABILITIES_DISABLE_SCHEDULE=true
```
which will **disable** the internal scheduling mechanism for vulnerability processing.
And then externally run with the same environment variables/configuration files passed to the server command.
```
fleet vuln_processing
```
## Performance
### Windows/Mac OS
Vulnerability processing is performed in one Fleet instance. If your Fleet deployment uses multiple
instances, only one will be doing the work.
In order to conduct vulnerability processing, Fleet downloads the following files:
1. A preprocessed CPE database generated by FleetDM to speed up the translation process: https://github.com/fleetdm/nvd/releases
2. The historical data for all CVEs and how to match to a CPE: from
https://nvd.nist.gov/vuln/data-feeds
The database generated in step 1 is processed from the original official CPE dictionary
https://nvd.nist.gov/products/cpe. This CPE dictionary is typically updated once a day.
The matching occurs server-side to make the processing as fast as possible, but the whole process is both CPU and memory intensive.
For example, when running a development instance of Fleet on an Apple Macbook Pro with 16 cores, matching 200,000 CPEs against the CVE database will take around 10 seconds and consume about 3GBs of RAM.
The CPU and memory usages are in burst once every hour (or the configured periodicity) on the
instance that does the processing. RAM spikes are expected to not exceed the 2GBs.
### Linux
As with Windows/Mac OS, vulnerability detection for Linux is performed in a single Fleet instance. The
files downloaded will vary depending on what distributions are on your fleet. The list of all the
OVAL files we use can be found [here](https://github.com/fleetdm/nvd/blob/master/oval_sources.json).
When determining what specific file(s) to download we use the reported OS version and map that to an
entry in the `oval_sources.json` dictionary. The mapping rules we use are fairly simple, depending on the
distribution, we either use the major and minor versions and the platform name (for example `Ubuntu
22.4.0` -> `ubuntu_2204`) or just the major version (for example `Red Hat Enterprise Linux
9.0.0` -> `rhel_09`).
To reduce memory footprint during the evaluation phase and because of performance reasons, all downloaded OVAL files are
parsed, and the result is stored in a file following the following naming convention: `fleet_oval_platform_date.json`.
The performance will be a function of three variables:
- The size of the OVAL file
- The amount of hosts to scan
- The amount of installed software
That said, the performance characteristic should be linear (if scanning 200 hosts take
~20 seconds, then scanning 2000 hosts should take ~200 seconds).
## Detection pipeline
There are several steps that go into the vulnerability detection process. In this section we'll dive into what they are and how it works.
The process has different parts that are more error-prone than others. Each OS and each application developer and maintainer can (and do) have their own way of defining each part of their app. Some Linux distributions are very strict, but each distribution handles things differently.
The whole pipeline exists to compensate for these differences, and it can be divided in two sections:
1. Collection:
```mermaid
graph TD;
host1[Host1 send software list]-->normalize[Normalization of names, versions, etc]
host2[Host2 send software list]-->normalize
host3[Host3 send software list]-->normalize
normalize-->store[Storage for later processing]
```
2. Processing
Processing happens in a loop and varies depending on the platform - first Windows/Mac OS hosts
will be processed, then we look at Linux hosts. The default interval is 1hr.
### General process
```mermaid
graph TD;
interval{Once an hour}-->normalize[Normalized software list]
normalize-->process1[Process Windows/Mac OS hosts]
process1-->process2[Process Linux hosts]
process2-->interval
```
### Windows/Mac OS
```mermaid
graph TD;
process[Process Windows/Mac OS hosts] -->downloadCPE(Download CPE database from Fleet)
downloadCPE-->cpeTranslate[CPE translation]
cpeTranslate-->cveDownload(CVE datastreams downloaded)
cveDownload-->cveMap[CVE detection]
```
### Linux
```mermaid
graph TD;
process[Process Linux hosts] --> fresh{OVAL defs older than one day?}
fresh --no--> execute(Analyze hosts using OVAL definitions)
fresh --yes--> remove(Remove old OVAL definitions)
remove --> download(Download new OVAL definitions)
download --> parse(Parse OVAL definitions)
parse --> execute
```
### Ingesting software lists from hosts
The ingestion of software varies per platform. We run a `UNION` of several queries in each:
- [macOS](https://github.com/fleetdm/fleet/blob/main/server/service/osquery_utils/queries.go#L315)
- [Windows](https://github.com/fleetdm/fleet/blob/main/server/service/osquery_utils/queries.go#L478)
- [Linux](https://github.com/fleetdm/fleet/blob/main/server/service/osquery_utils/queries.go#L391)
This is the first step into normalizing data across platforms, as we try to get all the same data for all different types of software we detect vulnerabilities on.
Ingestion can be resource hungry, both on the hosts and the Fleet server. A lot of work has gone into reducing the resources needed, and it's still ongoing.
### Translating to CPE
With a somewhat normalized list of software, in order to search CVEs for it, we need to derive a [CPE](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) from the vendor, name, version, and OS.
As described briefly above, we do this by translating the NVD database of CPEs into a [sqlite database that helps Fleet do the lookup of CPEs very quickly](https://github.com/fleetdm/nvd).
#### How accurate is this translation process?
This is the most error prone part of the process.
The CPE can have some vagueness.
This means that parts of it can be a `*`, which means when you match that CPE to a CVE it can match any of that part of the CPE.
If the CPE is too vague, the extreme case being all parts are `*`, all CVEs will match. You want a very specific CPE, but not too specific that a small error would make it not match a CVE (false negative).
Let's look into some examples of this stage.
##### Example: tmux
tmux is a Unix terminal utility to multiplex ttys. It appears listed like this in macOS:
```
osquery> SELECT * FROM homebrew_packages WHERE name='tmux';
+------+----------------------------+---------+
| name | path | version |
+------+----------------------------+---------+
| tmux | /opt/homebrew/Cellar/tmux/ | 3.2a |
+------+----------------------------+---------+
```
If we look at the [official releases](https://github.com/tmux/tmux/releases/tag/3.2a) the version we get is the same as the one listed. This means that it'll be easy to map it to a CPE that will accurately represent the software.
Now let's look at Chrome on macOS:
```
osquery> select name, bundle_version from apps where name like '%Chrome%';
+-------------------+----------------+
| name | bundle_version |
+-------------------+----------------+
| Google Chrome.app | 4758.102 |
+-------------------+----------------+
```
Now things start to get slightly more tricky. We have to remove the `.app` suffix from the name, then derive the first word as the vendor and the second as the app name. We could use `bundle_name` for the app name, but nothing stops the app developer of adding the vendor to `bundle_name`, so a similar parsing would have to happen.
These are two illustrative examples. The reality is that there is no map or list of all the software available and how it's presented in each platform, so the "software to CPE" translation process is going to be evolving constantly.
#### Improving accuracy
In order to improve the accuracy of matching software to CPEs, CPE translations rules are added for known cases where matching fails.
`server/vulnerabilities/cpe_translations.json` contains these rules and is included in the [NVD release](https://github.com/fleetdm/nvd/releases/latest).
##### Example: `ruby@2.7` installed via `homebrew`
The following CPE translation rule is used to reduce false positives when ruby is installed via homebrew.
This is needed because ruby is commonly included in the title in the CPE database.
This rule matches the software name `ruby` matching a regular expression pattern and installed using `homebrew`.
When searching for CPEs, the specifed `product` and `vendor` will be added to the filter critera.
```
[
{
"software": {
"name": ["/^ruby(@.*)?$/"],
"source": ["homebrew_packages"]
},
"translation": {
"product": ["ruby"],
"vendor": ["ruby-lang"]
}
}
]
```
##### Excluding software
If software is mapped to the wrong CPE and it is known that there are no entries for it in the
NVD dataset, you can specify an exclusion rule by using the `skip` field. If the rule matches, the
software will be excluded from the NVD vulnerability scanning process and, **no NVD vulnerabilities**
will be reported.
```
{
"software": {
"name": ["Docs"],
"source": ["chrome_extensions"]
},
"filter": {
"skip": true
}
}
```
##### CPE Translations (array[CPE Translation Entry])
##### CPE Translation Entry (object)
The CPE translation rule.
| Name | Type | Description |
| --- | --- | --- |
| `software` | array[CPE Translation Software] | The CPE translation software match criteria. |
| `translation` | array[CPE Translation] | The CPE translation. |
##### CPE Translation Software (object)
The CPE translation software match criteria. Used to match software collected from hosts. Fields are are AND'd together. Values inside each field are OR'd together.
| Name | Type | Description |
| --- | --- | --- |
| `name` | array[string] | The software name to match. Enclose within `/` to specify a regular expression pattern. |
| `bundle_identifer` | array[string] | The software bundle identifier (MacOS apps only) to match. Enclose within `/` to specify a regular expression pattern. |
| `source` | array[string] | The software source to match. Enclose within `/` to specify a regular expression pattern. |
##### CPE Translation (object)
The CPE translation. Used to match CPEs in the CPE database. Fields are are AND'd together. Values inside each field are OR'd together.
| Name | Type | Description |
| --- | --- | --- |
| `product` | array[string] | The CPE product. |
| `vendor` | array[string] | The CPE vendor. |
| `target_sw` | array[string] | The CPE target software. |
| `skip` | bool | If true, matched software will be skipped from the NVD vulnerability scanning process |
### Matching a CPE to a CVE
Once we have a good CPE, we can match it against the CVE database. We download the data streams locally and match each CPE to the whole list. The matching is done using the [nvdtools implementation](https://github.com/facebookincubator/nvdtools).
<meta name="pageOrderInSection" value="1300">
<meta name="description" value="Find out how Fleet detects vulnerabilities and what software it covers.">
<meta name="navSection" value="Vuln management">
docs/Using Fleet/enroll-chromebooks.md
+30
View File
@@ -0,0 +1,30 @@
# ChromeOS
For visibility on ChromeOS hosts, Fleet provides the fleetd Chrome extension which provides similar functionality as osquery on other operating systems.
## Adding ChromeOS hosts to Fleet
To learn how to add ChromeOS hosts to Fleet, visit [here](https://fleetdm.com/docs/using-fleet/adding-hosts#add-chromebooks-with-the-fleetd-chrome-extension).
> The fleetd Chrome browser extension is supported on ChromeOS operating systems that are managed using [Google Admin](https://admin.google.com). It is not intended for non-ChromeOS hosts with the Chrome browser installed.
## Available tables
To see the available tables for ChromeOS, visit [here](https://fleetdm.com/tables/chrome_extensions?platformFilter=chrome).
## Setting the hostname
By default, the hostname for a Chromebook host will be blank. The hostname can be customized in Google Admin under Devices > Chrome > Settings > Device > Device Settings > Other Settings > [Device network hostname template](https://support.google.com/chrome/a/answer/1375678#zippy=%2Cdevice-network-hostname-template%2Creport-device-os-information).
## Current Limitations in ChromeOS
- Scheduled queries are currently not available in ChromeOS
- The Fleetd Chrome extension must be force-installed by enterprise policy in order to have full access to the host's data.
- More tables that could be added:
- `disk_events`: https://github.com/fleetdm/fleet/issues/12405
- `client_certificates`: https://github.com/fleetdm/fleet/issues/12465
- `usb_devices`: https://github.com/fleetdm/fleet/issues/12780
## Debugging ChromeOS
To learn how to debug the Fleetd Chrome extension, visit [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#fleetd-chrome-extension).
<meta name="title" value="Enroll Chromebooks">
<meta name="pageOrderInSection" value="2000">
<meta name="navSection" value="Dig deeper">
docs/Using Fleet/enroll-hosts.md
+372
View File
@@ -0,0 +1,372 @@
# Enroll hosts
- [Enroll hosts](#enroll-hosts)
- [Introduction](#introduction)
- [Add hosts with Fleetd](#add-hosts-with-fleetd)
- [Signing installers](#signing-installers)
- [Including Fleet Desktop](#including-fleet-desktop)
- [Enrolling multiple hosts](#adding-multiple-hosts)
- [Automatically adding hosts to a team](#automatically-adding-hosts-to-a-team)
- [Configuration options](#configuration-options)
- [Add hosts with plain osquery](#add-hosts-with-plain-osquery)
- [Set up your Fleet enroll secret](#set-up-your-fleet-enroll-secret)
- [Provide the TLS certificate that osquery will use to communicate with Fleet](#provide-the-tls-certificate-that-osquery-will-use-to-communicate-with-fleet)
- [Configure and launch osquery](#configure-and-launch-osquery)
- [Launching osqueryd using command-line flags](#launching-osqueryd-using-command-line-flags)
- [Launching osqueryd using a flag file](#launching-osqueryd-using-a-flag-file)
- [Migrating from plain osquery to osquery installer](#migrating-from-plain-osquery-to-osquery-installer)
- [Generate installer](#generate-installer)
- [Migrate](#migrate)
- [Add Chromebooks with the fleetd Chrome extension](#add-chromebooks-with-the-fleetd-chrome-extension)
- [Grant full disk access to osquery on macOS](#grant-full-disk-access-to-osquery-on-macos)
- [Creating the configuration profile](#creating-the-configuration-profile)
- [Obtaining identifiers](#obtaining-identifiers)
- [Creating the profile](#creating-the-profile)
- [Test the profile](#test-the-profile)
## Introduction
Fleet gathers information from an [osquery](https://github.com/osquery/osquery) agent installed on each of your hosts. The recommended way to install osquery is using Fleetd, which includes [Orbit](https://fleetdm.com/docs/using-fleet/fleetd), Fleet's lightweight osquery runtime and auto-updater.
You can also install plain osquery on your hosts and connect to Fleet using osquery's `TLS API` plugins.
> For ChromeOS hosts, the [fleetd Chrome extension](#add-chromebooks-with-the-fleetd-chrome-extension) is installed instead of osquery.
## Enroll hosts with Fleetd
To create a Fleet installer, you can use the `fleetctl package` command. To use the `fleetctl package` command, you must first install the `fleetctl` command-line tool. [Learn how to install `fleetctl`](https://fleetdm.com/fleetctl-preview).
The `fleetctl package` can create a Fleetd installer, which adds macOS hosts (**.pkg**), Windows hosts (**.msi**), or Linux hosts (**.deb** or **.rpm**) to Fleet.
The following command creates a Fleetd installer, `.pkg` file, which adds macOS hosts to Fleet. Locate this osquery installer in the folder where the `fleetctl package` command is run.
```sh
fleetctl package --type pkg --fleet-url=[YOUR FLEET URL] --enroll-secret=[YOUR ENROLLMENT SECRET]
```
>**Note:** The only configuration option required to create an installer is `--type`, but to communicate with a Fleet instance, you'll need to specify a `--fleet-url` and `--enroll-secret`
When you install the generated Fleetd installer on a host, this host will automatically enroll in the specified Fleet instance.
### Signing installers
>**Note:** Currently, the `fleetctl package` does not provide support for signing Windows Fleetd installers. Windows installers can be signed after building.
The `fleetctl package` provides support for signing and notarizing macOS osquery installers via the
`--sign-identity` and `--notarize` flags.
Check out the example below:
```sh
AC_USERNAME=appleid@example.com AC_PASSWORD=app-specific-password fleetctl package --type pkg --sign-identity=[PATH TO SIGN IDENTITY] --notarize --fleet-url=[YOUR FLEET URL] --enroll-secret=[YOUR ENROLLMENT SECRET]
```
The above command should be run on a macOS device, as the notarizing and signing of macOS Fleetd installers can only be done on macOS devices.
Also, remember to replace both `AC_USERNAME` and `AC_PASSWORD` environment variables with your Apple ID and a valid [app-specific](https://support.apple.com/en-ca/HT204397) password, respectively. Some organizations (notably those with Apple Enterprise Developer Accounts) may also need to specify `AC_TEAM_ID`. This value can be found on the [Apple Developer "Membership" page](https://developer.apple.com/account/#!/membership) under "Team ID."
### Including Fleet Desktop
> Fleet Desktop requires a Fleet version of 4.12.0 and above. To check your Fleet version, select
> the avatar on the right side of the top bar and select **My account**. Your Fleet version is
> displayed below the **Get API token** button.
Hosts without Fleet Desktop currently installed require a new installer to be generated and run on the target host.
How to generate an installer that includes Fleet Desktop in the Fleet UI:
1. On the top bar in the Fleet UI, select **Hosts > Add hosts**.
2. Select the **Include Fleet Desktop** checkbox.
3. Select the clipboard icon to copy the `fleetctl package` command.
4. In your terminal application, paste and run the copied command.
Alternatively, you can generate an installer that includes Fleet Desktop in `fleetctl package` by appending the `--fleet-desktop` flag.
> Fleet Desktop is supported on macOS, Windows, and Linux. Check out the supported Linux distributions
> and versions [here
> on GitHub](https://github.com/fleetdm/fleet/issues/5684#issuecomment-1123906753).
Once installed on the target host, Fleet Desktop will be managed by Fleetd. To learn more about Fleetd updates, see [here](https://fleetdm.com/docs/deploying/fleetctl-agent-updates).
To prevent this auto-update behavior, you can turn off auto-updates via the `--disable-updates` flag or you can set a specific channel using the `--desktop-channel` flag.
### Adding multiple hosts
If you're managing an enterprise environment with multiple hosts, you likely have an enterprise deployment tool like [Munki](https://www.munki.org/munki/), [Jamf Pro](https://www.jamf.com/products/jamf-pro/), [Chef](https://www.chef.io/), [Ansible](https://www.ansible.com/), or [Puppet](https://puppet.com/) to deliver software to your hosts.
You can distribute your Fleetd installer and add all your hosts to Fleet using your software management tool of choice.
### Automatically adding hosts to a team
`Applies only to Fleet Premium`
```
ℹ️ Fleet 4.0 introduced Teams.
```
The Teams feature in Fleet allows you to place hosts in exclusive groups. With hosts segmented into Teams, you can apply unique queries and give users access to only the hosts in specific Teams.
You can add a host to a team by generating and using a unique osquery installer for a team or by [manually transferring a host to a team in the Fleet UI](https://fleetdm.com/docs/using-fleet/teams#transfer-hosts-to-a-team).
To generate an osquery installer for a team:
1. First, create a team in Fleet by selecting **Create team** in **Settings > Teams**.
2. Then, navigate to **Hosts** and select your team.
3. Next, select **Add hosts** and copy the `fleetctl package` command for the platform (macOS, Windows, Linux) of the hosts you'd like to add to a team in Fleet.
4. Run the copied `fleetctl package` command and [distribute your installer](#adding-multiple-hosts) to add your hosts to a team in Fleet.
### Configuration options
The following command-line flags allow you to configure an osquery installer further to communicate with a specific Fleet instance.
| Flag | Options |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| --type | **Required** - Type of package to build.<br> Options: `pkg`(macOS),`msi`(Windows), `deb`(Debian based Linux), `rpm`(RHEL, CentOS, etc.) |
| --fleet-desktop | Include Fleet Desktop. |
| --enroll-secret | Enroll secret for authenticating to Fleet server |
| --fleet-url | URL (`host:port`) of Fleet server |
| --fleet-certificate | Path to server certificate bundle |
| --identifier | Identifier for package product (default: `com.fleetdm.orbit`) |
| --version | Version for package product (default: `0.0.3`) |
| --insecure | Disable TLS certificate verification (default: `false`) |
| --service | Install osquery with a persistence service (launchd, systemd, etc.) (default: `true`) |
| --sign-identity | Identity to use for macOS codesigning |
| --notarize | Whether to notarize macOS packages (default: `false`) |
| --disable-updates | Disable auto updates on the generated package (default: false) |
| --osqueryd-channel | Update channel of osqueryd to use (default: `stable`) |
| --orbit-channel | Update channel of Orbit to use (default: `stable`) |
| --desktop-channel | Update channel of desktop to use (default: `stable`) |
| --update-url | URL for update server (default: `https://tuf.fleetctl.com`) |
| --update-roots | Root key JSON metadata for update server (from fleetctl updates roots) |
| --use-system-configuration | Try to read --fleet-url and --enroll-secret using configuration in the host (currently only macOS profiles are supported) |
| --debug | Enable debug logging (default: `false`) |
| --verbose | Log detailed information when building the package (default: false) |
| --help, -h | show help (default: `false`) |
Fleet supports other methods for adding your hosts to Fleet, such as the [plain osquery binaries](#add-hosts-with-plain-osquery) or [Kolide Osquery Launcher](https://github.com/kolide/launcher/blob/master/docs/launcher.md#connecting-to-fleet).
## Add hosts with plain osquery
Osquery's [TLS API plugin](http://osquery.readthedocs.io/en/stable/deployment/remote/) lets you use the native osqueryd binaries to connect to Fleet.
You can find various ways to install osquery on your hosts at https://osquery.io/downloads. Once you have installed osquery, you need to do three things on your hosts:
- Set up your Fleet enroll secret.
- Provide the TLS certificate that osquery will use to communicate with Fleet.
- Configure and launch osqueryd.
### Set up your Fleet enroll secret
The enroll secret is a value that osquery provides to authenticate with Fleet. There are a few ways you can set the enroll secret on the hosts which you control. You can either set the value as
- a value of an environment variable (a common name is `OSQUERY_ENROLL_SECRET`)
- the content of a local file (a common path is `/etc/osquery/enroll_secret`)
The value of the environment variable or content of the file should be a secret shared between the osqueryd client and the Fleet server. This is osqueryd's passphrase which it uses to authenticate with Fleet, convincing Fleet that it is actually one of your hosts. The passphrase could be whatever you'd like, but it would be prudent to have the passphrase long, complex, mixed-case, etc. When you launch the Fleet server, you should specify this same value.
If you use an environment variable for this, you can specify it with the `--enroll_secret_env` flag when you launch osqueryd. If you use a local file for this, you can specify its path with the `--enroll_secret_path` flag.
To retrieve the enroll secret, use the "Add New Host" dialog in the Fleet UI or
`fleetctl get enroll_secret`).
If your organization has a robust internal public key infrastructure (PKI) and you already deploy TLS client certificates to each host to uniquely identify them, then osquery supports an advanced authentication mechanism that takes advantage of this. Fleet can be fronted with a proxy that will perform the TLS client authentication.
### Provide the TLS certificate that osquery will use to communicate with Fleet
When Fleet uses a self-signed certificate, osquery agents will need a copy of that certificate in order to authenticate the Fleet server. If clients connect directly to the Fleet server, you can download the certificate through the Fleet UI. From the main dashboard (`/hosts/manage`), click **Add New Host** and **Fetch Certificate**. If Fleet is running behind a load-balancer that terminates TLS, you will have to talk to your system administrator about where to find this certificate.
It is important that the CN of this certificate matches the hostname or IP that osqueryd clients will use to connect.
Specify the path to this certificate with the `--tls_server_certs` flag when you launch osqueryd.
### Configure and launch osquery
In order for osquery to connect to the fleet server, there are some flags that need to be set:
```
--enroll_secret_path=/etc/osquery/enroll_secret
--tls_server_certs=/etc/osquery/fleet.crt
--tls_hostname=fleet.example.com
--host_identifier=uuid
--enroll_tls_endpoint=/api/osquery/enroll
--config_plugin=tls
--config_tls_endpoint=/api/osquery/config
--config_refresh=10
--disable_distributed=false
--distributed_plugin=tls
--distributed_interval=10
--distributed_tls_max_attempts=3
--distributed_tls_read_endpoint=/api/osquery/distributed/read
--distributed_tls_write_endpoint=/api/osquery/distributed/write
--logger_plugin=tls
--logger_tls_endpoint=/api/osquery/log
--logger_tls_period=10
```
These can be specified directly in the command line or saved to a flag file.
#### Launching osqueryd using command-line flags
Assuming that you are deploying your enroll secret in the file `/etc/osquery/enroll_secret` and your osquery server certificate is at `/etc/osquery/fleet.crt`, you could copy and paste the following command with the following flags (be sure to replace `fleet.acme.net` with the hostname or IP of your Fleet installation):
```
sudo osqueryd \
--enroll_secret_path=/etc/osquery/enroll_secret \
--tls_server_certs=/etc/osquery/fleet.crt \
--tls_hostname=fleet.example.com \
--host_identifier=uuid \
--enroll_tls_endpoint=/api/osquery/enroll \
--config_plugin=tls \
--config_tls_endpoint=/api/osquery/config \
--config_refresh=10 \
--disable_distributed=false \
--distributed_plugin=tls \
--distributed_interval=10 \
--distributed_tls_max_attempts=3 \
--distributed_tls_read_endpoint=/api/osquery/distributed/read \
--distributed_tls_write_endpoint=/api/osquery/distributed/write \
--logger_plugin=tls \
--logger_tls_endpoint=/api/osquery/log \
--logger_tls_period=10
```
If your osquery server certificate is deployed to a path that is not `/etc/osquery/fleet.crt`, be sure to update the `--tls_server_certs` flag. Similarly, if your enroll secret is in an environment variable that is not called `OSQUERY_ENROLL_SECRET`. Then, be sure to update the `--enroll_secret_env` environment variable.
If your enroll secret is defined in a local file, specify the file's path with the `--enroll_secret_path` flag instead of using the `--enroll_secret_env` flag.
#### Launching osqueryd using a flag file
For your convenience, osqueryd supports putting all your flags into a single file. We suggest deploying this file to `/etc/osquery/fleet.flags`. If you've deployed the appropriate osquery flags to that path, you could simply launch osquery via:
```
osqueryd --flagfile=/etc/osquery/fleet.flags
```
When using a flag file on Windows, make sure that file paths in the flag file are absolute and not quoted. For example, in `C:\Program Files\osquery\osquery.flags`:
```
--tls_server_certs=C:\Program Files\osquery\fleet.pem
--enroll_secret_path=C:\Program Files\osquery\secret.txt
```
### Migrating from plain osquery to osquery installer
The following is a strategy for migrating a plain osquery deployment. Unlike plain osquery, Fleet's
osquery installer supports the automatic updating of osquery on your hosts so that you don't have to
deploy a new package for every new osquery release.
#### Generate installer
```
fleetctl package --type [pkg|msi|deb|rpm] --fleet-url [fleet-hostname:port] --enroll-secret [secret]
```
If you currently ship a certificate (`fleet.pem`), also include this in the generated package with
`--fleet-certificate [/path/to/fleet.pem]`.
Fleet automatically manages most of the osquery flags to connect to the Fleet server. There's no
need to set any of the flags mentioned above in [Configure and launch osquery](#configure-and-launch-osquery). To
include other osquery flags, provide a flagfile when packaging with `--osquery-flagfile
[/path/to/osquery.flags]`.
Test the installers on each platform before initiating the migration.
#### Migrate
Install the generated package using your standard deployment tooling (Chef, Puppet, etc.). At this
time, [uninstall the existing
osquery](https://blog.fleetdm.com/how-to-uninstall-osquery-f01cc49a37b9).
If the existing enrolled hosts use `--host_identifier=uuid` (or the `uuid` setting for Fleet's
[osquery_host_identifier](https://fleetdm.com/docs/deploying/configuration#osquery-host-identifier)), the new
installation should appear as the same host in the Fleet UI. If other settings are used, duplicate
entries will appear in the Fleet UI. The older entries can be automatically cleaned up with the host
expiration setting. To configure this setting, in the Fleet UI, head to **Settings > Organization settings > Advanced options**.
## Add Chromebooks with the fleetd Chrome extension
> The fleetd Chrome browser extension is supported on ChromeOS operating systems that are managed using [Google Admin](https://admin.google.com). It is not intended for non-ChromeOS hosts with the Chrome browser installed.
Visit the Google Admin console. In the navigation menu, visit Devices > Chrome > Apps & Extensions > Users & browsers.
Select the relevant organizational unit, users, or group where you want the fleetd Chrome extension to be installed.
In the bottom right, click the yellow "+" button and select "Add Chrome app or extension by ID."
Visit your Fleet instance and select Hosts > Add Hosts and select ChromeOS in the popup modal.
Enter the "Extension ID," "Installation URL," and "Policy for extensions" using the data provided in the modal.
Under "Installation Policy", select "Force install". Under "Update URL", select "Installation URL (see above)".
> For the fleetd Chrome extension to have full access to Chrome data, it must be force-installed by enterprise policy as per above
## Grant full disk access to osquery on macOS
macOS does not allow applications to access all system files by default. If you are using MDM, which
is required to deploy these profiles, you
can deploy a "Privacy Preferences Policy Control" policy to grant Fleetd or osquery that level of
access. This is necessary to query for files located in protected paths as well as to use event
tables that require access to the [EndpointSecurity
API](https://developer.apple.com/documentation/endpointsecurity#overview), such as *es_process_events*.
### Creating the configuration profile
#### Obtaining identifiers
If you use plain osquery, instructions are [available here](https://osquery.readthedocs.io/en/stable/deployment/process-auditing/).
On a system with osquery installed via the Fleet osquery installer (Fleetd), obtain the
`CodeRequirement` of Fleetd by running:
```
codesign -dr - /opt/orbit/bin/orbit/macos/stable/orbit
```
The output should be similar or identical to:
```
Executable=/opt/orbit/bin/orbit/macos/edge/orbit
designated => identifier "com.fleetdm.orbit" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "8VBZ3948LU"
```
> **NOTE:** Depending on the version of `fleetctl` used to package and install Orbit, as well as the update channel you've specified, the executable path may differ.
> Fleetctl versions <= 4.13.2 would install Orbit to `/var/lib/orbit` instead of `/opt/orbit`.
Note down the **executable path** and the entire **identifier**.
Osqueryd will inherit the privileges from Orbit and does not need explicit permissions.
#### Creating the profile
Depending on your MDM, this might be possible in the UI or require a custom profile. If your MDM has a feature to configure *Policy Preferences*, follow these steps:
1. Configure the identifier type to “path.”
2. Paste the full path to Orbit as the identifier.
3. Paste the full code signing identifier into the Code requirement field.
4. Allow “Access all files.” Access to Downloads, Documents, etc., is inherited from this.
If your MDM does not have built-in support for privacy preferences profiles, you can use
[PPPC-Utility](https://github.com/jamf/PPPC-Utility) to create a profile with those values, then upload it to
your MDM as a custom profile.
#### Test the profile
Link the profile to a test group that contains at least one Mac.
Once the computer has received the profile, which you can verify by looking at *Profiles* in *System
Preferences*, run this query from Fleet:
```sql
SELECT * FROM file WHERE path LIKE '/Users/%/Downloads/%%';
```
If this query returns files, the profile was applied, as **Downloads** is a
protected location. You can now enjoy the benefits of osquery on all system files and start
using the **es_process_events** table!
If this query does not return data, you can look at operating system logs to confirm whether or not full disk
access has been applied.
See the last hour of logs related to TCC permissions with this command:
`log show --predicate 'subsystem == "com.apple.TCC"' --info --last 1h`
You can then look for `orbit` or `osquery` to narrow down results.
<meta name="pageOrderInSection" value="500">
<meta name="description" value="Learn how to generate installers and enroll hosts in your Fleet instance using fleetd or osquery.">
<meta name="navSection" value="The basics">
docs/Using Fleet/fleetctl-CLI.md
+436
View File
@@ -0,0 +1,436 @@
# fleetctl CLI
Fleetctl (pronounced "Fleet control") is a CLI tool for managing Fleet from the command line. Fleetctl enables a GitOps workflow with Fleet and osquery. With fleetctl, you can manage configurations, queries, generate osquery installers, etc.
Fleetctl also provides a quick way to work with all the data exposed by Fleet without having to use the Fleet UI or work directly with the Fleet API.
## Using fleetctl
To install the latest version of `fleetctl` run `npm install -g fleetctl` or download the binary from [GitHub](https://github.com/fleetdm/fleet/releases).
You can use `fleetctl` to accomplish many tasks you would typically need to do through the Fleet UI. You can even set up or apply configuration files to the Fleet server.
<div purpose="embedded-content">
<iframe src="https://www.youtube.com/embed/ERbknt6w8eg" allowfullscreen></iframe>
</div>
### Available commands
Much of the functionality available in the Fleet UI is also available in `fleetctl`. You can run queries, add and remove users, generate agent (fleetd) installers to add new hosts, get information about existing hosts, and more!
To see the commands you can run with fleetctl, run the `fleetctl --help` command.
### Get more info about a command
Each command available to `fleetctl` has a help menu with additional information. To pull up the help menu, run `fleetctl <command> --help`, replacing `<command>` with the command you're looking up:
```
> fleetctl setup --help
```
You will see more info about the command, including the usage and information about any additional commands and options (or 'flags') that can be passed with it:
```
NAME:
fleetctl setup - Set up a Fleet instance
USAGE:
fleetctl setup [options]
OPTIONS:
--email value Email of the admin user to create (required) [$EMAIL]
--name value Name or nickname of the admin user to create (required) [$NAME]
--password value Password for the admin user (recommended to use interactive entry) [$PASSWORD]
--org-name value Name of the organization (required) [$ORG_NAME]
--config value Path to the fleetctl config file (default: "/Users/ksatter/.fleet/config") [$CONFIG]
--context value Name of fleetctl config context to use (default: "default") [$CONTEXT]
--debug Enable debug http request logging (default: false) [$DEBUG]
--help, -h show help (default: false)
```
## Setting up Fleet
This section walks through setting up and configuring Fleet via the CLI. If you already have a running Fleet instance, skip ahead to [Logging in to an existing Fleet instance](#logging-in-to-an-existing-fleet-instance) to configure the `fleetctl` CLI.
This guide illustrates:
- A minimal CLI workflow for managing an osquery fleet
- The set of API interactions that are required if you want to perform remote, automated management of a Fleet instance
### Running Fleet
For the sake of this tutorial, we will be using the local development Docker Compose infrastructure to run Fleet locally. This is documented in some detail in the [developer documentation](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Building-Fleet.md#development-infrastructure), but the following are the minimal set of commands that you can run from the root of the repository (assuming that you have a working Go/JavaScript toolchain installed along with Docker Compose):
```
docker-compose up -d
make deps
make generate
make
./build/fleet prepare db
./build/fleet serve
```
The `fleet serve` command will be the long running command that runs the Fleet server.
### Fleetctl config
At this point, the MySQL database doesn't have any users in it. Because of this, Fleet is exposing a one-time setup endpoint. Before we can hit that endpoint (by running `fleetctl setup`), we have to first configure the local `fleetctl` context.
Now, since our Fleet instance is local in this tutorial, we didn't get a valid TLS certificate, so we need to run the following to configure our Fleet context:
```
fleetctl config set --address https://localhost:8080 --tls-skip-verify
[+] Set the address config key to "https://localhost:8080" in the "default" context
[+] Set the tls-skip-verify config key to "true" in the "default" context
```
Now, if you were connecting to a Fleet instance for real, you wouldn't want to skip TLS certificate verification, so you might run something like:
```
fleetctl config set --address https://fleet.corp.example.com
[+] Set the address config key to "https://fleet.corp.example.com" in the "default" context
```
### Fleetctl setup
Now that we've configured our local CLI context, lets go ahead and create our admin account:
```
fleetctl setup --email zwass@example.com --name 'Zach' --org-name 'Fleet Test'
Password:
[+] Fleet setup successful and context configured!
```
It's possible to specify the password via the `--password` flag or the `$PASSWORD` environment variable, but be cautious of the security implications of such an action. For local use, the interactive mode above is the most secure.
### Query hosts
To run a simple query against all hosts, you might run something like the following:
```
fleetctl query --query 'SELECT * FROM osquery_info;' --labels='All Hosts' > results.json
⠂ 100% responded (100% online) | 1/1 targeted hosts (1/1 online)
^C
```
When the query is done (or you have enough results), CTRL-C and look at the `results.json` file:
```json
{
"host": "marpaia",
"rows": [
{
"build_distro": "10.13",
"build_platform": "darwin",
"config_hash": "d7cafcd183cc50c686b4c128263bd4eace5d89e1",
"config_valid": "1",
"extensions": "active",
"host_hostname": "marpaia",
"host_display_name": "marpaia",
"instance_id": "37840766-7182-4a68-a204-c7f577bd71e1",
"pid": "22984",
"start_time": "1527031727",
"uuid": "B312055D-9209-5C89-9DDB-987299518FF7",
"version": "3.2.3",
"watcher": "-1"
}
]
}
```
## Logging in to an existing Fleet instance
If you have an existing Fleet instance, run `fleetctl login` (after configuring your local CLI context):
```
fleetctl config set --address https://fleet.corp.example.com
[+] Set the address config key to "https://fleet.corp.example.com" in the "default" context
fleetctl login
Log in using the standard Fleet credentials.
Email: mike@arpaia.co
Password:
[+] Fleet login successful and context configured!
```
Once your local context is configured, you can use the above `fleetctl` normally. See `fleetctl --help` for more information.
### Logging in with SAML (SSO) authentication
Users that authenticate to Fleet via SSO should retrieve their API token from the UI and set it manually in their `fleetctl` configuration (instead of logging in via `fleetctl login`).
1. Go to the "My account" page in Fleet (https://fleet.corp.example.com/profile). Click the "Get API token" button to bring up a modal with the API token.
2. Set the API token in the `~/.fleet/config` file. The file should look like the following:
```
contexts:
default:
address: https://fleet.corp.example.com
email: example@example.com
token: your_token_here
```
Note the token can also be set with `fleetctl config set --token`, but this may leak the token into a user's shell history.
## Using fleetctl to configure Fleet
A Fleet configuration is defined using one or more declarative "messages" in yaml syntax.
Fleet configuration can be retrieved and applied using the `fleetctl` tool.
### Fleetctl get
The `fleetctl get <fleet-entity-here> > <configuration-file-name-here>.yml` command allows you retrieve the current configuration and create a new file for specified Fleet entity (queries, hosts, etc.)
### Fleetctl apply
The `fleetctl apply -f <configuration-file-name-here>.yml` allows you to apply the current configuration in the specified file.
When a new configuration is applied, agent options are validated. If any errors are found, you will receive an error message describing the issue and the new configuration will not be applied. You can also verify that your agent options are valid without applying using the `--dry-run` flag. Validation is based on the latest version of osquery. If you don't use the latest version of osquery, you can override validation using the `--force` flag. This will update agent options even if they are invalid.
Check out the [configuration files](https://fleetdm.com/docs/using-fleet/configuration-files) section of the documentation for example yaml files.
## Using fleetctl with an API-only user
When running automated workflows using the Fleet API, we recommend an API-only user's API key rather than the API key of a regular user. A regular user's API key expires frequently for security purposes, requiring routine updates. Meanwhile, an API-only user's key does not expire.
An API-only user does not have access to the Fleet UI. Instead, it's only purpose is to interact with the API programmatically or from fleetctl.
### Create an API-only user
To create your new API-only user, run `fleetctl user create` and pass values for `--name`, `--email`, and `--password`, and include the `--api-only` flag:
```
fleetctl user create --name "API User" --email api@example.com --password temp!pass --api-only
```
### Creating an API-only user
An API-only user can be given the same permissions as a regular user. The default access level is `Observer`. For more information on permissions, see the [user permissions documentation](https://fleetdm.com/docs/using-fleet/permissions#user-permissions).
If you'd like your API-only user to have a different access level than the default `Observer` role, you can specify what level of access the new user should have using the `--global-role` flag:
```
fleetctl user create --name "API User" --email api@example.com --password temp#pass --api-only --global-role admin
```
On Fleet Premium, use the `--team` flag setting `team_id:role` to create an API-only user on a team:
```
fleetctl user create --name "API Team Maintainer User" --email apimaintainer@example.com --password temp#pass --team 4:maintainer
```
Assigning the [GitOps role](https://fleetdm.com/docs/using-fleet/permissions#gitops) to a user is also completed using this method because GitOps is an API-only role.
### Changing permissions of an API-only user
To change roles of a current user, log into the Fleet UI as an admin and navigate to **Settings > Users**.
> Suggestion: To disable/enable a user's access to the UI (converting a regular user to an API-only user or vice versa), create a new user.
### Use fleetctl as an API-only user
To use fleetctl with an API-only user, you will need to log in with `fleetctl login`. Once done, you'll be able to perform tasks using `fleetctl` as your new API-only user.
> If you are using a version of Fleet older than `4.13.0`, you will need to [reset the API-only user's password](https://github.com/fleetdm/fleet/blob/a1eba3d5b945cb3339004dd1181526c137dc901c/docs/Using-Fleet/fleetctl-CLI.md#reset-the-password) before running queries.
### Get the API token of an API-only user
To get the API key of an API-only user, you need to call the Login API with the credentials supplied during user creation.
For example, say the credentials provided were `api@example.com` for the email and `foobar12345` for the password. You may call the [Log in API](https://fleetdm.com/docs/using-fleet/rest-api#log-in) like so:
```sh
curl --location --request POST 'https://myfleetdomain.com/api/v1/fleet/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "api@example.com",
"password": "foobar12345"
}'
```
The [Log in API](https://fleetdm.com/docs/using-fleet/rest-api#log-in) will return a response similar to the one below with the API token included that will not expire.
```json
{
"user": {
"id": 82,
"name": "API User",
"email": "api@example.com",
"global_role": "observer",
"api_only": true
},
"available_teams": [],
"token": "foo_token"
}
```
### Switching users
To use `fleetctl` with your regular user account but occasionally use your API-only user for specific cases, you can set up your `fleetctl` config with a new `context` to hold the credentials of your API-only user:
```
fleetctl config set --address https://dogfood.fleetdm.com --context api
[+] Context "api" not found, creating it with default values
[+] Set the address config key to "https://dogfood.fleetdm.com" in the "api" context
```
From there on, you can use the `--context api` flag whenever you need to use the API-only user's identity, rather than logging in and out to switch accounts:
```
fleetctl login --context admin
Log in using the admin Fleet credentials.
Email: admin@example.com
Password:
[+] Fleet login successful and context configured!
```
Running a command with no context will use the default profile.
## MDM commands
With fleetctl, you can run MDM commands to take some action on your macOS hosts, like restart the host, remotely. Learn how [here](./MDM-commands.md).
## File carving
Fleet supports osquery's file carving functionality as of Fleet 3.3.0. This allows the Fleet server to request files (and sets of files) from osquery agents, returning the full contents to Fleet.
File carving data can be either stored in Fleet's database or to an external S3 bucket. For information on how to configure the latter, consult the [configuration docs](https://fleetdm.com/docs/deploying/configuration#s-3-file-carving-backend).
### Configuration
Given a working flagfile for connecting osquery agents to Fleet, add the following flags to enable carving:
```
--disable_carver=false
--carver_disable_function=false
--carver_start_endpoint=/api/v1/osquery/carve/begin
--carver_continue_endpoint=/api/v1/osquery/carve/block
--carver_block_size=8000000
```
The default flagfile provided in the "Add New Host" dialog also includes this configuration.
#### Carver block size
The `carver_block_size` flag should be configured in osquery.
For the (default) MySQL Backend, the configured value must be less than the value of
`max_allowed_packet` in the MySQL connection, allowing for some overhead. The default for [MySQL 5.7](https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_max_allowed_packet)
is 4MB and for [MySQL 8](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_allowed_packet) it is 64MB.
For the S3/Minio backend, this value must be set to at least 5MiB (`5242880`) due to the
[constraints of S3's multipart
uploads](https://docs.aws.amazon.com/AmazonS3/latest/dev/qfacts.html).
#### Compression
Compression of the carve contents can be enabled with the `carver_compression` flag in osquery. When used, the carve results will be compressed with [Zstandard](https://facebook.github.io/zstd/) compression.
### Usage
File carves are initiated with osquery queries. Issue a query to the `carves` table, providing `carve = 1` along with the desired path(s) as constraints.
For example, to extract the `/etc/hosts` file on a host with hostname `mac-workstation`:
```
fleetctl query --hosts mac-workstation --query 'SELECT * FROM carves WHERE carve = 1 AND path = "/etc/hosts"'
```
The standard osquery file globbing syntax is also supported to carve entire directories or more:
```
fleetctl query --hosts mac-workstation --query 'SELECT * FROM carves WHERE carve = 1 AND path LIKE "/etc/%%"'
```
#### Retrieving carves
List the non-expired (see below) carves with `fleetctl get carves`. Note that carves will not be available through this command until osquery checks in to the Fleet server with the first of the carve contents. This can take some time from initiation of the carve.
To also retrieve expired carves, use `fleetctl get carves --expired`.
Contents of carves are returned as .tar archives, and compressed if that option is configured.
To download the contents of a carve with ID 3, use
```
fleetctl get carve --outfile carve.tar 3
```
It can also be useful to pipe the results directly into the tar command for unarchiving:
```
fleetctl get carve --stdout 3 | tar -x
```
#### Expiration
Carve contents remain available for 24 hours after the first data is provided from the osquery client. After this time, the carve contents are cleaned from the database and the carve is marked as "expired".
The same is not true if S3 is used as the storage backend. In that scenario, it is suggested to setup a [bucket lifecycle configuration](https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lifecycle-mgmt.html) to avoid retaining data in excess. Fleet, in an "eventual consistent" manner (i.e. by periodically performing comparisons), will keep the metadata relative to the files carves in sync with what it is actually available in the bucket.
### Alternative carving backends
#### Minio
Configure the following:
- `FLEET_S3_ENDPOINT_URL=minio_host:port`
- `FLEET_S3_BUCKET=minio_bucket_name`
- `FLEET_S3_SECRET_ACCESS_KEY=your_secret_access_key`
- `FLEET_S3_ACCESS_KEY_ID=acces_key_id`
- `FLEET_S3_FORCE_S3_PATH_STYLE=true`
- `FLEET_S3_REGION=minio` or any non-empty string otherwise Fleet will attempt to derive the region.
### Troubleshooting
#### Check carve status in osquery
Osquery can report on the status of carves through queries to the `carves` table.
The details provided by
```
fleetctl query --labels 'All Hosts' --query 'SELECT * FROM carves'
```
can be helpful to debug carving problems.
#### Ensure `carver_block_size` is set appropriately
`carver_block_size` is an osquery flag that sets the size of each part of a file carve that osquery
sends to the Fleet server.
When using the MySQL backend (default), this value must be less than the `max_allowed_packet`
setting in MySQL. If it is too large, MySQL will reject the writes.
When using S3, the value must be at least 5MiB (5242880 bytes), as smaller multipart upload
sizes are rejected. Additionally, [S3
limits](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html) the maximum number of
parts to 10,000.
The value must be small enough that HTTP requests do not time out.
Start with a default of 2MiB for MySQL (2097152 bytes), and 5MiB for S3/Minio (5242880 bytes).
## Debugging Fleet
`fleetctl` provides debugging capabilities about the running Fleet server via the `debug` command. To see a complete list of all the options run:
```
fleetctl debug --help
```
To generate a full debugging archive, run:
```
fleetctl debug archive
```
This will generate a `tar.gz` file with:
- `prof` archives that can be inspected via `go tools pprof <archive_name_here>`.
- A file containing a set of all the errors that happened in the server during the interval of time defined by the [logging_error_retention_period](https://fleetdm.com/docs/deploying/configuration#logging-error-retention-period) configuration.
- Files containing database-specific information.
<meta name="pageOrderInSection" value="300">
<meta name="description" value="Read about fleetctl, a CLI tool for managing Fleet and osquery configurations, running queries, generating installers, and more.">
<meta name="navSection" value="The basics">
docs/Using Fleet/fleetd.md
+402
View File
@@ -0,0 +1,402 @@
# Fleetd
- [Fleetd](#fleetd)
- [Overview](#overview)
- [Components](#components)
- [Capabilities](#capabilities)
- [Packaging](#packaging)
- [Dependencies](#dependencies)
- [Packaging support](#packaging-support)
- [Building packages](#building-packages)
- [Configuration options](#configuration-options)
- [Fleet Desktop](#fleet-desktop)
- [Update channels](#update-channels)
- [macOS signing \& notarization](#macos-signing--notarization)
- [Fleetd osquery result and status logs](#fleetd-osquery-result-and-status-logs)
- [Fleetd mTLS support](#fleetd-mtls-support)
- [Debug](#debug)
- [Orbit](#orbit)
- [Usage](#usage)
- [Permissions](#permissions)
- [macOS/Linux](#macoslinux)
- [Windows](#windows)
- [Osquery shell](#osquery-shell)
- [Connect to a Fleet server](#connect-to-a-fleet-server)
- [Osquery flags](#osquery-flags)
- [Osquery extensions](#osquery-extensions)
- [Orbit development](#orbit-development)
- [Run Orbit from source](#run-orbit-from-source)
- [Generate installer packages from Orbit source](#generate-installer-packages-from-orbit-source)
- [Troubleshooting](#troubleshooting)
- [Logs](#logs)
- [Uninstall](#uninstall)
- [Windows](#windows-1)
- [Linux](#linux)
- [macOS](#macos)
- [Bugs](#bugs)
- [Try Fleetd](#try-fleetd)
- [With `fleetctl preview` already running](#with-fleetctl-preview-already-running)
## Overview
Fleetd is the bundle of agents that includes:
- [osquery](https://osquery.io/)
- [Orbit](#orbit)
- [Fleet Desktop](./fleet-desktop.md)
## Components
```mermaid
graph LR;
tuf["<a href=https://theupdateframework.io/>TUF</a> file server<br>(default: <a href=https://tuf.fleetctl.com>tuf.fleetctl.com</a>)"];
fleet_server[Fleet<br>Server];
subgraph Fleetd
orbit[orbit];
desktop[Fleet Desktop<br>Tray App];
osqueryd[osqueryd];
desktop_browser[Fleet Desktop<br> from Browser];
end
orbit -- "Fleet Orbit API (TLS)" --> fleet_server;
desktop -- "Fleet Desktop API (TLS)" --> fleet_server;
osqueryd -- "osquery<br>remote API (TLS)" --> fleet_server;
desktop_browser -- "My Device API (TLS)" --> fleet_server;
orbit -- "Auto Update (TLS)" --> tuf;
```
## Capabilities
| Capability | Status |
| ------------------------------------ | ------ |
| Secure autoupdate for osquery | ✅ |
| Secure autoupdate for Orbit | ✅ |
| Configurable update channels | ✅ |
| Full osquery flag customization | ✅ |
| Package tooling for macOS `.pkg` | ✅ |
| Package tooling for Linux `.deb` | ✅ |
| Package tooling for Linux `.rpm` | ✅ |
| Package tooling for Windows `.msi` | ✅ |
| Manage/update osquery extensions | ✅ |
| Manage cgroups for Linux performance | 🔜 |
## Packaging
Fleetd is typically deployed via OS-specific packages. Tooling is provided with this repository to generate installation packages.
### Dependencies
Fleetd currently supports building packages on macOS and Linux.
Before building packages, clone or download [this repository](https://github.com/fleetdm/fleet/tree/main) and [install Go](https://golang.org/doc/install).
Building Windows packages requires Docker to be installed.
### Packaging support
- **macOS** - `.pkg` package generation with (optional) [notarization](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution) and codesigning - Persistence via `launchd`.
- **Linux** - `.deb` (Debian, Ubuntu, etc.) & `.rpm` (RHEL, CentOS, etc.) package generation - Persistence via `systemd`.
- **Windows** - `.msi` package generation - Persistence via Services.
### Building packages
Use `fleetctl package` to run the packaging tools.
The only required parameter is `--type`, use one of `deb`, `rpm`, `pkg`, or `msi`.
Configure osquery to connect to a Fleet (or other TLS) server with the `--fleet-url` and `--enroll-secret` flags.
A minimal invocation for communicating with Fleet:
```sh
fleetctl package --type deb --fleet-url=fleet.example.com --enroll-secret=notsosecret
```
This will build a `.deb` package configured to communicate with a Fleet server at `fleet.example.com` using the enroll secret `notsosecret`.
When the Fleet server uses a self-signed (or otherwise invalid) TLS certificate, package with the `--insecure` or `--fleet-certificate` options.
#### Configuration options
The following command-line flags allow you to configure an osquery installer further to communicate with a specific Fleet instance.
| Flag | Options |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| --type | **Required** - Type of package to build.<br> Options: `pkg`(macOS),`msi`(Windows), `deb`(Debian based Linux), `rpm`(RHEL, CentOS, etc.) |
| --fleet-desktop | Include Fleet Desktop. |
| --enroll-secret | Enroll secret for authenticating to Fleet server |
| --fleet-url | URL (`host:port`) of Fleet server |
| --fleet-certificate | Path to server certificate bundle |
| --identifier | Identifier for package product (default: `com.fleetdm.orbit`) |
| --version | Version for package product (default: `0.0.3`) |
| --insecure | Disable TLS certificate verification (default: `false`) |
| --service | Install osquery with a persistence service (launchd, systemd, etc.) (default: `true`) |
| --sign-identity | Identity to use for macOS codesigning |
| --notarize | Whether to notarize macOS packages (default: `false`) |
| --disable-updates | Disable auto updates on the generated package (default: false) |
| --osqueryd-channel | Update channel of osqueryd to use (default: `stable`) |
| --orbit-channel | Update channel of Orbit to use (default: `stable`) |
| --desktop-channel | Update channel of desktop to use (default: `stable`) |
| --update-url | URL for update server (default: `https://tuf.fleetctl.com`) |
| --update-roots | Root key JSON metadata for update server (from fleetctl updates roots) |
| --use-system-configuration | Try to read --fleet-url and --enroll-secret using configuration in the host (currently only macOS profiles are supported) |
| --debug | Enable debug logging (default: `false`) |
| --verbose | Log detailed information when building the package (default: false) |
| --help, -h | show help (default: `false`) |
#### Fleet Desktop
[Fleet Desktop](./Fleet-desktop.md) is a menu bar icon available on macOS, Windows, and Linux that gives your end users visibility into the security posture of their machine.
You can include Fleet Desktop in the orbit package by including the `--fleet-desktop`option.
#### Update channels
Fleetd uses the concept of "update channels" to determine the version of Orbit, Fleet Desktop, osquery, and any extensions (extension support coming soon) to run. This concept is modeled from the common versioning convention for Docker containers.
Configure update channels for Fleetd and osqueryd with the `--orbit-channel`, `--desktop-channel` and `--osqueryd-channel` flags when packaging.
| Channel | Versions |
| ------- | -------- |
| `4` | 4.x.x |
| `4.6` | 4.6.x |
| `4.6.0` | 4.6.0 |
Additionally, `stable` and `edge` are special channel names. The `stable` channel will provide the most recent osquery version that Fleet deems to be stable. When a new version of osquery is released, it's added to the `edge` channel for beta testing. Fleet then provides input to the osquery TSC based on testing. After the version is declared stable by the osquery TSC, Fleet will promote the version to `stable` ASAP.
#### macOS signing & notarization
Fleetd's packager can automate the codesigning and notarization steps to allow the resulting package to generate packages that appear "trusted" when installed on macOS hosts. Signing and notarization are supported only on macOS hosts.
For signing, a "Developer ID Installer" certificate must be available on the build machine ([generation instructions](https://help.apple.com/xcode/mac/current/#/dev154b28f09)). Use `security find-identity -v` to verify the existence of this certificate and make note of the identifier provided in the left column.
For notarization, valid App Store Connect credentials must be available on the build machine. Set these in the environment variables `AC_USERNAME` and `AC_PASSWORD`. It's common to configure this via [app-specific passwords](https://support.apple.com/en-ca/HT204397). Some organizations (notably those with Apple Enterprise Developer Accounts) may also need to specify `AC_TEAM_ID`. This value can be found on the [Apple Developer "Membership" page](https://developer.apple.com/account/#!/membership) under "Team ID."
Build a signed and notarized macOS package with an invocation like the following:
```sh
AC_USERNAME=zach@example.com AC_PASSWORD=llpk-sije-kjlz-jdzw fleetctl package --type=pkg --fleet-url=fleet.example.com --enroll-secret=63SBzTT+2UyW --sign-identity 3D7260BF99539C6E80A94835A8921A988F4E6498 --notarize
```
This process may take several minutes, as the notarization process completes on Apple's servers.
After successful notarization, the generated "ticket" is automatically stapled to the package.
#### Fleetd osquery result and status logs
If the `logger_path` configuration is set to `filesystem`, Fleetd will store osquery's "result" and
"status" logs to the following directories:
- Windows: C:\Program Files\Orbit\osquery_log
- macOS: /opt/orbit/osquery_log
- Linux: /opt/orbit/osquery_log
#### Fleetd mTLS support
Fleetd supports using TLS client certificates for authentication to the Fleet server and [TUF](https://theupdateframework.io/) server.
This functionality is licensed under the Fleet EE License. Usage requires a current Fleet EE subscription.
> The mTLS feature requires Orbit to be version v1.10.0 or greater and `fleetctl` v4.31.0 or greater.
When generating the packages, use the following flags:
```sh
fleetctl package \
[...]
--fleet-tls-client-certificate=fleet-client.crt \
--fleet-tls-client-key=fleet-client.key \
--update-tls-client-certificate=update-client.crt \
--update-tls-client-key=update-client.key \
[...]
```
The certificates must be in PEM format.
The client certificates can also be pushed to existing installations by placing them in the following locations:
- For macOS and Linux:
- `/opt/orbit/fleet_client.crt`
- `/opt/orbit/fleet_client.key`
- `/opt/orbit/update_client.crt`
- `/opt/orbit/update_client.key`
- For Windows:
- `C:\Program Files\Orbit\fleet_client.crt`
- `C:\Program Files\Orbit\fleet_client.key`
- `C:\Program Files\Orbit\update_client.crt`
- `C:\Program Files\Orbit\update_client.key`
If using Fleet Desktop, you may need to specify an alternative host for the "My device" URL (in the Fleet tray icon).
Such alternative host should not require client certificates on the TLS connection.
```sh
fleetctl package
[...]
--fleet-desktop \
--fleet-desktop-alternative-browser-host=fleet-desktop.example.com \
[...]
```
If this setting is not used, you will need to configure client TLS certificates on devices' browsers.
#### Debug
You can use the `--debug` option in `fleetctl package` to generate installers in "debug mode." This mode increases the verbosity of logging for orbit and osqueryd (log DEBUG level).
## Orbit
Orbit is an [osquery](https://github.com/osquery/osquery) runtime and autoupdater that is bundled in Fleetd. With Orbit, it's easy to deploy osquery, manage configurations, and stay up to date. Orbit eases the deployment of osquery connected with a [Fleet server](https://github.com/fleetdm/fleet) and is a (near) drop-in replacement for osquery in a variety of deployment scenarios.
Orbit is the recommended agent for Fleet. But Orbit can be used with or without Fleet, and Fleet can be used with or without Orbit.
### Usage
General information and flag documentation can be accessed by running `orbit --help`.
#### Permissions
Orbit generally expects root permissions to be able to create and access its working files.
To get root level permissions:
##### macOS/Linux
Prefix `orbit` commands with `sudo` (`sudo orbit ...`) or run in a root shell.
##### Windows
Run Powershell or cmd.exe with "Run as administrator" and start `orbit` commands from that shell.
#### Osquery shell
Run an `osqueryi` shell with `orbit osqueryi` or `orbit shell`.
#### Connect to a Fleet server
Use the `--fleet-url` and `--enroll-secret` flags to connect to a Fleet server.
For example:
```sh
orbit --fleet-url=https://localhost:8080 --enroll-secret=the_secret_value
```
Use `--fleet_certificate` to provide a path to a certificate bundle when necessary for osquery to verify the authenticity of the Fleet server (typically when using a Windows client or self-signed certificates):
```sh
orbit --fleet-url=https://localhost:8080 --enroll-secret=the_secret_value --fleet-certificate=cert.pem
```
Add the `--insecure` flag for connections using otherwise invalid certificates:
```sh
orbit --fleet-url=https://localhost:8080 --enroll-secret=the_secret_value --insecure
```
#### Osquery flags
Orbit can be used as a near drop-in replacement for `osqueryd`, enhancing standard osquery with autoupdate capabilities. Orbit passes through any options after `--` directly to the `osqueryd` instance.
For example, the following would be a typical drop-in usage of Orbit:
```sh
orbit -- --flagfile=flags.txt
```
#### Osquery extensions
Orbit can be used to remotely deploy and manage osquery extensions. This saves the time and energy required to maintain extensions using a separate tool like Munki or an MDM solution.
[Learn how](https://fleetdm.com/docs/using-fleet/configuration-files#code-extensions-code-option)
#### Orbit development
##### Run Orbit from source
To execute orbit from source directly, run the following command:
```sh
go run github.com/fleetdm/fleet/v4/orbit/cmd/orbit \
--dev-mode \
--disable-updates \
--root-dir /tmp/orbit \
--fleet-url https://localhost:8080 \
--insecure \
--enroll-secret Pz3zC0NMDdZfb3FtqiLgwoexItojrYh/ \
-- --verbose
```
Or, using a `flagfile.txt` for osqueryd:
```sh
go run github.com/fleetdm/fleet/v4/orbit/cmd/orbit \
--dev-mode \
--disable-updates \
--root-dir /tmp/orbit \
-- --flagfile=flagfile.txt --verbose
```
##### Generate installer packages from Orbit source
The `fleetctl package` command generates installers by fetching the targets/executables from a [TUF](https://theupdateframework.io/) repository.
To generate an installer that contains an Orbit built from source, you need to setup a local TUF repository.
The following document explains how you can generate a TUF repository and installers that use it: [tools/tuf/test](https://github.com/fleetdm/fleet/tree/main/tools/tuf/test/README.md).
#### Troubleshooting
##### Logs
Orbit captures and streams osqueryd's stdout/stderr into its own stdout/stderr output.
These are the log destinations for each platform:
- Linux: Orbit and osqueryd stdout/stderr output is sent to syslog (`/var/log/syslog` on Debian systems and `/var/log/messages` on CentOS).
- macOS: `/private/var/log/orbit/orbit.std{out|err}.log`.
- Windows: `C:\Windows\system32\config\systemprofile\AppData\Local\FleetDM\Orbit\Logs\orbit-osquery.log` (the log file is rotated).
Users will need administrative permissions on the host to access these log destinations.
#### Uninstall
##### Windows
Use the "Add or remove programs" dialog to remove Orbit.
##### Linux
Uninstall the package with the corresponding package manager:
- Ubuntu
```sh
sudo apt remove fleet-osquery -y
```
- CentOS
```sh
sudo rpm -e fleet-osquery-X.Y.Z.x86_64
```
##### macOS
Run the [cleanup script](https://github.com/fleetdm/fleet/tree/main/orbit/tools/cleanup/cleanup_macos.sh).
## Bugs
[Create an issue](https://github.com/fleetdm/fleet/issues) to report a bug or request a feature.
## Try Fleetd
### With [`fleetctl preview` already running](https://github.com/fleetdm/fleet#try-fleet):
```bash
# With fleetctl in your $PATH
# Generate a macOS installer pointed at your local Fleet
fleetctl package --type=pkg --fleet-url=localhost:8412 --insecure --enroll-secret=YOUR_FLEET_ENROLL_SECRET_HERE
```
> With fleetctl preview running, you can find your Fleet enroll secret by selecting the "Add hosts" button on the Hosts page in the Fleet UI.
An installer configured to point at your Fleet instance has now been generated.
Now run that installer (double click, on a Mac) to enroll your own computer as a host in Fleet. Refresh after several seconds (≈30s), and you should now see your local computer as a new host in Fleet.
<meta name="pageOrderInSection" value="600">
<meta name="navSection" value="The basics">
docs/Using Fleet/manage-access.md
+159
View File
@@ -0,0 +1,159 @@
# Manage access
Users have different abilities depending on the access level they have.
## Roles
### Admin
Users with the admin role receive all permissions.
### Maintainer
Maintainers can manage most entities in Fleet, like queries, policies, labels and schedules.
Unlike admins, maintainers cannot edit higher level settings like application configuration, teams or users.
### Observer
The Observer role is a read-only role. It can access most entities in Fleet, like queries, policies, labels, schedules, application configuration, teams, etc.
They can also run queries configured with the `observer_can_run` flag set to `true`.
### Observer+
`Applies only to Fleet Premium`
Observer+ is an Observer with the added ability to run *any* query.
### GitOps
`Applies only to Fleet Premium`
GitOps is a modern approach to Continuous Deployment (CD) that uses Git as the single source of truth for declarative infrastructure and application configurations.
GitOps is an API-only and write-only role that can be used on CI/CD pipelines.
## User permissions
| **Action** | Observer | Observer+* | Maintainer | Admin | GitOps* |
| ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ---------- | ---------- | ----- | ------- |
| View all [activity](https://fleetdm.com/docs/using-fleet/rest-api#activities) | ✅ | ✅ | ✅ | ✅ | |
| View all hosts | ✅ | ✅ | ✅ | ✅ | |
| Filter hosts using [labels](https://fleetdm.com/docs/using-fleet/rest-api#labels) | ✅ | ✅ | ✅ | ✅ | |
| Target hosts using labels | ✅ | ✅ | ✅ | ✅ | |
| Add and delete hosts | | | ✅ | ✅ | |
| Transfer hosts between teams\* | | | ✅ | ✅ | ✅ |
| Create, edit, and delete labels | | | ✅ | ✅ | ✅ |
| View all software | ✅ | ✅ | ✅ | ✅ | |
| Filter software by [vulnerabilities](https://fleetdm.com/docs/using-fleet/vulnerability-processing#vulnerability-processing) | ✅ | ✅ | ✅ | ✅ | |
| Filter hosts by software | ✅ | ✅ | ✅ | ✅ | |
| Filter software by team\* | ✅ | ✅ | ✅ | ✅ | |
| Manage [vulnerability automations](https://fleetdm.com/docs/using-fleet/automations#vulnerability-automations) | | | | ✅ | ✅ |
| Run queries designated "**observer can run**" as live queries against all hosts | ✅ | ✅ | ✅ | ✅ | |
| Run any query as [live query](https://fleetdm.com/docs/using-fleet/fleet-ui#run-a-query) against all hosts | | ✅ | ✅ | ✅ | |
| Create, edit, and delete queries | | | ✅ | ✅ | ✅ |
| View all queries\** | ✅ | ✅ | ✅ | ✅ | |
| Add, edit, and remove queries from all schedules | | | ✅ | ✅ | ✅ |
| Create, edit, view, and delete packs | | | ✅ | ✅ | ✅ |
| View all policies | ✅ | ✅ | ✅ | ✅ | |
| Filter hosts using policies | ✅ | ✅ | ✅ | ✅ | |
| Create, edit, and delete policies for all hosts | | | ✅ | ✅ | ✅ |
| Create, edit, and delete policies for all hosts assigned to team\* | | | ✅ | ✅ | ✅ |
| Manage [policy automations](https://fleetdm.com/docs/using-fleet/automations#policy-automations) | | | | ✅ | ✅ |
| Create, edit, view, and delete users | | | | ✅ | |
| Add and remove team members\* | | | | ✅ | ✅ |
| Create, edit, and delete teams\* | | | | ✅ | ✅ |
| Create, edit, and delete [enroll secrets](https://fleetdm.com/docs/deploying/faq#when-do-i-need-to-deploy-a-new-enroll-secret-to-my-hosts) | | | ✅ | ✅ | ✅ |
| Create, edit, and delete [enroll secrets for teams](https://fleetdm.com/docs/using-fleet/rest-api#get-enroll-secrets-for-a-team)\* | | | ✅ | ✅ | |
| Read organization settings\*** | ✅ | ✅ | ✅ | ✅ | |
| Read Single Sign-On settings\*** | | | | ✅ | |
| Read SMTP settings\*** | | | | ✅ | |
| Read osquery agent options\*** | | | | ✅ | |
| Edit [organization settings](https://fleetdm.com/docs/using-fleet/configuration-files#organization-settings) | | | | ✅ | ✅ |
| Edit [agent options](https://fleetdm.com/docs/using-fleet/configuration-files#agent-options) | | | | ✅ | ✅ |
| Edit [agent options for hosts assigned to teams](https://fleetdm.com/docs/using-fleet/configuration-files#team-agent-options)\* | | | | ✅ | ✅ |
| Initiate [file carving](https://fleetdm.com/docs/using-fleet/rest-api#file-carving) | | | ✅ | ✅ | |
| Retrieve contents from file carving | | | | ✅ | |
| View Apple mobile device management (MDM) certificate information | | | | ✅ | |
| View Apple business manager (BM) information | | | | ✅ | |
| Generate Apple mobile device management (MDM) certificate signing request (CSR) | | | | ✅ | |
| View disk encryption key for macOS hosts | ✅ | ✅ | ✅ | ✅ | |
| Create edit and delete configuration profiles for macOS hosts | | | ✅ | ✅ | ✅ |
| Execute MDM commands on macOS hosts*** | | | ✅ | ✅ | |
| View results of MDM commands executed on macOS hosts*** | ✅ | ✅ | ✅ | ✅ | |
| Edit [MDM settings](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ |
| Edit [MDM settings for teams](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ |
| Upload an EULA file for MDM automatic enrollment\* | | | | ✅ | |
| View/download MDM macOS setup assistant\* | | | ✅ | ✅ | |
| Edit/upload MDM macOS setup assistant\* | | | ✅ | ✅ | ✅ |
| View metadata of MDM macOS bootstrap packages\* | | | ✅ | ✅ | |
| Edit/upload MDM macOS bootstrap packages\* | | | ✅ | ✅ | ✅ |
| Enable/disable MDM macOS setup end user authentication\* | | | ✅ | ✅ | ✅ |
\* Applies only to Fleet Premium
\** Global observers can view all queries but the UI and fleetctl only list the ones they can run (**observer can run**).
\*** Applies only to [Fleet REST API](https://fleetdm.com/docs/using-fleet/rest-api)
## Team member permissions
`Applies only to Fleet Premium`
Users in Fleet either have team access or global access.
Users with team access only have access to the [hosts](https://fleetdm.com/docs/using-fleet/rest-api#hosts), [software](https://fleetdm.com/docs/using-fleet/rest-api#software), [schedules](https://fleetdm.com/docs/using-fleet/fleet-ui#schedule-a-query) , and [policies](https://fleetdm.com/docs/using-fleet/rest-api#policies) assigned to
their team.
Users with global access have access to all
[hosts](https://fleetdm.com/docs/using-fleet/rest-api#hosts), [software](https://fleetdm.com/docs/using-fleet/rest-api#software), [queries](https://fleetdm.com/docs/using-fleet/rest-api#queries), [schedules](https://fleetdm.com/docs/using-fleet/fleet-ui#schedule-a-query) , and [policies](https://fleetdm.com/docs/using-fleet/rest-api#policies). Check out [the user permissions
table](#user-permissions) above for global user permissions.
Users can be a member of multiple teams in Fleet.
Users that are members of multiple teams can be assigned different roles for each team. For example, a user can be given access to the "Workstations" team and assigned the "Observer" role. This same user can be given access to the "Servers" team and assigned the "Maintainer" role.
| **Action** | Team observer | Team observer+ | Team maintainer | Team admin | Team GitOps |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------- | --------------- | ---------- | ----------- |
| View hosts | ✅ | ✅ | ✅ | ✅ | |
| Filter hosts using [labels](https://fleetdm.com/docs/using-fleet/rest-api#labels) | ✅ | ✅ | ✅ | ✅ | |
| Target hosts using labels | ✅ | ✅ | ✅ | ✅ | |
| Add and delete hosts | | | ✅ | ✅ | |
| Filter software by [vulnerabilities](https://fleetdm.com/docs/using-fleet/vulnerability-processing#vulnerability-processing) | ✅ | ✅ | ✅ | ✅ | |
| Filter hosts by software | ✅ | ✅ | ✅ | ✅ | |
| Filter software | ✅ | ✅ | ✅ | ✅ | |
| Run queries designated "**observer can run**" as live queries against hosts | ✅ | ✅ | ✅ | ✅ | |
| Run any query as [live query](https://fleetdm.com/docs/using-fleet/fleet-ui#run-a-query) | | ✅ | ✅ | ✅ | |
| Create, edit, and delete only **self authored** queries | | | ✅ | ✅ | ✅ |
| View all queries\** | ✅ | ✅ | ✅ | ✅ | |
| Add, edit, and remove queries from the schedule | | | ✅ | ✅ | ✅ |
| View policies | ✅ | ✅ | ✅ | ✅ | |
| View global (inherited) policies | ✅ | ✅ | ✅ | ✅ | |
| Run global (inherited) policies as a live policy | | | ✅ | ✅ | |
| Filter hosts using policies | ✅ | ✅ | ✅ | ✅ | |
| Create, edit, and delete team policies | | | ✅ | ✅ | ✅ |
| Manage [policy automations](https://fleetdm.com/docs/using-fleet/automations#policy-automations) | | | | ✅ | ✅ |
| Add and remove team members | | | | ✅ | ✅ |
| Edit team name | | | | ✅ | ✅ |
| Create, edit, and delete [team enroll secrets](https://fleetdm.com/docs/using-fleet/rest-api#get-enroll-secrets-for-a-team) | | | ✅ | ✅ | |
| Read organization settings\* | ✅ | ✅ | ✅ | ✅ | |
| Read agent options\* | ✅ | ✅ | ✅ | ✅ | |
| Edit [agent options](https://fleetdm.com/docs/using-fleet/configuration-files#agent-options) | | | | ✅ | ✅ |
| Initiate [file carving](https://fleetdm.com/docs/using-fleet/rest-api#file-carving) | | | ✅ | ✅ | |
| View disk encryption key for macOS hosts | ✅ | ✅ | ✅ | ✅ | |
| Create edit and delete configuration profiles for macOS hosts | | | ✅ | ✅ | ✅ |
| Execute MDM commands on macOS hosts, and read command results* | | | ✅ | ✅ | |
| Execute MDM commands on macOS hosts* | | | ✅ | ✅ | |
| View results of MDM commands executed on macOS hosts* | ✅ | ✅ | ✅ | ✅ | |
| Edit [team MDM settings](https://fleetdm.com/docs/using-fleet/mdm-macos-settings) | | | | ✅ | ✅ |
| View/download MDM macOS setup assistant | | | ✅ | ✅ | |
| Edit/upload MDM macOS setup assistant | | | ✅ | ✅ | ✅ |
| View metadata of MDM macOS bootstrap packages | | | ✅ | ✅ | |
| Edit/upload MDM macOS bootstrap packages | | | ✅ | ✅ | ✅ |
| Enable/disable MDM macOS setup end user authentication | | | ✅ | ✅ | ✅ |
\* Applies only to [Fleet REST API](https://fleetdm.com/docs/using-fleet/rest-api)
\** Team observers can view all queries but the UI and fleetctl only list the ones they can run (**observer can run**).
<meta name="pageOrderInSection" value="900">
<meta name="description" value="Learn about the different roles and permissions in Fleet.">
<meta name="navSection" value="The basics">
docs/Using Fleet/segment-hosts.md
+135
View File
@@ -0,0 +1,135 @@
# Segment hosts
`Applies only to Fleet Premium`
```
ℹ️ In Fleet 4.0, Teams were introduced.
```
- [View teams](#view-teams)
- [Create a team](#create-a-team)
- [Automatically adding hosts to a team](#automatically-adding-hosts-to-a-team)
- [Transfer hosts to a team](#transfer-hosts-to-a-team)
- [Add users to a team](#add-users-to-a-team)
- [Remove a member from a team](#remove-a-member-from-a-team)
- [Remove a team](#remove-a-team)
In Fleet, you can group hosts together in a team.
With hosts segmented into exclusive teams, you can apply specific queries, policies, and agent options to each team.
For example, you might create a team for each type of system in your organization. You can name the teams `Workstations`, `Workstations - sandbox`, `Servers`, and `Servers - sandbox`.
> A popular pattern is to end a team’s name with “- sandbox”, then you can use this to test new queries and configuration with staging hosts or volunteers acting as canaries.
Then you can:
- Enroll hosts to one team using team specific enroll secrets
- Apply unique agent options to each team
- Schedule queries that target one or more teams
- Run live queries against one or more teams
- Grant users access to one or more
## View teams
To view teams:
In the top navigation select "Settings" and then "Teams."
## Create a team
To create a team:
1. In the top navigation select "Settings" and then, in the sub-navigation, select "Teams."
2. To the left of the search box, select "Create team."
3. Enter your new team's name and select "Save."
## Automatically adding hosts to a team
Hosts can only belong to one team in Fleet.
You can add hosts to a new team in Fleet by either enrolling the host with a team's enroll secret or by [transferring the host via the Fleet UI](#transfer-hosts-to-a-team) after the host has been enrolled to Fleet.
To automatically add hosts to a team in Fleet, check out the ["Adding hosts" documentation](https://fleetdm.com/docs/using-fleet/adding-hosts#automatically-adding-hosts-to-a-team).
> If a host was previously enrolled using a global enroll secret, changing the host's osquery enroll
> secret will not cause the host to be transferred to the desired team. You must delete the
> `osquery/osquery.db` file on the host, which forces the host to re-enroll
> using the new team enroll secret. Alternatively, you can transfer the host via the Fleet UI, the
> fleetctl CLI using `fleetctl hosts transfer`, or the [transfer host API endpoint](https://fleetdm.com/docs/using-fleet/rest-api#transfer-hosts-to-a-team).
## Transfer hosts to a team
Hosts can be transferred to a different team they've has been enrolled to Fleet.
To transfer a host to a team:
1. In the top navigation, select "Hosts."
2. Using the checkboxes in the Hosts table, select the hosts you'd like to transfer.
3. In the Hosts table header select "Transfer to team."
4. Choose the team you'd like to transfer the hosts to and confirm the action.
## Add users to a team
Global users cannot be added to a team.
To add users to a team:
1. In the top navigation, select "Settings" and then, in the sub-navigation, select "Teams."
2. Find your team and select it.
3. To the left of the search box, select "Add member."
4. Select one or more users by searching for their full name and confirm the action.
Users will be given the [Observer role](https://fleetdm.com/docs/using-fleet/permissions#team-member-permissions) when added to the team. The [Edit a member's role](#edit-a-members-role) provides instructions on changing the permission level of users on a team.
## Edit a member's role
To edit a member's role:
1. In the top navigation, select "Settings" and then, in the sub-navigation, select "Teams."
2. Find your team and select it.
3. In the Members table, select the "Actions" button for the user you'd like to edit and then select "Edit."
4. In the Teams section of the form, to the right of the team you'd like to change the users role on, select "Observer" (this may also say "Maintainer") and then select the new role.
5. Confirm the action.
## Remove a member from a team
To remove a member from a team:
1. In the top navigation, select "Settings" and then, in the sub-navigation, select "Teams."
2. Find your team and select it.
3. In the Members table, select the "Actions" button for the user you'd like to edit and then select "Remove."
4. Confirm the action.
## Delete a team
To delete a team:
1. In the top navigation, select "Settings" and then, in the sub-navigation, select "Teams."
2. Find your team and select it.
3. On the right side, select "Delete team" and confirm the action.
<meta name="pageOrderInSection" value="1000">
<meta name="description" value="Learn how to group hosts in Fleet to apply specific queries, policies, and agent options using teams.">
<meta name="navSection" value="The basics">
docs/Using Fleet/update-agents.md
+165
View File
@@ -0,0 +1,165 @@
# Self-managed agent updates
[Fleetd](https://fleetdm.com/docs/using-fleet/fleetd) will periodically check the public Fleet update repository and update Orbit, Fleet Desktop, and/or osquery
if it detects a later version.
To override this behavior, users can set a channel for each component or disable updates altogether. Visit [Adding Hosts](https://fleetdm.com/docs/using-fleet/adding-hosts#fleet-desktop) to learn more.
Alternatively, users with a Fleet Premium subscription can self-manage an update server.
## Securing updates
Fleetd utilizes [The Update Framework](https://theupdateframework.io/) to secure the update system. The TUF specification provides a robust framework for establishing trust over the content of updates. See [TUF's security documentation](https://theupdateframework.io/security/) for more details.
Fleet's usage of TUF allows the keys most critical to the security of the system to be stored offline, and provides a simple deployment model for update metadata and content.
There is no server that must be maintained for updates, instead Fleet provides tools via `fleetctl` to manage the static metadata and update assets. These can be served by any static content hosting solution (Apache, nginx, S3, etc.).
## Operations
Update management is handled by the `fleetctl updates` subcommands.
Fleet will prompt for passphrases when needed, or passphrases may be set in the environment variables `FLEET_ROOT_PASSPHRASE`, `FLEET_TARGETS_PASSPHRASE`, `FLEET_SNAPSHOT_PASSPHRASE`, and `FLEET_TIMESTAMP_PASSPHRASE`. Passphrases should be stored separately from keys.
By default, the current working directory is used for the TUF repository. All update commands support a `--path` parameter to use a different directory.
### Initialize the repository
_The root cryptographic key generated in this step is highly sensitive, and critical to the security of the update system. We recommend following these steps from a trusted, offline, ephemeral environment such as [Debian Live](https://www.debian.org/CD/live/) running from a USB stick. Avoid placing the root key in an online environment. Fleet will soon support the use of Hardware security modules (HSMs) to further protect the root key._
For testing purposes it is okay to initialize the repository in an online environment. Be sure to use a clean offline environment with new keys and passphrases when deploying to production.
Initialize the repository:
```
fleetctl updates init
```
Choose and record secure passphrases, _different for each key_. If the passphrases are not already set in the environment, you will be prompted to input them.
Make multiple copies of the `keys` directory to be stored offline on USB drives. These copies contain the root key:
```
cp -r keys <destination>
```
Delete the root key from the `keys` directory:
```
rm keys/root.json
```
Copy the `keys`, `repository`, and `staged` directories to a separate "working" USB drive:
```
cp -r keys repository staged <destination>
```
Shut down the environment.
### Deploy updates
Updates are deployed first by staging the contents and metadata, then publishing.
#### Staging
_Staging targets requires access to the `target`, `snapshot`, and `timestamp` keys. Best practice is to connect the drive containing the keys while staging updates and leave the keys offline at other times._
Use `fleetctl updates add` to stage updates. Fleetd updates the `osqueryd` binary, as well as the `orbit` binary. Updates are staged for each of these separately using the `--name` flag. It is not necessary to update both at the same time.
The following commands will prompt for key passphrases if not specified in the environment.
To stage updates for `osqueryd`:
```
fleetctl updates add --target ./path/to/linux/osqueryd --platform linux --name osqueryd --version 4.6.0 -t 4.6 -t 4 -t stable
```
This will add the `osqueryd` binary located at `./path/to/osqueryd` to the channels `4.6.0`, `4.6`, `4`, and `stable` for the `linux` platform.
In a typical scenario, each platform is staged before the repository is published.
Stage the equivalent macOS update:
```
fleetctl updates add --target ./path/to/macos/osqueryd --platform macos --name osqueryd --version 4.6.0 -t 4.6 -t 4 -t stable
```
A similar process can be used to stage the `orbit` artifacts by substituting `--name orbit`
When updates are staged, publish the repository.
#### Publishing
Publishing updates is as simple as making the contents of the `repository` directory available over HTTP. This can be achieved with [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/HostingWebsiteOnS3Setup.html), [Apache](https://access.redhat.com/solutions/67298), [NGINX](https://docs.nginx.com/nginx/admin-guide/web-server/serving-static-content/), or any other static file hosting solution or CDN.
Python's `SimpleHTTPServer` can be used for quick local testing:
```
cd repository && python -m SimpleHTTPServer
```
Or, for Python version 3.0 and greater:
```
cd repository && python -m http.server
```
Run this to host the repository at http://localhost:8000.
#### Update timestamp
Fleetd verifies freshness of the update metadata using the signed [timestamp file](https://theupdateframework.io/metadata/#timestamp-metadata-timestampjson). _This file must be re-signed every two weeks_ (this interval will be made configurable soon).
To update the timestamp metadata:
```
fleetctl updates timestamp
```
_This operation requires the `timestamp` key to be available, along with the corresponding passphrase. Best practice is to keep these keys "online" in a context where they can be used to update the metadata on an interval (via `cron`, AWS Lambda, etc.). This "online" context should be on a separate host from the static file server, to prevent leaking these less sensitive (though still sensitive) keys in the event the static file server is compromised._
### Building packages
Note that `osqueryd` and `orbit` updates must be published before packages can be produced.
Record the root key metadata with a copy of the repository:
```
fleetctl updates roots
```
This output is _not sensitive_ and will be shared in agent deployments to verify the contents of updates and metadata. Provide the JSON output in the `--update-roots` flag of the [Fleetd packager](https://fleetdm.com/docs/using-fleet/fleetd):
### Packaging with Fleetd
See the [Fleetd docs](https://fleetdm.com/docs/using-fleet/fleetd) for more details
You can use `fleetctl package` to generate installer packages of Fleetd (Fleet's bundle of agents that includes a bootstrapped osquery wrapper) to integrate with your Fleet instance.
For example running `fleetctl package --type deb --fleet-url=<fleet url> --enroll-secret=<enroll secret>` will build a `.deb` installer with everything needed
to communicate with your fleet instance.
### Key rotation
Key rotation is supported for each of the update role keys via the `fleetctl updates rotate` command.
Rotation is required for a key if the key has been compromised, or before the key expires.
Compromise of a single key (besides the root key) within the system does not enable an attacker to
push arbitrary updates. Compromise of the root key is a catastrophic failure allowing arbitrary
updates, and for this reason the root key is highly guarded in an offline context. See Section 7.4
of the [_Survivable Key
Compromise_](https://theupdateframework.io/papers/survivable-key-compromise-ccs2010.pdf) paper for a
more in-depth discussion of the implications of key compromise in the TUF system.
To rotate (for example) the targets key:
```
fleetctl updates rotate targets
```
After the key(s) have been rotated, publish the repository in the same fashion as any other update.
<meta name="pageOrderInSection" value="400">
<meta name="description" value="Information on how to manage and secure Fleet agent updates.">
<meta name="navSection" value="Dig deeper">